libpurple/pluginpref.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
  23 #ifndef PURPLE_PLUGINPREF_H
  24 #define PURPLE_PLUGINPREF_H
  25 /**
  26  * SECTION:pluginpref
  27  * @section_id: libpurple-pluginpref
  28  * @short_description: <filename>pluginpref.h</filename>
  29  * @title: Plugin Preferences Frontend
  30  */
  31
  32 typedef struct _PurplePluginPrefFrame           PurplePluginPrefFrame;
  33 typedef struct _PurplePluginPref                        PurplePluginPref;
  34
  35 /**
  36  * PurpleStringFormatType:
  37  * @PURPLE_STRING_FORMAT_TYPE_NONE:      The string is plain text.
  38  * @PURPLE_STRING_FORMAT_TYPE_MULTILINE: The string can have newlines.
  39  * @PURPLE_STRING_FORMAT_TYPE_HTML:      The string can be in HTML.
  40  *
  41  * String format for preferences.
  42  */
  43 typedef enum
  44 {
  45         PURPLE_STRING_FORMAT_TYPE_NONE      = 0,
  46         PURPLE_STRING_FORMAT_TYPE_MULTILINE = 1 << 0,
  47         PURPLE_STRING_FORMAT_TYPE_HTML      = 1 << 1
  48 } PurpleStringFormatType;
  49
  50 /**
  51  * PurplePluginPrefType:
  52  * @PURPLE_PLUGIN_PREF_INFO:          no-value label
  53  * @PURPLE_PLUGIN_PREF_STRING_FORMAT: The preference has a string value.
  54  */
  55 typedef enum {
  56         PURPLE_PLUGIN_PREF_NONE,
  57         PURPLE_PLUGIN_PREF_CHOICE,
  58         PURPLE_PLUGIN_PREF_INFO,
  59         PURPLE_PLUGIN_PREF_STRING_FORMAT
  60 } PurplePluginPrefType;
  61
  62 #include <glib.h>
  63 #include "prefs.h"
  64
  65 G_BEGIN_DECLS
  66
  67 /**************************************************************************/
  68 /* Plugin Preference API                                                  */
  69 /**************************************************************************/
  70
  71 /**
  72  * purple_plugin_pref_frame_new:
  73  *
  74  * Create a new plugin preference frame
  75  *
  76  * Returns: a new PurplePluginPrefFrame
  77  */
  78 PurplePluginPrefFrame *purple_plugin_pref_frame_new(void);
  79
  80 /**
  81  * purple_plugin_pref_frame_destroy:
  82  * @frame: The plugin frame to destroy
  83  *
  84  * Destroy a plugin preference frame
  85  */
  86 void purple_plugin_pref_frame_destroy(PurplePluginPrefFrame *frame);
  87
  88 /**
  89  * purple_plugin_pref_frame_add:
  90  * @frame: The plugin frame to add the preference to
  91  * @pref:  The preference to add to the frame
  92  *
  93  * Adds a plugin preference to a plugin preference frame
  94  */
  95 void purple_plugin_pref_frame_add(PurplePluginPrefFrame *frame, PurplePluginPref *pref);
  96
  97 /**
  98  * purple_plugin_pref_frame_get_prefs:
  99  * @frame: The plugin frame to get the plugin preferences from
 100  *
 101  * Get the plugin preferences from a plugin preference frame
 102  *
 103  * Returns: (element-type PurplePluginPref) (transfer none): a list of plugin preferences
 104  */
 105 GList *purple_plugin_pref_frame_get_prefs(PurplePluginPrefFrame *frame);
 106
 107 /**
 108  * purple_plugin_pref_new:
 109  *
 110  * Create a new plugin preference
 111  *
 112  * Returns: a new PurplePluginPref
 113  */
 114 PurplePluginPref *purple_plugin_pref_new(void);
 115
 116 /**
 117  * purple_plugin_pref_new_with_name:
 118  * @name: The name of the pref
 119  *
 120  * Create a new plugin preference with name
 121  *
 122  * Returns: a new PurplePluginPref
 123  */
 124 PurplePluginPref *purple_plugin_pref_new_with_name(const char *name);
 125
 126 /**
 127  * purple_plugin_pref_new_with_label:
 128  * @label: The label to be displayed
 129  *
 130  * Create a new plugin preference with label
 131  *
 132  * Returns: a new PurplePluginPref
 133  */
 134 PurplePluginPref *purple_plugin_pref_new_with_label(const char *label);
 135
 136 /**
 137  * purple_plugin_pref_new_with_name_and_label:
 138  * @name:  The name of the pref
 139  * @label: The label to be displayed
 140  *
 141  * Create a new plugin preference with name and label
 142  *
 143  * Returns: a new PurplePluginPref
 144  */
 145 PurplePluginPref *purple_plugin_pref_new_with_name_and_label(const char *name, const char *label);
 146
 147 /**
 148  * purple_plugin_pref_destroy:
 149  * @pref: The preference to destroy
 150  *
 151  * Destroy a plugin preference
 152  */
 153 void purple_plugin_pref_destroy(PurplePluginPref *pref);
 154
 155 /**
 156  * purple_plugin_pref_set_name:
 157  * @pref: The plugin pref
 158  * @name: The name of the pref
 159  *
 160  * Set a plugin pref name
 161  */
 162 void purple_plugin_pref_set_name(PurplePluginPref *pref, const char *name);
 163
 164 /**
 165  * purple_plugin_pref_get_name:
 166  * @pref: The plugin pref
 167  *
 168  * Get a plugin pref name
 169  *
 170  * Returns: The name of the pref
 171  */
 172 const char *purple_plugin_pref_get_name(PurplePluginPref *pref);
 173
 174 /**
 175  * purple_plugin_pref_set_label:
 176  * @pref:  The plugin pref
 177  * @label: The label for the plugin pref
 178  *
 179  * Set a plugin pref label
 180  */
 181 void purple_plugin_pref_set_label(PurplePluginPref *pref, const char *label);
 182
 183 /**
 184  * purple_plugin_pref_get_label:
 185  * @pref: The plugin pref
 186  *
 187  * Get a plugin pref label
 188  *
 189  * Returns: The label for the plugin pref
 190  */
 191 const char *purple_plugin_pref_get_label(PurplePluginPref *pref);
 192
 193 /**
 194  * purple_plugin_pref_set_bounds:
 195  * @pref: The plugin pref
 196  * @min:  The min value
 197  * @max:  The max value
 198  *
 199  * Set the bounds for an integer pref
 200  */
 201 void purple_plugin_pref_set_bounds(PurplePluginPref *pref, int min, int max);
 202
 203 /**
 204  * purple_plugin_pref_get_bounds:
 205  * @pref: The plugin pref
 206  * @min:  The min value
 207  * @max:  The max value
 208  *
 209  * Get the bounds for an integer pref
 210  */
 211 void purple_plugin_pref_get_bounds(PurplePluginPref *pref, int *min, int *max);
 212
 213 /**
 214  * purple_plugin_pref_set_pref_type:
 215  * @pref: The plugin pref
 216  * @type: The type
 217  *
 218  * Set the type of a plugin pref
 219  */
 220 void purple_plugin_pref_set_pref_type(PurplePluginPref *pref, PurplePluginPrefType type);
 221
 222 /**
 223  * purple_plugin_pref_get_pref_type:
 224  * @pref: The plugin pref
 225  *
 226  * Get the type of a plugin pref
 227  *
 228  * Returns: The type
 229  */
 230 PurplePluginPrefType purple_plugin_pref_get_pref_type(PurplePluginPref *pref);
 231
 232 /**
 233  * purple_plugin_pref_add_choice:
 234  * @pref:  The plugin pref
 235  * @label: The label for the choice
 236  * @choice:  A gpointer of the choice
 237  *
 238  * Set the choices for a choices plugin pref
 239  */
 240 void purple_plugin_pref_add_choice(PurplePluginPref *pref, const char *label, gpointer choice);
 241
 242 /**
 243  * purple_plugin_pref_get_choices:
 244  * @pref: The plugin pref
 245  *
 246  * Get the choices for a choices plugin pref
 247  *
 248  * Returns: (transfer none): GList of the choices
 249  */
 250 GList *purple_plugin_pref_get_choices(PurplePluginPref *pref);
 251
 252 /**
 253  * purple_plugin_pref_set_max_length:
 254  * @pref:       The plugin pref
 255  * @max_length: The max length of the string
 256  *
 257  * Set the max length for a string plugin pref
 258  */
 259 void purple_plugin_pref_set_max_length(PurplePluginPref *pref, unsigned int max_length);
 260
 261 /**
 262  * purple_plugin_pref_get_max_length:
 263  * @pref: The plugin pref
 264  *
 265  * Get the max length for a string plugin pref
 266  *
 267  * Returns: the max length
 268  */
 269 unsigned int purple_plugin_pref_get_max_length(PurplePluginPref *pref);
 270
 271 /**
 272  * purple_plugin_pref_set_masked:
 273  * @pref: The plugin pref
 274  * @mask: The value to set
 275  *
 276  * Sets the masking of a string plugin pref
 277  */
 278 void purple_plugin_pref_set_masked(PurplePluginPref *pref, gboolean mask);
 279
 280 /**
 281  * purple_plugin_pref_get_masked:
 282  * @pref: The plugin pref
 283  *
 284  * Gets the masking of a string plugin pref
 285  *
 286  * Returns: The masking
 287  */
 288 gboolean purple_plugin_pref_get_masked(PurplePluginPref *pref);
 289
 290 /**
 291  * purple_plugin_pref_set_format_type:
 292  * @pref:        The plugin pref
 293  * @format: The format of the string
 294  *
 295  * Sets the format type for a formattable-string plugin pref. You need to set the
 296  * pref type to PURPLE_PLUGIN_PREF_STRING_FORMAT first before setting the format.
 297  */
 298 void purple_plugin_pref_set_format_type(PurplePluginPref *pref, PurpleStringFormatType format);
 299
 300 /**
 301  * purple_plugin_pref_get_format_type:
 302  * @pref: The plugin pref
 303  *
 304  * Gets the format type of the formattable-string plugin pref.
 305  *
 306  * Returns: The format of the pref
 307  */
 308 PurpleStringFormatType purple_plugin_pref_get_format_type(PurplePluginPref *pref);
 309
 310 G_END_DECLS
 311
 312 #endif /* PURPLE_PLUGINPREF_H */