1Canvas(3)             User Contributed Perl Documentation            Canvas(3)
2
3
4

NAME

6       Tk::Canvas - Create and manipulate Canvas widgets
7

SYNOPSIS

9       $canvas = $parent->Canvas(?options?);
10

STANDARD OPTIONS

12       -background    -highlightthickness -insertwidth   -state
13       -borderwidth   -insertbackground   -relief   -tile
14       -cursor   -insertborderwidth  -selectbackground   -takefocus
15       -highlightbackground     -insertofftime -selectborderwidth  -xscrollcommand
16       -highlightcolor     -insertontime  -selectforeground   -yscrollcommand
17

WIDGET-SPECIFIC OPTIONS

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

DESCRIPTION

97       The Canvas method creates a new window (given by the $canvas argument)
98       and makes it into a canvas widget.  Additional options, described
99       above, may be specified on the command line or in the option database
100       to configure aspects of the canvas such as its colors and 3-D relief.
101       The canvas command returns its $canvas argument.  At the time this
102       command is invoked, there must not exist a window named $canvas, but
103       $canvas's parent must exist.
104
105       Canvas widgets implement structured graphics.  A canvas displays any
106       number of items, which may be things like rectangles, circles, lines,
107       and text.  Items may be manipulated (e.g. moved or re-colored) and
108       callbacks may be associated with items in much the same way that the
109       bind method allows callbacks to be bound to widgets.  For example, a
110       particular callback may be associated with the <Button-1> event so that
111       the callback is invoked whenever button 1 is pressed with the mouse
112       cursor over an item.  This means that items in a canvas can have
113       behaviors defined by the Callbacks bound to them.
114

DISPLAY LIST

116       The items in a canvas are ordered for purposes of display, with the
117       first item in the display list being displayed first, followed by the
118       next item in the list, and so on.  Items later in the display list
119       obscure those that are earlier in the display list and are sometimes
120       referred to as being ``on top'' of earlier items.  When a new item is
121       created it is placed at the end of the display list, on top of
122       everything else.  Widget methods may be used to re-arrange the order of
123       the display list.
124
125       Window items are an exception to the above rules.  The underlying
126       window systems require them always to be drawn on top of other items.
127       In addition, the stacking order of window items is not affected by any
128       of the canvas methods; you must use the raise and lower Tk widget
129       methods instead.
130

ITEM IDS AND TAGS

132       Items in a canvas widget may be named in either of two ways: by id or
133       by tag.  Each item has a unique identifying number which is assigned to
134       that item when it is created.  The id of an item never changes and id
135       numbers are never re-used within the lifetime of a canvas widget.
136
137       Each item may also have any number of tags associated with it.  A tag
138       is just a string of characters, and it may take any form except that of
139       an integer.  For example, ``x123'' is OK but ``123'' isn't.  The same
140       tag may be associated with many different items.  This is commonly done
141       to group items in various interesting ways;  for example, all selected
142       items might be given the tag ``selected''.
143
144       The tag all is implicitly associated with every item in the canvas;  it
145       may be used to invoke operations on all the items in the canvas.
146
147       The tag current is managed automatically by Tk; it applies to the
148       current item, which is the topmost item whose drawn area covers the
149       position of the mouse cursor.  If the mouse is not in the canvas widget
150       or is not over an item, then no item has the current tag.
151
152       When specifying items in canvas methods, if the specifier is an integer
153       then it is assumed to refer to the single item with that id.  If the
154       specifier is not an integer, then it is assumed to refer to all of the
155       items in the canvas that have a tag matching the specifier.  The symbol
156       tagOrId is used below to indicate that an argument specifies either an
157       id that selects a single item or a tag that selects zero or more items.
158
159       tagOrId may contain a logical expressions of tags by using operators:
160       '&&', '||', '^' '!', and parenthezised subexpressions.  For example:
161
162       $c->find('withtag',  '(a&&!b)|(!a&&b)');
163
164       or equivalently:
165
166       $c->find('withtag', 'a^b');
167
168       will find only those items with either "a" or "b" tags, but not both.
169
170       Some methods only operate on a single item at a time;  if tagOrId is
171       specified in a way that names multiple items, then the normal behavior
172       is for the methods is to use the first (lowest) of these items in the
173       display list that is suitable for the method.  Exceptions are noted in
174       the method descriptions below.
175

COORDINATES

177       All coordinates related to canvases are stored as floating-point
178       numbers.  Coordinates and distances are specified in screen units,
179       which are floating-point numbers optionally followed by one of several
180       letters.  If no letter is supplied then the distance is in pixels.  If
181       the letter is m then the distance is in millimeters on the screen;  if
182       it is c then the distance is in centimeters; i means inches, and p
183       means printers points (1/72 inch).  Larger y-coordinates refer to
184       points lower on the screen;  larger x-coordinates refer to points
185       farther to the right.
186

TRANSFORMATIONS

188       Normally the origin of the canvas coordinate system is at the upper-
189       left corner of the window containing the canvas.  It is possible to
190       adjust the origin of the canvas coordinate system relative to the
191       origin of the window using the xview and yview methods;  this is
192       typically used for scrolling.  Canvases do not support scaling or
193       rotation of the canvas coordinate system relative to the window
194       coordinate system.
195
196       Individual items may be moved or scaled using methods described below,
197       but they may not be rotated.
198

INDICES

