pidgin/gtkconv.h

   1 /* pidgin
   2  *
   3  * Pidgin is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PIDGIN_CONVERSATION_H_
  23 #define _PIDGIN_CONVERSATION_H_
  24 /**
  25  * SECTION:gtkconv
  26  * @section_id: pidgin-gtkconv
  27  * @short_description: <filename>gtkconv.h</filename>
  28  * @title: Conversation API
  29  * @see_also: <link linkend="chapter-signals-gtkconv">Conversation signals</link>
  30  */
  31
  32 #define PIDGIN_TYPE_CONVERSATION (pidgin_conversation_get_type())
  33
  34 typedef struct _PidginImPane       PidginImPane;
  35 typedef struct _PidginChatPane     PidginChatPane;
  36 typedef struct _PidginConversation PidginConversation;
  37
  38 /**
  39  * PidginUnseenState:
  40  * @PIDGIN_UNSEEN_NONE:   No unseen text in the conversation.
  41  * @PIDGIN_UNSEEN_EVENT:  Unseen events in the conversation.
  42  * @PIDGIN_UNSEEN_NO_LOG: Unseen text with NO_LOG flag.
  43  * @PIDGIN_UNSEEN_TEXT:   Unseen text in the conversation.
  44  * @PIDGIN_UNSEEN_NICK:   Unseen text and the nick was said.
  45  *
  46  * Unseen text states.
  47  */
  48 typedef enum
  49 {
  50         PIDGIN_UNSEEN_NONE,
  51         PIDGIN_UNSEEN_EVENT,
  52         PIDGIN_UNSEEN_NO_LOG,
  53         PIDGIN_UNSEEN_TEXT,
  54         PIDGIN_UNSEEN_NICK
  55 } PidginUnseenState;
  56
  57 enum {
  58         CHAT_USERS_ICON_COLUMN,
  59         CHAT_USERS_ALIAS_COLUMN,
  60         CHAT_USERS_ALIAS_KEY_COLUMN,
  61         CHAT_USERS_NAME_COLUMN,
  62         CHAT_USERS_FLAGS_COLUMN,
  63         CHAT_USERS_COLOR_COLUMN,
  64         CHAT_USERS_WEIGHT_COLUMN,
  65         CHAT_USERS_ICON_STOCK_COLUMN,
  66         CHAT_USERS_COLUMNS
  67 };
  68
  69 #define PIDGIN_CONVERSATION(conv) \
  70         ((PidginConversation *)purple_conversation_get_ui_data(conv))
  71
  72 #define PIDGIN_IS_PIDGIN_CONVERSATION(conv) \
  73         (purple_conversation_get_ui_ops(conv) == \
  74          pidgin_conversations_get_conv_ui_ops())
  75
  76 #include "pidgin.h"
  77 #include "conversation.h"
  78 #include "gtkconvwin.h"
  79
  80 /**************************************************************************
  81  * Structures
  82  **************************************************************************/
  83
  84 /**
  85  * PidginConversation:
  86  *
  87  * A GTK+ conversation pane.
  88  */
  89 struct _PidginConversation
  90 {
  91         gint box_count;
  92
  93         PurpleConversation *active_conv;
  94         PurpleConversation *last_conversed;
  95         GList *convs;
  96         GList *send_history;
  97
  98         PidginConvWindow *win;
  99
 100         gboolean make_sound;
 101
 102         GtkWidget *tab_cont;
 103         GtkWidget *tabby;
 104         GtkWidget *menu_tabby;
 105
 106         GArray *nick_colors;
 107         PurpleMessageFlags last_flags;
 108         GtkTextBuffer *history_buffer;
 109         GtkWidget *history;
 110
 111         GtkWidget *editor;
 112         GtkWidget *entry;
 113
 114         GtkWidget *close; /* "x" on the tab */
 115         GtkWidget *icon;
 116         GtkWidget *tab_label;
 117         GtkWidget *menu_icon;
 118         GtkWidget *menu_label;
 119
 120         GtkWidget *lower_hbox;
 121
 122         PidginUnseenState unseen_state;
 123         guint unseen_count;
 124
 125         union
 126         {
 127                 PidginImPane   *im;
 128                 PidginChatPane *chat;
 129
 130         } u;
 131
 132         time_t newday;
 133         GtkWidget *infopane_hbox;
 134         GtkWidget *infopane;
 135         GtkListStore *infopane_model;
 136         GtkTreeIter infopane_iter;
 137
 138         /* Used when attaching a PidginConversation to a PurpleConversation
 139          * with message history */
 140         int attach_timer;
 141         GList *attach_current;
 142
 143         /*
 144          * Quick Find.
 145          */
 146         GtkWidget *quickfind_entry;
 147         GtkWidget *quickfind_container;
 148 };
 149
 150 G_BEGIN_DECLS
 151
 152 /**************************************************************************
 153  * GTK+ Conversation API
 154  **************************************************************************/
 155
 156 /**
 157  * pidgin_conversation_get_type:
 158  *
 159  * Returns: The #GType for the #PidginConversation boxed structure.
 160  */
 161 GType pidgin_conversation_get_type(void);
 162
 163 /**
 164  * pidgin_conversations_get_conv_ui_ops:
 165  *
 166  * Returns the UI operations structure for GTK+ conversations.
 167  *
 168  * Returns: The GTK+ conversation operations structure.
 169  */
 170 PurpleConversationUiOps *pidgin_conversations_get_conv_ui_ops(void);
 171
 172 /**
 173  * pidgin_conv_update_buddy_icon:
 174  * @im: The IM conversation.
 175  *
 176  * Updates the buddy icon on a conversation.
 177  */
 178 void pidgin_conv_update_buddy_icon(PurpleIMConversation *im);
 179
 180 /**
 181  * pidgin_conv_switch_active_conversation:
 182  * @conv: The conversation
 183  *
 184  * Sets the active conversation within a GTK-conversation.
 185  */
 186 void pidgin_conv_switch_active_conversation(PurpleConversation *conv);
 187
 188 /**
 189  * pidgin_conv_update_buttons_by_protocol:
 190  * @conv: The conversation.
 191  *
 192  * Updates conversation buttons by protocol.
 193  */
 194 void pidgin_conv_update_buttons_by_protocol(PurpleConversation *conv);
 195
 196 /**
 197  * pidgin_conversations_get_unseen_all:
 198  * @min_state:    The minimum unseen state.
 199  * @hidden_only:  If %TRUE, only consider hidden conversations.
 200  * @max_count:    Maximum number of conversations to return, or 0 for
 201  *                no maximum.
 202  *
 203  * Returns a list of conversations of any type which have an unseen
 204  * state greater than or equal to the specified minimum state. Using the
 205  * hidden_only parameter, this search can be limited to hidden
 206  * conversations. The max_count parameter will limit the total number of
 207  * converations returned if greater than zero. The returned list should
 208  * be freed by the caller.
 209  *
 210  * Returns: (transfer container) (element-type PurpleConversation): List of PurpleConversation matching criteria, or %NULL.
 211  */
 212 GList *
 213 pidgin_conversations_get_unseen_all(PidginUnseenState min_state,
 214                                                                                 gboolean hidden_only,
 215                                                                                 guint max_count);
 216
 217 /**
 218  * pidgin_conversations_get_unseen_ims:
 219  * @min_state:    The minimum unseen state.
 220  * @hidden_only:  If %TRUE, only consider hidden conversations.
 221  * @max_count:    Maximum number of conversations to return, or 0 for
 222  *                no maximum.
 223  *
 224  * Returns a list of IM conversations which have an unseen state greater
 225  * than or equal to the specified minimum state. Using the hidden_only
 226  * parameter, this search can be limited to hidden IM conversations. The
 227  * max_count parameter will limit the total number of IM converations
 228  * returned if greater than zero. The returned list should be freed by the
 229  * caller.
 230  *
 231  * Returns: (transfer container) (element-type PurpleConversation): List of PurpleIMConversation matching criteria, or %NULL.
 232  */
 233 GList *
 234 pidgin_conversations_get_unseen_ims(PidginUnseenState min_state,
 235                                                                                 gboolean hidden_only,
 236                                                                                 guint max_count);
 237
 238 /**
 239  * pidgin_conversations_get_unseen_chats:
 240  * @min_state:    The minimum unseen state.
 241  * @hidden_only:  If %TRUE, only consider hidden conversations.
 242  * @max_count:    Maximum number of conversations to return, or 0 for
 243  *                no maximum.
 244  *
 245  * Returns a list of chat conversations which have an unseen state greater
 246  * than or equal to the specified minimum state. Using the hidden_only
 247  * parameter, this search can be limited to hidden chat conversations. The
 248  * max_count parameter will limit the total number of chat converations
 249  * returned if greater than zero. The returned list should be freed by the
 250  * caller.
 251  *
 252  * Returns: (transfer container) (element-type PurpleConversation): List of PurpleChatConversation matching criteria, or %NULL.
 253  */
 254 GList *
 255 pidgin_conversations_get_unseen_chats(PidginUnseenState min_state,
 256                                                                                 gboolean hidden_only,
 257                                                                                 guint max_count);
 258
 259 /**
 260  * pidgin_conversations_fill_menu:
 261  * @menu: Menu widget to add items to.
 262  * @convs: (element-type PurpleConversation): List of PurpleConversation to add to menu.
 263  *
 264  * Fill a menu with a list of conversations. Clicking the conversation
 265  * menu item will present that conversation to the user.
 266  *
 267  * Returns:       Number of conversations added to menu.
 268  */
 269 guint
 270 pidgin_conversations_fill_menu(GtkWidget *menu, GList *convs);
 271
 272 /**
 273  * pidgin_conv_present_conversation:
 274  * @conv: The conversation.
 275  *
 276  * Presents a purple conversation to the user.
 277  */
 278 void pidgin_conv_present_conversation(PurpleConversation *conv);
 279
 280 /**
 281  * pidgin_conv_attach_to_conversation:
 282  * @conv:  The conversation.
 283  *
 284  * Reattach Pidgin UI to a conversation.
 285  *
 286  * Returns:  Wheter Pidgin UI was successfully attached.
 287  */
 288 gboolean pidgin_conv_attach_to_conversation(PurpleConversation *conv);
 289
 290 /**
 291  * pidgin_conv_get_window:
 292  * @gtkconv: The GTK+ conversation.
 293  *
 294  * Returns: The window the conversation belongs to.
 295  */
 296 PidginConvWindow *pidgin_conv_get_window(PidginConversation *gtkconv);
 297
 298 /**
 299  * pidgin_conv_get_tab_icon:
 300  * @conv:       The conversation.
 301  * @small_icon: Whether to get the small icon.
 302  *
 303  * Returns: (transfer full): The tab icon.
 304  */
 305 GdkPixbuf *pidgin_conv_get_tab_icon(PurpleConversation *conv, gboolean small_icon);
 306
 307 /**
 308  * pidgin_conv_new:
 309  * @conv: The conversation.
 310  *
 311  * Creates a new GTK+ conversation for a given #PurpleConversation.
 312  */
 313 void pidgin_conv_new(PurpleConversation *conv);
 314
 315 /**
 316  * pidgin_conv_get_tab_at_xy:
 317  * @win:      The conversation window.
 318  * @x:        X-coordinate to look up.
 319  * @y:        Y-coordinate to look up.
 320  * @to_right: (out): Return address for a boolean which will be %TRUE if the
 321  *            coordinates are on the right side of the tab (or bottom in case of
 322  *            a vertical notebook), %FALSE otherwise.
 323  *
 324  * Returns: The tab index of a conversation in @win at (@x, @y).
 325  */
 326 int pidgin_conv_get_tab_at_xy(PidginConvWindow *win, int x, int y, gboolean *to_right);
 327
 328 /**
 329  * pidgin_conv_is_hidden:
 330  * @gtkconv: The GTK+ conversation.
 331  *
 332  * Returns: %TRUE if the conversation is hidden, %FALSE otherwise.
 333  */
 334 gboolean pidgin_conv_is_hidden(PidginConversation *gtkconv);
 335
 336 /**************************************************************************/
 337 /* GTK+ Conversations Subsystem                                           */
 338 /**************************************************************************/
 339
 340 /**
 341  * pidgin_conversations_get_handle:
 342  *
 343  * Returns the gtk conversations subsystem handle.
 344  *
 345  * Returns: The conversations subsystem handle.
 346  */
 347 void *pidgin_conversations_get_handle(void);
 348
 349 /**
 350  * pidgin_conversations_init:
 351  *
 352  * Initializes the GTK+ conversations subsystem.
 353  */
 354 void pidgin_conversations_init(void);
 355
 356 /**
 357  * pidgin_conversations_uninit:
 358  *
 359  * Uninitialized the GTK+ conversation subsystem.
 360  */
 361 void pidgin_conversations_uninit(void);
 362
 363 G_END_DECLS
 364
 365 #endif /* _PIDGIN_CONVERSATION_H_ */