* doc/Notifier.3: Documented Tcl_SetNotifier and Tcl_ServiceModeHook.

Quite against my better judgment.  [Bug 414933]

2 files changed, 58 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index daae6d7..1066a6c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,4 @@
-2007-04-19  Kevin B. Kenny  <kennykb@acm.org>
+2007-04-20  Kevin B. Kenny  <kennykb@acm.org>
 
 	* doc/clock.n: Corrected a silly error (transposed 'uppercase'
 	and 'lowercase' in clock.n. [Bug 1656002]
@@ -25,6 +25,9 @@
 	* generic/tclGetDate.y (MilitaryTable): Fixed an ancient bug where
 	the military NZA time zones had the signs reversed [Bug 1586828].
 	* generic/tclDate.c: Regenerated.
+	* doc/Notifier.3: Documented Tcl_SetNotifier and
+	Tcl_ServiceModeHook. Quite against my better judgment.
+	[Bug 414933]
 	
 2007-04-19  Donal K. Fellows  <donal.k.fellows@manchester.ac.uk>
 
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 7776610..f7495fe 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -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: Notifier.3,v 1.15 2005/05/10 18:33:56 kennykb Exp $
+'\" RCS: @(#) $Id: Notifier.3,v 1.16 2007/04/20 04:44:31 kennykb Exp $
 '\" 
 .so man.macros
 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
@@ -66,9 +66,14 @@ int
 .sp
 int
 \fBTcl_SetServiceMode\fR(\fImode\fR)
-
+.sp
+void
+\fBTcl_ServiceModeHook\fR(\fImode\fR)
+.sp
+void
+\fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR)
 .SH ARGUMENTS
-.AS Tcl_EventDeleteProc *deleteProc
+.AS Tcl_EventDeleteProc *notifierProcPtr
 .AP Tcl_EventSetupProc *setupProc in
 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
 .AP Tcl_EventCheckProc *checkProc in
@@ -100,6 +105,10 @@ passed to \fBTcl_DoOneEvent\fR.
 .AP int mode in
 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
+.AP Tcl_NotifierProcs* notifierProcPtr in
+Structure of function pointers describing notifier procedures that are
+to replace the ones installed in the executable.  See "REPLACING THE
+NOTIFIER" for details.
 .BE
 
 .SH INTRODUCTION
@@ -430,10 +439,11 @@ entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
 available on all platforms, and \fBTcl_CreateFileHandler\fR and
 \fBTcl_DeleteFileHandler\fR, which are Unix-specific.  Most of these
 procedures are generic, in that they are the same for all notifiers.
-However, eight of the procedures are notifier-dependent:
+However, none of the procedures are notifier-dependent:
 \fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR, 
 \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR.  To
+\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR and
+\fBTcl_ServiceModeHook.  To
 support a new platform or to integrate Tcl with an
 application-specific event loop, you must write new versions of these
 procedures.
@@ -495,6 +505,13 @@ event loop.  If the
 notifier will only be used from \fBTcl_DoOneEvent\fR, then
 \fBTcl_SetTimer\fR need not do anything.
 .PP
+\fBTcl_ServiceModeHook\R is called by the platform-independent portion
+of the notifier when client code makes a call to
+\fBTcl_SetServiceMode\fR. This hook is provided to support operating
+systems that require special event handling when the application is in
+a modal loop (the Windows notifier, for instance, uses this hook to
+create a communication window).
+.PP
 On Unix systems, the file event source also needs support from the
 notifier.  The file event source consists of the
 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
@@ -508,6 +525,38 @@ The easiest way to create a new notifier is to look at the code
 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
 
+.SH "REPLACING THE NOTIFIER"
+.PP
+A notifier that has been written according to the conventions above
+can also be installed in a running process in place of the standard
+notifier.  This mechanism is used so that a single executable can be
+used (with the standard notifier) as a stand-alone program and reused
+(with a replacement notifier in a loadable extension) as an extension
+to another program, such as a Web browser plugin.
+.PP
+To do this, the extension makes a call to \fBTcl_SetNotifier\fR
+passing a pointer to a \fBTcl_NotifierProcs\fR data structure.  The
+structure has the following layout:
+.CS
+typedef struct Tcl_NotifierProcs {
+    Tcl_SetTimerProc *setTimerProc;
+    Tcl_WaitForEventProc *waitForEventProc;
+    Tcl_CreateFileHandlerProc *createFileHandlerProc;
+    Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
+    Tcl_InitNotifierProc *initNotifierProc;
+    Tcl_FinalizeNotifierProc *finalizeNotifierProc;
+    Tcl_AlertNotifierProc *alertNotifierProc;
+    Tcl_ServiceModeHookProc *serviceModeHookProc;
+} Tcl_NotifierProcs;
+.CE
+Following the call to \fBTcl_SetNotifier\fR, the pointers given in
+the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
+been installed in the process.
+.PP
+It is extraordinarily unwise to replace a running notifier. Normally,
+\fBTcl_SetNotifier\fR should be called at process initialization time
+before the first call to \fBTcl_InitNotifier\fR.
+
 .SH "EXTERNAL EVENT LOOPS"
 .PP
 The notifier interfaces are designed so that Tcl can be embedded into