AnjutaPreferences

AnjutaPreferences — Anjuta Prefereces system.

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <libanjuta/anjuta-preferences.h>


enum                AnjutaPropertyObjectType;
enum                AnjutaPropertyDataType;
enum                AnjutaPreferencesFilterType;
                    AnjutaProperty;
GtkWidget*          anjuta_property_get_widget          (AnjutaProperty *prop);
                    AnjutaPreferencesPriv;
                    AnjutaPreferences;
gboolean            (*AnjutaPreferencesCallback)        (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         gpointer data);
GtkWidget*          anjuta_preferences_new              (void);
void                anjuta_preferences_add_page         (AnjutaPreferences *pr,
                                                         GladeXML *gxml,
                                                         const gchar *glade_widget_name,
                                                         const gchar *title,
                                                         const gchar *icon_filename);
void                anjuta_preferences_register_all_properties_from_glade_xml
                                                        (AnjutaPreferences *pr,
                                                         GladeXML *gxml,
                                                         GtkWidget *parent);
gboolean            anjuta_preferences_register_property_from_string
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *property_desc);
gboolean            anjuta_preferences_register_property_raw
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *key,
                                                         const gchar *default_value,
                                                         guint flags,
                                                         AnjutaPropertyObjectType object_type,
                                                         AnjutaPropertyDataType data_type);
gboolean            anjuta_preferences_register_property_custom
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *key,
                                                         const gchar *default_value,
                                                         AnjutaPropertyDataType data_type,
                                                         guint flags,
                                                         void (*set_property) (AnjutaProperty *prop, const gchar *value),
                                                         gchar* (*get_property) (AnjutaProperty *));
void                anjuta_preferences_reset_defaults   (AnjutaPreferences *pr);
gboolean            anjuta_preferences_load_gconf       (AnjutaPreferences *pr);
gboolean            anjuta_preferences_save             (AnjutaPreferences *pr,
                                                         FILE *stream);
gboolean            anjuta_preferences_save_filtered    (AnjutaPreferences *pr,
                                                         FILE *stream,
                                                         AnjutaPreferencesFilterType filter);
gboolean            anjuta_preferences_save_gconf       (AnjutaPreferences *pr,
                                                         AnjutaPreferencesFilterType filter);
void                anjuta_preferences_foreach          (AnjutaPreferences *pr,
                                                         AnjutaPreferencesFilterType filter,
                                                         AnjutaPreferencesCallback callback,
                                                         gpointer data);
void                anjuta_preferences_sync_to_session  (AnjutaPreferences *pr);
void                anjuta_preferences_set              (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         const gchar *value);
void                anjuta_preferences_set_list         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType list_type,
                                                         GSList *list);
gboolean            anjuta_preferences_set_pair         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType car_type,
                                                         GConfValueType cdr_type,
                                                         gconstpointer address_of_car,
                                                         gconstpointer address_of_cdr);
void                anjuta_preferences_set_int          (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         const gint value);
gchar*              anjuta_preferences_get              (AnjutaPreferences *pr,
                                                         const gchar *key);
GSList*             anjuta_preferences_get_list         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType list_type);
gboolean            anjuta_preferences_get_pair         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType car_type,
                                                         GConfValueType cdr_type,
                                                         gpointer car_retloc,
                                                         gpointer cdr_retloc);
gint                anjuta_preferences_get_int          (AnjutaPreferences *pr,
                                                         const gchar *key);
gint                anjuta_preferences_get_int_with_default
                                                        (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         gint default_value);
gchar*              anjuta_preferences_default_get      (AnjutaPreferences *pr,
                                                         const gchar *key);
gint                anjuta_preferences_default_get_int  (AnjutaPreferences *pr,
                                                         const gchar *key);
guint               anjuta_preferences_notify_add       (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfClientNotifyFunc func,
                                                         gpointer data,
                                                         GFreeFunc destroy_notify);
void                anjuta_preferences_notify_remove    (AnjutaPreferences *pr,
                                                         guint notify_id);
