10.2 Custom events


So far, several types of predefined events have been mentioned. It is also possible to create custom events that can be raised and handled by your application. Visualize processes custom events no differently from predefined events. However, the setup requires an additional step - you must select a channel for your event type. The remainder of the logic is identical to the built-in event handling mechanism, as shown below:

[snippet 10.2.a]
intptr_t myEventType = 1; // select a channel for your custom events
MyEventHandler* myHandler = new MyEventHandler();
dispatcher.Subscribe(*myHandler, myEventType);
MyCustomEvent myEvent(myEventType); // creates an object based on the event type above
dispatcher.InjectEvent(myEvent); // puts this event into the event handling system
IntPtr myEventType = new IntPtr(1); // select a channel for your custom events
MyEventHandler myHandler = new MyEventHandler();
HPS.EventDispatcher dispatcher = HPS.Database.GetEventDispatcher();
dispatcher.Subscribe(myHandler, myEventType);
MyCustomEvent myEvent = new MyCustomEvent(myEventType); // creates an object based on the event type acquired above
dispatcher.InjectEvent(myEvent); // puts this event into the event handling system

The event dispatcher informs the MyEventHandler instance that it needs to listen for events on channel 1 through the call to Subscribe. A handler instance can subscribe to any number of channels. Next, the event is instantiated and assigned a channel of 1, which means it will eventually be routed to the handlers on that channel. Lastly, the event dispatcher injects the event onto the event queue with a call to InjectEvent.

As events are handled in their own separate thread, it is important that event handlers do not throw exceptions above their scope since there would be no way to catch the exception.

10.2.1 Dropping unimportant events

Sometimes, events are generated so quickly that they cannot be processed in real-time. Often, these quickly-generated events are extraneous or unimportant. For instance, if a user moves the mouse across the screen very quickly, we usually don't care about the cursor's intermediate locations, just the most recent position. On these occasions, Visualize will try to determine whether the event can be ignored based on the event's internal logic.

For custom events, it is possible to write this logic yourself. This is especially important when processing an event takes a lot of time. The drop attempt takes place when an event enters the queue. Visualize calls Event::Drop to determine whether or not the event is extraneous. It is attempted for all queued events on the same channel, or until Drop returns false (meaning the event is important and should not be dropped).

[snippet 10.2.1.a]
class MyEventHandler : public EventHandler
{
public:
~MyEventHandler() { Shutdown(); }
EventHandler::HandleResult Handle(Event const * in_event) const
{
// do any processing or recovery logic here
return HandleResult::Handled; // or return NotHandled, as the case may be
}
bool Drop(Event const * other_event) const
{
bool mergeable = false;
// ... some logic
if (mergeable == true)
return true;
return false;
}
};
class MyEventHandler : HPS.EventHandler
{
public override HandleResult Handle(HPS.Event in_event)
{
// do any processing or recovery logic here
return HandleResult.Handled; // or return NotHandled, as the case may be
}
public bool Drop(Event other_event)
{
bool mergeable = false;
// ... some logic
if (mergeable == true)
return true;
return false;
}
};