## AnjutaPreferences

AnjutaPreferences — Anjuta Prefereces system.

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/anjuta-preferences.h>

    enum                AnjutaPropertyObjectType;
    enum                AnjutaPropertyDataType;
                        AnjutaProperty;
    GtkWidget*          anjuta_property_get_widget          (AnjutaProperty *prop);
                        AnjutaPreferences;
                        AnjutaPreferencesClass;
                        AnjutaPreferencesPriv;
    gboolean            (*AnjutaPreferencesCallback)        (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gpointer data);
    AnjutaPreferences * anjuta_preferences_new              (AnjutaPluginManager *plugin_manager);
    AnjutaPreferences * anjuta_preferences_default          (void);
    void                anjuta_preferences_add_from_builder (AnjutaPreferences *pr,
                                                             GtkBuilder *builder,
                                                             const gchar *glade_widget_name,
                                                             const gchar *title,
                                                             const gchar *icon_filename);
    void                anjuta_preferences_remove_page      (AnjutaPreferences *pr,
                                                             const gchar *page_name);
    void                anjuta_preferences_register_all_properties_from_builder_xml
                                                            (AnjutaPreferences *pr,
                                                             GtkBuilder *builder,
                                                             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_propertyAnjutaProperty *prop, const gchar *value) (),
                                                             gchar* (get_propertyAnjutaProperty *) ());
    void                anjuta_preferences_reset_defaults   (AnjutaPreferences *pr);
    void                anjuta_preferences_foreach          (AnjutaPreferences *pr,
                                                             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_int          (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             const gint value);
    void                anjuta_preferences_set_bool         (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             const gboolean value);
    gchar *             anjuta_preferences_get              (AnjutaPreferences *pr,
                                                             const gchar *key);
    gint                anjuta_preferences_get_int          (AnjutaPreferences *pr,
                                                             const gchar *key);
    gboolean            anjuta_preferences_get_bool         (AnjutaPreferences *pr,
                                                             const gchar *key);
    gint                anjuta_preferences_get_int_with_default
                                                            (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gint default_value);
    gboolean            anjuta_preferences_get_bool_with_default
                                                            (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gboolean default_value);
    gchar *             anjuta_preferences_default_get      (AnjutaPreferences *pr,
                                                             const gchar *key);
    gint                anjuta_preferences_default_get_int  (AnjutaPreferences *pr,
                                                             const gchar *key);
    gint                anjuta_preferences_default_get_bool (AnjutaPreferences *pr,
                                                             const gchar *key);
    GtkWidget *         anjuta_preferences_get_dialog       (AnjutaPreferences *pr);
    gboolean            anjuta_preferences_is_dialog_created
                                                            (AnjutaPreferences *pr);
    void                (*AnjutaPreferencesNotify)          (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gpointer data);
    void                (*AnjutaPreferencesNotifyInt)       (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gint value,
                                                             gpointer data);
    void                (*AnjutaPreferencesNotifyBool)      (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gboolean value,
                                                             gpointer data);
    guint               anjuta_preferences_notify_add_int   (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             AnjutaPreferencesNotifyInt func,
                                                             gpointer data,
                                                             GFreeFunc destroy_notify);
    guint               anjuta_preferences_notify_add_string
                                                            (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             AnjutaPreferencesNotify func,
                                                             gpointer data,
                                                             GFreeFunc destroy_notify);
    guint               anjuta_preferences_notify_add_bool  (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             AnjutaPreferencesNotifyBool func,
                                                             gpointer data,
                                                             GFreeFunc destroy_notify);
    void                anjuta_preferences_notify_remove    (AnjutaPreferences *pr,
                                                             guint notify_id);
    const gchar*        anjuta_preferences_get_prefix       (AnjutaPreferences *pr);

## Object Hierarchy

      GObject
       +----AnjutaPreferences

## 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_COMBO,
    	ANJUTA_PROPERTY_OBJECT_TYPE_TEXT,
    	ANJUTA_PROPERTY_OBJECT_TYPE_COLOR,
    	ANJUTA_PROPERTY_OBJECT_TYPE_FONT,
    	ANJUTA_PROPERTY_OBJECT_TYPE_FILE,
    	ANJUTA_PROPERTY_OBJECT_TYPE_FOLDER
    } 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;

### 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.

### AnjutaPreferences

    typedef struct _AnjutaPreferences AnjutaPreferences;

