GNOME.org

GooCanvasItem

GooCanvasItem — the interface for canvas items.

Synopsis

                    GooCanvasItem;
                    GooCanvasItemIface;

void                goo_canvas_item_translate           (GooCanvasItem *item,
                                                         gdouble tx,
                                                         gdouble ty);
void                goo_canvas_item_scale               (GooCanvasItem *item,
                                                         gdouble sx,
                                                         gdouble sy);
void                goo_canvas_item_rotate              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);
void                goo_canvas_item_skew_x              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);
void                goo_canvas_item_skew_y              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);
gboolean            goo_canvas_item_get_transform       (GooCanvasItem *item,
                                                         cairo_matrix_t *transform);
void                goo_canvas_item_set_transform       (GooCanvasItem *item,
                                                         const cairo_matrix_t *transform);
gboolean            goo_canvas_item_get_simple_transform
                                                        (GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y,
                                                         gdouble *scale,
                                                         gdouble *rotation);
void                goo_canvas_item_set_simple_transform
                                                        (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble scale,
                                                         gdouble rotation);
void                goo_canvas_item_get_bounds          (GooCanvasItem *item,
                                                         GooCanvasBounds *bounds);
gboolean            goo_canvas_item_is_visible          (GooCanvasItem *item);
gboolean            goo_canvas_item_get_is_static       (GooCanvasItem *item);
void                goo_canvas_item_set_is_static       (GooCanvasItem *item,
                                                         gboolean is_static);

void                goo_canvas_item_animate             (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble scale,
                                                         gdouble degrees,
                                                         gboolean absolute,
                                                         gint duration,
                                                         gint step_time,
                                                         GooCanvasAnimateType type);
void                goo_canvas_item_stop_animation      (GooCanvasItem *item);

void                goo_canvas_item_raise               (GooCanvasItem *item,
                                                         GooCanvasItem *above);
void                goo_canvas_item_lower               (GooCanvasItem *item,
                                                         GooCanvasItem *below);

void                goo_canvas_item_remove              (GooCanvasItem *item);

GooCanvas*          goo_canvas_item_get_canvas          (GooCanvasItem *item);
void                goo_canvas_item_set_canvas          (GooCanvasItem *item,
                                                         GooCanvas *canvas);

GooCanvasItem*      goo_canvas_item_get_parent          (GooCanvasItem *item);
void                goo_canvas_item_set_parent          (GooCanvasItem *item,
                                                         GooCanvasItem *parent);

GooCanvasItemModel* goo_canvas_item_get_model           (GooCanvasItem *item);
void                goo_canvas_item_set_model           (GooCanvasItem *item,
                                                         GooCanvasItemModel *model);

gboolean            goo_canvas_item_is_container        (GooCanvasItem *item);
gint                goo_canvas_item_get_n_children      (GooCanvasItem *item);
GooCanvasItem*      goo_canvas_item_get_child           (GooCanvasItem *item,
                                                         gint child_num);
gint                goo_canvas_item_find_child          (GooCanvasItem *item,
                                                         GooCanvasItem *child);
void                goo_canvas_item_add_child           (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         gint position);
void                goo_canvas_item_move_child          (GooCanvasItem *item,
                                                         gint old_position,
                                                         gint new_position);
void                goo_canvas_item_remove_child        (GooCanvasItem *item,
                                                         gint child_num);
gboolean            goo_canvas_item_get_transform_for_child
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         cairo_matrix_t *transform);

GooCanvasStyle*     goo_canvas_item_get_style           (GooCanvasItem *item);
void                goo_canvas_item_set_style           (GooCanvasItem *item,
                                                         GooCanvasStyle *style);

void                goo_canvas_item_request_update      (GooCanvasItem *item);
void                goo_canvas_item_ensure_updated      (GooCanvasItem *item);
void                goo_canvas_item_update              (GooCanvasItem *item,
                                                         gboolean entire_tree,
                                                         cairo_t *cr,
                                                         GooCanvasBounds *bounds);
gboolean            goo_canvas_item_get_requested_area  (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         GooCanvasBounds *requested_area);
gdouble             goo_canvas_item_get_requested_height
                                                        (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         gdouble width);
void                goo_canvas_item_allocate_area       (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *requested_area,
                                                         const GooCanvasBounds *allocated_area,
                                                         gdouble x_offset,
                                                         gdouble y_offset);
GList*              goo_canvas_item_get_items_at        (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         cairo_t *cr,
                                                         gboolean is_pointer_event,
                                                         gboolean parent_is_visible,
                                                         GList *found_items);
void                goo_canvas_item_paint               (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *bounds,
                                                         gdouble scale);

