Document new syntax for "notify install", "notify uninstall" and "notify linkage" as well as deprecating old-style syntax.

New percentsCommand argument to "notify generate".
New %P and %? %-substitution characters.
New "DYNAMIC EVENTS" section to describe use of "notify install", "notify generate", and percentsCommand.

1 files changed, 188 insertions, 120 deletions

diff --git a/doc/treectrl.n b/doc/treectrl.n
index 46968e8..d3a3ad3 100644
--- a/doc/treectrl.n
+++ b/doc/treectrl.n
@@ -6,7 +6,7 @@
 '\"   See the file "license.terms" for information on usage and redistribution
 '\"   of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\"   $Id: treectrl.n,v 1.27 2005/01/03 21:24:29 treectrl Exp $
+'\"   $Id: treectrl.n,v 1.28 2005/03/29 21:20:42 treectrl Exp $
 .so man.macros
 .TH "treectrl" n 1.1  "Tk Commands"
 .BS
@@ -189,22 +189,28 @@ package require \fBtreectrl  1.1\fR
 .sp
 \fIpathName\fR \fBnotify\fR \fIoption\fR ?\fIarg ...\fR?\fR
 .sp
-\fIpathName\fR \fBnotify bind\fR ?\fIobject\fR? ?\fIpattern\fR? ?\fIscript\fR?\fR
+\fIpathName\fR \fBnotify bind\fR ?\fIobject\fR? ?\fIpattern\fR? ?+??\fIscript\fR?\fR
 .sp
-\fIpathName\fR \fBnotify configure\fR \fIwindow\fR \fIpattern\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR
+\fIpathName\fR \fBnotify configure\fR \fIobject\fR \fIpattern\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR
 .sp
 \fIpathName\fR \fBnotify detailnames\fR \fIeventName\fR\fR
 .sp
 \fIpathName\fR \fBnotify eventnames\fR\fR
 .sp
-\fIpathName\fR \fBnotify generate\fR \fIpattern\fR ?\fIcharMap\fR?\fR
+\fIpathName\fR \fBnotify generate\fR \fIpattern\fR ?\fIcharMap\fR? ?\fIpercentsCommand\fR?\fR
+.sp
+\fIpathName\fR \fBnotify install\fR \fIpattern\fR ?\fIpercentsCommand\fR?\fR
 .sp
 \fIpathName\fR \fBnotify install detail\fR \fIeventName\fR \fIdetail\fR ?\fIpercentsCommand\fR?\fR
 .sp
 \fIpathName\fR \fBnotify install event\fR \fIeventName\fR ?\fIpercentsCommand\fR?\fR
 .sp
+\fIpathName\fR \fBnotify linkage\fR \fIpattern\fR\fR
+.sp
 \fIpathName\fR \fBnotify linkage\fR \fIeventName\fR ?\fIdetail\fR?\fR
 .sp
+\fIpathName\fR \fBnotify uninstall\fR \fIpattern\fR\fR
+.sp
 \fIpathName\fR \fBnotify uninstall detail\fR \fIeventName\fR \fIdetail\fR\fR
 .sp
 \fIpathName\fR \fBnotify uninstall event\fR \fIeventName\fR\fR
@@ -650,6 +656,17 @@ The default value is false.
 .LP
 .nf
 .ta 6c
+Command-Line Switch:	\fB-showrootlines\fR
+Database Name:	\fBshowRootLines\fR
+Database Class:	\fBShowRootLines\fR
+.fi
+.IP
+Specifies a boolean value that determines whether this widget
+should draw the connecting lines between children of the root item.
+The default value is true.
+.LP
+.nf
+.ta 6c
 Command-Line Switch:	\fB-treecolumn\fR
 Database Name:	\fBtreeColumn\fR
 Database Class:	\fBTreeColumn\fR
@@ -701,7 +718,7 @@ Database Class:	\fBScrollDelay\fR
 .IP
 Specifies the amount of time before the default binding should handle
 repeating mouse motion events in horizontal direction with button 1 pressed.
