Mercurialadium-1.4 / file revision
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
Frameworks/libpurple.framework/Versions/0.6.2/Headers/pluginpref.h
author Zachary West <zacw@adium.im>
Fri Aug 21 13:25:11 2009 -0700 (2009-08-21)
changeset 2592 e8d15275025e
parent 1739 Frameworks/libpurple.framework/Versions/0.6.0/Headers/pluginpref.h@8b0daad9656c
permissions -rw-r--r--
im.pidgin.adium.1-4 at 267c6165e02e34318a1823960bd04c0639952f73 
     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_ */
adium-1.4