GnomeCanvas

Name

GnomeCanvas -- Main canvas widget

Synopsis


#include libgnomecanvas/libgnomecanvas.h


struct      GnomeCanvas;
#define     GNOME_CANVAS_EPSILON
#define     GNOME_CANVAS_COLOR              (r, g, b)
#define     GNOME_CANVAS_COLOR_A            (r, g, b, a)
typedef     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_center_scroll_region
                                            (GnomeCanvas *canvas,
                                             gboolean center_scroll_region);
gboolean    gnome_canvas_get_center_scroll_region
                                            (GnomeCanvas *canvas);
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,
                                             const char *spec,
                                             GdkColor *color);
gulong      gnome_canvas_get_color_pixel    (GnomeCanvas *canvas,
                                             guint rgba);
void        gnome_canvas_set_stipple_origin (GnomeCanvas *canvas,
                                             GdkGC *gc);
void        gnome_canvas_set_dither         (GnomeCanvas *canvas,
                                             GdkRgbDither dither);
GdkRgbDither gnome_canvas_get_dither        (GnomeCanvas *canvas);

Description

The GnomeCanvas 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 GnomeCanvas widget call gnome_canvas_new() or gnome_canvas_new_aa() for an anti-aliased mode canvas.

A GnomeCanvas widget contains one or more GnomeCanvasItem objects. Items consist of graphing elements like lines, ellipses, polygons, images, text, and curves. These items are organized using GnomeCanvasGroup objects, which are themselves derived from GnomeCanvasItem. 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 call gnome_canvas_root().

There are several different coordinate systems used by GnomeCanvas 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 GnomeCanvasItem 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().

Details

struct GnomeCanvas {

	GtkLayout layout;

	/* Root canvas group */
	GnomeCanvasItem *root;

	/* Area that needs redrawing, stored as a microtile array */
	ArtUta *redraw_area;

	/* The item containing the mouse pointer, or NULL if none */
	GnomeCanvasItem *current_item;

	/* Item that is about to become current (used to track deletions and such) */
	GnomeCanvasItem *new_current_item;

	/* Item that holds a pointer grab, or NULL if none */
	GnomeCanvasItem *grabbed_item;

	/* If non-NULL, the currently focused item */
	GnomeCanvasItem *focused_item;

	/* GC for temporary draw pixmap */
	GdkGC *pixmap_gc;

	/* Event on which selection of current item is based */
	GdkEvent pick_event;

	/* Scrolling region */
	double scroll_x1, scroll_y1;
	double scroll_x2, scroll_y2;

	/* Scaling factor to be used for display */
	double pixels_per_unit;

	/* Idle handler ID */
	guint idle_id;

	/* Signal handler ID for destruction of the root item */
	guint root_destroy_id;

	/* Area that is being redrawn.  Contains (x1, y1) but not (x2, y2).
	 * Specified in canvas pixel coordinates.
	 */
	int redraw_x1, redraw_y1;
	int redraw_x2, redraw_y2;

	/* Offsets of the temprary drawing pixmap */
	int draw_xofs, draw_yofs;

	/* Internal pixel offsets when zoomed out */
	int zoom_xofs, zoom_yofs;

	/* Last known modifier state, for deferred repick when a button is down */
	int state;

	/* Event mask specified when grabbing an item */
	guint grabbed_event_mask;

	/* Tolerance distance for picking items */
	int close_enough;

	/* Whether the canvas should center the scroll region in the middle of
	 * the window if the scroll region is smaller than the window.
	 */
	unsigned int center_scroll_region : 1;

	/* Whether items need update at next idle loop iteration */
	unsigned int need_update : 1;

	/* Whether the canvas needs redrawing at the next idle loop iteration */
	unsigned int need_redraw : 1;

	/* Whether current item will be repicked at next idle loop iteration */
	unsigned int need_repick : 1;

	/* For use by internal pick_current_item() function */
	unsigned int left_grabbed_item : 1;

	/* For use by internal pick_current_item() function */
	unsigned int in_repick : 1;

	/* Whether the canvas is in antialiased mode or not */
	unsigned int aa : 1;

	/* Which dither mode to use for antialiased mode drawing */
	GdkRgbDither dither;
};

This should not be accessed directly. Use the accessor functions as described below.


#define GNOME_CANVAS_EPSILON 1e-10

A tiny value used by internal canvas operations.


#define     GNOME_CANVAS_COLOR(r, g, b)

Macro for creating a canvas 32 bit RGBA color from red, green and blue components.

r:

Red value (0-255)

g:

Green value (0-255)

b:

Blue value (0-255)