What needs to be done to implement a new event?

Table of Contents

• When to use this guide
• Origin and processing of Events
• Event Implementation
• Configuration File & Event Factory

When to use this guide

In general there are no restriction about how events are created and processed. The intention of this page is to provide how to construct Events in order to use them with the MITK Interaction Concept.

Origin and processing of Events

Interaction Concepts gives a brief description of how events are generated and processed. After events are created they need to be send via mitk::RenderWindowBase::HandleEvent() so that they are relayed to a Dispatcher which handles the event distribution to the DataInteractors.

Event Implementation

The only prerequisite for a new event to be accepted is that it is derived from the mitk::InteractionEvent class. The new event must implement at least two functions, as shown in the example of the MousePressEvent.

Implementation of equality for each event class by implementing IsEqual. Equality does not mean an exact copy or pointer equality. Equality is determined by agreement in all attributes that are necessary to describe the event for a state machine transition. Here, for example, for the a mouse event press event, it is important which modifiers are used, which mouse button was used to triggered the event, but the mouse position is irrelevant.

bool mitk::MousePressEvent::IsEqual(const mitk::InteractionEvent& interactionEvent)
{
  // cast to your event class here (this is guaranteed to work
  const mitk::MousePressEvent& mpe = static_cast<const mitk::MousePressEvent&>(interactionEvent);
  // Checking relevant attributes, such as EventButton and Modifiers, but omitting the mouse coordinates
  // Replace this to check for your event class' attributes
  return (this->GetEventButton() == mpe.GetEventButton() && this->GetModifiers() == mpe.GetModifiers()
      && this->GetButtonStates() == mpe.GetButtonStates()) && Superclass::IsEqual(interactionEvent);
}

The function IsSuperClassOf() implements an up cast to check if the provided baseClass object is derived from this class. This function is used to support polymorphism on state machine pattern (XML) level.

bool mitk::MousePressEvent::IsSuperClassOf(InteractionEvent::Pointer baseClass)
{
  // Replace with your class, or implement some rules which classes are accepted.
  MousePressEvent* event = dynamic_cast<MousePressEvent*>(baseClass.GetPointer());
  if (event != NULL)
  {
    return true;
  }
  return false;
}

Configuration File & Event Factory

Regarding the state machine and the state machine pattern parser there are no changes necessary. To be able to parse the new event, changes have to be made in the mitk::EventConfig and mitk::EventFactory classes.

The mitk::EventConfig class has to be adapted in a way such that the parameters that describe the event are parsed. The parsing can be easily extended, and should provide a mitk::PropertyList for each event parsed. Lastly the mitk::EventFactory has to be extended to use this mitk::PropertyList and construct an event based on it.