Handling User Input
139
Handling User Input
Events, such as mouse motion, key presses, and window resize, are converted to csEvent
objects and queued on their associated csWindow. When the application is ready to
process these events the getEvents() method of each csWindow can be called to get the
array of queued csEvent’s. After processing the events, the event array should be
discarded by calling the window’s resetEvents() method.
Using Callback Functions
Retrieving and handling user events using getEvents() requires constant polling by the
application, which can waste processor time. To avoid this polling, a Cosmo 3D
application typically sets event callbacks on csWindow objects and calls the static
csWindow::mainLoop() method to handle all event processing. Using callbacks, the
application is notified when events are waiting to be processed.
To set up event callbacks, an application can use either csWindow::setFrameFunc() or the
newer (recommended) methods, setEventFunc(), setRenderFunc(), and setFreeRun().
The user-defined, callback’s return value of setFrameFunc() controls the manner in
which events are processed. The return values include:
• BLOCK—the event processing loop blocks until another event occurs on some
window.
In BLOCK mode, the callback is called for every event, but not at all when no events
are generated.
• CONTINUE—the callback is called every time the main loop goes idle.
In CONTINUE mode, events are queued and delivered when things go idle. The
callback continues to be called even when no events are generated.
Each window has its own “frameFunc” and that function is called when there are events
on that window. This model gets confusing when multiple windows use the CONTNUE
mode.
setEventFunc() defines a per-window event callback similar to setFrameFunc(), but the
mode of event handling is controlled by csWindow::setFreeRun(). When there are no
more events to process a global callback, setRenderFunc() is called indicating the
windows should be re-rendered.
