GooCanvasItemModel: GooCanvas Reference Manual

GooCanvasItemModel

GooCanvasItemModel — the interface for canvas item models.

Functions

void	goo_canvas_item_model_translate ()
void	goo_canvas_item_model_scale ()
void	goo_canvas_item_model_rotate ()
void	goo_canvas_item_model_skew_x ()
void	goo_canvas_item_model_skew_y ()
gboolean	goo_canvas_item_model_get_transform ()
void	goo_canvas_item_model_set_transform ()
gboolean	goo_canvas_item_model_get_simple_transform ()
void	goo_canvas_item_model_set_simple_transform ()
void	goo_canvas_item_model_animate ()
void	goo_canvas_item_model_stop_animation ()
void	goo_canvas_item_model_raise ()
void	goo_canvas_item_model_lower ()
void	goo_canvas_item_model_remove ()
GooCanvasItemModel *	goo_canvas_item_model_get_parent ()
void	goo_canvas_item_model_set_parent ()
gboolean	goo_canvas_item_model_is_container ()
gint	goo_canvas_item_model_get_n_children ()
GooCanvasItemModel *	goo_canvas_item_model_get_child ()
void	goo_canvas_item_model_add_child ()
void	goo_canvas_item_model_move_child ()
void	goo_canvas_item_model_remove_child ()
gint	goo_canvas_item_model_find_child ()
GooCanvasStyle *	goo_canvas_item_model_get_style ()
void	goo_canvas_item_model_set_style ()
void	goo_canvas_item_model_class_install_child_property ()
GParamSpec **	goo_canvas_item_model_class_list_child_properties ()
GParamSpec *	goo_canvas_item_model_class_find_child_property ()
void	goo_canvas_item_model_get_child_property ()
void	goo_canvas_item_model_set_child_property ()
void	goo_canvas_item_model_get_child_properties ()
void	goo_canvas_item_model_get_child_properties_valist ()
void	goo_canvas_item_model_set_child_properties ()
void	goo_canvas_item_model_set_child_properties_valist ()

Properties

gboolean	can-focus	Read / Write
gchar *	description	Read / Write
GooCanvasItemModel *	parent	Read / Write
GooCanvasPointerEvents	pointer-events	Read / Write
gchar *	title	Read / Write
gchar *	tooltip	Read / Write
GooCairoMatrix *	transform	Read / Write
GooCanvasItemVisibility	visibility	Read / Write
gdouble	visibility-threshold	Read / Write

Signals

void	animation-finished	Run Last
void	changed	Run Last
void	child-added	Run Last
void	child-moved	Run Last
void	child-notify	No Hooks
void	child-removed	Run Last

Types and Values

	GooCanvasItemModel
struct	GooCanvasItemModelIface

Object Hierarchy

    GInterface
    ╰── GooCanvasItemModel

Prerequisites

GooCanvasItemModel requires GObject.

Known Implementations

GooCanvasItemModel is implemented by GooCanvasEllipseModel, GooCanvasGridModel, GooCanvasGroupModel, GooCanvasImageModel, GooCanvasItemModelSimple, GooCanvasPathModel, GooCanvasPolylineModel, GooCanvasRectModel, GooCanvasTableModel and GooCanvasTextModel.

Description

GooCanvasItemModel defines the interface that models for canvas items must implement, and contains methods for operating on canvas item models.

The Model/View canvas feature may be removed in a future version of GooCanvas.

Functions

goo_canvas_item_model_translate ()

void
goo_canvas_item_model_translate (GooCanvasItemModel *model,
                                 gdouble tx,
                                 gdouble ty);

Translates the origin of the model's coordinate system by the given amounts.

Parameters

model	an item model.
tx	the amount to move the origin in the horizontal direction.
ty	the amount to move the origin in the vertical direction.

goo_canvas_item_model_scale ()

void
goo_canvas_item_model_scale (GooCanvasItemModel *model,
                             gdouble sx,
                             gdouble sy);

Scales the model's coordinate system by the given amounts.

