KisKXMLGUIClient Class Reference

#include <kxmlguiclient.h>

Inheritance diagram for KisKXMLGUIClient:

Classes
struct	StateChange

Public Types
enum	ReverseStateChange { StateNoReverse , StateReverse }

Public Member Functions
QAction *	action (const char *name) const
virtual QAction *	action (const QDomElement &element) const
virtual KisKActionCollection *	actionCollection () const
void	addStateActionDisabled (const QString &state, const QString &action)
void	addStateActionEnabled (const QString &state, const QString &action)
void	beginXMLPlug (QWidget *)
QList< KisKXMLGUIClient * >	childClients ()
KisKXMLGUIBuilder *	clientBuilder () const
virtual QString	componentName () const
virtual QDomDocument	domDocument () const
void	endXMLPlug ()
KisKXMLGUIFactory *	factory () const
StateChange	getActionsToChangeForState (const QString &state)
void	insertChildClient (KisKXMLGUIClient *child)
	KisKXMLGUIClient ()
	KisKXMLGUIClient (KisKXMLGUIClient *parent)
virtual QString	localXMLFile () const
KisKXMLGUIClient *	parentClient () const
void	plugActionList (const QString &name, const QList< QAction * > &actionList)
void	prepareXMLUnplug (QWidget *)
void	reloadXML ()
void	removeChildClient (KisKXMLGUIClient *child)
void	replaceXMLFile (const QString &xmlfile, const QString &localxmlfile, bool merge=false)
void	setClientBuilder (KisKXMLGUIBuilder *builder)
void	setFactory (KisKXMLGUIFactory *factory)
void	setXMLGUIBuildDocument (const QDomDocument &doc)
void	unplugActionList (const QString &name)
virtual QString	xmlFile () const
QDomDocument	xmlguiBuildDocument () const
virtual	~KisKXMLGUIClient ()

Static Public Member Functions
static QString	findMostRecentXMLFile (const QStringList &files, QString &doc)

Protected Member Functions
void	loadStandardsXmlFile ()
virtual void	setComponentName (const QString &componentName, const QString &componentDisplayName)
void	setDOMDocument (const QDomDocument &document, bool merge=false)
void	setLocalXMLFile (const QString &file)
void	setXML (const QString &document, bool merge=false)
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)

Static Protected Member Functions
static QString	standardsXmlFileLocation ()

Private Attributes
KisKXMLGUIClientPrivate *const	d

Friends
class	KDEPrivate::KisKEditToolBarWidget

Detailed Description

A KisKXMLGUIClient can be used with KisKXMLGUIFactory to create a GUI from actions and an XML document, and can be dynamically merged with other KisKXMLGUIClients.

Definition at line 36 of file kxmlguiclient.h.

Member Enumeration Documentation

ReverseStateChange

enum KisKXMLGUIClient::ReverseStateChange

Enumerator
StateNoReverse
StateReverse

Definition at line 252 of file kxmlguiclient.h.

{ StateNoReverse, StateReverse };

Constructor & Destructor Documentation

KisKXMLGUIClient() [1/2]

KisKXMLGUIClient::KisKXMLGUIClient

(

)

Constructs a KisKXMLGUIClient which can be used with a KisKXMLGUIFactory to create a GUI from actions and an XML document, and which can be dynamically merged with other KisKXMLGUIClients.

Definition at line 75 of file kxmlguiclient.cpp.

    : d(new KisKXMLGUIClientPrivate)
{
}

KisKXMLGUIClient() [2/2]

KisKXMLGUIClient::KisKXMLGUIClient ( KisKXMLGUIClient * parent )

explicit

Constructs a KisKXMLGUIClient which can be used with a KisKXMLGUIFactory to create a GUI from actions and an XML document, and which can be dynamically merged with other KisKXMLGUIClients.

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

    : d(new KisKXMLGUIClientPrivate)
{
    parent->insertChildClient(this);
}

~KisKXMLGUIClient()

KisKXMLGUIClient::~KisKXMLGUIClient ( )

virtual

Destructs the KisKXMLGUIClient.

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

{
    if (d->m_parent) {
        d->m_parent->removeChildClient(this);
    }
 
    if (d->m_factory) {
        qWarning() << this << "deleted without having been removed from the factory first. This will leak standalone popupmenus and could lead to crashes.";
        d->m_factory->forgetClient(this);
    }
 
    Q_FOREACH (KisKXMLGUIClient *client, d->m_children) {
        if (d->m_factory) {
            d->m_factory->forgetClient(client);
        }
        assert(client->d->m_parent == this);
        client->d->m_parent = 0;
    }
 
    delete d->m_actionCollection;
    delete d;
}