-The value should be a list of upto 2 integers.
+The value should be a list of 1 or 2 integers.
 The first integer specifies the timespan in microseconds
 before the active item should be changed to get nearer to the
 current mouse position. If there are two integers specified, the first is only
@@ -734,7 +751,7 @@ Database Class:	\fBScrollDelay\fR
 .IP
 Specifies the amount of time before the default binding should handle
 repeating mouse motion events in vertical direction with button 1 pressed.
-The value should be a list of upto 2 integers.
+The value should be a list of 1 or 2 integers.
 The first integer specifies the timespan in microseconds
 before the active item should be changed to get nearer to the
 current mouse position. If there are two integers specified, the first is only
@@ -1145,7 +1162,7 @@ The following forms of the command are supported:
 .TP
 \fIpathName\fR \fBitem ancestors\fR \fIitemDesc\fR\fR
 Returns a list containing the numerical indexes of all ancestors
-of the item specified by \fIitemDesc\fR from its parent upto the
+of the item specified by \fIitemDesc\fR from its parent up to the
 root item.
 .TP
 \fIpathName\fR \fBitem bbox\fR \fIitemDesc\fR ?\fIcolumn\fR? ?\fIelement\fR?\fR
@@ -1599,136 +1616,160 @@ if there are any.
 .RE
 .TP
 \fIpathName\fR \fBnotify\fR \fIoption\fR ?\fIarg ...\fR?\fR
-This command is used to manipulate the event mechanism of a treectrl widget,
-which stands in parallel to Tk's event mechanism.
-It has two major advantages:
-arbitrary new events can be defined
-together with arbitrary details,
-and before the event is triggered
-the called Tcl command underlys a customizable percent substitution.
+Many Tk widgets communicate with the outside world via \fB-command\fR
+callbacks and/or virtual events. For example, the Text widget
+evaluates its \fB-yscrollcommand\fR when the view in the widget changes,
+and generates a <<Modified>> virtual event when text is inserted or deleted.
+A treectrl widget replaces both methods of communication with its own event
+mechanism accessed through the \fBnotify\fR subcommands.
 .sp
 The exact behavior of the command depends on the \fIoption\fR argument
 that follows the \fBnotify\fR argument.
 The following forms of the command are supported:
 .RS
 .TP
-\fIpathName\fR \fBnotify bind\fR ?\fIobject\fR? ?\fIpattern\fR? ?\fIscript\fR?\fR
-This command associates \fIscript\fR with the object given by
-\fIobject\fR such that whenever the event sequence given by
-\fIpattern\fR occurs for the object
-the command will be invoked.
-This widget command is similar to the \fBbind\fR command except that
-it operates on any object in a treectl rather than entire widgets,
-and it works also for non X11 event pattern.
-If all arguments are specified then a new binding is created, replacing
-any existing binding for the same \fIpattern\fR and \fIobject\fR
-(if the first character of \fIscript\fR is \fB+\fR then \fIscript\fR
-augments an existing binding rather than replacing it).
-In this case the return value is an empty string.
-If \fIscript\fR is omitted then the command returns the \fIscript\fR
-associated with \fIobject\fR and \fIpattern\fR (an error occurs
-if there is no such binding).
-If both \fIscript\fR and \fIpattern\fR are omitted then the command
-returns a list of all the sequences for which bindings have been
-defined for \fIobject\fR.
-If no optional argument is specified, a list of all \fIobject\fRs
-to which a pattern-script combination is bound yet, is returned.
-.TP
-\fIpathName\fR \fBnotify configure\fR \fIwindow\fR \fIpattern\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR
-This command is similar to the \fBconfigure\fR widget command except
-that it modifies event options defined for \fIpattern\fR in \fIwindow\fR
-instead of modifying options for the overall treectrl widget.
+\fIpathName\fR \fBnotify bind\fR ?\fIobject\fR? ?\fIpattern\fR? ?+??\fIscript\fR?\fR
+This command associates Tcl scripts with events generated by a
+treectrl widget.
+If all three arguments are specified, \fBnotify bind\fR will arrange for
+\fIscript\fR (a Tcl script) to be evaluated whenever the event(s) specified
+by \fIpattern\fR are generated by this treectrl widget.
+If \fIscript\fR is prefixed with a "+", then it is appended to any existing
+binding for \fIpattern\fR;  otherwise \fIscript\fR replaces any existing binding.
+If \fIscript\fR is an empty string then the current binding for \fIpattern\fR
+is destroyed, leaving \fIpattern\fR unbound. In all of the cases where a script
+argument is provided, \fBnotify bind\fR returns an empty string.
+.sp
+If \fIpattern\fR is specified without a \fIscript\fR, then the script currently
+bound to \fIpattern\fR is returned, or an empty string is returned if there is
+no binding for \fIpattern\fR. If neither \fIpattern\fR nor \fIscript\fR is
+specified, then the return value is a list whose elements are all the patterns
+for which there exist bindings for \fIobject\fR.
+.sp
+The \fIobject\fR argument determines which window(s) the binding applies to.
+If \fIobject\fR begins with a dot, as in .a.b.c, then it must be the path name
+for a window; otherwise it may be an arbitrary string. Unlike the regular
+\fBbind\fR command, bindings on window names are not automatically removed if
+that window is destroyed.
+.TP
+\fIpathName\fR \fBnotify configure\fR \fIobject\fR \fIpattern\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?\fR
+This command sets and retrieves options for bindings created by the
+\fBnotify bind\fR command.
+.sp
 If no \fIoption\fR is specified, the command returns a list with
 \fIoption\fR-\fIvalue\fR pairs describing all
