head	1.13;
access;
symbols
	core-8-5-9:1.10.2.2
	core-8-5-8:1.10
	macosx-cocoa-merge:1.13
	macosx-cocoa-premerge:1.13
	macosx-carbon-freeze:1.13
	core-8-5-7:1.10
	core-8-5-6:1.10
	core-8-6-b1:1.12
	core-8-6-a3:1.12
	core-8-5-5:1.10
	core-8-6-a2:1.11
	core-8-5-4:1.10
	core-8-5-3:1.10
	core-8-6-a1:1.10
	core-8-5-branch:1.10.0.2
	core-8-5-2:1.10
	core-8-5-1:1.10
	core-8-5-0:1.10
	core-8-5-b3:1.8
	core-8-5-b2:1.6
	core-8-5-b1:1.3
	core-stablilizer-merge:1.3
	core-stabilizer-branch:1.3.0.2
	core-stabilizer-merge:1.10
	core-8-5-a6:1.3;
locks; strict;
comment	@# @;


1.13
date	2009.02.16.09.30.26;	author dkf;	state Exp;
branches;
next	1.12;

1.12
date	2008.09.23.13.36.56;	author dkf;	state Exp;
branches;
next	1.11;

1.11
date	2008.06.30.22.57.03;	author dkf;	state Exp;
branches;
next	1.10;

1.10
date	2007.12.13.15.23.44;	author dgp;	state Exp;
branches
	1.10.2.1;
next	1.9;

1.9
date	2007.12.12.15.51.21;	author jenglish;	state Exp;
branches;
next	1.8;

1.8
date	2007.11.01.10.59.43;	author dkf;	state Exp;
branches;
next	1.7;

1.7
date	2007.10.29.16.04.14;	author dkf;	state Exp;
branches;
next	1.6;

1.6
date	2007.10.26.20.13.23;	author dgp;	state Exp;
branches;
next	1.5;

1.5
date	2007.10.23.15.44.36;	author dkf;	state Exp;
branches;
next	1.4;

1.4
date	2007.10.22.14.33.13;	author dkf;	state Exp;
branches;
next	1.3;

1.3
date	2006.12.13.23.04.33;	author hobbs;	state Exp;
branches
	1.3.2.1;
next	1.2;

1.2
date	2006.11.15.13.29.17;	author dkf;	state Exp;
branches;
next	1.1;

1.1
date	2006.10.31.01.42.25;	author hobbs;	state Exp;
branches;
next	;

1.3.2.1
date	2007.10.24.12.59.31;	author dgp;	state Exp;
branches;
next	1.3.2.2;

1.3.2.2
date	2007.10.27.04.23.14;	author dgp;	state Exp;
branches;
next	1.3.2.3;

1.3.2.3
date	2007.11.01.16.37.16;	author dgp;	state Exp;
branches;
next	1.3.2.4;

1.3.2.4
date	2007.12.13.06.28.47;	author dgp;	state Exp;
branches;
next	;

1.10.2.1
date	2010.03.09.04.20.56;	author hobbs;	state Exp;
branches;
next	1.10.2.2;

1.10.2.2
date	2010.08.26.02.06.09;	author hobbs;	state Exp;
branches;
next	;


desc
@@


