goocanvas.Canvas

goocanvas.Canvas
Prev	PyGooCanvas Core Class Reference	Next

goocanvas.Canvas — The Canvas

Synopsis

class goocanvas.Canvas(gtk.Container):
    goocanvas.Canvas()
    def convert_from_item_space(item, x, y)
    def convert_to_item_space(item, x, y)
    def convert_from_pixel(x, y)
    def convert_to_pixel(x, y)
    def create_cairo_context()
    def create_item(model)
    def get_bounds()
    def get_default_line_width()
    def get_item(model)
    def get_item_at(x, y, is_pointer_event)
    def get_items_at(x, y, is_pointer_event)
    def get_items_in_area(area, inside_area, allow_overlaps, including_containers)
    def get_root_item()
    def get_root_item_model()
    def get_scale()
    def grab_focus(item)
    def keyboard_grab(item, owner_events, time)
    def keyboard_ungrab(item, time)
    def pointer_grab(item, event_mask, cursor, time)
    def pointer_ungrab(item, time)
    def register_widget_item(witem)
    def render(cr, bounds, scale)
    def request_redraw(bounds)
    def request_update()
    def scroll_to(left, top)
    def set_bounds(left, top, right, bottom)
    def set_root_item(item)
    def set_root_item_model(model)
    def set_scale(scale)
    def unregister_item(model)
    def unregister_widget_item(witem)
    def update()

Ancestry

+-- gobject.GObject
	+-- gtk.Object
		+-- gtk.Widget
			+-- gtk.Container
				+-- goocanvas.Canvas

goocanvas.Canvas Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"anchor"	Read/Write	Where to place the canvas when it is smaller than the widget's allocated area. Default value: gtk.ANCHOR_NORTH_WEST
"automatic-bounds"	Read/Write	If the bounds are automatically calculated based on the bounds of all the items in the canvas.
"bounds-from-origin"	Read/Write	If the automatic bounds are calculated from the origin.
"bounds-padding"	Read/Write	The padding added to the automatic bounds.
"clear-background"	Read/Write	If the background is cleared before the canvas is painted. Default value: `True`
"integer-layout"	Read/Write	If all item layout is done to the nearest integer.
"resolution_x"	Read/Write	The horizontal resolution of the display, in dots per inch. Allowed values: >= 0 Default value: 96
"resolution_y"	Read/Write	The vertical resolution of the display, in dots per inch. Allowed values: >= 0 Default value: 96
"scale"	Read/Write	The number of pixels to use for each device unit. Allowed values: >= 0 Default value: 1
"scale-x"	Read/Write	The horizontal magnification factor of the canvas.
"scale-y"	Read/Write	The vertical magnification factor of the canvas.
"x1"	Read/Write	The x coordinate of the left edge of the canvas bounds, in device units. Default value: 0.
"x2"	Read/Write	The x coordinate of the right edge of the canvas bounds, in device units. Default value: 1000.
"y1"	Read/Write	The y coordinate at the top edge of the canvas bounds, in device units. Default value: 0.
"y2"	Read/Write	The y coordinate at the bottom edge of the canvas bounds, in device units. Default value: 1000.

goocanvas.Canvas Signal Prototypes

"item-created"	`def callback(canvas, item, model, user_param, ...)`
"set-scroll-adjustments"	`def callback(canvas_view, hadjustment, vadjustment, user_param, ...)`

Description

goocanvas.Canvas is the main widget containing a number of canvas items.

Constructor

    goocanvas.Canvas()

Returns:

A new goocanvas.Canvas

Creates a new canvas.

Methods

goocanvas.Canvas.convert_from_item_space

    def convert_from_item_space(item, x, y)

`item`:	A goocanvas.Item
`x`:	The x coordinate to convert.
`y`:	The y coordinate to convert.
Returns:	The new x and y coordinates.

Converts a coordinate from the given item's coordinate space to the canvas coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.

goocanvas.Canvas.convert_from_pixel

    def convert_from_pixel(x, y)

`x`:	The x coordinate to convert.
`y`:	The y coordinate to convert.
Returns:	The new x and y coordinates.

Converts a coordinate from pixels to the canvas coordinate space. The pixel coordinate space specifies pixels from the top-left of the entire canvas window, according to the current scale setting. See set_scale(). The canvas view coordinate space is specified in the call to set_bounds().

goocanvas.Canvas.convert_to_item_space

    def convert_to_item_space(item, x, y)

`item`:	A goocanvas.Item
`x`:	The x coordinate to convert.
`y`:	The y coordinate to convert.
Returns:	The new x and y coordinates.

Converts a coordinate from the canvas coordinate space to the given item's coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.

goocanvas.Canvas.convert_to_pixel

    def convert_to_pixel(x, y)