Parameters

model	an item model.
sx	the amount to scale the horizontal axis.
sy	the amount to scale the vertical axis.

goo_canvas_item_model_rotate ()

void
goo_canvas_item_model_rotate (GooCanvasItemModel *model,
                              gdouble degrees,
                              gdouble cx,
                              gdouble cy);

Rotates the model's coordinate system by the given amount, about the given origin.

Parameters

model	an item model.
degrees	the clockwise angle of rotation.
cx	the x coordinate of the origin of the rotation.
cy	the y coordinate of the origin of the rotation.

goo_canvas_item_model_skew_x ()

void
goo_canvas_item_model_skew_x (GooCanvasItemModel *model,
                              gdouble degrees,
                              gdouble cx,
                              gdouble cy);

Skews the model's coordinate system along the x axis by the given amount, about the given origin.

Parameters

model	an item model.
degrees	the skew angle.
cx	the x coordinate of the origin of the skew transform.
cy	the y coordinate of the origin of the skew transform.

goo_canvas_item_model_skew_y ()

void
goo_canvas_item_model_skew_y (GooCanvasItemModel *model,
                              gdouble degrees,
                              gdouble cx,
                              gdouble cy);

Skews the model's coordinate system along the y axis by the given amount, about the given origin.

Parameters

model	an item model.
degrees	the skew angle.
cx	the x coordinate of the origin of the skew transform.
cy	the y coordinate of the origin of the skew transform.

goo_canvas_item_model_get_transform ()

gboolean
goo_canvas_item_model_get_transform (GooCanvasItemModel *model,
                                     cairo_matrix_t *transform);

Gets the transformation matrix of an item model.

Parameters

model	an item model.
transform	the place to store the transform.

Returns

TRUE if a transform is set.

goo_canvas_item_model_set_transform ()

void
goo_canvas_item_model_set_transform (GooCanvasItemModel *model,
                                     const cairo_matrix_t *transform);

Sets the transformation matrix of an item model.

Parameters

model	an item model.
transform	the new transformation matrix, or `NULL` to reset the transformation to the identity matrix.	[allow-none]

goo_canvas_item_model_get_simple_transform ()

gboolean
goo_canvas_item_model_get_simple_transform
                               (GooCanvasItemModel *model,
                                gdouble *x,
                                gdouble *y,
                                gdouble *scale,
                                gdouble *rotation);

This function can be used to get the position, scale and rotation of an item model, providing that the model has a simple transformation matrix (e.g. set with goo_canvas_item_model_set_simple_transform(), or using a combination of simple translate, scale and rotate operations). If the model has a complex transformation matrix the results will be incorrect.

Parameters

model	an item model.
x	returns the x coordinate of the origin of the model's coordinate space.
y	returns the y coordinate of the origin of the model's coordinate space.
scale	returns the scale of the model.
rotation	returns the clockwise rotation of the model, in degrees (0-360).

Returns

TRUE if a transform is set.

goo_canvas_item_model_set_simple_transform ()

void
goo_canvas_item_model_set_simple_transform
                               (GooCanvasItemModel *model,
                                gdouble x,
                                gdouble y,
                                gdouble scale,
                                gdouble rotation);

A convenience function to set the item model's transformation matrix.

Parameters

model	an item model.
x	the x coordinate of the origin of the model's coordinate space.
y	the y coordinate of the origin of the model's coordinate space.
scale	the scale of the model.
rotation	the clockwise rotation of the model, in degrees.

goo_canvas_item_model_animate ()

void
goo_canvas_item_model_animate (GooCanvasItemModel *model,
                               gdouble x,
                               gdouble y,
                               gdouble scale,
                               gdouble degrees,
                               gboolean absolute,
                               gint duration,
                               gint step_time,
                               GooCanvasAnimateType type);

Animates a model from its current position to the given offsets, scale and rotation.

Parameters

model	an item model.
x	the final x coordinate.
y	the final y coordinate.
scale	the final scale.
degrees	the final rotation. This can be negative to rotate anticlockwise, and can also be greater than 360 to rotate a number of times.
absolute	if the `x` , `y` , `scale` and `degrees` values are absolute, or relative to the current transform. Note that absolute animations only work if the model currently has a simple transform. If the model has a shear or some other complicated transform it may result in strange animations.
duration	the duration of the animation, in milliseconds (1/1000ths of a second).
step_time	the time between each animation step, in milliseconds.
type	specifies what happens when the animation finishes.

goo_canvas_item_model_stop_animation ()

void
goo_canvas_item_model_stop_animation (GooCanvasItemModel *model);

Stops any current animation for the given model, leaving it at its current position.

Parameters

model

an item model.

goo_canvas_item_model_raise ()

void
goo_canvas_item_model_raise (GooCanvasItemModel *model,
                             GooCanvasItemModel *above);

Raises a model in the stacking order.

Parameters

model	an item model.
above	the item model to raise `model` above, or `NULL` to raise `model` to the top of the stack.	[allow-none]

goo_canvas_item_model_lower ()

void
goo_canvas_item_model_lower (GooCanvasItemModel *model,
                             GooCanvasItemModel *below);

Lowers a model in the stacking order.

Parameters

model	an item model.
below	the item model to lower `model` below, or `NULL` to lower `model` to the bottom of the stack.	[allow-none]

goo_canvas_item_model_remove ()

void
goo_canvas_item_model_remove (GooCanvasItemModel *model);

Removes a model from its parent. If the model is in a canvas it will be removed.

This would normally also result in the model being freed.

Parameters

model

an item model.

goo_canvas_item_model_get_parent ()

GooCanvasItemModel *
goo_canvas_item_model_get_parent (GooCanvasItemModel *model);

Gets the parent of the given model.

Parameters

model

an item model.

Returns

the parent model, or NULL if the model has no parent.

[transfer none]

goo_canvas_item_model_set_parent ()

void
goo_canvas_item_model_set_parent (GooCanvasItemModel *model,
                                  GooCanvasItemModel *parent);

This function is only intended to be used when implementing new canvas item models (specifically container models such as GooCanvasGroupModel). It sets the parent of the child model.

This function cannot be used to add a model to a group or to change the parent of a model. To do that use the “parent” property.

Parameters

model	an item model.
parent	the new parent item model.

goo_canvas_item_model_is_container ()

gboolean
goo_canvas_item_model_is_container (GooCanvasItemModel *model);

Tests to see if the given item model is a container.

Parameters

model

an item model.

Returns

TRUE if the item model is a container.

goo_canvas_item_model_get_n_children ()

gint
goo_canvas_item_model_get_n_children (GooCanvasItemModel *model);

Gets the number of children of the container.

Parameters

model

an item model.

Returns

the number of children.

goo_canvas_item_model_get_child ()

GooCanvasItemModel *
goo_canvas_item_model_get_child (GooCanvasItemModel *model,
                                 gint child_num);

Gets the child at the given stack position.

Parameters

model	an item model.
child_num	the position of a child in the container's stack.

Returns

the child at the given stack position, or NULL if child_num is out of range.

[transfer none]

goo_canvas_item_model_add_child ()

void
goo_canvas_item_model_add_child (GooCanvasItemModel *model,
                                 GooCanvasItemModel *child,
                                 gint position);

Adds a child at the given stack position.

Parameters

model	an item model.
child	the child to add.
position	the position of the child, or -1 to place it last (at the top of the stacking order).

goo_canvas_item_model_move_child ()

void
goo_canvas_item_model_move_child (GooCanvasItemModel *model,
                                  gint old_position,
                                  gint new_position);

Moves a child to a new stack position.

Parameters

model	an item model.
old_position	the current position of the child.
new_position	the new position of the child.

goo_canvas_item_model_remove_child ()

void
goo_canvas_item_model_remove_child (GooCanvasItemModel *model,
                                    gint child_num);

Removes the child at the given position.

Parameters

