* Pidgin is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
* @section_id: pidgin-gtkblist
* @short_description: <filename>gtkblist.h</filename>
* @see_also: <link linkend="chapter-signals-gtkblist">Buddy List signals</link>
#define PIDGIN_TYPE_BUDDY_LIST (pidgin_buddy_list_get_type())
typedef struct _PidginBuddyList PidginBuddyList;
STATUS_ICON_VISIBLE_COLUMN,
BUDDY_ICON_VISIBLE_COLUMN,
GROUP_EXPANDER_VISIBLE_COLUMN,
CONTACT_EXPANDER_VISIBLE_COLUMN,
PROTOCOL_ICON_VISIBLE_COLUMN,
PIDGIN_STATUS_ICON_LARGE,
#include "gtkblist-theme.h"
/**************************************************************************
**************************************************************************/
* @notebook: The notebook that switches between the real buddy list
* and the helpful instructions page
* @main_vbox: This vbox contains the menu and notebook
* @vbox: This is the vbox that everything important gets packed
* into. Your plugin might want to pack something in it
* @treeview: It's a treeview... d'uh.
* @treemodel: This is the treemodel.
* @menutray: The menu tray widget.
* @menutrayicon: The menu tray icon.
* @refresh_timer: The timer for refreshing every 30 seconds
* @timeout: The timeout for the tooltip.
* @drag_timeout: The timeout for expanding contacts on drags
* @tip_rect: This is the bounding rectangle of the cell we're
* currently hovering over. This is used for tooltips.
* @contact_rect: This is the bounding rectangle of the contact node and
* its children. This is used for auto-expand on mouseover.
* @mouseover_contact: This is the contact currently mouse-over expanded
* @tipwindow: The window used by the tooltip
* @tooltipdata: The data for each "chunk" of the tooltip
* @selected_node: The currently selected node
* @scrollbook: Scrollbook for alerts
* @headline: Widget for headline notifications
* @headline_label: Label for headline notifications
* @headline_image: Image for headline notifications
* @headline_callback: Callback for headline notifications
* @headline_data: User data for headline notifications
* @headline_destroy: Callback to use for destroying the headline-data
* @statusbox: The status selector dropdown
* @empty_avatar: A 32x32 transparent pixbuf
* @priv: Pointer to opaque private data
* Like, everything you need to know about the gtk buddy list
struct _PidginBuddyList {
GtkTreeViewColumn *text_column;
GtkCellRenderer *text_rend;
GdkRectangle contact_rect;
PurpleBlistNode *mouseover_contact;
PurpleBlistNode *selected_node;
GtkWidget *headline_label;
GtkWidget *headline_image;
GCallback headline_callback;
GDestroyNotify headline_destroy;
/**************************************************************************
**************************************************************************/
* pidgin_buddy_list_get_type:
* Returns: The #GType for the #PidginBuddyList boxed structure.
G_DECLARE_FINAL_TYPE(PidginBuddyList, pidgin_buddy_list, PIDGIN, BUDDY_LIST,
* pidgin_blist_get_handle:
* Get the handle for the GTK+ blist system.
* Returns: the handle to the blist system
void *pidgin_blist_get_handle(void);
* Initializes the GTK+ blist system.
void pidgin_blist_init(void);
* Uninitializes the GTK+ blist system.
void pidgin_blist_uninit(void);
* pidgin_blist_get_default_gtk_blist:
* Returns the default gtk buddy list
* There's normally only one buddy list window, but that isn't a necessity. This function
* returns the PidginBuddyList we're most likely wanting to work with. This is slightly
* cleaner than an externed global.
* Returns: (transfer none): The default GTK+ buddy list.
PidginBuddyList *pidgin_blist_get_default_gtk_blist(void);
* pidgin_blist_make_buddy_menu:
* @menu: The menu to populate
* @buddy: The buddy whose menu to get
* @sub: %TRUE if this is a sub-menu, %FALSE otherwise
* Populates a menu with the items shown on the buddy list for a buddy.
void pidgin_blist_make_buddy_menu(GtkWidget *menu, PurpleBuddy *buddy, gboolean sub);
* @list: This is the core list that gets updated from
* Refreshes all the nodes of the buddy list.
* This should only be called when something changes to affect most of the nodes (such as a ui preference changing)
void pidgin_blist_refresh(PurpleBuddyList *list);
void pidgin_blist_update_columns(void);
void pidgin_blist_update_refresh_timeout(void);
* pidgin_blist_get_emblem:
* @node: The node to return an emblem for
* Returns the blist emblem.
* This may be an existing pixbuf that has been given an additional ref,
* so it shouldn't be modified.
* Returns: (transfer full): A GdkPixbuf for the emblem to show, or NULL
pidgin_blist_get_emblem(PurpleBlistNode *node);
* pidgin_blist_get_status_icon:
* Useful for the buddy ticker
* Returns: (transfer full): A #GdkPixbuf of status icon.
GdkPixbuf *pidgin_blist_get_status_icon(PurpleBlistNode *node,
PidginStatusIconSize size);
* pidgin_blist_node_is_contact_expanded:
* @node: The node in question.
* Returns a boolean indicating if @node is part of an expanded contact.
* This only makes sense for contact and buddy nodes. %FALSE is returned
* for other types of nodes.
* Returns: A boolean indicating if @node is part of an expanded contact.
gboolean pidgin_blist_node_is_contact_expanded(PurpleBlistNode *node);
* pidgin_blist_toggle_visibility:
* Intelligently toggles the visibility of the buddy list. If the buddy
* list is obscured, it is brought to the front. If it is not obscured,
* it is hidden. If it is hidden it is shown.
void pidgin_blist_toggle_visibility(void);
* pidgin_blist_visibility_manager_add:
* Increases the reference count of visibility managers. Callers should
* call the complementary remove function when no longer managing
* A visibility manager is something that provides some method for
* showing the buddy list after it is hidden (e.g. docklet plugin).
void pidgin_blist_visibility_manager_add(void);
* pidgin_blist_visibility_manager_remove:
* Decreases the reference count of visibility managers. If the count
* drops below zero, the buddy list is shown.
void pidgin_blist_visibility_manager_remove(void);
* pidgin_blist_add_alert:
* @widget: The widget to add
* Adds a mini-alert to the blist scrollbook
void pidgin_blist_add_alert(GtkWidget *widget);
* pidgin_blist_set_theme:
* @theme: the new theme to use
* Sets the current theme for Pidgin to use
void pidgin_blist_set_theme(PidginBlistTheme *theme);
* pidgin_blist_get_theme:
* Gets Pidgin's current buddy list theme
* Returns: (transfer none): the current theme
PidginBlistTheme *pidgin_blist_get_theme(void);
/**************************************************************************
* GTK+ Buddy List sorting functions
**************************************************************************/
typedef void (*pidgin_blist_sort_function)(PurpleBlistNode *new, PurpleBuddyList *blist, GtkTreeIter group, GtkTreeIter *cur, GtkTreeIter *iter);
* pidgin_blist_get_sort_methods:
* Gets the current list of sort methods.
* Returns: (transfer none) (element-type PidginBlistSortMethod): A GSlist of sort methods
GList *pidgin_blist_get_sort_methods(void);
struct _PidginBlistSortMethod {
pidgin_blist_sort_function func;
typedef struct _PidginBlistSortMethod PidginBlistSortMethod;
* pidgin_blist_sort_method_reg:
* @id: The unique ID of the sorting method
* @name: The method's name.
* @func: (scope call): A pointer to the function.
* Registers a buddy list sorting method.
void pidgin_blist_sort_method_reg(const char *id, const char *name, pidgin_blist_sort_function func);
* pidgin_blist_sort_method_unreg:
* Unregisters a buddy list sorting method.
void pidgin_blist_sort_method_unreg(const char *id);
* pidgin_blist_sort_method_set:
* Sets a buddy list sorting method.
void pidgin_blist_sort_method_set(const char *id);
* pidgin_blist_setup_sort_methods:
* Sets up the programs default sort methods
void pidgin_blist_setup_sort_methods(void);
* pidgin_blist_update_accounts_menu:
* Updates the accounts menu on the GTK+ buddy list window.
void pidgin_blist_update_accounts_menu(void);
* pidgin_blist_update_plugin_actions:
* Updates the plugin actions menu on the GTK+ buddy list window.
void pidgin_blist_update_plugin_actions(void);
* pidgin_blist_update_sort_methods:
* Updates the Sorting menu on the GTK+ buddy list window.
void pidgin_blist_update_sort_methods(void);
* pidgin_blist_joinchat_is_showable:
* Determines if showing the join chat dialog is a valid action.
* Returns: Returns TRUE if there are accounts online capable of
* joining chat rooms. Otherwise returns FALSE.
gboolean pidgin_blist_joinchat_is_showable(void);
* pidgin_blist_joinchat_show:
* Shows the join chat dialog.
void pidgin_blist_joinchat_show(void);
* pidgin_append_blist_node_privacy_menu:
* Appends the privacy menu items for a PurpleBlistNode
void pidgin_append_blist_node_privacy_menu(GtkWidget *menu, PurpleBlistNode *node);
* pidgin_append_blist_node_proto_menu:
* Appends the protocol specific menu items for a PurpleBlistNode
void pidgin_append_blist_node_proto_menu (GtkWidget *menu, PurpleConnection *gc, PurpleBlistNode *node);
* pidgin_append_blist_node_extended_menu:
* Appends the extended menu items for a PurpleBlistNode
void pidgin_append_blist_node_extended_menu(GtkWidget *menu, PurpleBlistNode *node);
* pidgin_blist_set_headline:
* @text: Pango Markup for the label text
* @icon_name: The icon name from the #GtkIconTheme
* @callback: The callback to call when headline is clicked
* @user_data: The userdata to include in the callback
* @destroy: The callback to call when headline is closed or replaced by another headline.
* Sets a headline notification
* This is currently used for mail notification, but could theoretically be used for anything.
* Only the most recent headline will be shown.
void pidgin_blist_set_headline(const char *text, const gchar *icon_name,
GCallback callback, gpointer user_data, GDestroyNotify destroy);
* pidgin_blist_get_name_markup:
* @buddy: The buddy to return markup from
* @selected: Whether this buddy is selected. If TRUE, the markup will not change the color.
* @aliased: TRUE to return the appropriate alias of this buddy, FALSE to return its username and status information
* Returns a buddy's Pango markup appropriate for setting in a GtkCellRenderer.
* Returns: The markup for this buddy
gchar *pidgin_blist_get_name_markup(PurpleBuddy *buddy, gboolean selected, gboolean aliased);
* pidgin_blist_draw_tooltip:
* @node: The buddy list node to show a tooltip for
* @widget: The widget to draw the tooltip on
* Creates the Buddy List tooltip at the current pointer location for the given buddy list node.
* This tooltip will be destroyed the next time this function is called, or when XXXX
void pidgin_blist_draw_tooltip(PurpleBlistNode *node, GtkWidget *widget);
* pidgin_blist_tooltip_destroy:
* Destroys the current (if any) Buddy List tooltip
void pidgin_blist_tooltip_destroy(void);
#endif /* _PIDGINBLIST_H_ */
