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
28class QAction;
29class KXMLGUIFactoryPrivate;
30class KXMLGUIClient;
31class KXMLGUIBuilder;
32class KComponentData;
33
34class QDomAttr;
35class QDomDocument;
36class QDomElement;
37class QDomNode;
38class QDomNamedNodeMap;
39
40namespace KXMLGUI
41{
42struct MergingIndex;
43struct ContainerNode;
44struct ContainerClient;
45class 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 */
65class 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
202Q_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
218private:
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