C.1.2 iEvent Changes

Property Bags

The iEvent::Find() method was renamed to Retrieve() and exhibits different return value semantics. Rather than returning a mere boolean result, it now returns one of the `csEventError' enumeration constants. Of particular note, in the case of success, csEventErrNone is returned, which has a value of 0. This success value could be misinterpreted as "false" by the unwary when fixing code to deal with this semantic change. Conditionals which test if retrieval of an attribute succeeded must be changed to take this new semantic into account. For instance, code such as the following:

iEvent* ev = ...;
if (ev->Find(...))
{
  ...
}

must be changed to perform an explicit test on the return value of Retrieve(), rather than relying upon default boolean semantics:

if (ev->Retrieve(...) == csEventErrNone)
{
  ...
}

Mouse, Joystick, and Command event properties

The `union' containing the `Mouse', `Joystick', and `Command' structures has been removed; all event attributes are now stored and accessed using the Add() and Retrieve() mechanisms. To ease access to event data, use the static methods of the `csMouseEventHelper', `csJoystickEventHelper', and `csCommandEventHelper' classes. For example, code such as the following:

iEvent* ev = ...;
let X = ev->Mouse.X;

should be changed to:

iEvent* ev = ...;
let X = csMouseEventHelper::GetX(ev);

See the API documentation for details.

Multiple mice

There is now support for handling input from more than one mouse. You can retrieve the identity (basis 0) of the mouse producing a mouse event with csMouseEventHelper::GetNumber().

Joystick and Mouse axes

Joysticks can now have up to `CS_MAX_JOYSTICK_AXES' axes, and mice can have up to `CS_MAX_MOUSE_AXES'. Their values should be accessed using the csJoystickEventHelper::GetAxis() and csMouseEventHelper::GetAxis() functions, respectively, where both devices and axes are enumerated basis 0. Each helper class also has GetX() and GetY() methods available; for joystick events, these are deprecated.

This document was generated using texi2html 1.76.