void                goo_canvas_item_class_install_child_property
                                                        (GObjectClass *iclass,
                                                         guint property_id,
                                                         GParamSpec *pspec);
GParamSpec**        goo_canvas_item_class_list_child_properties
                                                        (GObjectClass *iclass,
                                                         guint *n_properties);
GParamSpec*         goo_canvas_item_class_find_child_property
                                                        (GObjectClass *iclass,
                                                         const gchar *property_name);
void                goo_canvas_item_get_child_property  (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         const gchar *property_name,
                                                         GValue *value);
void                goo_canvas_item_set_child_property  (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         const gchar *property_name,
                                                         const GValue *value);
void                goo_canvas_item_get_child_properties
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         ...);
void                goo_canvas_item_get_child_properties_valist
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         va_list var_args);
void                goo_canvas_item_set_child_properties
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         ...);
void                goo_canvas_item_set_child_properties_valist
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         va_list var_args);

Object Hierarchy

  GInterface
   +----GooCanvasItem

Prerequisites

GooCanvasItem requires GObject.

Known Implementations

GooCanvasItem is implemented by GooCanvasEllipse, GooCanvasGrid, GooCanvasGroup, GooCanvasImage, GooCanvasItemSimple, GooCanvasPath, GooCanvasPolyline, GooCanvasRect, GooCanvasTable, GooCanvasText and GooCanvasWidget.

Properties

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

Signals

  "animation-finished"                             : Run Last
  "button-press-event"                             : Run Last
  "button-release-event"                           : Run Last
  "child-notify"                                   : Run First / No Recursion / Has Details / No Hooks
  "enter-notify-event"                             : Run Last
  "focus-in-event"                                 : Run Last
  "focus-out-event"                                : Run Last
  "grab-broken-event"                              : Run Last
  "key-press-event"                                : Run Last
  "key-release-event"                              : Run Last
  "leave-notify-event"                             : Run Last
  "motion-notify-event"                            : Run Last
  "query-tooltip"                                  : Run Last
  "scroll-event"                                   : Run Last

Description

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

Details

GooCanvasItem

typedef struct _GooCanvasItem GooCanvasItem;

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

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

GooCanvasItemIface

