7.2 Canvas widget

local C Desc=canvas(handle:C width:200 height:200)in {{QTk.build td(Desc)} show} {C create(rect 10 10 190 190 fill:blue outline:red)} {C create(text 100 100 text:"Canvas" fill:yellow)}end

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. The coordinates can be specified either as floats or integers, but they are returned as floats only.

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

7.2.2 Parameter List

Specific Parameters

closeenough confine height scrollregion width xscrollincrement yscrollincrement

Non Specific Parameters

background borderwidth cursor feature glue handle highlightbackground highlightcolor highlightthickness insertbackground insertborderwidth insertofftime insertontime insertwidth look lrscrollbar onCreation padx pady relief scrollwidth selectbackground selectborderwidth selectforeground takefocus tdscrollbar tooltips

7.2.3 Method List

'raise'

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

bind

bind(event:E action:A args:LA append:AP): Specifies an action LA to execute when the event E is triggered.

Actions can be specified either as a procedure, a pair Port#Message or a pair Object#Method (see Section 4.3.3).
Events are strings (see Section 8.11.1).
The list of arguments LA specifies supplementary information to pass to the action, like the key code of a keypress, or the mouse coordinates of a mouse button click (see Section 8.11.2). If LA if not specified, nil is assumed.
The boolean append parameter specifies if the binding overrides the previous binding for this event, or adds a supplementary action. If not specified, false is assumed.

canvasx

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. This method 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

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. This method 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

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. If a handle parameter is specified, it is bound to an Oz object controlling the canvas item. See the subsections on individual item types below for more on the syntax of this command.

focus

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.

get

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 that will receive the current value of the parameters.

getFocus

getFocus(force:B): if B is false (or by default): if the application currently has the input focus on the widget's display, this command resets the input focus for the widget's display to the widget. If the application doesn't currently have the input focus on the widget's display, the widget 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 the widget. If B is true: sets the focus of the widget's display to the widget, 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.

getGrabStatus

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.

lower

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

newTag

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

postscript

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 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 8.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 8.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 8.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 8.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 8.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 8.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 8.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 8.6).

releaseGrab

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

scan

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 8.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

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.

set

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.

setGrab

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 willbe reported to other applications as if the grab had never occurred. A global grablocks out all applications on the screen, so that only the given subtree of the grabbing application will besensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, andwindow 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.

winfo

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

7.2.4 Detailed Parameters List

closeenough

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

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

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 8.6).

background

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

borderwidth

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 8.6).

cursor

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

feature

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.

glue

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 neighbor or border of the frame if there is no neighbor. 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.

handle

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

highlightbackground

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 8.2)

highlightcolor

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 8.2)

highlightthickness

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 8.6).

insertbackground

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 8.2).

insertborderwidth

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 8.6).

insertofftime

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

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

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 8.6).

look

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 5.1 for more details.

lrscrollbar

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.

onCreation

onCreation:P: When a widget is created, for example by QTk.build, this parameter specifies an action to execute right after the widget has been created, but before returning from the build instruction. It is usefull if one needs the handle of the widget to initialize it in ways not permitted by its description record (for example binding the Enter or Leave mouse events).

padx

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 8.6)

pady

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 8.6)

relief

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.

scrollwidth

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

selectbackground

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

selectborderwidth

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 8.6).

selectforeground

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

takefocus

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 widget should be skipped entirely during keyboard traversal. true means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.

tdscrollbar

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.

tooltips

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.

scrollregion

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 8.6).

width

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 8.6).

xscrollincrement

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 8.6).

yscrollincrement

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 8.6).

7.2.5 Canvas item handles and canvas tags

When creating an item, it is possible to ask for a handle to further manipulate this item. Another way of manipulating items is to by means of canvas tags. Zero, one or more canvas items can be assigned to a single tag. A tag is an Oz object that manipulates all items that are assigned to it. Tags are obtained by the newTag($) method and are assigned to items by their tag parameter. Canvas tags and canvas items objects support the same methods. The handle to a canvas item can be seen as a private tag for this item only. As such, the documentation below will only refer to tags, implicitely implying handle to canvas items also.

Note: 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.

Methods supported by canvas tags and canvas items handles:

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(...) (Warning: This method is supported for canvas tags only): Adds items to the list of items managed by the tag. The parameters of the command designate the items to add to the list of items managed by the tag. This command can take several forms :
- addtag(above 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 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 returned values 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 widgets. 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). 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 in 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 in 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.

7.2.6 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 8.2) 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 8.2) 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 8.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 8.2). 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 a Tk pre-defined bitmap to display in the item, or a file containing a bitmap description in the standard X11 or X10 format. The exact way in which the bitmap is displayed may be affected by other options such as anchor or justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both bitmap and image options, image will usually override bitmap. This parameter can't be get at runtime, however it can be set. B can be one of these atoms: error, gray75, gray50, gray25, gray12, hourglass, info, questhead, question, warning, or B can be a virtual string beginning by @ and then containing the name of a bitmap description in the standard X11 or X10 format like "@x11.xbm" for example.
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 8.2).
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 (see Section 8.4).
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 8.2) 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 8.2) 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 8.2) 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 8.2) 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 8.2) 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 8.2) 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 8.2) 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 8.2).
font:F: Specifies the font to use for the text item. F must be a valid font (see Section 8.8)
justify:A: Specifies how to justify the text within its bounding region. A must be one of the these 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 8.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 8.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.