diff --git a/src/KProperty.h b/src/KProperty.h index 1029808..df9e330 100644 --- a/src/KProperty.h +++ b/src/KProperty.h @@ -1,450 +1,490 @@ /* This file is part of the KDE project Copyright (C) 2004 Cedric Pasteur Copyright (C) 2004 Alexander Dymo - Copyright (C) 2004-2015 Jarosław Staniek + Copyright (C) 2004-2016 Jarosław Staniek This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef KPROPERTY_PROPERTY_H #define KPROPERTY_PROPERTY_H #include #include #include #include #include "kpropertycore_export.h" /*! \brief Namespace for a set of classes implementing generic properties framework. Main classes of this framework are: - Property, representing a single property with its own type and value - Set, a set of properties - Editor, a widget for displaying and editing properties provided by a Set object. Every property has its own row displayed using EditorItem object, within Editor widget. Widget class provides editing feature for EditorItem objects if a user selects a given item. KProperty framework also supports adding composed and property types and custom property editor types. Take a look at the test application, available in the test/ directory to see example uses of the framework. @author Cedric Pasteur @author Alexander Dymo @author Jarosław Staniek */ class KComposedPropertyInterface; class KPropertySet; /*! Data container for properties of list type. */ class KPROPERTYCORE_EXPORT KPropertyListData { public: /*! Data container for list-value property. We will be able to choose an item from this list. */ KPropertyListData(const QStringList& keys_, const QStringList& names_); KPropertyListData(const QList keys_, const QStringList& names_); KPropertyListData(); ~KPropertyListData(); void setKeysAsStringList(const QStringList& list); QStringList keysAsStringList() const; /*! The string list containing all possible keys for this property or NULL if this is not a property of type 'list'. The values in this list are ordered, so the first key element is associated with first element from the 'names' list, and so on. */ QList keys; // QStringList keys; //! @todo what about using QValueList here too? /*! The list of translated names that will be visible on the screen. First value is referenced by first key, and so on. */ QStringList names; //unused for now /*! True (the default), if the list has fixed number of possible //unused for now items (keys). If this is false, user can add or enter own values. */ //unused for now bool fixed; }; /*! \brief The base class representing a single property It can hold a property of any type supported by QVariant. You can also create you own property types (see Using Custom Properties in Factory doc). As a consequence, do not subclass Property, use \ref KComposedPropertyInterface instead. \n Each property stores old value to allow undo. It has a name (a QByteArray), a caption (user-visible translated name shown in Editor) and a description (also translated). \n It also supports setting arbitrary number of options (of type option=value). See Editor for a list of options, and their meaning. \code // To create a property property = Property(name, value, caption, description); // name is a QByteArray, // value is whatever type QVariant supports // To create a valueFromList property (matching strings with strings) QStringList keys, strings; keys << "one" << "two" << "three"; // possible values of the property // Strings (possibly translated) shown in the editor instead of the values strings << tr("One") << tr("Two") << tr("Three"); property = Property(name, keys, strings, "two", caption); // To create a valueFromList property (matching strings with QVariant) QValueList keys2; keys2.append(1); keys2.append(2); keys2.append(3); Property::ListData listData(keys2, strings); m_set->addProperty(new Property("List2", listData, "otheritem", "List2"), group); \endcode Note that you need to use QVariant(bool, int) to create a boolean property value. See QVariant docs for more details. Sometimes, for longer property captions or these with more words, e.g. "Allow Zero Size", its usable to provide newline characters, e.g. "Allow Zero\nSize". If caption argument of the constructors contains newline characters, caption() will return this text with substituted these characters with spaces. In such cases, captionForDisplaying() is used to get the original caption text usable (with newline, if any) for displaying within a property editor. \author Cedric Pasteur \author Alexander Dymo \author Jarosław Staniek */ class KPROPERTYCORE_EXPORT KProperty { public: /*! Defines types of properties. Properties defined by plugins should have a type number >= UserDefined .*/ enum Type { //standard supported QVariant types Auto = 0x00ffffff, Invalid = QVariant::Invalid, BitArray = QVariant::BitArray, Bitmap = QVariant::Bitmap, Bool = QVariant::Bool, Brush = QVariant::Brush, ByteArray = QVariant::ByteArray, Char = QVariant::Char, Color = QVariant::Color, Cursor = QVariant::Cursor, Date = QVariant::Date, DateTime = QVariant::DateTime, Double = QVariant::Double, Font = QVariant::Font, Icon = QVariant::Icon, Image = QVariant::Image, Int = QVariant::Int, KeySequence = QVariant::KeySequence, Line = QVariant::Line, LineF = QVariant::LineF, List = QVariant::List, Locale = QVariant::Locale, LongLong = QVariant::LongLong, Map = QVariant::Map, Matrix = QVariant::Matrix, Transform = QVariant::Transform, Palette = QVariant::Palette, Pen = QVariant::Pen, Pixmap = QVariant::Pixmap, Point = QVariant::Point, PointF = QVariant::PointF, Polygon = QVariant::Polygon, Rect = QVariant::Rect, RectF = QVariant::RectF, RegExp = QVariant::RegExp, Region = QVariant::Region, Size = QVariant::Size, SizeF = QVariant::SizeF, SizePolicy = QVariant::SizePolicy, String = QVariant::String, StringList = QVariant::StringList, TextFormat = QVariant::TextFormat, TextLength = QVariant::TextLength, Time = QVariant::Time, UInt = QVariant::UInt, ULongLong = QVariant::ULongLong, Url = QVariant::Url, //predefined custom types ValueFromList = 1000 /*** children() const; /*! \return a child property for \a name, or NULL if there is no property with that name. */ KProperty* child(const QByteArray &name); /*! \return parent property for this property, or NULL if there is no parent property. */ KProperty* parent() const; /*! \return the composed property for this property, or NULL if there was no composed property defined. */ KComposedPropertyInterface* composedProperty() const; /*! Sets composed property \a prop for this property. */ void setComposedProperty(KComposedPropertyInterface *prop); /*! \return true if this property is null. Null properties have empty names. */ bool isNull() const; //! \return true if this property value is changed. bool isModified() const; //! Clears "modified" flag, so isModified() will return false. void clearModifiedFlag(); /*! \return true if the property is read-only. The property can be read-write but still not editable because the property set containing it may be set to read-only. By default the property is read-write. See Set::isReadOnly() for more details. */ bool isReadOnly() const; /*! Sets this property to be read-only. @see isReadOnly() */ void setReadOnly(bool readOnly); /*! \return true if the property is visible.*/ bool isVisible() const; /*! Set the visibility.*/ void setVisible(bool visible); /*! \return true if the property can be saved to a stream, xml, etc. There is a possibility to use "GUI" properties that aren't stored but used only in a GUI.*/ bool isStorable() const; /*! Sets "storable" flag for this property. @see isStorable() */ void setStorable(bool storable); /*! \return 1 if the property should be synced automatically in Property Editor as soon as editor contents change (e.g. when the user types text). If autoSync() == 0, property value will be updated when the user presses Enter or when another editor gets the focus. Property follows Property Editor's global rule if autoSync() !=0 and !=1 (the default). */ int autoSync() const; /*! if \a sync is 1, the property will be synced automatically in the Property Editor as soon as editor's contents change (e.g. when the user types text). If \a sync is 0, property value will be updated when the user presses Enter or when another editor gets the focus. Property follows Property Editor's global rule if sync !=0 and !=1 (the default). */ void setAutoSync(int sync); /*! Sets value \a val for option \a name. - Options are used to describe additional details for property behaviour, - e.g. within Editor. See Editor ctor documentation for - the list of supported options. - */ + Options are used to override default settings of individual properties. + This is most visible in property editor widget. + + Currently supported options are: +
  • min: integer value describing minimum value for properties of integer and + double types. The default is 0.
  • +
  • minValueText: user-visible translated string to be displayed in editor for integer + type when minimum is set for the property. + @see QAbstractSpinBox::specialValueText
  • +
  • max: integer describing minimum value for properties of integer type. Default is 0xffff.
  • +
  • precision: integer value describing the number of decimals after the decimal point + for double type.
  • +
  • step: integer describing the size of the step that is taken when the user hits + the up or down button of editor for double type.
  • +
  • 3State: boolean value used for boolean type; if @c true, the editor becomes a combobox + (instead of checkable button) and accepts the third "null" state.
  • +
  • yesName: user-visible translated string used for boolean type (both 2- and 3-state) + to visually represent the "true" value. If not present, tr("Yes") is used.
  • +
  • noName: user-visible translated string used for boolean type (both 2- and 3-state) + to visually represent the "false" value. If not present, tr("No") is used.
  • +
  • 3rdStateName: user-visible translated string used for boolean type (both 2- and 3-state) + to visually represent the third "null" value. If not present, tr("None") is used.
  • +
  • nullName: user-visible translated string used for boolean type to display the "null" + value, if and only if the property accepts two states (i.e. when "3State" option + is @c false). If the "nullName" option is not set, null values are displayed as + @c false.
  • +
  • extraValueAllowed: boolean value, if @c true the user is able to manually add extra + values to a combobox.
  • +
  • fileMode: string value that describes what objects may select in the file dialog + of the url editor: +
      +
    • "dirsOnly": only support and display directories; + @see QFileDialog::ShowDirsOnly QFileDialog::Directory
    • +
    • "existingFile": only allow to select one existing file; + @see QFileDialog::ExistingFile
    • +
    • Any other value: any file is supported, whether it exists or not + @see QFileDialog::AnyFile
    • +
    +
  • +
  • confirmOverwrites: boolean value, if @c true, user will be asked for confirmation + of file overwriting in the url editor. @c false by default. + @note The line edit does not validate the content.
  • +
*/ void setOption(const char* name, const QVariant& val); /*! \return a value for option \a name or null value if there is no such option set. - If there is no such value, @a defaultValue is returned. */ + If there is no such value, @a defaultValue is returned. + @see setOption */ QVariant option(const char* name, const QVariant& defaultValue = QVariant()) const; /*! \return true if at least one option is defined for this property. */ bool hasOptions() const; /*! Equivalent to setValue(const QVariant &) */ KProperty& operator= (const QVariant& val); /*! Assigns a deep copy of all attributes of \a property to this property. */ KProperty& operator= (const KProperty &property); /*! Compares two properties.*/ bool operator ==(const KProperty &prop) const; #if 0 /*! \return a key used for sorting. Usually its set by Set::addProperty() and Property::addChild() to a unique value, so that this property can be sorted in a property editor in original order. \see EditorItem::compare() */ int sortingKey() const; #endif protected: /*! Adds \a prop as a child of this property. The children will be owned by this property. */ void addChild(KProperty *prop); /*! Adds \a set to this property. */ void addSet(KPropertySet *set); #if 0 /*! Sets a key used for sorting. */ void setSortingKey(int key); #endif /*! \return a list of related properties for this property. */ const QList* related() const; /*! Adds related property for this property. */ void addRelatedProperty(KProperty *property); /*! This method emits the \a Set::propertyChanged() signal for all sets this property is registered in. The \a value() method above calls this method of the value changed. */ void emitPropertyChanged(); /*! Outputs debug string for this property. */ void debug() const; /*! For operator <<. */ QMap options() const; //! @internal class Private; friend class Private; Private * const d; friend class KPropertySet; friend class KPropertyBuffer; friend class KComposedPropertyInterface; friend KPROPERTYCORE_EXPORT QDebug operator<<(QDebug dbg, const KProperty &p); }; //! qDebug() stream operator. Writes property @a p to the debug output in a nicely formatted way. KPROPERTYCORE_EXPORT QDebug operator<<(QDebug dbg, const KProperty &p); #endif diff --git a/src/KPropertyEditorView.h b/src/KPropertyEditorView.h index f069737..62b9cbd 100644 --- a/src/KPropertyEditorView.h +++ b/src/KPropertyEditorView.h @@ -1,184 +1,144 @@ /* This file is part of the KDE project Copyright (C) 2008-2016 Jarosław Staniek This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef KPROPERTY_EDITORVIEW_H #define KPROPERTY_EDITORVIEW_H #include "kpropertywidgets_export.h" #include class KProperty; class KPropertySet; //! @brief A widget for editing properties -//! @todo review this ............. -/*! Editor widgets use property options using Property::option(const char *) - to override default behaviour of editor items. - Currently supported options are: -
  • min: integer setting for minimum value for integer and double types. - The default is 0. - Set it to -1, if you want this special value to be allowed.
  • -
  • minValueText: user-visible translated string used for integer type to set "specialValueText" - widget's property
  • -
  • max: integer setting for minimum value the property of integer type. Default is 0xffff.
  • -
  • precision: The number of decimals after the decimal point (for double types).
  • -
  • step: the size of the step that is taken when the user hits the up - or down buttons (for double types).
  • -
  • 3State: boolean value used for boolean types; if true, the editor becomes a combobox - (instead of checkable button) and accepta the third "null" state.
  • -
  • yesName: user-visible translated string used for boolean types (both 2- and 3-state) - to display the "true" value. If not present, tr("Yes") is used.
  • -
  • noName: user-visible translated string used for boolean types (both 2- and 3-state) - to display the "false" value. If not present, tr("No") is used.
  • -
  • 3rdStateName: user-visible translated string used for boolean types (both 2- and 3-state) - to display the 3rd state "null" value. If not present, tr("None") is used.
  • -
  • nullName: user-visible translated string used for boolean types to display the "null" value if - and only if the property accepts two states (i.e. when "3State" option is not true). - If this option is not present, null values are displayed as false.
  • -
  • extraValueAllowed: Allow the user to manually enter a value into a combobox - that is not in the list. The entered text will be returned as opposed to a matching key.
  • -
  • fileMode: indicates what the user may select in the file dialog for the url type's editor: -
      -
    • "dirsOnly": only support and display directories - See QFileDialog::ShowDirsOnly and QFileDialog::Directory.
    • -
    • "existingFile": only allow to select one existing file. See QFileDialog::ExistingFile.
    • -
    • For any other value, supports any file, whether it exists or not. See QFileDialog::AnyFile.
    • -
    - @note The line edit does not validate the content. -
  • -
  • confirmOverwrites: if true, user will be asked for file overwriting by url editor; false by default. - @note The line edit does not validate the content. -
  • -
- */ class KPROPERTYWIDGETS_EXPORT KPropertyEditorView : public QTreeView { Q_OBJECT public: /*! Creates an empty property editor with @a parent as parent widget. */ explicit KPropertyEditorView(QWidget *parent = 0); ~KPropertyEditorView(); //! Options for changeSet(). enum SetOption { NoOptions = 0, PreservePreviousSelection = 1, //!< If used, previously selected editor item //!< will be kept selected. AlphabeticalOrder = 2, //!< Alphabetical order of properties (the default is insert-order) ExpandChildItems = 4 //!< Child property items are expanded (the default is "collapsed") }; Q_DECLARE_FLAGS(SetOptions, SetOption) //! @return grid line color, defaultGridLineColor() by default QColor gridLineColor() const; //! @return default grid line color - Qt::gray static QColor defaultGridLineColor() { return Qt::gray; } //! Reimplemented to suggest widget size that is based on number of property items. QSize sizeHint() const Q_DECL_OVERRIDE; //! @return the property set object that is assigned to this view or nullptr is no set //! is currently assigned. KPropertySet* propertySet() const; public Q_SLOTS: /*! Populates the editor view with items for each property from the @ set set. Child items for composed properties are also created. See SetOption documentation for description of @a options options. If @a preservePreviousSelection is true, previously selected editor item will be kept selected, if present. */ void changeSet(KPropertySet *set, SetOptions options = NoOptions); /*! Populates the editor view with items for each property from the @ set set. Child items for composed properties are also created. If @a propertyToSelect is provided, item for this property name will be selected, if present. */ void changeSet(KPropertySet *set, const QByteArray& propertyToSelect, SetOptions options = NoOptions); /*! If @a enable is true (the default), property values are automatically synced as soon as editor contents change (e.g. every time the user types a character) and the values are written back to the assigned property set. If @a enable is false, property set is updated only when selection within the property editor or user presses Enter/Return key. Each property can overwrite this setting by changing its own autoSync flag. */ void setAutoSync(bool enable); /*! @return value of autoSync flag. */ bool isAutoSync() const; /*! Accepts the changes made to the current editor item (if any) (as if the user had pressed Enter key). */ void acceptInput(); //! Sets color of grid lines. Use invalid color QColor() to hide grid lines. void setGridLineColor(const QColor& color); Q_SIGNALS: /*! Emitted when current property set has been changed. May be 0. */ void propertySetChanged(KPropertySet *set); protected: virtual bool viewportEvent( QEvent * event ); protected Q_SLOTS: virtual void currentChanged( const QModelIndex & current, const QModelIndex & previous ); virtual void commitData( QWidget * editor ); /*! Called when current propertis of this set are about to be cleared. */ void slotSetWillBeCleared(); /*! Called when current property set is about to be destroyed. */ void slotSetWillBeDeleted(); /*! Updates editor widget in the editor.*/ void slotPropertyChanged(KPropertySet& set, KProperty& property); void slotPropertyReset(KPropertySet& set, KProperty& property); private: /*! Used by changeSet(). */ void changeSetInternal(KPropertySet *set, SetOptions options, const QByteArray& propertyToSelect); virtual bool edit( const QModelIndex & index, EditTrigger trigger, QEvent * event ); virtual void drawBranches( QPainter * painter, const QRect & rect, const QModelIndex & index ) const; virtual void mousePressEvent( QMouseEvent * event ); //! @return true if @a x is within the area of the revert button for @a index index. bool withinRevertButtonArea( int x, const QModelIndex& index ) const; //! @return area of revert button, if it is displayed for @a index index. //! Otherwise invalid QRect is returned. QRect revertButtonArea( const QModelIndex& index ) const; //! Updates item for @a index and all its children. void updateSubtree(const QModelIndex &index); /*! Undoes the last change in the property editor.*/ void undo(); class Private; Private * const d; }; Q_DECLARE_OPERATORS_FOR_FLAGS(KPropertyEditorView::SetOptions) #endif