typedef struct {
  /* Virtual methods that group items must implement. */
  GooCanvas*		(* get_canvas)			(GooCanvasItem		*item);
  void			(* set_canvas)			(GooCanvasItem		*item,
							 GooCanvas		*canvas);
  gint			(* get_n_children)		(GooCanvasItem		*item);
  GooCanvasItem* (* get_child)			(GooCanvasItem		*item,
							 gint			 child_num);
  void			(* request_update)		(GooCanvasItem		*item);

  /* Virtual methods that group items may implement. */
  void			(* add_child)			(GooCanvasItem		*item,
							 GooCanvasItem		*child,
							 gint			 position);
  void			(* move_child)			(GooCanvasItem		*item,
							 gint			 old_position,
							 gint			 new_position);
  void			(* remove_child)		(GooCanvasItem		*item,
							 gint			 child_num);
  void			(* get_child_property)		(GooCanvasItem		*item,
							 GooCanvasItem		*child,
							 guint			 property_id,
							 GValue			*value,
							 GParamSpec		*pspec);
  void			(* set_child_property)		(GooCanvasItem		*item,
							 GooCanvasItem		*child,
							 guint			 property_id,
							 const GValue		*value,
							 GParamSpec		*pspec);
  gboolean		(* get_transform_for_child) (GooCanvasItem		*item,
							 GooCanvasItem		*child,
							 cairo_matrix_t		*transform);

  /* Virtual methods that all canvas items must implement. */
  GooCanvasItem* (* get_parent)			(GooCanvasItem		*item);
  void			(* set_parent)			(GooCanvasItem		*item,
							 GooCanvasItem		*parent);
  void			(* get_bounds)			(GooCanvasItem		*item,
							 GooCanvasBounds *bounds);
  GList*		(* get_items_at)		(GooCanvasItem		*item,
							 gdouble		 x,
							 gdouble		 y,
							 cairo_t		*cr,
							 gboolean		 is_pointer_event,
							 gboolean		 parent_is_visible,
							 GList                  *found_items);
  void			(* update)			(GooCanvasItem		*item,
							 gboolean		 entire_tree,
							 cairo_t		*cr,
							 GooCanvasBounds *bounds);
  void			(* paint)			(GooCanvasItem		*item,
							 cairo_t		*cr,
							 const GooCanvasBounds *bounds,
							 gdouble		 scale);

  gboolean		(* get_requested_area)		(GooCanvasItem		*item,
							 cairo_t		*cr,
							 GooCanvasBounds *requested_area);
  void			(* allocate_area)		(GooCanvasItem		*item,
							 cairo_t		*cr,
							 const GooCanvasBounds *requested_area,
							 const GooCanvasBounds *allocated_area,
							 gdouble		 x_offset,
							 gdouble		 y_offset);

  /* Virtual methods that canvas items may implement. */
  gboolean		(* get_transform)		(GooCanvasItem		*item,
							 cairo_matrix_t		*transform);
  void			(* set_transform)		(GooCanvasItem		*item,
							 const cairo_matrix_t *transform);
  GooCanvasStyle* (* get_style)			(GooCanvasItem		*item);
  void			(* set_style)			(GooCanvasItem		*item,
							 GooCanvasStyle		*style);
  gboolean		(* is_visible)			(GooCanvasItem		*item);
  gdouble               (* get_requested_height) (GooCanvasItem		*item,
							 cairo_t		*cr,
							 gdouble		 width);

  /* Virtual methods that model/view items must implement. */
  GooCanvasItemModel* (* get_model)			(GooCanvasItem		*item);
  void			(* set_model)			(GooCanvasItem		*item,
							 GooCanvasItemModel *model);


  /* Signals. */
  gboolean		(* enter_notify_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventCrossing *event);
  gboolean		(* leave_notify_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventCrossing *event);
  gboolean		(* motion_notify_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventMotion		*event);
  gboolean		(* button_press_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventButton		*event);
  gboolean		(* button_release_event) (GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventButton		*event);
  gboolean		(* focus_in_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventFocus		*event);
  gboolean		(* focus_out_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventFocus		*event);
  gboolean		(* key_press_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventKey		*event);
  gboolean		(* key_release_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventKey		*event);
  gboolean		(* grab_broken_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventGrabBroken *event);
  void			(* child_notify)		(GooCanvasItem		*item,
							 GParamSpec		*pspec);
  gboolean		(* query_tooltip)		(GooCanvasItem		*item,
							 gdouble		 x,
							 gdouble		 y,
							 gboolean		 keyboard_tooltip,
							 GtkTooltip		*tooltip);

  gboolean		(* get_is_static)		(GooCanvasItem		*item);
  void			(* set_is_static)		(GooCanvasItem		*item,
							 gboolean		 is_static);

  void			(* animation_finished)		(GooCanvasItem           *item,
							 gboolean                 stopped);

  gboolean		(* scroll_event)		(GooCanvasItem		*item,
							 GooCanvasItem		*target,
							 GdkEventScroll		*event);
} GooCanvasItemIface;

GooCanvasItemIFace holds the virtual methods that make up the GooCanvasItem interface.

Simple canvas items only need to implement the get_parent(), set_parent(), get_bounds(), get_items_at(), update() and paint() methods (and also get_requested_area() and allocate_area() if they are going to be used inside a layout container like GooCanvasTable).

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_canvas(), set_canvas(), get_n_children(), get_child() and request_update(). 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(), set_child_property() and get_transform_for_child().

get_canvas ()

 returns the canvas the item is in.

set_canvas ()

 sets the canvas the item is in.

get_n_children ()

 returns the number of children of the item.

get_child ()

 returns the child at the given index.

request_update ()

 requests that an update is scheduled.

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 item, e.g. the "row" or "column" property of an item in a GooCanvasTable.

set_child_property ()

 sets a child property for a given child item.

get_transform_for_child ()

 gets the transform used to lay out a given child.

get_parent ()

 gets the item's parent.

set_parent ()

 sets the item's parent.

get_bounds ()

 gets the bounds of the item.

get_items_at ()

 gets all the items at the given point.

update ()

 updates the item, if needed. It recalculates the bounds of the item and requests redraws of parts of the canvas if necessary.

paint ()

 renders the item to the given cairo context.

get_requested_area ()

 returns the requested area of the item, in its parent's coordinate space. This is only used for items in layout containers such as GooCanvasTable.

allocate_area ()

 allocates the item's area, in its parent's coordinate space. The item must recalculate its bounds and request redraws of parts of the canvas if necessary. This is only used for items in layout containers such as GooCanvasTable.

get_transform ()

 gets the item's transformation matrix.

set_transform ()

 sets the item's transformation matrix.

get_style ()

 gets the item's style.

set_style ()

 sets the item's style.

is_visible ()

 returns TRUE if the item is currently visible.

get_requested_height ()

 returns the requested height of the item, given a particular allocated width, using the parent's coordinate space.

get_model ()

 gets the model that the canvas item is viewing.

