attributeCallback.h

Go to the documentation of this file.

/******************************************************************************
 ** Copyright (c) 2025 MAK Technologies
 ** All rights reserved.
 ******************************************************************************/
 
//! \file attributeCallback.h
//! \ingroup vreUtil
//! \brief Provides a callback mechanism for attribute changes in the VREngage system
//!
//! This file defines the DtAttributeChangeCallback class which provides a scoped
//! callback wrapper for attribute changes. It allows objects to register callbacks
//! that are invoked when attributes are modified.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreutil/delegate.h"
 
#include <list>
#include <map>
 
namespace makVre
{
class DtAttribute;
class DtAttributeHandle;
 
class UTIL_DLL DtAttributeCallbackBase
{
public:
   DtAttributeCallbackBase();
 
   //! \brief Virtual destructor
   //!
   //! Automatically disconnects from all connected attributes
   virtual ~DtAttributeCallbackBase();
 
   //! \brief Connects the callback to an attribute
   //! \param attribute Reference to the attribute to connect to
   virtual void connect(DtAttributeHandle attribute);
 
   //! \brief Disconnects the callback from a specific attribute
   //! \param attribute Reference to the attribute to disconnect from
   virtual void disconnect(DtAttributeHandle attribute);
 
   //! \brief Disconnects the callback from all connected attributes
   virtual void disconnectAll();
 
   //! \brief Checks if the callback is connected to a specific attribute
   //! \param attribute Reference to the attribute to check
   //! \return True if connected to the attribute, false otherwise
   virtual bool isConnected(const DtAttributeHandle& attribute) const;
 
   //! \brief Checks if the callback is connected to any attributes
   //! \return True if connected to at least one attribute, false otherwise
   virtual bool hasConnection() const;
 
   virtual unsigned int threadId() const;
 
protected:
   virtual void invoke(const DtAttributeHandle& changedAttribute) const = 0;
 
   friend class DtAttribute;
 
protected:
   //! \brief Type definition for the list of connected attributes
   using AttributeList = std::list<DtAttributeHandle>;
 
   //! \brief List of attributes this callback is connected to
   AttributeList myConnections;
 
   unsigned int myThreadId;
};
 
 
//! \brief Scoped attribute change callback wrapper
//!
//! This class provides a mechanism for registering callbacks that are triggered when attributes are changed.
//! It maintains a list of connected attributes and manages the lifecycle of these connections.
//!
//! This is a type-agnostic callback. It passes to the callback function an un-typed DtAttributeHandle
//! representing the attribute which was changed. If includeChildren is set false (default), then this
//! will be the same attribute to which the callback was connected. If includeChildren is set true,
//! the changed attribute may also be any child of the connected attribute.
class UTIL_DLL DtAttributeChangeCallback : public DtAttributeCallbackBase,
                                           public DtDelegate<void, const DtAttributeHandle&>
{
public:
   //! \brief Constructor for attribute callbacks using member functions
   //! 
   //! \tparam OBJECT_T Type of the object containing the method
   //! 
   //! \param object Pointer to the object containing the method
   //! \param method Method pointer to be called when an attribute changes
   template <class OBJECT_T>
   DtAttributeChangeCallback(OBJECT_T* object, void (OBJECT_T::*method)(const DtAttributeHandle&));
 
   //! \brief Constructor for attribute callbacks using static function
   //! \param func Pointer to function to be called when attribute changes
   DtAttributeChangeCallback(void (*func)(const DtAttributeHandle&));
 
   //! \brief Virtual destructor
   //!
   //! Automatically disconnects from all connected attributes
   virtual ~DtAttributeChangeCallback() override;
 
   //! \brief Set whether this callback should also be invoked for any change to any child attribute
   //! \param on Set true for callbacks on change to any child. Set false for callbacks only to the 
   //! connected attribute. Default is false.
   //! 
   //! Check current state with includesChildren()
   virtual void includeChildren(bool on);
 
   //! \brief Get whether this callback is set to trigger on changes to child attributes.
   //! 
   //! Set state with includeChildren(bool on)
   virtual bool includesChildren() const;
 
protected:
   virtual void invoke(const DtAttributeHandle& changedAttribute) const override;
 
protected:
   //! \brief Defines whether this callback is also invoked for any changes to children of the connected attribute.
   bool myIncludeChildren = false;
};
 
//! \brief Scoped attribute change callback wrapper
//!
//! This class provides a mechanism for registering callbacks that are triggered when attributes are changed.
//! It maintains a list of connected attributes and manages the lifecycle of these connections.
//!
//! This is a type-specific callback. The new value of the connected attribute is passed to the callback function.
template <typename T>
class DtAttributeValueCallback : public DtAttributeCallbackBase, public DtDelegate<void, T>
{
public:
   //! \brief Constructor for attribute callbacks using member functions
   //! 
   //! \tparam OBJECT_T Type of the object containing the method
   //! \tparam METHOD_T Pattern of the callback function, should be one of:
   //! void(OBJECT_T::*method)(const T&) or void(OBJECT_T::*method)(T)
   //! 
   //! \param object Pointer to the object containing the method
   //! \param method Method pointer to be called when an attribute changes
   template <class OBJECT_T, typename METHOD_T>
   DtAttributeValueCallback(OBJECT_T* object, METHOD_T method);
 
   //! \brief Constructor for attribute callbacks using static function
   //! 
   //! \tparam FUNC_T Pattern for the callback function, should be one of:
   //! void(*func)(const T&) or void(*func)(T)
   //! 
   //! \param func Pointer to function to be called when attribute changes
   template <typename FUNC_T>
   DtAttributeValueCallback(FUNC_T func);
 
   //! \brief Virtual destructor
   //!
   //! Automatically disconnects from all connected attributes
   virtual ~DtAttributeValueCallback() override;
 
protected:
   virtual void invoke(const DtAttributeHandle& changedAttribute) const override;
};
 
class UTIL_DLL DtAttributeCallbackManager
{
public:
   DtAttributeCallbackManager();
   virtual ~DtAttributeCallbackManager();
 
   DtAttributeCallbackManager(const DtAttributeCallbackManager&) = delete;
   DtAttributeCallbackManager& operator=(const DtAttributeCallbackManager&) = delete;
 
   // Attribute handle callbacks
   template <class OBJECT_T>
   void connect(DtAttributeHandle attr, OBJECT_T* object, void (OBJECT_T::*method)(const DtAttributeHandle&));
 
   void connect(DtAttributeHandle attr, void (*func)(const DtAttributeHandle&));
 
   // Value callbacks
   template <class OBJECT_T, typename ATTRIBUTE_T>
   void connect(DtAttributeHandle attr, OBJECT_T* object, void (OBJECT_T::*method)(const ATTRIBUTE_T&));
 
   template <class OBJECT_T, typename ATTRIBUTE_T>
   void connect(DtAttributeHandle attr, OBJECT_T* object, void (OBJECT_T::*method)(ATTRIBUTE_T));
 
   template <typename ATTRIBUTE_T>
   void connect(DtAttributeHandle attr, void (*func)(const ATTRIBUTE_T&));
 
   template <typename ATTRIBUTE_T>
   void connect(DtAttributeHandle attr, void (*func)(ATTRIBUTE_T));
 
   bool isConnected(DtAttributeHandle attr) const;
   DtAttributeCallbackBase* connection(DtAttributeHandle attr);
 
   void disconnect(DtAttributeHandle attr);
   void disconnectAll();
 
protected:
   std::map<std::string, std::unique_ptr<DtAttributeCallbackBase>> myCallbackMap;
};
 
} // namespace makVre