18 GnomeCanvas

Main canvas widget

18.1 Overview

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.

To create a new <gnome-canvas> widget call gnome-canvas-new or
gnome-canvas-new-aa for an anti-aliased mode canvas.

A <gnome-canvas> widget contains one or more <gnome-canvas-item>
objects. Items consist of graphing elements like lines, ellipses, polygons,
images, text, and curves. These items are organized using
<gnome-canvas-group> objects, which are themselves derived from
<gnome-canvas-item>. 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 <gnome-canvas>. This is the
top level group under which all items in a canvas are contained. To get the root
group from a canvas call gnome-canvas-root. To clear a canvas you can
simply walk through the item_list member of the <gnome-canvas-group> and
call gtk-object-destroy on each one.

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.
gnome-canvas-w2c converts world to canvas pixel coordinates and
gnome-canvas-c2w converts from canvas to world. gnome-canvas-w2c-d
is like gnome-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 gnome-canvas-w2c-affine. gnome-canvas-window-to-world
converts from window to world coordinates and
gnome-canvas-world-to-window 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-canvas-item>
objects.

To set the canvas zoom factor (canvas pixels per world unit, the scaling factor)
call gnome-canvas-set-pixels-per-unit, 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
gnome-canvas-set-scroll-region and to get the current region
gnome-canvas-get-scroll-region can be used. If the window is larger than
the canvas scrolling region it can optionally be centered in the window. Use
gnome-canvas-set-center-scroll-region to enable or disable this behavior.
To scroll to a particular canvas pixel coordinate use
gnome-canvas-scroll-to (typically not used since scrollbars are usually
set up to handle the scrolling), and to get the current canvas pixel scroll
offset call gnome-canvas-get-scroll-offsets.

Sets the scrolling region of a canvas to the specified rectangle. The canvas
will then be able to scroll only within this region. The view of the canvas is
adjusted as appropriate to display as much of the new region as possible.

Sets the zooming factor of a canvas by specifying the number of pixels that
correspond to one canvas unit.

The anchor point for zooming, i.e. the point that stays fixed and all others
zoom inwards or outwards from it, depends on whether the canvas is set to center
the scrolling region or not. You can control this using the
gnome-canvas-set-center-scroll-region function. If the canvas is set to
center the scroll region, then the center of the canvas window is used as the
anchor point for zooming. Otherwise, the upper-left corner of the canvas window
is used as the anchor point.

Makes a canvas scroll to the specified offsets, given in canvas pixel units. The
canvas will adjust the view so that it is not outside the scrolling region. This
function is typically not used, as it is better to hook scrollbars to the canvas
layout's scrolling adjusments.

Forces an immediate update and redraw of a canvas. If the canvas does not have
any pending update or redraw requests, then no action is taken. This is
typically only used by applications that need explicit control of when the
display is updated, like games. It is not needed by normal applications.

Convenience function that informs a canvas that the specified rectangle needs to
be repainted. This function converts the rectangle to a microtile array and
feeds it to gnome-canvas-request-redraw-uta. The rectangle includes
x1 and y1, but not x2 and y2. To be used only by item
implementations.

Allocates a color based on the specified X color specification. As a convenience
to item implementations, it returns TRUE if the color was allocated, or FALSE if
the specification was NULL. A NULL color specification is considered as
"transparent" by the canvas.

canvas

A canvas.

spec

X color specification, or NULL for "transparent".

color

Returns the allocated color.

ret

TRUE if spec is non-NULL and the color is allocated. If spec is
NULL, then returns FALSE.

Sets the stipple origin of the specified GC as is appropriate for the canvas, so
that it will be aligned with other stipple patterns used by canvas items. This
is typically only needed by item implementations.

Controls dithered rendering for antialiased canvases. The value of dither should
be <gdk-rgb-dither-none>, <gdk-rgb-dither-normal>, or
<gdk-rgb-dither-max>. The default canvas setting is
<gdk-rgb-dither-normal>.