Input Event Handling

Platform-agnostic abstraction layer for input event handling. More...

Collaboration diagram for Input Event Handling:

Detailed Description

Platform-agnostic abstraction layer for input event handling.

One essential building block of the ImFusionGUI component is the generic abstraction layer to handle input events from the user such as mouse, touch, or keyboard events.

The main classes and interfaces of this component are as follows:

• The InputEvent class for representing user inputs in a GUI.
• Classes receiving and handling InputEvents, usually referred to as "[Input] Event Handlers". There is no single base interface for them, however they usually implement a function with the signature EventResult handleInputEvent(const InputEvent& event). Most classes of this component such as Display, View, ViewObject, or ViewOverlay have such a member function.
• All event handlers return an EventResult to indicate how to continue and if the GUI should show any visual reaction to the event (such as mouse cursor, tooltip, context menu).

High-level overview of the ImFusion::GUI event handling flow.

A separate platform-specific wrapper will convert the native input events from the GUI toolkit (e.g. Qt) to the generic InputEvents. The InputEvent is then passed to one or multiple event handlers (usually the Display). They return a EventResult instance which can eventually converted back to platform-specific actions. The ImFusion SDK provides the necessary classes for integration into a Qt-based application. Integrations for other GUI toolkits are usually straight-forward to implement.

A basic input event handler function for a button overlay could look like this:

EventResult MyButtonOverlay::handleInputEvent(const InputEvent& event)
{
    EventResult result;
 
    if (const MouseEvent* mouseEvent = event.asMouseEvent())
    {
        // check if mouse pointer is hovering over the button area
        if (m_viewport.includesPoint(mouseEvent->position().cast<int>()))
        {
            m_buttonOverlay->setHighlighted(true);
 
            if (mouseEvent->type() == MouseEvent::Type::Press && mouseEvent->button() == MouseEvent::Button::Left)
            {
                // Claim the mouse event to get the buttonRelease later
                result.stopPropagation = true;
                m_wasPressed = true;
            }
 
            // show a tooltip if available
            if (!m_wasPressed && !m_tooltip.empty())
                result.tooltip = m_tooltip;
 
            // Only accept the release event if also the press event was handled before
            if (m_wasPressed && mouseEvent->type() == MouseEvent::Type::Release && mouseEvent->button() == MouseEvent::Button::Left)
            {
                m_wasPressed = false;
                signalClicked.emitSignal();
                if (showMenu())
                    result.contextMenu = createMenu();
                result.stopPropagation = true;
            }
        }
        else if (m_buttonOverlay->isHighlighted())
        {
            m_buttonOverlay->setHighlighted(false);
            m_wasPressed = false;
        }
    }
 
    return result;
}

Due to the hierarchical nature of the view framework a single InputEvent is often passed to multiple handlers in a cascading fashion until it is consumed in a terminal fashion and propagation stops. A typical usage looks like this

EventResult result;
for (ViewObject* object : objects) {
    result.combine(object->handleInputEvent(event));
    if (result.stopPropagation)
        return result;
}
return result;

Classes
struct	EventResult
	Simple record intended to be used as return value of the a handleInputEvent() function to indicate how to proceed. More...
class	InputEvent
	Base class for user input events in a graphical user interface (GUI). More...
class	KeyEvent
	Key events are triggered when a keyboard key was pressed or released on the GUI. More...
class	MouseEvent
	Mouse events are triggered whenever the status of the mouse has changed wrt. More...
class	TouchEvent
	Touch events occur when pressing, releasing, or moving one ore multiple touch points on a touch device. More...
class	ContextMenuEvent
	A ContextMenuEvent signals that a context-sensitive popup menu was requested by the user, for instance by a click with the right mouse button. More...
class	InputEventMapperBase
	Helper class to maintain a map of mouse/keyboard combinations to an enumeration of actions. More...
class	InputEventMapper< T >
	Specialization of InputEventMapperBase with a templated action enumeration type to increase type safety. More...
class	Menu
	Represents a hierarchical menu of actions used to describe menu bars, context menus, or popup menus. More...

Enumerations
enum class	MouseCursorShape {   Default , PointingHand , Crosshair , Help ,   Busy , Wait , OpenHand , ClosedHand ,   SizeVertical , SizeHorizontal , SizeDiagonalBLTR , SizeDiagonalTLBR ,   SizeAll , SplitVertical , SplitHorizontal , TextInput ,   Forbidden , Blank , Custom = 100 }
	Enumeration of cursor shapes that are usually available on all platforms. More...

Enumeration Type Documentation

MouseCursorShape

enum class MouseCursorShape

strong

#include <ImFusion/GUI/MouseCursorShape.h>

Enumeration of cursor shapes that are usually available on all platforms.

Enumerator
Default	Use the default cursor shape.
PointingHand	A pointing hand cursor that is typically used for clickable elements such as hyperlinks.
Crosshair	Crosshair cursor, typically used to help the user accurately select a point on the screen.
Help	Indicate that help information is available, usually a pointer with a question mark.
Busy	The program is busy in the background but the user can still interact with the interface.
Wait	The program is busy and the user can't interact with the interface.
OpenHand	Indicate that something can be grabbed and moved around.
ClosedHand	Indicate that something is currently being grabbed and moved around.
SizeVertical	Indicate that you can resize or move something vertically.
SizeHorizontal	Indicate that you can resize or move something horizontally.
SizeDiagonalBLTR	Indicate that you can resize or move something diagonally either in the bottom left or top right corner.
SizeDiagonalTLBR	Indicate that you can resize or move something diagonally either in the top left or bottom right corner.
SizeAll	Indicate that you can resize or move something in all directions.
SplitVertical	The handle/item/row can be resized vertically, for instance to adjust the amount of available space.
SplitHorizontal	The handle/item/column can be resized horizontally, for instance to adjust the amount of available space.
TextInput	Indicate that you can enter text underneath, usually represented by an I-beam.
Forbidden	Usually a slashed circle indicating that the action is impossible/not allowed.
Blank	Don't render any cursor.
Custom	If you need to extend this enumeration with application-specific shapes, this is the first value you can use.