## GogObject

GogObject

## Synopsis

    #include <goffice/graph/gog-object.h>

                        GogObject;
                        GogObjectClass;
    #define             GOG_PARAM_FORCE_SAVE
    #define             GOG_PARAM_POSITION
    void                (*GogDataDuplicator)                (GogDataset const *src,
                                                             GogDataset *dst);
    enum                GogObjectNamingConv;
                        GogObjectRole;
    GogObject *         gog_object_dup                      (GogObject const *src,
                                                             GogObject *new_parent,
                                                             GogDataDuplicator datadup);
    GogObject *         gog_object_get_parent               (GogObject const *obj);
    GogObject *         gog_object_get_parent_typed         (GogObject const *obj,
                                                             GType t);
    GogGraph *          gog_object_get_graph                (GogObject const *obj);
    GogTheme *          gog_object_get_theme                (GogObject const *obj);
    unsigned            gog_object_get_id                   (GogObject const *obj);
    char const  *       gog_object_get_name                 (GogObject const *obj);
    void                gog_object_set_name                 (GogObject *obj,
                                                             char *name,
                                                             GError **err);
    GSList *            gog_object_get_children             (GogObject const *obj,
                                                             GogObjectRole const *filter);
    GogObject *         gog_object_get_child_by_role        (GogObject const *obj,
                                                             GogObjectRole const *role);
    GogObject *         gog_object_get_child_by_name        (GogObject const *obj,
                                                             char const *name);
    gpointer            gog_object_get_editor               (GogObject *obj,
                                                             GogDataAllocator *dalloc,
                                                             GOCmdContext *cc);
    GogView *           gog_object_new_view                 (GogObject const *obj,
                                                             GogView *parent);
    gboolean            gog_object_is_deletable             (GogObject const *obj);
    GSList *            gog_object_possible_additions       (GogObject const *parent);
    void                gog_object_register_roles           (GogObjectClass *klass,
                                                             GogObjectRole const *roles,
                                                             unsigned int n_roles);
    GogObject *         gog_object_add_by_role              (GogObject *parent,
                                                             GogObjectRole const *role,
                                                             GogObject *child);
    GogObject *         gog_object_add_by_name              (GogObject *parent,
                                                             char const *role,
                                                             GogObject *child);
    void                gog_object_can_reorder              (GogObject const *obj,
                                                             gboolean *inc_ok,
                                                             gboolean *dec_ok);
    GogObject *         gog_object_reorder                  (GogObject const *obj,
                                                             gboolean inc,
                                                             gboolean goto_max);
    GogObjectPosition   gog_object_get_position_flags       (GogObject const *obj,
                                                             GogObjectPosition mask);
    gboolean            gog_object_set_position_flags       (GogObject *obj,
                                                             GogObjectPosition flags,
                                                             GogObjectPosition mask);
    gboolean            gog_object_is_default_position_flags
                                                            (GogObject const *obj,
                                                             char const *name);
    void                gog_object_get_manual_position      (GogObject *obj,
                                                             GogViewAllocation *pos);
    void                gog_object_set_manual_position      (GogObject *obj,
                                                             GogViewAllocation const *pos);
    GogViewAllocation   gog_object_get_manual_allocation    (GogObject *gobj,
                                                             GogViewAllocation const *parent_allocation,
                                                             GogViewRequisition const *requisition);
    GogObjectRole const * gog_object_find_role_by_name      (GogObject const *obj,
                                                             char const *role);
    void                gog_object_update                   (GogObject *obj);
    gboolean            gog_object_request_update           (GogObject *obj);
    void                gog_object_emit_changed             (GogObject *obj,
                                                             gboolean size);
    gboolean            gog_object_clear_parent             (GogObject *obj);
    gboolean            gog_object_set_parent               (GogObject *child,
                                                             GogObject *parent,
                                                             GogObjectRole const *role,
                                                             unsigned int id);
    void                gog_object_request_editor_update    (GogObject *obj);
    void                gog_object_document_changed         (GogObject *obj,
                                                             GODoc *doc);
    #define             gog_object_is_visible               (obj)
    void                gog_object_set_invisible            (GogObject *obj,
                                                             gboolean invisible);

    enum                GogObjectPosition;
    #define             GOG_POSITION_IS_PADDING             (pos)
    #define             GOG_POSITION_IS_SPECIAL             (pos)

    enum                GogDataType;
    enum                GogDimType;
    enum                GogMSDimType;
    void                (*GogEnumFunc)                      (unsigned  i,
                                                             gpointer style,
                                                             char const *name,
                                                             gpointer data);

