summaryrefslogtreecommitdiffstats
path: root/doc/Notifier.3
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2007-10-28 14:17:38 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2007-10-28 14:17:38 (GMT)
commitccacc920f9cd610a9a9d8e800f623c20bf43a702 (patch)
treedaec40c266097bb1d38f10254010691b0131d4cc /doc/Notifier.3
parent8ffb8fa76d0d34283e491044dd28385674ba113e (diff)
downloadtcl-ccacc920f9cd610a9a9d8e800f623c20bf43a702.zip
tcl-ccacc920f9cd610a9a9d8e800f623c20bf43a702.tar.gz
tcl-ccacc920f9cd610a9a9d8e800f623c20bf43a702.tar.bz2
First stage of doing GOOBE improvements to documentation now that the html generation works
Diffstat (limited to 'doc/Notifier.3')
-rw-r--r--doc/Notifier.329
1 files changed, 17 insertions, 12 deletions
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index b1aec3f..15eae60 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.19 2007/10/26 20:11:51 dgp Exp $
+'\" RCS: @(#) $Id: Notifier.3,v 1.20 2007/10/28 14:17:39 dkf Exp $
'\"
.so man.macros
.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
@@ -107,8 +107,8 @@ 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.
+to replace the ones installed in the executable. See
+\fBREPLACING THE NOTIFIER\fR for details.
.BE
.SH INTRODUCTION
@@ -243,7 +243,7 @@ The \fIflags\fR argument will be the same as the \fIflags\fR
argument passed to \fBTcl_DoOneEvent\fR except that it will never
be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
\fIFlags\fR indicates what kinds of events should be considered;
-if the bit corresponding to this event source isn't set, the event
+if the bit corresponding to this event source is not set, the event
source should return immediately without doing anything. For
example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
bit.
@@ -385,7 +385,7 @@ There are several reasons why an event source might defer an event.
One possibility is that events of this type are excluded by the
\fIflags\fR argument.
For example, the file event source will always return 0 if the
-\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
+\fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR.
Another example of deferring events happens in Tk if
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
of window events.
@@ -409,8 +409,9 @@ Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
procedure. (A thread would then need to pass this identifier to other
threads for those threads to be able to add events to its queue.)
After adding an event to another thread's queue, you then typically
-need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
-alert it to the new event.
+need to call \fBTcl_ThreadAlert\fR to
+.QW "wake up"
+that thread's notifier to alert it to the new event.
.PP
\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
@@ -454,7 +455,9 @@ procedure when initializing a Tcl interpreter. Similarly,
called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
.PP
\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
-it is responsible for waiting for an ``interesting'' event to occur or
+it is responsible for waiting for an
+.QW interesting
+event to occur or
for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
each of the event sources' setup procedure will have been invoked.
The \fItimePtr\fR argument to
@@ -468,13 +471,13 @@ to occur; it should not actually process the event in any way.
Later on, the
event sources will process the raw events and create Tcl_Events on
the event queue in their \fIcheckProc\fR procedures.
-However, on some platforms (such as Windows) this isn't possible;
+However, on some platforms (such as Windows) this is not possible;
events may be processed in \fBTcl_WaitForEvent\fR, including queuing
Tcl_Events and more (for example, callbacks for native widgets may be
invoked). The return value from \fBTcl_WaitForEvent\fR must be either
0, 1, or \-1. On platforms such as Windows where events get processed in
\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
-events still pending that haven't been processed. This is a sign to the
+events still pending that have not been processed. This is a sign to the
caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
pending events to be processed. A 0 return value means that calling
\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
@@ -489,7 +492,9 @@ forever because there were no active event sources and the timeout was
infinite.
.PP
\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
-any thread to "wake up" the notifier to alert it to new events on its
+any thread to
+.QW "wake up"
+the notifier to alert it to new events on its
queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier
handle returned by \fBTcl_InitNotifier\fR.
.PP
@@ -499,7 +504,7 @@ invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
time has been reduced. \fBTcl_SetTimer\fR should arrange for the
external event loop to invoke \fBTcl_ServiceAll\fR after the specified
interval even if no events have occurred. This interface is needed
-because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
+because \fBTcl_WaitForEvent\fR is not invoked when there is an external
event loop. If the
notifier will only be used from \fBTcl_DoOneEvent\fR, then
\fBTcl_SetTimer\fR need not do anything.