pidgin/gtkblist.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 _PIDGINBLIST_H_
  23 #define _PIDGINBLIST_H_
  24 /**
  25  * SECTION:gtkblist
  26  * @section_id: pidgin-gtkblist
  27  * @short_description: <filename>gtkblist.h</filename>
  28  * @title: Buddy List API
  29  * @see_also: <link linkend="chapter-signals-gtkblist">Buddy List signals</link>
  30  */
  31
  32 #define PIDGIN_TYPE_BUDDY_LIST (pidgin_buddy_list_get_type())
  33
  34 typedef struct _PidginBuddyList PidginBuddyList;
  35
  36 enum {
  37         STATUS_ICON_COLUMN,
  38         STATUS_ICON_VISIBLE_COLUMN,
  39         NAME_COLUMN,
  40         IDLE_COLUMN,
  41         IDLE_VISIBLE_COLUMN,
  42         BUDDY_ICON_COLUMN,
  43         BUDDY_ICON_VISIBLE_COLUMN,
  44         NODE_COLUMN,
  45         BGCOLOR_COLUMN,
  46         GROUP_EXPANDER_COLUMN,
  47         GROUP_EXPANDER_VISIBLE_COLUMN,
  48         CONTACT_EXPANDER_COLUMN,
  49         CONTACT_EXPANDER_VISIBLE_COLUMN,
  50         EMBLEM_COLUMN,
  51         EMBLEM_VISIBLE_COLUMN,
  52         PROTOCOL_ICON_COLUMN,
  53         PROTOCOL_ICON_VISIBLE_COLUMN,
  54         BLIST_COLUMNS
  55
  56 };
  57
  58 typedef enum {
  59         PIDGIN_STATUS_ICON_LARGE,
  60         PIDGIN_STATUS_ICON_SMALL
  61
  62 } PidginStatusIconSize;
  63
  64 #include "pidgin.h"
  65 #include "buddylist.h"
  66 #include "gtkblist-theme.h"
  67
  68 /**************************************************************************
  69  * Structures
  70  **************************************************************************/
  71 /**
  72  * PidginBuddyList:
  73  * @notebook:          The notebook that switches between the real buddy list
  74  *                     and the helpful instructions page
  75  * @main_vbox:         This vbox contains the menu and notebook
  76  * @vbox:              This is the vbox that everything important gets packed
  77  *                     into.  Your plugin might want to pack something in it
  78  *                     itself.  Go, plugins!
  79  * @treeview:          It's a treeview... d'uh.
  80  * @treemodel:         This is the treemodel.
  81  * @text_column:       Column
  82  * @menutray:          The menu tray widget.
  83  * @menutrayicon:      The menu tray icon.
  84  * @refresh_timer:     The timer for refreshing every 30 seconds
  85  * @timeout:           The timeout for the tooltip.
  86  * @drag_timeout:      The timeout for expanding contacts on drags
  87  * @tip_rect:          This is the bounding rectangle of the cell we're
  88  *                     currently hovering over.  This is used for tooltips.
  89  * @contact_rect:      This is the bounding rectangle of the contact node and
  90  *                     its children.  This is used for auto-expand on mouseover.
  91  * @mouseover_contact: This is the contact currently mouse-over expanded
  92  * @tipwindow:         The window used by the tooltip
  93  * @tooltipdata:       The data for each "chunk" of the tooltip
  94  * @selected_node:     The currently selected node
  95  * @scrollbook:        Scrollbook for alerts
  96  * @headline:          Widget for headline notifications
  97  * @headline_label:    Label for headline notifications
  98  * @headline_image:    Image for headline notifications
  99  * @headline_callback: Callback for headline notifications
 100  * @headline_data:     User data for headline notifications
 101  * @headline_destroy:  Callback to use for destroying the headline-data
 102  * @statusbox:         The status selector dropdown
 103  * @empty_avatar:      A 32x32 transparent pixbuf
 104  * @priv:              Pointer to opaque private data
 105  *
 106  * Like, everything you need to know about the gtk buddy list
 107  */
 108 struct _PidginBuddyList {
 109         PurpleBuddyList parent;
 110
 111         GtkWidget *window;
 112         GtkWidget *notebook;
 113         GtkWidget *main_vbox;
 114         GtkWidget *vbox;
 115
 116         GtkWidget *treeview;
 117         GtkTreeStore *treemodel;
 118         GtkTreeViewColumn *text_column;
 119
 120         GtkCellRenderer *text_rend;
 121
 122         GtkUIManager *ui;
 123         GtkWidget *menutray;
 124         GtkWidget *menutrayicon;
 125
 126         guint refresh_timer;
 127
 128         guint      timeout;
 129         guint      drag_timeout;
 130         GdkRectangle tip_rect;
 131         GdkRectangle contact_rect;
 132         PurpleBlistNode *mouseover_contact;
 133
 134         GtkWidget *tipwindow;
 135         GList *tooltipdata;
 136
 137         PurpleBlistNode *selected_node;
 138
 139         GtkWidget *scrollbook;
 140         GtkWidget *headline;
 141         GtkWidget *headline_label;
 142         GtkWidget *headline_image;
 143         GCallback headline_callback;
 144         gpointer headline_data;
 145         GDestroyNotify headline_destroy;
 146
 147         GtkWidget *statusbox;
 148         GdkPixbuf *empty_avatar;
 149 };
 150
 151 G_BEGIN_DECLS
 152
 153 /**************************************************************************
 154  * GTK+ Buddy List API
 155  **************************************************************************/
 156
 157 /**
 158  * pidgin_buddy_list_get_type:
 159  *
 160  * Returns: The #GType for the #PidginBuddyList boxed structure.
 161  */
 162 G_DECLARE_FINAL_TYPE(PidginBuddyList, pidgin_buddy_list, PIDGIN, BUDDY_LIST,
 163                      PurpleBuddyList)
 164
 165 /**
 166  * pidgin_blist_get_handle:
 167  *
 168  * Get the handle for the GTK+ blist system.
 169  *
 170  * Returns: the handle to the blist system
 171  */
 172 void *pidgin_blist_get_handle(void);
 173
 174 /**
 175  * pidgin_blist_init:
 176  *
 177  * Initializes the GTK+ blist system.
 178  */
 179 void pidgin_blist_init(void);
 180
 181 /**
 182  * pidgin_blist_uninit:
 183  *
 184  * Uninitializes the GTK+ blist system.
 185  */
 186 void pidgin_blist_uninit(void);
 187
 188 /**
 189  * pidgin_blist_get_default_gtk_blist:
 190  *
 191  * Returns the default gtk buddy list
 192  *
 193  * There's normally only one buddy list window, but that isn't a necessity. This function
 194  * returns the PidginBuddyList we're most likely wanting to work with. This is slightly
 195  * cleaner than an externed global.
 196  *
 197  * Returns: (transfer none): The default GTK+ buddy list.
 198  */
 199 PidginBuddyList *pidgin_blist_get_default_gtk_blist(void);
 200
 201 /**
 202  * pidgin_blist_make_buddy_menu:
 203  * @menu:  The menu to populate
 204  * @buddy: The buddy whose menu to get
 205  * @sub:   %TRUE if this is a sub-menu, %FALSE otherwise
 206  *
 207  * Populates a menu with the items shown on the buddy list for a buddy.
 208  */
 209 void pidgin_blist_make_buddy_menu(GtkWidget *menu, PurpleBuddy *buddy, gboolean sub);
 210
 211 /**
 212  * pidgin_blist_refresh:
 213  * @list:   This is the core list that gets updated from
 214  *
 215  * Refreshes all the nodes of the buddy list.
 216  * This should only be called when something changes to affect most of the nodes (such as a ui preference changing)
 217  */
 218 void pidgin_blist_refresh(PurpleBuddyList *list);
 219
 220 void pidgin_blist_update_columns(void);
 221 void pidgin_blist_update_refresh_timeout(void);
 222
 223 /**
 224  * pidgin_blist_get_emblem:
 225  * @node:   The node to return an emblem for
 226  *
 227  * Returns the blist emblem.
 228  *
 229  * This may be an existing pixbuf that has been given an additional ref,
 230  * so it shouldn't be modified.
 231  *
 232  * Returns: (transfer full): A GdkPixbuf for the emblem to show, or NULL
 233  */
 234 GdkPixbuf *
 235 pidgin_blist_get_emblem(PurpleBlistNode *node);
 236
 237 /**
 238  * pidgin_blist_get_status_icon:
 239  *
 240  * Useful for the buddy ticker
 241  *
 242  * Returns: (transfer full): A #GdkPixbuf of status icon.
 243  */
 244 GdkPixbuf *pidgin_blist_get_status_icon(PurpleBlistNode *node,
 245                 PidginStatusIconSize size);
 246
 247 /**
 248  * pidgin_blist_node_is_contact_expanded:
 249  * @node: The node in question.
 250  *
 251  * Returns a boolean indicating if @node is part of an expanded contact.
 252  *
 253  * This only makes sense for contact and buddy nodes. %FALSE is returned
 254  * for other types of nodes.
 255  *
 256  * Returns: A boolean indicating if @node is part of an expanded contact.
 257  */
 258 gboolean pidgin_blist_node_is_contact_expanded(PurpleBlistNode *node);
 259
 260 /**
 261  * pidgin_blist_toggle_visibility:
 262  *
 263  * Intelligently toggles the visibility of the buddy list. If the buddy
 264  * list is obscured, it is brought to the front. If it is not obscured,
 265  * it is hidden. If it is hidden it is shown.
 266  */
 267 void pidgin_blist_toggle_visibility(void);
 268
 269 /**
 270  * pidgin_blist_visibility_manager_add:
 271  *
 272  * Increases the reference count of visibility managers. Callers should
 273  * call the complementary remove function when no longer managing
 274  * visibility.
 275  *
 276  * A visibility manager is something that provides some method for
 277  * showing the buddy list after it is hidden (e.g. docklet plugin).
 278  */
 279 void pidgin_blist_visibility_manager_add(void);
 280
 281 /**
 282  * pidgin_blist_visibility_manager_remove:
 283  *
 284  * Decreases the reference count of visibility managers. If the count
 285  * drops below zero, the buddy list is shown.
 286  */
 287 void pidgin_blist_visibility_manager_remove(void);
 288
 289 /**
 290  * pidgin_blist_add_alert:
 291  * @widget:   The widget to add
 292  *
 293  * Adds a mini-alert to the blist scrollbook
 294  */
 295 void pidgin_blist_add_alert(GtkWidget *widget);
 296
 297 /**
 298  * pidgin_blist_set_theme:
 299  * @theme:      the new theme to use
 300  *
 301  * Sets the current theme for Pidgin to use
 302  */
 303 void pidgin_blist_set_theme(PidginBlistTheme *theme);
 304
 305 /**
 306  * pidgin_blist_get_theme:
 307  *
 308  * Gets Pidgin's current buddy list theme
 309  *
 310  * Returns:     (transfer none): the current theme
 311  */
 312 PidginBlistTheme *pidgin_blist_get_theme(void);
 313
 314 /**************************************************************************
 315  * GTK+ Buddy List sorting functions
 316  **************************************************************************/
 317
 318 typedef void (*pidgin_blist_sort_function)(PurpleBlistNode *new, PurpleBuddyList *blist, GtkTreeIter group, GtkTreeIter *cur, GtkTreeIter *iter);
 319
 320 /**
 321  * pidgin_blist_get_sort_methods:
 322  *
 323  * Gets the current list of sort methods.
 324  *
 325  * Returns: (transfer none) (element-type PidginBlistSortMethod): A GSlist of sort methods
 326  */
 327 GList *pidgin_blist_get_sort_methods(void);
 328
 329 struct _PidginBlistSortMethod {
 330         char *id;
 331         char *name;
 332         pidgin_blist_sort_function func;
 333 };
 334
 335 typedef struct _PidginBlistSortMethod PidginBlistSortMethod;
 336
 337 /**
 338  * pidgin_blist_sort_method_reg:
 339  * @id:   The unique ID of the sorting method
 340  * @name: The method's name.
 341  * @func: (scope call): A pointer to the function.
 342  *
 343  * Registers a buddy list sorting method.
 344  */
 345 void pidgin_blist_sort_method_reg(const char *id, const char *name, pidgin_blist_sort_function func);
 346
 347 /**
 348  * pidgin_blist_sort_method_unreg:
 349  * @id: The method's id
 350  *
 351  * Unregisters a buddy list sorting method.
 352  */
 353 void pidgin_blist_sort_method_unreg(const char *id);
 354
 355 /**
 356  * pidgin_blist_sort_method_set:
 357  * @id: The method's id.
 358  *
 359  * Sets a buddy list sorting method.
 360  */
 361 void pidgin_blist_sort_method_set(const char *id);
 362
 363 /**
 364  * pidgin_blist_setup_sort_methods:
 365  *
 366  * Sets up the programs default sort methods
 367  */
 368 void pidgin_blist_setup_sort_methods(void);
 369
 370 /**
 371  * pidgin_blist_update_accounts_menu:
 372  *
 373  * Updates the accounts menu on the GTK+ buddy list window.
 374  */
 375 void pidgin_blist_update_accounts_menu(void);
 376
 377 /**
 378  * pidgin_blist_update_plugin_actions:
 379  *
 380  * Updates the plugin actions menu on the GTK+ buddy list window.
 381  */
 382 void pidgin_blist_update_plugin_actions(void);
 383
 384 /**
 385  * pidgin_blist_update_sort_methods:
 386  *
 387  * Updates the Sorting menu on the GTK+ buddy list window.
 388  */
 389 void pidgin_blist_update_sort_methods(void);
 390
 391 /**
 392  * pidgin_blist_joinchat_is_showable:
 393  *
 394  * Determines if showing the join chat dialog is a valid action.
 395  *
 396  * Returns: Returns TRUE if there are accounts online capable of
 397  *         joining chat rooms.  Otherwise returns FALSE.
 398  */
 399 gboolean pidgin_blist_joinchat_is_showable(void);
 400
 401 /**
 402  * pidgin_blist_joinchat_show:
 403  *
 404  * Shows the join chat dialog.
 405  */
 406 void pidgin_blist_joinchat_show(void);
 407
 408 /**
 409  * pidgin_append_blist_node_privacy_menu:
 410  *
 411  * Appends the privacy menu items for a PurpleBlistNode
 412  */
 413 /* TODO Rename these. */
 414 void pidgin_append_blist_node_privacy_menu(GtkWidget *menu, PurpleBlistNode *node);
 415
 416 /**
 417  * pidgin_append_blist_node_proto_menu:
 418  *
 419  * Appends the protocol specific menu items for a PurpleBlistNode
 420  */
 421 /* TODO Rename these. */
 422 void pidgin_append_blist_node_proto_menu (GtkWidget *menu, PurpleConnection *gc, PurpleBlistNode *node);
 423
 424 /**
 425  * pidgin_append_blist_node_extended_menu:
 426  *
 427  * Appends the extended menu items for a PurpleBlistNode
 428  */
 429 /* TODO Rename these. */
 430 void pidgin_append_blist_node_extended_menu(GtkWidget *menu, PurpleBlistNode *node);
 431
 432 /**
 433  * pidgin_blist_set_headline:
 434  * @text:           Pango Markup for the label text
 435  * @icon_name: The icon name from the #GtkIconTheme
 436  * @callback:  The callback to call when headline is clicked
 437  * @user_data: The userdata to include in the callback
 438  * @destroy:   The callback to call when headline is closed or replaced by another headline.
 439  *
 440  * Sets a headline notification
 441  *
 442  * This is currently used for mail notification, but could theoretically be used for anything.
 443  * Only the most recent headline will be shown.
 444  */
 445 void pidgin_blist_set_headline(const char *text, const gchar *icon_name,
 446                 GCallback callback, gpointer user_data, GDestroyNotify destroy);
 447
 448 /**
 449  * pidgin_blist_get_name_markup:
 450  * @buddy: The buddy to return markup from
 451  * @selected:  Whether this buddy is selected. If TRUE, the markup will not change the color.
 452  * @aliased:  TRUE to return the appropriate alias of this buddy, FALSE to return its username and status information
 453  *
 454  * Returns a buddy's Pango markup appropriate for setting in a GtkCellRenderer.
 455  *
 456  * Returns: The markup for this buddy
 457  */
 458 gchar *pidgin_blist_get_name_markup(PurpleBuddy *buddy, gboolean selected, gboolean aliased);
 459
 460 /**
 461  * pidgin_blist_draw_tooltip:
 462  * @node: The buddy list node to show a tooltip for
 463  * @widget: The widget to draw the tooltip on
 464  *
 465  * Creates the Buddy List tooltip at the current pointer location for the given buddy list node.
 466  *
 467  * This tooltip will be destroyed the next time this function is called, or when XXXX
 468  * is called
 469  */
 470 void pidgin_blist_draw_tooltip(PurpleBlistNode *node, GtkWidget *widget);
 471
 472 /**
 473  * pidgin_blist_tooltip_destroy:
 474  *
 475  * Destroys the current (if any) Buddy List tooltip
 476  */
 477 void pidgin_blist_tooltip_destroy(void);
 478
 479 G_END_DECLS
 480
 481 #endif /* _PIDGINBLIST_H_ */