(v13) Advanced use of events

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

It is possible for a higher priority handler to modify an Event before the remaining handlers get it. Handlers can use the SwEventTail () mechanism to call the remaining handlers, potentially multiple times; modify the results of what the remaining handlers did and then, potentially, return a different value than would normally have been returned. In addition, SW_EVENT_FORCE_UNHANDLED can be used to make it appear that none of the handlers handled the Event, even if one of the remaining handlers had returned SW_EVENT_HANDLED.

An example of this could be a simple Event used to report error messages to the RIP skin or device. Consider that an error is reported using an Event. A default handler will pick up the error and display a message on the LCD. It is possible that another handler could be used to modify the error message by either suppressing it or, by having the

SwEventTail () mechanism call the default handler multiple times to pass on the original message and add an extra line of text. In fact, it could call it multiple times to add further lines of text before returning SW_EVENT_FORCE_UNHANDLED or SW_EVENT_HANDLED to exit the loop and return to the Event issuer. This is done in response to the system generating a single line of text.

Note that only SW_EVENT_CONTINUE causes the Event to be submitted to the next handler. Any other return value is returned to the caller (who may be the original Event issuer, or may be a previous handler that has called SwEventTail ()).

In pseudo-code, a handler that wants to prefix an error report with "Error!" could do this:

                      copy = event->message ; event->message = "Error!" ;
                      (void) SwEventTail(event) ; /* Call remaining with our message */
                      event->message = copy ;
                      return SW_EVENT_CONTINUE ; /* Then pass on the original */
                      Or, if it wanted to postfix with "Sorry!":
                      (void) SwEventTail(event) ; /* Call remaining with original */ event->message = "Sorry!" ;
                      return SW_EVENT_CONTINUE ; /* Then pass on our line */

Using SwEventTail () does not compel you to use any particular return code. The difficulty in using worked examples is distinguishing between syntax mandated by the Event system itself, and syntax required by the protocol implemented using the Event system. This is why we need to be clear about return codes. SW_EVENT_CONTINUE continues to the next handler (if there is one), or returns SW_EVENT_UNHANDLED to the issuer. Any other return code gets returned to the issuer immediately. It is for this reason that SW_EVENT_CONTINUE and SW_EVENT_UNHANDLED are in fact synonyms use whichever is most consistent with the idiom in use.