Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/pluginpref.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     1 /**
       
     2  * @file pluginpref.h Plugin Preferences API
       
     3  * @ingroup core
       
     4  */
       
     5 
       
     6 /* purple
       
     7  *
       
     8  * Purple is the legal property of its developers, whose names are too numerous
       
     9  * to list here.  Please refer to the COPYRIGHT file distributed with this
       
    10  * source distribution.
       
    11  *
       
    12  * This program is free software; you can redistribute it and/or modify
       
    13  * it under the terms of the GNU General Public License as published by
       
    14  * the Free Software Foundation; either version 2 of the License, or
       
    15  * (at your option) any later version.
       
    16  *
       
    17  * This program is distributed in the hope that it will be useful,
       
    18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
       
    19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       
    20  * GNU General Public License for more details.
       
    21  *
       
    22  * You should have received a copy of the GNU General Public License
       
    23  * along with this program; if not, write to the Free Software
       
    24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
       
    25  *
       
    26  */
       
    27 #ifndef _PURPLE_PLUGINPREF_H_
       
    28 #define _PURPLE_PLUGINPREF_H_
       
    29 
       
    30 typedef struct _PurplePluginPrefFrame		PurplePluginPrefFrame;
       
    31 typedef struct _PurplePluginPref			PurplePluginPref;
       
    32 
       
    33 /**
       
    34  * String format for preferences.
       
    35  */
       
    36 typedef enum
       
    37 {
       
    38 	PURPLE_STRING_FORMAT_TYPE_NONE      = 0,          /**< The string is plain text. */
       
    39 	PURPLE_STRING_FORMAT_TYPE_MULTILINE = 1 << 0,     /**< The string can have newlines. */
       
    40 	PURPLE_STRING_FORMAT_TYPE_HTML      = 1 << 1      /**< The string can be in HTML. */
       
    41 } PurpleStringFormatType;
       
    42 
       
    43 typedef enum {
       
    44 	PURPLE_PLUGIN_PREF_NONE,
       
    45 	PURPLE_PLUGIN_PREF_CHOICE,
       
    46 	PURPLE_PLUGIN_PREF_INFO,              /**< no-value label */
       
    47 	PURPLE_PLUGIN_PREF_STRING_FORMAT      /**< The preference has a string value. */
       
    48 } PurplePluginPrefType;
       
    49 
       
    50 #include <glib.h>
       
    51 #include "prefs.h"
       
    52 
       
    53 #ifdef __cplusplus
       
    54 extern "C" {
       
    55 #endif
       
    56 
       
    57 /**************************************************************************/
       
    58 /** @name Plugin Preference API                                           */
       
    59 /**************************************************************************/
       
    60 /*@{*/
       
    61 
       
    62 /**
       
    63  * Create a new plugin preference frame
       
    64  *
       
    65  * @return a new PurplePluginPrefFrame
       
    66  */
       
    67 PurplePluginPrefFrame *purple_plugin_pref_frame_new(void);
       
    68 
       
    69 /**
       
    70  * Destroy a plugin preference frame
       
    71  *
       
    72  * @param frame The plugin frame to destroy
       
    73  */
       
    74 void purple_plugin_pref_frame_destroy(PurplePluginPrefFrame *frame);
       
    75 
       
    76 /**
       
    77  * Adds a plugin preference to a plugin preference frame
       
    78  *
       
    79  * @param frame The plugin frame to add the preference to
       
    80  * @param pref  The preference to add to the frame
       
    81  */
       
    82 void purple_plugin_pref_frame_add(PurplePluginPrefFrame *frame, PurplePluginPref *pref);
       
    83 
       
    84 /**
       
    85  * Get the plugin preferences from a plugin preference frame
       
    86  *
       
    87  * @param frame The plugin frame to get the plugin preferences from
       
    88  * @constreturn a GList of plugin preferences
       
    89  */
       
    90 GList *purple_plugin_pref_frame_get_prefs(PurplePluginPrefFrame *frame);
       
    91 
       
    92 /**
       
    93  * Create a new plugin preference
       
    94  *
       
    95  * @return a new PurplePluginPref
       
    96  */
       
    97 PurplePluginPref *purple_plugin_pref_new(void);
       
    98 
       
    99 /**
       
   100  * Create a new plugin preference with name
       
   101  *
       
   102  * @param name The name of the pref
       
   103  * @return a new PurplePluginPref
       
   104  */
       
   105 PurplePluginPref *purple_plugin_pref_new_with_name(const char *name);
       
   106 
       
   107 /**
       
   108  * Create a new plugin preference with label
       
   109  *
       
   110  * @param label The label to be displayed
       
   111  * @return a new PurplePluginPref
       
   112  */
       
   113 PurplePluginPref *purple_plugin_pref_new_with_label(const char *label);
       
   114 
       
   115 /**
       
   116  * Create a new plugin preference with name and label
       
   117  *
       
   118  * @param name  The name of the pref
       
   119  * @param label The label to be displayed
       
   120  * @return a new PurplePluginPref
       
   121  */
       
   122 PurplePluginPref *purple_plugin_pref_new_with_name_and_label(const char *name, const char *label);
       
   123 
       
   124 /**
       
   125  * Destroy a plugin preference
       
   126  *
       
   127  * @param pref The preference to destroy
       
   128  */
       
   129 void purple_plugin_pref_destroy(PurplePluginPref *pref);
       
   130 
       
   131 /**
       
   132  * Set a plugin pref name
       
   133  *
       
   134  * @param pref The plugin pref
       
   135  * @param name The name of the pref
       
   136  */
       
   137 void purple_plugin_pref_set_name(PurplePluginPref *pref, const char *name);
       
   138 
       
   139 /**
       
   140  * Get a plugin pref name
       
   141  *
       
   142  * @param pref The plugin pref
       
   143  * @return The name of the pref
       
   144  */
       
   145 const char *purple_plugin_pref_get_name(PurplePluginPref *pref);
       
   146 
       
   147 /**
       
   148  * Set a plugin pref label
       
   149  *
       
   150  * @param pref  The plugin pref
       
   151  * @param label The label for the plugin pref
       
   152  */
       
   153 void purple_plugin_pref_set_label(PurplePluginPref *pref, const char *label);
       
   154 
       
   155 /**
       
   156  * Get a plugin pref label
       
   157  *
       
   158  * @param pref The plugin pref
       
   159  * @return The label for the plugin pref
       
   160  */
       
   161 const char *purple_plugin_pref_get_label(PurplePluginPref *pref);
       
   162 
       
   163 /**
       
   164  * Set the bounds for an integer pref
       
   165  *
       
   166  * @param pref The plugin pref
       
   167  * @param min  The min value
       
   168  * @param max  The max value
       
   169  */
       
   170 void purple_plugin_pref_set_bounds(PurplePluginPref *pref, int min, int max);
       
   171 
       
   172 /**
       
   173  * Get the bounds for an integer pref
       
   174  *
       
   175  * @param pref The plugin pref
       
   176  * @param min  The min value
       
   177  * @param max  The max value
       
   178  */
       
   179 void purple_plugin_pref_get_bounds(PurplePluginPref *pref, int *min, int *max);
       
   180 
       
   181 /**
       
   182  * Set the type of a plugin pref
       
   183  *
       
   184  * @param pref The plugin pref
       
   185  * @param type The type
       
   186  */
       
   187 void purple_plugin_pref_set_type(PurplePluginPref *pref, PurplePluginPrefType type);
       
   188 
       
   189 /**
       
   190  * Get the type of a plugin pref
       
   191  *
       
   192  * @param pref The plugin pref
       
   193  * @return The type
       
   194  */
       
   195 PurplePluginPrefType purple_plugin_pref_get_type(PurplePluginPref *pref);
       
   196 
       
   197 /**
       
   198  * Set the choices for a choices plugin pref
       
   199  *
       
   200  * @param pref  The plugin pref
       
   201  * @param label The label for the choice
       
   202  * @param choice  A gpointer of the choice
       
   203  */
       
   204 void purple_plugin_pref_add_choice(PurplePluginPref *pref, const char *label, gpointer choice);
       
   205 
       
   206 /**
       
   207  * Get the choices for a choices plugin pref
       
   208  *
       
   209  * @param pref The plugin pref
       
   210  * @constreturn GList of the choices
       
   211  */
       
   212 GList *purple_plugin_pref_get_choices(PurplePluginPref *pref);
       
   213 
       
   214 /**
       
   215  * Set the max length for a string plugin pref
       
   216  *
       
   217  * @param pref       The plugin pref
       
   218  * @param max_length The max length of the string
       
   219  */
       
   220 void purple_plugin_pref_set_max_length(PurplePluginPref *pref, unsigned int max_length);
       
   221 
       
   222 /**
       
   223  * Get the max length for a string plugin pref
       
   224  *
       
   225  * @param pref The plugin pref
       
   226  * @return the max length
       
   227  */
       
   228 unsigned int purple_plugin_pref_get_max_length(PurplePluginPref *pref);
       
   229 
       
   230 /**
       
   231  * Sets the masking of a string plugin pref
       
   232  *
       
   233  * @param pref The plugin pref
       
   234  * @param mask The value to set
       
   235  */
       
   236 void purple_plugin_pref_set_masked(PurplePluginPref *pref, gboolean mask);
       
   237 
       
   238 /**
       
   239  * Gets the masking of a string plugin pref
       
   240  *
       
   241  * @param pref The plugin pref
       
   242  * @return The masking
       
   243  */
       
   244 gboolean purple_plugin_pref_get_masked(PurplePluginPref *pref);
       
   245 
       
   246 /**
       
   247  * Sets the format type for a formattable-string plugin pref. You need to set the
       
   248  * pref type to PURPLE_PLUGIN_PREF_STRING_FORMAT first before setting the format.
       
   249  *
       
   250  * @param pref	 The plugin pref
       
   251  * @param format The format of the string
       
   252  */
       
   253 void purple_plugin_pref_set_format_type(PurplePluginPref *pref, PurpleStringFormatType format);
       
   254 
       
   255 /**
       
   256  * Gets the format type of the formattable-string plugin pref.
       
   257  *
       
   258  * @param pref The plugin pref
       
   259  * @return The format of the pref
       
   260  */
       
   261 PurpleStringFormatType purple_plugin_pref_get_format_type(PurplePluginPref *pref);
       
   262 
       
   263 /*@}*/
       
   264 
       
   265 #ifdef __cplusplus
       
   266 }
       
   267 #endif
       
   268 
       
   269 #endif /* _PURPLE_PLUGINPREF_H_ */