<section ID="chapter.widgets.canvas">
  <TITLE>Canvas widget</TITLE>

<subsection> <TITLE>Description</TITLE>

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

</P>

<P>
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. 
</P>

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


<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;
&param_background;
&param_borderwidth;
&param_cursor;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;
&param_insertbackground;
&param_insertborderwidth;
&param_insertofftime;
&param_insertontime;
&param_insertwidth;
&param_relief;
&param_selectbackground;
&param_selectborderwidth;
&param_selectforeground;
&param_takefocus;

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

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

<ITEM> <<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  <ptr to="misc.distance">).

<ITEM> <<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  <ptr to="misc.distance">).

<ITEM> <<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  <ptr to="misc.distance">).

<ITEM> <<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  <ptr to="misc.distance">).

<ITEM> <<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  <ptr to="misc.distance">).

&param_lrscrollbar;
&param_tdscrollbar;
&param_scrollwidth;

</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

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

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

<ITEM> <<newTag(1:V)>> : Binds <<V>> to a canvas tag (see <ptr to="canvas.tags"> for details).

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

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

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

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

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

<LIST>

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

<ITEM> <<file:VS>> : Specifies the name of the file in which to write the Postscript. <<VS>> must be a virtual string.

<ITEM> <<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 <ptr to="misc.distance">).

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

<ITEM> <<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 <ptr to="misc.distance">). 

<ITEM> <<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 <ptr to="misc.distance">). 

<ITEM> <<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 <ptr to="misc.distance">). 

<ITEM> <<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 <ptr to="misc.distance">). 

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

<ITEM> <<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 <ptr to="misc.distance">).

<ITEM> <<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 <ptr to="misc.distance">).

<ITEM> <<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 <ptr to="misc.distance">).

</LIST>


<ITEM> <<scan(...)>> : This command is used to implement scanning on canvases. It has two forms, depending
    on option: 
<LIST>
<ITEM> <<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 <ptr to="misc.distance">).

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

</LIST>

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

<LIST>
<ITEM> <<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.

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

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

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

</LIST>

</LIST>


<subsection id="canvas.tags"><TITLE>Canvas tags</TITLE>

<P>
Warning : this model is subject to changes in the future.
</P>
<P>
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. 
</P>
<P>
When manipulating text items, particular positions of the charaters are specified by one of the following form :
<LIST>
<ITEM> <<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.
<ITEM> <<end>> : Refers to the character just after the last one in the item (same as the number of characters in the item).
<ITEM> <<insert>> : Refers to the character just before which the insertion cursor is drawn in this item.
<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.
<ITEM> <<'self.last'>> : Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal.
</LIST>
</P>
<P>
A tag is an object that allow to manipulate its items by the following methods :

<LIST>

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

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

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

<LIST>

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

<ITEM> <<addtag(all)>> : Selects all the items in the canvas. 

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

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

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

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

<ITEM> <<addtag(withtag Tag)>> : Selects all the items given by Tag.

</LIST>

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

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

<ITEM> <<delete>> : Delete all items in the tag.

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

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

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

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

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

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

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

<ITEM> <<lower>> : Move all of the items ine the tag to a new position in the display list, depending on the form of the call :
<LIST> 
<ITEM> <<lower()>> : All items are moved below all other items.
<ITEM> <<lower(Tag)>> : All items are moved just below the lowest item in <<Tag>>.
</LIST>
Note: this command has no effect on window items. Window items always obscure other item types. 

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

<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 :
<LIST> 
<ITEM> <<'raise'()>> : All items are moved above all other items.
<ITEM> <<'raise'(Tag)>> : All items are moved just above the highest item in <<Tag>>.
</LIST>
Note: this command has no effect on window items. Window items always obscure other item types. 

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

<ITEM> <<type(V)>> : Binds <<V>> to an atom that is the type of the first item in tag.

</LIST>

<subsection id="canvas.items"><TITLE>Graphical items</TITLE>

