## 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

- `glue:A` : Specifies how a widget must fit in its own available place. `A` must be an atom that is any combination of `n`, `s`, `w` and `e`. If a direction is specified, the corresponding border is glued to its neighboor or border of the frame if there is no neighboor. If a direction is not specified, the corresponding border if such that the widget takes just the width or height it needs to draw itself. If none of opposite directions is specified, the widget is centered. For more details, see Section 4.1.

- `padx:P` : Specifies how much horizontal external padding to leave on each side of the widget. This space is added outside the widget border. `P` must be a valid screen distance (see Section 6.6)

- `pady:P` : Specifies how much vertical external padding to leave on each side of the widget. This space is added outside the widget border. `P` must be a valid screen distance (see Section 6.6)

- `feature:A` : Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. `A` must be an atom.

- `handle:V` : Specifies a variable to reference the object controlling this widget. This variable is binded when the window is built. For more details, see Section 4.2. `V` must be a free variable.

- `tooltips:VS` : Specifies a tooltip for the widget. A tooltip is a small message that appears when the mouse cursor if left still over the widget for a while. If `VS` is set to `nil`, no tooltip will appear at all. `VS` must be a virtual string.

- `look:L` : Specifies a look to use for the widget. A look specifies default values for the parameters of widgets. This parameter can be specified at creation time only. Moreover changing a look will not change the appearance of widgets that are already displayed with that look. See Section 6.2 for more details.

- `background:C` or `bg:C` : Specifies the normal background color to use when displaying the widget. `C` must be a valid color (see Section 6.1).

- `borderwidth:P` : Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the `relief` option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. `P` must be a valid screen distance (see Section 6.6).

- `cursor:A` : Specifies the mouse cursor to be used for the widget. `A` must be a valid cursor (see Section 6.7)

- `highlightbackground:C` : Specifies the color to display in the traversal highlight region when the widget does not have the input focus. `C` must be a valid color (see Section 6.1)

- `highlightcolor:C` : Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. `C` must be a valid color (see Section 6.1)

- `highlightthickness:P` : Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. If the value is zero, no focus highlight is drawn around the widget. `P` must be a valid screen distance (see Section 6.6).

- `insertbackground:C` : Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). `C` must be a valid color (see Section 6.1).

- `insertborderwidth:P` : Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. `P` must be a valid screen distance (see Section 6.6).

- `insertofftime:I` : Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``off'' in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time. `I` must be a positive integer value.

- `insertontime:I` : Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``on'' in each blink cycle. `I` must be a positive integer value.

- `insertwidth:P` : Specifies a value indicating the total width of the insertion cursor. If a border has been specified for the insertion cursor (using the `insertborderwidth` option), the border will be drawn inside the width specified by the `insertwidth` option. `P` must be a valid screen distance (see Section 6.6).

- `relief:A` : Specifies the 3-D effect desired for the widget. Must be one of these atoms : `raised`, `sunken`, `flat`, `ridge`, `solid` or `groove`. The value indicates how the interior of the widget should appear relative to its exterior; for example, `raised` means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

- `selectbackground:C` : Specifies the background color to use when displaying selected items. `C` must be a valid color (see Section 6.1).

- `selectborderwidth:P` : pecifies a non-negative value indicating the width of the 3-D border to draw around selected items. `P` must be a valid screen distance (see Section 6.6).

- `selectforeground:C` : Specifies the foreground color to use when displaying selected items. `C` must be a valid color (see Section 6.1).

- `takefocus:B` : Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the takeFocus option. A value of `false` means that the window should be skipped entirely during keyboard traversal. `true` means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). `B` must be a boolean.

- `closeenough:F` : Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be ``inside'' the item. Defaults to 1.0. `F` must be a float value.

- `confine:B` : Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the `scrollregion` argument. Defaults to true, which means that the view will be constrained within the scroll region. `B` must be a boolean.

- `height:P` : Specifies a desired window height that the canvas widget should request from its geometry manager. `P` must be a valid screen distance (see Section 6.6).

- `scrollregion:Q` : Specifies four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. `Q` must be a record of the form `q(X1 Y1 X2 Y2)`. `X1`, `Y1`, `X2` and `Y2` must be valid screen distances (see Section 6.6).