set_model ()

 sets the model that the canvas item will view.

enter_notify_event ()

 signal emitted when the mouse enters the item.

leave_notify_event ()

 signal emitted when the mouse leaves the item.

motion_notify_event ()

 signal emitted when the mouse moves within the item.

button_press_event ()

 signal emitted when a mouse button is pressed within the item.

button_release_event ()

 signal emitted when a mouse button is released.

focus_in_event ()

 signal emitted when the item receices the keyboard focus.

focus_out_event ()

 signal emitted when the item loses the keyboard focus.

key_press_event ()

 signal emitted when a key is pressed.

key_release_event ()

 signal emitted when a key is released.

grab_broken_event ()

 signal emitted when a grab that the item has is lost.

child_notify ()

 signal emitted when a child property is changed.

query_tooltip ()

 signal emitted to query the tooltip of an item.

get_is_static ()

 returns TRUE if the item is static.

set_is_static ()

 notifies the item whether it is static or not.

animation_finished ()

 signal emitted when the item's animation has finished.

scroll_event ()

 signal emitted when the mouse wheel is activated within the item.

goo_canvas_item_translate ()

void                goo_canvas_item_translate           (GooCanvasItem *item,
                                                         gdouble tx,
                                                         gdouble ty);

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

item :

 an item.

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

void                goo_canvas_item_scale               (GooCanvasItem *item,
                                                         gdouble sx,
                                                         gdouble sy);

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

item :

 an item.

sx :

 the amount to scale the horizontal axis.

sy :

 the amount to scale the vertical axis.

goo_canvas_item_rotate ()

void                goo_canvas_item_rotate              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);

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

item :

 an item.

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

void                goo_canvas_item_skew_x              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);

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

item :

 an item.

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

void                goo_canvas_item_skew_y              (GooCanvasItem *item,
                                                         gdouble degrees,
                                                         gdouble cx,
                                                         gdouble cy);

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

item :

 an item.

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

gboolean            goo_canvas_item_get_transform       (GooCanvasItem *item,
                                                         cairo_matrix_t *transform);

Gets the transformation matrix of an item.

item :

 an item.

transform :

 the place to store the transform.

Returns :

 TRUE if a transform is set.

goo_canvas_item_set_transform ()

void                goo_canvas_item_set_transform       (GooCanvasItem *item,
                                                         const cairo_matrix_t *transform);

Sets the transformation matrix of an item.

item :

 an item.

transform :

 the new transformation matrix, or NULL to reset the transformation to the identity matrix.

goo_canvas_item_get_simple_transform ()

gboolean            goo_canvas_item_get_simple_transform
                                                        (GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y,
                                                         gdouble *scale,
                                                         gdouble *rotation);

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

item :

 an item.

x :

 returns the x coordinate of the origin of the item's coordinate space.

y :

 returns the y coordinate of the origin of the item's coordinate space.

scale :

 returns the scale of the item.

rotation :

 returns the clockwise rotation of the item, in degrees (0-360).

Returns :

 TRUE if a transform is set.

goo_canvas_item_set_simple_transform ()

void                goo_canvas_item_set_simple_transform
                                                        (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble scale,
                                                         gdouble rotation);

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

item :

 an item.

x :

 the x coordinate of the origin of the item's coordinate space.

y :

 the y coordinate of the origin of the item's coordinate space.

scale :

 the scale of the item.

rotation :

 the clockwise rotation of the item, in degrees.

goo_canvas_item_get_bounds ()

void                goo_canvas_item_get_bounds          (GooCanvasItem *item,
                                                         GooCanvasBounds *bounds);

Gets the bounds of the item.

Note that the bounds includes the entire fill and stroke extents of the item, whether they are painted or not.

item :

 a GooCanvasItem.

bounds :

 a GooCanvasBounds to return the bounds in.

goo_canvas_item_is_visible ()

gboolean            goo_canvas_item_is_visible          (GooCanvasItem *item);

Checks if the item is visible.

This entails checking the item's own visibility setting, as well as those of its ancestors.

Note that the item may be scrolled off the screen and so may not be actually visible to the user.

item :

 a GooCanvasItem.

Returns :

 TRUE if the item is visible.

goo_canvas_item_get_is_static ()

gboolean            goo_canvas_item_get_is_static       (GooCanvasItem *item);

Returns TRUE if the item is static. Static items do not move or change size when the canvas is scrolled or the scale changes.

item :

 an item.

Returns :

 TRUE if the item is static.

goo_canvas_item_set_is_static ()

void                goo_canvas_item_set_is_static       (GooCanvasItem *item,
                                                         gboolean is_static);

