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 #include "gtkconv-theme.h"
  80
  81 /**************************************************************************
  82  * Structures
  83  **************************************************************************/
  84
  85 /**
  86  * PidginConversation:
  87  *
  88  * A GTK+ conversation pane.
  89  */
  90 struct _PidginConversation
  91 {
  92         gint box_count;
  93
  94         PurpleConversation *active_conv;
  95         PurpleConversation *last_conversed;
  96         GList *convs;
  97         GList *send_history;
  98
  99         PidginConvWindow *win;
 100
 101         gboolean make_sound;
 102
 103         GtkWidget *tab_cont;
 104         GtkWidget *tabby;
 105         GtkWidget *menu_tabby;
 106
 107         PidginConvTheme *theme;
 108         GArray *nick_colors;
 109         PurpleMessageFlags last_flags;
 110         GtkWidget *webview;
 111         GtkWidget *entry;
 112         gboolean auto_resize;   /* this is set to TRUE if the conversation
 113                                  * is being resized by a non-user-initiated
 114                                  * event, such as the buddy icon appearing
 115                                  */
 116         gboolean entry_growing; /* True if the size of the entry was set
 117                                  * automatically by typing too much to fit
 118                                  * in one line */
 119
 120         GtkWidget *close; /* "x" on the tab */
 121         GtkWidget *icon;
 122         GtkWidget *tab_label;
 123         GtkWidget *menu_icon;
 124         GtkWidget *menu_label;
 125
 126         GtkWidget *lower_hbox;
 127
 128         PidginUnseenState unseen_state;
 129         guint unseen_count;
 130
 131         union
 132         {
 133                 PidginImPane   *im;
 134                 PidginChatPane *chat;
 135
 136         } u;
 137
 138         time_t newday;
 139         GtkWidget *infopane_hbox;
 140         GtkWidget *infopane;
 141         GtkListStore *infopane_model;
 142         GtkTreeIter infopane_iter;
 143
 144         /* Used when attaching a PidginConversation to a PurpleConversation
 145          * with message history */
 146         int attach_timer;
 147         GList *attach_current;
 148
 149         /*
 150          * Quick Find.
 151          */
 152         GtkWidget *quickfind_entry;
 153         GtkWidget *quickfind_container;
 154 };
 155
 156 G_BEGIN_DECLS
 157
 158 /**************************************************************************
 159  * GTK+ Conversation API
 160  **************************************************************************/
 161
 162 /**
 163  * pidgin_conversation_get_type:
 164  *
 165  * Returns: The #GType for the #PidginConversation boxed structure.
 166  */
 167 GType pidgin_conversation_get_type(void);
 168
 169 /**
 170  * pidgin_conversations_get_conv_ui_ops:
 171  *
 172  * Returns the UI operations structure for GTK+ conversations.
 173  *
 174  * Returns: The GTK+ conversation operations structure.
 175  */
 176 PurpleConversationUiOps *pidgin_conversations_get_conv_ui_ops(void);
 177
 178 /**
 179  * pidgin_conversations_get_default_theme:
 180  *
 181  * Returns the default theme for GTK+ conversations.
 182  *
 183  * Returns: The default GTK+ conversation theme.
 184  */
 185 PurpleTheme *pidgin_conversations_get_default_theme(void);
 186
 187 /**
 188  * pidgin_conv_update_buddy_icon:
 189  * @im: The IM conversation.
 190  *
 191  * Updates the buddy icon on a conversation.
 192  */
 193 void pidgin_conv_update_buddy_icon(PurpleIMConversation *im);
 194
 195 /**
 196  * pidgin_conv_switch_active_conversation:
 197  * @conv: The conversation
 198  *
 199  * Sets the active conversation within a GTK-conversation.
 200  */
 201 void pidgin_conv_switch_active_conversation(PurpleConversation *conv);
 202
 203 /**
 204  * pidgin_conv_update_buttons_by_protocol:
 205  * @conv: The conversation.
 206  *
 207  * Updates conversation buttons by protocol.
 208  */
 209 void pidgin_conv_update_buttons_by_protocol(PurpleConversation *conv);
 210
 211 /**
 212  * pidgin_conversations_get_unseen_all:
 213  * @min_state:    The minimum unseen state.
 214  * @hidden_only:  If %TRUE, only consider hidden conversations.
 215  * @max_count:    Maximum number of conversations to return, or 0 for
 216  *                no maximum.
 217  *
 218  * Returns a list of conversations of any type which have an unseen
 219  * state greater than or equal to the specified minimum state. Using the
 220  * hidden_only parameter, this search can be limited to hidden
 221  * conversations. The max_count parameter will limit the total number of
 222  * converations returned if greater than zero. The returned list should
 223  * be freed by the caller.
 224  *
 225  * Returns: List of PurpleConversation matching criteria, or %NULL.
 226  */
 227 GList *
 228 pidgin_conversations_get_unseen_all(PidginUnseenState min_state,
 229                                                                                 gboolean hidden_only,
 230                                                                                 guint max_count);
 231
 232 /**
 233  * pidgin_conversations_get_unseen_ims:
 234  * @min_state:    The minimum unseen state.
 235  * @hidden_only:  If %TRUE, only consider hidden conversations.
 236  * @max_count:    Maximum number of conversations to return, or 0 for
 237  *                no maximum.
 238  *
 239  * Returns a list of IM conversations which have an unseen state greater
 240  * than or equal to the specified minimum state. Using the hidden_only
 241  * parameter, this search can be limited to hidden IM conversations. The
 242  * max_count parameter will limit the total number of IM converations
 243  * returned if greater than zero. The returned list should be freed by the
 244  * caller.
 245  *
 246  * Returns: List of PurpleIMConversation matching criteria, or %NULL.
 247  */
 248 GList *
 249 pidgin_conversations_get_unseen_ims(PidginUnseenState min_state,
 250                                                                                 gboolean hidden_only,
 251                                                                                 guint max_count);
 252
 253 /**
 254  * pidgin_conversations_get_unseen_chats:
 255  * @min_state:    The minimum unseen state.
 256  * @hidden_only:  If %TRUE, only consider hidden conversations.
 257  * @max_count:    Maximum number of conversations to return, or 0 for
 258  *                no maximum.
 259  *
 260  * Returns a list of chat conversations which have an unseen state greater
 261  * than or equal to the specified minimum state. Using the hidden_only
 262  * parameter, this search can be limited to hidden chat conversations. The
 263  * max_count parameter will limit the total number of chat converations
 264  * returned if greater than zero. The returned list should be freed by the
 265  * caller.
 266  *
 267  * Returns: List of PurpleChatConversation matching criteria, or %NULL.
 268  */
 269 GList *
 270 pidgin_conversations_get_unseen_chats(PidginUnseenState min_state,
 271                                                                                 gboolean hidden_only,
 272                                                                                 guint max_count);
 273
 274 /**
 275  * pidgin_conversations_fill_menu:
 276  * @menu:   Menu widget to add items to.
 277  * @convs:  List of PurpleConversation to add to menu.
 278  *
 279  * Fill a menu with a list of conversations. Clicking the conversation
 280  * menu item will present that conversation to the user.
 281  *
 282  * Returns:       Number of conversations added to menu.
 283  */
 284 guint
 285 pidgin_conversations_fill_menu(GtkWidget *menu, GList *convs);
 286
 287 /**
 288  * pidgin_conv_present_conversation:
 289  * @conv: The conversation.
 290  *
 291  * Presents a purple conversation to the user.
 292  */
 293 void pidgin_conv_present_conversation(PurpleConversation *conv);
 294
 295 /**
 296  * pidgin_conv_attach_to_conversation:
 297  * @conv:  The conversation.
 298  *
 299  * Reattach Pidgin UI to a conversation.
 300  *
 301  * Returns:  Wheter Pidgin UI was successfully attached.
 302  */
 303 gboolean pidgin_conv_attach_to_conversation(PurpleConversation *conv);
 304
 305 /**
 306  * pidgin_conv_get_window:
 307  * @gtkconv: The GTK+ conversation.
 308  *
 309  * Returns: The window the conversation belongs to.
 310  */
 311 PidginConvWindow *pidgin_conv_get_window(PidginConversation *gtkconv);
 312
 313 /**
 314  * pidgin_conv_get_tab_icon:
 315  * @conv:       The conversation.
 316  * @small_icon: Whether to get the small icon.
 317  *
 318  * Returns: The tab icon.
 319  */
 320 GdkPixbuf *pidgin_conv_get_tab_icon(PurpleConversation *conv, gboolean small_icon);
 321
 322 /**
 323  * pidgin_conv_new:
 324  * @conv: The conversation.
 325  *
 326  * Creates a new GTK+ conversation for a given #PurpleConversation.
 327  */
 328 void pidgin_conv_new(PurpleConversation *conv);
 329
 330 /**
 331  * pidgin_conv_get_tab_at_xy:
 332  * @win:      The conversation window.
 333  * @x:        X-coordinate to look up.
 334  * @y:        Y-coordinate to look up.
 335  * @to_right: (out): Return address for a boolean which will be %TRUE if the
 336  *            coordinates are on the right side of the tab (or bottom in case of
 337  *            a vertical notebook), %FALSE otherwise.
 338  *
 339  * Returns: The tab index of a conversation in @win at (@x, @y).
 340  */
 341 int pidgin_conv_get_tab_at_xy(PidginConvWindow *win, int x, int y, gboolean *to_right);
 342
 343 /**
 344  * pidgin_conv_is_hidden:
 345  * @gtkconv: The GTK+ conversation.
 346  *
 347  * Returns: %TRUE if the conversation is hidden, %FALSE otherwise.
 348  */
 349 gboolean pidgin_conv_is_hidden(PidginConversation *gtkconv);
 350
 351 /**************************************************************************/
 352 /* GTK+ Conversations Subsystem                                           */
 353 /**************************************************************************/
 354
 355 /**
 356  * pidgin_conversations_get_handle:
 357  *
 358  * Returns the gtk conversations subsystem handle.
 359  *
 360  * Returns: The conversations subsystem handle.
 361  */
 362 void *pidgin_conversations_get_handle(void);
 363
 364 /**
 365  * pidgin_conversations_init:
 366  *
 367  * Initializes the GTK+ conversations subsystem.
 368  */
 369 void pidgin_conversations_init(void);
 370
 371 /**
 372  * pidgin_conversations_uninit:
 373  *
 374  * Uninitialized the GTK+ conversation subsystem.
 375  */
 376 void pidgin_conversations_uninit(void);
 377
 378 G_END_DECLS
 379
 380 #endif /* _PIDGIN_CONVERSATION_H_ */