Main canvas widget
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.
Derives from
<gtk-layout>.This class defines the following properties:
aa- The antialiasing mode of the canvas.
focused-item
<gdk-drawable>) (arg1 <gint>) (arg2 <gint>) (arg3 <gint>) (arg4 <gint>)This signal is emitted to draw the background for non-antialiased mode canvas widgets. The default method uses the canvas widget's style to draw the background.
<gpointer>)This signal is emitted for antialiased mode canvas widgets to render the background. The buf data structure contains both a pointer to a packed 24-bit RGB array and the coordinates.
<gtk-widget>)Creates a new empty canvas in non-antialiased mode.
- ret
- A newly-created canvas.
<gtk-widget>)Creates a new empty canvas in antialiased mode.
- ret
- A newly-created antialiased canvas.
<gnome-canvas>) ⇒ (ret <gnome-canvas-group>)Queries the root group of a canvas.
- canvas
- A canvas.
- ret
- The root group of the specified canvas.
<gnome-canvas>) (x1 double) (y1 double) (x2 double) (y2 double)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.
- canvas
- A canvas.
- x1
- Leftmost limit of the scrolling region.
- y1
- Upper limit of the scrolling region.
- x2
- Rightmost limit of the scrolling region.
- y2
- Lower limit of the scrolling region.
<gnome-canvas>) ⇒ (x1 double) (y1 double) (x2 double) (y2 double)Queries the scrolling region of a canvas.
- canvas
- A canvas.
- x1
- Leftmost limit of the scrolling region (return value).
- y1
- Upper limit of the scrolling region (return value).
- x2
- Rightmost limit of the scrolling region (return value).
- y2
- Lower limit of the scrolling region (return value).
<gnome-canvas>) (n double)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-regionfunction. 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.
- canvas
- A canvas.
- n
- The number of pixels that correspond to one canvas unit.
<gnome-canvas>) (cx int) (cy int)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.
- canvas
- A canvas.
- cx
- Horizontal scrolling offset in canvas pixel units.
- cy
- Vertical scrolling offset in canvas pixel units.
<gnome-canvas>) ⇒ (cx int) (cy int)Queries the scrolling offsets of a canvas. The values are returned in canvas pixel units.
- canvas
- A canvas.
- cx
- Horizontal scrolling offset (return value).
- cy
- Vertical scrolling offset (return value).
<gnome-canvas>)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.
- canvas
- A canvas.
<gnome-canvas>) (x double) (y double) ⇒ (ret <gnome-canvas-item>)Looks for the item that is under the specified position, which must be specified in world coordinates.
- canvas
- A canvas.
- x
- X position in world coordinates.
- y
- Y position in world coordinates.
- ret
- The sought item, or NULL if no item is at the specified coordinates.
<gnome-canvas>) (x1 int) (y1 int) (x2 int) (y2 int)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.
- canvas
- A canvas.
- x1
- Leftmost coordinate of the rectangle to be redrawn.
- y1
- Upper coordinate of the rectangle to be redrawn.
- x2
- Rightmost coordinate of the rectangle to be redrawn, plus 1.
- y2
- Lower coordinate of the rectangle to be redrawn, plus 1.
<gnome-canvas>) (wx double) (wy double) ⇒ (cx int) (cy int)Converts world coordinates into canvas pixel coordinates.
- canvas
- A canvas.
- wx
- World X coordinate.
- wy
- World Y coordinate.
- cx
- X pixel coordinate (return value).
- cy
- Y pixel coordinate (return value).
<gnome-canvas>) (wx double) (wy double) ⇒ (cx double) (cy double)Converts world coordinates into canvas pixel coordinates. This version returns coordinates in floating point coordinates, for greater precision.
- canvas
- A canvas.
- wx
- World X coordinate.
- wy
- World Y coordinate.
- cx
- X pixel coordinate (return value).
- cy
- Y pixel coordinate (return value).
<gnome-canvas>) (cx int) (cy int) ⇒ (wx double) (wy double)Converts canvas pixel coordinates to world coordinates.
- canvas
- A canvas.
- cx
- Canvas pixel X coordinate.
- cy
- Canvas pixel Y coordinate.
- wx
- X world coordinate (return value).
- wy
- Y world coordinate (return value).
<gnome-canvas>) (winx double) (winy double) ⇒ (worldx double) (worldy double)Converts window-relative coordinates into world coordinates. You can use this when you need to convert mouse coordinates into world coordinates, for example.
- canvas
- A canvas.
- winx
- Window-relative X coordinate.
- winy
- Window-relative Y coordinate.
- worldx
- X world coordinate (return value).
- worldy
- Y world coordinate (return value).
<gnome-canvas>) (worldx double) (worldy double) ⇒ (winx double) (winy double)Converts world coordinates into window-relative coordinates.
- canvas
- A canvas.
- worldx
- World X coordinate.
- worldy
- World Y coordinate.
- winx
- X window-relative coordinate.
- winy
- Y window-relative coordinate.
<gnome-canvas>) (spec mchars) (color <gdk-color>) ⇒ (ret int)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.
<gnome-canvas>) (rgba unsigned-int) ⇒ (ret unsigned-long)Allocates a color from the RGBA value passed into this function. The alpha opacity value is discarded, since normal X colors do not support it.
- canvas
- A canvas.
- rgba
- RGBA color specification.
- ret
- Allocated pixel value corresponding to the specified color.
<gnome-canvas>) (gc <gdk-gc>)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.
- canvas
- A canvas.
- gc
- GC on which to set the stipple origin.
<gnome-canvas>) (dither <gdk-rgb-dither>)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>.
- canvas
- A canvas.
- dither
- Type of dithering used to render an antialiased canvas.