Author: engelsman
Date: 2009-05-14 13:16:09 -0700 (Thu, 14 May 2009)
New Revision: 6787
Log:
added extra text for Fl::awake() and Fl::flush()
also converted some old html tags to doxygen in Fl.cxx and Fl_lock.cxx
Modified:
branches/branch-1.3/src/Fl.cxx
branches/branch-1.3/src/Fl_lock.cxx
Modified: branches/branch-1.3/src/Fl.cxx
===================================================================
--- branches/branch-1.3/src/Fl.cxx 2009-05-03 17:43:19 UTC (rev 6786)
+++ branches/branch-1.3/src/Fl.cxx 2009-05-14 20:16:09 UTC (rev 6787)
@@ -288,14 +288,14 @@
is only called once, then FLTK calls the system and tells it not to
return until an event happens.
- <p>This can be used by code that wants to monitor the
+ This can be used by code that wants to monitor the
application's state, such as to keep a display up to date. The
advantage of using a check callback is that it is called only when no
events are pending. If events are coming in quickly, whole blocks of
them will be processed before this is called once. This can save
significant time and avoid the application falling behind the events.
- <p>Sample code:
+ Sample code:
\code
bool state_changed; // anything that changes the display turns this on
@@ -499,21 +499,21 @@
each time after this returns, which is quite useful for managing
program state.
- <P>What this really does is call all idle callbacks, all elapsed
+ What this really does is call all idle callbacks, all elapsed
timeouts, call Fl::flush() to get the screen to update, and
then wait some time (zero if there are idle callbacks, the shortest of
all pending timeouts, or infinity), for any events from the user or
any Fl::add_fd() callbacks. It then handles the events and
calls the callbacks and then returns.
- <P>The return value of the first form is non-zero if there are
+ The return value of the first form is non-zero if there are
any visible windows - this may change in future versions of
FLTK.
- <P>The second form waits a maximum of <i>time</i>
+ The second form waits a maximum of <i>time</i>
seconds. <i>It can return much sooner if something happens.</i>
- <P>The return value is positive if an event or fd happens before the
+ The return value is positive if an event or fd happens before the
time elapsed. It is zero if nothing happens (on Win32 this will only
return zero if <i>time</i> is zero). It is negative if an error
occurs (this will happen on UNIX if a signal happens).
@@ -536,7 +536,7 @@
}
\endcode
- <P>The returns non-zero if any windows are displayed, and 0 if no
+ The returns non-zero if any windows are displayed, and 0 if no
windows are displayed (this is likely to change in future versions of
FLTK).
*/
@@ -546,7 +546,7 @@
}
/**
- This is similar to Fl::check() except this does <I>not</I>
+ This is similar to Fl::check() except this does \e not
call Fl::flush() or any callbacks, which is useful if your
program is in a state where such callbacks are illegal. This returns
true if Fl::check() would do anything (it will continue to
@@ -609,7 +609,7 @@
a modal() window is shown this is the top-most modal window, otherwise
it is the most recent window to get an event.
- <P>The second form sets the window that is returned by
+ The second form sets the window that is returned by
first_window. The window is removed from wherever it is in the
list and inserted at the top. This is not done if Fl::modal()
is on or if the window is not shown(). Because the first window
@@ -647,8 +647,14 @@
/**
Causes all the windows that need it to be redrawn and graphics forced
- out through the pipes. This is what wait() does before
- looking for events.
+ out through the pipes.
+
+ This is what wait() does before looking for events.
+
+ Note: in multi-threaded applications you should only call Fl::flush()
+ from the main thread. If a child thread needs to trigger a redraw event,
+ it should instead call Fl::awake() to get the main thread to process the
+ event queue.
*/
void Fl::flush() {
if (damage()) {
@@ -691,15 +697,12 @@
them returns non zero then the event is ignored. Events that cause
this to be called are:
- <UL>
- <LI>FL_SHORTCUT events that are not recognized by any widget.
- This lets you provide global shortcut keys. </LI>
- <LI>System events that FLTK does not recognize. See
- fl_xevent. </LI>
- <LI><I>Some</I> other events when the widget FLTK selected returns
- zero from its handle() method. Exactly which ones may change
- in future versions, however. </LI>
- </UL>
+ - FL_SHORTCUT events that are not recognized by any widget.
+ This lets you provide global shortcut keys.
+ - System events that FLTK does not recognize. See fl_xevent.
+ - \e Some other events when the widget FLTK selected returns
+ zero from its handle() method. Exactly which ones may change
+ in future versions, however.
*/
void Fl::add_handler(int (*ha)(int)) {
handler_link *l = new handler_link;
@@ -786,10 +789,10 @@
typically go to this widget. This is also the first widget tried for
FL_SHORTCUT events.
- <P>If you change the belowmouse widget, the previous one and all
+ If you change the belowmouse widget, the previous one and all
parents (that don't contain the new widget) are sent FL_LEAVE
- events. Changing this does <I>not</I> send FL_ENTER to this
- or any widget, because sending FL_ENTER is supposed to <I>test</I>
+ events. Changing this does \e not send FL_ENTER to this
+ or any widget, because sending FL_ENTER is supposed to \e test
if the widget wants the mouse (by it returning non-zero from
handle()).
*/
@@ -812,10 +815,10 @@
FL_RELEASE (and any more FL_PUSH) events will be sent to
this widget.
- <P>If you change the pushed widget, the previous one and all parents
+ If you change the pushed widget, the previous one and all parents
(that don't contain the new widget) are sent FL_RELEASE
- events. Changing this does <I>not</I> send FL_PUSH to this
- or any widget, because sending FL_PUSH is supposed to <I>test</I>
+ events. Changing this does \e not send FL_PUSH to this
+ or any widget, because sending FL_PUSH is supposed to \e test
if the widget wants the mouse (by it returning non-zero from
handle()).
*/
@@ -1320,18 +1323,18 @@
selection. FL_SELECTIONCLEAR is sent to the previous
selection owner, if any.
- <P><I>Copying the buffer every time the selection is changed is
+ <i>Copying the buffer every time the selection is changed is
obviously wasteful, especially for large selections. An interface will
probably be added in a future version to allow the selection to be made
by a callback function. The current interface will be emulated on top
- of this.</I>
+ of this.</i>
*/
void Fl::selection_owner(Fl_Widget *owner) {selection_owner_ = owner;}
/**
Changes the current selection. The block of text is
copied to an internal buffer by FLTK (be careful if doing this in
- response to an FL_PASTE as this <I>may</I> be the same buffer
+ response to an FL_PASTE as this \e may be the same buffer
returned by event_text()). The selection_owner()
widget is set to the passed owner.
*/
@@ -1343,8 +1346,8 @@
/** Backward compatibility only:
Set things up so the receiver widget will be called with an FL_PASTE event
some
time in the future for the specified clipboard. The reciever
- should be prepared to be called <I>directly</I> by this, or for
- it to happen <I>later</I>, or possibly <I>not at all</I>. This
+ should be prepared to be called \e directly by this, or for
+ it to happen \e later, or possibly <i>not at all</i>. This
allows the window system to take as long as necessary to retrieve
the paste buffer (or even to screw up completely) without complex
and error-prone synchronization code in FLTK.
Modified: branches/branch-1.3/src/Fl_lock.cxx
===================================================================
--- branches/branch-1.3/src/Fl_lock.cxx 2009-05-03 17:43:19 UTC (rev 6786)
+++ branches/branch-1.3/src/Fl_lock.cxx 2009-05-14 20:16:09 UTC (rev 6787)
@@ -142,16 +142,16 @@
data. The main thread must call lock() to initialize
the threading support in FLTK.
- <P>Child threads must call unlock() when they are done
+ Child threads must call unlock() when they are done
accessing FLTK.
- <P>When the wait() method is waiting
+ When the wait() method is waiting
for input or timeouts, child threads are given access to FLTK.
Similarly, when the main thread needs to do processing, it will
wait until all child threads have called unlock() before processing
additional data.
- <P>See also: multithreading
+ See also: \ref advanced_multithreading
*/
/** \fn void Fl::unlock()
The unlock() method releases the lock that was set
@@ -159,7 +159,7 @@
threads should call this method as soon as they are finished
accessing FLTK.
- <P>See also: multithreading
+ See also: \ref advanced_multithreading
*/
/** \fn void Fl::awake(void* msg)
The awake() method sends a message pointer to the main thread,
@@ -167,19 +167,24 @@
terminate so that the main thread can retrieve the message and any pending
redraws can be processed.
- <P>Multiple calls to Fl::awake() will queue multiple pointers
+ Multiple calls to Fl::awake() will queue multiple pointers
for the main thread to process, up to a system-defined (typically several
thousand) depth. The default message handler saves the last message which
can be accessed using the
Fl::thread_message() function.
- <P>The second form of awake() registers a function that will be
+ The second form of awake() registers a function that will be
called by the main thread during the next message handling cycle.
awake() will return 0 if the callback function was registered,
and -1 if registration failed. Over a thousand awake callbacks can be
registered simultaneously.
+
+ In the context of a threaded application, a call to Fl::awake() with no
+ argument will trigger event loop handling in the main thread. Since
+ it is not possible to call Fl::flush() from a subsidiary thread,
+ Fl::awake() is the best (and only, really) substitute.
- <P>See also: multithreading.
+ See also: \ref advanced_multithreading
*/
#ifdef WIN32
# include <windows.h>
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
