5.2 Canvas widget

5.2.1 Description

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and commands may be associated with items in much the same way that the bind command allows commands to be bound to widgets. This means that items in a canvas can have behaviors defined by the Oz commands bound to them.

Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the xview and yview widget commands; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system.

Individual items may be moved or scaled using widget commands described below, but they may not be rotated.

5.2.2 Parameters

5.2.3 Interface

The object you get by an handle on the widget implements the following methods :

5.2.4 Canvas tags

Warning : this model is subject to changes in the future.

Several graphical objects can be manipulated together by assigning them the same tag. Tags are obtained by the newTag($) method and are assigned to items by their tag parameter.

When manipulating text items, particular positions of the charaters are specified by one of the following form :

A tag is an object that allow to manipulate its items by the following methods :

5.2.5 Graphical items

The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the create method used to create instances of the type; and second, a set of configuration options for items of that type.

ARC ITEMS

Items of type arc appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified by the start and extent options) and displayed in one of several ways (specified by the style option). Arcs are created with widget commands of the following form:

create(arc X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)

The arguments X1, Y1, X2, and Y2 give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval that defines the arc. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure widget commands to change the item's configuration. The following options are supported for arcs:

BITMAP ITEMS

Items of type bitmap appear on the display as images with two colors, foreground and background. Bitmaps are created with widget commands of the following form:

create(bitmap X Y param1:value1 ... paramX:valueX)

The arguments X and Y specify the coordinates of a point used to position the bitmap on the display (see the anchor option below for more information on how bitmaps are displayed). After the coordinates there may be any number of parameters, each of which sets one of the configuration options for the item. The following options are supported for bitmaps:

IMAGE ITEMS

Items of type image are used to display images on a canvas. Images are created with widget commands of the following form:

create(image X Y param1:value1 ... paramX:valueX)

The arguments X and Y specify the coordinates of a point used to position the image on the display (see the anchor option below for more information). After the coordinates there may be any number of parameters, each of which sets one of the configuration options for the item. The following options are supported for images:

LINE ITEMS

Items of type line appear on the display as one or more connected line segments or curves. Lines are created with widget commands of the following form:

create(line X1 Y1 ... Xn Yn param1:value1 ... paramX:valueX)

The arguments X1 through Yn give the coordinates for a series of two or more points that describe a series of connected line segments. After the coordinates there may be any number of parameters, each of which sets one of the configuration options for the item. The following options are supported for lines:

OVAL ITEMS

Items of type oval appear as circular or oval regions on the display. Each oval may have an outline, a fill, or both. Ovals are created with widget commands of the following form:

create(oval X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)

The arguments X1, Y1, X2, and Y2 give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval. The oval will include the top and left edges of the rectangle not the lower or right edges. If the region is square then the resulting oval is circular; otherwise it is elongated in shape. After the coordinates there may be any number of parameters, each of which sets one of the configuration options for the item. The following parameters are supported for ovals:

POLYGON ITEMS

Items of type polygon appear as polygonal or curved filled regions on the display. Polygons are created with widget commands of the following form:

create(polygon X1 Y1 ... Xn Yn param1:value1 ... paramX:valueX)

The arguments X1 through Yn specify the coordinates for three or more points that define a closed polygon. The first and last points may be the same; whether they are or not, the polygon if drawed as a closed polygon. After the coordinates there may be any number of parameters, each of which sets one of the configuration options for the item. The following parameters are supported for polygons:

Polygon items are different from other items such as rectangles, ovals and arcs in that interior points are considered to be ``inside'' a polygon even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead.

RECTANGLE ITEMS

Items of type rectangle appear as rectangular regions on the display. Each rectangle may have an outline, a fill, or both. Rectangles are created with widget commands of the following form:

create(rectangle X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)

The arguments X1, Y1, X2, and Y2 give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of parameters for the item. The following parameters are supported for rectangles:

TEXT ITEMS

A text item displays a string of characters on the screen in one or more lines. Text items support indexing and selection, along with the following tag methods: dchars, focus, icursor, index, insert, select. Text items are created with widget commands of the following form:

create(text X Y param1:value1 ... paramX:valueX)

The arguments X and Y specify the coordinates of a point used to position the text on the display (see the options below for more information on how text is displayed). After the coordinates there may be any number of paremeters. The following parameters are supported for text items:

WINDOW ITEMS

Items of type window cause a particular window to be displayed at a given position on the canvas. Window items are created with widget commands of the following form:

create(window X Y window:Desc param1:value1 ... paramX:valueX)

The arguments X and Y specify the coordinates of a point used to position the window on the display. The Desc parameter is a usual description of a window (like td(...)) that is to display. After these parameters there may be any number of parameters. The following options are supported for window items:

Note: due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list.


Donatien Grolaux
Version 1.2.3 (20011129)