Chris@49: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@0: 
Chris@0: /*
Chris@52:     Sonic Visualiser
Chris@52:     An audio file viewer and annotation editor.
Chris@52:     Centre for Digital Music, Queen Mary, University of London.
Chris@202:     This file copyright 2006 Chris Cannam and QMUL.
Chris@0:     
Chris@52:     This program is free software; you can redistribute it and/or
Chris@52:     modify it under the terms of the GNU General Public License as
Chris@52:     published by the Free Software Foundation; either version 2 of the
Chris@52:     License, or (at your option) any later version.  See the file
Chris@52:     COPYING included with this distribution for more information.
Chris@0: */
Chris@0: 
Chris@0: #ifndef _PROPERTY_CONTAINER_H_
Chris@0: #define _PROPERTY_CONTAINER_H_
Chris@0: 
Chris@46: #include "Command.h"
Chris@46: 
Chris@0: #include <QString>
Chris@0: #include <QObject>
Chris@0: #include <vector>
Chris@0: 
Chris@28: class PlayParameters;
Chris@190: class RangeMapper;
Chris@0: 
Chris@29: class PropertyContainer : public QObject
Chris@0: {
Chris@29:     Q_OBJECT
Chris@29: 
Chris@0: public:
Chris@27:     virtual ~PropertyContainer() { }
Chris@27: 
Chris@0:     typedef QString PropertyName;
Chris@0:     typedef std::vector<PropertyName> PropertyList;
Chris@0:     
Chris@0:     enum PropertyType {
Chris@0: 	ToggleProperty, // on or off
Chris@0: 	RangeProperty, // range of integers
Chris@0: 	ValueProperty, // range of integers given string labels
Chris@277: 	ColourProperty, // colours, get/set as ColourDatabase indices
Chris@116:         UnitsProperty, // unit from UnitDatabase, get/set unit id
Chris@0: 	InvalidProperty, // property not found!
Chris@0:     };
Chris@0: 
Chris@0:     /**
Chris@0:      * Get a list of the names of all the supported properties on this
Chris@94:      * container.  These should be fixed (i.e. not internationalized).
Chris@0:      */
Chris@0:     virtual PropertyList getProperties() const;
Chris@0: 
Chris@0:     /**
Chris@94:      * Return the human-readable (and i18n'ised) name of a property.
Chris@94:      */
Chris@94:     virtual QString getPropertyLabel(const PropertyName &) const = 0;
Chris@94: 
Chris@94:     /**
Chris@0:      * Return the type of the given property, or InvalidProperty if
Chris@0:      * the property is not supported on this container.
Chris@0:      */
Chris@0:     virtual PropertyType getPropertyType(const PropertyName &) const;
Chris@0: 
Chris@0:     /**
Chris@340:      * Return an icon for the property, if any.
Chris@340:      */
Chris@340:     virtual QString getPropertyIconName(const PropertyName &) const;
Chris@340: 
Chris@340:     /**
Chris@0:      * If this property has something in common with other properties
Chris@0:      * on this container, return a name that can be used to group them
Chris@0:      * (in order to save screen space, for example).  e.g. "Window
Chris@0:      * Type" and "Window Size" might both have a group name of "Window".
Chris@0:      * If this property is not groupable, return the empty string.
Chris@0:      */
Chris@0:     virtual QString getPropertyGroupName(const PropertyName &) const;
Chris@0: 
Chris@0:     /**
Chris@0:      * Return the minimum and maximum values for the given property
Chris@0:      * and its current value in this container.  Min and/or max may be
Chris@0:      * passed as NULL if their values are not required.
Chris@0:      */
Chris@0:     virtual int getPropertyRangeAndValue(const PropertyName &,
Chris@245: 					 int *min, int *max, int *deflt) const;
Chris@0: 
Chris@0:     /**
Chris@0:      * If the given property is a ValueProperty, return the display
Chris@0:      * label to be used for the given value for that property.
Chris@0:      */
Chris@0:     virtual QString getPropertyValueLabel(const PropertyName &,
Chris@0: 					  int value) const;
Chris@0: 
Chris@190:     /**
Chris@190:      * If the given property is a RangeProperty, return a new
Chris@190:      * RangeMapper object mapping its integer range onto an underlying
Chris@190:      * floating point value range for human-intelligible display, if
Chris@190:      * appropriate.  The RangeMapper should be allocated with new, and
Chris@190:      * the caller takes responsibility for deleting it.  Return NULL
Chris@190:      * (as in the default implementation) if there is no such mapping.
Chris@190:      */
Chris@190:     virtual RangeMapper *getNewPropertyRangeMapper(const PropertyName &) const;
Chris@190: 
Chris@29:     virtual QString getPropertyContainerName() const = 0;
Chris@29:     virtual QString getPropertyContainerIconName() const = 0;
Chris@29: 
Chris@29:     virtual PlayParameters *getPlayParameters() { return 0; }
Chris@29: 
Chris@29: signals:
Chris@141:     void propertyChanged(PropertyContainer::PropertyName);
Chris@224: 
Chris@29: public slots:
Chris@0:     /**
Chris@0:      * Set a property.  This is used for all property types.  For
Chris@0:      * boolean properties, zero is false and non-zero true; for
Chris@277:      * colours, the integer value is an index into the colours in the
Chris@277:      * global ColourDatabase.
Chris@0:      */
Chris@0:     virtual void setProperty(const PropertyName &, int value);
Chris@46: 
Chris@46:     /**
Chris@387:      * Obtain a command that sets the given property, which can be
Chris@387:      * added to the command history for undo/redo.  Returns NULL
Chris@387:      * if the property is already set to the given value.
Chris@46:      */
Chris@387:     virtual Command *getSetPropertyCommand(const PropertyName &, int value);
Chris@46: 
Chris@199:     /**
Chris@199:      * Set a property using a fuzzy match.  Compare nameString with
Chris@199:      * the property labels and underlying names, and if it matches one
Chris@199:      * (with preference given to labels), try to convert valueString
Chris@199:      * appropriately and set it.  The valueString should contain a
Chris@199:      * value label for value properties, a mapped value for range
Chris@199:      * properties, "on" or "off" for toggle properties, a colour or
Chris@199:      * unit name, or the underlying integer value for the property.
Chris@199:      *
Chris@199:      * Note that as property and value labels may be translatable, the
Chris@199:      * results of this function may vary by locale.  It is intended
Chris@199:      * for handling user-originated strings, _not_ persistent storage.
Chris@199:      *
Chris@199:      * The default implementation should work for most subclasses.
Chris@199:      */
Chris@199:     virtual void setProperty(QString nameString, QString valueString);
Chris@199: 
Chris@199:     /**
Chris@387:      * As above, but returning a command.
Chris@199:      */
Chris@387:     virtual Command *getSetPropertyCommand(QString nameString, QString valueString);
Chris@199: 
Chris@46: protected:
Chris@46: 
Chris@46:     class SetPropertyCommand : public Command
Chris@46:     {
Chris@46:     public:
Chris@46: 	SetPropertyCommand(PropertyContainer *pc, const PropertyName &pn, int);
Chris@46: 	virtual ~SetPropertyCommand() { }
Chris@46: 
Chris@46: 	virtual void execute();
Chris@46: 	virtual void unexecute();
Chris@46: 	virtual QString getName() const;
Chris@46: 
Chris@46:     protected:
Chris@46: 	PropertyContainer *m_pc;
Chris@46: 	PropertyName m_pn;
Chris@46: 	int m_value;
Chris@46: 	int m_oldValue;
Chris@46:     };
Chris@199: 
Chris@199:     virtual bool convertPropertyStrings(QString nameString, QString valueString,
Chris@199:                                         PropertyName &name, int &value);
Chris@0: };
Chris@0: 
Chris@0: #endif