- `width:P` : Specifies a desired window width that the canvas widget should request from its geometry manager. `P` must be a valid screen distance (see Section 6.6).

- `xscrollincrement:P` : Specifies an increment for horizontal scrolling. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of `xscrollincrement`; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be `xscrollincrement`. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained. `P` must be a valid screen distance (see Section 6.6).

- `yscrollincrement:P` : Specifies an increment for vertical scrolling. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of `yscrollincrement`; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be `yscrollincrement`. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained. `P` must be a valid screen distance (see Section 6.6).

- `lrscrollbar:B` : Determines whether the widget has got a horizontal bar below. This option can be specified at creation time only. `B` must be a boolean.

- `tdscrollbar:B` : Determines whether the widget has got a vertical bar at the right. This option can be specified at creation time only. `B` must be a boolean.

- `scrollwidth:P` : Specifies the width of the vertical and horizontal scrollbars. `P` must be a valid screen distance (see Section 6.6)

### 5.2.3 Interface

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

- `set(parameter1:value1 ... parameterX:valueX)` : Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)` : Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables which will receive the current value of the parameters.

- `bind(event:E
  args:LA
  action:A)` : Specifies an action `LA` to execute when the event `E` is triggered. The event can have parameters (like mouse coordinates for a mouse click). You must explicitly ask in the `LA` list the parameters you are interested for. For more details, see Section 4.3.3.

- `getFocus(force:B)` : if `B` is `false` (which is the default) : if the application currently has the input focus on window's display, this command resets the input focus for window's display to window. If the application doesn't currently have the input focus on window's display, window will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, it will be redirected it to window. If `B` is `true` : sets the focus of window's display to window, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. `B` must be a boolean.

- `setGrab(global:B)` : Sets a grab on the widget. If `B` is `true` then the grab is global, otherwise it is local (`B` false by default). If a grab was already in effect for this application then it is automatically released. If there is already a grab on the widget and it has the same global/local form as the requested grab, then the command does nothing. Local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. Warning : whe a grab is set, it is define for the whole Oz process so that it will prevent the user to do input to other windows as well. Moreover a grab is still effective even if the window that contains the grabbed widgets is hidden. `B` must be a boolean.

- `releaseGrab` : Releases the grab on the widget if there is one, otherwise does nothing.

- `getGrabStatus(1:V)` : Binds `V` to the atom `none` if there is no grab on the widget, to the atom `local` if there is a local grab and to `global` if there is a global grab. `V` must be a free variable.

- `'raise'(1:W)` : If the `W` argument is omitted then the command raises the widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If `W` is specified then it must be an handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the `'raise'` command will insert this widget into the stacking order just above `W`; this could end up either raising or lowering window.

- `lower(1:W)` : If the `W` argument is omitted then the command lowers the widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). If `W` is specified then it must be an handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the `lower` command will insert this widget into the stacking order just below `W`; this could end up either raising or lowering window.

- `winfo(parameter1:value1 ... parameterX:valueX)` : This commands works like the `get` method, but for window-related information. For more details, see Section 6.9.

- `newTag(1:V)` : Binds `V` to a canvas tag (see Section 5.2.4 for details).

- `canvasx(1:I 2:V` or `canvasx(1:I 2:I 3:V)` : Returns the canvas x-coordinate corresponding to a window coordinate. The first parameter specifies the window coordinate. The methods binds the last parameter to the corresponding canvas coordinate. If a supplementary second parameter is given, then the canvas coordinate is rounded to the nearest multiple of that parameter.

- `canvasy(1:I 2:V` or `canvasy(1:I 2:I 3:V)` : Returns the canvas y-coordinate corresponding to a window coordinate. The first parameter specifies the window coordinate. The methods binds the last parameter to the corresponding canvas coordinate. If a supplementary second parameter is given, then the canvas coordinate is rounded to the nearest multiple of that parameter.

- `create(1:A ...)` : Creates a new item in the canvas of type `A`. The exact format of the arguments after type depends on type, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this command.

- `focus(1:R)` : Set the keyboard focus for the canvas widget to the item given by `R`. If `R` refers to several items, then the focus is set to the first such item in the display list that supports the insertion cursor. If `R` doesn't refer to any items, or if none of them support the insertion cursor, then the focus isn't changed. If `R` is an empty string, then the focus item is reset so that no item has the focus.

- `postscript(param1:value1 ... paramX:valueX` : Generate a Postscript representation for part or all of the canvas. The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions. Note: by default Postscript is only generated for information that appears in the canvas's window on the screen. If the canvas is freshly created it may still have its initial size of 1x1 pixel so nothing will appear in the Postscript. To get around this problem either invoke the `update` command to wait for the canvas window to reach its final size, or else use the `width` and `height` options to specify the area of the canvas to print. The option-value argument pairs provide additional information to control the generation of Postscript. The following options are supported:

  - `colormode:A` : Specifies how to output color information. `A` must be either `color` (for full color output), `gray` (convert all colors to their gray-scale equivalents) or `mono` (convert all colors to black or white).

  - `file:VS` : Specifies the name of the file in which to write the Postscript. `VS` must be a virtual string.

  - `height:P` : Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window. `P` must be a valid distance (see Section 6.6).

  - `pageanchor:A` : Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the `pagex` and `pagey` options). For example, `pageanchor:n` means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to `center`. `A` must be one the following atoms : `n`, `s`, `e`, `w`, `nw`, `ne`, `sw`, `se` or `center`.

  - `pageheight:P` : Specifies that the Postscript should be scaled in both x and y so that the printed area is `P` high on the Postscript page. Defaults to the height of the printed area on the screen. If both `pageheight` and `pagewidth` are specified then the scale factor from `pagewidth` is used (non-uniform scaling is not implemented). `P` must be a valid distance (see Section 6.6).

  - `pagewidth:P` : Specifies that the Postscript should be scaled in both x and y so that the printed area is `P` wide on the Postscript page. Defaults to the width of the printed area on the screen. If both `pageheight` and `pagewidth` are specified then the scale factor from `pagewidth` is used (non-uniform scaling is not implemented). `P` must be a valid distance (see Section 6.6).

  - `pagex:P` : `P` gives the x-coordinate of the positioning point on the Postscript page. Used in conjunction with the `pagey` and `pageanchor` options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. `P` must be a valid distance (see Section 6.6).

  - `pagey:P` : `P` gives the y-coordinate of the positioning point on the Postscript page. Used in conjunction with the `pagex` and `pageanchor` options to determine where the printed area appears on the Postscript page. Defaults to the center of the page. `P` must be a valid distance (see Section 6.6).

  - `rotate:B` : Specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page (``portrait'' orientation); in rotated output the x-axis runs along the long dimension of the page (``landscape'' orientation). Defaults to non-rotated. `B` must be a boolean.

  - `width:P` : Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window. `P` must be a valid distance (see Section 6.6).

  - `x:P` : Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window. `P` must be a valid distance (see Section 6.6).

  - `y:P` : Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window. `P` must be a valid distance (see Section 6.6).

- `scan(...)` : This command is used to implement scanning on canvases. It has two forms, depending on option:

  - `scan(mark X Y)` : Records x and y and the canvas's current view; used in conjunction with later `scan(dragto ...)` commands. Typically this command is associated with a mouse button press in the widget and `X` and `Y` are the coordinates of the mouse. `X` and `Y` must be valid distances (see Section 6.6).

  - `scan(dragto X Y)` : This command computes the difference between its `X` and `Y` arguments (which are typically mouse coordinates) and the `X` and `Y` arguments to the last `scan(mark ...)` command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window.

- `select(...)` : Manipulates the selection in one of several ways, depending on option. The command may take any of the forms described below. In all of the descriptions below, `Tag` must refer to an item that supports indexing and selection; if it refers to multiple items then the first of these that supports indexing and the selection is used.

  - `select(adjust Tag I)` : Locate the end of the selection in `Tag` nearest to the character given by `I`, and adjust that end of the selection to be at `I` (i.e. including but not going beyond `I`). The other end of the selection is made the anchor point for future select to commands. If the selection isn't currently in `I` then this command behaves the same as the `select(to ...)` widget command.

  - `select(clear)` : Clear the selection if it is in this widget. If the selection isn't in this widget then the command has no effect.

  - `select(from Tag I)` : Set the selection anchor point for the widget to be just before the character given by `I` in the item given by `Tag`. This command doesn't change the selection; it just sets the fixed end of the selection for future `select(to ...)` commands.

  - `select(to Tag I)` : Set the selection to consist of those characters of `Tag` between the selection anchor point and `I`. The new selection will include the character given by `I`; it will include the character given by the anchor point only if index is greater than or equal to the anchor point. The anchor point is determined by the most recent `select(adjust ...)` or `select(from ...)` command for this widget. If the selection anchor point for the widget isn't currently in `Tag`, then it is set to the same character given by `I`.

### 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 :

- `I` : A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item.

- `end` : Refers to the character just after the last one in the item (same as the number of characters in the item).

- `insert` : Refers to the character just before which the insertion cursor is drawn in this item.

- `'self.first'` : Refers to the first selected character in the item. If the selection isn't in this item then this form is illegal.

- `'self.last'` : Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal.

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

- `set(param1:value1 ... paramX:valueX)` : This command is similar to `set` except that it modifies item-specific options for the items of the tag instead of modifying options for the overall canvas widget. The command modifies the given widget option(s) to have the given value(s) in each of the items of the tag. The options and values are the same as those permissible in the `create(...)` method when the item(s) were created; see the sections describing individual item types below for details on the legal options.

- `get(param1:Variable1 ... paramX:VariableX)` : This command is similar to `get` except that it obtains item-specific options for the items of the tag instead of obtaining options for the overall canvas widget. `paramX` may have any of the values accepted by the `create(...)` method when the item was created. If the tag refers to more than one item, the first (lowest) such item is used.

- `addtag(...)` : Adds items to the list of items managed by the tag. The parameters of the command designate the items to select to add to the list of items managed by the tag. This command can take several forms :

  - `addtag(abvode Tag)` : Selects the item just after (above) the one given by `Tag` in the display list. If `Tag` denotes more than one item, then the last (topmost) of these items in the display list is used.

  - `addtag(all)` : Selects all the items in the canvas.

  - `addtag(below Tag)` : Selects the item just before (below) the one given by `Tag` in the display list. If `Tag` denotes more than one item, then the first (lowest) of these items in the display list is used.

  - `addtag(closest X Y ?Halo? ?Start?)` : Selects the item closest to the point given by `X` and `Y`. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If `Halo` is specified, then it must be a non-negative value. Any item closer than `Halo` to the point is considered to overlap it. The start argument may be used to step circularly through all the closest items. If `Start` is specified, it is a tag and it selects the first item in the display list with the given that tag. Instead of selecting the topmost closest item, this form will select the topmost closest item that is below `Start` in the display list; if no such item exists, then the selection behaves as if the `Start` argument had not been specified.

  - `addtag(enclosed X1 Y1 X2 Y2)` : Selects all the items completely enclosed within the rectangular region given by `X1`, `Y1`, `X2`, and `Y2`. `X1` must be no greater then `X2` and `Y1` must be no greater than `Y2`.

  - `addtag(overlapping X1 Y1 X2 Y2)` : Selects all the items that overlap or are enclosed within the rectangular region given by `X1`, `Y1`, `X2`, and `Y2`. `X1` must be no greater then `X2` and `Y1` must be no greater than `Y2`.

  - `addtag(withtag Tag)` : Selects all the items given by Tag.

- `bbox(Tag1 ... TagX V)` : Binds `V` to a list of four integers giving an approximate bounding box for all the items named by the tag and `Tag1` to `TagX` (if these are supplied). The list The return value may overestimate the actual bounding box by a few pixels.

- `bind(event:VS
  args:LA
  action:A)` : This command associates the `A` command with all the items given of the tag such that whenever the event sequence given by `VS` occurs for one of the items `A` will be invoked with the parameters specified in the `LA` list. This method is similar to the `bind` method for widgets except that it operates on items in a canvas rather than entire widgets. See this specific method for all parameters supported by this method. The only events for which bindings may be specified are those related to the mouse and keyboard (such as `Enter`, `Leave`, `ButtonPress`, `Motion`, and `KeyPress`) or virtual events. `Enter` and `Leave` events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than `Enter` and `Leave` events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the `getFocus` method below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event. It is possible for multiple bindings to match a particular event. When this occurs, all of the matching bindings are invoked. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. If bindings have been created for a canvas window using the `bind` method , then they are invoked in addition to bindings created for the canvas's items. The bindings for items will be invoked before any of the bindings for the window as a whole.

- `delete` : Delete all items in the tag.

- `getCoords(1:L)` : Binds L to a list of integers that are coordinates for the first item in the display list of the tag.

- `setCoords(X1 Y1 ... Xn Yn)` : Modify the coordinates of the first item in the display list defined by the tag. The number of coordinates you may enter depends on the number of coordinates supported by this item.

- `dchars(F L)` : For each item given in the tag, delete the characters in the range given by `F` and `L`, inclusive. If some of the items don't support text operations, then they are ignored. `F` and `L` must have one of the forms described above for textual indices.

- `focus` : Set the keyboard focus for the canvas widget to the first item of the tag that supports the insertion cursor. Once the focus has been set to an item, the item will display the insertion cursor and all keyboard events will be directed to that item. The focus item within a canvas and the focus window on the screen (set with the focus command) are totally independent: a given item doesn't actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the focus widget command with the focus command to set the focus window to the canvas (if it wasn't there already).

- `icursor(I)` : Set the position of the insertion cursor for the item(s) in the tag to just before the character whose position is given by `I`. If some or all of the items don't support an insertion cursor then this command has no effect on them. `I` must have one of the forms described above for textual indices. Note: the insertion cursor is only displayed in an item if that item currently has the keyboard focus, but the cursor position may be set even when the item doesn't have the focus.

- `index(I V)` : Binds `V` to the numerical index corresponding to `V` for the first item in tag that support text indices. `I` must have one of the forms described above for textual indices.

- `insert(I VS)` : For all items in tag that supports text insertion, `VS` is inserted just before the character at position `I`.

- `lower` : Move all of the items ine the tag to a new position in the display list, depending on the form of the call :

  - `lower()` : All items are moved below all other items.

  - `lower(Tag)` : All items are moved just below the lowest item in `Tag`.

  Note: this command has no effect on window items. Window items always obscure other item types.

- `move(X Y)` : Move all items in tag in the canvas coordinate space by adding `X` to the x-coordinate of each point associated with the item and `Y` to the y-coordinate of each point associated with the item.

- `'raise'` : Move all of the items ine the tag to a new position in the display list, depending on the form of the call :

  - `'raise'()` : All items are moved above all other items.

  - `'raise'(Tag)` : All items are moved just above the highest item in `Tag`.

  Note: this command has no effect on window items. Window items always obscure other item types.

- `scale(X Y SX SY)` : Rescale all of the items in the tag. `X` and `Y` identify the origin for the scaling operation and `SX` and `SY` identify the scale factors for x- and y-coordinates, respectively (a scale factor of 1.0 implies no change to that coordinate). For each of the points defining each item, the x-coordinate is adjusted to change the distance from `X` by a factor of `SX`. Similarly, each y-coordinate is adjusted to change the distance from `Y` by a factor of `SY`.

- `type(V)` : Binds `V` to an atom that is the type of the first item in tag.

### 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:

- `extent:I` : Specifies the size of the angular range occupied by the arc. The arc's range extends for degrees degrees counter-clockwise from the starting angle given by the `start` option. Degrees may be negative. If it is greater than 360 or less than -360, then degrees modulo 360 is used as the extent. `I` must be an integer.

- `fill:C` : Fill the region of the arc with the color `C`. `C` must be a valid color (see Section 6.1) or `nil` for a non-filled arc.

- `outline:C` : `C` specifies a color to use for drawing the arc's outline. `C` must be a valid color (see Section 6.1) or `nil` for no outline.

- `outlinestipple:B` : Indicates that the outline for the arc should be drawn with a stipple pattern; `B` specifies the stipple pattern to use or nil for no bitmap.

- `start:I` : Specifies the beginning of the angular range occupied by the arc. `I` is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative.

- `stipple:B` : Indicates that the arc should be filled in a stipple pattern; `B` specifies the stipple pattern to use. If the `fill` option hasn't been specified then this option has no effect. If `B` is `nil` then filling is done in a solid fashion.

- `style:A` : Specifies how to draw the arc. If `A` is the atom `pieslice` (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If `A` is the atom `chord` then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. If `A` is the atom `arc` then the arc's region consists of a section of the perimeter alone. In this last case the `fill` option is ignored.

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:C` : Specifies the width of the outline to be drawn around the arc's region. If the `outline` option has been specified as `nil` then this option has no effect. Wide outlines will be drawn centered on the edges of the arc's region. This option defaults to `1.0`. `C` must be a valid screen distance (see Section 6.6).

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:

- `anchor:A` : Specifies how to position the bitmap relative to the positioning point for the item. `A` must be one of the following atoms : `center`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w` or `nw`. This option defaults to `center`.

- `background:C` : Specifies a color to use for each of the bitmap pixels whose value is 0. `C` must be a valid color (see Section 6.1). If this option isn't specified, or if it is specified as `nil`, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect.

- `bitmap:B` : Specifies the bitmap to display in the item. `B` must be a bitmap generated by the `QTk.newBitmap` command, or and atom specifying one of the built-in bitmaps.

- `foreground:C` : Specifies a color to use for each of the bitmap pixels whose value is 1. `C` must be a valid color (see Section 6.1).

- `tags:Tag` : Specifies a tag to apply to the item.

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:

- `anchor:A` : Specifies how to position the bitmap relative to the positioning point for the item. `A` must be one of the following atoms : `center`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w` or `nw`. This option defaults to `center`.

- `image:I` : Specifies the image to display in the item. `I` must be an image generated by the `QTk.newImage` command.

- `tags:Tag` : Specifies a tag to apply to the item.

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:

- `arrow:A` : Indicates whether or not arrowheads are to be drawn at one or both ends of the line. `A` must have be one of the following atoms : `none` (for no arrowheads), `first` (for an arrowhead at the first point of the line), `last` (for an arrowhead at the last point of the line), or `both` (for arrowheads at both ends). This option defaults to `none`.

- `arrowshape:S` : Specifies how to draw arrowheads. The shape argument must be a record of the form `q(I1 I2 I3)` with `I1`, `I2` and `I3` integers. `I1` gives the distance along the line from the neck of the arrowhead to its tip. `I2` gives the distance along the line from the trailing points of the arrowhead to the tip, and `I3` gives the distance from the outside edge of the line to the trailing points. If this option isn't specified then a ``reasonable'' shape is taken.

- `capstyle:A` : Specifies the ways in which caps are to be drawn at the endpoints of the line. `A` must be one of the following atoms : `butt`, `projecting` or `round`. If this option isn't specified then it defaults to `butt`. Where arrowheads are drawn the cap style is ignored.

- `fill:C` : Specifies a color to use for drawing the line. `C` must be a valid color (see Section 6.1) or `nil` for a non-filled arc.

- `joinstyle:A` : Specifies the ways in which joints are to be drawn at the vertices of the line. `A` must be one of the following atoms: `bevel`, `miter` or `round`. If this option isn't specified then it defaults to `miter`. If the line only contains two points then this option is irrelevant.

- `smooth:B` : Specifies whether or not the line should be drawn as a curve. If so, the line is rendered as a set of parabolic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment. `B` must be a boolean.

- `splinesteps:I` : Specifies the degree of smoothness desired for curves: each spline will be approximated with `I` line segments. This option is ignored unless the `smooth` option is true. `I` must be an integer.

- `stipple:B` : Indicates that the line should be filled in a stipple pattern; `B` specifies the stipple pattern to use. If the `fill` option hasn't been specified then this option has no effect. If `B` is `nil` then filling is done in a solid fashion.

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:I` : Specifies the width of the line. Wide lines will be drawn centered on the path specified by the points. If this option isn't specified then it defaults to 1.0.

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:

- `fill:C` : Specifies a color to fill the area of the oval. `C` must be a valid color (see Section 6.1) or `nil` for a non-filled oval.

- `outline:C` : `C` specifies a color to use for drawing the oval's outline. `C` must be a valid color (see Section 6.1) or `nil` for no outline.

- `stipple:B` : Indicates that the oval should be filled in a stipple pattern; `B` specifies the stipple pattern to use. If the `fill` option hasn't been specified then this option has no effect. If `B` is `nil` then filling is done in a solid fashion.

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:I` : Specifies the width of the outline of the oval. Wide outlines are drawn centered on the oval path defined by `X1`, `Y1`, `X2`, and `Y2`. If this option isn't specified then it defaults to 1.0.

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:

- `fill:C` : Specifies a color to fill the area of the polygon. `C` must be a valid color (see Section 6.1) or `nil` for a non-filled oval.

- `outline:C` : `C` specifies a color to use for drawing the polygon's outline. `C` must be a valid color (see Section 6.1) or `nil` for no outline.

- `smooth:B` : Specifies whether or not the polygon should be drawn with a curved perimeter. If so, the outline of the polygon becomes a set of parabolic splines, one spline for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated in a smoothed polygon by duplicating the end-points of the desired line segment. `B` must be a boolean.

- `splinesteps:I` : Specifies the degree of smoothness desired for curves: each spline will be approximated with `I` line segments. This option is ignored unless the `smooth` option is `true`. `I` must be an integer.

- `stipple:B` : Indicates that the polygon should be filled in a stipple pattern; `B` specifies the stipple pattern to use. If the `fill` option hasn't been specified then this option has no effect. If `B` is `nil` then filling is done in a solid fashion.

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:I` : Specifies the width of the outline of the polygon. Wide outlines are drawn centered on the polygon path defined by `X1`, `Y1`, `X2`, and `Y2`. If this option isn't specified then it defaults to 1.0.

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:

- `fill:C` : Specifies a color to fill the area of the rectangle. `C` must be a valid color (see Section 6.1) or `nil` for a non-filled rectangle.

- `outline:C` : `C` specifies a color to use for drawing the rectangle's outline. `C` must be a valid color (see Section 6.1) or `nil` for no outline.

- `stipple:B` : Indicates that the rectangle should be filled in a stipple pattern; `B` specifies the stipple pattern to use. If the `fill` option hasn't been specified then this option has no effect. If `B` is `nil` then filling is done in a solid fashion.

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:I` : Specifies the width of the outline of the rectangle. Wide outlines are drawn centered on the rectanglar path defined by `X1`, `Y1`, `X2`, and `Y2`. If this option isn't specified then it defaults to 1.0.

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:

- `anchor:A` : Specifies how to position the text relative to the positioning point for the item. `A` must be one of the following atoms : `center`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w` or `nw`. This option defaults to `center`.

- `fill:C` : Specifies a color to fill the text characters. `C` must be a valid color (see Section 6.1).

- `font:F` : Specifies the font to use for the text item. `F` must be a valid font (see Section 6.8)

- `justify:A` : Specifies how to justify the text within its bounding region. `A` must be one of the floowing atoms : `left`, `right` or `center`. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to `left`.

- `stipple:B` : Indicates that the text should be drawed in a stippled pattern; `B` specifies the stipple pattern to use. If `B` is `nil` then filling is done in a solid fashion.

- `tags:Tag` : Specifies a tag to apply to the item.

- `text:VS` : Specifies the characters to be displayed in the text item. Newline characters cause line breaks. `VS` must be an empty string.

- `width:I` : Specifies a maximum line length for the text. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than `I` is broken just before a space character to make the line shorter than `I`; the space character is treated as if it were a newline character.

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:

- `anchor:A` : Specifies how to position the window relative to the positioning point for the item. `A` must be one of the following atoms : `center`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w` or `nw`. This option defaults to `center`.

- `height:P` : Specifies the height to assign to the item's window. If this option isn't specified, or if it is specified as `nil`, then the window is given whatever height it requests internally. `P` must be a valid screen distance (see Section 6.6).

- `tags:Tag` : Specifies a tag to apply to the item.

- `width:P` : Specifies the width to assign to the item's window. If this option isn't specified, or if it is specified as `nil`, then the window is given whatever width it requests internally. `P` must be a valid screen distance (see Section 6.6).

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.