-the available event options for \fIpattern\fR in \fIwindow\fR.
+the available binding options for \fIpattern\fR on \fIobject\fR.
 If \fIoption\fR is specified with no \fIvalue\fR,
-then the command does nothing.
+then the command returns the current value of that option.
 If one or more \fIoption\fR-\fIvalue\fR pairs are specified, then the command
-modifies the given option(s) to have the given value(s) for the layout;
+modifies the given option(s) to have the given value(s) for the binding;
 in this case the command returns an empty string.
 .sp
-The following event options are supported:
+The following binding options are supported:
 .RS
 .TP
 \fB\fB-active\fR\fR \fIboolean\fR
-Specifies if the event should be active.
+Specifies if the binding should be active.
 As long as this option is specified as false,
-the event will not trigger.
+a binding script will not be evaluated when the corresponding event is
+generated.
 .RE
 .TP
 \fIpathName\fR \fBnotify detailnames\fR \fIeventName\fR\fR
 Returns a list containing the names of all details,
 which are installed for the event with the name \fIeventName\fR
-by means of the \fBnotify install detail\fR widget command
+by means of the \fBnotify install\fR widget command
 or by the treectrl widget itself.
 .TP
 \fIpathName\fR \fBnotify eventnames\fR\fR
 Returns a list containing the names of all events,
-which are installed by means of the \fBnotify install event\fR widget command
+which are installed by means of the \fBnotify install\fR widget command
 or by the treectrl widget itself.
 .TP
-\fIpathName\fR \fBnotify generate\fR \fIpattern\fR ?\fIcharMap\fR?\fR
-The event with the pattern \fIpattern\fR is generated,
-if it is configured as active.
+\fIpathName\fR \fBnotify generate\fR \fIpattern\fR ?\fIcharMap\fR? ?\fIpercentsCommand\fR?\fR
+This command causes the treectrl widget to generate an event. This command is
+typically used to generate dynamic events created by the \fBnotify install\fR
+command, but may be used to generate static events also.
+The event specified by \fIpattern\fR is generated, and any active binding
+scripts on the event are evaluated after undergoing %-substitution.
 If there are details defined for the event,