const gchar*        anjuta_preferences_get_prefix       (AnjutaPreferences *pr);
gboolean            anjuta_preferences_dir_exists       (AnjutaPreferences *pr,
                                                         const gchar *dir);
void                anjuta_preferences_add_dir          (AnjutaPreferences *pr,
                                                         const gchar *dir,
                                                         GConfClientPreloadType preload);
void                anjuta_preferences_remove_dir       (AnjutaPreferences *pr,
                                                         const gchar *dir);

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----GtkDialog
                                             +----AnjutaPreferencesDialog
                                                   +----AnjutaPreferences

Implemented Interfaces

AnjutaPreferences implements AtkImplementorIface.

Description

AnjutaPreferences is a way to let plugins register their preferences. There are mainly two ways a plugin could register its preferences in Anjuta.

First is to not use AnjutaPreferences at all. Simply register a preferences page in AnjutaPreferencesDialog using the function anjuta_preferences_dialog_add_page(). The plugin should take care of loading, saving and widgets synchronization of the preferences values. It is particularly useful if the plugin uses gconf system for its preferences. Also no "changed" signal will be emitted from it.

Second is to use anjuta_preferences_add_page(), which will automatically register the preferences keys and values from a glade xml file. The glade xml file contains a preferences page of the plugin. The widget names in the page are given in a particular way (see anjuta_preferences_add_page()) to let it know property key details. Loading, saving and widget synchronization are automatically done. "changed" signal is emitted when a preference is changed.

anjuta_preferences_register_all_properties_from_glade_xml() only registers the preferences propery keys for automatic loading, saving and widget syncrhronization, but does not add the page in preferences dialog. It is useful if the plugin wants to show the preferences page somewhere else.

anjuta_preferences_register_property_from_string() is similar to anjuta_preferences_register_all_properties_from_glade_xml(), but it only registers one property, the detail of which is given in its arguments. anjuta_preferences_register_property_custom() is used to register a property that uses a widget which is not supported by AnjutaPreferences.

Details

enum AnjutaPropertyObjectType

typedef enum
{
	ANJUTA_PROPERTY_OBJECT_TYPE_TOGGLE,
	ANJUTA_PROPERTY_OBJECT_TYPE_SPIN,
	ANJUTA_PROPERTY_OBJECT_TYPE_ENTRY,
	ANJUTA_PROPERTY_OBJECT_TYPE_MENU,
	ANJUTA_PROPERTY_OBJECT_TYPE_TEXT,
	ANJUTA_PROPERTY_OBJECT_TYPE_COLOR,
	ANJUTA_PROPERTY_OBJECT_TYPE_FONT
} AnjutaPropertyObjectType;


enum AnjutaPropertyDataType

typedef enum
{
	ANJUTA_PROPERTY_DATA_TYPE_BOOL,
	ANJUTA_PROPERTY_DATA_TYPE_INT,
	ANJUTA_PROPERTY_DATA_TYPE_TEXT,
	ANJUTA_PROPERTY_DATA_TYPE_COLOR,
	ANJUTA_PROPERTY_DATA_TYPE_FONT
} AnjutaPropertyDataType;


enum AnjutaPreferencesFilterType

typedef enum
{
	ANJUTA_PREFERENCES_FILTER_NONE = 0,
	ANJUTA_PREFERENCES_FILTER_PROJECT = 1
} AnjutaPreferencesFilterType;


AnjutaProperty

typedef struct _AnjutaProperty AnjutaProperty;


anjuta_property_get_widget ()

GtkWidget*          anjuta_property_get_widget          (AnjutaProperty *prop);

Gets the widget associated with the property.

prop : an AnjutaProperty reference
Returns : a GtkWidget object associated with the property.

AnjutaPreferencesPriv

typedef struct _AnjutaPreferencesPriv AnjutaPreferencesPriv;


AnjutaPreferences

typedef struct _AnjutaPreferences AnjutaPreferences;


