Standard Canvas Item Reference

Rectangle and Ellipse Items

The GnomeCanvasRect and GnomeCanvasEllipse canvas items share exactly the same interface, via a GnomeCanvasRE base class. Their shape is given as a bounding box: a top left coordinate (x1, y1) and a bottom right coordinate (x2, y2). The rectangle item matches the shape of the bounding box; the ellipse is inscribed in the bounding box, touching the center of each side. Rectangles and ellipses can be filled or simply an outline. If they are only an outline, they are considered to be "hollow"; that is, the transparent area inside the shape is not part of the canvas item and events that occur in that area will not be relayed to the item.

GnomeCanvasRE does not behave gracefully if you give the coordinates in the wrong order. That is, x2 must be greater than x1, and y2 must be greater than y1; otherwise GnomeCanvasRE gets confused.

Line Item

GnomeCanvasLine represents one or more line segments joined at their endpoints. You can use it to represent an unfilled polygon as well. GnomeCanvasPolygon is used for filled polygons.

A line is specified using a GnomeCanvasPoints structure, which looks like this:

typedef struct {
        int num_points;
        double *coords;
        int ref_count;
} GnomeCanvasPoints;

      

The coords field contains an array of points, alternating X and Y coordinates. You fill the coords array directly, after creating a GnomeCanvasPoints with gnome_canvas_points_new(); the structure should be destroyed with gnome_canvas_points_unref().

Lines can have arrowheads on either end; the arrowhead shape is specified via three parameters, arbitrarily named A, B, and C. Parameter A (specified with the arrow_shape_a argument) specifies the distance from the base of the arrowhead to the tip. B specifies the distance from the tip of the arrowhead to one of the trailing points; C specifies the distance of a trailing point from the outer edge of the line.

Polygon Item

GnomeCanvasPolygon represents a filled polygon; it can be filled or only an outline. Unlike GnomeCanvasRE, an unfilled GnomeCanvasPolygon is not "hollow"; the transparent portion in the center is part of the canvas item. GnomeCanvasLine is used for "hollow" polygons.

Image Item

GnomeCanvasImage places an image on the canvas; you pass it a GdkImlibImage, loaded using one of the Imlib routines. If the image has transparent areas, they will be properly handled (they won't be considered part of the item, and will not receive events). To use GnomeCanvasImage with a GDK canvas, you must push the Imlib visual and colormap before creating the canvas; see the section called Preparing the GnomeCanvas Widget.

Text Item

GnomeCanvasText displays a text string. You can specify the coordinates of the string as an ordered pair; these coordinates will represent the location of the text's anchor. For example, if the "anchor" argument is set to GTK_ANCHOR_NORTH, the text item's coordinates will represent the location of the top-center of the item. That is, the text will be centered around the X position and begin just below the Y position. Possible anchor values are:

• GTK_ANCHOR_CENTER

• GTK_ANCHOR_NORTH

• GTK_ANCHOR_NORTH_WEST

• GTK_ANCHOR_NORTH_EAST

• GTK_ANCHOR_SOUTH

• GTK_ANCHOR_SOUTH_WEST

• GTK_ANCHOR_SOUTH_EAST

• GTK_ANCHOR_WEST

• GTK_ANCHOR_EAST

Affine transformation of GnomeCanvasText is not implemented very well. Because the X font model is inflexible and limited, there is no good way to rotate and otherwise transform rendered text. In antialiased mode the canvas item implements this in the only way it can: it draws the entire font to a GdkPixmap, then copies the pixmap to a GdkImage, then reads individual pixels out of the image into a client-side bitmap, then copies the characters to be displayed from the entire-font bitmap into a temporary buffer, then uses libart_lgpl to apply any affine transformations to this buffer, then copies the transformed buffer to the canvas RGB buffer. Finally the canvas copies the RGB buffer to the screen. Needless to say this is slower than molasses: an entire bitmap goes over the network more than once. Moreover, scaling and rotating fonts as bitmaps leads to a low quality image. If you try to use GnomeCanvasText with antialiased mode, you will probably notice this; if your canvas is slow to update, suspect the text item.

There are plans to fix the text item, using a new font abstraction called GnomeFont. However, Gnome 1.0 lacks this feature.

There is not a good solution to the problem; if your application allows it, you can get dramatic speed increases by creating your own text item that caches the entire-font bitmaps. However, if you don't reuse the same fonts often, caching will be useless. Another possibility is to abandon X fonts and use Type 1 fonts with a rasterization library like t1lib, but this limits the fonts available to you and adds a library dependency. You could also use True Type fonts with the FreeType library, or use the Display PostScript extension to X (XDPS).

Unfortunately, your best bet is probably to wait for the GnomeFont feature in a future version of the Gnome libraries.

Widget Item

The GnomeCanvasWidget item places a widget on the canvas. The canvas item emulates a container widget, passing a size allocation to the widget it holds. You can specify an anchor point for the widget item, just as you can for GnomeCanvasText.