GooCanvas.CanvasItem¶

Implementations:: GooCanvas.CanvasItemSimple

Methods¶

class	`class_find_child_property` (iclass, property_name)
class	`class_install_child_property` (iclass, property_id, pspec)
class	`class_list_child_properties` (iclass)
	`add_child` (child, position)
	`allocate_area` (cr, requested_area, allocated_area, x_offset, y_offset)
	`animate` (x, y, scale, degrees, absolute, duration, step_time, type)
	`ensure_updated` ()
	`find_child` (child)
	`get_bounds` ()
	`get_canvas` ()
	`get_child` (child_num)
	`get_child_property` (child, property_name, value)
	`get_is_static` ()
	`get_items_at` (x, y, cr, is_pointer_event, parent_is_visible, found_items)
	`get_model` ()
	`get_n_children` ()
	`get_parent` ()
	`get_requested_area` (cr, requested_area)
	`get_requested_area_for_width` (cr, width, requested_area)
	`get_requested_height` (cr, width)
	`get_simple_transform` ()
	`get_style` ()
	`get_transform` ()
	`get_transform_for_child` (child)
	`is_container` ()
	`is_visible` ()
	`lower` (below)
	`move_child` (old_position, new_position)
	`paint` (cr, bounds, scale)
	`raise_` (above)
	`remove` ()
	`remove_child` (child_num)
	`request_update` ()
	`rotate` (degrees, cx, cy)
	`scale` (sx, sy)
	`set_canvas` (canvas)
	`set_child_property` (child, property_name, value)
	`set_is_static` (is_static)
	`set_model` (model)
	`set_parent` (parent)
	`set_simple_transform` (x, y, scale, rotation)
	`set_style` (style)
	`set_transform` (transform)
	`skew_x` (degrees, cx, cy)
	`skew_y` (degrees, cx, cy)
	`stop_animation` ()
	`translate` (tx, ty)
	`update` (entire_tree, cr, bounds)

Virtual Methods¶

	`do_add_child` (child, position)
	`do_allocate_area` (cr, requested_area, allocated_area, x_offset, y_offset)
	`do_animation_finished` (stopped)
	`do_button_press_event` (target, event)
	`do_button_release_event` (target, event)
	`do_child_notify` (pspec)
	`do_enter_notify_event` (target, event)
	`do_focus_in_event` (target, event)
	`do_focus_out_event` (target, event)
	`do_get_bounds` ()
	`do_get_canvas` ()
	`do_get_child` (child_num)
	`do_get_child_property` (child, property_id, value, pspec)
	`do_get_is_static` ()
	`do_get_items_at` (x, y, cr, is_pointer_event, parent_is_visible, found_items)
	`do_get_model` ()
	`do_get_n_children` ()
	`do_get_parent` ()
	`do_get_requested_area` (cr, requested_area)
	`do_get_requested_area_for_width` (cr, width, requested_area)
	`do_get_requested_height` (cr, width)
	`do_get_style` ()
	`do_get_transform` ()
	`do_get_transform_for_child` (child)
	`do_grab_broken_event` (target, event)
	`do_is_visible` ()
	`do_key_press_event` (target, event)
	`do_key_release_event` (target, event)
	`do_leave_notify_event` (target, event)
	`do_motion_notify_event` (target, event)
	`do_move_child` (old_position, new_position)
	`do_paint` (cr, bounds, scale)
	`do_query_tooltip` (x, y, keyboard_tooltip, tooltip)
	`do_remove_child` (child_num)
	`do_request_update` ()
	`do_scroll_event` (target, event)
	`do_set_canvas` (canvas)
	`do_set_child_property` (child, property_id, value, pspec)
	`do_set_is_static` (is_static)
	`do_set_model` (model)
	`do_set_parent` (parent)
	`do_set_style` (style)
	`do_set_transform` (transform)
	`do_update` (entire_tree, cr, bounds)

Properties¶

