KProperty

KPropertyEditorView.h
1/* This file is part of the KDE project
2 Copyright (C) 2008-2018 Jarosław Staniek <staniek@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KPROPERTY_EDITORVIEW_H
21#define KPROPERTY_EDITORVIEW_H
22
23#include "kpropertywidgets_export.h"
24
25#include <QTreeView>
26
27class KProperty;
28class KPropertySet;
30
31//! @brief A widget for editing properties
32class KPROPERTYWIDGETS_EXPORT KPropertyEditorView : public QTreeView
33{
34 Q_OBJECT
35public:
36 /*! Creates an empty property editor with @a parent as parent widget. */
37 explicit KPropertyEditorView(QWidget *parent = nullptr);
38
39 ~KPropertyEditorView() override;
40
41 //! Options for changeSet()
42 enum class SetOption {
43 None = 0,
44 PreservePreviousSelection = 1, //!< If used, previously selected editor item
45 //!< will be kept selected.
46 AlphabeticalOrder = 2 //!< Alphabetical order of properties. The default is order of insertion.
47 };
48 Q_DECLARE_FLAGS(SetOptions, SetOption)
49
50 //! @return grid line color, defaultGridLineColor() by default
51 QColor gridLineColor() const;
52
53 //! @return default grid line color - Qt::gray
55
56 //! Reimplemented to suggest widget size that is based on number of property items.
57 QSize sizeHint() const override;
58
59 //! @return the property set object that is assigned to this view or nullptr is no set
60 //! is currently assigned.
61 KPropertySet* propertySet() const;
62
63 /*! @return @c true if items for parent composed properties are expanded so items for child
64 properties are displayed.
65 @since 3.1 */
66 bool childPropertyItemsExpanded() const;
67
68 /*! @return value of the valueSyncEnabled flag.
69 @since 3.1 */
70 bool isValueSyncEnabled() const;
71
72 /*! @return @c true if the property groups should be visible.
73 By default groups are visible.
74 A group is visualized as a subtree displaying group caption and group icon at its root node
75 (see KProperty::groupCaption and KProperty::groupIconName) and properties as children of this node.
76 A property is assigned to a group while KPropertySet::addProperty() is called.
77
78 @note Regardless of this flag, no groups are displayed if there is only the default group
79 "common".
80
81 When the group visibility flag is off or only the "common" group is present, all properties
82 are displayed on the same (top) level.
83 @since 3.1 */
84 bool groupsVisible() const;
85
86 /*! @return @c true if group items for newly added groups are exapanded so properties for these
87 groups are displayed.
88 @see setGroupItemsExpanded()
89 @since 3.1 */
90 bool groupItemsExpanded() const;
91
92 /**
93 * Returns @c true if the property editor widget has enabled visibility of tooltips
94 *
95 * Tooltips are displayed over each property item, both the name and value column, and are
96 * equal to property descriptions (KProperty::description()). Tooltips are not displayed for
97 * items having empty descriptions.
98 *
99 * Tooltips visibility is disabled by default.
100 * @since 3.1
101 */
102 bool toolTipsVisible() const;
103
104public Q_SLOTS:
105 /*! Populates the editor view with items for each property from the @a set set.
106 Child items for composed properties are also created.
107 See SetOption documentation for description of @a options options.
108 If @a preservePreviousSelection is true, previously selected editor
109 item will be kept selected, if present. */
110 void changeSet(KPropertySet *set, SetOptions options = SetOption::None);
111
112 /*! Populates the editor view with items for each property from the @a set set.
113 Child items for composed properties are also created.
114 If @a propertyToSelect is provided, item for this property name
115 will be selected, if present. */
116 void changeSet(KPropertySet *set, const QByteArray& propertyToSelect, SetOptions options = SetOption::None);
117
118 /*! If @a set is @c true (the default), items for parent composed properties are expanded
119 so items for child properties are displayed.
120 If @a set is @c false, the items are collapsed.
121 @note Appearance of the existing child items is not altered. This method can be typically called
122 before a changeSet() call or before adding properties.
123 @note Expansion of group items is not affected by this method. Use setGroupItemsExpanded()
124 to control expansion of group items.
125 @note To expand all items use expandAll(). To collapse all items use collapseAll().
126 @since 3.1 */
127 void setChildPropertyItemsExpanded(bool set);
128
129 /*! If @a set is @c true (the default), property values are automatically synchronized as
130 soon as editor contents change (e.g. every time the user types a character)
131 and the values are saved back to the assigned property set.
132 If @a enable is false, property set is updated only when selection within the property editor
133 or user presses Enter/Return key.
134 Each property can override this policy by changing its own valueSyncPolicy flag.
135 @see KProperty::setValueSyncPolicy()
136 @since 3.1 */
137 void setValueSyncEnabled(bool set);
138
139 /*! Accepts the changes made to the current editor item (if any)
140 (as if the user had pressed Enter key). */
141 void acceptInput();
142
143 //! Sets color of grid lines. Use invalid color QColor() to hide grid lines.
144 void setGridLineColor(const QColor& color);
145
146 /*! Shows the property groups if @a set is @c true.
147 @see groupsVisible()
148 @since 3.1 */
149 void setGroupsVisible(bool set);
150
151 /*! If @a set is @c true (the default), group items for newly added groups are exapanded
152 so properties for these groups are displayed.
153 If @a set is @c false, the items are collapsed.
154 @note Appearance of the existing group items is not altered. This method can be typically called
155 before a changeSet() call or before adding properties.
156 @note Expansion of child items for composed properties is not affected by this method.
157 Use setChildPropertyItemsExpanded() to control expansion child items for composed properties.
158 @note To expand all items use expandAll(). To collapse all items use collapseAll().
159 @since 3.1 */
160 void setGroupItemsExpanded(bool set);
161
162 /**
163 * If @a set is @c true tooltips are visible for property editor items
164 *
165 * See toolTipsVisible() for details.
166 * @since 3.1
167 */
168 void setToolTipsVisible(bool set);
169
171 /*! Emitted when current property set has been changed. May be 0. */
173
174 /**
175 * Emitted when active property editor widget offers overriding of its editing behavior.
176 *
177 * See KPropertyEditorItemEvent for usage details.
178 *
179 * @note @a event is owned by the KPropertyEditorView object.
180 *
181 * @since 3.2
182 */
184
185protected:
186 bool viewportEvent(QEvent * event) override;
187
188protected Q_SLOTS:
189 void currentChanged(const QModelIndex &current, const QModelIndex &previous) override;
190 void commitData(QWidget * editor) override;
191
192 /*! Called when current propertis of this set are about to be cleared. */
193 void slotSetWillBeCleared();
194
195 /*! Called when current property set is about to be destroyed. */
196 void slotSetWillBeDeleted();
197
198 /*! Called when property set's read-only flag has changed.
199 Refreshes selection so editor is displayed again if needed. */
200 void slotReadOnlyFlagChanged();
201
202 /*! Updates editor widget in the editor.*/
203 void slotPropertyChanged(KPropertySet& set, KProperty& property);
204
205 void slotPropertyReset(KPropertySet& set, KProperty& property);
206
207private:
208 /*! Used by changeSet(). */
209 void changeSetInternal(KPropertySet *set, SetOptions options, const QByteArray &propertyToSelect);
210 bool edit(const QModelIndex &index, EditTrigger trigger, QEvent *event) override;
211 void drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const override;
212
213 //! Reimplemented to draw group header text by hand.
214 void drawRow(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
215
216 void mousePressEvent(QMouseEvent *event) override;
217
218 //! @return true if @a x is within the area of the revert button for @a index index.
219 bool withinRevertButtonArea( int x, const QModelIndex& index ) const;
220
221 //! @return area of revert button, if it is displayed for @a index index.
222 //! Otherwise invalid QRect is returned.
223 QRect revertButtonArea( const QModelIndex& index ) const;
224
225 //! Updates item for @a index and all its children.
226 void updateSubtree(const QModelIndex &index);
227
228 /*! Undoes the last change in the property editor.*/
229 void undo();
230
231 Q_DISABLE_COPY(KPropertyEditorView)
232 class Private;
233 Private * const d;
234};
235
236Q_DECLARE_OPERATORS_FOR_FLAGS(KPropertyEditorView::SetOptions)
237
238#endif
The KPropertyEditorItemEvent class describes request for handling a single property editor widget ite...
A widget for editing properties.
void propertySetChanged(KPropertySet *set)
static QColor defaultGridLineColor()
void handlePropertyEditorItemEvent(KPropertyEditorItemEvent *event)
Emitted when active property editor widget offers overriding of its editing behavior.
SetOption
Options for changeSet()
Set of properties.
The base class representing a single property.
Definition KProperty.h:96
virtual void commitData(QWidget *editor)
virtual bool edit(const QModelIndex &index, EditTrigger trigger, QEvent *event)
virtual QSize sizeHint() const const override
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
virtual void currentChanged(const QModelIndex &current, const QModelIndex &previous) override
virtual void drawBranches(QPainter *painter, const QRect &rect, const QModelIndex &index) const const
virtual void drawRow(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const const
virtual void mousePressEvent(QMouseEvent *event) override
virtual bool viewportEvent(QEvent *event) override
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:15:40 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.