Notifies the item that it is static. Static items do not move or change size when the canvas is scrolled or the scale changes.

Container items such as GooCanvasGroup should call this function when children are added, to notify children whether they are static or not. Containers should also pass on any changes in their own status to children.

item :

 an item.

is_static :

 if the item is static.

goo_canvas_item_animate ()

void                goo_canvas_item_animate             (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         gdouble scale,
                                                         gdouble degrees,
                                                         gboolean absolute,
                                                         gint duration,
                                                         gint step_time,
                                                         GooCanvasAnimateType type);

Animates an item from its current position to the given offsets, scale and rotation.

item :

 an item.

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 item currently has a simple transform. If the item 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_stop_animation ()

void                goo_canvas_item_stop_animation      (GooCanvasItem *item);

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

item :

 an item.

goo_canvas_item_raise ()

void                goo_canvas_item_raise               (GooCanvasItem *item,
                                                         GooCanvasItem *above);

Raises an item in the stacking order.

item :

 an item.

above :

 the item to raise item above, or NULL to raise item to the top of the stack.

goo_canvas_item_lower ()

void                goo_canvas_item_lower               (GooCanvasItem *item,
                                                         GooCanvasItem *below);

Lowers an item in the stacking order.

item :

 an item.

below :

 the item to lower item below, or NULL to lower item to the bottom of the stack.

goo_canvas_item_remove ()

void                goo_canvas_item_remove              (GooCanvasItem *item);

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

This would normally also result in the item being freed.

item :

 an item.

goo_canvas_item_get_canvas ()

GooCanvas*          goo_canvas_item_get_canvas          (GooCanvasItem *item);

Returns the GooCanvas containing the given GooCanvasItem.

item :

 a GooCanvasItem.

Returns :

 the GooCanvas.

goo_canvas_item_set_canvas ()

void                goo_canvas_item_set_canvas          (GooCanvasItem *item,
                                                         GooCanvas *canvas);

This function is only intended to be used when implementing new canvas items, specifically container items such as GooCanvasGroup.

It sets the canvas of the item.

item :

 a GooCanvasItem.

canvas :

 a GooCanvas

goo_canvas_item_get_parent ()

GooCanvasItem*      goo_canvas_item_get_parent          (GooCanvasItem *item);

Gets the parent of the given item.

item :

 an item.

Returns :

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

goo_canvas_item_set_parent ()

void                goo_canvas_item_set_parent          (GooCanvasItem *item,
                                                         GooCanvasItem *parent);

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

item :

 an item.

parent :

 the new parent item.

Note

This function cannot be used to add an item to a group or to change the parent of an item. To do that use the "parent" property.

goo_canvas_item_get_model ()

GooCanvasItemModel* goo_canvas_item_get_model           (GooCanvasItem *item);

Gets the model of the given canvas item.

item :

 a GooCanvasItem.

Returns :

 the item's model, or NULL if it has no model.

goo_canvas_item_set_model ()

void                goo_canvas_item_set_model           (GooCanvasItem *item,
                                                         GooCanvasItemModel *model);

Sets the model of the given canvas item.

item :

 a GooCanvasItem.

model :

 a GooCanvasItemModel.

goo_canvas_item_is_container ()

gboolean            goo_canvas_item_is_container        (GooCanvasItem *item);

Tests to see if the given item is a container.

item :

 an item.

Returns :

 TRUE if the item is a container.

goo_canvas_item_get_n_children ()

gint                goo_canvas_item_get_n_children      (GooCanvasItem *item);

Gets the number of children of the container.

item :

 a container item.

Returns :

 the number of children.

goo_canvas_item_get_child ()

GooCanvasItem*      goo_canvas_item_get_child           (GooCanvasItem *item,
                                                         gint child_num);

Gets the child item at the given stack position.

item :

 a container item.

child_num :

 the position of a child in the container's stack.

Returns :

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

goo_canvas_item_find_child ()

gint                goo_canvas_item_find_child          (GooCanvasItem *item,
                                                         GooCanvasItem *child);

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

item :

 a container item.

child :

 the child item to find.

Returns :

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

goo_canvas_item_add_child ()

void                goo_canvas_item_add_child           (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         gint position);

Adds a child item to a container item at the given stack position.

item :

 the container to add the item to.

child :

 the item to add.

position :

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

goo_canvas_item_move_child ()

void                goo_canvas_item_move_child          (GooCanvasItem *item,
                                                         gint old_position,
                                                         gint new_position);

Moves a child item to a new stack position within the container.

item :

 a container item.

old_position :

 the current position of the child item.

new_position :

 the new position of the child item.

goo_canvas_item_remove_child ()

