Go to the first, previous, next, last section, table of contents.
button \- Create and manipulate button widgets
button pathName ?options?
activeBackground bitmap font relief
activeForeground borderWidth foreground text
anchor cursor padX textVariable
background disabledForeground padY
See section options, for more information.
:command
-
Name="command" Class="
Command"
Specifies a Tcl command to associate with the button. This command
is typically invoked when mouse button 1 is released over the button
window.
:height
-
Name="height" Class="
Height"
Specifies a desired height for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in lines of text.
If this option isn't specified, the button's desired height is computed
from the size of the bitmap or text being displayed in it.
:state
-
Name="state" Class="
State"
Specifies one of three states for the button: normal, active,
or disabled. In normal state the button is displayed using the
foreground and background options. The active state is
typically used when the pointer is over the button. In active state
the button is displayed using the activeForeground and
activeBackground options. Disabled state means that the button
is insensitive: it doesn't activate and doesn't respond to mouse
button presses. In this state the disabledForeground and
background options determine how the button is displayed.
:width
-
Name="width" Class="
Width"
Specifies a desired width for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in characters.
If this option isn't specified, the button's desired width is computed
from the size of the bitmap or text being displayed in it.
The button command creates a new window (given by the
pathName argument) and makes it into a button widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the button such as its colors, font,
text, and initial relief. The button command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A button is a widget
that displays a textual string or bitmap.
It can display itself in either of three different ways, according
to
the state option;
it can be made to appear raised, sunken, or flat;
and it can be made to flash. When a user invokes the
button (by pressing mouse button 1 with the cursor over the
button), then the Tcl command specified in the :command
option is invoked.
The button command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for button widgets:
- pathName :activate
-
Change the button's state to active and redisplay the button
using its active foreground and background colors instead of normal
colors.
This command is ignored if the button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state active" instead.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the button
command.
- pathName :deactivate
-
Change the button's state to normal and redisplay the button
using its normal foreground and background colors.
This command is ignored if the button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state normal" instead.
- pathName :flash
-
Flash the button. This is accomplished by redisplaying the button
several times, alternating between active and normal colors. At
the end of the flash the button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the button's state is disabled.
- pathName :invoke
-
Invoke the Tcl command associated with the button, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the button.
This command is ignored if the button's state is disabled.
Tk automatically creates class bindings for buttons that give them
the following default behavior:
-
[1]
The button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the button.
-
[2]
The button's relief is changed to sunken whenever mouse button 1 is
pressed over the button, and the relief is restored to its original
value when button 1 is later released.
-
[3]
If mouse button 1 is pressed over the button and later released over
the button, the button is invoked. However, if the mouse is not
over the button when button 1 is released, then no invocation occurs.
If the button's state is disabled then none of the above
actions occur: the button is completely non-responsive.
The behavior of buttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
button, widget
listbox \- Create and manipulate listbox widgets
listbox pathName ?options?
background foreground selectBackground xScrollCommand
borderWidth font selectBorderWidth yScrollCommand
cursor geometry selectForeground
exportSelection relief setGrid
See section options, for more information.
None.
The listbox command creates a new window (given by the
pathName argument) and makes it into a listbox widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the listbox such as its colors, font,
text, and relief. The listbox command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A listbox is a widget that displays a list of strings, one per line.
When first created, a new listbox has no elements in its list.
Elements may be added or deleted using widget commands described
below. In addition, one or more elements may be selected as described
below.
If a listbox is exporting its selection (see exportSelection
option), then it will observe the standard X11 protocols
for handling the selection; listbox selections are available
as type STRING, consisting of a Tcl list with one entry
for each selected element.
For large lists only a subset of the list elements will be
displayed in the listbox window at once; commands described below
may be used to change the view in the window. Listboxes allow
scrolling in both directions using the standard xScrollCommand
and yScrollCommand options.
They also support scanning, as described below.
The listbox command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for listbox widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the listbox
command.
- pathName :curselection
-
Returns a list containing the indices of
all of the elements in the listbox that are currently selected.
If there are no elements selected in the listbox then an empty
string is returned.
- pathName :delete first ?last?
-
Delete one or more elements of the listbox. First and last
give the integer indices of the first and last elements in the range
to be deleted. If last isn't specified it defaults to
first, i.e. a single element is deleted. An index of
0 corresponds to the first element in the listbox. Either
first or last may be specified as end, in which
case it refers to the last element of the listbox. This command
returns an empty string
- pathName :get index
-
Return the contents of the listbox element indicated by index.
Index must be a non-negative integer (0 corresponds to
the first element in the listbox), or it may also be specified as
end to indicate the last element in the listbox.
- pathName :insert index ?element element ...?
-
Insert zero or more new elements in the list just before the
element given by index. If index is specified as
end then the new elements are added to the end of the
list. Returns an empty string.
- pathName :nearest y
-
Given a y-coordinate within the listbox window, this command returns
the index of the (visible) listbox element nearest to that y-coordinate.
- pathName :scan option args
-
This command is used to implement scanning on listboxes. It has
two forms, depending on option:
- pathName :scan :mark x y
-
Records x and y and the current view in the listbox
window; used in conjunction with later scan dragto commands.
Typically this command is associated with a mouse button press in
the widget. It returns an empty string.
- pathName :scan :dragto x y.
-
This command computes the difference between its x and y
arguments and the x and y arguments to the last
scan mark command for the widget.
It then adjusts the view by 10 times the
difference in coordinates. This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the list at high speed through the window. The return
value is an empty string.
- pathName :select option arg
-
This command is used to adjust the selection within a listbox. It
has several forms, depending on option. In all of the forms
the index end refers to the last element in the listbox.
- pathName :select :adjust index
-
Locate the end of the selection nearest to the element given by
index, and adjust that end of the selection to be at index
(i.e including but not going beyond index). The other
end of the selection is made the anchor point for future
select to commands. If the selection
isn't currently in the listbox, then this command is identical to
the select from widget command.
Returns an empty string.
- pathName :select :clear
-
If the selection is in this listbox then it is cleared so that
none of the listbox's elements are selected anymore.
- pathName :select :from index
-
Set the selection to consist of element index, and make
index the anchor point for future select to widget
commands. Returns an empty string.
- pathName :select :to index
-
Set the selection to consist of the elements from the anchor
point to element index, inclusive. The anchor point is
determined by the most recent select from or select adjust
command in this widget. If the selection isn't in this widget,
this command is identical to select from.
Returns an empty string.
- pathName :size
-
Returns a decimal string indicating the total number of elements
in the listbox.
- pathName :xview index
-
Adjust the view in the listbox so that character position index
is displayed at the left edge of the widget.
Returns an empty string.
- pathName :yview index
-
Adjust the view in the listbox so that element index is
displayed at the top of the widget.
If index is specified as end it indicates the last
element of the listbox. Returns an empty string.
Tk automatically creates class bindings for listboxes that give them
the following default behavior:
-
[1]
When button 1 is pressed over a listbox, the element underneath the
mouse cursor is selected. The mouse can be dragged to select a
range of elements.
-
[2]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down; this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed.
-
[3]
The view in the listbox can be adjusted by dragging with mouse button 2.
The behavior of listboxes can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
In addition, the procedure tk_listboxSingleSelect may be
invoked to change listbox behavior so that only a single element
may be selected at once.
listbox, widget
scale \- Create and manipulate scale widgets
scale pathName ?options?
activeForeground borderWidth font orient
background cursor foreground relief
See section options, for more information.
:command
-
Name="command" Class="
Command"
Specifies the prefix of a Tcl command to invoke whenever the value of
the scale is changed interactively. The actual command consists
of this option followed by
a space and a number. The number indicates the new value of the
scale.
:from
-
Name="from" Class="
From"
Specifies the value corresponding to the left or top end of the
scale. Must be an integer.
:label
-
Name="label" Class="
Label"
Specifies a string to displayed as a label for the scale. For
vertical scales the label is displayed just to the right of the
top end of the scale. For horizontal scales the label is displayed
just above the left end of the scale.
:length
-
Name="length" Class="
Length"
Specifies the desired long dimension of the scale in screen units,
that is in any of the forms acceptable to Tk_GetPixels.
For vertical scales this is the scale's height; for horizontal scales
it is the scale's width.
:showvalue
-
Name="showValue" Class="
ShowValue"
Specifies a boolean value indicating whether or not the current
value of the scale is to be displayed.
:sliderforeground
-
Name="sliderForeground" Class="
sliderForeground"
Specifies the color to use for drawing the slider under normal conditions.
When the mouse is in the slider window then the slider's color is
determined by the activeForeground option.
:sliderlength
-
Name="sliderLength" Class="
SliderLength"
Specfies the size of the slider, measured in screen units along the slider's
long dimension. The value may be specified in any of the forms acceptable
to Tk_GetPixels.
:state
-
Name="state" Class="
State"
Specifies one of two states for the scale: normal or disabled.
If the scale is disabled then the value may not be changed and the scale
won't activate when the mouse enters it.
:tickinterval
-
Name="tickInterval" Class="
TickInterval"
Must be an integer value. Determines the spacing between numerical
tick-marks displayed below or to the left of the slider. If specified
as 0, then no tick-marks will be displayed.
:to
-
Name="to" Class="
To"
Specifies the value corresponding to the right or bottom end of the
scale. Must be an integer. This value may be either less than or
greater than the from option.
:width
-
Name="width" Class="
Width"
Specifies the desired narrow dimension of the scale in screen units
(i.e. any of the forms acceptable to Tk_GetPixels).
For vertical scales this is the scale's width; for horizontal scales
this is the scale's height.
The scale command creates a new window (given by the
pathName argument) and makes it into a scale widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the scale such as its colors, orientation,
and relief. The scale command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A scale is a widget that displays a rectangular region and a
small slider. The rectangular region corresponds to a range
of integer values (determined by the from and to options),
and the position of the slider selects a particular integer value.
The slider's position (and hence the scale's value) may be adjusted
by clicking or dragging with the mouse as described in the BINDINGS
section below. Whenever the scale's value is changed, a Tcl
command is invoked (using the command option) to notify
other interested widgets of the change.
Three annotations may be displayed in a scale widget: a label
appearing at the top-left of the widget (top-right for vertical
scales), a number displayed just underneath the slider
(just to the left of the slider for vertical scales), and a collection
of numerical tick-marks just underneath the current value (just to the left of
the current value for vertical scales). Each of these three
annotations may be selectively enabled or disabled using the
configuration options.
The scale command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for scale widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the scale
command.
- pathName :get
-
Returns a decimal string giving the current value of the scale.
- pathName :set value
-
This command is invoked to change the current value of the scale,
and hence the position at which the slider is displayed. Value
gives the new value for the scale.
When a new scale is created, it is given the following initial
behavior by default:
- <Enter>
-
Change the slider display to use activeForeground instead of
sliderForeground.
- <Leave>
-
Reset the slider display to use sliderForeground instead of
activeForeground.
- <ButtonPress-1>
-
Change the slider display so that the slider appears sunken rather
than raised. Move the slider (and adjust the scale's value)
to correspond to the current mouse position.
- <Button1-Motion>
-
Move the slider (and adjust the scale's value) to correspond to
the current mouse position.
- <ButtonRelease-1>
-
Reset the slider display so that the slider appears raised again.
scale, widget
canvas \- Create and manipulate canvas widgets
canvas pathName ?options?
background insertBorderWidth relief xScrollCommand
borderWidth insertOffTime selectBackground yScrollCommand
cursor insertOnTime selectBorderWidth
insertBackground insertWidth selectForeground
See section options, for more information.
:closeenough
-
Name="closeEnough" Class="
CloseEnough"
Specifies a floating-point value indicating how close the mouse cursor
must be to an item before it is considered to be "inside" the item.
Defaults to 1.0.
:confine
-
Name="confine" Class="
Confine"
Specifies a boolean value that indicates whether or not it should be
allowable to set the canvas's view outside the region defined by the
scrollRegion argument.
Defaults to true, which means that the view will
be constrained within the scroll region.
:height
-
Name="height" Class="
Height"
Specifies a desired window height that the canvas widget should request from
its geometry manager. The value may be specified in any
of the forms described in the COORDINATES section below.
:scrollincrement
-
Name="scrollIncrement" Class="
ScrollIncrement"
Specifies a distance used as increment during scrolling: when one of
the arrow buttons on an associated scrollbar is pressed, the picture
will shift by this distance. The distance may be specified in any
of the forms described in the COORDINATES section below.
:scrollregion
-
Name="scrollRegion" Class="
ScrollRegion"
Specifies a list with four coordinates describing the left, top, right, and
bottom coordinates of a rectangular region.
This region is used for scrolling purposes and is considered to be
the boundary of the information in the canvas.
Each of the coordinates may be specified
in any of the forms given in the COORDINATES section below.
:width
-
Name="width" Class="
width"
Specifies a desired window width that the canvas widget should request from
its geometry manager. The value may be specified in any
of the forms described in the COORDINATES section below.
The canvas command creates a new window (given
by the pathName argument) and makes it into a canvas widget.
Additional options, described above, may be specified on the
command line or in the option database
to configure aspects of the canvas such as its colors and 3-D relief.
The canvas command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
Canvas widgets implement structured graphics.
A canvas displays any number of items, which may be things like
rectangles, circles, lines, and text.
Items may be manipulated (e.g. moved or re-colored) and commands may
be associated with items in much the same way that the bind
command allows commands to be bound to widgets. For example,
a particular command may be associated with the <Button-1> event
so that the command is invoked whenever button 1 is pressed with
the mouse cursor over an item.
This means that items in a canvas can have behaviors defined by
the Tcl scripts bound to them.
The items in a canvas are ordered for purposes of display,
with the first item in the display list being displayed
first, followed by the next item in the list, and so on.
Items later in the display list obscure those that are
earlier in the display list and are sometimes referred to
as being "on top" of earlier items.
When a new item is created it is placed at the end of the
display list, on top of everything else.
Widget commands may be used to re-arrange the order of the
display list.
Items in a canvas widget may be named in either of two ways:
by id or by tag.
Each item has a unique identifying number which is assigned to
that item when it is created. The id of an item never changes
and id numbers are never re-used within the lifetime of a
canvas widget.
Each item may also have any number of tags associated
with it. A tag is just a string of characters, and it may
take any form except that of an integer.
For example, "x123" is OK but "123" isn't.
The same tag may be associated with many different items.
This is commonly done to group items in various interesting
ways; for example, all selected items might be given the
tag "selected".
The tag all is implicitly associated with every item
in the canvas; it may be used to invoke operations on
all the items in the canvas.
The tag current is managed automatically by Tk;
it applies to the current item, which is the
topmost item whose drawn area covers the position of
the mouse cursor.
If the mouse is not in the canvas widget or is not over
an item, then no item has the current tag.
When specifying items in canvas widget commands, if the
specifier is an integer then it is assumed to refer to
the single item with that id.
If the specifier is not an integer, then it is assumed to
refer to all of the items in the canvas that have a tag
matching the specifier.
The symbol tagOrId is used below to indicate that
an argument specifies either an id that selects a single
item or a tag that selects zero or more items.
Some widget commands only operate on a single item at a
time; if tagOrId is specified in a way that
names multiple items, then the normal behavior is for
the command to use the first (lowest) of these items in
the display list that is suitable for the command.
Exceptions are noted in the widget command descriptions
below.
All coordinates related to canvases are stored as floating-point
numbers.
Coordinates and distances are specified in screen units,
which are floating-point numbers optionally followed
by one of several letters.
If no letter is supplied then the distance is in pixels.
If the letter is m then the distance is in millimeters on
the screen; if it is c then the distance is in centimeters;
i means inches, and p means printers points (1/72 inch).
Larger y-coordinates refer to points lower on the screen; larger
x-coordinates refer to points farther to the right.
Normally the origin of the canvas coordinate system is at the
upper-left corner of the window containing the canvas.
It is possible to adjust the origin of the canvas
coordinate system relative to the origin of the window using the
xview and yview widget commands; this is typically used
for scrolling.
Canvases do not support scaling or rotation of the canvas coordinate
system relative to the window coordinate system.
Indidividual items may be moved or scaled using widget commands
described below, but they may not be rotated.
Text items support the notion of an index for identifying
particular positions within the item.
Indices are used for commands such as inserting text, deleting
a range of characters, and setting the insertion cursor position.
An index may be specified in any of a number of ways, and
different types of items may support different forms for
specifying indices.
Text items support the following forms for an index; if you
define new types of text-like items, it would be advisable to
support as many of these forms as practical.
Note that it is possible to refer to the character just after
the last one in the text item; this is necessary for such
tasks as inserting new text at the end of the item.
- number
-
A decimal number giving the position of the desired character
within the text item.
0 refers to the first character, 1 to the next character, and
so on.
A number less than 0 is treated as if it were zero, and a
number greater than the length of the text item is treated
as if it were equal to the length of the text item.
- end
-
Refers to the character just after the last one in the item
(same as the number of characters in the item).
- insert
-
Refers to the character just before which the insertion cursor
is drawn in this item.
- sel.first
-
Refers to the first selected character in the item.
If the selection isn't in this item then this form is illegal.
- sel.last
-
Refers to the last selected character in the item.
If the selection isn't in this item then this form is illegal.
- @x,y
-
Refers to the character at the point given by x and
y, where x and y are specified in the coordinate
system of the canvas.
If x and y lie outside the coordinates covered by the
text item, then they refer to the first or last character in the
line that is closest to the given point.
The canvas command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command.
The following widget commands are possible for canvas widgets:
- pathName :addtag tag searchSpec ?arg arg ...?
-
For each item that meets the constraints specified by
searchSpec and the args, add
tag to the list of tags associated with the item if it
isn't already present on that list.
It is possible that no items will satisfy the constraints
given by searchSpec and args, in which case the
command has no effect.
This command returns an empty string as result.
SearchSpec and arg's may take any of the following
forms:
- above tagOrId
-
Selects the item just after (above) the one given by tagOrId
in the display list.
If tagOrId denotes more than one item, then the last (topmost)
of these items in the display list is used.
- all
-
Selects all the items in the canvas.
- below tagOrId
-
Selects the item just before (below) the one given by tagOrId
in the display list.
If tagOrId denotes more than one item, then the first (lowest)
of these items in the display list is used.
- closest x y ?halo? ?start?
-
Selects the item closest to the point given by x and y.
If more than one item is at the same closest distance (e.g. two
items overlap the point), then the top-most of these items (the
last one in the display list) is used.
If halo is specified, then it must be a non-negative
value.
Any item closer than halo to the point is considered to
overlap it.
The start argument may be used to step circularly through
all the closest items.
If start is specified, it names an item using a tag or id
(if by tag, it selects the first item in the display list with
the given tag).
Instead of selecting the topmost closest item, this form will
select the topmost closest item that is below start in
the display list; if no such item exists, then the selection
behaves as if the start argument had not been specified.
- enclosed x1 y1 x2 y2
-
Selects all the items completely enclosed within the rectangular
region given by x1, y1, x2, and y2.
X1 must be no greater then x2 and y1 must be
no greater than y2.
- overlapping x1 y1 x2 y2
-
Selects all the items that overlap or are enclosed within the
rectangular region given by x1, y1, x2,
and y2.
X1 must be no greater then x2 and y1 must be
no greater than y2.
- withtag tagOrId
-
Selects all the items given by tagOrId.
- pathName :bbox tagOrId ?tagOrId tagOrId ...?
-
Returns a list with four elements giving an approximate bounding box
for all the items named by the tagOrId arguments.
The list has the form "x1 y1 x2 y2" such that the drawn
areas of all the named elements are within the region bounded by
x1 on the left, x2 on the right, y1 on the top,
and y2 on the bottom.
The return value may overestimate the actual bounding box by
a few pixels.
If no items match any of the tagOrId arguments then an
empty string is returned.
- pathName :bind tagOrId ?sequence? ?command?
-
This command associates command with all the items given by
tagOrId such that whenever the event sequence given by
sequence occurs for one of the items the command will
be invoked.
This widget command is similar to the bind command except that
it operates on items in a canvas rather than entire widgets.
See the bind manual entry for complete details
on the syntax of sequence and the substitutions performed
on command before invoking it.
If all arguments are specified then a new binding is created, replacing
any existing binding for the same sequence and tagOrId
(if the first character of command is "+" then command
augments an existing binding rather than replacing it).
In this case the return value is an empty string.
If command is omitted then the command returns the command
associated with tagOrId and sequence (an error occurs
if there is no such binding).
If both command and sequence are omitted then the command
returns a list of all the sequences for which bindings have been
defined for tagOrId.
The only events for which bindings may be specified are those related
to the mouse and keyboard, such as Enter, Leave,
ButtonPress, Motion, and KeyPress.
The handling of events in canvases uses the current item defined
in ITEM IDS AND TAGS above.
Enter and Leave events trigger for an item when it
becomes the current item or ceases to be the current item; note
that these events are different than Enter and Leave
events for windows.
Mouse-related events are directed to the current item, if any.
Keyboard-related events are directed to the focus item, if any
(see the focus widget command below for more on this).
It is possible for multiple commands to be bound to a single
event sequence for a single object.
This occurs, for example, if one command is associated with the
item's id and another is associated with one of the item's tags.
When this occurs, the first matching binding is used.
A binding for the item's id has highest priority, followed by
the oldest tag for the item and proceeding through all of the
item's tags up through the most-recently-added one.
If a binding is associated with the tag all, the binding
will have lower priority than all other bindings associated
with the item.
- pathName :canvasx screenx ?gridspacing?
-
Given a screen x-coordinate screenx this command returns
the canvas x-coordinate that is displayed at that location.
If gridspacing is specified, then the canvas coordinate is
rounded to the nearest multiple of gridspacing units.
- pathName :canvasy screeny ?gridspacing?
-
Given a screen y-coordinate screeny this command returns
the canvas y-coordinate that is displayed at that location.
If gridspacing is specified, then the canvas coordinate is
rounded to the nearest multiple of gridspacing units.
- pathName :configure ?option? ?value? ?option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the canvas
command.
- pathName :coords tagOrId ?x0 y0 ...?
-
Query or modify the coordinates that define an item.
If no coordinates are specified, this command returns a list
whose elements are the coordinates of the item named by
tagOrId.
If coordinates are specified, then they replace the current
coordinates for the named item.
If tagOrId refers to multiple items, then
the first one in the display list is used.
- pathName :create type x y ?x y ...? ?option value ...?
-
Create a new item in pathName of type type.
The exact format of the arguments after type depends
on type, but usually they consist of the coordinates for
one or more points, followed by specifications for zero or
more item options.
See the subsections on individual item types below for more
on the syntax of this command.
This command returns the id for the new item.
- pathName :dchars tagOrId first ?last?
-
For each item given by tagOrId, delete the characters
in the range given by first and last,
inclusive.
If some of the items given by tagOrId don't support
text operations, then they are ignored.
First and last are indices of characters
within the item(s) as described in INDICES above.
If last is omitted, it defaults to first.
This command returns an empty string.
- pathName :delete ?tagOrId tagOrId ...?
-
Delete each of the items given by each tagOrId, and return
an empty string.
- pathName :dtag tagOrId ?tagToDelete?
-
For each of the items given by tagOrId, delete the
tag given by tagToDelete from the list of those
associated with the item.
If an item doesn't have the tag tagToDelete then
the item is unaffected by the command.
If tagToDelete is omitted then it defaults to tagOrId.
This command returns an empty string.
- pathName :find searchCommand ?arg arg ...?
-
This command returns a list consisting of all the items that
meet the constraints specified by searchCommand and
arg's.
SearchCommand and args have any of the forms
accepted by the addtag command.
- pathName :focus ?tagOrId?
-
Set the keyboard focus for the canvas widget to the item given by
tagOrId.
If tagOrId refers to several items, then the focus is set
to the first such item in the display list that supports the
insertion cursor.
If tagOrId doesn't refer to any items, or if none of them
support the insertion cursor, then the focus isn't changed.
If tagOrId is an empty
string, then the focus item is reset so that no item has the focus.
If tagOrId is not specified then the command returns the
id for the item that currently has the focus, or an empty string
if no item has the focus.
Once the focus has been set to an item, the item will display
the insertion cursor and all keyboard events will be directed
to that item.
The focus item within a canvas and the focus window on the
screen (set with the focus command) are totally independent:
a given item doesn't actually have the input focus unless (a)
its canvas is the focus window and (b) the item is the focus item
within the canvas.
In most cases it is advisable to follow the focus widget
command with the focus command to set the focus window to
the canvas (if it wasn't there already).
- pathName :gettags tagOrId
-
Return a list whose elements are the tags associated with the
item given by tagOrId.
If tagOrId refers to more than one item, then the tags
are returned from the first such item in the display list.
If tagOrId doesn't refer to any items, or if the item
contains no tags, then an empty string is returned.
- pathName :icursor tagOrId index
-
Set the position of the insertion cursor for the item(s)
given by tagOrId
to just before the character whose position is given by index.
If some or all of the items given by tagOrId don't support
an insertion cursor then this command has no effect on them.
See INDICES above for a description of the
legal forms for index.
Note: the insertion cursor is only displayed in an item if
that item currently has the keyboard focus (see the widget
command focus, below), but the cursor position may
be set even when the item doesn't have the focus.
This command returns an empty string.
- pathName :index tagOrId index
-
This command returns a decimal string giving the numerical index
within tagOrId corresponding to index.
Index gives a textual description of the desired position
as described in INDICES above.
The return value is guaranteed to lie between 0 and the number
of characters within the item, inclusive.
If tagOrId refers to multiple items, then the index
is processed in the first of these items that supports indexing
operations (in display list order).
- pathName :insert tagOrId beforeThis string
-
For each of the items given by tagOrId, if the item supports
text insertion then string is inserted into the item's
text just before the character whose index is beforeThis.
See INDICES above for information about the forms allowed
for beforeThis.
This command returns an empty string.
- pathName :itemconfigure tagOrId ?option? ?value? ?option value ...?
-
This command is similar to the configure widget command except
that it modifies item-specific options for the items given by
tagOrId instead of modifying options for the overall
canvas widget.
If no option is specified, returns a list describing all of
the available options for the first item given by tagOrId
(see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s) in
each of the items given by tagOrId; in
this case the command returns an empty string.
The options and values are the same as those permissible
in the create widget command when the item(s) were created;
see the sections describing individual item types below for details
on the legal options.
- pathName :lower tagOrId ?belowThis?
-
Move all of the items given by tagOrId to a new position
in the display list just before the item given by belowThis.
If tagOrId refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
BelowThis is a tag or id; if it refers to more than one
item then the first (lowest) of these items in the display list is used
as the destination location for the moved items.
This command returns an empty string.
- pathName :move tagOrId xAmount yAmount
-
Move each of the items given by tagOrId in the canvas coordinate
space by adding xAmount to the x-coordinate of each point
associated with the item and yAmount to the y-coordinate of
each point associated with the item.
This command returns an empty string.
- pathName :postscript ?option value option value ...?
-
Generate a Postscript representation for part or all of the canvas.
If the :file option is specified then the Postscript is written
to a file and an empty string is returned; otherwise the Postscript
is returned as the result of the command.
The Postscript is created in Encapsulated Postscript form using
version 3.0 of the Document Structuring Conventions.
The option\-value argument pairs provide additional
information to control the generation of Postscript. The following
options are supported:
- :colormap varName
-
VarName must be the name of a global array variable
that specifies a color mapping to use in the Postscript.
Each element of varName must consist of Postscript
code to set a particular color value (e.g. "1.0 1.0 0.0 setrgbcolor").
When outputting color information in the Postscript, Tk checks
to see if there is an element of varName with the same
name as the color.
If so, Tk uses the value of the element as the Postscript command
to set the color.
If this option hasn't been specified, or if there isn't an entry
in varName for a given color, then Tk uses the red, green,
and blue intensities from the X color.
- :colormode mode
-
Specifies how to output color information. Mode must be either
color (for full color output), gray (convert all colors
to their gray-scale equivalents) or mono (convert all colors
to black or white).
- :file fileName
-
Specifies the name of the file in which to write the Postscript.
If this option isn't specified then the Postscript is returned as the
result of the command instead of being written to a file.
- :fontmap varName
-
VarName must be the name of a global array variable
that specifies a font mapping to use in the Postscript.
Each element of varName must consist of a Tcl list with
two elements, which are the name and point size of a Postscript font.
When outputting Postscript commands for a particular font, Tk
checks to see if varName contains an element with the same
name as the font.
If there is such an element, then the font information contained in
that element is used in the Postscript.
Otherwise Tk attempts to guess what Postscript font to use.
Tk's guesses generally only work for well-known fonts such as
Times and Helvetica and Courier, and only if the X font name does not
omit any dashes up through the point size.
For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-* will work but
\fB*Courier\-Bold\-R\-Normal*120* will not; Tk needs the dashes to
parse the font name).
- :height size
-
Specifies the height of the area of the canvas to print.
Defaults to the height of the canvas window.
- :pageanchor anchor
-
Specifies which point of the printed area should be appear over
the positioning point on the page (which is given by the :pagex
and :pagey options).
For example, :pageanchor n means that the top center of the
printed area should be over the positioning point.
Defaults to center.
- :pageheight size
-
Specifies that the Postscript should be scaled in both x and y so
that the printed area is size high on the Postscript page.
Size consists of a floating-point number followed by
c for centimeters, i for inches, m for millimeters,
or p or nothing for printer's points (1/72 inch).
Defaults to the height of the printed area on the screen.
If both :pageheight and :pagewidth are specified then
the scale factor from the later option is used (non-uniform scaling
is not implemented).
- :pagewidth size
-
Specifies that the Postscript should be scaled in both x and y so
that the printed area is size wide on the Postscript page.
Size has the same form as for :pageheight.
Defaults to the width of the printed area on the screen.
If both :pageheight and :pagewidth are specified then
the scale factor from the later option is used (non-uniform scaling
is not implemented).
- :pagex position
-
Position gives the x-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for :pageheight.
Used in conjunction with the :pagey and :pageanchor options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.
- :pagey position
-
Position gives the y-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for :pageheight.
Used in conjunction with the :pagex and :pageanchor options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.
- :rotate boolean
-
Boolean specifies whether the printed area is to be rotated 90
degrees.
In non-rotated output the x-axis of the printed area runs along
the short dimension of the page ("portrait" orientation);
in rotated output the x-axis runs along the long dimension of the
page ("landscape" orientation).
Defaults to non-rotated.
- :width size
-
Specifies the width of the area of the canvas to print.
Defaults to the width of the canvas window.
- :x position
-
Specifies the x-coordinate of the left edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the left edge of the window.
- :y position
-
Specifies the y-coordinate of the top edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the top edge of the window.
- pathName :raise tagOrId ?aboveThis?
-
Move all of the items given by tagOrId to a new position
in the display list just after the item given by aboveThis.
If tagOrId refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
AboveThis is a tag or id; if it refers to more than one
item then the last (topmost) of these items in the display list is used
as the destination location for the moved items.
This command returns an empty string.
- pathName :scale tagOrId xOrigin yOrigin xScale yScale
-
Rescale all of the items given by tagOrId in canvas coordinate
space.
XOrigin and yOrigin identify the origin for the scaling
operation and xScale and yScale identify the scale
factors for x- and y-coordinates, respectively (a scale factor of
1.0 implies no change to that coordinate).
For each of the points defining each item, the x-coordinate is
adjusted to change the distance from xOrigin by a factor
of xScale.
Similarly, each y-coordinate is adjusted to change the distance
from yOrigin by a factor of yScale.
This command returns an empty string.
- pathName :scan option args
-
This command is used to implement scanning on canvases. It has
two forms, depending on option:
- pathName :scan :mark x y
-
Records x and y and the canvas's current view; used
in conjunction with later scan dragto commands.
Typically this command is associated with a mouse button press in
the widget and x and y are the coordinates of the
mouse. It returns an empty string.
- pathName :scan :dragto x y.
-
This command computes the difference between its x and y
arguments (which are typically mouse coordinates) and the x and
y arguments to the last scan mark command for the widget.
It then adjusts the view by 10 times the
difference in coordinates. This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the canvas at high speed through its window. The return
value is an empty string.
- pathName :select option ?tagOrId arg?
-
Manipulates the selection in one of several ways, depending on
option.
The command may take any of the forms described below.
In all of the descriptions below, tagOrId must refer to
an item that supports indexing and selection; if it refers to
multiple items then the first of
these that supports indexing and the selection is used.
Index gives a textual description of a position
within tagOrId, as described in INDICES above.
- pathName :select :adjust tagOrId index
-
Locate the end of the selection in tagOrId nearest
to the character given by index, and adjust that
end of the selection to be at index (i.e. including
but not going beyond index).
The other end of the selection is made the anchor point
for future select to commands.
If the selection isn't currently in tagOrId then
this command behaves the same as the select to widget
command.
Returns an empty string.
- pathName :select :clear
-
Clear the selection if it is in this widget.
If the selection isn't in this widget then the command
has no effect.
Returns an empty string.
- pathName :select :from tagOrId index
-
Set the selection anchor point for the widget to be just
before the character
given by index in the item given by tagOrId.
This command doesn't change the selection; it just sets
the fixed end of the selection for future select to
commands.
Returns an empty string.
- pathName :select :item
-
Returns the id of the selected item, if the selection is in an
item in this canvas.
If the selection is not in this canvas then an empty string
is returned.
- pathName :select :to tagOrId index
-
Set the selection to consist of those characters of tagOrId
between the selection anchor point and
index.
The new selection will include the character given by index;
it will include the character given by the anchor point only if
index is greater than or equal to the anchor point.
The anchor point is determined by the most recent select adjust
or select from command for this widget.
If the selection anchor point for the widget isn't currently in
tagOrId, then it is set to the same character given
by index.
Returns an empty string.
- pathName :type tagOrId
-
Returns the type of the item given by tagOrId, such as
rectangle or text.
If tagOrId refers to more than one item, then the type
of the first item in the display list is returned.
If tagOrId doesn't refer to any items at all then
an empty string is returned.
- pathName :xview index
-
Change the view in the canvas so that the canvas position given by
index appears at the left edge of the window.
This command is typically used by scrollbars to scroll the
canvas.
Index counts in units of scroll increments (the value of the
scrollIncrement option): a value of 0 corresponds to the left
edge of the scroll region (as defined by the scrollRegion
option), a value of 1 means one scroll unit to the right of this,
and so on. The return value is an empty string.
- pathName :yview index
-
Change the view in the canvas so that the canvas position given by
index appears at the top edge of the window.
This command is typically used by scrollbars to scroll the
canvas.
Index counts in units of scroll increments (the value of the
scrollIncrement option): a value of 0 corresponds to the top
edge of the scroll region (as defined by the scrollRegion
option), a value of 1 means one scroll unit below this,
and so on. The return value is an empty string.
The sections below describe the various types of items supported
by canvas widgets. Each item type is characterized by two things:
first, the form of the create command used to create
instances of the type; and second, a set of configuration options
for items of that type, which may be used in the
create and itemconfigure widget commands.
Most items don't support indexing or selection or the commands
related to them, such as index and insert.
Where items do support these facilities, it is noted explicitly
in the descriptions below (at present, only text items provide
this support).
Items of type arc appear on the display as arc-shaped regions.
An arc is a section of an oval delimited by two angles (specified
by the :start and :extent options) and displayed in
one of several ways (specified by the :style option).
Arcs are created with widget commands of the following form:
- pathName :create arc x1 y1 x2 y2 ?option value option value ...?
-
The arguments x1, y1, x2, and y2 give
the coordinates of two diagonally opposite corners of a
rectangular region enclosing the oval that defines the arc.
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for arcs:
- :extent degrees
-
Specifies the size of the angular range occupied by the arc.
The arc's range extends for degrees degrees counter-clockwise
from the starting angle given by the :start option.
Degrees may be negative.
- :fill color
-
Fill the region of the arc with color.
Color may have any of the forms accepted by Tk_GetColor.
If color is an empty string (the default), then
then the arc will not be filled.
- :outline color
-
Color specifies a color to use for drawing the arc's
outline; it may have any of the forms accepted by Tk_GetColor.
This option defaults to black. If the arc's style is
arc then this option is ignored (the section of perimeter is
filled using the :fill option). If color is specified
as an empty string then no outline is drawn for the arc.
- :start degrees
-
Specifies the beginning of the angular range occupied by the
arc.
Degrees is given in units of degrees measured counter-clockwise
from the 3-o'clock position; it may be either positive or negative.
- :stipple bitmap
-
Indicates that the arc should be filled in a stipple pattern;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If the :fill option hasn't been specified then this option
has no effect.
If bitmap is an empty string (the default), then filling is done
in a solid fashion.
- :style type
-
Specifies how to draw the arc. If type is pieslice
(the default) then the arc's region is defined by a section
of the oval's perimeter plus two line segments, one between the center
of the oval and each end of the perimeter section.
If type is chord then the arc's region is defined
by a section of the oval's perimeter plus a single line segment
connecting the two end points of the perimeter section.
If type is arc then the arc's region consists of
a section of the perimeter alone. In this last case there is
no outline for the arc and the :outline option is ignored.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :width outlineWidth
-
Specifies the width of the outline to be drawn around
the arc's region, in any of the forms described in the COORDINATES
section above.
If the :outline option has been specified as an empty string
then this option has no effect.
Wide outlines will be drawn centered on the edges of the arc's region.
This option defaults to 1.0.
Items of type bitmap appear on the display as images with
two colors, foreground and background.
Bitmaps are created with widget commands of the following form:
- pathName :create bitmap x y ?option value option value ...?
-
The arguments x and y specify the coordinates of a
point used to position the bitmap on the display (see the :anchor
option below for more information on how bitmaps are displayed).
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for bitmaps:
- :anchor anchorPos
-
AnchorPos tells how to position the bitmap relative to the
positioning point for the item; it may have any of the forms
accepted by Tk_GetAnchor. For example, if anchorPos
is center then the bitmap is centered on the point; if
anchorPos is n then the bitmap will be drawn so that
its top center point is at the positioning point.
This option defaults to center.
- :background color
-
Specifies a color to use for each of the bitmap pixels
whose value is 0.
Color may have any of the forms accepted by Tk_GetColor.
If this option isn't specified, or if it is specified as an empty
string, then the background color for the canvas is used.
- :bitmap bitmap
-
Specifies the bitmap to display in the item.
Bitmap may have any of the forms accepted by Tk_GetBitmap.
- :foreground color
-
Specifies a color to use for each of the bitmap pixels
whose value is 1.
Color may have any of the forms accepted by Tk_GetColor and
defaults to black.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
Items of type line appear on the display as one or more connected
line segments or curves.
Lines are created with widget commands of the following form:
- pathName :create line x1 y1... xn yn ?option value option value ...?
-
The arguments x1 through yn give
the coordinates for a series of two or more points that describe
a series of connected line segments.
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for lines:
- :arrow where
-
Indicates whether or not arrowheads are to be drawn at one or both
ends of the line.
Where must have one of the values none (for no arrowheads),
first (for an arrowhead at the first point of the line),
last (for an arrowhead at the last point of the line), or
both (for arrowheads at both ends).
This option defaults to none.
- :arrowshape shape
-
This option indicates how to draw arrowheads.
The shape argument must be a list with three elements, each
specifying a distance in any of the forms described in
the COORDINATES section above.
The first element of the list gives the distance along the line
from the neck of the arrowhead to its tip.
The second element gives the distance along the line from the
trailing points of the arrowhead to the tip, and the third
element gives the distance from the outside edge of the line to the
trailing points.
If this option isn't specified then Tk picks a "reasonable" shape.
- :capstyle style
-
Specifies the ways in which caps are to be drawn at the endpoints
of the line.
Style may have any of the forms accepted by Tk_GetCapStyle
(butt, projecting, or round).
If this option isn't specified then it defaults to butt.
Where arrowheads are drawn the cap style is ignored.
- :fill color
-
Color specifies a color to use for drawing the line; it may have
any of the forms acceptable to Tk_GetColor. It may also be an
empty string, in which case the line will be transparent.
This option defaults to black.
- :joinstyle style
-
Specifies the ways in which joints are to be drawn at the vertices
of the line.
Style may have any of the forms accepted by Tk_GetCapStyle
(bevel, miter, or round).
If this option isn't specified then it defaults to miter.
If the line only contains two points then this option is
irrelevant.
- :smooth boolean
-
Boolean must have one of the forms accepted by Tk_GetBoolean.
It indicates whether or not the line should be drawn as a curve.
If so, the line is rendered as a set of Bezier splines: one spline
is drawn for the first and second line segments, one for the second
and third, and so on. Straight-line segments can be generated within
a curve by duplicating the end-points of the desired line segment.
- :splinesteps number
-
Specifies the degree of smoothness desired for curves: each spline
will be approximated with number line segments. This
option is ignored unless the :smooth option is true.
- :stipple bitmap
-
Indicates that the line should be filled in a stipple pattern;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If bitmap is an empty string (the default), then filling is
done in a solid fashion.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :width lineWidth
-
LineWidth specifies the width of the line, in any of the forms
described in the COORDINATES section above.
Wide lines will be drawn centered on the path specified by the
points.
If this option isn't specified then it defaults to 1.0.
Items of type oval appear as circular or oval regions on
the display. Each oval may have an outline, a fill, or
both. Ovals are created with widget commands of the
following form:
- pathName :create oval x1 y1 x2 y2 ?option value option value ...?
-
The arguments x1, y1, x2, and y2 give
the coordinates of two diagonally opposite corners of a
rectangular region enclosing the oval.
The oval will include the top and left edges of the rectangle
not the lower or right edges.
If the region is square then the resulting oval is circular;
otherwise it is elongated in shape.
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for ovals:
- :fill color
-
Fill the area of the oval with color.
Color may have any of the forms accepted by Tk_GetColor.
If color is an empty string (the default), then
then the oval will not be filled.
- :outline color
-
Color specifies a color to use for drawing the oval's
outline; it may have any of the forms accepted by Tk_GetColor.
This option defaults to black.
If color is an empty string then no outline will be
drawn for the oval.
- :stipple bitmap
-
Indicates that the oval should be filled in a stipple pattern;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If the :fill option hasn't been specified then this option
has no effect.
If bitmap is an empty string (the default), then filling is done
in a solid fashion.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :width outlineWidth
-
outlineWidth specifies the width of the outline to be drawn around
the oval, in any of the forms described in the COORDINATES section above.
If the :outline option hasn't been specified then this option
has no effect.
Wide outlines are drawn centered on the oval path defined by
x1, y1, x2, and y2.
This option defaults to 1.0.
Items of type polygon appear as polygonal or curved filled regions
on the display.
Polygons are created with widget commands of the following form:
- pathName :create polygon x1 y1 ... xn yn ?option value option value ...?
-
The arguments x1 through yn specify the coordinates for
three or more points that define a closed polygon.
The first and last points may be the same; whether they are or not,
Tk will draw the polygon as a closed polygon.
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for polygons:
- :fill color
-
Color specifies a color to use for filling the area of the
polygon; it may have any of the forms acceptable to Tk_GetColor.
If color is an empty string then the polygon will be
transparent.
This option defaults to black.
- :smooth boolean
-
Boolean must have one of the forms accepted by Tk_GetBoolean
It indicates whether or not the polygon should be drawn with a
curved perimeter.
If so, the outline of the polygon becomes a set of Bezier splines,
one spline for the first and second line segments, one for the second
and third, and so on. Straight-line segments can be generated in a
smoothed polygon by duplicating the end-points of the desired line segment.
- :splinesteps number
-
Specifies the degree of smoothness desired for curves: each spline
will be approximated with number line segments. This
option is ignored unless the :smooth option is true.
- :stipple bitmap
-
Indicates that the polygon should be filled in a stipple pattern;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If bitmap is an empty string (the default), then filling is
done in a solid fashion.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
Items of type rectangle appear as rectangular regions on
the display. Each rectangle may have an outline, a fill, or
both. Rectangles are created with widget commands of the
following form:
- pathName :create rectangle x1 y1 x2 y2 ?option value option value ...?
-
The arguments x1, y1, x2, and y2 give
the coordinates of two diagonally opposite corners of the rectangle
(the rectangle will include its upper and left edges but not
its lower or right edges).
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for rectangles:
- :fill color
-
Fill the area of the rectangle with color, which may be
specified in any of the forms accepted by Tk_GetColor.
If color is an empty string (the default), then
then the rectangle will not be filled.
- :outline color
-
Draw an outline around the edge of the rectangle in color.
Color may have any of the forms accepted by Tk_GetColor.
This option defaults to black.
If color is an empty string then no outline will be
drawn for the rectangle.
- :stipple bitmap
-
Indicates that the rectangle should be filled in a stipple pattern;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If the :fill option hasn't been specified then this option
has no effect.
If bitmap is an empty string (the default), then filling
is done in a solid fashion.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :width outlineWidth
-
OutlineWidth specifies the width of the outline to be drawn around
the rectangle, in any of the forms described in the COORDINATES section above.
If the :outline option hasn't been specified then this option
has no effect.
Wide outlines are drawn centered on the rectangular path
defined by x1, y1, x2, and y2.
This option defaults to 1.0.
A text item displays a string of characters on the screen in one
or more lines.
Text items support indexing and selection, along with the
following text-related canvas widget commands: dchars,
focus, icursor, index, insert,
select.
Text items are created with widget commands of the following
form:
- pathName :create text x y ?option value option value ...?
-
The arguments x and y specify the coordinates of a
point used to position the text on the display (see the options
below for more information on how text is displayed).
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for text items:
- :anchor anchorPos
-
AnchorPos tells how to position the text relative to the
positioning point for the text; it may have any of the forms
accepted by Tk_GetAnchor. For example, if anchorPos
is center then the text is centered on the point; if
anchorPos is n then the text will be drawn such that
the top center point of the rectangular region occupied by the
text will be at the positioning point.
This option defaults to center.
- :fill color
-
Color specifies a color to use for filling the text characters;
it may have any of the forms accepted by Tk_GetColor.
If this option isn't specified then it defaults to black.
- :font fontName
-
Specifies the font to use for the text item.
FontName may be any string acceptable to Tk_GetFontStruct.
If this option isn't specified, it defaults to a system-dependent
font.
- :justify how
-
Specifies how to justify the text within its bounding region.
How must be one of the values left, right,
or center.
This option will only matter if the text is displayed as multiple
lines.
If the option is omitted, it defaults to left.
- :stipple bitmap
-
Indicates that the text should be drawn in a stippled pattern
rather than solid;
bitmap specifies the stipple pattern to use, in any of the
forms accepted by Tk_GetBitmap.
If bitmap is an empty string (the default) then the text
is drawn in a solid fashion.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :text string
-
String specifies the characters to be displayed in the text item.
Newline characters cause line breaks.
The characters in the item may also be changed with the
insert and delete widget commands.
This option defaults to an empty string.
- :width lineLength
-
Specifies a maximum line length for the text, in any of the forms
described in the COORDINATES section abov.
If this option is zero (the default) the text is broken into
lines only at newline characters.
However, if this option is non-zero then any line that would
be longer than lineLength is broken just before a space
character to make the line shorter than lineLength; the
space character is treated as if it were a newline
character.
Items of type window cause a particular window to be displayed
at a given position on the canvas.
Window items are created with widget commands of the following form:
pathName :create window x y ?option value option value ...?
The arguments x and y specify the coordinates of a
point used to position the window on the display (see the :anchor
option below for more information on how bitmaps are displayed).
After the coordinates there may be any number of option-value
pairs, each of which sets one of the configuration options
for the item. These same option\-value pairs may be
used in itemconfigure widget commands to change the item's
configuration.
The following options are supported for window items:
- :anchor anchorPos
-
AnchorPos tells how to position the window relative to the
positioning point for the item; it may have any of the forms
accepted by Tk_GetAnchor. For example, if anchorPos
is center then the window is centered on the point; if
anchorPos is n then the window will be drawn so that
its top center point is at the positioning point.
This option defaults to center.
- :height pixels
-
Specifies the height to assign to the item's window.
Pixels may have any of the
forms described in the COORDINATES section above.
If this option isn't specified, or if it is specified as an empty
string, then the window is given whatever height it requests internally.
- :tags tagList
-
Specifies a set of tags to apply to the item.
TagList consists of a list of tag names, which replace any
existing tags for the item.
TagList may be an empty list.
- :width pixels
-
Specifies the width to assign to the item's window.
Pixels may have any of the
forms described in the COORDINATES section above.
If this option isn't specified, or if it is specified as an empty
string, then the window is given whatever width it requests internally.
- :window pathName
-
Specifies the window to associate with this item.
The window specified by pathName must either be a child of
the canvas widget or a child of some ancestor of the canvas widget.
PathName may not refer to a top-level window.
It is possible for individual applications to define new item
types for canvas widgets using C code.
The interfaces for this mechanism are not presently documented,
and it's possible they may change, but you should be able to
see how they work by examining the code for some of the existing
item types.
In the current implementation, new canvases are not given any
default behavior: you'll have to execute explicit Tcl commands
to give the canvas its behavior.
Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
ezd program. Ezd provides structured graphics in a Scheme
environment and preceded canvases by a year or two. Its simple
mechanisms for placing and animating graphical objects inspired the
functions of canvases.
canvas, widget
menu \- Create and manipulate menu widgets
menu pathName ?options?
activeBackground background disabledForeground
activeBorderWidth borderWidth font
activeForeground cursor foreground
See section options, for more information.
:postcommand
-
Name="postCommand" Class="
Command"
If this option is specified then it provides a Tcl command to execute
each time the menu is posted. The command is invoked by the post
widget command before posting the menu.
:selector
-
Name="selector" Class="
Foreground"
For menu entries that are check buttons or radio buttons, this option
specifies the color to display in the selector when the check button
or radio button is selected.
The menu command creates a new top-level window (given
by the pathName argument) and makes it into a menu widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the menu such as its colors and font.
The menu command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A menu is a widget that displays a collection of one-line entries arranged
in a column. There exist several different types of entries,
each with different properties. Entries of different types may be
combined in a single menu. Menu entries are not the same as
entry widgets. In fact, menu entries are not even distinct widgets;
the entire menu is one widget.
Menu entries are displayed with up to three
separate fields. The main field is a label in the form of text or
a bitmap, which is determined by the :label or :bitmap
option for the entry.
If the :accelerator option is specified for an entry then a second
textual field is displayed to the right of the label. The accelerator
typically describes a keystroke sequence that may be typed in the
application to cause the same result as invoking the menu entry.
The third field is a selector. The selector is present only for
check-button or radio-button entries. It indicates whether the entry
is selected or not, and is displayed to the left of the entry's
string.
In normal use, an entry becomes active (displays itself differently)
whenever the mouse pointer is over the entry. If a mouse
button is released over the entry then the entry is invoked.
The effect of invocation is different for each type of entry;
these effects are described below in the sections on individual
entries.
Entries may be disabled, which causes their labels
and accelerators to be displayed
with dimmer colors. A disabled entry cannot be activated or invoked.
Disabled entries may be re-enabled, at which point it becomes
possible to activate and invoke them again.
The most common kind of menu entry is a command entry, which
behaves much like a button widget. When a command entry is
invoked, a Tcl command is executed. The Tcl
command is specified with the :command option.
A separator is an entry that is displayed as a horizontal dividing
line. A separator may not be activated or invoked, and it has
no behavior other than its display appearance.
A check-button menu entry behaves much like a check-button widget.
When it is invoked it toggles back and forth between the selected
and deselected states. When the entry is selected, a particular
value is stored in a particular global variable (as determined by
the :onvalue and :variable options for the entry); when
the entry is deselected another value (determined by the
:offvalue option) is stored in the global variable.
A selector box is displayed to the left of the label in a check-button
entry. If the entry is selected then the box's center is displayed
in the color given by the selector option for the menu;
otherwise the box's center is displayed in the background color for
the menu. If a :command option is specified for a check-button
entry, then its value is evaluated as a Tcl command each time the entry
is invoked; this happens after toggling the entry's
selected state.
A radio-button menu entry behaves much like a radio-button widget.
Radio-button entries are organized in groups of which only one
entry may be selected at a time. Whenever a particular entry
becomes selected it stores a particular value into a particular
global variable (as determined by the :value and
:variable options for the entry). This action
causes any previously-selected entry in the same group
to deselect itself.
Once an entry has become selected, any change to the entry's
associated variable will cause the entry to deselect itself.
Grouping of radio-button entries is determined by their
associated variables: if two entries have the same associated
variable then they are in the same group.
A selector diamond is displayed to the left of the label in each
radio-button entry. If the entry is selected then the diamond's
center is displayed in the color given by the selector option
for the menu;
otherwise the diamond's center is displayed in the background color for
the menu. If a :command option is specified for a radio-button
entry, then its value is evaluated as a Tcl command each time the entry
is invoked; this happens after selecting the entry.
A cascade entry is one with an associated menu (determined
by the :menu option). Cascade entries allow the construction
of cascading menus. When the entry is activated, the
associated menu is posted just to the right of the entry;
that menu remains posted until the higher-level menu is unposted or
until some other entry is activated in the higher-level menu.
The associated menu should normally be a child of the menu containing
the cascade entry, in order for menu traversal to work correctly.
A cascade entry posts its associated menu by invoking a
Tcl command of the form
- menu :post x y
-
where menu is the path name of the associated menu, x
and y are the root-window coordinates of the upper-right
corner of the cascade entry, and group is the name of the
menu's group (as determined in its last post widget command).
The lower-level menu is unposted by executing a Tcl command with
the form
- menu:unpost
-
where menu is the name of the associated menu.
If a :command option is specified for a cascade entry then it is
evaluated as a Tcl command each time the associated menu is posted (the
evaluation occurs before the menu is posted).
The menu command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
- pathName option ?arg arg ...?
-
Option and the args
determine the exact behavior of the command.
Many of the widget commands for a menu take as one argument an
indicator of which entry of the menu to operate on. These
indicators are called indexes and may be specified in
any of the following forms:
- number
-
Specifies the entry numerically, where 0 corresponds
to the top-most entry of the menu, 1 to the entry below it, and
so on.
- active
-
Indicates the entry that is currently active. If no entry is
active then this form is equivalent to none. This form may
not be abbreviated.
- last
-
Indicates the bottommost entry in the menu. If there are no
entries in the menu then this form is equivalent to none.
This form may not be abbreviated.
- none
-
Indicates "no entry at all"; this is used most commonly with
the activate option to deactivate all the entries in the
menu. In most cases the specification of none causes
nothing to happen in the widget command.
This form may not be abbreviated.
- @number
-
In this form, number is treated as a y-coordinate in the
menu's window; the entry spanning that y-coordinate is used.
For example, "@0" indicates the top-most entry in the
window. If number is outside the range of the window
then this form is equivalent to none.
- pattern
-
If the index doesn't satisfy one of the above forms then this
form is used. Pattern is pattern-matched against the label of
each entry in the menu, in order from the top down, until a
matching entry is found. The rules of Tcl_StringMatch
are used.
The following widget commands are possible for menu widgets:
- pathName :activate index
-
Change the state of the entry indicated by index to active
and redisplay it using its active colors.
Any previously-active entry is deactivated. If index
is specified as none, or if the specified entry is
disabled, then the menu ends up with no active entry.
Returns an empty string.
- pathName :add type ?option value option value ...?
-
Add a new entry to the bottom of the menu. The new entry's type
is given by type and must be one of cascade,
checkbutton, command, radiobutton, or separator,
or a unique abbreviation of one of the above. If additional arguments
are present, they specify any of the following options:
- :activebackground value
-
Specifies a background color to use for displaying this entry when it
is active.
If this option is specified as an empty string (the default), then the
activeBackground option for the overall menu is used.
This option is not available for separator entries.
- :accelerator value
-
Specifies a string to display at the right side of the menu entry.
Normally describes an accelerator keystroke sequence that may be
typed to invoke the same function as the menu entry. This option
is not available for separator entries.
- :background value
-
Specifies a background color to use for displaying this entry when it
is in the normal state (neither active nor disabled).
If this option is specified as an empty string (the default), then the
background option for the overall menu is used.
This option is not available for separator entries.
- :bitmap value
-
Specifies a bitmap to display in the menu instead of a textual
label, in any of the forms accepted by Tk_GetBitmap.
This option overrides the :label option but may be reset
to an empty string to enable a textual label to be displayed.
This option is not available for separator entries.
- :command value
-
For command, checkbutton, and radiobutton entries, specifies a
Tcl command to execute when the menu entry is invoked.
For cascade entries, specifies a Tcl command to execute
when the entry is activated (i.e. just before its submenu is
posted).
Not available for separator entries.
- :font value
-
Specifies the font to use when drawing the label or accelerator
string in this entry.
If this option is specified as an empty string (the default) then
the font option for the overall menu is used.
This option is not available for separator entries.
- :label value
-
Specifies a string to display as an identifying label in the menu
entry. Not available for separator entries.
- :menu value
-
Available only for cascade entries. Specifies the path name of
the menu associated with this entry.
- :offvalue value
-
Available only for check-button entries. Specifies the value to
store in the entry's associated variable when the entry is
deselected.
- :onvalue value
-
Available only for check-button entries. Specifies the value to
store in the entry's associated variable when the entry is selected.
- :state value
-
Specifies one of three states for the entry: normal, active,
or disabled. In normal state the entry is displayed using the
foreground option for the menu and the background
option from the entry or the menu.
The active state is typically used when the pointer is over the entry.
In active state the entry is displayed using the activeForeground
option for the menu along with the activebackground option from
the entry.
Disabled state means that the entry is insensitive: it doesn't activate
and doesn't respond to mouse button presses or releases.
In this state the entry is displayed according to the
disabledForeground option for the menu and the
background option from the entry.
This option is not available for separator entries.
- :underline value
-
Specifies the integer index of a character to underline in the entry.
This option is typically used to indicate keyboard traversal characters.
0 corresponds to the first character of the text displayed in the entry,
1 to the next character, and so on.
If a bitmap is displayed in the entry then this option is ignored.
This option is not available for separator entries.
- :value value
-
Available only for radio-button entries. Specifies the value to
store in the entry's associated variable when the entry is selected.
- :variable value
-
Available only for check-button and radio-button entries. Specifies
the name of a global value to set when the entry is selected.
For check-button entries the variable is also set when the entry
is deselected. For radio-button entries, changing the variable
causes the currently-selected entry to deselect itself.
The add widget command returns an empty string.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the menu
command.
- pathName :delete index1 ?index2?
-
Delete all of the menu entries between index1 and
index2 inclusive.
If index2 is omitted then it defaults to index1.
Returns an empty string.
- pathName :disable index
-
Change the state of the entry given by index to disabled
and redisplay the entry using its disabled colors.
Returns an empty string.
This command is obsolete and will eventually be removed;
use "pathName :entryconfigure index :state disabled" instead.
- pathName :enable index
-
Change the state of the entry given by index to normal
and redisplay the entry using its normal colors.
Returns an empty string.
This command is obsolete and will eventually be removed;
use "pathName :entryconfigure index :state normal" instead.
- pathName :entryconfigure index ?options?
-
This command is similar to the configure command, except that
it applies to the options for an individual entry, whereas configure
applies to the options for the menu as a whole.
Options may have any of the values accepted by the add
widget command. If options are specified, options are modified
as indicated
in the command and the command returns an empty string.
If no options are specified, returns a list describing
the current options for entry index (see Tk_ConfigureInfo for
information on the format of this list).
- pathName :index index
-
Returns the numerical index corresponding to index, or
none if index was specified as none.
- pathName :invoke index
-
Invoke the action of the menu entry. See the sections on the
individual entries above for details on what happens. If the
menu entry is disabled then nothing happens. If the
entry has a command associated with it then the result of that
command is returned as the result of the invoke widget
command. Otherwise the result is an empty string. Note: invoking
a menu entry does not automatically unpost the menu. Normally
the associated menubutton will take care of unposting the menu.
- pathName :post x y
-
Arrange for the menu to be displayed on the screen at the root-window
coordinates given by x and y. These coordinates are
adjusted if necessary to guarantee that the entire menu is visible on
the screen. This command normally returns an empty string.
If the :postcommand option has been specified, then its value is
executed as a Tcl script before posting the menu and the result of
that script is returned as the result of the post widget
command.
If an error returns while executing the command, then the error is
returned without posting the menu.
- pathName :unpost
-
Unmap the window so that it is no longer displayed. If a
lower-level cascaded menu is posted, unpost that menu. Returns an
empty string.
- pathName :yposition index
-
Returns a decimal string giving the y-coordinate within the menu
window of the topmost pixel in the entry specified by index.
Tk automatically creates class bindings for menus that give them
the following default behavior:
-
[1]
When the mouse cursor enters a menu, the entry underneath the mouse
cursor is activated; as the mouse moves around the menu, the active
entry changes to track the mouse.
-
[2]
When button 1 is released over a menu, the active entry (if any) is invoked.
-
[3]
A menu can be repositioned on the screen by dragging it with mouse
button 2.
-
[4]
A number of other bindings are created to support keyboard menu traversal.
See the manual entry for tk_bindForTraversal for details on these
bindings.
Disabled menu entries are non-responsive: they don't activate and
ignore mouse button presses and releases.
The behavior of menus can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
At present it isn't possible to use the
option database to specify values for the options to individual
entries.
menu, widget
scrollbar \- Create and manipulate scrollbar widgets
scrollbar pathName ?options?
activeForeground cursor relief
background foreground repeatDelay
borderWidth orient repeatInterval
See section options, for more information.
:command
-
Name="command" Class="
Command"
Specifies the prefix of a Tcl command to invoke to change the view
in the widget associated with the scrollbar. When a user requests
a view change by manipulating the scrollbar, a Tcl command is
invoked. The actual command consists of this option followed by
a space and a number. The number indicates the logical unit that
should appear at the top of the associated window.
:width
-
Name="width" Class="
Width"
Specifies the desired narrow dimension of the scrollbar window,
not including 3-D border, if any. For vertical
scrollbars this will be the width and for horizontal scrollbars
this will be the height.
The value may have any of the forms acceptable to Tk_GetPixels.
The scrollbar command creates a new window (given by the
pathName argument) and makes it into a scrollbar widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the scrollbar such as its colors, orientation,
and relief. The scrollbar command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A scrollbar is a widget that displays two arrows, one at each end of
the scrollbar, and a slider in the middle portion of the
scrollbar. A scrollbar is used to provide information about what
is visible in an associated window that displays an object
of some sort (such as a file being edited or a drawing).
The position and size of the slider indicate which portion of the
object is visible in the associated window. For example, if the
slider in a vertical scrollbar covers the top third of the area
between the two arrows, it means that the associated window displays
the top third of its object.
Scrollbars can be used to adjust the view in the associated window
by clicking or dragging with the mouse. See the BINDINGS section
below for details.
The scrollbar command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for scrollbar widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the scrollbar
command.
- pathName :get
-
Returns a Tcl list containing four decimal values, which are
the current totalUnits, widnowUnits, firstUnit,
and lastUnit values for the scrollbar. These are the values
from the most recent set widget command on the scrollbar.
- pathName :set totalUnits windowUnits firstUnit lastUnit
-
This command is invoked to give the scrollbar information about the
widget associated with the scrollbar. TotalUnits is an integer
value giving the total size of the object being displayed in the
associated widget. The meaning of one unit depends on the associated
widget; for example, in a text editor widget units might
correspond to lines of
text. WindowUnits indicates the total number of units that
can fit in the associated window at one time. FirstUnit
and lastUnit give the indices of the first and last units
currently visible in the associated window (zero corresponds to the
first unit of the object). This command should
be invoked by the associated widget whenever its object or window
changes size and whenever it changes the view in its window.
The description below assumes a vertically-oriented scrollbar.
For a horizontally-oriented scrollbar replace the words "up", "down",
"top", and "bottom" with "left", "right", "left",
and "right", respectively
A scrollbar widget is divided into five distinct areas. From top
to bottom, they are: the top arrow, the top gap (the empty space
between the arrow and the slider), the slider, the bottom gap,
and the bottom arrow. Pressing mouse button 1 in each area has
a different effect:
- top arrow
-
Causes the view in the associated window to shift up by one unit
(i.e. the object appears to move down one unit in its window).
If the button is held down the action will auto-repeat.
- top gap
-
Causes the view in the associated window to shift up by one
less than the number of units in the window
(i.e. the portion of the object that used to appear at the very
top of the window will now appear at the very bottom).
If the button is held down the action will auto-repeat.
- slider
-
Pressing button 1 in this area has no immediate effect except to
cause the slider to appear sunken rather than raised. However,
if the mouse is moved with the button down then the slider will
be dragged, adjusting the view as the mouse is moved.
- bottom gap
-
Causes the view in the associated window to shift down by one
less than the number of units in the window
(i.e. the portion of the object that used to appear at the very
bottom of the window will now appear at the very top).
If the button is held down the action will auto-repeat.
- bottom arrow
-
Causes the view in the associated window to shift down by one unit
(i.e. the object appears to move up one unit in its window).
If the button is held down the action will auto-repeat.
Note: none of the actions described above has an immediate impact
on the position of the slider in the scrollbar. It simply invokes
the command specified in the command option to notify the
associated widget that a change in view is desired. If the view is
actually changed then the associated widget must invoke the
scrollbar's set widget command to change what is displayed in
the scrollbar.
scrollbar, widget
checkbutton \- Create and manipulate check-button widgets
checkbutton pathName ?options?
activeBackground bitmap font relief
activeForeground borderWidth foreground text
anchor cursor padX textVariable
background disabledForeground padY
See section options, for more information.
:command
-
Name="command" Class="
Command"
Specifies a Tcl command to associate with the button. This command
is typically invoked when mouse button 1 is released over the button
window. The button's global variable (:variable option) will
be updated before the command is invoked.
:height
-
Name="height" Class="
Height"
Specifies a desired height for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in lines of text.
If this option isn't specified, the button's desired height is computed
from the size of the bitmap or text being displayed in it.
:offvalue
-
Name="offValue" Class="
Value"
Specifies value to store in the button's associated variable whenever
this button is deselected. Defaults to "0".
:onvalue
-
Name="onValue" Class="
Value"
Specifies value to store in the button's associated variable whenever
this button is selected. Defaults to "1".
:selector
-
Name="selector" Class="
Foreground"
Specifies the color to draw in the selector when this button is
selected.
If specified as an empty string then no selector is
drawn for the button.
:state
-
Name="state" Class="
State"
Specifies one of three states for the check button: normal, active,
or disabled. In normal state the check button is displayed using the
foreground and background options. The active state is
typically used when the pointer is over the check button. In active state
the check button is displayed using the activeForeground and
activeBackground options. Disabled state means that the check button
is insensitive: it doesn't activate and doesn't respond to mouse
button presses. In this state the disabledForeground and
background options determine how the check button is displayed.
:variable
-
Name="variable" Class="
Variable"
Specifies name of global variable to set to indicate whether
or not this button is selected. Defaults to the name of the
button within its parent (i.e. the last element of the button
window's path name).
:width
-
Name="width" Class="
Width"
Specifies a desired width for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in characters.
If this option isn't specified, the button's desired width is computed
from the size of the bitmap or text being displayed in it.
The checkbutton command creates a new window (given by the
pathName argument) and makes it into a check-button widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the check button such as its colors, font,
text, and initial relief. The checkbutton command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A check button is a widget
that displays a textual string or bitmap
and a square called a selector.
A check button has
all of the behavior of a simple button, including the
following: it can display itself in either of three different
ways, according to the state option;
it can be made to appear
raised, sunken, or flat; it can be made to flash; and it invokes
a Tcl command whenever mouse button 1 is clicked over the
check button.
In addition, check buttons can be selected. If a check button is
selected then a special highlight appears in the selector, and
a Tcl variable associated with the check button is set to a particular
value (normally 1). If the check button is not selected, then
the selector is drawn in a different fashion and the associated
variable is set to a different value (typically 0). By default,
the name of the variable associated with a check button is the
same as the name used to create the check button. The
variable name, and the "on" and "off" values stored in it,
may be modified with options on the command line or in the option
database. By default a check button is configured to select and deselect
itself on alternate button clicks.
In addition, each check button monitors its associated variable and
automatically selects and deselects itself when the variables value
changes to and from the button's "on" value.
The checkbutton command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for check button widgets:
- pathName :activate
-
Change the check button's state to active and redisplay the button
using its active foreground and background colors instead of normal
colors.
This command is ignored if the check button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state active" instead.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the checkbutton
command.
- pathName :deactivate
-
Change the check button's state to normal and redisplay the button
using its normal foreground and background colors.
This command is ignored if the check button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state normal" instead.
- pathName :deselect
-
Deselect the check button: redisplay it without a highlight in
the selector and set the associated variable to its "off"
value.
- pathName :flash
-
Flash the check button. This is accomplished by redisplaying the check button
several times, alternating between active and normal colors. At
the end of the flash the check button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the check button's state is disabled.
- pathName :invoke
-
Does just what would have happened if the user invoked the check button
with the mouse: toggle the selection state of the button and invoke
the Tcl command associated with the check button, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the check button.
This command is ignored if the check button's state is disabled.
- pathName :select
-
Select the check button: display it with a highlighted
selector and set the associated variable to its "on"
value.
- pathName :toggle
-
Toggle the selection state of the button, redisplaying it and
modifying its associated variable to reflect the new state.
Tk automatically creates class bindings for check buttons that give them
the following default behavior:
-
[1]
The check button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the check button.
-
[2]
The check button's relief is changed to sunken whenever mouse button 1 is
pressed over it, and the relief is restored to its original
value when button 1 is later released.
-
[3]
If mouse button 1 is pressed over the check button and later released over
the check button, the check button is invoked (i.e. its selection
state toggles and the command associated with the button is invoked,
if there is one). However, if the mouse is not
over the check button when button 1 is released, then no invocation occurs.
If the check button's state is disabled then none of the above
actions occur: the check button is completely non-responsive.
The behavior of check buttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
check button, widget
menubutton \- Create and manipulate menubutton widgets
menubutton pathName ?options?
activeBackground bitmap font relief
activeForeground borderWidth foreground text
anchor cursor padX textVariable
background disabledForeground padY underline
See section options, for more information.
:height
-
Name="height" Class="
Height"
Specifies a desired height for the menu button.
If a bitmap is being displayed in the menu button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in lines of text.
If this option isn't specified, the menu button's desired height is computed
from the size of the bitmap or text being displayed in it.
:menu
-
Name="menu" Class="
MenuName"
Specifies the path name of the menu associated with this menubutton.
The menu must be a descendant of the menubutton in order for normal pull-down
operation to work via the mouse.
:state
-
Name="state" Class="
State"
Specifies one of three states for the menu button: normal, active,
or disabled. In normal state the menu button is displayed using the
foreground and background options. The active state is
typically used when the pointer is over the menu button. In active state
the menu button is displayed using the activeForeground and
activeBackground options. Disabled state means that the menu button
is insensitive: it doesn't activate and doesn't respond to mouse
button presses. In this state the disabledForeground and
background options determine how the button is displayed.
:width
-
Name="width" Class="
Width"
Specifies a desired width for the menu button.
If a bitmap is being displayed in the menu button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in characters.
If this option isn't specified, the menu button's desired width is computed
from the size of the bitmap or text being displayed in it.
The menubutton command creates a new window (given by the
pathName argument) and makes it into a menubutton widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the menubutton such as its colors, font,
text, and initial relief. The menubutton command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A menubutton is a widget that displays a
textual string or bitmap
and is associated with a menu widget. In normal usage, pressing
mouse button 1 over the menubutton causes the associated menu to
be posted just underneath the menubutton. If the mouse is moved over
the menu before releasing the mouse button, the button release
causes the underlying menu entry to be invoked. When the button
is released, the menu is unposted.
Menubuttons are typically organized into groups called menu bars
that allow scanning:
if the mouse button is pressed over one menubutton (causing it
to post its menu) and the mouse is moved over another menubutton
in the same menu bar without releasing the mouse button, then the
menu of the first menubutton is unposted and the menu of the
new menubutton is posted instead.
The tk-menu-bar procedure is used to set up menu bars for
scanning; see that procedure for more details.
The menubutton command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for menubutton widgets:
- pathName :activate
-
Change the menu button's state to active and redisplay the menu
button using its active foreground and background colors instead of normal
colors.
The command returns an empty string.
This command is ignored if the menu button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state active" instead.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the menubutton
command.
- pathName :deactivate
-
Change the menu button's state to normal and redisplay the menu
button using its normal foreground and background colors.
The command returns an empty string.
This command is ignored if the menu button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state normal" instead.
Tk automatically creates class bindings for menu buttons that give them
the following default behavior:
-
[1]
A menu button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves it.
-
[2]
A menu button's relief is changed to raised whenever mouse button 1 is
pressed over it, and the relief is restored to its original value
when button 1 is later released or the mouse is dragged into another
menu button in the same menu bar.
-
[3]
When mouse button 1 is pressed over a menu button, or when the mouse
is dragged into a menu button with mouse button 1 pressed, the associated
menu is posted; the mouse can be dragged across the menu and released
over an entry in the menu to invoke that entry. The menu is unposted
when button 1 is released outside either the menu or the menu button.
The menu is also unposted when the mouse is dragged into another
menu button in the same menu bar.
-
[4]
If mouse button 1 is pressed and released within the menu button,
then the menu stays posted and keyboard traversal is possible as
described in the manual entry for tk-menu-bar.
-
[5]
Menubuttons may also be posted by typing characters on the keyboard.
See the manual entry for tk-menu-bar for full details on keyboard
menu traversal.
-
[6]
If mouse button 2 is pressed over a menu button then the associated
menu is posted and also torn off: it can then be dragged around on
the screen with button 2 and the menu will not automatically unpost when
entries in it are invoked.
To close a torn off menu, click mouse button 1 over the associated
menu button.
If the menu button's state is disabled then none of the above
actions occur: the menu button is completely non-responsive.
The behavior of menu buttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
menubutton, widget
text \- Create and manipulate text widgets
text pathName ?options?
background foreground insertWidth selectBorderWidth
borderWidth insertBackground padX selectForeground
cursor insertBorderWidth padY setGrid
exportSelection insertOffTime relief yScrollCommand
font insertOnTime selectBackground
See section options, for more information.
:height
-
Name="height" Class="
Height"
Specifies the desired height for the window, in units of characters.
Must be at least one.
:state
-
Name="state" Class="
State"
Specifies one of two states for the text: normal or disabled.
If the text is disabled then characters may not be inserted or deleted
and no insertion cursor will be displayed, even if the input focus is
in the widget.
:width
-
Name="width" Class="
Width"
Specifies the desired width for the window in units of characters.
If the font doesn't have a uniform width then the width of the
character "0" is used in translating from character units to
screen units.
:wrap
-
Name="wrap" Class="
Wrap"
Specifies how to handle lines in the text that are too long to be
displayed in a single line of the text's window.
The value must be none or char or word.
A wrap mode of none means that each line of text appears as
exactly one line on the screen; extra characters that don't fit
on the screen are not displayed.
In the other modes each line of text will be broken up into several
screen lines if necessary to keep all the characters visible.
In char mode a screen line break may occur after any character;
in word mode a line break will only be made at word boundaries.
The text command creates a new window (given by the
pathName argument) and makes it into a text widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the text such as its default background color
and relief. The text command returns the
path name of the new window.
A text widget displays one or more lines of text and allows that
text to be edited.
Text widgets support three different kinds of annotations on the
text, called tags, marks, and windows.
Tags allow different portions of the text
to be displayed with different fonts and colors.
In addition, Tcl commands can be associated with tags so
that commands are invoked when particular actions such as keystrokes
and mouse button presses occur in particular ranges of the text.
See TAGS below for more details.
The second form of annotation consists of marks, which are floating
markers in the text.
Marks are used to keep track of various interesting positions in the
text as it is edited.
See MARKS below for more details.
The third form of annotation allows arbitrary windows to be displayed
in the text widget.
See WINDOWS below for more details.
Many of the widget commands for texts take one or more indices
as arguments.
An index is a string used to indicate a particular place within
a text, such as a place to insert characters or one endpoint of a
range of characters to delete.
Indices have the syntax
base modifier modifier modifier ...
Where base gives a starting point and the modifiers
adjust the index from the starting point (e.g. move forward or
backward one character). Every index must contain a base,
but the modifiers are optional.
The base for an index must have one of the following forms:
- line.char
-
Indicates char'th character on line line.
Lines are numbered from 1 for consistency with other UNIX programs
that use this numbering scheme.
Within a line, characters are numbered from 0.
- @x,y
-
Indicates the character that covers the pixel whose x and y coordinates
within the text's window are x and y.
- end
-
Indicates the last character in the text, which is always a newline
character.
- mark
-
Indicates the character just after the mark whose name is mark.
- tag.first
-
Indicates the first character in the text that has been tagged with
tag.
This form generates an error if no characters are currently tagged
with tag.
- tag.last
-
Indicates the character just after the last one in the text that has
been tagged with tag.
This form generates an error if no characters are currently tagged
with tag.
If modifiers follow the base index, each one of them must have one
of the forms listed below. Keywords such as chars and wordend
may be abbreviated as long as the abbreviation is unambiguous.
- + count chars
-
Adjust the index forward by count characters, moving to later
lines in the text if necessary. If there are fewer than count
characters in the text after the current index, then set the index
to the last character in the text.
Spaces on either side of count are optional.
- - count chars
-
Adjust the index backward by count characters, moving to earlier
lines in the text if necessary. If there are fewer than count
characters in the text before the current index, then set the index
to the first character in the text.
Spaces on either side of count are optional.
- + count lines
-
Adjust the index forward by count lines, retaining the same
character position within the line. If there are fewer than count
lines after the line containing the current index, then set the index
to refer to the same character position on the last line of the text.
Then, if the line is not long enough to contain a character at the indicated
character position, adjust the character position to refer to the last
character of the line (the newline).
Spaces on either side of count are optional.
- - count lines
-
Adjust the index backward by count lines, retaining the same
character position within the line. If there are fewer than count
lines before the line containing the current index, then set the index
to refer to the same character position on the first line of the text.
Then, if the line is not long enough to contain a character at the indicated
character position, adjust the character position to refer to the last
character of the line (the newline).
Spaces on either side of count are optional.
- linestart
-
Adjust the index to refer to the first character on the line.
- lineend
-
Adjust the index to refer to the last character on the line (the newline).
- wordstart
-
Adjust the index to refer to the first character of the word containing
the current index. A word consists of any number of adjacent characters
that are letters, digits, or underscores, or a single character that
is not one of these.
- wordend
-
Adjust the index to refer to the character just after the last one of the
word containing the current index. If the current index refers to the last
character of the text then it is not modified.
If more than one modifier is present then they are applied in
left-to-right order. For example, the index "\fBend \- 1 chars"
refers to the next-to-last character in the text and
"\fBinsert wordstart \- 1 c" refers to the character just before
the first one in the word containing the insertion cursor.
The first form of annotation in text widgets is a tag.
A tag is a textual string that is associated with some of the characters
in a text.
There may be any number of tags associated with characters in a
text.
Each tag may refer to a single character, a range of characters, or
several ranges of characters.
An individual character may have any number of tags associated with it.
A priority order is defined among tags, and this order is used in
implementing some of the tag-related functions described below.
When a tag is defined (by associating it with characters or setting
its display options or binding commands to it), it is given
a priority higher than any existing tag.
The priority order of tags may be redefined using the
"pathName :tag :raise" and "pathName :tag :lower"
widget commands.
Tags serve three purposes in text widgets.
First, they control the way information is displayed on the screen.
By default, characters are displayed as determined by the
background, font, and foreground options for the
text widget.
However, display options may be associated with individual tags
using the "pathName :tag configure" widget command.
If a character has been tagged, then the display options associated
with the tag override the default display style.
The following options are currently supported for tags:
- :background color
-
Color specifies the background color to use for characters
associated with the tag.
It may have any of the forms accepted by Tk_GetColor.
- :bgstipple bitmap
-
Bitmap specifies a bitmap that is used as a stipple pattern
for the background.
It may have any of the forms accepted by Tk_GetBitmap.
If bitmap hasn't been specified, or if it is specified
as an empty string, then a solid fill will be used for the
background.
- :borderwidth pixels
-
Pixels specifies the width of a 3-D border to draw around
the background.
It may have any of the forms accepted by Tk_GetPixels.
This option is used in conjunction with the :relief
option to give a 3-D appearance to the background for characters;
it is ignored unless the :background option
has been set for the tag.
- :fgstipple bitmap
-
Bitmap specifies a bitmap that is used as a stipple pattern
when drawing text and other foreground information such as
underlines.
It may have any of the forms accepted by Tk_GetBitmap.
If bitmap hasn't been specified, or if it is specified
as an empty string, then a solid fill will be used.
- :font fontName
-
FontName is the name of a font to use for drawing characters.
It may have any of the forms accepted by Tk_GetFontStruct.
- :foreground color
-
Color specifies the color to use when drawing text and other
foreground information such as underlines.
It may have any of the forms accepted by Tk_GetColor.
- :relief relief
-
\fIRelief specifies the 3-D relief to use for drawing backgrounds,
in any of the forms accepted by Tk_GetRelief.
This option is used in conjunction with the :borderwidth
option to give a 3-D appearance to the background for characters;
it is ignored unless the :background option
has been set for the tag.
- :underline boolean
-
Boolean specifies whether or not to draw an underline underneath
characters.
It may have any of the forms accepted by Tk_GetBoolean.
If a character has several tags associated with it, and if their
display options conflict, then the options of the highest priority
tag are used.
If a particular display option hasn't been specified for a
particular tag, or if it is specified as an empty string, then
that option will never be used; the next-highest-priority
tag's option will used instead.
If no tag specifies a particular display optionl, then the default
style for the widget will be used.
The second purpose for tags is event bindings.
You can associate bindings with a tag in much the same way you can
associate bindings with a widget class: whenever particular X
events occur on characters with the given tag, a given
Tcl command will be executed.
Tag bindings can be used to give behaviors to ranges of characters;
among other things, this allows hypertext-like
features to be implemented.
For details, see the description of the tag bind widget
command below.
The third use for tags is in managing the selection.
See THE SELECTION below.
The second form of annotation in text widgets is a mark.
Marks are used for remembering particular places in a text.
They are something like tags, in that they have names and
they refer to places in the file, but a mark isn't associated
with particular characters.
Instead, a mark is associated with the gap between two characters.
Only a single position may be associated with a mark at any given
time.
If the characters around a mark are deleted the mark will still
remain; it will just have new neighbor characters.
In contrast, if the characters containing a tag are deleted then
the tag will no longer have an association with characters in
the file.
Marks may be manipulated with the "pathName :mark" widget
command, and their current locations may be determined by using the
mark name as an index in widget commands.
The name space for marks is different from that for tags: the
same name may be used for both a mark and a tag, but they will refer
to different things.
Two marks have special significance.
First, the mark insert is associated with the insertion cursor,
as described under THE INSERTION CURSOR below.
Second, the mark current is associated with the character
closest to the mouse and is adjusted automatically to track the
mouse position and any changes to the text in the widget (one
exception: current is not updated in response to mouse
motions if a mouse button is down; the update will be deferred
until all mouse buttons have been released).
Neither of these special marks may be unset.
The third form of annotation in text widgets is a window.
Window support isn't implemented yet, but when it is it will be
described here.
Text widgets support the standard X selection.
Selection support is implemented via tags.
If the exportSelection option for the text widget is true
then the sel tag will be associated with the selection:
-
[1]
Whenever characters are tagged with sel the text widget
will claim ownership of the selection.
-
[2]
Attempts to retrieve the
selection will be serviced by the text widget, returning all the
charaters with the sel tag.
-
[3]
If the selection is claimed away by another application or by another
window within this application, then the sel tag will be removed
from all characters in the text.
The sel tag is automatically defined when a text widget is
created, and it may not be deleted with the "pathName :tag delete"
widget command. Furthermore, the selectBackground,
selectBorderWidth, and selectForeground options for
the text widget are tied to the :background,
:borderwidth, and :foreground options for the sel
tag: changes in either will automatically be reflected in the
other.
The mark named insert has special significance in text widgets.
It is defined automatically when a text widget is created and it
may not be unset with the "pathName :mark unset" widget
command.
The insert mark represents the position of the insertion
cursor, and the insertion cursor will automatically be drawn at
this point whenever the text widget has the input focus.
The text command creates a new Tcl command whose
name is the same as the path name of the text's window. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as
the text widget's path name. Option and the args
determine the exact behavior of the command. The following
commands are possible for text widgets:
- pathName :compare index1 op index2
-
Compares the indices given by index1 and index2 according
to the relational operator given by op, and returns 1 if
the relationship is satisfied and 0 if it isn't.
Op must be one of the operators <, <=, ==, >=, >, or !=.
If op is == then 1 is returned if the two indices refer to
the same character, if op is < then 1 is returned if index1
refers to an earlier character in the text than index2, and
so on.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the text
command.
- pathName :debug ?boolean?
-
If boolean is specified, then it must have one of the true or
false values accepted by Tcl_GetBoolean.
If the value is a true one then internal consistency checks will be
turned on in the B-tree code associated with text widgets.
If boolean has a false value then the debugging checks will
be turned off.
In either case the command returns an empty string.
If boolean is not specified then the command returns on
or off to indicate whether or not debugging is turned on.
There is a single debugging switch shared by all text widgets: turning
debugging on or off in any widget turns it on or off for all widgets.
For widgets with large amounts of text, the consistency checks may
cause a noticeable slow-down.
- pathName :delete index1 ?index2?
-
Delete a range of characters from the text.
If both index1 and index2 are specified, then delete
all the characters starting with the one given by index1
and stopping just before index2 (i.e. the character at
index2 is not deleted).
If index2 doesn't specify a position later in the text
than index1 then no characters are deleted.
If index2 isn't specified then the single character at
index1 is deleted.
It is not allowable to delete characters in a way that would leave
the text without a newline as the last character.
The command returns an empty string.
- pathName :get index1 ?index2?
-
Return a range of characters from the text.
The return value will be all the characters in the text starting
with the one whose index is index1 and ending just before
the one whose index is index2 (the character at index2
will not be returned).
If index2 is omitted then the single character at index1
is returned.
If there are no characters in the specified range (e.g. index1
is past the end of the file or index2 is less than or equal
to index1) then an empty string is returned.
- pathName :index index
-
Returns the position corresponding to index in the form
line.char where line is the line number and char
is the character number.
Index may have any of the forms described under INDICES above.
- pathName :insert \fIindex chars
-
Inserts chars into the text just before the character at
index and returns an empty string.
It is not possible to insert characters after the last newline
of the text.
- pathName :mark option ?arg arg ...?
-
This command is used to manipulate marks. The exact behavior of
the command depends on the option argument that follows
the mark argument. The following forms of the command
are currently supported:
- pathName :mark :names
-
Returns a list whose elements are the names of all the marks that
are currently set.
- pathName :mark :set markName index
-
Sets the mark named markName to a position just before the
character at index.
If markName already exists, it is moved from its old position;
if it doesn't exist, a new mark is created.
This command returns an empty string.
- pathName :mark :unset markName ?markName markName ...?
-
Remove the mark corresponding to each of the markName arguments.
The removed marks will not be usable in indices and will not be
returned by future calls to "pathName :mark names".
This command returns an empty string.
- pathName :scan option args
-
This command is used to implement scanning on texts. It has
two forms, depending on option:
- pathName :scan :mark y
-
Records y and the current view in the text window; used in
conjunction with later scan dragto commands. Typically this
command is associated with a mouse button press in the widget. It
returns an empty string.
- pathName :scan :dragto y
-
This command computes the difference between its y argument
and the y argument to the last scan mark command for
the widget. It then adjusts the view up or down by 10 times the
difference in y-coordinates. This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the text at high speed through the window. The return
value is an empty string.
- pathName :tag option ?arg arg ...?
-
This command is used to manipulate tags. The exact behavior of the
command depends on the option argument that follows the
tag argument. The following forms of the command are currently
supported:
- pathName :tag :add tagName index1 ?index2?
-
Associate the tag tagName with all of the characters starting
with index1 and ending just before
index2 (the character at index2 isn't tagged).
If index2 is omitted then the single character at
index1 is tagged.
If there are no characters in the specified range (e.g. index1
is past the end of the file or index2 is less than or equal
to index1) then the command has no effect.
This command returns an empty string.
- pathName :tag :bind tagName ?sequence? ?command?
-
This command associates command with the tag given by
tagName.
Whenever the event sequence given by sequence occurs for a
character that has been tagged with tagName,
the command will be invoked.
This widget command is similar to the bind command except that
it operates on characters in a text rather than entire widgets.
See the bind manual entry for complete details
on the syntax of sequence and the substitutions performed
on command before invoking it.
If all arguments are specified then a new binding is created, replacing
any existing binding for the same sequence and tagName
(if the first character of command is "+" then command
augments an existing binding rather than replacing it).
In this case the return value is an empty string.
If command is omitted then the command returns the command
associated with tagName and sequence (an error occurs
if there is no such binding).
If both command and sequence are omitted then the command
returns a list of all the sequences for which bindings have been
defined for tagName.
The only events for which bindings may be specified are those related
to the mouse and keyboard, such as Enter, Leave,
ButtonPress, Motion, and KeyPress.
Event bindings for a text widget use the current mark
described under MARKS above.
Enter events trigger for a character when it
becomes the current character (i.e. the current mark moves
to just in front of that character).
Leave events trigger for a character when it ceases to be
the current item (i.e. the current mark moves away from
that character, or the character is deleted).
These events are different than Enter and Leave
events for windows.
Mouse and keyboard events are directed to the current character.
It is possible for the current character to have multiple tags,
and for each of them to have a binding for a particular event
sequence.
When this occurs, the binding from the highest priority tag is
used.
If a particular tag doesn't have a binding that matches an
event, then the tag is ignored and tags with lower priority
will be checked.
If bindings are created for the widget as a whole using the
bind command, then those bindings will supplement the
tag bindings.
This means that a single event can trigger two Tcl scripts,
one for a widget-level binding and one for a tag-level
binding.
- pathName :tag :configure tagName ?option? ?value? ?option value ...?
-
This command is similar to the configure widget command except
that it modifies options associated with the tag given by tagName
instead of modifying options for the overall text widget.
If no option is specified, the command returns a list describing
all of the available options for tagName (see Tk_ConfigureInfo
for information on the format of this list).
If option is specified with no value, then the command returns
a list describing the one named option (this list will be identical to
the corresponding sublist of the value returned if no option
is specified).
If one or more option:value pairs are specified, then the command
modifies the given option(s) to have the given value(s) in tagName;
in this case the command returns an empty string.
See TAGS above for details on the options available for tags.
- pathName :tag :delete tagName ?tagName ...?
-
Deletes all tag information for each of the tagName
arguments.
The command removes the tags from all characters in the file
and also deletes any other information associated with the tags,
such as bindings and display information.
The command returns an empty string.
- pathName :tag :lower tagName ?belowThis?
-
Changes the priority of tag tagName so that it is just lower
in priority than the tag whose name is belowThis.
If belowThis is omitted, then tagName's priority
is changed to make it lowest priority of all tags.
- pathName :tag :names ?index?
-
Returns a list whose elements are the names of all the tags that
are active at the character position given by index.
If index is omitted, then the return value will describe
all of the tags that exist for the text (this includes all tags
that have been named in a "pathName :tag" widget
command but haven't been deleted by a "pathName :tag :delete"
widget command, even if no characters are currently marked with
the tag).
The list will be sorted in order from lowest priority to highest
priority.
- pathName :tag :nextrange tagName index1 ?index2?
-
This command searches the text for a range of characters tagged
with tagName where the first character of the range is
no earlier than the character at index1 and no later than
the character just before index2 (a range starting at
index2 will not be considered).
If several matching ranges exist, the first one is chosen.
The command's return value is a list containing
two elements, which are the index of the first character of the
range and the index of the character just after the last one in
the range.
If no matching range is found then the return value is an
empty string.
If index2 is not given then it defaults to the end of the text.
- pathName :tag :raise tagName ?aboveThis?
-
Changes the priority of tag tagName so that it is just higher
in priority than the tag whose name is aboveThis.
If aboveThis is omitted, then tagName's priority
is changed to make it highest priority of all tags.
- pathName :tag :ranges tagName
-
Returns a list describing all of the ranges of text that have been
tagged with tagName.
The first two elements of the list describe the first tagged range
in the text, the next two elements describe the second range, and
so on.
The first element of each pair contains the index of the first
character of the range, and the second element of the pair contains
the index of the character just after the last one in the
range.
If there are no characters tagged with tag then an
empty string is returned.
- pathName :tag :remove tagName index1 ?index2?
-
Remove the tag tagName from all of the characters starting
at index1 and ending just before
index2 (the character at index2 isn't affected).
If index2 is omitted then the single character at
index1 is untagged.
If there are no characters in the specified range (e.g. index1
is past the end of the file or index2 is less than or equal
to index1) then the command has no effect.
This command returns an empty string.
- pathName :yview ?:pickplace? what
-
This command changes the view in the widget's window so that the line
given by what is visible in the window.
What may be either an absolute line number, where 0 corresponds
to the first line of the file, or an index with any of the forms
described under INDICES above.
The first form (absolute line number) is used in the commands issued
by scrollbars to control the widget's view.
If the :pickplace option isn't specified then what will
appear at the top of the window.
If :pickplace is specified then the widget chooses where
what appears in the window:
-
[1]
If what is already visible somewhere in the window then the
command does nothing.
-
[2]
If what is only a few lines off-screen above the window then
it will be positioned at the top of the window.
-
[3]
If what is only a few lines off-screen below the window then
it will be positioned at the bottom of the window.
-
[4]
Otherwise, what will be centered in the window.
The :pickplace option is typically used after inserting text
to make sure that the insertion cursor is still visible on the screen.
This command returns an empty string.
Tk automatically creates class bindings for texts that give them
the following default behavior:
-
[1]
Pressing mouse button 1 in an text positions the insertion cursor
just before the character underneath the mouse cursor and sets the
input focus to this widget.
-
[2]
Dragging with mouse button 1 strokes out a selection between
the insertion cursor and the character under the mouse.
-
[3]
If you double-press mouse button 1 then the word under the mouse cursor
will be selected, the insertion cursor will be positioned at the
beginning of the word, and dragging the mouse will stroke out a selection
whole words at a time.
-
[4]
If you triple-press mouse button 1 then the line under the mouse cursor
will be selected, the insertion cursor will be positioned at the
beginning of the line, and dragging the mouse will stroke out a selection
whole line at a time.
-
[5]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down; this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed. If the selection was made in word or line mode then
it will be adjusted in this same mode.
-
[6]
The view in the text can be adjusted by dragging with mouse button 2.
-
[7]
If the input focus is in a text widget and characters are typed on the
keyboard, the characters are inserted just before the insertion cursor.
-
[8]
Control+h and the Backspace and Delete keys erase the character just
before the insertion cursor.
-
[9]
Control+v inserts the current selection just before the insertion cursor.
-
[10]
Control+d deletes the selected characters; an error occurs if the selection
is not in this widget.
If the text is disabled using the state option, then the text's
view can still be adjusted and text in the text can still be selected,
but no insertion cursor will be displayed and no text modifications will
take place.
The behavior of texts can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
Text widgets should run efficiently under a variety
of conditions. The text widget uses about 2-3 bytes of
main memory for each byte of text, so texts containing a megabyte
or more should be practical on most workstations.
Text is represented internally with a modified B-tree structure
that makes operations relatively efficient even with large texts.
Tags are included in the B-tree structure in a way that allows
tags to span large ranges or have many disjoint smaller ranges
without loss of efficiency.
Marks are also implemented in a way that allows large numbers of
marks.
The only known mode of operation where a text widget may not run
efficiently is if it has a very large number of different tags.
Hundreds of tags should be fine, or even a thousand,
but tens of thousands of tags will make texts consume a lot of
memory and run slowly.
text, widget
entry \- Create and manipulate entry widgets
entry pathName ?options?
background foreground insertWidth selectForeground
borderWidth insertBackground relief textVariable
cursor insertBorderWidth scrollCommand
exportSelection insertOffTime selectBackground
font insertOnTime selectBorderWidth
See section options, for more information.
:state
-
Name="state" Class="
State"
Specifies one of two states for the entry: normal or disabled.
If the entry is disabled then the value may not be changed using widget
commands and no insertion cursor will be displayed, even if the input focus is
in the widget.
:width
-
Name="width" Class="
Width"
Specifies an integer value indicating the desired width of the entry window,
in average-size characters of the widget's font.
The entry command creates a new window (given by the
pathName argument) and makes it into an entry widget.
Additional options, described above, may be specified on the
command line or in the option database
to configure aspects of the entry such as its colors, font,
and relief. The entry command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
An entry is a widget that displays a one-line text string and
allows that string to be edited using widget commands described below, which
are typically bound to keystrokes and mouse actions.
When first created, an entry's string is empty.
A portion of the entry may be selected as described below.
If an entry is exporting its selection (see the exportSelection
option), then it will observe the standard X11 protocols for handling the
selection; entry selections are available as type STRING.
Entries also observe the standard Tk rules for dealing with the
input focus. When an entry has the input focus it displays an
insertion cursor to indicate where new characters will be
inserted.
Entries are capable of displaying strings that are too long to
fit entirely within the widget's window. In this case, only a
portion of the string will be displayed; commands described below
may be used to change the view in the window. Entries use
the standard scrollCommand mechanism for interacting with
scrollbars (see the description of the scrollCommand option
for details). They also support scanning, as described below.
The entry command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command.
Many of the widget commands for entries take one or more indices as
arguments. An index specifies a particular character in the entry's
string, in any of the following ways:
- number
-
Specifies the character as a numerical index, where 0 corresponds
to the first character in the string.
- end
-
Indicates the character just after the last one in the entry's string.
This is equivalent to specifying a numerical index equal to the length
of the entry's string.
- insert
-
Indicates the character adjacent to and immediately following the
insertion cursor.
- sel.first
-
Indicates the first character in the selection. It is an error to
use this form if the selection isn't in the entry window.
- sel.last
-
Indicates the last character in the selection. It is an error to
use this form if the selection isn't in the entry window.
- @number
-
In this form, number is treated as an x-coordinate in the
entry's window; the character spanning that x-coordinate is used.
For example, "@0" indicates the left-most character in the
window.
Abbreviations may be used for any of the forms above, e.g. "e"
or "sel.f". In general, out-of-range indices are automatically
rounded to the nearest legal value.
The following commands are possible for entry widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the entry
command.
- pathName :delete first ?last?
-
Delete one or more elements of the entry. First and last
are indices of of the first and last characters in the range to
be deleted. If last isn't specified it defaults to
first, i.e. a single character is deleted. This command
returns an empty string.
- pathName :get
-
Returns the entry's string.
- pathName :icursor index
-
Arrange for the insertion cursor to be displayed just before the character
given by index. Returns an empty string.
- pathName :index index
-
Returns the numerical index corresponding to index.
- pathName :insert index string
-
Insert the characters of string just before the character
indicated by index. Returns an empty string.
- pathName :scan option args
-
This command is used to implement scanning on entries. It has
two forms, depending on option:
- pathName :scan :mark x
-
Records x and the current view in the entry window; used in
conjunction with later scan dragto commands. Typically this
command is associated with a mouse button press in the widget. It
returns an empty string.
- pathName :scan :dragto x
-
This command computes the difference between its x argument
and the x argument to the last scan mark command for
the widget. It then adjusts the view left or right by 10 times the
difference in x-coordinates. This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the entry at high speed through the window. The return
value is an empty string.
- pathName :select option arg
-
This command is used to adjust the selection within an entry. It
has several forms, depending on option:
- pathName :select :adjust index
-
Locate the end of the selection nearest to the character given by
index, and adjust that end of the selection to be at index
(i.e including but not going beyond index). The other
end of the selection is made the anchor point for future
select to commands. If the selection
isn't currently in the entry, then a new selection is created to
include the characters between index and the most recent
selection anchor point, inclusive.
Returns an empty string.
- pathName :select :clear
-
Clear the selection if it is currently in this widget. If the
selection isn't in this widget then the command has no effect.
Returns an empty string.
- pathName :select :from index
-
Set the selection anchor point to just before the character
given by index. Doesn't change the selection.
Returns an empty string.
- pathName :select :to index
-
Set the selection to consist of the elements from the anchor
point to element index, inclusive. The anchor point is
determined by the most recent select from or select adjust
command in this widget. If the selection isn't in this widget
then a new selection is created using the most recent anchor point
specified for the widget. Returns an empty string.
- pathName :view index
-
Adjust the view in the entry so that element index is
at the left edge of the window. Returns an empty string.
Tk automatically creates class bindings for entries that give them
the following default behavior:
-
[1]
Clicking mouse button 1 in an entry positions the insertion cursor
just before the character underneath the mouse cursor and sets the
input focus to this widget.
-
[2]
Dragging with mouse button 1 strokes out a selection between
the insertion cursor and the character under the mouse.
-
[3]
The ends of the selection can be adjusted by dragging with mouse
button 1 while the shift key is down; this will adjust the end
of the selection that was nearest to the mouse cursor when button
1 was pressed.
-
[4]
The view in the entry can be adjusted by dragging with mouse button 2.
-
[5]
If the input focus is in an entry widget and characters are typed on the
keyboard, the characters are inserted just before the insertion cursor.
-
[6]
Control-h and the Backspace and Delete keys erase the character just
before the insertion cursor.
-
[7]
Control-w erases the word just before the insertion cursor.
-
[8]
Control-u clears the entry to an empty string.
-
[9]
Control-v inserts the current selection just before the insertion cursor.
-
[10]
Control-d deletes the selected characters; an error occurs if the selection
is not in this widget.
If the entry is disabled using the state option, then the entry's
view can still be adjusted and text in the entry can still be selected,
but no insertion cursor will be displayed and no text modifications will
take place.
The behavior of entries can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
entry, widget
message \- Create and manipulate message widgets
message pathName ?options?
anchor cursor padX text
background font padY textVariable
borderWidth foreground relief width
See section options, for more information.
:aspect
-
Name="aspect" Class="
Aspect"
Specifies a non-negative integer value indicating desired
aspect ratio for the text. The aspect ratio is specified as
100*width/height. 100 means the text should
be as wide as it is tall, 200 means the text should
be twice as wide as it is tall, 50 means the text should
be twice as tall as it is wide, and so on.
Used to choose line length for text if width option
isn't specified.
Defaults to 150.
:justify
-
Name="justify" Class="
Justify"
Specifies how to justify lines of text.
Must be one of left, center, or right. Defaults
to left.
This option works together with the anchor, aspect,
padX, padY, and width options to provide a variety
of arrangements of the text within the window.
The aspect and width options determine the amount of
screen space needed to display the text.
The anchor, padX, and padY options determine where this
rectangular area is displayed within the widget's window, and the
justify option determines how each line is displayed within that
rectangular region.
For example, suppose anchor is e and justify is
left, and that the message window is much larger than needed
for the text.
The the text will displayed so that the left edges of all the lines
line up and the right edge of the longest line is padX from
the right side of the window; the entire text block will be centered
in the vertical span of the window.
:width
-
Name="width" Class="
Width"
Specifies the length of lines in the window.
The value may have any of the forms acceptable to Tk_GetPixels.
If this option has a value greater than zero then the aspect
option is ignored and the width option determines the line
length.
If this option has a value less than or equal to zero, then
the aspect option determines the line length.
The message command creates a new window (given by the
pathName argument) and makes it into a message widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the message such as its colors, font,
text, and initial relief. The message command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A message is a widget that displays a textual string. A message
widget has three special features. First, it breaks up
its string into lines in order to produce a given aspect ratio
for the window. The line breaks are chosen at word boundaries
wherever possible (if not even a single word would fit on a
line, then the word will be split across lines). Newline characters
in the string will force line breaks; they can be used, for example,
to leave blank lines in the display.
The second feature of a message widget is justification. The text
may be displayed left-justified (each line starts at the left side of
the window), centered on a line-by-line basis, or right-justified
(each line ends at the right side of the window).
The third feature of a message widget is that it handles control
characters and non-printing characters specially. Tab characters
are replaced with enough blank space to line up on the next
8-character boundary. Newlines cause line breaks. Other control
characters (ASCII code less than 0x20) and characters not defined
in the font are displayed as a four-character sequence \fB\exhh where
hh is the two-digit hexadecimal number corresponding to
the character. In the unusual case where the font doesn't contain
all of the characters in "0123456789abcdef\ex" then control
characters and undefined characters are not displayed at all.
The message command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for message widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the message
command.
When a new message is created, it has no default event bindings:
messages are intended for output purposes only.
Tabs don't work very well with text that is centered or right-justified.
The most common result is that the line is justified wrong.
message, widget
frame \- Create and manipulate frame widgets
frame pathName ?:class className? ?options?
background cursor relief
borderWidth geometry
See section options, for more information.
:height
-
Name="height" Class="
Height"
Specifies the desired height for the window in any of the forms
acceptable to Tk_GetPixels.
This option is only used if the :geometry option is
unspecified.
If this option is less than or equal to zero (and :geometry
is not specified) then the window will not request any size at
all.
:width
-
Name="width" Class="
Width"
Specifies the desired width for the window in any of the forms
acceptable to Tk_GetPixels.
This option is only used if the :geometry option is
unspecified.
If this option is less than or equal to zero (and :geometry
is not specified) then the window will not request any size at
all.
The frame command creates a new window (given by the
pathName argument) and makes it into a frame widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the frame such as its background color
and relief. The frame command returns the
path name of the new window.
A frame is a simple widget. Its primary purpose is to act as a
spacer or container for complex window layouts. The only features
of a frame are its background color and an optional 3-D border to make the
frame appear raised or sunken.
In addition to the standard options listed above, a :class
option may be specified on the command line. If it is specified, then
the new widget's class will be set to className instead of
Frame. Changing the class of a frame widget may be useful
in order to use a special class name in database options referring
to this widget and its children. Note: :class is handled
differently than other command-line options and cannot be specified
using the option database (it has to be processed
before the other options are even looked up, since the new class
name will affect the lookup of the other options). In addition,
the :class option may not be queried or changed using the
config command described below.
The frame command creates a new Tcl command whose
name is the same as the path name of the frame's window. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as
the frame widget's path name. Option and the args
determine the exact behavior of the command. The following
commands are possible for frame widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the frame
command.
When a new frame is created, it has no default event bindings:
frames are not intended to be interactive.
frame, widget
label \- Create and manipulate label widgets
label pathName ?options?
anchor borderWidth foreground relief
background cursor padX text
bitmap font padY textVariable
See section options, for more information.
:height
-
Name="height" Class="
Height"
Specifies a desired height for the label.
If a bitmap is being displayed in the label then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in lines of text.
If this option isn't specified, the label's desired height is computed
from the size of the bitmap or text being displayed in it.
:width
-
Name="width" Class="
Width"
Specifies a desired width for the label.
If a bitmap is being displayed in the label then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in characters.
If this option isn't specified, the label's desired width is computed
from the size of the bitmap or text being displayed in it.
The label command creates a new window (given by the
pathName argument) and makes it into a label widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the label such as its colors, font,
text, and initial relief. The label command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A label is a widget
that displays a textual string or bitmap.
The label can be manipulated in a few simple ways, such as
changing its relief or text, using the commands described below.
The label command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for label widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the label
command.
When a new label is created, it has no default event bindings:
labels are not intended to be interactive.
label, widget
radiobutton \- Create and manipulate radio-button widgets
radiobutton pathName ?options?
activeBackground bitmap font relief
activeForeground borderWidth foreground text
anchor cursor padX textVariable
background disabledForeground padX
See section options, for more information.
:command
-
Name="command" Class="
Command"
Specifies a Tcl command to associate with the button. This command
is typically invoked when mouse button 1 is released over the button
window. The button's global variable (:variable option) will
be updated before the command is invoked.
:height
-
Name="height" Class="
Height"
Specifies a desired height for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in lines of text.
If this option isn't specified, the button's desired height is computed
from the size of the bitmap or text being displayed in it.
:selector
-
Name="selector" Class="
Foreground"
Specifies the color to draw in the selector when this button is
selected.
If specified as an empty string then no selector is drawn for the button.
:state
-
Name="state" Class="
State"
Specifies one of three states for the radio button: normal, active,
or disabled. In normal state the radio button is displayed using the
foreground and background options. The active state is
typically used when the pointer is over the radio button. In active state
the radio button is displayed using the activeForeground and
activeBackground options. Disabled state means that the radio button
is insensitive: it doesn't activate and doesn't respond to mouse
button presses. In this state the disabledForeground and
background options determine how the radio button is displayed.
:value
-
Name="value" Class="
Value"
Specifies value to store in the button's associated variable whenever
this button is selected. Defaults to the name of the radio button.
:variable
-
Name="variable" Class="
Variable"
Specifies name of global variable to set whenever this button is
selected. Changes in this variable also cause the button to select
or deselect itself.
Defaults to the value selectedButton.
:width
-
Name="width" Class="
Width"
Specifies a desired width for the button.
If a bitmap is being displayed in the button then the value is in
screen units (i.e. any of the forms acceptable to Tk_GetPixels);
for text it is in characters.
If this option isn't specified, the button's desired width is computed
from the size of the bitmap or text being displayed in it.
The radiobutton command creates a new window (given by the
pathName argument) and makes it into a radiobutton widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the radio button such as its colors, font,
text, and initial relief. The radiobutton command returns its
pathName argument. At the time this command is invoked,
there must not exist a window named pathName, but
pathName's parent must exist.
A radio button is a widget
that displays a textual string or bitmap
and a diamond called a selector.
A radio button has
all of the behavior of a simple button: it can display itself in either
of three different ways, according to the state option;
it can be made to appear
raised, sunken, or flat; it can be made to flash; and it invokes
a Tcl command whenever mouse button 1 is clicked over the
check button.
In addition, radio buttons can be selected.
If a radio button is selected then a special highlight appears
in the selector and a Tcl variable associated with the radio button
is set to a particular value.
If the radio button is not selected then the selector is drawn
in a different fashion.
Typically, several radio buttons share a single variable and the
value of the variable indicates which radio button is to be selected.
When a radio button is selected it sets the value of the variable to
indicate that fact; each radio button also monitors the value of
the variable and automatically selects and deselects itself when the
variable's value changes.
By default the variable selectedButton
is used; its contents give the name of the button that is
selected, or the empty string if no button associated with that
variable is selected.
The name of the variable for a radio button,
plus the variable to be stored into it, may be modified with options
on the command line or in the option database. By default a radio
button is configured to select itself on button clicks.
The radiobutton command creates a new Tcl command whose
name is pathName. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
Option and the args
determine the exact behavior of the command. The following
commands are possible for radio-button widgets:
- pathName :activate
-
Change the radio button's state to active and redisplay the button
using its active foreground and background colors instead of normal
colors.
This command is ignored if the radio button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state active" instead.
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the radiobutton
command.
- pathName :deactivate
-
Change the radio button's state to normal and redisplay the button
using its normal foreground and background colors.
This command is ignored if the radio button's state is disabled.
This command is obsolete and will eventually be removed;
use "pathName :configure :state normal" instead.
- pathName :deselect
-
Deselect the radio button: redisplay it without a highlight in
the selector and set the associated variable to an empty string. If
this radio button was not currently selected, then the command has
no effect.
- pathName :flash
-
Flash the radio button. This is accomplished by redisplaying the radio button
several times, alternating between active and normal colors. At
the end of the flash the radio button is left in the same normal/active
state as when the command was invoked.
This command is ignored if the radio button's state is disabled.
- pathName :invoke
-
Does just what would have happened if the user invoked the radio button
with the mouse: select the button and invoke
its associated Tcl command, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the radio button.
This command is ignored if the radio button's state is disabled.
- pathName :select
-
Select the radio button: display it with a highlighted
selector and set the associated variable to the value corresponding
to this widget.
Tk automatically creates class bindings for radio buttons that give them
the following default behavior:
-
[1]
The radio button activates whenever the mouse passes over it and deactivates
whenever the mouse leaves the radio button.
-
[2]
The radio button's relief is changed to sunken whenever mouse button 1 is
pressed over it, and the relief is restored to its original
value when button 1 is later released.
-
[3]
If mouse button 1 is pressed over the radio button and later released over
the radio button, the radio button is invoked (i.e. it is selected
and the command associated with the button is invoked,
if there is one). However, if the mouse is not
over the radio button when button 1 is released, then no invocation occurs.
The behavior of radio buttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
radio button, widget
toplevel \- Create and manipulate toplevel widgets
toplevel pathName ?:screen screenName? ?:class className? ?options?
background geometry
borderWidth relief
See section options, for more information.
The toplevel command creates a new toplevel widget (given
by the pathName argument). Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the toplevel such as its background color
and relief. The toplevel command returns the
path name of the new window.
A toplevel is similar to a frame except that it is created as a
top-level window: its X parent is the root window of a screen
rather than the logical parent from its path name. The primary
purpose of a toplevel is to serve as a container for dialog boxes
and other collections of widgets. The only features
of a toplevel are its background color and an optional 3-D border
to make the toplevel appear raised or sunken.
Two special command-line options may be provided to the toplevel
command: :class and :screen. If :class
is specified, then the new widget's class will be set to
className instead of Toplevel. Changing the class of
a toplevel widget may be useful
in order to use a special class name in database options referring
to this widget and its children. The :screen option
may be used to place the window on a different screen than the
window's logical parent. Any valid screen name may be used, even
one associated with a different display.
Note: :class and :screen are handled
differently than other command-line options. They may not be specified
using the option database (these options must have been processed
before the new window has been created enough to use the option database;
in particular, the new class name will affect the lookup of options
in the database). In addition, :class and :screen
may not be queried or changed using the config command described
below. However, the winfo :class command may be used to query
the class of a window, and winfo :screen may be used to query
its screen.
The toplevel command creates a new Tcl command whose
name is the same as the path name of the toplevel's window. This
command may be used to invoke various
operations on the widget. It has the following general form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as
the toplevel widget's path name. Option and the args
determine the exact behavior of the command. The following
commands are possible for toplevel widgets:
- pathName :configure ?option? ?value option value ...?
-
Query or modify the configuration options of the widget.
If no option is specified, returns a list describing all of
the available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no option is specified). If
one or more option:value pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
Option may have any of the values accepted by the toplevel
command.
When a new toplevel is created, it has no default event bindings:
toplevels are not intended to be interactive.
toplevel, widget
Go to the first, previous, next, last section, table of contents.