Tk Source Code

have been returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in
Potentially multi-line string whose dimensions are to be computed and
stored in the text layout.  The \fIstring\fR must remain valid for the
lifetime of the text layout.
.AP int numChars in
The number of characters to consider from \fIstring\fR.  If
\fInumChars\fR is less than 0, then assumes \fIstring\fR is null
terminated and uses \fBTcl_NumUtfChars\fR to determine the length of
\fIstring\fR.
.AP int wrapLength in
Longest permissible line length, in pixels.  Lines in \fIstring\fR will
automatically be broken at word boundaries and wrapped when they reach
this length.  If \fIwrapLength\fR is too small for even a single
character to fit on a line, it will be expanded to allow one character to

\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the
character closest to the given point.  The point is specified with respect
to the upper-left hand corner of the \fIlayout\fR, which is considered to be
located at (0, 0).  Any point whose \fIy\fR-value is less that 0 will be
considered closest to the first character in the text layout; any point
whose \fIy\fR-value is greater than the height of the text layout will be
considered closest to the last character in the text layout.  Any point
whose \fIx\fR-value is less than 0 will be considered closest to the first
character on that line; any point whose \fIx\fR-value is greater than the
width of the text layout will be considered closest to the last character on
that line.  The return value is the index of the character that was closest
to the point, or one more than the index of any character (to indicate that
the point was after the end of the string and that the corresponding caret
would be at the end of the string).  Given a \fIlayout\fR with no characters,
the value 0 will always be returned, referring to a hypothetical zero-width

Specifies an increment for horizontal scrolling, in any of the usual forms
permitted for screen distances. If the value of this option is greater
than zero, the horizontal view in the window will be constrained so that
the canvas x coordinate at the left edge of the window is always an even
multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling
(e.g., the change in view when the left and right arrows of a scrollbar
are selected) will also be \fBxScrollIncrement\fR. If the value of
this option is less than or equal to zero, then horizontal scrolling
is unconstrained.
.OP \-yscrollincrement yScrollIncrement ScrollIncrement
Specifies an increment for vertical scrolling, in any of the usual forms
permitted for screen distances. If the value of this option is greater
than zero, the vertical view in the window will be constrained so that
the canvas y coordinate at the top edge of the window is always an even
multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling
(e.g., the change in view when the top and bottom arrows of a scrollbar
are selected) will also be \fByScrollIncrement\fR. If the value of
this option is less than or equal to zero, then vertical scrolling
is unconstrained.
.BE
.SH INTRODUCTION
.PP
The \fBcanvas\fR command creates a new window (given
by the \fIpathName\fR argument) and makes it into a canvas widget.
Additional options, described above, may be specified on the

\fInumber\fR
.
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. If indexes are odd for lines and polygons, they will be
automatically decremented by one.
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. For
polygons, numbers less than 0 or greater than the length
of the coordinate list will be adjusted by adding or subtracting
the length until the result is between zero and the length,
inclusive.
.TP 10
\fBend\fR
.
Refers to the character or coordinate just after the last one

the dialog, to the left of the text.
If this is an empty string then no bitmap is displayed in the dialog.
.TP
\fIdefault\fR
If this is an integer greater than or equal to zero, then it gives
the index of the button that is to be the default button for the dialog
(0 for the leftmost button, and so on).
If less than zero or an empty string then there will not be any default
button.
.TP
\fIstring\fR
There will be one button for each of these arguments.
Each \fIstring\fR specifies text to display in a button,
in order from left to right.
.PP

the valid Tcl boolean equivalent) then it means you reject the new edition
and it will not occur and the \fB\-invalidcommand\fR will be evaluated if it
is set. If it returns 1, then the new edition occurs.
See \fBVALIDATION\fR below for more information.
.OP \-width width Width
Specifies an integer value indicating the desired width of the entry window,
in average-size characters of the widget's font.
If the value is less than or equal to zero, the widget picks a
size just large enough to hold its current text.
.BE
.SH DESCRIPTION
.PP
The \fBentry\fR command creates a new window (given by the
\fIpathName\fR argument) and makes it into an entry widget.
Additional options, described above, may be specified on the