200       Text items support the notion of an index for identifying particular
201       positions within the item.
202
203       Indices are used for methods such as inserting text, deleting a range
204       of characters, and setting the insertion cursor position.  An index may
205       be specified in any of a number of ways, and different types of items
206       may support different forms for specifying indices.
207
208       In a similar fashion, line and polygon items support index for
209       identifying, inserting and deleting subsets of their coordinates.
210       Indices are used for commands such as inserting or deleting a range of
211       characters or coordinates, and setting the insertion cursor position.
212       An index may be specified in any of a number of ways, and different
213       types of items may support different forms for specifying indices.
214
215       Text items support the following forms for an index;  if you define new
216       types of text-like items, it would be advisable to support as many of
217       these forms as practical.  Note that it is possible to refer to the
218       character just after the last one in the text item;  this is necessary
219       for such tasks as inserting new text at the end of the item.  Lines and
220       Polygons don't support the insertion cursor and the selection. Their
221       indices are supposed to be even always, because coordinates always
222       appear in pairs.
223
224       number
225           A decimal number giving the position of the desired character
226           within the text item.  0 refers to the first character, 1 to the
227           next character, and so on. If indexes are odd for lines and
228           polygons, they will be automatically decremented by one.  A number
229           less than 0 is treated as if it were zero, and a number greater
230           than the length of the text item is treated as if it were equal to
231           the length of the text item. For polygons, numbers less than 0 or
232           greater then the length of the coordinate list will be adjusted by
233           adding or substracting the length until the result is between zero
234           and the length, inclusive.
235
236       end Refers to the character or coordinate just after the last one in
237           the item (same as the number of characters or coordinates in the
238           item).
239
240       insert
241           Refers to the character just before which the insertion cursor is
242           drawn in this item. Not valid for lines and polygons.
243
244       sel.first
245           Refers to the first selected character in the item.  If the
246           selection isn't in this item then this form is illegal.
247
248       sel.last
249           Refers to the last selected character in the item.  If the
250           selection isn't in this item then this form is illegal.
251
252       [x,y]
253           Refers to the character or coordinate at the point given by x and
254           y, where x and y are specified in the coordinate system of the
255           canvas.  If x and y lie outside the coordinates covered by the text
256           item, then they refer to the first or last character in the line
257           that is closest to the given point.  The Tcl string form "@x,y" is
258           also allowed.
259

DASH PATTERNS

261       Many items support the notion of an dash pattern for outlines.
262
263       The first possible syntax is a list of integers. Each element
264       represents the number of pixels of a line segment. Only the odd
265       segments are drawn using the "outline" color. The other segments are
266       drawn transparent.
267
268       The second possible syntax is a character list containing only 5
269       possible characters [.,-_ ],  with the first 4 characters producing a
270       segment of length 1 to 4, respectively, followed by a transparent
271       segment of length 2. The space can be used repeatedly to enlarge the
272       space between other line elements by 1, and can not occur as the first
273       position in the string.  The main difference of this syntax with the
274       previous one is that it it shape-conserving. This means that all values
275       in the dash list will be multiplied by the line width before display.
276       This assures that "." will always be displayed as a dot and "-" always
277       as a dash regardless of the line width.
278
279       Some examples, for a line width of 2:
280
281        -dash .     = -dash [2,4]
282        -dash -     = -dash [6,4]
283        -dash -.    = -dash [6,4,2,4]
284        -dash -..   = -dash [6,4,2,4,2,4]
285        -dash '.  ' = -dash [2,8]
286        -dash ','   = -dash [4,4]
287
288       On systems where only a limited set of dash patterns is available, the
289       dash pattern will be displayed as the closest available dash pattern.
290       For example, on Windows only the first 4 of the above examples are
291       available. The last 2 examples will be displayed identically as the
292       first one.
293

WIDGET METHODS

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

OVERVIEW OF ITEM TYPES

895       The sections below describe the various types of items supported by
896       canvas widgets.  Each item type is characterized by two things: first,
897       the form of the create method used to create instances of the type;
898       and second, a set of configuration options for items of that type,
899       which may be used in the create and itemconfigure methods.  Most items
900       don't support indexing or selection or the methods related to them,
901       such as index and insert.  Where items do support these facilities, it
902       is noted explicitly in the descriptions below.  At present, text, line
903       and polygon items provide this support.  For lines and polygons the
904       indexing facility is used to manipulate the coordinates of the item.
905

ARC ITEMS

