Member Function Documentation

KXMLGUIClient::KXMLGUIClient()

Constructs a KXMLGUIClient that can be used with a KXMLGUIFactory to create a GUI from actions and an XML document, and that can be dynamically merged with other KXMLGUIClients.

[explicit] KXMLGUIClient::KXMLGUIClient(KXMLGUIClient *parent)

Constructs a KXMLGUIClient that can be used with a KXMLGUIFactory to create a GUI from actions and an XML document, and that 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.

[virtual noexcept] KXMLGUIClient::~KXMLGUIClient()

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.

[virtual] QAction *KXMLGUIClient::action(const QDomElement &element) const

Retrieves an action for a given QDomElement element.

The default implementation uses the "name" attribute to query the action object via the other action() method.

[since 6.0] QAction *KXMLGUIClient::action(const QString &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.

This function was introduced in 6.0.

[virtual] KActionCollection *KXMLGUIClient::actionCollection() const

Retrieves the entire action collection for the GUI client.

QList<KXMLGUIClient *> KXMLGUIClient::childClients()

Retrieves a list of all child clients.

KXMLGUIBuilder *KXMLGUIClient::clientBuilder() const

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

See also setClientBuilder().

[virtual] QString KXMLGUIClient::componentName() const

Returns the component name for this GUI client.

See also setComponentName().

[virtual] QDomDocument KXMLGUIClient::domDocument() const

Returns the parsed XML in a QDomDocument, set by setXMLFile() or setXML().

This document describes the layout of the GUI.

KXMLGUIFactory *KXMLGUIClient::factory() const

Retrieves a pointer to the KXMLGUIFactory this client is associated with.

Will return nullptr if the client's GUI has not been built by a KXMLGUIFactory.

See also setFactory().

[static, since 5.73] QString KXMLGUIClient::findVersionNumber(const QString &xml)

Returns the version number of the given xml data belonging to an XML rc file.

This function was introduced in 5.73.

void KXMLGUIClient::insertChildClient(KXMLGUIClient *child)

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

[protected, since 4.6] void KXMLGUIClient::loadStandardsXmlFile()

Load the ui_standards.rc file.

Usually followed by setXMLFile(xmlFile, true) for merging.

This function was introduced in 4.6.

KXMLGUIClient *KXMLGUIClient::parentClient() const

Returns a pointer to the parent client or nullptr if it has no parent client assigned.

KXMLGUIClients can form a simple child/parent object tree.

void KXMLGUIClient::plugActionList(const QString &name, const QList<QAction *> &actionList)

Plugs a new actionList with the given name.

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:

<gui name="xxx_part" version="1">
<MenuBar>
  <Menu name="file">
    ...  <!-- some useful actions-->
    <ActionList name="xxx_file_actionlist" />
    ...  <!-- even more useful actions-->
  </Menu>
  ...
</MenuBar>
</gui>

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

See also unplugActionList().

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. This will only have an effect if the client is then removed and re-added to the factory.

This method is only for child clients, do not call it for a mainwindow! For a mainwindow, use loadStandardsXmlFile + setXmlFile(xmlFile()) instead.

void KXMLGUIClient::removeChildClient(KXMLGUIClient *child)

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

[since 4.4] void KXMLGUIClient::replaceXMLFile(const QString &xmlfile, const QString &localxmlfile, bool merge = false)

Sets a new xmlfile and localxmlfile.

The purpose of this public method is to allow non-inherited objects to replace the ui definition of an embedded client with a customized version. It corresponds to the usual calls to setXMLFile() and setLocalXMLFile().

xmlfile The xml file to use. Contrary to setXMLFile(), this must be an absolute file path.

localxmlfile The local xml file to set. This should be the full path to a writeable file, usually using QStandardPaths::writableLocation. You can set this to QString(), but no user changes to shortcuts / toolbars will be possible in this case.

merge Whether to merge with the global document.

This function was introduced in 4.4.

See also setLocalXMLFile().

void KXMLGUIClient::setClientBuilder(KXMLGUIBuilder *builder)

Use this method to assign your builder instance to the client (so that the KXMLGUIFactory can use it when building the client's GUI).

A client can have its own KXMLGUIBuilder.

Client specific guibuilders are useful if you want to create custom container widgets for your GUI.

See also clientBuilder().

[virtual protected] void KXMLGUIClient::setComponentName(const QString &componentName, const QString &componentDisplayName)

Sets the component name for this part.

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

componentName The name of the directory where the XMLGUI files will be found.

componentDisplayName A user-visible name (e.g. for the toolbar editor).

See also componentName().

[virtual protected] void KXMLGUIClient::setDOMDocument(const QDomDocument &document, bool merge = false)

Sets the document for the part, describing the layout of the GUI, and whether to merge with the global document.

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

For application-specific changes to a client's XML, it is a better idea to save the modified dom document to an app/default-client.xml and define a local-xml-file to something specific like app/local-client.xml, using replaceXMLFile(). See kdepimlibs/kontactinterface/plugin.cpp for an example.

void KXMLGUIClient::setFactory(KXMLGUIFactory *factory)

Sets a new factory.

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

See also factory().

[virtual protected] void KXMLGUIClient::setLocalXMLFile(const QString &file)

Set the full path to the "local" xml file used for saving toolbar and shortcut changes.

You normally don't need to call this if you pass a simple filename to setXMLFile().

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

Sets the XML document for the part and whether to merge with the global document.

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

[virtual protected] void KXMLGUIClient::setXMLFile(const QString &file, bool merge = false, bool setXMLDoc = true)

Sets the name of the rc file containing the XML for the part.

Call this in the inherited class constructor, for parts and plugins.

file Either an absolute path for the file, or simply the filename. See below for details. 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.

The preferred way to call this method is with a simple filename for the file argument.

Since 5.1, the file will then be assumed to be installed in DATADIR/kxmlgui5/, under a directory named after the component name. You should use ${KDE_INSTALL_KXMLGUIDIR}/componentname in your CMakeLists.txt file to install the .rc file(s).

Since 5.4, the file will then be assumed to be installed in a Qt resource in :/kxmlgui5/, under a directory named after the component name.

[static protected, since 5.16] QString KXMLGUIClient::standardsXmlFileLocation()

Returns the full path to the ui_standards.rc, always non-empty.

Might return a resource path.

This function was introduced in 5.16.

[virtual protected] void KXMLGUIClient::stateChanged(const QString &newstate, KXMLGUIClient::ReverseStateChange reverse = StateNoReverse)

Emitted when an action has changed state to newstate.

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.

newstate Name of a State in the XMLfile.

reverse If the reverse flag is set to StateReverse, the State is reversed (actions to be enabled will be disabled and action to be disabled will be enabled).

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().

[virtual] QString KXMLGUIClient::xmlFile() const

Returns the name of the XML file as set by setXMLFile(); if setXML() is used directly, then this will return an empty string.

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.