==============
Event Handling
==============

Visualize uses its event handling system as an asynchronous way to respond to various types of events raised within the application. Key presses, mouse motion, errors, and warnings are all examples of asynchronous events. This section will describe how you can intercept events and process them so that your application responds appropriately.


Event Handling System Anatomy
-----------------------------

The event handler system consists of four main parts:

* ``HPS::Event`` objects, or a subclass thereof
* A number of channels, which direct events to the event handlers that are able to process them.
* The ``HPS::EventDispatcher``, which injects the event into the event queue based on the event's assigned channel.
* The ``HPS::EventHandler`` object which responds to the event. Event handlers listen for events on a particular channel.

The sequence below shows how these parts work together to handle events:

.. raw:: html
	
	<table class="table_style1">
		<tr>
			<td>1 - Something happens in the execution environment that requires a response from your application. This could be anything from a mouse click to a run-time error. You also have the ability to generate custom events at any time you require. For this example, we'll imagine Visualize has detected a mouse click in the main window.</td><td style="width: 100px;"><img style="padding-left: 30px;" src="../_images/cursor.png"></td>
		</tr>
		
		<tr>
			<td>2 - In order to process the mouse click, Visualize builds an HPS::Event object which includes information about what happened. At construction time, the event is assigned a channel which will later be used to get the event to a handler that is able to process it.</td><td style="width: 100px;"><img style="padding-left: 30px;" src="../_images/blue_dot.png"></td>
		</tr>
		
		<tr>
			<td>3 - Event is dispatched by the HPS::EventDispatcher. The dispatcher injects the event into the channel it was assigned to from the previous step. Visualize maintains a few default channels - examples include (but are not limited to) the error channel, warning channel, and keyboard event channel.</td><td style="width: 100px"><img style="padding-left: 30px;" src="../_images/arrow.png"></td>
		</tr>
		
		<tr>
			<td>4 - In our example, the mouse event channel (highlighted in green) is chosen. A single event instance can only go into one channel, however, there are no resistrictions on what type of event can go into which channel. Be aware that placing an event on a channel that is not equipped to handle it will likely result in your event being ignored.</td><td style="width: 100px"><img style="padding-left: 30px;" src="../_images/dispatcher.png"></td>
		</tr>
		
		<tr>
			<td>5 - Each line of small dots represents a stack of event handlers. Event handlers are associated with one or more channels. In this case, the orange dots represent a group of handlers that are able to process mouse click events. As the event is placed in the channel, the handler at the top of the stack gets to process the event first. The handler can consume the event or pass it on to the next handler in the stack. Our imaginary example ends with the first handler interpreting the mouse click as a selection event and highlighting a piece of geometry.</td><td style="width: 100px"><img style="vertical-align:text-top;" src="../_images/handlers.png"></td>
		</tr>
	</table>
	<br><br>

.. _event_handler_object:

The Event Handler Object
========================

The first step to handling events is to create your own event handler by subclassing ``HPS::EventHandler``. The ``Handle`` method is called when an event is dispatched, so any processing or recovery logic should be placed in that function, as shown below:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [MyEventHandler]
		   :end-before: //! [MyEventHandler]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [MyEventHandler]
		   :end-before: //! [MyEventHandler]

Note that the example above returns ``Handled``. You may also return ``NotHandled`` if for some reason this handler does not consume the event. In this case, the event would be passed to the next handler that is subscribed to handle events on that channel. See the next subsection for a discussion on the *event stack*.


**IMPORTANT:** Your event handler must call ``HPS::EventHandler::Shutdown`` in its destructor. Failure to do so may result in undefined behavior, including crashes or deadlocks.


.. _event_dispatcher:

The Event Dispatcher
====================

The next step to handling events is to instantiate your handler and subscribe it to an ``HPS::EventDispatcher``. There are several event dispatchers - the Database and application window each have their own, as well as any dispatchers for custom events that you create.

All handlers live in a stack with others of the same type. By defaut, if one handler can't process the event, (as indicated by returning ``NotHandled`` from ``EventHandler::Handle()``), the handler below it will receive the event. There can be any number of handlers in a stack. The code below demonstrates how to add an event handler for errors.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [dispatcher]
		   :end-before: //! [dispatcher]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [dispatcher]
		   :end-before: //! [dispatcher]

**IMPORTANT:** When your handler is destroyed, it will be automatically unsubscribed. Therefore, in order for the handler to work, it must not go out of scope. You are responsible for maintaining the pointer.

Note the second parameter to ``Subscribe`` in the code snippet. This parameter indicates which channel the handler will be subscribing to. You can associate any type of event with any channel.

As stated above, the default behavior of the event subsystem will cause an event to be consumed when the ``HPS::EventHandler::Handle`` function returns ``Handled``. However, this logic can be configured in different ways depending on your needs. For example, a channel can be set to never consume an event, or it could be set so that only the first handler in the stack processes the event, regardless of the result of ``HPS::EventHandler::Handle``.


.. _event_objects:

Event objects
=============

As mentioned previously, the error event is just one type of event. Warnings, errors, timer ticks, and key presses are all examples of Visualize events, and are typically injected on their own channel. Your handler can subscribe to any channel, or all of them. The ``HPS::Event`` class is abstract. In order to raise an event, you must subclass it...

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [MyEvent]
		   :end-before: //! [MyEvent]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [MyEvent]
		   :end-before: //! [MyEvent]

...before injecting your new event into the system.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [dispatch_MyEvent]
		   :end-before: //! [dispatch_MyEvent]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [dispatch_MyEvent]
		   :end-before: //! [dispatch_MyEvent]
		   

Notifiers
=========

You can use a notifier to learn that an event has been processed. A notifier is an object that is associated with an event injection and can be used to track its progress. Querying the notifier will tell you the status of the event:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [event_status]
		   :end-before: //! [event_status]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [event_status]
		   :end-before: //! [event_status]

It is also possible to simply wait until an event is handled using an ``HPS::EventNotifier``. The following code will cause its thread to sleep until the event handling is completed:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_event_handler.cpp
		   :start-after: //! [wait]
		   :end-before: //! [wait]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_event_handler.cs
		   :start-after: //! [wait]
		   :end-before: //! [wait]
		   