907       Items of type arc appear on the display as arc-shaped regions.  An arc
908       is a section of an oval delimited by two angles (specified by the
909       -start and -extent options) and displayed in one of several ways
910       (specified by the -style option).  Arcs are created with methods of the
911       following form:
912
913        $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)
914
915       The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
916       opposite corners of a rectangular region enclosing the oval that
917       defines the arc.  After the coordinates there may be any number of
918       option-value pairs, each of which sets one of the configuration options
919       for the item.  These same option-value pairs may be used in
920       itemconfigure methods to change the item's configuration.  The
921       following options are supported for arcs:
922
923       -dash => pattern
924       -activedash => pattern
925       -disableddash => pattern
926           This option specifies dash patterns for the normal state, the
927           active state, and the disabled state of an arc item.  pattern may
928           have any of the forms accepted by Tk_GetDash.  If the dash options
929           are omitted then the default is a solid outline.
930
931       -dashoffset => offset
932           The starting offset into the pattern provided by the -dash option.
933           -dashoffset is ignored if there is no -dash pattern.
934
935       -extent => degrees
936           Specifies the size of the angular range occupied by the arc.  The
937           arc's range extends for degrees degrees counter-clockwise from the
938           starting angle given by the -start option.  Degrees may be
939           negative.  If it is greater than 360 or less than -360, then
940           degrees modulo 360 is used as the extent.
941
942       -fill => color
943       -activefill => color
944       -disabledfill => color
945           Specifies the color to be used to fill the arc region in its
946           normal, active, and disabled states, Color may have any of the
947           forms accepted by Tk_GetColor.  If color is an empty string (the
948           default), then then the arc will not be filled.
949
950       -outline => color
951       -activeoutline => color
952       -disabledoutline => color
953           This option specifies the color that should be used to draw the
954           outline of the arc in its normal, active and disabled states.
955           Color may have any of the forms accepted by Tk_GetColor.  This
956           option defaults to black.  If color is specified as undef then no
957           outline is drawn for the arc.
958
959       -outlinestipple => bitmap
960       -activeoutlinestipple => bitmap
961       -disabledoutlinestipple => bitmap
962           This option specifies stipple patterns that should be used to draw
963           the outline of the arc in its normal, active and disabled states.
964           Indicates that the outline for the arc should be drawn with a
965           stipple pattern; bitmap specifies the stipple pattern to use, in
966           any of the forms accepted by Tk_GetBitmap.  If the -outline option
967           hasn't been specified then this option has no effect.  If bitmap is
968           an empty string (the default), then the outline is drawn in a solid
969           fashion.
970
971       -start => degrees
972           Specifies the beginning of the angular range occupied by the arc.
973           Degrees is given in units of degrees measured counter-clockwise
974           from the 3-o'clock position;  it may be either positive or
975           negative.
976
977       -state => state
978           Modifies the state of the arc item where state may be set to one
979           of: normal, disabled, hidden or "". If set to empty, the state of
980           the canvas itself is used. An arc item may also be in the "active"
981           state if the mouse is currently over it.  Many options can take
982           separate specifications in normal, active and disabled states such
983           that the appearance of the item can be different in each state.
984
985       -stipple => bitmap
986       -activestipple => bitmap
987       -disabledstipple => bitmap
988           This option specifies stipple patterns that should be used to fill
989           the the arc in its normal, active and disabled states.  bitmap
990           specifies the stipple pattern to use, in any of the forms accepted
991           by Tk_GetBitmap.  If the -fill option hasn't been specified then
992           this option has no effect.  If bitmap is an empty string (the
993           default), then filling is done in a solid fashion.
994
995       -style => type
996           Specifies how to draw the arc.  If type is pieslice (the default)
997           then the arc's region is defined by a section of the oval's
998           perimeter plus two line segments, one between the center of the
999           oval and each end of the perimeter section.  If type is chord then
1000           the arc's region is defined by a section of the oval's perimeter
1001           plus a single line segment connecting the two end points of the
1002           perimeter section.  If type is arc then the arc's region consists
1003           of a section of the perimeter alone.  In this last case the -fill
1004           option is ignored.
1005
1006       -tags => tagList
1007           Specifies a set of tags to apply to the item.  TagList consists of
1008           a list of tag names, which replace any existing tags for the item.
1009           TagList may be an empty list.
1010
1011       -updatecommand => command
1012           Specifies a callback that is to be executed every time the arc item
1013           is updated on the screen.
1014
1015       -width => outlineWidth
1016       -activewidth => outlineWidth
1017       -disabledwidth => outlineWidth
1018           Specifies the width of the outline to be drawn around the arc's
1019           region, in its normal, active and disabled states.  outlineWidth
1020           may be in any of the forms described in the "COORDINATES" section
1021           above.  If the -outline option has been specified as undef then
1022           this option has no effect.  Wide outlines will be drawn centered on
1023           the edges of the arc's region.  This option defaults to 1.0.
1024

BITMAP ITEMS

1026       Items of type bitmap appear on the display as images with two colors,
1027       foreground and background.  Bitmaps are created with methods of the
1028       following form:
1029
1030        $canvas->createBitmap(x, y, ?option, value, option, value, ...?)
1031
1032       The arguments x and y specify the coordinates of a point used to
1033       position the bitmap on the display (see the -anchor option below for
1034       more information on how bitmaps are displayed).  After the coordinates
1035       there may be any number of option-value pairs, each of which sets one
1036       of the configuration options for the item.  These same option-value
1037       pairs may be used in itemconfigure methods to change the item's
1038       configuration.  The following options are supported for bitmaps:
1039
1040       -anchor => anchorPos
1041           AnchorPos tells how to position the bitmap relative to the
1042           positioning point for the item;  it may have any of the forms
1043           accepted by Tk_GetAnchor.  For example, if anchorPos is center then
1044           the bitmap is centered on the point;  if anchorPos is n then the
1045           bitmap will be drawn so that its top center point is at the
1046           positioning point.  This option defaults to center.
1047
1048       -background => color
1049       -activebackground => color
1050       -disabledbackground => color
1051           Specifies the color to use for each of the bitmap's '0' valued
1052           pixels in its normal, active and disabled states.  Color may have
1053           any of the forms accepted by Tk_GetColor.  If this option isn't
1054           specified, or if it is specified as undef, then nothing is
1055           displayed where the bitmap pixels are 0;  this produces a
1056           transparent effect.
1057
1058       -bitmap => bitmap
1059       -activebitmap => bitmap
1060       -disabledbitmap => bitmap
1061           Specifies the bitmaps to display in the item in its normal, active
1062           and disabled states. All bitmaps must have the same width and
1063           height.  Bitmap may have any of the forms accepted by Tk_GetBitmap.
1064
1065       -foreground => color
1066       -activeforeground => color
1067       -disabledforeground => color
1068           Specifies the color to use for each of the bitmap's '1' valued
1069           pixels in its normal, active and disabled states.  Color may have
1070           any of the forms accepted by Tk_GetColor and defaults to black.
1071
1072       -state => state
1073           Modifies the state of the bitmap item where state may be set to one
1074           of: normal, disabled, or hidden.  An bitmap item may also be in the
1075           "active" state if the mouse is currently over it.  Many options can
1076           take separate specifications in normal, active and disabled states
1077           such that the appearance of the item can be different in each
1078           state.
1079
1080       -tags => tagList
1081           Specifies a set of tags to apply to the item.  TagList consists of
1082           a list of tag names, which replace any existing tags for the item.
1083           TagList may be an empty list.
1084
1085       -updatecommand => command
1086           Specifies a callback that is to be executed every time the bitmap
1087           item is updated on the screen.
1088

GRID ITEMS

