KProperty

KPropertySet.h
1 /* This file is part of the KDE project
2  Copyright (C) 2004 Cedric Pasteur <[email protected]>
3  Copyright (C) 2004 Alexander Dymo <[email protected]>
4  Copyright (C) 2004-2017 Jarosław Staniek <[email protected]>
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 
31 class KPropertySetPrivate;
32 
33 //! An interface for functor selecting properties.
34 /*! Used in Iterator. */
35 class KPROPERTYCORE_EXPORT KPropertySelector
36 {
37 public:
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 */
57 class KPROPERTYCORE_EXPORT KPropertySetIterator
58 {
59 public:
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 
112 private:
113  class Private;
114  Private * const d;
115 };
116 
117 /*! \brief Set of properties
118  */
119 class KPROPERTYCORE_EXPORT KPropertySet : public QObject
120 {
121  Q_OBJECT
122 public:
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 
244 public 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 
285 Q_SIGNALS:
286  /*! Emitted when the value of the property is changed.*/
287  void propertyChanged(KPropertySet& set, KProperty& property);
288 
289  /*! @internal Exists to be sure that we emitted it before propertyChanged(),
290  so editor object can handle this. */
291  void propertyChangedInternal(KPropertySet& set, KProperty& property);
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.*/
297  void aboutToDeleteProperty(KPropertySet& set, KProperty& property);
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(). */
301  void aboutToBeCleared();
302 
303  /*! Emitted when property set object is about to be deleted.*/
304  void aboutToBeDeleted();
305 
306  /*! Emitted when property set object's read-only flag has changed.*/
307  void readOnlyFlagChanged();
308 
309 protected:
310  /*! Constructs a set which owns or does not own it's properties.*/
311  explicit KPropertySet(bool propertyOwner);
312 
313 private:
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.
319 KPROPERTYCORE_EXPORT QDebug operator<<(QDebug dbg, const KPropertySet &set);
320 
321 #endif
A class to iterate over a KPropertySet.
Definition: KPropertySet.h:57
Order
Ordering options for properties.
Definition: KPropertySet.h:92
bool operator!=(const KPropertySetIterator &other) const
Definition: KPropertySet.h:88
An interface for functor selecting properties.
Definition: KPropertySet.h:35
Set of properties.
Definition: KPropertySet.h:119
The base class representing a single property.
Definition: KProperty.h:95
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Apr 14 2021 23:03:03 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.