1.13
log
@Apply some GOOBE to the ttk::intro(n) manpage. [Bug 2604420]
@
text
@'\"
'\" Copyright (c) 2004 Joe English
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.12 2008/09/23 13:36:56 dkf Exp $
'\" 
.so man.macros
.TH ttk::intro n 8.5 Tk "Tk Themed Widget"
.BS
.SH NAME
ttk::intro \- Introduction to the Tk theme engine
.BE
.SH "OVERVIEW"
.PP
The Tk themed widget set is based on a revised and enhanced version
of TIP #48 (http://tip.tcl.tk/48) specified style engine.
The main concepts are described below.
The basic idea is to separate, to the extent possible,
the code implementing a widget's behavior from
the code implementing its appearance.
Widget class bindings are primarily responsible for
maintaining the widget state and invoking callbacks;
all aspects of the widget's appearance are controlled by the style of
the widget (i.e. the style of the elements of the widget).
.SH "THEMES"
.PP
A \fItheme\fR is a collection of elements and styles 
that determine the look and feel of the widget set.
Themes can be used to:
.IP \(bu
isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)
.IP \(bu
adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
.IP \(bu
accessibility (high contrast, large type)
.IP \(bu
application suite branding
.IP \(bu
blend in with the rest of the desktop (Gnome, KDE, Java)
.IP \(bu
and, of course: eye candy.
.SH "ELEMENTS"
.PP
An \fIelement\fR displays an individual part of a widget.
For example, a vertical scrollbar widget contains \fBuparrow\fR,
\fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements.
.PP
Element names use a recursive dotted notation.
For example, \fBuparrow\fR identifies a generic arrow element,
and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify 
widget-specific elements.
When looking for an element, the style engine looks for
the specific name first, and if an element of that name is
not found it looks for generic elements by stripping off
successive leading components of the element name.
.PP
Like widgets, elements have \fIoptions\fR which
specify what to display and how to display it.
For example, the \fBtext\fR element 
(which displays a text string) has
\fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, 
\fB\-underline\fR, and \fB\-width\fR options.
The value of an element option is taken from:
.IP \(bu
an option of the same name and type in the widget containing the element;
.IP \(bu
a dynamic setting specified by \fBstyle map\fR and the current state;
.IP \(bu
the default setting specified by \fBstyle configure\fR; or
.IP \(bu
the element's built-in default value for the option.
.SH "LAYOUTS"
.PP
A \fIlayout\fR specifies which elements make up a widget
and how they are arranged.
The layout engine uses a simplified version of the \fBpack\fR
algorithm: starting with an initial cavity equal to the size
of the widget, elements are allocated a parcel within the cavity along
the side specified by the \fB\-side\fR option,
and placed within the parcel according to the \fB\-sticky\fR
option.
For example, the layout for a horizontal scrollbar is:
.PP
.CS
ttk::\fBstyle layout\fR Horizontal.TScrollbar {
    Scrollbar.trough \-children {
	Scrollbar.leftarrow \-side left \-sticky w
	Scrollbar.rightarrow \-side right \-sticky e
	Scrollbar.thumb \-side left \-expand true \-sticky ew
    }
}
.CE
.PP
By default, the layout for a widget is the same as its class name.
Some widgets may override this (for example, the \fBttk::scrollbar\fR
widget chooses different layouts based on the \fB\-orient\fR option).
.SH "STATES"
.PP
In standard Tk, many widgets have a \fB\-state\fR option
which (in most cases) is either \fBnormal\fR or \fBdisabled\fR.
Some widgets support additional states, such
as the \fBentry\fR widget which has a \fBreadonly\fR state
and the various flavors of buttons which have \fBactive\fR state.
.PP
The themed Tk widgets generalizes this idea:
every widget has a bitmap of independent state flags.
Widget state flags include \fBactive\fR, \fBdisabled\fR,
\fBpressed\fR, \fBfocus\fR, etc., 
(see \fIttk::widget(n)\fR for the full list of state flags).
.PP
Instead of a \fB\-state\fR option, every widget now has 
a \fBstate\fR widget command which is used to set or query
the state.
A \fIstate specification\fR is a list of symbolic state names
indicating which bits are set, each optionally prefixed with an 
exclamation point indicating that the bit is cleared instead.
.PP
For example, the class bindings for the \fBttk::button\fR
widget are:
.PP
.CS
bind TButton <Enter>		{ %W state active }
bind TButton <Leave>		{ %W state !active }
bind TButton <ButtonPress-1>	{ %W state pressed }
bind TButton <Button1-Leave>	{ %W state !pressed }
bind TButton <Button1-Enter>	{ %W state pressed }
bind TButton <ButtonRelease-1>	\e
    { %W instate {pressed} { %W state !pressed ; %W invoke } }
.CE
.PP
This specifies that the widget becomes \fBactive\fR when
the pointer enters the widget, and inactive when it leaves.
Similarly it becomes \fBpressed\fR when the mouse button is pressed,
and \fB!pressed\fR on the ButtonRelease event.
In addition, the button unpresses if 
pointer is dragged outside the widget while Button-1 is held down,
and represses if it's dragged back in.
Finally, when the mouse button is released, the widget's
\fB\-command\fR is invoked, but only if the button is currently
in the \fBpressed\fR state.
(The actual bindings are a little more complicated than the above,
but not by much).
'\" Note to self: rewrite that paragraph.  It's horrible.
.SH "STYLES"
.PP
Each widget is associated with a \fIstyle\fR, 
which specifies values for element options.
Style names use a recursive dotted notation like layouts and elements;
by default, widgets use the class name to look up a style in the current theme.
For example:
.PP
.CS
ttk::\fBstyle configure\fR TButton \e
	\-background #d9d9d9 \e
	\-foreground black \e
	\-relief raised \e
	;
.CE
.PP
Many elements are displayed differently depending on the widget state.  
For example, buttons have a different background when they are active,
a different foreground when disabled, and a different relief when pressed.
The \fBstyle map\fR command specifies dynamic option settings
for a particular style:
.PP
.CS
ttk::\fBstyle map\fR TButton \e
	\-background [list disabled #d9d9d9  active #ececec] \e
	\-foreground [list disabled #a3a3a3] \e
	\-relief [list {pressed !disabled} sunken] \e
	;
.CE
.SH "SEE ALSO"
ttk::widget(n), ttk::style(n)
'\" Local Variables:
'\" mode: nroff
'\" End:
@


1.12
log
@Fix [Bug 2118116]
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.11 2008/06/30 22:57:03 dkf Exp $
d25 2
a26 1
all aspects of the widgets appearance is
d33 1
a33 1
Isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)
d35 1
a35 1
Adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
d37 1
a37 1
Accessibility (high contrast, large type)
d39 1
a39 1
Application suite branding
d41 1
a41 1
Blend in with the rest of the desktop (Gnome, KDE, Java)
d43 1
a43 1
And, of course: eye candy.
d67 1
a67 1
An option of the same name and type in the widget containing the element;
d69 1
a69 1
A dynamic setting specified by \fBstyle map\fR and the current state;
d71 1
a71 1
The default setting specified by \fBstyle configure\fR; or
d73 1
a73 1
The element's built-in default value for the option.
d84 2
a85 1
For example, the layout for a horizontal scrollbar 
d87 1
a87 1
ttk::style layout Horizontal.TScrollbar {
d95 1
d122 1
d132 1
d145 1
a145 2
.PP
\fINote to self: rewrite that paragraph.  It's horrible.\fR
d153 1
d155 1
a155 1
ttk::style configure TButton \e
d161 1
d167 1
d169 1
a169 1
ttk::style map TButton \e
@


1.11
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@a0 1
'\" -*- nroff -*-
d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.10 2007/12/13 15:23:44 dgp Exp $
d170 3
@


1.10
log
@merge stable branch onto HEAD
@
text
@d1 1
d8 1
a8 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3.2.4 2007/12/13 06:28:47 dgp Exp $
d17 1
d28 1
d45 1
d75 1
d98 1
d144 1
@


1.10.2.1
log
@correct doc backport from head
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.10 2007/12/13 15:23:44 dgp Exp $
d24 1
a24 2
all aspects of the widget's appearance are controlled by the style of
the widget (i.e. the style of the elements of the widget).
@


1.10.2.2
log
@        Major backport of 8.6 Ttk for 8.5.9.  Most changes were only being
        committed to head (8.6), although they could apply for 8.5 as well.
        This re-sync makes future work easier to maintain and adds some
        useful work for 8.5 users. Notable changes:
        - Lots of code cleanup
        - Some bug fixes never backported
        - Addition of ttk::spinbox
        - minor color changes
        - Improved Vista/7 styling
        - Move to tile version 0.8.6 (pseudo-package)
        - ABI and API compatible (even $w identify)
        - minor new features (extended $w identify)
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.13 2009/02/16 09:30:26 dkf Exp $
a15 1
.PP
a26 1
.PP
d31 1
a31 1
isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)
d33 1
a33 1
adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
d35 1
a35 1
accessibility (high contrast, large type)
d37 1
a37 1
application suite branding
d39 1
a39 1
blend in with the rest of the desktop (Gnome, KDE, Java)
d41 1
a41 1
and, of course: eye candy.
a42 1
.PP
d64 1
a64 1
an option of the same name and type in the widget containing the element;
d66 1
a66 1
a dynamic setting specified by \fBstyle map\fR and the current state;
d68 1
a68 1
the default setting specified by \fBstyle configure\fR; or
d70 1
a70 1
the element's built-in default value for the option.
a71 1
.PP
d80 1
a80 2
For example, the layout for a horizontal scrollbar is:
.PP
d82 1
a82 1
ttk::\fBstyle layout\fR Horizontal.TScrollbar {
a89 1
.PP
a93 1
.PP
a114 1
.PP
a123 1
.PP
d136 2
a137 1
'\" Note to self: rewrite that paragraph.  It's horrible.
a138 1
.PP
a143 1
.PP
d145 1
a145 1
ttk::\fBstyle configure\fR TButton \e
a150 1
.PP
a155 1
.PP
d157 1
a157 1
ttk::\fBstyle map\fR TButton \e
a164 3
'\" Local Variables:
'\" mode: nroff
'\" End:
@


1.9
log
@Various minor updates to ttk_* manpages.
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.8 2007/11/01 10:59:43 dkf Exp $
@


1.8
log
@Make documentation use the name that scripts use as much as possible.
[Bug 1640073]
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.7 2007/10/29 16:04:14 dkf Exp $
d36 1
a36 2
Application suite
.QW branding
d48 1
a48 1
and \fBScrollbar.arrow\fR and \fBCombobox.uparrow\fR identify 
d61 3
a63 1
The value of an element resource is taken from:
d67 1
a67 3
An option of the same name and type in the widget containing the element;
.IP \(bu
The default setting specified by \fBstyle default\fR; or
d69 1
a69 1
The element's built-in default value for the resource.
d81 1
a81 1
style layout Horizontal.TScrollbar {
d90 1
a90 1
Some widgets may override this (for example, the \fBscrollbar\fR
d112 1
a112 1
For example, the class bindings for the \fBtbutton\fR
d139 1
a139 1
which specifies values for element resources.
d144 1
a144 1
style default TButton \e
d153 1
a153 1
The \fBstyle map\fR command specifies dynamic resources
d156 1
a156 1
style map TButton \e
@


1.7
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.6 2007/10/26 20:13:23 dgp Exp $
d10 1
a10 1
.TH ttk_intro n 8.5 Tk "Tk Themed Widget"
d13 1
a13 1
ttk_intro \- Introduction to the Tk theme engine
a14 1

a24 1

a41 1

a92 1

d104 1
a104 1
(see \fIttk_widget(n)\fR for the full list of state flags).
a137 1

a162 1

d164 1
a164 1
ttk_widget(n), ttk_style(n)
@


1.6
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $
d38 2
a39 1
Application suite "branding"
d63 2
a64 2
\fB-text\fR, \fB-font\fR, \fB-foreground\fR, \fB-background\fR, 
\fB-underline\fR, and \fB-width\fR options.
d80 2
a81 2
the side specified by the \fB-side\fR option,
and placed within the parcel according to the \fB-sticky\fR
d86 4
a89 4
    Scrollbar.trough -children {
	Scrollbar.leftarrow -side left -sticky w
	Scrollbar.rightarrow -side right -sticky e
	Scrollbar.thumb -side left -expand true -sticky ew
d95 1
a95 1
widget chooses different layouts based on the \fB-orient\fR option).
d98 1
a98 1
In standard Tk, many widgets have a \fB-state\fR option
d110 1
a110 1
Instead of a \fB-state\fR option, every widget now has 
d136 1
a136 1
\fB-command\fR is invoked, but only if the button is currently
d151 3
a153 3
	-background #d9d9d9 \e
	-foreground black \e
	-relief raised \e
d163 3
a165 3
	-background [list disabled #d9d9d9  active #ececec] \e
	-foreground [list disabled #a3a3a3] \e
	-relief [list {pressed !disabled} sunken] \e
@


1.5
log
@Rendering-with-groff GOOBE.
@
text
@d6 3
a8 3
'\"
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.4 2007/10/22 14:33:13 dkf Exp $
'\"
d17 10
a26 6
The Tk themed widget set is based on a revised and enhanced version of TIP #48
(http://tip.tcl.tk/48) specified style engine. The main concepts are described
below. The basic idea is to separate, to the extent possible, the code
implementing a widget's behavior from the code implementing its appearance.
Widget class bindings are primarily responsible for maintaining the widget
state and invoking callbacks; all aspects of the widgets appearance is
d28 3
a30 2
A \fItheme\fR is a collection of elements and styles that determine the look
and feel of the widget set. Themes can be used to:
d43 1
d45 11
a55 9
An \fIelement\fR displays an individual part of a widget. For example, a
vertical scrollbar widget contains \fBuparrow\fR, \fBdownarrow\fR,
\fBtrough\fR and \fBslider\fR elements.
.PP
Element names use a recursive dotted notation. For example, \fBuparrow\fR
identifies a generic arrow element, and \fBScrollbar.arrow\fR and
\fBCombobox.uparrow\fR identify widget-specific elements. When looking for an
element, the style engine looks for the specific name first, and if an element
of that name is not found it looks for generic elements by stripping off
d58 7
a64 5
Like widgets, elements have \fIoptions\fR which specify what to display and
how to display it. For example, the \fBtext\fR element (which displays a text
string) has \fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR,
\fB\-background\fR, \fB\-underline\fR, and \fB\-width\fR options. The value of
an element resource is taken from:
d74 9
a82 6
A \fIlayout\fR specifies which elements make up a widget and how they are
arranged. The layout engine uses a simplified version of the \fBpack\fR
algorithm: starting with an initial cavity equal to the size of the widget,
elements are allocated a parcel within the cavity along the side specified by
the \fB\-side\fR option, and placed within the parcel according to the
\fB\-sticky\fR option. For example, the layout for a horizontal scrollbar:
d86 3
a88 3
        Scrollbar.leftarrow -side left -sticky w
        Scrollbar.rightarrow -side right -sticky e
        Scrollbar.thumb -side left -expand true -sticky ew
d92 4
a95 3
By default, the layout for a widget is the same as its class name. Some
widgets may override this (for example, the \fBscrollbar\fR widget chooses
different layouts based on the \fB\-orient\fR option).
d97 18
a114 15
In standard Tk, many widgets have a \fB\-state\fR option which (in most cases)
is either \fBnormal\fR or \fBdisabled\fR. Some widgets support additional
states, such as the \fBentry\fR widget which has a \fBreadonly\fR state and
the various flavors of buttons which have \fBactive\fR state.
.PP
The themed Tk widgets generalizes this idea: every widget has a bitmap of
independent state flags. Widget state flags include \fBactive\fR,
\fBdisabled\fR, \fBpressed\fR, \fBfocus\fR, etc., (see \fIttk_widget(n)\fR for
the full list of state flags).
.PP
Instead of a \fB\-state\fR option, every widget now has a \fBstate\fR widget
command which is used to set or query the state. A \fIstate specification\fR
is a list of symbolic state names indicating which bits are set, each
optionally prefixed with an exclamation point indicating that the bit is
cleared instead.
d116 2
a117 1
For example, the class bindings for the \fBttk::button\fR widget are:
d119 6
a124 6
bind TButton <Enter>            { %W state active }
bind TButton <Leave>            { %W state !active }
bind TButton <ButtonPress-1>    { %W state pressed }
bind TButton <Button1-Leave>    { %W state !pressed }
bind TButton <Button1-Enter>    { %W state pressed }
bind TButton <ButtonRelease-1>  \e
d127 12
a138 9
This specifies that the widget becomes \fBactive\fR when the pointer enters
the widget, and inactive when it leaves. Similarly it becomes \fBpressed\fR
when the mouse button is pressed, and \fB!pressed\fR on the ButtonRelease
event. In addition, the button unpresses if pointer is dragged outside the
widget while Button-1 is held down, and represses if it's dragged back in.
Finally, when the mouse button is released, the widget's \fB\-command\fR is
invoked, but only if the button is currently in the \fBpressed\fR state. (The
actual bindings are a little more complicated than the above, but not by
much).
d140 2
a141 1
\fINote to self: rewrite that paragraph. It's horrible.\fR
d143 5
a147 4
Each widget is associated with a \fIstyle\fR, which specifies values for
element resources. Style names use a recursive dotted notation like layouts
and elements; by default, widgets use the class name to look up a style in the
current theme. For example:
d150 4
a153 4
        -background #d9d9d9 \e
        -foreground black \e
        -relief raised \e
        ;
d155 5
a159 4
Many elements are displayed differently depending on the widget state. For
example, buttons have a different background when they are active, a different
foreground when disabled, and a different relief when pressed. The \fBstyle
map\fR command specifies dynamic resources for a particular style:
d162 4
a165 4
        -background [list disabled #d9d9d9  active #ececec] \e
        -foreground [list disabled #a3a3a3] \e
        -relief [list {pressed !disabled} sunken] \e
        ;
d167 1
@


1.4
log
@Documentation improvements, all minor.
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $
a22 1

a37 1

d73 3
a75 3
	Scrollbar.leftarrow -side left -sticky w
	Scrollbar.rightarrow -side right -sticky e
	Scrollbar.thumb -side left -expand true -sticky ew
d81 1
a81 2
different layouts based on the \fB-orient\fR option).

d101 6
a106 6
bind TButton <Enter>		{ %W state active }
bind TButton <Leave>		{ %W state !active }
bind TButton <ButtonPress-1>	{ %W state pressed }
bind TButton <Button1-Leave>	{ %W state !pressed }
bind TButton <Button1-Enter>	{ %W state pressed }
bind TButton <ButtonRelease-1>	\e
a119 1

d127 4
a130 4
	-background #d9d9d9 \e
	-foreground black \e
	-relief raised \e
	;
d138 4
a141 4
	-background [list disabled #d9d9d9  active #ececec] \e
	-foreground [list disabled #a3a3a3] \e
	-relief [list {pressed !disabled} sunken] \e
	;
a142 1

@


1.3
log
@	* unix/Makefile.in (install-doc): intentionally skip ttk_dialog.n
	installation (not for public consumption)

	* doc/scrollbar.n, doc/button.n, doc/checkbutton.n:
	* doc/entry.n, doc/frame.n, doc/label.n, doc/labelframe.n:
	* doc/menu.n, doc/menubutton.n, doc/panedwindow.n:
	* doc/radiobutton.n, doc/scrollbar.n, doc/ttk_*: revamp ttk docs
	to use consist nroff format (not 100% consistent with classic
	widget docs).  Add more man page cross-linking "SEE ALSO".
@
text
@d6 3
a8 3
'\" 
'\" RCS: @@(#) $Id: popup.n,v 1.4 2004/06/21 20:59:29 dkf Exp $
'\" 
d17 6
a22 9
The Tk themed widget set is based on a revised and enhanced version
of TIP #48 (http://tip.tcl.tk/48) specified style engine.
The main concepts are described below.
The basic idea is to separate, to the extent possible,
the code implementing a widget's behavior from
the code implementing its appearance.
Widget class bindings are primarily responsible for
maintaining the widget state and invoking callbacks;
all aspects of the widgets appearance is
d25 2
a26 3
A \fItheme\fR is a collection of elements and styles 
that determine the look and feel of the widget set.
Themes can be used to:
d41 9
a49 11
An \fIelement\fR displays an individual part of a widget.
For example, a vertical scrollbar widget contains \fBuparrow\fR,
\fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements.
.PP
Element names use a recursive dotted notation.
For example, \fBuparrow\fR identifies a generic arrow element,
and \fBScrollbar.arrow\fR and \fBCombobox.uparrow\fR identify 
widget-specific elements.
When looking for an element, the style engine looks for
the specific name first, and if an element of that name is
not found it looks for generic elements by stripping off
d52 5
a56 7
Like widgets, elements have \fIoptions\fR which
specify what to display and how to display it.
For example, the \fBtext\fR element 
(which displays a text string) has
\fB-text\fR, \fB-font\fR, \fB-foreground\fR, \fB-background\fR, 
\fB-underline\fR, and \fB-width\fR options.
The value of an element resource is taken from:
d66 6
a71 9
A \fIlayout\fR specifies which elements make up a widget
and how they are arranged.
The layout engine uses a simplified version of the \fBpack\fR
algorithm: starting with an initial cavity equal to the size
of the widget, elements are allocated a parcel within the cavity along
the side specified by the \fB-side\fR option,
and placed within the parcel according to the \fB-sticky\fR
option.
For example, the layout for a horizontal scrollbar 
d81 3
a83 3
By default, the layout for a widget is the same as its class name.
Some widgets may override this (for example, the \fBscrollbar\fR
widget chooses different layouts based on the \fB-orient\fR option).
d86 15
a100 18
In standard Tk, many widgets have a \fB-state\fR option
which (in most cases) is either \fBnormal\fR or \fBdisabled\fR.
Some widgets support additional states, such
as the \fBentry\fR widget which has a \fBreadonly\fR state
and the various flavors of buttons which have \fBactive\fR state.
.PP
The themed Tk widgets generalizes this idea:
every widget has a bitmap of independent state flags.
Widget state flags include \fBactive\fR, \fBdisabled\fR,
\fBpressed\fR, \fBfocus\fR, etc., 
(see \fIttk_widget(n)\fR for the full list of state flags).
.PP
Instead of a \fB-state\fR option, every widget now has 
a \fBstate\fR widget command which is used to set or query
the state.
A \fIstate specification\fR is a list of symbolic state names
indicating which bits are set, each optionally prefixed with an 
exclamation point indicating that the bit is cleared instead.
d102 1
a102 2
For example, the class bindings for the \fBtbutton\fR
widget are:
d112 9
a120 12
This specifies that the widget becomes \fBactive\fR when
the pointer enters the widget, and inactive when it leaves.
Similarly it becomes \fBpressed\fR when the mouse button is pressed,
and \fB!pressed\fR on the ButtonRelease event.
In addition, the button unpresses if 
pointer is dragged outside the widget while Button-1 is held down,
and represses if it's dragged back in.
Finally, when the mouse button is released, the widget's
\fB-command\fR is invoked, but only if the button is currently
in the \fBpressed\fR state.
(The actual bindings are a little more complicated than the above,
but not by much).
d122 1
a122 1
\fINote to self: rewrite that paragraph.  It's horrible.\fR
d125 4
a128 5
Each widget is associated with a \fIstyle\fR, 
which specifies values for element resources.
Style names use a recursive dotted notation like layouts and elements;
by default, widgets use the class name to look up a style in the current theme.
For example:
d136 4
a139 5
Many elements are displayed differently depending on the widget state.  
For example, buttons have a different background when they are active,
a different foreground when disabled, and a different relief when pressed.
The \fBstyle map\fR command specifies dynamic resources
for a particular style:
@


1.3.2.1
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $
d17 10
a26 6
The Tk themed widget set is based on a revised and enhanced version of TIP #48
(http://tip.tcl.tk/48) specified style engine. The main concepts are described
below. The basic idea is to separate, to the extent possible, the code
implementing a widget's behavior from the code implementing its appearance.
Widget class bindings are primarily responsible for maintaining the widget
state and invoking callbacks; all aspects of the widgets appearance is
d28 3
a30 2
A \fItheme\fR is a collection of elements and styles that determine the look
and feel of the widget set. Themes can be used to:
d43 1
d45 11
a55 9
An \fIelement\fR displays an individual part of a widget. For example, a
vertical scrollbar widget contains \fBuparrow\fR, \fBdownarrow\fR,
\fBtrough\fR and \fBslider\fR elements.
.PP
Element names use a recursive dotted notation. For example, \fBuparrow\fR
identifies a generic arrow element, and \fBScrollbar.arrow\fR and
\fBCombobox.uparrow\fR identify widget-specific elements. When looking for an
element, the style engine looks for the specific name first, and if an element
of that name is not found it looks for generic elements by stripping off
d58 7
a64 5
Like widgets, elements have \fIoptions\fR which specify what to display and
how to display it. For example, the \fBtext\fR element (which displays a text
string) has \fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR,
\fB\-background\fR, \fB\-underline\fR, and \fB\-width\fR options. The value of
an element resource is taken from:
d74 9
a82 6
A \fIlayout\fR specifies which elements make up a widget and how they are
arranged. The layout engine uses a simplified version of the \fBpack\fR
algorithm: starting with an initial cavity equal to the size of the widget,
elements are allocated a parcel within the cavity along the side specified by
the \fB\-side\fR option, and placed within the parcel according to the
\fB\-sticky\fR option. For example, the layout for a horizontal scrollbar:
d86 3
a88 3
        Scrollbar.leftarrow -side left -sticky w
        Scrollbar.rightarrow -side right -sticky e
        Scrollbar.thumb -side left -expand true -sticky ew
d92 4
a95 3
By default, the layout for a widget is the same as its class name. Some
widgets may override this (for example, the \fBscrollbar\fR widget chooses
different layouts based on the \fB\-orient\fR option).
d97 18
a114 15
In standard Tk, many widgets have a \fB\-state\fR option which (in most cases)
is either \fBnormal\fR or \fBdisabled\fR. Some widgets support additional
states, such as the \fBentry\fR widget which has a \fBreadonly\fR state and
the various flavors of buttons which have \fBactive\fR state.
.PP
The themed Tk widgets generalizes this idea: every widget has a bitmap of
independent state flags. Widget state flags include \fBactive\fR,
\fBdisabled\fR, \fBpressed\fR, \fBfocus\fR, etc., (see \fIttk_widget(n)\fR for
the full list of state flags).
.PP
Instead of a \fB\-state\fR option, every widget now has a \fBstate\fR widget
command which is used to set or query the state. A \fIstate specification\fR
is a list of symbolic state names indicating which bits are set, each
optionally prefixed with an exclamation point indicating that the bit is
cleared instead.
d116 2
a117 1
For example, the class bindings for the \fBttk::button\fR widget are:
d119 6
a124 6
bind TButton <Enter>            { %W state active }
bind TButton <Leave>            { %W state !active }
bind TButton <ButtonPress-1>    { %W state pressed }
bind TButton <Button1-Leave>    { %W state !pressed }
bind TButton <Button1-Enter>    { %W state pressed }
bind TButton <ButtonRelease-1>  \e
d127 12
a138 9
This specifies that the widget becomes \fBactive\fR when the pointer enters
the widget, and inactive when it leaves. Similarly it becomes \fBpressed\fR
when the mouse button is pressed, and \fB!pressed\fR on the ButtonRelease
event. In addition, the button unpresses if pointer is dragged outside the
widget while Button-1 is held down, and represses if it's dragged back in.
Finally, when the mouse button is released, the widget's \fB\-command\fR is
invoked, but only if the button is currently in the \fBpressed\fR state. (The
actual bindings are a little more complicated than the above, but not by
much).
d140 2
a141 1
\fINote to self: rewrite that paragraph. It's horrible.\fR
d143 5
a147 4
Each widget is associated with a \fIstyle\fR, which specifies values for
element resources. Style names use a recursive dotted notation like layouts
and elements; by default, widgets use the class name to look up a style in the
current theme. For example:
d150 4
a153 4
        -background #d9d9d9 \e
        -foreground black \e
        -relief raised \e
        ;
d155 5
a159 4
Many elements are displayed differently depending on the widget state. For
example, buttons have a different background when they are active, a different
foreground when disabled, and a different relief when pressed. The \fBstyle
map\fR command specifies dynamic resources for a particular style:
d162 4
a165 4
        -background [list disabled #d9d9d9  active #ececec] \e
        -foreground [list disabled #a3a3a3] \e
        -relief [list {pressed !disabled} sunken] \e
        ;
d167 1
@


1.3.2.2
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3.2.1 2007/10/24 12:59:31 dgp Exp $
d17 6
a22 10
The Tk themed widget set is based on a revised and enhanced version
of TIP #48 (http://tip.tcl.tk/48) specified style engine.
The main concepts are described below.
The basic idea is to separate, to the extent possible,
the code implementing a widget's behavior from
the code implementing its appearance.
Widget class bindings are primarily responsible for
maintaining the widget state and invoking callbacks;
all aspects of the widgets appearance is

d24 2
a25 3
A \fItheme\fR is a collection of elements and styles 
that determine the look and feel of the widget set.
Themes can be used to:
a37 1

d39 9
a47 11
An \fIelement\fR displays an individual part of a widget.
For example, a vertical scrollbar widget contains \fBuparrow\fR,
\fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements.
.PP
Element names use a recursive dotted notation.
For example, \fBuparrow\fR identifies a generic arrow element,
and \fBScrollbar.arrow\fR and \fBCombobox.uparrow\fR identify 
widget-specific elements.
When looking for an element, the style engine looks for
the specific name first, and if an element of that name is
not found it looks for generic elements by stripping off
d50 5
a54 7
Like widgets, elements have \fIoptions\fR which
specify what to display and how to display it.
For example, the \fBtext\fR element 
(which displays a text string) has
\fB-text\fR, \fB-font\fR, \fB-foreground\fR, \fB-background\fR, 
\fB-underline\fR, and \fB-width\fR options.
The value of an element resource is taken from:
d64 6
a69 9
A \fIlayout\fR specifies which elements make up a widget
and how they are arranged.
The layout engine uses a simplified version of the \fBpack\fR
algorithm: starting with an initial cavity equal to the size
of the widget, elements are allocated a parcel within the cavity along
the side specified by the \fB-side\fR option,
and placed within the parcel according to the \fB-sticky\fR
option.
For example, the layout for a horizontal scrollbar 
d73 3
a75 3
	Scrollbar.leftarrow -side left -sticky w
	Scrollbar.rightarrow -side right -sticky e
	Scrollbar.thumb -side left -expand true -sticky ew
d79 3
a81 4
By default, the layout for a widget is the same as its class name.
Some widgets may override this (for example, the \fBscrollbar\fR
widget chooses different layouts based on the \fB-orient\fR option).

d83 15
a97 18
In standard Tk, many widgets have a \fB-state\fR option
which (in most cases) is either \fBnormal\fR or \fBdisabled\fR.
Some widgets support additional states, such
as the \fBentry\fR widget which has a \fBreadonly\fR state
and the various flavors of buttons which have \fBactive\fR state.
.PP
The themed Tk widgets generalizes this idea:
every widget has a bitmap of independent state flags.
Widget state flags include \fBactive\fR, \fBdisabled\fR,
\fBpressed\fR, \fBfocus\fR, etc., 
(see \fIttk_widget(n)\fR for the full list of state flags).
.PP
Instead of a \fB-state\fR option, every widget now has 
a \fBstate\fR widget command which is used to set or query
the state.
A \fIstate specification\fR is a list of symbolic state names
indicating which bits are set, each optionally prefixed with an 
exclamation point indicating that the bit is cleared instead.
d99 1
a99 2
For example, the class bindings for the \fBtbutton\fR
widget are:
d101 6
a106 6
bind TButton <Enter>		{ %W state active }
bind TButton <Leave>		{ %W state !active }
bind TButton <ButtonPress-1>	{ %W state pressed }
bind TButton <Button1-Leave>	{ %W state !pressed }
bind TButton <Button1-Enter>	{ %W state pressed }
bind TButton <ButtonRelease-1>	\e
d109 9
a117 12
This specifies that the widget becomes \fBactive\fR when
the pointer enters the widget, and inactive when it leaves.
Similarly it becomes \fBpressed\fR when the mouse button is pressed,
and \fB!pressed\fR on the ButtonRelease event.
In addition, the button unpresses if 
pointer is dragged outside the widget while Button-1 is held down,
and represses if it's dragged back in.
Finally, when the mouse button is released, the widget's
\fB-command\fR is invoked, but only if the button is currently
in the \fBpressed\fR state.
(The actual bindings are a little more complicated than the above,
but not by much).
d119 1
a119 2
\fINote to self: rewrite that paragraph.  It's horrible.\fR

d121 4
a124 5
Each widget is associated with a \fIstyle\fR, 
which specifies values for element resources.
Style names use a recursive dotted notation like layouts and elements;
by default, widgets use the class name to look up a style in the current theme.
For example:
d127 4
a130 4
	-background #d9d9d9 \e
	-foreground black \e
	-relief raised \e
	;
d132 4
a135 5
Many elements are displayed differently depending on the widget state.  
For example, buttons have a different background when they are active,
a different foreground when disabled, and a different relief when pressed.
The \fBstyle map\fR command specifies dynamic resources
for a particular style:
d138 4
a141 4
	-background [list disabled #d9d9d9  active #ececec] \e
	-foreground [list disabled #a3a3a3] \e
	-relief [list {pressed !disabled} sunken] \e
	;
a142 1

@


1.3.2.3
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id$
d10 1
a10 1
.TH ttk::intro n 8.5 Tk "Tk Themed Widget"
d13 1
a13 1
ttk::intro \- Introduction to the Tk theme engine
d15 1
d26 1
d38 1
a38 2
Application suite
.QW branding
d43 1
d62 2
a63 2
\fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, \fB\-background\fR, 
\fB\-underline\fR, and \fB\-width\fR options.
d79 2
a80 2
the side specified by the \fB\-side\fR option,
and placed within the parcel according to the \fB\-sticky\fR
d85 4
a88 4
    Scrollbar.trough \-children {
	Scrollbar.leftarrow \-side left \-sticky w
	Scrollbar.rightarrow \-side right \-sticky e
	Scrollbar.thumb \-side left \-expand true \-sticky ew
d94 2
a95 1
widget chooses different layouts based on the \fB\-orient\fR option).
d97 1
a97 1
In standard Tk, many widgets have a \fB\-state\fR option
d107 1
a107 1
(see \fIttk::widget(n)\fR for the full list of state flags).
d109 1
a109 1
Instead of a \fB\-state\fR option, every widget now has 
d135 1
a135 1
\fB\-command\fR is invoked, but only if the button is currently
d141 1
d150 3
a152 3
	\-background #d9d9d9 \e
	\-foreground black \e
	\-relief raised \e
d162 3
a164 3
	\-background [list disabled #d9d9d9  active #ececec] \e
	\-foreground [list disabled #a3a3a3] \e
	\-relief [list {pressed !disabled} sunken] \e
d167 1
d169 1
a169 1
ttk::widget(n), ttk::style(n)
@


1.3.2.4
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: ttk_intro.n,v 1.3.2.3 2007/11/01 16:37:16 dgp Exp $
d36 2
a37 1
Application suite branding
d49 1
a49 1
and \fBScrollbar.uparrow\fR and \fBCombobox.uparrow\fR identify 
d62 3
a64 1
The value of an element option is taken from:
d68 1
a68 3
A dynamic setting specified by \fBstyle map\fR and the current state;
.IP \(bu
The default setting specified by \fBstyle configure\fR; or
d70 1
a70 1
The element's built-in default value for the option.
d82 1
a82 1
ttk::style layout Horizontal.TScrollbar {
d91 1
a91 1
Some widgets may override this (for example, the \fBttk::scrollbar\fR
d113 1
a113 1
For example, the class bindings for the \fBttk::button\fR
d140 1
a140 1
which specifies values for element options.
d145 1
a145 1
ttk::style configure TButton \e
d154 1
a154 1
The \fBstyle map\fR command specifies dynamic option settings
d157 1
a157 1
ttk::style map TButton \e
@


1.2
log
@Convert \fP to \fR so that man-page scrapers have an easier time.
@
text
@d4 5
d15 1
d26 1
d107 1
a107 1
(see \fIwidget(n)\fR for the full list of state flags).
d141 1
d167 1
d169 1
a169 1
widget(n), style(n)
@


1.1
log
@	* doc/ttk_Geometry.3, doc/ttk_Theme.3, doc/ttk_button.n:
	* doc/ttk_checkbutton.n, doc/ttk_combobox.n, doc/ttk_dialog.n:
	* doc/ttk_entry.n, doc/ttk_frame.n, doc/ttk_image.n:
	* doc/ttk_intro.n, doc/ttk_label.n, doc/ttk_labelframe.n:
	* doc/ttk_menubutton.n, doc/ttk_notebook.n, doc/ttk_panedwindow.n:
	* doc/ttk_progressbar.n, doc/ttk_radiobutton.n, doc/ttk_scrollbar.n:
	* doc/ttk_separator.n, doc/ttk_sizegrip.n, doc/ttk_style.n:
	* doc/ttk_treeview.n, doc/ttk_widget.n,:
	* generic/ttk/ttk.decls, generic/ttk/ttkBlink.c:
	* generic/ttk/ttkButton.c, generic/ttk/ttkCache.c:
	* generic/ttk/ttkClamTheme.c, generic/ttk/ttkClassicTheme.c:
	* generic/ttk/ttkDecls.h, generic/ttk/ttkDefaultTheme.c:
	* generic/ttk/ttkElements.c, generic/ttk/ttkEntry.c:
	* generic/ttk/ttkFrame.c, generic/ttk/ttkImage.c:
	* generic/ttk/ttkInit.c, generic/ttk/ttkLabel.c:
	* generic/ttk/ttkLayout.c, generic/ttk/ttkManager.c:
	* generic/ttk/ttkManager.h, generic/ttk/ttkNotebook.c:
	* generic/ttk/ttkPanedwindow.c, generic/ttk/ttkProgress.c:
	* generic/ttk/ttkScale.c, generic/ttk/ttkScroll.c:
	* generic/ttk/ttkScrollbar.c, generic/ttk/ttkSeparator.c:
	* generic/ttk/ttkSquare.c, generic/ttk/ttkState.c:
	* generic/ttk/ttkStubInit.c, generic/ttk/ttkStubLib.c:
	* generic/ttk/ttkTagSet.c, generic/ttk/ttkTheme.c:
	* generic/ttk/ttkTheme.h, generic/ttk/ttkThemeInt.h:
	* generic/ttk/ttkTrace.c, generic/ttk/ttkTrack.c:
	* generic/ttk/ttkTreeview.c, generic/ttk/ttkWidget.c:
	* generic/ttk/ttkWidget.h:
	* library/demos/ttk_demo.tcl, library/demos/ttk_iconlib.tcl:
	* library/demos/ttk_repeater.tcl:
	* library/ttk/altTheme.tcl, library/ttk/aquaTheme.tcl:
	* library/ttk/button.tcl, library/ttk/clamTheme.tcl:
	* library/ttk/classicTheme.tcl, library/ttk/combobox.tcl:
	* library/ttk/cursors.tcl, library/ttk/defaults.tcl:
	* library/ttk/dialog.tcl, library/ttk/entry.tcl:
	* library/ttk/fonts.tcl, library/ttk/icons.tcl:
	* library/ttk/keynav.tcl, library/ttk/menubutton.tcl:
	* library/ttk/notebook.tcl, library/ttk/panedwindow.tcl:
	* library/ttk/progress.tcl, library/ttk/scale.tcl:
	* library/ttk/scrollbar.tcl, library/ttk/sizegrip.tcl:
	* library/ttk/treeview.tcl, library/ttk/ttk.tcl:
	* library/ttk/utils.tcl, library/ttk/winTheme.tcl:
	* library/ttk/xpTheme.tcl:
	* macosx/ttkMacOSXTheme.c:
	* tests/ttk/all.tcl, tests/ttk/bwidget.test, tests/ttk/combobox.test:
	* tests/ttk/entry.test, tests/ttk/image.test:
	* tests/ttk/labelframe.test, tests/ttk/layout.test:
	* tests/ttk/misc.test, tests/ttk/notebook.test:
	* tests/ttk/panedwindow.test, tests/ttk/progressbar.test:
	* tests/ttk/scrollbar.test, tests/ttk/treetags.test:
	* tests/ttk/treeview.test, tests/ttk/ttk.test, tests/ttk/validate.test:
	* win/ttkWinMonitor.c, win/ttkWinTheme.c, win/ttkWinXPTheme.c:
	First import of Ttk themed Tk widgets as branched from tile 0.7.8

	* generic/tkInt.h, generic/tkWindow.c: add Ttk_Init call, copy
	tk classic widgets to ::tk namespace.
	* library/tk.tcl: add source of ttk/ttk.tcl, define $::ttk::library.
	* unix/Makefile.in, win/Makefile.in: add Ttk build bits
	* win/configure, win/configure.in: check for uxtheme.h (XP theme).
@
text
@d150 1
a150 1
The \fBstyle map\fP command specifies dynamic resources
@

