glade-widget-adaptor.h 42.5 KB
Newer Older
1 2
#ifndef _GLADE_WIDGET_ADAPTOR_H_
#define _GLADE_WIDGET_ADAPTOR_H_
3

4 5
#include <gladeui/glade-xml-utils.h>
#include <gladeui/glade-property-class.h>
6
#include <gladeui/glade-editor-property.h>
7
#include <gladeui/glade-signal-class.h>
8
#include <gladeui/glade-catalog.h>
9
#include <gladeui/glade-editable.h>
10 11 12 13 14 15 16
#include <glib-object.h>
#include <gmodule.h>
#include <gtk/gtk.h>

G_BEGIN_DECLS

#define GLADE_TYPE_WIDGET_ADAPTOR            (glade_widget_adaptor_get_type())
Vincent Geddes's avatar
Vincent Geddes committed
17 18 19 20 21
#define GLADE_WIDGET_ADAPTOR(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GLADE_TYPE_WIDGET_ADAPTOR, GladeWidgetAdaptor))
#define GLADE_WIDGET_ADAPTOR_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GLADE_TYPE_WIDGET_ADAPTOR, GladeWidgetAdaptorClass))
#define GLADE_IS_WIDGET_ADAPTOR(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GLADE_TYPE_WIDGET_ADAPTOR))
#define GLADE_IS_WIDGET_ADAPTOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GLADE_TYPE_WIDGET_ADAPTOR))
#define GLADE_WIDGET_ADAPTOR_GET_CLASS(o)    (G_TYPE_INSTANCE_GET_CLASS ((o), GLADE_WIDGET_ADAPTOR, GladeWidgetAdaptorClass))
22

Vincent Geddes's avatar
Vincent Geddes committed
23 24
typedef struct _GladeWidgetAdaptorPrivate GladeWidgetAdaptorPrivate;
typedef struct _GladeWidgetAdaptorClass   GladeWidgetAdaptorClass;
25

26 27 28 29 30 31 32
/**
 * GWA_DEPRECATED:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks whether this widget class is marked as deprecated
 */
#define GWA_DEPRECATED(obj) \
33
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->deprecated : FALSE)
34 35 36 37 38 39 40

/**
 * GWA_VERSION_SINCE_MAJOR:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks major version in which this widget was introduced
 */
41
#define GWA_VERSION_SINCE_MAJOR(obj) \
42
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->version_since_major : 0)
43 44 45 46 47 48 49

/**
 * GWA_VERSION_SINCE_MINOR:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks minor version in which this widget was introduced
 */
50
#define GWA_VERSION_SINCE_MINOR(obj) \
51
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->version_since_minor : 0)
52

53 54 55 56 57 58 59 60 61
/**
 * GWA_VERSION_CHECK:
 * @adaptor: A #GladeWidgetAdaptor
 * @major_version: The major version to check
 * @minor_version: The minor version to check
 *
 * Evaluates to %TRUE if @adaptor is available in its owning library version-@major_verion.@minor_version.
 *
 */
62 63 64
#define GWA_VERSION_CHECK(adaptor, major_version, minor_version) \
  ((GWA_VERSION_SINCE_MAJOR (adaptor) == major_version) ?        \
   (GWA_VERSION_SINCE_MINOR (adaptor) <= minor_version) :        \
65
   (GWA_VERSION_SINCE_MAJOR (adaptor) <= major_version))
66

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
/**
 * GWA_DEPRECATED_SINCE_MAJOR:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks major version in which this widget was deprecated
 */
#define GWA_DEPRECATED_SINCE_MAJOR(obj) \
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->deprecated_since_major : 0)

/**
 * GWA_DEPRECATED_SINCE_MINOR:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks minor version in which this widget was deprecated
 */
#define GWA_DEPRECATED_SINCE_MINOR(obj) \
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->deprecated_since_minor : 0)

/**
 * GWA_DEPRECATED_SINCE_CHECK:
 * @adaptor: A #GladeWidgetAdaptor
 * @major_version: The major version to check
 * @minor_version: The minor version to check
 *
 * Evaluates to %TRUE if @adaptor is deprecated in its owning library version-@major_verion.@minor_version.
 *
 */
94
#define GWA_DEPRECATED_SINCE_CHECK(adaptor, major_version, minor_version)           \
95
  ((GWA_DEPRECATED_SINCE_MAJOR (adaptor) || GWA_DEPRECATED_SINCE_MINOR (adaptor)) ? \
96 97 98
    ((GWA_DEPRECATED_SINCE_MAJOR (adaptor) == major_version)  ?                     \
      (GWA_DEPRECATED_SINCE_MINOR (adaptor) <= minor_version)  :                    \
      (GWA_DEPRECATED_SINCE_MAJOR (adaptor) <= major_version)) :                    \
99 100
    FALSE)

101 102 103 104 105 106 107 108
/**
 * GWA_IS_TOPLEVEL:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks whether this widget class has been marked as
 * a toplevel one.
 */
#define GWA_IS_TOPLEVEL(obj) \
109
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->toplevel : FALSE)
110

