GnomeCanvas

Name

GnomeCanvas — A generic engine for structured graphics.

The GNOME canvas is an engine for displaying structured graphics and simplyfing the development of complex graphic-based applications.

Canvas Items

The GNOME Canvas basic building block are the GNOME Canvas Items (GnomeCanvasItem): lines, rectangles, text, ellipses, polylines, images and embedded widgets. You can use any of those directly in your application.

The CanvasItem system is designed to be extensible. Applications can define their own GnomeCanvasItem objects for special purpose tasks. For example, the GNOME Gnumeric spreadsheet defines a number of special Canvas Items that are specialized for the task of spreadsheets.

Specialized canvas items allows the developer to write custom items that can adapt to its needs of speed, scalability and gives the user the power to extend the canvas.

Items on the canvas can be reconfigured by using the Gtk argument system. Users can reconfigure the parameters of the canvas items and the changes on the parameters will be reflected inmediately on the screen.


Flicker free display

The GNOME Canvas uses off-screen buffers to render the images before transfering them to the screen. Transfers can take place at the command of the programmer (by explicitly requesting a repait update) or done automatically by the engine (during the idle look handler).


Event dispatching

Each GnomeCanvasItem can receive mouse events, keyboard events, mouse-enter and mouse leave events. In addition a canvas item can grab the mouse (for example to implement reliable dragging of objects).


Canvas types

The Canvas can be run in two different modes: X11 mode and Art mode. The mode is chosen at the creation time of the widget by either calling gnome_canvas_new() or gnome_canvas_new_aa(), the former creates an X11 canvas, while the later creates an Art-based canvas.

The X11 mode uses the X server to draw the items and it takes advantage of the X server acceleration features for drawing on the screen. The only drawback is that the output quality and the imaging model are restricted to the X11 quality and imaging model.

The Art mode of the canvas has an advanced imaging model based on LibArt and it allows any GnomeCanvasItem (with the exception of the embedded widget item) to be rotated, scaled and translated (this is done by means of applying an affine transformation on the object).

Synopsis


#include <gnome.h>


struct      GnomeCanvas;
#define     GNOME_CANVAS_EPSILON
#define     GNOME_CANVAS_COLOR              (r, g, b)
#define     GNOME_CANVAS_COLOR_A            (r, g, b, a)
struct      GnomeCanvasBuf;
GtkWidget*  gnome_canvas_new                (void);
GtkWidget*  gnome_canvas_new_aa             (void);
GnomeCanvasGroup* gnome_canvas_root         (GnomeCanvas *canvas);
void        gnome_canvas_set_scroll_region  (GnomeCanvas *canvas,
                                             double x1,
                                             double y1,
                                             double x2,
                                             double y2);
void        gnome_canvas_get_scroll_region  (GnomeCanvas *canvas,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);
void        gnome_canvas_set_pixels_per_unit
                                            (GnomeCanvas *canvas,
                                             double n);
void        gnome_canvas_scroll_to          (GnomeCanvas *canvas,
                                             int cx,
                                             int cy);
void        gnome_canvas_get_scroll_offsets (GnomeCanvas *canvas,
                                             int *cx,
                                             int *cy);
void        gnome_canvas_update_now         (GnomeCanvas *canvas);
GnomeCanvasItem* gnome_canvas_get_item_at   (GnomeCanvas *canvas,
                                             double x,
                                             double y);
void        gnome_canvas_request_redraw_uta (GnomeCanvas *canvas,
                                             ArtUta *uta);
void        gnome_canvas_request_redraw     (GnomeCanvas *canvas,
                                             int x1,
                                             int y1,
                                             int x2,
                                             int y2);
void        gnome_canvas_w2c_affine         (GnomeCanvas *canvas,
                                             double affine[6]);
void        gnome_canvas_w2c                (GnomeCanvas *canvas,
                                             double wx,
                                             double wy,
                                             int *cx,
                                             int *cy);
void        gnome_canvas_w2c_d              (GnomeCanvas *canvas,
                                             double wx,
                                             double wy,
                                             double *cx,
                                             double *cy);