void                goo_canvas_item_remove_child        (GooCanvasItem *item,
                                                         gint child_num);

Removes the child item at the given position.

item :

 a container item.

child_num :

 the position of the child item to remove.

goo_canvas_item_get_transform_for_child ()

gboolean            goo_canvas_item_get_transform_for_child
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         cairo_matrix_t *transform);

Gets the transformation matrix of an item combined with any special transform needed for the given child. These special transforms are used by layout items such as GooCanvasTable.

item :

 an item.

child :

 a child of item.

transform :

 the place to store the transform.

Returns :

 TRUE if a transform is set.

goo_canvas_item_get_style ()

GooCanvasStyle*     goo_canvas_item_get_style           (GooCanvasItem *item);

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

item :

 an item.

Returns :

 the item's style.

goo_canvas_item_set_style ()

void                goo_canvas_item_set_style           (GooCanvasItem *item,
                                                         GooCanvasStyle *style);

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

item :

 an item.

style :

 a style.

goo_canvas_item_request_update ()

void                goo_canvas_item_request_update      (GooCanvasItem *item);

This function is only intended to be used when implementing new canvas items.

It requests that an update of the item is scheduled. It will be performed as soon as the application is idle, and before the canvas is redrawn.

item :

 a GooCanvasItem.

goo_canvas_item_ensure_updated ()

void                goo_canvas_item_ensure_updated      (GooCanvasItem *item);

This function is only intended to be used when implementing new canvas items.

It updates the canvas immediately, if an update is scheduled. This ensures that all item bounds are up-to-date.

item :

 a GooCanvasItem.

goo_canvas_item_update ()

void                goo_canvas_item_update              (GooCanvasItem *item,
                                                         gboolean entire_tree,
                                                         cairo_t *cr,
                                                         GooCanvasBounds *bounds);

This function is only intended to be used when implementing new canvas items, specifically container items such as GooCanvasGroup.

Updates the item, if needed, and any children.

item :

 a GooCanvasItem.

entire_tree :

 if the entire subtree should be updated.

cr :

 a cairo context.

bounds :

 a GooCanvasBounds to return the new bounds in.

goo_canvas_item_get_requested_area ()

gboolean            goo_canvas_item_get_requested_area  (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         GooCanvasBounds *requested_area);

This function is only intended to be used when implementing new canvas items, specifically layout items such as GooCanvasTable.

It gets the requested area of a child item.

item :

 a GooCanvasItem.

cr :

 a cairo context.

requested_area :

 a GooCanvasBounds to return the requested area in, in the parent's coordinate space.

Returns :

 TRUE if the item should be allocated space.

goo_canvas_item_get_requested_height ()

gdouble             goo_canvas_item_get_requested_height
                                                        (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         gdouble width);

This function is only intended to be used when implementing new canvas items, specifically layout items such as GooCanvasTable.

It gets the requested height of a child item, assuming it is allocated the given width. This is useful for text items whose requested height may change depending on the allocated width.

item :

 a GooCanvasItem.

cr :

 a cairo context.

width :

 the width that the item may be allocated.

Returns :

 the requested height of the item, given the allocated width, or -1 if the item doesn't support this method or its height doesn't change when allocated different widths.

goo_canvas_item_allocate_area ()

void                goo_canvas_item_allocate_area       (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *requested_area,
                                                         const GooCanvasBounds *allocated_area,
                                                         gdouble x_offset,
                                                         gdouble y_offset);

This function is only intended to be used when implementing new canvas items, specifically layout items such as GooCanvasTable.

It allocates an area to a child GooCanvasItem.

Note that the parent layout item will use a transform to move each of its children for the layout, so there is no need for the child item to reposition itself. It only needs to recalculate its device bounds.

To help recalculate the item's device bounds, the x_offset and y_offset of the child item's allocated position from its requested position are provided. Simple items can just add these to their bounds.

item :

 a GooCanvasItem.

cr :

 a cairo context.

requested_area :

 the area that the item originally requested, in the parent's coordinate space.

allocated_area :

 the area that the item has been allocated, in the parent's coordinate space.

x_offset :

 the x offset of the allocated area from the requested area in the device coordinate space.

y_offset :

 the y offset of the allocated area from the requested area in the device coordinate space.

goo_canvas_item_get_items_at ()

GList*              goo_canvas_item_get_items_at        (GooCanvasItem *item,
                                                         gdouble x,
                                                         gdouble y,
                                                         cairo_t *cr,
                                                         gboolean is_pointer_event,
                                                         gboolean parent_is_visible,
                                                         GList *found_items);

This function is only intended to be used when implementing new canvas items, specifically container items such as GooCanvasGroup.

