1canvas(n)                    Tk Built-In Commands                    canvas(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       canvas  -  Create and manipulate 'canvas' hypergraphics drawing surface
9       widgets
10

SYNOPSIS

12       canvas pathName ?options?
13

STANDARD OPTIONS

15       -background           -borderwidth         -cursor
16       -highlightbackground  -highlightcolor      -highlightthickness
17       -insertbackground     -insertborderwidth   -insertofftime
18       -insertontime         -insertwidth         -relief
19       -selectbackground     -selectborderwidth   -selectforeground
20       -takefocus            -xscrollcommand      -yscrollcommand
21
22       See the options manual entry for details on the standard options.
23

WIDGET-SPECIFIC OPTIONS

25       Command-Line Name:-closeenough
26       Database Name:  closeEnough
27       Database Class: CloseEnough
28
29              Specifies a floating-point value indicating how close the  mouse
30              cursor must be to an item before it is considered to be “inside”
31              the item. Defaults to 1.0.
32
33       Command-Line Name:-confine
34       Database Name:  confine
35       Database Class: Confine
36
37              Specifies a boolean value  that  indicates  whether  or  not  it
38              should  be allowable to set the canvas's view outside the region
39              defined by the scrollRegion argument.  Defaults to  true,  which
40              means  that  the  view  will  be  constrained  within the scroll
41              region.
42
43       Command-Line Name:-height
44       Database Name:  height
45       Database Class: Height
46
47              Specifies a desired window height that the canvas widget  should
48              request from its geometry manager. The value may be specified in
49              any of the forms described in the COORDINATES section below.
50
51       Command-Line Name:-scrollregion
52       Database Name:  scrollRegion
53       Database Class: ScrollRegion
54
55              Specifies a list with four coordinates describing the left, top,
56              right,  and  bottom  coordinates  of a rectangular region.  This
57              region is used for scrolling purposes and is  considered  to  be
58              the  boundary  of  the  information  in the canvas.  Each of the
59              coordinates may be specified in any of the forms  given  in  the
60              COORDINATES section below.
61
62       Command-Line Name:-state
63       Database Name:  state
64       Database Class: State
65
66              Modifies  the default state of the canvas where state may be set
67              to one  of:  normal,  disabled,  or  hidden.  Individual  canvas
68              objects  all  have their own state option which may override the
69              default state. Many options  can  take  separate  specifications
70              such that the appearance of the item can be different in differ‐
71              ent situations. The options that start with active  control  the
72              appearance  when  the mouse pointer is over it, while the option
73              starting with disabled controls the appearance when the state is
74              disabled. Canvas items which are disabled will not react to can‐
75              vas bindings.
76
77       Command-Line Name:-width
78       Database Name:  width
79       Database Class: width
80
81              Specifies a desired window width that the canvas  widget  should
82              request from its geometry manager. The value may be specified in
83              any of the forms described in the COORDINATES section below.
84
85       Command-Line Name:-xscrollincrement
86       Database Name:  xScrollIncrement
87       Database Class: ScrollIncrement
88
89              Specifies an increment for horizontal scrolling, in any  of  the
90              usual forms permitted for screen distances. If the value of this
91              option is greater than zero, the horizontal view in  the  window
92              will  be constrained so that the canvas x coordinate at the left
93              edge of the window is always an even multiple  of  xScrollIncre‐
94              ment;  furthermore, the units for scrolling (e.g., the change in
95              view when the left and right arrows of a scrollbar are selected)
96              will  also  be  xScrollIncrement. If the value of this option is
97              less than or equal to zero, then horizontal scrolling is  uncon‐
98              strained.
99
100       Command-Line Name:-yscrollincrement
101       Database Name:  yScrollIncrement
102       Database Class: ScrollIncrement
103
104              Specifies  an  increment  for  vertical scrolling, in any of the
105              usual forms permitted for screen distances. If the value of this
106              option  is  greater  than  zero, the vertical view in the window
107              will be constrained so that the canvas y coordinate at  the  top
108              edge  of  the window is always an even multiple of yScrollIncre‐
109              ment; furthermore, the units for scrolling (e.g., the change  in
110              view when the top and bottom arrows of a scrollbar are selected)
111              will also be yScrollIncrement. If the value of  this  option  is
112              less  than  or  equal to zero, then vertical scrolling is uncon‐
113              strained.
114______________________________________________________________________________
115

INTRODUCTION

117       The canvas command creates a new window (given by  the  pathName  argu‐
118       ment) and makes it into a canvas widget.  Additional options, described
119       above, may be specified on the command line or in the  option  database
120       to  configure  aspects of the canvas such as its colors and 3-D relief.
121       The canvas command returns its pathName argument. At the time this com‐
122       mand  is  invoked,  there  must  not exist a window named pathName, but
123       pathName's parent must exist.
124
125       Canvas widgets implement structured graphics.  A  canvas  displays  any
126       number  of  items, which may be things like rectangles, circles, lines,
127       and text.  Items may be manipulated (e.g. moved or re-colored) and com‐
128       mands  may  be associated with items in much the same way that the bind
129       command allows commands to be bound to widgets. For example, a particu‐
130       lar  command  may  be  associated with the <Button-1> event so that the
131       command is invoked whenever button 1 is pressed with the  mouse  cursor
132       over  an  item.   This  means that items in a canvas can have behaviors
133       defined by the Tcl scripts bound to them.
134

DISPLAY LIST

136       The items in a canvas are ordered for purposes  of  display,  with  the
137       first  item  in the display list being displayed first, followed by the
138       next item in the list, and so on.  Items  later  in  the  display  list
139       obscure  those  that  are earlier in the display list and are sometimes
140       referred to as being “on top” of earlier items.  When  a  new  item  is
141       created  it  is placed at the end of the display list, on top of every‐
142       thing else.  Widget commands may be used to re-arrange the order of the
143       display list.
144
145       Window items are an exception to the above rules. The underlying window
146       systems require them always to be drawn on  top  of  other  items.   In
147       addition,  the stacking order of window items is not affected by any of
148       the canvas widget commands; you must use the Tk raise command and lower
149       command instead.
150

ITEM IDS AND TAGS

152       Items  in  a canvas widget may be named in either of two ways: by id or
153       by tag.  Each item has a unique identifying number, which  is  assigned
154       to that item when it is created. The id of an item never changes and id
155       numbers are never re-used within the lifetime of a canvas widget.
156
157       Each item may also have any number of tags associated with it. A tag is
158       just a string of characters, and it may take any form except that of an
159       integer.  For example, “x123” is OK but “123” is not.  The same tag may
160       be  associated  with  many  different  items.  This is commonly done to
161       group items in various interesting  ways;  for  example,  all  selected
162       items might be given the tag “selected”.
163
164       The  tag all is implicitly associated with every item in the canvas; it
165       may be used to invoke operations on all the items in the canvas.
166
167       The tag current is managed automatically by Tk; it applies to the  cur‐
168       rent  item, which is the topmost item whose drawn area covers the posi‐
169       tion of the mouse cursor (different item types interpret this in  vary‐
170       ing  ways; see the individual item type documentation for details).  If
171       the mouse is not in the canvas widget or is not over an item,  then  no
172       item has the current tag.
173
174       When specifying items in canvas widget commands, if the specifier is an
175       integer then it is assumed to refer to the single item  with  that  id.
176       If  the specifier is not an integer, then it is assumed to refer to all
177       of the items in the canvas that have a tag matching the specifier.  The
178       symbol  tagOrId  is  used  below to indicate that an argument specifies
179       either an id that selects a single item or a tag that selects  zero  or
180       more items.
181
182       tagOrId  may  contain a logical expressions of tags by using operators:
183&&”, “||”, “^”, “!”, and parenthesized subexpressions. For example:
184                    .c find withtag {(a&&!b)||(!a&&b)}
185       or equivalently:
186                    .c find withtag {a^b}
187       will find only those items with either “a” or “b” tags, but not both.
188
189       Some widget commands only operate on  a  single  item  at  a  time;  if
190       tagOrId  is specified in a way that names multiple items, then the nor‐
191       mal behavior is for the command to use  the  first  (lowest)  of  these
192       items in the display list that is suitable for the command.  Exceptions
193       are noted in the widget command descriptions below.
194

COORDINATES

196       All coordinates related to canvases are stored as  floating-point  num‐
197       bers.   Coordinates  and distances are specified in screen units, which
198       are floating-point numbers optionally followed by one of  several  let‐
199       ters.  If no letter is supplied then the distance is in pixels.  If the
200       letter is m then the distance is in millimeters on the screen; if it is
201       c  then  the  distance  is  in centimeters; i means inches, and p means
202       printers points (1/72 inch).   Larger  y-coordinates  refer  to  points
203       lower  on  the  screen; larger x-coordinates refer to points farther to
204       the right.  Coordinates can be specified either as an  even  number  of
205       parameters,  or as a single list parameter containing an even number of
206       x and y coordinate values.
207
208   TRANSFORMATIONS
209       Normally the origin of the canvas coordinate system is  at  the  upper-
210       left  corner  of  the  window containing the canvas.  It is possible to
211       adjust the origin of the canvas coordinate system relative to the  ori‐
212       gin  of  the  window using the xview and yview widget commands; this is
213       typically used for scrolling.  Canvases do not support scaling or rota‐
214       tion  of the canvas coordinate system relative to the window coordinate
215       system.
216
217       Individual items may be moved or scaled using widget commands described
218       below, but they may not be rotated.
219
220       Note that the default origin of the canvas's visible area is coincident
221       with the origin for the whole window as that makes bindings  using  the
222       mouse  position  easier  to work with; you only need to use the canvasx
223       and canvasy widget commands if you adjust the  origin  of  the  visible
224       area.  However,  this  also means that any focus ring (as controlled by
225       the -highlightthickness option) and window border (as controlled by the
226       -borderwidth  option)  must be taken into account before you get to the
227       visible area of the canvas.
228

INDICES

230       Text items support the notion of an index  for  identifying  particular
231       positions  within  the  item.   In  a similar fashion, line and polygon
232       items support index for identifying, inserting and deleting subsets  of
233       their  coordinates.  Indices are used for commands such as inserting or
234       deleting a range of characters or coordinates, and setting  the  inser‐
235       tion  cursor  position. An index may be specified in any of a number of
236       ways, and different types of items  may  support  different  forms  for
237       specifying  indices.   Text  items  support  the following forms for an
238       index; if you define new types of text-like items, it would  be  advis‐
239       able  to  support as many of these forms as practical.  Note that it is
240       possible to refer to the character just after the last one in the  text
241       item; this is necessary for such tasks as inserting new text at the end
242       of the item.  Lines and Polygons do not support  the  insertion  cursor
243       and  the  selection.  Their  indices  are  supposed  to be even always,
244       because coordinates always appear in pairs.
245
246       number    A decimal number giving the position of the desired character
247                 within  the text item.  0 refers to the first character, 1 to
248                 the next character, and so on. If indexes are odd  for  lines
249                 and  polygons, they will be automatically decremented by one.
250                 A number less than 0 is treated as if it  were  zero,  and  a
251                 number greater than the length of the text item is treated as
252                 if it were equal to the length of the text  item.  For  poly‐
253                 gons,  numbers  less than 0 or greater than the length of the
254                 coordinate list will be adjusted by adding or subtracting the
255                 length  until  the  result  is  between  zero and the length,
256                 inclusive.
257
258       end       Refers to the character or coordinate just after the last one
259                 in  the item (same as the number of characters or coordinates
260                 in the item).
261
262       insert    Refers to the character just before which the insertion  cur‐
263                 sor is drawn in this item. Not valid for lines and polygons.
264
265       sel.first Refers  to  the first selected character in the item.  If the
266                 selection is not in this item then this form is illegal.
267
268       sel.last  Refers to the last selected character in the  item.   If  the
269                 selection is not in this item then this form is illegal.
270
271       @x,y      Refers to the character or coordinate at the point given by x
272                 and y, where x and y are specified in the  coordinate  system
273                 of  the  canvas.  If x and y lie outside the coordinates cov‐
274                 ered by the text item, then they refer to the first  or  last
275                 character in the line that is closest to the given point.
276

DASH PATTERNS

278       Many items support the notion of a dash pattern for outlines.
279
280       The  first  possible  syntax is a list of integers. Each element repre‐
281       sents the number of pixels of a line segment. Only the odd segments are
282       drawn using the “outline” color. The other segments are drawn transpar‐
283       ent.
284
285       The second possible syntax is a character list containing only 5 possi‐
286       ble  characters  “.,-_  ”.   The space can be used to enlarge the space
287       between other line elements, and cannot occur as the first position  in
288       the string. Some examples:
289              -dash .     → -dash {2 4}
290              -dash -     → -dash {6 4}
291              -dash -.    → -dash {6 4 2 4}
292              -dash -..   → -dash {6 4 2 4 2 4}
293              -dash {. }  → -dash {2 8}
294              -dash ,     → -dash {4 4}
295
296       The  main  difference  of  this  syntax with the previous is that it is
297       shape-conserving. This means that all values in the dash list  will  be
298       multiplied  by  the  line  width  before display. This assures that “.”
299       will always be displayed as a dot and “-” always as a  dash  regardless
300       of the line width.
301
302       On  systems which support only a limited set of dash patterns, the dash
303       pattern will be displayed as the closest dash pattern  that  is  avail‐
304       able.   For  example, on Windows only the first 4 of the above examples
305       are available. The last 2 examples will be displayed identically to the
306       first one.
307

WIDGET COMMAND

309       The  canvas  command  creates a new Tcl command whose name is pathName.
310       This command may be used to invoke various operations on the widget. It
311       has the following general form:
312              pathName option ?arg arg ...?
313       Option  and  the args determine the exact behavior of the command.  The
314       following widget commands are possible for canvas widgets:
315
316       pathName addtag tag searchSpec ?arg arg ...?
317              For each item that meets the constraints specified by searchSpec
318              and  the  args,  add tag to the list of tags associated with the
319              item if it is not already present on that list.  It is  possible
320              that  no  items will satisfy the constraints given by searchSpec
321              and args, in which case the command has no effect.  This command
322              returns  an  empty  string  as result.  SearchSpec and arg's may
323              take any of the following forms:
324
325              above tagOrId
326                     Selects the item just after  (above)  the  one  given  by
327                     tagOrId  in  the  display  list.  If tagOrId denotes more
328                     than one item, then the last (topmost) of these items  in
329                     the display list is used.
330
331              all    Selects all the items in the canvas.
332
333              below tagOrId
334                     Selects  the  item  just  before (below) the one given by
335                     tagOrId in the display list.   If  tagOrId  denotes  more
336                     than  one item, then the first (lowest) of these items in
337                     the display list is used.
338
339              closest x y ?halo? ?start?
340                     Selects the item closest to the point given by x  and  y.
341                     If  more  than  one  item is at the same closest distance
342                     (e.g. two items overlap the point), then the top-most  of
343                     these  items  (the last one in the display list) is used.
344                     If halo is specified, then  it  must  be  a  non-negative
345                     value.  Any item closer than halo to the point is consid‐
346                     ered to overlap it.  The start argument may  be  used  to
347                     step  circularly through all the closest items.  If start
348                     is specified, it names an item using a tag or id  (if  by
349                     tag,  it  selects the first item in the display list with
350                     the given tag).  Instead of selecting the topmost closest
351                     item, this form will select the topmost closest item that
352                     is below start in the  display  list;  if  no  such  item
353                     exists,  then the selection behaves as if the start argu‐
354                     ment had not been specified.
355
356              enclosed x1 y1 x2 y2
357                     Selects all the items completely enclosed within the rec‐
358                     tangular  region given by x1, y1, x2, and y2.  X1 must be
359                     no greater than x2 and y1 must be no greater than y2.
360
361              overlapping x1 y1 x2 y2
362                     Selects all the items that overlap or are enclosed within
363                     the  rectangular  region given by x1, y1, x2, and y2.  X1
364                     must be no greater than x2 and y1 must be no greater than
365                     y2.
366
367              withtag tagOrId
368                     Selects all the items given by tagOrId.
369
370       pathName bbox tagOrId ?tagOrId tagOrId ...?
371              Returns a list with four elements giving an approximate bounding
372              box for all the items named by the tagOrId arguments.  The  list
373              has  the form “x1 y1 x2 y2” such that the drawn areas of all the
374              named elements are within the region bounded by x1 on the  left,
375              x2  on  the  right,  y1  on  the top, and y2 on the bottom.  The
376              return value may overestimate the actual bounding box by  a  few
377              pixels.   If  no  items match any of the tagOrId arguments or if
378              the matching items have empty bounding  boxes  (i.e.  they  have
379              nothing to display) then an empty string is returned.
380
381       pathName bind tagOrId ?sequence? ?command?
382              This  command  associates  command  with  all the items given by
383              tagOrId such that whenever the event sequence given by  sequence
384              occurs  for  one of the items the command will be invoked.  This
385              widget command is similar to the bind  command  except  that  it
386              operates  on  items in a canvas rather than entire widgets.  See
387              the bind manual entry for complete  details  on  the  syntax  of
388              sequence  and  the  substitutions  performed  on  command before
389              invoking it.  If all arguments are specified then a new  binding
390              is created, replacing any existing binding for the same sequence
391              and tagOrId (if the first character of command is “+” then  com‐
392              mand augments an existing binding rather than replacing it).  In
393              this case the return value is an empty string.   If  command  is
394              omitted  then  the  command  returns the command associated with
395              tagOrId and sequence (an error occurs if there is no such  bind‐
396              ing).  If both command and sequence are omitted then the command
397              returns a list of all the sequences for which bindings have been
398              defined for tagOrId.
399
400              The  only  events  for which bindings may be specified are those
401              related to the mouse and keyboard (such as Enter, Leave, Button‐
402              Press, Motion, and KeyPress) or virtual events.  The handling of
403              events in canvases uses the current item defined in ITEM IDS AND
404              TAGS  above.  Enter and Leave events trigger for an item when it
405              becomes the current item or ceases to be the current item;  note
406              that  these events are different than Enter and Leave events for
407              windows. Mouse-related events are directed to the current  item,
408              if  any. Keyboard-related events are directed to the focus item,
409              if any (see the focus widget command below for more on this). If
410              a  virtual  event is used in a binding, that binding can trigger
411              only if the virtual event is defined  by  an  underlying  mouse-
412              related or keyboard-related event.
413
414              It  is  possible  for  multiple  bindings  to match a particular
415              event.  This could occur, for example, if one binding is associ‐
416              ated  with  the  item's id and another is associated with one of
417              the item's tags.  When this occurs, all of the matching bindings
418              are  invoked.   A binding associated with the all tag is invoked
419              first, followed by one binding for each of the item's  tags  (in
420              order), followed by a binding associated with the item's id.  If
421              there are multiple matching bindings for a single tag, then only
422              the  most  specific binding is invoked.  A continue command in a
423              binding script terminates that script, and a break command  ter‐
424              minates  that  script  and  skips  any remaining scripts for the
425              event, just as for the bind command.
426
427              If bindings have been created for a canvas window using the bind
428              command,  then  they are invoked in addition to bindings created
429              for the canvas's items using the bind widget command.  The bind‐
430              ings  for  items  will be invoked before any of the bindings for
431              the window as a whole.
432
433       pathName canvasx screenx ?gridspacing?
434              Given a window x-coordinate in the canvas screenx, this  command
435              returns  the canvas x-coordinate that is displayed at that loca‐
436              tion.  If gridspacing is specified, then the  canvas  coordinate
437              is rounded to the nearest multiple of gridspacing units.
438
439       pathName canvasy screeny ?gridspacing?
440              Given  a  window y-coordinate in the canvas screeny this command
441              returns the canvas y-coordinate that is displayed at that  loca‐
442              tion.   If  gridspacing is specified, then the canvas coordinate
443              is rounded to the nearest multiple of gridspacing units.
444
445       pathName cget option
446              Returns the current value of the configuration option  given  by
447              option.   Option may have any of the values accepted by the can‐
448              vas command.
449
450       pathName configure ?option? ?value? ?option value ...?
451              Query or modify the configuration options of the widget.  If  no
452              option is specified, returns a list describing all of the avail‐
453              able options for pathName (see Tk_ConfigureInfo for  information
454              on  the  format  of  this  list). If option is specified with no
455              value, then the command returns a list describing the one  named
456              option (this list will be identical to the corresponding sublist
457              of the value returned if no option is specified). If one or more
458              option-value  pairs are specified, then the command modifies the
459              given widget option(s) to have the given value(s); in this  case
460              the command returns an empty string.  Option may have any of the
461              values accepted by the canvas command.
462
463       pathName coords tagOrId ?x0 y0 ...?
464
465       pathName coords tagOrId ?coordList?
466              Query or modify the coordinates that  define  an  item.   If  no
467              coordinates  are  specified,  this  command returns a list whose
468              elements are the coordinates of the item named by  tagOrId.   If
469              coordinates are specified, then they replace the current coordi‐
470              nates for the named item.  If tagOrId refers to multiple  items,
471              then the first one in the display list is used.
472
473              Note  that  for  rectangles, ovals and arcs the returned list of
474              coordinates has a fixed order, namely the left, top,  right  and
475              bottom coordinates, which may not be the order originally given.
476              Also the coordinates are always returned in screen units with no
477              units  (that is, in pixels). So if the original coordinates were
478              specified for instance in centimeters or  inches,  the  returned
479              values will nevertheless be in pixels.
480
481       pathName create type x y ?x y ...? ?option value ...?
482
483       pathName create type coordList ?option value ...?
484              Create a new item in pathName of type type.  The exact format of
485              the arguments after type depends on type, but usually they  con‐
486              sist  of  the  coordinates  for  one or more points, followed by
487              specifications for zero or more item options.  See  the  subsec‐
488              tions  on  individual item types below for more on the syntax of
489              this command.  This command returns the id for the new item.
490
491       pathName dchars tagOrId first ?last?
492              For each item given by tagOrId, delete the characters, or  coor‐
493              dinates,  in  the  range given by first and last, inclusive.  If
494              some of the items given by tagOrId do not support indexing oper‐
495              ations  then  they  ignore this operation.  Text items interpret
496              first and last as indices to a character, line and polygon items
497              interpret  them  as  indices  to  a  coordinate  (an  x,y pair).
498              Indices are described in INDICES above.  If last is omitted,  it
499              defaults to first.  This command returns an empty string.
500
501       pathName delete ?tagOrId tagOrId ...?
502              Delete  each  of  the items given by each tagOrId, and return an
503              empty string.
504
505       pathName dtag tagOrId ?tagToDelete?
506              For each of the items given by tagOrId, delete the tag given  by
507              tagToDelete from the list of those associated with the item.  If
508              an item does not have the tag tagToDelete then the item is unaf‐
509              fected  by  the  command.   If  tagToDelete  is  omitted then it
510              defaults to tagOrId.  This command returns an empty string.
511
512       pathName find searchCommand ?arg arg ...?
513              This command returns a list consisting of  all  the  items  that
514              meet  the  constraints  specified  by  searchCommand  and arg's.
515              SearchCommand and args have any of the  forms  accepted  by  the
516              addtag  command.  The items are returned in stacking order, with
517              the lowest item first.
518
519       pathName focus ?tagOrId?
520              Set the keyboard focus for the canvas widget to the  item  given
521              by  tagOrId.  If tagOrId refers to several items, then the focus
522              is set to the first such item in the display list that  supports
523              the  insertion  cursor.  If tagOrId does not refer to any items,
524              or if none of them support the insertion cursor, then the  focus
525              is  not  changed.  If tagOrId is an empty string, then the focus
526              item is reset so that no item has the focus.  If tagOrId is  not
527              specified then the command returns the id for the item that cur‐
528              rently has the focus, or an empty string  if  no  item  has  the
529              focus.
530
531              Once  the  focus  has been set to an item, the item will display
532              the insertion cursor and all keyboard events will be directed to
533              that  item.  The focus item within a canvas and the focus window
534              on the screen (set with the focus command) are totally  indepen‐
535              dent: a given item does not actually have the input focus unless
536              (a) its canvas is the focus window and (b) the item is the focus
537              item within the canvas.  In most cases it is advisable to follow
538              the focus widget command with the focus command to set the focus
539              window to the canvas (if it was not there already).
540
541       pathName gettags tagOrId
542              Return  a  list  whose elements are the tags associated with the
543              item given by tagOrId.  If tagOrId refers to more than one item,
544              then  the tags are returned from the first such item in the dis‐
545              play list.  If tagOrId does not refer to any items,  or  if  the
546              item contains no tags, then an empty string is returned.
547
548       pathName icursor tagOrId index
549              Set  the  position of the insertion cursor for the item(s) given
550              by tagOrId to just before the character whose position is  given
551              by  index.   If some or all of the items given by tagOrId do not
552              support an insertion cursor then this command has no  effect  on
553              them.   See  INDICES  above for a description of the legal forms
554              for index.  Note: the insertion cursor is only displayed  in  an
555              item  if  that  item  currently  has the keyboard focus (see the
556              focus widget command, above), but the cursor position may be set
557              even  when  the  item  does  not  have  the focus.  This command
558              returns an empty string.
559
560       pathName imove tagOrId index x y
561              This command causes the index'th coordinate of each of the items │
562              indicated  by  tagOrId  to  be  relocated to the location (x,y). │
563              Each item interprets index independently according to the  rules │
564              described  in  INDICES  above. Out of the standard set of items, │
565              only line and polygon items may have their coordinates relocated │
566              this way.
567
568       pathName index tagOrId index
569              This command returns a decimal string giving the numerical index
570              within tagOrId corresponding to index.  Index  gives  a  textual
571              description  of  the  desired  position  as described in INDICES
572              above.  Text items interpret index as an index to  a  character,
573              line  and polygon items interpret it as an index to a coordinate
574              (an x,y pair).  The return value is guaranteed to lie between  0
575              and  the  number of characters, or coordinates, within the item,
576              inclusive.  If tagOrId refers to multiple items, then the  index
577              is  processed in the first of these items that supports indexing
578              operations (in display list order).
579
580       pathName insert tagOrId beforeThis string
581              For each of the items given by tagOrId,  if  the  item  supports
582              text  or  coordinate, insertion then string is inserted into the
583              item's text just before  the  character,  or  coordinate,  whose
584              index  is  beforeThis.   Text  items  interpret beforeThis as an
585              index to a character, line and polygon items interpret it as  an
586              index to a coordinate (an x,y pair).  For lines and polygons the
587              string must be a valid coordinate sequence.  See  INDICES  above
588              for  information  about  the forms allowed for beforeThis.  This
589              command returns an empty string.
590
591       pathName itemcget tagOrId option
592              Returns the current value of the configuration  option  for  the
593              item  given  by  tagOrId  whose name is option.  This command is
594              similar to the cget widget command except that it applies  to  a
595              particular  item  rather than the widget as a whole.  Option may
596              have any of the values accepted by  the  create  widget  command
597              when  the  item was created.  If tagOrId is a tag that refers to
598              more than one item, the first (lowest) such item is used.
599
600       pathName itemconfigure tagOrId ?option? ?value? ?option value ...?
601              This command is similar to the configure widget  command  except
602              that  it  modifies  item-specific options for the items given by
603              tagOrId instead of modifying options for the overall canvas wid‐
604              get.   If  no option is specified, returns a list describing all
605              of the available options for the first  item  given  by  tagOrId
606              (see  Tk_ConfigureInfo  for  information  on  the format of this
607              list). If option is specified with no value,  then  the  command
608              returns  a  list describing the one named option (this list will
609              be identical to the corresponding sublist of the value  returned
610              if  no  option  is specified). If one or more option-value pairs
611              are specified,  then  the  command  modifies  the  given  widget
612              option(s)  to have the given value(s) in each of the items given
613              by tagOrId; in this case the command returns  an  empty  string.
614              The  options and values are the same as those permissible in the
615              create widget command when the item(s)  were  created;  see  the
616              sections  describing  individual item types below for details on
617              the legal options.
618
619       pathName lower tagOrId ?belowThis?
620              Move all of the items given by tagOrId to a new position in  the
621              display  list  just  before  the  item  given  by belowThis.  If
622              tagOrId refers to more than one item then all are moved but  the
623              relative   order  of  the  moved  items  will  not  be  changed.
624              BelowThis is a tag or id; if it refers to  more  than  one  item
625              then  the  first  (lowest) of these items in the display list is
626              used as the destination location for  the  moved  items.   Note:
627              this  command has no effect on window items. Window items always
628              obscure other item types, and the stacking order of window items
629              is  determined  by  the raise command and lower command, not the
630              raise widget command and  lower  widget  command  for  canvases.
631              This command returns an empty string.
632
633       pathName move tagOrId xAmount yAmount
634              Move each of the items given by tagOrId in the canvas coordinate
635              space by adding xAmount to the x-coordinate of each point  asso‐
636              ciated  with  the  item  and yAmount to the y-coordinate of each
637              point associated with the item.  This command returns  an  empty
638              string.
639
640       pathName moveto tagOrId xPos yPos
641              Move  the  items given by tagOrId in the canvas coordinate space │
642              so that the first coordinate pair of the  bottommost  item  with │
643              tag  tagOrId  is  located at position (xPos,yPos). xPos and yPos
644              may be the empty string, in which case the corresponding coordi‐ │
645              nate will be unchanged. All items matching tagOrId remain in the │
646              same positions relative to each other.  This command returns  an │
647              empty string.
648
649       pathName postscript ?option value option value ...?
650              Generate a Postscript representation for part or all of the can‐
651              vas.  If the -file option is specified then  the  Postscript  is
652              written to a file and an empty string is returned; otherwise the
653              Postscript is returned as the result of  the  command.   If  the
654              interpreter  that  owns the canvas is marked as safe, the opera‐
655              tion will fail because safe  interpreters  are  not  allowed  to
656              write  files.  If the -channel option is specified, the argument
657              denotes the name of a channel already opened  for  writing.  The
658              Postscript  is  written to that channel, and the channel is left
659              open for further writing at the end of the operation.  The Post‐
660              script  is created in Encapsulated Postscript form using version
661              3.0 of the Document Structuring Conventions.  Note:  by  default
662              Postscript is only generated for information that appears in the
663              canvas's window on the screen. If the canvas is freshly  created
664              it  may still have its initial size of 1x1 pixel so nothing will
665              appear in the Postscript. To  get  around  this  problem  either
666              invoke the update command to wait for the canvas window to reach
667              its final size, or else use the -width and  -height  options  to
668              specify the area of the canvas to print.  The option-value argu‐
669              ment pairs provide additional information to control the genera‐
670              tion of Postscript. The following options are supported:
671
672              -channel channelName
673                     Specifies  the  name of the channel to which to write the
674                     Postscript.  If this option and the -file option are  not
675                     specified  then  the Postscript is returned as the result
676                     of the command.
677
678              -colormap varName
679                     VarName must be the name of an array variable that speci‐
680                     fies a color mapping to use in the Postscript.  Each ele‐
681                     ment of varName must consist of Postscript code to set  a
682                     particular color value (e.g.  “1.0 1.0 0.0 setrgbcolor”).
683                     When outputting color information in the  Postscript,  Tk
684                     checks  to see if there is an element of varName with the
685                     same name as the color.  If so, Tk uses the value of  the
686                     element  as  the Postscript command to set the color.  If
687                     this option has not been specified, or  if  there  is  no
688                     entry in varName for a given color, then Tk uses the red,
689                     green, and blue intensities from the X color.
690
691              -colormode mode
692                     Specifies how to output color information. Mode  must  be
693                     either  color  (for full color output), gray (convert all
694                     colors to their gray-scale equivalents) or mono  (convert
695                     all colors to black or white).
696
697              -file fileName
698                     Specifies  the  name  of  the  file in which to write the
699                     Postscript.  If this option and the -channel  option  are
700                     not  specified  then  the  Postscript  is returned as the
701                     result of the command.
702
703              -fontmap varName
704                     VarName must be the name of an array variable that speci‐
705                     fies  a font mapping to use in the Postscript.  Each ele‐
706                     ment of varName must consist of a Tcl list with two  ele‐
707                     ments,  which are the name and point size of a Postscript
708                     font.  When outputting Postscript commands for a particu‐
709                     lar font, Tk checks to see if varName contains an element
710                     with the same name as the font.  If there is such an ele‐
711                     ment, then the font information contained in that element
712                     is used in the  Postscript.   Otherwise  Tk  attempts  to
713                     guess  what  Postscript font to use.  Tk's guesses gener‐
714                     ally only work for well-known fonts  such  as  Times  and
715                     Helvetica  and  Courier, and only if the X font name does
716                     not omit any dashes up through the point size.  For exam‐
717                     ple,   -*-Courier-Bold-R-Normal--*-120-*  will  work  but
718                     *Courier-Bold-R-Normal*120* will not; Tk needs the dashes
719                     to parse the font name).
720
721              -height size
722                     Specifies  the height of the area of the canvas to print.
723                     Defaults to the height of the canvas window.
724
725              -pageanchor anchor
726                     Specifies which point of the printed area of  the  canvas
727                     should  appear  over  the  positioning  point on the page
728                     (which is given by the -pagex and -pagey  options).   For
729                     example,  -pageanchor  n means that the top center of the
730                     area of the canvas being printed (as it  appears  in  the
731                     canvas  window)  should  be  over  the positioning point.
732                     Defaults to center.
733
734              -pageheight size
735                     Specifies that the Postscript should be scaled in both  x
736                     and  y so that the printed area is size high on the Post‐
737                     script page.  Size consists of  a  floating-point  number
738                     followed  by  c for centimeters, i for inches, m for mil‐
739                     limeters, or p or  nothing  for  printer's  points  (1/72
740                     inch).  Defaults to the height of the printed area on the
741                     screen.  If both -pageheight and -pagewidth are specified
742                     then  the  scale factor from -pagewidth is used (non-uni‐
743                     form scaling is not implemented).
744
745              -pagewidth size
746                     Specifies that the Postscript should be scaled in both  x
747                     and  y so that the printed area is size wide on the Post‐
748                     script page.  Size has the same form as for  -pageheight.
749                     Defaults  to the width of the printed area on the screen.
750                     If both -pageheight and -pagewidth are specified then the
751                     scale factor from -pagewidth is used (non-uniform scaling
752                     is not implemented).
753
754              -pagex position
755                     Position gives the x-coordinate of the positioning  point
756                     on  the  Postscript  page, using any of the forms allowed
757                     for -pageheight.  Used in conjunction with the -pagey and
758                     -pageanchor  options  to determine where the printed area
759                     appears on the Postscript page.  Defaults to  the  center
760                     of the page.
761
762              -pagey position
763                     Position  gives the y-coordinate of the positioning point
764                     on the Postscript page, using any of  the  forms  allowed
765                     for -pageheight.  Used in conjunction with the -pagex and
766                     -pageanchor options to determine where the  printed  area
767                     appears  on  the Postscript page.  Defaults to the center
768                     of the page.
769
770              -rotate boolean
771                     Boolean specifies whether  the  printed  area  is  to  be
772                     rotated  90 degrees.  In non-rotated output the x-axis of
773                     the printed area runs along the short  dimension  of  the
774                     page  (“portrait”  orientation); in rotated output the x-
775                     axis runs along the long dimension of  the  page  (“land‐
776                     scape” orientation).  Defaults to non-rotated.
777
778              -width size
779                     Specifies  the  width of the area of the canvas to print.
780                     Defaults to the width of the canvas window.
781
782              -x position
783                     Specifies the x-coordinate of the left edge of  the  area
784                     of  the  canvas  that is to be printed, in canvas coordi‐
785                     nates, not window coordinates.  Defaults to  the  coordi‐
786                     nate of the left edge of the window.
787
788              -y position
789                     Specifies the y-coordinate of the top edge of the area of
790                     the canvas that is to be printed, in canvas  coordinates,
791                     not  window  coordinates.   Defaults to the coordinate of
792                     the top edge of the window.
793
794       pathName raise tagOrId ?aboveThis?
795              Move all of the items given by tagOrId to a new position in  the
796              display list just after the item given by aboveThis.  If tagOrId
797              refers to more than one item then all are moved but the relative
798              order  of  the  moved items will not be changed.  AboveThis is a
799              tag or id; if it refers to more than  one  item  then  the  last
800              (topmost) of these items in the display list is used as the des‐
801              tination location for the moved items.  This command returns  an
802              empty string.
803
804              Note:  this  command has no effect on window items. Window items
805              always obscure other item types, and the stacking order of  win‐
806              dow  items is determined by the raise command and lower command,
807              not the raise widget command and lower widget command  for  can‐
808              vases.
809
810       pathName rchars tagOrId first last string
811              This  command  causes  the text or coordinates between first and │
812              last for each of the items indicated by tagOrId to  be  replaced │
813              by  string.  Each  item  interprets first and last independently │
814              according to the rules described in INDICES above.  Out  of  the │
815              standard  set  of  items,  text  items support this operation by │
816              altering their text as directed, and line and polygon items sup‐ │
817              port  this operation by altering their coordinate list (in which │
818              case string should be a list of coordinates to use as a replace‐ │
819              ment). The other items ignore this operation.
820
821       pathName scale tagOrId xOrigin yOrigin xScale yScale
822              Rescale  the coordinates of all of the items given by tagOrId in
823              canvas coordinate space.  XOrigin and yOrigin identify the  ori‐
824              gin for the scaling operation and xScale and yScale identify the
825              scale factors for x- and y-coordinates,  respectively  (a  scale
826              factor  of  1.0 implies no change to that coordinate).  For each
827              of the points defining each item, the x-coordinate  is  adjusted
828              to change the distance from xOrigin by a factor of xScale.  Sim‐
829              ilarly, each y-coordinate is adjusted  to  change  the  distance
830              from  yOrigin  by  a  factor of yScale.  This command returns an
831              empty string.
832
833              Note that some items have only  a  single  pair  of  coordinates
834              (e.g.,  text, images and windows) and so scaling of them by this
835              command can only move them around.
836
837       pathName scan option args
838              This command is used to implement scanning on canvases.  It  has
839              two forms, depending on option:
840
841              pathName scan mark x y
842                     Records  x  and  y and the canvas's current view; used in
843                     conjunction with later scan dragto  commands.   Typically
844                     this  command  is associated with a mouse button press in
845                     the widget and x and y are the coordinates of the  mouse.
846                     It returns an empty string.
847
848              pathName scan dragto x y ?gain?
849                     This  command computes the difference between its x and y
850                     arguments (which are typically mouse coordinates) and the
851                     x  and  y arguments to the last scan mark command for the
852                     widget.  It then adjusts the view by gain times the  dif‐
853                     ference  in coordinates, where gain defaults to 10.  This
854                     command is typically associated with mouse motion  events
855                     in the widget, to produce the effect of dragging the can‐
856                     vas at high speed through its window. The return value is
857                     an empty string.
858
859       pathName select option ?tagOrId arg?
860              Manipulates  the  selection in one of several ways, depending on
861              option.  The command may take any of the forms described  below.
862              In  all of the descriptions below, tagOrId must refer to an item
863              that supports indexing and selection; if it refers  to  multiple
864              items  then  the  first  of these that supports indexing and the
865              selection is used.  Index gives a textual description of a posi‐
866              tion within tagOrId, as described in INDICES above.
867
868              pathName select adjust tagOrId index
869                     Locate the end of the selection in tagOrId nearest to the
870                     character given by index, and  adjust  that  end  of  the
871                     selection  to  be  at index (i.e. including but not going
872                     beyond index).  The other end of the  selection  is  made
873                     the  anchor  point for future select to commands.  If the
874                     selection is not currently in tagOrId then  this  command
875                     behaves  the  same  as  the  select  to  widget  command.
876                     Returns an empty string.
877
878              pathName select clear
879                     Clear the selection if it is  in  this  widget.   If  the
880                     selection  is  not in this widget then the command has no
881                     effect.  Returns an empty string.
882
883              pathName select from tagOrId index
884                     Set the selection anchor point for the widget to be  just
885                     before  the character given by index in the item given by
886                     tagOrId.  This command does not change the selection;  it
887                     just  sets  the  fixed  end  of  the selection for future
888                     select to commands.  Returns an empty string.
889
890              pathName select item
891                     Returns the id of the selected item, if the selection  is
892                     in  an  item  in this canvas.  If the selection is not in
893                     this canvas then an empty string is returned.
894
895              pathName select to tagOrId index
896                     Set the selection  to  consist  of  those  characters  of
897                     tagOrId  between  the  selection  anchor point and index.
898                     The new selection will include  the  character  given  by
899                     index;  it will include the character given by the anchor
900                     point only if index is  greater  than  or  equal  to  the
901                     anchor point.  The anchor point is determined by the most
902                     recent select adjust or select from command for this wid‐
903                     get.  If the selection anchor point for the widget is not
904                     currently in tagOrId, then it is set to the same  charac‐
905                     ter given by index.  Returns an empty string.
906
907       pathName type tagOrId
908              Returns the type of the item given by tagOrId, such as rectangle
909              or text.  If tagOrId refers to more than one item, then the type
910              of  the  first item in the display list is returned.  If tagOrId
911              does not refer to any items at  all  then  an  empty  string  is
912              returned.
913
914       pathName xview ?args?
915              This command is used to query and change the horizontal position
916              of the information displayed in the  canvas's  window.   It  can
917              take any of the following forms:
918
919              pathName xview
920                     Returns  a list containing two elements.  Each element is
921                     a real fraction between 0 and 1; together  they  describe
922                     the  horizontal  span that is visible in the window.  For
923                     example, if the first element is .2 and the  second  ele‐
924                     ment  is  .6, 20% of the canvas's area (as defined by the
925                     -scrollregion option) is off-screen to the left, the mid‐
926                     dle  40%  is visible in the window, and 40% of the canvas
927                     is off-screen to the right.  These are  the  same  values
928                     passed to scrollbars via the -xscrollcommand option.
929
930              pathName xview moveto fraction
931                     Adjusts  the  view  in the window so that fraction of the
932                     total width of the canvas  is  off-screen  to  the  left.
933                     Fraction must be a fraction between 0 and 1.
934
935              pathName xview scroll number what
936                     This  command shifts the view in the window left or right
937                     according to number and what.  Number must be an integer.
938                     What  must be either units or pages or an abbreviation of
939                     one of these.  If what is units, the view adjusts left or
940                     right  in  units of the xScrollIncrement option, if it is
941                     greater than zero, or in units of one-tenth the  window's
942                     width  otherwise.  If what is pages then the view adjusts
943                     in units of nine-tenths the window's width.  If number is
944                     negative  then  information  farther  to the left becomes
945                     visible; if it is positive then  information  farther  to
946                     the right becomes visible.
947
948       pathName yview ?args?
949              This  command  is used to query and change the vertical position
950              of the information displayed in the  canvas's  window.   It  can
951              take any of the following forms:
952
953              pathName yview
954                     Returns  a list containing two elements.  Each element is
955                     a real fraction between 0 and 1; together  they  describe
956                     the  vertical  span  that  is visible in the window.  For
957                     example, if the first element is .6 and the  second  ele‐
958                     ment  is  1.0,  the  lowest  40% of the canvas's area (as
959                     defined by the -scrollregion option) is  visible  in  the
960                     window.   These  are the same values passed to scrollbars
961                     via the -yscrollcommand option.
962
963              pathName yview moveto fraction
964                     Adjusts the view in the window so that  fraction  of  the
965                     canvas's  area  is  off-screen to the top.  Fraction is a
966                     fraction between 0 and 1.
967
968              pathName yview scroll number what
969                     This command adjusts the view in the window  up  or  down
970                     according to number and what.  Number must be an integer.
971                     What must be either units or pages.  If  what  is  units,
972                     the view adjusts up or down in units of the yScrollIncre‐
973                     ment option, if it is greater than zero, or in  units  of
974                     one-tenth  the  window's  height  otherwise.   If what is
975                     pages then the view adjusts in units of  nine-tenths  the
976                     window's  height.   If  number  is  negative  then higher
977                     information becomes visible; if it is positive then lower
978                     information becomes visible.
979

