goocanvas.Item — The interface for canvas items.
goocanvas.Item extends, gobject.GInterface {add_child(item,
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_properties(child,
properties);get_child_property(child,
property);get_items_at(x,
y,
cr,
is_pointer_event,
parent_is_visible);get_model();get_n_children();get_parent();get_requested_area(cr);get_requested_height(cr,
width);get_style();get_simple_tranform();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(child_num);rotate(degrees,
cx,
cy);scale(sx,
sy);set_canvas(canvas);set_child_properties(child,
properties);set_child_property(child,
property);set_model(model);set_parent(parent);set_simple_transform(x,
y,
scale,
rotation);set_style(style);set_transform(matrix);skew_x(degrees,
cx,
cy);skew_y(degrees,
cx,
cy);stop_animation();translate(tx,
ty);update(entire_tree,
cr);
}
"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: None."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: None."tooltip" Read/Write The tooltip to display for the item. Default value: None."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.
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
| |
callback(item,
|
goocanvas.Item
is implementated by
goocanvas.Rect,
goocanvas.Ellipse,
goocanvas.Path,
goocanvas.Polyline,
goocanvas.Text,
goocanvas.Image,
goocanvas.Group,
goocanvas.Widget,
goocanvas.Table,
goocanvas.ItemSimple
goocanvas.Item
defines the interface that canvas items must implement, and contains methods for operating on canvas items.
add_child(item,
position);
| The item to add. |
| 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);
| A cairo context. |
| The area that the item originally requested, in the parent's coordinate space. |
| The area that the item has been allocated, in the parent's coordinate space. |
| The x offset of the allocated area from the requested area in the device coordinate space. |
| 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.
animate(x,
y,
scale,
degrees,
absolute,
duration,
step_time,
type);
| the final x offset from the current position. |
| the final y offset from the current position. |
| the final scale of the item. |
| the final rotation of the item. |
| 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. |
| the duration of the animation, in milliseconds (1/1000ths of a second). |
| the time between each animation step, in milliseconds. |
| specifies what happens when the animation finishes. |
Animates an item from its current position to the given offsets, scale and rotation.
ensure_updated();Updates the canvas immediately, if an update is scheduled. This ensures that all item bounds are up-to-date.
find_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.
get_bounds();Returns : | A goocanvas.Bounds
holding 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.
get_child(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.
get_child_properties(child,
properties);
| a child
goocanvas.Item
|
| property names as string |
Returns : | A tuple containing the property values. |
Gets the values of one or more child properties of child.
get_child_property(child,
property);
| a child
goocanvas.Item
|
| property name as string |
Returns : | The property value. |
Gets a child property of child.
get_items_at(x,
y,
cr,
is_pointer_event,
parent_is_visible);
| The x coordinate of the point. |
| The y coordinate of the point. |
| A cairo context. |
| True if the "pointer-events" properties of items should be used to determine which parts of the item are tested. |
| True if the parent item is visible (which implies that all ancestors are also visible). |
Returns : | A list of items found at the given point, or None if no item was found. |
Gets the items at the given point.
get_model();Returns : | the canvas model, or None of the item isn't in a model. |
Gets the model of the canvas item.
get_n_children();Returns : | The number of children. |
Gets the number of children of the container.
get_parent();Returns : | The parent item, or None if the item has no parent. |
Gets the parent of the given item.
get_requested_area(cr);
| A cairo context. |
Returns : | A goocanvas.Bounds
containing the requested area. |
This function is only intended to be used when implementing new canvas items, specifically layout items such as
goocanvas.Table.
It gets the requested area of a child item.
get_requested_height(cr,
width);
| A cairo context. |
| 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. |
This function is only intended to be used when implementing new canvas items,
specifically layout items such as
goocanvas.Table.
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_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.
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.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.
get_transform();Returns : | The item's transformation matrix. |
Gets the transformation matrix of an item.
get_transform_for_child(child);
| A child of item. |
Returns : | The transformation matrix or None |
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.Table.
is_container();Returns : | True if the item is a container. |
Tests to see if the given item is a container.
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.
lower(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.
move_child(old_position,
new_position);
| the current position of the child item. |
| the new position of the child item. |
Moves a child item to a new stack position within the container.
paint(cr,
bounds,
scale);
| A cairo context. |
| The bounds that need to be repainted. |
| 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.
raise_(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.
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);
| the position of the child item to remove. |
Removes the child item at the given position.
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.
rotate(degrees,
cx,
cy);
| the clockwise angle of rotation. |
| the x coordinate of the origin of the rotation. |
| 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);
| the amount to scale the horizontal axis. |
| the amount to scale the vertical axis. |
Scales the item's coordinate system by the given amounts.
set_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.
set_child_properties(child,
properties);
| A child goocanvas.Item |
| The properties to set as **kwargs |
Sets the values of one or more child properties of child.
set_child_property(child,
property,
value);
| A child goocanvas.Item |
| The property to set as string |
| The value to set for the property. |
Sets a child property of child.
set_model(model);
| A goocanvas.ItemModel |
Sets the model of the given canvas item.
set_parent(parent);
| the new parent item. |
This method is only intended to be used when implementing new canvas items (specifically container items such as goocanvas.Group). It sets the parent of the child item.
set_simple_transform(x,
y,
scale,
rotation);
| The x coordinate of the origin of the item's coordinate space. |
| The x coordinate of the origin of the item's coordinate space. |
| The scale of the item. |
| The clockwise rotation of the item, in degrees. |
A convenience function to set the item's transformation matrix.
set_style(style);
| A goocanvas.Style |
Sets the item's style, by copying the properties from the given style.
set_transform(matrix);
| 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);
| the skew angle. |
| the x coordinate of the origin of the skew transform. |
| 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);
| the skew angle. |
| the x coordinate of the origin of the skew transform. |
| 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);
| the amount to move the origin in the horizontal direction. |
| 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);
| If the entire subtree should be updated. |
| A cairo context. |
Returns : | A goocanvas.Bounds
containing the requested area. |
This function is only intended to be used when implementing new canvas items, specifically layout items such as
goocanvas.Group.
Updates the item, if needed, and any children, returning the bounding box.
callback(item,
stopped,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| if the animation was explicitly stopped. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
The "animation-finished" signal is emitted when the item animation has finished.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| 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.
callback(item,
pspec,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The GParamSpec of the changed child property. |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data, with coordinates translated to canvas coordinates. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data, with coordinates translated to canvas coordinates. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data, with coordinates translated to canvas coordinates. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data, with coordinates translated to canvas coordinates. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data, with coordinates translated to canvas coordinates. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| 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.
callback(item,
x,
y,
keyboard_mode,
tooltip,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| the x coordinate of the mouse. |
| the y coordinate of the mouse. |
|
True if the tooltip was triggered using the keyboard.
|
|
a gtk.Tooltip
|
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| True to stop the signal emission, or False to let it continue. |
The "query-tooltip" signal is 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.
callback(item,
target_item,
event,
user_param,
...);
|
The goocanvas.Item
that received the signal.
|
| The target of the event. |
| The event data. The x and y fields contain the mouse position in the item's coordinate space. The root_x and root_y fields contain the same coordinates converted to the canvas coordinate space. |
| the first user parameter (if any) specified
with the connect()
method
|
| additional user parameters (if any) |
| True to stop the signal emission, or False to let it continue. |
The "scroll-event" signal is 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.