Name	Type	Flags	Short Description
`can-focus`	`bool`	r/w	If the item can take the keyboard focus
`description`	`str`	r/w	A description of the item for use by assistive technologies
`parent`	`GooCanvas.CanvasItem`	r/w	The parent item
`pointer-events`	`GooCanvas.CanvasPointerEvents`	r/w	Specifies when the item receives pointer events
`title`	`str`	r/w	A short context-rich description of the item for use by assistive technologies
`tooltip`	`str`	r/w	The tooltip to display for the item
`transform`		r/w	The transformation matrix of the item
`visibility`	`GooCanvas.CanvasItemVisibility`	r/w	When the canvas item is visible
`visibility-threshold`	`float`	r/w	The scale threshold at which the item becomes visible

Signals¶

Name	Short Description
`animation-finished`	Emitted when the item animation has finished.
`button-press-event`	Emitted when a mouse button is pressed in an item.
`button-release-event`	Emitted when a mouse button is released in an item.
`child-notify`	Emitted for each child property that has changed.
`enter-notify-event`	Emitted when the mouse enters an item.
`focus-in-event`	Emitted when the item receives the keyboard focus.
`focus-out-event`	Emitted when the item loses the keyboard focus.
`grab-broken-event`	Emitted when the item’s keyboard or pointer grab was lost unexpectedly.
`key-press-event`	Emitted when a key is pressed and the item has the keyboard focus.
`key-release-event`	Emitted when a key is released and the item has the keyboard focus.
`leave-notify-event`	Emitted when the mouse leaves an item.
`motion-notify-event`	Emitted when the mouse moves within an item.
`query-tooltip`	Emitted when the mouse has paused over the item for a certain amount of time, or the tooltip was requested via the keyboard.
`scroll-event`	Emitted when a button in the 4 to 7 range is pressed.

Fields¶

None

Class Details¶

class GooCanvas.CanvasItem¶

Bases:: GObject.GInterface
Structure:: GooCanvas.CanvasItemIface

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

classmethod class_find_child_property(iclass, property_name)¶

Parameters:

iclass (GObject.ObjectClass) – a GObject.ObjectClass
property_name (str) – the name of the child property to find

Returns:

the GObject.ParamSpec of the child property or None if class has no child property with that name.

Return type:

GObject.ParamSpec

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

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

classmethod class_install_child_property(iclass, property_id, pspec)¶

Parameters:

iclass (GObject.ObjectClass) – a GObject.ObjectClass
property_id (int) – the id for the property
pspec (GObject.ParamSpec) – the GObject.ParamSpec for the property

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

It installs a child property on a canvas item class.

classmethod class_list_child_properties(iclass)¶

Parameters:: iclass (GObject.ObjectClass) – a GObject.ObjectClass
Returns:: a newly allocated array of GObject.ParamSpec. The array must be freed with GLib.free().
Return type:: [GObject.ParamSpec]

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

It returns all child properties of a canvas item class.

add_child(child, position)¶

Parameters:

child (GooCanvas.CanvasItem) – the item to add.
position (int) – the position of the item, or -1 to place it last (at the top of the stacking order).

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

allocate_area(cr, requested_area, allocated_area, x_offset, y_offset)¶

Parameters:

cr (cairo.Context) – a cairo context.
requested_area (GooCanvas.CanvasBounds) – the area that the item originally requested, in the parent’s coordinate space.
allocated_area (GooCanvas.CanvasBounds) – the area that the item has been allocated, in the parent’s coordinate space.
x_offset (float) – the x offset of the allocated area from the requested area in the device coordinate space.
y_offset (float) – the y offset of the allocated area from the requested area in the device coordinate space.

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

It allocates an area to a child GooCanvas.CanvasItem.

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.

animate(x, y, scale, degrees, absolute, duration, step_time, type)¶

Parameters:

x (float) – the final x coordinate.
y (float) – the final y coordinate.
scale (float) – the final scale.
degrees (float) – the final rotation. This can be negative to rotate anticlockwise, and can also be greater than 360 to rotate a number of times.
absolute (bool) – 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 GooCanvas.simple transform. If the item has a shear or some other complicated transform it may result in strange animations.
duration (int) – the duration of the animation, in milliseconds (1/1000ths of a second).
step_time (int) – the time between each animation step, in milliseconds.
type (GooCanvas.CanvasAnimateType) – specifies what happens when the animation finishes.

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

ensure_updated()¶

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.

find_child(child)¶