111 112 113 114 115 116 117 118
/**
 * GWA_USE_PLACEHOLDERS:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks whether this widget class has been marked to
 * use placeholders in child widget operations
 */
#define GWA_USE_PLACEHOLDERS(obj) \
119
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->use_placeholders : FALSE)
120

121 122 123 124 125

/**
 * GWA_DEFAULT_WIDTH:
 * @obj: A #GladeWidgetAdaptor
 *
126
 * Returns: the default width to be used when this widget
127 128 129
 * is toplevel in the GladeDesignLayout
 */
#define GWA_DEFAULT_WIDTH(obj) \
130
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->default_width : -1)
131 132 133 134 135 136


/**
 * GWA_DEFAULT_HEIGHT:
 * @obj: A #GladeWidgetAdaptor
 *
137
 * Returns: the default width to be used when this widget
138 139 140
 * is toplevel in the GladeDesignLayout
 */
#define GWA_DEFAULT_HEIGHT(obj) \
141
  ((obj) ? GLADE_WIDGET_ADAPTOR_GET_CLASS(obj)->default_height : -1)
142

143 144 145 146 147 148 149

/**
 * GWA_SCROLLABLE_WIDGET:
 * @obj: A #GladeWidgetAdaptor
 *
 * Checks whether this is a GtkWidgetClass with scrolling capabilities.
 */
150 151 152 153 154
#define GWA_SCROLLABLE_WIDGET(obj)                   \
  ((obj) ?                                           \
   g_type_is_a (glade_widget_adaptor_get_object_type \
                (GLADE_WIDGET_ADAPTOR (obj)),        \
                GTK_TYPE_SCROLLABLE) : FALSE)
155

156 157 158 159 160 161 162
/**
 * GWA_GET_CLASS:
 * @type: A #GType
 *
 * Shorthand for referencing glade adaptor classes from
 * the plugin eg. GWA_GET_CLASS (GTK_TYPE_CONTAINER)->post_create (adaptor...
 */
163 164
#define GWA_GET_CLASS(type)                                                   \
  (((type) == G_TYPE_OBJECT) ?                                                \
165 166
   (GladeWidgetAdaptorClass *)g_type_class_peek (GLADE_TYPE_WIDGET_ADAPTOR) : \
   GLADE_WIDGET_ADAPTOR_GET_CLASS (glade_widget_adaptor_get_by_type(type)))
167

168 169 170 171 172 173 174 175
/**
 * GWA_GET_OCLASS:
 * @type: A #GType.
 *
 * Same as GWA_GET_CLASS but casted to GObjectClass
 */
#define GWA_GET_OCLASS(type) ((GObjectClass*)GWA_GET_CLASS(type))

176 177 178

#define GLADE_VALID_CREATE_REASON(reason) (reason >= 0 && reason < GLADE_CREATE_REASONS)

179 180 181 182 183 184 185
/**
 * GWA_INSTANTIABLE_PREFIX:
 *
 * Class prefix used for abstract classes (ie GtkBin -> GladeInstantiableGtkBin)
 */
#define GWA_INSTANTIABLE_PREFIX "GladeInstantiable"

186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
/**
 * GladeCreateReason:
 * @GLADE_CREATE_USER: Was created at the user's request
 *                     (this is a good time to set any properties
 *                     or add children to the project; like GtkFrame's 
 *                     label for example).
 * @GLADE_CREATE_COPY: Was created as a result of the copy/paste 
 *                     mechanism, at this point you can count on glade
 *                     to follow up with properties and children on 
 *                     its own.
 * @GLADE_CREATE_LOAD: Was created during the load process.
 * @GLADE_CREATE_REBUILD: Was created as a replacement for another project 
 *                        object; this only happens when the user is 
 *                        changing a property that is marked by the type 
 *                        system as G_PARAM_SPEC_CONSTRUCT_ONLY.
 * @GLADE_CREATE_REASONS: Never used.
 *
 * These are the reasons your #GladePostCreateFunc can be called.
 */
Vincent Geddes's avatar
Vincent Geddes committed
205
typedef enum
206
{
207 208 209 210 211
  GLADE_CREATE_USER = 0,
  GLADE_CREATE_COPY,
  GLADE_CREATE_LOAD,
  GLADE_CREATE_REBUILD,
  GLADE_CREATE_REASONS
Vincent Geddes's avatar
Vincent Geddes committed
212
} GladeCreateReason;
213

214
/**
215
 * GladeCreateWidgetFunc:
216 217 218 219 220 221 222 223 224 225 226
 * @adaptor: A #GladeWidgetAdaptor
 * @first_property_name: the name of the first property
 * @var_args: the value of the first property, followed optionally by more
 *  name/value pairs, followed by %NULL
 *
 * This entry point allows the backend to create a specialized GladeWidget
 * derived object for handling instances in the core.
 *
 * Returns: A newly created #GladeWidget for the said adaptor.
 */
typedef GladeWidget * (* GladeCreateWidgetFunc) (GladeWidgetAdaptor *adaptor,
227 228
                                                 const gchar        *first_property_name,
                                                 va_list             var_args);