References d, KisKXMLGUIClientPrivate::m_actionCollection, KisKXMLGUIClientPrivate::m_children, KisKXMLGUIClientPrivate::m_factory, KisKXMLGUIClientPrivate::m_parent, and removeChildClient().

Member Function Documentation

action() [1/2]

QAction * KisKXMLGUIClient::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 109 of file kxmlguiclient.cpp.

{
    QAction *act = actionCollection()->action(QLatin1String(name));
    if (!act) {
        Q_FOREACH (KisKXMLGUIClient *client, d->m_children) {
            act = client->actionCollection()->action(QLatin1String(name));
            if (act) {
                break;
            }
        }
    }
    return act;
}

References KisKActionCollection::action(), actionCollection(), d, and KisKXMLGUIClientPrivate::m_children.

action() [2/2]

QAction * KisKXMLGUIClient::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 132 of file kxmlguiclient.cpp.

{
    return actionCollection()->action(element.attribute(QStringLiteral("name")));
}

References KisKActionCollection::action(), and actionCollection().

actionCollection()

KisKActionCollection * KisKXMLGUIClient::actionCollection ( ) const

virtual

Retrieves the entire action collection for the GUI client.

Reimplemented in KDEPrivate::KisKEditToolBarWidget.

Definition at line 123 of file kxmlguiclient.cpp.

{
    if (!d->m_actionCollection) {
        d->m_actionCollection = new KisKActionCollection(this);
        d->m_actionCollection->setObjectName(QStringLiteral("KisKXMLGUIClient-KisKActionCollection"));
    }
    return d->m_actionCollection;
}

References d, and KisKXMLGUIClientPrivate::m_actionCollection.

addStateActionDisabled()

void KisKXMLGUIClient::addStateActionDisabled	(	const QString &	state,
		const QString &	action )

Definition at line 739 of file kxmlguiclient.cpp.

{
    StateChange stateChange = getActionsToChangeForState(state);
 
    stateChange.actionsToDisable.append(action);
    //qDebug(260) << "KisKXMLGUIClient::addStateActionDisabled( " << state << ", " << action << ")";
 
    d->m_actionsStateMap.insert(state, stateChange);
}

References action(), KisKXMLGUIClient::StateChange::actionsToDisable, d, getActionsToChangeForState(), and KisKXMLGUIClientPrivate::m_actionsStateMap.

addStateActionEnabled()

void KisKXMLGUIClient::addStateActionEnabled	(	const QString &	state,
		const QString &	action )

Definition at line 728 of file kxmlguiclient.cpp.

{
    StateChange stateChange = getActionsToChangeForState(state);
 
    stateChange.actionsToEnable.append(action);
    //qDebug(260) << "KisKXMLGUIClient::addStateActionEnabled( " << state << ", " << action << ")";
 
    d->m_actionsStateMap.insert(state, stateChange);
}

References action(), KisKXMLGUIClient::StateChange::actionsToEnable, d, getActionsToChangeForState(), and KisKXMLGUIClientPrivate::m_actionsStateMap.

beginXMLPlug()

void KisKXMLGUIClient::beginXMLPlug

(

QWidget *

w

)

Definition at line 786 of file kxmlguiclient.cpp.

{
    actionCollection()->addAssociatedWidget(w);
    foreach (KisKXMLGUIClient *client, d->m_children) {
        client->beginXMLPlug(w);
    }
}

References actionCollection(), KisKActionCollection::addAssociatedWidget(), beginXMLPlug(), d, and KisKXMLGUIClientPrivate::m_children.

childClients()

QList< KisKXMLGUIClient * > KisKXMLGUIClient::childClients

(

)

Retrieves a list of all child clients.

Definition at line 688 of file kxmlguiclient.cpp.

{
    return d->m_children;
}

References d, and KisKXMLGUIClientPrivate::m_children.

clientBuilder()

KisKXMLGUIBuilder * KisKXMLGUIClient::clientBuilder

(

)

const

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

Definition at line 698 of file kxmlguiclient.cpp.

{
    return d->m_builder;
}

References d, and KisKXMLGUIClientPrivate::m_builder.

componentName()

QString KisKXMLGUIClient::componentName ( ) const

virtual

Returns

The component name for this GUI client.

Definition at line 137 of file kxmlguiclient.cpp.

