File indexing completed on 2024-03-24 16:11:33

0001 /* This file is part of the KDE project
0002    Copyright (C) 2008-2018 Jarosław Staniek <staniek@kde.org>
0003 
0004    This library is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This library is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this library; see the file COPYING.LIB.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KPROPERTY_EDITORVIEW_H
0021 #define KPROPERTY_EDITORVIEW_H
0022 
0023 #include "kpropertywidgets_export.h"
0024 
0025 #include <QTreeView>
0026 
0027 class KProperty;
0028 class KPropertySet;
0029 class KPropertyEditorItemEvent;
0030 
0031 //! @brief A widget for editing properties
0032 class KPROPERTYWIDGETS_EXPORT KPropertyEditorView : public QTreeView
0033 {
0034     Q_OBJECT
0035 public:
0036     /*! Creates an empty property editor with @a parent as parent widget. */
0037     explicit KPropertyEditorView(QWidget *parent = nullptr);
0038 
0039     ~KPropertyEditorView() override;
0040 
0041     //! Options for changeSet()
0042     enum class SetOption {
0043         None = 0,
0044         PreservePreviousSelection = 1, //!< If used, previously selected editor item
0045                                        //!< will be kept selected.
0046         AlphabeticalOrder = 2          //!< Alphabetical order of properties. The default is order of insertion.
0047     };
0048     Q_DECLARE_FLAGS(SetOptions, SetOption)
0049 
0050     //! @return grid line color, defaultGridLineColor() by default
0051     QColor gridLineColor() const;
0052 
0053     //! @return default grid line color - Qt::gray
0054     static QColor defaultGridLineColor() { return Qt::gray; }
0055 
0056     //! Reimplemented to suggest widget size that is based on number of property items.
0057     QSize sizeHint() const override;
0058 
0059     //! @return the property set object that is assigned to this view or nullptr is no set
0060     //! is currently assigned.
0061     KPropertySet* propertySet() const;
0062 
0063     /*! @return @c true if items for parent composed properties are expanded so items for child
0064      properties are displayed.
0065      @since 3.1 */
0066     bool childPropertyItemsExpanded() const;
0067 
0068     /*! @return value of the valueSyncEnabled flag.
0069      @since 3.1 */
0070     bool isValueSyncEnabled() const;
0071 
0072     /*! @return @c true if the property groups should be visible.
0073      By default groups are visible.
0074      A group is visualized as a subtree displaying group caption and group icon at its root node
0075      (see KProperty::groupCaption and KProperty::groupIconName) and properties as children of this node.
0076      A property is assigned to a group while KPropertySet::addProperty() is called.
0077 
0078      @note Regardless of this flag, no groups are displayed if there is only the default group
0079      "common".
0080 
0081      When the group visibility flag is off or only the "common" group is present, all properties
0082      are displayed on the same (top) level.
0083      @since 3.1 */
0084     bool groupsVisible() const;
0085 
0086     /*! @return @c true if group items for newly added groups are exapanded so properties for these
0087      groups are displayed.
0088      @see setGroupItemsExpanded()
0089      @since 3.1 */
0090     bool groupItemsExpanded() const;
0091 
0092     /**
0093      * Returns @c true if the property editor widget has enabled visibility of tooltips
0094      *
0095      * Tooltips are displayed over each property item, both the name and value column, and are
0096      * equal to property descriptions (KProperty::description()). Tooltips are not displayed for
0097      * items having empty descriptions.
0098      *
0099      * Tooltips visibility is disabled by default.
0100      * @since 3.1
0101      */
0102     bool toolTipsVisible() const;
0103 
0104 public Q_SLOTS:
0105     /*! Populates the editor view with items for each property from the @a set set.
0106      Child items for composed properties are also created.
0107      See SetOption documentation for description of @a options options.
0108      If @a preservePreviousSelection is true, previously selected editor
0109      item will be kept selected, if present. */
0110     void changeSet(KPropertySet *set, SetOptions options = SetOption::None);
0111 
0112     /*! Populates the editor view with items for each property from the @a set set.
0113      Child items for composed properties are also created.
0114      If @a propertyToSelect is provided, item for this property name
0115      will be selected, if present. */
0116     void changeSet(KPropertySet *set, const QByteArray& propertyToSelect, SetOptions options = SetOption::None);
0117 
0118     /*! If @a set is @c true (the default), items for parent composed properties are expanded
0119      so items for child properties are displayed.
0120      If @a set is @c false, the items are collapsed.
0121      @note Appearance of the existing child items is not altered. This method can be typically called
0122            before a changeSet() call or before adding properties.
0123      @note Expansion of group items is not affected by this method. Use setGroupItemsExpanded()
0124            to control expansion of group items.
0125      @note To expand all items use expandAll(). To collapse all items use collapseAll().
0126      @since 3.1 */
0127     void setChildPropertyItemsExpanded(bool set);
0128 
0129     /*! If @a set is @c true (the default), property values are automatically synchronized as
0130     soon as editor contents change (e.g. every time the user types a character)
0131     and the values are saved back to the assigned property set.
0132     If @a enable is false, property set is updated only when selection within the property editor
0133     or user presses Enter/Return key.
0134     Each property can override this policy by changing its own valueSyncPolicy flag.
0135     @see KProperty::setValueSyncPolicy()
0136      @since 3.1 */
0137     void setValueSyncEnabled(bool set);
0138 
0139     /*! Accepts the changes made to the current editor item (if any)
0140      (as if the user had pressed Enter key). */
0141     void acceptInput();
0142 
0143     //! Sets color of grid lines. Use invalid color QColor() to hide grid lines.
0144     void setGridLineColor(const QColor& color);
0145 
0146     /*! Shows the property groups if @a set is @c true.
0147      @see groupsVisible()
0148      @since 3.1 */
0149     void setGroupsVisible(bool set);
0150 
0151     /*! If @a set is @c true (the default), group items for newly added groups are exapanded
0152      so properties for these groups are displayed.
0153      If @a set is @c false, the items are collapsed.
0154      @note Appearance of the existing group items is not altered. This method can be typically called
0155            before a changeSet() call or before adding properties.
0156      @note Expansion of child items for composed properties is not affected by this method.
0157            Use setChildPropertyItemsExpanded() to control expansion child items for composed properties.
0158      @note To expand all items use expandAll(). To collapse all items use collapseAll().
0159      @since 3.1 */
0160     void setGroupItemsExpanded(bool set);
0161 
0162     /**
0163      * If @a set is @c true tooltips are visible for property editor items
0164      *
0165      * See toolTipsVisible() for details.
0166      * @since 3.1
0167      */
0168     void setToolTipsVisible(bool set);
0169 
0170 Q_SIGNALS:
0171     /*! Emitted when current property set has been changed. May be 0. */
0172     void propertySetChanged(KPropertySet *set);
0173 
0174     /**
0175      * Emitted when active property editor widget offers overriding of its editing behavior.
0176      *
0177      * See KPropertyEditorItemEvent for usage details.
0178      *
0179      * @note @a event is owned by the KPropertyEditorView object.
0180      *
0181      * @since 3.2
0182      */
0183     void handlePropertyEditorItemEvent(KPropertyEditorItemEvent *event);
0184 
0185 protected:
0186     bool viewportEvent(QEvent * event) override;
0187 
0188 protected Q_SLOTS:
0189     void currentChanged(const QModelIndex &current, const QModelIndex &previous) override;
0190     void commitData(QWidget * editor) override;
0191 
0192     /*! Called when current propertis of this set are about to be cleared. */
0193     void slotSetWillBeCleared();
0194 
0195     /*! Called when current property set is about to be destroyed. */
0196     void slotSetWillBeDeleted();
0197 
0198     /*! Called when property set's read-only flag has changed.
0199      Refreshes selection so editor is displayed again if needed. */
0200     void slotReadOnlyFlagChanged();
0201 
0202     /*! Updates editor widget in the editor.*/
0203     void slotPropertyChanged(KPropertySet& set, KProperty& property);
0204 
0205     void slotPropertyReset(KPropertySet& set, KProperty& property);
0206 
0207 private:
0208     /*! Used by changeSet(). */
0209     void changeSetInternal(KPropertySet *set, SetOptions options, const QByteArray &propertyToSelect);
0210     bool edit(const QModelIndex &index, EditTrigger trigger, QEvent *event) override;
0211     void drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const override;
0212 
0213     //! Reimplemented to draw group header text by hand.
0214     void drawRow(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0215 
0216     void mousePressEvent(QMouseEvent *event) override;
0217 
0218     //! @return true if @a x is within the area of the revert button for @a index index.
0219     bool withinRevertButtonArea( int x, const QModelIndex& index ) const;
0220 
0221     //! @return area of revert button, if it is displayed for @a index index.
0222     //! Otherwise invalid QRect is returned.
0223     QRect revertButtonArea( const QModelIndex& index ) const;
0224 
0225     //! Updates item for @a index and all its children.
0226     void updateSubtree(const QModelIndex &index);
0227 
0228     /*! Undoes the last change in the property editor.*/
0229     void undo();
0230 
0231     Q_DISABLE_COPY(KPropertyEditorView)
0232     class Private;
0233     Private * const d;
0234 };
0235 
0236 Q_DECLARE_OPERATORS_FOR_FLAGS(KPropertyEditorView::SetOptions)
0237 
0238 #endif