Parameters:: child (GooCanvas.CanvasItem) – the child item to find.
Returns:: the position of the given child item, or -1 if it isn’t found.
Return type:: int

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

get_bounds()¶

Returns:: a GooCanvas.CanvasBounds to return the bounds in.
Return type:: bounds: GooCanvas.CanvasBounds

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.

get_canvas()¶

Returns:: the GooCanvas.Canvas.
Return type:: GooCanvas.Canvas

Returns the GooCanvas.Canvas containing the given GooCanvas.CanvasItem.

get_child(child_num)¶

Parameters:: child_num (int) – the position of a child in the container’s stack.
Returns:: the child item at the given stack position, or None if child_num is out of range.
Return type:: GooCanvas.CanvasItem

Gets the child item at the given stack position.

get_child_property(child, property_name, value)¶

Parameters:

child (GooCanvas.CanvasItem) – a child GooCanvas.CanvasItem.
property_name (str) – the name of the child property to get.
value (GObject.Value) – a location to return the value.

Gets a child property of child.

get_is_static()¶

Returns:: True if the item is static.
Return type:: bool

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

get_items_at(x, y, cr, is_pointer_event, parent_is_visible, found_items)¶

Parameters:

x (float) – the x coordinate of the point.
y (float) – the y coordinate of the point.
cr (cairo.Context) – a cairo contect.
is_pointer_event (bool) – True if the “pointer-events” properties of items should be used to determine which parts of the item are tested.
parent_is_visible (bool) – True if the parent item is visible (which implies that all ancestors are also visible).
found_items ([GooCanvas.CanvasItem]) – 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.

Return type:

[GooCanvas.CanvasItem]

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

It gets the items at the given point.

get_model()¶

Returns:: the item’s model, or None if it has no model.
Return type:: GooCanvas.CanvasItemModel

Gets the model of the given canvas item.

get_n_children()¶

Returns:: the number of children.
Return type:: int

Gets the number of children of the container.

get_parent()¶

Returns:: the parent item, or None if the item has no parent.
Return type:: GooCanvas.CanvasItem

Gets the parent of the given item.

get_requested_area(cr, requested_area)¶

Parameters:

cr (cairo.Context) – a cairo context.
requested_area (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the requested area in, in the parent’s coordinate space.

Returns:

True if the item should be allocated space.

Return type:

bool

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

It gets the requested area of a child item.

get_requested_area_for_width(cr, width, requested_area)¶

Parameters:

cr (cairo.Context) – a cairo context.
width (float) – the allocated width.
requested_area (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the requested area in, in the parent’s coordinate space. If False is returned, this is undefined.

Returns:

True if the item’s requested area changes due to the new allocated width.

Return type:

bool

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

It gets the requested area 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.

New in version 2.0.1.

get_requested_height(cr, width)¶

Parameters:

cr (cairo.Context) – a cairo context.
width (float) – 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.

Return type:

float

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

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.

get_simple_transform()¶

Returns:

True if a transform is set.

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

Return type:

(bool, x: float, y: float, scale: float, rotation: float)

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

get_style()¶

Returns:: the item’s style.
Return type:: GooCanvas.CanvasStyle

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

get_transform()¶

Returns:

True if a transform is set.

transform:: the place to store the transform.

Return type:

(bool, transform: cairo.Matrix)

Gets the transformation matrix of an item.

get_transform_for_child(child)¶

Parameters:

child (GooCanvas.CanvasItem) – a child of self.

Returns:

True if a transform is set.

transform:: the place to store the transform.

Return type:

(bool, transform: cairo.Matrix)

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 GooCanvas.CanvasTable.

is_container()¶

Returns:: True if the item is a container.
Return type:: bool

Tests to see if the given item is a container.

is_visible()¶

Returns:: True if the item is visible.
Return type:: bool

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.

lower(below)¶

Parameters:: below (GooCanvas.CanvasItem or None) – the item to lower self below, or None to lower self to the bottom of the stack.

Lowers an item in the stacking order.

move_child(old_position, new_position)¶

Parameters:

old_position (int) – the current position of the child item.
new_position (int) – the new position of the child item.

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

paint(cr, bounds, scale)¶

Parameters:

cr (cairo.Context) – a cairo context.
bounds (GooCanvas.CanvasBounds) – the bounds that need to be repainted, in device space.
scale (float) – the scale to use to determine whether an item should be painted. See GooCanvas.CanvasItem :visibility-threshold.

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

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 GooCanvas.CanvasItem, e.g. when the canvas is being printed.

raise_(above)¶

Parameters:: above (GooCanvas.CanvasItem or None) – the item to raise self above, or None to raise self to the top of the stack.

Raises an item in the stacking order.

remove()¶

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.

remove_child(child_num)¶

Parameters:: child_num (int) – the position of the child item to remove.

Removes the child item at the given position.

request_update()¶

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.

rotate(degrees, cx, cy)¶

Parameters:

degrees (float) – the clockwise angle of rotation.
cx (float) – the x coordinate of the origin of the rotation.
cy (float) – the y coordinate of the origin of the rotation.

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

scale(sx, sy)¶

Parameters:

sx (float) – the amount to scale the horizontal axis.
sy (float) – the amount to scale the vertical axis.

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

set_canvas(canvas)¶

Parameters:: canvas (GooCanvas.Canvas) – a GooCanvas.Canvas

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

It sets the canvas of the item.

set_child_property(child, property_name, value)¶

Parameters:

child (GooCanvas.CanvasItem) – a child GooCanvas.CanvasItem.
property_name (str) – the name of the child property to set.
value (GObject.Value) – the value to set the property to.

Sets a child property of child.

set_is_static(is_static)¶

Parameters:: is_static (bool) – if the item 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 GooCanvas.CanvasGroup 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.

set_model(model)¶

Parameters:: model (GooCanvas.CanvasItemModel) – a GooCanvas.CanvasItemModel.

Sets the model of the given canvas item.

set_parent(parent)¶

Parameters:: parent (GooCanvas.CanvasItem) – the new parent item.

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

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 GooCanvas.CanvasItem :parent property.

set_simple_transform(x, y, scale, rotation)¶

Parameters:

x (float) – the x coordinate of the origin of the item’s coordinate space.
y (float) – the y coordinate of the origin of the item’s coordinate space.
scale (float) – the scale of the item.
rotation (float) – the clockwise rotation of the item, in degrees.

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

set_style(style)¶

Parameters:: style (GooCanvas.CanvasStyle) – a style.

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

set_transform(transform)¶

Parameters:: transform (cairo.Matrix or None) – the new transformation matrix, or None to reset the transformation to the identity matrix.

Sets the transformation matrix of an item.

skew_x(degrees, cx, cy)¶

Parameters:

degrees (float) – the skew angle.
cx (float) – the x coordinate of the origin of the skew transform.
cy (float) – the y coordinate of the origin of the skew transform.

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

skew_y(degrees, cx, cy)¶

Parameters:

degrees (float) – the skew angle.
cx (float) – the x coordinate of the origin of the skew transform.
cy (float) – the y coordinate of the origin of the skew transform.

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

stop_animation()¶: Stops any current animation for the given item, leaving it at its current position.

translate(tx, ty)¶

Parameters:

tx (float) – the amount to move the origin in the horizontal direction.
ty (float) – the amount to move the origin in the vertical direction.

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

update(entire_tree, cr, bounds)¶

Parameters:

entire_tree (bool) – if the entire subtree should be updated.
cr (cairo.Context) – a cairo context.
bounds (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the new bounds in.

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

Updates the item, if needed, and any children.

do_add_child(child, position) virtual¶

Parameters:

child (GooCanvas.CanvasItem) – the item to add.
position (int) – the position of the item, or -1 to place it last (at the top of the stacking order).

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

do_allocate_area(cr, requested_area, allocated_area, x_offset, y_offset) virtual¶

Parameters:

cr (cairo.Context) – a cairo context.
requested_area (GooCanvas.CanvasBounds) – the area that the item originally requested, in the parent’s coordinate space.
allocated_area (GooCanvas.CanvasBounds) – the area that the item has been allocated, in the parent’s coordinate space.
x_offset (float) – the x offset of the allocated area from the requested area in the device coordinate space.
y_offset (float) – the y offset of the allocated area from the requested area in the device coordinate space.

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

It allocates an area to a child GooCanvas.CanvasItem.

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.

do_animation_finished(stopped) virtual¶

Parameters:: stopped (bool) –

do_button_press_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventButton) –

Return type:

bool

do_button_release_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventButton) –

Return type:

bool

do_child_notify(pspec) virtual¶

Parameters:: pspec (GObject.ParamSpec) –

do_enter_notify_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventCrossing) –

Return type:

bool

do_focus_in_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventFocus) –

Return type:

bool

do_focus_out_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventFocus) –

Return type:

bool

do_get_bounds() virtual¶

Returns:: a GooCanvas.CanvasBounds to return the bounds in.
Return type:: bounds: GooCanvas.CanvasBounds

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.

do_get_canvas() virtual¶

Returns:: the GooCanvas.Canvas.
Return type:: GooCanvas.Canvas

Returns the GooCanvas.Canvas containing the given GooCanvas.CanvasItem.

do_get_child(child_num) virtual¶

Parameters:: child_num (int) – the position of a child in the container’s stack.
Returns:: the child item at the given stack position, or None if child_num is out of range.
Return type:: GooCanvas.CanvasItem

Gets the child item at the given stack position.

do_get_child_property(child, property_id, value, pspec) virtual¶

Parameters:

child (GooCanvas.CanvasItem) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

do_get_is_static() virtual¶

Returns:: True if the item is static.
Return type:: bool

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

do_get_items_at(x, y, cr, is_pointer_event, parent_is_visible, found_items) virtual¶

Parameters:

x (float) – the x coordinate of the point.
y (float) – the y coordinate of the point.
cr (cairo.Context) – a cairo contect.
is_pointer_event (bool) – True if the “pointer-events” properties of items should be used to determine which parts of the item are tested.
parent_is_visible (bool) – True if the parent item is visible (which implies that all ancestors are also visible).
found_items ([GooCanvas.CanvasItem]) – 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.

Return type:

[GooCanvas.CanvasItem]

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

It gets the items at the given point.

do_get_model() virtual¶

Returns:: the item’s model, or None if it has no model.
Return type:: GooCanvas.CanvasItemModel

Gets the model of the given canvas item.

do_get_n_children() virtual¶

Returns:: the number of children.
Return type:: int

Gets the number of children of the container.

do_get_parent() virtual¶

Returns:: the parent item, or None if the item has no parent.
Return type:: GooCanvas.CanvasItem

Gets the parent of the given item.

do_get_requested_area(cr, requested_area) virtual¶

Parameters:

cr (cairo.Context) – a cairo context.
requested_area (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the requested area in, in the parent’s coordinate space.

Returns:

True if the item should be allocated space.

Return type:

bool

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

It gets the requested area of a child item.

do_get_requested_area_for_width(cr, width, requested_area) virtual¶

Parameters:

cr (cairo.Context) – a cairo context.
width (float) – the allocated width.
requested_area (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the requested area in, in the parent’s coordinate space. If False is returned, this is undefined.

Returns:

True if the item’s requested area changes due to the new allocated width.

Return type:

bool

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

It gets the requested area 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.

New in version 2.0.1.

do_get_requested_height(cr, width) virtual¶

Parameters:

cr (cairo.Context) – a cairo context.
width (float) – 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.

Return type:

float

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

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.

do_get_style() virtual¶

Returns:: the item’s style.
Return type:: GooCanvas.CanvasStyle

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

do_get_transform() virtual¶

Returns:

True if a transform is set.

transform:: the place to store the transform.

Return type:

(bool, transform: cairo.Matrix)

Gets the transformation matrix of an item.

do_get_transform_for_child(child) virtual¶

Parameters:

child (GooCanvas.CanvasItem) – a child of item.

Returns:

True if a transform is set.

transform:: the place to store the transform.

Return type:

(bool, transform: cairo.Matrix)

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 GooCanvas.CanvasTable.

do_grab_broken_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventGrabBroken) –

Return type:

bool

do_is_visible() virtual¶

Returns:: True if the item is visible.
Return type:: bool

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.

do_key_press_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventKey) –

Return type:

bool

do_key_release_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventKey) –

Return type:

bool