`x`:	The x coordinate to convert.
`y`:	The y coordinate to convert.
Returns:	The new x and y coordinates.

Converts a coordinate from the canvas coordinate space to pixels. The canvas coordinate space is specified in the call to set_bounds The pixel coordinate space specifies pixels from the top-left of the entire canvas window, according to the current scale setting. See set_scale

goocanvas.Canvas.create_cairo_context

    def create_cairo_context()

Returns:

a new cairo context.

Creates a cairo context, initialized with the default canvas settings.

goocanvas.Canvas.create_item

    def create_item(model)

`model`:	The item model to create a canvas item for.
Returns:	A new canvas item.

Creates a new canvas item for the given item model, and recursively creates items for any children. It uses the create_item virtual method if it has been set. Subclasses of GooCanvas can define this method if they want to use custom views for items. It emits the "item-created" signal after creating the view, so application code can connect signal handlers to the new view if desired.

goocanvas.Canvas.get_bounds

    def get_bounds()

Returns:

A tuple with the four coordinates.

Gets the bounds of the canvas, in canvas units. By default, canvas units are pixels, though the GooCanvas:units property can be used to change the units to points, inches or millimeters.

goocanvas.Canvas.get_default_line_width

    def get_default_line_width()

Returns:

The default line width of the canvas.

Gets the default line width, which depends on the current units setting.

goocanvas.Canvas.get_item

    def get_item(model)

`model`:	A `goocanvas.ItemModel`
Returns:	The canvas item corresponding to the given `goocanvas.ItemModel` or None if no canvas item has been created for it yet.

Gets the canvas item associated with the given goocanvas.ItemModel. This is only useful when set_root_item_model has been used to set a model for the canvas.

For simple applications you can use get_item to set up signal handlers for your items, e.g.

                item = canvas.get_item (my_item)
                item.connect ("button_press_event", on_my_item_button_press)

More complex applications may want to use the GooCanvas::item-created signal to hook up their signal handlers.

goocanvas.Canvas.get_item_at

    def get_item_at(x, y, is_pointer_event)

`x`:	The x coordinate of the point.
`y`:	The y coordinate of the point.
`is_pointer_event`:	True if the "pointer-events" property of items should be used to determine which parts of the item are tested.
Returns:	The item found at the given point, or None if no item was found.

Gets the item at the given point.

goocanvas.Canvas.get_items_at

    def get_items_at(x, y, is_pointer_event)

`x`:	The x coordinate of the point.
`y`:	The y coordinate of the point.
`is_pointer_event`:	True if the "pointer-events" property of items should be used to determine which parts of the item are tested.
Returns:	A list of items found at the given point, with the top item at the start of the list, or None if no items were found.

Gets all items at the given point.

goocanvas.Canvas.get_items_in_area

    def get_items_in_area(area, inside_area, allow_overlaps, include_containers)

`area`:	The area to compare with each item's bounds.
`inside_area`:	True if items inside area should be returned, or False if items outside area should be returned.
`allow_overlaps`:	True if items which are partly inside and partly outside should be returned.
`include_containers`:	True if containers should be checked as well as normal items.
Returns:	A list of items in the given area, or None if no items are found.

Gets a list of items inside or outside a given area.

goocanvas.Canvas.get_root_item

    def get_root_item()

Returns:

The root item, or None if there is no root item.

Gets the root item of the canvas, usually a goocanvas.Group.

goocanvas.Canvas.get_root_item_model

    def get_root_item_model()

Returns:

The root item model, or None if there is no root item.

Gets the root item model of the canvas, usually a goocanvas.GroupModel.

goocanvas.Canvas.get_scale

    def get_scale()

Returns:

The current scale setting.

Gets the current scale of the canvas, i.e. the number of pixels to use for each device unit.

goocanvas.Canvas.grab_focus

    def grab_focus(item)

item:

The item to grab the focus.

Grabs the keyboard focus for the given item.

goocanvas.Canvas.keyboard_grab

    def keyboard_grab(item, owner_events, time)

`item`:	The item to grab the keyword for.
`owner_events`:	`True` if keyboard events for this application will be reported normally, or `False` if all keyboard events will be reported with respect to the grab item.
`time`:	The time of the event that lead to the keyboard grab. This should come from the relevant `gtk.gdk.Event`
Returns:	gtk.gdk.GRAB_SUCCESS if the grab succeeded.

Grabs the keyboard focus for the given item.

goocanvas.Canvas.keyboard_ungrab

    def keyboard_grab(item, time)

`item`:	The item that has the keyboard grab.
`time`:	The time of the event that lead to the keyboard ungrab. This should come from the relevant `gtk.gdk.Event`

Ungrabs the pointer, if the given item view has the pointer grab.

