summaryrefslogtreecommitdiffstats
path: root/doc/ttk_intro.n
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2007-10-26 20:13:21 (GMT)
committerdgp <dgp@users.sourceforge.net>2007-10-26 20:13:21 (GMT)
commitc19dbf2054468ec3004041fef41a4b01a465eb54 (patch)
tree8355bd802491be2c1de242e0598914b0bb36fca5 /doc/ttk_intro.n
parent7eb434043e09e028ca9af4dc444bcf3dd63b3c10 (diff)
downloadtk-c19dbf2054468ec3004041fef41a4b01a465eb54.zip
tk-c19dbf2054468ec3004041fef41a4b01a465eb54.tar.gz
tk-c19dbf2054468ec3004041fef41a4b01a465eb54.tar.bz2
* doc/*.1: Revert doc changes that broke
* doc/*.3: `make html` so we can get the release * doc/*.n: out the door.
Diffstat (limited to 'doc/ttk_intro.n')
-rw-r--r--doc/ttk_intro.n189
1 files changed, 107 insertions, 82 deletions
diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n
index 4a96e66..064cc7a 100644
--- a/doc/ttk_intro.n
+++ b/doc/ttk_intro.n
@@ -3,9 +3,9 @@
'\"
'\" 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.5 2007/10/23 15:44:36 dkf Exp $
-'\"
+'\"
+'\" RCS: @(#) $Id: ttk_intro.n,v 1.6 2007/10/26 20:13:23 dgp Exp $
+'\"
.so man.macros
.TH ttk_intro n 8.5 Tk "Tk Themed Widget"
.BS
@@ -14,15 +14,20 @@ ttk_intro \- Introduction to the Tk theme engine
.BE
.SH "OVERVIEW"
-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
+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
+
.SH "THEMES"
-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:
+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
@@ -35,23 +40,28 @@ Application suite "branding"
Blend in with the rest of the desktop (Gnome, KDE, Java)
.IP \(bu
And, of course: eye candy.
+
.SH "ELEMENTS"
-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.
+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
+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
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 resource is taken from:
+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:
.IP \(bu
A dynamic setting specified by \fBstyle map\fR and the current state;
.IP \(bu
@@ -61,84 +71,99 @@ The default setting specified by \fBstyle default\fR; or
.IP \(bu
The element's built-in default value for the resource.
.SH "LAYOUTS"
-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:
+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
.CS
style layout 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
+ Scrollbar.leftarrow -side left -sticky w
+ Scrollbar.rightarrow -side right -sticky e
+ Scrollbar.thumb -side left -expand true -sticky ew
}
}
.CE
-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).
+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).
+
.SH "STATES"
-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.
+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).
+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.
+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:
+For example, the class bindings for the \fBtbutton\fR
+widget are:
.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
+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
-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).
+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).
.PP
-\fINote to self: rewrite that paragraph. It's horrible.\fR
+\fINote to self: rewrite that paragraph. It's horrible.\fR
+
.SH "STYLES"
-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:
+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:
.CS
style default TButton \e
- -background #d9d9d9 \e
- -foreground black \e
- -relief raised \e
- ;
+ -background #d9d9d9 \e
+ -foreground black \e
+ -relief raised \e
+ ;
.CE
-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:
+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:
.CS
style map TButton \e
- -background [list disabled #d9d9d9 active #ececec] \e
- -foreground [list disabled #a3a3a3] \e
- -relief [list {pressed !disabled} sunken] \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)