{
    return d->m_componentName;
}

References d, and KisKXMLGUIClientPrivate::m_componentName.

domDocument()

QDomDocument KisKXMLGUIClient::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 142 of file kxmlguiclient.cpp.

{
    return d->m_doc;
}

References d, and KisKXMLGUIClientPrivate::m_doc.

endXMLPlug()

void KisKXMLGUIClient::endXMLPlug

(

)

Definition at line 794 of file kxmlguiclient.cpp.

{
}

factory()

KisKXMLGUIFactory * KisKXMLGUIClient::factory

(

)

const

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

Definition at line 654 of file kxmlguiclient.cpp.

{
    return d->m_factory;
}

References d, and KisKXMLGUIClientPrivate::m_factory.

findMostRecentXMLFile()

QString KisKXMLGUIClient::findMostRecentXMLFile ( const QStringList & files, QString & doc )

static

Definition at line 721 of file kxmlguiclient.cpp.

{
    KXmlGuiVersionHandler versionHandler(files);
    doc = versionHandler.finalDocument();
    return versionHandler.finalFile();
}

References KXmlGuiVersionHandler::finalDocument(), and KXmlGuiVersionHandler::finalFile().

getActionsToChangeForState()

KisKXMLGUIClient::StateChange KisKXMLGUIClient::getActionsToChangeForState

(

const QString &

state

)

Definition at line 750 of file kxmlguiclient.cpp.

{
    return d->m_actionsStateMap[state];
}

References d, and KisKXMLGUIClientPrivate::m_actionsStateMap.

insertChildClient()

void KisKXMLGUIClient::insertChildClient

(

KisKXMLGUIClient *

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

{
    if (child->d->m_parent) {
        child->d->m_parent->removeChildClient(child);
    }
    d->m_children.append(child);
    child->d->m_parent = this;
}

References d, KisKXMLGUIClientPrivate::m_children, KisKXMLGUIClientPrivate::m_parent, and removeChildClient().

loadStandardsXmlFile()

void KisKXMLGUIClient::loadStandardsXmlFile ( )

protected

Load the ui_standards.xmlgui file. Usually followed by setXMLFile(xmlFile, true), for merging.

Since

4.6

Definition at line 202 of file kxmlguiclient.cpp.

{
    setXML(KisKXMLGUIFactory::readConfigFile(standardsXmlFileLocation()));
}

References KisKXMLGUIFactory::readConfigFile(), setXML(), and standardsXmlFileLocation().

localXMLFile()

QString KisKXMLGUIClient::localXMLFile ( ) const

virtual

Definition at line 152 of file kxmlguiclient.cpp.

{
    if (!d->m_localXMLFile.isEmpty()) {
        return d->m_localXMLFile;
    }
 
    if (!QDir::isRelativePath(d->m_xmlFile)) {
        return QString();    // can't save anything here
    }
 
    if (d->m_xmlFile.isEmpty()) { // setXMLFile not called at all, can't save. Use case: ToolBarHandler
        return QString();
    }
 
    return QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) + QStringLiteral("/kxmlgui5/") +
           componentName() + QLatin1Char('/') + d->m_xmlFile;
}

References componentName(), d, KisKXMLGUIClientPrivate::m_localXMLFile, and KisKXMLGUIClientPrivate::m_xmlFile.

parentClient()

KisKXMLGUIClient * KisKXMLGUIClient::parentClient

(

)

const

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

{
    return d->m_parent;
}

References d, and KisKXMLGUIClientPrivate::m_parent.

plugActionList()

void KisKXMLGUIClient::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.xmlgui 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 ...

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

{
    if (!d->m_factory) {
        return;
    }
 
    d->m_factory->plugActionList(this, name, actionList);
}

References d, and KisKXMLGUIClientPrivate::m_factory.

prepareXMLUnplug()

void KisKXMLGUIClient::prepareXMLUnplug

(

QWidget *

w

)

Definition at line 798 of file kxmlguiclient.cpp.

{
    actionCollection()->removeAssociatedWidget(w);
    foreach (KisKXMLGUIClient *client, d->m_children) {
        client->prepareXMLUnplug(w);
    }
}

References actionCollection(), d, KisKXMLGUIClientPrivate::m_children, prepareXMLUnplug(), and KisKActionCollection::removeAssociatedWidget().

reloadXML()

void KisKXMLGUIClient::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.

Definition at line 170 of file kxmlguiclient.cpp.

