GogObject: GOffice Reference Manual

## GogObject GogObject — The base class for graph objects. |

## Functions

void | (*GogDataDuplicator) ()
GogObject * | gog_object_add_by_name ()
GogObject * | gog_object_add_by_role ()
void | gog_object_can_reorder ()
gboolean | gog_object_clear_parent ()
void | gog_object_document_changed ()
GogObject * | gog_object_dup ()
void | gog_object_emit_changed ()
GogObjectRole const * | gog_object_find_role_by_name ()
GogObject * | gog_object_get_child_by_name ()
GogObject * | gog_object_get_child_by_role ()
GSList * | gog_object_get_children ()
gpointer | gog_object_get_editor ()
GogGraph * | gog_object_get_graph ()
unsigned | gog_object_get_id ()
GogViewAllocation | gog_object_get_manual_allocation ()
void | gog_object_get_manual_position ()
GogManualSizeMode | gog_object_get_manual_size_mode ()
char const * | gog_object_get_name ()
GogObject * | gog_object_get_parent ()
GogObject * | gog_object_get_parent_typed ()
GogObjectPosition | gog_object_get_position_flags ()
GogTheme * | gog_object_get_theme ()
gboolean | gog_object_is_default_position_flags ()
gboolean | gog_object_is_deletable ()
#define | gog_object_is_visible()
GogView * | gog_object_new_view ()
GSList * | gog_object_possible_additions ()
void | gog_object_register_roles ()
GogObject * | gog_object_reorder ()
void | gog_object_request_editor_update ()
gboolean | gog_object_request_update ()
void | gog_object_set_invisible ()
void | gog_object_set_manual_position ()
void | gog_object_set_name ()
gboolean | gog_object_set_parent ()
gboolean | gog_object_set_position_flags ()
void | gog_object_update ()

## Properties

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

## Signals

void | changed | Run Last
void | child-added | Run Last
void | child-name-changed | Run Last
void | child-removed | Run Last
void | children-reordered | Run Last
void | name-changed | Run Last
void | update-editor | Run Last

## Types and Values

#define | GOG_PARAM_FORCE_SAVE
#define | GOG_PARAM_POSITION
enum | GogManualSizeMode
| GogObject
| GogObjectClass
enum | GogObjectNamingConv
| GogObjectRole
enum | GogObjectPosition

## Object Hierarchy

        GBoxed
        ╰── GogObjectRole
        GObject
        ╰── GogObject
            ├── Gog3DBox
            ├── GogStyledObject
            ╰── GogPlot

## Description

Abstract base class that objects in the graph hierarchy are based on. This class handles manipulation of the object hierarchy, and positioning of objects in the graph.

Every object has a name that is unique in the graph. It can have a parent and a list of children in specific roles (see GogObjectRole). There can generally be several children in each role.

If built with GTK+ support, each object also knows how to populate a widget that allows one to manipulate the attributes of that object. This can be used by GOEditor to present a widget that allows manipulation of the whole graph.

## Functions

### GogDataDuplicator ()

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

### gog_object_add_by_name ()

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

#### Parameters

parent | GogObject |
child | optionally null GogObject. | [transfer full][allow-none]

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

[transfer none]

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

#### Parameters

parent | GogObject |
role | GogObjectRole |
child | GogObject. | [transfer full][allow-none]

#### Returns

`child` or a newly created object with `role` .

[transfer none]

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

#### Parameters

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

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

#### Parameters

obj | GogObject |

#### Returns

`TRUE` on success.

### gog_object_document_changed ()

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

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

#### Parameters

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). | [scope call]

#### Returns

the duplicated object.

[transfer full]

### gog_object_emit_changed ()

    void
    gog_object_emit_changed (GogObject *obj,
                             gboolean size);

### gog_object_find_role_by_name ()

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

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

#### Parameters

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.

[transfer none]

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

#### Parameters

obj | a GogObject |
role | a GogObjectRole to use as a filter |

#### Returns

`NULL` and spews an error if there is more than one.

[transfer none]

### gog_object_get_children ()

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

#### Parameters

obj | a GogObject |
filter | an optional GogObjectRole to use as a filter |

#### Returns

list of `obj` 's Children. Caller must free the list, but not the children.

[element-type GogObject][transfer container]

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

#### Parameters

obj | a GogObject |
dalloc | a GogDataAllocator |
cc | a GOCmdContext |

#### Returns

a GtkNotebook widget.

[transfer full]

### gog_object_get_graph ()

    GogGraph *
    gog_object_get_graph (GogObject const *obj);

#### Parameters

obj | const * GogObject |

#### Returns

the parent graph.

[transfer none]

### gog_object_get_id ()

    unsigned
    gog_object_get_id (GogObject const *obj);

### gog_object_get_manual_allocation ()

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

#### Parameters

gobj | GogObject |
parent_allocation | GogViewAllocation |
requisition | GogViewRequisition |

#### Returns

manual allocation of a GogObject given its parent allocation and its size request.

### gog_object_get_manual_position ()

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

FIXME

#### Parameters

obj | GogObject |
pos | GogViewAllocation |

### gog_object_get_manual_size_mode ()

    GogManualSizeMode
    gog_object_get_manual_size_mode (GogObject *obj);

### gog_object_get_name ()

    char const  *
    gog_object_get_name (GogObject const *obj);

No need to free the result

#### Parameters

obj | a GogObject |

#### Returns

a name.

### gog_object_get_parent ()

    GogObject *
    gog_object_get_parent (GogObject const *obj);

#### Parameters

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.

[transfer none]

### gog_object_get_parent_typed ()

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

#### Parameters

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` .

[transfer none]

### gog_object_get_position_flags ()

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

#### Parameters

obj | GogObject |
mask | GogObjectPosition |

#### Returns

`obj` 's position flags, masked by `mask` .

### gog_object_get_theme ()

    GogTheme *
    gog_object_get_theme (GogObject const *obj);

#### Parameters

obj | const * GogObject |

#### Returns

the parent graph theme.

[transfer none]

### gog_object_is_default_position_flags ()

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

### gog_object_is_deletable ()

    gboolean
    gog_object_is_deletable (GogObject const *obj);

#### Parameters

obj | a GogObject |

#### Returns

`TRUE` if `obj` can be deleted.

### gog_object_is_visible()

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

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

#### Parameters

obj | a GogObject |
parent | parent view |

#### Returns

a new GogView.

[transfer full]

### gog_object_possible_additions ()

    GSList *
    gog_object_possible_additions (GogObject const *parent);

#### Parameters

parent | a GogObject |

#### Returns

a list of GogObjectRoles that could be added. The resulting list needs to be freed.

[element-type GogObjectRole][transfer container]

### gog_object_register_roles ()

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

#### Parameters

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

### gog_object_reorder ()

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

#### Parameters

obj | GogObject |

#### Returns

the object just before `obj` in the new ordering.

[transfer none]

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

#### Parameters

obj | GogObject |

### gog_object_request_update ()

    gboolean
    gog_object_request_update (GogObject *obj);

### gog_object_set_invisible ()

    void
    gog_object_set_invisible (GogObject *obj,
                              gboolean invisible);

#### Parameters

obj | GogObject |

### gog_object_set_manual_position ()

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

set manual position of given object, in points.

#### Parameters

obj | GogObject |
pos | GogViewAllocation |

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

#### Parameters

obj | GogObject |
name | The new name for `obj` . | [transfer full]
err | GError |

### gog_object_set_parent ()

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

Absorbs a ref to `child`

#### Parameters

child | GogObject. | [transfer full]
parent | GogObject. |
id | optionally `NULL`. |
role | a static string that can be sent to `parent` ::add |

#### Returns

`TRUE` on success

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

#### Parameters

obj | GogObject |
flags | GogObjectPosition |
mask | GogObjectPosition |

#### Returns

TRUE the new flags are permitted.

### gog_object_update ()

    void
    gog_object_update (GogObject *obj);

## Types and Values

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

### enum GogManualSizeMode

#### Members

GOG_MANUAL_SIZE_AUTO | auto size, can't be changed. |
GOG_MANUAL_SIZE_WIDTH | the width can be changed. |
GOG_MANUAL_SIZE_HEIGHT | the height can be changed. |
GOG_MANUAL_SIZE_FULL | both height and width can be changed. |

### 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);
    	GogManualSizeMode (*get_manual_size_mode) (GogObject *obj);

    	/* 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);
    	void (*extra_signal1)	   (GogObject *view);
    	void (*extra_signal2)	   (GogObject *view);
    } GogObjectClass;

#### Members

GObjectClass `base`; |  |
GHashTable *`roles`; | roles for the class. |
GType `view_type`; | view type. |
`update` () | updates the object. |
`parent_changed` () | called when parent changed. |
`type_name` () | gets the type public name. |
`populate_editor` () | populates the editor. |
`document_changed` () | the document changed. |
`get_manual_size_mode` () | resize mode. |
`changed` () |  |
`name_changed` () |  |
`possible_additions_changed` () |  |
`child_added` () |  |
`child_removed` () |  |
`child_name_changed` () |  |
`children_reordered` () |  |
`update_editor` () |  |
`extra_signal1` () |  |
`extra_signal2` () |  |

### enum GogObjectNamingConv

#### Members

GOG_OBJECT_NAME_BY_ROLE | named built from role. |
GOG_OBJECT_NAME_BY_TYPE | named built from type. |
GOG_OBJECT_NAME_MANUALLY | custom name. |

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

Describes allowable children for a GogObject.

#### Members

char const *`id`; | id for persistence. |
char const *`is_a_typename`; | type name. |
guint32 `allowable_positions`; | allowed positions inside parent. |
GogObjectPosition `default_position`; | default position. |
GogObjectNamingConv `naming_conv`; | naming convention. |
`can_add` () | return `TRUE` if a new child can be added. |
`can_remove` () | return `TRUE` if the child can be removed. |
`allocate` () | optional allocator, `g_object_new()` is used if `NULL`. |
`post_add` () | called after adding the child. |
`pre_remove` () | called before removing the child. |
`post_remove` () | called after removing the child. |

### enum GogObjectPosition

#### Members

GOG_POSITION_AUTO | automatic. |
GOG_POSITION_N | north, might be combined with east or west. |
GOG_POSITION_S | south, might be combined with east or west. |
GOG_POSITION_E | east. |
GOG_POSITION_W | west. |
GOG_POSITION_COMPASS | mask of the four previous positions. |
GOG_POSITION_ALIGN_FILL | fills. |
GOG_POSITION_ALIGN_START | start. |
GOG_POSITION_ALIGN_END | end. |
GOG_POSITION_ALIGN_CENTER | centered. |
GOG_POSITION_ALIGNMENT | mask for start or end. |
GOG_POSITION_SPECIAL | special. |
GOG_POSITION_MANUAL | manual. |
GOG_POSITION_MANUAL_X_ABS | whether the x position is absolute or relative. |
GOG_POSITION_MANUAL_Y_ABS | whether the y position is absolute or relative. |
GOG_POSITION_MANUAL_X_END | x position relative to start or end. |
GOG_POSITION_MANUAL_Y_END | y position relative to start or end. |
GOG_POSITION_ANCHOR_NW | anchored north-west. |
GOG_POSITION_ANCHOR_N | anchored north. |
GOG_POSITION_ANCHOR_NE | anchored north-east. |
GOG_POSITION_ANCHOR_E | anchored east. |
GOG_POSITION_ANCHOR_SE | anchored south-east. |
GOG_POSITION_ANCHOR_S | anchored south. |
GOG_POSITION_ANCHOR_SW | anchored south-west. |
GOG_POSITION_ANCHOR_W | anchored west. |
GOG_POSITION_ANCHOR_CENTER | anchored at center. |
GOG_POSITION_ANCHOR | mask for anchors. |
GOG_POSITION_ANY_MANUAL | mask for all manual positions |
GOG_POSITION_PADDING | padding. |
GOG_POSITION_MANUAL_W | relative width. |
GOG_POSITION_MANUAL_W_ABS | absolute width. |
GOG_POSITION_MANUAL_H | relative height. |
GOG_POSITION_MANUAL_H_ABS | absolute height. |
GOG_POSITION_ANY_MANUAL_SIZE | mask for manual sizes. |
GOG_POSITION_HEXPAND |  |
GOG_POSITION_VEXPAND |  |
GOG_POSITION_EXPAND |  |

## Property Details

### The `“alignment”` property

      “alignment”                gchar *

Alignment flag.

Flags: Read / Write

Default value: "fill"

### The `“anchor”` property

      “anchor”                   gchar *

Anchor for manual position.

Flags: Read / Write

Default value: "top-left"

### The `“compass”` property

      “compass”                  gchar *

Compass auto position flags.

Flags: Read / Write

Default value: "top"

### The `“id”` property

      “id”                       guint

Object numerical ID.

Flags: Read / Write

Allowed values: <= G_MAXLONG

Default value: 0

### The `“invisible”` property

      “invisible”                gboolean

Should the object be hidden.

Flags: Read / Write

Default value: FALSE

### The `“is-position-manual”` property

      “is-position-manual”       gboolean

Is position manual.

Flags: Read / Write

Default value: FALSE

### The `“manual-size”` property

      “manual-size”              gchar *

Whether the height or width are manually set.

Flags: Read / Write

Default value: "none"

### The `“position”` property

      “position”                 gchar *

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

Flags: Read / Write

Default value: "0 0 1 1"

## Signal Details

### The `“changed”` signal

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

Flags: Run Last

### The `“child-added”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“child-name-changed”` signal

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

Flags: Run Last

### The `“child-removed”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“children-reordered”` signal

    void
    user_function (GogObject *gogobject,
                   gpointer   user_data)

Flags: Run Last

### The `“name-changed”` signal

    void
    user_function (GogObject *gogobject,
                   gpointer   user_data)

Flags: Run Last

### The `“update-editor”` signal

    void
    user_function (GogObject *gogobject,
                   gpointer   user_data)

Flags: Run Last

## See Also

GogGraph