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