summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2009-12-25 18:28:17 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2009-12-25 18:28:17 (GMT)
commit5951d917af47ce8a6067ce7433a69a3549f7efca (patch)
tree9ecc144f7f46fbecd3e94feb3329492e3a3c880d /doc
parenteadda61039f9bbda73ee32ded65f915b3ed27523 (diff)
downloadtk-5951d917af47ce8a6067ce7433a69a3549f7efca.zip
tk-5951d917af47ce8a6067ce7433a69a3549f7efca.tar.gz
tk-5951d917af47ce8a6067ce7433a69a3549f7efca.tar.bz2
[Bug 2914943]: Correct the first option(n) example.
Also define what the format of option patterns is; that's a much less commonly known fact than it used to be.
Diffstat (limited to 'doc')
-rw-r--r--doc/option.n47
1 files changed, 40 insertions, 7 deletions
diff --git a/doc/option.n b/doc/option.n
index be87208..1262b9f 100644
--- a/doc/option.n
+++ b/doc/option.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: option.n,v 1.7 2007/12/13 15:23:43 dgp Exp $
+'\" RCS: @(#) $Id: option.n,v 1.7.2.1 2009/12/25 18:28:17 dkf Exp $
'\"
.so man.macros
.TH option n "" Tk "Tk Built-In Commands"
@@ -21,7 +21,6 @@ option \- Add/retrieve window options to/from the option database
\fBoption readfile \fIfileName \fR?\fIpriority\fR?
.fi
.BE
-
.SH DESCRIPTION
.PP
The \fBoption\fR command allows you to add entries to the Tk option
@@ -29,7 +28,8 @@ database or to retrieve options from the database. The \fBadd\fR
form of the command adds a new option to the database.
\fIPattern\fR contains
the option being specified, and consists of names and/or classes
-separated by asterisks or dots, in the usual X format. \fIValue\fR
+separated by asterisks or dots, in the usual X format (see \fBPATTERN
+FORMAT\fR). \fIValue\fR
contains a text string to associate with \fIpattern\fR; this is the
value that will be returned in calls to \fBTk_GetOption\fR or by
invocations of the \fBoption get\fR command. If \fIpriority\fR
@@ -65,31 +65,60 @@ The \fIpriority\fR arguments to the \fBoption\fR command are
normally specified symbolically using one of the following values:
.TP
\fBwidgetDefault\fR
+.
Level 20. Used for default values hard-coded into widgets.
.TP
\fBstartupFile\fR
+.
Level 40. Used for options specified in application-specific
startup files.
.TP
\fBuserDefault\fR
+.
Level 60. Used for options specified in user-specific defaults
files, such as \fB.Xdefaults\fR, resource databases loaded into
the X server, or user-specific startup files.
.TP
\fBinteractive\fR
+.
Level 80. Used for options specified interactively after the application
starts running. If \fIpriority\fR is not specified, it defaults to
this level.
-.LP
+.PP
Any of the above keywords may be abbreviated. In addition, priorities
may be specified numerically using integers between 0 and 100,
inclusive. The numeric form is probably a bad idea except for new priority
levels other than the ones given above.
+.SH "PATTERN FORMAT"
+.PP
+Patterns consist of a sequence of words separated by either periods,
+.QW . ,
+or asterisks
+.QW * .
+The overall pattern may also be optionally preceded by an asterisk.
+.PP
+Each word in the pattern conventionally starts with either an upper-case
+letter (in which case it denotes the class of either a widget or an option) or
+any other character, when it denotes the name of a widget or option. The last
+word in the pattern always indicates the option; the preceding ones constrain
+which widgets that option will be looked for in.
+.PP
+When two words are separated by a period, the latter widget must be a direct
+child of the former (or the option must apply to only the indicated widgets).
+When two words are separated by an asterisk, any depth of widgets may lie
+between the former and latter widgets (and the option applies to all widgets
+that are children of the former widget).
+.PP
+If the overall pattern is preceded by an asterisk, then the overall pattern
+applies anywhere it can throughout the whole widget hierarchy. Otherwise the
+first word of the pattern is matched against the name and class of the
+.QW \fB.\fR
+\fBtoplevel\fR, which are usually set by options to \fBwish\fR.
.SH EXAMPLES
Instruct every button in the application to have red text on it unless
-explicitly overridden:
+explicitly overridden (note that on some platforms the option is ignored):
.CS
-\fBoption add\fR *button.foreground red startupFile
+\fBoption add\fR *Button.foreground red startupFile
.CE
.PP
Allow users to control what happens in an entry widget when the Return
@@ -100,6 +129,10 @@ entry .e
bind .e <Return> [\fBoption get\fR .e returnCommand Command]
\fBoption add\fR *.e.returnCommand bell widgetDefault
.CE
-
+.SH "SEE ALSO"
+options(n), wish(1)
.SH KEYWORDS
database, option, priority, retrieve
+'\" Local Variables:
+'\" mode: nroff
+'\" End: