GogObject: Goffice Reference Manual

GogObject

GogObject — The base class for graph objects.

Functions

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

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

	GogObject
	GogObjectClass
#define	GOG_PARAM_FORCE_SAVE
#define	GOG_PARAM_POSITION
enum	GogObjectNamingConv
	GogObjectRole
enum	GogObjectPosition
enum	GogDataType
enum	GogDimType
enum	GogMSDimType

Object Hierarchy

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

Includes

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

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

Returns

FIXME

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.

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 .

gog_object_get_graph ()

GogGraph *
gog_object_get_graph (GogObject const *obj);

Parameters

obj

const * GogObject

Returns

the parent graph.

gog_object_get_theme ()

GogTheme *
gog_object_get_theme (GogObject const *obj);

gog_object_get_id ()

unsigned
gog_object_get_id (GogObject const *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_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`
err	GError

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

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 .

Parameters

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

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.

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

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

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

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

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

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.

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

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

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

gog_object_get_manual_position ()

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

FIXME

Parameters

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.

Parameters

obj	GogObject
pos	GogViewAllocation

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_find_role_by_name ()

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

gog_object_update ()

void
gog_object_update (GogObject *obj);

gog_object_request_update ()

gboolean
gog_object_request_update (GogObject *obj);

gog_object_emit_changed ()

void
gog_object_emit_changed (GogObject *obj,
                         gboolean 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.

Parameters

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

Parameters

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.

Parameters

obj

GogObject

gog_object_document_changed ()

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

gog_object_is_visible()

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

gog_object_set_invisible ()

void
gog_object_set_invisible (GogObject *obj,
                          gboolean invisible);

Parameters

obj

GogObject

GOG_POSITION_IS_PADDING()

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

GOG_POSITION_IS_SPECIAL()

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

GogEnumFunc ()

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

Types and Values

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

enum GogObjectNamingConv

Members

GOG_OBJECT_NAME_BY_ROLE
GOG_OBJECT_NAME_BY_TYPE
GOG_OBJECT_NAME_MANUALLY

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;

enum GogObjectPosition

Members

GOG_POSITION_AUTO
GOG_POSITION_N
GOG_POSITION_S
GOG_POSITION_E
GOG_POSITION_W
GOG_POSITION_COMPASS
GOG_POSITION_ALIGN_FILL
GOG_POSITION_ALIGN_START
GOG_POSITION_ALIGN_END
GOG_POSITION_ALIGN_CENTER
GOG_POSITION_ALIGNMENT
GOG_POSITION_SPECIAL
GOG_POSITION_MANUAL
GOG_POSITION_MANUAL_X_ABS
GOG_POSITION_MANUAL_Y_ABS
GOG_POSITION_MANUAL_X_END
GOG_POSITION_MANUAL_Y_END
GOG_POSITION_ANCHOR_NW
GOG_POSITION_ANCHOR_N
GOG_POSITION_ANCHOR_NE
GOG_POSITION_ANCHOR_E
GOG_POSITION_ANCHOR_SE
GOG_POSITION_ANCHOR_S
GOG_POSITION_ANCHOR_SW
GOG_POSITION_ANCHOR_W
GOG_POSITION_ANCHOR_CENTER
GOG_POSITION_ANCHOR
GOG_POSITION_ANY_MANUAL
GOG_POSITION_PADDING

enum GogDataType

Members

GOG_DATA_SCALAR
GOG_DATA_VECTOR
GOG_DATA_MATRIX

enum GogDimType

Members

GOG_DIM_INVALID
GOG_DIM_LABEL
GOG_DIM_INDEX
GOG_DIM_VALUE
GOG_DIM_MATRIX
GOG_DIM_TYPES

enum GogMSDimType

Members

GOG_MS_DIM_LABELS
GOG_MS_DIM_VALUES
GOG_MS_DIM_CATEGORIES
GOG_MS_DIM_BUBBLES
GOG_MS_DIM_TYPES
GOG_MS_DIM_ERR_plus1
GOG_MS_DIM_ERR_minus1
GOG_MS_DIM_ERR_plus2
GOG_MS_DIM_ERR_minus2
GOG_MS_DIM_START
GOG_MS_DIM_END
GOG_MS_DIM_LOW
GOG_MS_DIM_HIGH
GOG_MS_DIM_EXTRA1
GOG_MS_DIM_EXTRA2

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