summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKevin B Kenny <kennykb@acm.org>2007-04-20 04:44:29 (GMT)
committerKevin B Kenny <kennykb@acm.org>2007-04-20 04:44:29 (GMT)
commit0823d0ce0477c8a5a0183f4f9d76768b4cc203fc (patch)
treecd695bd004ad1aa7ee936fd476a30fb64194b314
parent97d7bdb53a0311ef3da99b07b875611f1f2e6394 (diff)
downloadtcl-0823d0ce0477c8a5a0183f4f9d76768b4cc203fc.zip
tcl-0823d0ce0477c8a5a0183f4f9d76768b4cc203fc.tar.gz
tcl-0823d0ce0477c8a5a0183f4f9d76768b4cc203fc.tar.bz2
* doc/Notifier.3: Documented Tcl_SetNotifier and Tcl_ServiceModeHook.
Quite against my better judgment. [Bug 414933]
-rw-r--r--ChangeLog5
-rw-r--r--doc/Notifier.359
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