children of its own in this application.
This option may not be changed with the \fBconfigure\fR
widget command.
Note that \fB\-borderwidth\fR, \fB\-padx\fR and \fB\-pady\fR are ignored when
configured as a container since a container has no border.
.OP \-height height Height
Specifies the desired height for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.  If this option is less than or equal
to zero then the window will not request any size at all.  Note that this
sets the total height of the frame, any \fB\-borderwidth\fR or similar is
not added.  Normally \fB\-height\fR should not be used if a propagating
geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the
frame since the geometry manager will override the height of the frame.
.OP \-tile tile Tile
.VS "8.7, TIP262"
This specifies how to draw the background image (see

forms accepted by \fBTk_GetVisual\fR.
If this option is not specified, the new window will use the same
visual as its parent.
The \fB\-visual\fR option may not be modified with the \fBconfigure\fR
widget command.
.OP \-width width Width
Specifies the desired width for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.  If this option is less than or equal
to zero then the window will not request any size at all.  Note that this
sets the total width of the frame, any \fB\-borderwidth\fR or similar is
not added.  Normally \fB\-width\fR should not be used if a propagating
geometry manager, such as \fBgrid\fR or \fBpack\fR, is used within the
frame since the geometry manager will override the width of the frame.
.BE
.SH DESCRIPTION
.PP

If the \fB\-colormap\fR option is not specified, the new window
uses the same colormap as its parent.
This option may not be changed with the \fBconfigure\fR
widget command.
.OP \-height height Height
Specifies the desired height for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.
If this option is less than or equal to zero then the window will
not request any size at all.
.OP \-labelanchor labelAnchor LabelAnchor
Specifies where to place the label. A label is only displayed if the
\fB\-text\fR option is not the empty string.
Valid values for this option are (listing them clockwise)
\fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR,
\fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR.

If this option is not specified, the new window will use the same
visual as its parent.
The \fB\-visual\fR option may not be modified with the \fBconfigure\fR
widget command.
.OP \-width width Width
Specifies the desired width for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.
If this option is less than or equal to zero then the window will
not request any size at all.
.BE
.SH DESCRIPTION
.PP
The \fBlabelframe\fR command creates a new window (given by the
\fIpathName\fR argument) and makes it into a labelframe widget.
Additional

in the vertical span of the window.
.OP \-width width Width
Specifies the length of lines in the window.
The value may have any of the forms acceptable to \fBTk_GetPixels\fR.
If this option has a value greater than zero then the \fB\-aspect\fR
option is ignored and the \fB\-width\fR option determines the line
length.
If this option has a value less than or equal to zero, then
the \fB\-aspect\fR option determines the line length.
.BE
.SH DESCRIPTION
.PP
The \fBmessage\fR command creates a new window (given by the
\fIpathName\fR argument) and makes it into a message widget.
Additional

.OP \-wraplength wrapLength WrapLength
For widgets that can perform word-wrapping, this option specifies
the maximum line length.
Lines that would exceed this length are wrapped onto the next line,
so that no line is longer than the specified length.
The value may be specified in any of the standard forms for
screen distances.
If this value is less than or equal to 0 then no wrapping is done:  lines
will break only at newline characters in the text.
.OP \-xscrollcommand xScrollCommand ScrollCommand
Specifies the prefix for a command used to communicate with horizontal
scrollbars.
When the view in the widget's window changes (or
whenever anything else occurs that could change the display in a
scrollbar, such as a change in the total size of the widget's

value is changed via a widget command.
The actual command consists
of this option followed by a space and a real number indicating the
new value of the scale.
.OP \-digits digits Digits
An integer specifying how many significant digits should be retained
when converting the value of the scale to a string.
If the number is less than or equal to zero, then the scale picks
the smallest value that guarantees that every possible slider
position prints as a different string.
.OP \-from from From
A real value corresponding to the left or top end of the scale.
.OP \-label label Label
A string to display 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.  If the option is specified
as an empty string, no label is displayed.
.OP \-length length Length
Specifies the desired long dimension of the scale in screen units
(i.e. any of the forms acceptable to \fBTk_GetPixels\fR).
For vertical scales this is the scale's height;  for horizontal scales
it is the scale's width.
.OP \-resolution resolution Resolution
A real value specifying the resolution for the scale.
If this value is greater than zero then the scale's value will always be
rounded to an even multiple of this value, as will
the endpoints of the scale.  If the value is less than zero then no
rounding occurs.  Defaults to 1 (i.e., the value will be integral).
.OP \-showvalue showValue ShowValue
Specifies a boolean value indicating whether or not the current
value of the scale is to be displayed.
.OP \-sliderlength sliderLength SliderLength
Specifies 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

All scrollable widgets have \fBxview\fR and \fByview\fR commands
that take exactly the additional arguments appended by the scrollbar
as described in \fBSCROLLING COMMANDS\fR below.
.OP \-elementborderwidth elementBorderWidth BorderWidth
Specifies the width of borders drawn around the internal elements
of the scrollbar (the two arrows and the slider).  The value may
have any of the forms acceptable to \fBTk_GetPixels\fR.
If this value is less than zero, the value of the \fB\-borderwidth\fR
option is used in its place.
.OP \-width width 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 \fBTk_GetPixels\fR.
.BE

.OP \-values values Values
Must be a proper list value.  If specified, the spinbox will use these
values as to control its contents, starting with the first value.  This
option has precedence over the \fB\-from\fR and \fB\-to\fR range.
.OP \-width width Width
Specifies an integer value indicating the desired width of the spinbox window,
in average-size characters of the widget's font.
If the value is less than or equal to zero, the widget picks a
size just large enough to hold its current text.
.OP \-wrap wrap wrap
Must be a proper boolean value.  If on, the spinbox will wrap around the
values of data in the widget.
.BE
.SH DESCRIPTION
.PP

things like geometry requests.  The window should not have any
children of its own in this application.
This option may not be changed with the \fBconfigure\fR
widget command.
.OP \-height height Height
Specifies the desired height for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.
If this option is less than or equal to zero then the window will
not request any size at all.
.OP \-menu menu Menu
Specifies a menu widget to be used as a menubar. On the Macintosh, the
menubar will be displayed across the top of the main monitor. On
Microsoft Windows and all UNIX platforms, the menu will appear across
the toplevel window as part of the window dressing maintained by the
window manager.

If this option is not specified, the new window will use the default
visual for its screen.
The \fB\-visual\fR option may not be modified with the \fBconfigure\fR
widget command.
.OP \-width width Width
Specifies the desired width for the window in any of the forms
acceptable to \fBTk_GetPixels\fR.
If this option is less than or equal to zero then the window will
not request any size at all.
.BE
.SH DESCRIPTION
.PP
The \fBtoplevel\fR command creates a new toplevel widget (given
by the \fIpathName\fR argument).  Additional
options, described above, may be specified on the command line

A script template to evaluate whenever validation is triggered.
If set to the empty string (the default), validation is disabled.
The script must return a boolean value.
See \fBVALIDATION\fR below.
.OP \-width width Width
Specifies an integer value indicating the desired width of the entry window,
in average-size characters of the widget's font.
.\" Not in ttk: If the value is less than or equal to zero, the widget picks a
.\" Not in ttk: size just large enough to hold its current text.
.SH NOTES
.PP
A portion of the entry may be selected as described below.
If an entry is exporting its selection (see the \fB\-exportselection\fR
option), then it will observe the standard X11 protocols for handling the
selection;  entry selections are available as type \fBSTRING\fR.

a single number specifies the same border all the way around the element.
See \fBIMAGE STRETCHING\fR, below.
.\" OPTION: -height
.TP
\fB\-height \fIheight\fR
.
Specifies a minimum height for the element.
If less than zero, the base image's height is used as a default.
.\" OPTION: -padding
.TP
\fB\-padding\fI padding\fR
.
Specifies the element's interior padding.
The padding is a list of up to four length specifications
\fIleft top right bottom\fR.

or
.QW e .
.\" OPTION: -width
.TP
\fB\-width \fIwidth\fR
.
Specifies a minimum width for the element.
If less than zero, the base image's width is used as a default.
.SH "IMAGE STRETCHING"
.PP
If the element's allocated parcel is larger than the image,
the image will be placed in the parcel based on the \fB\-sticky\fR option.
If the image needs to stretch horizontally (i.e., \fB\-sticky ew\fR)
or vertically (\fB\-sticky ns\fR),
subregions of the image are replicated to fill the parcel

.\" Rewrite this:
Specifies the 3-D effect desired for the widget border.
Valid values are
\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR,
and \fBsunken\fR.
.OP \-wraplength wrapLength WrapLength
Specifies the maximum line length (in pixels).
If this option is less than or equal to zero,
then automatic wrapping is not performed; otherwise
the text is split into lines such that no line is longer
than the specified value.
.SH "WIDGET COMMAND"
.PP
Label widgets support the standard commands
\fBcget\fR, \fBconfigure\fR, \fBidentify element\fR, \fBinstate\fR,

.
Creates a new item.
\fIparent\fR is the item ID of the parent item,
or the empty string \fB{}\fR
to create a new top-level item.
\fIindex\fR is an integer, or the value \fBend\fR, specifying where in the
list of \fIparent\fR's children to insert the new item.
If \fIindex\fR is less than or equal to zero,
the new node is inserted at the beginning;
if \fIindex\fR is greater than or equal to the current number of children,
it is inserted at the end.
If \fB\-id\fR is specified, it is used as the item identifier;
\fIid\fR must not already exist in the tree.
Otherwise, a new unique identifier is generated.
.RS

.TP
\fIpathname \fBmove \fIitem parent index\fR
.
Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children.
It is illegal to move an item under one of its descendants.
.RS
.PP
If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved
to the beginning; if greater than or equal to the number of children,
it is moved to the end.
.RE
.\" METHOD: next
.TP
\fIpathname \fBnext \fIitem\fR
.