finch/gntblist.h

   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