GogObject

GogObject — Base class for all objects of graph model

Synopsis


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

                    GogObject;
#define             GOG_PARAM_PERSISTENT
#define             GOG_PARAM_FORCE_SAVE
void                (*GogDataDuplicator)                (GogDataset const *src,
                                                         GogDataset *dst);
enum                GogObjectNamingConv;
                    GogObjectRole;
GogObject*          gog_object_dup                      (GogObject const *src,
                                                         GogObject *new_parent,
                                                         GogDataDuplicator datadup);
GogObject*          gog_object_get_parent               (GogObject const *obj);
GogObject*          gog_object_get_parent_typed         (GogObject const *obj,
                                                         GType t);
GogGraph*           gog_object_get_graph                (GogObject const *obj);
GogTheme*           gog_object_get_theme                (GogObject const *obj);
unsigned            gog_object_get_id                   (GogObject const *obj);
charconst  *        gog_object_get_name                 (GogObject const *obj);
void                gog_object_set_name                 (GogObject *obj,
                                                         char *name,
                                                         GError **err);
GSList*             gog_object_get_children             (GogObject const *obj,
                                                         GogObjectRole const *filter);
GogObject*          gog_object_get_child_by_role        (GogObject const *obj,
                                                         GogObjectRole const *role);
GogObject*          gog_object_get_child_by_name        (GogObject const *obj,
                                                         char const *name);
gpointer            gog_object_get_editor               (GogObject *obj,
                                                         GogDataAllocator *dalloc,
                                                         GOCmdContext *cc);
GogView*            gog_object_new_view                 (GogObject const *obj,
                                                         GogView *parent);
gboolean            gog_object_is_deletable             (GogObject const *obj);
GSList*             gog_object_possible_additions       (GogObject const *parent);
void                gog_object_register_roles           (GogObjectClass *klass,
                                                         GogObjectRole const *roles,
                                                         unsigned int n_roles);
GogObject*          gog_object_add_by_role              (GogObject *parent,
                                                         GogObjectRole const *role,
                                                         GogObject *child);
GogObject*          gog_object_add_by_name              (GogObject *parent,
                                                         char const *role,
                                                         GogObject *child);
void                gog_object_can_reorder              (GogObject const *obj,
                                                         gboolean *inc_ok,
                                                         gboolean *dec_ok);
GogObject*          gog_object_reorder                  (GogObject const *obj,
                                                         gboolean inc,
                                                         gboolean goto_max);
GogObjectPosition   gog_object_get_position_flags       (GogObject const *obj,
                                                         GogObjectPosition mask);
gboolean            gog_object_set_position_flags       (GogObject *obj,
                                                         GogObjectPosition flags,
                                                         GogObjectPosition mask);
gboolean            gog_object_is_default_position_flags
                                                        (GogObject const *obj,
                                                         char const *name);
void                gog_object_get_manual_position      (GogObject *obj,
                                                         GogViewAllocation *pos);
void                gog_object_set_manual_position      (GogObject *obj,
                                                         GogViewAllocation const *pos);
GogViewAllocation   gog_object_get_manual_allocation    (GogObject *gobj,
                                                         GogViewAllocation const *parent_allocation,
                                                         GogViewRequisition const *requisition);
GogObjectRoleconst * gog_object_find_role_by_name       (GogObject const *obj,
                                                         char const *role);
void                gog_object_update                   (GogObject *obj);
gboolean            gog_object_request_update           (GogObject *obj);
void                gog_object_emit_changed             (GogObject *obj,
                                                         gboolean size);
gboolean            gog_object_clear_parent             (GogObject *obj);
gboolean            gog_object_set_parent               (GogObject *child,
                                                         GogObject *parent,
                                                         GogObjectRole const *role,
                                                         unsigned int id);
void                gog_object_request_editor_update    (GogObject *obj);

Object Hierarchy

  GObject
   +----GogObject
         +----GogStyledObject
         +----GogPlot

Properties

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

Signals

  "changed"                                        : Run Last
  "child-added"                                    : Run Last
  "child-name-changed"                             : Run Last
  "child-removed"                                  : Run Last
  "children-reordered"                             : Run Last
  "name-changed"                                   : Run Last
  "update-editor"                                  : Run Last

Description

Details

GogObject

typedef struct _GogObject GogObject;


GOG_PARAM_PERSISTENT