-\fIpattern\fR must describe an \fIeventName\fR-\fIdetail\fR pair,
-otherwise pattern should be a simple event name.
-.sp
-The optional \fIcharMap\fR is a list of \fIkey\fR-\fIvalue\fR pairs
-as in the form returned by \fBarray get\fR;
-each key has to be exactly one character.
-If this argument is specified,
-the following substitution will be done in the script
-registered for the generated event
-before it will be evaluated:
-every occurence of a percent character (\fB%\fR) followed by a \fIkey\fR
-will be replaced with its corresponding \fIvalue\fR.
+\fIpattern\fR must describe an <\fIeventName\fR-\fIdetail\fR> pair,
+otherwise \fIpattern\fR should be <\fIeventName\fR>.
+.sp
+The optional \fIcharMap\fR is a list of \fIchar\fR-\fIvalue\fR pairs
+as in the form returned by \fBarray get\fR.
+Each \fIchar\fR has to be exactly one character.
+The \fIcharMap\fR is used in %-substitution.
+.sp
+If \fIpercentsCommand\fR is specified, then it will be used to perform %-substitution
+on any scripts bound to the event. If \fIpercentsCommand\fR is not specified and
+the event is dynamic, then the %-subtitution command passed to \fBnotify install\fR
+will be used if it was provided. If the event is static or no %-substitution
+command is available, then all %-substitution is done using \fIcharMap\fR only .
+See \fBnotify install\fR for a description of \fIpercentsCommand\fR.
+.TP
+\fIpathName\fR \fBnotify install\fR \fIpattern\fR ?\fIpercentsCommand\fR?\fR
+This command installs a new event or detail specified by \fIpattern\fR.
+Events created by this command are called dynamic,
+whereas events created by the treectrl widget itself are called static.
+This command may be called to set or retrieve the \fIpercentsCommand\fR for
+an existing dynamic event.
+.sp
+The optional \fIpercentsCommand\fR is a list containing the name of a Tcl
+command, plus any optional arguments, to which five additional arguments
+will be appended. The command will be called to perform %-substitution on any
+scripts bound to the event specified by \fIpattern\fR (see \fBEVENTS AND SCRIPT SUBSTITUTIONS\fR).
+\fIPercentsCommand\fR should be defined as follows:
+.nf
+proc percentsCommand {?arg arg ...? char object event detail charMap} {
+	switch -- $char {
+		...
+	}
+	return $value
+}
+.fi
+The optional \fIarg\fR arguments are part of the \fIpercentsCommand\fR list.
+\fIChar\fR is the %-character to be substituted. \fIObject\fR is the same
+as the argument to \fBnotify bind\fR. \fIEvent\fR and \fIdetail\fR specify
+the event. \fICharMap\fR is the same as the argument to \fBnotify generate\fR.
+\fIPercentsCommand\fR should return the value to replace the %-character by.
+If an error occurs evaluating \fIpercentsCommand\fR, the %-character is replaced
+by itself.
+.sp
+\fBnotify install\fR returns the current \fIpercentsCommand\fR for the event,
+or an error if the event is not dynamic.
 .TP
 \fIpathName\fR \fBnotify install detail\fR \fIeventName\fR \fIdetail\fR ?\fIpercentsCommand\fR?\fR
-Installs a new detail \fIdetail\fR
-for the event with the name \fIeventName\fR.
-A detail create by this command is called dynamic,
-whereas details created by the treectrl widget itself are called static.
-.sp
-The optional \fIpercentsCommand\fR will be called
-before the event is triggered
-for every two character sequence
-starting with a percent character (\fB%\fR).
-The script is called with at least four additional arguments:
-the second character of the sequence,
-the window for which the event is triggered,
-\fIeventName\fR and \fIdetail\fR,
-and finally the \fIfield\fR-\fIvalue\fR pairs specified
-as arguments in the \fBnotify generate\fR call to generate the event
-(the leading dash is dropped from the \fIfield\fRs).
-The two character sequence of the command will be replaced by
-the returning string, or by an empty string
-if the command returns with a returnCode other than 0.
+This command is for backward compatibility only.
+Use \fBnotify install\fR with a \fIpattern\fR of <\fIeventName\fR-\fIdetail\fR> instead.
 .TP
 \fIpathName\fR \fBnotify install event\fR \fIeventName\fR ?\fIpercentsCommand\fR?\fR
