Crystal Space 2.0.0: C.5.2 iEvent Changes

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### C.5.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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated using texi2html 1.76.