### AnjutaPreferencesClass

    typedef struct {
    	GObjectClass parent;
    } AnjutaPreferencesClass;

### AnjutaPreferencesPriv

    typedef struct _AnjutaPreferencesPriv AnjutaPreferencesPriv;

### AnjutaPreferencesCallback ()

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

`pr` : |
`key` : |
`data` : |
Returns : |

### anjuta_preferences_new ()

    AnjutaPreferences * anjuta_preferences_new              (AnjutaPluginManager *plugin_manager);

Creates a new AnjutaPreferences object

`plugin_manager` : | AnjutaPluginManager to be used
Returns : | A AnjutaPreferences object.

### anjuta_preferences_default ()

    AnjutaPreferences * anjuta_preferences_default          (void);

Get the default instace of anjuta preferences

Returns : | A AnjutaPreferences object.

### anjuta_preferences_add_from_builder ()

    void                anjuta_preferences_add_from_builder (AnjutaPreferences *pr,
                                                             GtkBuilder *builder,
                                                             const gchar *glade_widget_name,
                                                             const gchar *title,
                                                             const gchar *icon_filename);

`pr` : |
`builder` : |
`glade_widget_name` : |
`title` : |
`icon_filename` : |

### anjuta_preferences_remove_page ()

    void                anjuta_preferences_remove_page      (AnjutaPreferences *pr,
                                                             const gchar *page_name);

`pr` : |
`page_name` : |

### anjuta_preferences_register_all_properties_from_builder_xml ()

    void                anjuta_preferences_register_all_properties_from_builder_xml
                                                            (AnjutaPreferences *pr,
                                                             GtkBuilder *builder,
                                                             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
`builder` : | GtkBuilder object containing the properties widgets.
`parent` : | Parent widget in the builder 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_page()`)
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_propertyAnjutaProperty *prop, const gchar *value) (),
                                                             gchar* (get_propertyAnjutaProperty *) ());

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
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_foreach ()

    void                anjuta_preferences_foreach          (AnjutaPreferences *pr,
                                                             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.
`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_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_set_bool ()

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

Sets the value of `key` in current session.

`pr` : | A AnjutaPreferences object.
`key` : | Property key.
`value` : | Boolean 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_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 boolean or FALSE if the key is not defined.

### anjuta_preferences_get_bool ()

    gboolean            anjuta_preferences_get_bool         (AnjutaPreferences *pr,
                                                             const gchar *key);

`pr` : |
`key` : |
Returns : |

### 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_get_bool_with_default ()

    gboolean            anjuta_preferences_get_bool_with_default
                                                            (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gboolean default_value);

`pr` : |
`key` : |
`default_value` : |
Returns : |

### 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_default_get_bool ()

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

`pr` : |
`key` : |
Returns : |

### anjuta_preferences_get_dialog ()

    GtkWidget *         anjuta_preferences_get_dialog       (AnjutaPreferences *pr);

`pr` : |
Returns : |

### anjuta_preferences_is_dialog_created ()

    gboolean            anjuta_preferences_is_dialog_created
                                                            (AnjutaPreferences *pr);

`pr` : |
Returns : |

### AnjutaPreferencesNotify ()

    void                (*AnjutaPreferencesNotify)          (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             gpointer data);

`pr` : |
`key` : |
`value` : |
`data` : |

### AnjutaPreferencesNotifyInt ()

    void                (*AnjutaPreferencesNotifyInt)       (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gint value,
                                                             gpointer data);

`pr` : |
`key` : |
`value` : |
`data` : |

### AnjutaPreferencesNotifyBool ()

    void                (*AnjutaPreferencesNotifyBool)      (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             gboolean value,
                                                             gpointer data);

`pr` : |
`key` : |
`value` : |
`data` : |

### anjuta_preferences_notify_add_int ()

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

`pr` : |
`key` : |
`func` : |
`data` : |
`destroy_notify` : |
Returns : |

### anjuta_preferences_notify_add_string ()

    guint               anjuta_preferences_notify_add_string
                                                            (AnjutaPreferences *pr,
                                                             const gchar *key,
                                                             AnjutaPreferencesNotify 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_add_bool ()

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

`pr` : |
`key` : |
`func` : |
`data` : |
`destroy_notify` : |
Returns : |

### 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.

## See Also

AnjutaPreferencesDialog