1Canvas(3) User Contributed Perl Documentation Canvas(3)
2
6 Tk::Canvas - Create and manipulate Canvas widgets
7
9 $canvas = $parent->Canvas(?options?);
10
12 -background -highlightthickness -insertwidth -state -border‐
13 width -insertbackground -relief -tile -cursor -insertborder‐
14 width -selectbackground -takefocus -highlightback‐
15 ground -insertofftime -selectborderwidth -xscrollcommand -high‐
16 lightcolor -insertontime -selectforeground -yscrollcommand
17
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 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 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 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 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 appear‐
58 ance of the item can be different in different situations. The
59 options that start with "active" control the appearence when the
60 mouse pointer is over it, while the option starting with "disabled"
61 controls the appearence when the state is disabled.
62 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 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; fur‐
78 thermore, 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 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 con‐
89 strained so that the canvas y coordinate at the top edge of the
90 window is always an even multiple of yScrollIncrement; further‐
91 more, the units for scrolling (e.g., the change in view when the
92 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
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 com‐
102 mand is invoked, there must not exist a window named $canvas, but $can‐
103 vas's parent must exist.
104 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 behav‐
113 iors defined by the Callbacks bound to them.
114
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 every‐
122 thing else. Widget methods may be used to re-arrange the order of the
123 display list.
124 Window items are an exception to the above rules. The underlying win‐
126 dow systems require them always to be drawn on top of other items. In
127 addition, the stacking order of window items is not affected by any of
128 the canvas methods; you must use the raise and lower Tk widget methods
129 instead.
130
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 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 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 The tag current is managed automatically by Tk; it applies to the cur‐
148 rent item, which is the topmost item whose drawn area covers the posi‐
149 tion of the mouse cursor. If the mouse is not in the canvas widget or
150 is not over an item, then no item has the current tag.
151 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 tagOrId may contain a logical expressions of tags by using operators:
160 '&&', '⎪⎪', '^' '!', and parenthezised subexpressions. For example:
161 $c->find('withtag', '(a&&!b)⎪(!a&&b)');
163 or equivalently:
165 $c->find('withtag', 'a^b');
167 will find only those items with either "a" or "b" tags, but not both.
169 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
177 All coordinates related to canvases are stored as floating-point num‐
178 bers. Coordinates and distances are specified in screen units, which
179 are floating-point numbers optionally followed by one of several let‐
180 ters. If no letter is supplied then the distance is in pixels. If the
181 letter is m then the distance is in millimeters on the screen; if it
182 is c then the distance is in centimeters; i means inches, and p means
183 printers points (1/72 inch). Larger y-coordinates refer to points
184 lower on the screen; larger x-coordinates refer to points farther to
185 the right.
186
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 ori‐
191 gin of the window using the xview and yview methods; this is typically
192 used for scrolling. Canvases do not support scaling or rotation of the
193 canvas coordinate system relative to the window coordinate system.
194 Individual items may be moved or scaled using methods described below,
196 but they may not be rotated.
197
199 Text items support the notion of an index for identifying particular
200 positions within the item.
201 Indices are used for methods such as inserting text, deleting a range
203 of characters, and setting the insertion cursor position. An index may
204 be specified in any of a number of ways, and different types of items
205 may support different forms for specifying indices.
206 In a similar fashion, line and polygon items support index for identi‐
208 fying, inserting and deleting subsets of their coordinates. Indices
209 are used for commands such as inserting or deleting a range of charac‐
210 ters or coordinates, and setting the insertion cursor position. An
211 index may be specified in any of a number of ways, and different types
212 of items may support different forms for specifying indices.
213 Text items support the following forms for an index; if you define new
215 types of text-like items, it would be advisable to support as many of
216 these forms as practical. Note that it is possible to refer to the
217 character just after the last one in the text item; this is necessary
218 for such tasks as inserting new text at the end of the item. Lines and
219 Polygons don't support the insertion cursor and the selection. Their
220 indices are supposed to be even always, because coordinates always
221 appear in pairs.
222 number
224 A decimal number giving the position of the desired character
225 within the text item. 0 refers to the first character, 1 to the
226 next character, and so on. If indexes are odd for lines and poly‐
227 gons, they will be automatically decremented by one. A number less
228 than 0 is treated as if it were zero, and a number greater than the
229 length of the text item is treated as if it were equal to the
230 length of the text item. For polygons, numbers less than 0 or
231 greater then the length of the coordinate list will be adjusted by
232 adding or substracting the length until the result is between zero
233 and the length, inclusive.
234 end Refers to the character or coordinate just after the last one in
236 the item (same as the number of characters or coordinates in the
237 item).
238 insert
240 Refers to the character just before which the insertion cursor is
241 drawn in this item. Not valid for lines and polygons.
242 sel.first
244 Refers to the first selected character in the item. If the selec‐
245 tion isn't in this item then this form is illegal.
246 sel.last
248 Refers to the last selected character in the item. If the selec‐
249 tion isn't in this item then this form is illegal.
250 [x,y]
252 Refers to the character or coordinate at the point given by x and
253 y, where x and y are specified in the coordinate system of the can‐
254 vas. If x and y lie outside the coordinates covered by the text
255 item, then they refer to the first or last character in the line
256 that is closest to the given point. The Tcl string form "@x,y" is
257 also allowed.
258
260 Many items support the notion of an dash pattern for outlines.
261 The first possible syntax is a list of integers. Each element repre‐
263 sents the number of pixels of a line segment. Only the odd segments are
264 drawn using the "outline" color. The other segments are drawn transpar‐
265 ent.
266 The second possible syntax is a character list containing only 5 possi‐
268 ble characters [.,-_ ], with the first 4 characters producing a seg‐
269 ment of length 1 to 4, respectively, followed by a transparent segment
270 of length 2. The space can be used repeatedly to enlarge the space
271 between other line elements by 1, and can not occur as the first posi‐
272 tion in the string. The main difference of this syntax with the previ‐
273 ous one is that it it shape-conserving. This means that all values in
274 the dash list will be multiplied by the line width before display. This
275 assures that "." will always be displayed as a dot and "-" always as a
276 dash regardless of the line width.
277 Some examples, for a line width of 2:
279 -dash . = -dash [2,4]
281 -dash - = -dash [6,4]
282 -dash -. = -dash [6,4,2,4]
283 -dash -.. = -dash [6,4,2,4,2,4]
284 -dash '. ' = -dash [2,8]
285 -dash ',' = -dash [4,4]
286 On systems where only a limited set of dash patterns is available, the
288 dash pattern will be displayed as the closest available dash pattern.
289 For example, on Windows only the first 4 of the above examples are
290 available. The last 2 examples will be displayed identically as the
291 first one.
292
294 The Canvas method creates a widget object. This object supports the
295 configure and cget methods described in Tk::options which can be used
296 to enquire and modify the options described above. The widget also
297 inherits all the methods provided by the generic Tk::Widget class.
298 The following additional methods are available for canvas widgets:
300 $canvas->addtag(tag, searchSpec, ?arg, arg, ...?)
302 For each item that meets the constraints specified by searchSpec
303 and the args, add tag to the list of tags associated with the item
304 if it isn't already present on that list. It is possible that no
305 items will satisfy the constraints given by searchSpec and args, in
306 which case the method has no effect. This command returns an empty
307 string as result. SearchSpec and arg's may take any of the follow‐
308 ing forms:
309 above tagOrId
311 Selects the item just after (above) the one given by
312 tagOrId in the display list. If tagOrId denotes more than
313 one item, then the last (topmost) of these items in the
314 display list is used.
315 all Selects all the items in the canvas.
317 below tagOrId
319 Selects the item just before (below) the one given by
320 tagOrId in the display list. If tagOrId denotes more than
321 one item, then the first (lowest) of these items in the
322 display list is used.
323 closest x y ?halo? ?start?
325 Selects the item closest to the point given by x and y. If
326 more than one item is at the same closest distance (e.g.
327 two items overlap the point), then the top-most of these
328 items (the last one in the display list) is used. If halo
329 is specified, then it must be a non-negative value. Any
330 item closer than halo to the point is considered to overlap
331 it. The start argument may be used to step circularly
332 through all the closest items. If start is specified, it
333 names an item using a tag or id (if by tag, it selects the
334 first item in the display list with the given tag).
335 Instead of selecting the topmost closest item, this form
336 will select the topmost closest item that is below start in
337 the display list; if no such item exists, then the selec‐
338 tion behaves as if the start argument had not been speci‐
339 fied.
340 enclosed x1 y1 x2 y2
342 Selects all the items completely enclosed within the rec‐
343 tangular region given by x1, y1, x2, and y2. X1 must be no
344 greater then x2 and y1 must be no greater than y2.
345 overlapping x1 y1 x2 y2
347 Selects all the items that overlap or are enclosed within
348 the rectangular region given by x1, y1, x2, and y2. X1
349 must be no greater then x2 and y1 must be no greater than
350 y2.
351 withtag tagOrId
353 Selects all the items given by tagOrId.
354 $canvas->bbox(tagOrId, ?tagOrId, tagOrId, ...?)
356 Returns a list with four elements giving an approximate bounding
357 box for all the items named by the tagOrId arguments. The list has
358 the form ``x1 y1 x2 y2'' such that the drawn areas of all the named
359 elements are within the region bounded by x1 on the left, x2 on the
360 right, y1 on the top, and y2 on the bottom. The return value may
361 overestimate the actual bounding box by a few pixels. If no items
362 match any of the tagOrId arguments or if the matching items have
363 empty bounding boxes (i.e. they have nothing to display) then an
364 empty string is returned.
365 $canvas->bind(tagOrId?, sequence? ?,callback?)
367 This method associates callback with all the items given by tagOrId
368 such that whenever the event sequence given by sequence occurs for
369 one of the items the callback will be invoked. This method is sim‐
370 ilar to the bind method except that it operates on items in a can‐
371 vas rather than entire widgets. See Tk::bind for complete details
372 on the syntax of sequence and the substitutions performed on call‐
373 back before invoking it. If all arguments are specified then a new
374 binding is created, replacing any existing binding for the same
375 sequence and tagOrId (if the first character of command is ``+''
376 then command augments an existing binding rather than replacing
377 it). In this case the return value is an empty string. If call‐
378 back is omitted then the method returns the callback associated
379 with tagOrId and sequence (an error occurs if there is no such
380 binding). If both callback and sequence are omitted then the
381 method returns a list of all the sequences for which bindings have
382 been defined for tagOrId.
383 The only events for which bindings may be specified are
385 those related to the mouse and keyboard (such as Enter,
386 Leave, ButtonPress, Motion, and KeyPress) or virtual
387 events. The handling of events in canvases uses the cur‐
388 rent item defined in "ITEM IDS AND TAGS" above. Enter and
389 Leave events trigger for an item when it becomes the cur‐
390 rent item or ceases to be the current item; note that these
391 events are different than Enter and Leave events for win‐
392 dows. Mouse-related events are directed to the current
393 item, if any. Keyboard-related events are directed to the
394 focus item, if any (see the focus method below for more on
395 this). If a virtual event is used in a binding, that bind‐
396 ing can trigger only if the virtual event is defined by an
397 underlying mouse-related or keyboard-related event.
398 It is possible for multiple bindings to match a particular
400 event. This could occur, for example, if one binding is
401 associated with the item's id and another is associated
402 with one of the item's tags. When this occurs, all of the
403 matching bindings are invoked. A binding associated with
404 the all tag is invoked first, followed by one binding for
405 each of the item's tags (in order), followed by a binding
406 associated with the item's id. If there are multiple
407 matching bindings for a single tag, then only the most spe‐
408 cific binding is invoked. A continue in a callback termi‐
409 nates that subroutine, and a break method terminates that
410 subroutine and skips any remaining callbacks for the event,
411 just as for the bind method.
412 If bindings have been created for a canvas window using the
414 CanvasBind method, then they are invoked in addition to
415 bindings created for the canvas's items using the bind
416 method. The bindings for items will be invoked before any
417 of the bindings for the window as a whole.
418 $canvas->canvasx(screenx?, gridspacing?)
420 Given a window x-coordinate in the canvas screenx, this method
421 returns the canvas x-coordinate that is displayed at that location.
422 If gridspacing is specified, then the canvas coordinate is rounded
423 to the nearest multiple of gridspacing units.
424 $canvas->canvasy(screeny, ?gridspacing?)
426 Given a window y-coordinate in the canvas screeny this method
427 returns the canvas y-coordinate that is displayed at that location.
428 If gridspacing is specified, then the canvas coordinate is rounded
429 to the nearest multiple of gridspacing units.
430 $canvas->coords(tagOrId ?x0,y0 ...?)
432 Query or modify the coordinates that define an item. If no coordi‐
433 nates are specified, this method returns a list whose elements are
434 the coordinates of the item named by tagOrId. If coordinates are
435 specified, then they replace the current coordinates for the named
436 item. If tagOrId refers to multiple items, then the first one in
437 the display list is used.
438 $canvas->create(type, x, y, ?x, y, ...?, ?option, value, ...?)
440 Create a new item in $canvas of type type. The exact format of the
441 arguments after type depends on type, but usually they consist of
442 the coordinates for one or more points, followed by specifications
443 for zero or more item options. See the subsections on individual
444 item types below for more on the syntax of this method. This
445 method returns the id for the new item.
446 $canvas->dchars(tagOrId, first, ?last?)
448 For each item given by tagOrId, delete the characters, or coordi‐
449 nates, in the range given by first and last, inclusive. If some of
450 the items given by tagOrId don't support Text items interpret first
451 and last as indices to a character, line and polygon items inter‐
452 pret them indices to a coordinate (an x,y pair). within the
453 item(s) as described in "INDICES" above. If last is omitted, it
454 defaults to first. This method returns an empty string.
455 $canvas->delete(?tagOrId, tagOrId, ...?)
457 Delete each of the items given by each tagOrId, and return an empty
458 string.
459 $canvas->dtag(tagOrId, ?tagToDelete?)
461 For each of the items given by tagOrId, delete the tag given by
462 tagToDelete from the list of those associated with the item. If an
463 item doesn't have the tag tagToDelete then the item is unaffected
464 by the method. If tagToDelete is omitted then it defaults to
465 tagOrId. This method returns an empty string.
466 $canvas->find(searchCommand, ?arg, arg, ...?)
468 This method returns a list consisting of all the items that meet
469 the constraints specified by searchCommand and arg's. SearchCom‐
470 mand and args have any of the forms accepted by the addtag method.
471 The items are returned in stacking order, with the lowest item
472 first.
473 focus
475 $canvas->focus(?tagOrId?)
476 Set the keyboard focus for the canvas widget to the item given by
477 tagOrId. If tagOrId refers to several items, then the focus is set
478 to the first such item in the display list that supports the inser‐
479 tion cursor. If tagOrId doesn't refer to any items, or if none of
480 them support the insertion cursor, then the focus isn't changed.
481 If tagOrId is an empty string, then the focus item is reset so that
482 no item has the focus. If tagOrId is not specified then the method
483 returns the id for the item that currently has the focus, or an
484 empty string if no item has the focus.
485 Once the focus has been set to an item, the item will dis‐
487 play the insertion cursor and all keyboard events will be
488 directed to that item. The focus item within a canvas and
489 the focus window on the screen (set with the focus method)
490 are totally independent: a given item doesn't actually have
491 the input focus unless (a) its canvas is the focus window
492 and (b) the item is the focus item within the canvas. In
493 most cases it is advisable to follow the focus widget
494 method with the CanvasFocus method to set the focus window
495 to the canvas (if it wasn't there already).
496 $canvas->gettags(tagOrId)
498 Return a list whose elements are the tags associated with the item
499 given by tagOrId. If tagOrId refers to more than one item, then
500 the tags are returned from the first such item in the display list.
501 If tagOrId doesn't refer to any items, or if the item contains no
502 tags, then an empty string is returned.
503 $canvas->icursor(tagOrId, index)
505 Set the position of the insertion cursor for the item(s) given by
506 tagOrId to just before the character whose position is given by
507 index. If some or all of the items given by tagOrId don't support
508 an insertion cursor then this method has no effect on them. See
509 "INDICES" above for a description of the legal forms for index.
510 Note: the insertion cursor is only displayed in an item if that
511 item currently has the keyboard focus (see the widget method focus,
512 below), but the cursor position may be set even when the item
513 doesn't have the focus. This method returns an empty string.
514 $canvas->index(tagOrId, index)
516 This method returns a decimal string giving the numerical index
517 within tagOrId corresponding to index. Index gives a textual
518 description of the desired position as described in "INDICES"
519 above. Text items interpret index as an index to a character,
520 line and polygon items interpret it as an index to a coordinate (an
521 x,y pair). The return value is guaranteed to lie between 0 and the
522 number of characters, or coordinates, within the item, inclusive.
523 If tagOrId refers to multiple items, then the index is processed in
524 the first of these items that supports indexing operations (in dis‐
525 play list order).
526 $canvas->insert(tagOrId, beforeThis, string)
528 For each of the items given by tagOrId, if the item supports text
529 or coordinate, insertion then string is inserted into the item's
530 text just before the character, or coordinate, whose index is
531 beforeThis. Text items interpret beforethis as an index to a
532 character, line and polygon items interpret it as an index to a
533 coordinate (an x,y pair). For lines and polygons the string must
534 be a valid coordinate sequence. See "INDICES" above for informa‐
535 tion about the forms allowed for beforeThis. This method returns
536 an empty string.
537 $canvas->itemcget(tagOrId, option)
539 Returns the current value of the configuration option for the item
540 given by tagOrId whose name is option. This method is similar to
541 the cget method except that it applies to a particular item rather
542 than the widget as a whole. Option may have any of the values
543 accepted by the create method when the item was created. If
544 tagOrId is a tag that refers to more than one item, the first (low‐
545 est) such item is used.
546 $canvas->itemconfigure(tagOrId, ?option?, ?value?, ?option, value,
548 ...?)
549 This method is similar to the configure method except that it modi‐
550 fies item-specific options for the items given by tagOrId instead
551 of modifying options for the overall canvas widget. If no option
552 is specified, returns a list describing all of the available
553 options for the first item given by tagOrId (see Tk::options for
554 information on the format of this list). If option is specified
555 with no value, then the method returns a list describing the one
556 named option (this list will be identical to the corresponding sub‐
557 list of the value returned if no option is specified). If one or
558 more option-value pairs are specified, then the method modifies the
559 given widget option(s) to have the given value(s) in each of the
560 items given by tagOrId; in this case the method returns an empty
561 string. The options and values are the same as those permissible
562 in the create method when the item(s) were created; see the sec‐
563 tions describing individual item types below for details on the
564 legal options.
565 $canvas->lower(tagOrId, ?belowThis?)
567 Move all of the items given by tagOrId to a new position in the
568 display list just before the item given by belowThis. If tagOrId
569 refers to more than one item then all are moved but the relative
570 order of the moved items will not be changed. BelowThis is a tag
571 or id; if it refers to more than one item then the first (lowest)
572 of these items in the display list is used as the destination loca‐
573 tion for the moved items. Note: this method has no effect on win‐
574 dow items. Window items always obscure other item types, and the
575 stacking order of window items is determined by the raise and lower
576 methods of the widget, not the raise and lower methods for can‐
577 vases. This method returns an empty string.
578 $canvas->move(tagOrId, xAmount, yAmount)
580 Move each of the items given by tagOrId in the canvas coordinate
581 space by adding xAmount to the x-coordinate of each point associ‐
582 ated with the item and yAmount to the y-coordinate of each point
583 associated with the item. This method returns an empty string.
584 $canvas->postscript(?option, value, option, value, ...?)
586 Generate a Postscript representation for part or all of the canvas.
587 If the -file option is specified then the Postscript is written to
588 a file and an empty string is returned; otherwise the Postscript
589 is returned as the result of the method. If the interpreter that
590 owns the canvas is marked as safe, the operation will fail because
591 safe interpreters are not allowed to write files. If the -channel
592 option is specified, the argument denotes the name of a channel
593 already opened for writing. The Postscript is written to that chan‐
594 nel, and the channel is left open for further writing at the end of
595 the operation. The Postscript is created in Encapsulated Post‐
596 script form using version 3.0 of the Document Structuring Conven‐
597 tions. Note: by default Postscript is only generated for informa‐
598 tion that appears in the canvas's window on the screen. If the
599 canvas is freshly created it may still have its initial size of 1x1
600 pixel so nothing will appear in the Postscript. To get around this
601 problem either invoke the update method to wait for the canvas win‐
602 dow to reach its final size, or else use the -width and -height
603 options to specify the area of the canvas to print. The
604 option-value argument pairs provide additional information to con‐
605 trol the generation of Postscript. The following options are sup‐
606 ported:
607 -colormap => hashRef
609 HashRef must be a reference to a hash variable or an anony‐
610 mous hash that specifies a color mapping to use in the
611 Postscript. Each value of the hash must consist of Post‐
612 script code to set a particular color value (e.g. ``1.0 1.0
613 0.0 setrgbcolor''). When outputting color information in
614 the Postscript, Tk checks to see if there is a key in the
615 hash with the same name as the color. If so, Tk uses the
616 value of the element as the Postscript method to set the
617 color. If this option hasn't been specified, or if there
618 isn't a key in hashRef for a given color, then Tk uses the
619 red, green, and blue intensities from the X color.
620 -colormode => mode
622 Specifies how to output color information. Mode must be
623 either color (for full color output), gray (convert all
624 colors to their gray-scale equivalents) or mono (convert
625 all colors to black or white).
626 -file => fileName
628 Specifies the name of the file in which to write the Post‐
629 script. If this option isn't specified then the Postscript
630 is returned as the result of the method instead of being
631 written to a file.
632 -fontmap => hashRef
634 HashRef must be a reference to a hash variable or an anony‐
635 mous hash that specifies a font mapping to use in the Post‐
636 script. Each value of the hash must consist of an array
637 reference with two elements, which are the name and point
638 size of a Postscript font. When outputting Postscript com‐
639 mands for a particular font, Tk checks to see if hashRef
640 contains a value with the same name as the font. If there
641 is such an element, then the font information contained in
642 that element is used in the Postscript. Otherwise Tk
643 attempts to guess what Postscript font to use. Tk's
644 guesses generally only work for well-known fonts such as
645 Times and Helvetica and Courier, and only if the X font
646 name does not omit any dashes up through the point size.
647 For example, -*-Courier-Bold-R-Normal--*-120-* will work
648 but *Courier-Bold-R-Normal*120* will not; Tk needs the
649 dashes to parse the font name).
650 -height => size
652 Specifies the height of the area of the canvas to print.
653 Defaults to the height of the canvas window.
654 -pageanchor => anchor
656 Specifies which point of the printed area of the canvas
657 should appear over the positioning point on the page (which
658 is given by the -pagex and -pagey options). For example,
659 -pageanchor=>n means that the top center of the area of the
660 canvas being printed (as it appears in the canvas window)
661 should be over the positioning point. Defaults to center.
662 -pageheight => size
664 Specifies that the Postscript should be scaled in both x
665 and y so that the printed area is size high on the Post‐
666 script page. Size consists of a floating-point number fol‐
667 lowed by c for centimeters, i for inches, m for millime‐
668 ters, or p or nothing for printer's points (1/72 inch).
669 Defaults to the height of the printed area on the screen.
670 If both -pageheight and -pagewidth are specified then the
671 scale factor from -pagewidth is used (non-uniform scaling
672 is not implemented).
673 -pagewidth => size
675 Specifies that the Postscript should be scaled in both x
676 and y so that the printed area is size wide on the Post‐
677 script page. Size has the same form as for -pageheight.
678 Defaults to the width of the printed area on the screen.
679 If both -pageheight and -pagewidth are specified then the
680 scale factor from -pagewidth is used (non-uniform scaling
681 is not implemented).
682 -pagex => position
684 Position gives the x-coordinate of the positioning point on
685 the Postscript page, using any of the forms allowed for
686 -pageheight. Used in conjunction with the -pagey and
687 -pageanchor options to determine where the printed area
688 appears on the Postscript page. Defaults to the center of
689 the page.
690 -pagey => position
692 Position gives the y-coordinate of the positioning point on
693 the Postscript page, using any of the forms allowed for
694 -pageheight. Used in conjunction with the -pagex and
695 -pageanchor options to determine where the printed area
696 appears on the Postscript page. Defaults to the center of
697 the page.
698 -rotate => boolean
700 Boolean specifies whether the printed area is to be rotated
701 90 degrees. In non-rotated output the x-axis of the
702 printed area runs along the short dimension of the page
703 (``portrait'' orientation); in rotated output the x-axis
704 runs along the long dimension of the page (``landscape''
705 orientation). Defaults to non-rotated.
706 -width => size
708 Specifies the width of the area of the canvas to print.
709 Defaults to the width of the canvas window.
710 -x => position
712 Specifies the x-coordinate of the left edge of the area of
713 the canvas that is to be printed, in canvas coordinates,
714 not window coordinates. Defaults to the coordinate of the
715 left edge of the window.
716 -y => position
718 Specifies the y-coordinate of the top edge of the area of
719 the canvas that is to be printed, in canvas coordinates,
720 not window coordinates. Defaults to the coordinate of the
721 top edge of the window.
722 $canvas->raise(tagOrId, ?aboveThis?)
724 Move all of the items given by tagOrId to a new position in the
725 display list just after the item given by aboveThis. If tagOrId
726 refers to more than one item then all are moved but the relative
727 order of the moved items will not be changed. AboveThis is a tag
728 or id; if it refers to more than one item then the last (topmost)
729 of these items in the display list is used as the destination loca‐
730 tion for the moved items. Note: this method has no effect on win‐
731 dow items. Window items always obscure other item types, and the
732 stacking order of window items is determined by the raise and lower
733 widget commands, not the raise and lower methods for canvases.
734 This method returns an empty string.
735 $canvas->scale(tagOrId, xOrigin, yOrigin, xScale, yScale)
737 Rescale all of the items given by tagOrId in canvas coordinate
738 space. XOrigin and yOrigin identify the origin for the scaling
739 operation and xScale and yScale identify the scale factors for x-
740 and y-coordinates, respectively (a scale factor of 1.0 implies no
741 change to that coordinate). For each of the points defining each
742 item, the x-coordinate is adjusted to change the distance from
743 xOrigin by a factor of xScale. Similarly, each y-coordinate is
744 adjusted to change the distance from yOrigin by a factor of yScale.
745 This method returns an empty string.
746 $canvas->scan(option, args)
748 This method is used to implement scanning on canvases. It has two
749 forms, depending on option:
750 $canvas->scanMark(x, y)
752 Records x and y and the canvas's current view; used in
753 conjunction with later scanDragto method. Typically this
754 method is associated with a mouse button press in the wid‐
755 get and x and y are the coordinates of the mouse. It
756 returns an empty string.
757 $canvas->scanDragto(x, y, ?gain?.)
759 This method computes the difference between its x and y
760 arguments (which are typically mouse coordinates) and the x
761 and y arguments to the last scanMark method for the widget.
762 It then adjusts the view by 10 times the difference in
763 coordinates. This method is typically associated It then
764 adjusts the view by gain times the difference in coordi‐
765 nates, where gain defaults to 10. This command is typi‐
766 cally associated with mouse motion events in the widget, to
767 produce the effect of dragging the canvas at high speed
768 through its window. The return value is an empty string.
769 $canvas->select(option, ?tagOrId, arg?)
771 Manipulates the selection in one of several ways, depending on
772 option. The method may take any of the forms described below. In
773 all of the descriptions below, tagOrId must refer to an item that
774 supports indexing and selection; if it refers to multiple items
775 then the first of these that supports indexing and the selection is
776 used. Index gives a textual description of a position within
777 tagOrId, as described in "INDICES" above.
778 $canvas->selectAdjust(tagOrId, index)
780 Locate the end of the selection in tagOrId nearest to the
781 character given by index, and adjust that end of the selec‐
782 tion to be at index (i.e. including but not going beyond
783 index). The other end of the selection is made the anchor
784 point for future selectTo method calls. If the selection
785 isn't currently in tagOrId then this method behaves the
786 same as the selectTo widget method. Returns an empty
787 string.
788 $canvas->selectClear
790 Clear the selection if it is in this widget. If the selec‐
791 tion isn't in this widget then the method has no effect.
792 Returns an empty string.
793 $canvas->selectFrom(tagOrId, index)
795 Set the selection anchor point for the widget to be just
796 before the character given by index in the item given by
797 tagOrId. This method doesn't change the selection; it
798 just sets the fixed end of the selection for future
799 selectTo method calls. Returns an empty string.
800 $canvas->selectItem
802 Returns the id of the selected item, if the selection is in
803 an item in this canvas. If the selection is not in this
804 canvas then an empty string is returned.
805 $canvas->selectTo(tagOrId, index)
807 Set the selection to consist of those characters of tagOrId
808 between the selection anchor point and index. The new
809 selection will include the character given by index; it
810 will include the character given by the anchor point only
811 if index is greater than or equal to the anchor point. The
812 anchor point is determined by the most recent selectAdjust
813 or selectFrom method calls for this widget. If the selec‐
814 tion anchor point for the widget isn't currently in
815 tagOrId, then it is set to the same character given by
816 index. Returns an empty string.
817 $canvas->type(tagOrId)
819 Returns the type of the item given by tagOrId, such as rectangle or
820 text. If tagOrId refers to more than one item, then the type of
821 the first item in the display list is returned. If tagOrId doesn't
822 refer to any items at all then an empty string is returned.
823 $canvas->xview(?args?)
825 This method is used to query and change the horizontal position of
826 the information displayed in the canvas's window. It can take any
827 of the following forms:
828 $canvas->xview
830 Returns a list containing two elements. Each element is a
831 real fraction between 0 and 1; together they describe the
832 horizontal span that is visible in the window. For exam‐
833 ple, if the first element is .2 and the second element is
834 .6, 20% of the canvas's area (as defined by the -scrollre‐
835 gion option) is off-screen to the left, the middle 40% is
836 visible in the window, and 40% of the canvas is off-screen
837 to the right. These are the same values passed to scroll‐
838 bars via the -xscrollcommand option.
839 $canvas->xviewMoveto(fraction)
841 Adjusts the view in the window so that fraction of the
842 total width of the canvas is off-screen to the left. Frac‐
843 tion must be a fraction between 0 and 1.
844 $canvas->xviewScroll(number, what)
846 This method shifts the view in the window left or right
847 according to number and what. Number must be an integer.
848 What must be either units or pages or an abbreviation of
849 one of these. If what is units, the view adjusts left or
850 right in units of the xScrollIncrement option, if it is
851 greater than zero, or in units of one-tenth the window's
852 width otherwise. If what is pages then the view adjusts in
853 units of nine-tenths the window's width. If number is neg‐
854 ative then information farther to the left becomes visible;
855 if it is positive then information farther to the right
856 becomes visible.
857 $canvas->yview(?args?)
859 This method is used to query and change the vertical position of
860 the information displayed in the canvas's window. It can take any
861 of the following forms:
862 $canvas->yview
864 Returns a list containing two elements. Each element is a
865 real fraction between 0 and 1; together they describe the
866 vertical span that is visible in the window. For example,
867 if the first element is .6 and the second element is 1.0,
868 the lowest 40% of the canvas's area (as defined by the
869 -scrollregion option) is visible in the window. These are
870 the same values passed to scrollbars via the -yscrollcom‐
871 mand option.
872 $canvas->yviewMoveto(fraction)
874 Adjusts the view in the window so that fraction of the can‐
875 vas's area is off-screen to the top. Fraction is a frac‐
876 tion between 0 and 1.
877 $canvas->yviewScroll(number, what)
879 This method adjusts the view in the window up or down
880 according to number and what. Number must be an integer.
881 What must be either units or pages. If what is units, the
882 view adjusts up or down in units of the yScrollIncrement
883 option, if it is greater than zero, or in units of one-
884 tenth the window's height otherwise. If what is pages then
885 the view adjusts in units of nine-tenths the window's
886 height. If number is negative then higher information
887 becomes visible; if it is positive then lower information
888 becomes visible.
889
891 The sections below describe the various types of items supported by
892 canvas widgets. Each item type is characterized by two things: first,
893 the form of the create method used to create instances of the type;
894 and second, a set of configuration options for items of that type,
895 which may be used in the create and itemconfigure methods. Most items
896 don't support indexing or selection or the methods related to them,
897 such as index and insert. Where items do support these facilities, it
898 is noted explicitly in the descriptions below. At present, text, line
899 and polygon items provide this support. For lines and polygons the
900 indexing facility is used to manipulate the coordinates of the item.
901
903 Items of type arc appear on the display as arc-shaped regions. An arc
904 is a section of an oval delimited by two angles (specified by the
905 -start and -extent options) and displayed in one of several ways (spec‐
906 ified by the -style option). Arcs are created with methods of the fol‐
907 lowing form:
908 $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)
910 The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
912 opposite corners of a rectangular region enclosing the oval that
913 defines the arc. After the coordinates there may be any number of
914 option-value pairs, each of which sets one of the configuration options
915 for the item. These same option-value pairs may be used in itemconfig‐
916 ure methods to change the item's configuration. The following options
917 are supported for arcs:
918 -dash => pattern
920 -activedash => pattern
921 -disableddash => pattern
922 This option specifies dash patterns for the normal state, the
923 active state, and the disabled state of an arc item. pattern may
924 have any of the forms accepted by Tk_GetDash. If the dash options
925 are omitted then the default is a solid outline.
926 -dashoffset => offset
928 The starting offset into the pattern provided by the -dash option.
929 -dashoffset is ignored if there is no -dash pattern.
930 -extent => degrees
932 Specifies the size of the angular range occupied by the arc. The
933 arc's range extends for degrees degrees counter-clockwise from the
934 starting angle given by the -start option. Degrees may be nega‐
935 tive. If it is greater than 360 or less than -360, then degrees
936 modulo 360 is used as the extent.
937 -fill => color
939 -activefill => color
940 -disabledfill => color
941 Specifies the color to be used to fill the arc region in its nor‐
942 mal, active, and disabled states, Color may have any of the forms
943 accepted by Tk_GetColor. If color is an empty string (the
944 default), then then the arc will not be filled.
945 -outline => color
947 -activeoutline => color
948 -disabledoutline => color
949 This option specifies the color that should be used to draw the
950 outline of the arc in its normal, active and disabled states.
951 Color may have any of the forms accepted by Tk_GetColor. This
952 option defaults to black. If color is specified as undef then no
953 outline is drawn for the arc.
954 -outlinestipple => bitmap
956 -activeoutlinestipple => bitmap
957 -disabledoutlinestipple => bitmap
958 This option specifies stipple patterns that should be used to draw
959 the outline of the arc in its normal, active and disabled states.
960 Indicates that the outline for the arc should be drawn with a stip‐
961 ple pattern; bitmap specifies the stipple pattern to use, in any of
962 the forms accepted by Tk_GetBitmap. If the -outline option hasn't
963 been specified then this option has no effect. If bitmap is an
964 empty string (the default), then the outline is drawn in a solid
965 fashion.
966 -start => degrees
968 Specifies the beginning of the angular range occupied by the arc.
969 Degrees is given in units of degrees measured counter-clockwise
970 from the 3-o'clock position; it may be either positive or nega‐
971 tive.
972 -state => state
974 Modifies the state of the arc item where state may be set to one
975 of: normal, disabled, hidden or "". If set to empty, the state of
976 the canvas itself is used. An arc item may also be in the "active"
977 state if the mouse is currently over it. Many options can take
978 separate specifications in normal, active and disabled states such
979 that the appearance of the item can be different in each state.
980 -stipple => bitmap
982 -activestipple => bitmap
983 -disabledstipple => bitmap
984 This option specifies stipple patterns that should be used to fill
985 the the arc in its normal, active and disabled states. bitmap
986 specifies the stipple pattern to use, in any of the forms accepted
987 by Tk_GetBitmap. If the -fill option hasn't been specified then
988 this option has no effect. If bitmap is an empty string (the
989 default), then filling is done in a solid fashion.
990 -style => type
992 Specifies how to draw the arc. If type is pieslice (the default)
993 then the arc's region is defined by a section of the oval's perime‐
994 ter plus two line segments, one between the center of the oval and
995 each end of the perimeter section. If type is chord then the arc's
996 region is defined by a section of the oval's perimeter plus a sin‐
997 gle line segment connecting the two end points of the perimeter
998 section. If type is arc then the arc's region consists of a sec‐
999 tion of the perimeter alone. In this last case the -fill option is
1000 ignored.
1001 -tags => tagList
1003 Specifies a set of tags to apply to the item. TagList consists of
1004 a list of tag names, which replace any existing tags for the item.
1005 TagList may be an empty list.
1006 -updatecommand => command
1008 Specifies a callback that is to be executed every time the arc item
1009 is updated on the screen.
1010 -width => outlineWidth
1012 -activewidth => outlineWidth
1013 -disabledwidth => outlineWidth
1014 Specifies the width of the outline to be drawn around the arc's
1015 region, in its normal, active and disabled states. outlineWidth
1016 may be in any of the forms described in the "COORDINATES" section
1017 above. If the -outline option has been specified as undef then
1018 this option has no effect. Wide outlines will be drawn centered on
1019 the edges of the arc's region. This option defaults to 1.0.
1020
1022 Items of type bitmap appear on the display as images with two colors,
1023 foreground and background. Bitmaps are created with methods of the
1024 following form:
1025 $canvas->createBitmap(x, y, ?option, value, option, value, ...?)
1027 The arguments x and y specify the coordinates of a point used to posi‐
1029 tion the bitmap on the display (see the -anchor option below for more
1030 information on how bitmaps are displayed). After the coordinates there
1031 may be any number of option-value pairs, each of which sets one of the
1032 configuration options for the item. These same option-value pairs may
1033 be used in itemconfigure methods to change the item's configuration.
1034 The following options are supported for bitmaps:
1035 -anchor => anchorPos
1037 AnchorPos tells how to position the bitmap relative to the posi‐
1038 tioning point for the item; it may have any of the forms accepted
1039 by Tk_GetAnchor. For example, if anchorPos is center then the bit‐
1040 map is centered on the point; if anchorPos is n then the bitmap
1041 will be drawn so that its top center point is at the positioning
1042 point. This option defaults to center.
1043 -background => color
1045 -activebackground => color
1046 -disabledbackground => color
1047 Specifies the color to use for each of the bitmap's '0' valued pix‐
1048 els in its normal, active and disabled states. Color may have any
1049 of the forms accepted by Tk_GetColor. If this option isn't speci‐
1050 fied, or if it is specified as undef, then nothing is displayed
1051 where the bitmap pixels are 0; this produces a transparent effect.
1052 -bitmap => bitmap
1054 -activebitmap => bitmap
1055 -disabledbitmap => bitmap
1056 Specifies the bitmaps to display in the item in its normal, active
1057 and disabled states. All bitmaps must have the same width and
1058 height. Bitmap may have any of the forms accepted by Tk_GetBitmap.
1059 -foreground => color
1061 -activeforeground => color
1062 -disabledforeground => color
1063 Specifies the color to use for each of the bitmap's '1' valued pix‐
1064 els in its normal, active and disabled states. Color may have any
1065 of the forms accepted by Tk_GetColor and defaults to black.
1066 -state => state
1068 Modifies the state of the bitmap item where state may be set to one
1069 of: normal, disabled, or hidden. An bitmap item may also be in the
1070 "active" state if the mouse is currently over it. Many options can
1071 take separate specifications in normal, active and disabled states
1072 such that the appearance of the item can be different in each
1073 state.
1074 -tags => tagList
1076 Specifies a set of tags to apply to the item. TagList consists of
1077 a list of tag names, which replace any existing tags for the item.
1078 TagList may be an empty list.
1079 -updatecommand => command
1081 Specifies a callback that is to be executed every time the bitmap
1082 item is updated on the screen.
1083
1085 Items of type grid are intended for producing a visual reference for
1086 interpreting other items. They can be drawn as either lines (with dash
1087 style) or as rectangular "dots" at each grid point.
1088 Items of type grid are unlike other items they always cover the whole
1090 of the canvas, but are never enclosed by nor overlap any area and are
1091 not near any point. That is they are intended to be always visible but
1092 not "pickable", as such they do support the "active" state. They are
1093 like other items in that: multiple grids are permitted, they can be
1094 raised and lowered relative to other items, they can be moved and
1095 scaled. As yet grids do not apear in PostScript output.
1096 Grids have outline like configure options. Grids are created with meth‐
1098 ods of the following form:
1099 $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)
1101 The arguments x1, y1 give the origin of the grid. x2, and y2 give the
1103 coordinates of the next grid point in their respective directions.
1104 After the coordinates there may be any number of option-value pairs,
1105 each of which sets one of the configuration options for the item.
1106 These same option-value pairs may be used in itemconfigure methods to
1107 change the item's configuration. The following options are supported
1108 for grids:
1109 -lines => boolean
1111 If -lines is set to a true value then lines are drawn for both X
1112 and Y grids in the style determined by -dash. Otherwise retangular
1113 "dots" are drawn at each grid point.
1114 -dash => pattern
1116 -disableddash => pattern
1117 This option specifies dash patterns for the normal state, and the
1118 disabled state of a grid item. pattern may have any of the forms
1119 accepted by Tk_GetDash. If the dash options are omitted then the
1120 default is a solid outline.
1121 -dashoffset => offset
1123 The starting offset into the pattern provided by the -dash option.
1124 -dashoffset is ignored if there is no -dash pattern.
1125 -color => color
1127 -disabledcolor => color
1128 This option specifies the color that should be used to draw the
1129 outline of the grid in its normal and disabled states. Color may
1130 have any of the forms accepted by Tk_GetColor. This option
1131 defaults to black. If color is undef then no grid will be drawn.
1132 -stipple => bitmap
1134 -disabledstipple => bitmap
1135 This option specifies stipple patterns that should be used to draw
1136 the outline of the rectangle in its normal and disabled states.
1137 bitmap specifies the stipple pattern to use, in any of the forms
1138 accepted by Tk_GetBitmap. If bitmap is an empty string (the
1139 default), then the outline is drawn in a solid fashion.
1140 -state => state
1142 Modifies the state of the rectangle item where state may be set to
1143 one of: normal, disabled, or hidden. Many options can take separate
1144 specifications in normal and disabled states such that the appear‐
1145 ance of the item can be different in each state.
1146 -tags => tagList
1148 Specifies a set of tags to apply to the item. TagList consists of
1149 a list of tag names, which replace any existing tags for the item.
1150 TagList may be an empty list.
1151 -updatecommand => command
1153 Specifies a callback that is to be executed every time the grid
1154 item is updated on the screen.
1155 -width => outlineWidth
1157 -disabledwidth => outlineWidth
1158 Specifies the width of the lines drawn by the grid or the size (in
1159 both X and Y) of the dots, in its normal and disabled states. This
1160 option defaults to 1.0.
1161
1163 Items of type image are used to display images on a canvas. Images are
1164 created with methods of the following form:
1165 $canvas->createImage(x, y, ?option, value, option, value, ...?)
1167 The arguments x and y specify the coordinates of a point used to posi‐
1169 tion the image on the display (see the -anchor option below for more
1170 information). After the coordinates there may be any number of
1171 option-value pairs, each of which sets one of the configuration options
1172 for the item. These same option-value pairs may be used in itemconfig‐
1173 ure methods to change the item's configuration. The following options
1174 are supported for images:
1175 -anchor => anchorPos
1177 AnchorPos tells how to position the image relative to the position‐
1178 ing point for the item; it may have any of the forms accepted by
1179 Tk_GetAnchor. For example, if anchorPos is center then the image
1180 is centered on the point; if anchorPos is n then the image will be
1181 drawn so that its top center point is at the positioning point.
1182 This option defaults to center.
1183 -image => name
1185 -activeimage => name
1186 -disabledimage => name
1187 Specifies the name of the images to display in the item in is nor‐
1188 mal, active and disabled states. This image must have been created
1189 previously, see Tk::Image.
1190 -state => state
1192 Modifies the state of the image item where state may be set to one
1193 of: normal, disabled, or hidden. An image item may also be in the
1194 "active" state if the mouse is currently over it. Many options can
1195 take separate specifications in normal, active and disabled states
1196 such that the appearance of the item can be different in each
1197 state.
1198 -tags => tagList
1200 Specifies a set of tags to apply to the item. TagList consists of
1201 a list of tag names, which replace any existing tags for the item;
1202 it may be an empty list.
1203 -updatecommand => command
1205 Specifies a callback that is to be executed every time the image
1206 item is updated on the screen.
1207
1209 Items of type line appear on the display as one or more connected line
1210 segments or curves. Line items support coordinate indexing operations
1211 using the canvas methods: dchars, index, insert. Lines are created
1212 with methods of the following form:
1213 $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)
1215 The arguments x1 through yn give the coordinates for a series of two or
1217 more points that describe a series of connected line segments. After
1218 the coordinates there may be any number of option-value pairs, each of
1219 which sets one of the configuration options for the item. These same
1220 option-value pairs may be used in itemconfigure methods to change the
1221 item's configuration. The following options are supported for lines:
1222 -arrow => where
1224 Indicates whether or not arrowheads are to be drawn at one or both
1225 ends of the line. Where must have one of the values none (for no
1226 arrowheads), first (for an arrowhead at the first point of the
1227 line), last (for an arrowhead at the last point of the line), or
1228 both (for arrowheads at both ends). This option defaults to none.
1229 -arrowshape => shape
1231 This option indicates how to draw arrowheads. The shape argument
1232 must be a list with three elements, each specifying a distance in
1233 any of the forms described in the "COORDINATES" section above. The
1234 first element of the list gives the distance along the line from
1235 the neck of the arrowhead to its tip. The second element gives the
1236 distance along the line from the trailing points of the arrowhead
1237 to the tip, and the third element gives the distance from the out‐
1238 side edge of the line to the trailing points. If this option isn't
1239 specified then Tk picks a ``reasonable'' shape.
1240 -capstyle => style
1242 Specifies the ways in which caps are to be drawn at the endpoints
1243 of the line. Style may have any of the forms accepted by Tk_Get‐
1244 CapStyle (butt, projecting, or round). If this option isn't speci‐
1245 fied then it defaults to butt. Where arrowheads are drawn the cap
1246 style is ignored.
1247 -dash => pattern
1249 -activedash => pattern
1250 -disableddash => pattern
1251 This option specifies dash patterns for the normal state, the
1252 active state, and the disabled state of a line item. pattern may
1253 have any of the forms accepted by Tk_GetDash. If the dash options
1254 are omitted then the default is a solid outline.
1255 -dashoffset => offset
1257 The starting offset into the pattern provided by the -dash option.
1258 -dashoffset is ignored if there is no -dash pattern.
1259 -fill => color
1261 -activefill => color
1262 -disabledfill => color
1263 Specifies the color to be used to fill the line in its normal,
1264 active, and disabled states. Color may have any of the forms
1265 acceptable to Tk_GetColor. It may also be undef, in which case the
1266 line will be transparent. This option defaults to black.
1267 -joinstyle => style
1269 Specifies the ways in which joints are to be drawn at the vertices
1270 of the line. Style may have any of the forms accepted by Tk_Get‐
1271 CapStyle (bevel, miter, or round). If this option isn't specified
1272 then it defaults to miter. If the line only contains two points
1273 then this option is irrelevant.
1274 -smooth => boolean
1276 Boolean must have one of the forms accepted by Tk_GetBoolean. It
1277 indicates whether or not the line should be drawn as a curve. If
1278 so, the line is rendered as a set of parabolic splines: one spline
1279 is drawn for the first and second line segments, one for the second
1280 and third, and so on. Straight-line segments can be generated
1281 within a curve by duplicating the end-points of the desired line
1282 segment.
1283 -splinesteps => number
1285 Specifies the degree of smoothness desired for curves: each spline
1286 will be approximated with number line segments. This option is
1287 ignored unless the -smooth option is true.
1288 -state => state
1290 Modifies the state of the line item where state may be set to one
1291 of: normal, disabled, or hidden. A line item may also be in the
1292 "active" state if the mouse is currently over it. Many options can
1293 take separate specifications in normal, active and disabled states
1294 such that the appearance of the item can be different in each
1295 state.
1296 -stipple => bitmap
1298 -activestipple => bitmap
1299 -disabledstipple => bitmap
1300 This option specifies stipple patterns that should be used to fill
1301 the the line in its normal, active and disabled states. bitmap
1302 specifies the stipple pattern to use, in any of the forms accepted
1303 by Tk_GetBitmap. If bitmap is an empty string (the default), then
1304 filling is done in a solid fashion.
1305 -tags => tagList
1307 Specifies a set of tags to apply to the item. TagList consists of
1308 a list of tag names, which replace any existing tags for the item.
1309 TagList may be an empty list.
1310 -updatecommand => command
1312 Specifies a callback that is to be executed every time the line
1313 item is updated on the screen.
1314 -width => lineWidth
1316 -activewidth => lineWidth
1317 -disabledwidth => lineWidth
1318 Specifies the width of the line in its normal, active and disabled
1319 states. lineWidth may be in any of the forms described in the
1320 "COORDINATES" section above.
1321 Wide lines will be drawn centered on the path specified by the
1323 points. If this option isn't specified then it defaults to 1.0.
1324
1326 Items of type oval appear as circular or oval regions on the display.
1327 Each oval may have an outline, a fill, or both. Ovals are created with
1328 methods of the following form:
1329 $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)
1331 The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
1333 opposite corners of a rectangular region enclosing the oval. The oval
1334 will include the top and left edges of the rectangle not the lower or
1335 right edges. If the region is square then the resulting oval is circu‐
1336 lar; otherwise it is elongated in shape. After the coordinates there
1337 may be any number of option-value pairs, each of which sets one of the
1338 configuration options for the item. These same option-value pairs may
1339 be used in itemconfigure methods to change the item's configuration.
1340 The following options are supported for ovals:
1341 -dash => pattern
1343 -activedash => pattern
1344 -disableddash => pattern
1345 This option specifies dash patterns for the normal state, the
1346 active state, and the disabled state of an oval item. pattern may
1347 have any of the forms accepted by Tk_GetDash. If the dash options
1348 are omitted then the default is a solid outline.
1349 -dashoffset => offset
1351 The starting offset into the pattern provided by the -dash option.
1352 -dashoffset is ignored if there is no -dash pattern.
1353 -fill => color
1355 -activefill => color
1356 -disabledfill => color
1357 Specifies the color to be used to fill the oval in its normal,
1358 active, and disabled states. Color may have any of the forms
1359 accepted by Tk_GetColor. If color is undef (the default), then
1360 then the oval will not be filled.
1361 -outline => color
1363 -activeoutline => color
1364 -disabledoutline => color
1365 This option specifies the color that should be used to draw the
1366 outline of the oval in its normal, active and disabled states.
1367 Color may have any of the forms accepted by Tk_GetColor. This
1368 option defaults to black. If color is undef then no outline will
1369 be drawn for the oval.
1370 -outlinestipple => bitmap
1372 -activeoutlinestipple => bitmap
1373 -disabledoutlinestipple => bitmap
1374 This option specifies stipple patterns that should be used to draw
1375 the outline of the oval in its normal, active and disabled states.
1376 bitmap specifies the stipple pattern to use, in any of the forms
1377 accepted by Tk_GetBitmap. If the -outline option hasn't been spec‐
1378 ified then this option has no effect. If bitmap is an empty string
1379 (the default), then the outline is drawn in a solid fashion.
1380 -state => state
1382 Modifies the state of the oval item where state may be set to one
1383 of: normal, disabled, or hidden. An oval item may also be in the
1384 "active" state if the mouse is currently over it. Many options can
1385 take separate specifications in normal, active and disabled states
1386 such that the appearance of the item can be different in each
1387 state.
1388 -stipple => bitmap
1390 -activestipple => bitmap
1391 -disabledstipple => bitmap
1392 This option specifies stipple patterns that should be used to fill
1393 the the oval in its normal, active and disabled states. bitmap
1394 specifies the stipple pattern to use, in any of the forms accepted
1395 by Tk_GetBitmap. If the -fill option hasn't been specified then
1396 this option has no effect. If bitmap is an empty string (the
1397 default), then filling is done in a solid fashion.
1398 -tags => tagList
1400 Specifies a set of tags to apply to the item. TagList consists of
1401 a list of tag names, which replace any existing tags for the item.
1402 TagList may be an empty list.
1403 -updatecommand => command
1405 Specifies a callback that is to be executed every time the oval
1406 item is updated on the screen.
1407 -width => outlineWidth
1409 -activewidth => outlineWidth
1410 -disabledwidth => outlineWidth
1411 Specifies the width of the outline to be drawn around the oval, in
1412 its normal, active and disabled states. outlineWidth specifies the
1413 width of the outline to be drawn around the oval, in any of the
1414 forms described in the "COORDINATES" section above.
1415 If the -outline option hasn't been specified then this option has
1417 no effect. Wide outlines are drawn centered on the oval path
1418 defined by x1, y1, x2, and y2. This option defaults to 1.0.
1419
1421 Items of type polygon appear as polygonal or curved filled regions on
1422 the display. Polygon items support coordinate indexing operations
1423 using the canvas methods: dchars, index, insert. Polygons are created
1424 with methods of the following form:
1425 $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)
1427 The arguments x1 through yn specify the coordinates for three or more
1429 points that define a closed polygon. The first and last points may be
1430 the same; whether they are or not, Tk will draw the polygon as a
1431 closed polygon. After the coordinates there may be any number of
1432 option-value pairs, each of which sets one of the configuration options
1433 for the item. These same option-value pairs may be used in itemconfig‐
1434 ure methods to change the item's configuration. The following options
1435 are supported for polygons:
1436 -dash => pattern
1438 -activedash => pattern
1439 -disableddash => pattern
1440 This option specifies dash patterns for the normal state, the
1441 active state, and the disabled state of an polygon item. pattern
1442 may have any of the forms accepted by Tk_GetDash. If the dash
1443 options are omitted then the default is a solid outline.
1444 -dashoffset => offset
1446 The starting offset into the pattern provided by the -dash option.
1447 -dashoffset is ignored if there is no -dash pattern.
1448 -fill => color
1450 -activefill => color
1451 -disabledfill => color
1452 Specifies the color to be used to fill the polygon in its normal,
1453 active, and disabled states. Color may have any of the forms
1454 acceptable to Tk_GetColor. If color is undef then the polygon will
1455 be transparent. This option defaults to black.
1456 -joinstyle => style
1458 Specifies the ways in which joints are to be drawn at the vertices
1459 of the outline. Style may have any of the forms accepted by
1460 Tk_GetCapStyle (bevel, miter, or round). If this option isn't
1461 specified then it defaults to miter.
1462 -outline => color
1464 -activeoutline => color
1465 -disabledoutline => color
1466 This option specifies the color that should be used to draw the
1467 outline of the polygon in its normal, active and disabled states.
1468 Color may have any of the forms accepted by Tk_GetColor. If color
1469 is undef then no outline will be drawn for the polygon. This
1470 option defaults to undef (no outline).
1471 -outlinestipple => bitmap
1473 -activeoutlinestipple => bitmap
1474 -disabledoutlinestipple => bitmap
1475 This option specifies stipple patterns that should be used to draw
1476 the outline of the polygon in its normal, active and disabled
1477 states. bitmap specifies the stipple pattern to use, in any of the
1478 forms accepted by Tk_GetBitmap. If the -outline option hasn't been
1479 specified then this option has no effect. If bitmap is an empty
1480 string (the default), then the outline is drawn in a solid fashion.
1481 -smooth => boolean
1483 Boolean must have one of the forms accepted by Tk_GetBoolean It
1484 indicates whether or not the polygon should be drawn with a curved
1485 perimeter. If so, the outline of the polygon becomes a set of par‐
1486 abolic splines, one spline for the first and second line segments,
1487 one for the second and third, and so on. Straight-line segments
1488 can be generated in a smoothed polygon by duplicating the end-
1489 points of the desired line segment.
1490 -splinesteps => number
1492 Specifies the degree of smoothness desired for curves: each spline
1493 will be approximated with number line segments. This option is
1494 ignored unless the -smooth option is true.
1495 -state => state
1497 Modifies the state of the polygon item where state may be set to
1498 one of: normal, disabled, or hidden. A polygon item may also be in
1499 the "active" state if the mouse is currently over it. Many options
1500 can take separate specifications in normal, active and disabled
1501 states such that the appearance of the item can be different in
1502 each state.
1503 -stipple => bitmap
1505 -activestipple => bitmap
1506 -disabledstipple => bitmap
1507 This option specifies stipple patterns that should be used to fill
1508 the the polygon in its normal, active and disabled states. bitmap
1509 specifies the stipple pattern to use, in any of the forms accepted
1510 by Tk_GetBitmap. If bitmap is an empty string (the default), then
1511 filling is done in a solid fashion.
1512 -tags => tagList
1514 Specifies a set of tags to apply to the item. TagList consists of
1515 a list of tag names, which replace any existing tags for the item.
1516 TagList may be an empty list.
1517 -updatecommand => command
1519 Specifies a callback that is to be executed every time the polygon
1520 item is updated on the screen.
1521 -width => outlineWidth
1523 -activewidth => outlineWidth
1524 -disabledwidth => outlineWidth
1525 Specifies the width of the outline to be drawn around
1526 the polygon, in its normal, active and disabled states. out‐
1527 lineWidth may be in any of the forms described in the COORDINATES
1528 section above. OutlineWidth specifies the width of the outline to
1529 be drawn around the polygon, in any of the forms described in the
1530 "COORDINATES" section above. If the -outline option hasn't been
1531 specified then this option has no effect. This option defaults to
1532 1.0.
1533 Polygon items are different from other items such as rectangles,
1535 ovals and arcs in that interior points are considered to be
1536 ``inside'' a polygon (e.g. for purposes of the find closest and
1537 find overlapping methods) even if it is not filled. For most other
1538 item types, an interior point is considered to be inside the item
1539 only if the item is filled or if it has neither a fill nor an out‐
1540 line. If you would like an unfilled polygon whose interior points
1541 are not considered to be inside the polygon, use a line item
1542 instead.
1543
1545 Items of type rectangle appear as rectangular regions on the display.
1546 Each rectangle may have an outline, a fill, or both. Rectangles are
1547 created with methods of the following form:
1548 $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)
1550 The arguments x1, y1, x2, and y2 give the coordinates of two diagonally
1552 opposite corners of the rectangle (the rectangle will include its upper
1553 and left edges but not its lower or right edges). After the coordi‐
1554 nates there may be any number of option-value pairs, each of which sets
1555 one of the configuration options for the item. These same option-value
1556 pairs may be used in itemconfigure methods to change the item's config‐
1557 uration. The following options are supported for rectangles:
1558 -dash => pattern
1560 -activedash => pattern
1561 -disableddash => pattern
1562 This option specifies dash patterns for the normal state, the
1563 active state, and the disabled state of a rectangle item. pattern
1564 may have any of the forms accepted by Tk_GetDash. If the dash
1565 options are omitted then the default is a solid outline.
1566 -dashoffset => offset
1568 The starting offset into the pattern provided by the -dash option.
1569 -dashoffset is ignored if there is no -dash pattern.
1570 -fill => color
1572 -activefill => color
1573 -disabledfill => color
1574 Specifies the color to be used to fill the rectangle in its normal,
1575 active, and disabled states. Color may be specified in any of the
1576 forms accepted by Tk_GetColor. If color is undef (the default),
1577 then the rectangle will not be filled.
1578 -outline => color
1580 -activeoutline => color
1581 -disabledoutline => color
1582 This option specifies the color that should be used to draw the
1583 outline of the rectangle in its normal, active and disabled states.
1584 Color may have any of the forms accepted by Tk_GetColor. This
1585 option defaults to black. If color is undef then no outline will
1586 be drawn for the rectangle.
1587 -outlinestipple => bitmap
1589 -activeoutlinestipple => bitmap
1590 -disabledoutlinestipple => bitmap
1591 This option specifies stipple patterns that should be used to draw
1592 the outline of the rectangle in its normal, active and disabled
1593 states. bitmap specifies the stipple pattern to use, in any of the
1594 forms accepted by Tk_GetBitmap. If the -outline option hasn't been
1595 specified then this option has no effect. If bitmap is an empty
1596 string (the default), then the outline is drawn in a solid fashion.
1597 -state => state
1599 Modifies the state of the rectangle item where state may be set to
1600 one of: normal, disabled, or hidden. A rectangle item may also be
1601 in the "active" state if the mouse is currently over it. Many
1602 options can take separate specifications in normal, active and dis‐
1603 abled states such that the appearance of the item can be different
1604 in each state.
1605 -stipple => bitmap
1607 -activestipple => bitmap
1608 -disabledstipple => bitmap
1609 This option specifies stipple patterns that should be used to fill
1610 the the rectangle in its normal, active and disabled states. bit‐
1611 map specifies the stipple pattern to use, in any of the forms
1612 accepted by Tk_GetBitmap. If the -fill option hasn't been speci‐
1613 fied then this option has no effect. If bitmap is an empty string
1614 (the default), then filling is done in a solid fashion.
1615 -tags => tagList
1617 Specifies a set of tags to apply to the item. TagList consists of
1618 a list of tag names, which replace any existing tags for the item.
1619 TagList may be an empty list.
1620 -updatecommand => command
1622 Specifies a callback that is to be executed every time the rectan‐
1623 gle item is updated on the screen.
1624 -width => outlineWidth
1626 -activewidth => outlineWidth
1627 -disabledwidth => outlineWidth
1628 Specifies the width of the outline to be drawn around the rectan‐
1629 gle, in its normal, active and disabled states. OutlineWidth spec‐
1630 ifies the width of the outline to be drawn around the rectangle, in
1631 any of the forms described in the "COORDINATES" section above.
1632 If the -outline option hasn't been specified then this option has
1634 no effect. Wide outlines are drawn centered on the rectangular
1635 path defined by x1, y1, x2, and y2. This option defaults to 1.0.
1636
1638 A text item displays a string of characters on the screen in one or
1639 more lines. Text items support indexing and selection, along with the
1640 following text-related canvas methods: dchars, focus, icursor, index,
1641 insert, select. Text items are created with methods of the following
1642 form:
1643 $canvas->createText(x, y, ?option, value, option, value, ...?)
1645 The arguments x and y specify the coordinates of a point used to posi‐
1647 tion the text on the display (see the options below for more informa‐
1648 tion on how text is displayed). After the coordinates there may be any
1649 number of option-value pairs, each of which sets one of the configura‐
1650 tion options for the item. These same option-value pairs may be used
1651 in itemconfigure methods to change the item's configuration. The fol‐
1652 lowing options are supported for text items:
1653 -anchor => anchorPos
1655 AnchorPos tells how to position the text relative to the position‐
1656 ing point for the text; it may have any of the forms accepted by
1657 Tk_GetAnchor. For example, if anchorPos is center then the text is
1658 centered on the point; if anchorPos is n then the text will be
1659 drawn such that the top center point of the rectangular region
1660 occupied by the text will be at the positioning point. This option
1661 defaults to center.
1662 -fill => color
1664 -activefill => color
1665 -disabledfill => color
1666 Specifies the color to be used to fill the text in its normal,
1667 active, and disabled states. Color may have any of the forms
1668 accepted by Tk_GetColor. If color is undef then the text will be
1669 transparent. If this option isn't specified then it defaults to
1670 black.
1671 -font => fontName
1673 Specifies the font to use for the text item. FontName may be any
1674 string acceptable to Tk_GetFontStruct. If this option isn't speci‐
1675 fied, it defaults to a system-dependent font.
1676 -justify => how
1678 Specifies how to justify the text within its bounding region. How
1679 must be one of the values left, right, or center. This option will
1680 only matter if the text is displayed as multiple lines. If the
1681 option is omitted, it defaults to left.
1682 -state => state
1684 Modifies the state of the text item where state may be set to one
1685 of: normal, disabled, or hidden. A text item may also be in the
1686 "active" state if the mouse is currently over it. Many options can
1687 take separate specifications in normal, active and disabled states
1688 such that the appearance of the item can be different in each
1689 state.
1690 -stipple => bitmap
1692 -activestipple => bitmap
1693 -disabledstipple => bitmap
1694 This option specifies stipple patterns that should be used to fill
1695 the the text in its normal, active and disabled states. bitmap
1696 specifies the stipple pattern to use, in any of the forms accepted
1697 by Tk_GetBitmap. If bitmap is an empty string (the default) then
1698 the text is drawn in a solid fashion.
1699 -tags => tagList
1701 Specifies a set of tags to apply to the item. TagList consists of
1702 a list of tag names, which replace any existing tags for the item.
1703 TagList may be an empty list.
1704 -text => string
1706 String specifies the characters to be displayed in the text item.
1707 Newline characters cause line breaks. The characters in the item
1708 may also be changed with the insert and delete methods. This
1709 option defaults to an empty string.
1710 -updatecommand => command
1712 Specifies a callback that is to be executed every time the text
1713 item is updated on the screen.
1714 -width => lineLength
1716 Specifies a maximum line length for the text, in any of the forms
1717 described in the "COORDINATES" section above. If this option is
1718 zero (the default) the text is broken into lines only at newline
1719 characters. However, if this option is non-zero then any line that
1720 would be longer than lineLength is broken just before a space char‐
1721 acter to make the line shorter than lineLength; the space charac‐
1722 ter is treated as if it were a newline character.
1723
1725 Items of type window cause a particular window to be displayed at a
1726 given position on the canvas. Window items are created with methods of
1727 the following form:
1728 $canvas->createWindow(x, y?, -option=>value, -option=>value, ...?)
1730 The arguments x and y specify the coordinates of a point used to posi‐
1732 tion the window on the display (see the -anchor option below for more
1733 information on how bitmaps are displayed). After the coordinates there
1734 may be any number of option-value pairs, each of which sets one of the
1735 configuration options for the item. These same option-value pairs may
1736 be used in itemconfigure method to change the item's configuration.
1737 The following options are supported for window items:
1738 -anchor => anchorPos
1740 AnchorPos tells how to position the window relative to the posi‐
1741 tioning point for the item; it may have any of the forms accepted
1742 by Tk_GetAnchor. For example, if anchorPos is center then the win‐
1743 dow is centered on the point; if anchorPos is n then the window
1744 will be drawn so that its top center point is at the positioning
1745 point. This option defaults to center.
1746 -height => pixels
1748 Specifies the height to assign to the item's window. Pixels may
1749 have any of the forms described in the "COORDINATES" section above.
1750 If this option isn't specified, or if it is specified as an empty
1751 string, then the window is given whatever height it requests inter‐
1752 nally.
1753 -state => state
1755 Modifies the state of the window item where state may be set to one
1756 of: normal, disabled, or hidden.
1757 -tags => tagList
1759 Specifies a set of tags to apply to the item. TagList consists of
1760 a list of tag names, which replace any existing tags for the item.
1761 TagList may be an empty list.
1762 -updatecommand => command
1764 Specifies a callback that is to be executed every time the window
1765 item is updated on the screen.
1766 -width => pixels
1768 Specifies the width to assign to the item's window. Pixels may
1769 have any of the forms described in the "COORDINATES" section above.
1770 If this option isn't specified, or if it is specified as an empty
1771 string, then the window is given whatever width it requests inter‐
1772 nally.
1773 -window => $widget
1775 Specifies the window to associate with this item. The window spec‐
1776 ified by $widget must either be a child of the canvas widget or a
1777 child of some ancestor of the canvas widget. PathName may not
1778 refer to a top-level window.
1779 Note: due to restrictions in the ways that windows are managed, it
1781 is not possible to draw other graphical items (such as lines and
1782 images) on top of window items. A window item always obscures any
1783 graphics that overlap it, regardless of their order in the display
1784 list.
1785
1787 It is possible for individual applications to define new item types for
1788 canvas widgets using C code. See the documentation for Tk_CreateItem‐
1789 Type.
1790
1792 Canvas has default bindings to allow scrolling if necessary: <Up>,
1793 <Down>, <Left> and <Right> (and their <Control-*> counter parts). Fur‐
1794 ther <Proir>, <Next>, <Home> and <End>. These bindings allow you to
1795 navigate the same way as in other widgets that can scroll.
1796
1798 The following methods are added as perl code:
1799 $canvas->get_corners
1801 Returns the bounding box in Canvas coordinates of the visible por‐
1802 tion of the Canvas. (Written by Slaven Rezic.)
1803
1805 Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
1806 ezd program. Ezd provides structured graphics in a Scheme environment
1807 and preceded canvases by a year or two. Its simple mechanisms for
1808 placing and animating graphical objects inspired the functions of can‐
1809 vases.
1810
1812 canvas, widget
1813perl v5.8.8 2008-02-05 Canvas(3)