-Installs a new event with the name \fIeventName\fR.
-An event create by this command is called dynamic,
-whereas events created by the treectrl widget itself are called static.
-For the optional \fIpercentsCommand\fR argument
-see the description of the \fBnotify install detail\fR widget command above;
-the value for the argument \fIdetail\fR is the empty string.
+This command is for backward compatibility only.
+Use \fBnotify install\fR with a \fIpattern\fR of <\fIeventName\fR> instead.
 .TP
-\fIpathName\fR \fBnotify linkage\fR \fIeventName\fR ?\fIdetail\fR?\fR
+\fIpathName\fR \fBnotify linkage\fR \fIpattern\fR\fR
 Returns a string indicating
 whether the specified event or detail is created
 by means of the \fBnotify install\fR widget command (\fBdynamic\fR)
 or by the treectrl widget itself (\fBstatic\fR).
 .TP
-\fIpathName\fR \fBnotify uninstall detail\fR \fIeventName\fR \fIdetail\fR\fR
-If the specified detail \fIdetail\fR
-of the event with the name \fIeventName\fR is static
+\fIpathName\fR \fBnotify linkage\fR \fIeventName\fR ?\fIdetail\fR?\fR
+This form of this command is for backward compatibility only.
+Use \fBnotify linkage\fR with a \fIpattern\fR of <\fIeventName\fR> or
+<\fIeventName\fR-\fIdetail\fR> instead.
+.TP
+\fIpathName\fR \fBnotify uninstall\fR \fIpattern\fR\fR
+If the event or detail specified by \fIpattern\fR is static
 (i.e. created by the treectrl widget itself), an error is generated.
-Otherwise the dynamic detail is removed from the event.
+Otherwise the dynamic event or detail is removed.
+.TP
+\fIpathName\fR \fBnotify uninstall detail\fR \fIeventName\fR \fIdetail\fR\fR
+This command is for backward compatibility only.
+Use \fBnotify uninstall\fR with a \fIpattern\fR of <\fIeventName\fR-\fIdetail\fR> instead.
 .TP
 \fIpathName\fR \fBnotify uninstall event\fR \fIeventName\fR\fR
-If the specified event with the name \fIeventName\fR is static
-(i.e. created by the treectrl widget itself), an error is generated.
-Otherwise the dynamic event is removed.
+This command is for backward compatibility only.
+Use \fBnotify uninstall\fR with a \fIpattern\fR of <\fIeventName\fR> instead.
 .RE
 .TP
 \fIpathName\fR \fBnumcolumns\fR\fR
@@ -2269,7 +2310,7 @@ This state is set for every item, which is included in the selection.
 It can be modified by means of the widget command \fBselection\fR.
 .PP
 By means of the \fBstate define\fR widget command
-upto 27 additional \fIstateName\fRs can be defined.
+up to 27 additional \fIstateName\fRs can be defined.
 .PP
 Some widget commands expect a \fIstateDesc\fR argument,
 which is a \fIstateName\fR
@@ -2509,7 +2550,7 @@ Indicates the root item of the treectrl.
 .PP
 The \fIitemDesc\fR may be followed by one or more \fImodifier\fRs.
 A modifier changes the item described by the \fIitemDesc\fR relative to
-the description upto this point.
+the description up to this point.
 It may be specified in any of the following forms:
 .TP
 \fBabove\fR
@@ -2566,27 +2607,17 @@ Use the \fIn\fRth child of the item's parent.
 \fBtop\fR
 Use the item in the first row of this column.
 .SH "EVENTS AND SCRIPT SUBSTITUTIONS"