## Object Hierarchy

      GObject
       +----GogObject
             +----Gog3DBox
             +----GogStyledObject
             +----GogPlot

## Properties

      "alignment"                gchar*                : Read / Write
      "anchor"                   gchar*                : Read / Write
      "compass"                  gchar*                : Read / Write
      "id"                       guint                 : Read / Write
      "invisible"                gboolean              : Read / Write
      "is-position-manual"       gboolean              : Read / Write
      "position"                 gchar*                : Read / Write

## Signals

      "changed"                                        : Run Last
      "child-added"                                    : Run Last
      "child-name-changed"                             : Run Last
      "child-removed"                                  : Run Last
      "children-reordered"                             : Run Last
      "name-changed"                                   : Run Last
      "update-editor"                                  : Run Last

## Description

## Details

### GogObject

    typedef struct _GogObject GogObject;

### GogObjectClass

    typedef struct {
    	GObjectClass base;

    	GHashTable *roles;
    	GType	    view_type;

    	/* using some Private/Public statements to make gtk-doc happy since it does not like the ":1"*/

    	/* Virtuals */
    	void	     (*update)		(GogObject *obj);
    	void	     (*parent_changed) (GogObject *obj, gboolean was_set);
    	char const  *(*type_name) (GogObject const *obj);
    	void	     (*populate_editor) (GogObject *obj,
    					 GOEditor *editor,
    					 GogDataAllocator *dalloc,
    					 GOCmdContext *cc);
    	void	     (*document_changed)(GogObject *obj, GODoc *doc);

    	/* signals */
    	void (*changed)		(GogObject *obj, gboolean size);
    	void (*name_changed) (GogObject *obj);
    	void (*possible_additions_changed) (GogObject const *obj);
    	void (*child_added)	   (GogObject *parent, GogObject *child);
    	void (*child_removed)	   (GogObject *parent, GogObject *child);
    	void (*child_name_changed) (GogObject const *obj, GogObject const *child);
    	void (*children_reordered) (GogObject *obj);
    	void (*update_editor)	   (GogObject *obj);
    } GogObjectClass;

### GOG_PARAM_FORCE_SAVE

    #define GOG_PARAM_FORCE_SAVE (1 << (G_PARAM_USER_SHIFT+1)) /* even if the value == default */

### GOG_PARAM_POSITION

    #define GOG_PARAM_POSITION (1 << (G_PARAM_USER_SHIFT+2)) /* position parameters */

### GogDataDuplicator ()

    void                (*GogDataDuplicator)                (GogDataset const *src,
                                                             GogDataset *dst);

`src` : |
`dst` : |

### enum GogObjectNamingConv

    typedef enum {
    	GOG_OBJECT_NAME_BY_ROLE	 = 1,
    	GOG_OBJECT_NAME_BY_TYPE  = 2,
    	GOG_OBJECT_NAME_MANUALLY = 3
    } GogObjectNamingConv;

### GogObjectRole

    typedef struct {
    	char const *id; /* for persistence */
    	char const *is_a_typename;
    	unsigned    priority;

    	guint32		  	allowable_positions;
    	GogObjectPosition 	default_position;
    	GogObjectNamingConv naming_conv;

    	gboolean   (*can_add)	  (GogObject const *parent);
    	gboolean   (*can_remove)  (GogObject const *child);
    	GogObject *(*allocate)    (GogObject *parent);
    	void	   (*post_add)    (GogObject *parent, GogObject *child);
    	void       (*pre_remove)  (GogObject *parent, GogObject *child);
    	void       (*post_remove) (GogObject *parent, GogObject *child);

    	union { /* allow people to tack some useful tidbits on the end */
    		int		i;
    		gpointer p;
    	} user;
    } GogObjectRole;

