1 /** 2 * @file gntblist.h GNT BuddyList API 3 * @ingroup finch 4 */ 5 6 /* finch 7 * 8 * Finch is the legal property of its developers, whose names are too numerous 9 * to list here. Please refer to the COPYRIGHT file distributed with this 10 * source distribution. 11 * 12 * This program is free software; you can redistribute it and/or modify 13 * it under the terms of the GNU General Public License as published by 14 * the Free Software Foundation; either version 2 of the License, or 15 * (at your option) any later version. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU General Public License for more details. 21 * 22 * You should have received a copy of the GNU General Public License 23 * along with this program; if not, write to the Free Software 24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 25 */ 26 #ifndef _GNT_BLIST_H 27 #define _GNT_BLIST_H 28 29 #include "blist.h" 30 #include "gnttree.h" 31 32 /********************************************************************** 33 * @name GNT BuddyList API 34 **********************************************************************/ 35 /*@{*/ 36 37 /** 38 * Buddylist manager for finch. This decides the visility, ordering and hierarchy 39 * of the buddylist nodes. This also manages the creation of tooltips. 40 */ 41 typedef struct 42 { 43 const char *id; /**< An identifier for the manager. */ 44 const char *name; /**< Displayable name for the manager. */ 45 gboolean (*init)(void); /**< Called right before it's being used. */ 46 gboolean (*uninit)(void); /**< Called right after it's not being used any more. */ 47 gboolean (*can_add_node)(PurpleBlistNode *node); /**< Whether a node should be added to the view. */ 48 gpointer (*find_parent)(PurpleBlistNode *node); /**< Find the parent row for a node. */ 49 gboolean (*create_tooltip)(gpointer selected_row, GString **body, char **title); /**< Create tooltip for a selected row. */ 50 gpointer reserved[4]; 51 } FinchBlistManager; 52 53 /** 54 * Get the ui-functions. 55 * 56 * @return The PurpleBlistUiOps structure populated with the appropriate functions. 57 */ 58 PurpleBlistUiOps * finch_blist_get_ui_ops(void); 59 60 /** 61 * Perform necessary initializations. 62 */ 63 void finch_blist_init(void); 64 65 /** 66 * Perform necessary uninitializations. 67 */ 68 void finch_blist_uninit(void); 69 70 /** 71 * Show the buddy list. 72 */ 73 void finch_blist_show(void); 74 75 /** 76 * Get the position of the buddy list. 77 * 78 * @param x The x-coordinate is set here if not @ NULL. 79 * @param y The y-coordinate is set here if not @c NULL. 80 * 81 * @return Returns @c TRUE if the values were set, @c FALSE otherwise. 82 */ 83 gboolean finch_blist_get_position(int *x, int *y); 84 85 /** 86 * Set the position of the buddy list. 87 * 88 * @param x The x-coordinate of the buddy list. 89 * @param y The y-coordinate of the buddy list. 90 */ 91 void finch_blist_set_position(int x, int y); 92 93 /** 94 * Get the size of the buddy list. 95 * 96 * @param width The width is set here if not @ NULL. 97 * @param height The height is set here if not @c NULL. 98 * 99 * @return Returns @c TRUE if the values were set, @c FALSE otherwise. 100 */ 101 gboolean finch_blist_get_size(int *width, int *height); 102 103 /** 104 * Set the size of the buddy list. 105 * 106 * @param width The width of the buddy list. 107 * @param height The height of the buddy list. 108 */ 109 void finch_blist_set_size(int width, int height); 110 111 /** 112 * Get information about a user. Show immediate feedback. 113 * 114 * @param conn The connection to get information fro 115 * @param name The user to get information about. 116 * 117 * @return Returns the ui-handle for the userinfo notification. 118 * 119 * @since 2.1.0 120 */ 121 gpointer finch_retrieve_user_info(PurpleConnection *conn, const char *name); 122 123 /** 124 * Get the tree list of the buddy list. 125 * @return The GntTree widget. 126 * @since 2.4.0 127 */ 128 GntTree * finch_blist_get_tree(void); 129 130 /** 131 * Add an alternate buddy list manager. 132 * 133 * @param manager The alternate buddylist manager. 134 * @since 2.4.0 135 */ 136 void finch_blist_install_manager(const FinchBlistManager *manager); 137 138 /** 139 * Remove an alternate buddy list manager. 140 * 141 * @param manager The buddy list manager to remove. 142 * @since 2.4.0 143 */ 144 void finch_blist_uninstall_manager(const FinchBlistManager *manager); 145 146 /** 147 * Find a buddy list manager. 148 * 149 * @param id The identifier for the desired buddy list manager. 150 * 151 * @return The manager with the requested identifier, if available. @c NULL otherwise. 152 * @since 2.4.0 153 */ 154 FinchBlistManager * finch_blist_manager_find(const char *id); 155 156 /** 157 * Request the active buddy list manager to add a node. 158 * 159 * @param node The node to add 160 * @since 2.4.0 161 */ 162 void finch_blist_manager_add_node(PurpleBlistNode *node); 163 164 /*@}*/ 165 166 #endif 167