GUIDataPool.h

/*
* Copyright (C) TES Electronic Solutions GmbH,
* All Rights Reserved.
* Contact: info@guiliani.de
*
* This file is part of the Guiliani HMI framework
* for the development of graphical user interfaces on embedded systems.
*/
 
#ifndef GUIDATAPOOL__H_
#define GUIDATAPOOL__H_
 
#include "eC_Types.h"
#include "eC_TList_doubleLinked.h"
#include "eC_Semaphore.h"
#include "GUISubject.h"
#include "GUIObserver.h"
#include "eC_String.h"
#include "GUIValue.h"
#include "GUIObjectHandleResource.h"
#include "GUIDataPoolResource.h"
 
 
class CDataPoolEntry;
 
typedef void(*DataPoolCallback)(CDataPoolEntry&);
 
 
// @guiliani_doxygen toplevel_module DataPool
// @endguiliani_doxygen
 
 
 
class CDataPoolConnector : public CGUIObserver, public CGUISubject
{
public:
    CDataPoolConnector(CGUIObject* pkParentObject = NULL) :
        CGUIObserver(),
        m_pkParentObject(pkParentObject)
    {}
 
    void SetParentObject(CGUIObject* pkParentObject)
    {
        m_pkParentObject = pkParentObject;
    }
 
#ifndef GUILIANI_NO_DATAPOOL
    virtual void OnNotification(CDataPoolEntry& kObservedValue);
#endif
 
private:
    CGUIObject * m_pkParentObject;
 
    // Unused OnNotification slots. Declared only to prevent compiler warnings.
    virtual void OnNotification() {}
    virtual void OnNotification(const eC_String& kMessage) {}
    virtual void OnNotification(const CGUIObject* const pkUpdatedObject) {}
    virtual void OnNotification(const CGUIValue& kObservedValue, const CGUIObject* const pkUpdatedObject, const eC_UInt uiX = 0, const eC_UInt uiY = 0) {}
};
 
#ifndef GUILIANI_NO_DATAPOOL
 
class CDataPoolEntry : public CGUIObserver, public CGUISubject
{
    friend class CGUIDataPool;  
 
public:
    virtual const CGUIValue& Get(const eC_UInt uiX = 0, const eC_UInt uiY = 0);
 
    void GetQuantity(eC_UInt& uiX, eC_UInt& uiY)
    {
        uiX = m_uiMaxX;
        uiY = m_uiMaxY;
    }
 
    DataPoolResource_t GetID() const
    {
        return m_eDataID;
    }
 
protected:
    CDataPoolEntry();
 
    CDataPoolEntry(const CGUIValue& kValue);
 
    void SetQuantity(const eC_UInt uiX, const eC_UInt uiY, const eC_Bool& bPreserve = false);
 
    virtual void Set(const CGUIValue& kValue, const eC_UInt uiX = 0, const eC_UInt uiY = 0);
 
    virtual CDataPoolEntry& operator= (const CDataPoolEntry& kDataPoolEntry);
 
    void AddObserver(CDataPoolConnector *pObserver)
    {
        CGUISubject::AddObserver(pObserver);
    }
 
    void SetCallback(DataPoolCallback pCallback)
    {
        m_pDataPoolCallback = pCallback;
    }
 
    void NotifyDataPoolConnectors();
 
    virtual void OnNotification(const CGUIValue& kValue, const CGUIObject* const pkUpdatedObject, const eC_UInt uiX = 0, const eC_UInt uiY = 0);
 
protected:
    eC_UInt m_uiMaxX;
    eC_UInt m_uiMaxY;
 
    eC_TArray<CGUIValue> m_kValue;
 
    DataPoolResource_t m_eDataID;
 
    DataPoolCallback m_pDataPoolCallback;
 
    virtual ~CDataPoolEntry() {}
 
private:
    inline void SetID(const DataPoolResource_t &eID)
    {
        m_eDataID = eID;
    }
 
    void AddObserver(CGUIObserver *pObserver);
};
 
 
#define DATAPOOL_FILE_VERSION   3
 
