goocanvas.Canvas
Prev | PyGooCanvas Core Class Reference | Next

## goocanvas.Canvas

goocanvas.Canvas — The Canvas

## Synopsis

    class goocanvas.Canvas(gtk.Container):
        goocanvas.Canvas()
        def convert_bounds_to_item_space(item, bounds)
        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 get_static_root_item()
        def get_static_root_item_model()
        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_item_redraw(bounds, is_static)
        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 set_static_root_item(item)
        def set_static_root_item_model(model)
        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.
"redraw-when-scrolled" | Read/Write | If the canvas is completely redrawn when scrolled, to reduce the flicker of static items. Default value: `False`.
"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_bounds_to_item_space

        def convert_bounds_to_item_space(item, bounds)

`item`: | A goocanvas.Item
`bounds`: | the bounds in device space.

Converts the bound in device space to a bounding box in item space. This is useful in the item paint() methods to convert the bounds to be painted to the item's coordinate space.

### 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.get_static_root_item

        def get_static_root_item()

Returns: | the static root item, or `None`.

Gets the static root item of the canvas.

### goocanvas.Canvas.get_static_root_item_model

        def get_static_root_item_model()

Returns: | the static root item model, or `None`.

Gets the static root item model of the canvas.

### 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_item_redraw

        def request_item_redraw(bounds, is_static)

`bounds`: | the bounds of the item to redraw.
`is_static`: | if the item is static.

Requests that the given bounds be redrawn.

### 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.set_static_root_item

        def set_static_root_item(item)

`item`: | the static root item.

Sets the static root item. Any existing static items are removed.

### goocanvas.Canvas.set_static_root_item_model

        def set_static_root_item_model(model)

`model`: | the static root item model.

Sets the static root item model. Any existing static items are removed.

### 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-created" goocanvas.Canvas 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.

Prev | Up | Next
PyGooCanvas Core Class Reference | Home | goocanvas.Item