Mercurial > pidgin.yaz
annotate src/roomlist.h @ 8937:fd1a4ff1f7ed
[gaim-migrate @ 9707]
Tools->Room List will now be grayed out when you're not signed on
with an account that supports listing rooms.
This involved 2 big changes:
-Change when the sign_on_off_cb function in gtkblist gets called...
it used to get called when the signing-on and signing-off signal
was emitted, but I changed it to signed-on and signed-off. This
makes more sense to me, and it makes my code work :-) Let me know
if you notice any side-effects
-Add functions to the roomlist API for determining if any online
accounts support chatting or not. This involved extracting a
function from gtkroomlist.c and putting it in roomlist.c, and
adding a little helper TRUE/FALSE function
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Sat, 15 May 2004 21:56:17 +0000 |
parents | c2dff943e240 |
children | 19885cb8a24c |
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 | |
29 /**************************************************************************/ | |
30 /** Data Structures */ | |
31 /**************************************************************************/ | |
32 | |
33 typedef struct _GaimRoomlist GaimRoomlist; | |
34 typedef struct _GaimRoomlistRoom GaimRoomlistRoom; | |
35 typedef enum _GaimRoomlistRoomType GaimRoomlistRoomType; | |
36 typedef struct _GaimRoomlistField GaimRoomlistField; | |
37 typedef enum _GaimRoomlistFieldType GaimRoomlistFieldType; | |
38 typedef struct _GaimRoomlistUiOps GaimRoomlistUiOps; | |
39 | |
40 /** | |
41 * Represents a list of rooms for a given connection on a given protocol. | |
42 */ | |
43 struct _GaimRoomlist { | |
44 GaimAccount *account; /**< The account this list belongs to. */ | |
45 GList *fields; /**< The fields. */ | |
46 GList *rooms; /**< The list of rooms. */ | |
8199 | 47 gboolean in_progress; /**< The listing is in progress. */ |
8113 | 48 gpointer ui_data; /**< UI private data. */ |
49 gpointer proto_data; /** Prpl private data. */ | |
50 guint ref; /**< The reference count. */ | |
51 }; | |
52 | |
53 /** | |
54 * The types of rooms. | |
55 * | |
56 * These are ORable flags. | |
57 */ | |
58 enum _GaimRoomlistRoomType { | |
8584 | 59 GAIM_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */ |
8113 | 60 GAIM_ROOMLIST_ROOMTYPE_ROOM = 0x02, /**< It's a room, like the kind you can join. */ |
61 }; | |
62 | |
63 /** | |
64 * Represents a room. | |
65 */ | |
66 struct _GaimRoomlistRoom { | |
67 GaimRoomlistRoomType type; /**< The type of room. */ | |
68 gchar *name; /**< The name of the room. */ | |
69 GList *fields; /**< Other fields. */ | |
70 GaimRoomlistRoom *parent; /**< The parent room, or NULL. */ | |
71 gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */ | |
72 }; | |
73 | |
74 /** | |
75 * The types of fields. | |
76 */ | |
77 enum _GaimRoomlistFieldType { | |
78 GAIM_ROOMLIST_FIELD_BOOL, | |
79 GAIM_ROOMLIST_FIELD_INT, | |
80 GAIM_ROOMLIST_FIELD_STRING, /**< We do a g_strdup on the passed value if it's this type. */ | |
81 }; | |
82 | |
83 /** | |
84 * A field a room might have. | |
85 */ | |
86 struct _GaimRoomlistField { | |
87 GaimRoomlistFieldType type; /**< The type of field. */ | |
88 gchar *label; /**< The i18n user displayed name of the field. */ | |
89 gchar *name; /**< The internal name of the field. */ | |
90 gboolean hidden; /**< Hidden? */ | |
91 }; | |
92 | |
93 /** | |
94 * The room list ops to be filled out by the UI. | |
95 */ | |
96 struct _GaimRoomlistUiOps { | |
8352 | 97 void (*show_with_account)(GaimAccount *account); /**< Force the ui to pop up a dialog and get the list */ |
8113 | 98 void (*new)(GaimRoomlist *list); /**< A new list was created. */ |
99 void (*set_fields)(GaimRoomlist *list, GList *fields); /**< Sets the columns. */ | |
100 void (*add_room)(GaimRoomlist *list, GaimRoomlistRoom *room); /**< Add a room to the list. */ | |
101 void (*in_progress)(GaimRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */ | |
102 void (*destroy)(GaimRoomlist *list); /**< We're destroying list. */ | |
103 }; | |
104 | |
105 | |
106 #ifdef __cplusplus | |
107 extern "C" { | |
108 #endif | |
109 | |
110 /**************************************************************************/ | |
111 /** @name Room List API */ | |
112 /**************************************************************************/ | |
113 /*@{*/ | |
114 | |
115 /** | |
8937 | 116 * Return true if there are accounts signed on that support showing |
117 * a roomlist. | |
118 * | |
119 * @return True if showing the roomlist is a valid action. | |
120 */ | |
121 gboolean gaim_roomlist_is_showable(); | |
122 | |
123 /** | |
124 * Get the first online acocunt that supports showing a roomlist. | |
125 * | |
126 * @return The first selected account of all the accounts that | |
127 * support showing a roomlist. | |
128 */ | |
129 GaimAccount *gaim_roomlist_get_first_valid_account(); | |
130 | |
131 /** | |
8352 | 132 * This is used to get the room list on an account, asking the UI |
133 * to pop up a dialog with the specified account already selected, | |
134 * and pretend the user clicked the get list button. | |
135 * While we're pretending, predend I didn't say anything about dialogs | |
136 * or buttons, since this is the core. | |
137 * | |
138 * @param account The account to get the list on. | |
139 */ | |
140 void gaim_roomlist_show_with_account(GaimAccount *account); | |
141 | |
142 /** | |
8113 | 143 * Returns a newly created room list object. |
144 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
145 * It has an initial reference count of 1. |
8113 | 146 * |
147 * @param account The account that's listing rooms. | |
148 * @return The new room list handle. | |
149 */ | |
150 GaimRoomlist *gaim_roomlist_new(GaimAccount *account); | |
151 | |
152 /** | |
153 * Increases the reference count on the room list. | |
154 * | |
155 * @param list The object to ref. | |
156 */ | |
157 void gaim_roomlist_ref(GaimRoomlist *list); | |
158 | |
159 /** | |
160 * Decreases the reference count on the room list. | |
161 * | |
162 * The room list will be destroyed when this reaches 0. | |
163 * | |
164 * @param list The room list object to unref and possibly | |
165 * destroy. | |
166 */ | |
167 void gaim_roomlist_unref(GaimRoomlist *list); | |
168 | |
169 /** | |
170 * Set the different field types and their names for this protocol. | |
171 * | |
172 * This must be called before gaim_roomlist_room_add(). | |
173 * | |
174 * @param list The room list. | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
175 * @param fields A GList of GaimRoomlistField's. UI's are encouraged |
8113 | 176 * to default to displaying them in the order given. |
177 */ | |
178 void gaim_roomlist_set_fields(GaimRoomlist *list, GList *fields); | |
179 | |
180 /** | |
181 * Set 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 |
8113 | 184 * whether or not we're busy downloading a room list or not. |
185 * | |
186 * @param list The room list. | |
187 * @param in_progress We're downloading it, or we're not. | |
188 */ | |
189 void gaim_roomlist_set_in_progress(GaimRoomlist *list, gboolean in_progress); | |
190 | |
191 /** | |
8199 | 192 * Gets the "in progress" state of the room list. |
193 * | |
8735
92cbf9713795
[gaim-migrate @ 9490]
Christian Hammond <chipx86@chipx86.com>
parents:
8584
diff
changeset
|
194 * The UI is encouraged to somehow hint to the user |
8199 | 195 * whether or not we're busy downloading a room list or not. |
196 * | |
197 * @param list The room list. | |
8866 | 198 * @return True if we're downloading it, or false if we're not. |
8199 | 199 */ |
200 gboolean gaim_roomlist_get_in_progress(GaimRoomlist *list); | |
201 | |
202 /** | |
8113 | 203 * Adds a room to the list of them. |
204 * | |
205 * @param list The room list. | |
206 * @param room The room to add to the list. The GList of fields must be in the same | |
207 order as was given in gaim_roomlist_set_fields(). | |
208 */ | |
209 void gaim_roomlist_room_add(GaimRoomlist *list, GaimRoomlistRoom *room); | |
210 | |
211 /** | |
212 * Do we support room listing? | |
213 * | |
214 * @param gc The GaimConnection we're asking. | |
215 * @return @c TRUE if it's possible to get a room list. | |
216 */ | |
217 gboolean gaim_roomlist_is_possible(GaimConnection *gc); | |
218 | |
219 /** | |
220 * Returns a GaimRoomlist structure from the prpl, and | |
221 * instructs the prpl to start fetching the list. | |
222 * | |
223 * @param gc The GaimConnection to have get a list. | |
224 * | |
225 * @return A GaimRoomlist* or @c NULL if the protocol | |
226 * doesn't support that. | |
227 */ | |
228 GaimRoomlist *gaim_roomlist_get_list(GaimConnection *gc); | |
229 | |
230 /** | |
231 * Tells the prpl to stop fetching the list. | |
232 * If this is possible and done, the prpl will | |
233 * call set_in_progress with @c FALSE and possibly | |
234 * unref the list if it took a reference. | |
235 * | |
236 * @param list The room list to cancel a get_list on. | |
237 */ | |
238 void gaim_roomlist_cancel_get_list(GaimRoomlist *list); | |
239 | |
240 /** | |
8584 | 241 * Tells the prpl that a category was expanded. |
8113 | 242 * |
8584 | 243 * On some protocols, the rooms in the category |
8113 | 244 * won't be fetched until this is called. |
245 * | |
246 * @param list The room list. | |
8584 | 247 * @param room The category that was expanded. The expression |
248 * (category->type & GAIM_ROOMLIST_ROOMTYPE_CATEGORY) | |
8113 | 249 * must be true. |
250 */ | |
8584 | 251 void gaim_roomlist_expand_category(GaimRoomlist *list, GaimRoomlistRoom *category); |
8113 | 252 |
253 /*@}*/ | |
254 | |
255 /**************************************************************************/ | |
256 /** @name Room API */ | |
257 /**************************************************************************/ | |
258 /*@{*/ | |
259 | |
260 /** | |
261 * Creates a new room, to be added to the list. | |
262 * | |
263 * @param type The type of room. | |
264 * @param name The name of the room. | |
265 * @param parent The room's parent, if any. | |
266 * | |
267 * @return A new room. | |
268 */ | |
269 GaimRoomlistRoom *gaim_roomlist_room_new(GaimRoomlistRoomType type, const gchar *name, | |
270 GaimRoomlistRoom *parent); | |
271 | |
272 /** | |
273 * Adds a field to a room. | |
274 * | |
275 * @param list The room list the room belongs to. | |
276 * @param room The room. | |
277 * @param field The field to append. Strings get g_strdup'd internally. | |
278 */ | |
279 void gaim_roomlist_room_add_field(GaimRoomlist *list, GaimRoomlistRoom *room, gconstpointer field); | |
280 | |
8199 | 281 /** |
282 * Join a room, given a GaimRoomlistRoom and it's associated GaimRoomlist. | |
283 * | |
284 * @param list The room list the room belongs to. | |
285 * @param room The room to join. | |
286 */ | |
287 void gaim_roomlist_room_join(GaimRoomlist *list, GaimRoomlistRoom *room); | |
288 | |
8113 | 289 /*@}*/ |
290 | |
291 /**************************************************************************/ | |
292 /** @name Room Field API */ | |
293 /**************************************************************************/ | |
294 /*@{*/ | |
295 | |
296 /** | |
297 * Creates a new field. | |
298 * | |
299 * @param type The type of the field. | |
300 * @param label The i18n'ed, user displayable name. | |
301 * @param name The internal name of the field. | |
302 * | |
303 * @return A new GaimRoomlistField, ready to be added to a GList and passed to | |
304 * gaim_roomlist_set_fields(). | |
305 */ | |
306 GaimRoomlistField *gaim_roomlist_field_new(GaimRoomlistFieldType type, | |
307 const gchar *label, const gchar *name, | |
308 gboolean hidden); | |
309 /*@}*/ | |
310 | |
311 /**************************************************************************/ | |
312 /** @name UI Registration Functions */ | |
313 /**************************************************************************/ | |
314 /*@{*/ | |
315 | |
316 /** | |
317 * Sets the UI operations structure to be used in all gaim room lists. | |
318 * | |
319 * @param ops The UI operations structure. | |
320 */ | |
321 void gaim_roomlist_set_ui_ops(GaimRoomlistUiOps *ops); | |
322 | |
323 /** | |
324 * Returns the gaim window UI operations structure to be used in | |
325 * new windows. | |
326 * | |
327 * @return A filled-out GaimRoomlistUiOps structure. | |
328 */ | |
329 GaimRoomlistUiOps *gaim_roomlist_get_ui_ops(void); | |
330 | |
331 /*@}*/ | |
332 | |
333 #ifdef __cplusplus | |
334 } | |
335 #endif | |
336 | |
337 #endif /* _GAIM_ROOMLIST_H_ */ |