From 4e059441bd763f8465f83868ad7b70e729cfb533 Mon Sep 17 00:00:00 2001 From: engelsman Date: Thu, 14 May 2009 20:16:09 +0000 Subject: [PATCH] added extra text for Fl::awake() and Fl::flush() 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 --- src/Fl.cxx | 65 ++++++++++++++++++++++++++----------------------- src/Fl_lock.cxx | 19 +++++++++------ 2 files changed, 46 insertions(+), 38 deletions(-) diff --git a/src/Fl.cxx b/src/Fl.cxx index 1c4705075..663e38630 100644 --- a/src/Fl.cxx +++ b/src/Fl.cxx @@ -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 return until an event happens. -

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. -

Sample code: + Sample code: \code 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 program state. -

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. -

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. -

The second form waits a maximum of time + The second form waits a maximum of time seconds. It can return much sooner if something happens. -

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 time is zero). It is negative if an error occurs (this will happen on UNIX if a signal happens). @@ -536,7 +536,7 @@ int Fl::wait() { } \endcode -

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 @@ int Fl::check() { } /** - This is similar to Fl::check() except this does not + 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 @@ Fl_Window* fl_find(Window xid) { a modal() window is shown this is the top-most modal window, otherwise it is the most recent window to get an event. -

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 @@ void Fl::redraw() { /** 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 @@ static handler_link *handlers = 0; them returns non zero then the event is ignored. Events that cause this to be called are: -

+ - 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 @@ 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 FL_SHORTCUT events. -

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 not send FL_ENTER to this - or any widget, because sending FL_ENTER is supposed to test + 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 @@ void Fl::belowmouse(Fl_Widget *o) { FL_RELEASE (and any more FL_PUSH) events will be sent to this widget. -

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 not send FL_PUSH to this - or any widget, because sending FL_PUSH is supposed to test + 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 @@ int Fl_Window::handle(int ev) selection. FL_SELECTIONCLEAR is sent to the previous selection owner, if any. -

Copying the buffer every time the selection is changed is + 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. + of this. */ 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 may 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 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) { /** 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 directly by this, or for - it to happen later, or possibly not at all. This + should be prepared to be called \e directly by this, or for + it to happen \e later, or possibly not at all. 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. diff --git a/src/Fl_lock.cxx b/src/Fl_lock.cxx index 199720058..27787cd99 100644 --- a/src/Fl_lock.cxx +++ b/src/Fl_lock.cxx @@ -142,16 +142,16 @@ int Fl::awake(Fl_Awake_Handler func, void *data) { data. The main thread must call lock() to initialize the threading support in FLTK. -

Child threads must call unlock() when they are done + Child threads must call unlock() when they are done accessing FLTK. -

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. -

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 @@ int Fl::awake(Fl_Awake_Handler func, void *data) { threads should call this method as soon as they are finished accessing FLTK. -

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 @@ int Fl::awake(Fl_Awake_Handler func, void *data) { terminate so that the main thread can retrieve the message and any pending redraws can be processed. -

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. -

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. -

See also: multithreading. + See also: \ref advanced_multithreading */ #ifdef WIN32 # include