From 34f5764e6203564bf56b0f31fea103d7c31898a2 Mon Sep 17 00:00:00 2001 From: dkf Date: Fri, 25 Dec 2009 18:21:30 +0000 Subject: [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. --- ChangeLog | 27 +++++++++++++++++---------- doc/option.n | 39 ++++++++++++++++++++++++++++++++++----- 2 files changed, 51 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index a4bba57..61e528d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,14 +1,20 @@ +2009-12-25 Donal K. Fellows + + * doc/option.n: [Bug 2914943]: Correct the first example. + Also define what the format of option patterns is; that's a much less + commonly known fact than it used to be. + 2009-12-22 Jan Nijtmans - * unix/tcl.m4 Sync with current Tcl version - * unix/Makefile.in Use EXE_SUFFIX for Cygwin, and - install libtk8.6.dll in bin directory - * unix/configure (regenerated) + * unix/tcl.m4: Sync with current Tcl version. + * unix/Makefile.in: Use EXE_SUFFIX for Cygwin, and install + libtk8.6.dll in bin directory. + * unix/configure: (regenerated) 2009-12-22 Joe English - * library/ttk/sizegrip.tcl: Patch to avoid bizarro behavior - under compiz [Bug 2912356]. + * library/ttk/sizegrip.tcl: [Bug 2912356]: Patch to avoid bizarro + behavior under compiz. 2009-12-20 Donal K. Fellows @@ -17,10 +23,11 @@ 2009-12-16 Jan Nijtmans - * generic/tkListbox.c: Fix gcc warning: ignoring return value of "strtol", - declared with attribute warn_unused_result. - * unix/tkUnixEvent.c: Fix gcc warning: dereferencing pointer "xgePtr" does - break strict-aliasing rules. + * generic/tkListbox.c: Fix gcc warning: ignoring return value of + "strtol", declared with attribute + warn_unused_result. + * unix/tkUnixEvent.c: Fix gcc warning: dereferencing pointer + "xgePtr" does break strict-aliasing rules. * generic/tkInt.decls: CONSTify return values of TkKeysymToString, * generic/tkBind.c TkFindStateString, TkpGetString, TkpGetChar, * generic/tkIntDecls.h which are all not supposed to be modified by diff --git a/doc/option.n b/doc/option.n index 93e0bdb..083e05e 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.9 2008/09/23 13:36:45 dkf Exp $ +'\" RCS: @(#) $Id: option.n,v 1.10 2009/12/25 18:21:30 dkf Exp $ '\" .so man.macros .TH option n "" Tk "Tk Built-In Commands" @@ -28,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 @@ -79,17 +80,43 @@ the X server, or user-specific startup files. 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 .PP Instruct every button in the application to have red text on it unless -explicitly overridden: +explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR +class (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 +127,8 @@ entry .e bind .e [\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: -- cgit v0.12