GOffice Reference Manual: GogObject

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

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

Returns

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

Returns

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

Returns

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

Returns

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

Returns

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.
role	a static string that can be sent to `parent` ::add
id	optionally `NULL`.

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_MAXINT

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)

Parameters

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

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)

Parameters

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

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)

Parameters

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

Flags: Run Last

The `“name-changed”` signal

void
user_function (GogObject *gogobject,
               gpointer   user_data)

Parameters

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

Flags: Run Last

The `“update-editor”` signal

void
user_function (GogObject *gogobject,
               gpointer   user_data)

Parameters

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

Flags: Run Last