229

230 231 232 233 234 235 236 237 238 239 240 241 242
/**
 * GladeSetPropertyFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject
 * @property_name: The property identifier
 * @value: The #GValue
 *
 * This delagate function is used to apply the property value on
 * the runtime object.
 *
 * Sets @value on @object for a given #GladePropertyClass
 */
typedef void     (* GladeSetPropertyFunc)    (GladeWidgetAdaptor *adaptor,
243 244 245
                                              GObject            *object,
                                              const gchar        *property_name,
                                              const GValue       *value);
246 247 248 249 250 251 252 253 254 255 256

/**
 * GladeGetPropertyFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject
 * @property_name: The property identifier
 * @value: The #GValue
 *
 * Gets @value on @object for a given #GladePropertyClass
 */
typedef void     (* GladeGetPropertyFunc)    (GladeWidgetAdaptor *adaptor,
257 258 259
                                              GObject            *object,
                                              const gchar        *property_name,
                                              GValue             *value);
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276

/**
 * GladeVerifyPropertyFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject
 * @property_name: The property identifier
 * @value: The #GValue
 *
 * This delagate function is always called whenever setting any
 * properties with the exception of load time, and copy/paste time
 * (basicly the two places where we recreate a hierarchy that we
 * already know "works") its basicly an optional backend provided
 * boundry checker for properties.
 *
 * Returns: whether or not its OK to set @value on @object
 */
typedef gboolean (* GladeVerifyPropertyFunc)      (GladeWidgetAdaptor *adaptor,
277 278 279
                                                   GObject            *object,
                                                   const gchar        *property_name,
                                                   const GValue       *value);
280

281 282 283
/**
 * GladeChildSetPropertyFunc:
 * @adaptor: A #GladeWidgetAdaptor
284
 * @container: The #GObject container
285 286 287 288 289 290 291 292
 * @child: The #GObject child
 * @property_name: The property name
 * @value: The #GValue
 *
 * Called to set the packing property @property_name to @value
 * on the @child object of @container.
 */
typedef void   (* GladeChildSetPropertyFunc)      (GladeWidgetAdaptor *adaptor,
293 294 295 296
                                                   GObject            *container,
                                                   GObject            *child,
                                                   const gchar        *property_name,
                                                   const GValue       *value);
297 298 299

/**
 * GladeChildGetPropertyFunc:
300 301
 * @adaptor: A #GladeWidgetAdaptor
 * @container: The #GObject container
302 303 304 305 306 307 308 309
 * @child: The #GObject child
 * @property_name: The property name
 * @value: The #GValue
 *
 * Called to get the packing property @property_name
 * on the @child object of @container into @value.
 */
typedef void   (* GladeChildGetPropertyFunc)      (GladeWidgetAdaptor *adaptor,
310 311 312 313
                                                   GObject            *container,
                                                   GObject            *child,
                                                   const gchar        *property_name,
                                                   GValue             *value);
314

315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
/**
 * GladeChildVerifyPropertyFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @container: The #GObject container
 * @child: The #GObject child
 * @property_name: The property name
 * @value: The #GValue
 *
 * This delagate function is always called whenever setting any
 * properties with the exception of load time, and copy/paste time
 * (basicly the two places where we recreate a hierarchy that we
 * already know "works") its basicly an optional backend provided
 * boundry checker for properties.
 *
 * Returns: whether or not its OK to set @value on @object
 */
typedef gboolean (* GladeChildVerifyPropertyFunc) (GladeWidgetAdaptor *adaptor,
332 333 334 335
                                                   GObject            *container,
                                                   GObject            *child,
                                                   const gchar        *property_name,
                                                   const GValue       *value);
336

337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
/**
 * GladeAddChildVerifyFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @parent: A #GObject container
 * @child: A #GObject child
 * @user_feedback: whether a notification dialog should be
 * presented in the case that the child cannot not be added.
 *
 * Checks whether @child can be added to @parent.
 *
 * If @user_feedback is %TRUE and @child cannot be
 * added then this shows a notification dialog to the user 
 * explaining why.
 *
 * Returns: whether @child can be added to @parent.
 */
typedef gboolean (* GladeAddChildVerifyFunc)      (GladeWidgetAdaptor *adaptor,
354 355 356
                                                   GObject            *parent,
                                                   GObject            *child,
                                                   gboolean            user_feedback);
357

358 359
/**
 * GladeGetChildrenFunc:
360
 * @adaptor: A #GladeWidgetAdaptor
361 362 363
 * @container: A #GObject container
 *
 * A function called to get @containers children.
364 365
 *
 * Returns: A #GList of #GObject children.
366 367
 */
typedef GList   *(* GladeGetChildrenFunc)         (GladeWidgetAdaptor *adaptor,
368
                                                   GObject            *container);
369 370 371

/**
 * GladeAddChildFunc:
372
 * @adaptor: A #GladeWidgetAdaptor
373 374 375 376 377 378
 * @parent: A #GObject container
 * @child: A #GObject child
 *
 * Called to add @child to @parent.
 */