void        gnome_canvas_c2w                (GnomeCanvas *canvas,
                                             int cx,
                                             int cy,
                                             double *wx,
                                             double *wy);
void        gnome_canvas_window_to_world    (GnomeCanvas *canvas,
                                             double winx,
                                             double winy,
                                             double *worldx,
                                             double *worldy);
void        gnome_canvas_world_to_window    (GnomeCanvas *canvas,
                                             double worldx,
                                             double worldy,
                                             double *winx,
                                             double *winy);
int         gnome_canvas_get_color          (GnomeCanvas *canvas,
                                             char *spec,
                                             GdkColor *color);
void        gnome_canvas_set_stipple_origin (GnomeCanvas *canvas,
                                             GdkGC *gc);

Object Hierarchy


  GtkObject
   +----GtkWidget
         +----GtkContainer
               +----GtkLayout
                     +----GnomeCanvas

Description

Details

struct GnomeCanvas

struct GnomeCanvas;

Most of the fields in this structure are for private use only. However, canvas item implementations may make use of some of them.


GNOME_CANVAS_EPSILON

#define GNOME_CANVAS_EPSILON 1e-10

This macro defines a ‘small’ floating-point value for the internal computations that the canvas performs. It can be used by item implementations as a test to see whether a number is “almost zero”.


GNOME_CANVAS_COLOR()

#define     GNOME_CANVAS_COLOR(r, g, b)

This macro is used to build a 32-bit integer with an RGB color specification. The specified values must be integers in the range [0, 255].

r :Red component of the color.
g :Green component of the color.
b :Blue component of the color.


GNOME_CANVAS_COLOR_A()

#define     GNOME_CANVAS_COLOR_A(r, g, b, a)

This macro is used to build a 32-bit integer with an RGBA color specification. This is the same as an RGB color specification, but with an added alpha or opacity value. The specified values must be integers in the range [0, 255].

r :Red component of the color.
g :Green component of the color.
b :Blue component of the color.
a :Opacity component of the color.


struct GnomeCanvasBuf

typedef struct {
	/* 24-bit RGB buffer for rendering */
	guchar *buf;

	/* Rowstride for the buffer */
	int buf_rowstride;

	/* Rectangle describing the rendering area */
	ArtIRect rect;

	/* Background color, given as 0xrrggbb */
	guint32 bg_color;

	/* Invariant: at least one of the following flags is true. */

	/* Set when the render rectangle area is the solid color bg_color */
	unsigned int is_bg : 1;

	/* Set when the render rectangle area is represented by the buf */
	unsigned int is_buf : 1;
} GnomeCanvasBuf;

This structure is passed to the render method of canvas items when they need to paint themselves on an antialiased canvas. The buf field points to a 24-bit RGB buffer for rendering. The buf_rowstride field specifies the number of bytes in each row in the buffer, which should be used to calculate byte offsets inside it. The buffer's pixel offsets in canvas pixel coordinates are given by the rect rectangle. The is_bg and is_buf fields are flags that items can use to implement rendering optimizations, and they ar used in conjunction with the bg_color field.

The is_buf flag specifies whether the contents of the buffer are an accurate representation of the state of the canvas. If this flag is true, then the RGB data in the buf is valid, that is, it contains meaningful data.

The is_bg flag specifies whether the buffer has all its pixels set to the same color. This allows canvas items to optimize for this case by doing alpha compositing for a smaller set of values than if the buffer had pixels of different colors.

At least one of these flags is on at any one time. The meaning of their combinations is as follows:

Table 1. Values for is_bg and is_buf

is_bufis_bgMeaning
FALSETRUE The buffer does not contain meaningful data. However, it should be considered as if it were filled with the solid color specified in the bg_color field. Item implementations may want to call gnome_canvas_buf_ensure_buf() to fill the buffer automatically.
TRUEFALSE The buffer contains meaningful data and not all of its pixels may be the same color. Item implementations can use the buffer data as-is for alpha compositing.
TRUETRUE The buffer contains meaningful data, and all the pixels are of the same color. Item implementations can use the buffer data as-is for alpha compositing, or be smarter and do less operations since they can just composite over a single color.

