Diffstat (limited to 'microkde/kdeui/kxmlguiclient.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | microkde/kdeui/kxmlguiclient.h | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/microkde/kdeui/kxmlguiclient.h b/microkde/kdeui/kxmlguiclient.h new file mode 100644 index 0000000..cd74c8e --- a/dev/null +++ b/microkde/kdeui/kxmlguiclient.h | |||
@@ -0,0 +1,361 @@ | |||
1 | /* This file is part of the KDE libraries | ||
2 | Copyright (C) 2000 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., 59 Temple Place - Suite 330, | ||
17 | Boston, MA 02111-1307, USA. | ||
18 | */ | ||
19 | #ifndef _KXMLGUICLIENT_H | ||
20 | #define _KXMLGUICLIENT_H | ||
21 | |||
22 | |||
23 | //US #include <qdom.h> | ||
24 | #include <qptrlist.h> | ||
25 | #include <qmap.h> | ||
26 | #include <qstringlist.h> | ||
27 | |||
28 | class QWidget; | ||
29 | class KAction; | ||
30 | class KActionCollection; | ||
31 | class KInstance; | ||
32 | |||
33 | class KXMLGUIClientPrivate; | ||
34 | class KXMLGUIFactory; | ||
35 | class KXMLGUIBuilder; | ||
36 | |||
37 | /** | ||
38 | * | ||
39 | * A KXMLGUIClient can be used with @ref KXMLGUIFactory to create a | ||
40 | * GUI from actions and an XML document, and can be dynamically merged | ||
41 | * with other KXMLGUIClients. | ||
42 | */ | ||
43 | class KXMLGUIClient | ||
44 | { | ||
45 | friend class KEditToolbarWidget; // for setXMLFile(3 args) | ||
46 | public: | ||
47 | /** | ||
48 | * Constructs a KXMLGUIClient which can be used with a | ||
49 | * @ref KXMLGUIFactory to create a GUI from actions and an XML document, and | ||
50 | * which can be dynamically merged with other KXMLGUIClients. | ||
51 | */ | ||
52 | KXMLGUIClient(); | ||
53 | |||
54 | /** | ||
55 | * Constructs a KXMLGUIClient which can be used with a @ref KXMLGUIFactory | ||
56 | * to create a GUI from actions and an XML document, | ||
57 | * and which can be dynamically merged with other KXMLGUIClients. | ||
58 | * | ||
59 | * This constructor takes an additional @p parent argument, which makes | ||
60 | * the client a child client of the parent. | ||
61 | * | ||
62 | * Child clients are automatically added to the GUI if the parent is added. | ||
63 | * | ||
64 | */ | ||
65 | KXMLGUIClient( KXMLGUIClient *parent ); | ||
66 | |||
67 | /** | ||
68 | * Destructs the KXMLGUIClient. | ||
69 | */ | ||
70 | virtual ~KXMLGUIClient(); | ||
71 | |||
72 | /** | ||
73 | * Retrieves an action of the client by name. If not found, it looks in its child clients. | ||
74 | * This method is provided for convenience, as it uses @ref #actionCollection() | ||
75 | * to get the action object. | ||
76 | */ | ||
77 | KAction* action( const char* name ) const; | ||
78 | |||
79 | /** | ||
80 | * Retrieves an action for a given @ref QDomElement. The default | ||
81 | * implementation uses the "name" attribute to query the action | ||
82 | * object via the other action() method. | ||
83 | */ | ||
84 | //US virtual KAction *action( const QDomElement &element ) const; | ||
85 | |||
86 | /** | ||
87 | * Retrieves the entire action collection for the GUI client | ||
88 | */ | ||
89 | virtual KActionCollection* actionCollection() const; | ||
90 | |||
91 | /** | ||
92 | * @return The instance (@ref KInstance) for this part. | ||
93 | */ | ||
94 | //US virtual KInstance *instance() const; | ||
95 | |||
96 | /** | ||
97 | * @return The parsed XML in a @ref QDomDocument, set by @ref | ||
98 | * setXMLFile() or @ref setXML(). | ||
99 | * This document describes the layout of the GUI. | ||
100 | */ | ||
101 | //US virtual QDomDocument domDocument() const; | ||
102 | |||
103 | /** | ||
104 | * This will return the name of the XML file as set by @ref #setXMLFile(). | ||
105 | * If @ref #setXML() is used directly, then this will return NULL. | ||
106 | * | ||
107 | * The filename that this returns is obvious for components as each | ||
108 | * component has exactly one XML file. In non-components, however, | ||
109 | * there are usually two: the global file and the local file. This | ||
110 | * function doesn't really care about that, though. It will always | ||
111 | * return the last XML file set. This, in almost all cases, will | ||
112 | * be the local XML file. | ||
113 | * | ||
114 | * @return The name of the XML file or QString::null | ||
115 | */ | ||
116 | //US virtual QString xmlFile() const; | ||
117 | |||
118 | //US virtual QString localXMLFile() const; | ||
119 | |||
120 | /** | ||
121 | * @internal | ||
122 | */ | ||
123 | //US void setXMLGUIBuildDocument( const QDomDocument &doc ); | ||
124 | /** | ||
125 | * @internal | ||
126 | */ | ||
127 | //US QDomDocument xmlguiBuildDocument() const; | ||
128 | |||
129 | /** | ||
130 | * This method is called by the @ref KXMLGUIFactory as soon as the client | ||
131 | * is added to the KXMLGUIFactory's GUI. | ||
132 | */ | ||
133 | //US void setFactory( KXMLGUIFactory *factory ); | ||
134 | /** | ||
135 | * Retrieves a pointer to the @ref KXMLGUIFactory this client is | ||
136 | * associated with (will return 0L if the client's GUI has not been built | ||
137 | * by a KXMLGUIFactory. | ||
138 | */ | ||
139 | //US KXMLGUIFactory *factory() const; | ||
140 | |||
141 | /** | ||
142 | * KXMLGUIClients can form a simple child/parent object tree. This | ||
143 | * method returns a pointer to the parent client or 0L if it has no | ||
144 | * parent client assigned. | ||
145 | */ | ||
146 | KXMLGUIClient *parentClient() const; | ||
147 | |||
148 | /** | ||
149 | * Use this method to make a client a child client of another client. | ||
150 | * Usually you don't need to call this method, as it is called | ||
151 | * automatically when using the second constructor, which takes a | ||
152 | * arent argument. | ||
153 | */ | ||
154 | void insertChildClient( KXMLGUIClient *child ); | ||
155 | |||
156 | /** | ||
157 | * Removes the given @p child from the client's children list. | ||
158 | */ | ||
159 | void removeChildClient( KXMLGUIClient *child ); | ||
160 | |||
161 | /** | ||
162 | * Retrieves a list of all child clients. | ||
163 | */ | ||
164 | const QPtrList<KXMLGUIClient> *childClients(); | ||
165 | |||
166 | /** | ||
167 | * A client can have an own @ref KXMLGUIBuilder. | ||
168 | * Use this method to assign your builder instance to the client (so that the | ||
169 | * @ref KXMLGUIFactory can use it when building the client's GUI) | ||
170 | * | ||
171 | * Client specific guibuilders are useful if you want to create | ||
172 | * custom container widgets for your GUI. | ||
173 | */ | ||
174 | //US void setClientBuilder( KXMLGUIBuilder *builder ); | ||
175 | |||
176 | /** | ||
177 | * Retrieves the client's GUI builder or 0L if no client specific | ||
178 | * builder has been assigned via @ref #setClientBuilder() | ||
179 | */ | ||
180 | //US KXMLGUIBuilder *clientBuilder() const; | ||
181 | |||
182 | /** | ||
183 | * Forces this client to re-read its XML resource file. This is | ||
184 | * intended to be used when you know that the resource file has | ||
185 | * changed and you will soon be rebuilding the GUI. It has no | ||
186 | * useful effect with non-KParts GUIs, so don't bother using it | ||
187 | * unless your app is component based. | ||
188 | */ | ||
189 | //US void reloadXML(); | ||
190 | |||
191 | /** | ||
192 | * ActionLists are a way for XMLGUI to support dynamic lists of | ||
193 | * actions. E.g. if you are writing a file manager, and there is a | ||
194 | * menu file whose contents depend on the mimetype of the file that | ||
195 | * is selected, then you can achieve this using ActionLists. It | ||
196 | * works as follows: | ||
197 | * In your xxxui.rc file ( the one that you set in @ref setXMLFile() | ||
198 | * ), you put an <ActionList name="xxx"> tag. E.g. | ||
199 | * \verbatim | ||
200 | * <kpartgui name="xxx_part" version="1"> | ||
201 | * <MenuBar> | ||
202 | * <Menu name="file"> | ||
203 | * ... <!-- some useful actions--> | ||
204 | * <ActionList name="xxx_file_actionlist" /> | ||
205 | * ... <!-- even more useful actions--> | ||
206 | * </Menu> | ||
207 | * ... | ||
208 | * </MenuBar> | ||
209 | * </kpartgui> | ||
210 | * \endverbatim | ||
211 | * | ||
212 | * This tag will get expanded to a list of actions. In the example | ||
213 | * above ( a file manager with a dynamic file menu ), you would call | ||
214 | * \code | ||
215 | * QPtrList<KAction> file_actions; | ||
216 | * for( ... ) | ||
217 | * if( ... ) | ||
218 | * file_actions.append( cool_action ); | ||
219 | * unplugActionList( "xxx_file_actionlist" ); | ||
220 | * plugActionList( "xxx_file_actionlist", file_actions ); | ||
221 | * \endcode | ||
222 | * every time a file is selected, unselected or ... | ||
223 | * | ||
224 | * \note You should not call createGUI() after calling this | ||
225 | * function. In fact, that would remove the newly added | ||
226 | * actionlists again... | ||
227 | * \note Forgetting to call unplugActionList() before | ||
228 | * plugActionList() would leave the previous actions in the | ||
229 | * menu too.. | ||
230 | */ | ||
231 | void plugActionList( const QString &name, const QPtrList<KAction> &actionList ); | ||
232 | |||
233 | /** | ||
234 | * The complement of \ref plugActionList() ... | ||
235 | */ | ||
236 | void unplugActionList( const QString &name ); | ||
237 | |||
238 | //US static QString findMostRecentXMLFile( const QStringList &files, QString &doc ); | ||
239 | |||
240 | void addStateActionEnabled(const QString& state, const QString& action); | ||
241 | |||
242 | void addStateActionDisabled(const QString& state, const QString& action); | ||
243 | |||
244 | enum ReverseStateChange { StateNoReverse, StateReverse }; | ||
245 | struct StateChange | ||
246 | { | ||
247 | QStringList actionsToEnable; | ||
248 | QStringList actionsToDisable; | ||
249 | }; | ||
250 | |||
251 | StateChange getActionsToChangeForState(const QString& state); | ||
252 | |||
253 | /// @since 3.1 | ||
254 | //US void beginXMLPlug( QWidget * ); | ||
255 | /// @since 3.1 | ||
256 | //US void endXMLPlug(); | ||
257 | /// @since 3.1 | ||
258 | //US void prepareXMLUnplug( QWidget * ); | ||
259 | |||
260 | protected: | ||
261 | /** | ||
262 | * Returns true if client was added to super client list. | ||
263 | * Returns false if client was already in list. | ||
264 | */ | ||
265 | //bool addSuperClient( KXMLGUIClient * ); | ||
266 | |||
267 | /** | ||
268 | * Sets the instance (@ref KInstance) for this part. | ||
269 | * | ||
270 | * Call this first in the inherited class constructor. | ||
271 | * (At least before @ref setXMLFile().) | ||
272 | */ | ||
273 | //US virtual void setInstance( KInstance *instance ); | ||
274 | |||
275 | /** | ||
276 | * Sets the name of the rc file containing the XML for the part. | ||
277 | * | ||
278 | * Call this in the Part-inherited class constructor. | ||
279 | * | ||
280 | * @param file Either an absolute path for the file, or simply the | ||
281 | * filename, which will then be assumed to be installed | ||
282 | * in the "data" resource, under a directory named like | ||
283 | * the instance. | ||
284 | * @param setXML Specify whether to call setXML. Default is true. | ||
285 | * and the DOM document at once. | ||
286 | **/ | ||
287 | //US virtual void setXMLFile( const QString& file, bool merge = false, bool setXMLDoc = true ); | ||
288 | |||
289 | //US virtual void setLocalXMLFile( const QString &file ); | ||
290 | |||
291 | /** | ||
292 | * Sets the XML for the part. | ||
293 | * | ||
294 | * Call this in the Part-inherited class constructor if you | ||
295 | * don't call @ref setXMLFile(). | ||
296 | **/ | ||
297 | //US virtual void setXML( const QString &document, bool merge = false ); | ||
298 | |||
299 | /** | ||
300 | * Sets the Document for the part, describing the layout of the GUI. | ||
301 | * | ||
302 | * Call this in the Part-inherited class constructor if you don't call | ||
303 | * @ref setXMLFile or @ref setXML . | ||
304 | */ | ||
305 | //US virtual void setDOMDocument( const QDomDocument &document, bool merge = false ); | ||
306 | |||
307 | /** | ||
308 | * This function will attempt to give up some memory after the GUI | ||
309 | * is built. It should never be used in apps where the GUI may be | ||
310 | * rebuilt at some later time (components, for instance). | ||
311 | */ | ||
312 | //US virtual void conserveMemory(); | ||
313 | |||
314 | /** | ||
315 | * Actions can collectively be assigned a "State". To accomplish this | ||
316 | * the respective actions are tagged as <enable> or <disable> in | ||
317 | * a <State> </State> group of the XMLfile. During program execution the | ||
318 | * programmer can call stateChanged() to set actions to a defined state. | ||
319 | * | ||
320 | * @param newstate Name of a State in the XMLfile. | ||
321 | * @param reverse If the flag reverse is set to StateReverse, the State is reversed. | ||
322 | * (actions to be enabled will be disabled and action to be disabled will be enabled) | ||
323 | * Default is reverse=false. | ||
324 | */ | ||
325 | virtual void stateChanged(const QString &newstate, ReverseStateChange reverse = StateNoReverse); | ||
326 | |||
327 | // Use this one for KDE 4.0 | ||
328 | //virtual void stateChanged(const QString &newstate, bool reverse = false); | ||
329 | |||
330 | private: | ||
331 | /*US | ||
332 | struct DocStruct | ||
333 | { | ||
334 | QString file; | ||
335 | QString data; | ||
336 | }; | ||
337 | |||
338 | bool mergeXML( QDomElement &base, const QDomElement &additive, | ||
339 | KActionCollection *actionCollection ); | ||
340 | |||
341 | QDomElement findMatchingElement( const QDomElement &base, | ||
342 | const QDomElement &additive ); | ||
343 | */ | ||
344 | typedef QMap<QString, QMap<QString, QString> > ActionPropertiesMap; | ||
345 | |||
346 | //US static ActionPropertiesMap extractActionProperties( const QDomDocument &doc ); | ||
347 | |||
348 | //US static void storeActionProperties( QDomDocument &doc, const ActionPropertiesMap &properties ); | ||
349 | |||
350 | //US static QString findVersionNumber( const QString &_xml ); | ||
351 | |||
352 | // Actions to enable/disable on a state change | ||
353 | QMap<QString,StateChange> m_actionsStateMap; | ||
354 | |||
355 | protected: | ||
356 | virtual void virtual_hook( int id, void* data ); | ||
357 | private: | ||
358 | KXMLGUIClientPrivate *d; | ||
359 | }; | ||
360 | |||
361 | #endif | ||