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

Types and Values

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

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


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

See Also

GogGraph