Tk Source Code

\fBttk::button\fR \fIpathName \fR?\fIoptions\fR?
.BE
.SH DESCRIPTION
A \fBttk::button\fR widget displays a textual label and/or image,
and evaluates a command when pressed.
.SO ttk_widget
\-class	\-compound	\-cursor
\-image	\-justify	\-state	\-style
\-takefocus	\-text	\-textvariable
\-underline	\-width
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
.OP \-command command Command
A script to evaluate when the widget is invoked.
.OP \-default default Default

\fBdisabled\fR means that it is not defaultable.
The default is \fBnormal\fR.
.RS
.PP
Depending on the theme, the default button may be displayed
with an extra highlight ring, or with a different border color.
.RE







.\" Not documented -- may go away
.\" .OP \-padding padding Padding
.\" .OP \-foreground foreground Foreground
.\" .OP \-font font Font
.\" .OP \-anchor anchor Anchor
.\" .OP \-padding padding Padding
.\" .OP \-relief relief Relief

.BE
.SH DESCRIPTION
.PP
A \fBttk::label\fR widget displays a textual label and/or image.
The label may be linked to a Tcl variable
to automatically change the displayed text.
.SO ttk_widget
\-anchor	\-class	\-compound	\-cursor
\-font	\-foreground
\-image	\-justify	\-style	\-takefocus
\-text	\-textvariable	\-underline
\-width	\-wraplength
.SE
.SH "WIDGET-SPECIFIC OPTIONS"






.OP \-background frameColor FrameColor
The widget's background color.
If unspecified, the theme default is used.










.OP \-padding padding Padding
Specifies the amount of extra space to allocate for the widget.
The padding is a list of up to four length specifications
\fIleft top right bottom\fR.
If fewer than four elements are specified,
\fIbottom\fR defaults to \fItop\fR,
\fIright\fR defaults to \fIleft\fR, and
\fItop\fR defaults to \fIleft\fR.
.OP \-relief relief Relief
.\" 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.









.SH "WIDGET COMMAND"
.PP
Supports the standard widget commands
\fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR;
see \fIttk::widget(n)\fR.
.SH "SEE ALSO"
ttk::widget(n), label(n)
'\" Local Variables:
'\" mode: nroff
'\" End:

.SH DESCRIPTION
.PP
A \fBttk::progressbar\fR widget shows the status of a long-running
operation.  They can operate in two modes: \fIdeterminate\fR mode shows the
amount completed relative to the total amount of work to be done, and
\fIindeterminate\fR mode provides an animated display to let the user know
that something is happening.
.PP
If the value of \fB-orient\fR is \fBhorizontal\fR a text string can be
displayed inside the progressbar. This string can be configured using
the \fB-anchor\fR, \fB-font\fR, \fB-foreground\fR, \fB-justify\fR,
\fB-text\fR and \fB-wraplength\fR options. If the value of \fB-orient\fR
is \fBvertical\fR then these options are ignored.
.SO ttk_widget
\-anchor	\-class	\-cursor
\-font	\-foreground	\-justify	\-style
\-takefocus	\-text	\-wraplength
.SE
.SH "WIDGET-SPECIFIC OPTIONS"



.OP \-length length Length
Specifies the length of the long axis of the progress bar
(width if horizontal, height if vertical). The value may have any of the forms


acceptable to \fBTk_GetPixels\fR.
.OP \-maximum maximum Maximum
A floating point number specifying the maximum \fB\-value\fR.
Defaults to 100.
.OP \-mode mode Mode
One of \fBdeterminate\fR or \fBindeterminate\fR.
.OP \-orient orient Orient
One of \fBhorizontal\fR or \fBvertical\fR.
Specifies the orientation of the progress bar.
.OP \-phase phase Phase
Read-only option.
The widget periodically increments the value of this option
whenever the \fB\-value\fR is greater than 0 and,
in \fIdeterminate\fR mode, less than \fB\-maximum\fR.
This option may be used by the current theme
to provide additional animation effects.
.OP \-value value Value
The current value of the progress bar.
In \fIdeterminate\fR mode, this represents the amount of work completed.
In \fIindeterminate\fR mode, it is interpreted modulo \fB\-maximum\fR;
that is, the progress bar completes one
.QW cycle
when the \fB\-value\fR increases by \fB\-maximum\fR.
.OP \-variable variable Variable
The name of a global Tcl variable which is linked to the \fB\-value\fR.
If specified, the \fB\-value\fR of the progress bar is
automatically set to the value of the variable whenever
the latter is modified.







