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
13 -borderwidth -insertbackground -relief -tile
14 -cursor -insertborderwidth -selectbackground -takefocus
15 -highlightbackground -insertofftime -selectborderwidth -xscrollcommand
16 -highlightcolor -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
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 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;
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 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
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 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
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 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
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
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 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
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
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 Individual items may be moved or scaled using methods described below,
197 but they may not be rotated.
198
200 Text items support the notion of an index for identifying particular
201 positions within the item.
202 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 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 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 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 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 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 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 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 [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
261 Many items support the notion of an dash pattern for outlines.
262 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 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 Some examples, for a line width of 2:
280 -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 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
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 The following additional methods are available for canvas widgets:
301 $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 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 all Selects all the items in the canvas.
318 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 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 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 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 withtag tagOrId
354 Selects all the items given by tagOrId.
355 $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 $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 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 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 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 $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 $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 $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 $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 $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 $canvas->delete(?tagOrId, tagOrId, ...?)
459 Delete each of the items given by each tagOrId, and return an empty
460 string.
461 $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 $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 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 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 $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 $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 $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 $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 $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 $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 $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 $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 $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 -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 -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 -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 -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 -height => size
655 Specifies the height of the area of the canvas to print.
656 Defaults to the height of the canvas window.
657 -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 -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 -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 -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 -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 -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 -width => size
711 Specifies the width of the area of the canvas to print.
712 Defaults to the width of the canvas window.
713 -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 -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 $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 $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 $canvas->scan(option, args)
751 This method is used to implement scanning on canvases. It has two
752 forms, depending on option:
753 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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
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
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 $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)
914 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1012 Specifies a callback that is to be executed every time the arc item
1013 is updated on the screen.
1014 -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
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 $canvas->createBitmap(x, y, ?option, value, option, value, ...?)
1031 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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1086 Specifies a callback that is to be executed every time the bitmap
1087 item is updated on the screen.
1088
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 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 Grids have outline like configure options. Grids are created with
1103 methods of the following form:
1104 $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)
1106 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 The following options are supported for grids:
1115 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1159 Specifies a callback that is to be executed every time the grid
1160 item is updated on the screen.
1161 -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
1169 Items of type image are used to display images on a canvas. Images are
1170 created with methods of the following form:
1171 $canvas->createImage(x, y, ?option, value, option, value, ...?)
1173 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 -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 -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 -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 -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 -updatecommand => command
1211 Specifies a callback that is to be executed every time the image
1212 item is updated on the screen.
1213
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 $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)
1221 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1318 Specifies a callback that is to be executed every time the line
1319 item is updated on the screen.
1320 -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 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
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 $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)
1337 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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1411 Specifies a callback that is to be executed every time the oval
1412 item is updated on the screen.
1413 -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 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
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 $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)
1433 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1525 Specifies a callback that is to be executed every time the polygon
1526 item is updated on the screen.
1527 -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 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
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 $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)
1556 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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1629 Specifies a callback that is to be executed every time the
1630 rectangle item is updated on the screen.
1631 -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 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
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 $canvas->createText(x, y, ?option, value, option, value, ...?)
1653 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 -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 -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 -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 -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 -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 -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 -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 -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 -updatecommand => command
1720 Specifies a callback that is to be executed every time the text
1721 item is updated on the screen.
1722 -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
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 $canvas->createWindow(x, y?, -option=>value, -option=>value, ...?)
1738 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 -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 -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 -state => state
1763 Modifies the state of the window item where state may be set to one
1764 of: normal, disabled, or hidden.
1765 -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 -updatecommand => command
1772 Specifies a callback that is to be executed every time the window
1773 item is updated on the screen.
1774 -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 -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 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
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
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
1806 The following methods are added as perl code:
1807 $canvas->get_corners
1809 Returns the bounding box in Canvas coordinates of the visible
1810 portion of the Canvas. (Written by Slaven Rezic.)
1811
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
1820 canvas, widget
1821perl v5.34.0 2021-07-23 Canvas(3)