typedef void     (* GladeAddChildFunc)            (GladeWidgetAdaptor *adaptor,
379 380
                                                   GObject            *parent,
                                                   GObject            *child);
381

382 383
/**
 * GladeRemoveChildFunc:
384
 * @adaptor: A #GladeWidgetAdaptor
385 386 387 388 389 390
 * @parent: A #GObject container
 * @child: A #GObject child
 *
 * Called to remove @child from @parent.
 */
typedef void     (* GladeRemoveChildFunc)         (GladeWidgetAdaptor *adaptor,
391 392
                                                   GObject            *parent,
                                                   GObject            *child);
393 394 395

/**
 * GladeReplaceChildFunc:
396
 * @adaptor: A #GladeWidgetAdaptor
397
 * @container: A #GObject container
398 399
 * @old_obj: The old #GObject child
 * @new_obj: The new #GObject child to take its place
400 401 402 403 404
 * 
 * Called to swap placeholders with project objects
 * in containers.
 */
typedef void     (* GladeReplaceChildFunc)        (GladeWidgetAdaptor *adaptor,
405 406 407
                                                   GObject            *container,  
                                                   GObject            *old_obj,
                                                   GObject            *new_obj);
408

409 410 411 412 413 414 415 416 417 418 419 420 421 422 423

/**
 * GladeConstructObjectFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @n_parameters: amount of construct parameters
 * @parameters: array of construct #GParameter args to create 
 *              the new object with.
 *
 * This function is called to construct a GObject instance.
 * (for language bindings that may need to construct a wrapper
 * object).
 *
 * Returns: A newly created #GObject
 */
typedef GObject *(* GladeConstructObjectFunc)     (GladeWidgetAdaptor *adaptor,
424 425
                                                   guint               n_parameters,
                                                   GParameter         *parameters);
426

427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446
/**
 * GladeDestroyObjectFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject to destroy
 *
 * This function is called to break any additional references to
 * a GObject instance. Note that this function is not responsible
 * for calling g_object_unref() on @object, the reference count
 * of @object belongs to it's #GladeWidget wrapper.
 *
 * The #GtkWidget adaptor will call gtk_widget_destroy() before
 * chaining up in this function.
 *
 * If your adaptor adds any references in any way at
 * #GladePostCreateFunc time or #GladeConstructObjectFunc
 * time, then this function must be implemented to also
 * remove that reference.
 *
 */
typedef void (* GladeDestroyObjectFunc) (GladeWidgetAdaptor *adaptor,
447
                                         GObject            *object);
448 449


450 451
/**
 * GladePostCreateFunc:
452
 * @adaptor: A #GladeWidgetAdaptor
453 454 455 456 457 458 459
 * @object: a #GObject
 * @reason: a #GladeCreateReason
 *
 * This function is called exactly once for any project object
 * instance and can be for any #GladeCreateReason.
 */
typedef void     (* GladePostCreateFunc)          (GladeWidgetAdaptor *adaptor,
460 461
                                                   GObject            *object,
                                                   GladeCreateReason   reason);
462 463 464

/**
 * GladeGetInternalFunc:
465
 * @adaptor: A #GladeWidgetAdaptor
466 467 468 469
 * @parent: A #GObject composite object
 * @name: A string identifier
 *
 * Called to lookup @child in composite object @parent by @name.
470 471
 *
 * Returns: The specified internal widget.
472 473
 */
typedef GObject *(* GladeGetInternalFunc)         (GladeWidgetAdaptor *adaptor,
474 475
                                                   GObject            *parent,
                                                   const gchar        *name);
476

477
/**
478
 * GladeActionActivateFunc:
479 480
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject
481
 * @action_path: The action path
482 483 484 485 486
 *
 * This delagate function is used to catch actions from the core.
 *
 */
typedef void     (* GladeActionActivateFunc)  (GladeWidgetAdaptor *adaptor,
487 488
                                               GObject            *object,
                                               const gchar        *action_path);
489 490

/**
491
 * GladeChildActionActivateFunc:
492 493 494 495 496 497 498 499 500
 * @adaptor: A #GladeWidgetAdaptor
 * @container: The #GtkContainer
 * @object: The #GObject
 * @action_path: The action path
 *
 * This delagate function is used to catch packing actions from the core.
 *
 */
typedef void     (* GladeChildActionActivateFunc) (GladeWidgetAdaptor *adaptor,
501 502 503
                                                   GObject            *container,
                                                   GObject            *object,
                                                   const gchar        *action_path);
504

Tristan Van Berkom's avatar
Tristan Van Berkom committed
505 506 507 508 509 510 511 512 513 514 515 516

/**
 * GladeActionSubmenuFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @object: The #GObject
 * @action_path: The action path
 *
 * This delagate function is used to create dynamically customized
 * submenus. Called only for actions that dont have children.
 *
 */
typedef GtkWidget  *(* GladeActionSubmenuFunc)  (GladeWidgetAdaptor *adaptor,
517 518
                                                 GObject            *object,
                                                 const gchar        *action_path);