### gog_object_dup ()

    GogObject *         gog_object_dup                      (GogObject const *src,
                                                             GogObject *new_parent,
                                                             GogDataDuplicator datadup);

Create a deep copy of `obj` using `new_parent` as its parent.

`src` : | GogObject
`new_parent` : | GogObject the parent tree for the object (can be NULL)
`datadup` : | a function to duplicate the data (a default one is used if NULL)
Returns : | FIXME

### gog_object_get_parent ()

    GogObject *         gog_object_get_parent               (GogObject const *obj);

`obj` : | a GogObject
Returns : | `obj`'s parent, potentially `NULL` if it has not been added to a heirarchy yet. does not change ref-count in any way.

### gog_object_get_parent_typed ()

    GogObject *         gog_object_get_parent_typed         (GogObject const *obj,
                                                             GType t);

`obj` : | a GogObject
`t` : | a GType
Returns : | `obj`'s parent of type `type`, potentially `NULL` if it has not been added to a hierarchy yet or none of the parents are of type `type`.

### gog_object_get_graph ()

    GogGraph *          gog_object_get_graph                (GogObject const *obj);

`obj` : | const * GogObject
Returns : | the parent graph.

### gog_object_get_theme ()

    GogTheme *          gog_object_get_theme                (GogObject const *obj);

`obj` : |
Returns : |

### gog_object_get_id ()

    unsigned            gog_object_get_id                   (GogObject const *obj);

`obj` : |
Returns : |

### gog_object_get_name ()

    char const  *       gog_object_get_name                 (GogObject const *obj);

No need to free the result

`obj` : | a GogObject
Returns : | a name.

### gog_object_set_name ()

    void                gog_object_set_name                 (GogObject *obj,
                                                             char *name,
                                                             GError **err);

Assign the new name and signals that it has changed. NOTE : it _absorbs_ `name` rather than copying it, and generates a new name if `name` == `NULL`

`obj` : | GogObject
`name` : | The new name for `obj`
`err` : | GError

### gog_object_get_children ()

    GSList *            gog_object_get_children             (GogObject const *obj,
                                                             GogObjectRole const *filter);

`obj` : | a GogObject
`filter` : | an optional GogObjectRole to use as a filter
Returns : | A list of `obj`'s Children. Caller must free the list, but not the children.

### gog_object_get_child_by_role ()

    GogObject *         gog_object_get_child_by_role        (GogObject const *obj,
                                                             GogObjectRole const *role);

A convenience routine to find a unique child with `role`.

`obj` : | a GogObject
`role` : | a GogObjectRole to use as a filter
Returns : | `NULL` and spews an error if there is more than one.

### gog_object_get_child_by_name ()

    GogObject *         gog_object_get_child_by_name        (GogObject const *obj,
                                                             char const *name);

A convenience routine to find a unique child with role == `name`

`obj` : | a GogObject
`name` : | a char to use as a role name filter
Returns : | `NULL` and spews an error if there is more than one.

### gog_object_get_editor ()

    gpointer            gog_object_get_editor               (GogObject *obj,
                                                             GogDataAllocator *dalloc,
                                                             GOCmdContext *cc);

Builds an object property editor, by calling GogObject::populate_editor virtual functions.

`obj` : | a GogObject
`dalloc` : | a GogDataAllocator
`cc` : | a GOCmdContext
Returns : | a GtkNotebook widget

### gog_object_new_view ()

    GogView *           gog_object_new_view                 (GogObject const *obj,
                                                             GogView *parent);

Creates a new GogView associated to `obj`, and sets its parent to `parent`.

`obj` : | a GogObject
`parent` : | parent view
Returns : | a new GogView

### gog_object_is_deletable ()

    gboolean            gog_object_is_deletable             (GogObject const *obj);

`obj` : | a GogObject
Returns : | `TRUE` if `obj` can be deleted.

### gog_object_possible_additions ()

    GSList *            gog_object_possible_additions       (GogObject const *parent);

`parent` : | a GogObject
Returns : | a list of GogObjectRoles that could be added. The resulting list needs to be freed

### gog_object_register_roles ()

    void                gog_object_register_roles           (GogObjectClass *klass,
                                                             GogObjectRole const *roles,
                                                             unsigned int n_roles);