goocanvas.Canvas.pointer_grab

    def pointer_grab(item, event_mask, cursor, time)

`item`:	The item to grab the pointer for.
`event_mask`:	The events to receive during the grab.
`cursor`:	The cursor to display during the grab, or `None`.
`time`:	The time of the event that lead to the pointer grab. This should come from the relevant `gtk.gdk.Event`.
Returns:	gtk.gdk.GRAB_SUCCESS if the grab succeeded.

Attempts to grab the pointer for the given item.

goocanvas.Canvas.pointer_ungrab

    def pointer_ungrab(item, time)

`item`:	The item that has the pointer grab.
`time`:	The time of the event that lead to the pointer ungrab. This should come from the relevant `gtk.gdk.Event`

Ungrabs the pointer, if the given item view has the pointer grab.

goocanvas.Canvas.register_widget_item

    def register_widget_item(witem)

witem:

A goocanvas.Widget.

Registers a widget item with the canvas, so that the canvas can do the necessary actions to move and resize the widget as needed.

This function should only be used by goocanvas.Widget and subclass implementations.

goocanvas.Canvas.render

    def render(cr, bounds, scale)

`cr`:	A cairo context.
`bounds`:	The area to render, or `None` to render the entire canvas.
`scale`:	The scale to compare with each item's visibility threshold to see if they should be rendered. This only affects items that have their visibility set to goocanvas.ITEM_VISIBLE_ABOVE_THRESHOLD.

Renders all or part of a canvas to the given cairo context.

goocanvas.Canvas.request_redraw

    def request_redraw(bounds)

bounds:

The bounds to redraw.

Requests that the given bounds be redrawn.

goocanvas.Canvas.request_update

    def request_update()

Schedules an update of the goocanvas.Canvas. This will be performed in the idle loop, after all pending events have been handled, but before the canvas has been repainted.

goocanvas.Canvas.scroll_to

    def scroll_to(left, top)

`left`:	The x coordinate to scroll to.
`top`:	The y coordinate to scroll to.

Scrolls the canvas, placing the given point as close to the top-left of the view as possible.

goocanvas.Canvas.set_bounds

    def set_bounds(left, top, right, bottom)

`left`:	The left edge.
`top`:	The top edge.
`right`:	The right edge.
`bottom`:	The bottom edge.

Sets the bounds of the goocanvas.Canvas in device units. By default, device units are the same as pixels, though set_scale can be used to specify a different scale.

goocanvas.Canvas.set_root_item

    def set_root_item(item)

item:

The root canvas item.

Sets the root item of the canvas. Any existing canvas items are removed.

goocanvas.Canvas.set_root_item_model

    def set_root_item_model(model)

model:

The root canvas item model.

Sets the root item of the canvas. A hierarchy of canvas items will be created, corresponding to the hierarchy of items in the model. Any current canvas items will be removed.

goocanvas.Canvas.set_scale

    def set_scale(pixel_per_unit)

pixel_per_unit:

The new scale setting.

Sets the current scale of the canvas, i.e. the number of pixels to use for each device unit.

goocanvas.Canvas.unregister_item

    def unregister_item(model)

model:

The item model whose canvas item is being finalized.

This function should be called in the finalize method of goocanvas.Item objects, to remove the canvas item from the GooCanvas's hash table.

goocanvas.Canvas.unregister_widget_item

    def unregister_widget_item(witem)

witem:

A goocanvas.Widget item.

Unregisters a widget item from the canvas, when the item is no longer in the canvas.

This function should only be used by goocanvas.Widget and ubclass implementations.

goocanvas.Canvas.update

    def update()

Updates any items that need updating. This is only intended to be used by subclasses of goocanvas.Canvas or goocanvas.Item implementation.

Signals

The "item-view-created" goocanvas.CanvasView Signal

    def callback(canvas, item, model, user_param, ...)

`canvas`:	The `goocanvas.Canvas`.
`item`:	The new `goocanvas.Item`.
`model`:	The `goocanvas.ItemModel`.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)

The 'item-created" signal is emitted when the a new canvas item is created. Applications can set up signal handlers for the new items here.

The "set-scroll-adjustments" goocanvas.Canvas Signal

    def callback(canvas, hadjustment, vadjustment, user_param, ...)

`canvas`:	The `goocanvas.Canvas`.
`hadjustment`:	The horizontal adjustment.
`vadjustment`:	The vertical adjustment.
`user_param`:	the first user parameter (if any) specified with the `connect`() method
`...`:	additional user parameters (if any)

The 'set-scroll-adjustments" signal is emitted when the GooCanvas is placed inside a gtk.ScrolledWindow, to connect up the adjustments so scrolling works properly. It isn't useful for applications.