OVERVIEW OF ITEM TYPES

981       The  sections  below  describe  the various types of items supported by
982       canvas widgets. Each item type is characterized by two  things:  first,
983       the  form  of  the create command used to create instances of the type;
984       and second, a set of configuration options  for  items  of  that  type,
985       which  may  be  used  in  the create and itemconfigure widget commands.
986       Most items do not support indexing or selection or the commands related
987       to them, such as index and insert.  Where items do support these facil‐
988       ities, it is noted explicitly in the descriptions below.   At  present,
989       text, line and polygon items provide this support.  For lines and poly‐
990       gons the indexing facility is used to manipulate the coordinates of the
991       item.
992
993   COMMON ITEM OPTIONS
994       Many  items  share a common set of options. These options are explained
995       here, and then referred to be each widget type for brevity.
996
997       -anchor anchorPos
998              AnchorPos tells how to position the item relative to  the  posi‐
999              tioning  point  for  the  item;  it  may  have  any of the forms
1000              accepted by Tk_GetAnchor. For example, if  anchorPos  is  center
1001              then  the  item is centered on the point; if anchorPos is n then
1002              the item will be drawn so that its top center point  is  at  the
1003              positioning point.  This option defaults to center.
1004
1005       -dash pattern
1006
1007       -activedash pattern
1008
1009       -disableddash pattern
1010              This  option  specifies  dash  patterns  for  the normal, active
1011              state, and disabled state of an item.  pattern may have  any  of
1012              the forms accepted by Tk_GetDash.  If the dash options are omit‐
1013              ted then the default is a solid outline.  See DASH PATTERNS  for
1014              more information.
1015
1016       -dashoffset offset
1017              The  starting  offset in pixels into the pattern provided by the
1018              -dash option. -dashoffset is ignored if there is no  -dash  pat‐
1019              tern.  The  offset  may  have  any of the forms described in the
1020              COORDINATES section above.
1021
1022       -fill color
1023
1024       -activefill color
1025
1026       -disabledfill color
1027              Specifies the color to be used to fill item's area.  in its nor‐
1028              mal,  active,  and  disabled  states,  Color may have any of the
1029              forms accepted by Tk_GetColor.  For the line item, it  specifies
1030              the  color  of  the line drawn.  For the text item, it specifies
1031              the foreground color of the text.  If color is an  empty  string
1032              (the  default  for  all canvas items except line and text), then
1033              the item will not be filled.
1034
1035       -outline color
1036
1037       -activeoutline color
1038
1039       -disabledoutline color
1040              This option specifies the color that should be used to draw  the
1041              outline  of  the item in its normal, active and disabled states.
1042              Color may have any of the forms  accepted  by  Tk_GetColor.   If
1043              color  is  specified as an empty string then no outline is drawn
1044              for the item.
1045
1046       -offset offset
1047              Specifies the offset of stipples. The offset value can be of the
1048              form  x,y or side, where side can be n, ne, e, se, s, sw, w, nw,
1049              or center. In the first case the origin is  the  origin  of  the
1050              toplevel  of the current window.  For the canvas itself and can‐
1051              vas objects the origin is the canvas origin, but  putting  #  in
1052              front of the coordinate pair indicates using the toplevel origin
1053              instead. For canvas objects, the  -offset  option  is  used  for
1054              stippling as well. For the line and polygon canvas items you can
1055              also specify an index as argument, which  connects  the  stipple
1056              origin to one of the coordinate points of the line/polygon. Note
1057              that stipple  offsets  are  only  supported  on  X11;  they  are
1058              silently ignored on other platforms.
1059
1060       -outlinestipple bitmap
1061
1062       -activeoutlinestipple bitmap
1063
1064       -disabledoutlinestipple bitmap
1065              This  option  specifies  stipple patterns that should be used to
1066              draw the outline of the item in its normal, active and  disabled
1067              states.  Indicates that the outline for the item should be drawn
1068              with a stipple pattern; bitmap specifies the stipple pattern  to
1069              use, in any of the forms accepted by Tk_GetBitmap.  If the -out‐
1070              line option has not been  specified  then  this  option  has  no
1071              effect.   If  bitmap  is an empty string (the default), then the
1072              outline is drawn in a solid fashion.  Note that stipples are not
1073              well supported on platforms that do not use X11 as their drawing
1074              API.
1075
1076       -outlineoffset offset
1077              Specifies the offset of the stipple pattern used  for  outlines,
1078              in the same way that the -outline option controls fill stipples.
1079              (See the -outline option for a description of the syntax of off‐
1080              set.)
1081
1082       -stipple bitmap
1083
1084       -activestipple bitmap
1085
1086       -disabledstipple bitmap
1087              This  option  specifies  stipple patterns that should be used to
1088              fill the item in its normal, active and disabled states.  bitmap
1089              specifies  the  stipple  pattern  to  use,  in  any of the forms
1090              accepted by Tk_GetBitmap.  If the  -fill  option  has  not  been
1091              specified then this option has no effect.  If bitmap is an empty
1092              string (the default), then filling is done in a  solid  fashion.
1093              For  the text item, it affects the actual text.  Note that stip‐
1094              ples are not well supported on platforms that do not use X11  as
1095              their drawing API.
1096
1097       -state state
1098              This allows an item to override the canvas widget's global state
1099              option. It takes the same values: normal, disabled or hidden.
1100
1101       -tags tagList
1102              Specifies a set of tags to apply to the item.  TagList  consists
1103              of  a list of tag names, which replace any existing tags for the
1104              item. TagList may be an empty list.
1105
1106       -width outlineWidth
1107
1108       -activewidth outlineWidth
1109
1110       -disabledwidth outlineWidth
1111              Specifies the width of the outline to be drawn around the item's
1112              region, in its normal, active and disabled states.  outlineWidth
1113              may be in any of the forms described in the COORDINATES  section
1114              above.   If  the  -outline option has been specified as an empty
1115              string then this option has no effect. This option  defaults  to
1116              1.0.   For  arcs,  wide  outlines  will be drawn centered on the
1117              edges of the arc's region.
1118

