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         GtkWidget *window;
 110         GtkWidget *notebook;
 111         GtkWidget *main_vbox;
 112         GtkWidget *vbox;
 113
 114         GtkWidget *treeview;
 115         GtkTreeStore *treemodel;
 116         GtkTreeViewColumn *text_column;
 117
 118         GtkCellRenderer *text_rend;
 119
 120         GtkUIManager *ui;
 121         GtkWidget *menutray;
 122         GtkWidget *menutrayicon;
 123
 124         guint refresh_timer;
 125
 126         guint      timeout;
 127         guint      drag_timeout;
 128         GdkRectangle tip_rect;
 129         GdkRectangle contact_rect;
 130         PurpleBlistNode *mouseover_contact;
 131
 132         GtkWidget *tipwindow;
 133         GList *tooltipdata;
 134
 135         PurpleBlistNode *selected_node;
 136
 137         GtkWidget *scrollbook;
 138         GtkWidget *headline;
 139         GtkWidget *headline_label;
 140         GtkWidget *headline_image;
 141         GCallback headline_callback;
 142         gpointer headline_data;
 143         GDestroyNotify headline_destroy;
 144
 145         GtkWidget *statusbox;
 146         GdkPixbuf *empty_avatar;
 147
 148         gpointer priv;
 149 };
 150
 151 #define PIDGIN_BLIST(list) ((PidginBuddyList *)purple_blist_get_ui_data())
 152 #define PIDGIN_IS_PIDGIN_BLIST(list) \
 153         (purple_blist_get_ui_ops() == pidgin_blist_get_ui_ops())
 154
 155 G_BEGIN_DECLS
 156
 157 /**************************************************************************
 158  * GTK+ Buddy List API
 159  **************************************************************************/
 160
 161 /**
 162  * pidgin_buddy_list_get_type:
 163  *
 164  * Returns: The #GType for the #PidginBuddyList boxed structure.
 165  */
 166 GType pidgin_buddy_list_get_type(void);
 167
 168 /**
 169  * pidgin_blist_get_handle:
 170  *
 171  * Get the handle for the GTK+ blist system.
 172  *
 173  * Returns: the handle to the blist system
 174  */
 175 void *pidgin_blist_get_handle(void);
 176
 177 /**
 178  * pidgin_blist_init:
 179  *
 180  * Initializes the GTK+ blist system.
 181  */
 182 void pidgin_blist_init(void);
 183
 184 /**
 185  * pidgin_blist_uninit:
 186  *
 187  * Uninitializes the GTK+ blist system.
 188  */
 189 void pidgin_blist_uninit(void);
 190
 191 /**
 192  * pidgin_blist_get_ui_ops:
 193  *
 194  * Returns the UI operations structure for the buddy list.
 195  *
 196  * Returns: The GTK+ list operations structure.
 197  */
 198 PurpleBlistUiOps *pidgin_blist_get_ui_ops(void);
 199
 200 /**
 201  * pidgin_blist_get_default_gtk_blist:
 202  *
 203  * Returns the default gtk buddy list
 204  *
 205  * There's normally only one buddy list window, but that isn't a necessity. This function
 206  * returns the PidginBuddyList we're most likely wanting to work with. This is slightly
 207  * cleaner than an externed global.
 208  *
 209  * Returns: The default GTK+ buddy list
 210  */
 211 PidginBuddyList *pidgin_blist_get_default_gtk_blist(void);
 212
 213 /**
 214  * pidgin_blist_make_buddy_menu:
 215  * @menu:  The menu to populate
 216  * @buddy: The buddy whose menu to get
 217  * @sub:   %TRUE if this is a sub-menu, %FALSE otherwise
 218  *
 219  * Populates a menu with the items shown on the buddy list for a buddy.
 220  */
 221 void pidgin_blist_make_buddy_menu(GtkWidget *menu, PurpleBuddy *buddy, gboolean sub);
 222
 223 /**
 224  * pidgin_blist_refresh:
 225  * @list:   This is the core list that gets updated from
 226  *
 227  * Refreshes all the nodes of the buddy list.
 228  * This should only be called when something changes to affect most of the nodes (such as a ui preference changing)
 229  */
 230 void pidgin_blist_refresh(PurpleBuddyList *list);
 231
 232 void pidgin_blist_update_columns(void);
 233 void pidgin_blist_update_refresh_timeout(void);
 234
 235 /**
 236  * pidgin_blist_get_emblem:
 237  * @node:   The node to return an emblem for
 238  *
 239  * Returns the blist emblem.
 240  *
 241  * This may be an existing pixbuf that has been given an additional ref,
 242  * so it shouldn't be modified.
 243  *
 244  * Returns:  A GdkPixbuf for the emblem to show, or NULL
 245  */
 246 GdkPixbuf *
 247 pidgin_blist_get_emblem(PurpleBlistNode *node);
 248
 249 /**
 250  * pidgin_blist_get_status_icon:
 251  *
 252  * Useful for the buddy ticker
 253  */
 254 GdkPixbuf *pidgin_blist_get_status_icon(PurpleBlistNode *node,
 255                 PidginStatusIconSize size);
 256
 257 /**
 258  * pidgin_blist_node_is_contact_expanded:
 259  * @node: The node in question.
 260  *
 261  * Returns a boolean indicating if @node is part of an expanded contact.
 262  *
 263  * This only makes sense for contact and buddy nodes. %FALSE is returned
 264  * for other types of nodes.
 265  *
 266  * Returns: A boolean indicating if @node is part of an expanded contact.
 267  */
 268 gboolean pidgin_blist_node_is_contact_expanded(PurpleBlistNode *node);
 269
 270 /**
 271  * pidgin_blist_toggle_visibility:
 272  *
 273  * Intelligently toggles the visibility of the buddy list. If the buddy
 274  * list is obscured, it is brought to the front. If it is not obscured,
 275  * it is hidden. If it is hidden it is shown.
 276  */
 277 void pidgin_blist_toggle_visibility(void);
 278
 279 /**
 280  * pidgin_blist_visibility_manager_add:
 281  *
 282  * Increases the reference count of visibility managers. Callers should
 283  * call the complementary remove function when no longer managing
 284  * visibility.
 285  *
 286  * A visibility manager is something that provides some method for
 287  * showing the buddy list after it is hidden (e.g. docklet plugin).
 288  */
 289 void pidgin_blist_visibility_manager_add(void);
 290
 291 /**
 292  * pidgin_blist_visibility_manager_remove:
 293  *
 294  * Decreases the reference count of visibility managers. If the count
 295  * drops below zero, the buddy list is shown.
 296  */
 297 void pidgin_blist_visibility_manager_remove(void);
 298
 299 /**
 300  * pidgin_blist_add_alert:
 301  * @widget:   The widget to add
 302  *
 303  * Adds a mini-alert to the blist scrollbook
 304  */
 305 void pidgin_blist_add_alert(GtkWidget *widget);
 306
 307 /**
 308  * pidgin_blist_set_theme:
 309  * @theme:      the new theme to use
 310  *
 311  * Sets the current theme for Pidgin to use
 312  */
 313 void pidgin_blist_set_theme(PidginBlistTheme *theme);
 314
 315 /**
 316  * pidgin_blist_get_theme:
 317  *
 318  * Gets Pidgin's current buddy list theme
 319  *
 320  * Returns:     the current theme
 321  */
 322 PidginBlistTheme *pidgin_blist_get_theme(void);
 323
 324 /**************************************************************************
 325  * GTK+ Buddy List sorting functions
 326  **************************************************************************/
 327
 328 typedef void (*pidgin_blist_sort_function)(PurpleBlistNode *new, PurpleBuddyList *blist, GtkTreeIter group, GtkTreeIter *cur, GtkTreeIter *iter);
 329
 330 /**
 331  * pidgin_blist_get_sort_methods:
 332  *
 333  * Gets the current list of sort methods.
 334  *
 335  * Returns: A GSlist of sort methods
 336  */
 337 GList *pidgin_blist_get_sort_methods(void);
 338
 339 struct _PidginBlistSortMethod {
 340         char *id;
 341         char *name;
 342         pidgin_blist_sort_function func;
 343 };
 344
 345 typedef struct _PidginBlistSortMethod PidginBlistSortMethod;
 346
 347 /**
 348  * pidgin_blist_sort_method_reg:
 349  * @id:   The unique ID of the sorting method
 350  * @name: The method's name.
 351  * @func:  A pointer to the function.
 352  *
 353  * Registers a buddy list sorting method.
 354  */
 355 void pidgin_blist_sort_method_reg(const char *id, const char *name, pidgin_blist_sort_function func);
 356
 357 /**
 358  * pidgin_blist_sort_method_unreg:
 359  * @id: The method's id
 360  *
 361  * Unregisters a buddy list sorting method.
 362  */
 363 void pidgin_blist_sort_method_unreg(const char *id);
 364
 365 /**
 366  * pidgin_blist_sort_method_set:
 367  * @id: The method's id.
 368  *
 369  * Sets a buddy list sorting method.
 370  */
 371 void pidgin_blist_sort_method_set(const char *id);
 372
 373 /**
 374  * pidgin_blist_setup_sort_methods:
 375  *
 376  * Sets up the programs default sort methods
 377  */
 378 void pidgin_blist_setup_sort_methods(void);
 379
 380 /**
 381  * pidgin_blist_update_accounts_menu:
 382  *
 383  * Updates the accounts menu on the GTK+ buddy list window.
 384  */
 385 void pidgin_blist_update_accounts_menu(void);
 386
 387 /**
 388  * pidgin_blist_update_plugin_actions:
 389  *
 390  * Updates the plugin actions menu on the GTK+ buddy list window.
 391  */
 392 void pidgin_blist_update_plugin_actions(void);
 393
 394 /**
 395  * pidgin_blist_update_sort_methods:
 396  *
 397  * Updates the Sorting menu on the GTK+ buddy list window.
 398  */
 399 void pidgin_blist_update_sort_methods(void);
 400
 401 /**
 402  * pidgin_blist_joinchat_is_showable:
 403  *
 404  * Determines if showing the join chat dialog is a valid action.
 405  *
 406  * Returns: Returns TRUE if there are accounts online capable of
 407  *         joining chat rooms.  Otherwise returns FALSE.
 408  */
 409 gboolean pidgin_blist_joinchat_is_showable(void);
 410
 411 /**
 412  * pidgin_blist_joinchat_show:
 413  *
 414  * Shows the join chat dialog.
 415  */
 416 void pidgin_blist_joinchat_show(void);
 417
 418 /**
 419  * pidgin_append_blist_node_privacy_menu:
 420  *
 421  * Appends the privacy menu items for a PurpleBlistNode
 422  */
 423 /* TODO Rename these. */
 424 void pidgin_append_blist_node_privacy_menu(GtkWidget *menu, PurpleBlistNode *node);
 425
 426 /**
 427  * pidgin_append_blist_node_proto_menu:
 428  *
 429  * Appends the protocol specific menu items for a PurpleBlistNode
 430  */
 431 /* TODO Rename these. */
 432 void pidgin_append_blist_node_proto_menu (GtkWidget *menu, PurpleConnection *gc, PurpleBlistNode *node);
 433
 434 /**
 435  * pidgin_append_blist_node_extended_menu:
 436  *
 437  * Appends the extended menu items for a PurpleBlistNode
 438  */
 439 /* TODO Rename these. */
 440 void pidgin_append_blist_node_extended_menu(GtkWidget *menu, PurpleBlistNode *node);
 441
 442 /**
 443  * pidgin_blist_set_headline:
 444  * @text:           Pango Markup for the label text
 445  * @pixbuf:    The GdkPixbuf for the icon
 446  * @callback:  The callback to call when headline is clicked
 447  * @user_data: The userdata to include in the callback
 448  * @destroy:   The callback to call when headline is closed or replaced by another headline.
 449  *
 450  * Sets a headline notification
 451  *
 452  * This is currently used for mail notification, but could theoretically be used for anything.
 453  * Only the most recent headline will be shown.
 454  */
 455 void pidgin_blist_set_headline(const char *text, GdkPixbuf *pixbuf, GCallback callback, gpointer user_data,
 456                 GDestroyNotify destroy);
 457
 458 /**
 459  * pidgin_blist_get_name_markup:
 460  * @buddy: The buddy to return markup from
 461  * @selected:  Whether this buddy is selected. If TRUE, the markup will not change the color.
 462  * @aliased:  TRUE to return the appropriate alias of this buddy, FALSE to return its username and status information
 463  *
 464  * Returns a buddy's Pango markup appropriate for setting in a GtkCellRenderer.
 465  *
 466  * Returns: The markup for this buddy
 467  */
 468 gchar *pidgin_blist_get_name_markup(PurpleBuddy *buddy, gboolean selected, gboolean aliased);
 469
 470 /**
 471  * pidgin_blist_draw_tooltip:
 472  * @node: The buddy list node to show a tooltip for
 473  * @widget: The widget to draw the tooltip on
 474  *
 475  * Creates the Buddy List tooltip at the current pointer location for the given buddy list node.
 476  *
 477  * This tooltip will be destroyed the next time this function is called, or when XXXX
 478  * is called
 479  */
 480 void pidgin_blist_draw_tooltip(PurpleBlistNode *node, GtkWidget *widget);
 481
 482 /**
 483  * pidgin_blist_tooltip_destroy:
 484  *
 485  * Destroys the current (if any) Buddy List tooltip
 486  */
 487 void pidgin_blist_tooltip_destroy(void);
 488
 489 G_END_DECLS
 490
 491 #endif /* _PIDGINBLIST_H_ */