FxProfile.h

Go to the documentation of this file.

//
// (C) Copyright 2005-2023 by Graebert GmbH.
//
// Permission to use, copy, modify, and distribute this software in
// object code form for any purpose and without fee is hereby granted, 
// provided that the above copyright notice appears in all copies and 
// that both that copyright notice and the limited warranty and
// restricted rights notice below appear in all supporting 
// documentation.
//
// GRAEBERT PROVIDES THIS PROGRAM "AS IS" AND WITH ALL FAULTS. 
// GRAEBERT SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF
// MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE.  GRAEBERT GMBH 
// DOES NOT WARRANT THAT THE OPERATION OF THE PROGRAM WILL BE
// UNINTERRUPTED OR ERROR FREE.
 
#pragma once
 
#include "DDKERNEL.h"
 
#include "FxString.h"
 
#include "FxPragmaPush.h"
 
class CFxProfileStorage;
class CFxSettings;
class CFxSystemFiles;
class CFxRecentFiles;
class CFxPreferences;
 
class DDKERNEL_API CFxProfile
{
public:
    virtual ~CFxProfile() {};
 
    virtual CFxString GetName() const = 0;
 
    virtual CFxString GetDescription() const = 0;
 
    /*
    Description:
        CFxSettings class provides low-level access to the profile
        internal data
    */
    virtual CFxSettings* GetSettings() = 0;
 
    /*
    Description:
        CFxProfileStorage class provides low-level access to the profile
        internal data
    */
    virtual CFxProfileStorage* GetStorage( bool bCreateIfNotExists ) = 0;
 
    /*
    Description:
        CFxSystemFiles class provides access to the system paths that are
        stored in the profile
    */
    virtual CFxSystemFiles* GetSystemFiles() = 0;
 
    /*
    Description:
        CFxRecentFiles class provides access to the recent files that are
        stored in the profile (is used from fixed profile only)
    */
    virtual CFxRecentFiles* GetRecentFiles() = 0;
 
    /*
    Description: 
        Resolves command alias
    */
    virtual CFxString ResolveAlias( const CFxString& strAlias ) const = 0;
 
    /*
    Description: 
        Load command aliases
    */
    virtual void LoadAliases() = 0;
 
    /*
    Description: 
    CFxPreferences class provides access to the different preferences 
    that are stored in the profile
    */
    virtual CFxPreferences* GetPreferences() = 0;
 
    /*
    Description: 
    Flushes the changes to disk.
    */
    virtual void Flush() = 0;
};
 
class DDKERNEL_API CFxProfileManagerReactor
{
public:
    virtual ~CFxProfileManagerReactor() {};
 
    /*
    Description:
        Notification sent out that the current profile will be changed. newProfile is the new profile that will be set current.
 
    Arguments:
        \param newProfile Profile that will be set current
    */
    virtual void currentProfileWillChange( const CFxString& newProfile ) {};
 
    /*
    Description:
        Notification sent out that the current profile has changed. newProfile is now the current profile.
 
    Arguments:
        \param newProfile Profile that is now current 
    */
    virtual void currentProfileChanged( const CFxString& newProfile ) {};
 
    /*
    Description:
        Notification sent out that the current profile will be reset.
 
    Arguments:
        \param currentProfile Name of the current profile
    */
    virtual void currentProfileWillBeReset( const CFxString& currentProfile ) {};
 
    /*
    Description:
 
    Arguments:
        \param
    */
    virtual void currentProfileReset( const CFxString& currentProfile ) {};
 
    /*
    Description:
        This method is called when the current profile is about to be saved. It is called before saving
        the profile. Applications that use profile storage file to store the settings should override
        this method (or profileWillBeSaved()) and store their latest settings.
 
    Arguments:
        \param currentProfile Input name of the current profile that will be saved
    */
    virtual void currentProfileWillBeSaved( const CFxString& currentProfile, CFxSettings* pCurrentProfileSettings ) {};
 
    /*
    Description:
    */
    virtual void currentProfileWillBeLoaded( const CFxString& currentProfile, CFxSettings* pCurrentProfileSettings ) {};
 
    /*
    Description:
        This method is called when the current profile was saved. It is called after saving the profile.
 
    Arguments:
        \param currentProfile Input name of the current profile that was saved
    */
    virtual void currentProfileSaved( const CFxString& currentProfile ) {};
 
    /*
    Description:
    */
    virtual void currentProfileLoaded( const CFxString& currentProfile ) {};
 
    /*
    Description:
        Notification sent out that a profile will be reset.
 
    Arguments:
        \param profileName Name of the profile to be reset
    */
    virtual void profileWillReset( const CFxString& profileName ) {};
 
    /*
    Description:
        Notification sent out when a profile has been reset.
 
    Arguments:
        \param profileName Name of the profile that was reset
    */
    virtual void profileReset( const CFxString& profileName ) {};
 