It gets the items at the given point.

item :

 a GooCanvasItem.

x :

 the x coordinate of the point.

y :

 the y coordinate of the point.

cr :

 a cairo contect.

is_pointer_event :

 TRUE if the "pointer-events" properties of items should be used to determine which parts of the item are tested.

parent_is_visible :

 TRUE if the parent item is visible (which implies that all ancestors are also visible).

found_items :

 the list of items found so far.

Returns :

 the found_items list, with any more found items added onto the start of the list, leaving the top item first.

goo_canvas_item_paint ()

void                goo_canvas_item_paint               (GooCanvasItem *item,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *bounds,
                                                         gdouble scale);

This function is only intended to be used when implementing new canvas items, specifically container items such as GooCanvasGroup.

It paints the item and all children if they intersect the given bounds.

Note that the scale argument may be different to the current scale in the GooCanvasItem, e.g. when the canvas is being printed.

item :

 a GooCanvasItem.

cr :

 a cairo context.

bounds :

 the bounds that need to be repainted, in device space.

scale :

 the scale to use to determine whether an item should be painted. See "visibility-threshold".

goo_canvas_item_class_install_child_property ()

void                goo_canvas_item_class_install_child_property
                                                        (GObjectClass *iclass,
                                                         guint property_id,
                                                         GParamSpec *pspec);

This function is only intended to be used when implementing new canvas items, specifically layout container items such as GooCanvasTable.

It installs a child property on a canvas item class.

iclass :

 a GObjectClass

property_id :

 the id for the property

pspec :

 the GParamSpec for the property

goo_canvas_item_class_list_child_properties ()

GParamSpec**        goo_canvas_item_class_list_child_properties
                                                        (GObjectClass *iclass,
                                                         guint *n_properties);

This function is only intended to be used when implementing new canvas items, specifically layout container items such as GooCanvasTable.

It returns all child properties of a canvas item class.

iclass :

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

goo_canvas_item_class_find_child_property ()

GParamSpec*         goo_canvas_item_class_find_child_property
                                                        (GObjectClass *iclass,
                                                         const gchar *property_name);

This function is only intended to be used when implementing new canvas items, specifically layout container items such as GooCanvasTable.

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

iclass :

 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.

goo_canvas_item_get_child_property ()

void                goo_canvas_item_get_child_property  (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         const gchar *property_name,
                                                         GValue *value);

Gets a child property of child.

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

property_name :

 the name of the child property to get.

value :

 a location to return the value.

goo_canvas_item_set_child_property ()

void                goo_canvas_item_set_child_property  (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         const gchar *property_name,
                                                         const GValue *value);

Sets a child property of child.

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

property_name :

 the name of the child property to set.

value :

 the value to set the property to.

goo_canvas_item_get_child_properties ()

void                goo_canvas_item_get_child_properties
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         ...);

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

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

... :

 pairs of property names and value pointers, and a terminating NULL.

goo_canvas_item_get_child_properties_valist ()

void                goo_canvas_item_get_child_properties_valist
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         va_list var_args);

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

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

var_args :

 pairs of property names and value pointers, and a terminating NULL.

goo_canvas_item_set_child_properties ()

void                goo_canvas_item_set_child_properties
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         ...);

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

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

... :

 pairs of property names and values, and a terminating NULL.

goo_canvas_item_set_child_properties_valist ()

void                goo_canvas_item_set_child_properties_valist
                                                        (GooCanvasItem *item,
                                                         GooCanvasItem *child,
                                                         va_list var_args);

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

item :

 a GooCanvasItem.

child :

 a child GooCanvasItem.

var_args :

 pairs of property names and values, and a terminating NULL.

Property Details

The "can-focus" property

  "can-focus"                gboolean              : Read / Write

If the item can take the keyboard focus.

Default value: FALSE

The "description" property

  "description"              gchar*                : Read / Write

A description of the item for use by assistive technologies.

Default value: NULL

The "parent" property

  "parent"                   GooCanvasItem*        : Read / Write

The parent item.

The "pointer-events" property

  "pointer-events"           GooCanvasPointerEvents  : Read / Write

Specifies when the item receives pointer events.

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

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

Default value: NULL

The "tooltip" property

  "tooltip"                  gchar*                : Read / Write

The tooltip to display for the item.

Default value: NULL

The "transform" property

  "transform"                GooCairoMatrix*       : Read / Write

The transformation matrix of the item.

The "visibility" property

  "visibility"               GooCanvasItemVisibility  : Read / Write

When the canvas item is visible.

Default value: GOO_CANVAS_ITEM_VISIBLE

