class Core::Portable::Parameter

Overview

Parameter base class. More…

#include <coreparams.h>

class Parameter: public Core::Portable::TypedObject
{
public:
    // enums

    enum MsgType;

    // fields

    static const TypeID kTypeID =  'Para';

    // construction

    Parameter(const ParamInfo& info, bool ownsInfo = false);

    // methods

    virtual void* castTo(TypeID typeId);
    void setFormatter(const Formatter* formatter);
    const Formatter* getFormatter() const;
    ParamType getType() const;
    int getTag() const;
    CStringPtr getName() const;
    CStringPtr getTitle(bool shortVersion = false) const;
    bool isOwnInfo() const;
    bool isPublic() const;
    void setPublic(bool state = true);
    bool isStorable() const;
    void setStorable(bool state = true);
    bool isLinkable() const;
    void setLinkable(bool state = true);
    bool isMutable() const;
    bool isReadOnly() const;
    bool isUserFlag1() const;
    bool isUserFlag2() const;
    virtual Parameter* getOriginal();
    void setController(IParamObserver* controller);
    IParamObserver* getController() const;
    void setFeedbackNeeded(bool state);
    virtual void beginEdit();
    virtual void endEdit();
    virtual bool isEditing() const;
    virtual void performEdit();
    void addObserver(IParamObserver* observer);
    void removeObserver(IParamObserver* observer);
    void changed();
    void rangeChanged();
    virtual bool isEnabled() const;
    virtual void enable(bool state);
    virtual int getVisualState() const;
    virtual void setVisualState(int state);
    virtual bool isBipolar() const;
    virtual bool isNumeric() const = 0;
    virtual ParamValue getMin() const = 0;
    virtual ParamValue getMax() const = 0;
    virtual ParamValue getDefault() const = 0;
    virtual ParamValue getValue() const = 0;
    virtual int getPrecision() const = 0;
    virtual void setMin(ParamValue min) = 0;
    virtual void setMax(ParamValue max) = 0;
    virtual void setDefault(ParamValue value) = 0;
    virtual void setValue(ParamValue value, bool edit = false) = 0;
    virtual void resetValue(bool edit = false) = 0;
    virtual ParamValue getNormalized() const = 0;
    virtual void setNormalized(ParamValue v, bool edit = false) = 0;
    virtual void increment(int steps = 1) = 0;
    virtual void decrement(int steps = 1) = 0;
    int getIntMin() const;
    int getIntMax() const;
    int getIntDefault() const;
    void setIntMin(int min);
    void setIntMax(int max);
    void setIntDefault(int value);
    void setIntValue(int value, bool edit = false);
    int getIntValue() const;
    void setBoolValue(bool value, bool edit = false);
    bool getBoolValue() const;
    virtual void toString(char* string, int size) const = 0;
    virtual void fromString(CStringPtr string, bool edit = false) = 0;
    uint32 getHashCode() const;
    static INLINE uint32 hashName(CStringPtr name);
};

// direct descendants

class AliasParam;
class ColorParam;
class NumericParam;
class StringParam;

Inherited Members

public:
    // typedefs

    typedef int32 TypeID;

    // methods

    virtual void* castTo(TypeID typeId) = 0;
    virtual void* castTo(TypeID typeId);

Detailed Documentation

Parameter base class.

Parameter Protocol

A parameter object is the link between application logic and UI elements. It is owned by a single controller instance, which is associated to the parameter via setController(). The controller role is different from other observers. If user input causes the parameter to change its value (edit = true), the controller is notified to update the underlying data model (msg = kEdit).

If the underlying data model changes (edit = true/false), changing the parameter value forces the UI element to update its value representation (msg = kChanged). A single parameter can be associated with multiple UI elements simultaneously via addObserver(), and there is no additional coding required to keep all representations in sync.

Observers need to be removed from the parameter in a clean way. The latest possible point in time is when the parameter is about to be destroyed (msg = kDestroyed).

Interaction between parameters like linking, etc. needs to be implemented by the controller class.

To simplify scenarios where the controller wants to be notified of non-editing changes of its own parameters, setFeedbackNeeded() can be used instead of addObserver(). In this case the controller will receive two paramChanged() calls, kEdit and kChanged.

String Conversion

Parameters can customize their string representation by assigning a specialized formatter class via setFormatter(). This is the preferred method of customization instead of deriving your own parameter classes.

Normalization

For numeric parameters, the normalized value representation [0..1] can be customized via interpolator objects. This can be useful if e.g. the parameter uses a logarithmic scale instead of a linear scale.

Methods

CStringPtr getTitle(bool shortVersion = false) const

shortVersion: use short version if available

void rangeChanged()

explicit signal if min/max or list entries changed