rwlogo

Rogue Wave Views
Foundation Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions | Static Public Member Functions
IlvEventLoop Class Reference

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

Detailed Description

Event loop class.

Library: display

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.

Constructor & Destructor Documentation

IlvEventLoop::IlvEventLoop ( IlBoolean  setIt = IlTrue)

Constructor.

Initializes an instance of event loop.

Parameters
setItIf it is set to IlTrue, the new instance is set as the current event loop by a call to the static member function setEventLoop.

Member Function Documentation

virtual IlvIdleProcId IlvEventLoop::addIdleProc ( IlvIdleProc  idleProc,
IlAny  userArg 
)
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:

  1. It removes the top-most idle procedure from the stack.
  2. It calls the idle procedure.
  3. 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
idleProcThe idle procedure.
userArgThe argument to use when calling the idle procedure.
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
fdFile descriptor of a type supported by select.
cbThe user callback to call when fd is ready for reading.
argThe user argument to pass to cb or errorCb.
errorCbThe user callback to call when an error is detected on the file descriptor fd.
See Also
IlvRegisterInput.
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
fdFile descriptor of a type supported by select.
cbThe user callback to call when fd is ready for writing.
argThe user argument to pass to cb or errorCb.
errorCbThe user callback to call when an error is detected on the file descriptor fd.
See Also
IlvRegisterOutput.
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().

virtual IlBoolean IlvEventLoop::dispatchEvent ( IlAny  systemEvent)
virtual

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
systemEventPointer 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 IlvEventLoop* IlvEventLoop::getEventLoop ( )
static

Gets the current event loop.

Returns
The instance of IlvEventLoop currently being used.
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
systemEventPointer 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 IlvInputMask IlvEventLoop::pendingInput ( )
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.

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)
virtual IlvInputMask IlvEventLoop::processInput ( IlvInputMask  inputMask)
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:

  • 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
inputMaskAn OR combination of IlvInputEvent, IlvInputTimer, and IlvInputExternal specifying the sources of input to process.
virtual IlBoolean IlvEventLoop::removeIdleProc ( IlvIdleProcId  idleProcId)
virtual

Removes an idle procedure from the event loop.

Returns
IlFalse if the idle procedure could not be found. Otherwise, IlTrue is returned.
Parameters
idleProcIdThe ID number identifying the idle procedure for the event loop. This value was returned by addIdeProc.
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
fdThe file descriptor to remove as source of input.
See Also
IlvUnRegisterInput.
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
fdThe file descriptor to remove from the event loop.
See Also
IlvUnRegisterOuput.
virtual IlBoolean IlvEventLoop::removeRedrawProc ( IlvRedrawProcLink *  procId)
virtual

Removes a redraw procedure from the queue.

Parameters
procIdA pointer to the redraw procedure that must be removed.
Returns
IlTrue if the removal was successful, or IlFalse otherwise.
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
eventLoopThe 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/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
lazyInteger value indicating the type of lazy redraw mechanism to use.

© Copyright 2014, 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.