UT/UT_Options.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:
 *      Edward Lam
 *      Side Effects
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_Options.h (C++, Utility Library)
 *
 * COMMENTS:    This is a smaller, faster, more type-safe version of
 *              UT_OptionFile. The reason UT_OptionFile was not simply
 *              re-implemented is that when saving and loading UT_OptionFiles,
 *              no information about the type of each option is saved. This
 *              implementation writes out the type of each data item.
 *
 */

#ifndef _UT_OPTIONS_H_
#define _UT_OPTIONS_H_

#include "UT_API.h"
#include <iostream.h>
#include "UT_SmallObject.h"
#include "UT_PtrArraySorted.h"
#include "UT_SymbolTable.h"
#include "UT_DeepString.h"

class UT_WorkBuffer;
class UT_String;
class UT_Vector2;
class UT_Vector3;
class UT_Vector4;
class UT_Quaternion;
class UT_Matrix3;
class UT_Matrix4;
class UT_OptionEntry;
class UT_IntArray;
class UT_FloatArray;

// NOTE: The values of UT_OptionType are saved to disk, thus we should NOT 
//       reorder these options if we want to maintain compatibility with older
//       saved options.
typedef enum {
    UT_OPTION_INVALID = -1,
    UT_OPTION_INT = 0,
    UT_OPTION_BOOL = 1,
    UT_OPTION_FPREAL = 2,
    UT_OPTION_STRING = 3,
    UT_OPTION_VECTOR2 = 4,
    UT_OPTION_VECTOR3 = 5,
    UT_OPTION_VECTOR4 = 6,
    UT_OPTION_QUATERNION = 7,
    UT_OPTION_MATRIX3 = 8,
    UT_OPTION_MATRIX4 = 9,
    UT_OPTION_UV = 10,
    UT_OPTION_UVW = 11,
    UT_OPTION_STRINGRAW = 12,   // used by getPyOptionString
    UT_OPTION_NUM_TYPES = 13
} UT_OptionType;

class UT_API UT_Options
{
public:
    UT_Options();
    UT_Options(const UT_Options &src);
    virtual ~UT_Options();

    // This function does not call optionChanged.
    void clear();

    // only returns false if the file encounters an error. true is returned on
    // success or if the file didn't exist.
    bool load(const char *filename);
    bool save(const char *filename) const;
    bool load(const char *filename, UT_IStream &is);
    bool save(const char *filename, ostream &os) const;

    // Remove an option.
    void                 removeOption(const char *name);
    // Get the string representation of any of our options.
    void                 getOptionString(const char *name,
                                         UT_String &result) const;
    // Get the string representation of any option.
    static void          getOptionString(const UT_OptionEntry *option,
                                         UT_String &result);

    // Append the python dictionary representation of ALL our options to the
    // buffer
    bool                 appendPyDictionary(UT_WorkBuffer &result) const;
    // Get the python representation of any of our options
    bool                 getPyOptionString(const char *name,
                                        UT_String &result) const;
    // Get the python string represention of any option.
    static bool          getPyOptionString(const UT_OptionEntry *option,
                                        UT_String &result);

    // Functions for accessing the options by name.
    bool                 hasOption(const char *name) const;
    UT_OptionType        getOptionType(const char *name) const;
    const UT_OptionEntry*getOptionEntry(const char *name) const;

    // Functions for accessing all options sequentially.
    int                  getNumOptions() const;
    const char          *getOptionName(int optionnum) const;
    UT_OptionType        getOptionType(int optionnum) const;
    const UT_OptionEntry*getOptionEntry(int optionnum) const;

    // Functions for accessing specific option values.
    int                  getOptionI(const char *name) const;
    bool                 getOptionB(const char *name) const;
    float                getOptionF(const char *name) const;
    void                 getOptionS(const char *name, UT_String &value) const;
    const UT_Vector2     getOptionV2(const char *name) const;
    const UT_Vector3     getOptionV3(const char *name) const;
    const UT_Vector4     getOptionV4(const char *name) const;
    const UT_Quaternion  getOptionQ(const char *name) const;
    const UT_Matrix3     getOptionM3(const char *name) const;
    const UT_Matrix4     getOptionM4(const char *name) const;
    const UT_Vector2     getOptionUV(const char *name) const;
    const UT_Vector3     getOptionUVW(const char *name) const;

    // Functions for accessing option values.  These methods will perform some
    // minimal "casting".
    //  importOption(... bool &value)   - Tests integers and string options
    //  importOption(... fpreal &value) - Evaluates integer/bool options
    //  importOption(... UT_Vector2 &)  - Evaluates Vector2 or UV
    //  importOption(... UT_Vector3 &)  - Evaluates Vector3 or UVW
    //  
    bool         importOption(const char *name, int &value) const;
    bool         importOption(const char *name, bool &value) const;
    bool         importOption(const char *name, fpreal32 &value) const;
    bool         importOption(const char *name, fpreal64 &value) const;
    bool         importOption(const char *name, UT_String &value) const;
    bool         importOption(const char *name, UT_Vector2 &value) const;
    bool         importOption(const char *name, UT_Vector3 &value) const;
    bool         importOption(const char *name, UT_Vector4 &value) const;
    bool         importOption(const char *name, UT_Quaternion &value) const;
    bool         importOption(const char *name, UT_Matrix3 &value) const;
    bool         importOption(const char *name, UT_Matrix4 &value) const;

