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);
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);
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);
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_register_roles       (GogObjectClass *klass,
                                             GogObjectRole const *roles,
                                             unsigned n_roles );
void        gog_object_request_editor_update
                                            (GogObject *obj);


Object Hierarchy


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

Properties


  "alignment"            gchararray            : Read / Write
  "anchor"               gchararray            : Read / Write
  "compass"              gchararray            : Read / Write
  "id"                   guint                 : Read / Write
  "is-position-manual"   gboolean              : Read / Write
  "position"             gchararray            : Read / Write

Signals


"changed"   void        user_function      (GogObject *gogobject,
                                            gboolean   arg1,
                                            gpointer   user_data)      : Run last
"child-added"
            void        user_function      (GogObject *gogobject,
                                            GObject   *arg1,
                                            gpointer   user_data)      : Run last
"child-name-changed"
            void        user_function      (GogObject *gogobject,
                                            GObject   *arg1,
                                            gpointer   user_data)      : Run last
"child-removed"
            void        user_function      (GogObject *gogobject,
                                            GObject   *arg1,
                                            gpointer   user_data)      : Run last
"children-reordered"
            void        user_function      (GogObject *gogobject,
                                            gpointer   user_data)      : Run last
"name-changed"
            void        user_function      (GogObject *gogobject,
                                            gpointer   user_data)      : Run last
"update-editor"
            void        user_function      (GogObject *gogobject,
                                            gpointer   user_data)      : 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 handle a unique child

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

Can the specified obj be deleted ?

obj : a GogObject
Returns :

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

GogObject*  gog_object_add_by_role          (GogObject *parent,
                                             GogObjectRole const *role,
                                             GogObject *child);

parent :
role :
child :
Returns :

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 : possibly NULL pointer.
dec_ok : possibly NULL pointer.

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

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

FIXME

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.

obj : GogObject
pos : GogViewAllocation

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

void        gog_object_register_roles       (GogObjectClass *klass,
                                             GogObjectRole const *roles,
                                             unsigned n_roles );

klass :
roles :
Param3 :

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"            gchararray            : Read / Write

Alignment flag.

Default value: "fill"


The "anchor" property

  "anchor"               gchararray            : Read / Write

Anchor for manual position.

Default value: "top-left"


The "compass" property

  "compass"              gchararray            : Read / Write

Compass auto position flags.

Default value: "top"


The "id" property

  "id"                   guint                 : Read / Write

Object ID.

Allowed values: <= G_MAXINT

Default value: 0


The "is-position-manual" property

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

Is position manual.

Default value: FALSE


The "position" property

  "position"             gchararray            : 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.