summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog5
-rw-r--r--doc/ttk_intro.n43
2 files changed, 30 insertions, 18 deletions
diff --git a/ChangeLog b/ChangeLog
index 1257cb1..516ce54 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-02-16 Donal K. Fellows <dkf@users.sf.net>
+
+ * doc/ttk_intro.n: [Bug 2604420]: Improve wording so that this page
+ feels less obviously incomplete.
+
2009-02-12 Donal K. Fellows <dkf@users.sf.net>
* library/iconlist.tcl: Split out the IconList megawidget from
diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n
index 1a8dd51..9572a2e 100644
--- a/doc/ttk_intro.n
+++ b/doc/ttk_intro.n
@@ -4,7 +4,7 @@
'\" 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 $
+'\" RCS: @(#) $Id: ttk_intro.n,v 1.13 2009/02/16 09:30:26 dkf Exp $
'\"
.so man.macros
.TH ttk::intro n 8.5 Tk "Tk Themed Widget"
@@ -22,24 +22,25 @@ 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
+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 ...)
+isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...)
.IP \(bu
-Adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
+adapt to display limitations (low-color, grayscale, monochrome, tiny screens)
.IP \(bu
-Accessibility (high contrast, large type)
+accessibility (high contrast, large type)
.IP \(bu
-Application suite branding
+application suite branding
.IP \(bu
-Blend in with the rest of the desktop (Gnome, KDE, Java)
+blend in with the rest of the desktop (Gnome, KDE, Java)
.IP \(bu
-And, of course: eye candy.
+and, of course: eye candy.
.SH "ELEMENTS"
.PP
An \fIelement\fR displays an individual part of a widget.
@@ -63,13 +64,13 @@ For example, the \fBtext\fR element
\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;
+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;
+a dynamic setting specified by \fBstyle map\fR and the current state;
.IP \(bu
-The default setting specified by \fBstyle configure\fR; or
+the default setting specified by \fBstyle configure\fR; or
.IP \(bu
-The element's built-in default value for the option.
+the element's built-in default value for the option.
.SH "LAYOUTS"
.PP
A \fIlayout\fR specifies which elements make up a widget
@@ -80,9 +81,10 @@ 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
+For example, the layout for a horizontal scrollbar is:
+.PP
.CS
-ttk::style layout Horizontal.TScrollbar {
+ttk::\fBstyle layout\fR Horizontal.TScrollbar {
Scrollbar.trough \-children {
Scrollbar.leftarrow \-side left \-sticky w
Scrollbar.rightarrow \-side right \-sticky e
@@ -90,6 +92,7 @@ ttk::style layout Horizontal.TScrollbar {
}
}
.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).
@@ -116,6 +119,7 @@ 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 }
@@ -125,6 +129,7 @@ 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,
@@ -137,8 +142,7 @@ Finally, when the mouse button is released, the widget's
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
+'\" Note to self: rewrite that paragraph. It's horrible.
.SH "STYLES"
.PP
Each widget is associated with a \fIstyle\fR,
@@ -146,20 +150,23 @@ 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::style configure TButton \e
+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::style map TButton \e
+ttk::\fBstyle map\fR TButton \e
\-background [list disabled #d9d9d9 active #ececec] \e
\-foreground [list disabled #a3a3a3] \e
\-relief [list {pressed !disabled} sunken] \e