All Tk widgets are created by a Tcl command of the same name as the widget. These widget creation commands have the form:
widgetCmd pathName [option value...]
where widgetCmd
is the name of the
widget type desired (e.g., button or
listbox) and pathName
is
the pathname for the new widget. The Return value for the command is
pathName
.
A widget’s pathname consists of a child name
appended to the pathname of its parent widget using a “.” character. The
child name is an arbitrary string that excludes the “.” character and is
unique among its siblings, the other widget children of its parent. The
pathname for the Tk main (or root) window is simply a single dot (i.e.,
“.”); its immediate children begin with a dot, and each additional level
of a child widget appears after an additional dot. This scheme is
analogous to file pathnames in the Unix file system, where the “/”
character is used as a directory name separator. For example, the
pathname of a frame widget named frame1
whose parent
is the main window would have the pathname .frame1
. A
button widget named button1
who is a child of
frame1
would have the pathname
.frame1.button1
. Almost all Tk commands require the
full pathname for arguments that specify a widget.
When a new widget is created with the pathname
pathName
, a new Tcl command is also defined
with the same name. Invoking this command allows one to manipulate the
widget in various ways depending on the arguments passed. The first
argument to the widget’s command is referred to as the widget
method and selects the action to be taken by the widget.
Additional arguments to the widget’s command may be allowed or required,
depending on the method. The methods available to each widget type are
described in the "Widget Commands" section, later in
this chapter.
The optional option-value
pair
arguments to the widget creation command allow one to set the value of
the widget’s supported configuration options. All widgets support the
conFigure and cget methods to
change and query their configuration options after creation.
The configure method has the form:
pathName
conFigure [option
[value
[option value
...] ] ]
If one or more option-value pairs are specified, the given options
are set to the given values. If no option-value pairs are specified, the
command returns a list with an element for each supported widget option.
Each element itself is a list of five items describing an option. These
items are the option itself, its database name, its class name, its
default value, and its current value. For example, the list for
-activebackground might look like this:
{-activebackground activeBackground Foreground #ececec
blue
}. If only the first option
argument is specified, just the five-item list describing that option is
returned.
The cget command has the form:
pathName cget option
and simply returns the current setting of the option
option
.
The configuration options available differ depending on the widget type. Many options are supported by all or several of the widget types. These standard options are described in the next section. Which standard options a widget type supports and the options that are specific to a particular widget type are described in the "Widget Commands" section.
For distance and coordinate options that take values in screen
units, the valid format is a floating-point number followed by an
optional one-character suffix: c
for centimeters,
i
for inches, m
for millimeters,
p
for printer’s points (1/72 inch), or no character
for pixels. Commands that return values for screen distances and
coordinates do so in pixels, unless otherwise stated.
Each of the following entries lists the option or options used in Tk, the name in the window system’s resource database for the option, the associated class name in the resource database, and a description of the option.
color
(activeBackground
,
Foreground
)width
(activeBorderWidth
,
BorderWidth
)Width, in screen units, of widget’s border when it is active.
color
(activeForeground
,
Background
)Foreground color of widget when it is active.
anchorPos
(anchor
,
Anchor
)How information is positioned inside widget. Valid
anchorPos
values are
n
, ne
,
e
, se
,
s
, sw
,
w
, nw
, and
center
.
color
(background
,
Background
)color
Background color of widget in normal state.
bitmap
(bitmap
,
Bitmap
)A bitmap image to display in the widget in place of a
textual label. Valid bitmap
values
are the special sequence @filename
,
specifying a file from which to read the bitmap data or one of
the built-in bitmaps: error
,
gray12
, gray25
,
gray50
, gray75
,
hourglass
, info
,
questhead
, question
, or
warning
. On the Macintosh, the following
bitmaps are available: document
,
stationery
, edition
,
application
, accessory
,
folder
, pfolder
,
trash
, floppy
,
ramdisk
, cdrom
,
preferences
, querydoc
,
stop
, note
, and
caution
.
width
(borderWidth
,
BorderWidth
)width
Width, in screen units, of widget’s border in its normal state.
cursor
(cursor
,
Cursor
)Cursor to display when mouse pointer is inside the
widget’s borders. The cursor
argument
may take the following forms:
name
[fgColor
[bgColor
] ]Name is the name of a cursor
font as defined in the X Window System
cursorfont.h include file (e.g.,
cross
and
left_ptr
). If
fgColor
and
bgColor
are specified, they
give the foreground and background colors for the cursor,
respectively. If bgColor
is
omitted, the background will be transparent. If neither is
specified, the defaults will be black and white,
respectively.
sourceName maskName fgColor
bgColor
Sourcename
and
maskName
are the names of files
describing bitmaps for the cursor’s source bits and mask.
Fgcolor
and
bgColor
indicate the foreground
and background colors, respectively, for the cursor. This
form is invalid on Macintosh and Windows platforms.
sourceName fgColor
sourceName
is the name of
a file describing a bitmap for the cursor’s source bits.
fgColor
is the foreground color
for the cursor. This form is invalid on Macintosh and
Windows platforms.
color
(disabledForeground
,
DisabledForeground
)Foreground color of widget when it is disabled.
boolean
(exportSelection
,
ExportSelection
)Whether a selection in the widget should also be made the X Window System selection.
font
(font
, Font
)Font to use when drawing text inside the widget.
color
(foreground
,
Foreground
)color
Foreground color of widget in its normal state.
color
(highlightBackground
,
HighlightBackground
)Color of the rectangle drawn around the widget when it does not have the input focus.
color
(highlightColor
,
HighlightColor
)Color of the rectangle drawn around the widget when it has the input focus.
width
(highlightThickness
,
HighlightThickness
)Width, in screen units, of highlighted rectangle drawn around widget when it has the input focus.
imageName
(image
,
Image
)Name of image to display in the widget in place of its textual label (see the image command).
color
(insertBackground
,
Foreground
)Color to use for the background of the area covered by the insertion cursor.
width
(insertBorderWidth
,
BorderWidth
)Width, in screen units, of the border to draw around the insertion cursor.
milliseconds
(insertOffTime
,
OffTime
)Time the insertion cursor should remain “off " in each blink cycle.
milliseconds
(insertOnTime
,
OnTime
)Time the insertion cursor should remain “on” in each blink cycle.
width
(insertWidth
,
InsertWidth
)Width, in screen units, of the insertion cursor.
boolean
(jump
,
Jump
)Whether to notify slider controls (e.g., scrollbars) connected to the widget to delay making updates until mouse button is released.
alignment
(justify
,
Justify
)How multiple lines of text are justified. Valid
alignment
values are left
,
center
, or right
.
orientation
(orient
,
Orient
)The orientation in which the widget should be laid out.
Valid orientation
values are
vertical
or
horizontal
.
width
(padX
, Pad
)Extra space, in screen units, to request for padding the widget’s top and bottom sides.
height
(padY
, Pad
)Extra space, in screen units, to request for padding the widget’s left and right sides.
effect
(relief
,
Relief
)3D effect desired for the widget’s border. Valid
effect
values are
flat
, groove
,
raised
, ridge
, or
sunken
.
milliseconds
(repeatDelay
,
RepeatDelay
)Time a button or key must be held down before it begins to autorepeat.
milliseconds
(repeatInterval
,
RepeatInterval
)Time between autorepeats once action has begun.
color
(selectBackground
,
Foreground
)Background color to use when displaying selected items or text.
width
(selectBorderWidth
,
BorderWidth
)Width, in screen units, of border to draw around selected items or text.
color
(selectForeground
,
Background
)Foreground color to use when displaying selected items or text.
boolean
(setGrid
,
SetGrid
)Whether the widget controls the resizing grid for its top-level window. See the wm grid command for details.
focusType
(takeFocus
,
TakeFocus
)If 0 or 1, signals that the widget should never or always take the focus. If empty, Tk decides. Otherwise, evaluates argument as script with widget name appended as argument. Returned value must be 0, 1, or empty.
string
(text
, Text
)Text string to be displayed inside the widget.
variable
(textVariable
,
Variable
)Variable whose value is a text string to be displayed inside the widget.
color
(troughColor
,
Background
)Color to use for the rectangular trough areas in widget.
index
(underline
,
Underline
)Integer index of a character to underline in the widget.
length
(wrapLength
,
WrapLength
)Maximum line length, in screen units, for word wrapping.
cmdPrefix
(xScrollCommand
,
ScrollCommand
)Prefix for a command used to communicate with an
associated horizontal scrollbar. Typically
scrollbar set
, where
scrollbar
is the pathname of a
horizontal scrollbar widget.
cmdPrefix
(yScrollCommand
,
ScrollCommand
)Prefix for a command used to communicate with an
associated vertical scrollbar. Typically scrollbar
set
, where scrollbar
is
the pathname of a vertical scrollbar widget.