Tristan Van Berkom's avatar
Tristan Van Berkom committed
519 520


521 522 523 524 525 526 527 528 529 530 531 532 533
/**
 * GladeDependsFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @widget: A #GladeWidget of the adaptor
 * @another: another #GladeWidget
 *
 * Checks whether @widget depends on @another to be placed earlier in
 * the glade file.
 *
 * Returns: whether @widget depends on @another being parsed first in
 * the resulting glade file.
 */
typedef gboolean (* GladeDependsFunc) (GladeWidgetAdaptor *adaptor,
534 535
                                       GladeWidget        *widget,
                                       GladeWidget        *another);
536

Tristan Van Berkom's avatar
Tristan Van Berkom committed
537 538


539 540 541 542 543 544 545 546 547 548
/**
 * GladeReadWidgetFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @widget: The #GladeWidget
 * @node: The #GladeXmlNode
 *
 * This function is called to update @widget from @node.
 *
 */
typedef void     (* GladeReadWidgetFunc) (GladeWidgetAdaptor *adaptor,
549 550
                                          GladeWidget        *widget,
                                          GladeXmlNode       *node);
551 552 553 554 555 556 557 558 559 560 561

/**
 * GladeWriteWidgetFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @widget: The #GladeWidget
 * @node: The #GladeXmlNode
 *
 * This function is called to fill in @node from @widget.
 *
 */
typedef void     (* GladeWriteWidgetFunc) (GladeWidgetAdaptor *adaptor,
562 563 564
                                           GladeWidget        *widget,
                                           GladeXmlContext    *context,
                                           GladeXmlNode       *node);
565 566 567 568 569 570 571 572 573 574 575 576 577 578


/**
 * GladeCreateEPropFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @klass: The #GladePropertyClass to be edited
 * @use_command: whether to use the GladeCommand interface
 * to commit property changes
 * 
 * Creates a GladeEditorProperty to edit @klass
 *
 * Returns: A newly created #GladeEditorProperty
 */
typedef GladeEditorProperty *(* GladeCreateEPropFunc) (GladeWidgetAdaptor *adaptor,
579 580
                                                       GladePropertyClass *klass,
                                                       gboolean            use_command);
581 582 583 584 585 586 587 588

/**
 * GladeStringFromValueFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @klass: The #GladePropertyClass 
 * @value: The #GValue to convert to a string
 * 
 * For normal properties this is used to serialize
589 590 591
 * property values, for custom properties (only when new pspecs are 
 * introduced) its needed for value comparisons in boxed pspecs 
 * and also to update the UI for undo/redo items etc.
592 593 594 595
 *
 * Returns: A newly allocated string representation of @value
 */
typedef gchar   *(* GladeStringFromValueFunc) (GladeWidgetAdaptor *adaptor,
596 597
                                               GladePropertyClass *klass,
                                               const GValue       *value);
598 599


600 601 602 603 604 605 606 607 608 609 610 611 612

/**
 * GladeCreateEditableFunc:
 * @adaptor: A #GladeWidgetAdaptor
 * @type: The #GladeEditorPageType
 * 
 * This is used to allow the backend to override the way an
 * editor page is layed out (note that editor widgets are created
 * on demand and not at startup).
 *
 * Returns: A new #GladeEditable widget
 */
typedef GladeEditable *(* GladeCreateEditableFunc) (GladeWidgetAdaptor   *adaptor,
613
                                                    GladeEditorPageType   type);
614 615


616 617 618 619 620 621 622
/* Note that everything that must be processed at the creation of
 * every instance is managed on the instance structure, and everywhere
 * that we want to take advantage of inheritance is handled in the class
 * structure.
 */
struct _GladeWidgetAdaptor
{
623
  GObject      parent_instance;
624

625
  GladeWidgetAdaptorPrivate *priv;
626 627 628 629 630

};

struct _GladeWidgetAdaptorClass
{
631
  GObjectClass               parent_class;
632

633 634
  guint16                    version_since_major; /* Version in which this widget was */
  guint16                    version_since_minor; /* introduced.                      */
635

636 637
  gint16                     default_width;       /* Default width in GladeDesignLayout */
  gint16                     default_height;      /* Default height in GladeDesignLayout */
638

639
  guint                      deprecated : 1;          /* If this widget is currently
640 641
                                                       * deprecated
                                                       */
642
  guint                      toplevel : 1;             /* If this class is toplevel */
643

644
  guint                      use_placeholders : 1;     /* Whether or not to use placeholders
645 646
                                                        * to interface with child widgets.
                                                        */
647

648 649 650
  GladeCreateWidgetFunc      create_widget;  /* Creates a GladeWidget for this adaptor */

  GladeConstructObjectFunc   construct_object;  /* Object constructor
651
                                                 */
652 653

  GladePostCreateFunc        deep_post_create;   /* Executed after widget creation: 
654 655 656 657
                                                  * plugins use this to setup various
                                                  * support codes (adaptors must always
                                                  * chain up in this stage of instantiation).
                                                  */
658 659