do_leave_notify_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventCrossing) –

Return type:

bool

do_motion_notify_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventMotion) –

Return type:

bool

do_move_child(old_position, new_position) virtual¶

Parameters:

old_position (int) – the current position of the child item.
new_position (int) – the new position of the child item.

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

do_paint(cr, bounds, scale) virtual¶

Parameters:

cr (cairo.Context) – a cairo context.
bounds (GooCanvas.CanvasBounds) – the bounds that need to be repainted, in device space.
scale (float) – the scale to use to determine whether an item should be painted. See GooCanvas.CanvasItem :visibility-threshold.

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

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 GooCanvas.CanvasItem, e.g. when the canvas is being printed.

do_query_tooltip(x, y, keyboard_tooltip, tooltip) virtual¶

Parameters:

x (float) –
y (float) –
keyboard_tooltip (bool) –
tooltip (Gtk.Tooltip) –

Return type:

bool

do_remove_child(child_num) virtual¶

Parameters:: child_num (int) – the position of the child item to remove.

Removes the child item at the given position.

do_request_update() virtual¶

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.

do_scroll_event(target, event) virtual¶

Parameters:

target (GooCanvas.CanvasItem) –
event (Gdk.EventScroll) –

Return type:

bool

do_set_canvas(canvas) virtual¶

Parameters:: canvas (GooCanvas.Canvas) – a GooCanvas.Canvas

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

It sets the canvas of the item.

do_set_child_property(child, property_id, value, pspec) virtual¶

Parameters:

child (GooCanvas.CanvasItem) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

do_set_is_static(is_static) virtual¶

Parameters:: is_static (bool) – if the item 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 GooCanvas.CanvasGroup 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.

do_set_model(model) virtual¶

Parameters:: model (GooCanvas.CanvasItemModel) – a GooCanvas.CanvasItemModel.

Sets the model of the given canvas item.

do_set_parent(parent) virtual¶

Parameters:: parent (GooCanvas.CanvasItem) – the new parent item.

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

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 GooCanvas.CanvasItem :parent property.

do_set_style(style) virtual¶

Parameters:: style (GooCanvas.CanvasStyle) – a style.

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

do_set_transform(transform) virtual¶

Parameters:: transform (cairo.Matrix or None) – the new transformation matrix, or None to reset the transformation to the identity matrix.

Sets the transformation matrix of an item.

do_update(entire_tree, cr, bounds) virtual¶

Parameters:

entire_tree (bool) – if the entire subtree should be updated.
cr (cairo.Context) – a cairo context.
bounds (GooCanvas.CanvasBounds) – a GooCanvas.CanvasBounds to return the new bounds in.

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

Updates the item, if needed, and any children.

Signal Details¶

GooCanvas.CanvasItem.signals.animation_finished(canvas_item, stopped)¶

Signal Name:

animation-finished

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
stopped (bool) – if the animation was explicitly stopped.

Emitted when the item animation has finished.

GooCanvas.CanvasItem.signals.button_press_event(canvas_item, target_item, event)¶

Signal Name:

button-press-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventButton) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when a mouse button is pressed in an item.

GooCanvas.CanvasItem.signals.button_release_event(canvas_item, target_item, event)¶

Signal Name:

button-release-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventButton) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when a mouse button is released in an item.

GooCanvas.CanvasItem.signals.child_notify(canvas_item, pspec)¶

Signal Name:

child-notify

Flags:

RUN_FIRST, NO_RECURSE, DETAILED, NO_HOOKS

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
pspec (GObject.ParamSpec) – the GObject.ParamSpec of the changed child property.

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

GooCanvas.CanvasItem.signals.enter_notify_event(canvas_item, target_item, event)¶

Signal Name:

enter-notify-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventCrossing) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when the mouse enters an item.

GooCanvas.CanvasItem.signals.focus_in_event(canvas_item, target_item, event)¶

Signal Name:

focus-in-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventFocus) – the event data.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when the item receives the keyboard focus.

GooCanvas.CanvasItem.signals.focus_out_event(canvas_item, target_item, event)¶

Signal Name:

focus-out-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventFocus) – the event data.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when the item loses the keyboard focus.

