goocanvas.ItemModel

goocanvas.ItemModel
Prev	PyGooCanvas Core Class Reference	Next

goocanvas.ItemModel — The interface for canvas item models.

Synopsis

class goocanvas.ItemModel(gobject.GInterface):
    def add_child(item, position)
    def allocate_area(cr, requested_area, allocated_area, x_offset, y_offset)
    def animate(x, y, scale, degrees, absolute, duration, step_time, type)
    def ensure_updated()
    def find_child(child)
    def get_bounds()
    def get_canvas()
    def get_child(child_num)
    def get_child_properties(child, ...)
    def get_child_property(child, property)
    def get_item_at(x, y, cr, is_pointer_event, parent_is_visible)
    def get_model()
    def get_n_children()
    def get_parent()
    def get_requested_area(cr, requested_area)
    def get_style()
    def get_transform()
    def get_simple_transform()
    def is_container()
    def is_visible()
    def lower(below)
    def move_child(old_position, new_position)
    def paint(cr, bounds, scale)
    def raise_(above)
    def remove()
    def remove_child(child_num)
    def request_update(child_num)
    def rotate(degrees, cx, cy)
    def scale(sx, sy)
    def set_canvas(canvas)
    def set_child_properties(child, properties)
    def set_child_property(child, property)
    def set_model(model)
    def set_parent(parent)
    def set_simple_transform(x, y, scale, rotation)
    def set_style(style)
    def set_transform(matrix)
    def skew_x(degrees, cx, cy)
    def skew_y(degrees, cx, cy)
    def stop_animation()
    def translate(tx, ty)
    def update(entire_tree, cr, bounds)

Ancestry

+-- gobject.GInterface
    +-- goocanvas.ItemModel

goocanvas.ItemModel Properties

"can-focus"	Read/Write	If the item can take the keyboard focus. Default value: False
"description"	Read/Write	A description of the item for use by assistive technologies. Default value: NULL
"parent"	Read/Write	The parent item.
"pointer-events"	Read/Write	Specifies when the item receives pointer events. Default value: goocanvas.EVENTS_VISIBLE_MASK\|goocanvas.EVENTS_PAINTED_MASK\| goocanvas.EVENTS_FILL_MASK\|goocanvas.EVENTS_STROKE_MASK
"title"	Read/Write	A short context-rich description of the item for use by assistive technologies. Default value: NULL
"transform"	Read/Write	The transformation matrix of the item.
"visibility"	Read/Write	When the canvas item is visible. Default value: goocanvas.ITEM_VISIBLE.
"visibility-threshold"	Read/Write	The scale threshold at which the item becomes visible. Allowed values: >= 0 Default value: 0

goocanvas.ItemModel Signal Prototypes

"button-press-event"	`def callback(item, target_item, event, user_param, ...)`
"button-release-event"	`def callback(item, target_item, event, user_param, ...)`
"child-notify"	`def callback(item, pspec, user_param, ...)`
"enter-notify-event"	`def callback(item, target_item, event, user_param, ...)`
"focus-in-event"	`def callback(item, target_item, event, user_param, ...)`
"focus-out-event"	`def callback(item, target_item, event, user_param, ...)`
"grab-broken-event"	`def callback(item, target_item, event, user_param, ...)`
"key-press-event"	`def callback(item, target_item, event, user_param, ...)`
"key-release-event"	`def callback(item, target_item, event, user_param, ...)`
"leave-notify-event"	`def callback(item, target_item, event, user_param, ...)`
"motion-notify-event"	`def callback(item, target_item, event, user_param, ...)`

Known Implementation

goocanvas.ItemModel is implementated by goocanvas.Rect, goocanvas.Ellipse, goocanvas.Path, goocanvas.Polyline, goocanvas.Text, goocanvas.Image, goocanvas.Group, goocanvas.Widget, goocanvas.Table, goocanvas.ItemModelSimple

Description

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

Methods

goocanvas.ItemModel.add_child

    def add_child(item, position)

`item`:	The item to add.
`position`:	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.