1090       Items of type grid are intended for producing a visual reference for
1091       interpreting other items. They can be drawn as either lines (with dash
1092       style) or as rectangular "dots" at each grid point.
1093
1094       Items of type grid are unlike other items they always cover the whole
1095       of the canvas, but are never enclosed by nor overlap any area and are
1096       not near any point. That is they are intended to be always visible but
1097       not "pickable", as such they do support the "active" state.  They are
1098       like other items in that: multiple grids are permitted, they can be
1099       raised and lowered relative to other items, they can be moved and
1100       scaled. As yet grids do not appear in PostScript output.
1101
1102       Grids have outline like configure options. Grids are created with
1103       methods of the following form:
1104
1105        $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)
1106
1107       The arguments x1, y1 give the origin of the grid. x2, and y2 give the
1108       coordinates of the next grid point in their respective directions.
1109       After the coordinates there may be any number of option-value pairs,
1110       each of which sets one of the configuration options for the item.
1111       These same option-value pairs may be used in itemconfigure methods to
1112       change the item's configuration.
1113
1114       The following options are supported for grids:
1115
1116       -lines => boolean
1117           If -lines is set to a true value then lines are drawn for both X
1118           and Y grids in the style determined by -dash. Otherwise retangular
1119           "dots" are drawn at each grid point.
1120
1121       -dash => pattern
1122       -disableddash => pattern
1123           This option specifies dash patterns for the normal state, and the
1124           disabled state of a grid item.  pattern may have any of the forms
1125           accepted by Tk_GetDash.  If the dash options are omitted then the
1126           default is a solid outline.
1127
1128       -dashoffset => offset
1129           The starting offset into the pattern provided by the -dash option.
1130           -dashoffset is ignored if there is no -dash pattern.
1131
1132       -color => color
1133       -disabledcolor => color
1134           This option specifies the color that should be used to draw the
1135           outline of the grid in its normal and disabled states.  Color may
1136           have any of the forms accepted by Tk_GetColor.  This option
1137           defaults to black.  If color is undef then no grid will be drawn.
1138
1139       -stipple => bitmap
1140       -disabledstipple => bitmap
1141           This option specifies stipple patterns that should be used to draw
1142           the outline of the rectangle in its normal and disabled states.
1143           bitmap specifies the stipple pattern to use, in any of the forms
1144           accepted by Tk_GetBitmap.  If bitmap is an empty string (the
1145           default), then the outline is drawn in a solid fashion.
1146
1147       -state => state
1148           Modifies the state of the rectangle item where state may be set to
1149           one of: normal, disabled, or hidden. Many options can take separate
1150           specifications in normal and disabled states such that the
1151           appearance of the item can be different in each state.
1152
1153       -tags => tagList
1154           Specifies a set of tags to apply to the item.  TagList consists of
1155           a list of tag names, which replace any existing tags for the item.
1156           TagList may be an empty list.
1157
1158       -updatecommand => command
1159           Specifies a callback that is to be executed every time the grid
1160           item is updated on the screen.
1161
1162       -width => outlineWidth
1163       -disabledwidth => outlineWidth
1164           Specifies the width of the lines drawn by the grid or the size (in
1165           both X and Y) of the dots, in its normal and disabled states.  This
1166           option defaults to 1.0.
1167

IMAGE ITEMS

1169       Items of type image are used to display images on a canvas.  Images are
1170       created with methods of the following form:
1171
1172        $canvas->createImage(x, y, ?option, value, option, value, ...?)
1173
1174       The arguments x and y specify the coordinates of a point used to
1175       position the image on the display (see the -anchor option below for
1176       more information).  After the coordinates there may be any number of
1177       option-value pairs, each of which sets one of the configuration options
1178       for the item.  These same option-value pairs may be used in
1179       itemconfigure methods to change the item's configuration.  The
1180       following options are supported for images:
1181
1182       -anchor => anchorPos
1183           AnchorPos tells how to position the image relative to the
1184           positioning point for the item;  it may have any of the forms
1185           accepted by Tk_GetAnchor.  For example, if anchorPos is center then
1186           the image is centered on the point;  if anchorPos is n then the
1187           image will be drawn so that its top center point is at the
1188           positioning point.  This option defaults to center.
1189
1190       -image => name
1191       -activeimage => name
1192       -disabledimage => name
1193           Specifies the name of the images to display in the item in is
1194           normal, active and disabled states. This image must have been
1195           created previously, see Tk::Image.
1196
1197       -state => state
1198           Modifies the state of the image item where state may be set to one
1199           of: normal, disabled, or hidden.  An image item may also be in the
1200           "active" state if the mouse is currently over it.  Many options can
1201           take separate specifications in normal, active and disabled states
1202           such that the appearance of the item can be different in each
1203           state.
1204
1205       -tags => tagList
1206           Specifies a set of tags to apply to the item.  TagList consists of
1207           a list of tag names, which replace any existing tags for the item;
1208           it may be an empty list.
1209
1210       -updatecommand => command
1211           Specifies a callback that is to be executed every time the image
1212           item is updated on the screen.
1213

LINE ITEMS