model	an item model.
child_num	the position of the child to remove.

goo_canvas_item_model_find_child ()

gint
goo_canvas_item_model_find_child (GooCanvasItemModel *model,
                                  GooCanvasItemModel *child);

Attempts to find the given child with the container's stack.

Parameters

model	an item model.
child	the child to find.

Returns

the position of the given child , or -1 if it isn't found.

goo_canvas_item_model_get_style ()

GooCanvasStyle *
goo_canvas_item_model_get_style (GooCanvasItemModel *model);

Gets the model's style. If the model doesn't have its own style it will return its parent's style.

Parameters

model

an item model.

Returns

the model's style.

[transfer none]

goo_canvas_item_model_set_style ()

void
goo_canvas_item_model_set_style (GooCanvasItemModel *model,
                                 GooCanvasStyle *style);

Sets the model's style, by copying the properties from the given style.

Parameters

model	an item model.
style	a style.

goo_canvas_item_model_class_install_child_property ()

void
goo_canvas_item_model_class_install_child_property
                               (GObjectClass *mclass,
                                guint property_id,
                                GParamSpec *pspec);

This function is only intended to be used when implementing new canvas item models, specifically layout container item models such as GooCanvasTableModel.

It installs a child property on a canvas item class.

Parameters

mclass	a GObjectClass
property_id	the id for the property
pspec	the GParamSpec for the property

goo_canvas_item_model_class_list_child_properties ()

GParamSpec **
goo_canvas_item_model_class_list_child_properties
                               (GObjectClass *mclass,
                                guint *n_properties);

This function is only intended to be used when implementing new canvas item models, specifically layout container item models such as GooCanvasTableModel.

It returns all child properties of a canvas item class.

Parameters

mclass	a GObjectClass
n_properties	location to return the number of child properties found

Returns

a newly allocated array of GParamSpec*. The array must be freed with g_free().

[array length=n_properties][element-type GObject.ParamSpec][transfer container]

goo_canvas_item_model_class_find_child_property ()

GParamSpec *
goo_canvas_item_model_class_find_child_property
                               (GObjectClass *mclass,
                                const gchar *property_name);

This function is only intended to be used when implementing new canvas item models, specifically layout container item models such as GooCanvasTableModel.

It finds a child property of a canvas item class by name.

Parameters

mclass	a GObjectClass
property_name	the name of the child property to find

Returns

The GParamSpec of the child property or NULL if class has no child property with that name.

[type GObject.ParamSpec][transfer none]

goo_canvas_item_model_get_child_property ()

void
goo_canvas_item_model_get_child_property
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                const gchar *property_name,
                                GValue *value);

Gets a child property of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
property_name	the name of the child property to get.
value	a location to return the value.

goo_canvas_item_model_set_child_property ()

void
goo_canvas_item_model_set_child_property
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                const gchar *property_name,
                                const GValue *value);

Sets a child property of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
property_name	the name of the child property to set.
value	the value to set the property to.

goo_canvas_item_model_get_child_properties ()

void
goo_canvas_item_model_get_child_properties
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                ...);

Gets the values of one or more child properties of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
...	pairs of property names and value pointers, and a terminating `NULL`.

goo_canvas_item_model_get_child_properties_valist ()

void
goo_canvas_item_model_get_child_properties_valist
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                va_list var_args);

Gets the values of one or more child properties of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
var_args	pairs of property names and value pointers, and a terminating `NULL`.

goo_canvas_item_model_set_child_properties ()

void
goo_canvas_item_model_set_child_properties
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                ...);

Sets the values of one or more child properties of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
...	pairs of property names and values, and a terminating `NULL`.

goo_canvas_item_model_set_child_properties_valist ()

void
goo_canvas_item_model_set_child_properties_valist
                               (GooCanvasItemModel *model,
                                GooCanvasItemModel *child,
                                va_list var_args);

Sets the values of one or more child properties of child .

Parameters

model	a GooCanvasItemModel.
child	a child GooCanvasItemModel.
var_args	pairs of property names and values, and a terminating `NULL`.

