KDEUI
KXMLGUIClient Class Reference
A KXMLGUIClient can be used with KXMLGUIFactory to create a GUI from actions and an XML document, and can be dynamically merged with other KXMLGUIClients. More...
#include <kxmlguiclient.h>

Classes | |
struct | StateChange |
Public Types | |
enum | ReverseStateChange { StateNoReverse, StateReverse } |
Public Member Functions | |
virtual QAction * | action (const QDomElement &element) const |
QAction * | action (const char *name) const |
virtual KActionCollection * | actionCollection () const |
void | addStateActionDisabled (const QString &state, const QString &action) |
void | addStateActionEnabled (const QString &state, const QString &action) |
void | beginXMLPlug (QWidget *) |
QList< KXMLGUIClient * > | childClients () |
KXMLGUIBuilder * | clientBuilder () const |
virtual KComponentData | componentData () const |
virtual QDomDocument | domDocument () const |
void | endXMLPlug () |
KXMLGUIFactory * | factory () const |
StateChange | getActionsToChangeForState (const QString &state) |
void | insertChildClient (KXMLGUIClient *child) |
KXMLGUIClient (KXMLGUIClient *parent) | |
KXMLGUIClient () | |
virtual QString | localXMLFile () const |
KXMLGUIClient * | parentClient () const |
void | plugActionList (const QString &name, const QList< QAction * > &actionList) |
void | prepareXMLUnplug (QWidget *) |
void | reloadXML () |
void | removeChildClient (KXMLGUIClient *child) |
void | setClientBuilder (KXMLGUIBuilder *builder) |
void | setFactory (KXMLGUIFactory *factory) |
void | setXMLGUIBuildDocument (const QDomDocument &doc) |
void | unplugActionList (const QString &name) |
virtual QString | xmlFile () const |
QDomDocument | xmlguiBuildDocument () const |
virtual | ~KXMLGUIClient () |
Static Public Member Functions | |
static QString | findMostRecentXMLFile (const QStringList &files, QString &doc) |
Protected Member Functions | |
virtual void | setComponentData (const KComponentData &componentData) |
virtual void | setDOMDocument (const QDomDocument &document, bool merge=false) |
virtual void | setLocalXMLFile (const QString &file) |
virtual void | setXML (const QString &document, bool merge=false) |
virtual void | setXMLFile (const QString &file, bool merge=false, bool setXMLDoc=true) |
virtual void | stateChanged (const QString &newstate, ReverseStateChange reverse=StateNoReverse) |
virtual void | virtual_hook (int id, void *data) |
Detailed Description
A KXMLGUIClient can be used with KXMLGUIFactory to create a GUI from actions and an XML document, and can be dynamically merged with other KXMLGUIClients.
Definition at line 46 of file kxmlguiclient.h.
Member Enumeration Documentation
Definition at line 260 of file kxmlguiclient.h.
Constructor & Destructor Documentation
KXMLGUIClient::KXMLGUIClient | ( | ) |
Constructs a KXMLGUIClient which can be used with a KXMLGUIFactory to create a GUI from actions and an XML document, and which can be dynamically merged with other KXMLGUIClients.
Definition at line 80 of file kxmlguiclient.cpp.
KXMLGUIClient::KXMLGUIClient | ( | KXMLGUIClient * | parent | ) | [explicit] |
Constructs a KXMLGUIClient which can be used with a KXMLGUIFactory to create a GUI from actions and an XML document, and which can be dynamically merged with other KXMLGUIClients.
This constructor takes an additional parent
argument, which makes the client a child client of the parent.
Child clients are automatically added to the GUI if the parent is added.
Definition at line 85 of file kxmlguiclient.cpp.
KXMLGUIClient::~KXMLGUIClient | ( | ) | [virtual] |
Destructs the KXMLGUIClient.
If the client was in a factory, the factory is NOT informed about the client being removed. This is a feature, it makes window destruction fast (the xmlgui is not updated for every client being deleted), but if you want to simply remove one client and to keep using the window, make sure to call factory->removeClient(client) before deleting the client.
Definition at line 91 of file kxmlguiclient.cpp.
Member Function Documentation
QAction * KXMLGUIClient::action | ( | const QDomElement & | element | ) | const [virtual] |
Retrieves an action for a given QDomElement.
The default implementation uses the "name" attribute to query the action object via the other action() method.
Definition at line 128 of file kxmlguiclient.cpp.
QAction * KXMLGUIClient::action | ( | const char * | name | ) | const |
Retrieves an action of the client by name.
If not found, it looks in its child clients. This method is provided for convenience, as it uses actionCollection() to get the action object.
Definition at line 105 of file kxmlguiclient.cpp.
KActionCollection * KXMLGUIClient::actionCollection | ( | ) | const [virtual] |
Retrieves the entire action collection for the GUI client.
Definition at line 118 of file kxmlguiclient.cpp.
Definition at line 653 of file kxmlguiclient.cpp.
Definition at line 641 of file kxmlguiclient.cpp.
void KXMLGUIClient::beginXMLPlug | ( | QWidget * | w | ) |
Definition at line 698 of file kxmlguiclient.cpp.
QList< KXMLGUIClient * > KXMLGUIClient::childClients | ( | ) |
Retrieves a list of all child clients.
Definition at line 601 of file kxmlguiclient.cpp.
KXMLGUIBuilder * KXMLGUIClient::clientBuilder | ( | ) | const |
Retrieves the client's GUI builder or 0 if no client specific builder has been assigned via setClientBuilder().
Definition at line 613 of file kxmlguiclient.cpp.
KComponentData KXMLGUIClient::componentData | ( | ) | const [virtual] |
- Returns:
- The componentData ( KComponentData ) for this GUI client.
Definition at line 134 of file kxmlguiclient.cpp.
QDomDocument KXMLGUIClient::domDocument | ( | ) | const [virtual] |
- Returns:
- The parsed XML in a QDomDocument, set by setXMLFile() or setXML(). This document describes the layout of the GUI.
Definition at line 139 of file kxmlguiclient.cpp.
void KXMLGUIClient::endXMLPlug | ( | ) |
Definition at line 705 of file kxmlguiclient.cpp.
KXMLGUIFactory * KXMLGUIClient::factory | ( | ) | const |
Retrieves a pointer to the KXMLGUIFactory this client is associated with (will return 0 if the client's GUI has not been built by a KXMLGUIFactory.
Definition at line 568 of file kxmlguiclient.cpp.
QString KXMLGUIClient::findMostRecentXMLFile | ( | const QStringList & | files, | |
QString & | doc | |||
) | [static] |
Definition at line 634 of file kxmlguiclient.cpp.
KXMLGUIClient::StateChange KXMLGUIClient::getActionsToChangeForState | ( | const QString & | state | ) |
Definition at line 665 of file kxmlguiclient.cpp.
void KXMLGUIClient::insertChildClient | ( | KXMLGUIClient * | child | ) |
Use this method to make a client a child client of another client.
Usually you don't need to call this method, as it is called automatically when using the second constructor, which takes a parent argument.
Definition at line 578 of file kxmlguiclient.cpp.
QString KXMLGUIClient::localXMLFile | ( | ) | const [virtual] |
Definition at line 149 of file kxmlguiclient.cpp.
KXMLGUIClient * KXMLGUIClient::parentClient | ( | ) | const |
KXMLGUIClients can form a simple child/parent object tree.
This method returns a pointer to the parent client or 0 if it has no parent client assigned.
Definition at line 573 of file kxmlguiclient.cpp.
void KXMLGUIClient::plugActionList | ( | const QString & | name, | |
const QList< QAction * > & | actionList | |||
) |
ActionLists are a way for XMLGUI to support dynamic lists of actions.
E.g. if you are writing a file manager, and there is a menu file whose contents depend on the mimetype of the file that is selected, then you can achieve this using ActionLists. It works as follows: In your xxxui.rc file ( the one that you set in setXMLFile() / pass to setupGUI() ), you put a tag <ActionList name="xxx">
.
Example:
<kpartgui name="xxx_part" version="1"> <MenuBar> <Menu name="file"> ... <!-- some useful actions--> <ActionList name="xxx_file_actionlist" /> ... <!-- even more useful actions--> </Menu> ... </MenuBar> </kpartgui>
This tag will get expanded to a list of actions. In the example above ( a file manager with a dynamic file menu ), you would call
QList<QAction*> file_actions; for( ... ) if( ... ) file_actions.append( cool_action ); unplugActionList( "xxx_file_actionlist" ); plugActionList( "xxx_file_actionlist", file_actions );
every time a file is selected, unselected or ...
- Note:
- You should not call createGUI() after calling this function. In fact, that would remove the newly added actionlists again...
- Forgetting to call unplugActionList() before plugActionList() would leave the previous actions in the menu too..
- See also:
- unplugActionList()
Definition at line 618 of file kxmlguiclient.cpp.
void KXMLGUIClient::prepareXMLUnplug | ( | QWidget * | w | ) |
Definition at line 709 of file kxmlguiclient.cpp.
void KXMLGUIClient::reloadXML | ( | ) |
Forces this client to re-read its XML resource file.
This is intended to be used when you know that the resource file has changed and you will soon be rebuilding the GUI. It has no useful effect with non-KParts GUIs, so don't bother using it unless your app is component based.
Definition at line 161 of file kxmlguiclient.cpp.
void KXMLGUIClient::removeChildClient | ( | KXMLGUIClient * | child | ) |
Removes the given child
from the client's children list.
Definition at line 586 of file kxmlguiclient.cpp.
void KXMLGUIClient::setClientBuilder | ( | KXMLGUIBuilder * | builder | ) |
A client can have an own KXMLGUIBuilder.
Use this method to assign your builder instance to the client (so that the KXMLGUIFactory can use it when building the client's GUI)
Client specific guibuilders are useful if you want to create custom container widgets for your GUI.
Definition at line 606 of file kxmlguiclient.cpp.
void KXMLGUIClient::setComponentData | ( | const KComponentData & | componentData | ) | [protected, virtual] |
Returns true if client was added to super client list.
Returns false if client was already in list. Sets the componentData ( KComponentData) for this part.
Call this first in the inherited class constructor. (At least before setXMLFile().)
Definition at line 168 of file kxmlguiclient.cpp.
void KXMLGUIClient::setDOMDocument | ( | const QDomDocument & | document, | |
bool | merge = false | |||
) | [protected, virtual] |
Sets the Document for the part, describing the layout of the GUI.
Call this in the Part-inherited class constructor if you don't call setXMLFile or setXML .
Definition at line 247 of file kxmlguiclient.cpp.
void KXMLGUIClient::setFactory | ( | KXMLGUIFactory * | factory | ) |
This method is called by the KXMLGUIFactory as soon as the client is added to the KXMLGUIFactory's GUI.
Definition at line 563 of file kxmlguiclient.cpp.
void KXMLGUIClient::setLocalXMLFile | ( | const QString & | file | ) | [protected, virtual] |
Set the full path to the "local" xml file, the one used for saving toolbar and shortcut changes.
You normally don't need to call this, if you pass a simple filename to setXMLFile.
Definition at line 222 of file kxmlguiclient.cpp.
Sets the XML for the part.
Call this in the Part-inherited class constructor if you don't call setXMLFile().
Definition at line 227 of file kxmlguiclient.cpp.
void KXMLGUIClient::setXMLFile | ( | const QString & | file, | |
bool | merge = false , |
|||
bool | setXMLDoc = true | |||
) | [protected, virtual] |
Sets the name of the rc file containing the XML for the part.
Call this in the inherited class constructor, for parts and plugins. NOTE: for mainwindows, don't call this, pass the name of the xml file to KXmlGuiWindow::setupGUI() or KXmlGuiWindow::createGUI().
- Parameters:
-
file Either an absolute path for the file, or simply the filename, which will then be assumed to be installed in the "data" resource, under a directory named like the componentData. If you pass an absolute path here, make sure to also call setLocalXMLFile, otherwise toolbar editing won't work. merge Whether to merge with the global document. setXMLDoc Specify whether to call setXML. Default is true.
Definition at line 176 of file kxmlguiclient.cpp.
void KXMLGUIClient::setXMLGUIBuildDocument | ( | const QDomDocument & | doc | ) |
void KXMLGUIClient::stateChanged | ( | const QString & | newstate, | |
KXMLGUIClient::ReverseStateChange | reverse = StateNoReverse | |||
) | [protected, virtual] |
Actions can collectively be assigned a "State".
To accomplish this the respective actions are tagged as <enable> or <disable> in a <State> </State> group of the XMLfile. During program execution the programmer can call stateChanged() to set actions to a defined state.
- Parameters:
-
newstate Name of a State in the XMLfile. reverse If the flag reverse is set to StateReverse, the State is reversed. (actions to be enabled will be disabled and action to be disabled will be enabled) Default is reverse=false.
Definition at line 671 of file kxmlguiclient.cpp.
void KXMLGUIClient::unplugActionList | ( | const QString & | name | ) |
Unplugs the action list name
from the XMLGUI.
Calling this removes the specified action list, i.e. this is the complement to plugActionList(). See plugActionList() for a more detailed example.
- See also:
- plugActionList()
Definition at line 626 of file kxmlguiclient.cpp.
void KXMLGUIClient::virtual_hook | ( | int | id, | |
void * | data | |||
) | [protected, virtual] |
Definition at line 716 of file kxmlguiclient.cpp.
QString KXMLGUIClient::xmlFile | ( | ) | const [virtual] |
This will return the name of the XML file as set by setXMLFile().
If setXML() is used directly, then this will return NULL.
The filename that this returns is obvious for components as each component has exactly one XML file. In non-components, however, there are usually two: the global file and the local file. This function doesn't really care about that, though. It will always return the last XML file set. This, in almost all cases, will be the local XML file.
- Returns:
- The name of the XML file or QString()
Definition at line 144 of file kxmlguiclient.cpp.
QDomDocument KXMLGUIClient::xmlguiBuildDocument | ( | ) | const |
The documentation for this class was generated from the following files: