DDD_Viewer.h

Go to the documentation of this file.

/*! \file DDD_Viewer.h
  
  \par Copyright Information

  Copyright (c) 2012 The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBLITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef DDD_VIEWER_H_
#define DDD_VIEWER_H_

#include "DDD_DataDirector.h"
#include "DDD_EventPublisher.h"
#include <sstream>


class Fl_RSO_Window;

namespace disti
{

class ComponentBase;

/** \brief Interface for GUI that utilizes the DataDirectorViewer (ie- DataDirector Editor) */
class IDataDirectorViewerFrontend
{
public:
    /* This function is used to let the front end define how to ask
     * the user if they want to save their changes if at all
     * \return True if the user wants to save changes False otherwise
     */
    virtual bool AskUserToSaveChanges() = 0;

    /* This function is used to let the front end define how to ask
     * the user if they want to delete an object
     * \param message Question string presented to the user (ie- "Are you sure you want to do this?")
     * \return  True if the user wants to continue and False otherwise
     */
    virtual bool ConfirmDialog(const char *message) = 0;

    /*  This is to let the front dn know that the document has been
     * modified
     */
    virtual void SetDocumentModified() = 0;

    /* This function is used to direct the front end to clear its UI
     * and reset itself at a starting point
     */
    virtual void ClearUI() = 0;

    /* This function is used to add a component to the the main window
     * 
     */
    virtual void AddComponentToWindow(disti::ComponentBase * comp) = 0;
};

/** \brief Viewer class. Contains a RSO Window and DataDirector instance. */
class DDD_EXPORT DataDirectorViewer : public XMLConfigTarget, public DDD_EventPublisher
{
public:

    /** Window Settings data */
    typedef struct
    {
        enum DrawRateType
        {
            CONSTANT,    /**< Redraw at a constant frame rate */
            CONTINUOUS   /**< Redraw continuously (no waiting between each frame) */
        };
        
        std::string title;         /**< Window title */
        unsigned int width;        /**< Window width */
        unsigned int height;       /**< Window height */
        int initialPosX;           /**< Window initial position X */
        int initialPosY;           /**< Window initial position Y */
        DrawRateType drawRateType; /**< Window draw rate type */
        unsigned int drawRate;     /**< Window draw rate (in Hz); only used when drawRateType is set to CONSTANT */
    } Window_Settings;

    struct WindowRestoreParams
    {
        std::stringstream ourlayout;
        std::string ourlayoutName;
        int MwX;
        int MwY;
        int MwW;
        int MwH;
    };

    typedef disti::DynamicArray<Window_Settings, false> RSOWindowList;

    /** Constructor */
    DataDirectorViewer();

    /* set the front end interface
     * \param fe  Front end instance to use
     */
    void SetFrontEnd(IDataDirectorViewerFrontend* fe) { frontEnd = fe; }
    

    // Menu
    /* Start with fresh new file
     * \return  True if the operation was sucesful and False otherwise
     */
    virtual bool FileNew(); 

    /* Close the current file
     * \return  True if the operation was succesful and False otherwise
     */
    virtual bool FileClose();   

    /* Close the viewer
     * \return  True if the operation was succesful and False otherwise
     */
    virtual void FileExit();

    ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

    /* XMLConfigTarget override */
    virtual DDD_AssetBase* AddAsset(const std::string &instanceName, const std::string &className, const std::string &libName, const DDD_AttributeList& params );

    /* XMLConfigTarget override */
    virtual void AddConnection(DDD_Connection *connection);

    /* XMLConfigTarget override */
    WindowAttributes GetXMLWindowAttributes( unsigned int currentWindow );

    /* Notifications from GUI elements to sync with DataDirector core   
     * \param connection  Pointer to the connection that we want to remove
     */
    void RemoveConnectionFromDirector(DDD_Connection *connection);