1215       Items of type line appear on the display as one or more connected line
1216       segments or curves.  Line items support coordinate indexing operations
1217       using the canvas methods: dchars, index, insert.  Lines are created
1218       with methods of the following form:
1219
1220        $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)
1221
1222       The arguments x1 through yn give the coordinates for a series of two or
1223       more points that describe a series of connected line segments.  After
1224       the coordinates there may be any number of option-value pairs, each of
1225       which sets one of the configuration options for the item.  These same
1226       option-value pairs may be used in itemconfigure methods to change the
1227       item's configuration.  The following options are supported for lines:
1228
1229       -arrow => where
1230           Indicates whether or not arrowheads are to be drawn at one or both
1231           ends of the line.  Where must have one of the values none (for no
1232           arrowheads), first (for an arrowhead at the first point of the
1233           line), last (for an arrowhead at the last point of the line), or
1234           both (for arrowheads at both ends).  This option defaults to none.
1235
1236       -arrowshape => shape
1237           This option indicates how to draw arrowheads.  The shape argument
1238           must be a list with three elements, each specifying a distance in
1239           any of the forms described in the "COORDINATES" section above.  The
1240           first element of the list gives the distance along the line from
1241           the neck of the arrowhead to its tip.  The second element gives the
1242           distance along the line from the trailing points of the arrowhead
1243           to the tip, and the third element gives the distance from the
1244           outside edge of the line to the trailing points.  If this option
1245           isn't specified then Tk picks a ``reasonable'' shape.
1246
1247       -capstyle => style
1248           Specifies the ways in which caps are to be drawn at the endpoints
1249           of the line.  Style may have any of the forms accepted by
1250           Tk_GetCapStyle (butt, projecting, or round).  If this option isn't
1251           specified then it defaults to butt.  Where arrowheads are drawn the
1252           cap style is ignored.
1253
1254       -dash => pattern
1255       -activedash => pattern
1256       -disableddash => pattern
1257           This option specifies dash patterns for the normal state, the
1258           active state, and the disabled state of a line item.  pattern may
1259           have any of the forms accepted by Tk_GetDash.  If the dash options
1260           are omitted then the default is a solid outline.
1261
1262       -dashoffset => offset
1263           The starting offset into the pattern provided by the -dash option.
1264           -dashoffset is ignored if there is no -dash pattern.
1265
1266       -fill => color
1267       -activefill => color
1268       -disabledfill => color
1269           Specifies the color to be used to fill the line in its normal,
1270           active, and disabled states.  Color may have any of the forms
1271           acceptable to Tk_GetColor.  It may also be undef, in which case the
1272           line will be transparent.  This option defaults to black.
1273
1274       -joinstyle => style
1275           Specifies the ways in which joints are to be drawn at the vertices
1276           of the line.  Style may have any of the forms accepted by
1277           Tk_GetCapStyle (bevel, miter, or round).  If this option isn't
1278           specified then it defaults to miter.  If the line only contains two
1279           points then this option is irrelevant.
1280
1281       -smooth => boolean
1282           Boolean must have one of the forms accepted by Tk_GetBoolean.  It
1283           indicates whether or not the line should be drawn as a curve.  If
1284           so, the line is rendered as a set of parabolic splines: one spline
1285           is drawn for the first and second line segments, one for the second
1286           and third, and so on.  Straight-line segments can be generated
1287           within a curve by duplicating the end-points of the desired line
1288           segment.
1289
1290       -splinesteps => number
1291           Specifies the degree of smoothness desired for curves:  each spline
1292           will be approximated with number line segments.  This option is
1293           ignored unless the -smooth option is true.
1294
1295       -state => state
1296           Modifies the state of the line item where state may be set to one
1297           of: normal, disabled, or hidden.  A line item may also be in the
1298           "active" state if the mouse is currently over it.  Many options can
1299           take separate specifications in normal, active and disabled states
1300           such that the appearance of the item can be different in each
1301           state.
1302
1303       -stipple => bitmap
1304       -activestipple => bitmap
1305       -disabledstipple => bitmap
1306           This option specifies stipple patterns that should be used to fill
1307           the the line in its normal, active and disabled states.  bitmap
1308           specifies the stipple pattern to use, in any of the forms accepted
1309           by Tk_GetBitmap.  If bitmap is an empty string (the default), then
1310           filling is done in a solid fashion.
1311
1312       -tags => tagList
1313           Specifies a set of tags to apply to the item.  TagList consists of
1314           a list of tag names, which replace any existing tags for the item.
1315           TagList may be an empty list.
1316
1317       -updatecommand => command
1318           Specifies a callback that is to be executed every time the line
1319           item is updated on the screen.
1320
1321       -width => lineWidth
1322       -activewidth => lineWidth
1323       -disabledwidth => lineWidth
1324           Specifies the width of the line in its normal, active and disabled
1325           states.  lineWidth may be in any of the forms described in the
1326           "COORDINATES" section above.
1327
1328           Wide lines will be drawn centered on the path specified by the
1329           points.  If this option isn't specified then it defaults to 1.0.
1330

OVAL ITEMS

1332       Items of type oval appear as circular or oval regions on the display.
1333       Each oval may have an outline, a fill, or both.  Ovals are created with
1334       methods of the following form:
1335
1336        $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)
1337
1338       The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
1339       opposite corners of a rectangular region enclosing the oval.  The oval
1340       will include the top and left edges of the rectangle not the lower or
1341       right edges.  If the region is square then the resulting oval is
1342       circular; otherwise it is elongated in shape.  After the coordinates
1343       there may be any number of option-value pairs, each of which sets one
1344       of the configuration options for the item.  These same option-value
1345       pairs may be used in itemconfigure methods to change the item's
1346       configuration.  The following options are supported for ovals:
1347
1348       -dash => pattern
1349       -activedash => pattern
1350       -disableddash => pattern
1351           This option specifies dash patterns for the normal state, the
1352           active state, and the disabled state of an oval item.  pattern may
1353           have any of the forms accepted by Tk_GetDash.  If the dash options
1354           are omitted then the default is a solid outline.
1355
1356       -dashoffset => offset
1357           The starting offset into the pattern provided by the -dash option.
1358           -dashoffset is ignored if there is no -dash pattern.
1359
1360       -fill => color
1361       -activefill => color
1362       -disabledfill => color
1363           Specifies the color to be used to fill the oval in its normal,
1364           active, and disabled states.  Color may have any of the forms
1365           accepted by Tk_GetColor.  If color is undef (the default), then
1366           then the oval will not be filled.
1367
1368       -outline => color
1369       -activeoutline => color
1370       -disabledoutline => color
1371           This option specifies the color that should be used to draw the
1372           outline of the oval in its normal, active and disabled states.
1373           Color may have any of the forms accepted by Tk_GetColor.  This
1374           option defaults to black.  If color is undef then no outline will
1375           be drawn for the oval.
1376
1377       -outlinestipple => bitmap
1378       -activeoutlinestipple => bitmap
1379       -disabledoutlinestipple => bitmap
1380           This option specifies stipple patterns that should be used to draw
1381           the outline of the oval in its normal, active and disabled states.
1382           bitmap specifies the stipple pattern to use, in any of the forms
1383           accepted by Tk_GetBitmap.  If the -outline option hasn't been
1384           specified then this option has no effect.  If bitmap is an empty
1385           string (the default), then the outline is drawn in a solid fashion.
1386
1387       -state => state
1388           Modifies the state of the oval item where state may be set to one
1389           of: normal, disabled, or hidden.  An oval item may also be in the
1390           "active" state if the mouse is currently over it.  Many options can
1391           take separate specifications in normal, active and disabled states
1392           such that the appearance of the item can be different in each
1393           state.
1394
1395       -stipple => bitmap
1396       -activestipple => bitmap
1397       -disabledstipple => bitmap
1398           This option specifies stipple patterns that should be used to fill
1399           the the oval in its normal, active and disabled states.  bitmap
1400           specifies the stipple pattern to use, in any of the forms accepted
1401           by Tk_GetBitmap.  If the -fill option hasn't been specified then
1402           this option has no effect.  If bitmap is an empty string (the
1403           default), then filling is done in a solid fashion.
1404
1405       -tags => tagList
1406           Specifies a set of tags to apply to the item.  TagList consists of
1407           a list of tag names, which replace any existing tags for the item.
1408           TagList may be an empty list.
1409
1410       -updatecommand => command
1411           Specifies a callback that is to be executed every time the oval
1412           item is updated on the screen.
1413
1414       -width => outlineWidth
1415       -activewidth => outlineWidth
1416       -disabledwidth => outlineWidth
1417           Specifies the width of the outline to be drawn around the oval, in
1418           its normal, active and disabled states.  outlineWidth specifies the
1419           width of the outline to be drawn around the oval, in any of the
1420           forms described in the "COORDINATES" section above.
1421
1422           If the -outline option hasn't been specified then this option has
1423           no effect.  Wide outlines are drawn centered on the oval path
1424           defined by x1, y1, x2, and y2.  This option defaults to 1.0.
1425

