comparison: src/roomlist.h
src/roomlist.h
- branch
- gaim
- changeset 20470
- 77693555855f
- parent 13071
- b98e72d4089a
- parent 20469
- b2836a24d81e
- child 20471
- 1966704b3e42
equal
deleted
inserted
replaced
| 13071:b98e72d4089a | 20470:77693555855f |
|---|---|
| 1 /** | |
| 2 * @file roomlist.h Room List API | |
| 3 * @ingroup core | |
| 4 * | |
| 5 * gaim | |
| 6 * | |
| 7 * Gaim is the legal property of its developers, whose names are too numerous | |
| 8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
| 9 * source distribution. | |
| 10 * | |
| 11 * This program is free software; you can redistribute it and/or modify | |
| 12 * it under the terms of the GNU General Public License as published by | |
| 13 * the Free Software Foundation; either version 2 of the License, or | |
| 14 * (at your option) any later version. | |
| 15 * | |
| 16 * This program is distributed in the hope that it will be useful, | |
| 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 19 * GNU General Public License for more details. | |
| 20 * | |
| 21 * You should have received a copy of the GNU General Public License | |
| 22 * along with this program; if not, write to the Free Software | |
| 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
| 24 */ | |
| 25 | |
| 26 #ifndef _GAIM_ROOMLIST_H_ | |
| 27 #define _GAIM_ROOMLIST_H_ | |
| 28 | |
| 29 typedef struct _GaimRoomlist GaimRoomlist; | |
| 30 typedef struct _GaimRoomlistRoom GaimRoomlistRoom; | |
| 31 typedef struct _GaimRoomlistField GaimRoomlistField; | |
| 32 typedef struct _GaimRoomlistUiOps GaimRoomlistUiOps; | |
| 33 | |
| 34 /** | |
| 35 * The types of rooms. | |
| 36 * | |
| 37 * These are ORable flags. | |
| 38 */ | |
| 39 typedef enum | |
| 40 { | |
| 41 GAIM_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */ | |
| 42 GAIM_ROOMLIST_ROOMTYPE_ROOM = 0x02 /**< It's a room, like the kind you can join. */ | |
| 43 | |
| 44 } GaimRoomlistRoomType; | |
| 45 | |
| 46 /** | |
| 47 * The types of fields. | |
| 48 */ | |
| 49 typedef enum | |
| 50 { | |
| 51 GAIM_ROOMLIST_FIELD_BOOL, | |
| 52 GAIM_ROOMLIST_FIELD_INT, | |
| 53 GAIM_ROOMLIST_FIELD_STRING /**< We do a g_strdup on the passed value if it's this type. */ | |
| 54 | |
| 55 } GaimRoomlistFieldType; | |
| 56 | |
| 57 #include "account.h" | |
| 58 #include "glib.h" | |
| 59 | |
| 60 /**************************************************************************/ | |
| 61 /** Data Structures */ | |
| 62 /**************************************************************************/ | |
| 63 | |
| 64 /** | |
| 65 * Represents a list of rooms for a given connection on a given protocol. | |
| 66 */ | |
| 67 struct _GaimRoomlist { | |
| 68 GaimAccount *account; /**< The account this list belongs to. */ | |
| 69 GList *fields; /**< The fields. */ | |
| 70 GList *rooms; /**< The list of rooms. */ | |
| 71 gboolean in_progress; /**< The listing is in progress. */ | |
| 72 gpointer ui_data; /**< UI private data. */ | |
| 73 gpointer proto_data; /** Prpl private data. */ | |
| 74 guint ref; /**< The reference count. */ | |
| 75 }; | |
| 76 | |
| 77 /** | |
| 78 * Represents a room. | |
| 79 */ | |
| 80 struct _GaimRoomlistRoom { | |
| 81 GaimRoomlistRoomType type; /**< The type of room. */ | |
| 82 gchar *name; /**< The name of the room. */ | |
| 83 GList *fields; /**< Other fields. */ | |
| 84 GaimRoomlistRoom *parent; /**< The parent room, or NULL. */ | |
| 85 gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */ | |
| 86 }; | |
| 87 | |
| 88 /** | |
| 89 * A field a room might have. | |
| 90 */ | |
| 91 struct _GaimRoomlistField { | |
| 92 GaimRoomlistFieldType type; /**< The type of field. */ | |
| 93 gchar *label; /**< The i18n user displayed name of the field. */ | |
| 94 gchar *name; /**< The internal name of the field. */ | |
| 95 gboolean hidden; /**< Hidden? */ | |
| 96 }; | |
| 97 | |
| 98 /** | |
| 99 * The room list ops to be filled out by the UI. | |
| 100 */ | |
| 101 struct _GaimRoomlistUiOps { | |
| 102 void (*show_with_account)(GaimAccount *account); /**< Force the ui to pop up a dialog and get the list */ | |
| 103 void (*create)(GaimRoomlist *list); /**< A new list was created. */ | |
| 104 void (*set_fields)(GaimRoomlist *list, GList *fields); /**< Sets the columns. */ | |
| 105 void (*add_room)(GaimRoomlist *list, GaimRoomlistRoom *room); /**< Add a room to the list. */ | |
| 106 void (*in_progress)(GaimRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */ | |
| 107 void (*destroy)(GaimRoomlist *list); /**< We're destroying list. */ | |
| 108 }; | |
| 109 | |
| 110 | |
| 111 #ifdef __cplusplus | |
| 112 extern "C" { | |
| 113 #endif | |
| 114 | |
| 115 /**************************************************************************/ | |
| 116 /** @name Room List API */ | |
| 117 /**************************************************************************/ | |
| 118 /*@{*/ | |
| 119 | |
| 120 /** | |
| 121 * This is used to get the room list on an account, asking the UI | |
| 122 * to pop up a dialog with the specified account already selected, | |
| 123 * and pretend the user clicked the get list button. | |
| 124 * While we're pretending, predend I didn't say anything about dialogs | |
| 125 * or buttons, since this is the core. | |
| 126 * | |
| 127 * @param account The account to get the list on. | |
| 128 */ | |
| 129 void gaim_roomlist_show_with_account(GaimAccount *account); | |
| 130 | |
| 131 /** | |
| 132 * Returns a newly created room list object. | |
| 133 * | |
| 134 * It has an initial reference count of 1. | |
| 135 * | |
| 136 * @param account The account that's listing rooms. | |
| 137 * @return The new room list handle. | |
| 138 */ | |
| 139 GaimRoomlist *gaim_roomlist_new(GaimAccount *account); | |
| 140 | |
| 141 /** | |
| 142 * Increases the reference count on the room list. | |
| 143 * | |
| 144 * @param list The object to ref. | |
| 145 */ | |
| 146 void gaim_roomlist_ref(GaimRoomlist *list); | |
| 147 | |
| 148 /** | |
| 149 * Decreases the reference count on the room list. | |
| 150 * | |
| 151 * The room list will be destroyed when this reaches 0. | |
| 152 * | |
| 153 * @param list The room list object to unref and possibly | |
| 154 * destroy. | |
| 155 */ | |
| 156 void gaim_roomlist_unref(GaimRoomlist *list); | |
| 157 | |
| 158 /** | |
| 159 * Set the different field types and their names for this protocol. | |
| 160 * | |
| 161 * This must be called before gaim_roomlist_room_add(). | |
| 162 * | |
| 163 * @param list The room list. | |
| 164 * @param fields A GList of GaimRoomlistField's. UI's are encouraged | |
| 165 * to default to displaying them in the order given. | |
| 166 */ | |
| 167 void gaim_roomlist_set_fields(GaimRoomlist *list, GList *fields); | |
| 168 | |
| 169 /** | |
| 170 * Set the "in progress" state of the room list. | |
| 171 * | |
| 172 * The UI is encouraged to somehow hint to the user | |
| 173 * whether or not we're busy downloading a room list or not. | |
| 174 * | |
| 175 * @param list The room list. | |
| 176 * @param in_progress We're downloading it, or we're not. | |
| 177 */ | |
| 178 void gaim_roomlist_set_in_progress(GaimRoomlist *list, gboolean in_progress); | |
| 179 | |
| 180 /** | |
| 181 * Gets the "in progress" state of the room list. | |
| 182 * | |
| 183 * The UI is encouraged to somehow hint to the user | |
| 184 * whether or not we're busy downloading a room list or not. | |
| 185 * | |
| 186 * @param list The room list. | |
| 187 * @return True if we're downloading it, or false if we're not. | |
| 188 */ | |
| 189 gboolean gaim_roomlist_get_in_progress(GaimRoomlist *list); | |
| 190 | |
| 191 /** | |
| 192 * Adds a room to the list of them. | |
| 193 * | |
| 194 * @param list The room list. | |
| 195 * @param room The room to add to the list. The GList of fields must be in the same | |
| 196 order as was given in gaim_roomlist_set_fields(). | |
| 197 */ | |
| 198 void gaim_roomlist_room_add(GaimRoomlist *list, GaimRoomlistRoom *room); | |
| 199 | |
| 200 /** | |
| 201 * Returns a GaimRoomlist structure from the prpl, and | |
| 202 * instructs the prpl to start fetching the list. | |
| 203 * | |
| 204 * @param gc The GaimConnection to have get a list. | |
| 205 * | |
| 206 * @return A GaimRoomlist* or @c NULL if the protocol | |
| 207 * doesn't support that. | |
| 208 */ | |
| 209 GaimRoomlist *gaim_roomlist_get_list(GaimConnection *gc); | |
| 210 | |
| 211 /** | |
| 212 * Tells the prpl to stop fetching the list. | |
| 213 * If this is possible and done, the prpl will | |
| 214 * call set_in_progress with @c FALSE and possibly | |
| 215 * unref the list if it took a reference. | |
| 216 * | |
| 217 * @param list The room list to cancel a get_list on. | |
| 218 */ | |
| 219 void gaim_roomlist_cancel_get_list(GaimRoomlist *list); | |
| 220 | |
| 221 /** | |
| 222 * Tells the prpl that a category was expanded. | |
| 223 * | |
| 224 * On some protocols, the rooms in the category | |
| 225 * won't be fetched until this is called. | |
| 226 * | |
| 227 * @param list The room list. | |
| 228 * @param category The category that was expanded. The expression | |
| 229 * (category->type & GAIM_ROOMLIST_ROOMTYPE_CATEGORY) | |
| 230 * must be true. | |
| 231 */ | |
| 232 void gaim_roomlist_expand_category(GaimRoomlist *list, GaimRoomlistRoom *category); | |
| 233 | |
| 234 /*@}*/ | |
| 235 | |
| 236 /**************************************************************************/ | |
| 237 /** @name Room API */ | |
| 238 /**************************************************************************/ | |
| 239 /*@{*/ | |
| 240 | |
| 241 /** | |
| 242 * Creates a new room, to be added to the list. | |
| 243 * | |
| 244 * @param type The type of room. | |
| 245 * @param name The name of the room. | |
| 246 * @param parent The room's parent, if any. | |
| 247 * | |
| 248 * @return A new room. | |
| 249 */ | |
| 250 GaimRoomlistRoom *gaim_roomlist_room_new(GaimRoomlistRoomType type, const gchar *name, | |
| 251 GaimRoomlistRoom *parent); | |
| 252 | |
| 253 /** | |
| 254 * Adds a field to a room. | |
| 255 * | |
| 256 * @param list The room list the room belongs to. | |
| 257 * @param room The room. | |
| 258 * @param field The field to append. Strings get g_strdup'd internally. | |
| 259 */ | |
| 260 void gaim_roomlist_room_add_field(GaimRoomlist *list, GaimRoomlistRoom *room, gconstpointer field); | |
| 261 | |
| 262 /** | |
| 263 * Join a room, given a GaimRoomlistRoom and it's associated GaimRoomlist. | |
| 264 * | |
| 265 * @param list The room list the room belongs to. | |
| 266 * @param room The room to join. | |
| 267 */ | |
| 268 void gaim_roomlist_room_join(GaimRoomlist *list, GaimRoomlistRoom *room); | |
| 269 | |
| 270 /*@}*/ | |
| 271 | |
| 272 /**************************************************************************/ | |
| 273 /** @name Room Field API */ | |
| 274 /**************************************************************************/ | |
| 275 /*@{*/ | |
| 276 | |
| 277 /** | |
| 278 * Creates a new field. | |
| 279 * | |
| 280 * @param type The type of the field. | |
| 281 * @param label The i18n'ed, user displayable name. | |
| 282 * @param name The internal name of the field. | |
| 283 * @param hidden Hide the field. | |
| 284 * | |
| 285 * @return A new GaimRoomlistField, ready to be added to a GList and passed to | |
| 286 * gaim_roomlist_set_fields(). | |
| 287 */ | |
| 288 GaimRoomlistField *gaim_roomlist_field_new(GaimRoomlistFieldType type, | |
| 289 const gchar *label, const gchar *name, | |
| 290 gboolean hidden); | |
| 291 /*@}*/ | |
| 292 | |
| 293 /**************************************************************************/ | |
| 294 /** @name UI Registration Functions */ | |
| 295 /**************************************************************************/ | |
| 296 /*@{*/ | |
| 297 | |
| 298 /** | |
| 299 * Sets the UI operations structure to be used in all gaim room lists. | |
| 300 * | |
| 301 * @param ops The UI operations structure. | |
| 302 */ | |
| 303 void gaim_roomlist_set_ui_ops(GaimRoomlistUiOps *ops); | |
| 304 | |
| 305 /** | |
| 306 * Returns the gaim window UI operations structure to be used in | |
| 307 * new windows. | |
| 308 * | |
| 309 * @return A filled-out GaimRoomlistUiOps structure. | |
| 310 */ | |
| 311 GaimRoomlistUiOps *gaim_roomlist_get_ui_ops(void); | |
| 312 | |
| 313 /*@}*/ | |
| 314 | |
| 315 #ifdef __cplusplus | |
| 316 } | |
| 317 #endif | |
| 318 | |
| 319 #endif /* _GAIM_ROOMLIST_H_ */ |
