GNOME.org

EConfig

EConfig

Synopsis

struct              EConfig;
enum                e_config_t;
struct              EConfigItem;
                    EConfigFactory;
struct              EConfigTarget;
void                (*EConfigFactoryFunc)               (EConfig *config,
                                                         gpointer data);
gboolean            (*EConfigCheckFunc)                 (EConfig *config,
                                                         const gchar *pageid,
                                                         gpointer data);
void                (*EConfigItemsFunc)                 (EConfig *config,
                                                         GSList *items,
                                                         gpointer data);
GtkWidget           (*EConfigItemFactoryFunc)           (EConfig *config,
                                                         EConfigItem *item,
                                                         GtkWidget *parent,
                                                         GtkWidget *old,
                                                         gint position,
                                                         gpointer data);
EConfigFactory *    e_config_class_add_factory          (EConfigClass *klass,
                                                         const gchar *id,
                                                         EConfigFactoryFunc func,
                                                         gpointer user_data);
EConfig *           e_config_construct                  (EConfig *config,
                                                         const gchar *id);
void                e_config_add_items                  (EConfig *config,
                                                         GSList *items,
                                                         EConfigItemsFunc freefunc,
                                                         gpointer data);
void                e_config_add_page_check             (EConfig *config,
                                                         const gchar *pageid,
                                                         EConfigCheckFunc func,
                                                         gpointer data);
void                e_config_set_target                 (EConfig *config,
                                                         EConfigTarget *target);
GtkWidget *         e_config_create_widget              (EConfig *config);
enum                e_config_target_change_t;
void                e_config_target_changed             (EConfig *config,
                                                         e_config_target_change_t how);
gboolean            e_config_page_check                 (EConfig *config,
                                                         const gchar *pageid);
void                e_config_abort                      (EConfig *config);
void                e_config_commit                     (EConfig *config);
gpointer            e_config_target_new                 (EConfig *config,
                                                         gint type,
                                                         gsize size);
void                e_config_target_free                (EConfig *config,
                                                         gpointer target);
struct              EConfigHookGroup;
struct              EConfigHook;
typedef             EConfigHookTargetMap;
typedef             EConfigHookTargetMask;
struct              EConfigHookItemFactoryData;
struct              EConfigHookPageCheckData;
void                (*EConfigHookFunc)                  (EPlugin *plugin,
                                                         EConfigTarget *target);
void                (*EConfigHookItemFactoryFunc)       (EPlugin *plugin,
                                                         EConfigHookItemFactoryData *data);
void                e_config_hook_class_add_target_map  (EConfigHookClass *hook_class,
                                                         const EConfigHookTargetMap *map);

Object Hierarchy

  GObject
   +----EConfig

  GObject
   +----EPluginHook
         +----EConfigHook

Signals

  "abort"                                          : Run Last
  "commit"                                         : Run Last

Description

Details

struct EConfig

struct EConfig;

enum e_config_t

enum e_config_t {
	/* use one and only one of these for any given config-window id */
	E_CONFIG_BOOK,

	E_CONFIG_PAGE,
	E_CONFIG_SECTION,
	E_CONFIG_SECTION_TABLE,
	E_CONFIG_ITEM,
	E_CONFIG_ITEM_TABLE /* only allowed in table sections */
};

struct EConfigItem

struct EConfigItem {
	enum _e_config_t type;
	gchar *path;		/* absolute path, must sort
				 * ascii-lexographically into the right spot */
	gchar *label;
	EConfigItemFactoryFunc factory;
	gpointer user_data;
};

EConfigFactory

typedef struct _EConfigFactory EConfigFactory;

struct EConfigTarget

struct EConfigTarget {
	struct _EConfig *config;
	GtkWidget *widget; /* used if you need a parent toplevel, if available */

	guint32 type;

	/* implementation fields follow, depends on window type */
};

EConfigFactoryFunc ()

void                (*EConfigFactoryFunc)               (EConfig *config,
                                                         gpointer data);

EConfigCheckFunc ()

gboolean            (*EConfigCheckFunc)                 (EConfig *config,
                                                         const gchar *pageid,
                                                         gpointer data);

EConfigItemsFunc ()

void                (*EConfigItemsFunc)                 (EConfig *config,
                                                         GSList *items,
                                                         gpointer data);

EConfigItemFactoryFunc ()

GtkWidget           (*EConfigItemFactoryFunc)           (EConfig *config,
                                                         EConfigItem *item,
                                                         GtkWidget *parent,
                                                         GtkWidget *old,
                                                         gint position,
                                                         gpointer data);

e_config_class_add_factory ()

EConfigFactory *    e_config_class_add_factory          (EConfigClass *klass,
                                                         const gchar *id,
                                                         EConfigFactoryFunc func,
                                                         gpointer user_data);

Add a config factory which will be called to add_items() any extra items's if wants to, to the current Config window.

TODO: Make the id a pattern?

klass :

 Implementing class pointer.

id :

 The name of the configuration window you're interested in. This may be NULL to be called for all windows.

func :

 An EConfigFactoryFunc to call when the window id is being created.

user_data :

 Callback data.

Returns :

 A handle to the factory.

e_config_construct ()

EConfig *           e_config_construct                  (EConfig *config,
                                                         const gchar *id);

Used by implementing classes to initialise base parameters.

config :

 The instance to initialise.

id :

 The name of the configuration window this manager drives.

Returns :

 config is returned.

e_config_add_items ()

void                e_config_add_items                  (EConfig *config,
                                                         GSList *items,
                                                         EConfigItemsFunc freefunc,
                                                         gpointer data);

Add new EConfigItems to the configuration window. Nothing will be done with them until the widget is built.

