qmlGamepad.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
//! \file qmlGamepad.h
//! \brief QML-based virtual gamepad UI component for custom input device example
//!
//! DtQmlGamepad implements a touch screen interface mimicking a gamepad, demonstrating
//! how to integrate QML-based UI with VR-Engage's input system. This serves as the
//! user-facing UI component for the custom input device example, showing the complete
//! pattern for bridging QML events into VR-Engage's C++ input processing pipeline.
 
#pragma once
 
#include "export.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <vrvUtil/signalslib.h>
#include "vreUtil/delegate.h"
 
#include <QObject>
 
#include <unordered_set>
 
class QQuickItem;
 
namespace makVre
{
//! \brief QML-based virtual gamepad UI that bridges QML events to C++ input callbacks
//!
//! DtQmlGamepad loads a QML user interface displaying virtual gamepad controls (buttons,
//! joysticks) and translates Qt Quick touch events into a generic event format that can
//! be consumed by VR-Engage's input system.
//!
//! Key Patterns Demonstrated:
//! - QML-to-C++ event bridging using Q_INVOKABLE methods
//! - Context property registration for QML access to C++ objects
//! - QML page lifecycle management (load, show/hide, unload)
//! - Application state-driven UI visibility control
//! - Generic event callback system using DtDelegate
//!
//! This class acts as the "view" layer in a custom input device implementation,
//! handling presentation and user interaction while delegating input processing
//! to DtQmlGamepadInputDevice.
//!
//! Integration with DtQmlGamepadInputDevice:
//! DtQmlGamepadInputDevice registers callbacks with this class to receive input
//! events, then transforms them into DtInputData structures for VR-Engage's
//! input mapping system.
//!
class INPUTDEVICE_DLL DtQmlGampad : public QObject
{
   Q_OBJECT;
 
public:
   DtQmlGampad();
   virtual ~DtQmlGampad();
 
   //! \brief Register a callback to receive virtual gamepad input events
   //!
   //! PATTERN: Callback Registration for Custom Input Devices
   //! Custom input devices should provide a callback mechanism allowing consumers
   //! to receive events without tight coupling. This pattern uses DtDelegate to
   //! store member function pointers with type-safe invocation.
   //!
   //! The callback signature is: void(std::string eventType, int id, double value)
   //! - eventType: "axis", "button", "hat", etc.
   //! - id: Control identifier (e.g., axis 0, button 1)
   //! - value: Event value (axis deflection, button state)
   //!
   //! REUSABLE: This callback pattern can be adapted for any event-driven device
   //! interface where multiple consumers need to receive events.
   //!
   //! \tparam T Type of the object receiving callbacks
   //! \tparam Method Member function pointer type
   //! \param object Pointer to the object instance that will receive callbacks
   //! \param method Member function to invoke when events occur
   //!
   template <typename T, typename Method>
   void addEventCallback(T* object, Method method)
   {
      myEventCallbacks[object] = EventCallback(object, method);
   }
 
   //! \brief Remove a previously registered event callback
   //!
   //! Should be called during cleanup (typically in the input device's shutdown()
   //! method) to prevent callbacks to destroyed objects.
   //!
   //! \tparam T Type of the object that registered the callback
   //! \tparam Method Member function pointer type (unused but kept for symmetry)
   //! \param object Pointer to the object whose callback should be removed
   //! \param method Member function (unused in current implementation)
   //!
   template <typename T, typename Method>
   void removeEventCallback(T* object, Method method)
   {
      myEventCallbacks.erase(object);
   }
 
   //! \brief QML-invokable method called when virtual gamepad generates input
   //!
   //! PATTERN: QML-to-C++ Event Bridge
   //! This method is marked Q_INVOKABLE and registered as a QML context property
   //! (named "DtQmlGamepad" in QML), allowing the QML UI to call directly into
   //! C++ when user interacts with on-screen controls:
   //!
   //!   // In QML:
   //!   onPressed: DtQmlGamepad.qmlEvent("button", buttonId, 1.0)
   //!
   //! The Q_INVOKABLE macro makes this method accessible from QML script code.
   //! Qt's meta-object system handles type conversions between QML types (QString,
   //! qreal) and C++ types automatically.
   //!
   //! REUSABLE: This pattern applies to any QML-based custom UI that needs to
   //! communicate events to VR-Engage components.
   //!
   //! \param type Input event type string ("axis", "button", "hat", etc.)
   //! \param id Control identifier within that type (e.g., button 0, axis 1)
   //! \param value Event value (button pressed=1.0/released=0.0, axis deflection)
   //!
   virtual Q_INVOKABLE void qmlEvent(QString type, int id, qreal value);
 
   //! \brief Show the virtual gamepad UI
   //!
   //! Typically called when entering engaged/gameplay state. The QML page becomes
   //! visible and interactive.
   //!
   virtual void show();
 
   //! \brief Hide the virtual gamepad UI
   //!
   //! Typically called when leaving engaged state (returning to menus, disconnecting).
   //! The QML page is hidden but remains loaded for quick re-display.
   //!
   virtual void hide();
 
protected:
   //! \brief Message handler to automatically show/hide gamepad based on app state
   //!
   //! PATTERN: UI Visibility Driven by Application State
   //! VR-Engage applications progress through states: Disconnected → Connecting →
   //! RoleSelection → Engaged. Custom UI should typically only be visible during
   //! the ENGAGED_STATE when the player is actively controlling an entity.
   //!
   //! This handler listens for state change messages and automatically shows/hides
   //! the gamepad appropriately. This is preferable to manually tracking state
   //! in multiple places.
   //!
   //! \param msg State change message from DtPlayerStationStateManager
   //! \return HANDLED to indicate message was processed
   //!
   virtual makVre::DtVreMessageResult handleAppStateMessage(makVre::DtVreMessage* msg);
 
   //! \brief Check if QML gamepad UI is currently visible
   //! \return true if visible, false if hidden or not loaded
   virtual bool isVisible();
 
   //! \brief Set QML gamepad UI visibility state
   //! \param visible true to show, false to hide
   virtual void setVisibility(bool visible);
 
protected:
   //! Callback delegate type for input events
   using EventCallback = DtDelegate<void, std::string, int, double>;
 
   QQuickItem* myRoot;              //!< Root QML item of the gamepad UI
   std::string myTargetWindow;      //!< Window identifier for QML placement
   std::string myTargetFile;        //!< Path to QML file defining UI
   
   //! Registered event callbacks keyed by object pointer
   //! When input events occur, all registered callbacks are invoked
   std::map<void*, EventCallback> myEventCallbacks;
};
 
} // namespace makVre