class KXMLGUIClient

# class KXMLGUIClient | More...
Definition | `#include <kxmlguiclient.h>`
Inherited by | KDockMainWindow, KEditToolbarWidget, KMainWindow, ToolBarHandler
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

- enum ReverseStateChange { StateNoReverse, StateReverse }
- struct StateChange

#### Public Methods

- KXMLGUIClient ()
- KXMLGUIClient ( KXMLGUIClient *parent )
- virtual ~KXMLGUIClient ()
- KAction* action ( const char* name ) const
- virtual KAction * action ( const QDomElement &element ) const
- virtual KActionCollection* actionCollection () const
- virtual KInstance * instance () const
- virtual QDomDocument domDocument () const
- virtual QString xmlFile () const
- virtual QString localXMLFile () const
- void setXMLGUIBuildDocument ( const QDomDocument &doc )
- QDomDocument xmlguiBuildDocument () const
- void setFactory ( KXMLGUIFactory *factory )
- KXMLGUIFactory * factory () const
- KXMLGUIClient * parentClient () const
- void insertChildClient ( KXMLGUIClient *child )
- void removeChildClient ( KXMLGUIClient *child )
- const QPtrList<KXMLGUIClient> * childClients ()
- void setClientBuilder ( KXMLGUIBuilder *builder )
- KXMLGUIBuilder * clientBuilder () const
- void reloadXML ()
- void plugActionList ( const QString &name, const QPtrList<KAction> &actionList )
- void unplugActionList ( const QString &name )
- void addStateActionEnabled (const QString& state, const QString& action)
- void addStateActionDisabled (const QString& state, const QString& action)
- StateChange getActionsToChangeForState (const QString& state)
- void beginXMLPlug ( QWidget * )
- void endXMLPlug ()
- void prepareXMLUnplug ( QWidget * )

#### Public Static Methods

- static QString findMostRecentXMLFile ( const QStringList &files, QString &doc )

#### Protected Methods

- virtual void setInstance ( KInstance *instance )
- virtual void setXMLFile ( const QString& file, bool merge = false, bool setXMLDoc = true )
- virtual void setLocalXMLFile ( const QString &file )
- virtual void setXML ( const QString &document, bool merge = false )
- virtual void setDOMDocument ( const QDomDocument &document, bool merge = false )
- virtual void conserveMemory ()
- 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.

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.

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

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.

~KXMLGUIClient () | ### ~KXMLGUIClient

[virtual]

Destructs the KXMLGUIClient.

KAction* action ( const char* name ) | ### action

[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.

KAction * action ( const QDomElement &element ) | ### action

[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.

KActionCollection* actionCollection () | ### actionCollection

[const virtual]

Retrieves the entire action collection for the GUI client

KInstance * instance () | ### instance

[const virtual]

Returns: The instance (KInstance) for this part.

QDomDocument domDocument () | ### domDocument

[const virtual]

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

QString xmlFile () | ### 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::null

QString localXMLFile () | ### localXMLFile

[const virtual]

void setXMLGUIBuildDocument ( const QDomDocument &doc ) | ### setXMLGUIBuildDocument

QDomDocument xmlguiBuildDocument () | ### xmlguiBuildDocument

[const]

void setFactory ( KXMLGUIFactory *factory ) | ### setFactory

This method is called by the KXMLGUIFactory as soon as the client is added to the KXMLGUIFactory's GUI.

KXMLGUIFactory * factory () | ### factory

[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 () | ### parentClient

[const]

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.

void insertChildClient ( KXMLGUIClient *child ) | ### insertChildClient

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.

void removeChildClient ( KXMLGUIClient *child ) | ### removeChildClient

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

const QPtrList<KXMLGUIClient> * childClients () | ### childClients

Retrieves a list of all child clients.

void setClientBuilder ( KXMLGUIBuilder *builder ) | ### setClientBuilder

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.

KXMLGUIBuilder * clientBuilder () | ### clientBuilder

[const]

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

void reloadXML () | ### 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.

void plugActionList ( const QString &name, const QPtrList<KAction> &actionList ) | ### plugActionList

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 tag. E.g. \verbatim ... ... ... \endverbatim

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 \code QPtrList file_actions; for( ... ) if( ... ) file_actions.append( cool_action ); unplugActionList( "xxx_file_actionlist" ); plugActionList( "xxx_file_actionlist", file_actions ); \endcode 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... \note Forgetting to call unplugActionList() before plugActionList() would leave the previous actions in the menu too..

void unplugActionList ( const QString &name ) | ### unplugActionList

The complement of \ref plugActionList() ...

QString findMostRecentXMLFile ( const QStringList &files, QString &doc ) | ### findMostRecentXMLFile

[static]

void addStateActionEnabled (const QString& state, const QString& action) | ### addStateActionEnabled

void addStateActionDisabled (const QString& state, const QString& action) | ### addStateActionDisabled

enum ReverseStateChange { StateNoReverse, StateReverse } | ### ReverseStateChange

StateChange (struct) | ### StateChange

StateChange getActionsToChangeForState (const QString& state) | ### getActionsToChangeForState

void beginXMLPlug ( QWidget * ) | ### beginXMLPlug

void endXMLPlug () | ### endXMLPlug

void prepareXMLUnplug ( QWidget * ) | ### prepareXMLUnplug

void setInstance ( KInstance *instance ) | ### setInstance

[protected virtual]

Sets the instance (KInstance) for this part.

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

void setXMLFile ( const QString& file, bool merge = false, bool setXMLDoc = true ) | ### setXMLFile

[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.

void setLocalXMLFile ( const QString &file ) | ### setLocalXMLFile

[protected virtual]

void setXML ( const QString &document, bool merge = false ) | ### setXML

[protected virtual]

Sets the XML for the part.

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

void setDOMDocument ( const QDomDocument &document, bool merge = false ) | ### setDOMDocument

[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 .

void conserveMemory () | ### 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).

void stateChanged (const QString &newstate, ReverseStateChange reverse = StateNoReverse) | ### stateChanged

[protected virtual]

Actions can collectively be assigned a "State". To accomplish this the respective actions are tagged as or in a 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.

void virtual_hook ( int id, void* data ) | ### virtual_hook

[protected virtual]

Generated by: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:37 2003, using kdoc 2.0a54.