'\"'\" Copyright (c) 1992-1994 The Regents of the University of California.'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.'\"'\" See the file "license.terms" for information on usage and redistribution'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.'\" '\" SCCS: @(#) canvas.n 1.58 97/10/31 12:58:45'\".so man.macros.TH canvas n 4.0 Tk "Tk Built-In Commands".BS'\" Note:  do not modify the .SH NAME line immediately below!.SH NAMEcanvas \- Create and manipulate canvas widgets.SH SYNOPSIS\fBcanvas\fR \fIpathName \fR?\fIoptions\fR?.SO\-background	\-highlightthickness	\-insertwidth	\-takefocus\-borderwidth	\-insertbackground	\-relief	\-xscrollcommand\-cursor	\-insertborderwidth	\-selectbackground	\-yscrollcommand\-highlightbackground	\-insertofftime	\-selectborderwidth\-highlightcolor	\-insertontime	\-selectforeground.SE.SH "WIDGET-SPECIFIC OPTIONS".OP \-closeenough closeEnough CloseEnoughSpecifies a floating-point value indicating how close the mouse cursormust be to an item before it is considered to be ``inside'' the item.Defaults to 1.0..OP \-confine confine ConfineSpecifies a boolean value that indicates whether or not it should beallowable to set the canvas's view outside the region defined by the\fBscrollRegion\fR argument.Defaults to true, which means that the view willbe constrained within the scroll region..OP \-height height HeightSpecifies a desired window height that the canvas widget should request fromits geometry manager.  The value may be specified in anyof the forms described in the COORDINATES section below..OP \-scrollregion scrollRegion ScrollRegionSpecifies a list with four coordinates describing the left, top, right, andbottom coordinates of a rectangular region.This region is used for scrolling purposes and is considered to bethe boundary of the information in the canvas.Each of the coordinates may be specifiedin any of the forms given in the COORDINATES section below..OP \-width width widthSpecifies a desired window width that the canvas widget should request fromits geometry manager.  The value may be specified in anyof the forms described in the COORDINATES section below..br.OP \-xscrollincrement xScrollIncrement ScrollIncrementSpecifies an increment for horizontal scrolling, in any of the usual formspermitted for screen distances.  If the value of this option is greaterthan zero, the horizontal view in the window will be constrained so thatthe canvas x coordinate at the left edge of the window is always an evenmultiple of \fBxScrollIncrement\fR;  furthermore, the units for scrolling(e.g., the change in view when the left and right arrows of a scrollbarare selected) will also be \fBxScrollIncrement\fR.  If the value ofthis option is less than or equal to zero, then horizontal scrollingis unconstrained..OP \-yscrollincrement yScrollIncrement ScrollIncrementSpecifies an increment for vertical scrolling, in any of the usual formspermitted for screen distances.  If the value of this option is greaterthan zero, the vertical view in the window will be constrained so thatthe canvas y coordinate at the top edge of the window is always an evenmultiple of \fByScrollIncrement\fR;  furthermore, the units for scrolling(e.g., the change in view when the top and bottom arrows of a scrollbarare selected) will also be \fByScrollIncrement\fR.  If the value ofthis option is less than or equal to zero, then vertical scrollingis unconstrained..BE.SH INTRODUCTION.PPThe \fBcanvas\fR command creates a new window (givenby the \fIpathName\fR argument) and makes it into a canvas widget.Additional options, described above, may be specified on thecommand line or in the option databaseto configure aspects of the canvas such as its colors and 3-D relief.The \fBcanvas\fR command returns its\fIpathName\fR argument.  At the time this command is invoked,there must not exist a window named \fIpathName\fR, but\fIpathName\fR's parent must exist..PPCanvas widgets implement structured graphics.A canvas displays any number of \fIitems\fR, which may be things likerectangles, circles, lines, and text.Items may be manipulated (e.g. moved or re-colored) and commands maybe associated with items in much the same way that the \fBbind\fRcommand allows commands to be bound to widgets.  For example,a particular command may be associated with the <Button-1> eventso that the command is invoked whenever button 1 is pressed withthe mouse cursor over an item.This means that items in a canvas can have behaviors defined bythe Tcl scripts bound to them..SH "DISPLAY LIST".PPThe items in a canvas are ordered for purposes of display,with the first item in the display list being displayedfirst, followed by the next item in the list, and so on.Items later in the display list obscure those that areearlier in the display list and are sometimes referred toas being ``on top'' of earlier items.When a new item is created it is placed at the end of thedisplay list, on top of everything else.Widget commands may be used to re-arrange the order of thedisplay list..PPWindow items are an exception to the above rules.  The underlyingwindow systems require them always to be drawn on top of other items.In addition, the stacking order of window itemsis not affected by any of the canvas widget commands; you must usethe \fBraise\fR and \fBlower\fR Tk commands instead..SH "ITEM IDS AND TAGS".PPItems in a canvas widget may be named in either of two ways:by id or by tag.Each item has a unique identifying number which is assigned tothat item when it is created.  The id of an item never changesand id numbers are never re-used within the lifetime of acanvas widget..PPEach item may also have any number of \fItags\fR associatedwith it.  A tag is just a string of characters, and it maytake any form except that of an integer.For example, ``x123'' is OK but ``123'' isn't.The same tag may be associated with many different items.This is commonly done to group items in various interestingways;  for example, all selected items might be given thetag ``selected''..PPThe tag \fBall\fR is implicitly associated with every itemin the canvas;  it may be used to invoke operations onall the items in the canvas..PPThe tag \fBcurrent\fR is managed automatically by Tk;it applies to the \fIcurrent item\fR, which is thetopmost item whose drawn area covers the position ofthe mouse cursor.If the mouse is not in the canvas widget or is not overan item, then no item has the \fBcurrent\fR tag..PPWhen specifying items in canvas widget commands, if thespecifier is an integer then it is assumed to refer tothe single item with that id.If the specifier is not an integer, then it is assumed torefer to all of the items in the canvas that have a tagmatching the specifier.The symbol \fItagOrId\fR is used below to indicate thatan argument specifies either an id that selects a singleitem or a tag that selects zero or more items.Some widget commands only operate on a single item at atime;  if \fItagOrId\fR is specified in a way thatnames multiple items, then the normal behavior is forthe command to use the first (lowest) of these items inthe display list that is suitable for the command.Exceptions are noted in the widget command descriptionsbelow..SH "COORDINATES".PPAll coordinates related to canvases are stored as floating-pointnumbers.Coordinates and distances are specified in screen units,which are floating-point numbers optionally followedby one of several letters.If no letter is supplied then the distance is in pixels.If the letter is \fBm\fR then the distance is in millimeters onthe screen;  if it is \fBc\fR then the distance is in centimeters;\fBi\fR means inches, and \fBp\fR means printers points (1/72 inch).Larger y-coordinates refer to points lower on the screen;  largerx-coordinates refer to points farther to the right..SH TRANSFORMATIONS.PPNormally the origin of the canvas coordinate system is at theupper-left corner of the window containing the canvas.It is possible to adjust the origin of the canvascoordinate system relative to the origin of the window using the\fBxview\fR and \fByview\fR widget commands;  this is typically usedfor scrolling.Canvases do not support scaling or rotation of the canvas coordinatesystem relative to the window coordinate system..PPIndividual items may be moved or scaled using widget commandsdescribed below, but they may not be rotated..SH "INDICES".PPText items support the notion of an \fIindex\fR for identifyingparticular positions within the item.Indices are used for commands such as inserting text, deletinga range of characters, and setting the insertion cursor position.An index may be specified in any of a number of ways, anddifferent types of items may support different forms forspecifying indices.Text items support the following forms for an index;  if youdefine new types of text-like items, it would be advisable tosupport as many of these forms as practical.Note that it is possible to refer to the character just afterthe last one in the text item;  this is necessary for suchtasks as inserting new text at the end of the item..TP 10\fInumber\fRA decimal number giving the position of the desired characterwithin the text item.0 refers to the first character, 1 to the next character, andso on.A number less than 0 is treated as if it were zero, and anumber greater than the length of the text item is treatedas if it were equal to the length of the text item..TP 10\fBend\fRRefers to the character just after the last one in the item(same as the number of characters in the item)..TP 10\fBinsert\fRRefers to the character just before which the insertion cursoris drawn in this item..TP 10\fBsel.first\fRRefers to the first selected character in the item.If the selection isn't in this item then this form is illegal..TP 10\fBsel.last\fRRefers to the last selected character in the item.If the selection isn't in this item then this form is illegal..TP 10\fB@\fIx,y\fRRefers to the character at the point given by \fIx\fR and\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinatesystem of the canvas.If \fIx\fR and \fIy\fR lie outside the coordinates covered by thetext item, then they refer to the first or last character in theline that is closest to the given point..SH "WIDGET COMMAND".PPThe \fBcanvas\fR command creates a new Tcl command whosename is \fIpathName\fR.  Thiscommand may be used to invoke variousoperations on the widget.  It has the following general form:.CS\fIpathName option \fR?\fIarg arg ...\fR?.CE\fIOption\fR and the \fIarg\fRsdetermine the exact behavior of the command.The following widget commands are possible for canvas widgets:.TP\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR?For each item that meets the constraints specified by\fIsearchSpec\fR and the \fIarg\fRs, add\fItag\fR to the list of tags associated with the item if itisn't already present on that list.It is possible that no items will satisfy the constraintsgiven by \fIsearchSpec\fR and \fIarg\fRs, in which case thecommand has no effect.This command returns an empty string as result.\fISearchSpec\fR and \fIarg\fR's may take any of the followingforms:.RS.TP\fBabove \fItagOrId\fRSelects the item just after (above) the one given by \fItagOrId\fRin the display list.If \fItagOrId\fR denotes more than one item, then the last (topmost)of these items in the display list is used..TP\fBall\fRSelects all the items in the canvas..TP\fBbelow \fItagOrId\fRSelects the item just before (below) the one given by \fItagOrId\fRin the display list.If \fItagOrId\fR denotes more than one item, then the first (lowest)of these items in the display list is used..TP\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?Selects the item closest to the point given by \fIx\fR and \fIy\fR.If more than one item is at the same closest distance (e.g. twoitems overlap the point), then the top-most of these items (thelast one in the display list) is used.If \fIhalo\fR is specified, then it must be a non-negativevalue.Any item closer than \fIhalo\fR to the point is considered tooverlap it.The \fIstart\fR argument may be used to step circularly throughall the closest items.If \fIstart\fR is specified, it names an item using a tag or id(if by tag, it selects the first item in the display list withthe given tag).Instead of selecting the topmost closest item, this form willselect the topmost closest item that is below \fIstart\fR in