libpurple/purpleaccountoption.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_ACCOUNT_OPTION_H
  23 #define PURPLE_ACCOUNT_OPTION_H
  24
  25 #include <glib.h>
  26 #include <glib-object.h>
  27
  28 /**
  29  * SECTION:accountopt
  30  * @section_id: libpurple-accountopt
  31  * @short_description: <filename>accountopt.h</filename>
  32  * @title: Account Options API
  33  */
  34
  35 #define PURPLE_TYPE_ACCOUNT_OPTION (purple_account_option_get_type())
  36
  37 /**
  38  * PurpleAccountOption:
  39  *
  40  * An option for an account.
  41  *
  42  * This is set by protocols, and appears in the account settings
  43  * dialogs.
  44  */
  45 typedef struct _PurpleAccountOption             PurpleAccountOption;
  46
  47 G_BEGIN_DECLS
  48
  49 GType purple_account_option_get_type(void);
  50
  51 /**
  52  * purple_account_option_new:
  53  * @type:      The type of option.
  54  * @text:      The text of the option.
  55  * @pref_name: The account preference name for the option.
  56  *
  57  * Creates a new account option.  If you know what @a type will be in advance,
  58  * consider using purple_account_option_bool_new(),
  59  * purple_account_option_int_new(), purple_account_option_string_new() or
  60  * purple_account_option_list_new() (as appropriate) instead.
  61  *
  62  * Returns: The account option.
  63  */
  64 PurpleAccountOption *purple_account_option_new(PurplePrefType type, const gchar *text, const gchar *pref_name);
  65
  66 /**
  67  * purple_account_option_copy:
  68  * @option: The option to copy.
  69  *
  70  * Creates a newly allocated copy of @option.
  71  *
  72  * Returns: (transfer: full): A new copy of @option.
  73  *
  74  * Since: 3.0.0
  75  */
  76 PurpleAccountOption *purple_account_option_copy(PurpleAccountOption *option);
  77
  78 /**
  79  * purple_account_option_bool_new:
  80  * @text:          The text of the option.
  81  * @pref_name:     The account preference name for the option.
  82  * @default_value: The default value.
  83  *
  84  * Creates a new boolean account option.
  85  *
  86  * Returns: The account option.
  87  */
  88 PurpleAccountOption *purple_account_option_bool_new(const gchar *text, const gchar *pref_name, gboolean default_value);
  89
  90 /**
  91  * purple_account_option_int_new:
  92  * @text:          The text of the option.
  93  * @pref_name:     The account preference name for the option.
  94  * @default_value: The default value.
  95  *
  96  * Creates a new integer account option.
  97  *
  98  * Returns: The account option.
  99  */
 100 PurpleAccountOption *purple_account_option_int_new(const gchar *text, const gchar *pref_name, gint default_value);
 101
 102 /**
 103  * purple_account_option_string_new:
 104  * @text:          The text of the option.
 105  * @pref_name:     The account preference name for the option.
 106  * @default_value: The default value.
 107  *
 108  * Creates a new string account option.
 109  *
 110  * Returns: The account option.
 111  */
 112 PurpleAccountOption *purple_account_option_string_new(const gchar *text, const gchar *pref_name, const gchar *default_value);
 113
 114 /**
 115  * purple_account_option_list_new:
 116  * @text:      The text of the option.
 117  * @pref_name: The account preference name for the option.
 118  * @list: (element-type PurpleKeyValuePair) (transfer full): The key, value list.
 119  *
 120  * Creates a new list account option.
 121  *
 122  * The list passed will be owned by the account option, and the
 123  * strings inside will be freed automatically.
 124  *
 125  * The list is a list of #PurpleKeyValuePair items. The key is the label that
 126  * should be displayed to the user, and the <type>(const char *)</type> value is
 127  * the internal ID that should be passed to purple_account_set_string() to
 128  * choose that value.
 129  *
 130  * Returns: The account option.
 131  */
 132 PurpleAccountOption *purple_account_option_list_new(const gchar *text, const gchar *pref_name, GList *list);
 133
 134 /**
 135  * purple_account_option_destroy:
 136  * @option: The option to destroy.
 137  *
 138  * Destroys an account option.
 139  */
 140 void purple_account_option_destroy(PurpleAccountOption *option);
 141
 142 /**
 143  * purple_account_option_set_default_bool:
 144  * @option: The account option.
 145  * @value:  The default boolean value.
 146  *
 147  * Sets the default boolean value for an account option.
 148  */
 149 void purple_account_option_set_default_bool(PurpleAccountOption *option, gboolean value);
 150
 151 /**
 152  * purple_account_option_set_default_int:
 153  * @option: The account option.
 154  * @value:  The default integer value.
 155  *
 156  * Sets the default integer value for an account option.
 157  */
 158 void purple_account_option_set_default_int(PurpleAccountOption *option, gint value);
 159
 160 /**
 161  * purple_account_option_set_default_string:
 162  * @option: The account option.
 163  * @value:  The default string value.
 164  *
 165  * Sets the default string value for an account option.
 166  */
 167 void purple_account_option_set_default_string(PurpleAccountOption *option, const gchar *value);
 168
 169 /**
 170  * purple_account_option_string_set_masked:
 171  * @option: The account option.
 172  * @masked: The masking.
 173  *
 174  * Sets the masking for an account option. Setting this to %TRUE acts
 175  * as a hint to the UI that the option's value should be obscured from
 176  * view, like a password.
 177  */
 178 void purple_account_option_string_set_masked(PurpleAccountOption *option, gboolean masked);
 179
 180 /**
 181  * purple_account_option_string_set_hints:
 182  * @option: The account option.
 183  * @hints: (element-type utf8) (transfer full): The list of hints, stored as strings.
 184  *
 185  * Sets the hint list for an account option.
 186  *
 187  * The list passed will be owned by the account option, and the
 188  * strings inside will be freed automatically.
 189  */
 190 void purple_account_option_string_set_hints(PurpleAccountOption *option, GSList *hints);
 191
 192 /**
 193  * purple_account_option_set_list:
 194  * @option: The account option.
 195  * @values: (element-type PurpleKeyValuePair) (transfer full): The default list
 196  *          value.
 197  *
 198  * Sets the list values for an account option.
 199  *
 200  * The list passed will be owned by the account option, and the
 201  * strings inside will be freed automatically.
 202  *
 203  * The list is in key, value pairs. The key is the ID stored and used
 204  * internally, and the value is the label displayed.
 205  */
 206 void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
 207
 208 /**
 209  * purple_account_option_add_list_item:
 210  * @option: The account option.
 211  * @key:    The key.
 212  * @value:  The value.
 213  *
 214  * Adds an item to a list account option.
 215  */
 216 void purple_account_option_add_list_item(PurpleAccountOption *option, const gchar *key, const gchar *value);
 217
 218 /**
 219  * purple_account_option_get_pref_type:
 220  * @option: The account option.
 221  *
 222  * Returns the specified account option's type.
 223  *
 224  * Returns: The account option's type.
 225  */
 226 PurplePrefType purple_account_option_get_pref_type(const PurpleAccountOption *option);
 227
 228 /**
 229  * purple_account_option_get_text:
 230  * @option: The account option.
 231  *
 232  * Returns the text for an account option.
 233  *
 234  * Returns: The account option's text.
 235  */
 236 const gchar *purple_account_option_get_text(const PurpleAccountOption *option);
 237
 238 /**
 239  * purple_account_option_get_setting:
 240  * @option: The account option.
 241  *
 242  * Returns the name of an account option.  This corresponds to the @c pref_name
 243  * parameter supplied to purple_account_option_new() or one of the
 244  * type-specific constructors.
 245  *
 246  * Returns: The option's name.
 247  */
 248 const gchar *purple_account_option_get_setting(const PurpleAccountOption *option);
 249
 250 /**
 251  * purple_account_option_get_default_bool:
 252  * @option: The account option.
 253  *
 254  * Returns the default boolean value for an account option.
 255  *
 256  * Returns: The default boolean value.
 257  */
 258 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
 259
 260 /**
 261  * purple_account_option_get_default_int:
 262  * @option: The account option.
 263  *
 264  * Returns the default integer value for an account option.
 265  *
 266  * Returns: The default integer value.
 267  */
 268 gint purple_account_option_get_default_int(const PurpleAccountOption *option);
 269
 270 /**
 271  * purple_account_option_get_default_string:
 272  * @option: The account option.
 273  *
 274  * Returns the default string value for an account option.
 275  *
 276  * Returns: The default string value.
 277  */
 278 const gchar *purple_account_option_get_default_string(const PurpleAccountOption *option);
 279
 280 /**
 281  * purple_account_option_get_default_list_value:
 282  * @option: The account option.
 283  *
 284  * Returns the default string value for a list account option.
 285  *
 286  * Returns: The default list string value.
 287  */
 288 const gchar *purple_account_option_get_default_list_value(const PurpleAccountOption *option);
 289
 290 /**
 291  * purple_account_option_string_get_masked:
 292  * @option: The account option.
 293  *
 294  * Returns whether an option's value should be masked from view, like a
 295  * password.  If so, the UI might display each character of the option
 296  * as a '*' (for example).
 297  *
 298  * Returns: %TRUE if the option's value should be obscured.
 299  */
 300 gboolean purple_account_option_string_get_masked(const PurpleAccountOption *option);
 301
 302 /**
 303  * purple_account_option_string_get_hints:
 304  * @option: The account option.
 305  *
 306  * Returns the list of hints for an account option.
 307  *
 308  * Returns: (element-type utf8) (transfer none): A list of hints.
 309  */
 310 const GSList *purple_account_option_string_get_hints(const PurpleAccountOption *option);
 311
 312 /**
 313  * purple_account_option_get_list:
 314  * @option: The account option.
 315  *
 316  * Returns the list values for an account option.
 317  *
 318  * Returns: (element-type PurpleKeyValuePair) (transfer none): A list of
 319  *          #PurpleKeyValuePair, mapping the human-readable description of the
 320  *          value to the <type>(const char *)</type> that should be passed to
 321  *          purple_account_set_string() to set the option.
 322  */
 323 GList *purple_account_option_get_list(const PurpleAccountOption *option);
 324
 325 G_END_DECLS
 326
 327 #endif /* PURPLE_ACCOUNT_OPTION_H */