TODO: perhaps commit and abort should just be signals.

config :

 An initialised implementing instance of EConfig.

items :

 A list of EConfigItem's to add to the configuration manager.

freefunc :

 If supplied, called to free the item list (and/or items) once they are no longer needed.

data :

 Data for the callback methods.

e_config_add_page_check ()

void                e_config_add_page_check             (EConfig *config,
                                                         const gchar *pageid,
                                                         EConfigCheckFunc func,
                                                         gpointer data);

Add a page-checking function callback. It will be called to validate the data in the given page or pages. If pageid is NULL then it will be called to validate every page, or the whole configuration window.

In the latter case, the pageid in the callback will be either the specific page being checked, or NULL when the whole config window is being checked.

The page check function is used to validate input before allowing the assistant to continue or the notebook to close.

config :

 Initialised implemeting instance of EConfig.

pageid :

 pageid to check.

func :

 checking callback.

data :

 user-data for the callback.

e_config_set_target ()

void                e_config_set_target                 (EConfig *config,
                                                         EConfigTarget *target);

Sets the target object for the config window. Generally the target is set only once, and will supply its own "changed" signal which can be used to drive the modal. This is a virtual method so that the implementing class can connect to the changed signal and initiate a e_config_target_changed() call where appropriate.

config :

 An initialised EConfig.

target :

 A target allocated from config.

e_config_create_widget ()

GtkWidget *         e_config_create_widget              (EConfig *config);

Create the GtkNotebook described by config.

This object will be self-driving, but will not close itself once complete.

Unless reffed otherwise, the management object config will be finalized when the widget is.

config :

 An initialised EConfig object.

Returns :

 The widget, also available in config.widget

enum e_config_target_change_t

enum e_config_target_change_t {
	E_CONFIG_TARGET_CHANGED_STATE,
	E_CONFIG_TARGET_CHANGED_REBUILD
};

e_config_target_changed ()

void                e_config_target_changed             (EConfig *config,
                                                         e_config_target_change_t how);

Indicate that the target has changed. This may be called by the self-aware target itself, or by the driving code. If how is E_CONFIG_TARGET_CHANGED_REBUILD, then the entire configuration widget may be recreated based on the changed target.

This is used to sensitise Assistant next/back buttons and the Apply button for the Notebook mode.

config :

 an EConfig

how :

 an enum value indicating how the target has changed

e_config_page_check ()

gboolean            e_config_page_check                 (EConfig *config,
                                                         const gchar *pageid);

Check that a given page is complete. If pageid is NULL, then check the whole config. No check is made that the page actually exists.

config :

 an EConfig

pageid :

 the path of the page item

Returns :

 FALSE if the data is inconsistent/incomplete.

e_config_abort ()

void                e_config_abort                      (EConfig *config);

Signify that the stateful configuration changes must be discarded to all listeners. This is used by self-driven assistant or notebook, or may be used by code using the widget directly.

config :

 an EConfig

e_config_commit ()

void                e_config_commit                     (EConfig *config);

Signify that the stateful configuration changes should be saved. This is used by the self-driven assistant or notebook, or may be used by code driving the widget directly.

config :

 an EConfig

e_config_target_new ()

gpointer            e_config_target_new                 (EConfig *config,
                                                         gint type,
                                                         gsize size);

Allocate a new config target suitable for this class. Implementing classes will define the actual content of the target.

config :

 an EConfig

type :

 type, up to implementor

size :

 size of object to allocate

e_config_target_free ()

void                e_config_target_free                (EConfig *config,
                                                         gpointer target);

Free a target. The implementing class can override this method to free custom targets.

config :

 an EConfig

target :

 the target to free

struct EConfigHookGroup

struct EConfigHookGroup {
	struct _EConfigHook *hook; /* parent pointer */
	gchar *id;		/* target menu id for these config items */
	gint target_type; /* target type of this group */
	GSList *items;		/* items to add to group */
	gchar *check;		/* validate handler, if set */
	gchar *commit;		/* commit handler, if set */
	gchar *abort;		/* abort handler, if set */
};

struct EConfigHook

struct EConfigHook;

EConfigHookTargetMap

typedef struct _EPluginHookTargetMap EConfigHookTargetMap;

EConfigHookTargetMask

typedef struct _EPluginHookTargetKey EConfigHookTargetMask;

struct EConfigHookItemFactoryData

struct EConfigHookItemFactoryData {
	EConfig *config;
	EConfigItem *item;
	EConfigTarget *target;
	GtkWidget *parent;
	GtkWidget *old;
	gint position;
};

struct EConfigHookPageCheckData

struct EConfigHookPageCheckData {
	EConfig *config;
	EConfigTarget *target;
	const gchar *pageid;
};

EConfigHookFunc ()

void                (*EConfigHookFunc)                  (EPlugin *plugin,
                                                         EConfigTarget *target);

EConfigHookItemFactoryFunc ()

void                (*EConfigHookItemFactoryFunc)       (EPlugin *plugin,
                                                         EConfigHookItemFactoryData *data);

e_config_hook_class_add_target_map ()

void                e_config_hook_class_add_target_map  (EConfigHookClass *hook_class,
                                                         const EConfigHookTargetMap *map);

hook_class: The dervied EConfigHook class. map: A map used to describe a single EConfigTarget type for this class.

Add a targe tmap to a concrete derived class of EConfig. The target map enumates the target types available for the implenting class.

Signal Details

The "abort" signal

void                user_function                      (EConfig *econfig,
                                                        gpointer user_data)      : Run Last

The "commit" signal

void                user_function                      (EConfig *econfig,
                                                        gpointer user_data)      : Run Last
Generated by GTK-Doc V1.18