POLYGON ITEMS

1427       Items of type polygon appear as polygonal or curved filled regions on
1428       the display.  Polygon items support coordinate indexing operations
1429       using the canvas methods: dchars, index, insert.  Polygons are created
1430       with methods of the following form:
1431
1432        $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)
1433
1434       The arguments x1 through yn specify the coordinates for three or more
1435       points that define a closed polygon.  The first and last points may be
1436       the same;  whether they are or not, Tk will draw the polygon as a
1437       closed polygon.  After the coordinates there may be any number of
1438       option-value pairs, each of which sets one of the configuration options
1439       for the item.  These same option-value pairs may be used in
1440       itemconfigure methods to change the item's configuration.  The
1441       following options are supported for polygons:
1442
1443       -dash => pattern
1444       -activedash => pattern
1445       -disableddash => pattern
1446           This option specifies dash patterns for the normal state, the
1447           active state, and the disabled state of an polygon item.  pattern
1448           may have any of the forms accepted by Tk_GetDash.  If the dash
1449           options are omitted then the default is a solid outline.
1450
1451       -dashoffset => offset
1452           The starting offset into the pattern provided by the -dash option.
1453           -dashoffset is ignored if there is no -dash pattern.
1454
1455       -fill => color
1456       -activefill => color
1457       -disabledfill => color
1458           Specifies the color to be used to fill the polygon in its normal,
1459           active, and disabled states.  Color may have any of the forms
1460           acceptable to Tk_GetColor.  If color is undef then the polygon will
1461           be transparent.  This option defaults to black.
1462
1463       -joinstyle => style
1464           Specifies the ways in which joints are to be drawn at the vertices
1465           of the outline.  Style may have any of the forms accepted by
1466           Tk_GetCapStyle (bevel, miter, or round).  If this option isn't
1467           specified then it defaults to miter.
1468
1469       -outline => color
1470       -activeoutline => color
1471       -disabledoutline => color
1472           This option specifies the color that should be used to draw the
1473           outline of the polygon in its normal, active and disabled states.
1474           Color may have any of the forms accepted by Tk_GetColor.  If color
1475           is undef then no outline will be drawn for the polygon.  This
1476           option defaults to undef (no outline).
1477
1478       -outlinestipple => bitmap
1479       -activeoutlinestipple => bitmap
1480       -disabledoutlinestipple => bitmap
1481           This option specifies stipple patterns that should be used to draw
1482           the outline of the polygon in its normal, active and disabled
1483           states.  bitmap specifies the stipple pattern to use, in any of the
1484           forms accepted by Tk_GetBitmap.  If the -outline option hasn't been
1485           specified then this option has no effect.  If bitmap is an empty
1486           string (the default), then the outline is drawn in a solid fashion.
1487
1488       -smooth => boolean
1489           Boolean must have one of the forms accepted by Tk_GetBoolean It
1490           indicates whether or not the polygon should be drawn with a curved
1491           perimeter.  If so, the outline of the polygon becomes a set of
1492           parabolic splines, one spline for the first and second line
1493           segments, one for the second and third, and so on.  Straight-line
1494           segments can be generated in a smoothed polygon by duplicating the
1495           end-points of the desired line segment.
1496
1497       -splinesteps => number
1498           Specifies the degree of smoothness desired for curves:  each spline
1499           will be approximated with number line segments.  This option is
1500           ignored unless the -smooth option is true.
1501
1502       -state => state
1503           Modifies the state of the polygon item where state may be set to
1504           one of: normal, disabled, or hidden.  A polygon item may also be in
1505           the "active" state if the mouse is currently over it.  Many options
1506           can take separate specifications in normal, active and disabled
1507           states such that the appearance of the item can be different in
1508           each state.
1509
1510       -stipple => bitmap
1511       -activestipple => bitmap
1512       -disabledstipple => bitmap
1513           This option specifies stipple patterns that should be used to fill
1514           the the polygon in its normal, active and disabled states.  bitmap
1515           specifies the stipple pattern to use, in any of the forms accepted
1516           by Tk_GetBitmap.  If bitmap is an empty string (the default), then
1517           filling is done in a solid fashion.
1518
1519       -tags => tagList
1520           Specifies a set of tags to apply to the item.  TagList consists of
1521           a list of tag names, which replace any existing tags for the item.
1522           TagList may be an empty list.
1523
1524       -updatecommand => command
1525           Specifies a callback that is to be executed every time the polygon
1526           item is updated on the screen.
1527
1528       -width => outlineWidth
1529       -activewidth => outlineWidth
1530       -disabledwidth => outlineWidth
1531       Specifies the width of the outline to be drawn around
1532           the polygon, in its normal, active and disabled states.
1533           outlineWidth may be in any of the forms described in the
1534           COORDINATES section above.  OutlineWidth specifies the width of the
1535           outline to be drawn around the polygon, in any of the forms
1536           described in the "COORDINATES" section above.  If the -outline
1537           option hasn't been specified then this option has no effect.  This
1538           option defaults to 1.0.
1539
1540           Polygon items are different from other items such as rectangles,
1541           ovals and arcs in that interior points are considered to be
1542           ``inside'' a polygon (e.g. for purposes of the find closest and
1543           find overlapping methods) even if it is not filled.  For most other
1544           item types, an interior point is considered to be inside the item
1545           only if the item is filled or if it has neither a fill nor an
1546           outline.  If you would like an unfilled polygon whose interior
1547           points are not considered to be inside the polygon, use a line item
1548           instead.
1549

