KProperty

KPropertySet.h
1/* This file is part of the KDE project
2 Copyright (C) 2004 Cedric Pasteur <cedric.pasteur@free.fr>
3 Copyright (C) 2004 Alexander Dymo <cloudtemple@mskat.net>
4 Copyright (C) 2004-2017 Jarosław Staniek <staniek@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KPROPERTY_SET_H
23#define KPROPERTY_SET_H
24
25#include <QObject>
26#include <QHash>
27#include <QDebug>
28
29#include "KProperty.h"
30
31class KPropertySetPrivate;
32
33//! An interface for functor selecting properties.
34/*! Used in Iterator. */
35class KPROPERTYCORE_EXPORT KPropertySelector
36{
37public:
39 virtual ~KPropertySelector();
40
41 //! An operator implementing the functor.
42 virtual bool operator()(const KProperty& prop) const = 0;
43
44 //! Creates a deep copy of the selector.
45 //! Required for proper usage of the selector.
46 virtual KPropertySelector* clone() const = 0;
47};
48
49//! A class to iterate over a KPropertySet.
50/*! It behaves like a QList::ConstIterator.
51 Usage:
52 @code for (KPropertySetIterator it(set); it.current(); ++it) { .... }
53 @endcode
54 Usage with selector:
55 @code for (KPropertySetIterator it(set, MySelector()); it.current(); ++it) { .... }
56 @endcode */
57class KPROPERTYCORE_EXPORT KPropertySetIterator
58{
59public:
60 //! Creates iterator for @a set set of properties.
61 /*! The properties are sorted by insertion order by default.
62 Use setOrder(Iterator::Alphabetical) to have alphabetical order. */
63 explicit KPropertySetIterator(const KPropertySet &set);
64
65 //! Creates iterator for @a set set of properties.
66 /*! @a selector functor is used to iterate only
67 over specified properties.
68 The properties are sorted by insertion order by default.
69 Use setOrder(Iterator::Alphabetical) to have alphabetical order. */
70 KPropertySetIterator(const KPropertySet &set, const KPropertySelector& selector);
71
72 //! Copy constructor
73 //! @since 3.1
75
77
78 //! Assigns @a other to this KPropertySetIterator
79 //! @since 3.1
80 KPropertySetIterator& operator=(const KPropertySetIterator &other);
81
82 //! @return true if this iterator equals to @a other
83 //! @since 3.1
84 bool operator==(const KPropertySetIterator &other) const;
85
86 //! @return true if this iterator does not equal to @a other
87 //! @since 3.1
88 inline bool operator!=(const KPropertySetIterator &other) const { return !operator==(other); }
89
90 //! Ordering options for properties
91 /*! @see setOrder() */
92 enum class Order {
93 Insertion, //!< insertion order
94 Alphabetical, //!< alphabetical order (case-insensitively by captions)
95 AlphabeticalByName //!< alphabetical order (case-insensitively by name)
96 };
97
98 //! Sets order for properties. Restarts the iterator.
99 void setOrder(Order order);
100
101 //! @return order for properties.
102 Order order() const;
103
104 void operator++();
105
106 inline KProperty* operator*() const { return current(); }
107
108 KProperty* current() const;
109
110 friend class KPropertySet;
111
112private:
113 class Private;
114 Private * const d;
115};
116
117/*! \brief Set of properties
118 */
119class KPROPERTYCORE_EXPORT KPropertySet : public QObject
120{
121 Q_OBJECT
122public:
123 //! Constructs a new property set object.
124 explicit KPropertySet(QObject *parent = nullptr);
125
126 /*! Constructs a deep copy of \a set.
127 The new object will not have a QObject parent even if \a set has such parent. */
128 explicit KPropertySet(const KPropertySet& set);
129
130 ~KPropertySet() override;
131
132 /*! @return the number of top-level properties in the set. */
133 int count() const;
134
135 /*! @return the number of top-level properties in the set
136 matching criteria defined by @a selector. */
137 int count(const KPropertySelector& selector) const;
138
139 /*! @return true if the set is empty, i.e. count() is 0; otherwise returns false. */
140 bool isEmpty() const;
141
142 /*! @return true if the set is contains visible properties. */
143 bool hasVisibleProperties() const;
144
145 /*! @return true if the set is contains properties
146 matching criteria defined by @a selector. */
147 bool hasProperties(const KPropertySelector& selector) const;
148
149 /*! \return true if the set is read-only when used in a property editor.
150 @c false by default.
151 In a read-only property set no property can be modified by the user regardless of read-only flag
152 of any property (KProperty::isReadOnly()). On the other hand if KProperty::isReadOnly() is @c true
153 and KPropertySet::isReadOnly() is @c false, the property is still read-only.
154 Read-only property set prevents editing in the property editor but it is still possible to change
155 value or other parameters of property programatically using KProperty::setValue(),
156 KProperty::resetValue(), etc. */
157 bool isReadOnly() const;
158
159 /*! \return true if the set contains property names \a name. */
160 bool contains(const QByteArray &name) const;
161
162 /*! \return property named with \a name. If no such property is found,
163 null property (KProperty()) is returned. */
164 KProperty& property(const QByteArray &name) const;
165
166 /*! Accesses a property by name.
167 A property reference is returned, so all property modifications are allowed.
168 If there is no such property, null property (KProperty()) is returned,
169 so it's good practice to use contains() if it's not known if the property exists.
170 For example to set a value of a property, use:
171 @code
172 KPropertySet set;
173 ...
174 if (!set.contains("myProperty")) {
175 dosomething;
176 }
177 set["myProperty"].setValue("My Value");
178 @endcode
179 @return \ref Property with given name.
180 @see changeProperty(const QByteArray &, const QVariant &)
181 @see changePropertyIfExists(const QByteArray &, const QVariant &)
182 */
183 KProperty& operator[](const QByteArray &name) const;
184
185 /*! @return value for property named with @a name.
186 If no such property is found, default value @a defaultValue is returned. */
187 QVariant propertyValue(const QByteArray &name, const QVariant& defaultValue = QVariant()) const;
188
189 /*! Creates a deep copy of \a set and assigns it to this property set. */
190 KPropertySet& operator= (const KPropertySet &set);
191
192 /*! \return the user-visible translated caption string for \a group that will
193 be shown in property editor to represent \a group. If there is no special
194 caption set for the group, \a group is just returned. */
195 QString groupCaption(const QByteArray &group) const;
196
197 /*! \return icon name for \a group. */
198 QString groupIconName(const QByteArray &group) const;
199
200 /**
201 * @return group name for property @a propertyName
202 * Empty value is returned if there is no such property.
203 * @since 3.1
204 */
205 QByteArray groupNameForProperty(const QByteArray &propertyName) const;
206
207 /**
208 * @overload QByteArray groupNameForProperty(const QByteArray &propertyName) const
209 * @since 3.1
210 */
211 QByteArray groupNameForProperty(const KProperty &property) const;
212
213 /*! \return a list of all group names. The order of items is undefined. */
214 QList<QByteArray> groupNames() const;
215
216 /*! \return a list of all property names for group @a group.
217 The order of items is undefined. */
218 QList<QByteArray> propertyNamesForGroup(const QByteArray &group) const;
219
220 /*! Used by property editor to preserve previous selection when this set
221 is assigned again. */
222 QByteArray previousSelection() const;
223
224 /*! Prints debug output for this set. */
225 void debug() const;
226
227 //! @return property values for this set
228 QMap<QByteArray, QVariant> propertyValues() const;
229
230 /**
231 * @brief Clears "modified" flag of all properties in this set, i.e. calls clearModifiedFlag() for each property.
232 * @since 3.1
233 * @see KProperty::clearModifiedFlag()
234 */
235 void clearModifiedFlags();
236
237 /**
238 * Returns @c true if at least one property in this set is modified, i.e. returns @c true for isModified()
239 * @since 3.1
240 * @see clearModifiedFlags() KProperty::isModified()
241 */
242 bool isModified() const;
243
244public Q_SLOTS:
245 /*! Adds the property to the set, in the group.
246 The property becomes owned by the set.
247 Any name can be used for the @a group. "common" is the default for a basic top-level group. */
248 void addProperty(KProperty *property, const QByteArray &group = "common");
249
250 /*! Removes property from the set and deletes the object.
251 Emits aboutToDeleteProperty before removing. */
252 void removeProperty(KProperty *property);
253
254 /*! Removes property with the given name from the set and deletes the object.
255 Emits aboutToDeleteProperty() before removing.*/
256 void removeProperty(const QByteArray &name);
257
258 /*! Removes all property objects from the property set and deletes them. */
259 void clear();
260
261 /*! Change the value of property whose key is \a property to \a value.
262 @see void changePropertyIfExists(const QByteArray &, const QVariant &) */
263 void changeProperty(const QByteArray &property, const QVariant &value);
264
265 /*! Change the value of property whose key is \a property to \a value
266 only if it exists in the set.
267 @see void changeProperty(const QByteArray &, const QVariant &) */
268 void changePropertyIfExists(const QByteArray &property, const QVariant &value);
269
270 /*! Sets @a caption as a user-visible translated string that will be shown in editor to represent
271 \a group. */
272 void setGroupCaption(const QByteArray &group, const QString &caption);
273
274 /*! Sets the icon name \a icon to be displayed for \a group. */
275 void setGroupIconName(const QByteArray &group, const QString& iconName);
276
277 //! Sets previous section.
278 //! @see previousSelection()
279 void setPreviousSelection(const QByteArray &prevSelection);
280
281 /*! Sets this set to be read-only.
282 @see isReadOnly */
283 void setReadOnly(bool readOnly);
284
285Q_SIGNALS:
286 /*! Emitted when the value of the property is changed.*/
288
289 /*! @internal Exists to be sure that we emitted it before propertyChanged(),
290 so editor object can handle this. */
292
293 /*! Emitted when the value of the property is reset.*/
294 void propertyReset(KPropertySet& set, KProperty& property);
295
296 /*! Emitted when property is about to be deleted.*/
298
299 /*! Emitted when property set object is about to be cleared (using clear()).
300 This signal is also emitted from destructor before emitting aboutToBeDeleted(). */
302
303 /*! Emitted when property set object is about to be deleted.*/
305
306 /*! Emitted when property set object's read-only flag has changed.*/
308
309protected:
310 /*! Constructs a set which owns or does not own it's properties.*/
311 explicit KPropertySet(bool propertyOwner);
312
313private:
314 KPropertySetPrivate * const d;
315 friend class KPropertySetPrivate;
316};
317
318//! qDebug() stream operator. Writes this set to the debug output in a nicely formatted way.
319KPROPERTYCORE_EXPORT QDebug operator<<(QDebug dbg, const KPropertySet &set);
320
321#endif
An interface for functor selecting properties.
virtual KPropertySelector * clone() const =0
Creates a deep copy of the selector.
virtual bool operator()(const KProperty &prop) const =0
An operator implementing the functor.
A class to iterate over a KPropertySet.
bool operator!=(const KPropertySetIterator &other) const
Order
Ordering options for properties.
Set of properties.
void aboutToDeleteProperty(KPropertySet &set, KProperty &property)
void aboutToBeCleared()
void readOnlyFlagChanged()
void propertyChangedInternal(KPropertySet &set, KProperty &property)
void propertyReset(KPropertySet &set, KProperty &property)
void aboutToBeDeleted()
void propertyChanged(KPropertySet &set, KProperty &property)
The base class representing a single property.
Definition KProperty.h:96
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:41:55 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.