.TH CANVAS 9.SH NAMEcanvas \- Create and manipulate canvas widgets.SH SYNOPSIS\f5canvas\fI \fIpathName \fR?\fIoptions\fR?.SH STANDARD OPTIONS.EX-background        -selectbackground  -takefocus-borderwidth       -selectborderwidth -xscrollcommand-relief            -selectforeground  -yscrollcommand.EE.SH "WIDGET-SPECIFIC OPTIONS".TP.B -closeenough \fIdist\fPSpecifies 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..TP.B -confine \fIboolean\fPSpecifies a boolean value that indicates whether or not it should beallowable to set the canvas's view outside the region defined by the\f5scrollRegion\fR argument.Defaults to true, which means that the view willbe constrained within the scroll region..TP.B -height \fIdist\fPSpecifies 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..TP.B -scrollregion \fIlist\fPSpecifies a list with four \fIdist\fP 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..TP.B -width \fIdist\fPSpecifies 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.TP.B -xscrollincrement \fIdist\fPSpecifies 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 \f5xscrollicrement\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 \f5xscrollicrement\fR.  If the value ofthis option is less than or equal to zero, then horizontal scrollingis unconstrained..TP.B -yscrollincrement \fIdist\fPSpecifies 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 \f5yscrollicrement\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 \f5yscrollicrement\fR.  If the value ofthis option is less than or equal to zero, then vertical scrollingis unconstrained..TP.B -buffer \fIwhat\fPSpecifies how much of the canvas region will bebacked by an offscreen bitmap buffer.\fIWhat\fP can be one of \f5all\fP (the entire scroll regionwill be buffered), \f5visible\fP (only the visible area), \f5none\fP(no buffering) or \f5auto\fP (equivalent to either \f5none\fPor \f5visible\fP depending on whether the canvas is packed insideanother canvas or not). .SH INTRODUCTIONThe \f5canvas\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 lineto configure aspects of the canvas such as its colours and 3-D relief.The \f5canvas\fR command returns its\fIpathName\fR argument.  At the time this command is invoked,there must not exist a window named \fIpathName\fR..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-coloured) and commands maybe associated with items in much the same way that the \f5bind\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 behaviours defined bythe Tk scripts bound to them. .SH "DISPLAY LIST"The 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. .SH "ITEM IDS AND TAGS"Items 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 \f5all\fR is implicitly associated with every itemin the canvas;  it may be used to invoke operations onall the items in the canvas..PPThe tag \f5current\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 \f5current\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 behaviour 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 COORDINATESAll coordinates related to canvases are stored as fixed-pointnumbers.Coordinates and distances are specified as documentedin the.I distsection of .IR types (9)..SH TRANSFORMATIONSNormally 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\f5xview\fR and \f5yview\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 INDICESText 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.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\f5end\fRRefers to the character just after the last one in the item(same as the number of characters in the item)..TP 10\f5insert\fRRefers to the character just before which the insertion cursoris drawn in this item..TP 10\f5sel.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\f5sel.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\f5@\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"The \f5canvas\fR command creates a new Tk command whosename is \fIpathName\fR.  Thiscommand may be used to invoke variousoperations on the widget.  It has the following general form:.RS.EX\fIpathName option \fR?\fIarg arg ...\fR?.EE.RE\fIOption\fR and the \fIarg\fRsdetermine the exact behaviour of the command.The following widget commands are possible for canvas widgets:.TP\fIpathName \f5addtag \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 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\f5above \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\f5all\fRSelects all the items in the canvas..TP\f5below \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\f5closest \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 inthe display list;  if no such item exists, then the selectionbehaves as if the \fIstart\fR argument had not been specified..TP\f5enclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fRSelects all the items completely enclosed within the rectangularregion given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must beno greater than \fIy2\fR..TP\f5overlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fRSelects all the items that overlap or are enclosed within therectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR,and \fIy2\fR.\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must beno greater than \fIy2\fR..TP\f5withtag \fItagOrId\fRSelects all the items given by \fItagOrId\fR..RE.TP\fIpathName \f5bbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR?Returns a list with four elements giving an approximate bounding boxfor all the items named by the \fItagOrId\fR arguments.The list has the form ``\fIx1 y1 x2 y2\fR'' such that the drawnareas of all the named elements are within the region bounded by\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top,and \fIy2\fR on the bottom.The return value may overestimate the actual bounding box bya few pixels.If no items match any of the \fItagOrId\fR arguments or if thematching items have empty bounding boxes (i.e. they have nothingto display)then an empty string is returned..TP\fIpathName \f5bind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR?This command associates \fIcommand\fR with all the items given by\fItagOrId\fR such that whenever the event sequence given by\fIsequence\fR occurs for one of the items the command willbe invoked.This widget command is similar to the \f5bind\fR command except thatit operates on items in a canvas rather than entire widgets.See the \f5bind\fR manual entry for complete detailson the syntax of \fIsequence\fR and the substitutions performedon \fIcommand\fR before invoking it.If all arguments are specified then a new binding is created, replacingany existing binding for the same \fIsequence\fR and \fItagOrId\fR(if the first character of \fIcommand\fR is ``+'' then \fIcommand\fRaugments an existing binding rather than replacing it).In this case the return value is an empty string.If \fIcommand\fR is omitted then the command returns the \fIcommand\fRassociated with \fItagOrId\fR and \fIsequence\fR (an error occursif there is no such binding).If both \fIcommand\fR and \fIsequence\fR are omitted then the commandreturns a list of all the sequences for which bindings have beendefined for \fItagOrId\fR..RS.PPThe only events for which bindings may be specified are those relatedto the mouse and keyboard, such as \f5Enter\fR, \f5Leave\fR,\f5ButtonPress\fR, \f5Motion\fR, and \f5KeyPress\fR.The handling of events in canvases uses the current item definedin ITEM IDS AND TAGS above.\f5Enter\fR and \f5Leave\fR events trigger for an item when itbecomes the current item or ceases to be the current item;  notethat these events are different than \f5Enter\fR and \f5Leave\fRevents 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 \f5focus\fR widget command below for more on this)..PPIt is possible for multiple bindings to match a particular event.This could occur, for example, if one binding is associated with theitem's id and another is associated with one of the item's tags.When this occurs, all of the matching bindings are invoked.A binding associated with the \f5all\fR tag is invoked first,followed by one binding for each of the item's tags (in order),followed by a binding associated with the item's id.If there are multiple matching bindings for a single tag,then only the most specific binding is invoked.A \f5continue\fR command in a binding script terminates thatscript, and a \f5break\fR command terminates that scriptand skips any remaining scripts for the event, just as for the\f5bind\fR command..PPIf bindings have been created for a canvas window using the \f5bind\fRcommand, then they are invoked in addition to bindings created forthe canvas's items using the \f5bind\fR widget command.The bindings for items will be invoked before any of the bindingsfor the window as a whole..RE.TP\fIpathName \f5canvasx \fIscreenx\fR ?\fIgridspacing\fR?Given a window x-coordinate in the canvas \fIscreenx\fR, this command returnsthe canvas x-coordinate that is displayed at that location.If \fIgridspacing\fR is specified, then the canvas coordinate isrounded to the nearest multiple of \fIgridspacing\fR units..TP\fIpathName \f5canvasy \fIscreeny\fR ?\fIgridspacing\fR?Given a window y-coordinate in the canvas \fIscreeny\fR this command returnsthe canvas y-coordinate that is displayed at that location.If \fIgridspacing\fR is specified, then the canvas coordinate isrounded to the nearest multiple of \fIgridspacing\fR units..TP\fIpathName \f5cget\fR \fIoption\fRReturns the current value of the configuration option givenby \fIoption\fR.\fIOption\fR may have any of the values accepted by the \f5canvas\fRcommand..TP\fIpathName \f5configure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?Query or modify the configuration options of the widget.If no \fIoption\fR is specified, returns a list of all ofthe available options for \fIpathName\fR.  Ifone or more \fIoption-value\fR pairs are specified, then the commandmodifies the given widget option(s) to have the given value(s);  inthis case the command returns an empty string.\fIOption\fR may have any of the values accepted by the \f5canvas\fRcommand..TP\fIpathName\fR \f5coords \fItagOrId \fR?\fIx0 y0 ...\fR?Query or modify the coordinates that define an item.If no coordinates are specified, this command returns a listwhose elements are the coordinates of the item named by\fItagOrId\fR.If coordinates are specified, then they replace the currentcoordinates for the named item.If \fItagOrId\fR refers to multiple items, thenthe first one in the display list is used..TP\fIpathName \f5create \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR?Create a new item in \fIpathName\fR of type \fItype\fR.The exact format of the arguments after \f5type\fR dependson \f5type\fR, but usually they consist of the coordinates forone or more points, followed by specifications for zero ormore item options.See the subsections on individual item types below for moreon the syntax of this command.This command returns the id for the new item..TP\fIpathName \f5dchars \fItagOrId first \fR?\fIlast\fR?For each item given by \fItagOrId\fR, delete the charactersin the range given by \fIfirst\fR and \fIlast\fR,inclusive.If some of the items given by \fItagOrId\fR don't supporttext operations, then they are ignored.\fIFirst\fR and \fIlast\fR are indices of characterswithin the item(s) as described in INDICES above.If \fIlast\fR is omitted, it defaults to \fIfirst\fR.This command returns an empty string..TP\fIpathName \f5delete \fR?\fItagOrId tagOrId ...\fR?Delete each of the items given by each \fItagOrId\fR, and returnan empty string..TP\fIpathName \f5dtag \fItagOrId \fR?\fItagToDelete\fR?For each of the items given by \fItagOrId\fR, delete thetag given by \fItagToDelete\fR from the list of thoseassociated with the item.If an item doesn't have the tag \fItagToDelete\fR thenthe item is unaffected by the command.If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR.This command returns an empty string..TP\fIpathName \f5find \fIsearchCommand \fR?\fIarg arg ...\fR?This command returns a list consisting of all the items thatmeet the constraints specified by \fIsearchCommand\fR and\fIarg\fR's.\fISearchCommand\fR and \fIargs\fR have any of the formsaccepted by the \f5addtag\fR command.If \fIsearchCommand\fR is \f5enclosed\fR, \f5overlapping\fR,or \f5all\fR, the items are returned in display-list order,i.e. bottommost first..TP\fIpathName \f5focus \fR?\fItagOrId\fR?Set the keyboard focus for the canvas widget to the item given by\fItagOrId\fR.If \fItagOrId\fR refers to several items, then the focus is setto the first such item in the display list that supports theinsertion cursor.If \fItagOrId\fR doesn't refer to any items, or if none of themsupport the insertion cursor, then the focus isn't changed.If \fItagOrId\fR is an emptystring, then the focus item is reset so that no item has the focus.If \fItagOrId\fR is not specified then the command returns theid for the item that currently has the focus, or an empty stringif no item has the focus..RS.PPOnce the focus has been set to an item, the item will displaythe insertion cursor and all keyboard events will be directedto that item.The focus item within a canvas and the focus window on thescreen (set with the \f5focus\fR 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 itemwithin the canvas.In most cases it is advisable to follow the \f5focus\fR widgetcommand with the \f5focus\fR command to set the focus window tothe canvas (if it wasn't there already)..RE.TP\fIpathName \f5gettags\fR \fItagOrId\fRReturn a list whose elements are the tags associated with theitem given by \fItagOrId\fR.If \fItagOrId\fR refers to more than one item, then the tagsare returned from the first such item in the display list.If \fItagOrId\fR doesn't refer to any items, then an error is returned. If the itemcontains no tags, then an empty string is returned..TP\fIpathName \f5grab\fR \fIwhat\fR \fItagOrId\fRDoes for canvas widgets what \fIgrab\fR(9) does fornormal tk widgets: mouse events will only be deliveredto \fItagOrId\fR. If \fItagOrId\fR refers to more than one item,then the first such item in the display list is grabbed.\fIWhat\fR is as described in.IR grab (9)..PPNote that the canvas grab item, as set by this command,and the tk grab item, as set by.IR grab (9)are totally independent; a canvas item doesn't actually grabthe mouse unless a) the canvas itself has grabbed the mouse

Lines 1–500 of 1358. Load more