annotate base/PropertyContainer.h @ 199:1d789d688f59

* When adding a layer, make it the selected layer on that pane
* More OSC support, including transforms

/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */

/*
    Sonic Visualiser
    An audio file viewer and annotation editor.
    Centre for Digital Music, Queen Mary, University of London.
    This file copyright 2006 Chris Cannam.
    
    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation; either version 2 of the
    License, or (at your option) any later version.  See the file
    COPYING included with this distribution for more information.
*/

#ifndef _PROPERTY_CONTAINER_H_
#define _PROPERTY_CONTAINER_H_

#include "Command.h"

#include <QString>
#include <QObject>
#include <vector>

class PlayParameters;
class RangeMapper;

class PropertyContainer : public QObject
{
    Q_OBJECT

public:
    virtual ~PropertyContainer() { }

    typedef QString PropertyName;
    typedef std::vector<PropertyName> PropertyList;
    
    enum PropertyType {
	ToggleProperty, // on or off
	RangeProperty, // range of integers
	ValueProperty, // range of integers given string labels
	ColourProperty, // colours, get/set as qRgb
        UnitsProperty, // unit from UnitDatabase, get/set unit id
	InvalidProperty, // property not found!
    };

    /**
     * Get a list of the names of all the supported properties on this
     * container.  These should be fixed (i.e. not internationalized).
     */
    virtual PropertyList getProperties() const;

    /**
     * Return the human-readable (and i18n'ised) name of a property.
     */
    virtual QString getPropertyLabel(const PropertyName &) const = 0;

    /**
     * Return the type of the given property, or InvalidProperty if
     * the property is not supported on this container.
     */
    virtual PropertyType getPropertyType(const PropertyName &) const;

    /**
     * If this property has something in common with other properties
     * on this container, return a name that can be used to group them
     * (in order to save screen space, for example).  e.g. "Window
     * Type" and "Window Size" might both have a group name of "Window".
     * If this property is not groupable, return the empty string.
     */
    virtual QString getPropertyGroupName(const PropertyName &) const;

    /**
     * Return the minimum and maximum values for the given property
     * and its current value in this container.  Min and/or max may be
     * passed as NULL if their values are not required.
     */
    virtual int getPropertyRangeAndValue(const PropertyName &,
					 int *min, int *max) const;

    /**
     * If the given property is a ValueProperty, return the display
     * label to be used for the given value for that property.
     */
    virtual QString getPropertyValueLabel(const PropertyName &,
					  int value) const;

    /**
     * If the given property is a RangeProperty, return a new
     * RangeMapper object mapping its integer range onto an underlying
     * floating point value range for human-intelligible display, if
     * appropriate.  The RangeMapper should be allocated with new, and
     * the caller takes responsibility for deleting it.  Return NULL
     * (as in the default implementation) if there is no such mapping.
     */
    virtual RangeMapper *getNewPropertyRangeMapper(const PropertyName &) const;

    virtual QString getPropertyContainerName() const = 0;
    virtual QString getPropertyContainerIconName() const = 0;

    virtual PlayParameters *getPlayParameters() { return 0; }

signals:
    void propertyChanged(PropertyContainer::PropertyName);
    
public slots:
    /**
     * Set a property.  This is used for all property types.  For
     * boolean properties, zero is false and non-zero true; for
     * colours, the integer value should be treated as a qRgb.
     */
    virtual void setProperty(const PropertyName &, int value);

    /**
     * Set a property using a command, supporting undo and redo.
     * The default implementation should work for most subclasses.
     */
    virtual void setPropertyWithCommand(const PropertyName &, int value);

    /**
     * Set a property using a fuzzy match.  Compare nameString with
     * the property labels and underlying names, and if it matches one
     * (with preference given to labels), try to convert valueString
     * appropriately and set it.  The valueString should contain a
     * value label for value properties, a mapped value for range
     * properties, "on" or "off" for toggle properties, a colour or
     * unit name, or the underlying integer value for the property.
     *
     * Note that as property and value labels may be translatable, the
     * results of this function may vary by locale.  It is intended
     * for handling user-originated strings, _not_ persistent storage.
     *
     * The default implementation should work for most subclasses.
     */
    virtual void setProperty(QString nameString, QString valueString);

    /**
     * As above, but using a command.
     */
    virtual void setPropertyWithCommand(QString nameString, QString valueString);

protected:

    class SetPropertyCommand : public Command
    {
    public:
	SetPropertyCommand(PropertyContainer *pc, const PropertyName &pn, int);
	virtual ~SetPropertyCommand() { }

	virtual void execute();
	virtual void unexecute();
	virtual QString getName() const;

    protected:
	PropertyContainer *m_pc;
	PropertyName m_pn;
	int m_value;
	int m_oldValue;
    };

    virtual bool convertPropertyStrings(QString nameString, QString valueString,
                                        PropertyName &name, int &value);
};

#endif