`klass` : | GogObjectClass
`roles` : | GogObjectRole
`n_roles` : | number of roles

### gog_object_add_by_role ()

    GogObject *         gog_object_add_by_role              (GogObject *parent,
                                                             GogObjectRole const *role,
                                                             GogObject *child);

Absorb a ref to `child` if it is non-NULL.

`parent` : | GogObject
`role` : | GogObjectRole
`child` : | GogObject
Returns : | `child` or a newly created object with `role`. Callers do _not_ own the reference.

### gog_object_add_by_name ()

    GogObject *         gog_object_add_by_name              (GogObject *parent,
                                                             char const *role,
                                                             GogObject *child);

`parent` : | GogObject
`child` : | optionally null GogObject
Returns : | a newly created child of `parent` in `role`. If `child` is provided, it is assumed to be an unaffiliated object that will be assigned in `role`. On failure return NULL.

### gog_object_can_reorder ()

    void                gog_object_can_reorder              (GogObject const *obj,
                                                             gboolean *inc_ok,
                                                             gboolean *dec_ok);

If `obj` can move forward or backward in its parents child list

`obj` : | GogObject
`inc_ok` : | optionally `NULL` pointer for result.
`dec_ok` : | optionally `NULL` pointer for result.

### gog_object_reorder ()

    GogObject *         gog_object_reorder                  (GogObject const *obj,
                                                             gboolean inc,
                                                             gboolean goto_max);

`obj` : | GogObject
Returns : | the object just before `obj` in the new ordering.

### gog_object_get_position_flags ()

    GogObjectPosition   gog_object_get_position_flags       (GogObject const *obj,
                                                             GogObjectPosition mask);

`obj` : | GogObject
`mask` : | GogObjectPosition
Returns : | `obj`'s position flags, masked by `mask`.

### gog_object_set_position_flags ()

    gboolean            gog_object_set_position_flags       (GogObject *obj,
                                                             GogObjectPosition flags,
                                                             GogObjectPosition mask);

Attempts to set the position flags of `obj` to `flags`.

`obj` : | GogObject
`flags` : | GogObjectPosition
`mask` : | GogObjectPosition
Returns : | TRUE the new flags are permitted.

### gog_object_is_default_position_flags ()

    gboolean            gog_object_is_default_position_flags
                                                            (GogObject const *obj,
                                                             char const *name);

`obj` : |
`name` : |
Returns : |

### gog_object_get_manual_position ()

    void                gog_object_get_manual_position      (GogObject *obj,
                                                             GogViewAllocation *pos);

FIXME

`obj` : | GogObject
`pos` : | GogViewAllocation

### gog_object_set_manual_position ()

    void                gog_object_set_manual_position      (GogObject *obj,
                                                             GogViewAllocation const *pos);

set manual position of given object, in points.

`obj` : | GogObject
`pos` : | GogViewAllocation

### gog_object_get_manual_allocation ()

    GogViewAllocation   gog_object_get_manual_allocation    (GogObject *gobj,
                                                             GogViewAllocation const *parent_allocation,
                                                             GogViewRequisition const *requisition);

`gobj` : | GogObject
`parent_allocation` : | GogViewAllocation
`requisition` : | GogViewRequisition
Returns : | manual allocation of a GogObject given its parent allocation and its size request.

### gog_object_find_role_by_name ()

    GogObjectRole const * gog_object_find_role_by_name      (GogObject const *obj,
                                                             char const *role);

`obj` : |
`role` : |
Returns : |

### gog_object_update ()

    void                gog_object_update                   (GogObject *obj);

`obj` : |

### gog_object_request_update ()

    gboolean            gog_object_request_update           (GogObject *obj);

`obj` : |
Returns : |

### gog_object_emit_changed ()

    void                gog_object_emit_changed             (GogObject *obj,
                                                             gboolean size);

`obj` : |
`size` : |

### gog_object_clear_parent ()

    gboolean            gog_object_clear_parent             (GogObject *obj);

Does _not_ unref the child, which in effect adds a ref by freeing up the ref previously associated with the parent.

