GogObject

GogObject — The base class for graph objects.

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

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


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


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

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;

	unsigned int use_parent_as_proxy : 1; /* when we change, pretend it was our parent */
	unsigned int roles_allocated: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);
} GogObjectClass;

Members

GObjectClass base;

base class.

 

GHashTable *roles;

roles for the class.

 

GType view_type;

view type.

 

unsigned int use_parent_as_proxy : 1;

   

unsigned int roles_allocated :1;

   

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

implements the "changed" signal.

 

name_changed ()

implements the "name-changed" signal.

 

possible_additions_changed ()

implements the "possible-additions-changed" signal.

 

child_added ()

implements the "child-added" signal.

 

child_removed ()

implements the "child-removed" signal.

 

child_name_changed ()

implements the "child-name-changed" signal.

 

children_reordered ()

implements the "children-reordered" signal.

 

update_editor ()

implements the "update-editor" signal.

 

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

 

unsigned    int priority;

   

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

expands in the horizontal direction.

 

GOG_POSITION_VEXPAND

expands in the vertical direction.

 

GOG_POSITION_EXPAND

expands in either direction.

 

Property Details

The “alignment” property

  “alignment”                gchar *

Alignment flag.

Owner: GogObject

Flags: Read / Write

Default value: "fill"


The “anchor” property

  “anchor”                   gchar *

Anchor for manual position.

Owner: GogObject

Flags: Read / Write

Default value: "top-left"


The “compass” property

  “compass”                  gchar *

Compass auto position flags.

Owner: GogObject

Flags: Read / Write

Default value: "top"


The “id” property

  “id”                       guint

Object numerical ID.

Owner: GogObject

Flags: Read / Write

Allowed values: <= G_MAXINT

Default value: 0


The “invisible” property

  “invisible”                gboolean

Should the object be hidden.

Owner: GogObject

Flags: Read / Write

Default value: FALSE


The “is-position-manual” property

  “is-position-manual”       gboolean

Is position manual.

Owner: GogObject

Flags: Read / Write

Default value: FALSE


The “manual-size” property

  “manual-size”              gchar *

Whether the height or width are manually set.

Owner: GogObject

Flags: Read / Write

Default value: "none"


The “position” property

  “position”                 gchar *

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

Owner: GogObject

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