==============
Handling Input
==============

Input such as mouse and keyboard actions are injected into the HOOPS Visualize Desktop event thread in the same way that other events are. Thus, handling input is a similar process to handling other types of events. Before reading any further, you should be aware that it is possible to handle input events using operators, which are covered at :doc:`this link <0601_standard_operators>`.

For this example, we'll demonstrate how to handle a mouse event. HOOPS Visualize Desktop intercepts and injects all mouse events from the operating system into the event thread, including mouse motion and dragging. As previously discussed, the first step to handling any event is to create an event handler class. This is accomplished by subclassing ``EventHandler`` and overriding the ``Handle`` method so that it performs your custom logic. In this example, we'll simply get the location of the mouse event. HOOPS Visualize Desktop abstracts mouse events into ``LocatorEvent`` objects. A locator event could represent an  event from a traditional mouse or a touch-screen input event:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_handling_input.cs
		   :start-after: //! [handling_input]
		   :end-before: //! [handling_input]
		   
Lastly, you need to ensure your event handler is subscribed to the appropriate ``EventDispatcher``. In HOOPS Visualize Desktop, there are two event dispatchers - one from the ``Database`` which dispatches events such as errors and warnings, and one from the window which dispatches input events. In this case, we'll use the window event dispatcher.

.. tabs::

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

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

**NOTE:** Make sure you retain a reference to your event handler object! If it goes out of scope, it won't work.

The code in the above example assumes there was only one locator in the event, which is usually fine for an application using a conventional mouse. In a touch-screen application, there could by more than one locator returned if the user is touching the screen at more than one location. In that case, you should process each locator separately by examining the ``locatorEvent.Locators`` structure. In C++, that structure is an STL ``vector``, and in C# it is a simple array of Locator objects.