AnjutaPreferencesCallback ()

gboolean            (*AnjutaPreferencesCallback)        (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         gpointer data);

pr :
key :
data :
Returns :

anjuta_preferences_new ()

GtkWidget*          anjuta_preferences_new              (void);

Creates a new AnjutaPreferences object

Returns : A AnjutaPreferences object.

anjuta_preferences_add_page ()

void                anjuta_preferences_add_page         (AnjutaPreferences *pr,
                                                         GladeXML *gxml,
                                                         const gchar *glade_widget_name,
                                                         const gchar *title,
                                                         const gchar *icon_filename);

Add a page to the preferences sytem. gxml is the GladeXML object of the glade dialog containing the page widget. The glade dialog will contain the layout of the preferences widgets. The widgets which are preference widgets (e.g. toggle button) should have widget names of the form:

    preferences_OBJECTTYPE:DATATYPE:DEFAULT:FLAGS:PROPERTYKEY
    where,
      OBJECTTYPE is 'toggle', 'spin', 'entry', 'text', 'color' or 'font'.
      DATATYPE   is 'bool', 'int', 'float', 'text', 'color' or 'font'.
      DEFAULT    is the default value (in the appropriate format). The format
                    for color is 'XXXXXX' representing RGB value and for
                    font, it is the pango font description.
      FLAGS      is any flag associated with the property. Currently it
                    has only two values -- 0 and 1. For normal preference
                    property which is saved/retrieved globally, the flag = 0.
                    For preference property which is also saved/retrieved
                    along with the project, the flag = 1.
      PROPERTYKEY is the property key. e.g - 'tab.size'.

All widgets having the above names in the gxml tree will be registered and will become part of auto saving/loading. For example, refer to anjuta preferences dialogs and study the widget names.

pr : a AnjutaPreferences object
gxml : GladeXML object containing the preferences page
glade_widget_name : Page widget name (as give with glade interface editor). The widget will be searched with the given name and detached (that is, removed from the container, if present) from it's parent.
title :
icon_filename : File name (of the form filename.png) of the icon representing the preference page.

anjuta_preferences_register_all_properties_from_glade_xml ()

void                anjuta_preferences_register_all_properties_from_glade_xml
                                                        (AnjutaPreferences *pr,
                                                         GladeXML *gxml,
                                                         GtkWidget *parent);

This will register all the properties names of the format described above without considering the UI. Useful if you have the widgets shown elsewhere but you want them to be part of preferences system.

pr : a AnjutaPreferences Object
gxml : GladeXML object containing the properties widgets.
parent : Parent widget in the gxml object

anjuta_preferences_register_property_from_string ()

gboolean            anjuta_preferences_register_property_from_string
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *property_desc);

This registers only one widget. The widget could be shown elsewhere. the property_description should be of the form described before.

pr : a AnjutaPreferences object
object : Widget to register
property_desc : Property description (see anjuta_preferences_add_pag())
Returns : TRUE if sucessful.

anjuta_preferences_register_property_raw ()

gboolean            anjuta_preferences_register_property_raw
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *key,
                                                         const gchar *default_value,
                                                         guint flags,
                                                         AnjutaPropertyObjectType object_type,
                                                         AnjutaPropertyDataType data_type);

This also registers only one widget, but instead of supplying the property parameters as a single parsable string (as done in previous method), it takes them separately.

pr : a AnjutaPreferences object
object : Widget to register
key : Property key
default_value : Default value of the key
flags : Flags
object_type : Object type of widget
data_type : Data type of the property
Returns : TRUE if sucessful.

anjuta_preferences_register_property_custom ()

gboolean            anjuta_preferences_register_property_custom
                                                        (AnjutaPreferences *pr,
                                                         GtkWidget *object,
                                                         const gchar *key,
                                                         const gchar *default_value,
                                                         AnjutaPropertyDataType data_type,
                                                         guint flags,
                                                         void (*set_property) (AnjutaProperty *prop, const gchar *value),
                                                         gchar* (*get_property) (AnjutaProperty *));

