Mirrors_UI_SDK/fltk
1
0
Fork 0
mirror of https://github.com/fltk/fltk.git synced 2026-06-01 23:06:54 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

added extra text for Fl::awake() and Fl::flush()

Browse Source 
also converted some old html tags to doxygen in Fl.cxx and Fl_lock.cxx



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6787 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman
2009-05-14 20:16:09 +00:00
parent 5a8e28d30b
commit 4e059441bd
2 changed files with 46 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Fl.cxx
+34 -31
View File
@@ -288,14 +288,14 @@ static Check *first_check, *next_check, *free_check;
is only called once, then FLTK calls the system and tells it not to is only called once, then FLTK calls the system and tells it not to
return until an event happens. 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 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 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 events are pending. If events are coming in quickly, whole blocks of
them will be processed before this is called once. This can save them will be processed before this is called once. This can save
significant time and avoid the application falling behind the events. significant time and avoid the application falling behind the events.
<p>Sample code: Sample code:
\code \code
bool state_changed; // anything that changes the display turns this on bool state_changed; // anything that changes the display turns this on
@@ -499,21 +499,21 @@ static Fl_Win32_At_Exit win32_at_exit;
each time after this returns, which is quite useful for managing each time after this returns, which is quite useful for managing
program state. 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 timeouts, call Fl::flush() to get the screen to update, and
then wait some time (zero if there are idle callbacks, the shortest of 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 all pending timeouts, or infinity), for any events from the user or
any Fl::add_fd() callbacks. It then handles the events and any Fl::add_fd() callbacks. It then handles the events and
calls the callbacks and then returns. 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 any visible windows - this may change in future versions of
FLTK. 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> 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 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 return zero if <i>time</i> is zero). It is negative if an error
occurs (this will happen on UNIX if a signal happens). occurs (this will happen on UNIX if a signal happens).
@@ -536,7 +536,7 @@ int Fl::wait() {
} }
\endcode \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 windows are displayed (this is likely to change in future versions of
FLTK). FLTK).
*/ */
@@ -546,7 +546,7 @@ int Fl::check() {
} }
/** /**
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 call Fl::flush() or any callbacks, which is useful if your
program is in a state where such callbacks are illegal. This returns program is in a state where such callbacks are illegal. This returns
true if Fl::check() would do anything (it will continue to true if Fl::check() would do anything (it will continue to
@@ -609,7 +609,7 @@ Fl_Window* fl_find(Window xid) {
a modal() window is shown this is the top-most modal window, otherwise a modal() window is shown this is the top-most modal window, otherwise
it is the most recent window to get an event. 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 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() 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 is on or if the window is not shown(). Because the first window
@@ -647,8 +647,14 @@ void Fl::redraw() {
/** /**
Causes all the windows that need it to be redrawn and graphics forced Causes all the windows that need it to be redrawn and graphics forced
out through the pipes. This is what wait() does before out through the pipes.
looking for events.
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() { void Fl::flush() {
if (damage()) { if (damage()) {
@@ -691,15 +697,12 @@ static handler_link *handlers = 0;
them returns non zero then the event is ignored. Events that cause them returns non zero then the event is ignored. Events that cause
this to be called are: this to be called are:
<UL> - FL_SHORTCUT events that are not recognized by any widget.
<LI>FL_SHORTCUT events that are not recognized by any widget. This lets you provide global shortcut keys.
This lets you provide global shortcut keys. </LI> - System events that FLTK does not recognize. See fl_xevent.
<LI>System events that FLTK does not recognize. See - \e Some other events when the widget FLTK selected returns
fl_xevent. </LI> zero from its handle() method. Exactly which ones may change
<LI><I>Some</I> other events when the widget FLTK selected returns in future versions, however.
zero from its handle() method. Exactly which ones may change
in future versions, however. </LI>
</UL>
*/ */
void Fl::add_handler(int (*ha)(int)) { void Fl::add_handler(int (*ha)(int)) {
handler_link *l = new handler_link; handler_link *l = new handler_link;
@@ -786,10 +789,10 @@ static char dnd_flag = 0; // make 'belowmouse' send DND_LEAVE instead of LEAVE
typically go to this widget. This is also the first widget tried for typically go to this widget. This is also the first widget tried for
FL_SHORTCUT events. 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 parents (that don't contain the new widget) are sent FL_LEAVE
events. Changing this does <I>not</I> send FL_ENTER to this events. Changing this does \e not send FL_ENTER to this
or any widget, because sending FL_ENTER is supposed to <I>test</I> or any widget, because sending FL_ENTER is supposed to \e test
if the widget wants the mouse (by it returning non-zero from if the widget wants the mouse (by it returning non-zero from
handle()). handle()).
*/ */
@@ -812,10 +815,10 @@ void Fl::belowmouse(Fl_Widget *o) {
FL_RELEASE (and any more FL_PUSH) events will be sent to FL_RELEASE (and any more FL_PUSH) events will be sent to
this widget. 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 (that don't contain the new widget) are sent FL_RELEASE
events. Changing this does <I>not</I> send FL_PUSH to this events. Changing this does \e not send FL_PUSH to this
or any widget, because sending FL_PUSH is supposed to <I>test</I> or any widget, because sending FL_PUSH is supposed to \e test
if the widget wants the mouse (by it returning non-zero from if the widget wants the mouse (by it returning non-zero from
handle()). handle()).
*/ */
@@ -1320,18 +1323,18 @@ int Fl_Window::handle(int ev)
selection. FL_SELECTIONCLEAR is sent to the previous selection. FL_SELECTIONCLEAR is sent to the previous
selection owner, if any. 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 obviously wasteful, especially for large selections. An interface will
probably be added in a future version to allow the selection to be made 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 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;} void Fl::selection_owner(Fl_Widget *owner) {selection_owner_ = owner;}
/** /**
Changes the current selection. The block of text is Changes the current selection. The block of text is
copied to an internal buffer by FLTK (be careful if doing this in 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() returned by event_text()). The selection_owner()
widget is set to the passed owner. widget is set to the passed owner.
*/ */
@@ -1343,8 +1346,8 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) {
/** Backward compatibility only: /** Backward compatibility only:
Set things up so the receiver widget will be called with an FL_PASTE event some 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 time in the future for the specified clipboard. The reciever
should be prepared to be called <I>directly</I> by this, or for should be prepared to be called \e directly by this, or for
it to happen <I>later</I>, or possibly <I>not at all</I>. This 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 allows the window system to take as long as necessary to retrieve
the paste buffer (or even to screw up completely) without complex the paste buffer (or even to screw up completely) without complex
and error-prone synchronization code in FLTK. and error-prone synchronization code in FLTK.
src/Fl_lock.cxx
+12 -7
View File
@@ -142,16 +142,16 @@ int Fl::awake(Fl_Awake_Handler func, void *data) {
data. The main thread must call lock() to initialize data. The main thread must call lock() to initialize
the threading support in FLTK. 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. 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. for input or timeouts, child threads are given access to FLTK.
Similarly, when the main thread needs to do processing, it will Similarly, when the main thread needs to do processing, it will
wait until all child threads have called unlock() before processing wait until all child threads have called unlock() before processing
additional data. additional data.
<P>See also: multithreading See also: \ref advanced_multithreading
*/ */
/** \fn void Fl::unlock() /** \fn void Fl::unlock()
The unlock() method releases the lock that was set The unlock() method releases the lock that was set
@@ -159,7 +159,7 @@ int Fl::awake(Fl_Awake_Handler func, void *data) {
threads should call this method as soon as they are finished threads should call this method as soon as they are finished
accessing FLTK. accessing FLTK.
<P>See also: multithreading See also: \ref advanced_multithreading
*/ */
/** \fn void Fl::awake(void* msg) /** \fn void Fl::awake(void* msg)
The awake() method sends a message pointer to the main thread, The awake() method sends a message pointer to the main thread,
@@ -167,19 +167,24 @@ int Fl::awake(Fl_Awake_Handler func, void *data) {
terminate so that the main thread can retrieve the message and any pending terminate so that the main thread can retrieve the message and any pending
redraws can be processed. 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 for the main thread to process, up to a system-defined (typically several
thousand) depth. The default message handler saves the last message which thousand) depth. The default message handler saves the last message which
can be accessed using the can be accessed using the
Fl::thread_message() function. 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. called by the main thread during the next message handling cycle.
awake() will return 0 if the callback function was registered, awake() will return 0 if the callback function was registered,
and -1 if registration failed. Over a thousand awake callbacks can be and -1 if registration failed. Over a thousand awake callbacks can be
registered simultaneously. registered simultaneously.
<P>See also: multithreading. 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.
See also: \ref advanced_multithreading
*/ */
#ifdef WIN32 #ifdef WIN32
# include <windows.h> # include <windows.h>