<P>
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. 
</P>
<P>
<EM> ARC ITEMS </EM>
</P>
<P>
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: 
<CODE DISPLAY>create(arc X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)</CODE>
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: 

<LIST>

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

<ITEM> <<fill:C>> : Fill the region of the arc with the color <<C>>. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for a non-filled arc.

<ITEM> <<outline:C>> : <<C>> specifies a color to use for drawing the arc's outline. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for no outline.

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

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

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

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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 <ptr to="misc.distance">).

</LIST>
</P>
<P>
<EM>BITMAP ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(bitmap X Y param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>
<ITEM> <<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>>. 

<ITEM> <<background:C>> : Specifies a color to use for each of the bitmap pixels whose value is 0. <<C>> must be a valid color (see <ptr to="misc.color">). 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. 

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

<ITEM> <<foreground:C>> : Specifies a color to use for each of the bitmap pixels whose value is 1. <<C>> must be a valid color (see <ptr to="misc.color">).

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

</LIST>
</P>
<P>
<EM>IMAGE ITEMS</EM>
</P>
<P>
Items of type image are used to display images on a canvas. Images are created with widget
commands of the following form: 
<CODE DISPLAY>create(image X Y param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>
<ITEM> <<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>>. 

<ITEM> <<image:I>> : Specifies the image to display in the item. <<I>> must be an image generated by the <<QTk.newImage>> command.

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

</LIST>
</P>
<P>
<EM>LINE ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(line X1 Y1 ... Xn Yn param1:value1 ... paramX:valueX)</CODE>
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: 
</P>
<P>
<LIST>
<ITEM> <<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>>. 

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

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

<ITEM> <<fill:C>> : Specifies a color to use for drawing the line. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for a non-filled arc.

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

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

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

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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. 
</LIST>
</P>
<P>
<EM>OVAL ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(oval X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>

<ITEM> <<fill:C>> : Specifies a color to fill the area of the oval. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for a non-filled oval.

<ITEM> <<outline:C>> : <<C>> specifies a color to use for drawing the oval's outline. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for no outline.

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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. 
</LIST>
</P>
<P>
<EM>POLYGON ITEMS</EM>
</P>
<P>
Items of type polygon appear as polygonal or curved filled regions on the display. Polygons are
created with widget commands of the following form: 
<CODE DISPLAY>create(polygon X1 Y1 ... Xn Yn param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>

<ITEM> <<fill:C>> : Specifies a color to fill the area of the polygon. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for a non-filled oval.

<ITEM> <<outline:C>> : <<C>> specifies a color to use for drawing the polygon's outline. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for no outline.

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

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

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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. 
</LIST>
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. 
</P>
<P>
<EM>RECTANGLE ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(rectangle X1 Y1 X2 Y2 param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>

<ITEM> <<fill:C>> : Specifies a color to fill the area of the rectangle. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for a non-filled rectangle.

<ITEM> <<outline:C>> : <<C>> specifies a color to use for drawing the rectangle's outline. <<C>> must be a valid color (see <ptr to="misc.color">) or <<nil>> for no outline.

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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. 
</LIST>
</P>
<P>
<EM>TEXT ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(text X Y param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>
<ITEM> <<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>>. 

<ITEM> <<fill:C>> : Specifies a color to fill the text characters. <<C>> must be a valid color (see <ptr to="misc.color">).

<ITEM> <<font:F>> : Specifies the font to use for the text item. <<F>> must be a valid font (see <ptr to="misc.font">)

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

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

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

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

<ITEM> <<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. 
</LIST>
</P>
<P>
<EM>WINDOW ITEMS</EM>
</P>
<P>
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: 
<CODE DISPLAY>create(window X Y window:Desc param1:value1 ... paramX:valueX)</CODE>
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: 
<LIST>
<ITEM> <<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>>. 

<ITEM> <<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 <ptr to="misc.distance">).

<ITEM> <<tags:Tag>> : Specifies a tag to apply to the item.

<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 <ptr to="misc.distance">).
</LIST>
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. 

</section>
