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