Event loop class.
More...
#include <ilviews/base/evloop.h>
Event loop class.
Library: xviews or winviews or mviews (mutually exclusive)
This class handles the processing of inputs and events. Rogue Wave Views creates a global instance of this class that the application can access using the getEventLoop static method. The application can define its own event-processing mechanism by subclassing IlvEventLoop and overriding the nextEvent and/or dispatchEvent member functions. See the description of setEventLoop for important warnings about the use of subclasses.
- See also
IlvDisplay::readAndDispatchEvents, IlvDisplay::waitAndDispatchEvents, IlvMainLoop, IlvTimer.
◆ IlvEventLoop()
Constructor.
Initializes an instance of event loop.
- Parameters
-
| setIt | If it is set to IlTrue, the new instance is set as the current event loop by a call to the static member function setEventLoop. |
◆ addIdleProc()
Add an idle procedure.
An idle procedure is a function provided by the user that is automatically called by the event loop when there is nothing else to do (no events, no timers or external inputs to process).
Idle procedures must be written in such a way that they do not alter the interactive responsiveness of the application. They should return quickly enough not to block the event loop, in case some input has arrived.
Idle procedures are handled as Last-In First-Out stack. Only the element at the top of the stack is used by the event loop. New idle procedures are put at the top of the stack. When an idle procedure must be called, the event loop does the following:
-
It removes the top-most idle procedure from the stack.
-
It calls the idle procedure.
-
It puts it back at the top of the stack if the idle procedure returns
IlFalse.
This mechanism shows that an idle procedure can be considered as removed when it returns IlTrue. It also shows that if an idle procedure A adds an idle procedure B and returns IlTrue, A will get priority over B because A is automatically added to the stack right after B.
The addIldleProc member function adds an idle procedure to the event loop and returns an ID that can be used by the application to explicitly remove the idle procedure by calling the removeIdleProc member function.
An idle procedure that has a lengthy process to perform should split the work into several small pieces. Typically, the user argument userArg could point to some data used to store the status of a long computation. The status can then be retrieved the next time the idle procedure is called.
- Returns
- The ID number used to identify the idle procedure entry.
- Parameters
-
| idleProc | The idle procedure. |
| userArg | The argument to use when calling the idle procedure. |
◆ addInput()
| virtual void IlvEventLoop::addInput |
( |
int |
fd, |
|
|
IlvLoopCallback |
cb, |
|
|
IlAny |
arg = 0, |
|
|
IlvLoopCallback |
errorCb = 0 |
|
) |
| |
|
virtual |
Adds an external source of input.
This member function is available only on Unix platforms. It is used to add Unix file descriptors as new input sources for the application. The fd argument must be of a file descriptor type supported by the select function used internally by the event loop.
The user input callback cb is triggered if the select function determines that fd is ready to be read, i.e. that a read will not block. The user error callback errorCb is triggered when an error occurs in the select function.
The user callbacks cb and errorCb are called with fd and arg as parameters.
The function call:
IlvRegisterInput(fd, cb, arg, errorCb);
is identical to:
IlvEventLoop::getEventLoop()->addInput(fd, cb, arg, errorCb)
- Parameters
-
| fd | File descriptor of a type supported by select. |
| cb | The user callback to call when fd is ready for reading. |
| arg | The user argument to pass to cb or errorCb. |
| errorCb | The user callback to call when an error is detected on the file descriptor fd. |
- See also
IlvRegisterInput.
◆ addOutput()
| virtual void IlvEventLoop::addOutput |
( |
int |
fd, |
|
|
IlvLoopCallback |
cb, |
|
|
IlAny |
arg = 0, |
|
|
IlvLoopCallback |
errorCb = 0 |
|
) |
| |
|
virtual |
Adds an external source of input.
This member function is available only on Unix platforms. Very similar to the member function addInput, this function is used to add to the event loop Unix file descriptors to watch. The fd argument must be of a file descriptor type supported by the select function used internally by the event loop.
The user callback cb is triggered if the select function determines that fd is ready for writing. The user error callback errorCb is triggered when an error occurs in the select function.
The user callbacks cb and errorCb are called with fd and arg as parameters.
The function call:
IlvRegisterOutput(fd, cb, arg, errorCb);
is identical to:
IlvEventLoop::getEventLoop()->addOutput(fd, cb, arg, errorCb)
- Parameters
-
| fd | File descriptor of a type supported by select. |
| cb | The user callback to call when fd is ready for writing. |
| arg | The user argument to pass to cb or errorCb. |
| errorCb | The user callback to call when an error is detected on the file descriptor fd. |
- See also
IlvRegisterOutput.
◆ addRedrawProc()
| virtual IlvRedrawProcLink* IlvEventLoop::addRedrawProc |
( |
IlvIdleProc |
redrawProc, |
|
|
IlAny |
userArg |
|
) |
| |
|
virtual |
Adds a redraw procedure.
Redraw procedures are like idle procedures, but they are executed with a higher priority level, every time some input has been handled by the main loop. They are mainly used to handle asynchronous redraws generated by IlvContainer::invalidateRegion() and IlvManager::invalidateRegion().
◆ dispatchEvent()
Dispatches an event.
Dispatches an event to its destination view. When redefining this member function, you should not call the function IlvDispatchEvent, to avoid endless recursion.
- Parameters
-
| systemEvent | Pointer to a system-dependant event type; it is equivalent to XEvent* on Unix/X11 platforms and to MSG* on Windows platforms. |
◆ flushRedraw()
| void IlvEventLoop::flushRedraw |
( |
IlUInt |
level = 0 | ) |
|
Executes any pending redraw requests.
This method sequentially removes all redraw requests from the queue and executes their attached callback.
◆ getEventLoop()
Gets the current event loop.
- Returns
- The instance of
IlvEventLoop currently being used.
◆ nextEvent()
| virtual IlAny IlvEventLoop::nextEvent |
( |
IlAny |
systemEvent | ) |
|
|
virtual |
Gets next event from the windowing system.
Gets the next system-dependant event that must be treated. The function also handles timers and external event sources (when applicable) internally managed. If no event is available, the function waits until a new event is sent by the system. When redefining this method, the function IlvNextEvent must not be called, to avoid endless recursion. In the Motif version, this method is equivalent to XtAppNextEvent.
- Returns
- On Unix/X11 platforms, the returned value is a pointer to the
IlvDisplay instance associated with the X Display that generated this event. On Windows platforms, the returned value is 0 if the event is the WM_QUIT message and non-0 value otherwise.
- Parameters
-
| systemEvent | Pointer to a system-dependant event type; it is equivalent to XEvent* on Unix/X11 platforms and to MSG* on Windows platforms. The parameter is used to return the next event. |
◆ pendingInput()
Indicates pending input sources.
Queries the event loop about pending input sources, that is, events, timers, and external inputs. On Unix platforms, external input sources are added by the addInput or addOutput member functions. On Microsoft Windows platforms, Rogue Wave Views considers user messages (that is, messages with a value greater than WM_USER) as external input sources.
- Returns
- One of the following values:
-
IlvInputNone: no input pending
-
IlvInputAll: all types of input are pending
or an OR combination of:
-
IlvInputEvent: events are pending
-
IlvInputTimer: timers are pending
-
IlvInputExternal: external inputs are pending
Note that IlvInputAll is equal to: (IlvInputEvent | IlvInputTimer | IlvInputExternal)
◆ processInput()
Process input from the selected source.
Processes one piece of input from the input sources specified by inputMask. Only one event, or one timer, or one external source of input is processed. Events are processed by calling IlvDispatchEvent. If there is no input on any of the specified sources, the function blocks until input is available. Specifying IlvInputNone as parameter makes little sense and may block the application permanently.
There are limitations on this method:
-
On Unix platforms, when using the libmviews library (as opposed to libxviews), the
processInput member function does not return the type of input processed (since this information is not provided by Xt).
-
On Windows platforms, not all combinations of
IlvInputMask are supported. The supported values are the following:
-
IlvInputEvent | IlvInputTimer
-
IlvInputTimer
-
IlvInputExternal
-
IlvInputAll
- Returns
- The one (and only one) type of input the function has processed.
- Parameters
-
| inputMask | An OR combination of IlvInputEvent, IlvInputTimer, and IlvInputExternal specifying the sources of input to process. |
◆ removeIdleProc()
Removes an idle procedure from the event loop.
- Returns
IlFalse if the idle procedure could not be found. Otherwise, IlTrue is returned.
- Parameters
-
| idleProcId | The ID number identifying the idle procedure for the event loop. This value was returned by addIdeProc. |
◆ removeInput()
| virtual void IlvEventLoop::removeInput |
( |
int |
fd | ) |
|
|
virtual |
Removes an external source of input.
This member function is available only on Unix platforms. It is used to remove a file descriptor registered by addInput to be monitored by the event loop as a source of input.
- Parameters
-
| fd | The file descriptor to remove as source of input. |
- See also
IlvUnRegisterInput.
◆ removeOutput()
| virtual void IlvEventLoop::removeOutput |
( |
int |
fd | ) |
|
|
virtual |
Removes an external source of input.
This member function is available only on Unix platforms. It is used to remove a file descriptor registered by addOutput to be monitored by the event loop.
- Parameters
-
| fd | The file descriptor to remove from the event loop. |
- See also
IlvUnRegisterOuput.
◆ removeRedrawProc()
| virtual IlBoolean IlvEventLoop::removeRedrawProc |
( |
IlvRedrawProcLink * |
procId | ) |
|
|
virtual |
Removes a redraw procedure from the queue.
- Parameters
-
| procId | A pointer to the redraw procedure that must be removed. |
- Returns
IlTrue if the removal was successful, or IlFalse otherwise.
◆ setEventLoop()
| static void IlvEventLoop::setEventLoop |
( |
IlvEventLoop * |
eventLoop | ) |
|
|
static |
Sets the current event loop.
Sets eventLoop as the current event loop. The previous event loop is not deleted. This static member function allows the application to use its own subclass of IlvEventLoop. The most common use of this function is to set the customized event loop once and for all at application start-up. You can also temporarily set a local event loop for a specific task and reset the previous one once the task is completed. Any other use is highly discouraged. In particular, the current event loop should be the same before and after the dispatching of an event.
- Parameters
-
| eventLoop | The event loop to set. |
◆ setLazyRedraw()
| void IlvEventLoop::setLazyRedraw |
( |
IlUInt |
lazy | ) |
|
Get/Set the lazy redraw mechanism.
When invalidating regions (calling invalidateRegion()), containers and managers schedule by default a redraw procedure that will defer redraws until no more object management needs to be done. This greatly improves the overall performance and responsiveness of the user interface. However, for compatibility reasons, or to implement special deferred draw mechanisms, you may wish to turn off this mechanism and perform redraw tasks only explicitly.
Call setLazyRedraw(0) to turn off the scheduling of redraw tasks when invalidating regions. Call setLazyRedraw(1) to turn the default lazy redraw mechanism back on. In this case, calls to initReDraw/reDrawViews will preempt the lazy redraw mechanism to maintain compatibility with former deferred redraw mechanisms. This means that calls to invalidateRegion inside a pair of initReDraw/reDrawViews will not schedule a redraw task, and that the most external reDrawViews will force a redrawing of the invalidated regions. However, if you never call initReDraw or reDrawViews in this mode, you will benefit from the lazy redraw mechanism, which schedules drawing tasks more efficiently. Call setLazyRedraw(2) to benefit from the full optimizations and code simplifications that the lazy redraw mechanism allows. At this level, calls to initReDraw/reDrawViews will not have any effect, allowing all existing programs to benefit from the full lazy redraw mechanism. However, some incompatibilities may appear in this mode when interleaving direct drawing (like when drawing in Xor mode) and deferred drawing, which is why this mode is not the default. Later versions of Views may however set the default value of the lazy redraw level to 2.
The environment variable ILV_LAZY_REDRAW can be used to control the lazy redraw mode externally.
- Parameters
-
| lazy | Integer value indicating the type of lazy redraw mechanism to use. |