    /*
    Description:
        This method is called when a profile is about to be saved. It is called before saving
        the profile. Applications that use profile storage file to store the settings should
        override this method (or currentProfileWillBeSaved()) and store their latest settings.
 
    Arguments:
        \param profileName  Input name of the profile that will be saved; if the profile is
                            a fixed profile, this will contain an empty string 
    */
    virtual void profileWillBeSaved( const CFxString& profileName, CFxSettings* pProfileSettings ) {};
 
    /*
    Description:
    */
    virtual void profileWillBeLoaded( const CFxString& profileName, CFxSettings* pProfileSettings ) {};
 
    /*
    Description:
        This method is called when a profile was saved. It is called after saving the profile.
 
    Arguments:
        \param profileName  Input name of the profile that was saved; if the profile is
                            a fixed profile, this will contain an empty string
    */
    virtual void profileSaved( const CFxString& profileName ) {};
 
    /*
    Description:
    */
    virtual void profileLoaded( const CFxString& profileName ) {};
};
 
typedef OdArray<CFxString> CFxProfileNameArray;
 
class DDKERNEL_API CFxProfileManager
{
public:
    /*
    Description:
        The registry path for the specified profile, strProfileName, is returned via strRegProfileKey if the profile
        is found in the registry.
 
    Arguments:
        \param strRegProfileKey Output registry path 
        \param strProfileName Input profile name 
 
    */
    virtual void ProfileRegistryKey( CFxString& strRegProfileKey, const CFxString& strProfileName ) = 0;
 
    /*
    Description:
        This function returns the profile names list via the AcApProfileNameArray argument, nameList. When passed in,
        this array should be empty. It is the caller’s responsibility to delete the entries of the array.
 
        Returns the number of profiles in the registry.
 
    Arguments:
        \param nameList Passed in AcApProfileNameArray
    */
    virtual int ProfileListNames( CFxProfileNameArray& nameList ) = 0;
 
    /*
    Description:
        The ARGON settings in the registry for the specified profile, strProfileName, are written out to the .arg file,
        exportFileName, in REGEDIT4 format.
 
        The function could return with the following return codes:
            eProfileDoesNotExist    The specified profile name is not found in the registry.
            eNoFileName             No file name specified.
            eInvalidFileExtension   The file should have an .arg extension.
            eCantOpenFile           File permission error.
            eRegistryAccessError    Could not access/update registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param strProfileName Input profile name 
        \param exportFileName Output .arg file name
    */
    virtual int ProfileExport( const CFxString& strProfileName, const CFxString& exportFileName ) = 0;
 
    /*
    Description:
        A new profile is created with the specified name, strProfileName, and description, profileDescription. If the
        profile already exists, it will be overwritten (if it is not the current profile). The ARGON settings from the
        specified .arg file, importFileName, are read into the registry for the new profile. bImportPathInfo
        determines whether the path information in the file should be read in or ignored.
 
        The function could return with the following return codes:
            eInvalidProfileName     Invalid characters in the Profile name.
            eNoFileName             No file name specified.
            eInvalidFileExtension   The file should have an .arg extension.
            eProfileIsInUse         Cannot import into the current profile.
            eCantOpenFile           File permission error.
            eRegistryCreateError    Could not update registry.
            eRegistryAccessError    Could not access registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param strProfileName       Input profile name 
        \param importFileName       Input .arg file name 
        \param profileDescription   Input profile description 
        \param bImportPathInfo      Input Boolean indicating whether path information should be read in or ignored 
 
    */
    virtual int ProfileImport( const CFxString& strProfileName, const CFxString& importFileName, const CFxString& profileDescription, bool bImportPathInfo ) = 0;
 
    /*
    Description:
        Deletes the profile specified in strProfileName from the registry.
 
        The function could return with the following return codes:
            eProfileDoesNotExist    The specified profile name is not found in the registry.
            eProfileIsInUse         Cannot delete the current profile.
            eRegistryAccessError    Could not access/update registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param strProfileName Input profile name
    */
    virtual int ProfileDelete( const CFxString& strProfileName ) = 0;
 
    /*
    Description:
        The settings under the profile strProfileName are deleted and the profile reverts to default settings.
 
        The function could return with the following return codes:
            eProfileDoesNotExist    The specified profile name is not found in the registry.
            eRegistryAccessError    Could not access/update registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param strProfileName Input profile name
    */
    virtual int ProfileReset( const CFxString& strProfileName ) = 0;
 
    /*
    Description:
        The profile specified, strprofileName, is made the current profile for the ARGON session.
 
        The function could return with the following return codes:
                eProfileDoesNotExist    The specified profile name is not found in the registry.
                eRegistryAccessError    Could not access/update registry.
                eOk                     Operation completed successfully.
 
    Arguments:
        \param strProfileName Input profile name
    */
    virtual int ProfileSetCurrent( const CFxString& strProfileName ) = 0;
 