RECTANGLE ITEMS

1551       Items of type rectangle appear as rectangular regions on the display.
1552       Each rectangle may have an outline, a fill, or both.  Rectangles are
1553       created with methods of the following form:
1554
1555        $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)
1556
1557       The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
1558       opposite corners of the rectangle (the rectangle will include its upper
1559       and left edges but not its lower or right edges).  After the
1560       coordinates there may be any number of option-value pairs, each of
1561       which sets one of the configuration options for the item.  These same
1562       option-value pairs may be used in itemconfigure methods to change the
1563       item's configuration.  The following options are supported for
1564       rectangles:
1565
1566       -dash => pattern
1567       -activedash => pattern
1568       -disableddash => pattern
1569           This option specifies dash patterns for the normal state, the
1570           active state, and the disabled state of a rectangle item.  pattern
1571           may have any of the forms accepted by Tk_GetDash.  If the dash
1572           options are omitted then the default is a solid outline.
1573
1574       -dashoffset => offset
1575           The starting offset into the pattern provided by the -dash option.
1576           -dashoffset is ignored if there is no -dash pattern.
1577
1578       -fill => color
1579       -activefill => color
1580       -disabledfill => color
1581           Specifies the color to be used to fill the rectangle in its normal,
1582           active, and disabled states.  Color may be specified in any of the
1583           forms accepted by Tk_GetColor.  If color is undef (the default),
1584           then the rectangle will not be filled.
1585
1586       -outline => color
1587       -activeoutline => color
1588       -disabledoutline => color
1589           This option specifies the color that should be used to draw the
1590           outline of the rectangle in its normal, active and disabled states.
1591           Color may have any of the forms accepted by Tk_GetColor.  This
1592           option defaults to black.  If color is undef then no outline will
1593           be drawn for the rectangle.
1594
1595       -outlinestipple => bitmap
1596       -activeoutlinestipple => bitmap
1597       -disabledoutlinestipple => bitmap
1598           This option specifies stipple patterns that should be used to draw
1599           the outline of the rectangle in its normal, active and disabled
1600           states.  bitmap specifies the stipple pattern to use, in any of the
1601           forms accepted by Tk_GetBitmap.  If the -outline option hasn't been
1602           specified then this option has no effect.  If bitmap is an empty
1603           string (the default), then the outline is drawn in a solid fashion.
1604
1605       -state => state
1606           Modifies the state of the rectangle item where state may be set to
1607           one of: normal, disabled, or hidden.  A rectangle item may also be
1608           in the "active" state if the mouse is currently over it.  Many
1609           options can take separate specifications in normal, active and
1610           disabled states such that the appearance of the item can be
1611           different in each state.
1612
1613       -stipple => bitmap
1614       -activestipple => bitmap
1615       -disabledstipple => bitmap
1616           This option specifies stipple patterns that should be used to fill
1617           the the rectangle in its normal, active and disabled states.
1618           bitmap specifies the stipple pattern to use, in any of the forms
1619           accepted by Tk_GetBitmap.  If the -fill option hasn't been
1620           specified then this option has no effect.  If bitmap is an empty
1621           string (the default), then filling is done in a solid fashion.
1622
1623       -tags => tagList
1624           Specifies a set of tags to apply to the item.  TagList consists of
1625           a list of tag names, which replace any existing tags for the item.
1626           TagList may be an empty list.
1627
1628       -updatecommand => command
1629           Specifies a callback that is to be executed every time the
1630           rectangle item is updated on the screen.
1631
1632       -width => outlineWidth
1633       -activewidth => outlineWidth
1634       -disabledwidth => outlineWidth
1635           Specifies the width of the outline to be drawn around the
1636           rectangle, in its normal, active and disabled states.  OutlineWidth
1637           specifies the width of the outline to be drawn around the
1638           rectangle, in any of the forms described in the "COORDINATES"
1639           section above.
1640
1641           If the -outline option hasn't been specified then this option has
1642           no effect.  Wide outlines are drawn centered on the rectangular
1643           path defined by x1, y1, x2, and y2.  This option defaults to 1.0.
1644

TEXT ITEMS

