PI/PI_SettingList.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 * 
 * Produced by:
 *      Luke Moore
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        PI_SettingList.h
 *
 * COMMENTS:
 *      This class maintains a list of settings that control how a PI
 *      behaves.  Each setting is named.  The corresponding value may
 *      be a bool, int, float, UT_String, or UT_Vector[2/3/4].  The version
 *      of the overloaded getSetting()/appendSetting() method that you
 *      call determines the value type.
 *
 *      There may only be one type of setting value per name.  Appending
 *      a setting that has the same name as an existing setting is not
 *      allowed.
 *
 *      If no setting with the given name exists, getSetting() will return
 *      the supplied default setting.
 */

#ifndef __PI_SettingList_h__
#define __PI_SettingList_h__

#include "PI_API.h"
#include <iostream.h>
#include <UT/UT_PtrArray.h>
class UT_String;
class UT_Vector2;
class UT_Vector3;
class UT_Vector4;
class pi_Setting;

// This enumerated type in used internally, but must be declared in this
// header because some private methods take these values as arguments.  A
// number of helper classes also use this type.  It could go in the public
// part of the header, but it's too cumbersome to type
// PI_SettingList::PI_SETTING_FLOAT, so it's not in the header.
enum pi_SettingType
{
    PI_SETTING_FLOAT,
    PI_SETTING_STRING,
    PI_SETTING_VECTOR2,
    PI_SETTING_VECTOR3,
    PI_SETTING_VECTOR4
};

class PI_API PI_SettingList
{
public:
    explicit PI_SettingList();
    ~PI_SettingList();

    // These methods are called by a PI when it loads its settings.
    void                 getSetting(const char       *setting_name,
                                    int              &setting,
                                    int               default_value) const;
    void                 getSetting(const char       *setting_name,
                                    bool             &setting,
                                    bool              default_value) const;
    void                 getSetting(const char       *setting_name,
                                    float            &setting,
                                    float             default_value) const;
    void                 getSetting(const char       *setting_name,
                                    UT_String        &setting,
                                    const char       *default_value) const;
    void                 getSetting(const char       *setting_name,
                                    UT_Vector2       &setting,
                                    const UT_Vector2 &default_value) const;
    void                 getSetting(const char       *setting_name,
                                    UT_Vector3       &setting,
                                    const UT_Vector3 &default_value) const;
    void                 getSetting(const char       *setting_name,
                                    UT_Vector4       &setting,
                                    const UT_Vector4 &default_value) const;

    // These methods are called by a PI when it saves its settings.
    void                 appendSetting(const char       *setting_name,
                                       int               setting);
    void                 appendSetting(const char       *setting_name,
                                       bool              setting);
    void                 appendSetting(const char       *setting_name,
                                       float             setting);
    void                 appendSetting(const char       *setting_name,
                                       const char       *setting);
    void                 appendSetting(const char       *setting_name,
                                       const UT_Vector2 &setting);
    void                 appendSetting(const char       *setting_name,
                                       const UT_Vector3 &setting);
    void                 appendSetting(const char       *setting_name,
                                       const UT_Vector4 &setting);

    // This method is used to remove a specific setting from the list.
    void                 removeSetting(const char       *setting_name);

    // When a PI reads a setting it will be marked as read.  This method
    // will return a string containing all unread (ie. unrecognized) settings.
    bool                 findUnreadSettings(UT_String &unread_settings) const;

    // The resource manager uses the == operator to see if settings differ from
    // the default settings.  Note that this operator is not const and does not
    // take a reference to a const object because it may sort the two lists.
    int                  operator==(PI_SettingList &setting_list);
    void                 sort();

    PI_SettingList      &operator=(const PI_SettingList &setting_list);

    // Clear the list or check if it's empty.
    void                 clear();
    bool                 isEmpty() const { return !mySettings.entries(); }

    // These methods convert the settings to and from ascii data.
    void                 loadFromSettingString(const char *setting_string);
    void                 generateSettingString(ostream &os) const;
    void                 generateSettingString(UT_String &str) const;

    friend ostream      &operator<<(ostream &os,
                                    const PI_SettingList &setting_list)
                        {
                            setting_list.generateSettingString(os);
                            return os;
                        }

private:
    // Find a setting with a given name and type.
    pi_Setting          *findSetting(const char *setting_name,
                                     pi_SettingType setting_type) const;

    // The setting parser needs to be a friend so it can call findSetting
    // and append to mySettings.
    friend class pi_SettingParser;

    // Data:

    UT_PtrArray<pi_Setting *>    mySettings;
    bool                         mySortedFlag;
};

#endif

---