UI_Value.h

Go to the documentation of this file.

#ifndef __UI_Value__
#define __UI_Value__

#include "UI_API.h"
#include "UI_Object.h"
#include <UT/UT_PtrProxy.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Types.h>
#include <iosfwd>
#include <deque>

/*
 *  A UI_Value is a utility class which maintains a single value of
 *  variable type and provides conversions between types.
 */

enum UI_ValueType {
    UI_VALUE_FLOAT,
    UI_VALUE_INTEGER,
    UI_VALUE_STRING,
    UI_VALUE_FLOAT_ARRAY,
    UI_VALUE_INT_ARRAY,
    UI_VALUE_STRING_ARRAY,
    UI_VALUE_POINTER
};
UI_API size_t format(char *buffer, size_t buffer_size, const UI_ValueType &v);

enum UI_Reason {
    UI_NO_REASON,           // event was likely explicitly generated
    UI_VALUE_CHANGED,       // mouse up
    UI_VALUE_ACTIVE,        // mouse drag
    UI_VALUE_START,         // mouse down
    UI_VALUE_NEW,           // dependent added to UI_Value
    UI_VALUE_RANGE_CHANGED, // UI_ScrollValue range changed
    UI_VALUE_PICKED,        // quick mouse down and release without drag
    UI_VALUE_LOCATED,       // mouse hover (only if wantsLocates() is true)
    UI_VALUE_ITEMS_CHANGED  // only generated by UI_StringList (and subclasses)
};
UI_API size_t format(char *buffer, size_t buffer_size, const UI_Reason &v);

#define UI_STEP_BIG     4

enum UI_StepType {
    UI_STEP_INCREMENT = 1,
    UI_STEP_DECREMENT = 2,
    UI_STEP_INCREMENT_BIG = (UI_STEP_INCREMENT | UI_STEP_BIG),
    UI_STEP_DECREMENT_BIG = (UI_STEP_DECREMENT | UI_STEP_BIG)
};
UI_API size_t format(char *buffer, size_t buffer_size, const UI_StepType &v);

class UI_Event;
class UT_Color;
class UT_String;
class UT_StringArray;
class UT_StringHolder;
class UT_StringRef;
class UT_IStream;
class ui_Client;

//====================================================================

class UI_API UI_Value : public UI_Object
{
public:
    UI_Value();
    explicit UI_Value(int32 i);
    explicit UI_Value(int64 i);
    explicit UI_Value(fpreal32 f);
    explicit UI_Value(fpreal64 f);
    explicit UI_Value(fpreal32 fp[], exint n);
    explicit UI_Value(fpreal64 dp[], exint n);
    explicit UI_Value(int32 ip[], exint n);
    explicit UI_Value(int64 ip[], exint n);
    explicit UI_Value(const UT_StringArray &ssp);
    explicit UI_Value(const char *s);
    explicit UI_Value(const UI_Value &v);

            ~UI_Value() override;

    virtual void setValue(int32 i);
    virtual void setValue(int64 i);
    virtual void setValue(fpreal64 f);
    virtual void setValue(fpreal64 f, exint n);
    virtual void setValue(int32 i, exint n);
    virtual void setValue(int64 i, exint n);
    virtual void setValue(const fpreal32 fp[], exint n);
    virtual void setValue(const fpreal64 dp[], exint n);
    virtual void setValue(const int32 ip[], exint n);
    virtual void setValue(const int64 ip[], exint n);
    virtual void setValue(const UT_StringArray &ssp);
    virtual void setValue(const char *s);
    virtual void setValue(const UI_Value &v);
            void setValue(const UT_Color &c);
            void setPointerValue(void *p);
            void stringPrintf(const char *fmt, ...);

    virtual void changed(UI_Object *by,
                         UI_Reason reason = UI_VALUE_CHANGED,
                         UI_DeviceEvent *state = 0);
    //  This method is similar to "changed" but it triggers the callback events
    //  immediately (bypassing the event queue). It also only notifies the
    //  objects that have added interests in this value. Not the immediate
    //  dependents. **This should only be used in special circumstances.**
    void triggerImmediate(UI_Object *by,
                          UI_Reason reason = UI_VALUE_CHANGED,
                          UI_DeviceEvent *state = 0);
    //  This method is similar to "triggerImmediate" but it notifies the
    //  immediate dependents rather than the objects that have added interests
    //  in this value.  **This should only be used in special circumstances.**
    void triggerDependents(UI_Object *by,
                           UI_Reason reason = UI_VALUE_CHANGED,
                           UI_DeviceEvent *state = 0);

    virtual void enable(bool state); // Sends enable event to dependents
    virtual void visible(bool state); // Sends visible event to dependents
    virtual void override(bool state, int);// Sends override event to dependents
    virtual void open(bool state);      // Sends open/close event to dependents
    virtual void refresh();             // Sends redraw in place events

    // This ugly hack attempts to determine the open state of UI_Feel clients
    // which are open. It returns true only if *any* of them are open.
    bool         areAnyFeelClientsOpen() const;

    void         handleEvent(UI_Event *event) override;
    void         deleteReferences(UI_Object *to_whom) override;

    virtual void setSteps(fpreal mysmall, fpreal large);
    virtual void setRange(fpreal min, fpreal max);
    virtual void getRange(fpreal *min, fpreal *max) const;

    virtual void rangeCheck();
    virtual int  step(UI_StepType how);

    int         save(std::ostream &os) const;
    bool        load(UT_IStream &is);

    void setFormat(const char *fmt) { myFormat = fmt; }
    const char *getFormat() const { return myFormat; }

    void getValue(int32 *ip) const;
    void getValue(int64 *ip) const;
    void getValue(fpreal32 *fp) const;
    void getValue(fpreal64 *fp) const;
    void getValue(fpreal32 *fp, exint n) const;
    void getValue(fpreal64 *dp, exint n) const;
    void getValue(int32 *ip, exint n) const;
    void getValue(int64 *ip, exint n) const;
    void getValue(char *sp, exint bufsize) const;
    void getValue(char *sp, exint bufsize, const char *format) const;
    void getValue(UT_String &s) const;
    void getValue(UT_StringHolder &s) const;
    void getValue(UT_StringArray &ssp, exint n) const;
    void getValue(UI_Value &v) const;
    void getValue(UT_Color &color) const;
    void getValue(void **pp) const;

    /// Same as getValue(UT_StringHolder &s) except it uses full precision for
    /// floating point to string conversions.
    void getValuePrecise(UT_StringHolder &s) const;

    void getArrayValue(fpreal *d, exint index) const;
    void getArrayValue(int32 *d, exint index) const;
    void getArrayValue(int64 *d, exint index) const;
    exint getArrayLength() const;

    SYS_FORCE_INLINE UI_ValueType getType() const { return myType; }
    virtual int  isVector() const { return 0; }

    void addInterest(UI_Object *client, UI_EventMethod method,
                     bool check_dup = false);
    void addPriorityInterest(UI_Object *client, UI_EventMethod method,
                             bool check_dup = false);
    bool hasInterest(UI_Object *in, UI_EventMethod method);
    bool hasInterest(UI_Object *obj);
    void removeInterest(UI_Object *in, UI_EventMethod method);
    void removeInterest(UI_Object *client);
    void removeAllInterests();

    //  Note: setString sets the char * value whereas setValue(char *) does
    //    a strdup. (ie UI_Value will own the string you set with setString)
    const char  *getString() const;     // Short cuts for string manipulation.
    void         setString(char *sp);
    char        *stealString();         // Take the string away from the value.
    
    // Expand environment variables and, on OSX and Linux, the ~ character.
    void         expandEnvironment();

    operator const char *() const;
    operator bool() const;
    operator int32() const;
    operator int64() const;
    operator fpreal32() const;
    operator fpreal64() const;
    operator void *() const;

    void operator=(int32 i)             { setValue(i); }
    void operator=(int64 i)             { setValue(i); }
    void operator=(fpreal32 f)          { setValue(f); }
    void operator=(fpreal64 f)          { setValue(f); }
    void operator=(const char *s)       { setValue(s); }
    void operator=(const UI_Value &v)   { setValue(v); }
    void operator=(const UT_Color &c)   { setValue(c); }

    bool operator==(const UI_Value &v) const;
    bool operator==(const fpreal32 fp[]) const;
    bool operator==(const fpreal64 fp[]) const;
    bool operator==(const int32 ip[]) const;
    bool operator==(const int64 ip[]) const;
    bool operator==(const UT_StringArray &ssp) const;
    bool operator==(fpreal64 f) const;
    bool operator==(fpreal32 f) const;
    bool operator==(int32 i) const;
    bool operator==(int64 i) const;
    bool operator==(const char *s) const;

    const char          *className() const override { return "UI_Value"; }

    // Return the number of interests expressed in this value
    int                  getNumInterested() const;
    UI_Object           *getInterest(int index) const; 

    // Utility method for debugging
    void                 dumpInterests(std::ostream &os,
                                       const char *prefix = 0) const;

    // Set to true to track 
    enum TraceLevel
    {
        TL_NONE,
        TL_EVENT,
        TL_VALUE
    };
    

    bool                 isTraced() const { return myTraceLevel != TL_NONE; }
    virtual void         setTraceLevel(TraceLevel tl) { myTraceLevel = tl; }
    TraceLevel           getTraceLevel() const { return myTraceLevel; }
    
protected:

    // Clamps value to given range.
    // NB: Only valid for float, int, {int,float} arrays
    void                 clampValue(fpreal min_value, fpreal max_value);

    void                 showTrace();
    
private:
    void                 zap();

    void                 addMyInterest(UI_Object *client,
                                       UI_EventMethod method,
                                       bool check_dup,
                                       bool priority);
    void                 sendEventToInterests(UI_Object *by, UI_Event &event,
                                              bool immediate);

    friend std::ostream &operator<<(std::ostream &os, const UI_Value &v)
                        {
                            v.save(os);
                            return os;
                        }
private:
    union ValueType
    {
        exint    i;
        fpreal   d;
        fpreal  *a;
        exint   *j;
        char    *s;
        char    **ss;
        void    *p;
    };

    class ui_Client
    {
    public:
                                ui_Client(UI_Object *who, UI_EventMethod func)
                                    : myClientId(who->getProxyId())
                                    , myMethod(func)
                                {
                                }

        // Not copyable
                                ui_Client(const ui_Client& copy) = delete;
        ui_Client&              operator=(const ui_Client& copy) = delete;
        // But movable
                                ui_Client(ui_Client&& src) = default;
        ui_Client&              operator=(ui_Client&& src) = default;

        bool                    isEqual(int id) { return myClientId == id; }
        int                     getClientId()   { return myClientId; }
        UI_Object *             getClient()     { return myClientId; }
        UI_EventMethod          getMethod()     { return myMethod; }

    private:
        UT_RefProxy<UI_Object>  myClientId;
        UI_EventMethod          myMethod;
    };

    using ui_ClientList = std::deque<ui_Client>;
    using ui_ClientListPtr = UT_UniquePtr<ui_ClientList>;
    using ui_ClientListIter = ui_ClientList::iterator;

    SYS_FORCE_INLINE
    ui_ClientListIter           ibegin()    { return myInterests->begin(); }
    SYS_FORCE_INLINE
    ui_ClientListIter           iend()      { return myInterests->end(); }
    
    ValueType                   myValue;
    UI_ValueType                myType:4;
    TraceLevel                  myTraceLevel:2;
    ui_ClientListPtr            myInterests;
    const char*                 myFormat;
};

UI_API size_t format(char *buffer, size_t buffer_size, const UI_Value &v);

inline int
UI_Value::getNumInterested() const
{
    return myInterests ? int(myInterests->size()) : 0;
}

inline UI_Object *
UI_Value::getInterest(int i) const
{
    if (!myInterests || i < 0 || i >= myInterests->size())
        return nullptr;
    
    return (*myInterests)[i].getClient();
}

inline void
UI_Value::clampValue(fpreal min_value, fpreal max_value)
{
    if (min_value > max_value)
        return;

    switch (myType)
    {
        case UI_VALUE_FLOAT:
            if (myValue.d < min_value)
                myValue.d = min_value;
            else if (myValue.d > max_value)
                myValue.d = max_value;
            break;

        case UI_VALUE_INTEGER:
            if (myValue.i < min_value)
                myValue.i = (int)min_value;
            else if (myValue.i > max_value)
                myValue.i = (int)max_value;
            break;

        case UI_VALUE_FLOAT_ARRAY:
            for (exint i = 1, n = myValue.a[0];  i < n; ++i)
            {
                if (myValue.a[n] < min_value)
                    myValue.a[n] = min_value;
                else if (myValue.a[n] > max_value)
                    myValue.a[n] = max_value;
            }
            break;

        case UI_VALUE_INT_ARRAY:
            for (exint i = 1, n = myValue.a[0];  i < n; ++i)
            {
                if (myValue.j[n] < (int)min_value)
                    myValue.j[n] = (int)min_value;
                else if (myValue.j[n] > (int)max_value)
                    myValue.j[n] = (int)max_value;
            }
            break;

        default: break;
    }
}

#endif