See Also: Canvas Members
The Gnome.Canvas is an engine for structured graphics that offers a rich imaging model, high performance rendering, and a powerful, high level API. It offers a choice of two rendering back-ends, one based on Xlib for extremely fast display, and another based on Libart, a sophisticated, antialiased, alpha-compositing engine. This widget can be used for flexible display of graphics and for creating interactive user interface elements.
A Gnome.Canvas widget contains one or more Gnome.CanvasItem objects. Items consist of graphing elements like lines, ellipses, polygons, images, text, and curves. These items are organized using Gnome.CanvasGroup objects, which are themselves derived from Gnome.CanvasItem. Since a group is an item it can be contained within other groups, forming a tree of canvas items. Certain operations, like translating and scaling, can be performed on all items in a group.
There is a special root group created by a GnomeCanvas. This is the top level group under which all items in a canvas are contained. To get the root group from a canvas, use Canvas.Root property.
There are several different coordinate systems used by Gnome.Canvas widgets. The primary system is a logical, abstract coordinate space called world coordinates. World coordinates are expressed as unbounded double floating point numbers. When it comes to rendering to a screen the canvas pixel coordinate system (also referred to as just canvas coordinates) is used. This system uses integers to specify screen pixel positions. A user defined scaling factor and offset are used to convert between world coordinates and canvas coordinates. Each item in a canvas has its own coordinate system called item coordinates. This system is specified in world coordinates but they are relative to an item (0.0, 0.0 would be the top left corner of the item). The final coordinate system of interest is window coordinates. These are like canvas coordinates but are offsets from within a window a canvas is displayed in. This last system is rarely used, but is useful when manually handling GDK events (such as drag and drop) which are specified in window coordinates (the events processed by the canvas are already converted for you).
Along with different coordinate systems comes functions to convert between them. Canvas.W2c converts world to canvas pixel coordinates and Canvas.C2w from canvas to world. Canvas.W2cD is like Canvas.W2c but returns the pixel coordinates as doubles which is useful to avoid precision loss from integer rounding. To get the affine transform matrix for converting from world coordinates to canvas coordinates call Canvas.W2cAffine. Canvas.WindowToWorld converts from window to world coordinates and Canvas.WorldToWindow converts in the other direction. There are no functions for converting between canvas and window coordinates, since this is just a matter of subtracting the canvas scrolling offset. To convert to/from item coordinates use the functions defined for Gnome.CanvasItem objects.
To set the canvas zoom factor (canvas pixels per world unit, the scaling factor) use the Canvas.PixelsPerUnit property, setting this to 1.0 will cause the two coordinate systems to correspond (e.g., [5, 6] in pixel units would be [5.0, 6.0] in world units).
Defining the scrollable area of a canvas widget is done by calling Canvas.SetScrollRegion and to get the current region Canvas.GetScrollRegion can be used. If the window is larger than the canvas scrolling region it can optionally be centered in the window. Use the Canvas.CenterScrollRegion property to enable or disable this behavior. To scroll to a particular canvas pixel coordinate use Canvas.ScrollTo (typically not used since scrollbars are usually set up to handle the scrolling), and to get the current canvas pixel scroll offset call Canvas.GetScrollOffsets.