Mercurial > pidgin
annotate src/roomlist.h @ 13238:1e855032d7bc
[gaim-migrate @ 15604]
Someone in #wingaim said this was necessary
committer: Tailor Script <tailor@pidgin.im>
author | Stu Tomlinson <stu@nosnilmot.com> |
---|---|
date | Sun, 12 Feb 2006 15:27:11 +0000 |
parents | 5151c6788f3d |
children |
rev | line source |
---|---|
8113 | 1 /** |
2 * @file roomlist.h Room List API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
8146 | 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. | |
8113 | 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 | |
9999 | 29 typedef struct _GaimRoomlist GaimRoomlist; |
30 typedef struct _GaimRoomlistRoom GaimRoomlistRoom; | |
31 typedef struct _GaimRoomlistField GaimRoomlistField; | |
32 typedef struct _GaimRoomlistUiOps GaimRoomlistUiOps; | |
9030 | 33 |
9999 | 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 | |
9030 | 57 #include "account.h" |
10023 | 58 #include "glib.h" |
9030 | 59 |
8113 | 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. */ | |
8199 | 71 gboolean in_progress; /**< The listing is in progress. */ |
8113 | 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 { | |
8352 | 102 void (*show_with_account)(GaimAccount *account); /**< Force the ui to pop up a dialog and get the list */ |
10027 | 103 void (*create)(GaimRoomlist *list); /**< A new list was created. */ |
8113 | 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 /** | |
8352 | 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 /** | |
8113 | 132 * Returns a newly created room list object. |
133 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
134 * It has an initial reference count of 1. |
8113 | 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. | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
164 * @param fields A GList of GaimRoomlistField's. UI's are encouraged |
8113 | 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 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
172 * The UI is encouraged to somehow hint to the user |
8113 | 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 /** | |
8199 | 181 * Gets the "in progress" state of the room list. |
182 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
183 * The UI is encouraged to somehow hint to the user |
8199 | 184 * whether or not we're busy downloading a room list or not. |
185 * | |
186 * @param list The room list. | |
8866 | 187 * @return True if we're downloading it, or false if we're not. |
8199 | 188 */ |
189 gboolean gaim_roomlist_get_in_progress(GaimRoomlist *list); | |
190 | |
191 /** | |
8113 | 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 /** | |
8584 | 222 * Tells the prpl that a category was expanded. |
8113 | 223 * |
8584 | 224 * On some protocols, the rooms in the category |
8113 | 225 * won't be fetched until this is called. |
226 * | |
9000 | 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. | |
8113 | 231 */ |
8584 | 232 void gaim_roomlist_expand_category(GaimRoomlist *list, GaimRoomlistRoom *category); |
8113 | 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 | |
8199 | 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 | |
8113 | 270 /*@}*/ |
271 | |
272 /**************************************************************************/ | |
273 /** @name Room Field API */ | |
274 /**************************************************************************/ | |
275 /*@{*/ | |
276 | |
277 /** | |
278 * Creates a new field. | |
279 * | |
9000 | 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. | |
8113 | 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_ */ |