#define GOG_PARAM_PERSISTENT	(1 << (G_PARAM_USER_SHIFT+0))


GOG_PARAM_FORCE_SAVE

#define GOG_PARAM_FORCE_SAVE	(1 << (G_PARAM_USER_SHIFT+1))	/* even if the value == default */


GogDataDuplicator ()

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

src :

dst :


enum GogObjectNamingConv

typedef enum {
	GOG_OBJECT_NAME_BY_ROLE	 = 1,
	GOG_OBJECT_NAME_BY_TYPE  = 2,
	GOG_OBJECT_NAME_MANUALLY = 3
} GogObjectNamingConv;


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;
		float		f;
		gpointer	p;
	} user;
} GogObjectRole;


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.

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

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

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

obj :

const * GogObject

Returns :

the parent graph.

gog_object_get_theme ()

GogTheme*           gog_object_get_theme                (GogObject const *obj);

obj :

Returns :


gog_object_get_id ()

unsigned            gog_object_get_id                   (GogObject const *obj);

obj :

Returns :


gog_object_get_name ()

charconst  *        gog_object_get_name                 (GogObject const *obj);

No need to free the result

obj :

a GogObject

Returns :


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

obj :

GogObject

name :

err :

GError

gog_object_get_children ()

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

The list needs to be Freed

obj :

a GogObject

filter :

an optional GogObjectRole to use as a filter

Returns :


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.

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

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.

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.

obj :

a GogObject

parent :

parent view

Returns :

a new GogView

gog_object_is_deletable ()

gboolean            gog_object_is_deletable             (GogObject const *obj);

obj :

a GogObject

Returns :

TRUE if obj can be deleted.

gog_object_possible_additions ()

GSList*             gog_object_possible_additions       (GogObject const *parent);

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

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.

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

parent :

GogObject

role :

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

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

obj :

GogObject

inc :

goto_max :

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

Retrieve position flags of GogObject obj, masked by mask.

obj :

GogObject

mask :

GogObjectPosition

Returns :


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.

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

obj :

name :

Returns :


gog_object_get_manual_position ()

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

FIXME


gog_object_set_manual_position ()

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

set manual position of given object, in points.


gog_object_get_manual_allocation ()

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

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

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

obj :

role :

Returns :


gog_object_update ()

void                gog_object_update                   (GogObject *obj);

obj :


gog_object_request_update ()

gboolean            gog_object_request_update           (GogObject *obj);

obj :

Returns :


gog_object_emit_changed ()

void                gog_object_emit_changed             (GogObject *obj,
                                                         gboolean size);

obj :

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.

obj :

GogObject

Returns :


gog_object_set_parent ()

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

Absorbs a ref to child

child :

GogObject.

parent :

GogObject.

role :

a static string that can be sent to parent::add

id :

optionally NULL.

Returns :


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.

obj :

GogObject

Property Details

The "alignment" property

  "alignment"                gchar*                : Read / Write

Alignment flag.

Default value: "fill"


The "anchor" property

  "anchor"                   gchar*                : Read / Write

Anchor for manual position.

Default value: "top-left"


The "compass" property

  "compass"                  gchar*                : Read / Write

Compass auto position flags.

Default value: "top"


The "id" property

  "id"                       guint                 : Read / Write

Object numerical ID.

Allowed values: <= G_MAXINT

Default value: 0


The "invisible" property

  "invisible"                gboolean              : Read / Write

Should the object be hidden.

Default value: FALSE


The "is-position-manual" property

  "is-position-manual"       gboolean              : Read / Write

Is position manual.

Default value: FALSE


The "position" property

  "position"                 gchar*                : Read / Write

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

Default value: "0 0 1 1"

Signal Details

The "changed" signal

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

gogobject :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "child-added" signal

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

gogobject :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "child-name-changed" signal

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

gogobject :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "child-removed" signal

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

gogobject :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "children-reordered" signal

void                user_function                      (GogObject *gogobject,
                                                        gpointer   user_data)      : Run Last

gogobject :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "name-changed" signal

void                user_function                      (GogObject *gogobject,
                                                        gpointer   user_data)      : Run Last

gogobject :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "update-editor" signal

void                user_function                      (GogObject *gogobject,
                                                        gpointer   user_data)      : Run Last

gogobject :

the object which received the signal.

user_data :

user data set when the signal handler was connected.