(v13) Implementation events

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

In the previous example the Event is used as permission before undertaking some action. Another model is to place that action as a default handler for the Event. The difference is far from cosmetic.

Consider a theoretical PostScript language error Event: it would be possible for a handler to do its own error handling (that is the intention after all) in fact it may choose to duplicate the existing error mechanism with some subtle difference or addition.

Returning SW_EVENT_HANDLED or setting message->suppress to TRUE as appropriate would only tell errorhandler () not to do what it was going to do it would not indicate if a suitable alternative had been done.

In other words, this event idiom already allows an action to be re-implemented, probably by some other system, possibly in the skin, perhaps contextually. However, it is not implicitly clear to the handler how much has already been done before the Event was issued, and how much can be disabled by handling it. Such details must be defined as part of the protocol.

The alternative is to place all such actions in a default handler a handler with a very low priority. This has two consequences: first it forces the author to define the effects of that Event very clearly; secondly it automatically provides an API for achieving that effect.

After all, any code can issue an Event.

A simple example is, if our theoretical handleerror () merely consisted of SwEvent (EVENT_PS_ERROR...), with the actual PostScript language mechanism as the default handler for that Event, then SwEvent (EVENT_PS_ERROR...) is entirely equivalent to calling handleerror () and, therefore, that mechanism can be invoked by anything that issues that Event. The Event becomes the API.

Another example can be found in HMR. When the Disable Output check box in the Throughput Controller dialog is toggled, a SWEVT_THROUGHPUT_ENABLE Event is sent. A handler for this Event contains the action code to set the desired output state. The same Event is sent when output needs to be enabled or disabled for any other reason (for example, when using the Cassette Manager dialog).