Index: sources/main.h =================================================================== diff -u -r7edcaf054062754370e0abd165f17ca9941b7d07 -rb8dd541d377ad1e8d7b988ce0163d99bff53843f --- sources/main.h (.../main.h) (revision 7edcaf054062754370e0abd165f17ca9941b7d07) +++ sources/main.h (.../main.h) (revision b8dd541d377ad1e8d7b988ce0163d99bff53843f) @@ -7,7 +7,7 @@ * * \file main.h * \author (last) Behrouz NematiPour - * \date (last) 30-Jul-2020 + * \date (last) 08-Sep-2020 * \author (original) Behrouz NematiPour * \date (original) 28-Oct-2019 * @@ -33,6 +33,10 @@ vCLASS(vCLASS const &) = delete; \ vCLASS & operator = (vCLASS const &) = delete; \ public: \ + /*! \brief instance accessor + \details A singleton class single instance creator/accessor + \return reference to the class static instance + */\ static vCLASS &I() { \ static vCLASS _instance; \ return _instance; \ @@ -50,46 +54,77 @@ //--------------------------------------------------------------------------------// #define DEBUG_PROPERTY_CHANGED(vVARIABLE, PREFIX) // qDebug() << "#" << #vVARIABLE << PREFIX##vVARIABLE; //--------------------------------------------------------------------------------// -#define PROPERTY_SLOT( vTYPE , vVARIABLE ) \ - protected : \ - void vVARIABLE ( const vTYPE & v##vVARIABLE ) { \ - static bool init = false; \ - if ( !init || _##vVARIABLE != v##vVARIABLE ) { \ - DEBUG_PROPERTY_CHANGED(vVARIABLE, v) \ - init = true; \ - _##vVARIABLE = v##vVARIABLE; \ - emit vVARIABLE##Changed( _##vVARIABLE ); \ - } \ +#define PROPERTY_SLOT( vTYPE , vVARIABLE ) \ + protected : \ + /*! \brief Property setter + \details The property setter which update the private variable \n + - if only the value has been changed \n + - or it's the first time property is set. \n + emits the Property notify (...Changed) signal on update. \n + the notify signal (...Changed) passes the new value as its parameter. \n + \param new value + */\ + void vVARIABLE ( const vTYPE & v##vVARIABLE ) { \ + static bool init = false; \ + if ( !init || _##vVARIABLE != v##vVARIABLE ) { \ + DEBUG_PROPERTY_CHANGED(vVARIABLE, v) \ + init = true; \ + _##vVARIABLE = v##vVARIABLE; \ + emit vVARIABLE##Changed( _##vVARIABLE ); \ + } \ } //--------------------------------------------------------------------------------// -#define TRIGGER_SLOT( vTYPE , vVARIABLE ) \ - protected: \ - void vVARIABLE ( const vTYPE & v##vVARIABLE ) { \ - DEBUG_PROPERTY_CHANGED(vVARIABLE, v) \ - _##vVARIABLE = v##vVARIABLE; \ - emit vVARIABLE##Triggered( _##vVARIABLE ); \ +#define TRIGGER_SLOT( vTYPE , vVARIABLE ) \ + protected: \ + /*! \brief Trigger setter + \details The Trigger setter which update the private variable \n + with no condition each time the value the passed. \n + emits the Trigger notify (...Triggered) signal after update. \n + the notify signal (...Triggered) passes the new value as its parameter.\n + \param new value + */\ + void vVARIABLE ( const vTYPE & v##vVARIABLE ) { \ + DEBUG_PROPERTY_CHANGED(vVARIABLE, v) \ + _##vVARIABLE = v##vVARIABLE; \ + emit vVARIABLE##Triggered( _##vVARIABLE ); \ } //--------------------------------------------------------------------------------// -#define PROPERTY_BASE(vTYPE , vVARIABLE , vDEFVALUE, vSIGNAL) \ - Q_PROPERTY( vTYPE vVARIABLE \ - READ vVARIABLE \ - WRITE vVARIABLE \ - NOTIFY vVARIABLE##vSIGNAL) \ - Q_SIGNALS: \ - void vVARIABLE##vSIGNAL( const vTYPE & v##vVARIABLE ); \ - private: \ - vTYPE _##vVARIABLE = vDEFVALUE; \ - protected: \ - vTYPE vVARIABLE () const { \ - return _##vVARIABLE ; \ - } +#define PROPERTY_BASE(vTYPE , vVARIABLE , vDEFVALUE, vSIGNAL) \ + /*! \brief Qt Property declaration + \details The Qt Property definition by Q_PROPERTY documentation. + */\ + Q_PROPERTY( vTYPE vVARIABLE \ + READ vVARIABLE \ + WRITE vVARIABLE \ + NOTIFY vVARIABLE##vSIGNAL) \ + Q_SIGNALS: \ + /*! \brief Property notify signal + \details The property notify signal (...Changed) + which will be emitted by property setter + - if only the value has been changed \n + - or it's the first time property is set. \n + \return current value + */\ + void vVARIABLE##vSIGNAL( const vTYPE & v##vVARIABLE ); \ + private: \ + vTYPE _##vVARIABLE = vDEFVALUE; \ + protected: \ + /*! \brief Property getter + \details The property getter which reads the private variable + \return current value + */\ + vTYPE vVARIABLE () const { \ + return _##vVARIABLE ; \ + } //--------------------------------------------------------------------------------// -#define PROPERTY( vTYPE , vVARIABLE , vDEFVALUE ) \ - PROPERTY_BASE( vTYPE , vVARIABLE , vDEFVALUE , Changed ) \ +#define PROPERTY( vTYPE , vVARIABLE , vDEFVALUE ) \ + \ + PROPERTY_BASE( vTYPE , vVARIABLE , vDEFVALUE , Changed ) \ PROPERTY_SLOT( vTYPE , vVARIABLE) //--------------------------------------------------------------------------------// -#define TRIGGER( vTYPE , vVARIABLE , vDEFVALUE ) \ - PROPERTY_BASE( vTYPE , vVARIABLE , vDEFVALUE , Triggered) \ +#define TRIGGER( vTYPE , vVARIABLE , vDEFVALUE ) \ + \ + PROPERTY_BASE( vTYPE , vVARIABLE , vDEFVALUE , Triggered) \ TRIGGER_SLOT( vTYPE , vVARIABLE) //--------------------------------------------------------------------------------// //--------------------------------------------------------------------------------// @@ -114,53 +149,91 @@ //--------------------------------------------------------------------------------// #define ACTION_RECEIVE_PRIVATE_SLOT(vTYPE) \ private Q_SLOTS: \ + /*! \brief Bridge slot + \details The bridge slot is for thread safety between classes for received message + and is used to emit its signal to pass the model data to next observer. + \param vData - The model data which has been received. + \note This method is private and the interface is signals only. (starts with 'on') + */\ void onActionReceive (const vTYPE &vData) { \ emit didActionReceive(vData); \ } //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_PRIVATE_SLOT_DEFINITION(vTYPE) \ private Q_SLOTS: \ + /*! \brief Adjustment slot + \details The bridge slot is for thread safety between classes for adjustment messages + and is used to emit its signal to pass the model data to next observer. + \param vData - The model data to be used for adjustment + \note This method is private and the interface is signals only. (starts with 'on') + This slot has to have its specific implementation and is not a bridge (not a signal emitter). + */\ void onAdjustment (const vTYPE &vData); //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_PRIVATE_SLOT(vTYPE) \ private Q_SLOTS: \ + /*! \brief Adjustment bridge slot + \details The bridge slot is for thread safety between classes for adjustment messages + and is used to emit its signal to pass the model data to next observer. + \param vData - The model data to be used for adjustment + \note This method is private and the interface is signals only. (starts with 'on') + */\ void onAdjustment (const vTYPE &vData) { \ emit didAdjustment( vData); \ } //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_PUBLIC_SLOT(vTYPE) \ public Q_SLOTS: \ + /*! \brief Adjustment invocable/exposed slot + \details This slot is able to be called within QML context + when an object of the class is instantiated in QML. + For thread safety it's calling its designated signal to notify observers. + \note This method is public and is the interface. (starts with 'do') + */\ void doAdjustment (const vTYPE &vData) { \ emit didAdjustment( vData); \ } //--------------------------------------------------------------------------------// #define ACTION_RECEIVE_SIGNAL(vTYPE) \ Q_SIGNALS: \ + /*! \brief Receive bridge signal + \details The bridge signal is for thread safety between classes for received message + and is used to be emitted in its slot to pass the model data to next observer. + \param vData - The model data which has been received. + \note This method is public to be exposed to the observers to be able to connect to it as the interface. (starts with 'did') + */\ void didActionReceive (const vTYPE &vData); //--------------------------------------------------------------------------------// -#define ACTION_TRANSMT_SIGNAL(vTYPE) \ -Q_SIGNALS: \ - void didActionTransmit(const vTYPE &vData); -//--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_SIGNAL(vTYPE) \ Q_SIGNALS: \ + /*! \brief Adjustment bridge signal + \details The bridge signal is for thread safety between classes for received message + and is used to be emitted in its slot to pass the model data to next observer. + \param vData - The model data which has been received. + \note This method is public to be exposed to the observers to be able to connect to it as the interface. (starts with 'did') + */\ void didAdjustment (const vTYPE &vData); //--------------------------------------------------------------------------------// #define ACTION_RECEIVE_BRIDGE_DEFINITION(vTYPE) \ + \ ACTION_RECEIVE_PRIVATE_SLOT (vTYPE) \ - ACTION_RECEIVE_SIGNAL (vTYPE) + ACTION_RECEIVE_SIGNAL (vTYPE) \ //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_BRIDGE_DEFINITION_NOEMIT(vTYPE) \ + \ ADJUST_TRANSMT_PRIVATE_SLOT_DEFINITION (vTYPE) \ - ADJUST_TRANSMT_SIGNAL (vTYPE) + ADJUST_TRANSMT_SIGNAL (vTYPE) \ //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_BRIDGE_DEFINITION(vTYPE) \ + \ ADJUST_TRANSMT_PRIVATE_SLOT (vTYPE) \ - ADJUST_TRANSMT_SIGNAL (vTYPE) + ADJUST_TRANSMT_SIGNAL (vTYPE) \ //--------------------------------------------------------------------------------// #define ADJUST_TRANSMT_BRIDGE_DEFINITION_PUBLIC(vTYPE) \ + \ ADJUST_TRANSMT_PUBLIC_SLOT (vTYPE) \ - ADJUST_TRANSMT_SIGNAL (vTYPE) + ADJUST_TRANSMT_SIGNAL (vTYPE) \ + //--------------------------------------------------------------------------------// #define REGISTER_METATYPE(vTYPE) \ qRegisterMetaType < vTYPE > (#vTYPE);