    virtual CFxProfile* ProfileGetCurrent() = 0;
 
    virtual CFxProfile* ProfileGetFixed() = 0;
 
    virtual CFxProfile* ProfileGet( const CFxString& strProfileName ) = 0;
 
    /*
    Description:
        A new profile is created with the new name and description. If the profile name already exists, it will be
        overwritten (if it's not the current profile). The ARGON settings from the old profile are copied into the
        new profile.
 
        The function could return with the following return codes:
            eProfileDoesNotExist    The old profile name is not found in the registry.
            eInvalidProfileName     Invalid characters in the new profile name.
            eProfileIsInUse         Cannot copy into current profile.
            eRegistryAccessError    Could not access registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param newProfileName Input new profile name
        \param oldProfileName Input profile name to be copied
        \param newProfileDesc Input new profile description
    */
    virtual int ProfileCopy( const CFxString& newProfileName, const CFxString& oldProfileName, const CFxString& newProfileDesc ) = 0;
 
    /*
    Description:
        Renames an existing profile, oldProfileName, to a new name, newProfileName, with a new description, newProfileDesc.
 
        The function could return with the following return codes:
            eProfileDoesNotExist    The specified profile name is not found in the registry.
            eInvalidProfileName     Invalid characters in the new profile name.
            eProfileIsInUse         Cannot rename a profile to the name of the current profile.
            eRegistryAccessError    Could not access/update registry.
            eOk                     Operation completed successfully.
 
    Arguments:
        \param newProfileName Input new profile name
        \param oldProfileName Input old profile name
        \param newProfileDesc Input new profile description
    */
    virtual int ProfileRename( const CFxString& newProfileName, const CFxString& oldProfileName, const CFxString& newProfileDesc ) = 0;
 
    /*
    Description:
        This function force profile saving.
 
        The function could return with the following return codes:
        eProfileDoesNotExist    The specified profile name is not found in the registry.
        eOk                     Operation completed successfully.
    */
    virtual int ProfileSave( const CFxString& profileName ) = 0;
 
    /*
    Description:
        This function adds a reactor to receive profile change event notifications.
    */
    virtual void addReactor( CFxProfileManagerReactor* ) = 0;
 
    /*
    Description:
        This function removes a reactor.
    */
    virtual void removeReactor( CFxProfileManagerReactor* ) = 0;
};
 
#define currProfile() GetFxSystemServices()->GetFxProfileManager()->ProfileGetCurrent()
 
class QDomNode;
 
class DDKERNEL_API CFxProfileStorage
{
public:
    virtual ~CFxProfileStorage() {};
 
    /*
    Description:
        Creates a node in the XML file at the specified path. If the node already exists, it gets the existing node.
 
    Arguments:
        \param pszNodePath  Input XML node path specifying the node to create 
        \param pNode        Output reference to receive the IUnknown interface of created IXMLDOMNode interface 
    */
    virtual int CreateNode( const CFxString& pszNodePath, QDomNode*& pNode ) = 0;
 
    /*
    Description:
        Gets the node in the XML file at the specified path.
 
    Arguments:
        \param pszNodePath  Input XML node path specifying the node to get;
                            for example, ToolPalette\ToolPaletteSets\ToolPaletteSet 
        \param pNode        Output reference to receive the IUnknown interface of IXMLDOMNode pointer
                            for the specified node path; set to NULL if the node is not found 
    */
    virtual int GetNode( const CFxString& pszNodePath, QDomNode*& pNode ) = 0;
 
    /*
    Description:
        Replaces the node in the XML file at the specified path with the specified node. The replaced node is released.
 
    Arguments:
        \param pszNodePath  Input XML node path specifying the node to replace;
                            for example, ToolPalette\ToolPaletteSets\ToolPaletteSet
        \param pNode        Input IUnknown interface of IXMLDOMNode pointer to replace the existing node
                            at the specified node path
    */
    virtual int ReplaceNode( const CFxString& pszNodePath, QDomNode* pNode ) = 0;
 
    /*
    Description:
        Deletes the node in the XML file at the specified path.
 
    Arguments:
        \param pszNodePath  Input XML node path specifying the node to delete;
                            for example, ToolPalette\ToolPaletteSets\ToolPaletteSet
    */
    virtual int DeleteNode( const CFxString& pszNodePath ) = 0;
 
    /*
    Description:
        Gets the physical storage file in which the profile is stored.
 
    Arguments:
        \param pszFile  Input pointer to character buffer to receive the profile storage file with path;
                        the buffer length should be at least MAX_PATH length 
    */
    virtual int GetStorageFile( CFxString& fileName ) = 0;
 
    /*
    Description:
        Saves the profile storage XML file. The profile storage file is saved automatically when required.
        For example, it will be saved when the profile is switched or renamed or when the session ends.
        Use this function to force a save of the file immediately if necessary.
    */
    virtual int Save( void ) = 0;
};
 
#include "FxPragmaPop.h"