## GogObject

GogObject — Base class for all objects of graph model

## Synopsis

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

                GogObject;
    #define     GOG_PARAM_PERSISTENT
    #define     GOG_PARAM_FORCE_SAVE
    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);
    charconst  * 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);
    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);
    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);
    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);
    GogObjectRoleconst * 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_register_roles       (GogObjectClass *klass,
                                                 GogObjectRole const *roles,
                                                 unsigned n_roles);
    void        gog_object_request_editor_update
                                                (GogObject *obj);

## Object Hierarchy

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

## Properties

      "alignment"            gchararray            : Read / Write
      "anchor"               gchararray            : Read / Write
      "compass"              gchararray            : Read / Write
      "id"                   guint                 : Read / Write
      "is-position-manual"   gboolean              : Read / Write
      "position"             gchararray            : Read / Write

## Signals

    "changed"   void        user_function      (GogObject *gogobject,
                                                gboolean   arg1,
                                                gpointer   user_data)      : Run last
    "child-added"
                void        user_function      (GogObject *gogobject,
                                                GObject   *arg1,
                                                gpointer   user_data)      : Run last
    "child-name-changed"
                void        user_function      (GogObject *gogobject,
                                                GObject   *arg1,
                                                gpointer   user_data)      : Run last
    "child-removed"
                void        user_function      (GogObject *gogobject,
                                                GObject   *arg1,
                                                gpointer   user_data)      : Run last
    "children-reordered"
                void        user_function      (GogObject *gogobject,
                                                gpointer   user_data)      : Run last
    "name-changed"
                void        user_function      (GogObject *gogobject,
                                                gpointer   user_data)      : Run last
    "update-editor"
                void        user_function      (GogObject *gogobject,
                                                gpointer   user_data)      : Run last

## Description

## Details

### GogObject

    typedef struct _GogObject GogObject;

### GOG_PARAM_PERSISTENT

    #define GOG_PARAM_PERSISTENT	(1 << (G_PARAM_USER_SHIFT+0))

### GOG_PARAM_FORCE_SAVE

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

### 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;
    		float		f;
    		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 ()

    charconst  * gog_object_get_name            (GogObject const *obj);

No need to free the result

`obj` : | a GogObject
Returns : |

### 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` : |
`err` : | GError

### gog_object_get_children ()

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

The list needs to be Freed

`obj` : | a GogObject
`filter` : | an optional GogObjectRole to use as a filter
Returns : |

### gog_object_get_child_by_role ()

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

A convenience routine to handle a unique child

`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_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);

Can the specified `obj` be deleted ?

`obj` : | a GogObject
Returns : |

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

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

`parent` : |
`role` : |
`child` : |
Returns : |

### gog_object_add_by_name ()

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

`parent` : | GogObject
`role` : |
`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` : | possibly NULL pointer.
`dec_ok` : | possibly NULL pointer.

### gog_object_reorder ()

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

`obj` : | GogObject
`inc` : |
`goto_max` : |
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);

Retrieve position flags of GogObject `obj`, masked by `mask`.

`obj` : | GogObject
`mask` : | GogObjectPosition
Returns : |

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

    GogObjectRoleconst * 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 : |

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

### gog_object_register_roles ()

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

`klass` : |
`roles` : |
`Param3` : |

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

## Property Details

### The "`alignment`" property

      "alignment"            gchararray            : Read / Write

Alignment flag.

Default value: "fill"

### The "`anchor`" property

      "anchor"               gchararray            : Read / Write

Anchor for manual position.

Default value: "top-left"

### The "`compass`" property

      "compass"              gchararray            : Read / Write

Compass auto position flags.

Default value: "top"

### The "`id`" property

      "id"                   guint                 : Read / Write

Object ID.

Allowed values: <= G_MAXINT

Default value: 0

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

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

Is position manual.

Default value: FALSE

### The "`position`" property

      "position"             gchararray            : 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 *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-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 *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 "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.