`obj` : | GogObject
Returns : | `TRUE` on success.

### gog_object_set_parent ()

    gboolean            gog_object_set_parent               (GogObject *child,
                                                             GogObject *parent,
                                                             GogObjectRole const *role,
                                                             unsigned int id);

Absorbs a ref to `child`

`child` : | GogObject.
`parent` : | GogObject.
`role` : | a static string that can be sent to `parent`::add
`id` : | optionally `NULL`.
Returns : | `TRUE` on success

### gog_object_request_editor_update ()

    void                gog_object_request_editor_update    (GogObject *obj);

Emits a update-editor signal. This signal should be used by object editors in order to refresh their states.

`obj` : | GogObject

### gog_object_document_changed ()

    void                gog_object_document_changed         (GogObject *obj,
                                                             GODoc *doc);

`obj` : |
`doc` : |

### gog_object_is_visible()

    #define	  gog_object_is_visible(obj) (!((GogObject*)obj)->invisible)

`obj` : |

### gog_object_set_invisible ()

    void                gog_object_set_invisible            (GogObject *obj,
                                                             gboolean invisible);

`obj` : | GogObject

### enum GogObjectPosition

    typedef enum {
    	GOG_POSITION_AUTO = 0,
    	GOG_POSITION_N		= 1 << 0, /* can be used with E or W */
    	GOG_POSITION_S		= 1 << 1, /* can be used with E or W */
    	GOG_POSITION_E		= 1 << 2,
    	GOG_POSITION_W		= 1 << 3,
    	GOG_POSITION_COMPASS = 0x0f,

    	/* modifiers for compass */
    	GOG_POSITION_ALIGN_FILL	  = 0 << 4,
    	GOG_POSITION_ALIGN_START  = 1 << 4,
    	GOG_POSITION_ALIGN_END	  = 2 << 4,
    	GOG_POSITION_ALIGN_CENTER = 3 << 4,
    	GOG_POSITION_ALIGNMENT	  = 0x30,

    	GOG_POSITION_SPECIAL = 1 << 6,

    	GOG_POSITION_MANUAL	  = 1 << 7,
    	GOG_POSITION_MANUAL_X_ABS = 1 << 8, /* abs vs relative pos */
    	GOG_POSITION_MANUAL_Y_ABS = 1 << 9,
    	GOG_POSITION_MANUAL_X_END = 1 << 10, /* pos relative to start or end */
    	GOG_POSITION_MANUAL_Y_END = 1 << 11,

    	/* modifiers for manual */
    	GOG_POSITION_ANCHOR_NW       = 0 << 12,
    	GOG_POSITION_ANCHOR_N	     = 1 << 12,
    	GOG_POSITION_ANCHOR_NE	     = 2 << 12,
    	GOG_POSITION_ANCHOR_E        = 3 << 12,
    	GOG_POSITION_ANCHOR_SE       = 4 << 12,
    	GOG_POSITION_ANCHOR_S        = 5 << 12,
    	GOG_POSITION_ANCHOR_SW       = 6 << 12,
    	GOG_POSITION_ANCHOR_W        = 7 << 12,
    	GOG_POSITION_ANCHOR_CENTER   = 8 << 12,
    	GOG_POSITION_ANCHOR          = 0xf000,

    	GOG_POSITION_ANY_MANUAL      = 0xff80,

    	GOG_POSITION_PADDING	     = 1 << 16
    } GogObjectPosition;

### GOG_POSITION_IS_PADDING()

    #define GOG_POSITION_IS_PADDING(pos) (((pos) & GOG_POSITION_PADDING)&&(!((pos) & GOG_POSITION_MANUAL)))

`pos` : |

### GOG_POSITION_IS_SPECIAL()

    #define GOG_POSITION_IS_SPECIAL(pos) (((pos) & GOG_POSITION_SPECIAL)&&(!((pos) & GOG_POSITION_MANUAL)))

`pos` : |

### enum GogDataType

    typedef enum {
    	GOG_DATA_SCALAR,
    	GOG_DATA_VECTOR,
    	GOG_DATA_MATRIX
    } GogDataType;