.SH "WIDGET COMMAND"
.PP
.TP
\fIpathName \fBcget \fIoption\fR
Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR.
.TP
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?

.RE
.OP \-yscrollcommand yScrollCommand ScrollCommand
A command prefix, used to communicate with vertical scrollbars.
See the description of \fB\-xscrollcommand\fR above for details.
.SH "LABEL OPTIONS"
The following options are supported by labels, buttons,
and other button-like widgets:
.OP \-anchor anchor Anchor
Specifies how the information in the widget is positioned






relative to the inner margins.  Legal values are






\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR,
\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR.
See also \fB\-justify\fR (for widgets supporting this option).

.OP \-compound compound Compound
Specifies how to display the image relative to the text,
in the case both \fB\-text\fR and \fB\-image\fR are present.
Valid values are:
.RS
.IP text
Display text only.
.IP image
Display image only.
.IP center
Display text centered on top of image.
.IP top
.IP bottom
.IP left
.IP right
Display image above, below, left of, or right of the text, respectively.
.IP none
The default; display the image if present, otherwise the text.
.RE
.OP \-font font Font
Font to use for the text displayed by the widget.
.OP \-foreground textColor TextColor
The widget's foreground color.
If unspecified, the theme default is used.
.OP \-image image Image
Specifies an image to display.
This is a list of 1 or more elements.
The first element is the default image name.
The rest of the list is a sequence of \fIstatespec / value\fR pairs
as per \fBstyle map\fR, specifying different images to use when
the widget is in a particular state or combination of states.
All images in the list should have the same size.
.OP \-justify justify Justify
If there are multiple lines of text, specifies how
the lines are laid out relative to one another.
One of \fBleft\fR, \fBcenter\fR, or \fBright\fR.
See also \fB\-anchor\fR (for widgets supporting this option).
.OP \-text text Text
Specifies a text string to be displayed inside the widget
(unless overridden by \fB\-textvariable\fR for the widgets supporting this option).
.OP \-textvariable textVariable Variable
Specifies the name of a global variable whose value will be used
in place of the \fB\-text\fR resource.
.OP \-underline underline Underline
If set, specifies the integer index (0-based) of a character to underline
in the text string.
The underlined character is used for mnemonic activation.
.OP \-width width Width
If greater than zero, specifies how much space, in character widths,
to allocate for the text label.
If less than zero, specifies a minimum width.
If zero or unspecified, the natural width of the text label is used.
Note that some themes may specify a non-zero \fB\-width\fR
in the style.
.OP \-wraplength wrapLength WrapLength
Specifies the maximum line length. The value may have any of the forms
acceptable to \fBTk_GetPixels\fR. 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 "COMPATIBILITY OPTIONS"
.OP \-state state State
May be set to \fBnormal\fR or \fBdisabled\fR
to control the \fBdisabled\fR state bit.
This is a write-only option:
setting it changes the widget state,
but the \fBstate\fR widget command

 */