This is meant for complex widgets which can not be set/get with the standard object set/get methods. Custom set/get methods are passed for the property to set/get the value to/from the widget.

pr : a AnjutaPreferences object.
object : Object to register.
key : Property key.
default_value : Default value of the key.
data_type : property data type.
flags : Flags
set_property : Set property to widget callback.
get_property : Get property from widget callback.
Returns : TRUE if sucessful.

anjuta_preferences_reset_defaults ()

void                anjuta_preferences_reset_defaults   (AnjutaPreferences *pr);

Resets the default values into the keys

pr : a AnjutaPreferences object.

anjuta_preferences_load_gconf ()

gboolean            anjuta_preferences_load_gconf       (AnjutaPreferences *pr);

pr :
Returns :

anjuta_preferences_save ()

gboolean            anjuta_preferences_save             (AnjutaPreferences *pr,
                                                         FILE *stream);

pr :
stream :
Returns :

anjuta_preferences_save_filtered ()

gboolean            anjuta_preferences_save_filtered    (AnjutaPreferences *pr,
                                                         FILE *stream,
                                                         AnjutaPreferencesFilterType filter);

pr :
stream :
filter :
Returns :

anjuta_preferences_save_gconf ()

gboolean            anjuta_preferences_save_gconf       (AnjutaPreferences *pr,
                                                         AnjutaPreferencesFilterType filter);

pr :
filter :
Returns :

anjuta_preferences_foreach ()

void                anjuta_preferences_foreach          (AnjutaPreferences *pr,
                                                         AnjutaPreferencesFilterType filter,
                                                         AnjutaPreferencesCallback callback,
                                                         gpointer data);

Calls callback function for each of the registered property keys. Keys with matching filter flags are left out of the loop. If filter is ANJUTA_PREFERENCES_FILTER_NONE, all properties are selected for the loop.

pr : A AnjutaPreferences object.
filter : Keys to filter out from the loop.
callback : User callback function.
data : User data passed to callback

anjuta_preferences_sync_to_session ()

void                anjuta_preferences_sync_to_session  (AnjutaPreferences *pr);

pr :

anjuta_preferences_set ()

void                anjuta_preferences_set              (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         const gchar *value);

Sets the value of key in current session.

pr : A AnjutaPreferences object.
key : Property key.
value : Value of the key.

anjuta_preferences_set_list ()

void                anjuta_preferences_set_list         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType list_type,
                                                         GSList *list);

Sets a list in current session.

pr : A AnjutaPreferences object.
key : Property key.
list_type : Type of each element.
list : New value of the key.

anjuta_preferences_set_pair ()

gboolean            anjuta_preferences_set_pair         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType car_type,
                                                         GConfValueType cdr_type,
                                                         gconstpointer address_of_car,
                                                         gconstpointer address_of_cdr);

pr : A AnjutaPreferences object.
key : Property key.
car_type : Type of the pair's first field (car).
cdr_type : Type of the pair's second field (cdr).
address_of_car : Address of the car.
address_of_cdr : Address of the cdr.
Returns :

anjuta_preferences_set_int ()

void                anjuta_preferences_set_int          (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         const gint value);

Sets the value of key in current session.

pr : A AnjutaPreferences object.
key : Property key.
value : Integer value of the key.

anjuta_preferences_get ()

gchar*              anjuta_preferences_get              (AnjutaPreferences *pr,
                                                         const gchar *key);

Gets the value of key as string. Returned string should be g_freed() when not required.

pr : A AnjutaPreferences object
key : Property key
Returns : Key value as string or NULL if the key is not defined.

anjuta_preferences_get_list ()

GSList*             anjuta_preferences_get_list         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType list_type);

Gets the list of key.

pr : A AnjutaPreferences object
key : Property key
list_type : Type of each list element
Returns : Key list or NULL if the key is not defined.

anjuta_preferences_get_pair ()