goocanvas.ItemModel.allocate_area

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

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

This is used by goocanvas.Table and other layout items to allocate an area to each of their children.

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

The x_offset and y_offset are provided since for the simple builtin items all they need to do is add these to their bounds.

goocanvas.ItemModel.animate

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

`x`:	the final x offset from the current position.
`y`:	the final y offset from the current position.
`scale`:	the final scale of the item.
`degrees`:	the final rotation of the item.
`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.

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

goocanvas.ItemModel.ensure_updated

    def ensure_updated()

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

goocanvas.ItemModel.find_child

    def find_child(child)

`child`:	the child item to find.
Returns:	The position of the given child item, or -1 if it isn't found.

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

goocanvas.ItemModel.get_bounds

    def get_bounds()

Returns:

A tuple containing the four coordinates.

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.

goocanvas.ItemModel.get_canvas

    def get_canvas()

Returns:

The goocanvas.Canvas

Returns the goocanvas.Canvas

goocanvas.ItemModel.get_child

    def get_child(child_num)

`child_num`:	the position of a child in the container's stack.
Returns:	The child item at the given stack position.

Gets the child item at the given stack position.

goocanvas.ItemModel.get_child_properties

    def get_child_properties(child, properties)

`child`:	a child `goocanvas.ItemModel`
`properties`:	property names as string
Returns:	A tuple containing the property values.

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

goocanvas.ItemModel.get_child_property

    def get_child_property(child, property)

`child`:	a child `goocanvas.ItemModel`
`property`:	property name as string
Returns:	The property value.

Gets the value of the property of child.

goocanvas.ItemModel.get_item_at

    def get_item_at(x, y, cr, is_pointer_event, parent_is_visible)

`x`:	The x coordinate of the point.
`y`:	The y coordinate of the point.
`cr`:	A cairo context.
`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).
Returns:	The item found at the given point, or None if no item was found.

Gets the item at the given point.

goocanvas.ItemModel.get_model

    def get_model()

Returns:

the canvas model, or None of the item isn't in a model.

Gets the model of the canvas item.

goocanvas.ItemModel.get_n_children

    def get_n_children()

Returns:

The number of children.

Gets the number of children of the container.

goocanvas.ItemModel.get_parent

    def get_parent()

Returns:

The parent item, or None if the item has no parent.

Gets the parent of the given item.

goocanvas.ItemModel.get_requested_area

    def get_requested_area(cr, requested_area)

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

This is used by GooCanvasTable and other layout items to get the requested area of each of their children.

FIXME: This method is currently broken, it needs to be manually wrapped returning the bounds instead of True/False.

goocanvas.ItemModel.get_style

    def get_style()

Returns:

The item's style.

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

goocanvas.ItemModel.get_simple_transform

    def get_simple_transform()

Returns:

A 4 item tuple containing the item's x, y, scale and 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 goocanvas.ItemModel.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.

goocanvas.ItemModel.get_transform

    def get_transform()

Returns:

The item's transformation matrix.

Gets the transformation matrix of an item.

goocanvas.ItemModel.is_container

    def is_container()

Returns:

True if the item is a container.

Tests to see if the given item is a container.

goocanvas.ItemModel.is_visible

    def is_visible()

Returns:

True if the item is visible.

Tests to see if the given 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.

goocanvas.ItemModel.lower

    def lower(below)

below:

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

Lowers an item in the stacking order.

goocanvas.ItemModel.move_child

    def move_child(old_position, new_position)

`old_position`:	the current position of the child item.
`new_position`:	the new position of the child item.

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

goocanvas.ItemModel.paint

    def paint(cr, bounds, scale)

`cr`:	A cairo context.
`bounds`:	The bounds that need to be repainted.
`scale`:	the scale to use to determine whether an item should be painted. See visibility-thresold

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

goocanvas.ItemModel.raise_

    def raise_(above)

above:

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

Raises an item in the stacking order.

goocanvas.ItemModel.remove

    def remove()

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

This would normally also result in the model being freed.

