Basic Canvas Architecture

GnomeCanvasGroup

Canvas items are arranged in a tree structure. You can group items together, to be moved as a unit; canvas architect Federico Mena Quintero likes to use a circuit diagram editor as an example. You might group together the shapes representing each logic gate, so you could manipulate the logic gate as a unit. You could also collect several logic gates into a single component; that is, groups can contain subgroups. Within each group, the canvas maintains a stacking order; objects higher in the stacking order obscure objects lower in the stacking order.

To implement this, the canvas comes with a special kind of canvas item called GnomeCanvasGroup. As the name suggests, a canvas group groups a number canvas items together so you can manipulate the child items as a single item. A GnomeCanvasGroup is invisible; to render itself, it simply recurses its children, rendering each of them in turn. When you create a new GnomeCanvas, a default group called the "root" is created for you. All canvas items are added somewhere below the root group. The canvas widget only deals with the root canvas item directly; all other canvas items are managed by their parent group.

An accessor function is provided to access the root canvas group, shown in Figure 1.

       #include <libgnomeui/gnome-canvas.h>
      

Items must always be part of a group; there is no such thing as an "orphan" canvas item. When you create an item, you must specify its canvas group. It is also possible to reparent items after creation. However, items are permanently bound to the GnomeCanvas they were created on; it is not permitted to reparent an item to a group on a different canvas.

Coordinates

Many of the features of the canvas are implemented via translations between different coordinate systems. Canvas items can be moved, rotated, or scaled via affine transformations, described in more detail below. (Short version: an affine transformation is a way to convert from one coordinate system to another.) Here are the important coordinate systems which come up when using the canvas and writing custom canvas items:

• World coordinates are an absolute coordinate system; i.e., the same world coordinate refers to the same place on the canvas in all cases. World coordinates are conceptually infinite and are represented by a double. World coordinates are the real, toplevel, untransformed, canonical coordinate system. Consistent with the X Window System and GDK, Y coordinates increase as they move downward, so lower Y coordinates are toward the top of the canvas.

• Item coordinates are the coordinates used by a particular canvas item. Item coordinates exist because each canvas item has an affine transformation associated with it. In the case of GnomeCanvasGroup, this transformation is applied to the group's children. To convert from world coordinates to item coordinates for some particular item, you apply the transform for each canvas group in the item's ancestry, starting with the root canvas group; then you apply the item's own transform. (Don't worry, Gnome comes with a function to do this for you.) Like world coordinates, item coordinates are conceptually infinite.

• Canvas coordinates are pixel coordinates. While item and world coordinates are floating-point numbers, canvas pixel coordinates are integers. To use the canvas, you must specify a "scroll region," which is the rectangle in world coordinate space you want the user to be able to see. Canvas pixel coordinates are relative to this rectangle. Canvas pixel coordinates also take into account a scaling factor representing the number of pixels per world coordinate unit. To convert from world coordinates to canvas coordinates, the canvas subtracts the X and Y coordinates of the scroll region, multiplies by the scaling factor, and then rounds to an integer. Thus, (0,0) in canvas coordinates will be the top left corner of the scroll region.

• Buffer coordinates are canvas coordinates modified by some offset. Item implementations use these during rendering. The canvas passes the item implementation a buffer (which is either a GdkDrawable or an RGB buffer, depending on the canvas mode). The canvas tells the item implementation which region of the screen the buffer represents---the buffer region is defined by an X offset, Y offset, width and height. The X and Y offsets are in canvas coordinates, and are equivalent to (0,0) in buffer coordinates. To convert from canvas coordinates to buffer coordinates, simply subtract the offset. Buffer coordinates are only valid from (0,0) to the maximum width and height of the buffer.

• Window coordinates are rarely used. The canvas eventually copies each temporary buffer to a GdkWindow (to be precise,it copies them to GTK_LAYOUT(canvas)->bin_window). Window coordinates are relative to this GdkWindow. In some rare cases you might want to draw to the window directly rather than using a canvas item, or you might want to respond to an event on the window (such as a drag-and-drop). Then you need to convert from window coordinates to one of the other coordinate systems.

When using preexisting canvas items, you will mostly be interested in world and item coordinates. When writing your own items, you will also need to use canvas and buffer coordinates.

There are two ways to convert between the various coordinate systems; one way is to obtain and use affines directly---this is described in the next section. The easy way is to use one of the convenience functions provided for the purpose, shown in Figure 2. Conversion between canvas and item coordinates requires you to convert to world coordinates first as an intermediate step. There is no function to convert to or from buffer coordinates, because this is a simple matter of subtracting the buffer offsets from the canvas coordinates (canvas to buffer), or adding the buffer offsets to the buffer coordinates (buffer to canvas).

       #include <libgnomeui/gnome-canvas.h>
      

Affine Transformations

An affine is a transformation matrix made up of six real numbers that can be applied to an ordered pair. Depending on the contents of the affine, the point it is applied to can be:

• translated---shifted by an arbitrary distance in either dimension;

• rotated some number of degrees;

• scaled by some factor.

Conceptually, an affine defines a relationship between points on a plane. For any point (A,B), the affine defines a single corresponding transformed point; the mapping is one-to-one, so given the transformed point you can determine the original point.

Affines have interesting properties that make them useful in computer graphics. Most importantly, they can be composed, concatenated, or multiplied (the three terms are synonymous). You can compose any number of affines to create a single affine; applying the single affine has the same effect as applying each of the original affines in order. Note that the order of composition is important! Unlike multiplication, affine composition is not commutative (which is a reason to avoid the term "multiply" in this context).

libart_lgpl contains a module for affine manipulation. It represents affines as an array of six doubles. Its affine functions are shown in Figure 3.

       #include <libart_lgpl/art_affine.h>
      

art_affine_point() applies an affine to a point. The affine is applied to the second argument (src) and the result is copied into the first argument (dst). An ArtPoint is simply:

typedef struct _ArtPoint ArtPoint;

struct _ArtPoint {
  double x, y;
};

      

Affines can be inverted. If an affine converts points in coordinate system A into points in coordinate system B, its inverse converts points in coordinate system B into points in coordinate system A. art_affine_invert() fills its first argument with the inverse of its second.

art_affine_multiply() composes two affines as described earlier in this section, placing the result in its first argument.

Four functions are provided to create affines with particular properties.

• art_affine_identity() creates the identity affine. Applying the identity affine to a point has no effect.

• art_affine_rotate() gives an affine that rotates points by theta degrees.

• art_affine_translate() gives an affine that translates points tx in the X dimension and ty in the Y dimension.

• art_affine_scale() gives an affine which scales the plane by the given factors (a factor of 1.0 does no scaling, less than 1.0 shrinks, greater than 1.0 expands).

art_affine_rectilinear() returns TRUE if the affine rotates rectangles aligned to the axes in such a way that they remain aligned to the axes. That is, it returns TRUE if the rotation is 0, 90, 180, or 270 degrees.

You can ask the canvas widget to compute affines which convert between its various coordinate systems. These functions are shown in Figure 4; each of them fills an array you pass in with the affine being requested.

       #include <libgnomeui/gnome-canvas.h>