kdeui Library API Documentation

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>

Inheritance diagram for KXMLGUIClient:

KDEPrivate::ToolBarHandler KEditToolbarWidget KMainWindow KDockMainWindow List of all members.

Public Methods

 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.

 KXMLGUIClient (KXMLGUIClient *parent)
 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.

virtual ~KXMLGUIClient ()
 Destructs the KXMLGUIClient.

KActionaction (const char *name) const
 Retrieves an action of the client by name.

virtual KActionaction (const QDomElement &element) const
 Retrieves an action for a given QDomElement.

virtual KActionCollectionactionCollection () const
 Retrieves the entire action collection for the GUI client.

virtual KInstanceinstance () const
virtual QDomDocument domDocument () const
virtual QString xmlFile () const
 This will return the name of the XML file as set by setXMLFile().

void setFactory (KXMLGUIFactory *factory)
 This method is called by the KXMLGUIFactory as soon as the client is added to the KXMLGUIFactory's GUI.

KXMLGUIFactoryfactory () const
 Retrieves a pointer to the KXMLGUIFactory this client is associated with (will return 0L if the client's GUI has not been built by a KXMLGUIFactory.

KXMLGUIClient * parentClient () const
 KXMLGUIClients can form a simple child/parent object tree.

void insertChildClient (KXMLGUIClient *child)
 Use this method to make a client a child client of another client.

void removeChildClient (KXMLGUIClient *child)
 Removes the given child from the client's children list.

const QPtrList< KXMLGUIClient > * childClients ()
 Retrieves a list of all child clients.

void setClientBuilder (KXMLGUIBuilder *builder)
 A client can have an own KXMLGUIBuilder.

KXMLGUIBuilderclientBuilder () const
 Retrieves the client's GUI builder or 0L if no client specific builder has been assigned via setClientBuilder().

void reloadXML ()
 Forces this client to re-read its XML resource file.

void plugActionList (const QString &name, const QPtrList< KAction > &actionList)
 ActionLists are a way for XMLGUI to support dynamic lists of actions.

void unplugActionList (const QString &name)
 The complement of plugActionList() ...

void beginXMLPlug (QWidget *)
 
Since:
3.1


void endXMLPlug ()
 
Since:
3.1


void prepareXMLUnplug (QWidget *)
 
Since:
3.1



Protected Methods

virtual void setInstance (KInstance *instance)
 Sets the instance (KInstance) for this part.

virtual void setXMLFile (const QString &file, bool merge=false, bool setXMLDoc=true)
 Sets the name of the rc file containing the XML for the part.

virtual void setXML (const QString &document, bool merge=false)
 Sets the XML for the part.

virtual void setDOMDocument (const QDomDocument &document, bool merge=false)
 Sets the Document for the part, describing the layout of the GUI.

virtual void conserveMemory ()
 This function will attempt to give up some memory after the GUI is built.

virtual void stateChanged (const QString &newstate, ReverseStateChange reverse=StateNoReverse)
 Actions can collectively be assigned a "State".


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 41 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 67 of file kxmlguiclient.cpp.

KXMLGUIClient::KXMLGUIClient KXMLGUIClient *    parent
 

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 72 of file kxmlguiclient.cpp.

References insertChildClient().

KXMLGUIClient::~KXMLGUIClient   [virtual]
 

Destructs the KXMLGUIClient.

Definition at line 78 of file kxmlguiclient.cpp.

References QPtrListIterator::current().


Member Function Documentation

KAction * 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 93 of file kxmlguiclient.cpp.

References KActionCollection::action(), actionCollection(), and QPtrListIterator::current().

Referenced by stateChanged().

KAction * 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 115 of file kxmlguiclient.cpp.

References KActionCollection::action(), actionCollection(), QDomElement::attribute(), and KGlobal::staticQString().

KActionCollection * KXMLGUIClient::actionCollection   [virtual]
 

Retrieves the entire action collection for the GUI client.

Reimplemented in KEditToolbarWidget.

Definition at line 107 of file kxmlguiclient.cpp.

Referenced by action(), beginXMLPlug(), KMainWindow::createGUI(), endXMLPlug(), KEditToolbarWidget::KEditToolbarWidget(), KMainWindowInterface::KMainWindowInterface(), prepareXMLUnplug(), setDOMDocument(), setInstance(), setXMLFile(), and stateChanged().

KInstance * KXMLGUIClient::instance   [virtual]
 

Returns:
The instance (KInstance) for this part.

Definition at line 121 of file kxmlguiclient.cpp.

Referenced by KMainWindow::createGUI(), KMainWindow::helpMenu(), KEditToolbarWidget::KEditToolbarWidget(), setClientBuilder(), and setXMLFile().

QDomDocument KXMLGUIClient::domDocument   [virtual]
 

Returns:
The parsed XML in a QDomDocument, set by setXMLFile() or setXML(). This document describes the layout of the GUI.

Definition at line 126 of file kxmlguiclient.cpp.

Referenced by KXMLGUIFactory::addClient(), KMainWindow::createGUI(), KEditToolbarWidget::KEditToolbarWidget(), and KXMLGUIFactory::removeClient().

QString KXMLGUIClient::xmlFile   [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::null

Definition at line 131 of file kxmlguiclient.cpp.

Referenced by KEditToolbarWidget::KEditToolbarWidget(), reloadXML(), and KEditToolbarWidget::save().

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 543 of file kxmlguiclient.cpp.

Referenced by KXMLGUIFactory::addClient(), KEditToolbarWidget::KEditToolbarWidget(), and KXMLGUIFactory::removeClient().

KXMLGUIFactory * KXMLGUIClient::factory  
 

Retrieves a pointer to the KXMLGUIFactory this client is associated with (will return 0L if the client's GUI has not been built by a KXMLGUIFactory.

Definition at line 548 of file kxmlguiclient.cpp.

Referenced by KXMLGUIFactory::addClient(), KXMLGUIFactory::removeClient(), KEditToolbarWidget::save(), and KMainWindow::setStandardToolBarMenuEnabled().

KXMLGUIClient * KXMLGUIClient::parentClient  
 

KXMLGUIClients can form a simple child/parent object tree.

This method returns a pointer to the parent client or 0L if it has no parent client assigned.

Definition at line 553 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 arent argument.

Definition at line 558 of file kxmlguiclient.cpp.

References d.

Referenced by KXMLGUIClient().

void KXMLGUIClient::removeChildClient KXMLGUIClient *    child
 

Removes the given child from the client's children list.

Definition at line 566 of file kxmlguiclient.cpp.

References d.

const QPtrList< KXMLGUIClient > * KXMLGUIClient::childClients  
 

Retrieves a list of all child clients.

Definition at line 581 of file kxmlguiclient.cpp.

Referenced by KXMLGUIFactory::addClient(), and KXMLGUIFactory::removeClient().

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 586 of file kxmlguiclient.cpp.

References instance(), and KXMLGUIBuilder::setBuilderInstance().

KXMLGUIBuilder * KXMLGUIClient::clientBuilder  
 

Retrieves the client's GUI builder or 0L if no client specific builder has been assigned via setClientBuilder().

Definition at line 593 of file kxmlguiclient.cpp.

Referenced by KXMLGUIFactory::addClient(), and KXMLGUIFactory::removeClient().

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 148 of file kxmlguiclient.cpp.

References QString::isEmpty(), setXMLFile(), and xmlFile().

void KXMLGUIClient::plugActionList const QString   name,
const QPtrList< KAction > &    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() ), you put an <ActionList name="xxx"> tag. E.g.

   * <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

 QPtrList<KAction> 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..

Definition at line 598 of file kxmlguiclient.cpp.

void KXMLGUIClient::unplugActionList const QString   name
 

The complement of plugActionList() ...

Definition at line 606 of file kxmlguiclient.cpp.

void KXMLGUIClient::beginXMLPlug QWidget  
 

Since:
3.1

Definition at line 914 of file kxmlguiclient.cpp.

References actionCollection(), KActionCollection::beginXMLPlug(), and QPtrListIterator::current().

Referenced by KXMLGUIFactory::addClient().

void KXMLGUIClient::endXMLPlug  
 

Since:
3.1

Definition at line 922 of file kxmlguiclient.cpp.

References actionCollection(), QPtrListIterator::current(), and KActionCollection::endXMLPlug().

Referenced by KXMLGUIFactory::addClient().

void KXMLGUIClient::prepareXMLUnplug QWidget  
 

Since:
3.1

Definition at line 930 of file kxmlguiclient.cpp.

References actionCollection(), QPtrListIterator::current(), and KActionCollection::prepareXMLUnplug().

Referenced by KXMLGUIFactory::removeClient().

void KXMLGUIClient::setInstance KInstance   instance [protected, virtual]
 

Sets the instance (KInstance) for this part.

Call this first in the inherited class constructor. (At least before setXMLFile().)

Definition at line 155 of file kxmlguiclient.cpp.

References actionCollection(), KNotifyClient::instance(), and KActionCollection::setInstance().

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 Part-inherited class constructor.

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 instance.
setXML  Specify whether to call setXML. Default is true. and the DOM document at once.

Definition at line 163 of file kxmlguiclient.cpp.

References actionCollection(), KInstance::dirs(), KStandardDirs::findAllResources(), QString::fromLatin1(), instance(), QString::isEmpty(), QString::isNull(), setXML(), and KActionCollection::setXMLFile().

Referenced by KMainWindow::createGUI(), KEditToolbarWidget::KEditToolbarWidget(), reloadXML(), and KEditToolbarWidget::save().

void KXMLGUIClient::setXML const QString   document,
bool    merge = false
[protected, virtual]
 

Sets the XML for the part.

Call this in the Part-inherited class constructor if you don't call setXMLFile().

Definition at line 209 of file kxmlguiclient.cpp.

References QDomDocument::setContent(), and setDOMDocument().

Referenced by KEditToolbarWidget::KEditToolbarWidget(), and setXMLFile().

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 216 of file kxmlguiclient.cpp.

References actionCollection(), QDomDocument::documentElement(), and KXMLGUIFactory::removeDOMComments().

Referenced by setXML().

void KXMLGUIClient::conserveMemory   [protected, virtual]
 

This function will attempt to give up some memory after the GUI is built.

It should never be used in apps where the GUI may be rebuilt at some later time (components, for instance).

Definition at line 527 of file kxmlguiclient.cpp.

Referenced by KMainWindow::createGUI().

void KXMLGUIClient::stateChanged const QString   newstate,
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 887 of file kxmlguiclient.cpp.

References KActionCollection::action(), action(), actionCollection(), and KAction::setEnabled().

Referenced by KMainWindow::slotStateChanged().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:21:08 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001