GooCanvas.CanvasItem.signals.grab_broken_event(canvas_item, target_item, event)¶

Signal Name:

grab-broken-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventGrabBroken) – the event data.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

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

GooCanvas.CanvasItem.signals.key_press_event(canvas_item, target_item, event)¶

Signal Name:

key-press-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventKey) – the event data.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

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

GooCanvas.CanvasItem.signals.key_release_event(canvas_item, target_item, event)¶

Signal Name:

key-release-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventKey) – the event data.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

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

GooCanvas.CanvasItem.signals.leave_notify_event(canvas_item, target_item, event)¶

Signal Name:

leave-notify-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventCrossing) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when the mouse leaves an item.

GooCanvas.CanvasItem.signals.motion_notify_event(canvas_item, target_item, event)¶

Signal Name:

motion-notify-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventMotion) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

Emitted when the mouse moves within an item.

GooCanvas.CanvasItem.signals.query_tooltip(canvas_item, x, y, keyboard_mode, tooltip)¶

Signal Name:

query-tooltip

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
x (float) – the x coordinate of the mouse.
y (float) – the y coordinate of the mouse.
keyboard_mode (bool) – True if the tooltip was triggered using the keyboard.
tooltip (Gtk.Tooltip) – a Gtk.Tooltip.

Returns:

True if the item has set a tooltip to show.

Return type:

bool

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.

GooCanvas.CanvasItem.signals.scroll_event(canvas_item, target_item, event)¶

Signal Name:

scroll-event

Flags:

RUN_LAST

Parameters:

canvas_item (GooCanvas.CanvasItem) – The object which received the signal
target_item (GooCanvas.CanvasItem) – the target of the event.
event (Gdk.EventScroll) – 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.

Returns:

True to stop the signal emission, or False to let it continue.

Return type:

bool

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.

Property Details¶

GooCanvas.CanvasItem.props.can_focus¶

Name:: can-focus
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

If the item can take the keyboard focus

GooCanvas.CanvasItem.props.description¶

Name:: description
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

A description of the item for use by assistive technologies

GooCanvas.CanvasItem.props.parent¶

Name:: parent
Type:: GooCanvas.CanvasItem
Default Value:: None
Flags:: READABLE, WRITABLE

The parent item

GooCanvas.CanvasItem.props.pointer_events¶

Name:: pointer-events
Type:: GooCanvas.CanvasPointerEvents
Default Value:: GooCanvas.CanvasPointerEvents.VISIBLE_MASK | GooCanvas.CanvasPointerEvents.PAINTED_MASK | GooCanvas.CanvasPointerEvents.FILL_MASK | GooCanvas.CanvasPointerEvents.STROKE_MASK | GooCanvas.CanvasPointerEvents.VISIBLE_PAINTED | GooCanvas.CanvasPointerEvents.VISIBLE_FILL | GooCanvas.CanvasPointerEvents.VISIBLE_STROKE | GooCanvas.CanvasPointerEvents.VISIBLE | GooCanvas.CanvasPointerEvents.PAINTED | GooCanvas.CanvasPointerEvents.FILL | GooCanvas.CanvasPointerEvents.STROKE | GooCanvas.CanvasPointerEvents.ALL
Flags:: READABLE, WRITABLE

Specifies when the item receives pointer events

GooCanvas.CanvasItem.props.title¶

Name:: title
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

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

GooCanvas.CanvasItem.props.tooltip¶

Name:: tooltip
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The tooltip to display for the item, or None to display no tooltip.

Note that this property has no effect unless the Gtk.Widget :has-tooltip property is set to True on the GooCanvas.Canvas containing this item.

GooCanvas.CanvasItem.props.transform¶

Name:: transform
Type:
Default Value:: None
Flags:: READABLE, WRITABLE

The transformation matrix of the item

GooCanvas.CanvasItem.props.visibility¶

Name:: visibility
Type:: GooCanvas.CanvasItemVisibility
Default Value:: GooCanvas.CanvasItemVisibility.VISIBLE
Flags:: READABLE, WRITABLE

When the canvas item is visible

GooCanvas.CanvasItem.props.visibility_threshold¶

Name:: visibility-threshold
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE

The scale threshold at which the item becomes visible