typedef struct
{
    /*
     * Text element resources:
     */
    Tcl_Obj *textObj;
    Tcl_Obj *justifyObj;
    Tcl_Obj *textVariableObj;
    Tcl_Obj *underlineObj;
    Tcl_Obj *widthObj;

    Ttk_TraceHandle	*textVariableTrace;
    Ttk_ImageSpec	*imageSpec;

{
    WidgetCore	core;
    BasePart	base;
} Base;

static Tk_OptionSpec BaseOptionSpecs[] =
{
    {TK_OPTION_JUSTIFY, "-justify", "justify", "Justify",
        "left", Tk_Offset(Base,base.justifyObj), -1,
        TK_OPTION_NULL_OK,0,GEOMETRY_CHANGED },
    {TK_OPTION_STRING, "-text", "text", "Text", "",
	Tk_Offset(Base,base.textObj), -1,
	0,0,GEOMETRY_CHANGED },
    {TK_OPTION_STRING, "-textvariable", "textVariable", "Variable", "",
	Tk_Offset(Base,base.textVariableObj), -1,
	TK_OPTION_NULL_OK,0,GEOMETRY_CHANGED },
    {TK_OPTION_INT, "-underline", "underline", "Underline",

    TTK_PROGRESSBAR_DETERMINATE, TTK_PROGRESSBAR_INDETERMINATE
};
static const char *const ProgressbarModeStrings[] = {
    "determinate", "indeterminate", NULL
};

typedef struct {
    Tcl_Obj 	*anchorObj;
    Tcl_Obj 	*fontObj;
    Tcl_Obj 	*foregroundObj;
    Tcl_Obj 	*justifyObj;
    Tcl_Obj 	*lengthObj;
    Tcl_Obj 	*maximumObj;
    Tcl_Obj 	*modeObj;
    Tcl_Obj 	*orientObj;
    Tcl_Obj 	*phaseObj;
    Tcl_Obj 	*textObj;
    Tcl_Obj 	*valueObj;
    Tcl_Obj 	*variableObj;
    Tcl_Obj 	*wrapLengthObj;

    int 	mode;
    Ttk_TraceHandle *variableTrace;	/* Trace handle for -variable option */
    int 	period;			/* Animation period */
    int 	maxPhase;		/* Max animation phase */
    Tcl_TimerToken timer;		/* Animation timer */

} ProgressbarPart;

typedef struct {
    WidgetCore 		core;
    ProgressbarPart	progress;
} Progressbar;

static Tk_OptionSpec ProgressbarOptionSpecs[] =
{
    {TK_OPTION_ANCHOR, "-anchor", "anchor", "Anchor",
	"w", Tk_Offset(Progressbar,progress.anchorObj), -1,
	TK_OPTION_NULL_OK, 0, GEOMETRY_CHANGED},
    {TK_OPTION_FONT, "-font", "font", "Font",
	DEFAULT_FONT, Tk_Offset(Progressbar,progress.fontObj), -1,
	TK_OPTION_NULL_OK,0,GEOMETRY_CHANGED },
    {TK_OPTION_COLOR, "-foreground", "textColor", "TextColor",
	"black", Tk_Offset(Progressbar,progress.foregroundObj), -1,
	TK_OPTION_NULL_OK,0,0 },
    {TK_OPTION_JUSTIFY, "-justify", "justify", "Justify",
	"left", Tk_Offset(Progressbar,progress.justifyObj), -1,
	TK_OPTION_NULL_OK,0,GEOMETRY_CHANGED },
    {TK_OPTION_PIXELS, "-length", "length", "Length",
        DEF_PROGRESSBAR_LENGTH, Tk_Offset(Progressbar,progress.lengthObj), -1,
	0, 0, GEOMETRY_CHANGED },
    {TK_OPTION_DOUBLE, "-maximum", "maximum", "Maximum",
	"100", Tk_Offset(Progressbar,progress.maximumObj), -1,
	0, 0, 0 },
    {TK_OPTION_STRING_TABLE, "-mode", "mode", "ProgressMode", "determinate",
	Tk_Offset(Progressbar,progress.modeObj),
	Tk_Offset(Progressbar,progress.mode),
	0, (ClientData)ProgressbarModeStrings, 0 },
    {TK_OPTION_STRING_TABLE, "-orient", "orient", "Orient",
	"horizontal", Tk_Offset(Progressbar,progress.orientObj), -1,
	0, (ClientData)ttkOrientStrings, STYLE_CHANGED },
    {TK_OPTION_INT, "-phase", "phase", "Phase",
	"0", Tk_Offset(Progressbar,progress.phaseObj), -1,
	0, 0, 0 },
    {TK_OPTION_STRING, "-text", "text", "Text", "",
	Tk_Offset(Progressbar,progress.textObj), -1,
	0,0,GEOMETRY_CHANGED },
    {TK_OPTION_DOUBLE, "-value", "value", "Value",
	"0.0", Tk_Offset(Progressbar,progress.valueObj), -1,
	0, 0, 0 },
    {TK_OPTION_STRING, "-variable", "variable", "Variable",
	NULL, Tk_Offset(Progressbar,progress.variableObj), -1,
	TK_OPTION_NULL_OK, 0, 0 },



    {TK_OPTION_PIXELS, "-wraplength", "wrapLength", "WrapLength",
	"0", Tk_Offset(Progressbar, progress.wrapLengthObj), -1,

	TK_OPTION_NULL_OK,0,GEOMETRY_CHANGED},

    WIDGET_TAKEFOCUS_FALSE,
    WIDGET_INHERIT_OPTIONS(ttkCoreOptionSpecs)
};

/*------------------------------------------------------------------------
 * +++ Animation procedures:

TTK_BEGIN_LAYOUT(VerticalProgressbarLayout)
    TTK_GROUP("Vertical.Progressbar.trough", TTK_FILL_BOTH,
	TTK_NODE("Vertical.Progressbar.pbar", TTK_PACK_BOTTOM|TTK_FILL_X))
TTK_END_LAYOUT

TTK_BEGIN_LAYOUT(HorizontalProgressbarLayout)
    TTK_GROUP("Horizontal.Progressbar.trough", TTK_FILL_BOTH,
	TTK_NODE("Horizontal.Progressbar.pbar", TTK_PACK_LEFT|TTK_FILL_Y)
	TTK_NODE("Horizontal.Progressbar.text", TTK_PACK_LEFT))
TTK_END_LAYOUT

/*
 * Initialization:
 */

MODULE_SCOPE

        # Progressbar
        ttk::style element create Horizontal.Progressbar.pbar vsapi \
            PROGRESS 3 {{} 1} -padding 8
        ttk::style layout Horizontal.TProgressbar {
            Horizontal.Progressbar.trough -sticky nswe -children {
                Horizontal.Progressbar.pbar -side left -sticky ns
                Horizontal.Progressbar.text -sticky nesw
            }
        }
        ttk::style element create Vertical.Progressbar.pbar vsapi \
            PROGRESS 3 {{} 1} -padding 8
        ttk::style layout Vertical.TProgressbar {
            Vertical.Progressbar.trough -sticky nswe -children {
                Vertical.Progressbar.pbar -side bottom -sticky we

    set PB		;# NOTREACHED
} -cleanup { unset PB } -returnCodes 1 -match glob -result "*YIPES!"

test progressbar-end "Cleanup" -body {
    destroy .pb
}

# check existence and default value of each non-core option of the widget
test progressbar-3.1 "progressbar non-core options" -setup {
    set res {}
    ttk::progressbar .defaultpb
} -body {
    foreach option {-anchor -foreground -justify -style -text -wraplength \
                    -length -maximum -mode -orient -phase -value -variable} {
        lappend res [.defaultpb cget $option]
    }
    set res
} -cleanup {
    unset res
    destroy .defaultpb
} -result {w black left {} {} 0 100 100 determinate horizontal 0 0.0 {}}

test progressbar-3.2 "TIP #442 options are taken into account" -setup {
    set res {}
    pack [ttk::progressbar .p -value 0 -maximum 50 -orient horizontal -mode determinate -length 500]
    set thefont [font actual {Arial 10}]
} -body {
    .p configure -anchor c -foreground blue -justify right \
            -text "TIP #442\noptions are now tested" -wraplength 100
    update
    .p step 10
    .p configure -anchor e -font $thefont -foreground green -justify center \
            -text "Changing the value of each option\nfrom TIP #442" -wraplength 250
    update
    .p step 20
    .p configure -orient vertical -text "Cannot be seen"
    update
    foreach option {-anchor -foreground -justify -text -wraplength} {
        lappend res [list $option [.p cget $option]]
    }
    set res
} -cleanup {
    unset res thefont
    destroy .p
} -result {{-anchor e} {-foreground green} {-justify center} {-text {Cannot be seen}} {-wraplength 250}}

tcltest::cleanupTests

    .t.b invoke
    list [winfo exists .t] [winfo exists .t.b]
} -result [list 0 0]

#
# Basic tests.
#
test ttk-1.1 "Create multiline button showing justified text" -body {
    pack [ttk::button .t -text "Hello\nWorld!!" -justify center] -expand true -fill both
    update
}

test ttk-1.2 "Check style" -body {
    .t cget -style
} -result {}