{
    // TODO: this method can't be used for the KXmlGuiWindow, since it doesn't merge in ui_standards.xmlgui!
    //   -> KDE5: load ui_standards_rc in setXMLFile using a flag, and remember that flag?
    //            and then KisKEditToolBar can use reloadXML.
    QString file(xmlFile());
    if (!file.isEmpty()) {
        setXMLFile(file);
    }
}

References setXMLFile(), and xmlFile().

removeChildClient()

void KisKXMLGUIClient::removeChildClient

(

KisKXMLGUIClient *

child

)

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

Definition at line 673 of file kxmlguiclient.cpp.

{
    assert(d->m_children.contains(child));
    d->m_children.removeAll(child);
    child->d->m_parent = 0;
}

References d, KisKXMLGUIClientPrivate::m_children, and KisKXMLGUIClientPrivate::m_parent.

replaceXMLFile()

void KisKXMLGUIClient::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().

Parameters

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.

See also

setLocalXMLFile()

Parameters

merge

Whether to merge with the global document

Note

If in any doubt whether you need this or not, use setXMLFile() and setLocalXMLFile(), instead of this function.

Just like setXMLFile(), this function has to be called before the client is added to a KisKXMLGUIFactory in order to have an effect.

Since

4.4

Definition at line 272 of file kxmlguiclient.cpp.

{
    if (!QDir::isAbsolutePath(xmlfile)) {
        qWarning() << "xml file" << xmlfile << "is not an absolute path";
    }
 
    setLocalXMLFile(localxmlfile);
    setXMLFile(xmlfile, merge);
}

References setLocalXMLFile(), and setXMLFile().

setClientBuilder()

void KisKXMLGUIClient::setClientBuilder

(

KisKXMLGUIBuilder *

builder

)