### enum GogDimType

    typedef enum {
    	GOG_DIM_INVALID = -1,
    	GOG_DIM_LABEL = 0,
    	GOG_DIM_INDEX,
    	GOG_DIM_VALUE,
    	GOG_DIM_MATRIX,
    	GOG_DIM_TYPES
    } GogDimType;

### enum GogMSDimType

    typedef enum {
    	GOG_MS_DIM_LABELS = 0,
    	GOG_MS_DIM_VALUES = 1,
    	GOG_MS_DIM_CATEGORIES = 2,
    	GOG_MS_DIM_BUBBLES = 3, /* undocumented */
    	GOG_MS_DIM_TYPES,
    	GOG_MS_DIM_ERR_plus1, /* we made it up */
    	GOG_MS_DIM_ERR_minus1, /* we made it up */
    	GOG_MS_DIM_ERR_plus2, /* we made it up */
    	GOG_MS_DIM_ERR_minus2, /* we made it up */
    	GOG_MS_DIM_START, /* we made it up for dropbars*/
    	GOG_MS_DIM_END, /* we made it up for dropbars */
    	GOG_MS_DIM_LOW, /* we made it up for hi-lo*/
    	GOG_MS_DIM_HIGH, /* we made it up for hi-lo */
    	GOG_MS_DIM_EXTRA1, /* we made it up for other uses */
    	GOG_MS_DIM_EXTRA2 /* we made it up for other uses */
    } GogMSDimType;

### GogEnumFunc ()

    void                (*GogEnumFunc)                      (unsigned  i,
                                                             gpointer style,
                                                             char const *name,
                                                             gpointer data);

`i` : |
`style` : |
`name` : |
`data` : |

## Property Details

### The `"alignment"` property

      "alignment"                gchar*                : Read / Write

Alignment flag.

Default value: "fill"

### The `"anchor"` property

      "anchor"                   gchar*                : Read / Write

Anchor for manual position.

Default value: "top-left"

### The `"compass"` property

      "compass"                  gchar*                : Read / Write

Compass auto position flags.

Default value: "top"

### The `"id"` property

      "id"                       guint                 : Read / Write

Object numerical ID.

Allowed values: <= G_MAXLONG

Default value: 0

### The `"invisible"` property

      "invisible"                gboolean              : Read / Write

Should the object be hidden.

Default value: FALSE

### The `"is-position-manual"` property

      "is-position-manual"       gboolean              : Read / Write

Is position manual.

Default value: FALSE

### The `"position"` property

      "position"                 gchar*                : Read / Write

Position and size of object, in percentage of parent size.

Default value: "0 0 1 1"

## Signal Details

### The `"changed"` signal

    void                user_function                      (GogObject *gogobject,
                                                            gboolean   arg1,
                                                            gpointer   user_data)      : Run Last

`gogobject` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"child-added"` signal

    void                user_function                      (GogObject *object,
                                                            GObject   *child,
                                                            gpointer   user_data)      : Run Last

The ::child-added signal is emitted AFTER the child has been added and AFTER the parent-changed signal has been called for it.

`object` : | the object on which the signal is emitted
`child` : | The new GogObject whose parent is `object`
`user_data` : | user data set when the signal handler was connected.

### The `"child-name-changed"` signal

    void                user_function                      (GogObject *gogobject,
                                                            GObject   *arg1,
                                                            gpointer   user_data)      : Run Last

`gogobject` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"child-removed"` signal

    void                user_function                      (GogObject *object,
                                                            GObject   *child,
                                                            gpointer   user_data)      : Run Last

The ::child-removed signal is emitted BEFORE the child has been added and BEFORE the parent-changed signal has been called for it.

`object` : | the object on which the signal is emitted
`child` : | The new GogObject whose parent is `object`
`user_data` : | user data set when the signal handler was connected.

### The `"children-reordered"` signal

    void                user_function                      (GogObject *gogobject,
                                                            gpointer   user_data)      : Run Last

`gogobject` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"name-changed"` signal

    void                user_function                      (GogObject *gogobject,
                                                            gpointer   user_data)      : Run Last

`gogobject` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"update-editor"` signal

    void                user_function                      (GogObject *gogobject,
                                                            gpointer   user_data)      : Run Last

`gogobject` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.