1646       A text item displays a string of characters on the screen in one or
1647       more lines.  Text items support indexing and selection, along with the
1648       following text-related canvas methods:  dchars, focus, icursor, index,
1649       insert, select.  Text items are created with methods of the following
1650       form:
1651
1652        $canvas->createText(x, y, ?option, value, option, value, ...?)
1653
1654       The arguments x and y specify the coordinates of a point used to
1655       position the text on the display (see the options below for more
1656       information on how text is displayed).  After the coordinates there may
1657       be any number of option-value pairs, each of which sets one of the
1658       configuration options for the item.  These same option-value pairs may
1659       be used in itemconfigure methods to change the item's configuration.
1660       The following options are supported for text items:
1661
1662       -anchor => anchorPos
1663           AnchorPos tells how to position the text relative to the
1664           positioning point for the text;  it may have any of the forms
1665           accepted by Tk_GetAnchor.  For example, if anchorPos is center then
1666           the text is centered on the point;  if anchorPos is n then the text
1667           will be drawn such that the top center point of the rectangular
1668           region occupied by the text will be at the positioning point.  This
1669           option defaults to center.
1670
1671       -fill => color
1672       -activefill => color
1673       -disabledfill => color
1674           Specifies the color to be used to fill the text in its normal,
1675           active, and disabled states.  Color may have any of the forms
1676           accepted by Tk_GetColor.  If color is undef then the text will be
1677           transparent.  If this option isn't specified then it defaults to
1678           black.
1679
1680       -font => fontName
1681           Specifies the font to use for the text item.  FontName may be any
1682           string acceptable to Tk_GetFontStruct.  If this option isn't
1683           specified, it defaults to a system-dependent font.
1684
1685       -justify => how
1686           Specifies how to justify the text within its bounding region.  How
1687           must be one of the values left, right, or center.  This option will
1688           only matter if the text is displayed as multiple lines.  If the
1689           option is omitted, it defaults to left.
1690
1691       -state => state
1692           Modifies the state of the text item where state may be set to one
1693           of: normal, disabled, or hidden.  A text item may also be in the
1694           "active" state if the mouse is currently over it.  Many options can
1695           take separate specifications in normal, active and disabled states
1696           such that the appearance of the item can be different in each
1697           state.
1698
1699       -stipple => bitmap
1700       -activestipple => bitmap
1701       -disabledstipple => bitmap
1702           This option specifies stipple patterns that should be used to fill
1703           the the text in its normal, active and disabled states.  bitmap
1704           specifies the stipple pattern to use, in any of the forms accepted
1705           by Tk_GetBitmap.  If bitmap is an empty string (the default) then
1706           the text is drawn in a solid fashion.
1707
1708       -tags => tagList
1709           Specifies a set of tags to apply to the item.  TagList consists of
1710           a list of tag names, which replace any existing tags for the item.
1711           TagList may be an empty list.
1712
1713       -text => string
1714           String specifies the characters to be displayed in the text item.
1715           Newline characters cause line breaks.  The characters in the item
1716           may also be changed with the insert and delete methods.  This
1717           option defaults to an empty string.
1718
1719       -updatecommand => command
1720           Specifies a callback that is to be executed every time the text
1721           item is updated on the screen.
1722
1723       -width => lineLength
1724           Specifies a maximum line length for the text, in any of the forms
1725           described in the "COORDINATES" section above.  If this option is
1726           zero (the default) the text is broken into lines only at newline
1727           characters.  However, if this option is non-zero then any line that
1728           would be longer than lineLength is broken just before a space
1729           character to make the line shorter than lineLength;  the space
1730           character is treated as if it were a newline character.
1731

WINDOW ITEMS

1733       Items of type window cause a particular window to be displayed at a
1734       given position on the canvas.  Window items are created with methods of
1735       the following form:
1736
1737           $canvas->createWindow(x, y?, -option=>value, -option=>value, ...?)
1738
1739       The arguments x and y specify the coordinates of a point used to
1740       position the window on the display (see the -anchor option below for
1741       more information on how bitmaps are displayed).  After the coordinates
1742       there may be any number of option-value pairs, each of which sets one
1743       of the configuration options for the item.  These same option-value
1744       pairs may be used in itemconfigure method to change the item's
1745       configuration.  The following options are supported for window items:
1746
1747       -anchor => anchorPos
1748           AnchorPos tells how to position the window relative to the
1749           positioning point for the item;  it may have any of the forms
1750           accepted by Tk_GetAnchor.  For example, if anchorPos is center then
1751           the window is centered on the point;  if anchorPos is n then the
1752           window will be drawn so that its top center point is at the
1753           positioning point.  This option defaults to center.
1754
1755       -height => pixels
1756           Specifies the height to assign to the item's window.  Pixels may
1757           have any of the forms described in the "COORDINATES" section above.
1758           If this option isn't specified, or if it is specified as an empty
1759           string, then the window is given whatever height it requests
1760           internally.
1761
1762       -state => state
1763           Modifies the state of the window item where state may be set to one
1764           of: normal, disabled, or hidden.
1765
1766       -tags => tagList
1767           Specifies a set of tags to apply to the item.  TagList consists of
1768           a list of tag names, which replace any existing tags for the item.
1769           TagList may be an empty list.
1770
1771       -updatecommand => command
1772           Specifies a callback that is to be executed every time the window
1773           item is updated on the screen.
1774
1775       -width => pixels
1776           Specifies the width to assign to the item's window.  Pixels may
1777           have any of the forms described in the "COORDINATES" section above.
1778           If this option isn't specified, or if it is specified as an empty
1779           string, then the window is given whatever width it requests
1780           internally.
1781
1782       -window => $widget
1783           Specifies the window to associate with this item.  The window
1784           specified by $widget must either be a child of the canvas widget or
1785           a child of some ancestor of the canvas widget.  PathName may not
1786           refer to a top-level window.
1787
1788           Note:  due to restrictions in the ways that windows are managed, it
1789           is not possible to draw other graphical items (such as lines and
1790           images) on top of window items.  A window item always obscures any
1791           graphics that overlap it, regardless of their order in the display
1792           list.
1793

APPLICATION-DEFINED ITEM TYPES

1795       It is possible for individual applications to define new item types for
1796       canvas widgets using C code.  See the documentation for
1797       Tk_CreateItemType.
1798

BINDINGS

1800       Canvas has default bindings to allow scrolling if necessary: <Up>,
1801       <Down>, <Left> and <Right> (and their <Control-*> counter parts).
1802       Further <Proir>, <Next>, <Home> and <End>.  These bindings allow you to
1803       navigate the same way as in other widgets that can scroll.
1804

Perl/Tk Methods

1806       The following methods are added as perl code:
1807
1808       $canvas->get_corners
1809           Returns the bounding box in Canvas coordinates of the visible
1810           portion of the Canvas. (Written by Slaven Rezic.)
1811

CREDITS

1813       Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
1814       ezd program.  Ezd provides structured graphics in a Scheme environment
1815       and preceded canvases by a year or two.  Its simple mechanisms for
1816       placing and animating graphical objects inspired the functions of
1817       canvases.
1818

KEYWORDS

1820       canvas, widget
1821
1822
1823
1824perl v5.36.0                      2022-07-22                         Canvas(3)
Impressum