class CGUIDataPool
{
public:
    typedef eC_TListDoubleLinked<DataPoolResource_t> DataIDList;
 
 
    static void Set(const DataPoolResource_t eDataID, CGUIValue kValue, const eC_UInt uiX = 0, const eC_UInt uiY = 0);
 
    static void Get(const DataPoolResource_t eDataID, CGUIValue& kValue, const eC_UInt uiX = 0, const eC_UInt uiY = 0);
 
    static void SetDataPoolEntry(const DataPoolResource_t eDataID, CDataPoolEntry* pkEntry);
 
    static void SetQuantity(const DataPoolResource_t eDataID, const eC_UInt uiX, const eC_UInt uiY, const eC_Bool& bPreserve = false);
 
    static void GetQuantity(const DataPoolResource_t eDataID, eC_UInt& uiX, eC_UInt& uiY);
 
    static void Get(const DataPoolResource_t eDataID, CDataPoolEntry **ppkEntry);
 
    static void GetUpdate(CDataPoolConnector* pkObserver);
 
 
    static eC_Bool Lock() { return ms_kDataPoolSema.Enter(); }
 
    static eC_Bool Unlock() { return ms_kDataPoolSema.Leave(); }
 
 
    static void Register(const DataPoolResource_t eDataID, CGUIObject* pkObserver);
 
    static void Register(const DataPoolResource_t eDataID, CDataPoolConnector* pkObserver);
 
    static void Register(const DataPoolResource_t eDataID, DataPoolCallback pCallback);
 
    static void UnregisterCallback(const DataPoolResource_t eDataID);
 
    static void Unregister(const DataPoolResource_t eDataID, CGUIObject* pkObserver);
 
    static void Unregister(const DataPoolResource_t eDataID, CDataPoolConnector* pkObserver);
 
    static void Unregister(CGUIObject* pkObserver);
 
    static void Unregister(CDataPoolConnector* pkObserver);
 
    static void AutoRegister(const DataPoolResource_t eDataID, const ObjectHandle_t eObjectID);
 
    static void RemoveAutoRegister(const DataPoolResource_t eDataID, const ObjectHandle_t eObjectID);
 
    static DataPoolResource_t RegisterDynamicDataPoolResource();
 
#ifdef GUILIANI_STREAM_GUI
    static eC_Bool ReadDataPoolFromFile(const eC_String& rkPath);
#endif
 
#ifdef GUILIANI_WRITE_GUI
    static void WriteDataPoolToFile(const eC_String& rkPath);
#endif
 
    static const eC_TListDoubleLinked<ObjectHandle_t> GetAutoRegisteredObservers(const DataPoolResource_t eDataID);
 
    static void AddToNotificationQueue(CDataPoolEntry& kEntry);
 
    static eC_UInt GetNOFDataPoolResources() { return ms_kDataPool.GetQuantity(); }
 
    static void Clear();
 
    static eC_UInt GetNumberOfPendingNotifications() { return ms_kPendingNotifications.GetQuantity(); }
 
    static void DumpDataPool();
 
private:
    // @todo to access private functions: only it may access NotifyOfCreation and NotifyOfDestruction
    friend class CGUIObject;
    // @todo to access private functions: only it may access ProcessNotifications
    friend class CGUI;
 
    // Called by CGUIObject base class upon construction of an object, or after an object got sucessfully streamed.
    static void NotifyOfCreation(CGUIObject* pkObject);
 
    // Once per cycle, the GUI checks for changes in the DataPool and Notifies all registered observers
    static void ProcessNotifications();
 
    // Called by CGUI during initialization
    static void Init();
 
    // Called by CGUI during DeInit
    static void DeInit();
 
    // Resizes the internal array of data pool entries to the given size
    static eC_Bool SetNOFDataPoolResources(const eC_UInt uiNumberOfDataPoolResources);
 
private:
    // The Data registry stores all ObjectIDs, which shall automatically be observing an entry in the datapool if the respective object is created
    class DataRegistryElement
    {
    public:
        DataRegistryElement(const ObjectHandle_t eObjectHandle) :
            m_eObjectHandle(eObjectHandle)
        {}
 
