finch/gntblist.h

   1 /* finch
   2  *
   3  * Finch 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 _GNT_BLIST_H
  23 #define _GNT_BLIST_H
  24 /**
  25  * SECTION:gntblist
  26  * @section_id: finch-gntblist
  27  * @short_description: <filename>gntblist.h</filename>
  28  * @title: Buddy List API
  29  */
  30
  31 #include "buddylist.h"
  32 #include "gnt.h"
  33 #include "gnttree.h"
  34
  35 #define FINCH_TYPE_BUDDY_LIST (finch_buddy_list_get_type())
  36 #define FINCH_TYPE_BLIST_MANAGER (finch_blist_manager_get_type())
  37
  38 /**********************************************************************
  39  * GNT BuddyList API
  40  **********************************************************************/
  41
  42 typedef struct _FinchBlistManager  FinchBlistManager;
  43
  44 /**
  45  * FinchBlistManager:
  46  * @id:             An identifier for the manager.
  47  * @name:           Displayable name for the manager.
  48  * @init:           Called right before it's being used.
  49  * @uninit:         Called right after it's not being used any more.
  50  * @can_add_node:   Whether a node should be added to the view.
  51  * @find_parent:    Find the parent row for a node.
  52  * @create_tooltip: Create tooltip for a selected row.
  53  *
  54  * Buddylist manager for finch. This decides the visility, ordering and hierarchy
  55  * of the buddylist nodes. This also manages the creation of tooltips.
  56  */
  57 struct _FinchBlistManager
  58 {
  59         const char *id;
  60         const char *name;
  61         gboolean (*init)(void);
  62         gboolean (*uninit)(void);
  63         gboolean (*can_add_node)(PurpleBlistNode *node);
  64         gpointer (*find_parent)(PurpleBlistNode *node);
  65         gboolean (*create_tooltip)(gpointer selected_row, GString **body, char **title);
  66
  67         /*< private >*/
  68         gpointer reserved[4];
  69 };
  70
  71 /**
  72  * finch_blist_manager_get_type:
  73  *
  74  * Returns: The #GType for the #FinchBlistManager boxed structure.
  75  */
  76 GType finch_blist_manager_get_type(void);
  77
  78 G_DECLARE_FINAL_TYPE(FinchBuddyList, finch_buddy_list, FINCH, BUDDY_LIST,
  79                      PurpleBuddyList)
  80
  81 /**
  82  * finch_blist_init:
  83  *
  84  * Perform necessary initializations.
  85  */
  86 void finch_blist_init(void);
  87
  88 /**
  89  * finch_blist_uninit:
  90  *
  91  * Perform necessary uninitializations.
  92  */
  93 void finch_blist_uninit(void);
  94
  95 /**
  96  * finch_blist_show:
  97  *
  98  * Show the buddy list.
  99  */
 100 void finch_blist_show(void);
 101
 102 /**
 103  * finch_blist_get_position:
 104  * @x: The x-coordinate is set here if not %NULL.
 105  * @y: The y-coordinate is set here if not %NULL.
 106  *
 107  * Get the position of the buddy list.
 108  *
 109  * Returns: Returns %TRUE if the values were set, %FALSE otherwise.
 110  */
 111 gboolean finch_blist_get_position(int *x, int *y);
 112
 113 /**
 114  * finch_blist_set_position:
 115  * @x: The x-coordinate of the buddy list.
 116  * @y: The y-coordinate of the buddy list.
 117  *
 118  * Set the position of the buddy list.
 119  */
 120 void finch_blist_set_position(int x, int y);
 121
 122 /**
 123  * finch_blist_get_size:
 124  * @width:  The width is set here if not %NULL.
 125  * @height: The height is set here if not %NULL.
 126  *
 127  * Get the size of the buddy list.
 128  *
 129  * Returns: Returns %TRUE if the values were set, %FALSE otherwise.
 130  */
 131 gboolean finch_blist_get_size(int *width, int *height);
 132
 133 /**
 134  * finch_blist_set_size:
 135  * @width:  The width of the buddy list.
 136  * @height: The height of the buddy list.
 137  *
 138  * Set the size of the buddy list.
 139  */
 140 void finch_blist_set_size(int width, int height);
 141
 142 /**
 143  * finch_retrieve_user_info:
 144  * @conn:   The connection to get information from
 145  * @name:   The user to get information about.
 146  *
 147  * Get information about a user. Show immediate feedback.
 148  *
 149  * Returns: (transfer none): Returns the ui-handle for the userinfo
 150  *          notification.
 151  */
 152 gpointer finch_retrieve_user_info(PurpleConnection *conn, const char *name);
 153
 154 /**
 155  * finch_blist_get_tree:
 156  *
 157  * Get the tree list of the buddy list.
 158  *
 159  * Returns: (transfer none): The GntTree widget.
 160  */
 161 GntTree * finch_blist_get_tree(void);
 162
 163 /**
 164  * finch_blist_install_manager:
 165  * @manager:   The alternate buddylist manager.
 166  *
 167  * Add an alternate buddy list manager.
 168  */
 169 void finch_blist_install_manager(const FinchBlistManager *manager);
 170
 171 /**
 172  * finch_blist_uninstall_manager:
 173  * @manager:   The buddy list manager to remove.
 174  *
 175  * Remove an alternate buddy list manager.
 176  */
 177 void finch_blist_uninstall_manager(const FinchBlistManager *manager);
 178
 179 /**
 180  * finch_blist_manager_find:
 181  * @id:   The identifier for the desired buddy list manager.
 182  *
 183  * Find a buddy list manager.
 184  *
 185  * Returns: The manager with the requested identifier, if available. %NULL
 186  *          otherwise.
 187  */
 188 FinchBlistManager * finch_blist_manager_find(const char *id);
 189
 190 /**
 191  * finch_blist_manager_add_node:
 192  * @node:  The node to add
 193  *
 194  * Request the active buddy list manager to add a node.
 195  */
 196 void finch_blist_manager_add_node(PurpleBlistNode *node);
 197
 198 #endif