Types and Values

GooCanvasItemModel

typedef struct _GooCanvasItemModel GooCanvasItemModel;

GooCanvasItemModel is a typedef used for objects that implement the GooCanvasItemModel interface.

(There is no actual GooCanvasItemModel struct, since it is only an interface. But using 'GooCanvasItemModel' is more helpful than using 'GObject'.)

struct GooCanvasItemModelIface

struct GooCanvasItemModelIface {
  /* Virtual methods that group models must implement. */
  gint		       (* get_n_children)		(GooCanvasItemModel *model);
  GooCanvasItemModel*  (* get_child)			(GooCanvasItemModel *model,
							 gint			 child_num);

  /* Virtual methods that group models may implement. */
  void                 (* add_child)			(GooCanvasItemModel *model,
							 GooCanvasItemModel *child,
							 gint			 position);
  void                 (* move_child)			(GooCanvasItemModel *model,
							 gint			 old_position,
							 gint			 new_position);
  void                 (* remove_child)			(GooCanvasItemModel *model,
							 gint			 child_num);
  void                 (* get_child_property)		(GooCanvasItemModel *model,
							 GooCanvasItemModel *child,
							 guint			 property_id,
							 GValue			*value,
							 GParamSpec		*pspec);
  void                 (* set_child_property)		(GooCanvasItemModel *item,
							 GooCanvasItemModel *child,
							 guint			 property_id,
							 const GValue		*value,
							 GParamSpec		*pspec);

  /* Virtual methods that all item models must implement. */
  GooCanvasItemModel*  (* get_parent)			(GooCanvasItemModel *model);
  void                 (* set_parent)			(GooCanvasItemModel *model,
							 GooCanvasItemModel *parent);

  GooCanvasItem*       (* create_item)			(GooCanvasItemModel *model,
							 GooCanvas		*canvas);

  /* Virtual methods that all item models may implement. */
  gboolean             (* get_transform)		(GooCanvasItemModel *model,
							 cairo_matrix_t         *transform);
  void                 (* set_transform)		(GooCanvasItemModel *model,
							 const cairo_matrix_t *transform);
  GooCanvasStyle*      (* get_style)			(GooCanvasItemModel *model);
  void                 (* set_style)			(GooCanvasItemModel *model,
							 GooCanvasStyle		*style);

  /* Signals. */
  void                 (* child_added)			(GooCanvasItemModel *model,
							 gint			 child_num);
  void                 (* child_moved)			(GooCanvasItemModel *model,
							 gint			 old_child_num,
							 gint			 new_child_num);
  void                 (* child_removed)		(GooCanvasItemModel *model,
							 gint			 child_num);
  void                 (* changed)			(GooCanvasItemModel *model,
							 gboolean		 recompute_bounds);
  void                 (* child_notify)			(GooCanvasItemModel *model,
							 GParamSpec		*pspec);

  void		       (* animation_finished)		(GooCanvasItemModel     *model,
							 gboolean                stopped);
};

GooCanvasItemModelIFace holds the virtual methods that make up the GooCanvasItemModel interface.

Simple item models only need to implement the get_parent(), set_parent() and create_item() methods.

Items that support transforms should also implement get_transform() and set_transform(). Items that support styles should implement get_style() and set_style().

Container items must implement get_n_children() and get_child(). Containers that support dynamic changes to their children should implement add_child(), move_child() and remove_child(). Layout containers like GooCanvasTable may implement get_child_property() and set_child_property().

Members

