IlvEventLoop Class Reference

Event loop class. More...

#include <ilviews/base/evloop.h>

List of all members.

Public Member Functions
	IlvEventLoop (IlBoolean setIt=((IlBoolean) 1))
	Constructor.
virtual IlvIdleProcId	addIdleProc (IlvIdleProc idleProc, IlAny userArg)
	Add an idle procedure.
virtual void	addInput (int fd, IlvLoopCallback cb, IlAny arg=0, IlvLoopCallback errorCb=0)
	Adds an external source of input.
virtual void	addOutput (int fd, IlvLoopCallback cb, IlAny arg=0, IlvLoopCallback errorCb=0)
	Adds an external source of input.
virtual IlvRedrawProcLink *	addRedrawProc (IlvIdleProc redrawProc, IlAny userArg)
	Adds a redraw procedure.
virtual IlBoolean	dispatchEvent (IlAny systemEvent)
	Dispatches an event.
void	flushRedraw (IlUInt level=0)
	Executes any pending redraw requests.
IlUInt	lazyRedrawLevel () const
	See below.
virtual IlAny	nextEvent (IlAny systemEvent)
	Gets next event from the windowing system.
virtual IlvInputMask	pendingInput ()
	Indicates pending input sources.
virtual IlvInputMask	processInput (IlvInputMask inputMask)
	Process input from the selected source.
virtual IlBoolean	removeIdleProc (IlvIdleProcId idleProcId)
	Removes an idle procedure from the event loop.
virtual void	removeInput (int fd)
	Removes an external source of input.
virtual void	removeOutput (int fd)
	Removes an external source of input.
virtual IlBoolean	removeRedrawProc (IlvRedrawProcLink *procId)
	Removes a redraw procedure from the queue.
void	setLazyRedraw (IlUInt lazy)
	Get/Set the lazy redraw mechanism.
Static Public Member Functions
static IlvEventLoop *	getEventLoop ()
	Gets the current event loop.
static void	setEventLoop (IlvEventLoop *eventLoop)
	Sets the current event loop.

---

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 = ((IlBoolean) 1)

)

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.

---

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:

	idleProc	The idle procedure.
	userArg	The 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:

	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.

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.

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:

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

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

inputMask

An 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:

idleProcId

The 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:

fd

The 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:

fd

The 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:

procId

A 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:

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