Gnome Developers' Information
<<< Previous | The GnomeCanvas widget | Next >>>

# Organization of items

Items in the canvas are organized in a tree hierarchy. Items can be groups (nodes in the tree), or terminal items (leaves in the tree). Groups can contain any number of children, which can be terminal items or other groups. Thus, items can be nested to an arbitrary depth inside a canvas.

A canvas has a single root group. For simple drawings, it is likely that you will want to put all your items directly inside this group. For more complex drawings, it may be convenient to use a hierarchical structure of nested canvas groups.

For example, consider a circuit editor. You could define groups that contain the items that are necessary to draw a certain type of logic gate. Then you could define groups for different components. A group representing an adder would contain several logic gates and some wires. You would then group some adders with other components to form a more complex circuit. This makes it convenient to handle whole hierarchies as single entities, for when you want to move all the items that define a chain of adders, for example.

## Stacking order

The items you put inside groups are stacked on top of each other, and items nearer the top of the stack obscure the items below them. When an item is created, it is put on top of all the items in its parent group.

The canvas provides several functions to let you change the stacking order of items inside groups. You can move items to the top or bottom of their parent group, and raise or lower them by an arbitrary number of positions.

## Behavior and events

The canvas does not have any predefined behavior for items. You can define the behavior of items by explicitly operating on them (change the color if item Foo when the user selects a menu item), or by defining actions that should take place when items receive events (let the user drag items with the mouse).

The rationale behind this is that the canvas should be as general-purpose as possible. If it had predefined behavior for items, it may not be suitable to all kinds of applications — a program for drawing schematic diagrams may benefit from having dragging functionality predefined in the canvas, but this would not be very useful (or even desirable) for a calendar display program.

<<< Previous | Home | Next >>>
The GnomeCanvas widget | Up | Coordinates