`get_n_children` ()	returns the number of children of the model.
`get_child` ()	returns the child at the given index.
`add_child` ()	adds a child.
`move_child` ()	moves a child up or down the stacking order.
`remove_child` ()	removes a child.
`get_child_property` ()	gets a child property of a given child model, e.g. the "row" or "column" property of a model in a GooCanvasTableModel.
`set_child_property` ()	sets a child property for a given child model.
`get_parent` ()	gets the model's parent.
`set_parent` ()	sets the model's parent.
`create_item` ()	creates a default canvas item to view the model.
`get_transform` ()	gets the model's transformation matrix.
`set_transform` ()	sets the model's transformation matrix.
`get_style` ()	gets the model's style.
`set_style` ()	sets the model's style.
`child_added` ()	signal emitted when a child is added.
`child_moved` ()	signal emitted when a child is moved in the stacking order.
`child_removed` ()	signal emitted when a child is removed.
`changed` ()	signal emitted when the model has changed.
`child_notify` ()	signal emitted when a child property has changed.
`animation_finished` ()	signal emitted when the model's animation has finished.

Property Details

The `“can-focus”` property

  “can-focus”                gboolean

If the item can take the keyboard focus.

Flags: Read / Write

Default value: FALSE

The `“description”` property

  “description”              gchar *

A description of the item for use by assistive technologies.

Flags: Read / Write

Default value: NULL

The `“parent”` property

  “parent”                   GooCanvasItemModel *

The parent item model.

Flags: Read / Write

The `“pointer-events”` property

  “pointer-events”           GooCanvasPointerEvents

Specifies when the item receives pointer events.

Flags: Read / Write

Default value: GOO_CANVAS_EVENTS_VISIBLE_MASK | GOO_CANVAS_EVENTS_PAINTED_MASK | GOO_CANVAS_EVENTS_FILL_MASK | GOO_CANVAS_EVENTS_STROKE_MASK

The `“title”` property

  “title”                    gchar *

A short context-rich description of the item for use by assistive technologies.

Flags: Read / Write

Default value: NULL

The `“tooltip”` property

  “tooltip”                  gchar *

The tooltip to display for the item.

Flags: Read / Write

Default value: NULL

The `“transform”` property

  “transform”                GooCairoMatrix *

The transformation matrix of the item.

Flags: Read / Write

The `“visibility”` property

  “visibility”               GooCanvasItemVisibility

When the canvas item is visible.

Flags: Read / Write

Default value: GOO_CANVAS_ITEM_VISIBLE

The `“visibility-threshold”` property

  “visibility-threshold”     gdouble

The scale threshold at which the item becomes visible.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Signal Details

The `“animation-finished”` signal

void
user_function (GooCanvasItemModel *item,
               gboolean            stopped,
               gpointer            user_data)

Emitted when the item model animation has finished.

Parameters

item	the item model that received the signal.
stopped	if the animation was explicitly stopped.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“changed”` signal

void
user_function (GooCanvasItemModel *model,
               gboolean            recompute_bounds,
               gpointer            user_data)

Emitted when the item model has been changed.

Parameters

model	the item model that received the signal.
recompute_bounds	if the bounds of the item need to be recomputed.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“child-added”` signal

void
user_function (GooCanvasItemModel *model,
               gint                child_num,
               gpointer            user_data)

Emitted when a child has been added.

Parameters

model	the item model that received the signal.
child_num	the index of the new child.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“child-moved”` signal

void
user_function (GooCanvasItemModel *model,
               gint                old_child_num,
               gint                new_child_num,
               gpointer            user_data)

Emitted when a child has been moved in the stacking order.

Parameters

model	the item model that received the signal.
old_child_num	the old index of the child.
new_child_num	the new index of the child.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“child-notify”` signal

void
user_function (GooCanvasItemModel *item,
               GParamSpec         *pspec,
               gpointer            user_data)

Emitted for each child property that has changed. The signal's detail holds the property name.

Parameters

item	the item model that received the signal.
pspec	the GParamSpec of the changed child property.	[type GObject.ParamSpec]
user_data	user data set when the signal handler was connected.

Flags: No Hooks

The `“child-removed”` signal

void
user_function (GooCanvasItemModel *model,
               gint                child_num,
               gpointer            user_data)

Emitted when a child has been removed.

Parameters

model	the item model that received the signal.
child_num	the index of the child that was removed.
user_data	user data set when the signal handler was connected.

Flags: Run Last