comparison base/PropertyContainer.h @ 0:fc9323a41f5a

start base : Sonic Visualiser sv1-1.0rc1

+/* -*- 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 and QMUL.
+    
+    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, int *deflt) 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