    // Generic import which handles arbitrary length int/float data
    bool         importOption(const char *name, UT_IntArray &value) const;
    bool         importOption(const char *name, UT_FloatArray &value) const;

    // All these functions cause optionChanged to be called.
    void                 setOptionI(const char *name, int value);
    void                 setOptionB(const char *name, bool value);
    void                 setOptionF(const char *name, float value);
    void                 setOptionS(const char *name, const char *value);
    // setOptionSRaw() is the same as setOptionS() instead of it being
    // additionally tagged as a "raw" string so that getPyOptionString() and
    // appendPyDictionary() won't add quotes around the value. To retrieve its
    // value, use getOptionS().
    void                 setOptionSRaw(const char *name, const char *value);
    void                 setOptionV2(const char *name,
                                     const UT_Vector2 &value);
    void                 setOptionV2(const char *name,
                                        fpreal x, fpreal y);
    void                 setOptionV3(const char *name,
                                     const UT_Vector3 &value);
    void                 setOptionV3(const char *name,
                                        fpreal x, fpreal y, fpreal z);
    void                 setOptionV4(const char *name,
                                     const UT_Vector4 &value);
    void                 setOptionV4(const char *name,
                                        fpreal x, fpreal y, fpreal z, fpreal w);
    void                 setOptionQ(const char *name,
                                    const UT_Quaternion &value);
    void                 setOptionM3(const char *name,
                                     const UT_Matrix3 &value);
    void                 setOptionM4(const char *name,
                                     const UT_Matrix4 &value);
    void                 setOptionUV(const char *name,
                                     const UT_Vector2 &value);
    void                 setOptionUVW(const char *name,
                                      const UT_Vector3 &value);

    const UT_Options    &operator=(const UT_Options &src);
    void                 merge(const UT_Options &src);
    int64                getMemoryUsage() const;

    static UT_OptionType getOptionTypeFromString(const char *optiontypestr);
    static const char   *getStringFromOptionType(UT_OptionType optiontype);

protected:
    void                 addError(const char *filename, int linecount,
                                  const char *error_str) const;
    void                 setOption(const char *name, UT_OptionEntry *value);
    virtual void         optionChanged(const char *name);

    static int           compareStrings(const char * const *str1,
                                        const char * const *str2);
    static const char   *getStringReference(const char *symbol);


    UT_PtrArraySorted<const char *>      myOptionNames;
    UT_PtrArray<UT_OptionEntry *>        myOptionValues;
    bool                                 mySendOptionChanges;
};

// The base class for data held by the UT_Options.
class UT_API UT_OptionEntry : public UT_SmallObject<UT_OptionEntry,
                                        UT_SMALLOBJECT_CLEANPAGES_DEFAULT,
                                        UT_SMALLOBJECT_PAGESIZE_DEFAULT,
                                        UT_SMALLOBJECT_THREADSAFE_ON>
{
public:
                                 UT_OptionEntry()
                                 { }
    virtual                     ~UT_OptionEntry()
                                 { }

    virtual UT_OptionType        getType() const = 0;
    virtual UT_OptionEntry      *clone() const = 0;
};

// A templatized version of the class above for holding specific data types.
template<class T, UT_OptionType ID, class outT = T>
class UT_API UT_OptionEntryImpl : public UT_OptionEntry
{
public:
                                 UT_OptionEntryImpl(const T &value)
                                     : myValue(value)
                                 { }
    virtual                     ~UT_OptionEntryImpl()
                                 { }

    const outT                  &getValue() const
                                 { return myValue; }
    virtual UT_OptionType        getType() const
                                 { return ID; }
    virtual UT_OptionEntry      *clone() const
                                 { return new UT_OptionEntryImpl(myValue); }

private:
    T                            myValue;
};

typedef UT_OptionEntryImpl<int, UT_OPTION_INT> UT_OptionInt;
typedef UT_OptionEntryImpl<bool, UT_OPTION_BOOL> UT_OptionBool;
typedef UT_OptionEntryImpl<float, UT_OPTION_FPREAL> UT_OptionFpreal;
typedef UT_OptionEntryImpl<UT_DeepString, UT_OPTION_STRING, UT_String> UT_OptionString;
typedef UT_OptionEntryImpl<UT_Vector2, UT_OPTION_VECTOR2> UT_OptionVector2;
typedef UT_OptionEntryImpl<UT_Vector3, UT_OPTION_VECTOR3> UT_OptionVector3;
typedef UT_OptionEntryImpl<UT_Vector4, UT_OPTION_VECTOR4> UT_OptionVector4;
typedef UT_OptionEntryImpl<UT_Quaternion, UT_OPTION_QUATERNION> UT_OptionQuaternion;
typedef UT_OptionEntryImpl<UT_Matrix3, UT_OPTION_MATRIX3> UT_OptionMatrix3;
typedef UT_OptionEntryImpl<UT_Matrix4, UT_OPTION_MATRIX4> UT_OptionMatrix4;
typedef UT_OptionEntryImpl<UT_Vector2, UT_OPTION_UV> UT_OptionUV;
typedef UT_OptionEntryImpl<UT_Vector3, UT_OPTION_UVW> UT_OptionUVW;

#endif

---