    /*  Helper function to find a pointer to a particular asset by using its name
     * \param assetInstance  Name of the asset we are looking for
     */
    virtual DDD_AssetBase* FindAsset(const std::string &assetInstance);

    /* Used to obtain the list of assets within the current viewer
     * \return DDD_AssetList reference
     */
    virtual DDD_AssetList& GetAssetList();

    /* Used to obtain the list of connections within the current viewer
     * \return DDD_ConnectionList reference
     */
    virtual DDD_ConnectionList& GetConnectionList();
    
    /* Used to create an instance of an asset within this viewer
     * \param instance  Instance name for the new asset
     * \param className  Name of the class we want to instantiate
     * \param params  List of attributes used to intialize the new asset instance
     * \return  Pointer to the new DDD_AssetBase instance
     */
    DDD_AssetBase* CreateAsset(const std::string& instance, const std::string& className, const DDD_AttributeList& params);

    /* Specialized AddAsset method to handle the RSO template browser callback
     * \param instanceName  Name for the new asset
     * \param params  List of attributes used to initialize the new asset instance
     */
    void AddRSOAsset(const std::string& instanceName, const DDD_AttributeList& params);

    /* Used to create and instance of a connection within this viewer
     * 
     */
    DDD_Connection * NewConnection();

    /* Starts an asset within the viewer
     * \param asset Asset to be started.
     */
    void StartAsset(DDD_AssetBase *asset = NULL);

    /* Stops an asset within the viewer
     * \param asset Asset to be stopped.
     */
    void StopAsset(DDD_AssetBase *asset = NULL);

    /* Frees up the resources taken by the asset by the given name and 
     * publishes a corresponding event
     * \param assetName  Name of the asset that is to be deleted
     */
    bool RemoveAsset(const std::string& assetName);

    /*  Changes the name of the asset with the given name
     * \param assetNameOld  Current name of the asset that is to be renamed
     * \param assetNameNew  New name for the asset that is to be renamed
     * \return True if succesful and False otherwise
     */
    bool ChangeAssetInstanceName(const std::string& assetNameOld, const std::string& assetNameNew);

    /*  Moves the specified connection to an earlier point on the list
     * The connection order is used when eveluating data flowing through each connection.
     * As well as used to display in the proper order vie a GUI.
     * \param connection  Pointer to the DDD_Connection instance that is to be moved
     */
    bool MoveConnectionUp(DDD_Connection* connection);

    /*  Moves the specified connection to a later point on the list
     * \param connection  Pointer to the DDD_Connection instance that is to be moved
     */
    bool MoveConnectionDown(DDD_Connection* connection);

    /*  Moves the specified asset to an earlier point on the list
     * \param asset  Pointer to the DDD_AssetBase instance that is to be moved
     */
    bool MoveAssetUp(DDD_AssetBase* asset);

    /*  Moves the specified asset to a later point on the list
     * \param asset  Pointer to the DDD_Assetbase instance that is to be moved
     */
    bool MoveAssetDown(DDD_AssetBase* asset);

    /* If there are no assets or connections, it returns true
     * \return  True if there are no assets or connections False otherwise
     */
    bool EmptyConfiguration();

    /* what version of DataDirector DLL are we linked against?
     * \return  C-string containing the current version
     */
    static const char* Version();

    /* DDD_EventPublisher override. Notifies subscribers that an asset is being deleted.
     * \param asset pointer to asset to be deleted
     */
    virtual void Dispatch_AssetDeleted(DDD_AssetBase *asset);

    /* DDD_EventPublisher override. Notifies subscribers that an asset has been shifted
     * \param connection pointer to asset to be shifted
     * \param direction shift direction (enum is defined in DDD_AssetShifted_Subscriber)
     * \note Depending on the DataDirector's ability to perform the shift 
             (specifically, the asset's index within the Core's internal list), 
             this may or may not notify subscribers.
     */
    virtual void Dispatch_AssetShifted(DDD_AssetBase *asset, DDD_AssetShifted_Subscriber::AssetShiftDirection direction);