A client can have an own KisKXMLGUIBuilder. Use this method to assign your builder instance to the client (so that the KisKXMLGUIFactory 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 693 of file kxmlguiclient.cpp.

{
    d->m_builder = builder;
}

References d, and KisKXMLGUIClientPrivate::m_builder.

setComponentName()

void KisKXMLGUIClient::setComponentName ( const QString & componentName, const QString & componentDisplayName )

protectedvirtual

Sets the component name for this part.

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

Parameters

componentName	the name of the directory where the XMLGUI files will be found
componentDisplayName	a user-visible name (e.g. for the toolbar editor)

Definition at line 181 of file kxmlguiclient.cpp.

{
    d->m_componentName = componentName;
    actionCollection()->setComponentName(componentName);
    actionCollection()->setComponentDisplayName(componentDisplayName);
    if (d->m_builder) {
        d->m_builder->setBuilderClient(this);
    }
}

References actionCollection(), componentName(), d, KisKXMLGUIClientPrivate::m_builder, KisKXMLGUIClientPrivate::m_componentName, KisKXMLGUIBuilder::setBuilderClient(), KisKActionCollection::setComponentDisplayName(), and KisKActionCollection::setComponentName().

setDOMDocument()

void KisKXMLGUIClient::setDOMDocument ( const QDomDocument & document, bool merge = false )

protected

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.

WARNING: using this method is not recommended. Many code paths lead to reloading from the XML file on disk. And editing toolbars requires that the result is written to disk anyway, and loaded from there the next time.

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.

Definition at line 342 of file kxmlguiclient.cpp.

{
    if (merge && !d->m_doc.isNull()) {
        QDomElement base = d->m_doc.documentElement();
 
        QDomElement e = document.documentElement();
 
        // merge our original (global) xml with our new one
        d->mergeXML(base, e, actionCollection());
 
        // reassign our pointer as mergeXML might have done something
        // strange to it
        base = d->m_doc.documentElement();
 
        //qDebug(260) << "Result of xmlgui merging:" << d->m_doc.toString();
 
        // we want some sort of failsafe.. just in case
        if (base.isNull()) {
            d->m_doc = document;
        }
    } else {
        d->m_doc = document;
    }
 
    setXMLGUIBuildDocument(QDomDocument());
}

References actionCollection(), d, KisKXMLGUIClientPrivate::m_doc, KisKXMLGUIClientPrivate::mergeXML(), and setXMLGUIBuildDocument().

setFactory()

void KisKXMLGUIClient::setFactory

(

KisKXMLGUIFactory *

factory

)

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

Definition at line 649 of file kxmlguiclient.cpp.

{
    d->m_factory = factory;
}

References d, factory(), and KisKXMLGUIClientPrivate::m_factory.

setLocalXMLFile()

void KisKXMLGUIClient::setLocalXMLFile ( const QString & file )

protected

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

{
    d->m_localXMLFile = file;
}

References d, and KisKXMLGUIClientPrivate::m_localXMLFile.

setXML()

void KisKXMLGUIClient::setXML ( const QString & document, bool merge = false )

protected

Sets the XML for the part.

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

Definition at line 312 of file kxmlguiclient.cpp.

{
    QDomDocument doc;
    // QDomDocument raises a parse error on empty document, but we accept no app-specific document,
    // in which case you only get ui_standards.xmlgui layout.
#if QT_VERSION < QT_VERSION_CHECK(6, 5, 0)
    QString errorMsg;
    int errorLine, errorColumn;
    bool result = document.isEmpty() || doc.setContent(document, &errorMsg, &errorLine, &errorColumn);
    if (result) {
#else
    QDomDocument::ParseResult result = doc.setContent(document);
    if (document.isEmpty() || result) {
#endif
        propagateTranslationDomain(doc, d->m_textTagNames);
        setDOMDocument(doc, merge);
    } else {
#if QT_VERSION < QT_VERSION_CHECK(6, 5, 0)
        qCritical() << "Error parsing XML document:" << errorMsg << "at line" << errorLine << "column" << errorColumn;
#else
        qCritical() << "Error parsing XML document:" << result.errorMessage << "at line" << result.errorLine << "column" << result.errorColumn;
#endif
#ifdef NDEBUG
        setDOMDocument(QDomDocument(), merge); // otherwise empty menus from ui_standards.xmlgui stay around
#else
        abort();
#endif
    }
}

References d, KisKXMLGUIClientPrivate::m_textTagNames, propagateTranslationDomain(), and setDOMDocument().

setXMLFile()

void KisKXMLGUIClient::setXMLFile ( const QString & file, bool merge = false, bool setXMLDoc = true )

protected

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. 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 KF 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 ${KisKXMLGUI_INSTALL_DIR}/componentname in your CMakeLists.txt file, to install the .xmlgui file(s).

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

Compatibility notes: Fallback lookups exist to older locations: DATADIR/componentname/file and DATADIR/file. The latter was there so that setXMLFile("componentname/filename") worked (but this was undocumented). Do not do this anymore after porting to KisKXMLGUI_INSTALL_DIR, use setComponentName("componentname") and setXMLFile("filename").

Definition at line 207 of file kxmlguiclient.cpp.

{
    // store our xml file name
    if (!_file.isNull()) {
        d->m_xmlFile = _file;
    }
 
    if (!setXMLDoc) {
        return;
    }
 
    QString file = _file;
    QStringList allFiles;
    if (!QDir::isRelativePath(file)) {
        allFiles.append(file);
    } else {
        const QString filter = componentName() + QLatin1Char('/') + _file;
 
        // files on filesystem
        allFiles << QStandardPaths::locateAll(QStandardPaths::AppDataLocation, QStringLiteral("kxmlgui5/") + filter); // KF >= 5.1
 
        // KF >= 5.4 (resource file)
        const QString qrcFile(QStringLiteral(":/kxmlgui5/") + filter);
        if (QFile::exists(qrcFile)) {
            allFiles << qrcFile;
        }
 
        // then compat locations
        const QStringList compatFiles =
                   QStandardPaths::locateAll(QStandardPaths::AppDataLocation, filter) + // kdelibs4, KF 5.0
                   QStandardPaths::locateAll(QStandardPaths::AppDataLocation, _file); // kdelibs4, KF 5.0, caller passes component name
 
        if (allFiles.isEmpty() && !compatFiles.isEmpty()) {
            qWarning() << "kxmlguiclient: KisKXMLGUI file found at deprecated location" << compatFiles << "-- please use ${KisKXMLGUI_INSTALL_DIR} to install this file instead.";
        }
        allFiles += compatFiles;
    }
    if (allFiles.isEmpty() && !_file.isEmpty()) {
        // if a non-empty file gets passed and we can't find it,
        // inform the developer using some debug output
        qWarning() << "cannot find .xmlgui file" << _file << "for component" << componentName();
    }
 
    // make sure to merge the settings from any file specified by setLocalXMLFile()
    if (!d->m_localXMLFile.isEmpty() && !file.endsWith(QStringLiteral("ui_standards.xmlgui"))) {
        const bool exists = QDir::isRelativePath(d->m_localXMLFile) || QFile::exists(d->m_localXMLFile);
        if (exists && !allFiles.contains(d->m_localXMLFile)) {
            allFiles.prepend(d->m_localXMLFile);
        }
    }
 
    QString doc;
    if (!allFiles.isEmpty()) {
        file = findMostRecentXMLFile(allFiles, doc);
    }
 
    // Always call setXML, even on error, so that we don't keep all ui_standards.xmlgui menus.
    setXML(doc, merge);
}

References componentName(), d, findMostRecentXMLFile(), KisKXMLGUIClientPrivate::m_localXMLFile, KisKXMLGUIClientPrivate::m_xmlFile, and setXML().

setXMLGUIBuildDocument()

void KisKXMLGUIClient::setXMLGUIBuildDocument

(

const QDomDocument &

doc

)

Definition at line 639 of file kxmlguiclient.cpp.

{
    d->m_buildDocument = doc;
}

References d, and KisKXMLGUIClientPrivate::m_buildDocument.

standardsXmlFileLocation()

QString KisKXMLGUIClient::standardsXmlFileLocation ( )

staticprotected

Return the full path to the ui_standards.xmlgui, might return a resource path.

Returns

full path to ui_standards.xmlgui, always non-empty.

Since

5.16

Definition at line 191 of file kxmlguiclient.cpp.

{
    QString file = QStandardPaths::locate(QStandardPaths::GenericConfigLocation, QStringLiteral("ui/ui_standards.xmlgui"));
    if (file.isEmpty()) {
        // fallback to resource, to allow to use the rc file compiled into this framework, must exist!
        file = QStringLiteral(":/kxmlgui5/ui_standards.xmlgui");
        Q_ASSERT(QFile::exists(file));
    }
    return file;
}

stateChanged()

void KisKXMLGUIClient::stateChanged ( const QString & newstate, KisKXMLGUIClient::ReverseStateChange reverse = StateNoReverse )

protectedvirtual

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

{
    StateChange stateChange = getActionsToChangeForState(newstate);
 
    bool setTrue = (reverse == StateNoReverse);
    bool setFalse = !setTrue;
 
    // Enable actions which need to be enabled...
    //
    for (QStringList::const_iterator it = stateChange.actionsToEnable.constBegin();
            it != stateChange.actionsToEnable.constEnd(); ++it) {
 
        QAction *action = actionCollection()->action(*it);
        if (action) {
            action->setEnabled(setTrue);
        }
    }
 
    // and disable actions which need to be disabled...
    //
    for (QStringList::const_iterator it = stateChange.actionsToDisable.constBegin();
            it != stateChange.actionsToDisable.constEnd(); ++it) {
 
        QAction *action = actionCollection()->action(*it);
        if (action) {
            action->setEnabled(setFalse);
        }
    }
 
}

References action(), KisKActionCollection::action(), actionCollection(), KisKXMLGUIClient::StateChange::actionsToDisable, KisKXMLGUIClient::StateChange::actionsToEnable, getActionsToChangeForState(), and StateNoReverse.

unplugActionList()

void KisKXMLGUIClient::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 712 of file kxmlguiclient.cpp.

{
    if (!d->m_factory) {
        return;
    }
 
    d->m_factory->unplugActionList(this, name);
}

References d, and KisKXMLGUIClientPrivate::m_factory.

virtual_hook()

void KisKXMLGUIClient::virtual_hook ( int id, void * data )

protectedvirtual

Definition at line 806 of file kxmlguiclient.cpp.

{
    /*BASE::virtual_hook( id, data );*/
}

xmlFile()

QString KisKXMLGUIClient::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 0.

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

{
    return d->m_xmlFile;
}

References d, and KisKXMLGUIClientPrivate::m_xmlFile.

xmlguiBuildDocument()

QDomDocument KisKXMLGUIClient::xmlguiBuildDocument

(

)

const

Definition at line 644 of file kxmlguiclient.cpp.

{
    return d->m_buildDocument;
}

References d, and KisKXMLGUIClientPrivate::m_buildDocument.

Friends And Related Symbol Documentation

KDEPrivate::KisKEditToolBarWidget

friend class KDEPrivate::KisKEditToolBarWidget

friend

Definition at line 38 of file kxmlguiclient.h.

Member Data Documentation

d

KisKXMLGUIClientPrivate* const KisKXMLGUIClient::d

private

Definition at line 395 of file kxmlguiclient.h.

---

The documentation for this class was generated from the following files:

• libs/widgetutils/xmlgui/kxmlguiclient.h
• libs/widgetutils/xmlgui/kxmlguiclient.cpp