        DataRegistryElement() :
            m_eObjectHandle(NO_HANDLE)
        {}
 
        ObjectHandle_t  m_eObjectHandle;
        DataIDList      m_DataIDList;
 
        bool operator==(const DataRegistryElement& Value)
        {
            return Value.m_eObjectHandle == m_eObjectHandle;
        }
    };
 
    typedef eC_TListDoubleLinked<DataRegistryElement> DataRegistryList;
 
    // Convenience typedef for a list of DataPoolEntries 
    typedef eC_TListDoubleLinked<CDataPoolEntry*> DataPoolEntryList;
 
private:
    // Array of all known DataPoolEntries (Index within the Array = DataPoolResource_t of the respective DataPoolEntry)
    static eC_TArray<CDataPoolEntry*> ms_kDataPool;
 
    // List of data pool entries, which shall be processed (And thus their observers be notified) during the next call to "ProcessNotifications"
    static DataRegistryList ms_kDataRegistry;
    static DataPoolEntryList ms_kPendingNotifications;
 
    // Semaphores guarding the DataPool
    static eC_Semaphore ms_kDataPoolSema;
    static eC_Semaphore ms_kNotificationQueueSema;
};
 
#else
 
class CGUIDataPool
{
    friend class CGUIObject; 
    friend class CGUI; 
public:
    static void Set(const DataPoolResource_t eDataID, CGUIValue kValue, const eC_UInt uiX = 0, const eC_UInt uiY = 0) {}
    static void SetDataPoolEntry(const DataPoolResource_t eDataID, CDataPoolEntry* pkEntry) {}
    static void Get(const DataPoolResource_t eDataID, CGUIValue& kValue, const eC_UInt uiX = 0, const eC_UInt uiY = 0) {}
    static void Get(const DataPoolResource_t eDataID, CDataPoolEntry* pkEntry) {}
    static void GetUpdate(CDataPoolConnector* pkObserver) {}
    static void Register(const DataPoolResource_t eDataID, CGUIObject* pkObserver) {}
    static void Register(const DataPoolResource_t eDataID, CDataPoolConnector* pkObserver) {}
    static void Register(const DataPoolResource_t eDataID, DataPoolCallback pCallback) {}
    static void Unregister(const DataPoolResource_t eDataID, CGUIObject* pkObserver) {}
    static void Unregister(const DataPoolResource_t eDataID, CDataPoolConnector* pkObserver) {}
    static void Unregister(CGUIObject* pkObserver) {}
    static void Unregister(CDataPoolConnector* pkObserver) {}
    static void AutoRegister(const DataPoolResource_t eDataID, const ObjectHandle_t eObjectID) {}
    static void RemoveAutoRegister(const DataPoolResource_t eDataID, const ObjectHandle_t eObjectID) {}
    static eC_Bool ReadDataPoolFromFile(const eC_String& kPath) {}
    static void WriteDataPoolToFile(const eC_String& kPath) {}
    static const eC_TListDoubleLinked<ObjectHandle_t> GetAutoRegisteredObservers(const DataPoolResource_t eDataID) { static eC_TListDoubleLinked <ObjectHandle_t> kDummyList; return kDummyList; }
    static DataPoolResource_t RegisterDynamicDataPoolResource() { return DUMMY_DATAPOOLRESOURCE; }
    static void AddToNotificationQueue(CDataPoolEntry* pkEntry) {}
    static eC_UInt GetNOFDataPoolResources() { return 0; }
    static void Clear() {}
    static eC_UInt GetNumberOfPendingNotifications() { return 0; }
    static void DumpDataPool() {}
private:
 
    static void NotifyOfCreation(CGUIObject* pkObject) {}
    static void ProcessNotifications() {}
    static void Init() {}
    static void DeInit() {}
};
 
#endif
 
#endif