Mercurial > pidgin3 / file comparison

comparison: libpurple/accountopt.h

libpurple/accountopt.h

branch
gtkdoc-conversion
changeset 35393
00f876b129bc
parent 33267
c3ee96290bfd
child 35394
38facb8226d4
equal deleted inserted replaced
35392:cc123f0d84af 35393:00f876b129bc
48 * Creates a new account option. If you know what @a type will be in advance, 48 * Creates a new account option. If you know what @a type will be in advance,
49 * consider using purple_account_option_bool_new(), 49 * consider using purple_account_option_bool_new(),
50 * purple_account_option_int_new(), purple_account_option_string_new() or 50 * purple_account_option_int_new(), purple_account_option_string_new() or
51 * purple_account_option_list_new() (as appropriate) instead. 51 * purple_account_option_list_new() (as appropriate) instead.
52 * 52 *
53 * @param type The type of option. 53 * @type: The type of option.
54 * @param text The text of the option. 54 * @text: The text of the option.
55 * @param pref_name The account preference name for the option. 55 * @pref_name: The account preference name for the option.
56 * 56 *
57 * @return The account option. 57 * Returns: The account option.
58 */ 58 */
59 PurpleAccountOption *purple_account_option_new(PurplePrefType type, 59 PurpleAccountOption *purple_account_option_new(PurplePrefType type,
60 const char *text, const char *pref_name); 60 const char *text, const char *pref_name);
61 61
62 /** 62 /**
63 * Creates a new boolean account option. 63 * Creates a new boolean account option.
64 * 64 *
65 * @param text The text of the option. 65 * @text: The text of the option.
66 * @param pref_name The account preference name for the option. 66 * @pref_name: The account preference name for the option.
67 * @param default_value The default value. 67 * @default_value: The default value.
68 * 68 *
69 * @return The account option. 69 * Returns: The account option.
70 */ 70 */
71 PurpleAccountOption *purple_account_option_bool_new(const char *text, 71 PurpleAccountOption *purple_account_option_bool_new(const char *text,
72 const char *pref_name, gboolean default_value); 72 const char *pref_name, gboolean default_value);
73 73
74 /** 74 /**
75 * Creates a new integer account option. 75 * Creates a new integer account option.
76 * 76 *
77 * @param text The text of the option. 77 * @text: The text of the option.
78 * @param pref_name The account preference name for the option. 78 * @pref_name: The account preference name for the option.
79 * @param default_value The default value. 79 * @default_value: The default value.
80 * 80 *
81 * @return The account option. 81 * Returns: The account option.
82 */ 82 */
83 PurpleAccountOption *purple_account_option_int_new(const char *text, 83 PurpleAccountOption *purple_account_option_int_new(const char *text,
84 const char *pref_name, int default_value); 84 const char *pref_name, int default_value);
85 85
86 /** 86 /**
87 * Creates a new string account option. 87 * Creates a new string account option.
88 * 88 *
89 * @param text The text of the option. 89 * @text: The text of the option.
90 * @param pref_name The account preference name for the option. 90 * @pref_name: The account preference name for the option.
91 * @param default_value The default value. 91 * @default_value: The default value.
92 * 92 *
93 * @return The account option. 93 * Returns: The account option.
94 */ 94 */
95 PurpleAccountOption *purple_account_option_string_new(const char *text, 95 PurpleAccountOption *purple_account_option_string_new(const char *text,
96 const char *pref_name, const char *default_value); 96 const char *pref_name, const char *default_value);
97 97
98 /** 98 /**
104 * The list is a list of #PurpleKeyValuePair items. The key is the label that 104 * The list is a list of #PurpleKeyValuePair items. The key is the label that
105 * should be displayed to the user, and the <tt>(const char *)</tt> value is 105 * should be displayed to the user, and the <tt>(const char *)</tt> value is
106 * the internal ID that should be passed to purple_account_set_string() to 106 * the internal ID that should be passed to purple_account_set_string() to
107 * choose that value. 107 * choose that value.
108 * 108 *
109 * @param text The text of the option. 109 * @text: The text of the option.
110 * @param pref_name The account preference name for the option. 110 * @pref_name: The account preference name for the option.
111 * @param list The key, value list. 111 * @list: The key, value list.
112 * 112 *
113 * @return The account option. 113 * Returns: The account option.
114 */ 114 */
115 PurpleAccountOption *purple_account_option_list_new(const char *text, 115 PurpleAccountOption *purple_account_option_list_new(const char *text,
116 const char *pref_name, GList *list); 116 const char *pref_name, GList *list);
117 117
118 /** 118 /**
119 * Destroys an account option. 119 * Destroys an account option.
120 * 120 *
121 * @param option The option to destroy. 121 * @option: The option to destroy.
122 */ 122 */
123 void purple_account_option_destroy(PurpleAccountOption *option); 123 void purple_account_option_destroy(PurpleAccountOption *option);
124 124
125 /** 125 /**
126 * Sets the default boolean value for an account option. 126 * Sets the default boolean value for an account option.
127 * 127 *
128 * @param option The account option. 128 * @option: The account option.
129 * @param value The default boolean value. 129 * @value: The default boolean value.
130 */ 130 */
131 void purple_account_option_set_default_bool(PurpleAccountOption *option, 131 void purple_account_option_set_default_bool(PurpleAccountOption *option,
132 gboolean value); 132 gboolean value);
133 133
134 /** 134 /**
135 * Sets the default integer value for an account option. 135 * Sets the default integer value for an account option.
136 * 136 *
137 * @param option The account option. 137 * @option: The account option.
138 * @param value The default integer value. 138 * @value: The default integer value.
139 */ 139 */
140 void purple_account_option_set_default_int(PurpleAccountOption *option, 140 void purple_account_option_set_default_int(PurpleAccountOption *option,
141 int value); 141 int value);
142 142
143 /** 143 /**
144 * Sets the default string value for an account option. 144 * Sets the default string value for an account option.
145 * 145 *
146 * @param option The account option. 146 * @option: The account option.
147 * @param value The default string value. 147 * @value: The default string value.
148 */ 148 */
149 void purple_account_option_set_default_string(PurpleAccountOption *option, 149 void purple_account_option_set_default_string(PurpleAccountOption *option,
150 const char *value); 150 const char *value);
151 151
152 /** 152 /**
153 * Sets the masking for an account option. Setting this to %TRUE acts 153 * Sets the masking for an account option. Setting this to %TRUE acts
154 * as a hint to the UI that the option's value should be obscured from 154 * as a hint to the UI that the option's value should be obscured from
155 * view, like a password. 155 * view, like a password.
156 * 156 *
157 * @param option The account option. 157 * @option: The account option.
158 * @param masked The masking. 158 * @masked: The masking.
159 */ 159 */
160 void 160 void
161 purple_account_option_string_set_masked(PurpleAccountOption *option, gboolean masked); 161 purple_account_option_string_set_masked(PurpleAccountOption *option, gboolean masked);
162 162
163 /** 163 /**
164 * Sets the hint list for an account option. 164 * Sets the hint list for an account option.
165 * 165 *
166 * The list passed will be owned by the account option, and the 166 * The list passed will be owned by the account option, and the
167 * strings inside will be freed automatically. 167 * strings inside will be freed automatically.
168 * 168 *
169 * @param option The account option. 169 * @option: The account option.
170 * @param hints The list of hints, stored as strings. 170 * @hints: The list of hints, stored as strings.
171 */ 171 */
172 void purple_account_option_string_set_hints(PurpleAccountOption *option, 172 void purple_account_option_string_set_hints(PurpleAccountOption *option,
173 GSList *hints); 173 GSList *hints);
174 174
175 /** 175 /**
179 * strings inside will be freed automatically. 179 * strings inside will be freed automatically.
180 * 180 *
181 * The list is in key, value pairs. The key is the ID stored and used 181 * The list is in key, value pairs. The key is the ID stored and used
182 * internally, and the value is the label displayed. 182 * internally, and the value is the label displayed.
183 * 183 *
184 * @param option The account option. 184 * @option: The account option.
185 * @param values The default list value. 185 * @values: The default list value.
186 */ 186 */
187 void purple_account_option_set_list(PurpleAccountOption *option, GList *values); 187 void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
188 188
189 /** 189 /**
190 * Adds an item to a list account option. 190 * Adds an item to a list account option.
191 * 191 *
192 * @param option The account option. 192 * @option: The account option.
193 * @param key The key. 193 * @key: The key.
194 * @param value The value. 194 * @value: The value.
195 */ 195 */
196 void purple_account_option_add_list_item(PurpleAccountOption *option, 196 void purple_account_option_add_list_item(PurpleAccountOption *option,
197 const char *key, const char *value); 197 const char *key, const char *value);
198 198
199 /** 199 /**
200 * Returns the specified account option's type. 200 * Returns the specified account option's type.
201 * 201 *
202 * @param option The account option. 202 * @option: The account option.
203 * 203 *
204 * @return The account option's type. 204 * Returns: The account option's type.
205 */ 205 */
206 PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option); 206 PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option);
207 207
208 /** 208 /**
209 * Returns the text for an account option. 209 * Returns the text for an account option.
210 * 210 *
211 * @param option The account option. 211 * @option: The account option.
212 * 212 *
213 * @return The account option's text. 213 * Returns: The account option's text.
214 */ 214 */
215 const char *purple_account_option_get_text(const PurpleAccountOption *option); 215 const char *purple_account_option_get_text(const PurpleAccountOption *option);
216 216
217 /** 217 /**
218 * Returns the name of an account option. This corresponds to the @c pref_name 218 * Returns the name of an account option. This corresponds to the @c pref_name
219 * parameter supplied to purple_account_option_new() or one of the 219 * parameter supplied to purple_account_option_new() or one of the
220 * type-specific constructors. 220 * type-specific constructors.
221 * 221 *
222 * @param option The account option. 222 * @option: The account option.
223 * 223 *
224 * @return The option's name. 224 * Returns: The option's name.
225 */ 225 */
226 const char *purple_account_option_get_setting(const PurpleAccountOption *option); 226 const char *purple_account_option_get_setting(const PurpleAccountOption *option);
227 227
228 /** 228 /**
229 * Returns the default boolean value for an account option. 229 * Returns the default boolean value for an account option.
230 * 230 *
231 * @param option The account option. 231 * @option: The account option.
232 * 232 *
233 * @return The default boolean value. 233 * Returns: The default boolean value.
234 */ 234 */
235 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option); 235 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
236 236
237 /** 237 /**
238 * Returns the default integer value for an account option. 238 * Returns the default integer value for an account option.
239 * 239 *
240 * @param option The account option. 240 * @option: The account option.
241 * 241 *
242 * @return The default integer value. 242 * Returns: The default integer value.
243 */ 243 */
244 int purple_account_option_get_default_int(const PurpleAccountOption *option); 244 int purple_account_option_get_default_int(const PurpleAccountOption *option);
245 245
246 /** 246 /**
247 * Returns the default string value for an account option. 247 * Returns the default string value for an account option.
248 * 248 *
249 * @param option The account option. 249 * @option: The account option.
250 * 250 *
251 * @return The default string value. 251 * Returns: The default string value.
252 */ 252 */
253 const char *purple_account_option_get_default_string( 253 const char *purple_account_option_get_default_string(
254 const PurpleAccountOption *option); 254 const PurpleAccountOption *option);
255 255
256 /** 256 /**
257 * Returns the default string value for a list account option. 257 * Returns the default string value for a list account option.
258 * 258 *
259 * @param option The account option. 259 * @option: The account option.
260 * 260 *
261 * @return The default list string value. 261 * Returns: The default list string value.
262 */ 262 */
263 const char *purple_account_option_get_default_list_value( 263 const char *purple_account_option_get_default_list_value(
264 const PurpleAccountOption *option); 264 const PurpleAccountOption *option);
265 265
266 /** 266 /**
267 * Returns whether an option's value should be masked from view, like a 267 * Returns whether an option's value should be masked from view, like a
268 * password. If so, the UI might display each character of the option 268 * password. If so, the UI might display each character of the option
269 * as a '*' (for example). 269 * as a '*' (for example).
270 * 270 *
271 * @param option The account option. 271 * @option: The account option.
272 * 272 *
273 * @return %TRUE if the option's value should be obscured. 273 * Returns: %TRUE if the option's value should be obscured.
274 */ 274 */
275 gboolean 275 gboolean
276 purple_account_option_string_get_masked(const PurpleAccountOption *option); 276 purple_account_option_string_get_masked(const PurpleAccountOption *option);
277 277
278 /** 278 /**
279 * Returns the list of hints for an account option. 279 * Returns the list of hints for an account option.
280 * 280 *
281 * @param option The account option. 281 * @option: The account option.
282 * 282 *
283 * @constreturn A list of hints, stored as strings. 283 * Returns: (TODO const): A list of hints, stored as strings.
284 */ 284 */
285 const GSList * purple_account_option_string_get_hints(const PurpleAccountOption *option); 285 const GSList * purple_account_option_string_get_hints(const PurpleAccountOption *option);
286 286
287 /** 287 /**
288 * Returns the list values for an account option. 288 * Returns the list values for an account option.
289 * 289 *
290 * @param option The account option. 290 * @option: The account option.
291 * 291 *
292 * @constreturn A list of #PurpleKeyValuePair, mapping the human-readable 292 * Returns: (TODO const): A list of #PurpleKeyValuePair, mapping the human-readable
293 * description of the value to the <tt>(const char *)</tt> that 293 * description of the value to the <tt>(const char *)</tt> that
294 * should be passed to purple_account_set_string() to set the 294 * should be passed to purple_account_set_string() to set the
295 * option. 295 * option.
296 */ 296 */
297 GList *purple_account_option_get_list(const PurpleAccountOption *option); 297 GList *purple_account_option_get_list(const PurpleAccountOption *option);
305 /*@{*/ 305 /*@{*/
306 306
307 /** 307 /**
308 * Creates a new account username split. 308 * Creates a new account username split.
309 * 309 *
310 * @param text The text of the option. 310 * @text: The text of the option.
311 * @param default_value The default value. 311 * @default_value: The default value.
312 * @param sep The field separator. 312 * @sep: The field separator.
313 * 313 *
314 * @return The new user split. 314 * Returns: The new user split.
315 */ 315 */
316 PurpleAccountUserSplit *purple_account_user_split_new(const char *text, 316 PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
317 const char *default_value, 317 const char *default_value,
318 char sep); 318 char sep);
319 319
320 /** 320 /**
321 * Destroys an account username split. 321 * Destroys an account username split.
322 * 322 *
323 * @param split The split to destroy. 323 * @split: The split to destroy.
324 */ 324 */
325 void purple_account_user_split_destroy(PurpleAccountUserSplit *split); 325 void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
326 326
327 /** 327 /**
328 * Returns the text for an account username split. 328 * Returns the text for an account username split.
329 * 329 *
330 * @param split The account username split. 330 * @split: The account username split.
331 * 331 *
332 * @return The account username split's text. 332 * Returns: The account username split's text.
333 */ 333 */
334 const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split); 334 const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split);
335 335
336 /** 336 /**
337 * Returns the default string value for an account split. 337 * Returns the default string value for an account split.
338 * 338 *
339 * @param split The account username split. 339 * @split: The account username split.
340 * 340 *
341 * @return The default string. 341 * Returns: The default string.
342 */ 342 */
343 const char *purple_account_user_split_get_default_value( 343 const char *purple_account_user_split_get_default_value(
344 const PurpleAccountUserSplit *split); 344 const PurpleAccountUserSplit *split);
345 345
346 /** 346 /**
347 * Returns the field separator for an account split. 347 * Returns the field separator for an account split.
348 * 348 *
349 * @param split The account username split. 349 * @split: The account username split.
350 * 350 *
351 * @return The field separator. 351 * Returns: The field separator.
352 */ 352 */
353 char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split); 353 char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
354 354
355 /** 355 /**
356 * Returns the 'reverse' value for an account split. 356 * Returns the 'reverse' value for an account split.
357 * 357 *
358 * @param split The account username split. 358 * @split: The account username split.
359 * 359 *
360 * @return The 'reverse' value. 360 * Returns: The 'reverse' value.
361 */ 361 */
362 gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split); 362 gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split);
363 363
364 /** 364 /**
365 * Sets the 'reverse' value for an account split. 365 * Sets the 'reverse' value for an account split.
366 * 366 *
367 * @param split The account username split. 367 * @split: The account username split.
368 * @param reverse The 'reverse' value 368 * @reverse: The 'reverse' value
369 */ 369 */
370 void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse); 370 void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);
371 371
372 /*@}*/ 372 /*@}*/
373 373

Mercurial Repository: pidgin3

mercurial