  GladePostCreateFunc        post_create;   /* Executed after widget creation: 
660 661 662 663 664
                                             * plugins use this to setup various
                                             * support codes (adaptors are free here
                                             * to chain up or not in this stage of
                                             * instantiation).
                                             */
665 666

  GladeGetInternalFunc       get_internal_child; /* Retrieves the the internal child
667 668
                                                  * of the given name.
                                                  */
669 670 671 672 673 674

  /* Delagate to verify if this is a valid value for this property,
   * if this function exists and returns FALSE, then glade_property_set
   * will abort before making any changes
   */
  GladeVerifyPropertyFunc verify_property;
675
        
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690
  /* An optional backend function used instead of g_object_set()
   * virtual properties must be handled with this function.
   */
  GladeSetPropertyFunc set_property;

  /* An optional backend function used instead of g_object_get()
   * virtual properties must be handled with this function.
   *
   * Note that since glade knows what the property values are 
   * at all times regardless of the objects copy, this is currently
   * only used to obtain the values of packing properties that are
   * set by the said object's parent at "container_add" time.
   */
  GladeGetPropertyFunc get_property;

691
  GladeAddChildVerifyFunc    add_verify;       /* Checks if a child can be added */
692 693 694
  GladeAddChildFunc          add;              /* Adds a new child of this type */
  GladeRemoveChildFunc       remove;           /* Removes a child from the container */
  GladeGetChildrenFunc       get_children;     /* Returns a list of direct children for
695 696
                                                * this support type.
                                                */
697 698

  GladeChildVerifyPropertyFunc child_verify_property; /* A boundry checker for 
699 700
                                                       * packing properties 
                                                       */
701 702 703
  GladeChildSetPropertyFunc    child_set_property; /* Sets/Gets a packing property */
  GladeChildGetPropertyFunc    child_get_property; /* for this child */
  GladeReplaceChildFunc        replace_child;  /* This method replaces a 
704 705 706 707 708 709
                                                * child widget with
                                                * another one: it's used to
                                                * replace a placeholder with
                                                * a widget and viceversa.
                                                */
        
710 711 712
  GladeActionActivateFunc      action_activate;       /* This method is used to catch actions */
  GladeChildActionActivateFunc child_action_activate; /* This method is used to catch packing actions */
  GladeActionSubmenuFunc       action_submenu;        /* Delagate function to create dynamic submenus
713
                                                       * in action menus. */
714 715 716 717 718 719 720 721
  GladeDependsFunc             depends;           /* Periodically sort widgets in the project */
  GladeReadWidgetFunc          read_widget;       /* Reads widget attributes from xml */
  GladeWriteWidgetFunc         write_widget;      /* Writes widget attributes to the xml */
  GladeReadWidgetFunc          read_child;        /* Reads widget attributes from xml */
  GladeWriteWidgetFunc         write_child;       /* Writes widget attributes to the xml */
  GladeCreateEPropFunc         create_eprop;      /* Creates a GladeEditorProperty */
  GladeStringFromValueFunc     string_from_value; /* Creates a string for a value */
  GladeCreateEditableFunc      create_editable;   /* Creates a page for the editor */
722 723 724

  GladeDestroyObjectFunc       destroy_object;    /* Object destructor */
  GladeWriteWidgetFunc         write_widget_after;/* Writes widget attributes to the xml (after children) */
725 726 727 728

  guint16                      deprecated_since_major;
  guint16                      deprecated_since_minor;

729 730 731 732 733
  void   (* glade_reserved1)   (void);
  void   (* glade_reserved2)   (void);
  void   (* glade_reserved3)   (void);
  void   (* glade_reserved4)   (void);
  void   (* glade_reserved5)   (void);
734 735 736 737 738
};

#define glade_widget_adaptor_create_widget(adaptor, query, ...) \
    (glade_widget_adaptor_create_widget_real (query, "adaptor", adaptor, __VA_ARGS__));

739

740
GType                 glade_widget_adaptor_get_type         (void) G_GNUC_CONST;
741

