2
'\" Copyright (c) 1992-1994 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8
'\" RCS: @(#) $Id: canvas.n,v 1.3 1998/10/16 00:46:18 rjohnson Exp $
11
.TH canvas n 4.0 Tk "Tk Built-In Commands"
13
'\" Note: do not modify the .SH NAME line immediately below!
15
canvas \- Create and manipulate canvas widgets
17
\fBcanvas\fR \fIpathName \fR?\fIoptions\fR?
19
\-background \-highlightthickness \-insertwidth \-takefocus
20
\-borderwidth \-insertbackground \-relief \-xscrollcommand
21
\-cursor \-insertborderwidth \-selectbackground \-yscrollcommand
22
\-highlightbackground \-insertofftime \-selectborderwidth
23
\-highlightcolor \-insertontime \-selectforeground
25
.SH "WIDGET-SPECIFIC OPTIONS"
26
.OP \-closeenough closeEnough CloseEnough
27
Specifies a floating-point value indicating how close the mouse cursor
28
must be to an item before it is considered to be ``inside'' the item.
30
.OP \-confine confine Confine
31
Specifies a boolean value that indicates whether or not it should be
32
allowable to set the canvas's view outside the region defined by the
33
\fBscrollRegion\fR argument.
34
Defaults to true, which means that the view will
35
be constrained within the scroll region.
36
.OP \-height height Height
37
Specifies a desired window height that the canvas widget should request from
38
its geometry manager. The value may be specified in any
39
of the forms described in the COORDINATES section below.
40
.OP \-scrollregion scrollRegion ScrollRegion
41
Specifies a list with four coordinates describing the left, top, right, and
42
bottom coordinates of a rectangular region.
43
This region is used for scrolling purposes and is considered to be
44
the boundary of the information in the canvas.
45
Each of the coordinates may be specified
46
in any of the forms given in the COORDINATES section below.
47
.OP \-width width width
48
Specifies a desired window width that the canvas widget should request from
49
its geometry manager. The value may be specified in any
50
of the forms described in the COORDINATES section below.
52
.OP \-xscrollincrement xScrollIncrement ScrollIncrement
53
Specifies an increment for horizontal scrolling, in any of the usual forms
54
permitted for screen distances. If the value of this option is greater
55
than zero, the horizontal view in the window will be constrained so that
56
the canvas x coordinate at the left edge of the window is always an even
57
multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling
58
(e.g., the change in view when the left and right arrows of a scrollbar
59
are selected) will also be \fBxScrollIncrement\fR. If the value of
60
this option is less than or equal to zero, then horizontal scrolling
62
.OP \-yscrollincrement yScrollIncrement ScrollIncrement
63
Specifies an increment for vertical scrolling, in any of the usual forms
64
permitted for screen distances. If the value of this option is greater
65
than zero, the vertical view in the window will be constrained so that
66
the canvas y coordinate at the top edge of the window is always an even
67
multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling
68
(e.g., the change in view when the top and bottom arrows of a scrollbar
69
are selected) will also be \fByScrollIncrement\fR. If the value of
70
this option is less than or equal to zero, then vertical scrolling
76
The \fBcanvas\fR command creates a new window (given
77
by the \fIpathName\fR argument) and makes it into a canvas widget.
78
Additional options, described above, may be specified on the
79
command line or in the option database
80
to configure aspects of the canvas such as its colors and 3-D relief.
81
The \fBcanvas\fR command returns its
82
\fIpathName\fR argument. At the time this command is invoked,
83
there must not exist a window named \fIpathName\fR, but
84
\fIpathName\fR's parent must exist.
86
Canvas widgets implement structured graphics.
87
A canvas displays any number of \fIitems\fR, which may be things like
88
rectangles, circles, lines, and text.
89
Items may be manipulated (e.g. moved or re-colored) and commands may
90
be associated with items in much the same way that the \fBbind\fR
91
command allows commands to be bound to widgets. For example,
92
a particular command may be associated with the <Button-1> event
93
so that the command is invoked whenever button 1 is pressed with
94
the mouse cursor over an item.
95
This means that items in a canvas can have behaviors defined by
96
the Tcl scripts bound to them.
100
The items in a canvas are ordered for purposes of display,
101
with the first item in the display list being displayed
102
first, followed by the next item in the list, and so on.
103
Items later in the display list obscure those that are
104
earlier in the display list and are sometimes referred to
105
as being ``on top'' of earlier items.
106
When a new item is created it is placed at the end of the
107
display list, on top of everything else.
108
Widget commands may be used to re-arrange the order of the
111
Window items are an exception to the above rules. The underlying
112
window systems require them always to be drawn on top of other items.
113
In addition, the stacking order of window items
114
is not affected by any of the canvas widget commands; you must use
115
the \fBraise\fR and \fBlower\fR Tk commands instead.
117
.SH "ITEM IDS AND TAGS"
119
Items in a canvas widget may be named in either of two ways:
121
Each item has a unique identifying number which is assigned to
122
that item when it is created. The id of an item never changes
123
and id numbers are never re-used within the lifetime of a
126
Each item may also have any number of \fItags\fR associated
127
with it. A tag is just a string of characters, and it may
128
take any form except that of an integer.
129
For example, ``x123'' is OK but ``123'' isn't.
130
The same tag may be associated with many different items.
131
This is commonly done to group items in various interesting
132
ways; for example, all selected items might be given the
135
The tag \fBall\fR is implicitly associated with every item
136
in the canvas; it may be used to invoke operations on
137
all the items in the canvas.
139
The tag \fBcurrent\fR is managed automatically by Tk;
140
it applies to the \fIcurrent item\fR, which is the
141
topmost item whose drawn area covers the position of
143
If the mouse is not in the canvas widget or is not over
144
an item, then no item has the \fBcurrent\fR tag.
146
When specifying items in canvas widget commands, if the
147
specifier is an integer then it is assumed to refer to
148
the single item with that id.
149
If the specifier is not an integer, then it is assumed to
150
refer to all of the items in the canvas that have a tag
151
matching the specifier.
152
The symbol \fItagOrId\fR is used below to indicate that
153
an argument specifies either an id that selects a single
154
item or a tag that selects zero or more items.
155
Some widget commands only operate on a single item at a
156
time; if \fItagOrId\fR is specified in a way that
157
names multiple items, then the normal behavior is for
158
the command to use the first (lowest) of these items in
159
the display list that is suitable for the command.
160
Exceptions are noted in the widget command descriptions
165
All coordinates related to canvases are stored as floating-point
167
Coordinates and distances are specified in screen units,
168
which are floating-point numbers optionally followed
169
by one of several letters.
170
If no letter is supplied then the distance is in pixels.
171
If the letter is \fBm\fR then the distance is in millimeters on
172
the screen; if it is \fBc\fR then the distance is in centimeters;
173
\fBi\fR means inches, and \fBp\fR means printers points (1/72 inch).
174
Larger y-coordinates refer to points lower on the screen; larger
175
x-coordinates refer to points farther to the right.
179
Normally the origin of the canvas coordinate system is at the
180
upper-left corner of the window containing the canvas.
181
It is possible to adjust the origin of the canvas
182
coordinate system relative to the origin of the window using the
183
\fBxview\fR and \fByview\fR widget commands; this is typically used
185
Canvases do not support scaling or rotation of the canvas coordinate
186
system relative to the window coordinate system.
188
Individual items may be moved or scaled using widget commands
189
described below, but they may not be rotated.
193
Text items support the notion of an \fIindex\fR for identifying
194
particular positions within the item.
195
Indices are used for commands such as inserting text, deleting
196
a range of characters, and setting the insertion cursor position.
197
An index may be specified in any of a number of ways, and
198
different types of items may support different forms for
200
Text items support the following forms for an index; if you
201
define new types of text-like items, it would be advisable to
202
support as many of these forms as practical.
203
Note that it is possible to refer to the character just after
204
the last one in the text item; this is necessary for such
205
tasks as inserting new text at the end of the item.
208
A decimal number giving the position of the desired character
209
within the text item.
210
0 refers to the first character, 1 to the next character, and
212
A number less than 0 is treated as if it were zero, and a
213
number greater than the length of the text item is treated
214
as if it were equal to the length of the text item.
217
Refers to the character just after the last one in the item
218
(same as the number of characters in the item).
221
Refers to the character just before which the insertion cursor
222
is drawn in this item.
225
Refers to the first selected character in the item.
226
If the selection isn't in this item then this form is illegal.
229
Refers to the last selected character in the item.
230
If the selection isn't in this item then this form is illegal.
233
Refers to the character at the point given by \fIx\fR and
234
\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate
235
system of the canvas.
236
If \fIx\fR and \fIy\fR lie outside the coordinates covered by the
237
text item, then they refer to the first or last character in the
238
line that is closest to the given point.
242
The \fBcanvas\fR command creates a new Tcl command whose
243
name is \fIpathName\fR. This
244
command may be used to invoke various
245
operations on the widget. It has the following general form:
247
\fIpathName option \fR?\fIarg arg ...\fR?
249
\fIOption\fR and the \fIarg\fRs
250
determine the exact behavior of the command.
251
The following widget commands are possible for canvas widgets:
253
\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR?
254
For each item that meets the constraints specified by
255
\fIsearchSpec\fR and the \fIarg\fRs, add
256
\fItag\fR to the list of tags associated with the item if it
257
isn't already present on that list.
258
It is possible that no items will satisfy the constraints
259
given by \fIsearchSpec\fR and \fIarg\fRs, in which case the
260
command has no effect.
261
This command returns an empty string as result.
262
\fISearchSpec\fR and \fIarg\fR's may take any of the following
266
\fBabove \fItagOrId\fR
267
Selects the item just after (above) the one given by \fItagOrId\fR
269
If \fItagOrId\fR denotes more than one item, then the last (topmost)
270
of these items in the display list is used.
273
Selects all the items in the canvas.
275
\fBbelow \fItagOrId\fR
276
Selects the item just before (below) the one given by \fItagOrId\fR
278
If \fItagOrId\fR denotes more than one item, then the first (lowest)
279
of these items in the display list is used.
281
\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?
282
Selects the item closest to the point given by \fIx\fR and \fIy\fR.
283
If more than one item is at the same closest distance (e.g. two
284
items overlap the point), then the top-most of these items (the
285
last one in the display list) is used.
286
If \fIhalo\fR is specified, then it must be a non-negative
288
Any item closer than \fIhalo\fR to the point is considered to
290
The \fIstart\fR argument may be used to step circularly through
291
all the closest items.
292
If \fIstart\fR is specified, it names an item using a tag or id
293
(if by tag, it selects the first item in the display list with
295
Instead of selecting the topmost closest item, this form will
296
select the topmost closest item that is below \fIstart\fR in
297
the display list; if no such item exists, then the selection
298
behaves as if the \fIstart\fR argument had not been specified.
300
\fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
301
Selects all the items completely enclosed within the rectangular
302
region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
303
\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be
304
no greater than \fIy2\fR.
306
\fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
307
Selects all the items that overlap or are enclosed within the
308
rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR,
310
\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be
311
no greater than \fIy2\fR.
313
\fBwithtag \fItagOrId\fR
314
Selects all the items given by \fItagOrId\fR.
317
\fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR?
318
Returns a list with four elements giving an approximate bounding box
319
for all the items named by the \fItagOrId\fR arguments.
320
The list has the form ``\fIx1 y1 x2 y2\fR'' such that the drawn
321
areas of all the named elements are within the region bounded by
322
\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top,
323
and \fIy2\fR on the bottom.
324
The return value may overestimate the actual bounding box by
326
If no items match any of the \fItagOrId\fR arguments or if the
327
matching items have empty bounding boxes (i.e. they have nothing
329
then an empty string is returned.
331
\fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR?
332
This command associates \fIcommand\fR with all the items given by
333
\fItagOrId\fR such that whenever the event sequence given by
334
\fIsequence\fR occurs for one of the items the command will
336
This widget command is similar to the \fBbind\fR command except that
337
it operates on items in a canvas rather than entire widgets.
338
See the \fBbind\fR manual entry for complete details
339
on the syntax of \fIsequence\fR and the substitutions performed
340
on \fIcommand\fR before invoking it.
341
If all arguments are specified then a new binding is created, replacing
342
any existing binding for the same \fIsequence\fR and \fItagOrId\fR
343
(if the first character of \fIcommand\fR is ``+'' then \fIcommand\fR
344
augments an existing binding rather than replacing it).
345
In this case the return value is an empty string.
346
If \fIcommand\fR is omitted then the command returns the \fIcommand\fR
347
associated with \fItagOrId\fR and \fIsequence\fR (an error occurs
348
if there is no such binding).
349
If both \fIcommand\fR and \fIsequence\fR are omitted then the command
350
returns a list of all the sequences for which bindings have been
351
defined for \fItagOrId\fR.
355
The only events for which bindings may be specified are those related to
356
the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR,
357
\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events.
358
The handling of events in canvases uses the current item defined in ITEM
359
IDS AND TAGS above. \fBEnter\fR and \fBLeave\fR events trigger for an
360
item when it becomes the current item or ceases to be the current item;
361
note that these events are different than \fBEnter\fR and \fBLeave\fR
362
events for windows. Mouse-related events are directed to the current
363
item, if any. Keyboard-related events are directed to the focus item, if
364
any (see the \fBfocus\fR widget command below for more on this). If a
365
virtual event is used in a binding, that binding can trigger only if the
366
virtual event is defined by an underlying mouse-related or
367
keyboard-related event.
370
It is possible for multiple bindings to match a particular event.
371
This could occur, for example, if one binding is associated with the
372
item's id and another is associated with one of the item's tags.
373
When this occurs, all of the matching bindings are invoked.
374
A binding associated with the \fBall\fR tag is invoked first,
375
followed by one binding for each of the item's tags (in order),
376
followed by a binding associated with the item's id.
377
If there are multiple matching bindings for a single tag,
378
then only the most specific binding is invoked.
379
A \fBcontinue\fR command in a binding script terminates that
380
script, and a \fBbreak\fR command terminates that script
381
and skips any remaining scripts for the event, just as for the
384
If bindings have been created for a canvas window using the \fBbind\fR
385
command, then they are invoked in addition to bindings created for
386
the canvas's items using the \fBbind\fR widget command.
387
The bindings for items will be invoked before any of the bindings
388
for the window as a whole.
391
\fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR?
392
Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns
393
the canvas x-coordinate that is displayed at that location.
394
If \fIgridspacing\fR is specified, then the canvas coordinate is
395
rounded to the nearest multiple of \fIgridspacing\fR units.
397
\fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR?
398
Given a window y-coordinate in the canvas \fIscreeny\fR this command returns
399
the canvas y-coordinate that is displayed at that location.
400
If \fIgridspacing\fR is specified, then the canvas coordinate is
401
rounded to the nearest multiple of \fIgridspacing\fR units.
403
\fIpathName \fBcget\fR \fIoption\fR
404
Returns the current value of the configuration option given
406
\fIOption\fR may have any of the values accepted by the \fBcanvas\fR
409
\fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
410
Query or modify the configuration options of the widget.
411
If no \fIoption\fR is specified, returns a list describing all of
412
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
413
information on the format of this list). If \fIoption\fR is specified
414
with no \fIvalue\fR, then the command returns a list describing the
415
one named option (this list will be identical to the corresponding
416
sublist of the value returned if no \fIoption\fR is specified). If
417
one or more \fIoption\-value\fR pairs are specified, then the command
418
modifies the given widget option(s) to have the given value(s); in
419
this case the command returns an empty string.
420
\fIOption\fR may have any of the values accepted by the \fBcanvas\fR
423
\fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR?
424
Query or modify the coordinates that define an item.
425
If no coordinates are specified, this command returns a list
426
whose elements are the coordinates of the item named by
428
If coordinates are specified, then they replace the current
429
coordinates for the named item.
430
If \fItagOrId\fR refers to multiple items, then
431
the first one in the display list is used.
433
\fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR?
434
Create a new item in \fIpathName\fR of type \fItype\fR.
435
The exact format of the arguments after \fBtype\fR depends
436
on \fBtype\fR, but usually they consist of the coordinates for
437
one or more points, followed by specifications for zero or
439
See the subsections on individual item types below for more
440
on the syntax of this command.
441
This command returns the id for the new item.
443
\fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR?
444
For each item given by \fItagOrId\fR, delete the characters
445
in the range given by \fIfirst\fR and \fIlast\fR,
447
If some of the items given by \fItagOrId\fR don't support
448
text operations, then they are ignored.
449
\fIFirst\fR and \fIlast\fR are indices of characters
450
within the item(s) as described in INDICES above.
451
If \fIlast\fR is omitted, it defaults to \fIfirst\fR.
452
This command returns an empty string.
454
\fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR?
455
Delete each of the items given by each \fItagOrId\fR, and return
458
\fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR?
459
For each of the items given by \fItagOrId\fR, delete the
460
tag given by \fItagToDelete\fR from the list of those
461
associated with the item.
462
If an item doesn't have the tag \fItagToDelete\fR then
463
the item is unaffected by the command.
464
If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR.
465
This command returns an empty string.
467
\fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR?
468
This command returns a list consisting of all the items that
469
meet the constraints specified by \fIsearchCommand\fR and
471
\fISearchCommand\fR and \fIargs\fR have any of the forms
472
accepted by the \fBaddtag\fR command.
473
The items are returned in stacking order, with the lowest item first.
475
\fIpathName \fBfocus \fR?\fItagOrId\fR?
476
Set the keyboard focus for the canvas widget to the item given by
478
If \fItagOrId\fR refers to several items, then the focus is set
479
to the first such item in the display list that supports the
481
If \fItagOrId\fR doesn't refer to any items, or if none of them
482
support the insertion cursor, then the focus isn't changed.
483
If \fItagOrId\fR is an empty
484
string, then the focus item is reset so that no item has the focus.
485
If \fItagOrId\fR is not specified then the command returns the
486
id for the item that currently has the focus, or an empty string
487
if no item has the focus.
490
Once the focus has been set to an item, the item will display
491
the insertion cursor and all keyboard events will be directed
493
The focus item within a canvas and the focus window on the
494
screen (set with the \fBfocus\fR command) are totally independent:
495
a given item doesn't actually have the input focus unless (a)
496
its canvas is the focus window and (b) the item is the focus item
498
In most cases it is advisable to follow the \fBfocus\fR widget
499
command with the \fBfocus\fR command to set the focus window to
500
the canvas (if it wasn't there already).
503
\fIpathName \fBgettags\fR \fItagOrId\fR
504
Return a list whose elements are the tags associated with the
505
item given by \fItagOrId\fR.
506
If \fItagOrId\fR refers to more than one item, then the tags
507
are returned from the first such item in the display list.
508
If \fItagOrId\fR doesn't refer to any items, or if the item
509
contains no tags, then an empty string is returned.
511
\fIpathName \fBicursor \fItagOrId index\fR
512
Set the position of the insertion cursor for the item(s)
513
given by \fItagOrId\fR
514
to just before the character whose position is given by \fIindex\fR.
515
If some or all of the items given by \fItagOrId\fR don't support
516
an insertion cursor then this command has no effect on them.
517
See INDICES above for a description of the
518
legal forms for \fIindex\fR.
519
Note: the insertion cursor is only displayed in an item if
520
that item currently has the keyboard focus (see the widget
521
command \fBfocus\fR, below), but the cursor position may
522
be set even when the item doesn't have the focus.
523
This command returns an empty string.
525
\fIpathName \fBindex \fItagOrId index\fR
526
This command returns a decimal string giving the numerical index
527
within \fItagOrId\fR corresponding to \fIindex\fR.
528
\fIIndex\fR gives a textual description of the desired position
529
as described in INDICES above.
530
The return value is guaranteed to lie between 0 and the number
531
of characters within the item, inclusive.
532
If \fItagOrId\fR refers to multiple items, then the index
533
is processed in the first of these items that supports indexing
534
operations (in display list order).
536
\fIpathName \fBinsert \fItagOrId beforeThis string\fR
537
For each of the items given by \fItagOrId\fR, if the item supports
538
text insertion then \fIstring\fR is inserted into the item's
539
text just before the character whose index is \fIbeforeThis\fR.
540
See INDICES above for information about the forms allowed
541
for \fIbeforeThis\fR.
542
This command returns an empty string.
544
\fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR
545
Returns the current value of the configuration option for the
546
item given by \fItagOrId\fR whose name is \fIoption\fR.
547
This command is similar to the \fBcget\fR widget command except that
548
it applies to a particular item rather than the widget as a whole.
549
\fIOption\fR may have any of the values accepted by the \fBcreate\fR
550
widget command when the item was created.
551
If \fItagOrId\fR is a tag that refers to more than one item,
552
the first (lowest) such item is used.
554
\fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
555
This command is similar to the \fBconfigure\fR widget command except
556
that it modifies item-specific options for the items given by
557
\fItagOrId\fR instead of modifying options for the overall
559
If no \fIoption\fR is specified, returns a list describing all of
560
the available options for the first item given by \fItagOrId\fR
561
(see \fBTk_ConfigureInfo\fR for
562
information on the format of this list). If \fIoption\fR is specified
563
with no \fIvalue\fR, then the command returns a list describing the
564
one named option (this list will be identical to the corresponding
565
sublist of the value returned if no \fIoption\fR is specified). If
566
one or more \fIoption\-value\fR pairs are specified, then the command
567
modifies the given widget option(s) to have the given value(s) in
568
each of the items given by \fItagOrId\fR; in
569
this case the command returns an empty string.
570
The \fIoption\fRs and \fIvalue\fRs are the same as those permissible
571
in the \fBcreate\fR widget command when the item(s) were created;
572
see the sections describing individual item types below for details
573
on the legal options.
575
\fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR?
576
Move all of the items given by \fItagOrId\fR to a new position
577
in the display list just before the item given by \fIbelowThis\fR.
578
If \fItagOrId\fR refers to more than one item then all are moved
579
but the relative order of the moved items will not be changed.
580
\fIBelowThis\fR is a tag or id; if it refers to more than one
581
item then the first (lowest) of these items in the display list is used
582
as the destination location for the moved items.
583
Note: this command has no effect on window items. Window items always
584
obscure other item types, and the stacking order of window items is
585
determined by the \fBraise\fR and \fBlower\fR commands, not the
586
\fBraise\fR and \fBlower\fR widget commands for canvases.
587
This command returns an empty string.
589
\fIpathName \fBmove \fItagOrId xAmount yAmount\fR
590
Move each of the items given by \fItagOrId\fR in the canvas coordinate
591
space by adding \fIxAmount\fR to the x-coordinate of each point
592
associated with the item and \fIyAmount\fR to the y-coordinate of
593
each point associated with the item.
594
This command returns an empty string.
596
\fIpathName \fBpostscript \fR?\fIoption value option value ...\fR?
597
Generate a Postscript representation for part or all of the canvas.
598
If the \fB\-file\fR option is specified then the Postscript is written
599
to a file and an empty string is returned; otherwise the Postscript
600
is returned as the result of the command.
602
If the interpreter that owns the canvas is marked as safe, the operation
603
will fail because safe interpreters are not allowed to write files.
604
If the \fB\-channel\fR option is specified, the argument denotes the name
605
of a channel already opened for writing. The Postscript is written to
606
that channel, and the channel is left open for further writing at the end
609
The Postscript is created in Encapsulated Postscript form using
610
version 3.0 of the Document Structuring Conventions.
611
Note: by default Postscript is only generated for information that
612
appears in the canvas's window on the screen. If the canvas is
613
freshly created it may still have its initial size of 1x1 pixel
614
so nothing will appear in the Postscript. To get around this problem
615
either invoke the "update" command to wait for the canvas window
616
to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR
617
options to specify the area of the canvas to print.
618
The \fIoption\fR\-\fIvalue\fR argument pairs provide additional
619
information to control the generation of Postscript. The following
620
options are supported:
623
\fB\-colormap \fIvarName\fR
624
\fIVarName\fR must be the name of an array variable
625
that specifies a color mapping to use in the Postscript.
626
Each element of \fIvarName\fR must consist of Postscript
627
code to set a particular color value (e.g. ``\fB1.0 1.0 0.0 setrgbcolor\fR'').
628
When outputting color information in the Postscript, Tk checks
629
to see if there is an element of \fIvarName\fR with the same
631
If so, Tk uses the value of the element as the Postscript command
633
If this option hasn't been specified, or if there isn't an entry
634
in \fIvarName\fR for a given color, then Tk uses the red, green,
635
and blue intensities from the X color.
637
\fB\-colormode \fImode\fR
638
Specifies how to output color information. \fIMode\fR must be either
639
\fBcolor\fR (for full color output), \fBgray\fR (convert all colors
640
to their gray-scale equivalents) or \fBmono\fR (convert all colors
643
\fB\-file \fIfileName\fR
644
Specifies the name of the file in which to write the Postscript.
645
If this option isn't specified then the Postscript is returned as the
646
result of the command instead of being written to a file.
648
\fB\-fontmap \fIvarName\fR
649
\fIVarName\fR must be the name of an array variable
650
that specifies a font mapping to use in the Postscript.
651
Each element of \fIvarName\fR must consist of a Tcl list with
652
two elements, which are the name and point size of a Postscript font.
653
When outputting Postscript commands for a particular font, Tk
654
checks to see if \fIvarName\fR contains an element with the same
656
If there is such an element, then the font information contained in
657
that element is used in the Postscript.
658
Otherwise Tk attempts to guess what Postscript font to use.
659
Tk's guesses generally only work for well-known fonts such as
660
Times and Helvetica and Courier, and only if the X font name does not
661
omit any dashes up through the point size.
662
For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but
663
\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to
664
parse the font name).
666
\fB\-height \fIsize\fR
667
Specifies the height of the area of the canvas to print.
668
Defaults to the height of the canvas window.
670
\fB\-pageanchor \fIanchor\fR
671
Specifies which point of the printed area of the canvas should appear over
672
the positioning point on the page (which is given by the \fB\-pagex\fR
673
and \fB\-pagey\fR options).
674
For example, \fB\-pageanchor n\fR means that the top center of the
675
area of the canvas being printed (as it appears in the canvas window)
676
should be over the positioning point. Defaults to \fBcenter\fR.
678
\fB\-pageheight \fIsize\fR
679
Specifies that the Postscript should be scaled in both x and y so
680
that the printed area is \fIsize\fR high on the Postscript page.
681
\fISize\fR consists of a floating-point number followed by
682
\fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters,
683
or \fBp\fR or nothing for printer's points (1/72 inch).
684
Defaults to the height of the printed area on the screen.
685
If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then
686
the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling
689
\fB\-pagewidth \fIsize\fR
690
Specifies that the Postscript should be scaled in both x and y so
691
that the printed area is \fIsize\fR wide on the Postscript page.
692
\fISize\fR has the same form as for \fB\-pageheight\fR.
693
Defaults to the width of the printed area on the screen.
694
If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then
695
the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling
698
\fB\-pagex \fIposition\fR
699
\fIPosition\fR gives the x-coordinate of the positioning point on
700
the Postscript page, using any of the forms allowed for \fB\-pageheight\fR.
701
Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options
702
to determine where the printed area appears on the Postscript page.
703
Defaults to the center of the page.
705
\fB\-pagey \fIposition\fR
706
\fIPosition\fR gives the y-coordinate of the positioning point on
707
the Postscript page, using any of the forms allowed for \fB\-pageheight\fR.
708
Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options
709
to determine where the printed area appears on the Postscript page.
710
Defaults to the center of the page.
712
\fB\-rotate \fIboolean\fR
713
\fIBoolean\fR specifies whether the printed area is to be rotated 90
715
In non-rotated output the x-axis of the printed area runs along
716
the short dimension of the page (``portrait'' orientation);
717
in rotated output the x-axis runs along the long dimension of the
718
page (``landscape'' orientation).
719
Defaults to non-rotated.
721
\fB\-width \fIsize\fR
722
Specifies the width of the area of the canvas to print.
723
Defaults to the width of the canvas window.
725
\fB\-x \fIposition\fR
726
Specifies the x-coordinate of the left edge of the area of the
727
canvas that is to be printed, in canvas coordinates, not window
729
Defaults to the coordinate of the left edge of the window.
731
\fB\-y \fIposition\fR
732
Specifies the y-coordinate of the top edge of the area of the
733
canvas that is to be printed, in canvas coordinates, not window
735
Defaults to the coordinate of the top edge of the window.
738
\fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR?
739
Move all of the items given by \fItagOrId\fR to a new position
740
in the display list just after the item given by \fIaboveThis\fR.
741
If \fItagOrId\fR refers to more than one item then all are moved
742
but the relative order of the moved items will not be changed.
743
\fIAboveThis\fR is a tag or id; if it refers to more than one
744
item then the last (topmost) of these items in the display list is used
745
as the destination location for the moved items.
746
Note: this command has no effect on window items. Window items always
747
obscure other item types, and the stacking order of window items is
748
determined by the \fBraise\fR and \fBlower\fR commands, not the
749
\fBraise\fR and \fBlower\fR widget commands for canvases.
750
This command returns an empty string.
752
\fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR
753
Rescale all of the items given by \fItagOrId\fR in canvas coordinate
755
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling
756
operation and \fIxScale\fR and \fIyScale\fR identify the scale
757
factors for x- and y-coordinates, respectively (a scale factor of
758
1.0 implies no change to that coordinate).
759
For each of the points defining each item, the x-coordinate is
760
adjusted to change the distance from \fIxOrigin\fR by a factor
762
Similarly, each y-coordinate is adjusted to change the distance
763
from \fIyOrigin\fR by a factor of \fIyScale\fR.
764
This command returns an empty string.
766
\fIpathName \fBscan\fR \fIoption args\fR
767
This command is used to implement scanning on canvases. It has
768
two forms, depending on \fIoption\fR:
771
\fIpathName \fBscan mark \fIx y\fR
772
Records \fIx\fR and \fIy\fR and the canvas's current view; used
773
in conjunction with later \fBscan dragto\fR commands.
774
Typically this command is associated with a mouse button press in
775
the widget and \fIx\fR and \fIy\fR are the coordinates of the
776
mouse. It returns an empty string.
778
\fIpathName \fBscan dragto \fIx y\fR.
779
This command computes the difference between its \fIx\fR and \fIy\fR
780
arguments (which are typically mouse coordinates) and the \fIx\fR and
781
\fIy\fR arguments to the last \fBscan mark\fR command for the widget.
782
It then adjusts the view by 10 times the
783
difference in coordinates. This command is typically associated
784
with mouse motion events in the widget, to produce the effect of
785
dragging the canvas at high speed through its window. The return
786
value is an empty string.
789
\fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR?
790
Manipulates the selection in one of several ways, depending on
792
The command may take any of the forms described below.
793
In all of the descriptions below, \fItagOrId\fR must refer to
794
an item that supports indexing and selection; if it refers to
795
multiple items then the first of
796
these that supports indexing and the selection is used.
797
\fIIndex\fR gives a textual description of a position
798
within \fItagOrId\fR, as described in INDICES above.
801
\fIpathName \fBselect adjust \fItagOrId index\fR
802
Locate the end of the selection in \fItagOrId\fR nearest
803
to the character given by \fIindex\fR, and adjust that
804
end of the selection to be at \fIindex\fR (i.e. including
805
but not going beyond \fIindex\fR).
806
The other end of the selection is made the anchor point
807
for future \fBselect to\fR commands.
808
If the selection isn't currently in \fItagOrId\fR then
809
this command behaves the same as the \fBselect to\fR widget
811
Returns an empty string.
813
\fIpathName \fBselect clear\fR
814
Clear the selection if it is in this widget.
815
If the selection isn't in this widget then the command
817
Returns an empty string.
819
\fIpathName \fBselect from \fItagOrId index\fR
820
Set the selection anchor point for the widget to be just
822
given by \fIindex\fR in the item given by \fItagOrId\fR.
823
This command doesn't change the selection; it just sets
824
the fixed end of the selection for future \fBselect to\fR
826
Returns an empty string.
828
\fIpathName \fBselect item\fR
829
Returns the id of the selected item, if the selection is in an
831
If the selection is not in this canvas then an empty string
834
\fIpathName \fBselect to \fItagOrId index\fR
835
Set the selection to consist of those characters of \fItagOrId\fR
836
between the selection anchor point and
838
The new selection will include the character given by \fIindex\fR;
839
it will include the character given by the anchor point only if
840
\fIindex\fR is greater than or equal to the anchor point.
841
The anchor point is determined by the most recent \fBselect adjust\fR
842
or \fBselect from\fR command for this widget.
843
If the selection anchor point for the widget isn't currently in
844
\fItagOrId\fR, then it is set to the same character given
846
Returns an empty string.
849
\fIpathName \fBtype\fI tagOrId\fR
850
Returns the type of the item given by \fItagOrId\fR, such as
851
\fBrectangle\fR or \fBtext\fR.
852
If \fItagOrId\fR refers to more than one item, then the type
853
of the first item in the display list is returned.
854
If \fItagOrId\fR doesn't refer to any items at all then
855
an empty string is returned.
857
\fIpathName \fBxview \fR?\fIargs\fR?
858
This command is used to query and change the horizontal position of the
859
information displayed in the canvas's window.
860
It can take any of the following forms:
863
\fIpathName \fBxview\fR
864
Returns a list containing two elements.
865
Each element is a real fraction between 0 and 1; together they describe
866
the horizontal span that is visible in the window.
867
For example, if the first element is .2 and the second element is .6,
868
20% of the canvas's area (as defined by the \fB\-scrollregion\fR option)
869
is off-screen to the left, the middle 40% is visible
870
in the window, and 40% of the canvas is off-screen to the right.
871
These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR
874
\fIpathName \fBxview moveto\fI fraction\fR
875
Adjusts the view in the window so that \fIfraction\fR of the
876
total width of the canvas is off-screen to the left.
877
\fIFraction\fR must be a fraction between 0 and 1.
879
\fIpathName \fBxview scroll \fInumber what\fR
880
This command shifts the view in the window left or right according to
881
\fInumber\fR and \fIwhat\fR.
882
\fINumber\fR must be an integer.
883
\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation
885
If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units
886
of the \fBxScrollIncrement\fR option, if it is greater than zero,
887
or in units of one-tenth the window's width otherwise.
888
If \fIwhat is \fBpages\fR then the view
889
adjusts in units of nine-tenths the window's width.
890
If \fInumber\fR is negative then information farther to the left
891
becomes visible; if it is positive then information farther to the right
895
\fIpathName \fByview \fI?args\fR?
896
This command is used to query and change the vertical position of the
897
information displayed in the canvas's window.
898
It can take any of the following forms:
901
\fIpathName \fByview\fR
902
Returns a list containing two elements.
903
Each element is a real fraction between 0 and 1; together they describe
904
the vertical span that is visible in the window.
905
For example, if the first element is .6 and the second element is 1.0,
906
the lowest 40% of the canvas's area (as defined by the \fB\-scrollregion\fR
907
option) is visible in the window.
908
These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR
911
\fIpathName \fByview moveto\fI fraction\fR
912
Adjusts the view in the window so that \fIfraction\fR of the canvas's
913
area is off-screen to the top.
914
\fIFraction\fR is a fraction between 0 and 1.
916
\fIpathName \fByview scroll \fInumber what\fR
917
This command adjusts the view in the window up or down according to
918
\fInumber\fR and \fIwhat\fR.
919
\fINumber\fR must be an integer.
920
\fIWhat\fR must be either \fBunits\fR or \fBpages\fR.
921
If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units
922
of the \fByScrollIncrement\fR option, if it is greater than zero,
923
or in units of one-tenth the window's height otherwise.
924
If \fIwhat\fR is \fBpages\fR then
925
the view adjusts in units of nine-tenths the window's height.
926
If \fInumber\fR is negative then higher information becomes
927
visible; if it is positive then lower information
931
.SH "OVERVIEW OF ITEM TYPES"
933
The sections below describe the various types of items supported
934
by canvas widgets. Each item type is characterized by two things:
935
first, the form of the \fBcreate\fR command used to create
936
instances of the type; and second, a set of configuration options
937
for items of that type, which may be used in the
938
\fBcreate\fR and \fBitemconfigure\fR widget commands.
939
Most items don't support indexing or selection or the commands
940
related to them, such as \fBindex\fR and \fBinsert\fR.
941
Where items do support these facilities, it is noted explicitly
942
in the descriptions below (at present, only text items provide
947
Items of type \fBarc\fR appear on the display as arc-shaped regions.
948
An arc is a section of an oval delimited by two angles (specified
949
by the \fB\-start\fR and \fB\-extent\fR options) and displayed in
950
one of several ways (specified by the \fB\-style\fR option).
951
Arcs are created with widget commands of the following form:
953
\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
955
The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
956
the coordinates of two diagonally opposite corners of a
957
rectangular region enclosing the oval that defines the arc.
958
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
959
pairs, each of which sets one of the configuration options
960
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
961
used in \fBitemconfigure\fR widget commands to change the item's
963
The following options are supported for arcs:
965
\fB\-extent \fIdegrees\fR
966
Specifies the size of the angular range occupied by the arc.
967
The arc's range extends for \fIdegrees\fR degrees counter-clockwise
968
from the starting angle given by the \fB\-start\fR option.
969
\fIDegrees\fR may be negative.
970
If it is greater than 360 or less than -360, then \fIdegrees\fR
971
modulo 360 is used as the extent.
973
\fB\-fill \fIcolor\fR
974
Fill the region of the arc with \fIcolor\fR.
975
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
976
If \fIcolor\fR is an empty string (the default), then
977
then the arc will not be filled.
979
\fB\-outline \fIcolor\fR
980
\fIColor\fR specifies a color to use for drawing the arc's
981
outline; it may have any of the forms accepted by \fBTk_GetColor\fR.
982
This option defaults to \fBblack\fR. If \fIcolor\fR is specified
983
as an empty string then no outline is drawn for the arc.
985
\fB\-outlinestipple \fIbitmap\fR
986
Indicates that the outline for the arc should be drawn with a stipple pattern;
987
\fIbitmap\fR specifies the stipple pattern to use, in any of the
988
forms accepted by \fBTk_GetBitmap\fR.
989
If the \fB\-outline\fR option hasn't been specified then this option
991
If \fIbitmap\fR is an empty string (the default), then the outline is drawn
994
\fB\-start \fIdegrees\fR
995
Specifies the beginning of the angular range occupied by the
997
\fIDegrees\fR is given in units of degrees measured counter-clockwise
998
from the 3-o'clock position; it may be either positive or negative.
1000
\fB\-stipple \fIbitmap\fR
1001
Indicates that the arc should be filled in a stipple pattern;
1002
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1003
forms accepted by \fBTk_GetBitmap\fR.
1004
If the \fB\-fill\fR option hasn't been specified then this option
1006
If \fIbitmap\fR is an empty string (the default), then filling is done
1009
\fB\-style \fItype\fR
1010
Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR
1011
(the default) then the arc's region is defined by a section
1012
of the oval's perimeter plus two line segments, one between the center
1013
of the oval and each end of the perimeter section.
1014
If \fItype\fR is \fBchord\fR then the arc's region is defined
1015
by a section of the oval's perimeter plus a single line segment
1016
connecting the two end points of the perimeter section.
1017
If \fItype\fR is \fBarc\fR then the arc's region consists of
1018
a section of the perimeter alone.
1019
In this last case the \fB\-fill\fR option is ignored.
1021
\fB\-tags \fItagList\fR
1022
Specifies a set of tags to apply to the item.
1023
\fITagList\fR consists of a list of tag names, which replace any
1024
existing tags for the item.
1025
\fITagList\fR may be an empty list.
1027
\fB\-width \fIoutlineWidth\fR
1028
Specifies the width of the outline to be drawn around
1029
the arc's region, in any of the forms described in the COORDINATES
1031
If the \fB\-outline\fR option has been specified as an empty string
1032
then this option has no effect.
1033
Wide outlines will be drawn centered on the edges of the arc's region.
1034
This option defaults to 1.0.
1038
Items of type \fBbitmap\fR appear on the display as images with
1039
two colors, foreground and background.
1040
Bitmaps are created with widget commands of the following form:
1042
\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR?
1044
The arguments \fIx\fR and \fIy\fR specify the coordinates of a
1045
point used to position the bitmap on the display (see the \fB\-anchor\fR
1046
option below for more information on how bitmaps are displayed).
1047
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1048
pairs, each of which sets one of the configuration options
1049
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1050
used in \fBitemconfigure\fR widget commands to change the item's
1052
The following options are supported for bitmaps:
1054
\fB\-anchor \fIanchorPos\fR
1055
\fIAnchorPos\fR tells how to position the bitmap relative to the
1056
positioning point for the item; it may have any of the forms
1057
accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR
1058
is \fBcenter\fR then the bitmap is centered on the point; if
1059
\fIanchorPos\fR is \fBn\fR then the bitmap will be drawn so that
1060
its top center point is at the positioning point.
1061
This option defaults to \fBcenter\fR.
1063
\fB\-background \fIcolor\fR
1064
Specifies a color to use for each of the bitmap pixels
1066
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
1067
If this option isn't specified, or if it is specified as an empty
1068
string, then nothing is displayed where the bitmap pixels are 0; this
1069
produces a transparent effect.
1071
\fB\-bitmap \fIbitmap\fR
1072
Specifies the bitmap to display in the item.
1073
\fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR.
1075
\fB\-foreground \fIcolor\fR
1076
Specifies a color to use for each of the bitmap pixels
1078
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and
1079
defaults to \fBblack\fR.
1081
\fB\-tags \fItagList\fR
1082
Specifies a set of tags to apply to the item.
1083
\fITagList\fR consists of a list of tag names, which replace any
1084
existing tags for the item.
1085
\fITagList\fR may be an empty list.
1089
Items of type \fBimage\fR are used to display images on a
1091
Images are created with widget commands of the following form:
1093
\fIpathName \fBcreate image \fIx y \fR?\fIoption value option value ...\fR?
1095
The arguments \fIx\fR and \fIy\fR specify the coordinates of a
1096
point used to position the image on the display (see the \fB\-anchor\fR
1097
option below for more information).
1098
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1099
pairs, each of which sets one of the configuration options
1100
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1101
used in \fBitemconfigure\fR widget commands to change the item's
1103
The following options are supported for images:
1105
\fB\-anchor \fIanchorPos\fR
1106
\fIAnchorPos\fR tells how to position the image relative to the
1107
positioning point for the item; it may have any of the forms
1108
accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR
1109
is \fBcenter\fR then the image is centered on the point; if
1110
\fIanchorPos\fR is \fBn\fR then the image will be drawn so that
1111
its top center point is at the positioning point.
1112
This option defaults to \fBcenter\fR.
1114
\fB\-image \fIname\fR
1115
Specifies the name of the image to display in the item.
1116
This image must have been created previously with the
1117
\fBimage create\fR command.
1119
\fB\-tags \fItagList\fR
1120
Specifies a set of tags to apply to the item.
1121
\fITagList\fR consists of a list of tag names, which replace any
1122
existing tags for the item; it may be an empty list.
1126
Items of type \fBline\fR appear on the display as one or more connected
1127
line segments or curves.
1128
Lines are created with widget commands of the following form:
1130
\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR?
1132
The arguments \fIx1\fR through \fIyn\fR give
1133
the coordinates for a series of two or more points that describe
1134
a series of connected line segments.
1135
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1136
pairs, each of which sets one of the configuration options
1137
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1138
used in \fBitemconfigure\fR widget commands to change the item's
1140
The following options are supported for lines:
1142
\fB\-arrow \fIwhere\fR
1143
Indicates whether or not arrowheads are to be drawn at one or both
1145
\fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads),
1146
\fBfirst\fR (for an arrowhead at the first point of the line),
1147
\fBlast\fR (for an arrowhead at the last point of the line), or
1148
\fBboth\fR (for arrowheads at both ends).
1149
This option defaults to \fBnone\fR.
1151
\fB\-arrowshape \fIshape\fR
1152
This option indicates how to draw arrowheads.
1153
The \fIshape\fR argument must be a list with three elements, each
1154
specifying a distance in any of the forms described in
1155
the COORDINATES section above.
1156
The first element of the list gives the distance along the line
1157
from the neck of the arrowhead to its tip.
1158
The second element gives the distance along the line from the
1159
trailing points of the arrowhead to the tip, and the third
1160
element gives the distance from the outside edge of the line to the
1162
If this option isn't specified then Tk picks a ``reasonable'' shape.
1164
\fB\-capstyle \fIstyle\fR
1165
Specifies the ways in which caps are to be drawn at the endpoints
1167
\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR
1168
(\fBbutt\fR, \fBprojecting\fR, or \fBround\fR).
1169
If this option isn't specified then it defaults to \fBbutt\fR.
1170
Where arrowheads are drawn the cap style is ignored.
1172
\fB\-fill \fIcolor\fR
1173
\fIColor\fR specifies a color to use for drawing the line; it may have
1174
any of the forms acceptable to \fBTk_GetColor\fR. It may also be an
1175
empty string, in which case the line will be transparent.
1176
This option defaults to \fBblack\fR.
1178
\fB\-joinstyle \fIstyle\fR
1179
Specifies the ways in which joints are to be drawn at the vertices
1181
\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR
1182
(\fBbevel\fR, \fBmiter\fR, or \fBround\fR).
1183
If this option isn't specified then it defaults to \fBmiter\fR.
1184
If the line only contains two points then this option is
1187
\fB\-smooth \fIboolean\fR
1188
\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR.
1189
It indicates whether or not the line should be drawn as a curve.
1190
If so, the line is rendered as a set of parabolic splines: one spline
1191
is drawn for the first and second line segments, one for the second
1192
and third, and so on. Straight-line segments can be generated within
1193
a curve by duplicating the end-points of the desired line segment.
1195
\fB\-splinesteps \fInumber\fR
1196
Specifies the degree of smoothness desired for curves: each spline
1197
will be approximated with \fInumber\fR line segments. This
1198
option is ignored unless the \fB\-smooth\fR option is true.
1200
\fB\-stipple \fIbitmap\fR
1201
Indicates that the line should be filled in a stipple pattern;
1202
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1203
forms accepted by \fBTk_GetBitmap\fR.
1204
If \fIbitmap\fR is an empty string (the default), then filling is
1205
done in a solid fashion.
1207
\fB\-tags \fItagList\fR
1208
Specifies a set of tags to apply to the item.
1209
\fITagList\fR consists of a list of tag names, which replace any
1210
existing tags for the item.
1211
\fITagList\fR may be an empty list.
1213
\fB\-width \fIlineWidth\fR
1214
\fILineWidth\fR specifies the width of the line, in any of the forms
1215
described in the COORDINATES section above.
1216
Wide lines will be drawn centered on the path specified by the
1218
If this option isn't specified then it defaults to 1.0.
1222
Items of type \fBoval\fR appear as circular or oval regions on
1223
the display. Each oval may have an outline, a fill, or
1224
both. Ovals are created with widget commands of the
1227
\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
1229
The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
1230
the coordinates of two diagonally opposite corners of a
1231
rectangular region enclosing the oval.
1232
The oval will include the top and left edges of the rectangle
1233
not the lower or right edges.
1234
If the region is square then the resulting oval is circular;
1235
otherwise it is elongated in shape.
1236
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1237
pairs, each of which sets one of the configuration options
1238
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1239
used in \fBitemconfigure\fR widget commands to change the item's
1241
The following options are supported for ovals:
1243
\fB\-fill \fIcolor\fR
1244
Fill the area of the oval with \fIcolor\fR.
1245
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
1246
If \fIcolor\fR is an empty string (the default), then
1247
then the oval will not be filled.
1249
\fB\-outline \fIcolor\fR
1250
\fIColor\fR specifies a color to use for drawing the oval's
1251
outline; it may have any of the forms accepted by \fBTk_GetColor\fR.
1252
This option defaults to \fBblack\fR.
1253
If \fIcolor\fR is an empty string then no outline will be
1256
\fB\-stipple \fIbitmap\fR
1257
Indicates that the oval should be filled in a stipple pattern;
1258
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1259
forms accepted by \fBTk_GetBitmap\fR.
1260
If the \fB\-fill\fR option hasn't been specified then this option
1262
If \fIbitmap\fR is an empty string (the default), then filling is done
1265
\fB\-tags \fItagList\fR
1266
Specifies a set of tags to apply to the item.
1267
\fITagList\fR consists of a list of tag names, which replace any
1268
existing tags for the item.
1269
\fITagList\fR may be an empty list.
1271
\fB\-width \fIoutlineWidth\fR
1272
\fIoutlineWidth\fR specifies the width of the outline to be drawn around
1273
the oval, in any of the forms described in the COORDINATES section above.
1274
If the \fB\-outline\fR option hasn't been specified then this option
1276
Wide outlines are drawn centered on the oval path defined by
1277
\fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
1278
This option defaults to 1.0.
1282
Items of type \fBpolygon\fR appear as polygonal or curved filled regions
1284
Polygons are created with widget commands of the following form:
1286
\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR?
1288
The arguments \fIx1\fR through \fIyn\fR specify the coordinates for
1289
three or more points that define a closed polygon.
1290
The first and last points may be the same; whether they are or not,
1291
Tk will draw the polygon as a closed polygon.
1292
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1293
pairs, each of which sets one of the configuration options
1294
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1295
used in \fBitemconfigure\fR widget commands to change the item's
1297
The following options are supported for polygons:
1299
\fB\-fill \fIcolor\fR
1300
\fIColor\fR specifies a color to use for filling the area of the
1301
polygon; it may have any of the forms acceptable to \fBTk_GetColor\fR.
1302
If \fIcolor\fR is an empty string then the polygon will be
1304
This option defaults to \fBblack\fR.
1306
\fB\-outline \fIcolor\fR
1307
\fIColor\fR specifies a color to use for drawing the polygon's
1308
outline; it may have any of the forms accepted by \fBTk_GetColor\fR.
1309
If \fIcolor\fR is an empty string then no outline will be
1310
drawn for the polygon.
1311
This option defaults to empty (no outline).
1313
\fB\-smooth \fIboolean\fR
1314
\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR
1315
It indicates whether or not the polygon should be drawn with a
1317
If so, the outline of the polygon becomes a set of parabolic splines,
1318
one spline for the first and second line segments, one for the second
1319
and third, and so on. Straight-line segments can be generated in a
1320
smoothed polygon by duplicating the end-points of the desired line segment.
1322
\fB\-splinesteps \fInumber\fR
1323
Specifies the degree of smoothness desired for curves: each spline
1324
will be approximated with \fInumber\fR line segments. This
1325
option is ignored unless the \fB\-smooth\fR option is true.
1327
\fB\-stipple \fIbitmap\fR
1328
Indicates that the polygon should be filled in a stipple pattern;
1329
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1330
forms accepted by \fBTk_GetBitmap\fR.
1331
If \fIbitmap\fR is an empty string (the default), then filling is
1332
done in a solid fashion.
1334
\fB\-tags \fItagList\fR
1335
Specifies a set of tags to apply to the item.
1336
\fITagList\fR consists of a list of tag names, which replace any
1337
existing tags for the item.
1338
\fITagList\fR may be an empty list.
1340
\fB\-width \fIoutlineWidth\fR
1341
\fIOutlineWidth\fR specifies the width of the outline to be drawn around
1342
the polygon, in any of the forms described in the COORDINATES section above.
1343
If the \fB\-outline\fR option hasn't been specified then this option
1344
has no effect. This option defaults to 1.0.
1346
Polygon items are different from other items such as rectangles, ovals
1347
and arcs in that interior points are considered to be ``inside'' a
1348
polygon (e.g. for purposes of the \fBfind closest\fR and
1349
\fBfind overlapping\fR widget commands) even if it is not filled.
1350
For most other item types, an
1351
interior point is considered to be inside the item only if the item
1352
is filled or if it has neither a fill nor an outline. If you would
1353
like an unfilled polygon whose interior points are not considered
1354
to be inside the polygon, use a line item instead.
1356
.SH "RECTANGLE ITEMS"
1358
Items of type \fBrectangle\fR appear as rectangular regions on
1359
the display. Each rectangle may have an outline, a fill, or
1360
both. Rectangles are created with widget commands of the
1363
\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR?
1365
The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR give
1366
the coordinates of two diagonally opposite corners of the rectangle
1367
(the rectangle will include its upper and left edges but not
1368
its lower or right edges).
1369
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1370
pairs, each of which sets one of the configuration options
1371
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1372
used in \fBitemconfigure\fR widget commands to change the item's
1374
The following options are supported for rectangles:
1376
\fB\-fill \fIcolor\fR
1377
Fill the area of the rectangle with \fIcolor\fR, which may be
1378
specified in any of the forms accepted by \fBTk_GetColor\fR.
1379
If \fIcolor\fR is an empty string (the default),
1380
then the rectangle will not be filled.
1382
\fB\-outline \fIcolor\fR
1383
Draw an outline around the edge of the rectangle in \fIcolor\fR.
1384
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
1385
This option defaults to \fBblack\fR.
1386
If \fIcolor\fR is an empty string then no outline will be
1387
drawn for the rectangle.
1389
\fB\-stipple \fIbitmap\fR
1390
Indicates that the rectangle should be filled in a stipple pattern;
1391
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1392
forms accepted by \fBTk_GetBitmap\fR.
1393
If the \fB\-fill\fR option hasn't been specified then this option
1395
If \fIbitmap\fR is an empty string (the default), then filling
1396
is done in a solid fashion.
1398
\fB\-tags \fItagList\fR
1399
Specifies a set of tags to apply to the item.
1400
\fITagList\fR consists of a list of tag names, which replace any
1401
existing tags for the item.
1402
\fITagList\fR may be an empty list.
1404
\fB\-width \fIoutlineWidth\fR
1405
\fIOutlineWidth\fR specifies the width of the outline to be drawn around
1406
the rectangle, in any of the forms described in the COORDINATES section above.
1407
If the \fB\-outline\fR option hasn't been specified then this option
1409
Wide outlines are drawn centered on the rectangular path
1410
defined by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
1411
This option defaults to 1.0.
1415
A text item displays a string of characters on the screen in one
1417
Text items support indexing and selection, along with the
1418
following text-related canvas widget commands: \fBdchars\fR,
1419
\fBfocus\fR, \fBicursor\fR, \fBindex\fR, \fBinsert\fR,
1421
Text items are created with widget commands of the following
1424
\fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR?
1426
The arguments \fIx\fR and \fIy\fR specify the coordinates of a
1427
point used to position the text on the display (see the options
1428
below for more information on how text is displayed).
1429
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1430
pairs, each of which sets one of the configuration options
1431
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1432
used in \fBitemconfigure\fR widget commands to change the item's
1434
The following options are supported for text items:
1436
\fB\-anchor \fIanchorPos\fR
1437
\fIAnchorPos\fR tells how to position the text relative to the
1438
positioning point for the text; it may have any of the forms
1439
accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR
1440
is \fBcenter\fR then the text is centered on the point; if
1441
\fIanchorPos\fR is \fBn\fR then the text will be drawn such that
1442
the top center point of the rectangular region occupied by the
1443
text will be at the positioning point.
1444
This option defaults to \fBcenter\fR.
1446
\fB\-fill \fIcolor\fR
1447
\fIColor\fR specifies a color to use for filling the text characters;
1448
it may have any of the forms accepted by \fBTk_GetColor\fR.
1449
If \fIcolor\fR is an empty string then the text will be transparent.
1450
If this option isn't specified then it defaults to \fBblack\fR.
1452
\fB\-font \fIfontName\fR
1453
Specifies the font to use for the text item.
1454
\fIFontName\fR may be any string acceptable to \fBTk_GetFontStruct\fR.
1455
If this option isn't specified, it defaults to a system-dependent
1458
\fB\-justify \fIhow\fR
1459
Specifies how to justify the text within its bounding region.
1460
\fIHow\fR must be one of the values \fBleft\fR, \fBright\fR,
1462
This option will only matter if the text is displayed as multiple
1464
If the option is omitted, it defaults to \fBleft\fR.
1466
\fB\-stipple \fIbitmap\fR
1467
Indicates that the text should be drawn in a stippled pattern
1469
\fIbitmap\fR specifies the stipple pattern to use, in any of the
1470
forms accepted by \fBTk_GetBitmap\fR.
1471
If \fIbitmap\fR is an empty string (the default) then the text
1472
is drawn in a solid fashion.
1474
\fB\-tags \fItagList\fR
1475
Specifies a set of tags to apply to the item.
1476
\fITagList\fR consists of a list of tag names, which replace any
1477
existing tags for the item.
1478
\fITagList\fR may be an empty list.
1480
\fB\-text \fIstring\fR
1481
\fIString\fR specifies the characters to be displayed in the text item.
1482
Newline characters cause line breaks.
1483
The characters in the item may also be changed with the
1484
\fBinsert\fR and \fBdelete\fR widget commands.
1485
This option defaults to an empty string.
1487
\fB\-width \fIlineLength\fR
1488
Specifies a maximum line length for the text, in any of the forms
1489
described in the COORDINATES section above.
1490
If this option is zero (the default) the text is broken into
1491
lines only at newline characters.
1492
However, if this option is non-zero then any line that would
1493
be longer than \fIlineLength\fR is broken just before a space
1494
character to make the line shorter than \fIlineLength\fR; the
1495
space character is treated as if it were a newline
1500
Items of type \fBwindow\fR cause a particular window to be displayed
1501
at a given position on the canvas.
1502
Window items are created with widget commands of the following form:
1504
\fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR?
1506
The arguments \fIx\fR and \fIy\fR specify the coordinates of a
1507
point used to position the window on the display (see the \fB\-anchor\fR
1508
option below for more information on how bitmaps are displayed).
1509
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
1510
pairs, each of which sets one of the configuration options
1511
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
1512
used in \fBitemconfigure\fR widget commands to change the item's
1514
The following options are supported for window items:
1516
\fB\-anchor \fIanchorPos\fR
1517
\fIAnchorPos\fR tells how to position the window relative to the
1518
positioning point for the item; it may have any of the forms
1519
accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR
1520
is \fBcenter\fR then the window is centered on the point; if
1521
\fIanchorPos\fR is \fBn\fR then the window will be drawn so that
1522
its top center point is at the positioning point.
1523
This option defaults to \fBcenter\fR.
1525
\fB\-height \fIpixels\fR
1526
Specifies the height to assign to the item's window.
1527
\fIPixels\fR may have any of the
1528
forms described in the COORDINATES section above.
1529
If this option isn't specified, or if it is specified as an empty
1530
string, then the window is given whatever height it requests internally.
1532
\fB\-tags \fItagList\fR
1533
Specifies a set of tags to apply to the item.
1534
\fITagList\fR consists of a list of tag names, which replace any
1535
existing tags for the item.
1536
\fITagList\fR may be an empty list.
1538
\fB\-width \fIpixels\fR
1539
Specifies the width to assign to the item's window.
1540
\fIPixels\fR may have any of the
1541
forms described in the COORDINATES section above.
1542
If this option isn't specified, or if it is specified as an empty
1543
string, then the window is given whatever width it requests internally.
1545
\fB\-window \fIpathName\fR
1546
Specifies the window to associate with this item.
1547
The window specified by \fIpathName\fR must either be a child of
1548
the canvas widget or a child of some ancestor of the canvas widget.
1549
\fIPathName\fR may not refer to a top-level window.
1551
Note: due to restrictions in the ways that windows are managed, it is not
1552
possible to draw other graphical items (such as lines and images) on top
1553
of window items. A window item always obscures any graphics that
1554
overlap it, regardless of their order in the display list.
1556
.SH "APPLICATION-DEFINED ITEM TYPES"
1558
It is possible for individual applications to define new item
1559
types for canvas widgets using C code.
1560
See the documentation for \fBTk_CreateItemType\fR.
1564
In the current implementation, new canvases are not given any
1565
default behavior: you'll have to execute explicit Tcl commands
1566
to give the canvas its behavior.
1570
Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
1571
\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme
1572
environment and preceded canvases by a year or two. Its simple
1573
mechanisms for placing and animating graphical objects inspired the
1574
functions of canvases.
added
removed
doc/canvas.n