STANDARD ITEM TYPES

1120   ARC ITEMS
1121       Items of type arc appear on the display as arc-shaped regions.  An  arc
1122       is  a  section  of  an  oval  delimited by two angles (specified by the
1123       -start and -extent options) and displayed in one of several ways (spec‐
1124       ified  by the -style option).  Arcs are created with widget commands of
1125       the following form:
1126              pathName create arc x1 y1 x2 y2 ?option value ...?
1127              pathName create arc coordList ?option value ...?
1128       The arguments x1, y1, x2, and y2 or coordList give the  coordinates  of
1129       two  diagonally  opposite corners of a rectangular region enclosing the
1130       oval that defines the arc.  After the coordinates there may be any num‐
1131       ber  of option-value pairs, each of which sets one of the configuration
1132       options for the item. These same option-value  pairs  may  be  used  in
1133       itemconfigure  widget  commands  to change the item's configuration. An
1134       arc item becomes the current item when the mouse pointer  is  over  any
1135       part  that is painted or (when fully transparent) that would be painted
1136       if both the -fill and -outline options were non-empty.
1137
1138       The following standard options are supported by arcs:
1139
1140              -dash                         -activedash
1141              -disableddash                 -dashoffset
1142              -fill                         -activefill
1143              -disabledfill                 -offset
1144              -outline                      -activeoutline
1145              -disabledoutline              -outlineoffset
1146              -outlinestipple               -activeoutlinestipple
1147              -disabledoutlinestipple       -stipple
1148              -activestipple                -disabledstipple
1149              -state                        -tags
1150              -width                        -activewidth
1151              -disabledwidth
1152
1153       The following extra options are supported for arcs:
1154
1155       -extent degrees
1156              Specifies the size of the angular range  occupied  by  the  arc.
1157              The  arc's  range  extends for degrees degrees counter-clockwise
1158              from the starting angle given by the -start option.  Degrees may
1159              be  negative.  If it is greater than 360 or less than -360, then
1160              degrees modulo 360 is used as the extent.
1161
1162       -start degrees
1163              Specifies the beginning of the angular  range  occupied  by  the
1164              arc.   Degrees  is  given  in units of degrees measured counter-
1165              clockwise from the 3-o'clock position; it may be either positive
1166              or negative.
1167
1168       -style type
1169              Specifies how to draw the arc. If type is pieslice (the default)
1170              then the arc's region is defined by  a  section  of  the  oval's
1171              perimeter  plus two line segments, one between the center of the
1172              oval and each end of the perimeter section.  If  type  is  chord
1173              then  the  arc's  region  is  defined by a section of the oval's
1174              perimeter plus a single line  segment  connecting  the  two  end
1175              points  of the perimeter section.  If type is arc then the arc's
1176              region consists of a section of the perimeter  alone.   In  this
1177              last case the -fill option is ignored.
1178
1179   BITMAP ITEMS
1180       Items  of  type bitmap appear on the display as images with two colors,
1181       foreground and background.  Bitmaps are created with widget commands of
1182       the following form:
1183              pathName create bitmap x y ?option value ...?
1184              pathName create bitmap coordList ?option value ...?
1185       The arguments x and y or coordList (which must have two elements) spec‐
1186       ify the coordinates of a point used to position the bitmap on the  dis‐
1187       play, as controlled by the -anchor option.  After the coordinates there
1188       may be any number of option-value pairs, each of which sets one of  the
1189       configuration  options  for the item. These same option-value pairs may
1190       be used in itemconfigure widget commands to change the item's  configu‐
1191       ration.  A  bitmap item becomes the current item when the mouse pointer
1192       is over any part of its bounding box.
1193
1194       The following standard options are supported by bitmaps:
1195
1196              -anchor                       -state
1197              -tags
1198
1199       The following extra options are supported for bitmaps:
1200
1201       -background color
1202
1203       -activebackground color
1204
1205       -disabledbackground color
1206              Specifies the color to use for each of the bitmap's  “0”  valued
1207              pixels  in  its  normal,  active and disabled states.  Color may
1208              have any of the forms accepted by Tk_GetColor.  If  this  option
1209              is not specified, or if it is specified as an empty string, then
1210              nothing is displayed where the bitmap pixels are  0;  this  pro‐
1211              duces a transparent effect.
1212
1213       -bitmap bitmap
1214
1215       -activebitmap bitmap
1216
1217       -disabledbitmap bitmap
1218              Specifies  the  bitmaps  to  display  in the item in its normal,
1219              active and disabled states.  Bitmap may have any  of  the  forms
1220              accepted by Tk_GetBitmap.
1221
1222       -foreground color
1223
1224       -activeforeground color
1225
1226       -disabledforeground color
1227              Specifies  the  color to use for each of the bitmap's “1” valued
1228              pixels in its normal, active and  disabled  states.   Color  may
1229              have any of the forms accepted by Tk_GetColor.
1230
1231   IMAGE ITEMS
1232       Items of type image are used to display images on a canvas.  Images are
1233       created with widget commands of the following form:
1234              pathName create image x y ?option value ...?
1235              pathName create image coordList ?option value ...?
1236       The arguments x and y or coordList specify the coordinates of  a  point
1237       used to position the image on the display, as controlled by the -anchor
1238       option.  After the coordinates there may be any number of  option-value
1239       pairs,  each  of  which  sets  one of the configuration options for the
1240       item. These same option-value pairs may be used in itemconfigure widget
1241       commands  to change the item's configuration. An image item becomes the
1242       current item when the mouse pointer is over any part  of  its  bounding
1243       box.
1244
1245       The following standard options are supported by images:
1246
1247              -anchor                       -state
1248              -tags
1249
1250       The following extra options are supported for images:
1251
1252       -image name
1253
1254       -activeimage name
1255
1256       -disabledimage name
1257              Specifies  the  name  of the images to display in the item in is
1258              normal, active and disabled states.  This image must  have  been
1259              created previously with the image create command.
1260
1261   LINE ITEMS
1262       Items  of type line appear on the display as one or more connected line
1263       segments or curves.  Line items support coordinate indexing  operations
1264       using  the dchars, index and insert widget commands.  Lines are created
1265       with widget commands of the following form:
1266              pathName create line x1 y1... xn yn ?option value ...?
1267              pathName create line coordList ?option value ...?
1268       The arguments x1 through yn or coordList give  the  coordinates  for  a
1269       series  of  two or more points that describe a series of connected line
1270       segments.   After  the  coordinates  there  may  be   any   number   of
1271       option-value pairs, each of which sets one of the configuration options
1272       for the item. These same option-value pairs may be used in  itemconfig‐
1273       ure  widget commands to change the item's configuration. A line item is
1274       the current item whenever the mouse pointer is over any segment of  the
1275       line, whether drawn or not and whether or not the line is smoothed.
1276
1277       The following standard options are supported by lines:
1278
1279              -dash                         -activedash
1280              -disableddash                 -dashoffset
1281              -fill                         -activefill
1282              -disabledfill                 -stipple
1283              -activestipple                -disabledstipple
1284              -state                        -tags
1285              -width                        -activewidth
1286              -disabledwidth
1287
1288       The following extra options are supported for lines:
1289
1290       -arrow where
1291              Indicates  whether  or  not arrowheads are to be drawn at one or
1292              both ends of the line.  Where must have one of the  values  none
1293              (for  no arrowheads), first (for an arrowhead at the first point
1294              of the line), last (for an arrowhead at the last  point  of  the
1295              line),  or  both  (for  arrowheads  at  both ends).  This option
1296              defaults to none.
1297
1298       -arrowshape shape
1299              This option indicates how to draw arrowheads.  The  shape  argu‐
1300              ment  must be a list with three elements, each specifying a dis‐
1301              tance in any of the forms described in the  COORDINATES  section
1302              above.   The  first element of the list gives the distance along
1303              the line from the neck of the arrowhead to its tip.  The  second
1304              element  gives  the  distance  along  the line from the trailing
1305              points of the arrowhead to the tip, and the third element  gives
1306              the  distance  from the outside edge of the line to the trailing
1307              points.  If this option is not specified then Tk picks  a  “rea‐
1308              sonable” shape.
1309
1310       -capstyle style
1311              Specifies  the  ways  in  which caps are to be drawn at the end‐
1312              points of the line.  Style may have any of the forms accepted by
1313              Tk_GetCapStyle  (butt, projecting, or round).  If this option is
1314              not specified then it defaults to butt.   Where  arrowheads  are
1315              drawn the cap style is ignored.
1316
1317       -joinstyle style
1318              Specifies  the  ways in which joints are to be drawn at the ver‐
1319              tices of the line.  Style may have any of the forms accepted  by
1320              Tk_GetJoinStyle (bevel, miter, or round).  If this option is not
1321              specified then it defaults to round.  If the line only  contains
1322              two points then this option is irrelevant.
1323
1324       -smooth smoothMethod
1325              smoothMethod  must  have  one  of the forms accepted by Tcl_Get‐
1326              Boolean or a line smoothing method.  Only true and raw are  sup‐
1327              ported  in  the  core (with bezier being an alias for true), but
1328              more can be added at runtime. If a boolean false value or  empty
1329              string  is given, no smoothing is applied. A boolean truth value
1330              assumes true smoothing.  If the smoothing method is  true,  this
1331              indicates  that the line should be drawn as a curve, rendered as
1332              a set of quadratic splines: one spline is drawn  for  the  first
1333              and  second  line segments, one for the second and third, and so
1334              on. Straight-line segments can be generated within  a  curve  by
1335              duplicating  the end-points of the desired line segment.  If the
1336              smoothing method is raw, this indicates  that  the  line  should
1337              also  be  drawn  as a curve but where the list of coordinates is
1338              such that the first coordinate pair (and every third  coordinate
1339              pair  thereafter)  is  a knot point on a cubic Bezier curve, and
1340              the other coordinates are control points  on  the  cubic  Bezier
1341              curve. Straight line segments can be generated within a curve by
1342              making control points equal to their neighbouring  knot  points.
1343              If  the  last point is a control point and not a knot point, the
1344              point is repeated (one or two times) so that it also  becomes  a
1345              knot point.
1346
1347       -splinesteps number
1348              Specifies  the  degree  of  smoothness  desired for curves: each
1349              spline will be approximated  with  number  line  segments.  This
1350              option is ignored unless the -smooth option is true or raw.
1351
1352   OVAL ITEMS
1353       Items  of  type oval appear as circular or oval regions on the display.
1354       Each oval may have an outline, a fill, or both. Ovals are created  with
1355       widget commands of the following form:
1356              pathName create oval x1 y1 x2 y2 ?option value ...?
1357              pathName create oval coordList ?option value ...?
1358       The  arguments  x1, y1, x2, and y2 or coordList give the coordinates of
1359       two diagonally opposite corners of a rectangular region  enclosing  the
1360       oval.   The  oval  will include the top and left edges of the rectangle
1361       not the lower or right edges.  If the region is square then the result‐
1362       ing  oval  is  circular; otherwise it is elongated in shape.  After the
1363       coordinates there may be any number  of  option-value  pairs,  each  of
1364       which  sets  one  of the configuration options for the item. These same
1365       option-value pairs may be used  in  itemconfigure  widget  commands  to
1366       change  the item's configuration. An oval item becomes the current item
1367       when the mouse pointer is over any part that is painted or (when  fully
1368       transparent)  that  would  be  painted  if  both the -fill and -outline
1369       options were non-empty.
1370
1371       The following standard options are supported by ovals:
1372
1373              -dash                         -activedash
1374              -disableddash                 -dashoffset
1375              -fill                         -activefill
1376              -disabledfill                 -offset
1377              -outline                      -activeoutline
1378              -disabledoutline              -outlineoffset
1379              -outlinestipple               -activeoutlinestipple
1380              -disabledoutlinestipple       -stipple
1381              -activestipple                -disabledstipple
1382              -state                        -tags
1383              -width                        -activewidth
1384              -disabledwidth
1385
1386       There are no oval-specific options.
1387
1388   POLYGON ITEMS
1389       Items of type polygon appear as polygonal or curved filled  regions  on
1390       the  display.   Polygon  items  support  coordinate indexing operations
1391       using the dchars, index and insert widget commands.  Polygons are  cre‐
1392       ated with widget commands of the following form:
1393              pathName create polygon x1 y1 ... xn yn ?option value ...?
1394              pathName create polygon coordList ?option value ...?
1395       The  arguments  x1  through yn or coordList specify the coordinates for
1396       three or more points that define a polygon.  The first point should not
1397       be repeated as the last to close the shape; Tk will automatically close
1398       the periphery between the first and last points.  After the coordinates
1399       there  may  be any number of option-value pairs, each of which sets one
1400       of the configuration options for  the  item.  These  same  option-value
1401       pairs may be used in itemconfigure widget commands to change the item's
1402       configuration. A polygon item is the current item  whenever  the  mouse
1403       pointer  is  over  any  part  of  the polygon, whether drawn or not and
1404       whether or not the outline is smoothed.
1405
1406       The following standard options are supported by polygons:
1407
1408              -dash                         -activedash
1409              -disableddash                 -dashoffset
1410              -fill                         -activefill
1411              -disabledfill                 -offset
1412              -outline                      -activeoutline
1413              -disabledoutline              -outlineoffset
1414              -outlinestipple               -activeoutlinestipple
1415              -disabledoutlinestipple       -stipple
1416              -activestipple                -disabledstipple
1417              -state                        -tags
1418              -width                        -activewidth
1419              -disabledwidth
1420
1421       The following extra options are supported for polygons:
1422
1423       -joinstyle style
1424              Specifies the ways in which joints are to be drawn at  the  ver‐
1425              tices  of the outline.  Style may have any of the forms accepted
1426              by Tk_GetJoinStyle (bevel, miter, or round).  If this option  is
1427              not specified then it defaults to round.
1428
1429       -smooth boolean
1430              Boolean must have one of the forms accepted by Tcl_GetBoolean or
1431              a line smoothing method. Only true and raw are supported in  the
1432              core  (with  bezier  being  an  alias for true), but more can be
1433              added at runtime. If a boolean false value or  empty  string  is
1434              given,  no  smoothing  is applied. A boolean truth value assumes
1435              true smoothing.  If the smoothing method is true, this indicates
1436              that  the  polygon should be drawn as a curve, rendered as a set
1437              of quadratic splines: one spline is drawn for the first and sec‐
1438              ond  line  segments,  one  for  the second and third, and so on.
1439              Straight-line segments can be generated within a curve by dupli‐
1440              cating  the  end-points  of  the  desired  line segment.  If the
1441              smoothing method is raw, this indicates that the polygon  should
1442              also  be  drawn  as a curve but where the list of coordinates is
1443              such that the first coordinate pair (and every third  coordinate
1444              pair  thereafter)  is  a knot point on a cubic Bezier curve, and
1445              the other coordinates are control points  on  the  cubic  Bezier
1446              curve. Straight line segments can be venerated within a curve by
1447              making control points equal to their neighbouring  knot  points.
1448              If  the  last point is not the second point of a pair of control
1449              points, the point is repeated (one or two times) so that it also
1450              becomes  the second point of a pair of control points (the asso‐
1451              ciated knot point will be the first control point).
1452
1453       -splinesteps number
1454              Specifies the degree of  smoothness  desired  for  curves:  each
1455              spline  will  be  approximated  with  number line segments. This
1456              option is ignored unless the -smooth option is true or raw.
1457
1458       Polygon items are different from other items such as rectangles,  ovals
1459       and  arcs in that interior points are considered to be “inside” a poly‐
1460       gon (e.g. for purposes of the find closest and find overlapping  widget
1461       commands)  even  if  it  is  not filled.  For most other item types, an
1462       interior point is considered to be inside the item only if the item  is
1463       filled or if it has neither a fill nor an outline. If you would like an
1464       unfilled polygon whose interior points are not considered to be  inside
1465       the polygon, use a line item instead.
1466
1467   RECTANGLE ITEMS
1468       Items  of  type rectangle appear as rectangular regions on the display.
1469       Each rectangle may have an outline, a fill,  or  both.  Rectangles  are
1470       created with widget commands of the following form:
1471              pathName create rectangle x1 y1 x2 y2 ?option value ...?
1472              pathName create rectangle coordList ?option value ...?
1473       The  arguments  x1,  y1,  x2, and y2 or coordList (which must have four
1474       elements) give the coordinates of two diagonally  opposite  corners  of
1475       the  rectangle (the rectangle will include its upper and left edges but
1476       not its lower or right edges).  After the coordinates there may be  any
1477       number  of option-value pairs, each of which sets one of the configura‐
1478       tion options for the item. These same option-value pairs may be used in
1479       itemconfigure  widget  commands  to  change the item's configuration. A
1480       rectangle item becomes the current item when the mouse pointer is  over
1481       any  part  that  is  painted  or (when fully transparent) that would be
1482       painted if both the -fill and -outline options were non-empty.
1483
1484       The following standard options are supported by rectangles:
1485
1486              -dash                         -activedash
1487              -disableddash                 -dashoffset
1488              -fill                         -activefill
1489              -disabledfill                 -offset
1490              -outline                      -activeoutline
1491              -disabledoutline              -outlineoffset
1492              -outlinestipple               -activeoutlinestipple
1493              -disabledoutlinestipple       -stipple
1494              -activestipple                -disabledstipple
1495              -state                        -tags
1496              -width                        -activewidth
1497              -disabledwidth
1498
1499       There are no rectangle-specific options.
1500
1501   TEXT ITEMS
1502       A text item displays a string of characters on the  screen  in  one  or
1503       more lines.  Text items support indexing, editing and selection through
1504       the dchars widget command, the focus widget command, the icursor widget
1505       command,  the  index widget command, the insert widget command, and the
1506       select widget command.  Text items are created with widget commands  of
1507       the following form:
1508              pathName create text x y ?option value ...?
1509              pathName create text coordList ?option value ...?
1510       The arguments x and y or coordList (which must have two elements) spec‐
1511       ify the coordinates of a point used to position the text on the display
1512       (see  the options below for more information on how text is displayed).
1513       After the coordinates there may be any number  of  option-value  pairs,
1514       each of which sets one of the configuration options for the item. These
1515       same option-value pairs may be used in itemconfigure widget commands to
1516       change  the  item's configuration. A text item becomes the current item
1517       when the mouse pointer is over any part of its bounding box.
1518
1519       The following standard options are supported by text items:
1520
1521              -anchor                       -fill
1522              -activefill                   -disabledfill
1523              -stipple                      -activestipple
1524              -disabledstipple              -state
1525              -tags
1526
1527       The following extra options are supported for text items:
1528
1529       -angle rotationDegrees
1530              RotationDegrees tells how many degrees to rotate the text  anti‐ │
1531              clockwise  about the positioning point for the text; it may have │
1532              any floating-point value from 0.0  to  360.0.  For  example,  if │
1533              rotationDegrees  is  90,  then the text will be drawn vertically │
1534              from bottom to top.  This option defaults to 0.0.
1535
1536       -font fontName
1537              Specifies the font to use for the text item.   FontName  may  be
1538              any  string  acceptable  to  Tk_GetFont.   If this option is not
1539              specified, it defaults to a system-dependent font.
1540
1541       -justify how
1542              Specifies how to justify the text within  its  bounding  region.
1543              How  must  be  one  of  the values left, right, or center.  This
1544              option will only matter if the text  is  displayed  as  multiple
1545              lines.  If the option is omitted, it defaults to left.
1546
1547       -text string
1548              String  specifies  the  characters  to  be displayed in the text
1549              item.  Newline characters cause line breaks.  The characters  in
1550              the  item  may also be changed with the insert and delete widget
1551              commands.  This option defaults to an empty string.
1552
1553       -underline
1554              Specifies the integer index of a character within the text to be
1555              underlined.  0  corresponds  to  the first character of the text
1556              displayed, 1 to the next character, and so on. -1 means that  no
1557              underline  should  be  drawn  (if  the  whole text item is to be
1558              underlined, the appropriate font should be used instead).
1559
1560       -width lineLength
1561              Specifies a maximum line length for the  text,  in  any  of  the
1562              forms  described  in  the  COORDINATES  section  above.  If this
1563              option is zero (the default) the text is broken into lines  only
1564              at newline characters.  However, if this option is non-zero then
1565              any line that would be longer than  lineLength  is  broken  just
1566              before  a  space  character  to make the line shorter than line‐
1567              Length; the space character is treated as if it were  a  newline
1568              character.
1569
1570   WINDOW ITEMS
1571       Items  of  type  window  cause a particular window to be displayed at a
1572       given position on the canvas.  Window items  are  created  with  widget
1573       commands of the following form:
1574              pathName create window x y ?option value ...?
1575              pathName create window coordList ?option value ...?
1576       The arguments x and y or coordList (which must have two elements) spec‐
1577       ify the coordinates of a point used to position the window on the  dis‐
1578       play, as controlled by the -anchor option.  After the coordinates there
1579       may be any number of option-value pairs, each of which sets one of  the
1580       configuration  options  for the item. These same option-value pairs may
1581       be used in itemconfigure widget commands to change the item's  configu‐
1582       ration.  Theoretically, a window item becomes the current item when the
1583       mouse pointer is over any part of its bounding  box,  but  in  practice
1584       this  typically  does not happen because the mouse pointer ceases to be
1585       over the canvas at that point.
1586
1587       The following standard options are supported by window items:
1588
1589              -anchor                       -state
1590              -tags
1591
1592       The following extra options are supported for window items:
1593
1594       -height pixels
1595              Specifies the height to assign to the item's window.  Pixels may
1596              have  any  of  the  forms  described  in the COORDINATES section
1597              above.  If this option is not specified, or if it  is  specified
1598              as  zero,  then  the window is given whatever height it requests
1599              internally.
1600
1601       -width pixels
1602              Specifies the width to assign to the item's window.  Pixels  may
1603              have  any  of  the  forms  described  in the COORDINATES section
1604              above.  If this option is not specified, or if it  is  specified
1605              as  zero,  then  the  window is given whatever width it requests
1606              internally.
1607
1608       -window pathName
1609              Specifies the window to associate with this  item.   The  window
1610              specified  by pathName must either be a child of the canvas wid‐
1611              get or a child of some ancestor of the canvas widget.   PathName
1612              may not refer to a top-level window.
1613
1614       Note:  due  to restrictions in the ways that windows are managed, it is
1615       not possible to draw other graphical items (such as lines  and  images)
1616       on top of window items. A window item always obscures any graphics that
1617       overlap it, regardless of their order in the display  list.  Also  note
1618       that  window items, unlike other canvas items, are not clipped for dis‐
1619       play by their containing canvas's border, and are  instead  clipped  by
1620       the  parent  widget of the window specified by the -window option; when
1621       the parent widget is the canvas, this means that the  window  item  can
1622       overlap the canvas's border.
1623

APPLICATION-DEFINED ITEM TYPES

1625       It is possible for individual applications to define new item types for
1626       canvas widgets using C code.  See the documentation for  Tk_CreateItem‐
1627       Type.
1628

BINDINGS

1630       In  the  current implementation, new canvases are not given any default
1631       behavior: you will have to execute explicit Tcl commands  to  give  the
1632       canvas its behavior.
1633

CREDITS

1635       Tk's  canvas  widget  is a blatant ripoff of ideas from Joel Bartlett's
1636       ezd program. Ezd provides structured graphics in a  Scheme  environment
1637       and preceded canvases by a year or two. Its simple mechanisms for plac‐
1638       ing and animating graphical objects inspired the functions of canvases.
1639

SEE ALSO

1641       bind(n), font(n), image(n), scrollbar(n)
1642

KEYWORDS

1644       canvas, widget
1645
1646
1647
1648Tk                                    8.3                            canvas(n)
Impressum