Whenever an item paints to an RGB buffer in which the is_bg field was true, the item is then responsible for turning off this flag if it knows that the result will not be pixels all of the same color. If a large item, like a solid rectangle, knows that it will be filling the buffer with a solid color, then it take any one of the following actions:

Most item implementations may only need to perform the actions for the first case described above. The other two are simply optimizations they can perform.


gnome_canvas_new ()

GtkWidget*  gnome_canvas_new                (void);

Creates a new empty canvas. If the user wishes to use the image item inside this canvas, then the gdk_imlib visual and colormap should be pushed into Gtk+'s stack before calling this function, and they can be popped afterwards.

Returns : The newly-created canvas.


gnome_canvas_new_aa ()

GtkWidget*  gnome_canvas_new_aa             (void);

Creates a new antialiased empty canvas. You want to push the GdkRgb colormap and visual for this.

Returns : The newly-created canvas.


gnome_canvas_root ()

GnomeCanvasGroup* gnome_canvas_root         (GnomeCanvas *canvas);

Queries the root group of a canvas.

canvas : The canvas whose root group should be extracted.
Returns : The root group of the canvas.


gnome_canvas_set_scroll_region ()

void        gnome_canvas_set_scroll_region  (GnomeCanvas *canvas,
                                             double x1,
                                             double y1,
                                             double x2,
                                             double y2);

Sets the scrolling region of the 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 : The canvas to set the scroll region for.
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_get_scroll_region ()

void        gnome_canvas_get_scroll_region  (GnomeCanvas *canvas,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);

Queries the scroll region of the canvas.

canvas : The canvas whose scroll region should be queried.
x1 : If non-NULL, returns the leftmost limit of the scrolling region.
y1 : If non-NULL, returns the upper limit of the scrolling region.
x2 : If non-NULL, returns the rightmost limit of the scrolling region.
y2 : If non-NULL, returns the lower limit of the scrolling region.


gnome_canvas_set_pixels_per_unit ()

void        gnome_canvas_set_pixels_per_unit
                                            (GnomeCanvas *canvas,
                                             double n);

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

canvas : The canvas whose zoom factor should be changed.
n : The number of pixels that correspond to one canvas unit.


gnome_canvas_scroll_to ()

void        gnome_canvas_scroll_to          (GnomeCanvas *canvas,
                                             int cx,
                                             int cy);

Makes the 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 : The canvas to scroll.
cx : Horizontal scrolling offset in canvas pixel units.
cy : Vertical scrolling offset in canvas pixel units.


gnome_canvas_get_scroll_offsets ()

void        gnome_canvas_get_scroll_offsets (GnomeCanvas *canvas,
                                             int *cx,
                                             int *cy);

Queries the scrolling offsets of the canvas.

canvas : The canvas whose scrolling offsets should be queried.
cx : If non-NULL, returns the horizontal scrolling offset.
cy : If non-NULL, returns the vertical scrolling offset.


gnome_canvas_update_now ()

void        gnome_canvas_update_now         (GnomeCanvas *canvas);

Forces an immediate redraw or update of the canvas. If the canvas does not have any pending 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 : The canvas whose view should be updated.


gnome_canvas_get_item_at ()

GnomeCanvasItem* gnome_canvas_get_item_at   (GnomeCanvas *canvas,
                                             double x,
                                             double y);

Looks for the item that is under the specified position (given in world coordinates).

canvas : The canvas from which to get the item
x : X position in world coordinates
y : Y position in world coordinates
Returns : The sought item, or NULL if no item is at the specified coordinates.


gnome_canvas_request_redraw_uta ()

void        gnome_canvas_request_redraw_uta (GnomeCanvas *canvas,
                                             ArtUta *uta);

Informs a canvas that the specified area, given as a microtile array, needs to be repainted.

canvas : The canvas whose area needs to be redrawn.
uta : Microtile array that specifies the area to be redrawn.


gnome_canvas_request_redraw ()

void        gnome_canvas_request_redraw     (GnomeCanvas *canvas,
                                             int x1,
                                             int y1,
                                             int x2,
                                             int y2);