goocanvas.ItemModel.remove_child

    def remove_child(child_num)

child_num:

the position of the child item to remove.

Removes the child item at the given position.

goocanvas.ItemModel.request_update

    def request_update()

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.

goocanvas.ItemModel.rotate

    def rotate(degrees, cx, cy)

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

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

goocanvas.ItemModel.scale

    def scale(sx, sy)

`sx`:	the amount to scale the horizontal axis.
`sy`:	the amount to scale the vertical axis.

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

goocanvas.ItemModel.set_canvas

    def set_canvas(canvas)

canvas:

A goocanvas.Canvas

Sets the canvas of the item.

This is only needed for setting the canvas of the root item, as the other items can get the canvas from their parents.

goocanvas.ItemModel.set_child_properties

    def set_child_properties(child, properties)

`childs`:	A child goocanvas.ItemModel
`properties`:	The properties to set as **kwargs

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

goocanvas.ItemModel.set_child_property

    def set_child_property(child, property)

`child`:	A child goocanvas.ItemModel
`property`:	The property to set as string

Sets a child property of child.

goocanvas.ItemModel.set_model

    def set_model(model)

model:

A goocanvas.ItemModelModel

Sets the model of the given canvas item.

goocanvas.ItemModel.set_parent

    def set_parent(parent)

parent:

the new parent item.

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

Note

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

goocanvas.ItemModel.set_simple_transform

    def set_simple_transform(x, y, scale, rotation)

`x`:	The x coordinate of the origin of the item's coordinate space.
`y`:	The x 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.

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

goocanvas.ItemModel.set_style

    def set_style(style)

style:

A goocanvas.Style

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

goocanvas.ItemModel.set_transform

    def set_transform(matrix)

matrix:

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

Sets the transformation matrix of an item.

goocanvas.ItemModel.skew_x

    def skew_x(degrees, cx, cy)

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

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

goocanvas.ItemModel.skew_y

    def skew_y(degrees, cx, cy)

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

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

goocanvas.ItemModel.stop_animation

    def stop_animation()

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

goocanvas.ItemModel.translate

    def translate(tx, ty)

`tx`:	the amount to move the origin in the horizontal direction.
`ty`:	the amount to move the origin in the vertical direction.

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

goocanvas.ItemModel.update

    def update(entire_tree, cr, bounds)

`entire_tree`:	If the entire subtree should be updated.
`cr`:	A cairo context.
`bounds`:	A GooCanvasBounds to return the new bounds in.

Updates the item, if needed, and any children.

Signals

The "button-press-events" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)

The "button-press-event" signal is emitted when a mouse button is pressed in an item.

The "button-press-events" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)

The "button-release-event" signal is emitted when a mouse button is released in an item.

The "child-notify" goocanvas.ItemModel Signal

    def callback(item, pspec, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`pspec`:	The GParamSpec of the changed child property.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)

The "child-notify" signal is emitted for each child property that has changed. The signal's detail holds the property name.

The "enter-notify-events" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "enter-notify-event" signal is emitted when the mouse enters an item.

The "focus-in-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "focus-in-event" signal is emitted when the item receives the keyboard focus.

The "focus-out-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "focus-out-event" signal is emitted when the item loses the keyboard focus.

The "grab-broken-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "grab-broken-event" signal is emitted when the item's keyboard or pointer grab was lost unexpectedly.

The "key-press-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "key-press-event" signal is emitted when a key is pressed and the item has the keyboard focus.

The "key-release-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "key-release-event" signal is emitted when a key is released and the item has the keyboard focus.

The "leave-notify-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "leave-notify-event" signal is emitted when the mouse leaves an item.

The "motion-notify-event" goocanvas.ItemModel Signal

    def callback(item, target_item, event, user_param, ...)

`item`:	The `goocanvas.ItemModel` that received the signal.
`target_item`:	The target of the event.
`event`:	The event data, with coordinates translated to canvas coordinates.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)
`Returns`:	True to stop the signal emission, or False to let it continue.

The "motion-notify-event" signal is emitted when the mouse moves within an item.