Rogue Wave Views Foundation Package API Reference Guide |
Rogue Wave Views Documentation Home |
Event loop class. More...
#include <ilviews/base/evloop.h>
Public Member Functions | |
IlvEventLoop (IlBoolean setIt=IlTrue) | |
Constructor. More... | |
virtual IlvIdleProcId | addIdleProc (IlvIdleProc idleProc, IlAny userArg) |
Add an idle procedure. More... | |
virtual void | addInput (int fd, IlvLoopCallback cb, IlAny arg=0, IlvLoopCallback errorCb=0) |
Adds an external source of input. More... | |
virtual void | addOutput (int fd, IlvLoopCallback cb, IlAny arg=0, IlvLoopCallback errorCb=0) |
Adds an external source of input. More... | |
virtual IlvRedrawProcLink * | addRedrawProc (IlvIdleProc redrawProc, IlAny userArg) |
Adds a redraw procedure. More... | |
virtual IlBoolean | dispatchEvent (IlAny systemEvent) |
Dispatches an event. More... | |
void | flushRedraw (IlUInt level=0) |
Executes any pending redraw requests. More... | |
IlUInt | lazyRedrawLevel () const |
See below. | |
virtual IlAny | nextEvent (IlAny systemEvent) |
Gets next event from the windowing system. More... | |
virtual IlvInputMask | pendingInput () |
Indicates pending input sources. More... | |
virtual IlvInputMask | processInput (IlvInputMask inputMask) |
Process input from the selected source. More... | |
virtual IlBoolean | removeIdleProc (IlvIdleProcId idleProcId) |
Removes an idle procedure from the event loop. More... | |
virtual void | removeInput (int fd) |
Removes an external source of input. More... | |
virtual void | removeOutput (int fd) |
Removes an external source of input. More... | |
virtual IlBoolean | removeRedrawProc (IlvRedrawProcLink *procId) |
Removes a redraw procedure from the queue. More... | |
void | setLazyRedraw (IlUInt lazy) |
Get/Set the lazy redraw mechanism. More... | |
Static Public Member Functions | |
static IlvEventLoop * | getEventLoop () |
Gets the current event loop. More... | |
static void | setEventLoop (IlvEventLoop *eventLoop) |
Sets the current event loop. More... | |
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.
Constructor.
Initializes an instance of event loop.
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 . |
|
virtual |
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:
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.
idleProc | The idle procedure. |
userArg | The argument to use when calling the idle procedure. |
|
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)
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. |
IlvRegisterInput
.
|
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)
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. |
IlvRegisterOutput
.
|
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()
.
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.
systemEvent | Pointer to a system-dependant event type; it is equivalent to XEvent* on Unix/X11 platforms and to MSG* on Windows platforms. |
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.
|
static |
Gets the current event loop.
IlvEventLoop
currently being used. 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
.
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. 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. |
|
virtual |
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.
IlvInputNone:
no input pending IlvInputAll:
all types of input are pending OR
combination of:IlvInputEvent:
events are pending IlvInputTimer:
timers are pending IlvInputExternal:
external inputs are pending IlvInputAll
is equal to: (IlvInputEvent | IlvInputTimer | IlvInputExternal)
|
virtual |
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:
processInput
member function does not return the type of input processed (since this information is not provided by Xt). IlvInputMask
are supported. The supported values are the following:IlvInputEvent | IlvInputTimer
IlvInputTimer
IlvInputExternal
IlvInputAll
inputMask | An OR combination of IlvInputEvent , IlvInputTimer , and IlvInputExternal specifying the sources of input to process. |
|
virtual |
Removes an idle procedure from the event loop.
IlFalse
if the idle procedure could not be found. Otherwise, IlTrue
is returned. idleProcId | The ID number identifying the idle procedure for the event loop. This value was returned by addIdeProc . |
|
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.
fd | The file descriptor to remove as source of input. |
IlvUnRegisterInput
.
|
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.
fd | The file descriptor to remove from the event loop. |
IlvUnRegisterOuput
.
|
virtual |
Removes a redraw procedure from the queue.
procId | A pointer to the redraw procedure that must be removed. |
IlTrue
if the removal was successful, or IlFalse
otherwise.
|
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.
eventLoop | The event loop to set. |
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/
preempt the lazy redraw mechanism to maintain compatibility with former deferred redraw mechanisms. This means that calls to reDrawViews
willinvalidateRegion
inside a pair of initReDraw/
not schedule a redraw task, and that the most external reDrawViews
willreDrawViews
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/
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 reDrawViews
will2
.
The environment variable ILV_LAZY_REDRAW
can be used to control the lazy redraw mode externally.
lazy | Integer value indicating the type of lazy redraw mechanism to use. |
© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.