Convenience function that informs a canvas that the specified area, specified as a 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.

canvas : The canvas whose area needs to be redrawn.
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_w2c_affine ()

void        gnome_canvas_w2c_affine         (GnomeCanvas *canvas,
                                             double affine[6]);

Gets the affine transform that converts world coordinates into canvas pixel coordinates.

canvas : The canvas whose coordinates need conversion.
affine : 


gnome_canvas_w2c ()

void        gnome_canvas_w2c                (GnomeCanvas *canvas,
                                             double wx,
                                             double wy,
                                             int *cx,
                                             int *cy);

Converts world coordinates into canvas pixel coordinates. Usually only needed by item implementations.

canvas : The canvas whose coordinates need conversion.
wx : World X coordinate.
wy : World Y coordinate.
cx : If non-NULL, returns the converted X pixel coordinate.
cy : If non-NULL, returns the converted Y pixel coordinate.


gnome_canvas_w2c_d ()

void        gnome_canvas_w2c_d              (GnomeCanvas *canvas,
                                             double wx,
                                             double wy,
                                             double *cx,
                                             double *cy);

Converts world coordinates into canvas pixel coordinates. Usually only needed by item implementations. This version results in double coordinates, which are useful in antialiased implementations.

canvas : The canvas whose coordinates need conversion.
wx : World X coordinate.
wy : World Y coordinate.
cx : If non-NULL, returns the converted X pixel coordinate.
cy : If non-NULL, returns the converted Y pixel coordinate.


gnome_canvas_c2w ()

void        gnome_canvas_c2w                (GnomeCanvas *canvas,
                                             int cx,
                                             int cy,
                                             double *wx,
                                             double *wy);

Converts canvas pixel coordinates to world coordinates. Usually only needed by item implementations.

canvas : The canvas whose coordinates need conversion.
cx : Canvas pixel X coordinate.
cy : Canvas pixel Y coordinate.
wx : If non-NULL, returns the converted X world coordinate.
wy : If non-NULL, returns the converted Y world coordinate.


gnome_canvas_window_to_world ()

void        gnome_canvas_window_to_world    (GnomeCanvas *canvas,
                                             double winx,
                                             double winy,
                                             double *worldx,
                                             double *worldy);

Converts window-relative coordinates into world coordinates. Use this when you need to convert from mouse coordinates into world coordinates, for example.

canvas : The canvas whose coordinates need conversion.
winx : Window-relative X coordinate.
winy : Window-relative Y coordinate.
worldx : If non-NULL, returns the converted X world coordinate.
worldy : If non-NULL, returns the converted Y world coordinate.


gnome_canvas_world_to_window ()

void        gnome_canvas_world_to_window    (GnomeCanvas *canvas,
                                             double worldx,
                                             double worldy,
                                             double *winx,
                                             double *winy);

Converts world coordinates into window-relative coordinates.

canvas : The canvas whose coordinates need conversion.
worldx : World X coordinate.
worldy : World Y coordinate.
winx : If non-NULL, returns the converted X window-relative coordinate.
winy : If non-NULL, returns the converted Y window-relative coordinate.


gnome_canvas_get_color ()

int         gnome_canvas_get_color          (GnomeCanvas *canvas,
                                             char *spec,
                                             GdkColor *color);

Allocates a color from the RGB value passed into this function.

canvas : The canvas in which to allocate the color.
spec : 
color : 
Returns : Pixel value for this color.


gnome_canvas_set_stipple_origin ()

void        gnome_canvas_set_stipple_origin (GnomeCanvas *canvas,
                                             GdkGC *gc);

Sets the stipple origin of the specified GC as is appropriate for the canvas. This is typically only needed by item implementations.

canvas : The canvas relative to which the stipple origin should be set.
gc : GC on which to set the stipple origin.

See Also

GnomeCanvasItem, GnomeCanvasGroup, GnomeCanvasRE, GnomeCanvasRectEllipse, GnomeCanvasImage, GnomeCanvasLine, GnomeCanvasPolygon, GnomeCanvasText, GnomeCanvasWidget