The "visibility-threshold" property

  "visibility-threshold"     gdouble               : Read / Write

The scale threshold at which the item becomes visible.

Allowed values: >= 0

Default value: 0

Signal Details

The "animation-finished" signal

void                user_function                      (GooCanvasItem *item,
                                                        gboolean       stopped,
                                                        gpointer       user_data)      : Run Last

Emitted when the item animation has finished.

item :

 the item that received the signal.

stopped :

 if the animation was explicitly stopped.

user_data :

 user data set when the signal handler was connected.

The "button-press-event" signal

gboolean            user_function                      (GooCanvasItem  *item,
                                                        GooCanvasItem  *target_item,
                                                        GdkEventButton *event,
                                                        gpointer        user_data)        : Run Last

Emitted when a mouse button is pressed in an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "button-release-event" signal

gboolean            user_function                      (GooCanvasItem  *item,
                                                        GooCanvasItem  *target_item,
                                                        GdkEventButton *event,
                                                        gpointer        user_data)        : Run Last

Emitted when a mouse button is released in an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "child-notify" signal

void                user_function                      (GooCanvasItem *item,
                                                        GParamSpec    *pspec,
                                                        gpointer       user_data)      : Run First / No Recursion / Has Details / No Hooks

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

item :

 the item that received the signal.

pspec :

 the GParamSpec of the changed child property.

user_data :

 user data set when the signal handler was connected.

The "enter-notify-event" signal

gboolean            user_function                      (GooCanvasItem    *item,
                                                        GooCanvasItem    *target_item,
                                                        GdkEventCrossing *event,
                                                        gpointer          user_data)        : Run Last

Emitted when the mouse enters an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "focus-in-event" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        GooCanvasItem *target_item,
                                                        GdkEventFocus *event,
                                                        gpointer       user_data)        : Run Last

Emitted when the item receives the keyboard focus.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "focus-out-event" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        GooCanvasItem *target_item,
                                                        GdkEventFocus *event,
                                                        gpointer       user_data)        : Run Last

Emitted when the item loses the keyboard focus.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "grab-broken-event" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        GooCanvasItem *target_item,
                                                        GdkEvent      *event,
                                                        gpointer       user_data)        : Run Last

Emitted when the item's keyboard or pointer grab was lost unexpectedly.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "key-press-event" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        GooCanvasItem *target_item,
                                                        GdkEventKey   *event,
                                                        gpointer       user_data)        : Run Last

Emitted when a key is pressed and the item has the keyboard focus.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "key-release-event" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        GooCanvasItem *target_item,
                                                        GdkEventKey   *event,
                                                        gpointer       user_data)        : Run Last

Emitted when a key is released and the item has the keyboard focus.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "leave-notify-event" signal

gboolean            user_function                      (GooCanvasItem    *item,
                                                        GooCanvasItem    *target_item,
                                                        GdkEventCrossing *event,
                                                        gpointer          user_data)        : Run Last

Emitted when the mouse leaves an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "motion-notify-event" signal

gboolean            user_function                      (GooCanvasItem  *item,
                                                        GooCanvasItem  *target_item,
                                                        GdkEventMotion *event,
                                                        gpointer        user_data)        : Run Last

Emitted when the mouse moves within an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.

The "query-tooltip" signal

gboolean            user_function                      (GooCanvasItem *item,
                                                        gdouble        x,
                                                        gdouble        y,
                                                        gboolean       keyboard_mode,
                                                        GtkTooltip    *tooltip,
                                                        gpointer       user_data)          : Run Last

Emitted when the mouse has paused over the item for a certain amount of time, or the tooltip was requested via the keyboard.

Note that if keyboard_mode is TRUE, the values of x and y are undefined and should not be used.

If the item wants to display a tooltip it should update tooltip and return TRUE.

item :

 the item which received the signal.

x :

 the x coordinate of the mouse.

y :

 the y coordinate of the mouse.

keyboard_mode :

 TRUE if the tooltip was triggered using the keyboard.

tooltip :

 a GtkTooltip.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE if the item has set a tooltip to show.

The "scroll-event" signal

gboolean            user_function                      (GooCanvasItem  *item,
                                                        GooCanvasItem  *target_item,
                                                        GdkEventScroll *event,
                                                        gpointer        user_data)        : Run Last

Emitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned in an item.

item :

 the item that received the signal.

target_item :

 the target of the event.

event :

 the event data. The x & y fields contain the mouse position in the item's coordinate space. The x_root & y_root fields contain the same coordinates converted to the canvas coordinate space.

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE to stop the signal emission, or FALSE to let it continue.
Generated by GTK-Doc V1.14