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