(v13) Event usage patterns

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP

There are a number of ways of using the Events system:

• Notification (signaling something to interested parties)
• Permission (allowing a system to prevent an action from occurring)
• Implementation (causing some action to occur, though not necessarily by one specific system)
• Some combination of the above.

These various idioms are described in detail in later sections, but in brief: the issuer of a notification Event does not care about the return code the handlers return; an issuer of a permission Event will or will not carry out some action depending on the return code; an issuer of an Implementation Event is relying on a handler (typically low priority and referred to as the “default handler”) to perform some action, though the return code may have some significance.

In the implementation case, handlers may be registered to replace or modify the expected functionality, or indeed to take advantage of that functionality. For example, an Event could be used to send an error message to the skin, which would be expected under such a protocol to have registered a default handler for that Event which would log or display the error.

This allows a third-party system to register a handler for that Event and augment the error message with additional information by altering or replacing the Message.

Alternatively, it could use SwEventTail to send multiple messages to the remaining handlers including, one expects, the default handler.

These types of Events are merely different idioms they are all implemented by the issuer calling SwEvent with an optional Message and responding to the resulting return code. The exact protocol is defined as part of the definition of a particular Event type.

It is therefore possible to combine these various behaviors into a single Event. For example, a single Event with a default handler of normal priority that returns SW_EVENT_CONTINUE, can be seen as both permission for high priority handlers (as they could stop the default handler from being called) and notification for low priority handlers (as they are only called if the default handler carries out its action).