gboolean            anjuta_preferences_get_pair         (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfValueType car_type,
                                                         GConfValueType cdr_type,
                                                         gpointer car_retloc,
                                                         gpointer cdr_retloc);

Gets the pair of key.

pr : A AnjutaPreferences object
key : Property key
car_type : Desired type of the pair's first field (car).
cdr_type : Desired type of the pair's second field (cdr).
car_retloc : Address of a return location for the car.
cdr_retloc : Address of a return location for the cdr.
Returns : TRUE or FALSE.

anjuta_preferences_get_int ()

gint                anjuta_preferences_get_int          (AnjutaPreferences *pr,
                                                         const gchar *key);

Gets the value of key as integer.

pr : A AnjutaPreferences object
key : Property key
Returns : Key value as integer or 0 if the key is not defined.

anjuta_preferences_get_int_with_default ()

gint                anjuta_preferences_get_int_with_default
                                                        (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         gint default_value);

Gets the value of key as integer.

pr : A AnjutaPreferences object
key : Property key
default_value : Default value to return if the key is not defined.
Returns : Key value as integer or default_value if the key is not defined.

anjuta_preferences_default_get ()

gchar*              anjuta_preferences_default_get      (AnjutaPreferences *pr,
                                                         const gchar *key);

Gets the default value of key as string. The default value of the key is the value defined in System defaults (generally installed during program installation). Returned value must be g_freed() when not required.

pr : A AnjutaPreferences object
key : Property key
Returns : Default key value as string or NULL if not defined.

anjuta_preferences_default_get_int ()

gint                anjuta_preferences_default_get_int  (AnjutaPreferences *pr,
                                                         const gchar *key);

Gets the default value of key as integer. The default value of the key is the value defined in System defaults (generally installed during program installation).

pr : A AnjutaPreferences object
key : Property key
Returns : Default key value as integer or 0 if the key is not defined.

anjuta_preferences_notify_add ()

guint               anjuta_preferences_notify_add       (AnjutaPreferences *pr,
                                                         const gchar *key,
                                                         GConfClientNotifyFunc func,
                                                         gpointer data,
                                                         GFreeFunc destroy_notify);

This is similar to gconf_client_notify_add(), except that the key is not given as full path. Only anjuta preference key is given. The key prefix is added internally.

pr : A AnjutaPreferences object.
key : Key to monitor.
func : User callback function.
data : User data passed to func
destroy_notify : Destroy notify function - called when notify is removed.
Returns : Notify ID.

anjuta_preferences_notify_remove ()

void                anjuta_preferences_notify_remove    (AnjutaPreferences *pr,
                                                         guint notify_id);

Removes the notify callback added with anjuta_preferences_notify_add().

pr : A AnjutaPreferences object.
notify_id : Notify ID returned by anjuta_preferences_notify_add().

anjuta_preferences_get_prefix ()

const gchar*        anjuta_preferences_get_prefix       (AnjutaPreferences *pr);

Returns the gconf key prefix used by anjuta to store its preferences.

pr : A AnjutaPreferences object.
Returns : preferences keys prefix.

anjuta_preferences_dir_exists ()

gboolean            anjuta_preferences_dir_exists       (AnjutaPreferences *pr,
                                                         const gchar *dir);

pr : A AnjutaPreferences object.
dir : Directory to checkfor.
Returns : TRUE if dir exists.

anjuta_preferences_add_dir ()

void                anjuta_preferences_add_dir          (AnjutaPreferences *pr,
                                                         const gchar *dir,
                                                         GConfClientPreloadType preload);

Add a directory to the list of directories the GConfClient.

pr : A AnjutaPreferences object.
dir : Directory to add to the list.
preload : Degree of preload.

anjuta_preferences_remove_dir ()

void                anjuta_preferences_remove_dir       (AnjutaPreferences *pr,
                                                         const gchar *dir);

Remove a directory from the list of directories.

pr : A AnjutaPreferences object.
dir : Directory to remove from the list.

See Also

AnjutaPreferencesDialog