742 743 744
GType                 glade_widget_adaptor_get_object_type  (GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN gchar *glade_widget_adaptor_get_name         (GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN gchar *glade_widget_adaptor_get_generic_name (GladeWidgetAdaptor   *adaptor);
745
G_CONST_RETURN gchar *glade_widget_adaptor_get_display_name (GladeWidgetAdaptor   *adaptor);
746 747 748
G_CONST_RETURN gchar *glade_widget_adaptor_get_title        (GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN gchar *glade_widget_adaptor_get_icon_name    (GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN gchar *glade_widget_adaptor_get_missing_icon (GladeWidgetAdaptor   *adaptor);
749
G_CONST_RETURN gchar *glade_widget_adaptor_get_catalog      (GladeWidgetAdaptor   *adaptor);
750
G_CONST_RETURN gchar *glade_widget_adaptor_get_book         (GladeWidgetAdaptor   *adaptor);
751 752 753
G_CONST_RETURN GList *glade_widget_adaptor_get_properties   (GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN GList *glade_widget_adaptor_get_packing_props(GladeWidgetAdaptor   *adaptor);
G_CONST_RETURN GList *glade_widget_adaptor_get_signals      (GladeWidgetAdaptor   *adaptor);
754

755
GList                *glade_widget_adaptor_list_adaptors    (void);
756

757
GladeWidgetAdaptor   *glade_widget_adaptor_from_catalog     (GladeCatalog         *catalog,
758 759
                                                             GladeXmlNode         *class_node,
                                                             GModule              *module);
760

761
void                  glade_widget_adaptor_register         (GladeWidgetAdaptor   *adaptor);
762
 
763
GladeWidget          *glade_widget_adaptor_create_internal  (GladeWidget          *parent,
764 765 766 767 768
                                                             GObject              *internal_object,
                                                             const gchar          *internal_name,
                                                             const gchar          *parent_name,
                                                             gboolean              anarchist,
                                                             GladeCreateReason     reason);
769 770

GladeWidget          *glade_widget_adaptor_create_widget_real (gboolean            query, 
771 772
                                                               const gchar        *first_property,
                                                               ...);
773 774 775 776 777


GladeWidgetAdaptor   *glade_widget_adaptor_get_by_name        (const gchar        *name);
GladeWidgetAdaptor   *glade_widget_adaptor_get_by_type        (GType               type);
GladeWidgetAdaptor   *glade_widget_adaptor_from_pspec         (GladeWidgetAdaptor *adaptor,
778
                                                               GParamSpec         *spec);
779 780

GladePropertyClass   *glade_widget_adaptor_get_property_class (GladeWidgetAdaptor *adaptor,
781
                                                               const gchar        *name);
782
GladePropertyClass   *glade_widget_adaptor_get_pack_property_class (GladeWidgetAdaptor *adaptor,
783
                                                                    const gchar        *name);
784 785

GParameter           *glade_widget_adaptor_default_params     (GladeWidgetAdaptor *adaptor,
786 787
                                                               gboolean            construct,
                                                               guint              *n_params);
788
GObject              *glade_widget_adaptor_construct_object   (GladeWidgetAdaptor *adaptor,
789 790
                                                               guint               n_parameters,
                                                               GParameter         *parameters);
791
void                  glade_widget_adaptor_destroy_object     (GladeWidgetAdaptor *adaptor,
792
                                                               GObject            *object);
793
void                  glade_widget_adaptor_post_create        (GladeWidgetAdaptor *adaptor,
794 795
                                                               GObject            *object,
                                                               GladeCreateReason   reason);
796
GObject              *glade_widget_adaptor_get_internal_child (GladeWidgetAdaptor *adaptor,
797 798
                                                               GObject            *object,
                                                               const gchar        *internal_name);
799
void                  glade_widget_adaptor_set_property       (GladeWidgetAdaptor *adaptor,
800 801 802
                                                               GObject            *object,
                                                               const gchar        *property_name,
                                                               const GValue       *value);
803
void                  glade_widget_adaptor_get_property       (GladeWidgetAdaptor *adaptor,
804 805 806
                                                               GObject            *object,
                                                               const gchar        *property_name,
                                                               GValue             *value);
807
gboolean              glade_widget_adaptor_verify_property    (GladeWidgetAdaptor *adaptor,
808 809 810
                                                               GObject            *object,
                                                               const gchar        *property_name,
                                                               const GValue       *value);
811
gboolean              glade_widget_adaptor_add_verify         (GladeWidgetAdaptor *adaptor,
812 813 814
                                                               GObject            *container,
                                                               GObject            *child,
                                                               gboolean            user_feedback);
815
void                  glade_widget_adaptor_add                (GladeWidgetAdaptor *adaptor,
816 817
                                                               GObject            *container,
                                                               GObject            *child);
818
void                  glade_widget_adaptor_remove             (GladeWidgetAdaptor *adaptor,
819 820
                                                               GObject            *container,
                                                               GObject            *child);
821
GList                *glade_widget_adaptor_get_children       (GladeWidgetAdaptor *adaptor,
822
                                                               GObject            *container);
823
gboolean              glade_widget_adaptor_has_child          (GladeWidgetAdaptor *adaptor,
824 825
                                                               GObject            *container,
                                                               GObject            *child);
826
void                  glade_widget_adaptor_child_set_property (GladeWidgetAdaptor *adaptor,
827 828 829 830
                                                               GObject            *container,
                                                               GObject            *child,
                                                               const gchar        *property_name,
                                                               const GValue       *value);
831
void                  glade_widget_adaptor_child_get_property (GladeWidgetAdaptor *adaptor,
832 833 834 835
                                                               GObject            *container,
                                                               GObject            *child,
                                                               const gchar        *property_name,
                                                               GValue             *value);
836
gboolean              glade_widget_adaptor_child_verify_property (GladeWidgetAdaptor *adaptor,
837 838 839 840
                                                                  GObject            *container,
                                                                  GObject            *child,
                                                                  const gchar        *property_name,
                                                                  const GValue       *value);
841
void                  glade_widget_adaptor_replace_child      (GladeWidgetAdaptor *adaptor,
842 843 844
                                                               GObject            *container,
                                                               GObject            *old_obj,
                                                               GObject            *new_obj);
845 846 847
gboolean              glade_widget_adaptor_query              (GladeWidgetAdaptor *adaptor);

G_CONST_RETURN gchar *glade_widget_adaptor_get_packing_default(GladeWidgetAdaptor *child_adaptor,
848 849
                                                               GladeWidgetAdaptor *container_adaptor,
                                                               const gchar        *id);
850 851
gboolean              glade_widget_adaptor_is_container       (GladeWidgetAdaptor *adaptor);
gboolean              glade_widget_adaptor_action_add         (GladeWidgetAdaptor *adaptor,
852 853 854 855
                                                               const gchar *action_path,
                                                               const gchar *label,
                                                               const gchar *stock,
                                                               gboolean important);
856
gboolean              glade_widget_adaptor_pack_action_add    (GladeWidgetAdaptor *adaptor,
857 858 859 860
                                                               const gchar *action_path,
                                                               const gchar *label,
                                                               const gchar *stock,
                                                               gboolean important);
861
gboolean              glade_widget_adaptor_action_remove      (GladeWidgetAdaptor *adaptor,
862
                                                               const gchar *action_path);
863
gboolean              glade_widget_adaptor_pack_action_remove (GladeWidgetAdaptor *adaptor,
864
                                                               const gchar *action_path);
865 866 867
GList                *glade_widget_adaptor_actions_new        (GladeWidgetAdaptor *adaptor);
GList                *glade_widget_adaptor_pack_actions_new   (GladeWidgetAdaptor *adaptor);
void                  glade_widget_adaptor_action_activate    (GladeWidgetAdaptor *adaptor,
868 869
                                                               GObject            *object,
                                                               const gchar        *action_path);
870
void                  glade_widget_adaptor_child_action_activate (GladeWidgetAdaptor *adaptor,
871 872 873
                                                                  GObject            *container,
                                                                  GObject            *object,
                                                                  const gchar        *action_path);
874
GtkWidget            *glade_widget_adaptor_action_submenu        (GladeWidgetAdaptor *adaptor,
875 876
                                                                  GObject            *object,
                                                                  const gchar        *action_path);
877 878

G_DEPRECATED
879
gboolean              glade_widget_adaptor_depends            (GladeWidgetAdaptor *adaptor,
880 881
                                                               GladeWidget        *widget,
                                                               GladeWidget        *another);
882 883

void                  glade_widget_adaptor_read_widget        (GladeWidgetAdaptor *adaptor,
884 885
                                                               GladeWidget        *widget,
                                                               GladeXmlNode       *node);
886
void                  glade_widget_adaptor_write_widget       (GladeWidgetAdaptor *adaptor,
887 888 889
                                                               GladeWidget        *widget,
                                                               GladeXmlContext    *context,
                                                               GladeXmlNode       *node);
890
void                  glade_widget_adaptor_write_widget_after (GladeWidgetAdaptor *adaptor,
891 892 893
                                                               GladeWidget        *widget,
                                                               GladeXmlContext    *context,
                                                               GladeXmlNode       *node);
894
void                  glade_widget_adaptor_read_child         (GladeWidgetAdaptor *adaptor,
895 896
                                                               GladeWidget        *widget,
                                                               GladeXmlNode       *node);
897
void                  glade_widget_adaptor_write_child        (GladeWidgetAdaptor *adaptor,
898 899 900
                                                               GladeWidget        *widget,
                                                               GladeXmlContext    *context,
                                                               GladeXmlNode       *node);
901 902

GladeEditorProperty  *glade_widget_adaptor_create_eprop       (GladeWidgetAdaptor *adaptor,
903 904
                                                               GladePropertyClass *klass,
                                                               gboolean            use_command);
905
GladeEditorProperty  *glade_widget_adaptor_create_eprop_by_name (GladeWidgetAdaptor *adaptor,
906 907 908
                                                                 const gchar        *property_id,
                                                                 gboolean            packing,
                                                                 gboolean            use_command);
909 910

gchar                *glade_widget_adaptor_string_from_value  (GladeWidgetAdaptor *adaptor,
911 912
                                                               GladePropertyClass *klass,
                                                               const GValue       *value);
913
GladeEditable        *glade_widget_adaptor_create_editable    (GladeWidgetAdaptor *adaptor,
914
                                                               GladeEditorPageType type);
915
GladeSignalClass     *glade_widget_adaptor_get_signal_class   (GladeWidgetAdaptor *adaptor,
916
                                                               const gchar        *name);
917
GladeWidgetAdaptor   *glade_widget_adaptor_get_parent_adaptor (GladeWidgetAdaptor *adaptor);
918

919
gboolean              glade_widget_adaptor_has_internal_children (GladeWidgetAdaptor *adaptor);
920

921 922
G_END_DECLS

923
#endif /* _GLADE_WIDGET_ADAPTOR_H_ */