-Many Tk widgets communicate with the outside world via \fB-command\fR
-callbacks and/or virtual events. A treectrl widget uses
-\fIquasi-events\fR which are like virtual events but each quasi-event can
-have its own event details and set of %-substitutions.
-.PP
-By means of the \fBnotify bind\fR widget command Tcl scripts can
-be specified,
-which will be executed whenever the event triggers.
-The command will be executed in the same interpreter that the
-\fBnotify bind\fR command was executed in, and it will run at global
-level (only global variables will be accessible).
-If the script contains any \fB%\fR characters,
-then the script will not be executed directly.
-Instead, a new script will be
-generated by replacing each \fB%\fR,
-and the character following it,
-with information from the current event.
-The replacement depends on the character following the \fB%\fR,
-as defined in the list below.
+The \fIscript\fR argument to \fBnotify bind\fR is a Tcl script, which will be
+evaluated whenever the given event is generated. \fIScript\fR will be executed
+in the same interpreter that the \fBnotify bind\fR command was executed in,
+and it will run at global level (only global variables will be accessible).
+If \fIscript\fR contains any \fB%\fR characters, then the script will not be
+evaluated directly.  Instead, a new script will be generated by replacing each
+\fB%\fR, and the character following it, with information from the current
+event. Unlike the regular Tk \fBbind\fR mechanism, each event generated by
+a treectrl widget has its own set of %-substitutions.
 .PP
-The following %-substitutions are valid for all events:
+The following %-substitutions are valid for all static events:
 .TP
 \fB%%\fR Replaced with a single %
 .TP
@@ -2594,9 +2625,14 @@ The following %-substitutions are valid for all events:
 .TP
 \fB%e\fR The event name
 .TP
+\fB%P\fR The pattern, either <event> or <event-detail>
+.TP
 \fB%W\fR The object argument to the \fBnotify bind\fR command
 .TP
 \fB%T\fR The treectrl widget which generated the event
+.TP
+\fB%?\fR A list of the format {char value char value ...} for each
+%-substitution character and the value it is replaced by
 .PP
 The following events may be generated by a treectrl widget:
 .TP
@@ -2624,7 +2660,8 @@ Generated after an item is collapsed.
 .RE
 .TP
 \fB<Expand-before>\fR
-Generated before an item is expanded.
+Generated before an item is expanded. This event is useful if you want to add
+child items to the item just before the item is expanded.
 .RS
 .TP
 \fB%I\fR The item id
@@ -2668,8 +2705,39 @@ how the selection changed.
 .TP
 \fB%S\fR List of newly-selected item ids
 .RE
+.SH "DYNAMIC EVENTS"
+In addition to the pre-defined static events such as <ActiveItem>
+and <Selection>, new dynamic events can be created by using the
+\fBnotify install\fR command. The default bindings provide an example
+of using a dynamic event called <Header-invoke>, which is generated when
+the mouse button is released over a column header.
+.nf
+treectrl .t
+.t notify install <Header-invoke>
+.t notify bind ConsoleTag <Header-invoke> {
+	puts "header %C clicked in treectrl %T"
+}
+proc ::TreeCtrl::Release1 {w x y} {
+	...
+	$w notify generate <Header-invoke> [list C $Priv(column)] \\
+		[list ::TreeCtrl::PercentsCmd $w]
+	...
+}
+.fi
+In the example a new treectrl widget is created and the <Header-invoke> event
+is installed. For convenience there is no \fIpercentsCommand\fR argument to
+\fBnotify install\fR; instead the call to \fBnotify generate\fR specifies
+the %-substitution command. A script is
+bound to the event with \fBnotify bind\fR which will print out the column
+number and widget
+name to the console (in the demos, <Header-invoke> is used to sort the list
+based on the column that was clicked). The \fIcharMap\fR argument to
+\fBnotify generate\fR
+provides a list of %-substitution characters and values which is used by
+::TreeCtrl::PercentsCmd. In this example any %C in any script bound to the
+<Header-invoke> event will be replaced by the value of $Priv(column).
 .SH "DEFAULT BINDINGS"
-Tk automatically creates class bindings for treectrls that give them
+Tk automatically creates class bindings for treectrl widgets that give them
 the following default behavior.
 .IP [1]
 Clicking mouse button 1 over an item positions the active cursor