1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999 Simon Hausmann <hausmann@kde.org> |
3 | Copyright (C) 2000 Kurt Granroth <granroth@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
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 kxmlguifactory_h |
21 | #define kxmlguifactory_h |
22 | |
23 | #include <kdeui_export.h> |
24 | #include <kcomponentdata.h> |
25 | |
26 | #include <QtCore/QObject> |
27 | |
28 | class QAction; |
29 | class KXMLGUIFactoryPrivate; |
30 | class KXMLGUIClient; |
31 | class KXMLGUIBuilder; |
32 | class KComponentData; |
33 | |
34 | class QDomAttr; |
35 | class QDomDocument; |
36 | class QDomElement; |
37 | class QDomNode; |
38 | class QDomNamedNodeMap; |
39 | |
40 | namespace KXMLGUI |
41 | { |
42 | struct MergingIndex; |
43 | struct ContainerNode; |
44 | struct ContainerClient; |
45 | class BuildHelper; |
46 | } |
47 | |
48 | /** |
49 | * KXMLGUIFactory, together with KXMLGUIClient objects, can be used to create |
50 | * a GUI of container widgets (like menus, toolbars, etc.) and container items |
51 | * (menu items, toolbar buttons, etc.) from an XML document and action objects. |
52 | * |
53 | * Each KXMLGUIClient represents a part of the GUI, composed from containers and |
54 | * actions. KXMLGUIFactory takes care of building (with the help of a KXMLGUIBuilder) |
55 | * and merging the GUI from an unlimited number of clients. |
56 | * |
57 | * Each client provides XML through a QDomDocument and actions through a |
58 | * KActionCollection . The XML document contains the rules for how to merge the |
59 | * GUI. |
60 | * |
61 | * KXMLGUIFactory processes the DOM tree provided by a client and plugs in the client's actions, |
62 | * according to the XML and the merging rules of previously inserted clients. Container widgets |
63 | * are built via a KXMLGUIBuilder , which has to be provided with the KXMLGUIFactory constructor. |
64 | */ |
65 | class KDEUI_EXPORT KXMLGUIFactory : public QObject |
66 | { |
67 | friend class KXMLGUI::BuildHelper; |
68 | Q_OBJECT |
69 | public: |
70 | /** |
71 | * Constructs a KXMLGUIFactory. The provided @p builder KXMLGUIBuilder will be called |
72 | * for creating and removing container widgets, when clients are added/removed from the GUI. |
73 | * |
74 | * Note that the ownership of the given KXMLGUIBuilder object won't be transferred to this |
75 | * KXMLGUIFactory, so you have to take care of deleting it properly. |
76 | */ |
77 | explicit KXMLGUIFactory( KXMLGUIBuilder *builder, QObject *parent = 0 ); |
78 | |
79 | /** |
80 | * Destructor |
81 | */ |
82 | ~KXMLGUIFactory(); |
83 | |
84 | // XXX move to somewhere else? (Simon) |
85 | /// @internal |
86 | static QString readConfigFile(const QString &filename, |
87 | const KComponentData &componentData = KComponentData()); |
88 | /// @internal |
89 | static bool saveConfigFile(const QDomDocument& doc, const QString& filename, |
90 | const KComponentData &componentData = KComponentData()); |
91 | |
92 | /** |
93 | * @internal |
94 | * Find or create the ActionProperties element, used when saving custom action properties |
95 | */ |
96 | static QDomElement actionPropertiesElement( QDomDocument& doc ); |
97 | |
98 | /** |
99 | * @internal |
100 | * Find or create the element for a given action, by name. |
101 | * Used when saving custom action properties |
102 | */ |
103 | static QDomElement findActionByName( QDomElement& elem, const QString& sName, bool create ); |
104 | |
105 | /** |
106 | * Creates the GUI described by the QDomDocument of the client, |
107 | * using the client's actions, and merges it with the previously |
108 | * created GUI. |
109 | * This also means that the order in which clients are added to the factory |
110 | * is relevant; assuming that your application supports plugins, you should |
111 | * first add your application to the factory and then the plugin, so that the |
112 | * plugin's UI is merged into the UI of your application, and not the other |
113 | * way round. |
114 | */ |
115 | void addClient( KXMLGUIClient *client ); |
116 | |
117 | /** |
118 | * Removes the GUI described by the client, by unplugging all |
119 | * provided actions and removing all owned containers (and storing |
120 | * container state information in the given client) |
121 | */ |
122 | void removeClient( KXMLGUIClient *client ); |
123 | |
124 | void plugActionList( KXMLGUIClient *client, const QString &name, const QList<QAction*> &actionList ); |
125 | void unplugActionList( KXMLGUIClient *client, const QString &name ); |
126 | |
127 | /** |
128 | * Returns a list of all clients currently added to this factory |
129 | */ |
130 | QList<KXMLGUIClient*> clients() const; |
131 | |
132 | /** |
133 | * Use this method to get access to a container widget with the name specified with @p containerName |
134 | * and which is owned by the @p client. The container name is specified with a "name" attribute in the |
135 | * XML document. |
136 | * |
137 | * This function is particularly useful for getting hold of a popupmenu defined in an XMLUI file. |
138 | * For instance: |
139 | * \code |
140 | * QMenu *popup = static_cast<QMenu*>(guiFactory()->container("my_popup",this)); |
141 | * \endcode |
142 | * where @p "my_popup" is the name of the menu in the XMLUI file, and |
143 | * @p "this" is XMLGUIClient which owns the popupmenu (e.g. the mainwindow, or the part, or the plugin...) |
144 | * |
145 | * @param containerName Name of the container widget |
146 | * @param client Owner of the container widget |
147 | * @param useTagName Specifies whether to compare the specified name with the name attribute or |
148 | * the tag name. |
149 | * |
150 | * This method may return 0 if no container with the given name exists or is not owned by the client. |
151 | */ |
152 | QWidget *container( const QString &containerName, KXMLGUIClient *client, bool useTagName = false ); |
153 | |
154 | QList<QWidget*> containers( const QString &tagName ); |
155 | |
156 | /** |
157 | * Use this method to free all memory allocated by the KXMLGUIFactory. This deletes the internal node |
158 | * tree and therefore resets the internal state of the class. Please note that the actual GUI is |
159 | * NOT touched at all, meaning no containers are deleted nor any actions unplugged. That is |
160 | * something you have to do on your own. So use this method only if you know what you are doing :-) |
161 | * |
162 | * (also note that this will call KXMLGUIClient::setFactory( 0 ) for all inserted clients) |
163 | */ |
164 | void reset(); |
165 | |
166 | /** |
167 | * Use this method to free all memory allocated by the KXMLGUIFactory for a specific container, |
168 | * including all child containers and actions. This deletes the internal node subtree for the |
169 | * specified container. The actual GUI is not touched, no containers are deleted or any actions |
170 | * unplugged. Use this method only if you know what you are doing :-) |
171 | * |
172 | * (also note that this will call KXMLGUIClient::setFactory( 0 ) for all clients of the |
173 | * container) |
174 | */ |
175 | void resetContainer( const QString &containerName, bool useTagName = false ); |
176 | |
177 | /** |
178 | * Use this method to reset and reread action properties (shortcuts, etc.) for all actions. |
179 | * This is needed, for example, when you change shortcuts scheme at runtime. |
180 | */ |
181 | void refreshActionProperties(); |
182 | |
183 | public Q_SLOTS: |
184 | /** |
185 | * Show a standard configure shortcut for every action in this factory. |
186 | * |
187 | * This slot can be connected directly to the action to configure shortcuts. This is very simple to |
188 | * do that by adding a single line |
189 | * \code |
190 | * KStandardAction::keyBindings( guiFactory(), SLOT( configureShortcuts() ), actionCollection() ); |
191 | * \endcode |
192 | * |
193 | * @param bAllowLetterShortcuts Set to false if unmodified alphanumeric |
194 | * keys ('A', '1', etc.) are not permissible shortcuts. |
195 | * @param bSaveSettings if true, the settings will also be saved back to |
196 | * the *uirc file which they were intially read from. |
197 | */ |
198 | int configureShortcuts(bool bAllowLetterShortcuts = true, bool bSaveSettings = true); |
199 | |
200 | void changeShortcutScheme(const QString &scheme); |
201 | |
202 | Q_SIGNALS: |
203 | void clientAdded( KXMLGUIClient *client ); |
204 | void clientRemoved( KXMLGUIClient *client ); |
205 | |
206 | /** |
207 | * Emitted when the factory is currently making changes to the GUI, |
208 | * i.e. adding or removing clients. |
209 | * makingChanges(true) is emitted before any change happens, and |
210 | * makingChanges(false) is emitted after the change is done. |
211 | * This allows e.g. KMainWindow to know that the GUI is |
212 | * being changed programmatically and not by the user (so there is no reason to |
213 | * save toolbar settings afterwards). |
214 | * @since 4.1.3 |
215 | */ |
216 | void makingChanges(bool); |
217 | |
218 | private: |
219 | friend class KXMLGUIClient; |
220 | /// Internal, called by KXMLGUIClient destructor |
221 | void forgetClient(KXMLGUIClient *client); |
222 | |
223 | KXMLGUIFactoryPrivate *const d; |
224 | }; |
225 | |
226 | #endif |
227 | /* vim: et sw=4 |
228 | */ |
229 | |