diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/Notifier.3 | 59 |
2 files changed, 58 insertions, 6 deletions
@@ -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 |