    /* DDD_EventPublisher override. Notifies subscribers that a connection is being deleted.
     * \param connection pointer to connection to be deleted
     */
    virtual void Dispatch_ConnectionDeleted(DDD_Connection *connection);

    /* DDD_EventPublisher override. Notifies subscribers that a connection has been shifted
     * \param connection pointer to connection to be shifted
     * \param direction shift direction (enum is defined in DDD_ConnectionShifted_Subscriber)
     * \note Depending on the DataDirector's ability to perform the shift 
             (specifically, the connection's index within the Core's internal list), 
             this may or may not notify subscribers.
     */
    virtual void Dispatch_ConnectionShifted(DDD_Connection *connection, DDD_ConnectionShifted_Subscriber::ConnectionShiftDirection direction);

    /* Load from an XML File
     * \param filename  Location of the file that needs to be loaded
     * \param errosString  Refference to an std::string to use in case of an error
     * \return True if succesful False otherwise
     */
    virtual bool LoadXML(const std::string &filename, std::string& errorString);

    /*  Start up the viewer
     *
     */
    virtual void Startup();

    /*  Stop the viewer
     *
     */
    virtual void Shutdown();

    ///////////////////////////////////////////////////////////////////////////////

    /* Asset Creator Callback (for non-plugin assets)
     * \param data  Pointer to the viewer instance
     * \param instance  Name for the new asset instance
     * \param className  Name of the class that needs to be instantiated
     * \param params  List of attributes to use when creating the asset instance
     * \param director Pointer to the data director instance
     * \return A pointer to the new DDD_AssetBase instance
     */
    static DDD_AssetBase* CreateAssetCb(void *data,const std::string& instance, const std::string& className, const DDD_AttributeList& params,DDD_DataDirector *director);  
    /* Returns the current window list
     * \return the current window list
     */
    RSOWindowList GetWindowList() { return _windowList; };

    /* Static callback for updating the viewer
     * \param data Void pointer to this that gets casted to call local callback UpdateViewer().
     */
    static void UpdateViewerCb(void *data);

    /* Local callback for updating the viewer. 
     */
    void UpdateViewer();

protected:
    /* Updates the Producer window title bar
     *
     */
    virtual void UpdateProducerWindowTitle();

    /* closes current document, reverts DataDirector to blank configuration
     *
     */
    void CloseDocument();

    /* Save to an XML file
     * \param filename  Name of the file to save to
     */
    bool SaveXML(const std::string &filename);  

    /* Refreshes the DataDirector core and damages the viewer window so that it gets redrawn.
     */
    void RefreshDirector();

    /* Sets the frame rate for given RSO Window
     * \param fps Desired frames per second.
     * \param windowIndex Index of RSO Window (only required if there are multiple RSO windows).
     */
    void SetFrameRate(int fps, unsigned int windowIndex=0);

protected:
    DDD_DataDirector *_director;   /**< DataDirector instance */

    bool _documentOpen;            /**< Is there a document (configuration) currently loaded? */
    bool _documentModified;        /**< Is the current document modified since last save?*/
    std::string _openFileName;     /**< Filename of current file (if it hasn't been created or none opened, it will be empty) */
    std::string _windowLabel;      /**< String that gets displayed on top window */
    bool _editorRunning;           /**< Flag for keeping the Startup/Shutdown methods from getting abused */
    RSOWindowList _windowList;     /**< Contains a list of all known windows */

    /** GUI instance for this viewer, if applicable. 
     * \warning  This may be NULL on some configurations. Be sure to check this before using it.
     */
    IDataDirectorViewerFrontend* frontEnd;

    Fl_RSO_Window *_rsoWindow;     /**< RSO Window instance */
};


#define FPS_TO_MICROSECONDS(x) (1000000.0/(x))   /**< Simple macro to convert from Hz to microsec */


}   // end namespace disti
#endif