e-util/e-config.h

   1 /*
   2  *
   3  * This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the GNU Lesser General Public License as published by
   5  * the Free Software Foundation.
   6  *
   7  * This program is distributed in the hope that it will be useful, but
   8  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   9  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  10  * for more details.
  11  *
  12  * You should have received a copy of the GNU Lesser General Public License
  13  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  14  *
  15  *
  16  * Authors:
  17  *              Michel Zucchi <notzed@ximian.com>
  18  *
  19  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  20  *
  21  */
  22
  23 #if !defined (__E_UTIL_H_INSIDE__) && !defined (LIBEUTIL_COMPILATION)
  24 #error "Only <e-util/e-util.h> should be included directly."
  25 #endif
  26
  27 #ifndef E_CONFIG_H
  28 #define E_CONFIG_H
  29
  30 #include <gtk/gtk.h>
  31
  32 /* Standard GObject macros */
  33 #define E_TYPE_CONFIG \
  34         (e_config_get_type ())
  35 #define E_CONFIG(obj) \
  36         (G_TYPE_CHECK_INSTANCE_CAST \
  37         ((obj), E_TYPE_CONFIG, EConfig))
  38 #define E_CONFIG_CLASS(cls) \
  39         (G_TYPE_CHECK_CLASS_CAST \
  40         ((cls), E_TYPE_CONFIG, EConfigClass))
  41 #define E_IS_CONFIG(obj) \
  42         (G_TYPE_CHECK_INSTANCE_TYPE \
  43         ((obj), E_TYPE_CONFIG))
  44 #define E_IS_CONFIG_CLASS(cls) \
  45         (G_TYPE_CHECK_CLASS_TYPE \
  46         ((cls), E_TYPE_CONFIG))
  47 #define E_CONFIG_GET_CLASS(obj) \
  48         (G_TYPE_INSTANCE_GET_CLASS \
  49         ((obj), E_TYPE_CONFIG, EConfigClass))
  50
  51 G_BEGIN_DECLS
  52
  53 /* This is a config window management/merging class. */
  54
  55 typedef struct _EConfig EConfig;
  56 typedef struct _EConfigClass EConfigClass;
  57 typedef struct _EConfigPrivate EConfigPrivate;
  58
  59 typedef struct _EConfigItem EConfigItem;
  60 typedef struct _EConfigFactory EConfigFactory;
  61 typedef struct _EConfigTarget EConfigTarget;
  62
  63 typedef void    (*EConfigFactoryFunc)           (EConfig *config,
  64                                                  gpointer data);
  65
  66 typedef gboolean
  67                 (*EConfigCheckFunc)             (EConfig *config,
  68                                                  const gchar *pageid,
  69                                                  gpointer data);
  70
  71 typedef void    (*EConfigItemsFunc)             (EConfig *config,
  72                                                  GSList *items,
  73                                                  gpointer data);
  74
  75 typedef GtkWidget *
  76                 (*EConfigItemFactoryFunc)       (EConfig *config,
  77                                                  EConfigItem *item,
  78                                                  GtkWidget *parent,
  79                                                  GtkWidget *old,
  80                                                  gint position,
  81                                                  gpointer data);
  82
  83 /* ok so this is all a bit bogussy
  84  * we need to map to glade stuff instead */
  85
  86 /* Add types?
  87  * if no factory, setup appropriate container ?
  88  * if factory, then assume that returns the right sort of object?
  89  * what about pages ?
  90 */
  91
  92 /**
  93  * enum _e_config_target_changed_t - Target changed mode.
  94  *
  95  * @E_CONFIG_TARGET_CHANGED_STATE: A state of the target has changed.
  96  * @E_CONFIG_TARGET_CHANGED_REBUILD: A state of the target has
  97  * changed, and the UI must be reconfigured as a result.
  98  *
  99  * How the target has changed.  If @E_CONFIG_TARGET_CHANGED_REBUILD then a
 100  * widget reconfigure is necessary, otherwise it is used to check if
 101  * the widget is complete yet.
 102  **/
 103 typedef
 104 enum _e_config_target_change_t {
 105         E_CONFIG_TARGET_CHANGED_STATE,
 106         E_CONFIG_TARGET_CHANGED_REBUILD
 107 } e_config_target_change_t;
 108
 109 /**
 110  * enum _e_config_t - configuration item type.
 111  *
 112  * @E_CONFIG_BOOK: A notebook item.  Only one of this or
 113  * @E_CONFIG_PAGE: A configuration page.  The item @label will be
 114  * either the notebook tab label or the assistant page title if no factory
 115  * is supplied.
 116  * @E_CONFIG_SECTION: A section in the configuration page.  A page for
 117  * this section must have already been defined.  The item @label if
 118  * supplied will be setup as a borderless hig-compliant frame title.
 119  * The content of the section will be a GtkBox.  If a factory is used
 120  * then it is up to the factory method to create the section and add
 121  * it to the parent page, and return a GtkBox for following sections.
 122  * @E_CONFIG_SECTION_TABLE: A table section.  The same as an
 123  * @E_CONFIG_SECTION but the content object is a GtkTable instead.
 124  * @E_CONFIG_ITEM: A configuration item.  It must have a parent
 125  * section defined in the configuration system.
 126  * @E_CONFIG_ITEM_TABLE: A configuration item with a parent
 127  * @E_CONFIG_SECTION_TABLE.
 128  *
 129  * A configuration item type for each configuration item added to the
 130  * EConfig object.  These are merged from all contributors to the
 131  * configuration window, and then processed to form the combined
 132  * display.
 133  **/
 134 enum _e_config_t {
 135         /* use one and only one of these for any given config-window id */
 136         E_CONFIG_BOOK,
 137
 138         E_CONFIG_PAGE,
 139         E_CONFIG_SECTION,
 140         E_CONFIG_SECTION_TABLE,
 141         E_CONFIG_ITEM,
 142         E_CONFIG_ITEM_TABLE     /* only allowed in table sections */
 143 };
 144
 145 /**
 146  * struct _EConfigItem - A configuration item.
 147  *
 148  * @type: The configuration item type.
 149  * @path: An absolute path positioning this item in the configuration
 150  * window.  This will be used as a sort key for an ASCII sort to
 151  * position the item in the layout tree.
 152  * @label: A label or section title string which is used if no factory
 153  * is supplied to title the page or section.
 154  * @factory: If supplied, this will be invoked instead to create the
 155  * appropriate item.
 156  * @user_data: User data for the factory.
 157  *
 158  * The basic descriptor of a configuration item.  This may be
 159  * subclassed to store extra context information for each item.
 160  **/
 161 struct _EConfigItem {
 162         enum _e_config_t type;
 163         gchar *path;            /* absolute path, must sort
 164                                  * ascii-lexographically into the right spot */
 165         gchar *label;
 166         EConfigItemFactoryFunc factory;
 167         gpointer user_data;
 168 };
 169
 170 /**
 171  * struct _EConfigTarget - configuration context.
 172  *
 173  * @config: The parent object.
 174  * @widget: A target-specific parent widget.
 175  * @type: The type of target, defined by implementing classes.
 176  *
 177  * The base target object is used as the parent and placeholder for
 178  * configuration context for a given configuration window.  It is
 179  * subclassed by implementing classes to provide domain-specific
 180  * context.
 181  **/
 182 struct _EConfigTarget {
 183         struct _EConfig *config;
 184         GtkWidget *widget;      /* used if you need a parent toplevel, if available */
 185
 186         guint32 type;
 187
 188         /* implementation fields follow, depends on window type */
 189 };
 190
 191 /**
 192  * struct _EConfig - A configuration management object.
 193  *
 194  * @object: Superclass.
 195  * @priv: Private data.
 196  * @id: The globally unique identifider for this configuration window,
 197  * used for hooking into it.
 198  * @target: The current target.
 199  * @widget: The GtkNoteBook or GtkAssistant created after
 200  * :create_widget() is called that represents the merged and combined
 201  * configuration window.
 202  * @window: If :create_window() is called, then the containing
 203  * toplevel GtkDialog or GtkWindow appropriate for the @type of
 204  * configuration window created.
 205  *
 206  **/
 207 struct _EConfig {
 208         GObject object;
 209         EConfigPrivate *priv;
 210
 211         gchar *id;
 212
 213         EConfigTarget *target;
 214
 215         GtkWidget *widget; /* the generated internal */
 216         GtkWidget *window; /* the window widget, GtkWindow or GtkDialog */
 217 };
 218
 219 /**
 220  * struct _EConfigClass - Configuration management abstract class.
 221  *
 222  * @object_class: Superclass.
 223  * @factories: A list of factories registered on this type of
 224  * configuration manager.
 225  * @set_target: A virtual method used to set the target on the
 226  * configuration manager.  This is used by subclasses so they may hook
 227  * into changes on the target to propery drive the manager.
 228  * @target_free: A virtual method used to free the target in an
 229  * implementation-defined way.
 230  *
 231  **/
 232 struct _EConfigClass {
 233         GObjectClass object_class;
 234
 235         GList *factories;
 236
 237         void            (*set_target)           (EConfig *config,
 238                                                  EConfigTarget *target);
 239         void            (*target_free)          (EConfig *config,
 240                                                  EConfigTarget *target);
 241
 242         /* Signals */
 243         void            (*abort)                (EConfig *config);
 244         void            (*commit)               (EConfig *config);
 245 };
 246
 247 GType           e_config_get_type               (void) G_GNUC_CONST;
 248
 249 /* Static class methods */
 250 EConfigFactory *e_config_class_add_factory      (EConfigClass *klass,
 251                                                  const gchar *id,
 252                                                  EConfigFactoryFunc func,
 253                                                  gpointer user_data);
 254
 255 EConfig *       e_config_construct              (EConfig *config,
 256                                                  const gchar *id);
 257
 258 void            e_config_add_items              (EConfig *config,
 259                                                  GSList *items,
 260                                                  EConfigItemsFunc freefunc,
 261                                                  gpointer data);
 262 void            e_config_add_page_check         (EConfig *config,
 263                                                  const gchar *pageid,
 264                                                  EConfigCheckFunc func,
 265                                                  gpointer data);
 266
 267 void            e_config_set_target             (EConfig *config,
 268                                                  EConfigTarget *target);
 269 GtkWidget *     e_config_create_widget          (EConfig *config);
 270
 271 void            e_config_target_changed         (EConfig *config,
 272                                                  e_config_target_change_t how);
 273
 274 gboolean        e_config_page_check             (EConfig *config,
 275                                                  const gchar *pageid);
 276
 277 void            e_config_abort                  (EConfig *config);
 278 void            e_config_commit                 (EConfig *config);
 279
 280 gpointer        e_config_target_new             (EConfig *config,
 281                                                  gint type,
 282                                                  gsize size);
 283 void            e_config_target_free            (EConfig *config,
 284                                                  gpointer target);
 285
 286 G_END_DECLS
 287
 288 /* ********************************************************************** */
 289
 290 /* config plugin target, they are closely integrated */
 291
 292 /* To implement a basic config plugin, you just need to subclass
 293  * this and initialise the class target type tables */
 294
 295 #include <e-util/e-plugin.h>
 296
 297 /* Standard GObject macros */
 298 #define E_TYPE_CONFIG_HOOK \
 299         (e_config_hook_get_type ())
 300 #define E_CONFIG_HOOK(obj) \
 301         (G_TYPE_CHECK_INSTANCE_CAST \
 302         ((obj), E_TYPE_CONFIG_HOOK, EConfigHook))
 303 #define E_CONFIG_HOOK_CLASS(cls) \
 304         (G_TYPE_CHECK_CLASS_CAST \
 305         ((cls), E_TYPE_CONFIG_HOOK, EConfigHookClass))
 306 #define E_IS_CONFIG_HOOK(obj) \
 307         (G_TYPE_CHECK_INSTANCE_TYPE \
 308         ((obj), E_TYPE_CONFIG_HOOK))
 309 #define E_IS_CONFIG_HOOK_CLASS(cls) \
 310         (G_TYPE_CHECK_CLASS_TYPE \
 311         ((cls), E_TYPE_CONFIG_HOOK))
 312 #define E_CONFIG_HOOK_GET_CLASS(obj) \
 313         (G_TYPE_INSTANCE_GET_CLASS \
 314         ((obj), E_TYPE_CONFIG_HOOK, EConfigHookClass))
 315
 316 G_BEGIN_DECLS
 317
 318 typedef struct _EConfigHookGroup EConfigHookGroup;
 319 typedef struct _EConfigHook EConfigHook;
 320 typedef struct _EConfigHookClass EConfigHookClass;
 321
 322 typedef struct _EPluginHookTargetMap EConfigHookTargetMap;
 323 typedef struct _EPluginHookTargetKey EConfigHookTargetMask;
 324
 325 typedef struct _EConfigHookItemFactoryData EConfigHookItemFactoryData;
 326 typedef struct _EConfigHookPageCheckData EConfigHookPageCheckData;
 327
 328 typedef void    (*EConfigHookFunc)              (EPlugin *plugin,
 329                                                  EConfigTarget *target);
 330 typedef void    (*EConfigHookItemFactoryFunc)   (EPlugin *plugin,
 331                                                  EConfigHookItemFactoryData *data);
 332
 333 /**
 334  * struct _EConfigHookItemFactoryData - Factory marshalling structure.
 335  *
 336  * @config: The parent EConfig.  This is also available in
 337  * @target->config but is here as a convenience. (TODO: do we need this).
 338  * @item: The corresponding configuration item.
 339  * @target: The current configuration target.  This is also available
 340  * on @config->target.
 341  * @parent: The parent widget for this item.  Depends on the item
 342  * type.
 343  * @old: The last widget created by this factory.  The factory is only
 344  * re-invoked if a reconfigure request is invoked on the EConfig.
 345  *
 346  * Used to marshal the callback data for the EConfigItemFactory method
 347  * to a single pointer for the EPlugin system.
 348  **/
 349 struct _EConfigHookItemFactoryData {
 350         EConfig *config;
 351         EConfigItem *item;
 352         EConfigTarget *target;
 353         GtkWidget *parent;
 354         GtkWidget *old;
 355         gint position;
 356 };
 357
 358 /**
 359  * struct _EConfigHookPageCheckData - Check callback data.
 360  *
 361  * @config:
 362  * @target: The current configuration target.  This is also available
 363  * on @config->target.
 364  * @pageid: Name of page to validate, or "" means check all configuration.
 365  *
 366  **/
 367 struct _EConfigHookPageCheckData {
 368         EConfig *config;
 369         EConfigTarget *target;
 370         const gchar *pageid;
 371 };
 372
 373 /**
 374  * struct _EConfigHookGroup - A group of configuration items.
 375  *
 376  * @hook: Parent object.
 377  * @id: The configuration window to which these items apply.
 378  * @target_type: The target type expected by the items.  This is
 379  * defined by implementing classes.
 380  * @items: A list of EConfigHookItem's for this group.
 381  * @check: A validate page handler.
 382  * @commit: The name of the commit function for this group of items, or NULL
 383  * for instant-apply configuration windows.  Its format is plugin-type defined.
 384  * @abort: Similar to the @commit function but for aborting or
 385  * cancelling a configuration edit.
 386  *
 387  * Each plugin that hooks into a given configuration page will define
 388  * all of the items for that page in a single group.
 389  **/
 390 struct _EConfigHookGroup {
 391         struct _EConfigHook *hook; /* parent pointer */
 392         gchar *id;              /* target menu id for these config items */
 393         gint target_type;       /* target type of this group */
 394         GSList *items;          /* items to add to group */
 395         gchar *check;           /* validate handler, if set */
 396         gchar *commit;          /* commit handler, if set */
 397         gchar *abort;           /* abort handler, if set */
 398 };
 399
 400 /**
 401  * struct _EConfigHook - Plugin hook for configuration windows.
 402  *
 403  * @hook: Superclass.
 404  * @groups: A list of EConfigHookGroup's of all configuration windows
 405  * this plugin hooks into.
 406  *
 407  **/
 408 struct _EConfigHook {
 409         EPluginHook hook;
 410
 411         GSList *groups;
 412 };
 413
 414 /**
 415  * EConfigHookClass:
 416  * @hook_class: Superclass.
 417  * @target_map: A table of EConfigHookTargetMap structures describing
 418  * the possible target types supported by this class.
 419  * @config_class: The EConfig derived class that this hook
 420  * implementation drives.
 421  *
 422  * This is an abstract class defining the plugin hook point for
 423  * configuration windows.
 424  *
 425  **/
 426 struct _EConfigHookClass {
 427         EPluginHookClass hook_class;
 428
 429         /* EConfigHookTargetMap by .type */
 430         GHashTable *target_map;
 431         /* the config class these configs's belong to */
 432         EConfigClass *config_class;
 433 };
 434
 435 GType e_config_hook_get_type (void);
 436
 437 /* for implementors */
 438 void            e_config_hook_class_add_target_map
 439                                         (EConfigHookClass *hook_class,
 440                                          const EConfigHookTargetMap *map);
 441
 442 G_END_DECLS
 443
 444 #endif /* E_CONFIG_H */