Synopsis
#define GOG_PARAM_FORCE_SAVE #define GOG_PARAM_POSITION void (*GogDataDuplicator) (GogDataset const *src
,GogDataset *dst
); enum GogManualSizeMode; GogObject; GogObjectClass; enum GogObjectNamingConv; GogObjectRole; enum GogObjectPosition; GogObject * gog_object_add_by_name (GogObject *parent
,char const *role
,GogObject *child
); GogObject * gog_object_add_by_role (GogObject *parent
,GogObjectRole const *role
,GogObject *child
); void gog_object_can_reorder (GogObject const *obj
,gboolean *inc_ok
,gboolean *dec_ok
); gboolean gog_object_clear_parent (GogObject *obj
); void gog_object_document_changed (GogObject *obj
,GODoc *doc
); GogObject * gog_object_dup (GogObject const *src
,GogObject *new_parent
,GogDataDuplicator datadup
); void gog_object_emit_changed (GogObject *obj
,gboolean size
); GogObjectRole const * gog_object_find_role_by_name (GogObject const *obj
,char const *role
); GogObject * gog_object_get_child_by_name (GogObject const *obj
,char const *name
); GogObject * gog_object_get_child_by_role (GogObject const *obj
,GogObjectRole const *role
); GSList * gog_object_get_children (GogObject const *obj
,GogObjectRole const *filter
); gpointer gog_object_get_editor (GogObject *obj
,GogDataAllocator *dalloc
,GOCmdContext *cc
); GogGraph * gog_object_get_graph (GogObject const *obj
); unsigned gog_object_get_id (GogObject const *obj
); GogViewAllocation gog_object_get_manual_allocation (GogObject *gobj
,GogViewAllocation const *parent_allocation
,GogViewRequisition const *requisition
); void gog_object_get_manual_position (GogObject *obj
,GogViewAllocation *pos
); GogManualSizeMode gog_object_get_manual_size_mode (GogObject *obj
); char const * gog_object_get_name (GogObject const *obj
); GogObject * gog_object_get_parent (GogObject const *obj
); GogObject * gog_object_get_parent_typed (GogObject const *obj
,GType t
); GogObjectPosition gog_object_get_position_flags (GogObject const *obj
,GogObjectPosition mask
); GogTheme * gog_object_get_theme (GogObject const *obj
); gboolean gog_object_is_default_position_flags (GogObject const *obj
,char const *name
); gboolean gog_object_is_deletable (GogObject const *obj
); #define gog_object_is_visible (obj) GogView * gog_object_new_view (GogObject const *obj
,GogView *parent
); 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_reorder (GogObject const *obj
,gboolean inc
,gboolean goto_max
); void gog_object_request_editor_update (GogObject *obj
); gboolean gog_object_request_update (GogObject *obj
); void gog_object_set_invisible (GogObject *obj
,gboolean invisible
); void gog_object_set_manual_position (GogObject *obj
,GogViewAllocation const *pos
); void gog_object_set_name (GogObject *obj
,char *name
,GError **err
); gboolean gog_object_set_parent (GogObject *child
,GogObject *parent
,GogObjectRole const *role
,unsigned int id
); gboolean gog_object_set_position_flags (GogObject *obj
,GogObjectPosition flags
,GogObjectPosition mask
); void gog_object_update (GogObject *obj
);
Object Hierarchy
GObject +----GogObject +----Gog3DBox +----GogStyledObject +----GogPlot
GBoxed +----GogObjectRole
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 "manual-size" gchar* : 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
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.
Details
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
typedef enum { GOG_MANUAL_SIZE_AUTO, /* auto size, can't be changed */ GOG_MANUAL_SIZE_WIDTH, /*=1*/ GOG_MANUAL_SIZE_HEIGHT, /*=2*/ GOG_MANUAL_SIZE_FULL /*=3 or GOG_MANUAL_SIZE_WIDTH | GOG_MANUAL_SIZE_HEIGHT */ } GogManualSizeMode;
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); 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); void (*extra_signal1) (GogObject *view); void (*extra_signal2) (GogObject *view); } GogObjectClass;
GObjectClass |
|
GHashTable * |
roles for the class. |
GType |
view type. |
updates the object. | |
called when parent changed. | |
gets the type public name. | |
populates the editor. | |
the document changed. | |
resize mode. | |
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; gpointer p; } user; } GogObjectRole;
Describes allowable children for a GogObject.
id for persistence. | |
type name. | |
allowed positions inside parent. | |
GogObjectPosition |
default position. |
GogObjectNamingConv |
naming convention. |
return TRUE if a new child can be added. |
|
return TRUE if the child can be removed. |
|
optional allocator, g_object_new() is used if NULL . |
|
called after adding the child. | |
called before removing the child. | |
called after removing the child. |
enum GogObjectPosition
typedef enum { GOG_POSITION_AUTO = 0, GOG_POSITION_N = 1 << 0, /* can be used with E or W */ GOG_POSITION_S = 1 << 1, /* can be used with E or W */ GOG_POSITION_E = 1 << 2, GOG_POSITION_W = 1 << 3, GOG_POSITION_COMPASS = 0x0f, /* modifiers for compass */ GOG_POSITION_ALIGN_FILL = 0 << 4, GOG_POSITION_ALIGN_START = 1 << 4, GOG_POSITION_ALIGN_END = 2 << 4, GOG_POSITION_ALIGN_CENTER = 3 << 4, GOG_POSITION_ALIGNMENT = 0x30, GOG_POSITION_SPECIAL = 1 << 6, GOG_POSITION_MANUAL = 1 << 7, GOG_POSITION_MANUAL_X_ABS = 1 << 8, /* abs vs relative pos */ GOG_POSITION_MANUAL_Y_ABS = 1 << 9, GOG_POSITION_MANUAL_X_END = 1 << 10, /* pos relative to start or end */ GOG_POSITION_MANUAL_Y_END = 1 << 11, /* modifiers for manual */ GOG_POSITION_ANCHOR_NW = 0 << 12, GOG_POSITION_ANCHOR_N = 1 << 12, GOG_POSITION_ANCHOR_NE = 2 << 12, GOG_POSITION_ANCHOR_E = 3 << 12, GOG_POSITION_ANCHOR_SE = 4 << 12, GOG_POSITION_ANCHOR_S = 5 << 12, GOG_POSITION_ANCHOR_SW = 6 << 12, GOG_POSITION_ANCHOR_W = 7 << 12, GOG_POSITION_ANCHOR_CENTER = 8 << 12, GOG_POSITION_ANCHOR = 0x1f000, GOG_POSITION_ANY_MANUAL = 0x1ff80, GOG_POSITION_PADDING = 1 << 16, GOG_POSITION_MANUAL_W = 1 << 21, /* relative width */ GOG_POSITION_MANUAL_W_ABS = 1 << 22, /* absolute width */ GOG_POSITION_MANUAL_H = 1 << 23, /* relative height */ GOG_POSITION_MANUAL_H_ABS = 1 << 24, /* absolute height */ GOG_POSITION_ANY_MANUAL_SIZE = 0x1e00000 } GogObjectPosition;
automatic. | |
north, might be combined with east or west. | |
south, might be combined with east or west. | |
east. | |
west. | |
mask of the four previous positions. | |
fills. | |
start. | |
end. | |
centered. | |
mask for start or end. | |
special. | |
manual. | |
whether the x position is absolute or relative. | |
whether the y position is absolute or relative. | |
x position relative to start or end. | |
y position relative to start or end. | |
anchored north-west. | |
anchored north. | |
anchored north-east. | |
anchored east. | |
anchored south-east. | |
anchored south. | |
anchored south-west. | |
anchored west. | |
anchored at center. | |
mask for anchors. | |
mask for all manual positions | |
padding. | |
relative width. | |
absolute width. | |
relative height. | |
absolute height. | |
mask for manual sizes. |
gog_object_add_by_name ()
GogObject * gog_object_add_by_name (GogObject *parent
,char const *role
,GogObject *child
);
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.
|
GogObject |
|
GogObjectRole |
|
GogObject |
Returns : |
child or a newly created object with role . Callers do _not_ own
the reference. [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
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.
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.
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
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
.
|
a GogObject |
|
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
);
|
a GogObject |
|
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.
|
a GogObject |
|
a GogDataAllocator |
|
a GOCmdContext |
Returns : |
a GtkNotebook widget. [transfer full] |
gog_object_get_graph ()
GogGraph * gog_object_get_graph (GogObject const *obj
);
|
const * GogObject |
Returns : |
the parent graph. [transfer none] |
gog_object_get_manual_allocation ()
GogViewAllocation gog_object_get_manual_allocation (GogObject *gobj
,GogViewAllocation const *parent_allocation
,GogViewRequisition const *requisition
);
|
GogObject |
|
GogViewAllocation |
|
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
|
GogObject |
|
GogViewAllocation |
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
|
a GogObject |
Returns : |
a name. |
gog_object_get_parent_typed ()
GogObject * gog_object_get_parent_typed (GogObject const *obj
,GType t
);
gog_object_get_position_flags ()
GogObjectPosition gog_object_get_position_flags (GogObject const *obj
,GogObjectPosition mask
);
|
GogObject |
|
GogObjectPosition |
Returns : |
obj 's position flags, masked by mask . |
gog_object_get_theme ()
GogTheme * gog_object_get_theme (GogObject const *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_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
.
gog_object_possible_additions ()
GSList * gog_object_possible_additions (GogObject const *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
);
|
GogObjectClass |
|
GogObjectRole |
|
number of roles |
gog_object_reorder ()
GogObject * gog_object_reorder (GogObject const *obj
,gboolean inc
,gboolean goto_max
);
|
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.
|
GogObject |
gog_object_set_invisible ()
void gog_object_set_invisible (GogObject *obj
,gboolean invisible
);
|
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.
|
GogObject |
|
GogViewAllocation |
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
gog_object_set_parent ()
gboolean gog_object_set_parent (GogObject *child
,GogObject *parent
,GogObjectRole const *role
,unsigned int id
);
Absorbs a ref to child
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
.
|
GogObject |
|
GogObjectPosition |
|
GogObjectPosition |
Returns : |
TRUE the new flags are permitted. |
Property Details
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 "manual-size"
property
"manual-size" gchar* : Read / Write
Whether the height or width are manually set.
Default value: "none"
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
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
The "child-added"
signal
void user_function (GogObject *object,
GObject *child,
gpointer user_data) : Run Last
The ::child-added signal is emitted AFTER the child has been added and AFTER the parent-changed signal has been called for it.
|
the object on which the signal is emitted |
|
The new GogObject whose parent is object
|
|
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
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
The "child-removed"
signal
void user_function (GogObject *object,
GObject *child,
gpointer user_data) : Run Last
The ::child-removed signal is emitted BEFORE the child has been added and BEFORE the parent-changed signal has been called for it.
|
the object on which the signal is emitted |
|
The new GogObject whose parent is object
|
|
user data set when the signal handler was connected. |
The "children-reordered"
signal
void user_function (GogObject *gogobject,
gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
The "name-changed"
signal
void user_function (GogObject *gogobject,
gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |