1
@c Copyright (c) 1994 William Schelter.
4
@c Copyright (c) 1990 The Regents of the University of California.
5
@c All rights reserved.
7
@c Permission is hereby granted, without written agreement and without
8
@c license or royalty fees, to use, copy, modify, and distribute this
9
@c documentation for any purpose, provided that the above copyright
10
@c notice and the following two paragraphs appear in all copies.
12
@c IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
13
@c FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
14
@c ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
15
@c CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17
@c THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
18
@c INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
19
@c AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
20
@c ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
21
@c PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
23
@node Widgets, Control, General, Top
44
@node button, listbox, Widgets, Widgets
48
button \- Create and manipulate button widgets
49
@unnumberedsubsec Synopsis
50
@b{button}@i{ }@i{pathName }@r{?}@i{options}?
51
@unnumberedsubsec Standard Options
55
activeBackground bitmap font relief
56
activeForeground borderWidth foreground text
57
anchor cursor padX textVariable
58
background disabledForeground padY
62
@xref{options}, for more information.
63
@unnumberedsubsec Arguments for Button
67
@item @code{@b{:command}}
69
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
73
Specifies a Tcl command to associate with the button. This command
74
is typically invoked when mouse button 1 is released over the button
80
@item @code{@b{:height}}
82
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
86
Specifies a desired height for the button.
87
If a bitmap is being displayed in the button then the value is in
88
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
89
for text it is in lines of text.
90
If this option isn't specified, the button's desired height is computed
91
from the size of the bitmap or text being displayed in it.
96
@item @code{@b{:state}}
98
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
102
Specifies one of three states for the button: @b{normal}@r{, }@b{active},
103
or @b{disabled}. In normal state the button is displayed using the
104
@b{foreground}@r{ and }@b{background} options. The active state is
105
typically used when the pointer is over the button. In active state
106
the button is displayed using the @b{activeForeground} and
107
@b{activeBackground} options. Disabled state means that the button
108
is insensitive: it doesn't activate and doesn't respond to mouse
109
button presses. In this state the @b{disabledForeground} and
110
@b{background} options determine how the button is displayed.
115
@item @code{@b{:width}}
117
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
121
Specifies a desired width for the button.
122
If a bitmap is being displayed in the button then the value is in
123
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
124
for text it is in characters.
125
If this option isn't specified, the button's desired width is computed
126
from the size of the bitmap or text being displayed in it.
130
@unnumberedsubsec Description
132
The @b{button} command creates a new window (given by the
133
@i{pathName} argument) and makes it into a button widget.
135
options, described above, may be specified on the command line
136
or in the option database
137
to configure aspects of the button such as its colors, font,
138
text, and initial relief. The @b{button} command returns its
139
@i{pathName} argument. At the time this command is invoked,
140
there must not exist a window named @i{pathName}, but
141
@i{pathName}'s parent must exist.
144
that displays a textual string or bitmap.
145
It can display itself in either of three different ways, according
147
the @b{state} option;
148
it can be made to appear raised, sunken, or flat;
149
and it can be made to flash. When a user invokes the
150
button (by pressing mouse button 1 with the cursor over the
151
button), then the Tcl command specified in the @b{:command}
154
@unnumberedsubsec A Button Widget's Arguments
156
The @b{button} command creates a new Tcl command whose
157
name is @i{pathName}. This
158
command may be used to invoke various
159
operations on the widget. It has the following general form:
162
@i{pathName option }@r{?}@i{arg arg ...}?
165
@i{Option}@r{ and the }@i{arg}s
166
determine the exact behavior of the command. The following
167
commands are possible for button widgets:
170
@item @i{pathName }@b{:activate}
171
Change the button's state to @b{active} and redisplay the button
172
using its active foreground and background colors instead of normal
174
This command is ignored if the button's state is @b{disabled}.
175
This command is obsolete and will eventually be removed;
176
use ``@i{pathName }@b{:configure :state active}'' instead.
177
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
178
Query or modify the configuration options of the widget.
179
If no @i{option} is specified, returns a list describing all of
180
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
181
information on the format of this list). If @i{option} is specified
182
with no @i{value}, then the command returns a list describing the
183
one named option (this list will be identical to the corresponding
184
sublist of the value returned if no @i{option} is specified). If
185
one or more @i{option:value} pairs are specified, then the command
186
modifies the given widget option(s) to have the given value(s); in
187
this case the command returns an empty string.
188
@i{Option}@r{ may have any of the values accepted by the }@b{button}
190
@item @i{pathName }@b{:deactivate}
191
Change the button's state to @b{normal} and redisplay the button
192
using its normal foreground and background colors.
193
This command is ignored if the button's state is @b{disabled}.
194
This command is obsolete and will eventually be removed;
195
use ``@i{pathName }@b{:configure :state normal}'' instead.
196
@item @i{pathName }@b{:flash}
197
Flash the button. This is accomplished by redisplaying the button
198
several times, alternating between active and normal colors. At
199
the end of the flash the button is left in the same normal/active
200
state as when the command was invoked.
201
This command is ignored if the button's state is @b{disabled}.
202
@item @i{pathName }@b{:invoke}
203
Invoke the Tcl command associated with the button, if there is one.
204
The return value is the return value from the Tcl command, or an
205
empty string if there is no command associated with the button.
206
This command is ignored if the button's state is @b{disabled}.
209
@unnumberedsubsec "Default Bindings"
211
Tk automatically creates class bindings for buttons that give them
212
the following default behavior:
216
The button activates whenever the mouse passes over it and deactivates
217
whenever the mouse leaves the button.
220
The button's relief is changed to sunken whenever mouse button 1 is
221
pressed over the button, and the relief is restored to its original
222
value when button 1 is later released.
225
If mouse button 1 is pressed over the button and later released over
226
the button, the button is invoked. However, if the mouse is not
227
over the button when button 1 is released, then no invocation occurs.
230
If the button's state is @b{disabled} then none of the above
231
actions occur: the button is completely non-responsive.
233
The behavior of buttons can be changed by defining new bindings for
234
individual widgets or by redefining the class bindings.
236
@unnumberedsubsec Keywords
238
@node listbox, scale, button, Widgets
242
listbox \- Create and manipulate listbox widgets
243
@unnumberedsubsec Synopsis
244
@b{listbox}@i{ }@i{pathName }@r{?}@i{options}?
245
@unnumberedsubsec Standard Options
249
background foreground selectBackground xScrollCommand
250
borderWidth font selectBorderWidth yScrollCommand
251
cursor geometry selectForeground
252
exportSelection relief setGrid
256
@xref{options}, for more information.
257
@unnumberedsubsec Arguments for Listbox
263
@unnumberedsubsec Description
265
The @b{listbox} command creates a new window (given by the
266
@i{pathName} argument) and makes it into a listbox widget.
268
options, described above, may be specified on the command line
269
or in the option database
270
to configure aspects of the listbox such as its colors, font,
271
text, and relief. The @b{listbox} command returns its
272
@i{pathName} argument. At the time this command is invoked,
273
there must not exist a window named @i{pathName}, but
274
@i{pathName}'s parent must exist.
276
A listbox is a widget that displays a list of strings, one per line.
277
When first created, a new listbox has no elements in its list.
278
Elements may be added or deleted using widget commands described
279
below. In addition, one or more elements may be selected as described
281
If a listbox is exporting its selection (see @b{exportSelection}
282
option), then it will observe the standard X11 protocols
283
for handling the selection; listbox selections are available
284
as type @b{STRING}, consisting of a Tcl list with one entry
285
for each selected element.
287
For large lists only a subset of the list elements will be
288
displayed in the listbox window at once; commands described below
289
may be used to change the view in the window. Listboxes allow
290
scrolling in both directions using the standard @b{xScrollCommand}
291
and @b{yScrollCommand} options.
292
They also support scanning, as described below.
294
@unnumberedsubsec A Listbox's Arguments
296
The @b{listbox} command creates a new Tcl command whose
297
name is @i{pathName}. This
298
command may be used to invoke various
299
operations on the widget. It has the following general form:
302
@i{pathName option }@r{?}@i{arg arg ...}?
305
@i{Option}@r{ and the }@i{arg}s
306
determine the exact behavior of the command. The following
307
commands are possible for listbox widgets:
310
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
311
Query or modify the configuration options of the widget.
312
If no @i{option} is specified, returns a list describing all of
313
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
314
information on the format of this list). If @i{option} is specified
315
with no @i{value}, then the command returns a list describing the
316
one named option (this list will be identical to the corresponding
317
sublist of the value returned if no @i{option} is specified). If
318
one or more @i{option:value} pairs are specified, then the command
319
modifies the given widget option(s) to have the given value(s); in
320
this case the command returns an empty string.
321
@i{Option}@r{ may have any of the values accepted by the }@b{listbox}
323
@item @i{pathName }@b{:curselection}
324
Returns a list containing the indices of
325
all of the elements in the listbox that are currently selected.
326
If there are no elements selected in the listbox then an empty
328
@item @i{pathName }@b{:delete }@i{first }@r{?}@i{last}?
329
Delete one or more elements of the listbox. @i{First}@r{ and }@i{last}
330
give the integer indices of the first and last elements in the range
331
to be deleted. If @i{last} isn't specified it defaults to
332
@i{first}, i.e. a single element is deleted. An index of
333
@b{0} corresponds to the first element in the listbox. Either
334
@i{first}@r{ or }@i{last}@r{ may be specified as }@b{end}, in which
335
case it refers to the last element of the listbox. This command
336
returns an empty string
337
@item @i{pathName }@b{:get }@i{index}
338
Return the contents of the listbox element indicated by @i{index}.
339
@i{Index} must be a non-negative integer (0 corresponds to
340
the first element in the listbox), or it may also be specified as
341
@b{end} to indicate the last element in the listbox.
342
@item @i{pathName }@b{:insert }@i{index }@r{?}@i{element element ...}?
343
Insert zero or more new elements in the list just before the
344
element given by @i{index}@r{. If }@i{index} is specified as
345
@b{end} then the new elements are added to the end of the
346
list. Returns an empty string.
347
@item @i{pathName }@b{:nearest }@i{y}
348
Given a y-coordinate within the listbox window, this command returns
349
the index of the (visible) listbox element nearest to that y-coordinate.
350
@item @i{pathName }@b{:scan}@r{ }@i{option args}
351
This command is used to implement scanning on listboxes. It has
352
two forms, depending on @i{option}:
354
@item @i{pathName }@b{:scan :mark }@i{x y}
355
Records @i{x}@r{ and }@i{y} and the current view in the listbox
356
window; used in conjunction with later @b{scan dragto} commands.
357
Typically this command is associated with a mouse button press in
358
the widget. It returns an empty string.
359
@item @i{pathName }@b{:scan :dragto }@i{x y}.
360
This command computes the difference between its @i{x}@r{ and }@i{y}
361
arguments and the @i{x}@r{ and }@i{y} arguments to the last
362
@b{scan mark} command for the widget.
363
It then adjusts the view by 10 times the
364
difference in coordinates. This command is typically associated
365
with mouse motion events in the widget, to produce the effect of
366
dragging the list at high speed through the window. The return
367
value is an empty string.
369
@item @i{pathName }@b{:select }@i{option arg}
370
This command is used to adjust the selection within a listbox. It
371
has several forms, depending on @i{option}. In all of the forms
372
the index @b{end} refers to the last element in the listbox.
374
@item @i{pathName }@b{:select :adjust }@i{index}
375
Locate the end of the selection nearest to the element given by
376
@i{index}@r{, and adjust that end of the selection to be at }@i{index}
377
(i.e including but not going beyond @i{index}). The other
378
end of the selection is made the anchor point for future
379
@b{select to} commands. If the selection
380
isn't currently in the listbox, then this command is identical to
381
the @b{select from} widget command.
382
Returns an empty string.
383
@item @i{pathName }@b{:select :clear}
384
If the selection is in this listbox then it is cleared so that
385
none of the listbox's elements are selected anymore.
386
@item @i{pathName }@b{:select :from }@i{index}
387
Set the selection to consist of element @i{index}, and make
388
@i{index}@r{ the anchor point for future }@b{select to} widget
389
commands. Returns an empty string.
390
@item @i{pathName }@b{:select :to }@i{index}
391
Set the selection to consist of the elements from the anchor
392
point to element @i{index}, inclusive. The anchor point is
393
determined by the most recent @b{select from}@r{ or }@b{select adjust}
394
command in this widget. If the selection isn't in this widget,
395
this command is identical to @b{select from}.
396
Returns an empty string.
399
@item @i{pathName }@b{:size}
400
Returns a decimal string indicating the total number of elements
402
@item @i{pathName }@b{:xview }@i{index}
403
Adjust the view in the listbox so that character position @i{index}
404
is displayed at the left edge of the widget.
405
Returns an empty string.
406
@item @i{pathName }@b{:yview }@i{index}
407
Adjust the view in the listbox so that element @i{index} is
408
displayed at the top of the widget.
409
If @i{index}@r{ is specified as }@b{end} it indicates the last
410
element of the listbox. Returns an empty string.
413
@unnumberedsubsec "Default Bindings"
415
Tk automatically creates class bindings for listboxes that give them
416
the following default behavior:
420
When button 1 is pressed over a listbox, the element underneath the
421
mouse cursor is selected. The mouse can be dragged to select a
425
The ends of the selection can be adjusted by dragging with mouse
426
button 1 while the shift key is down; this will adjust the end
427
of the selection that was nearest to the mouse cursor when button
431
The view in the listbox can be adjusted by dragging with mouse button 2.
434
The behavior of listboxes can be changed by defining new bindings for
435
individual widgets or by redefining the class bindings.
436
In addition, the procedure @b{tk_listboxSingleSelect} may be
437
invoked to change listbox behavior so that only a single element
438
may be selected at once.
440
@unnumberedsubsec Keywords
442
@node scale, canvas, listbox, Widgets
446
scale \- Create and manipulate scale widgets
447
@unnumberedsubsec Synopsis
448
@b{scale}@i{ }@i{pathName }@r{?}@i{options}?
449
@unnumberedsubsec Standard Options
453
activeForeground borderWidth font orient
454
background cursor foreground relief
458
@xref{options}, for more information.
459
@unnumberedsubsec Arguments for Scale
463
@item @code{@b{:command}}
465
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
469
Specifies the prefix of a Tcl command to invoke whenever the value of
470
the scale is changed interactively. The actual command consists
471
of this option followed by
472
a space and a number. The number indicates the new value of the
478
@item @code{@b{:from}}
480
Name=@code{"@b{from}@r{"} Class=@code{"}@b{From}"}
484
Specifies the value corresponding to the left or top end of the
485
scale. Must be an integer.
490
@item @code{@b{:label}}
492
Name=@code{"@b{label}@r{"} Class=@code{"}@b{Label}"}
496
Specifies a string to displayed as a label for the scale. For
497
vertical scales the label is displayed just to the right of the
498
top end of the scale. For horizontal scales the label is displayed
499
just above the left end of the scale.
504
@item @code{@b{:length}}
506
Name=@code{"@b{length}@r{"} Class=@code{"}@b{Length}"}
510
Specifies the desired long dimension of the scale in screen units,
511
that is in any of the forms acceptable to @b{Tk_GetPixels}.
512
For vertical scales this is the scale's height; for horizontal scales
513
it is the scale's width.
518
@item @code{@b{:showvalue}}
520
Name=@code{"@b{showValue}@r{"} Class=@code{"}@b{ShowValue}"}
524
Specifies a boolean value indicating whether or not the current
525
value of the scale is to be displayed.
530
@item @code{@b{:sliderforeground}}
532
Name=@code{"@b{sliderForeground}@r{"} Class=@code{"}@b{sliderForeground}"}
536
Specifies the color to use for drawing the slider under normal conditions.
537
When the mouse is in the slider window then the slider's color is
538
determined by the @b{activeForeground} option.
543
@item @code{@b{:sliderlength}}
545
Name=@code{"@b{sliderLength}@r{"} Class=@code{"}@b{SliderLength}"}
549
Specfies the size of the slider, measured in screen units along the slider's
550
long dimension. The value may be specified in any of the forms acceptable
556
@item @code{@b{:state}}
558
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
562
Specifies one of two states for the scale: @b{normal}@r{ or }@b{disabled}.
563
If the scale is disabled then the value may not be changed and the scale
564
won't activate when the mouse enters it.
569
@item @code{@b{:tickinterval}}
571
Name=@code{"@b{tickInterval}@r{"} Class=@code{"}@b{TickInterval}"}
575
Must be an integer value. Determines the spacing between numerical
576
tick-marks displayed below or to the left of the slider. If specified
577
as 0, then no tick-marks will be displayed.
584
Name=@code{"@b{to}@r{"} Class=@code{"}@b{To}"}
588
Specifies the value corresponding to the right or bottom end of the
589
scale. Must be an integer. This value may be either less than or
590
greater than the @b{from} option.
595
@item @code{@b{:width}}
597
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
601
Specifies the desired narrow dimension of the scale in screen units
602
(i.e. any of the forms acceptable to @b{Tk_GetPixels}).
603
For vertical scales this is the scale's width; for horizontal scales
604
this is the scale's height.
608
@unnumberedsubsec Description
610
The @b{scale} command creates a new window (given by the
611
@i{pathName} argument) and makes it into a scale widget.
613
options, described above, may be specified on the command line
614
or in the option database
615
to configure aspects of the scale such as its colors, orientation,
616
and relief. The @b{scale} command returns its
617
@i{pathName} argument. At the time this command is invoked,
618
there must not exist a window named @i{pathName}, but
619
@i{pathName}'s parent must exist.
621
A scale is a widget that displays a rectangular region and a
622
small @i{slider}. The rectangular region corresponds to a range
623
of integer values (determined by the @b{from}@r{ and }@b{to} options),
624
and the position of the slider selects a particular integer value.
625
The slider's position (and hence the scale's value) may be adjusted
626
by clicking or dragging with the mouse as described in the BINDINGS
627
section below. Whenever the scale's value is changed, a Tcl
628
command is invoked (using the @b{command} option) to notify
629
other interested widgets of the change.
631
Three annotations may be displayed in a scale widget: a label
632
appearing at the top-left of the widget (top-right for vertical
633
scales), a number displayed just underneath the slider
634
(just to the left of the slider for vertical scales), and a collection
635
of numerical tick-marks just underneath the current value (just to the left of
636
the current value for vertical scales). Each of these three
637
annotations may be selectively enabled or disabled using the
638
configuration options.
640
@unnumberedsubsec A Scale's"Argumentsommand"
642
The @b{scale} command creates a new Tcl command whose
643
name is @i{pathName}. This
644
command may be used to invoke various
645
operations on the widget. It has the following general form:
648
@i{pathName option }@r{?}@i{arg arg ...}?
651
@i{Option}@r{ and the }@i{arg}s
652
determine the exact behavior of the command. The following
653
commands are possible for scale widgets:
656
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
657
Query or modify the configuration options of the widget.
658
If no @i{option} is specified, returns a list describing all of
659
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
660
information on the format of this list). If @i{option} is specified
661
with no @i{value}, then the command returns a list describing the
662
one named option (this list will be identical to the corresponding
663
sublist of the value returned if no @i{option} is specified). If
664
one or more @i{option:value} pairs are specified, then the command
665
modifies the given widget option(s) to have the given value(s); in
666
this case the command returns an empty string.
667
@i{Option}@r{ may have any of the values accepted by the }@b{scale}
669
@item @i{pathName }@b{:get}
670
Returns a decimal string giving the current value of the scale.
671
@item @i{pathName }@b{:set}@r{ }@i{value}
672
This command is invoked to change the current value of the scale,
673
and hence the position at which the slider is displayed. @i{Value}
674
gives the new value for the scale.
677
@unnumberedsubsec Bindings
679
When a new scale is created, it is given the following initial
684
Change the slider display to use @b{activeForeground} instead of
685
@b{sliderForeground}.
687
Reset the slider display to use @b{sliderForeground} instead of
688
@b{activeForeground}.
689
@item @b{<ButtonPress-1>}
690
Change the slider display so that the slider appears sunken rather
691
than raised. Move the slider (and adjust the scale's value)
692
to correspond to the current mouse position.
693
@item @b{<Button1-Motion>}
694
Move the slider (and adjust the scale's value) to correspond to
695
the current mouse position.
696
@item @b{<ButtonRelease-1>}
697
Reset the slider display so that the slider appears raised again.
700
@unnumberedsubsec Keywords
702
@node canvas, menu, scale, Widgets
706
canvas \- Create and manipulate canvas widgets
707
@unnumberedsubsec Synopsis
708
@b{canvas}@i{ }@i{pathName }@r{?}@i{options}?
709
@unnumberedsubsec Standard Options
713
background insertBorderWidth relief xScrollCommand
714
borderWidth insertOffTime selectBackground yScrollCommand
715
cursor insertOnTime selectBorderWidth
716
insertBackground insertWidth selectForeground
720
@xref{options}, for more information.
721
@unnumberedsubsec Arguments for Canvas
725
@item @code{@b{:closeenough}}
727
Name=@code{"@b{closeEnough}@r{"} Class=@code{"}@b{CloseEnough}"}
731
Specifies a floating-point value indicating how close the mouse cursor
732
must be to an item before it is considered to be ``inside'' the item.
738
@item @code{@b{:confine}}
740
Name=@code{"@b{confine}@r{"} Class=@code{"}@b{Confine}"}
744
Specifies a boolean value that indicates whether or not it should be
745
allowable to set the canvas's view outside the region defined by the
746
@b{scrollRegion} argument.
747
Defaults to true, which means that the view will
748
be constrained within the scroll region.
753
@item @code{@b{:height}}
755
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
759
Specifies a desired window height that the canvas widget should request from
760
its geometry manager. The value may be specified in any
761
of the forms described in the COORDINATES section below.
766
@item @code{@b{:scrollincrement}}
768
Name=@code{"@b{scrollIncrement}@r{"} Class=@code{"}@b{ScrollIncrement}"}
772
Specifies a distance used as increment during scrolling: when one of
773
the arrow buttons on an associated scrollbar is pressed, the picture
774
will shift by this distance. The distance may be specified in any
775
of the forms described in the COORDINATES section below.
780
@item @code{@b{:scrollregion}}
782
Name=@code{"@b{scrollRegion}@r{"} Class=@code{"}@b{ScrollRegion}"}
786
Specifies a list with four coordinates describing the left, top, right, and
787
bottom coordinates of a rectangular region.
788
This region is used for scrolling purposes and is considered to be
789
the boundary of the information in the canvas.
790
Each of the coordinates may be specified
791
in any of the forms given in the COORDINATES section below.
796
@item @code{@b{:width}}
798
Name=@code{"@b{width}@r{"} Class=@code{"}@b{width}"}
802
Specifies a desired window width that the canvas widget should request from
803
its geometry manager. The value may be specified in any
804
of the forms described in the COORDINATES section below.
808
@unnumberedsubsec Introduction
810
The @b{canvas} command creates a new window (given
811
by the @i{pathName} argument) and makes it into a canvas widget.
812
Additional options, described above, may be specified on the
813
command line or in the option database
814
to configure aspects of the canvas such as its colors and 3-D relief.
815
The @b{canvas} command returns its
816
@i{pathName} argument. At the time this command is invoked,
817
there must not exist a window named @i{pathName}, but
818
@i{pathName}'s parent must exist.
820
Canvas widgets implement structured graphics.
821
A canvas displays any number of @i{items}, which may be things like
822
rectangles, circles, lines, and text.
823
Items may be manipulated (e.g. moved or re-colored) and commands may
824
be associated with items in much the same way that the @b{bind}
825
command allows commands to be bound to widgets. For example,
826
a particular command may be associated with the <Button-1> event
827
so that the command is invoked whenever button 1 is pressed with
828
the mouse cursor over an item.
829
This means that items in a canvas can have behaviors defined by
830
the Tcl scripts bound to them.
832
@unnumberedsubsec Display List
834
The items in a canvas are ordered for purposes of display,
835
with the first item in the display list being displayed
836
first, followed by the next item in the list, and so on.
837
Items later in the display list obscure those that are
838
earlier in the display list and are sometimes referred to
839
as being ``on top'' of earlier items.
840
When a new item is created it is placed at the end of the
841
display list, on top of everything else.
842
Widget commands may be used to re-arrange the order of the
845
@unnumberedsubsec Item Ids And Tags
847
Items in a canvas widget may be named in either of two ways:
849
Each item has a unique identifying number which is assigned to
850
that item when it is created. The id of an item never changes
851
and id numbers are never re-used within the lifetime of a
854
Each item may also have any number of @i{tags} associated
855
with it. A tag is just a string of characters, and it may
856
take any form except that of an integer.
857
For example, ``x123'' is OK but ``123'' isn't.
858
The same tag may be associated with many different items.
859
This is commonly done to group items in various interesting
860
ways; for example, all selected items might be given the
863
The tag @b{all} is implicitly associated with every item
864
in the canvas; it may be used to invoke operations on
865
all the items in the canvas.
867
The tag @b{current} is managed automatically by Tk;
868
it applies to the @i{current item}, which is the
869
topmost item whose drawn area covers the position of
871
If the mouse is not in the canvas widget or is not over
872
an item, then no item has the @b{current} tag.
874
When specifying items in canvas widget commands, if the
875
specifier is an integer then it is assumed to refer to
876
the single item with that id.
877
If the specifier is not an integer, then it is assumed to
878
refer to all of the items in the canvas that have a tag
879
matching the specifier.
880
The symbol @i{tagOrId} is used below to indicate that
881
an argument specifies either an id that selects a single
882
item or a tag that selects zero or more items.
883
Some widget commands only operate on a single item at a
884
time; if @i{tagOrId} is specified in a way that
885
names multiple items, then the normal behavior is for
886
the command to use the first (lowest) of these items in
887
the display list that is suitable for the command.
888
Exceptions are noted in the widget command descriptions
891
@unnumberedsubsec Coordinates
893
All coordinates related to canvases are stored as floating-point
895
Coordinates and distances are specified in screen units,
896
which are floating-point numbers optionally followed
897
by one of several letters.
898
If no letter is supplied then the distance is in pixels.
899
If the letter is @b{m} then the distance is in millimeters on
900
the screen; if it is @b{c} then the distance is in centimeters;
901
@b{i}@r{ means inches, and }@b{p} means printers points (1/72 inch).
902
Larger y-coordinates refer to points lower on the screen; larger
903
x-coordinates refer to points farther to the right.
905
@unnumberedsubsec Transformations
907
Normally the origin of the canvas coordinate system is at the
908
upper-left corner of the window containing the canvas.
909
It is possible to adjust the origin of the canvas
910
coordinate system relative to the origin of the window using the
911
@b{xview}@r{ and }@b{yview} widget commands; this is typically used
913
Canvases do not support scaling or rotation of the canvas coordinate
914
system relative to the window coordinate system.
916
Indidividual items may be moved or scaled using widget commands
917
described below, but they may not be rotated.
919
@unnumberedsubsec Indices
921
Text items support the notion of an @i{index} for identifying
922
particular positions within the item.
923
Indices are used for commands such as inserting text, deleting
924
a range of characters, and setting the insertion cursor position.
925
An index may be specified in any of a number of ways, and
926
different types of items may support different forms for
928
Text items support the following forms for an index; if you
929
define new types of text-like items, it would be advisable to
930
support as many of these forms as practical.
931
Note that it is possible to refer to the character just after
932
the last one in the text item; this is necessary for such
933
tasks as inserting new text at the end of the item.
937
A decimal number giving the position of the desired character
938
within the text item.
939
0 refers to the first character, 1 to the next character, and
941
A number less than 0 is treated as if it were zero, and a
942
number greater than the length of the text item is treated
943
as if it were equal to the length of the text item.
945
Refers to the character just after the last one in the item
946
(same as the number of characters in the item).
948
Refers to the character just before which the insertion cursor
949
is drawn in this item.
951
Refers to the first selected character in the item.
952
If the selection isn't in this item then this form is illegal.
954
Refers to the last selected character in the item.
955
If the selection isn't in this item then this form is illegal.
957
Refers to the character at the point given by @i{x} and
958
@i{y}@r{, where }@i{x}@r{ and }@i{y} are specified in the coordinate
959
system of the canvas.
960
If @i{x}@r{ and }@i{y} lie outside the coordinates covered by the
961
text item, then they refer to the first or last character in the
962
line that is closest to the given point.
965
@unnumberedsubsec A Canvas Widget's Arguments
967
The @b{canvas} command creates a new Tcl command whose
968
name is @i{pathName}. This
969
command may be used to invoke various
970
operations on the widget. It has the following general form:
973
@i{pathName option }@r{?}@i{arg arg ...}?
976
@i{Option}@r{ and the }@i{arg}s
977
determine the exact behavior of the command.
978
The following widget commands are possible for canvas widgets:
981
@item @i{pathName }@b{:addtag }@i{tag searchSpec }@r{?}@i{arg arg ...}?
982
For each item that meets the constraints specified by
983
@i{searchSpec}@r{ and the }@i{arg}s, add
984
@i{tag} to the list of tags associated with the item if it
985
isn't already present on that list.
986
It is possible that no items will satisfy the constraints
987
given by @i{searchSpec and }@i{arg}s, in which case the
988
command has no effect.
989
This command returns an empty string as result.
990
@i{SearchSpec}@r{ and }@i{arg}'s may take any of the following
994
@item @b{above }@i{tagOrId}
995
Selects the item just after (above) the one given by @i{tagOrId}
997
If @i{tagOrId} denotes more than one item, then the last (topmost)
998
of these items in the display list is used.
1000
Selects all the items in the canvas.
1001
@item @b{below }@i{tagOrId}
1002
Selects the item just before (below) the one given by @i{tagOrId}
1003
in the display list.
1004
If @i{tagOrId} denotes more than one item, then the first (lowest)
1005
of these items in the display list is used.
1006
@item @b{closest }@i{x y }@r{?}@i{halo}@r{? ?}@i{start}?
1007
Selects the item closest to the point given by @i{x}@r{ and }@i{y}.
1008
If more than one item is at the same closest distance (e.g. two
1009
items overlap the point), then the top-most of these items (the
1010
last one in the display list) is used.
1011
If @i{halo} is specified, then it must be a non-negative
1013
Any item closer than @i{halo} to the point is considered to
1015
The @i{start} argument may be used to step circularly through
1016
all the closest items.
1017
If @i{start} is specified, it names an item using a tag or id
1018
(if by tag, it selects the first item in the display list with
1020
Instead of selecting the topmost closest item, this form will
1021
select the topmost closest item that is below @i{start} in
1022
the display list; if no such item exists, then the selection
1023
behaves as if the @i{start} argument had not been specified.
1024
@item @b{enclosed}@r{ }@i{x1}@r{ }@i{y1}@r{ }@i{x2}@r{ }@i{y2}
1025
Selects all the items completely enclosed within the rectangular
1026
region given by @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
1027
@i{X1}@r{ must be no greater then }@i{x2}@r{ and }@i{y1} must be
1028
no greater than @i{y2}.
1029
@item @b{overlapping}@r{ }@i{x1}@r{ }@i{y1}@r{ }@i{x2}@r{ }@i{y2}
1030
Selects all the items that overlap or are enclosed within the
1031
rectangular region given by @i{x1}@r{, }@i{y1}@r{, }@i{x2},
1033
@i{X1}@r{ must be no greater then }@i{x2}@r{ and }@i{y1} must be
1034
no greater than @i{y2}.
1035
@item @b{withtag }@i{tagOrId}
1036
Selects all the items given by @i{tagOrId}.
1039
@item @i{pathName }@b{:bbox }@i{tagOrId}@r{ ?}@i{tagOrId tagOrId ...}?
1040
Returns a list with four elements giving an approximate bounding box
1041
for all the items named by the @i{tagOrId} arguments.
1042
The list has the form ``@i{x1 y1 x2 y2}'' such that the drawn
1043
areas of all the named elements are within the region bounded by
1044
@i{x1}@r{ on the left, }@i{x2}@r{ on the right, }@i{y1} on the top,
1045
and @i{y2} on the bottom.
1046
The return value may overestimate the actual bounding box by
1048
If no items match any of the @i{tagOrId} arguments then an
1049
empty string is returned.
1050
@item @i{pathName }@b{:bind }@i{tagOrId}@r{ ?}@i{sequence}@r{? ?}@i{command}?
1051
This command associates @i{command} with all the items given by
1052
@i{tagOrId} such that whenever the event sequence given by
1053
@i{sequence} occurs for one of the items the command will
1055
This widget command is similar to the @b{bind} command except that
1056
it operates on items in a canvas rather than entire widgets.
1057
See the @b{bind} manual entry for complete details
1058
on the syntax of @i{sequence} and the substitutions performed
1059
on @i{command} before invoking it.
1060
If all arguments are specified then a new binding is created, replacing
1061
any existing binding for the same @i{sequence}@r{ and }@i{tagOrId}
1062
(if the first character of @i{command}@r{ is ``+'' then }@i{command}
1063
augments an existing binding rather than replacing it).
1064
In this case the return value is an empty string.
1065
If @i{command}@r{ is omitted then the command returns the }@i{command}
1066
associated with @i{tagOrId}@r{ and }@i{sequence} (an error occurs
1067
if there is no such binding).
1068
If both @i{command}@r{ and }@i{sequence} are omitted then the command
1069
returns a list of all the sequences for which bindings have been
1070
defined for @i{tagOrId}.
1074
The only events for which bindings may be specified are those related
1075
to the mouse and keyboard, such as @b{Enter}@r{, }@b{Leave},
1076
@b{ButtonPress}@r{, }@b{Motion}@r{, and }@b{KeyPress}.
1077
The handling of events in canvases uses the current item defined
1078
in ITEM IDS AND TAGS above.
1079
@b{Enter}@r{ and }@b{Leave} events trigger for an item when it
1080
becomes the current item or ceases to be the current item; note
1081
that these events are different than @b{Enter}@r{ and }@b{Leave}
1083
Mouse-related events are directed to the current item, if any.
1084
Keyboard-related events are directed to the focus item, if any
1085
(see the @b{focus} widget command below for more on this).
1088
It is possible for multiple commands to be bound to a single
1089
event sequence for a single object.
1090
This occurs, for example, if one command is associated with the
1091
item's id and another is associated with one of the item's tags.
1092
When this occurs, the first matching binding is used.
1093
A binding for the item's id has highest priority, followed by
1094
the oldest tag for the item and proceeding through all of the
1095
item's tags up through the most-recently-added one.
1096
If a binding is associated with the tag @b{all}, the binding
1097
will have lower priority than all other bindings associated
1101
@item @i{pathName }@b{:canvasx }@i{screenx}@r{ ?}@i{gridspacing}?
1102
Given a screen x-coordinate @i{screenx} this command returns
1103
the canvas x-coordinate that is displayed at that location.
1104
If @i{gridspacing} is specified, then the canvas coordinate is
1105
rounded to the nearest multiple of @i{gridspacing} units.
1106
@item @i{pathName }@b{:canvasy }@i{screeny}@r{ ?}@i{gridspacing}?
1107
Given a screen y-coordinate @i{screeny} this command returns
1108
the canvas y-coordinate that is displayed at that location.
1109
If @i{gridspacing} is specified, then the canvas coordinate is
1110
rounded to the nearest multiple of @i{gridspacing} units.
1111
@item @i{pathName }@b{:configure ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
1112
Query or modify the configuration options of the widget.
1113
If no @i{option} is specified, returns a list describing all of
1114
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
1115
information on the format of this list). If @i{option} is specified
1116
with no @i{value}, then the command returns a list describing the
1117
one named option (this list will be identical to the corresponding
1118
sublist of the value returned if no @i{option} is specified). If
1119
one or more @i{option:value} pairs are specified, then the command
1120
modifies the given widget option(s) to have the given value(s); in
1121
this case the command returns an empty string.
1122
@i{Option}@r{ may have any of the values accepted by the }@b{canvas}
1124
@item @i{pathName}@r{ }@b{:coords }@i{tagOrId }@r{?}@i{x0 y0 ...}?
1125
Query or modify the coordinates that define an item.
1126
If no coordinates are specified, this command returns a list
1127
whose elements are the coordinates of the item named by
1129
If coordinates are specified, then they replace the current
1130
coordinates for the named item.
1131
If @i{tagOrId} refers to multiple items, then
1132
the first one in the display list is used.
1133
@item @i{pathName }@b{:create }@i{type x y }@r{?}@i{x y ...}@r{? ?}@i{option value ...}?
1134
Create a new item in @i{pathName}@r{ of type }@i{type}.
1135
The exact format of the arguments after @b{type} depends
1136
on @b{type}, but usually they consist of the coordinates for
1137
one or more points, followed by specifications for zero or
1139
See the subsections on individual item types below for more
1140
on the syntax of this command.
1141
This command returns the id for the new item.
1142
@item @i{pathName }@b{:dchars }@i{tagOrId first }@r{?}@i{last}?
1143
For each item given by @i{tagOrId}, delete the characters
1144
in the range given by @i{first}@r{ and }@i{last},
1146
If some of the items given by @i{tagOrId} don't support
1147
text operations, then they are ignored.
1148
@i{First}@r{ and }@i{last} are indices of characters
1149
within the item(s) as described in INDICES above.
1150
If @i{last}@r{ is omitted, it defaults to }@i{first}.
1151
This command returns an empty string.
1152
@item @i{pathName }@b{:delete }@r{?}@i{tagOrId tagOrId ...}?
1153
Delete each of the items given by each @i{tagOrId}, and return
1155
@item @i{pathName }@b{:dtag }@i{tagOrId }@r{?tagToDelete}?
1156
For each of the items given by @i{tagOrId}, delete the
1157
tag given by @i{tagToDelete} from the list of those
1158
associated with the item.
1159
If an item doesn't have the tag @i{tagToDelete} then
1160
the item is unaffected by the command.
1161
If @i{tagToDelete}@r{ is omitted then it defaults to }@i{tagOrId}.
1162
This command returns an empty string.
1163
@item @i{pathName }@b{:find }@i{searchCommand }@r{?}@i{arg arg ...}?
1164
This command returns a list consisting of all the items that
1165
meet the constraints specified by @i{searchCommand} and
1167
@i{SearchCommand}@r{ and }@i{args} have any of the forms
1168
accepted by the @b{addtag} command.
1169
@item @i{pathName }@b{:focus }@r{?}@i{tagOrId}?
1170
Set the keyboard focus for the canvas widget to the item given by
1172
If @i{tagOrId} refers to several items, then the focus is set
1173
to the first such item in the display list that supports the
1175
If @i{tagOrId} doesn't refer to any items, or if none of them
1176
support the insertion cursor, then the focus isn't changed.
1177
If @i{tagOrId} is an empty
1178
string, then the focus item is reset so that no item has the focus.
1179
If @i{tagOrId} is not specified then the command returns the
1180
id for the item that currently has the focus, or an empty string
1181
if no item has the focus.
1185
Once the focus has been set to an item, the item will display
1186
the insertion cursor and all keyboard events will be directed
1188
The focus item within a canvas and the focus window on the
1189
screen (set with the @b{focus} command) are totally independent:
1190
a given item doesn't actually have the input focus unless (a)
1191
its canvas is the focus window and (b) the item is the focus item
1193
In most cases it is advisable to follow the @b{focus} widget
1194
command with the @b{focus} command to set the focus window to
1195
the canvas (if it wasn't there already).
1198
@item @i{pathName }@b{:gettags}@r{ }@i{tagOrId}
1199
Return a list whose elements are the tags associated with the
1200
item given by @i{tagOrId}.
1201
If @i{tagOrId} refers to more than one item, then the tags
1202
are returned from the first such item in the display list.
1203
If @i{tagOrId} doesn't refer to any items, or if the item
1204
contains no tags, then an empty string is returned.
1205
@item @i{pathName }@b{:icursor }@i{tagOrId index}
1206
Set the position of the insertion cursor for the item(s)
1207
given by @i{tagOrId}
1208
to just before the character whose position is given by @i{index}.
1209
If some or all of the items given by @i{tagOrId} don't support
1210
an insertion cursor then this command has no effect on them.
1211
See INDICES above for a description of the
1212
legal forms for @i{index}.
1213
Note: the insertion cursor is only displayed in an item if
1214
that item currently has the keyboard focus (see the widget
1215
command @b{focus}, below), but the cursor position may
1216
be set even when the item doesn't have the focus.
1217
This command returns an empty string.
1218
@item @i{pathName }@b{:index }@i{tagOrId index}
1219
This command returns a decimal string giving the numerical index
1220
within @i{tagOrId}@r{ corresponding to }@i{index}.
1221
@i{Index} gives a textual description of the desired position
1222
as described in INDICES above.
1223
The return value is guaranteed to lie between 0 and the number
1224
of characters within the item, inclusive.
1225
If @i{tagOrId} refers to multiple items, then the index
1226
is processed in the first of these items that supports indexing
1227
operations (in display list order).
1228
@item @i{pathName }@b{:insert }@i{tagOrId beforeThis string}
1229
For each of the items given by @i{tagOrId}, if the item supports
1230
text insertion then @i{string} is inserted into the item's
1231
text just before the character whose index is @i{beforeThis}.
1232
See INDICES above for information about the forms allowed
1234
This command returns an empty string.
1235
@item @i{pathName }@b{:itemconfigure }@i{tagOrId}@r{ ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
1236
This command is similar to the @b{configure} widget command except
1237
that it modifies item-specific options for the items given by
1238
@i{tagOrId} instead of modifying options for the overall
1240
If no @i{option} is specified, returns a list describing all of
1241
the available options for the first item given by @i{tagOrId}
1242
(see @b{Tk_ConfigureInfo} for
1243
information on the format of this list). If @i{option} is specified
1244
with no @i{value}, then the command returns a list describing the
1245
one named option (this list will be identical to the corresponding
1246
sublist of the value returned if no @i{option} is specified). If
1247
one or more @i{option:value} pairs are specified, then the command
1248
modifies the given widget option(s) to have the given value(s) in
1249
each of the items given by @i{tagOrId}; in
1250
this case the command returns an empty string.
1251
The @i{option}@r{s and }@i{value}s are the same as those permissible
1252
in the @b{create} widget command when the item(s) were created;
1253
see the sections describing individual item types below for details
1254
on the legal options.
1255
@item @i{pathName }@b{:lower }@i{tagOrId }@r{?}@i{belowThis}?
1256
Move all of the items given by @i{tagOrId} to a new position
1257
in the display list just before the item given by @i{belowThis}.
1258
If @i{tagOrId} refers to more than one item then all are moved
1259
but the relative order of the moved items will not be changed.
1260
@i{BelowThis} is a tag or id; if it refers to more than one
1261
item then the first (lowest) of these items in the display list is used
1262
as the destination location for the moved items.
1263
This command returns an empty string.
1264
@item @i{pathName }@b{:move }@i{tagOrId xAmount yAmount}
1265
Move each of the items given by @i{tagOrId} in the canvas coordinate
1266
space by adding @i{xAmount} to the x-coordinate of each point
1267
associated with the item and @i{yAmount} to the y-coordinate of
1268
each point associated with the item.
1269
This command returns an empty string.
1270
@item @i{pathName }@b{:postscript }@r{?}@i{option value option value ...}?
1271
Generate a Postscript representation for part or all of the canvas.
1272
If the @b{:file} option is specified then the Postscript is written
1273
to a file and an empty string is returned; otherwise the Postscript
1274
is returned as the result of the command.
1275
The Postscript is created in Encapsulated Postscript form using
1276
version 3.0 of the Document Structuring Conventions.
1277
The @i{option}\-@i{value} argument pairs provide additional
1278
information to control the generation of Postscript. The following
1279
options are supported:
1282
@item @b{:colormap }@i{varName}
1283
@i{VarName} must be the name of a global array variable
1284
that specifies a color mapping to use in the Postscript.
1285
Each element of @i{varName} must consist of Postscript
1286
code to set a particular color value (e.g. ``@b{1.0 1.0 0.0 setrgbcolor}'').
1287
When outputting color information in the Postscript, Tk checks
1288
to see if there is an element of @i{varName} with the same
1290
If so, Tk uses the value of the element as the Postscript command
1292
If this option hasn't been specified, or if there isn't an entry
1293
in @i{varName} for a given color, then Tk uses the red, green,
1294
and blue intensities from the X color.
1295
@item @b{:colormode }@i{mode}
1296
Specifies how to output color information. @i{Mode} must be either
1297
@b{color}@r{ (for full color output), }@b{gray} (convert all colors
1298
to their gray-scale equivalents) or @b{mono} (convert all colors
1300
@item @b{:file }@i{fileName}
1301
Specifies the name of the file in which to write the Postscript.
1302
If this option isn't specified then the Postscript is returned as the
1303
result of the command instead of being written to a file.
1304
@item @b{:fontmap }@i{varName}
1305
@i{VarName} must be the name of a global array variable
1306
that specifies a font mapping to use in the Postscript.
1307
Each element of @i{varName} must consist of a Tcl list with
1308
two elements, which are the name and point size of a Postscript font.
1309
When outputting Postscript commands for a particular font, Tk
1310
checks to see if @i{varName} contains an element with the same
1312
If there is such an element, then the font information contained in
1313
that element is used in the Postscript.
1314
Otherwise Tk attempts to guess what Postscript font to use.
1315
Tk's guesses generally only work for well-known fonts such as
1316
Times and Helvetica and Courier, and only if the X font name does not
1317
omit any dashes up through the point size.
1318
For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-* will work but
1319
\fB*Courier\-Bold\-R\-Normal*120* will not; Tk needs the dashes to
1320
parse the font name).
1321
@item @b{:height }@i{size}
1322
Specifies the height of the area of the canvas to print.
1323
Defaults to the height of the canvas window.
1324
@item @b{:pageanchor }@i{anchor}
1325
Specifies which point of the printed area should be appear over
1326
the positioning point on the page (which is given by the @b{:pagex}
1327
and @b{:pagey} options).
1328
For example, @b{:pageanchor n} means that the top center of the
1329
printed area should be over the positioning point.
1330
Defaults to @b{center}.
1331
@item @b{:pageheight }@i{size}
1332
Specifies that the Postscript should be scaled in both x and y so
1333
that the printed area is @i{size} high on the Postscript page.
1334
@i{Size} consists of a floating-point number followed by
1335
@b{c}@r{ for centimeters, }@b{i}@r{ for inches, }@b{m} for millimeters,
1336
or @b{p} or nothing for printer's points (1/72 inch).
1337
Defaults to the height of the printed area on the screen.
1338
If both @b{:pageheight}@r{ and }@b{:pagewidth} are specified then
1339
the scale factor from the later option is used (non-uniform scaling
1340
is not implemented).
1341
@item @b{:pagewidth }@i{size}
1342
Specifies that the Postscript should be scaled in both x and y so
1343
that the printed area is @i{size} wide on the Postscript page.
1344
@i{Size}@r{ has the same form as for }@b{:pageheight}.
1345
Defaults to the width of the printed area on the screen.
1346
If both @b{:pageheight}@r{ and }@b{:pagewidth} are specified then
1347
the scale factor from the later option is used (non-uniform scaling
1348
is not implemented).
1349
@item @b{:pagex }@i{position}
1350
@i{Position} gives the x-coordinate of the positioning point on
1351
the Postscript page, using any of the forms allowed for @b{:pageheight}.
1352
Used in conjunction with the @b{:pagey}@r{ and }@b{:pageanchor} options
1353
to determine where the printed area appears on the Postscript page.
1354
Defaults to the center of the page.
1355
@item @b{:pagey }@i{position}
1356
@i{Position} gives the y-coordinate of the positioning point on
1357
the Postscript page, using any of the forms allowed for @b{:pageheight}.
1358
Used in conjunction with the @b{:pagex}@r{ and }@b{:pageanchor} options
1359
to determine where the printed area appears on the Postscript page.
1360
Defaults to the center of the page.
1361
@item @b{:rotate }@i{boolean}
1362
@i{Boolean} specifies whether the printed area is to be rotated 90
1364
In non-rotated output the x-axis of the printed area runs along
1365
the short dimension of the page (``portrait'' orientation);
1366
in rotated output the x-axis runs along the long dimension of the
1367
page (``landscape'' orientation).
1368
Defaults to non-rotated.
1369
@item @b{:width }@i{size}
1370
Specifies the width of the area of the canvas to print.
1371
Defaults to the width of the canvas window.
1372
@item @b{:x }@i{position}
1373
Specifies the x-coordinate of the left edge of the area of the
1374
canvas that is to be printed, in canvas coordinates, not window
1376
Defaults to the coordinate of the left edge of the window.
1377
@item @b{:y }@i{position}
1378
Specifies the y-coordinate of the top edge of the area of the
1379
canvas that is to be printed, in canvas coordinates, not window
1381
Defaults to the coordinate of the top edge of the window.
1384
@item @i{pathName }@b{:raise }@i{tagOrId }@r{?}@i{aboveThis}?
1385
Move all of the items given by @i{tagOrId} to a new position
1386
in the display list just after the item given by @i{aboveThis}.
1387
If @i{tagOrId} refers to more than one item then all are moved
1388
but the relative order of the moved items will not be changed.
1389
@i{AboveThis} is a tag or id; if it refers to more than one
1390
item then the last (topmost) of these items in the display list is used
1391
as the destination location for the moved items.
1392
This command returns an empty string.
1393
@item @i{pathName }@b{:scale }@i{tagOrId xOrigin yOrigin xScale yScale}
1394
Rescale all of the items given by @i{tagOrId} in canvas coordinate
1396
@i{XOrigin}@r{ and }@i{yOrigin} identify the origin for the scaling
1397
operation and @i{xScale}@r{ and }@i{yScale} identify the scale
1398
factors for x- and y-coordinates, respectively (a scale factor of
1399
1.0 implies no change to that coordinate).
1400
For each of the points defining each item, the x-coordinate is
1401
adjusted to change the distance from @i{xOrigin} by a factor
1403
Similarly, each y-coordinate is adjusted to change the distance
1404
from @i{yOrigin}@r{ by a factor of }@i{yScale}.
1405
This command returns an empty string.
1406
@item @i{pathName }@b{:scan}@r{ }@i{option args}
1407
This command is used to implement scanning on canvases. It has
1408
two forms, depending on @i{option}:
1411
@item @i{pathName }@b{:scan :mark }@i{x y}
1412
Records @i{x}@r{ and }@i{y} and the canvas's current view; used
1413
in conjunction with later @b{scan dragto} commands.
1414
Typically this command is associated with a mouse button press in
1415
the widget and @i{x}@r{ and }@i{y} are the coordinates of the
1416
mouse. It returns an empty string.
1417
@item @i{pathName }@b{:scan :dragto }@i{x y}.
1418
This command computes the difference between its @i{x}@r{ and }@i{y}
1419
arguments (which are typically mouse coordinates) and the @i{x} and
1420
@i{y}@r{ arguments to the last }@b{scan mark} command for the widget.
1421
It then adjusts the view by 10 times the
1422
difference in coordinates. This command is typically associated
1423
with mouse motion events in the widget, to produce the effect of
1424
dragging the canvas at high speed through its window. The return
1425
value is an empty string.
1428
@item @i{pathName }@b{:select }@i{option}@r{ ?}@i{tagOrId arg}?
1429
Manipulates the selection in one of several ways, depending on
1431
The command may take any of the forms described below.
1432
In all of the descriptions below, @i{tagOrId} must refer to
1433
an item that supports indexing and selection; if it refers to
1434
multiple items then the first of
1435
these that supports indexing and the selection is used.
1436
@i{Index} gives a textual description of a position
1437
within @i{tagOrId}, as described in INDICES above.
1440
@item @i{pathName }@b{:select :adjust }@i{tagOrId index}
1441
Locate the end of the selection in @i{tagOrId} nearest
1442
to the character given by @i{index}, and adjust that
1443
end of the selection to be at @i{index} (i.e. including
1444
but not going beyond @i{index}).
1445
The other end of the selection is made the anchor point
1446
for future @b{select to} commands.
1447
If the selection isn't currently in @i{tagOrId} then
1448
this command behaves the same as the @b{select to} widget
1450
Returns an empty string.
1451
@item @i{pathName }@b{:select :clear}
1452
Clear the selection if it is in this widget.
1453
If the selection isn't in this widget then the command
1455
Returns an empty string.
1456
@item @i{pathName }@b{:select :from }@i{tagOrId index}
1457
Set the selection anchor point for the widget to be just
1458
before the character
1459
given by @i{index}@r{ in the item given by }@i{tagOrId}.
1460
This command doesn't change the selection; it just sets
1461
the fixed end of the selection for future @b{select to}
1463
Returns an empty string.
1464
@item @i{pathName }@b{:select :item}
1465
Returns the id of the selected item, if the selection is in an
1466
item in this canvas.
1467
If the selection is not in this canvas then an empty string
1469
@item @i{pathName }@b{:select :to }@i{tagOrId index}
1470
Set the selection to consist of those characters of @i{tagOrId}
1471
between the selection anchor point and
1473
The new selection will include the character given by @i{index};
1474
it will include the character given by the anchor point only if
1475
@i{index} is greater than or equal to the anchor point.
1476
The anchor point is determined by the most recent @b{select adjust}
1477
or @b{select from} command for this widget.
1478
If the selection anchor point for the widget isn't currently in
1479
@i{tagOrId}, then it is set to the same character given
1481
Returns an empty string.
1484
@item @i{pathName }@b{:type}@i{ tagOrId}
1485
Returns the type of the item given by @i{tagOrId}, such as
1486
@b{rectangle}@r{ or }@b{text}.
1487
If @i{tagOrId} refers to more than one item, then the type
1488
of the first item in the display list is returned.
1489
If @i{tagOrId} doesn't refer to any items at all then
1490
an empty string is returned.
1491
@item @i{pathName }@b{:xview}@i{ index}
1492
Change the view in the canvas so that the canvas position given by
1493
@i{index} appears at the left edge of the window.
1494
This command is typically used by scrollbars to scroll the
1496
@i{Index} counts in units of scroll increments (the value of the
1497
@b{scrollIncrement} option): a value of 0 corresponds to the left
1498
edge of the scroll region (as defined by the @b{scrollRegion}
1499
option), a value of 1 means one scroll unit to the right of this,
1500
and so on. The return value is an empty string.
1501
@item @i{pathName }@b{:yview}@i{ index}
1502
Change the view in the canvas so that the canvas position given by
1503
@i{index} appears at the top edge of the window.
1504
This command is typically used by scrollbars to scroll the
1506
@i{Index} counts in units of scroll increments (the value of the
1507
@b{scrollIncrement} option): a value of 0 corresponds to the top
1508
edge of the scroll region (as defined by the @b{scrollRegion}
1509
option), a value of 1 means one scroll unit below this,
1510
and so on. The return value is an empty string.
1513
@unnumberedsubsec Overview Of Item Types
1515
The sections below describe the various types of items supported
1516
by canvas widgets. Each item type is characterized by two things:
1517
first, the form of the @b{create} command used to create
1518
instances of the type; and second, a set of configuration options
1519
for items of that type, which may be used in the
1520
@b{create}@r{ and }@b{itemconfigure} widget commands.
1521
Most items don't support indexing or selection or the commands
1522
related to them, such as @b{index}@r{ and }@b{insert}.
1523
Where items do support these facilities, it is noted explicitly
1524
in the descriptions below (at present, only text items provide
1527
@unnumberedsubsec Arc Items
1529
Items of type @b{arc} appear on the display as arc-shaped regions.
1530
An arc is a section of an oval delimited by two angles (specified
1531
by the @b{:start}@r{ and }@b{:extent} options) and displayed in
1532
one of several ways (specified by the @b{:style} option).
1533
Arcs are created with widget commands of the following form:
1536
@item @i{pathName }@b{:create arc }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?
1537
The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
1538
the coordinates of two diagonally opposite corners of a
1539
rectangular region enclosing the oval that defines the arc.
1540
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1541
pairs, each of which sets one of the configuration options
1542
for the item. These same @i{option}\-@i{value} pairs may be
1543
used in @b{itemconfigure} widget commands to change the item's
1545
The following options are supported for arcs:
1548
@item @b{:extent }@i{degrees}
1549
Specifies the size of the angular range occupied by the arc.
1550
The arc's range extends for @i{degrees} degrees counter-clockwise
1551
from the starting angle given by the @b{:start} option.
1552
@i{Degrees} may be negative.
1553
@item @b{:fill }@i{color}
1554
Fill the region of the arc with @i{color}.
1555
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
1556
If @i{color} is an empty string (the default), then
1557
then the arc will not be filled.
1558
@item @b{:outline }@i{color}
1559
@i{Color} specifies a color to use for drawing the arc's
1560
outline; it may have any of the forms accepted by @b{Tk_GetColor}.
1561
This option defaults to @b{black}. If the arc's style is
1562
@b{arc} then this option is ignored (the section of perimeter is
1563
filled using the @b{:fill}@r{ option). If }@i{color} is specified
1564
as an empty string then no outline is drawn for the arc.
1565
@item @b{:start }@i{degrees}
1566
Specifies the beginning of the angular range occupied by the
1568
@i{Degrees} is given in units of degrees measured counter-clockwise
1569
from the 3-o'clock position; it may be either positive or negative.
1570
@item @b{:stipple }@i{bitmap}
1571
Indicates that the arc should be filled in a stipple pattern;
1572
@i{bitmap} specifies the stipple pattern to use, in any of the
1573
forms accepted by @b{Tk_GetBitmap}.
1574
If the @b{:fill} option hasn't been specified then this option
1576
If @i{bitmap} is an empty string (the default), then filling is done
1578
@item @b{:style }@i{type}
1579
Specifies how to draw the arc. If @i{type}@r{ is }@b{pieslice}
1580
(the default) then the arc's region is defined by a section
1581
of the oval's perimeter plus two line segments, one between the center
1582
of the oval and each end of the perimeter section.
1583
If @i{type}@r{ is }@b{chord} then the arc's region is defined
1584
by a section of the oval's perimeter plus a single line segment
1585
connecting the two end points of the perimeter section.
1586
If @i{type}@r{ is }@b{arc} then the arc's region consists of
1587
a section of the perimeter alone. In this last case there is
1588
no outline for the arc and the @b{:outline} option is ignored.
1589
@item @b{:tags }@i{tagList}
1590
Specifies a set of tags to apply to the item.
1591
@i{TagList} consists of a list of tag names, which replace any
1592
existing tags for the item.
1593
@i{TagList} may be an empty list.
1594
@item @b{:width }@i{outlineWidth}
1595
Specifies the width of the outline to be drawn around
1596
the arc's region, in any of the forms described in the COORDINATES
1598
If the @b{:outline} option has been specified as an empty string
1599
then this option has no effect.
1600
Wide outlines will be drawn centered on the edges of the arc's region.
1601
This option defaults to 1.0.
1605
@unnumberedsubsec Bitmap Items
1607
Items of type @b{bitmap} appear on the display as images with
1608
two colors, foreground and background.
1609
Bitmaps are created with widget commands of the following form:
1612
@item @i{pathName }@b{:create bitmap }@i{x y }@r{?}@i{option value option value ...}?
1613
The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
1614
point used to position the bitmap on the display (see the @b{:anchor}
1615
option below for more information on how bitmaps are displayed).
1616
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1617
pairs, each of which sets one of the configuration options
1618
for the item. These same @i{option}\-@i{value} pairs may be
1619
used in @b{itemconfigure} widget commands to change the item's
1621
The following options are supported for bitmaps:
1624
@item @b{:anchor }@i{anchorPos}
1625
@i{AnchorPos} tells how to position the bitmap relative to the
1626
positioning point for the item; it may have any of the forms
1627
accepted by @b{Tk_GetAnchor}@r{. For example, if }@i{anchorPos}
1628
is @b{center} then the bitmap is centered on the point; if
1629
@i{anchorPos}@r{ is }@b{n} then the bitmap will be drawn so that
1630
its top center point is at the positioning point.
1631
This option defaults to @b{center}.
1632
@item @b{:background }@i{color}
1633
Specifies a color to use for each of the bitmap pixels
1635
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
1636
If this option isn't specified, or if it is specified as an empty
1637
string, then the background color for the canvas is used.
1638
@item @b{:bitmap }@i{bitmap}
1639
Specifies the bitmap to display in the item.
1640
@i{Bitmap}@r{ may have any of the forms accepted by }@b{Tk_GetBitmap}.
1641
@item @b{:foreground }@i{color}
1642
Specifies a color to use for each of the bitmap pixels
1644
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor} and
1645
defaults to @b{black}.
1646
@item @b{:tags }@i{tagList}
1647
Specifies a set of tags to apply to the item.
1648
@i{TagList} consists of a list of tag names, which replace any
1649
existing tags for the item.
1650
@i{TagList} may be an empty list.
1653
@unnumberedsubsec Line Items
1655
Items of type @b{line} appear on the display as one or more connected
1656
line segments or curves.
1657
Lines are created with widget commands of the following form:
1660
@item @i{pathName }@b{:create line }@i{x1 y1... xn yn }@r{?}@i{option value option value ...}?
1662
The arguments @i{x1}@r{ through }@i{yn} give
1663
the coordinates for a series of two or more points that describe
1664
a series of connected line segments.
1665
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1666
pairs, each of which sets one of the configuration options
1667
for the item. These same @i{option}\-@i{value} pairs may be
1668
used in @b{itemconfigure} widget commands to change the item's
1670
The following options are supported for lines:
1673
@item @b{:arrow }@i{where}
1674
Indicates whether or not arrowheads are to be drawn at one or both
1676
@i{Where}@r{ must have one of the values }@b{none} (for no arrowheads),
1677
@b{first} (for an arrowhead at the first point of the line),
1678
@b{last} (for an arrowhead at the last point of the line), or
1679
@b{both} (for arrowheads at both ends).
1680
This option defaults to @b{none}.
1681
@item @b{:arrowshape }@i{shape}
1682
This option indicates how to draw arrowheads.
1683
The @i{shape} argument must be a list with three elements, each
1684
specifying a distance in any of the forms described in
1685
the COORDINATES section above.
1686
The first element of the list gives the distance along the line
1687
from the neck of the arrowhead to its tip.
1688
The second element gives the distance along the line from the
1689
trailing points of the arrowhead to the tip, and the third
1690
element gives the distance from the outside edge of the line to the
1692
If this option isn't specified then Tk picks a ``reasonable'' shape.
1693
@item @b{:capstyle }@i{style}
1694
Specifies the ways in which caps are to be drawn at the endpoints
1696
@i{Style}@r{ may have any of the forms accepted by }@b{Tk_GetCapStyle}
1697
(@b{butt}@r{, }@b{projecting}@r{, or }@b{round}).
1698
If this option isn't specified then it defaults to @b{butt}.
1699
Where arrowheads are drawn the cap style is ignored.
1700
@item @b{:fill }@i{color}
1701
@i{Color} specifies a color to use for drawing the line; it may have
1702
any of the forms acceptable to @b{Tk_GetColor}. It may also be an
1703
empty string, in which case the line will be transparent.
1704
This option defaults to @b{black}.
1705
@item @b{:joinstyle }@i{style}
1706
Specifies the ways in which joints are to be drawn at the vertices
1708
@i{Style}@r{ may have any of the forms accepted by }@b{Tk_GetCapStyle}
1709
(@b{bevel}@r{, }@b{miter}@r{, or }@b{round}).
1710
If this option isn't specified then it defaults to @b{miter}.
1711
If the line only contains two points then this option is
1713
@item @b{:smooth }@i{boolean}
1714
@i{Boolean}@r{ must have one of the forms accepted by }@b{Tk_GetBoolean}.
1715
It indicates whether or not the line should be drawn as a curve.
1716
If so, the line is rendered as a set of Bezier splines: one spline
1717
is drawn for the first and second line segments, one for the second
1718
and third, and so on. Straight-line segments can be generated within
1719
a curve by duplicating the end-points of the desired line segment.
1720
@item @b{:splinesteps }@i{number}
1721
Specifies the degree of smoothness desired for curves: each spline
1722
will be approximated with @i{number} line segments. This
1723
option is ignored unless the @b{:smooth} option is true.
1724
@item @b{:stipple }@i{bitmap}
1725
Indicates that the line should be filled in a stipple pattern;
1726
@i{bitmap} specifies the stipple pattern to use, in any of the
1727
forms accepted by @b{Tk_GetBitmap}.
1728
If @i{bitmap} is an empty string (the default), then filling is
1729
done in a solid fashion.
1730
@item @b{:tags }@i{tagList}
1731
Specifies a set of tags to apply to the item.
1732
@i{TagList} consists of a list of tag names, which replace any
1733
existing tags for the item.
1734
@i{TagList} may be an empty list.
1735
@item @b{:width }@i{lineWidth}
1736
@i{LineWidth} specifies the width of the line, in any of the forms
1737
described in the COORDINATES section above.
1738
Wide lines will be drawn centered on the path specified by the
1740
If this option isn't specified then it defaults to 1.0.
1743
@unnumberedsubsec Oval Items
1745
Items of type @b{oval} appear as circular or oval regions on
1746
the display. Each oval may have an outline, a fill, or
1747
both. Ovals are created with widget commands of the
1751
@item @i{pathName }@b{:create oval }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?
1753
The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
1754
the coordinates of two diagonally opposite corners of a
1755
rectangular region enclosing the oval.
1756
The oval will include the top and left edges of the rectangle
1757
not the lower or right edges.
1758
If the region is square then the resulting oval is circular;
1759
otherwise it is elongated in shape.
1760
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1761
pairs, each of which sets one of the configuration options
1762
for the item. These same @i{option}\-@i{value} pairs may be
1763
used in @b{itemconfigure} widget commands to change the item's
1765
The following options are supported for ovals:
1768
@item @b{:fill }@i{color}
1769
Fill the area of the oval with @i{color}.
1770
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
1771
If @i{color} is an empty string (the default), then
1772
then the oval will not be filled.
1773
@item @b{:outline }@i{color}
1774
@i{Color} specifies a color to use for drawing the oval's
1775
outline; it may have any of the forms accepted by @b{Tk_GetColor}.
1776
This option defaults to @b{black}.
1777
If @i{color} is an empty string then no outline will be
1779
@item @b{:stipple }@i{bitmap}
1780
Indicates that the oval should be filled in a stipple pattern;
1781
@i{bitmap} specifies the stipple pattern to use, in any of the
1782
forms accepted by @b{Tk_GetBitmap}.
1783
If the @b{:fill} option hasn't been specified then this option
1785
If @i{bitmap} is an empty string (the default), then filling is done
1787
@item @b{:tags }@i{tagList}
1788
Specifies a set of tags to apply to the item.
1789
@i{TagList} consists of a list of tag names, which replace any
1790
existing tags for the item.
1791
@i{TagList} may be an empty list.
1792
@item @b{:width }@i{outlineWidth}
1793
@i{outlineWidth} specifies the width of the outline to be drawn around
1794
the oval, in any of the forms described in the COORDINATES section above.
1795
If the @b{:outline} option hasn't been specified then this option
1797
Wide outlines are drawn centered on the oval path defined by
1798
@i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
1799
This option defaults to 1.0.
1802
@unnumberedsubsec Polygon Items
1804
Items of type @b{polygon} appear as polygonal or curved filled regions
1806
Polygons are created with widget commands of the following form:
1809
@item @i{pathName }@b{:create polygon }@i{x1 y1 ... xn yn }@r{?}@i{option value option value ...}?
1812
The arguments @i{x1}@r{ through }@i{yn} specify the coordinates for
1813
three or more points that define a closed polygon.
1814
The first and last points may be the same; whether they are or not,
1815
Tk will draw the polygon as a closed polygon.
1816
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1817
pairs, each of which sets one of the configuration options
1818
for the item. These same @i{option}\-@i{value} pairs may be
1819
used in @b{itemconfigure} widget commands to change the item's
1821
The following options are supported for polygons:
1824
@item @b{:fill }@i{color}
1825
@i{Color} specifies a color to use for filling the area of the
1826
polygon; it may have any of the forms acceptable to @b{Tk_GetColor}.
1827
If @i{color} is an empty string then the polygon will be
1829
This option defaults to @b{black}.
1830
@item @b{:smooth }@i{boolean}
1831
@i{Boolean}@r{ must have one of the forms accepted by }@b{Tk_GetBoolean}
1832
It indicates whether or not the polygon should be drawn with a
1834
If so, the outline of the polygon becomes a set of Bezier splines,
1835
one spline for the first and second line segments, one for the second
1836
and third, and so on. Straight-line segments can be generated in a
1837
smoothed polygon by duplicating the end-points of the desired line segment.
1838
@item @b{:splinesteps }@i{number}
1839
Specifies the degree of smoothness desired for curves: each spline
1840
will be approximated with @i{number} line segments. This
1841
option is ignored unless the @b{:smooth} option is true.
1842
@item @b{:stipple }@i{bitmap}
1843
Indicates that the polygon should be filled in a stipple pattern;
1844
@i{bitmap} specifies the stipple pattern to use, in any of the
1845
forms accepted by @b{Tk_GetBitmap}.
1846
If @i{bitmap} is an empty string (the default), then filling is
1847
done in a solid fashion.
1848
@item @b{:tags }@i{tagList}
1849
Specifies a set of tags to apply to the item.
1850
@i{TagList} consists of a list of tag names, which replace any
1851
existing tags for the item.
1852
@i{TagList} may be an empty list.
1856
@unnumberedsubsec Rectangle Items
1858
Items of type @b{rectangle} appear as rectangular regions on
1859
the display. Each rectangle may have an outline, a fill, or
1860
both. Rectangles are created with widget commands of the
1864
@item @i{pathName }@b{:create rectangle }@i{x1 y1 x2 y2 }@r{?}@i{option value option value ...}?
1866
The arguments @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2} give
1867
the coordinates of two diagonally opposite corners of the rectangle
1868
(the rectangle will include its upper and left edges but not
1869
its lower or right edges).
1870
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1871
pairs, each of which sets one of the configuration options
1872
for the item. These same @i{option}\-@i{value} pairs may be
1873
used in @b{itemconfigure} widget commands to change the item's
1875
The following options are supported for rectangles:
1878
@item @b{:fill }@i{color}
1879
Fill the area of the rectangle with @i{color}, which may be
1880
specified in any of the forms accepted by @b{Tk_GetColor}.
1881
If @i{color} is an empty string (the default), then
1882
then the rectangle will not be filled.
1883
@item @b{:outline }@i{color}
1884
Draw an outline around the edge of the rectangle in @i{color}.
1885
@i{Color}@r{ may have any of the forms accepted by }@b{Tk_GetColor}.
1886
This option defaults to @b{black}.
1887
If @i{color} is an empty string then no outline will be
1888
drawn for the rectangle.
1889
@item @b{:stipple }@i{bitmap}
1890
Indicates that the rectangle should be filled in a stipple pattern;
1891
@i{bitmap} specifies the stipple pattern to use, in any of the
1892
forms accepted by @b{Tk_GetBitmap}.
1893
If the @b{:fill} option hasn't been specified then this option
1895
If @i{bitmap} is an empty string (the default), then filling
1896
is done in a solid fashion.
1897
@item @b{:tags }@i{tagList}
1898
Specifies a set of tags to apply to the item.
1899
@i{TagList} consists of a list of tag names, which replace any
1900
existing tags for the item.
1901
@i{TagList} may be an empty list.
1902
@item @b{:width }@i{outlineWidth}
1903
@i{OutlineWidth} specifies the width of the outline to be drawn around
1904
the rectangle, in any of the forms described in the COORDINATES section above.
1905
If the @b{:outline} option hasn't been specified then this option
1907
Wide outlines are drawn centered on the rectangular path
1908
defined by @i{x1}@r{, }@i{y1}@r{, }@i{x2}@r{, and }@i{y2}.
1909
This option defaults to 1.0.
1912
@unnumberedsubsec Text Items
1914
A text item displays a string of characters on the screen in one
1916
Text items support indexing and selection, along with the
1917
following text-related canvas widget commands: @b{dchars},
1918
@b{focus}@r{, }@b{icursor}@r{, }@b{index}@r{, }@b{insert},
1920
Text items are created with widget commands of the following
1924
@item @i{pathName }@b{:create text }@i{x y }@r{?}@i{option value option value ...}?
1926
The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
1927
point used to position the text on the display (see the options
1928
below for more information on how text is displayed).
1929
After the coordinates there may be any number of @i{option}@r{-}@i{value}
1930
pairs, each of which sets one of the configuration options
1931
for the item. These same @i{option}\-@i{value} pairs may be
1932
used in @b{itemconfigure} widget commands to change the item's
1934
The following options are supported for text items:
1937
@item @b{:anchor }@i{anchorPos}
1938
@i{AnchorPos} tells how to position the text relative to the
1939
positioning point for the text; it may have any of the forms
1940
accepted by @b{Tk_GetAnchor}@r{. For example, if }@i{anchorPos}
1941
is @b{center} then the text is centered on the point; if
1942
@i{anchorPos}@r{ is }@b{n} then the text will be drawn such that
1943
the top center point of the rectangular region occupied by the
1944
text will be at the positioning point.
1945
This option defaults to @b{center}.
1946
@item @b{:fill }@i{color}
1947
@i{Color} specifies a color to use for filling the text characters;
1948
it may have any of the forms accepted by @b{Tk_GetColor}.
1949
If this option isn't specified then it defaults to @b{black}.
1950
@item @b{:font }@i{fontName}
1951
Specifies the font to use for the text item.
1952
@i{FontName}@r{ may be any string acceptable to }@b{Tk_GetFontStruct}.
1953
If this option isn't specified, it defaults to a system-dependent
1955
@item @b{:justify }@i{how}
1956
Specifies how to justify the text within its bounding region.
1957
@i{How}@r{ must be one of the values }@b{left}@r{, }@b{right},
1959
This option will only matter if the text is displayed as multiple
1961
If the option is omitted, it defaults to @b{left}.
1962
@item @b{:stipple }@i{bitmap}
1963
Indicates that the text should be drawn in a stippled pattern
1965
@i{bitmap} specifies the stipple pattern to use, in any of the
1966
forms accepted by @b{Tk_GetBitmap}.
1967
If @i{bitmap} is an empty string (the default) then the text
1968
is drawn in a solid fashion.
1969
@item @b{:tags }@i{tagList}
1970
Specifies a set of tags to apply to the item.
1971
@i{TagList} consists of a list of tag names, which replace any
1972
existing tags for the item.
1973
@i{TagList} may be an empty list.
1974
@item @b{:text }@i{string}
1975
@i{String} specifies the characters to be displayed in the text item.
1976
Newline characters cause line breaks.
1977
The characters in the item may also be changed with the
1978
@b{insert}@r{ and }@b{delete} widget commands.
1979
This option defaults to an empty string.
1980
@item @b{:width }@i{lineLength}
1981
Specifies a maximum line length for the text, in any of the forms
1982
described in the COORDINATES section abov.
1983
If this option is zero (the default) the text is broken into
1984
lines only at newline characters.
1985
However, if this option is non-zero then any line that would
1986
be longer than @i{lineLength} is broken just before a space
1987
character to make the line shorter than @i{lineLength}; the
1988
space character is treated as if it were a newline
1993
@unnumberedsubsec Window Items
1995
Items of type @b{window} cause a particular window to be displayed
1996
at a given position on the canvas.
1997
Window items are created with widget commands of the following form:
2000
@i{pathName }@b{:create window }@i{x y }@r{?}@i{option value option value ...}?
2003
The arguments @i{x}@r{ and }@i{y} specify the coordinates of a
2004
point used to position the window on the display (see the @b{:anchor}
2005
option below for more information on how bitmaps are displayed).
2006
After the coordinates there may be any number of @i{option}@r{-}@i{value}
2007
pairs, each of which sets one of the configuration options
2008
for the item. These same @i{option}\-@i{value} pairs may be
2009
used in @b{itemconfigure} widget commands to change the item's
2011
The following options are supported for window items:
2014
@item @b{:anchor }@i{anchorPos}
2015
@i{AnchorPos} tells how to position the window relative to the
2016
positioning point for the item; it may have any of the forms
2017
accepted by @b{Tk_GetAnchor}@r{. For example, if }@i{anchorPos}
2018
is @b{center} then the window is centered on the point; if
2019
@i{anchorPos}@r{ is }@b{n} then the window will be drawn so that
2020
its top center point is at the positioning point.
2021
This option defaults to @b{center}.
2022
@item @b{:height }@i{pixels}
2023
Specifies the height to assign to the item's window.
2024
@i{Pixels} may have any of the
2025
forms described in the COORDINATES section above.
2026
If this option isn't specified, or if it is specified as an empty
2027
string, then the window is given whatever height it requests internally.
2028
@item @b{:tags }@i{tagList}
2029
Specifies a set of tags to apply to the item.
2030
@i{TagList} consists of a list of tag names, which replace any
2031
existing tags for the item.
2032
@i{TagList} may be an empty list.
2033
@item @b{:width }@i{pixels}
2034
Specifies the width to assign to the item's window.
2035
@i{Pixels} may have any of the
2036
forms described in the COORDINATES section above.
2037
If this option isn't specified, or if it is specified as an empty
2038
string, then the window is given whatever width it requests internally.
2039
@item @b{:window }@i{pathName}
2040
Specifies the window to associate with this item.
2041
The window specified by @i{pathName} must either be a child of
2042
the canvas widget or a child of some ancestor of the canvas widget.
2043
@i{PathName} may not refer to a top-level window.
2046
@unnumberedsubsec Application-Defined Item Types
2048
It is possible for individual applications to define new item
2049
types for canvas widgets using C code.
2050
The interfaces for this mechanism are not presently documented,
2051
and it's possible they may change, but you should be able to
2052
see how they work by examining the code for some of the existing
2055
@unnumberedsubsec Bindings
2057
In the current implementation, new canvases are not given any
2058
default behavior: you'll have to execute explicit Tcl commands
2059
to give the canvas its behavior.
2061
@unnumberedsubsec Credits
2063
Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
2064
@i{ezd}@r{ program. }@i{Ezd} provides structured graphics in a Scheme
2065
environment and preceded canvases by a year or two. Its simple
2066
mechanisms for placing and animating graphical objects inspired the
2067
functions of canvases.
2069
@unnumberedsubsec Keywords
2071
@node menu, scrollbar, canvas, Widgets
2075
menu \- Create and manipulate menu widgets
2076
@unnumberedsubsec Synopsis
2077
@b{menu}@i{ }@i{pathName }@r{?}@i{options}?
2078
@unnumberedsubsec Standard Options
2082
activeBackground background disabledForeground
2083
activeBorderWidth borderWidth font
2084
activeForeground cursor foreground
2088
@xref{options}, for more information.
2089
@unnumberedsubsec Arguments for Menu
2093
@item @code{@b{:postcommand}}
2095
Name=@code{"@b{postCommand}@r{"} Class=@code{"}@b{Command}"}
2099
If this option is specified then it provides a Tcl command to execute
2100
each time the menu is posted. The command is invoked by the @b{post}
2101
widget command before posting the menu.
2106
@item @code{@b{:selector}}
2108
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
2112
For menu entries that are check buttons or radio buttons, this option
2113
specifies the color to display in the selector when the check button
2114
or radio button is selected.
2118
@unnumberedsubsec Introduction
2120
The @b{menu} command creates a new top-level window (given
2121
by the @i{pathName} argument) and makes it into a menu widget.
2123
options, described above, may be specified on the command line
2124
or in the option database
2125
to configure aspects of the menu such as its colors and font.
2126
The @b{menu} command returns its
2127
@i{pathName} argument. At the time this command is invoked,
2128
there must not exist a window named @i{pathName}, but
2129
@i{pathName}'s parent must exist.
2131
A menu is a widget that displays a collection of one-line entries arranged
2132
in a column. There exist several different types of entries,
2133
each with different properties. Entries of different types may be
2134
combined in a single menu. Menu entries are not the same as
2135
entry widgets. In fact, menu entries are not even distinct widgets;
2136
the entire menu is one widget.
2138
Menu entries are displayed with up to three
2139
separate fields. The main field is a label in the form of text or
2140
a bitmap, which is determined by the @b{:label}@r{ or }@b{:bitmap}
2141
option for the entry.
2142
If the @b{:accelerator} option is specified for an entry then a second
2143
textual field is displayed to the right of the label. The accelerator
2144
typically describes a keystroke sequence that may be typed in the
2145
application to cause the same result as invoking the menu entry.
2146
The third field is a @i{selector}. The selector is present only for
2147
check-button or radio-button entries. It indicates whether the entry
2148
is selected or not, and is displayed to the left of the entry's
2151
In normal use, an entry becomes active (displays itself differently)
2152
whenever the mouse pointer is over the entry. If a mouse
2153
button is released over the entry then the entry is @i{invoked}.
2154
The effect of invocation is different for each type of entry;
2155
these effects are described below in the sections on individual
2158
Entries may be @i{disabled}, which causes their labels
2159
and accelerators to be displayed
2160
with dimmer colors. A disabled entry cannot be activated or invoked.
2161
Disabled entries may be re-enabled, at which point it becomes
2162
possible to activate and invoke them again.
2164
@unnumberedsubsec Command Entries
2166
The most common kind of menu entry is a command entry, which
2167
behaves much like a button widget. When a command entry is
2168
invoked, a Tcl command is executed. The Tcl
2169
command is specified with the @b{:command} option.
2171
@unnumberedsubsec Separator Entries
2173
A separator is an entry that is displayed as a horizontal dividing
2174
line. A separator may not be activated or invoked, and it has
2175
no behavior other than its display appearance.
2177
@unnumberedsubsec Check-Button Entries
2179
A check-button menu entry behaves much like a check-button widget.
2180
When it is invoked it toggles back and forth between the selected
2181
and deselected states. When the entry is selected, a particular
2182
value is stored in a particular global variable (as determined by
2183
the @b{:onvalue}@r{ and }@b{:variable} options for the entry); when
2184
the entry is deselected another value (determined by the
2185
@b{:offvalue} option) is stored in the global variable.
2186
A selector box is displayed to the left of the label in a check-button
2187
entry. If the entry is selected then the box's center is displayed
2188
in the color given by the @b{selector} option for the menu;
2189
otherwise the box's center is displayed in the background color for
2190
the menu. If a @b{:command} option is specified for a check-button
2191
entry, then its value is evaluated as a Tcl command each time the entry
2192
is invoked; this happens after toggling the entry's
2195
@unnumberedsubsec Radio-Button Entries
2197
A radio-button menu entry behaves much like a radio-button widget.
2198
Radio-button entries are organized in groups of which only one
2199
entry may be selected at a time. Whenever a particular entry
2200
becomes selected it stores a particular value into a particular
2201
global variable (as determined by the @b{:value} and
2202
@b{:variable} options for the entry). This action
2203
causes any previously-selected entry in the same group
2205
Once an entry has become selected, any change to the entry's
2206
associated variable will cause the entry to deselect itself.
2207
Grouping of radio-button entries is determined by their
2208
associated variables: if two entries have the same associated
2209
variable then they are in the same group.
2210
A selector diamond is displayed to the left of the label in each
2211
radio-button entry. If the entry is selected then the diamond's
2212
center is displayed in the color given by the @b{selector} option
2214
otherwise the diamond's center is displayed in the background color for
2215
the menu. If a @b{:command} option is specified for a radio-button
2216
entry, then its value is evaluated as a Tcl command each time the entry
2217
is invoked; this happens after selecting the entry.
2219
@unnumberedsubsec Cascade Entries
2221
A cascade entry is one with an associated menu (determined
2222
by the @b{:menu} option). Cascade entries allow the construction
2223
of cascading menus. When the entry is activated, the
2224
associated menu is posted just to the right of the entry;
2225
that menu remains posted until the higher-level menu is unposted or
2226
until some other entry is activated in the higher-level menu.
2227
The associated menu should normally be a child of the menu containing
2228
the cascade entry, in order for menu traversal to work correctly.
2230
A cascade entry posts its associated menu by invoking a
2231
Tcl command of the form
2234
@item @i{menu}@b{ :post }@i{x y}
2238
where @i{menu}@r{ is the path name of the associated menu, }@i{x}
2239
and @i{y} are the root-window coordinates of the upper-right
2240
corner of the cascade entry, and @i{group} is the name of the
2241
menu's group (as determined in its last @b{post} widget command).
2242
The lower-level menu is unposted by executing a Tcl command with
2245
@item @i{menu}@b{:unpost}
2246
where @i{menu} is the name of the associated menu.
2249
If a @b{:command} option is specified for a cascade entry then it is
2250
evaluated as a Tcl command each time the associated menu is posted (the
2251
evaluation occurs before the menu is posted).
2253
@unnumberedsubsec A Menu Widget's Arguments
2255
The @b{menu} command creates a new Tcl command whose
2256
name is @i{pathName}. This
2257
command may be used to invoke various
2258
operations on the widget. It has the following general form:
2261
@item @i{pathName option }@r{?}@i{arg arg ...}?
2262
@i{Option}@r{ and the }@i{arg}s
2263
determine the exact behavior of the command.
2266
Many of the widget commands for a menu take as one argument an
2267
indicator of which entry of the menu to operate on. These
2268
indicators are called @i{index}es and may be specified in
2269
any of the following forms:
2273
Specifies the entry numerically, where 0 corresponds
2274
to the top-most entry of the menu, 1 to the entry below it, and
2277
Indicates the entry that is currently active. If no entry is
2278
active then this form is equivalent to @b{none}. This form may
2281
Indicates the bottommost entry in the menu. If there are no
2282
entries in the menu then this form is equivalent to @b{none}.
2283
This form may not be abbreviated.
2285
Indicates ``no entry at all''; this is used most commonly with
2286
the @b{activate} option to deactivate all the entries in the
2287
menu. In most cases the specification of @b{none} causes
2288
nothing to happen in the widget command.
2289
This form may not be abbreviated.
2290
@item @b{@@}@i{number}
2291
In this form, @i{number} is treated as a y-coordinate in the
2292
menu's window; the entry spanning that y-coordinate is used.
2293
For example, ``@b{@@0}'' indicates the top-most entry in the
2294
window. If @i{number} is outside the range of the window
2295
then this form is equivalent to @b{none}.
2297
If the index doesn't satisfy one of the above forms then this
2298
form is used. @i{Pattern} is pattern-matched against the label of
2299
each entry in the menu, in order from the top down, until a
2300
matching entry is found. The rules of @b{Tcl_StringMatch}
2303
The following widget commands are possible for menu widgets:
2304
@item @i{pathName }@b{:activate }@i{index}
2305
Change the state of the entry indicated by @i{index}@r{ to }@b{active}
2306
and redisplay it using its active colors.
2307
Any previously-active entry is deactivated. If @i{index}
2308
is specified as @b{none}, or if the specified entry is
2309
disabled, then the menu ends up with no active entry.
2310
Returns an empty string.
2311
@item @i{pathName }@b{:add }@i{type }@r{?}@i{option value option value ...}?
2312
Add a new entry to the bottom of the menu. The new entry's type
2313
is given by @i{type}@r{ and must be one of }@b{cascade},
2314
@b{checkbutton}@r{, }@b{command}@r{, }@b{radiobutton}@r{, or }@b{separator},
2315
or a unique abbreviation of one of the above. If additional arguments
2316
are present, they specify any of the following options:
2319
@item @b{:activebackground }@i{value}
2320
Specifies a background color to use for displaying this entry when it
2322
If this option is specified as an empty string (the default), then the
2323
@b{activeBackground} option for the overall menu is used.
2324
This option is not available for separator entries.
2325
@item @b{:accelerator }@i{value}
2326
Specifies a string to display at the right side of the menu entry.
2327
Normally describes an accelerator keystroke sequence that may be
2328
typed to invoke the same function as the menu entry. This option
2329
is not available for separator entries.
2330
@item @b{:background }@i{value}
2331
Specifies a background color to use for displaying this entry when it
2332
is in the normal state (neither active nor disabled).
2333
If this option is specified as an empty string (the default), then the
2334
@b{background} option for the overall menu is used.
2335
This option is not available for separator entries.
2336
@item @b{:bitmap }@i{value}
2337
Specifies a bitmap to display in the menu instead of a textual
2338
label, in any of the forms accepted by @b{Tk_GetBitmap}.
2339
This option overrides the @b{:label} option but may be reset
2340
to an empty string to enable a textual label to be displayed.
2341
This option is not available for separator entries.
2342
@item @b{:command }@i{value}
2343
For command, checkbutton, and radiobutton entries, specifies a
2344
Tcl command to execute when the menu entry is invoked.
2345
For cascade entries, specifies a Tcl command to execute
2346
when the entry is activated (i.e. just before its submenu is
2348
Not available for separator entries.
2349
@item @b{:font }@i{value}
2350
Specifies the font to use when drawing the label or accelerator
2351
string in this entry.
2352
If this option is specified as an empty string (the default) then
2353
the @b{font} option for the overall menu is used.
2354
This option is not available for separator entries.
2355
@item @b{:label }@i{value}
2356
Specifies a string to display as an identifying label in the menu
2357
entry. Not available for separator entries.
2358
@item @b{:menu }@i{value}
2359
Available only for cascade entries. Specifies the path name of
2360
the menu associated with this entry.
2361
@item @b{:offvalue }@i{value}
2362
Available only for check-button entries. Specifies the value to
2363
store in the entry's associated variable when the entry is
2365
@item @b{:onvalue }@i{value}
2366
Available only for check-button entries. Specifies the value to
2367
store in the entry's associated variable when the entry is selected.
2368
@item @b{:state }@i{value}
2369
Specifies one of three states for the entry: @b{normal}@r{, }@b{active},
2370
or @b{disabled}. In normal state the entry is displayed using the
2371
@b{foreground}@r{ option for the menu and the }@b{background}
2372
option from the entry or the menu.
2373
The active state is typically used when the pointer is over the entry.
2374
In active state the entry is displayed using the @b{activeForeground}
2375
option for the menu along with the @b{activebackground} option from
2377
Disabled state means that the entry is insensitive: it doesn't activate
2378
and doesn't respond to mouse button presses or releases.
2379
In this state the entry is displayed according to the
2380
@b{disabledForeground} option for the menu and the
2381
@b{background} option from the entry.
2382
This option is not available for separator entries.
2383
@item @b{:underline }@i{value}
2384
Specifies the integer index of a character to underline in the entry.
2385
This option is typically used to indicate keyboard traversal characters.
2386
0 corresponds to the first character of the text displayed in the entry,
2387
1 to the next character, and so on.
2388
If a bitmap is displayed in the entry then this option is ignored.
2389
This option is not available for separator entries.
2390
@item @b{:value }@i{value}
2391
Available only for radio-button entries. Specifies the value to
2392
store in the entry's associated variable when the entry is selected.
2393
@item @b{:variable }@i{value}
2394
Available only for check-button and radio-button entries. Specifies
2395
the name of a global value to set when the entry is selected.
2396
For check-button entries the variable is also set when the entry
2397
is deselected. For radio-button entries, changing the variable
2398
causes the currently-selected entry to deselect itself.
2402
The @b{add} widget command returns an empty string.
2406
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
2407
Query or modify the configuration options of the widget.
2408
If no @i{option} is specified, returns a list describing all of
2409
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
2410
information on the format of this list). If @i{option} is specified
2411
with no @i{value}, then the command returns a list describing the
2412
one named option (this list will be identical to the corresponding
2413
sublist of the value returned if no @i{option} is specified). If
2414
one or more @i{option:value} pairs are specified, then the command
2415
modifies the given widget option(s) to have the given value(s); in
2416
this case the command returns an empty string.
2417
@i{Option}@r{ may have any of the values accepted by the }@b{menu}
2419
@item @i{pathName }@b{:delete }@i{index1}@r{ ?}@i{index2}?
2420
Delete all of the menu entries between @i{index1} and
2421
@i{index2} inclusive.
2422
If @i{index2}@r{ is omitted then it defaults to }@i{index1}.
2423
Returns an empty string.
2424
@item @i{pathName }@b{:disable }@i{index}
2425
Change the state of the entry given by @i{index}@r{ to }@b{disabled}
2426
and redisplay the entry using its disabled colors.
2427
Returns an empty string.
2428
This command is obsolete and will eventually be removed;
2429
use ``@i{pathName }@b{:entryconfigure }@i{index}@r{ :state disabled}'' instead.
2430
@item @i{pathName }@b{:enable }@i{index}
2431
Change the state of the entry given by @i{index}@r{ to }@b{normal}
2432
and redisplay the entry using its normal colors.
2433
Returns an empty string.
2434
This command is obsolete and will eventually be removed;
2435
use ``@i{pathName }@b{:entryconfigure }@i{index}@r{ :state normal}'' instead.
2436
@item @i{pathName }@b{:entryconfigure }@i{index}@r{ }@r{?}@i{options}?
2437
This command is similar to the @b{configure} command, except that
2438
it applies to the options for an individual entry, whereas @b{configure}
2439
applies to the options for the menu as a whole.
2440
@i{Options}@r{ may have any of the values accepted by the }@b{add}
2441
widget command. If @i{options} are specified, options are modified
2443
in the command and the command returns an empty string.
2444
If no @i{options} are specified, returns a list describing
2445
the current options for entry @i{index}@r{ (see }@b{Tk_ConfigureInfo} for
2446
information on the format of this list).
2447
@item @i{pathName }@b{:index }@i{index}
2448
Returns the numerical index corresponding to @i{index}, or
2449
@b{none}@r{ if }@i{index}@r{ was specified as }@b{none}.
2450
@item @i{pathName }@b{:invoke }@i{index}
2451
Invoke the action of the menu entry. See the sections on the
2452
individual entries above for details on what happens. If the
2453
menu entry is disabled then nothing happens. If the
2454
entry has a command associated with it then the result of that
2455
command is returned as the result of the @b{invoke} widget
2456
command. Otherwise the result is an empty string. Note: invoking
2457
a menu entry does not automatically unpost the menu. Normally
2458
the associated menubutton will take care of unposting the menu.
2459
@item @i{pathName }@b{:post }@i{x y}
2460
Arrange for the menu to be displayed on the screen at the root-window
2461
coordinates given by @i{x}@r{ and }@i{y}. These coordinates are
2462
adjusted if necessary to guarantee that the entire menu is visible on
2463
the screen. This command normally returns an empty string.
2464
If the @b{:postcommand} option has been specified, then its value is
2465
executed as a Tcl script before posting the menu and the result of
2466
that script is returned as the result of the @b{post} widget
2468
If an error returns while executing the command, then the error is
2469
returned without posting the menu.
2470
@item @i{pathName }@b{:unpost}
2471
Unmap the window so that it is no longer displayed. If a
2472
lower-level cascaded menu is posted, unpost that menu. Returns an
2474
@item @i{pathName }@b{:yposition }@i{index}
2475
Returns a decimal string giving the y-coordinate within the menu
2476
window of the topmost pixel in the entry specified by @i{index}.
2480
@unnumberedsubsec Default Bindings
2483
Tk automatically creates class bindings for menus that give them
2484
the following default behavior:
2488
When the mouse cursor enters a menu, the entry underneath the mouse
2489
cursor is activated; as the mouse moves around the menu, the active
2490
entry changes to track the mouse.
2493
When button 1 is released over a menu, the active entry (if any) is invoked.
2496
A menu can be repositioned on the screen by dragging it with mouse
2500
A number of other bindings are created to support keyboard menu traversal.
2501
See the manual entry for @b{tk_bindForTraversal} for details on these
2505
Disabled menu entries are non-responsive: they don't activate and
2506
ignore mouse button presses and releases.
2508
The behavior of menus can be changed by defining new bindings for
2509
individual widgets or by redefining the class bindings.
2511
@unnumberedsubsec Bugs
2513
At present it isn't possible to use the
2514
option database to specify values for the options to individual
2517
@unnumberedsubsec Keywords
2519
@node scrollbar, checkbutton, menu, Widgets
2523
scrollbar \- Create and manipulate scrollbar widgets
2524
@unnumberedsubsec Synopsis
2525
@b{scrollbar}@i{ pathName }@r{?}@i{options}?
2526
@unnumberedsubsec Standard Options
2530
activeForeground cursor relief
2531
background foreground repeatDelay
2532
borderWidth orient repeatInterval
2536
@xref{options}, for more information.
2537
@unnumberedsubsec Arguments for Scrollbar
2541
@item @code{@b{:command}}
2543
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
2547
Specifies the prefix of a Tcl command to invoke to change the view
2548
in the widget associated with the scrollbar. When a user requests
2549
a view change by manipulating the scrollbar, a Tcl command is
2550
invoked. The actual command consists of this option followed by
2551
a space and a number. The number indicates the logical unit that
2552
should appear at the top of the associated window.
2557
@item @code{@b{:width}}
2559
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
2563
Specifies the desired narrow dimension of the scrollbar window,
2564
not including 3-D border, if any. For vertical
2565
scrollbars this will be the width and for horizontal scrollbars
2566
this will be the height.
2567
The value may have any of the forms acceptable to @b{Tk_GetPixels}.
2571
@unnumberedsubsec Description
2573
The @b{scrollbar} command creates a new window (given by the
2574
@i{pathName} argument) and makes it into a scrollbar widget.
2576
options, described above, may be specified on the command line
2577
or in the option database
2578
to configure aspects of the scrollbar such as its colors, orientation,
2579
and relief. The @b{scrollbar} command returns its
2580
@i{pathName} argument. At the time this command is invoked,
2581
there must not exist a window named @i{pathName}, but
2582
@i{pathName}'s parent must exist.
2584
A scrollbar is a widget that displays two arrows, one at each end of
2585
the scrollbar, and a @i{slider} in the middle portion of the
2586
scrollbar. A scrollbar is used to provide information about what
2587
is visible in an @i{associated window} that displays an object
2588
of some sort (such as a file being edited or a drawing).
2589
The position and size of the slider indicate which portion of the
2590
object is visible in the associated window. For example, if the
2591
slider in a vertical scrollbar covers the top third of the area
2592
between the two arrows, it means that the associated window displays
2593
the top third of its object.
2595
Scrollbars can be used to adjust the view in the associated window
2596
by clicking or dragging with the mouse. See the BINDINGS section
2599
@unnumberedsubsec A Scrollbar Widget's Arguments
2601
The @b{scrollbar} command creates a new Tcl command whose
2602
name is @i{pathName}. This
2603
command may be used to invoke various
2604
operations on the widget. It has the following general form:
2607
@i{pathName option }@r{?}@i{arg arg ...}?
2610
@i{Option}@r{ and the }@i{arg}s
2611
determine the exact behavior of the command. The following
2612
commands are possible for scrollbar widgets:
2615
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
2616
Query or modify the configuration options of the widget.
2617
If no @i{option} is specified, returns a list describing all of
2618
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
2619
information on the format of this list). If @i{option} is specified
2620
with no @i{value}, then the command returns a list describing the
2621
one named option (this list will be identical to the corresponding
2622
sublist of the value returned if no @i{option} is specified). If
2623
one or more @i{option:value} pairs are specified, then the command
2624
modifies the given widget option(s) to have the given value(s); in
2625
this case the command returns an empty string.
2626
@i{Option}@r{ may have any of the values accepted by the }@b{scrollbar}
2628
@item @i{pathName }@b{:get}
2629
Returns a Tcl list containing four decimal values, which are
2630
the current @i{totalUnits}@r{, }@i{widnowUnits}@r{, }@i{firstUnit},
2631
and @i{lastUnit} values for the scrollbar. These are the values
2632
from the most recent @b{set} widget command on the scrollbar.
2633
@item @i{pathName }@b{:set}@r{ }@i{totalUnits windowUnits firstUnit lastUnit}
2634
This command is invoked to give the scrollbar information about the
2635
widget associated with the scrollbar. @i{TotalUnits} is an integer
2636
value giving the total size of the object being displayed in the
2637
associated widget. The meaning of one unit depends on the associated
2638
widget; for example, in a text editor widget units might
2639
correspond to lines of
2640
text. @i{WindowUnits} indicates the total number of units that
2641
can fit in the associated window at one time. @i{FirstUnit}
2642
and @i{lastUnit} give the indices of the first and last units
2643
currently visible in the associated window (zero corresponds to the
2644
first unit of the object). This command should
2645
be invoked by the associated widget whenever its object or window
2646
changes size and whenever it changes the view in its window.
2649
@unnumberedsubsec Bindings
2651
The description below assumes a vertically-oriented scrollbar.
2652
For a horizontally-oriented scrollbar replace the words ``up'', ``down'',
2653
``top'', and ``bottom'' with ``left'', ``right'', ``left'',
2654
and ``right'', respectively
2656
A scrollbar widget is divided into five distinct areas. From top
2657
to bottom, they are: the top arrow, the top gap (the empty space
2658
between the arrow and the slider), the slider, the bottom gap,
2659
and the bottom arrow. Pressing mouse button 1 in each area has
2664
Causes the view in the associated window to shift up by one unit
2665
(i.e. the object appears to move down one unit in its window).
2666
If the button is held down the action will auto-repeat.
2668
Causes the view in the associated window to shift up by one
2669
less than the number of units in the window
2670
(i.e. the portion of the object that used to appear at the very
2671
top of the window will now appear at the very bottom).
2672
If the button is held down the action will auto-repeat.
2674
Pressing button 1 in this area has no immediate effect except to
2675
cause the slider to appear sunken rather than raised. However,
2676
if the mouse is moved with the button down then the slider will
2677
be dragged, adjusting the view as the mouse is moved.
2678
@item @b{bottom gap}
2679
Causes the view in the associated window to shift down by one
2680
less than the number of units in the window
2681
(i.e. the portion of the object that used to appear at the very
2682
bottom of the window will now appear at the very top).
2683
If the button is held down the action will auto-repeat.
2684
@item @b{bottom arrow}
2685
Causes the view in the associated window to shift down by one unit
2686
(i.e. the object appears to move up one unit in its window).
2687
If the button is held down the action will auto-repeat.
2689
Note: none of the actions described above has an immediate impact
2690
on the position of the slider in the scrollbar. It simply invokes
2691
the command specified in the @b{command} option to notify the
2692
associated widget that a change in view is desired. If the view is
2693
actually changed then the associated widget must invoke the
2694
scrollbar's @b{set} widget command to change what is displayed in
2698
@unnumberedsubsec Keywords
2700
@node checkbutton, menubutton, scrollbar, Widgets
2701
@section checkbutton
2704
checkbutton \- Create and manipulate check-button widgets
2705
@unnumberedsubsec Synopsis
2706
@b{checkbutton}@i{ pathName }@r{?}@i{options}?
2707
@unnumberedsubsec Standard Options
2711
activeBackground bitmap font relief
2712
activeForeground borderWidth foreground text
2713
anchor cursor padX textVariable
2714
background disabledForeground padY
2718
@xref{options}, for more information.
2719
@unnumberedsubsec Arguments for Checkbutton
2723
@item @code{@b{:command}}
2725
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
2729
Specifies a Tcl command to associate with the button. This command
2730
is typically invoked when mouse button 1 is released over the button
2731
window. The button's global variable (@b{:variable} option) will
2732
be updated before the command is invoked.
2737
@item @code{@b{:height}}
2739
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
2743
Specifies a desired height for the button.
2744
If a bitmap is being displayed in the button then the value is in
2745
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
2746
for text it is in lines of text.
2747
If this option isn't specified, the button's desired height is computed
2748
from the size of the bitmap or text being displayed in it.
2753
@item @code{@b{:offvalue}}
2755
Name=@code{"@b{offValue}@r{"} Class=@code{"}@b{Value}"}
2759
Specifies value to store in the button's associated variable whenever
2760
this button is deselected. Defaults to ``0''.
2765
@item @code{@b{:onvalue}}
2767
Name=@code{"@b{onValue}@r{"} Class=@code{"}@b{Value}"}
2771
Specifies value to store in the button's associated variable whenever
2772
this button is selected. Defaults to ``1''.
2777
@item @code{@b{:selector}}
2779
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
2783
Specifies the color to draw in the selector when this button is
2785
If specified as an empty string then no selector is
2786
drawn for the button.
2791
@item @code{@b{:state}}
2793
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
2797
Specifies one of three states for the check button: @b{normal}@r{, }@b{active},
2798
or @b{disabled}. In normal state the check button is displayed using the
2799
@b{foreground}@r{ and }@b{background} options. The active state is
2800
typically used when the pointer is over the check button. In active state
2801
the check button is displayed using the @b{activeForeground} and
2802
@b{activeBackground} options. Disabled state means that the check button
2803
is insensitive: it doesn't activate and doesn't respond to mouse
2804
button presses. In this state the @b{disabledForeground} and
2805
@b{background} options determine how the check button is displayed.
2810
@item @code{@b{:variable}}
2812
Name=@code{"@b{variable}@r{"} Class=@code{"}@b{Variable}"}
2816
Specifies name of global variable to set to indicate whether
2817
or not this button is selected. Defaults to the name of the
2818
button within its parent (i.e. the last element of the button
2819
window's path name).
2824
@item @code{@b{:width}}
2826
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
2830
Specifies a desired width for the button.
2831
If a bitmap is being displayed in the button then the value is in
2832
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
2833
for text it is in characters.
2834
If this option isn't specified, the button's desired width is computed
2835
from the size of the bitmap or text being displayed in it.
2839
@unnumberedsubsec Description
2841
The @b{checkbutton} command creates a new window (given by the
2842
@i{pathName} argument) and makes it into a check-button widget.
2844
options, described above, may be specified on the command line
2845
or in the option database
2846
to configure aspects of the check button such as its colors, font,
2847
text, and initial relief. The @b{checkbutton} command returns its
2848
@i{pathName} argument. At the time this command is invoked,
2849
there must not exist a window named @i{pathName}, but
2850
@i{pathName}'s parent must exist.
2852
A check button is a widget
2853
that displays a textual string or bitmap
2854
and a square called a @i{selector}.
2856
all of the behavior of a simple button, including the
2857
following: it can display itself in either of three different
2858
ways, according to the @b{state} option;
2859
it can be made to appear
2860
raised, sunken, or flat; it can be made to flash; and it invokes
2861
a Tcl command whenever mouse button 1 is clicked over the
2864
In addition, check buttons can be @i{selected}. If a check button is
2865
selected then a special highlight appears in the selector, and
2866
a Tcl variable associated with the check button is set to a particular
2867
value (normally 1). If the check button is not selected, then
2868
the selector is drawn in a different fashion and the associated
2869
variable is set to a different value (typically 0). By default,
2870
the name of the variable associated with a check button is the
2871
same as the @i{name} used to create the check button. The
2872
variable name, and the ``on'' and ``off'' values stored in it,
2873
may be modified with options on the command line or in the option
2874
database. By default a check button is configured to select and deselect
2875
itself on alternate button clicks.
2876
In addition, each check button monitors its associated variable and
2877
automatically selects and deselects itself when the variables value
2878
changes to and from the button's ``on'' value.
2880
@unnumberedsubsec A Checkbutton Widget's Arguments
2882
The @b{checkbutton} command creates a new Tcl command whose
2883
name is @i{pathName}. This
2884
command may be used to invoke various
2885
operations on the widget. It has the following general form:
2888
@i{pathName option }@r{?}@i{arg arg ...}?
2891
@i{Option}@r{ and the }@i{arg}s
2892
determine the exact behavior of the command. The following
2893
commands are possible for check button widgets:
2896
@item @i{pathName }@b{:activate}
2897
Change the check button's state to @b{active} and redisplay the button
2898
using its active foreground and background colors instead of normal
2900
This command is ignored if the check button's state is @b{disabled}.
2901
This command is obsolete and will eventually be removed;
2902
use ``@i{pathName }@b{:configure :state active}'' instead.
2903
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
2904
Query or modify the configuration options of the widget.
2905
If no @i{option} is specified, returns a list describing all of
2906
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
2907
information on the format of this list). If @i{option} is specified
2908
with no @i{value}, then the command returns a list describing the
2909
one named option (this list will be identical to the corresponding
2910
sublist of the value returned if no @i{option} is specified). If
2911
one or more @i{option:value} pairs are specified, then the command
2912
modifies the given widget option(s) to have the given value(s); in
2913
this case the command returns an empty string.
2914
@i{Option}@r{ may have any of the values accepted by the }@b{checkbutton}
2916
@item @i{pathName }@b{:deactivate}
2917
Change the check button's state to @b{normal} and redisplay the button
2918
using its normal foreground and background colors.
2919
This command is ignored if the check button's state is @b{disabled}.
2920
This command is obsolete and will eventually be removed;
2921
use ``@i{pathName }@b{:configure :state normal}'' instead.
2922
@item @i{pathName }@b{:deselect}
2923
Deselect the check button: redisplay it without a highlight in
2924
the selector and set the associated variable to its ``off''
2926
@item @i{pathName }@b{:flash}
2927
Flash the check button. This is accomplished by redisplaying the check button
2928
several times, alternating between active and normal colors. At
2929
the end of the flash the check button is left in the same normal/active
2930
state as when the command was invoked.
2931
This command is ignored if the check button's state is @b{disabled}.
2932
@item @i{pathName }@b{:invoke}
2933
Does just what would have happened if the user invoked the check button
2934
with the mouse: toggle the selection state of the button and invoke
2935
the Tcl command associated with the check button, if there is one.
2936
The return value is the return value from the Tcl command, or an
2937
empty string if there is no command associated with the check button.
2938
This command is ignored if the check button's state is @b{disabled}.
2939
@item @i{pathName }@b{:select}
2940
Select the check button: display it with a highlighted
2941
selector and set the associated variable to its ``on''
2943
@item @i{pathName }@b{:toggle}
2944
Toggle the selection state of the button, redisplaying it and
2945
modifying its associated variable to reflect the new state.
2948
@unnumberedsubsec Bindings
2950
Tk automatically creates class bindings for check buttons that give them
2951
the following default behavior:
2955
The check button activates whenever the mouse passes over it and deactivates
2956
whenever the mouse leaves the check button.
2959
The check button's relief is changed to sunken whenever mouse button 1 is
2960
pressed over it, and the relief is restored to its original
2961
value when button 1 is later released.
2964
If mouse button 1 is pressed over the check button and later released over
2965
the check button, the check button is invoked (i.e. its selection
2966
state toggles and the command associated with the button is invoked,
2967
if there is one). However, if the mouse is not
2968
over the check button when button 1 is released, then no invocation occurs.
2971
If the check button's state is @b{disabled} then none of the above
2972
actions occur: the check button is completely non-responsive.
2974
The behavior of check buttons can be changed by defining new bindings for
2975
individual widgets or by redefining the class bindings.
2977
@unnumberedsubsec Keywords
2978
check button, widget
2979
@node menubutton, text, checkbutton, Widgets
2983
menubutton \- Create and manipulate menubutton widgets
2984
@unnumberedsubsec Synopsis
2985
@b{menubutton}@i{ }@i{pathName }@r{?}@i{options}?
2986
@unnumberedsubsec Standard Options
2990
activeBackground bitmap font relief
2991
activeForeground borderWidth foreground text
2992
anchor cursor padX textVariable
2993
background disabledForeground padY underline
2997
@xref{options}, for more information.
2998
@unnumberedsubsec Arguments for Menubutton
3002
@item @code{@b{:height}}
3004
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
3008
Specifies a desired height for the menu button.
3009
If a bitmap is being displayed in the menu button then the value is in
3010
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
3011
for text it is in lines of text.
3012
If this option isn't specified, the menu button's desired height is computed
3013
from the size of the bitmap or text being displayed in it.
3018
@item @code{@b{:menu}}
3020
Name=@code{"@b{menu}@r{"} Class=@code{"}@b{MenuName}"}
3024
Specifies the path name of the menu associated with this menubutton.
3025
The menu must be a descendant of the menubutton in order for normal pull-down
3026
operation to work via the mouse.
3031
@item @code{@b{:state}}
3033
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
3037
Specifies one of three states for the menu button: @b{normal}@r{, }@b{active},
3038
or @b{disabled}. In normal state the menu button is displayed using the
3039
@b{foreground}@r{ and }@b{background} options. The active state is
3040
typically used when the pointer is over the menu button. In active state
3041
the menu button is displayed using the @b{activeForeground} and
3042
@b{activeBackground} options. Disabled state means that the menu button
3043
is insensitive: it doesn't activate and doesn't respond to mouse
3044
button presses. In this state the @b{disabledForeground} and
3045
@b{background} options determine how the button is displayed.
3050
@item @code{@b{:width}}
3052
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
3056
Specifies a desired width for the menu button.
3057
If a bitmap is being displayed in the menu button then the value is in
3058
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
3059
for text it is in characters.
3060
If this option isn't specified, the menu button's desired width is computed
3061
from the size of the bitmap or text being displayed in it.
3065
@unnumberedsubsec Introduction
3067
The @b{menubutton} command creates a new window (given by the
3068
@i{pathName} argument) and makes it into a menubutton widget.
3070
options, described above, may be specified on the command line
3071
or in the option database
3072
to configure aspects of the menubutton such as its colors, font,
3073
text, and initial relief. The @b{menubutton} command returns its
3074
@i{pathName} argument. At the time this command is invoked,
3075
there must not exist a window named @i{pathName}, but
3076
@i{pathName}'s parent must exist.
3078
A menubutton is a widget that displays a
3079
textual string or bitmap
3080
and is associated with a menu widget. In normal usage, pressing
3081
mouse button 1 over the menubutton causes the associated menu to
3082
be posted just underneath the menubutton. If the mouse is moved over
3083
the menu before releasing the mouse button, the button release
3084
causes the underlying menu entry to be invoked. When the button
3085
is released, the menu is unposted.
3087
Menubuttons are typically organized into groups called menu bars
3088
that allow scanning:
3089
if the mouse button is pressed over one menubutton (causing it
3090
to post its menu) and the mouse is moved over another menubutton
3091
in the same menu bar without releasing the mouse button, then the
3092
menu of the first menubutton is unposted and the menu of the
3093
new menubutton is posted instead.
3094
The @b{tk-menu-bar} procedure is used to set up menu bars for
3095
scanning; see that procedure for more details.
3097
@unnumberedsubsec A Menubutton Widget's Arguments
3099
The @b{menubutton} command creates a new Tcl command whose
3100
name is @i{pathName}. This
3101
command may be used to invoke various
3102
operations on the widget. It has the following general form:
3105
@i{pathName option }@r{?}@i{arg arg ...}?
3108
@i{Option}@r{ and the }@i{arg}s
3109
determine the exact behavior of the command. The following
3110
commands are possible for menubutton widgets:
3113
@item @i{pathName }@b{:activate}
3114
Change the menu button's state to @b{active} and redisplay the menu
3115
button using its active foreground and background colors instead of normal
3117
The command returns an empty string.
3118
This command is ignored if the menu button's state is @b{disabled}.
3119
This command is obsolete and will eventually be removed;
3120
use ``@i{pathName }@b{:configure :state active}'' instead.
3121
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
3122
Query or modify the configuration options of the widget.
3123
If no @i{option} is specified, returns a list describing all of
3124
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
3125
information on the format of this list). If @i{option} is specified
3126
with no @i{value}, then the command returns a list describing the
3127
one named option (this list will be identical to the corresponding
3128
sublist of the value returned if no @i{option} is specified). If
3129
one or more @i{option:value} pairs are specified, then the command
3130
modifies the given widget option(s) to have the given value(s); in
3131
this case the command returns an empty string.
3132
@i{Option}@r{ may have any of the values accepted by the }@b{menubutton}
3134
@item @i{pathName }@b{:deactivate}
3135
Change the menu button's state to @b{normal} and redisplay the menu
3136
button using its normal foreground and background colors.
3137
The command returns an empty string.
3138
This command is ignored if the menu button's state is @b{disabled}.
3139
This command is obsolete and will eventually be removed;
3140
use ``@i{pathName }@b{:configure :state normal}'' instead.
3143
@unnumberedsubsec "Default Bindings"
3146
Tk automatically creates class bindings for menu buttons that give them
3147
the following default behavior:
3151
A menu button activates whenever the mouse passes over it and deactivates
3152
whenever the mouse leaves it.
3155
A menu button's relief is changed to raised whenever mouse button 1 is
3156
pressed over it, and the relief is restored to its original value
3157
when button 1 is later released or the mouse is dragged into another
3158
menu button in the same menu bar.
3161
When mouse button 1 is pressed over a menu button, or when the mouse
3162
is dragged into a menu button with mouse button 1 pressed, the associated
3163
menu is posted; the mouse can be dragged across the menu and released
3164
over an entry in the menu to invoke that entry. The menu is unposted
3165
when button 1 is released outside either the menu or the menu button.
3166
The menu is also unposted when the mouse is dragged into another
3167
menu button in the same menu bar.
3170
If mouse button 1 is pressed and released within the menu button,
3171
then the menu stays posted and keyboard traversal is possible as
3172
described in the manual entry for @b{tk-menu-bar}.
3175
Menubuttons may also be posted by typing characters on the keyboard.
3176
See the manual entry for @b{tk-menu-bar} for full details on keyboard
3180
If mouse button 2 is pressed over a menu button then the associated
3181
menu is posted and also @i{torn off}: it can then be dragged around on
3182
the screen with button 2 and the menu will not automatically unpost when
3183
entries in it are invoked.
3184
To close a torn off menu, click mouse button 1 over the associated
3188
If the menu button's state is @b{disabled} then none of the above
3189
actions occur: the menu button is completely non-responsive.
3191
The behavior of menu buttons can be changed by defining new bindings for
3192
individual widgets or by redefining the class bindings.
3194
@unnumberedsubsec Keywords
3196
@node text, entry, menubutton, Widgets
3200
text \- Create and manipulate text widgets
3201
@unnumberedsubsec Synopsis
3202
@b{text}@i{ }@i{pathName }@r{?}@i{options}?
3203
@unnumberedsubsec Standard Options
3207
background foreground insertWidth selectBorderWidth
3208
borderWidth insertBackground padX selectForeground
3209
cursor insertBorderWidth padY setGrid
3210
exportSelection insertOffTime relief yScrollCommand
3211
font insertOnTime selectBackground
3215
@xref{options}, for more information.
3216
@unnumberedsubsec Arguments for Text
3220
@item @code{@b{:height}}
3222
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
3226
Specifies the desired height for the window, in units of characters.
3227
Must be at least one.
3232
@item @code{@b{:state}}
3234
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
3238
Specifies one of two states for the text: @b{normal}@r{ or }@b{disabled}.
3239
If the text is disabled then characters may not be inserted or deleted
3240
and no insertion cursor will be displayed, even if the input focus is
3246
@item @code{@b{:width}}
3248
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
3252
Specifies the desired width for the window in units of characters.
3253
If the font doesn't have a uniform width then the width of the
3254
character ``0'' is used in translating from character units to
3260
@item @code{@b{:wrap}}
3262
Name=@code{"@b{wrap}@r{"} Class=@code{"}@b{Wrap}"}
3266
Specifies how to handle lines in the text that are too long to be
3267
displayed in a single line of the text's window.
3268
The value must be @b{none}@r{ or }@b{char}@r{ or }@b{word}.
3269
A wrap mode of @b{none} means that each line of text appears as
3270
exactly one line on the screen; extra characters that don't fit
3271
on the screen are not displayed.
3272
In the other modes each line of text will be broken up into several
3273
screen lines if necessary to keep all the characters visible.
3274
In @b{char} mode a screen line break may occur after any character;
3275
in @b{word} mode a line break will only be made at word boundaries.
3279
@unnumberedsubsec Description
3281
The @b{text} command creates a new window (given by the
3282
@i{pathName} argument) and makes it into a text widget.
3284
options, described above, may be specified on the command line
3285
or in the option database
3286
to configure aspects of the text such as its default background color
3287
and relief. The @b{text} command returns the
3288
path name of the new window.
3290
A text widget displays one or more lines of text and allows that
3292
Text widgets support three different kinds of annotations on the
3293
text, called tags, marks, and windows.
3294
Tags allow different portions of the text
3295
to be displayed with different fonts and colors.
3296
In addition, Tcl commands can be associated with tags so
3297
that commands are invoked when particular actions such as keystrokes
3298
and mouse button presses occur in particular ranges of the text.
3299
See TAGS below for more details.
3301
The second form of annotation consists of marks, which are floating
3302
markers in the text.
3303
Marks are used to keep track of various interesting positions in the
3304
text as it is edited.
3305
See MARKS below for more details.
3307
The third form of annotation allows arbitrary windows to be displayed
3309
See WINDOWS below for more details.
3311
@unnumberedsubsec Indices
3313
Many of the widget commands for texts take one or more indices
3315
An index is a string used to indicate a particular place within
3316
a text, such as a place to insert characters or one endpoint of a
3317
range of characters to delete.
3318
Indices have the syntax
3320
@i{base modifier modifier modifier ...}
3323
Where @i{base}@r{ gives a starting point and the }@i{modifier}s
3324
adjust the index from the starting point (e.g. move forward or
3325
backward one character). Every index must contain a @i{base},
3326
but the @i{modifier}s are optional.
3329
The @i{base} for an index must have one of the following forms:
3332
@item @i{line}@b{.}@i{char}
3333
Indicates @i{char}@r{'th character on line }@i{line}.
3334
Lines are numbered from 1 for consistency with other UNIX programs
3335
that use this numbering scheme.
3336
Within a line, characters are numbered from 0.
3337
@item @b{@@}@i{x}@b{,}@i{y}
3338
Indicates the character that covers the pixel whose x and y coordinates
3339
within the text's window are @i{x}@r{ and }@i{y}.
3341
Indicates the last character in the text, which is always a newline
3344
Indicates the character just after the mark whose name is @i{mark}.
3345
@item @i{tag}@b{.first}
3346
Indicates the first character in the text that has been tagged with
3348
This form generates an error if no characters are currently tagged
3350
@item @i{tag}@b{.last}
3351
Indicates the character just after the last one in the text that has
3352
been tagged with @i{tag}.
3353
This form generates an error if no characters are currently tagged
3358
If modifiers follow the base index, each one of them must have one
3359
of the forms listed below. Keywords such as @b{chars}@r{ and }@b{wordend}
3360
may be abbreviated as long as the abbreviation is unambiguous.
3363
@item @b{+ }@i{count}@b{ chars}
3364
Adjust the index forward by @i{count} characters, moving to later
3365
lines in the text if necessary. If there are fewer than @i{count}
3366
characters in the text after the current index, then set the index
3367
to the last character in the text.
3368
Spaces on either side of @i{count} are optional.
3369
@item @b{-} @i{count}@b{ chars}
3370
Adjust the index backward by @i{count} characters, moving to earlier
3371
lines in the text if necessary. If there are fewer than @i{count}
3372
characters in the text before the current index, then set the index
3373
to the first character in the text.
3374
Spaces on either side of @i{count} are optional.
3375
@item @b{+ }@i{count}@b{ lines}
3376
Adjust the index forward by @i{count} lines, retaining the same
3377
character position within the line. If there are fewer than @i{count}
3378
lines after the line containing the current index, then set the index
3379
to refer to the same character position on the last line of the text.
3380
Then, if the line is not long enough to contain a character at the indicated
3381
character position, adjust the character position to refer to the last
3382
character of the line (the newline).
3383
Spaces on either side of @i{count} are optional.
3384
@item @b{-} @i{count}@b{ lines}
3385
Adjust the index backward by @i{count} lines, retaining the same
3386
character position within the line. If there are fewer than @i{count}
3387
lines before the line containing the current index, then set the index
3388
to refer to the same character position on the first line of the text.
3389
Then, if the line is not long enough to contain a character at the indicated
3390
character position, adjust the character position to refer to the last
3391
character of the line (the newline).
3392
Spaces on either side of @i{count} are optional.
3394
Adjust the index to refer to the first character on the line.
3396
Adjust the index to refer to the last character on the line (the newline).
3398
Adjust the index to refer to the first character of the word containing
3399
the current index. A word consists of any number of adjacent characters
3400
that are letters, digits, or underscores, or a single character that
3401
is not one of these.
3403
Adjust the index to refer to the character just after the last one of the
3404
word containing the current index. If the current index refers to the last
3405
character of the text then it is not modified.
3409
If more than one modifier is present then they are applied in
3410
left-to-right order. For example, the index ``\fBend \- 1 chars''
3411
refers to the next-to-last character in the text and
3412
``\fBinsert wordstart \- 1 c'' refers to the character just before
3413
the first one in the word containing the insertion cursor.
3415
@unnumberedsubsec Tags
3417
The first form of annotation in text widgets is a tag.
3418
A tag is a textual string that is associated with some of the characters
3420
There may be any number of tags associated with characters in a
3422
Each tag may refer to a single character, a range of characters, or
3423
several ranges of characters.
3424
An individual character may have any number of tags associated with it.
3426
A priority order is defined among tags, and this order is used in
3427
implementing some of the tag-related functions described below.
3428
When a tag is defined (by associating it with characters or setting
3429
its display options or binding commands to it), it is given
3430
a priority higher than any existing tag.
3431
The priority order of tags may be redefined using the
3432
``@i{pathName }@b{:tag :raise}@r{'' and ``}@i{pathName }@b{:tag :lower}''
3435
Tags serve three purposes in text widgets.
3436
First, they control the way information is displayed on the screen.
3437
By default, characters are displayed as determined by the
3438
@b{background}@r{, }@b{font}@r{, and }@b{foreground} options for the
3440
However, display options may be associated with individual tags
3441
using the ``@i{pathName }@b{:tag configure}'' widget command.
3442
If a character has been tagged, then the display options associated
3443
with the tag override the default display style.
3444
The following options are currently supported for tags:
3447
@item @b{:background }@i{color}
3448
@i{Color} specifies the background color to use for characters
3449
associated with the tag.
3450
It may have any of the forms accepted by @b{Tk_GetColor}.
3451
@item @b{:bgstipple }@i{bitmap}
3452
@i{Bitmap} specifies a bitmap that is used as a stipple pattern
3454
It may have any of the forms accepted by @b{Tk_GetBitmap}.
3455
If @i{bitmap} hasn't been specified, or if it is specified
3456
as an empty string, then a solid fill will be used for the
3458
@item @b{:borderwidth }@i{pixels}
3459
@i{Pixels} specifies the width of a 3-D border to draw around
3461
It may have any of the forms accepted by @b{Tk_GetPixels}.
3462
This option is used in conjunction with the @b{:relief}
3463
option to give a 3-D appearance to the background for characters;
3464
it is ignored unless the @b{:background} option
3465
has been set for the tag.
3466
@item @b{:fgstipple }@i{bitmap}
3467
@i{Bitmap} specifies a bitmap that is used as a stipple pattern
3468
when drawing text and other foreground information such as
3470
It may have any of the forms accepted by @b{Tk_GetBitmap}.
3471
If @i{bitmap} hasn't been specified, or if it is specified
3472
as an empty string, then a solid fill will be used.
3473
@item @b{:font }@i{fontName}
3474
@i{FontName} is the name of a font to use for drawing characters.
3475
It may have any of the forms accepted by @b{Tk_GetFontStruct}.
3476
@item @b{:foreground }@i{color}
3477
@i{Color} specifies the color to use when drawing text and other
3478
foreground information such as underlines.
3479
It may have any of the forms accepted by @b{Tk_GetColor}.
3480
@item @b{:relief }@i{relief}
3481
\fIRelief specifies the 3-D relief to use for drawing backgrounds,
3482
in any of the forms accepted by @b{Tk_GetRelief}.
3483
This option is used in conjunction with the @b{:borderwidth}
3484
option to give a 3-D appearance to the background for characters;
3485
it is ignored unless the @b{:background} option
3486
has been set for the tag.
3487
@item @b{:underline }@i{boolean}
3488
@i{Boolean} specifies whether or not to draw an underline underneath
3490
It may have any of the forms accepted by @b{Tk_GetBoolean}.
3492
If a character has several tags associated with it, and if their
3493
display options conflict, then the options of the highest priority
3495
If a particular display option hasn't been specified for a
3496
particular tag, or if it is specified as an empty string, then
3497
that option will never be used; the next-highest-priority
3498
tag's option will used instead.
3499
If no tag specifies a particular display optionl, then the default
3500
style for the widget will be used.
3502
The second purpose for tags is event bindings.
3503
You can associate bindings with a tag in much the same way you can
3504
associate bindings with a widget class: whenever particular X
3505
events occur on characters with the given tag, a given
3506
Tcl command will be executed.
3507
Tag bindings can be used to give behaviors to ranges of characters;
3508
among other things, this allows hypertext-like
3509
features to be implemented.
3510
For details, see the description of the @b{tag bind} widget
3513
The third use for tags is in managing the selection.
3514
See THE SELECTION below.
3517
@unnumberedsubsec Marks
3519
The second form of annotation in text widgets is a mark.
3520
Marks are used for remembering particular places in a text.
3521
They are something like tags, in that they have names and
3522
they refer to places in the file, but a mark isn't associated
3523
with particular characters.
3524
Instead, a mark is associated with the gap between two characters.
3525
Only a single position may be associated with a mark at any given
3527
If the characters around a mark are deleted the mark will still
3528
remain; it will just have new neighbor characters.
3529
In contrast, if the characters containing a tag are deleted then
3530
the tag will no longer have an association with characters in
3532
Marks may be manipulated with the ``@i{pathName }@b{:mark}'' widget
3533
command, and their current locations may be determined by using the
3534
mark name as an index in widget commands.
3536
The name space for marks is different from that for tags: the
3537
same name may be used for both a mark and a tag, but they will refer
3538
to different things.
3540
Two marks have special significance.
3541
First, the mark @b{insert} is associated with the insertion cursor,
3542
as described under THE INSERTION CURSOR below.
3543
Second, the mark @b{current} is associated with the character
3544
closest to the mouse and is adjusted automatically to track the
3545
mouse position and any changes to the text in the widget (one
3546
exception: @b{current} is not updated in response to mouse
3547
motions if a mouse button is down; the update will be deferred
3548
until all mouse buttons have been released).
3549
Neither of these special marks may be unset.
3551
@unnumberedsubsec Windows
3553
The third form of annotation in text widgets is a window.
3554
Window support isn't implemented yet, but when it is it will be
3557
@unnumberedsubsec The Selection
3559
Text widgets support the standard X selection.
3560
Selection support is implemented via tags.
3561
If the @b{exportSelection} option for the text widget is true
3562
then the @b{sel} tag will be associated with the selection:
3566
Whenever characters are tagged with @b{sel} the text widget
3567
will claim ownership of the selection.
3570
Attempts to retrieve the
3571
selection will be serviced by the text widget, returning all the
3572
charaters with the @b{sel} tag.
3575
If the selection is claimed away by another application or by another
3576
window within this application, then the @b{sel} tag will be removed
3577
from all characters in the text.
3580
The @b{sel} tag is automatically defined when a text widget is
3581
created, and it may not be deleted with the ``@i{pathName }@b{:tag delete}''
3582
widget command. Furthermore, the @b{selectBackground},
3583
@b{selectBorderWidth}@r{, and }@b{selectForeground} options for
3584
the text widget are tied to the @b{:background},
3585
@b{:borderwidth}@r{, and }@b{:foreground}@r{ options for the }@b{sel}
3586
tag: changes in either will automatically be reflected in the
3589
@unnumberedsubsec The Insertion Cursor
3591
The mark named @b{insert} has special significance in text widgets.
3592
It is defined automatically when a text widget is created and it
3593
may not be unset with the ``@i{pathName }@b{:mark unset}'' widget
3595
The @b{insert} mark represents the position of the insertion
3596
cursor, and the insertion cursor will automatically be drawn at
3597
this point whenever the text widget has the input focus.
3599
@unnumberedsubsec A Text Widget's Arguments
3601
The @b{text} command creates a new Tcl command whose
3602
name is the same as the path name of the text's window. This
3603
command may be used to invoke various
3604
operations on the widget. It has the following general form:
3607
@i{pathName option }@r{?}@i{arg arg ...}?
3610
@i{PathName} is the name of the command, which is the same as
3611
the text widget's path name. @i{Option}@r{ and the }@i{arg}s
3612
determine the exact behavior of the command. The following
3613
commands are possible for text widgets:
3616
@item @i{pathName }@b{:compare}@r{ }@i{index1 op index2}
3617
Compares the indices given by @i{index1}@r{ and }@i{index2} according
3618
to the relational operator given by @i{op}, and returns 1 if
3619
the relationship is satisfied and 0 if it isn't.
3620
@i{Op} must be one of the operators <, <=, ==, >=, >, or !=.
3621
If @i{op} is == then 1 is returned if the two indices refer to
3622
the same character, if @i{op}@r{ is < then 1 is returned if }@i{index1}
3623
refers to an earlier character in the text than @i{index2}, and
3625
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? }@i{?value option value ...}?
3626
Query or modify the configuration options of the widget.
3627
If no @i{option} is specified, returns a list describing all of
3628
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
3629
information on the format of this list). If @i{option} is specified
3630
with no @i{value}, then the command returns a list describing the
3631
one named option (this list will be identical to the corresponding
3632
sublist of the value returned if no @i{option} is specified). If
3633
one or more @i{option:value} pairs are specified, then the command
3634
modifies the given widget option(s) to have the given value(s); in
3635
this case the command returns an empty string.
3636
@i{Option}@r{ may have any of the values accepted by the }@b{text}
3638
@item @i{pathName }@b{:debug }@r{?}@i{boolean}?
3639
If @i{boolean} is specified, then it must have one of the true or
3640
false values accepted by Tcl_GetBoolean.
3641
If the value is a true one then internal consistency checks will be
3642
turned on in the B-tree code associated with text widgets.
3643
If @i{boolean} has a false value then the debugging checks will
3645
In either case the command returns an empty string.
3646
If @i{boolean}@r{ is not specified then the command returns }@b{on}
3647
or @b{off} to indicate whether or not debugging is turned on.
3648
There is a single debugging switch shared by all text widgets: turning
3649
debugging on or off in any widget turns it on or off for all widgets.
3650
For widgets with large amounts of text, the consistency checks may
3651
cause a noticeable slow-down.
3652
@item @i{pathName }@b{:delete }@i{index1 }@r{?}@i{index2}?
3653
Delete a range of characters from the text.
3654
If both @i{index1}@r{ and }@i{index2} are specified, then delete
3655
all the characters starting with the one given by @i{index1}
3656
and stopping just before @i{index2} (i.e. the character at
3657
@i{index2} is not deleted).
3658
If @i{index2} doesn't specify a position later in the text
3659
than @i{index1} then no characters are deleted.
3660
If @i{index2} isn't specified then the single character at
3661
@i{index1} is deleted.
3662
It is not allowable to delete characters in a way that would leave
3663
the text without a newline as the last character.
3664
The command returns an empty string.
3665
@item @i{pathName }@b{:get }@i{index1 }@r{?}@i{index2}?
3666
Return a range of characters from the text.
3667
The return value will be all the characters in the text starting
3668
with the one whose index is @i{index1} and ending just before
3669
the one whose index is @i{index2}@r{ (the character at }@i{index2}
3670
will not be returned).
3671
If @i{index2}@r{ is omitted then the single character at }@i{index1}
3673
If there are no characters in the specified range (e.g. @i{index1}
3674
is past the end of the file or @i{index2} is less than or equal
3675
to @i{index1}) then an empty string is returned.
3676
@item @i{pathName }@b{:index }@i{index}
3677
Returns the position corresponding to @i{index} in the form
3678
@i{line.char}@r{ where }@i{line}@r{ is the line number and }@i{char}
3679
is the character number.
3680
@i{Index} may have any of the forms described under INDICES above.
3681
@item @i{pathName }@b{:insert }\fIindex chars
3682
Inserts @i{chars} into the text just before the character at
3683
@i{index} and returns an empty string.
3684
It is not possible to insert characters after the last newline
3686
@item @i{pathName }@b{:mark }@i{option }@r{?}@i{arg arg ...}?
3687
This command is used to manipulate marks. The exact behavior of
3688
the command depends on the @i{option} argument that follows
3689
the @b{mark} argument. The following forms of the command
3690
are currently supported:
3692
@item @i{pathName }@b{:mark :names}
3693
Returns a list whose elements are the names of all the marks that
3695
@item @i{pathName }@b{:mark :set }@i{markName index}
3696
Sets the mark named @i{markName} to a position just before the
3697
character at @i{index}.
3698
If @i{markName} already exists, it is moved from its old position;
3699
if it doesn't exist, a new mark is created.
3700
This command returns an empty string.
3701
@item @i{pathName }@b{:mark :unset }@i{markName }@r{?}@i{markName markName ...}?
3702
Remove the mark corresponding to each of the @i{markName} arguments.
3703
The removed marks will not be usable in indices and will not be
3704
returned by future calls to ``@i{pathName }@b{:mark names}''.
3705
This command returns an empty string.
3708
@item @i{pathName }@b{:scan}@r{ }@i{option args}
3709
This command is used to implement scanning on texts. It has
3710
two forms, depending on @i{option}:
3712
@item @i{pathName }@b{:scan :mark }@i{y}
3713
Records @i{y} and the current view in the text window; used in
3714
conjunction with later @b{scan dragto} commands. Typically this
3715
command is associated with a mouse button press in the widget. It
3716
returns an empty string.
3717
@item @i{pathName }@b{:scan :dragto }@i{y}
3718
This command computes the difference between its @i{y} argument
3719
and the @i{y}@r{ argument to the last }@b{scan mark} command for
3720
the widget. It then adjusts the view up or down by 10 times the
3721
difference in y-coordinates. This command is typically associated
3722
with mouse motion events in the widget, to produce the effect of
3723
dragging the text at high speed through the window. The return
3724
value is an empty string.
3727
@item @i{pathName }@b{:tag }@i{option }@r{?}@i{arg arg ...}?
3728
This command is used to manipulate tags. The exact behavior of the
3729
command depends on the @i{option} argument that follows the
3730
@b{tag} argument. The following forms of the command are currently
3734
@item @i{pathName }@b{:tag :add }@i{tagName index1 }@r{?}@i{index2}?
3735
Associate the tag @i{tagName} with all of the characters starting
3736
with @i{index1} and ending just before
3737
@i{index2}@r{ (the character at }@i{index2} isn't tagged).
3738
If @i{index2} is omitted then the single character at
3739
@i{index1} is tagged.
3740
If there are no characters in the specified range (e.g. @i{index1}
3741
is past the end of the file or @i{index2} is less than or equal
3742
to @i{index1}) then the command has no effect.
3743
This command returns an empty string.
3744
@item @i{pathName }@b{:tag :bind }@i{tagName}@r{ ?}@i{sequence}@r{? ?}@i{command}?
3745
This command associates @i{command} with the tag given by
3747
Whenever the event sequence given by @i{sequence} occurs for a
3748
character that has been tagged with @i{tagName},
3749
the command will be invoked.
3750
This widget command is similar to the @b{bind} command except that
3751
it operates on characters in a text rather than entire widgets.
3752
See the @b{bind} manual entry for complete details
3753
on the syntax of @i{sequence} and the substitutions performed
3754
on @i{command} before invoking it.
3755
If all arguments are specified then a new binding is created, replacing
3756
any existing binding for the same @i{sequence}@r{ and }@i{tagName}
3757
(if the first character of @i{command}@r{ is ``+'' then }@i{command}
3758
augments an existing binding rather than replacing it).
3759
In this case the return value is an empty string.
3760
If @i{command}@r{ is omitted then the command returns the }@i{command}
3761
associated with @i{tagName}@r{ and }@i{sequence} (an error occurs
3762
if there is no such binding).
3763
If both @i{command}@r{ and }@i{sequence} are omitted then the command
3764
returns a list of all the sequences for which bindings have been
3765
defined for @i{tagName}.
3768
The only events for which bindings may be specified are those related
3769
to the mouse and keyboard, such as @b{Enter}@r{, }@b{Leave},
3770
@b{ButtonPress}@r{, }@b{Motion}@r{, and }@b{KeyPress}.
3771
Event bindings for a text widget use the @b{current} mark
3772
described under MARKS above.
3773
@b{Enter} events trigger for a character when it
3774
becomes the current character (i.e. the @b{current} mark moves
3775
to just in front of that character).
3776
@b{Leave} events trigger for a character when it ceases to be
3777
the current item (i.e. the @b{current} mark moves away from
3778
that character, or the character is deleted).
3779
These events are different than @b{Enter}@r{ and }@b{Leave}
3781
Mouse and keyboard events are directed to the current character.
3784
It is possible for the current character to have multiple tags,
3785
and for each of them to have a binding for a particular event
3787
When this occurs, the binding from the highest priority tag is
3789
If a particular tag doesn't have a binding that matches an
3790
event, then the tag is ignored and tags with lower priority
3794
If bindings are created for the widget as a whole using the
3795
@b{bind} command, then those bindings will supplement the
3797
This means that a single event can trigger two Tcl scripts,
3798
one for a widget-level binding and one for a tag-level
3802
@item @i{pathName }@b{:tag :configure }@i{tagName}@r{ ?}@i{option}@r{? ?}@i{value}@r{? ?}@i{option value ...}?
3803
This command is similar to the @b{configure} widget command except
3804
that it modifies options associated with the tag given by @i{tagName}
3805
instead of modifying options for the overall text widget.
3806
If no @i{option} is specified, the command returns a list describing
3807
all of the available options for @i{tagName}@r{ (see }@b{Tk_ConfigureInfo}
3808
for information on the format of this list).
3809
If @i{option}@r{ is specified with no }@i{value}, then the command returns
3810
a list describing the one named option (this list will be identical to
3811
the corresponding sublist of the value returned if no @i{option}
3813
If one or more @i{option:value} pairs are specified, then the command
3814
modifies the given option(s) to have the given value(s) in @i{tagName};
3815
in this case the command returns an empty string.
3816
See TAGS above for details on the options available for tags.
3817
@item @i{pathName }@b{:tag :delete }@i{tagName }@r{?}@i{tagName ...}?
3818
Deletes all tag information for each of the @i{tagName}
3820
The command removes the tags from all characters in the file
3821
and also deletes any other information associated with the tags,
3822
such as bindings and display information.
3823
The command returns an empty string.
3824
@item @i{pathName }@b{:tag :lower }@i{tagName }@r{?}@i{belowThis}?
3825
Changes the priority of tag @i{tagName} so that it is just lower
3826
in priority than the tag whose name is @i{belowThis}.
3827
If @i{belowThis}@r{ is omitted, then }@i{tagName}'s priority
3828
is changed to make it lowest priority of all tags.
3829
@item @i{pathName }@b{:tag :names }@r{?}@i{index}?
3830
Returns a list whose elements are the names of all the tags that
3831
are active at the character position given by @i{index}.
3832
If @i{index} is omitted, then the return value will describe
3833
all of the tags that exist for the text (this includes all tags
3834
that have been named in a ``@i{pathName }@b{:tag}'' widget
3835
command but haven't been deleted by a ``@i{pathName }@b{:tag :delete}''
3836
widget command, even if no characters are currently marked with
3838
The list will be sorted in order from lowest priority to highest
3840
@item @i{pathName }@b{:tag :nextrange }@i{tagName index1 }@r{?}@i{index2}?
3841
This command searches the text for a range of characters tagged
3842
with @i{tagName} where the first character of the range is
3843
no earlier than the character at @i{index1} and no later than
3844
the character just before @i{index2} (a range starting at
3845
@i{index2} will not be considered).
3846
If several matching ranges exist, the first one is chosen.
3847
The command's return value is a list containing
3848
two elements, which are the index of the first character of the
3849
range and the index of the character just after the last one in
3851
If no matching range is found then the return value is an
3853
If @i{index2} is not given then it defaults to the end of the text.
3854
@item @i{pathName }@b{:tag :raise }@i{tagName }@r{?}@i{aboveThis}?
3855
Changes the priority of tag @i{tagName} so that it is just higher
3856
in priority than the tag whose name is @i{aboveThis}.
3857
If @i{aboveThis}@r{ is omitted, then }@i{tagName}'s priority
3858
is changed to make it highest priority of all tags.
3859
@item @i{pathName }@b{:tag :ranges }@i{tagName}
3860
Returns a list describing all of the ranges of text that have been
3861
tagged with @i{tagName}.
3862
The first two elements of the list describe the first tagged range
3863
in the text, the next two elements describe the second range, and
3865
The first element of each pair contains the index of the first
3866
character of the range, and the second element of the pair contains
3867
the index of the character just after the last one in the
3869
If there are no characters tagged with @i{tag} then an
3870
empty string is returned.
3871
@item @i{pathName }@b{:tag :remove }@i{tagName index1 }@r{?}@i{index2}?
3872
Remove the tag @i{tagName} from all of the characters starting
3873
at @i{index1} and ending just before
3874
@i{index2}@r{ (the character at }@i{index2} isn't affected).
3875
If @i{index2} is omitted then the single character at
3876
@i{index1} is untagged.
3877
If there are no characters in the specified range (e.g. @i{index1}
3878
is past the end of the file or @i{index2} is less than or equal
3879
to @i{index1}) then the command has no effect.
3880
This command returns an empty string.
3883
@item @i{pathName }@b{:yview }@r{?}@b{:pickplace}@r{? }@i{what}
3884
This command changes the view in the widget's window so that the line
3885
given by @i{what} is visible in the window.
3886
@i{What} may be either an absolute line number, where 0 corresponds
3887
to the first line of the file, or an index with any of the forms
3888
described under INDICES above.
3889
The first form (absolute line number) is used in the commands issued
3890
by scrollbars to control the widget's view.
3891
If the @b{:pickplace}@r{ option isn't specified then }@i{what} will
3892
appear at the top of the window.
3893
If @b{:pickplace} is specified then the widget chooses where
3894
@i{what} appears in the window:
3898
If @i{what} is already visible somewhere in the window then the
3899
command does nothing.
3902
If @i{what} is only a few lines off-screen above the window then
3903
it will be positioned at the top of the window.
3906
If @i{what} is only a few lines off-screen below the window then
3907
it will be positioned at the bottom of the window.
3910
Otherwise, @i{what} will be centered in the window.
3913
The @b{:pickplace} option is typically used after inserting text
3914
to make sure that the insertion cursor is still visible on the screen.
3915
This command returns an empty string.
3919
@unnumberedsubsec Bindings
3921
Tk automatically creates class bindings for texts that give them
3922
the following default behavior:
3926
Pressing mouse button 1 in an text positions the insertion cursor
3927
just before the character underneath the mouse cursor and sets the
3928
input focus to this widget.
3931
Dragging with mouse button 1 strokes out a selection between
3932
the insertion cursor and the character under the mouse.
3935
If you double-press mouse button 1 then the word under the mouse cursor
3936
will be selected, the insertion cursor will be positioned at the
3937
beginning of the word, and dragging the mouse will stroke out a selection
3938
whole words at a time.
3941
If you triple-press mouse button 1 then the line under the mouse cursor
3942
will be selected, the insertion cursor will be positioned at the
3943
beginning of the line, and dragging the mouse will stroke out a selection
3944
whole line at a time.
3947
The ends of the selection can be adjusted by dragging with mouse
3948
button 1 while the shift key is down; this will adjust the end
3949
of the selection that was nearest to the mouse cursor when button
3950
1 was pressed. If the selection was made in word or line mode then
3951
it will be adjusted in this same mode.
3954
The view in the text can be adjusted by dragging with mouse button 2.
3957
If the input focus is in a text widget and characters are typed on the
3958
keyboard, the characters are inserted just before the insertion cursor.
3961
Control+h and the Backspace and Delete keys erase the character just
3962
before the insertion cursor.
3965
Control+v inserts the current selection just before the insertion cursor.
3968
Control+d deletes the selected characters; an error occurs if the selection
3969
is not in this widget.
3972
If the text is disabled using the @b{state} option, then the text's
3973
view can still be adjusted and text in the text can still be selected,
3974
but no insertion cursor will be displayed and no text modifications will
3977
The behavior of texts can be changed by defining new bindings for
3978
individual widgets or by redefining the class bindings.
3980
@unnumberedsubsec "Performance Issues"
3982
Text widgets should run efficiently under a variety
3983
of conditions. The text widget uses about 2-3 bytes of
3984
main memory for each byte of text, so texts containing a megabyte
3985
or more should be practical on most workstations.
3986
Text is represented internally with a modified B-tree structure
3987
that makes operations relatively efficient even with large texts.
3988
Tags are included in the B-tree structure in a way that allows
3989
tags to span large ranges or have many disjoint smaller ranges
3990
without loss of efficiency.
3991
Marks are also implemented in a way that allows large numbers of
3993
The only known mode of operation where a text widget may not run
3994
efficiently is if it has a very large number of different tags.
3995
Hundreds of tags should be fine, or even a thousand,
3996
but tens of thousands of tags will make texts consume a lot of
3997
memory and run slowly.
3999
@unnumberedsubsec Keywords
4001
@node entry, message, text, Widgets
4005
entry \- Create and manipulate entry widgets
4006
@unnumberedsubsec Synopsis
4007
@b{entry}@i{ }@i{pathName }@r{?}@i{options}?
4008
@unnumberedsubsec Standard Options
4012
background foreground insertWidth selectForeground
4013
borderWidth insertBackground relief textVariable
4014
cursor insertBorderWidth scrollCommand
4015
exportSelection insertOffTime selectBackground
4016
font insertOnTime selectBorderWidth
4020
@xref{options}, for more information.
4021
@unnumberedsubsec Arguments for Entry
4025
@item @code{@b{:state}}
4027
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
4031
Specifies one of two states for the entry: @b{normal}@r{ or }@b{disabled}.
4032
If the entry is disabled then the value may not be changed using widget
4033
commands and no insertion cursor will be displayed, even if the input focus is
4039
@item @code{@b{:width}}
4041
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
4045
Specifies an integer value indicating the desired width of the entry window,
4046
in average-size characters of the widget's font.
4050
@unnumberedsubsec Description
4052
The @b{entry} command creates a new window (given by the
4053
@i{pathName} argument) and makes it into an entry widget.
4054
Additional options, described above, may be specified on the
4055
command line or in the option database
4056
to configure aspects of the entry such as its colors, font,
4057
and relief. The @b{entry} command returns its
4058
@i{pathName} argument. At the time this command is invoked,
4059
there must not exist a window named @i{pathName}, but
4060
@i{pathName}'s parent must exist.
4062
An entry is a widget that displays a one-line text string and
4063
allows that string to be edited using widget commands described below, which
4064
are typically bound to keystrokes and mouse actions.
4065
When first created, an entry's string is empty.
4066
A portion of the entry may be selected as described below.
4067
If an entry is exporting its selection (see the @b{exportSelection}
4068
option), then it will observe the standard X11 protocols for handling the
4069
selection; entry selections are available as type @b{STRING}.
4070
Entries also observe the standard Tk rules for dealing with the
4071
input focus. When an entry has the input focus it displays an
4072
@i{insertion cursor} to indicate where new characters will be
4075
Entries are capable of displaying strings that are too long to
4076
fit entirely within the widget's window. In this case, only a
4077
portion of the string will be displayed; commands described below
4078
may be used to change the view in the window. Entries use
4079
the standard @b{scrollCommand} mechanism for interacting with
4080
scrollbars (see the description of the @b{scrollCommand} option
4081
for details). They also support scanning, as described below.
4083
@unnumberedsubsec A Entry Widget's Arguments
4085
The @b{entry} command creates a new Tcl command whose
4086
name is @i{pathName}. This
4087
command may be used to invoke various
4088
operations on the widget. It has the following general form:
4091
@i{pathName option }@r{?}@i{arg arg ...}?
4094
@i{Option}@r{ and the }@i{arg}s
4095
determine the exact behavior of the command.
4097
Many of the widget commands for entries take one or more indices as
4098
arguments. An index specifies a particular character in the entry's
4099
string, in any of the following ways:
4103
Specifies the character as a numerical index, where 0 corresponds
4104
to the first character in the string.
4106
Indicates the character just after the last one in the entry's string.
4107
This is equivalent to specifying a numerical index equal to the length
4108
of the entry's string.
4110
Indicates the character adjacent to and immediately following the
4113
Indicates the first character in the selection. It is an error to
4114
use this form if the selection isn't in the entry window.
4116
Indicates the last character in the selection. It is an error to
4117
use this form if the selection isn't in the entry window.
4118
@item @b{@@}@i{number}
4119
In this form, @i{number} is treated as an x-coordinate in the
4120
entry's window; the character spanning that x-coordinate is used.
4121
For example, ``@b{@@0}'' indicates the left-most character in the
4126
Abbreviations may be used for any of the forms above, e.g. ``@b{e}''
4127
or ``@b{sel.f}''. In general, out-of-range indices are automatically
4128
rounded to the nearest legal value.
4130
The following commands are possible for entry widgets:
4133
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
4134
Query or modify the configuration options of the widget.
4135
If no @i{option} is specified, returns a list describing all of
4136
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
4137
information on the format of this list). If @i{option} is specified
4138
with no @i{value}, then the command returns a list describing the
4139
one named option (this list will be identical to the corresponding
4140
sublist of the value returned if no @i{option} is specified). If
4141
one or more @i{option:value} pairs are specified, then the command
4142
modifies the given widget option(s) to have the given value(s); in
4143
this case the command returns an empty string.
4144
@i{Option}@r{ may have any of the values accepted by the }@b{entry}
4146
@item @i{pathName }@b{:delete }@i{first }@r{?}@i{last}?
4147
Delete one or more elements of the entry. @i{First}@r{ and }@i{last}
4148
are indices of of the first and last characters in the range to
4149
be deleted. If @i{last} isn't specified it defaults to
4150
@i{first}, i.e. a single character is deleted. This command
4151
returns an empty string.
4152
@item @i{pathName }@b{:get}
4153
Returns the entry's string.
4154
@item @i{pathName }@b{:icursor }@i{index}
4155
Arrange for the insertion cursor to be displayed just before the character
4156
given by @i{index}. Returns an empty string.
4157
@item @i{pathName }@b{:index}@i{ index}
4158
Returns the numerical index corresponding to @i{index}.
4159
@item @i{pathName }@b{:insert }@i{index string}
4160
Insert the characters of @i{string} just before the character
4161
indicated by @i{index}. Returns an empty string.
4162
@item @i{pathName }@b{:scan}@r{ }@i{option args}
4163
This command is used to implement scanning on entries. It has
4164
two forms, depending on @i{option}:
4166
@item @i{pathName }@b{:scan :mark }@i{x}
4167
Records @i{x} and the current view in the entry window; used in
4168
conjunction with later @b{scan dragto} commands. Typically this
4169
command is associated with a mouse button press in the widget. It
4170
returns an empty string.
4171
@item @i{pathName }@b{:scan :dragto }@i{x}
4172
This command computes the difference between its @i{x} argument
4173
and the @i{x}@r{ argument to the last }@b{scan mark} command for
4174
the widget. It then adjusts the view left or right by 10 times the
4175
difference in x-coordinates. This command is typically associated
4176
with mouse motion events in the widget, to produce the effect of
4177
dragging the entry at high speed through the window. The return
4178
value is an empty string.
4180
@item @i{pathName }@b{:select }@i{option arg}
4181
This command is used to adjust the selection within an entry. It
4182
has several forms, depending on @i{option}:
4184
@item @i{pathName }@b{:select :adjust }@i{index}
4185
Locate the end of the selection nearest to the character given by
4186
@i{index}@r{, and adjust that end of the selection to be at }@i{index}
4187
(i.e including but not going beyond @i{index}). The other
4188
end of the selection is made the anchor point for future
4189
@b{select to} commands. If the selection
4190
isn't currently in the entry, then a new selection is created to
4191
include the characters between @i{index} and the most recent
4192
selection anchor point, inclusive.
4193
Returns an empty string.
4194
@item @i{pathName }@b{:select :clear}
4195
Clear the selection if it is currently in this widget. If the
4196
selection isn't in this widget then the command has no effect.
4197
Returns an empty string.
4198
@item @i{pathName }@b{:select :from }@i{index}
4199
Set the selection anchor point to just before the character
4200
given by @i{index}. Doesn't change the selection.
4201
Returns an empty string.
4202
@item @i{pathName }@b{:select :to }@i{index}
4203
Set the selection to consist of the elements from the anchor
4204
point to element @i{index}, inclusive. The anchor point is
4205
determined by the most recent @b{select from}@r{ or }@b{select adjust}
4206
command in this widget. If the selection isn't in this widget
4207
then a new selection is created using the most recent anchor point
4208
specified for the widget. Returns an empty string.
4210
@item @i{pathName }@b{:view }@i{index}
4211
Adjust the view in the entry so that element @i{index} is
4212
at the left edge of the window. Returns an empty string.
4215
@unnumberedsubsec "Default Bindings"
4217
Tk automatically creates class bindings for entries that give them
4218
the following default behavior:
4223
Clicking mouse button 1 in an entry positions the insertion cursor
4224
just before the character underneath the mouse cursor and sets the
4225
input focus to this widget.
4228
Dragging with mouse button 1 strokes out a selection between
4229
the insertion cursor and the character under the mouse.
4232
The ends of the selection can be adjusted by dragging with mouse
4233
button 1 while the shift key is down; this will adjust the end
4234
of the selection that was nearest to the mouse cursor when button
4238
The view in the entry can be adjusted by dragging with mouse button 2.
4241
If the input focus is in an entry widget and characters are typed on the
4242
keyboard, the characters are inserted just before the insertion cursor.
4245
Control-h and the Backspace and Delete keys erase the character just
4246
before the insertion cursor.
4249
Control-w erases the word just before the insertion cursor.
4252
Control-u clears the entry to an empty string.
4255
Control-v inserts the current selection just before the insertion cursor.
4258
Control-d deletes the selected characters; an error occurs if the selection
4259
is not in this widget.
4262
If the entry is disabled using the @b{state} option, then the entry's
4263
view can still be adjusted and text in the entry can still be selected,
4264
but no insertion cursor will be displayed and no text modifications will
4267
The behavior of entries can be changed by defining new bindings for
4268
individual widgets or by redefining the class bindings.
4270
@unnumberedsubsec Keywords
4272
@node message, frame, entry, Widgets
4276
message \- Create and manipulate message widgets
4277
@unnumberedsubsec Synopsis
4278
@b{message}@i{ }@i{pathName }@r{?}@i{options}?
4279
@unnumberedsubsec Standard Options
4283
anchor cursor padX text
4284
background font padY textVariable
4285
borderWidth foreground relief width
4289
@xref{options}, for more information.
4290
@unnumberedsubsec Arguments for Message
4294
@item @code{@b{:aspect}}
4296
Name=@code{"@b{aspect}@r{"} Class=@code{"}@b{Aspect}"}
4300
Specifies a non-negative integer value indicating desired
4301
aspect ratio for the text. The aspect ratio is specified as
4302
100*width/height. 100 means the text should
4303
be as wide as it is tall, 200 means the text should
4304
be twice as wide as it is tall, 50 means the text should
4305
be twice as tall as it is wide, and so on.
4306
Used to choose line length for text if @b{width} option
4313
@item @code{@b{:justify}}
4315
Name=@code{"@b{justify}@r{"} Class=@code{"}@b{Justify}"}
4319
Specifies how to justify lines of text.
4320
Must be one of @b{left}@r{, }@b{center}@r{, or }@b{right}. Defaults
4322
This option works together with the @b{anchor}@r{, }@b{aspect},
4323
@b{padX}@r{, }@b{padY}@r{, and }@b{width} options to provide a variety
4324
of arrangements of the text within the window.
4325
The @b{aspect}@r{ and }@b{width} options determine the amount of
4326
screen space needed to display the text.
4327
The @b{anchor}@r{, }@b{padX}@r{, and }@b{padY} options determine where this
4328
rectangular area is displayed within the widget's window, and the
4329
@b{justify} option determines how each line is displayed within that
4331
For example, suppose @b{anchor}@r{ is }@b{e}@r{ and }@b{justify} is
4332
@b{left}, and that the message window is much larger than needed
4334
The the text will displayed so that the left edges of all the lines
4335
line up and the right edge of the longest line is @b{padX} from
4336
the right side of the window; the entire text block will be centered
4337
in the vertical span of the window.
4342
@item @code{@b{:width}}
4344
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
4348
Specifies the length of lines in the window.
4349
The value may have any of the forms acceptable to @b{Tk_GetPixels}.
4350
If this option has a value greater than zero then the @b{aspect}
4351
option is ignored and the @b{width} option determines the line
4353
If this option has a value less than or equal to zero, then
4354
the @b{aspect} option determines the line length.
4358
@unnumberedsubsec Description
4360
The @b{message} command creates a new window (given by the
4361
@i{pathName} argument) and makes it into a message widget.
4363
options, described above, may be specified on the command line
4364
or in the option database
4365
to configure aspects of the message such as its colors, font,
4366
text, and initial relief. The @b{message} command returns its
4367
@i{pathName} argument. At the time this command is invoked,
4368
there must not exist a window named @i{pathName}, but
4369
@i{pathName}'s parent must exist.
4371
A message is a widget that displays a textual string. A message
4372
widget has three special features. First, it breaks up
4373
its string into lines in order to produce a given aspect ratio
4374
for the window. The line breaks are chosen at word boundaries
4375
wherever possible (if not even a single word would fit on a
4376
line, then the word will be split across lines). Newline characters
4377
in the string will force line breaks; they can be used, for example,
4378
to leave blank lines in the display.
4380
The second feature of a message widget is justification. The text
4381
may be displayed left-justified (each line starts at the left side of
4382
the window), centered on a line-by-line basis, or right-justified
4383
(each line ends at the right side of the window).
4385
The third feature of a message widget is that it handles control
4386
characters and non-printing characters specially. Tab characters
4387
are replaced with enough blank space to line up on the next
4388
8-character boundary. Newlines cause line breaks. Other control
4389
characters (ASCII code less than 0x20) and characters not defined
4390
in the font are displayed as a four-character sequence \fB\ex@i{hh} where
4391
@i{hh} is the two-digit hexadecimal number corresponding to
4392
the character. In the unusual case where the font doesn't contain
4393
all of the characters in ``0123456789abcdef\ex'' then control
4394
characters and undefined characters are not displayed at all.
4396
@unnumberedsubsec A Message Widget's Arguments
4398
The @b{message} command creates a new Tcl command whose
4399
name is @i{pathName}. This
4400
command may be used to invoke various
4401
operations on the widget. It has the following general form:
4404
@i{pathName option }@r{?}@i{arg arg ...}?
4407
@i{Option}@r{ and the }@i{arg}s
4408
determine the exact behavior of the command. The following
4409
commands are possible for message widgets:
4412
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
4413
Query or modify the configuration options of the widget.
4414
If no @i{option} is specified, returns a list describing all of
4415
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
4416
information on the format of this list). If @i{option} is specified
4417
with no @i{value}, then the command returns a list describing the
4418
one named option (this list will be identical to the corresponding
4419
sublist of the value returned if no @i{option} is specified). If
4420
one or more @i{option:value} pairs are specified, then the command
4421
modifies the given widget option(s) to have the given value(s); in
4422
this case the command returns an empty string.
4423
@i{Option}@r{ may have any of the values accepted by the }@b{message}
4427
@unnumberedsubsec "Default Bindings"
4429
When a new message is created, it has no default event bindings:
4430
messages are intended for output purposes only.
4432
@unnumberedsubsec Bugs
4434
Tabs don't work very well with text that is centered or right-justified.
4435
The most common result is that the line is justified wrong.
4437
@unnumberedsubsec Keywords
4439
@node frame, label, message, Widgets
4443
frame \- Create and manipulate frame widgets
4444
@unnumberedsubsec Synopsis
4445
@b{frame}@i{ }@i{pathName }@r{?}@b{:class }@i{className}@r{? ?}@i{options}?
4446
@unnumberedsubsec Standard Options
4450
background cursor relief
4451
borderWidth geometry
4455
@xref{options}, for more information.
4456
@unnumberedsubsec Arguments for Frame
4460
@item @code{@b{:height}}
4462
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
4466
Specifies the desired height for the window in any of the forms
4467
acceptable to @b{Tk_GetPixels}.
4468
This option is only used if the @b{:geometry} option is
4470
If this option is less than or equal to zero (and @b{:geometry}
4471
is not specified) then the window will not request any size at
4477
@item @code{@b{:width}}
4479
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
4483
Specifies the desired width for the window in any of the forms
4484
acceptable to @b{Tk_GetPixels}.
4485
This option is only used if the @b{:geometry} option is
4487
If this option is less than or equal to zero (and @b{:geometry}
4488
is not specified) then the window will not request any size at
4493
@unnumberedsubsec Description
4495
The @b{frame} command creates a new window (given by the
4496
@i{pathName} argument) and makes it into a frame widget.
4498
options, described above, may be specified on the command line
4499
or in the option database
4500
to configure aspects of the frame such as its background color
4501
and relief. The @b{frame} command returns the
4502
path name of the new window.
4504
A frame is a simple widget. Its primary purpose is to act as a
4505
spacer or container for complex window layouts. The only features
4506
of a frame are its background color and an optional 3-D border to make the
4507
frame appear raised or sunken.
4509
In addition to the standard options listed above, a @b{:class}
4510
option may be specified on the command line. If it is specified, then
4511
the new widget's class will be set to @i{className} instead of
4512
@b{Frame}. Changing the class of a frame widget may be useful
4513
in order to use a special class name in database options referring
4514
to this widget and its children. Note: @b{:class} is handled
4515
differently than other command-line options and cannot be specified
4516
using the option database (it has to be processed
4517
before the other options are even looked up, since the new class
4518
name will affect the lookup of the other options). In addition,
4519
the @b{:class} option may not be queried or changed using the
4520
@b{config} command described below.
4522
@unnumberedsubsec A Frame Widget's Arguments
4524
The @b{frame} command creates a new Tcl command whose
4525
name is the same as the path name of the frame's window. This
4526
command may be used to invoke various
4527
operations on the widget. It has the following general form:
4530
@i{pathName option }@r{?}@i{arg arg ...}?
4533
@i{PathName} is the name of the command, which is the same as
4534
the frame widget's path name. @i{Option}@r{ and the }@i{arg}s
4535
determine the exact behavior of the command. The following
4536
commands are possible for frame widgets:
4539
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? }@i{?value option value ...}?
4540
Query or modify the configuration options of the widget.
4541
If no @i{option} is specified, returns a list describing all of
4542
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
4543
information on the format of this list). If @i{option} is specified
4544
with no @i{value}, then the command returns a list describing the
4545
one named option (this list will be identical to the corresponding
4546
sublist of the value returned if no @i{option} is specified). If
4547
one or more @i{option:value} pairs are specified, then the command
4548
modifies the given widget option(s) to have the given value(s); in
4549
this case the command returns an empty string.
4550
@i{Option}@r{ may have any of the values accepted by the }@b{frame}
4554
@unnumberedsubsec Bindings
4556
When a new frame is created, it has no default event bindings:
4557
frames are not intended to be interactive.
4559
@unnumberedsubsec Keywords
4561
@node label, radiobutton, frame, Widgets
4565
label \- Create and manipulate label widgets
4566
@unnumberedsubsec Synopsis
4567
@b{label}@i{ }@i{pathName }@r{?}@i{options}?
4568
@unnumberedsubsec Standard Options
4572
anchor borderWidth foreground relief
4573
background cursor padX text
4574
bitmap font padY textVariable
4578
@xref{options}, for more information.
4579
@unnumberedsubsec Arguments for Label
4583
@item @code{@b{:height}}
4585
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
4589
Specifies a desired height for the label.
4590
If a bitmap is being displayed in the label then the value is in
4591
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
4592
for text it is in lines of text.
4593
If this option isn't specified, the label's desired height is computed
4594
from the size of the bitmap or text being displayed in it.
4599
@item @code{@b{:width}}
4601
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
4605
Specifies a desired width for the label.
4606
If a bitmap is being displayed in the label then the value is in
4607
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
4608
for text it is in characters.
4609
If this option isn't specified, the label's desired width is computed
4610
from the size of the bitmap or text being displayed in it.
4614
@unnumberedsubsec Description
4616
The @b{label} command creates a new window (given by the
4617
@i{pathName} argument) and makes it into a label widget.
4619
options, described above, may be specified on the command line
4620
or in the option database
4621
to configure aspects of the label such as its colors, font,
4622
text, and initial relief. The @b{label} command returns its
4623
@i{pathName} argument. At the time this command is invoked,
4624
there must not exist a window named @i{pathName}, but
4625
@i{pathName}'s parent must exist.
4628
that displays a textual string or bitmap.
4629
The label can be manipulated in a few simple ways, such as
4630
changing its relief or text, using the commands described below.
4632
@unnumberedsubsec A Label Widget's Arguments
4634
The @b{label} command creates a new Tcl command whose
4635
name is @i{pathName}. This
4636
command may be used to invoke various
4637
operations on the widget. It has the following general form:
4640
@i{pathName option }@r{?}@i{arg arg ...}?
4643
@i{Option}@r{ and the }@i{arg}s
4644
determine the exact behavior of the command. The following
4645
commands are possible for label widgets:
4648
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
4649
Query or modify the configuration options of the widget.
4650
If no @i{option} is specified, returns a list describing all of
4651
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
4652
information on the format of this list). If @i{option} is specified
4653
with no @i{value}, then the command returns a list describing the
4654
one named option (this list will be identical to the corresponding
4655
sublist of the value returned if no @i{option} is specified). If
4656
one or more @i{option:value} pairs are specified, then the command
4657
modifies the given widget option(s) to have the given value(s); in
4658
this case the command returns an empty string.
4659
@i{Option}@r{ may have any of the values accepted by the }@b{label}
4663
@unnumberedsubsec Bindings
4665
When a new label is created, it has no default event bindings:
4666
labels are not intended to be interactive.
4668
@unnumberedsubsec Keywords
4670
@node radiobutton, toplevel, label, Widgets
4671
@section radiobutton
4674
radiobutton \- Create and manipulate radio-button widgets
4675
@unnumberedsubsec Synopsis
4676
@b{radiobutton}@i{ }@i{pathName }@r{?}@i{options}?
4677
@unnumberedsubsec Standard Options
4681
activeBackground bitmap font relief
4682
activeForeground borderWidth foreground text
4683
anchor cursor padX textVariable
4684
background disabledForeground padX
4688
@xref{options}, for more information.
4689
@unnumberedsubsec Arguments for Radiobutton
4693
@item @code{@b{:command}}
4695
Name=@code{"@b{command}@r{"} Class=@code{"}@b{Command}"}
4699
Specifies a Tcl command to associate with the button. This command
4700
is typically invoked when mouse button 1 is released over the button
4701
window. The button's global variable (@b{:variable} option) will
4702
be updated before the command is invoked.
4707
@item @code{@b{:height}}
4709
Name=@code{"@b{height}@r{"} Class=@code{"}@b{Height}"}
4713
Specifies a desired height for the button.
4714
If a bitmap is being displayed in the button then the value is in
4715
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
4716
for text it is in lines of text.
4717
If this option isn't specified, the button's desired height is computed
4718
from the size of the bitmap or text being displayed in it.
4723
@item @code{@b{:selector}}
4725
Name=@code{"@b{selector}@r{"} Class=@code{"}@b{Foreground}"}
4729
Specifies the color to draw in the selector when this button is
4731
If specified as an empty string then no selector is drawn for the button.
4736
@item @code{@b{:state}}
4738
Name=@code{"@b{state}@r{"} Class=@code{"}@b{State}"}
4742
Specifies one of three states for the radio button: @b{normal}@r{, }@b{active},
4743
or @b{disabled}. In normal state the radio button is displayed using the
4744
@b{foreground}@r{ and }@b{background} options. The active state is
4745
typically used when the pointer is over the radio button. In active state
4746
the radio button is displayed using the @b{activeForeground} and
4747
@b{activeBackground} options. Disabled state means that the radio button
4748
is insensitive: it doesn't activate and doesn't respond to mouse
4749
button presses. In this state the @b{disabledForeground} and
4750
@b{background} options determine how the radio button is displayed.
4755
@item @code{@b{:value}}
4757
Name=@code{"@b{value}@r{"} Class=@code{"}@b{Value}"}
4761
Specifies value to store in the button's associated variable whenever
4762
this button is selected. Defaults to the name of the radio button.
4767
@item @code{@b{:variable}}
4769
Name=@code{"@b{variable}@r{"} Class=@code{"}@b{Variable}"}
4773
Specifies name of global variable to set whenever this button is
4774
selected. Changes in this variable also cause the button to select
4776
Defaults to the value @b{selectedButton}.
4781
@item @code{@b{:width}}
4783
Name=@code{"@b{width}@r{"} Class=@code{"}@b{Width}"}
4787
Specifies a desired width for the button.
4788
If a bitmap is being displayed in the button then the value is in
4789
screen units (i.e. any of the forms acceptable to @b{Tk_GetPixels});
4790
for text it is in characters.
4791
If this option isn't specified, the button's desired width is computed
4792
from the size of the bitmap or text being displayed in it.
4796
@unnumberedsubsec Description
4798
The @b{radiobutton} command creates a new window (given by the
4799
@i{pathName} argument) and makes it into a radiobutton widget.
4801
options, described above, may be specified on the command line
4802
or in the option database
4803
to configure aspects of the radio button such as its colors, font,
4804
text, and initial relief. The @b{radiobutton} command returns its
4805
@i{pathName} argument. At the time this command is invoked,
4806
there must not exist a window named @i{pathName}, but
4807
@i{pathName}'s parent must exist.
4809
A radio button is a widget
4810
that displays a textual string or bitmap
4811
and a diamond called a @i{selector}.
4813
all of the behavior of a simple button: it can display itself in either
4814
of three different ways, according to the @b{state} option;
4815
it can be made to appear
4816
raised, sunken, or flat; it can be made to flash; and it invokes
4817
a Tcl command whenever mouse button 1 is clicked over the
4820
In addition, radio buttons can be @i{selected}.
4821
If a radio button is selected then a special highlight appears
4822
in the selector and a Tcl variable associated with the radio button
4823
is set to a particular value.
4824
If the radio button is not selected then the selector is drawn
4825
in a different fashion.
4826
Typically, several radio buttons share a single variable and the
4827
value of the variable indicates which radio button is to be selected.
4828
When a radio button is selected it sets the value of the variable to
4829
indicate that fact; each radio button also monitors the value of
4830
the variable and automatically selects and deselects itself when the
4831
variable's value changes.
4832
By default the variable @b{selectedButton}
4833
is used; its contents give the name of the button that is
4834
selected, or the empty string if no button associated with that
4835
variable is selected.
4836
The name of the variable for a radio button,
4837
plus the variable to be stored into it, may be modified with options
4838
on the command line or in the option database. By default a radio
4839
button is configured to select itself on button clicks.
4841
@unnumberedsubsec A Radiobutton Widget's Arguments
4843
The @b{radiobutton} command creates a new Tcl command whose
4844
name is @i{pathName}. This
4845
command may be used to invoke various
4846
operations on the widget. It has the following general form:
4849
@i{pathName option }@r{?}@i{arg arg ...}?
4852
@i{Option}@r{ and the }@i{arg}s
4853
determine the exact behavior of the command. The following
4854
commands are possible for radio-button widgets:
4857
@item @i{pathName }@b{:activate}
4858
Change the radio button's state to @b{active} and redisplay the button
4859
using its active foreground and background colors instead of normal
4861
This command is ignored if the radio button's state is @b{disabled}.
4862
This command is obsolete and will eventually be removed;
4863
use ``@i{pathName }@b{:configure :state active}'' instead.
4864
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
4865
Query or modify the configuration options of the widget.
4866
If no @i{option} is specified, returns a list describing all of
4867
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
4868
information on the format of this list). If @i{option} is specified
4869
with no @i{value}, then the command returns a list describing the
4870
one named option (this list will be identical to the corresponding
4871
sublist of the value returned if no @i{option} is specified). If
4872
one or more @i{option:value} pairs are specified, then the command
4873
modifies the given widget option(s) to have the given value(s); in
4874
this case the command returns an empty string.
4875
@i{Option}@r{ may have any of the values accepted by the }@b{radiobutton}
4877
@item @i{pathName }@b{:deactivate}
4878
Change the radio button's state to @b{normal} and redisplay the button
4879
using its normal foreground and background colors.
4880
This command is ignored if the radio button's state is @b{disabled}.
4881
This command is obsolete and will eventually be removed;
4882
use ``@i{pathName }@b{:configure :state normal}'' instead.
4883
@item @i{pathName }@b{:deselect}
4884
Deselect the radio button: redisplay it without a highlight in
4885
the selector and set the associated variable to an empty string. If
4886
this radio button was not currently selected, then the command has
4888
@item @i{pathName }@b{:flash}
4889
Flash the radio button. This is accomplished by redisplaying the radio button
4890
several times, alternating between active and normal colors. At
4891
the end of the flash the radio button is left in the same normal/active
4892
state as when the command was invoked.
4893
This command is ignored if the radio button's state is @b{disabled}.
4894
@item @i{pathName }@b{:invoke}
4895
Does just what would have happened if the user invoked the radio button
4896
with the mouse: select the button and invoke
4897
its associated Tcl command, if there is one.
4898
The return value is the return value from the Tcl command, or an
4899
empty string if there is no command associated with the radio button.
4900
This command is ignored if the radio button's state is @b{disabled}.
4901
@item @i{pathName }@b{:select}
4902
Select the radio button: display it with a highlighted
4903
selector and set the associated variable to the value corresponding
4907
@unnumberedsubsec Bindings
4909
Tk automatically creates class bindings for radio buttons that give them
4910
the following default behavior:
4914
The radio button activates whenever the mouse passes over it and deactivates
4915
whenever the mouse leaves the radio button.
4918
The radio button's relief is changed to sunken whenever mouse button 1 is
4919
pressed over it, and the relief is restored to its original
4920
value when button 1 is later released.
4923
If mouse button 1 is pressed over the radio button and later released over
4924
the radio button, the radio button is invoked (i.e. it is selected
4925
and the command associated with the button is invoked,
4926
if there is one). However, if the mouse is not
4927
over the radio button when button 1 is released, then no invocation occurs.
4930
The behavior of radio buttons can be changed by defining new bindings for
4931
individual widgets or by redefining the class bindings.
4933
@unnumberedsubsec Keywords
4934
radio button, widget
4935
@node toplevel, , radiobutton, Widgets
4939
toplevel \- Create and manipulate toplevel widgets
4940
@unnumberedsubsec Synopsis
4941
@b{toplevel}@i{ }@i{pathName }@r{?}@b{:screen }@i{screenName}@r{? ?}@b{:class }@i{className}@r{? ?}@i{options}?
4942
@unnumberedsubsec Standard Options
4951
@xref{options}, for more information.
4952
@unnumberedsubsec Arguments for Toplevel
4955
@unnumberedsubsec Description
4957
The @b{toplevel} command creates a new toplevel widget (given
4958
by the @i{pathName} argument). Additional
4959
options, described above, may be specified on the command line
4960
or in the option database
4961
to configure aspects of the toplevel such as its background color
4962
and relief. The @b{toplevel} command returns the
4963
path name of the new window.
4965
A toplevel is similar to a frame except that it is created as a
4966
top-level window: its X parent is the root window of a screen
4967
rather than the logical parent from its path name. The primary
4968
purpose of a toplevel is to serve as a container for dialog boxes
4969
and other collections of widgets. The only features
4970
of a toplevel are its background color and an optional 3-D border
4971
to make the toplevel appear raised or sunken.
4973
Two special command-line options may be provided to the @b{toplevel}
4974
command: @b{:class}@r{ and }@b{:screen}@r{. If }@b{:class}
4975
is specified, then the new widget's class will be set to
4976
@i{className}@r{ instead of }@b{Toplevel}. Changing the class of
4977
a toplevel widget may be useful
4978
in order to use a special class name in database options referring
4979
to this widget and its children. The @b{:screen} option
4980
may be used to place the window on a different screen than the
4981
window's logical parent. Any valid screen name may be used, even
4982
one associated with a different display.
4984
Note: @b{:class}@r{ and }@b{:screen} are handled
4985
differently than other command-line options. They may not be specified
4986
using the option database (these options must have been processed
4987
before the new window has been created enough to use the option database;
4988
in particular, the new class name will affect the lookup of options
4989
in the database). In addition, @b{:class}@r{ and }@b{:screen}
4990
may not be queried or changed using the @b{config} command described
4991
below. However, the @b{winfo :class} command may be used to query
4992
the class of a window, and @b{winfo :screen} may be used to query
4995
@unnumberedsubsec A Toplevel Widget's Arguments
4997
The @b{toplevel} command creates a new Tcl command whose
4998
name is the same as the path name of the toplevel's window. This
4999
command may be used to invoke various
5000
operations on the widget. It has the following general form:
5003
@i{pathName option }@r{?}@i{arg arg ...}?
5006
@i{PathName} is the name of the command, which is the same as
5007
the toplevel widget's path name. @i{Option}@r{ and the }@i{arg}s
5008
determine the exact behavior of the command. The following
5009
commands are possible for toplevel widgets:
5012
@item @i{pathName }@b{:configure}@r{ ?}@i{option}@r{? ?}@i{value option value ...}?
5013
Query or modify the configuration options of the widget.
5014
If no @i{option} is specified, returns a list describing all of
5015
the available options for @i{pathName}@r{ (see }@b{Tk_ConfigureInfo} for
5016
information on the format of this list). If @i{option} is specified
5017
with no @i{value}, then the command returns a list describing the
5018
one named option (this list will be identical to the corresponding
5019
sublist of the value returned if no @i{option} is specified). If
5020
one or more @i{option:value} pairs are specified, then the command
5021
modifies the given widget option(s) to have the given value(s); in
5022
this case the command returns an empty string.
5023
@i{Option}@r{ may have any of the values accepted by the }@b{toplevel}
5027
@unnumberedsubsec Bindings
5029
When a new toplevel is created, it has no default event bindings:
5030
toplevels are not intended to be interactive.
5032
@unnumberedsubsec Keywords
added
removed
info/widgets.texi
