Kross

actioncollection.h
1 /***************************************************************************
2  * actioncollection.h
3  * This file is part of the KDE project
4  * copyright (C)2004-2007 by Sebastian Sauer ([email protected])
5  *
6  * This program 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  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Library General Public License for more details.
14  * You should have received a copy of the GNU Library General Public License
15  * along with this program; see the file COPYING. 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 KROSS_ACTIONCOLLECTION_H
21 #define KROSS_ACTIONCOLLECTION_H
22 
23 #include "krossconfig.h"
24 #include "action.h"
25 
26 #include <QObject>
27 #include <QDir>
28 
29 class QDomElement;
30 class QIODevice;
31 
32 namespace Kross
33 {
34 
35 /**
36  * The ActionCollection class manages collections of \a Action instances.
37  * An ActionCollection can have both actions and other collections as children.
38  * Child actions can be accessed using actions() which returns a list of Action pointers.
39  * Child collections can be accessed using collections() which returns a list of collection names.
40  * The collection can then be accessed with collection(name).
41  * To add a child action, call addAction(), and to remove an action: removeAction().
42  * To add a child collection, call setParentCollection(parent) in the collection you want to add to parent.
43  * To remove a collection call setParentCollection(0).
44  * NOTE: Do not use setParent().
45  */
46 class KROSSCORE_EXPORT ActionCollection : public QObject
47 {
48  Q_OBJECT
49 
50 public:
51 
52  /**
53  * Constructor.
54  *
55  * \param name The objectName the ActionCollection has.
56  * \param parent The parent ActionCollection this
57  * ActionCollection will be child of. If parent is not
58  * NULL, this \a ActionCollection instance will register
59  * itself as child of the parent \p parent by using the
60  * \a setParentCollection method.
61  */
62  explicit ActionCollection(const QString &name, ActionCollection *parent = nullptr);
63 
64  /**
65  * Destructor.
66  */
67  ~ActionCollection() override;
68 
69  /**
70  * \return the objectName for this ActionCollection.
71  */
72  QString name() const;
73 
74  /**
75  * \return the display text
76  */
77  QString text() const;
78 
79  /**
80  * Set the display text to \p text .
81  */
82  void setText(const QString &text);
83 
84  /**
85  * \return the optional description for this ActionCollection.
86  */
87  QString description() const;
88 
89  /**
90  * Set the optional description for this ActionCollection.
91  */
92  void setDescription(const QString &description);
93 
94  /**
95  * \return the name of the icon.
96  */
97  QString iconName() const;
98 
99  /**
100  * Set the name of the icon to \p iconname .
101  */
102  void setIconName(const QString &iconname);
103 
104  /**
105  * \return the icon defined with \p setIconName() .
106  */
107  QIcon icon() const;
108 
109  /**
110  * Return the enable this ActionCollection has.
111  */
112  bool isEnabled() const;
113 
114  /**
115  * Enable or disable this ActionCollection.
116  */
117  void setEnabled(bool enabled);
118 
119  /**
120  * \return the parent \a ActionCollection instance this
121  * \collection is child of or NULL if this collection
122  * does not have a parent.
123  */
124  ActionCollection *parentCollection() const;
125  /// Set the parent to @p parent. NOTE: Do not use setParent().
126  void setParentCollection(ActionCollection *parent);
127  /**
128  * \return true if this collection has a child \a ActionCollection
129  * instance which objectName is \p name .
130  */
131  bool hasCollection(const QString &name) const;
132 
133  /**
134  * \return the \a ActionCollection instance which objectName is
135  * \p name or NULL if there exists no such \a ActionCollection .
136  */
137  ActionCollection *collection(const QString &name) const;
138 
139  /**
140  * \return a list of names of child \a ActionCollection instances
141  * this collection has
142  */
143  QStringList collections() const;
144 
145  QList<Action *> actions() const;
146 
147  /**
148  * \return action with given name or 0 if it wasn't found
149  */
150  Action *action(const QString &name) const;
151  void addAction(Action *action);
152  void addAction(const QString &name, Action *action);
153  void removeAction(const QString &name);
154  void removeAction(Action *action);
155 
156  /**
157  * Load child \a Action and \a ActionCollection instances this
158  * collection has from the \p element .
159  *
160  * \param element The QDomElement that contains the XML.
161  * \param directory The current directory used for relative paths
162  * defined within a script-tag for the file-attribute. If the
163  * directory is QDir() relative paths are not resolved.
164  * \return true on success else false.
165  */
166  bool readXml(const QDomElement &element, const QDir &directory = QDir());
167  bool readXml(const QDomElement &element, const QStringList &searchPath/* = QStringList()*/);
168 
169  /**
170  * Read XML from the QIODevice \p device .
171  */
172  bool readXml(QIODevice *device, const QDir &directory = QDir());
173  bool readXml(QIODevice *device, const QStringList &searchPath/* = QStringList()*/);
174 
175  /**
176  * Read the XML from the file \p file .
177  *
178  * \param file The existing XML file that should be read.
179  * \return true if reading was successful else false.
180  */
181  bool readXmlFile(const QString &file);
182 
183  /**
184  * \return a QDomElement that represents the child \a Action
185  * and \a ActionCollection instances this collection has.
186  */
187  QDomElement writeXml();
188  QDomElement writeXml(const QStringList &searchPath/* = QStringList()*/);
189 
190  /**
191  * Write XML to the QIODevice \p device and use a space-idention
192  * of \p indent for the XML.
193  */
194  bool writeXml(QIODevice *device, int indent = 2);
195  bool writeXml(QIODevice *device, int indent/* = 2*/, const QStringList &searchPath/* = QStringList()*/);
196 
197 Q_SIGNALS:
198 
199  /**
200  * This signal is emitted if the content of the ActionCollection
201  * was changed.
202  */
203  void updated();
204 
205  /// This signal is emitted when the data of a child action is changed
206  void dataChanged(Action *);
207  /// This signal is emitted when the data of the ActionCollection is changed
208  void dataChanged(ActionCollection *);
209 
210  /// This signal is emitted just before @p child is added to @p parent
211  void collectionToBeInserted(ActionCollection *child, ActionCollection *parent);
212  /// This signal is emitted after @p child has been added to @p parent
213  void collectionInserted(ActionCollection *child, ActionCollection *parent);
214  /// This signal is emitted before @p child is removed from @p parent
215  void collectionToBeRemoved(ActionCollection *child, ActionCollection *parent);
216  /// This signal is emitted after @p child has been removed from @p parent
217  void collectionRemoved(ActionCollection *child, ActionCollection *parent);
218 
219  /// This signal is emitted just before @p child is added to @p parent
220  void actionToBeInserted(Action *child, ActionCollection *parent);
221  /// This signal is emitted after @p child has been added to @p parent
222  void actionInserted(Action *child, ActionCollection *parent);
223  /// This signal is emitted before @p child is removed from @p parent
224  void actionToBeRemoved(Action *child, ActionCollection *parent);
225  /// This signal is emitted after @p child has been removed from @p parent
226  void actionRemoved(Action *child, ActionCollection *parent);
227 
228 protected:
229  void registerCollection(ActionCollection *collection);
230  void unregisterCollection(const QString &name);
231  void connectSignals(ActionCollection *collection, bool conn);
232  void connectSignals(Action *collection, bool conn);
233 
234 private Q_SLOTS:
235  void emitUpdated();
236 
237 private:
238  /// \internal d-pointer class.
239  class Private;
240  /// \internal d-pointer instance.
241  Private *const d;
242 };
243 
244 }
245 
246 #endif
247 
Definition: action.cpp:36
const QLatin1String name
The Action class is an abstract container to deal with scripts like a single standalone script file...
Definition: action.h:95
The ActionCollection class manages collections of Action instances.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Dec 6 2021 22:51:18 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.