KisKXMLGUIFactory Class Reference

#include <kxmlguifactory.h>

Inheritance diagram for KisKXMLGUIFactory:

Signals
void	clientAdded (KisKXMLGUIClient *client)
void	clientRemoved (KisKXMLGUIClient *client)
void	makingChanges (bool)

Public Member Functions
void	addClient (KisKXMLGUIClient *client)
QList< KisKXMLGUIClient * >	clients () const
QWidget *	container (const QString &containerName, KisKXMLGUIClient *client, bool useTagName=false)
QList< QWidget * >	containers (const QString &tagName)
	KisKXMLGUIFactory (KisKXMLGUIBuilder *builder, QObject *parent=0)
void	plugActionList (KisKXMLGUIClient *client, const QString &name, const QList< QAction * > &actionList)
void	removeClient (KisKXMLGUIClient *client)
void	reset ()
void	resetContainer (const QString &containerName, bool useTagName=false)
void	unplugActionList (KisKXMLGUIClient *client, const QString &name)
	~KisKXMLGUIFactory () override

Static Public Member Functions
static QDomElement	actionPropertiesElement (QDomDocument &doc)
static QDomElement	findActionByName (QDomElement &elem, const QString &sName, bool create)
static QString	readConfigFile (const QString &filename, const QString &componentName=QString())
static bool	saveConfigFile (const QDomDocument &doc, const QString &filename, const QString &componentName=QString())

Private Member Functions
void	forgetClient (KisKXMLGUIClient *client)
	Internal, called by KisKXMLGUIClient destructor.

Private Attributes
KisKXMLGUIFactoryPrivate *const	d

Friends
class	KisKXMLGUI::BuildHelper
class	KisKXMLGUIClient

Detailed Description

KisKXMLGUIFactory, together with KisKXMLGUIClient objects, can be used to create a GUI of container widgets (like menus, toolbars, etc.) and container items (menu items, toolbar buttons, etc.) from an XML document and action objects.

Each KisKXMLGUIClient represents a part of the GUI, composed from containers and actions. KisKXMLGUIFactory takes care of building (with the help of a KisKXMLGUIBuilder) and merging the GUI from an unlimited number of clients.

Each client provides XML through a QDomDocument and actions through a KisKActionCollection . The XML document contains the rules for how to merge the GUI.

KisKXMLGUIFactory processes the DOM tree provided by a client and plugs in the client's actions, according to the XML and the merging rules of previously inserted clients. Container widgets are built via a KisKXMLGUIBuilder , which has to be provided with the KisKXMLGUIFactory constructor.

Definition at line 51 of file kxmlguifactory.h.

Constructor & Destructor Documentation

KisKXMLGUIFactory()

KisKXMLGUIFactory::KisKXMLGUIFactory ( KisKXMLGUIBuilder * builder, QObject * parent = 0 )

explicit

Constructs a KisKXMLGUIFactory. The provided builder KisKXMLGUIBuilder will be called for creating and removing container widgets, when clients are added/removed from the GUI.

Note that the ownership of the given KisKXMLGUIBuilder object won't be transferred to this KisKXMLGUIFactory, so you have to take care of deleting it properly.

Removes all QDomComment objects from the specified node and all its children.

Definition at line 202 of file kxmlguifactory.cpp.

    : QObject(parent), d(new KisKXMLGUIFactoryPrivate)
{
    d->builder = builder;
    d->guiClient = 0;
    if (d->builder) {
        d->builderContainerTags = d->builder->containerTags();
        d->builderCustomTags = d->builder->customTags();
    }
}

References KisKXMLGUI::BuildState::builder, KisKXMLGUI::BuildState::builderContainerTags, KisKXMLGUI::BuildState::builderCustomTags, KisKXMLGUIBuilder::containerTags(), KisKXMLGUIBuilder::customTags(), d, and KisKXMLGUI::BuildState::guiClient.

~KisKXMLGUIFactory()

KisKXMLGUIFactory::~KisKXMLGUIFactory ( )

override

Destructor

Definition at line 213 of file kxmlguifactory.cpp.

{
    Q_FOREACH (KisKXMLGUIClient *client, d->m_clients) {
        client->setFactory(0L);
    }
    delete d;
}

References d, KisKXMLGUIFactoryPrivate::m_clients, and KisKXMLGUIClient::setFactory().

Member Function Documentation

actionPropertiesElement()

QDomElement KisKXMLGUIFactory::actionPropertiesElement ( QDomDocument & doc )

static

Definition at line 653 of file kxmlguifactory.cpp.

{
    // first, lets see if we have existing properties
    QDomElement elem = findActionPropertiesElement(doc);
 
    // if there was none, create one
    if (elem.isNull()) {
        elem = doc.createElement(QStringLiteral("ActionProperties"));
        doc.documentElement().appendChild(elem);
    }
    return elem;
}

References findActionPropertiesElement().

addClient()

void KisKXMLGUIFactory::addClient

(

KisKXMLGUIClient *

client

)

Creates the GUI described by the QDomDocument of the client, using the client's actions, and merges it with the previously created GUI. This also means that the order in which clients are added to the factory is relevant; assuming that your application supports plugins, you should first add your application to the factory and then the plugin, so that the plugin's UI is merged into the UI of your application, and not the other way round.

Definition at line 221 of file kxmlguifactory.cpp.

{
    debugWidgetUtils << client;
    if (client->factory()) {
        if (client->factory() == this) {
            return;
        } else {
            client->factory()->removeClient(client);    //just in case someone does stupid things ;-)
        }
    }
 
    if (d->emptyState()) {
        Q_EMIT makingChanges(true);
    }
    d->pushState();
 
//    QTime dt; dt.start();
 
    d->guiClient = client;
 
    // add this client to our client list
    if (!d->m_clients.contains(client)) {
        d->m_clients.append(client);
    }
    else {
        debugWidgetUtils << "XMLGUI client already added " << client;
    }
    // Tell the client that plugging in is process and
    //  let it know what builder widget its mainwindow shortcuts
    //  should be attached to.
    client->beginXMLPlug(d->builder->widget());
 
    // try to use the build document for building the client's GUI, as the build document
    // contains the correct container state information (like toolbar positions, sizes, etc.) .
    // if there is non available, then use the "real" document.
    QDomDocument doc = client->xmlguiBuildDocument();
    if (doc.documentElement().isNull()) {
        doc = client->domDocument();
    }
 
    QDomElement docElement = doc.documentElement();
 
    d->m_rootNode->index = -1;
 
    // cache some variables
 
    d->clientName = docElement.attribute(d->attrName);
    d->clientBuilder = client->clientBuilder();
 
    if (d->clientBuilder) {
        d->clientBuilderContainerTags = d->clientBuilder->containerTags();
        d->clientBuilderCustomTags = d->clientBuilder->customTags();
    } else {
        d->clientBuilderContainerTags.clear();
        d->clientBuilderCustomTags.clear();
    }
 
    // load user-defined shortcuts and other action properties
    d->saveDefaultActionProperties(client->actionCollection()->actions());
    if (!doc.isNull()) {
        d->refreshActionProperties(client, client->actionCollection()->actions(), doc);
    }
 
    BuildHelper(*d, d->m_rootNode).build(docElement);
 
    // let the client know that we built its GUI.
    client->setFactory(this);
 
    // call the finalizeGUI method, to fix up the positions of toolbars for example.
    // ### FIXME : obey client builder
    // --- Well, toolbars have a bool "positioned", so it doesn't really matter,
    // if we call positionYourself on all of them each time. (David)
    d->builder->finalizeGUI(d->guiClient);
 
    // reset some variables, for safety
    d->BuildState::reset();
 
    client->endXMLPlug();
 
    d->popState();
 
    Q_EMIT clientAdded(client);
 
    // build child clients
    Q_FOREACH (KisKXMLGUIClient *child, client->childClients()) {
        addClient(child);
    }
 
    if (d->emptyState()) {
        Q_EMIT makingChanges(false);
    }
    /*
        QString unaddedActions;
        Q_FOREACH (KisKActionCollection* ac, KisKActionCollection::allCollections())
          Q_FOREACH (QAction* action, ac->actions())
            if (action->associatedWidgets().isEmpty())
              unaddedActions += action->objectName() + ' ';
 
        if (!unaddedActions.isEmpty())
          qWarning() << "The following actions are not plugged into the gui (shortcuts will not work): " << unaddedActions;
    */
 
//    qDebug() << "addClient took " << dt.elapsed();
}

References KisKXMLGUIClient::actionCollection(), KisKActionCollection::actions(), addClient(), KisKXMLGUIFactoryPrivate::attrName, KisKXMLGUIClient::beginXMLPlug(), KisKXMLGUI::BuildState::builder, KisKXMLGUIClient::childClients(), clientAdded(), KisKXMLGUIClient::clientBuilder(), KisKXMLGUI::BuildState::clientBuilder, KisKXMLGUI::BuildState::clientBuilderContainerTags, KisKXMLGUI::BuildState::clientBuilderCustomTags, KisKXMLGUI::BuildState::clientName, KisKXMLGUIBuilder::containerTags(), KisKXMLGUIBuilder::customTags(), d, debugWidgetUtils, KisKXMLGUIClient::domDocument(), KisKXMLGUIFactoryPrivate::emptyState(), KisKXMLGUIClient::endXMLPlug(), KisKXMLGUIClient::factory(), KisKXMLGUIBuilder::finalizeGUI(), KisKXMLGUI::BuildState::guiClient, KisKXMLGUI::ContainerNode::index, KisKXMLGUI::BuildHelper, KisKXMLGUIFactoryPrivate::m_clients, KisKXMLGUIFactoryPrivate::m_rootNode, makingChanges(), KisKXMLGUIFactoryPrivate::popState(), KisKXMLGUIFactoryPrivate::pushState(), KisKXMLGUIFactoryPrivate::refreshActionProperties(), removeClient(), KisKXMLGUIFactoryPrivate::saveDefaultActionProperties(), KisKXMLGUIClient::setFactory(), KisKXMLGUIBuilder::widget(), and KisKXMLGUIClient::xmlguiBuildDocument().

clientAdded

void KisKXMLGUIFactory::clientAdded ( KisKXMLGUIClient * client )

signal

clientRemoved

void KisKXMLGUIFactory::clientRemoved ( KisKXMLGUIClient * client )

signal

clients()

QList< KisKXMLGUIClient * > KisKXMLGUIFactory::clients

(

)

const

Returns a list of all clients currently added to this factory

Definition at line 445 of file kxmlguifactory.cpp.

{
    return d->m_clients;
}

References d, and KisKXMLGUIFactoryPrivate::m_clients.

container()

QWidget * KisKXMLGUIFactory::container	(	const QString &	containerName,
		KisKXMLGUIClient *	client,
		bool	useTagName = false )

Use this method to get access to a container widget with the name specified with containerName and which is owned by the client. The container name is specified with a "name" attribute in the XML document.

This function is particularly useful for getting hold of a popupmenu defined in an XMLUI file. For instance:

QMenu *popup = static_cast<QMenu*>(guiFactory()->container("my_popup",this));

where "my_popup" is the name of the menu in the XMLUI file, and "this" is XMLGUIClient which owns the popupmenu (e.g. the mainwindow, or the part, or the plugin...)

Parameters

containerName	Name of the container widget
client	Owner of the container widget
useTagName	Specifies whether to compare the specified name with the name attribute or the tag name.

This method may return 0 if no container with the given name exists or is not owned by the client.

Definition at line 450 of file kxmlguifactory.cpp.

{
    d->pushState();
    d->m_containerName = containerName;
    d->guiClient = client;
 
    QWidget *result = d->findRecursive(d->m_rootNode, useTagName);
 
    d->guiClient = 0L;
    d->m_containerName.clear();
 
    d->popState();
 
    return result;
}

References d, KisKXMLGUIFactoryPrivate::findRecursive(), KisKXMLGUI::BuildState::guiClient, KisKXMLGUIFactoryPrivate::m_containerName, KisKXMLGUIFactoryPrivate::m_rootNode, KisKXMLGUIFactoryPrivate::popState(), and KisKXMLGUIFactoryPrivate::pushState().

containers()

QList< QWidget * > KisKXMLGUIFactory::containers

(

const QString &

tagName

)

Definition at line 467 of file kxmlguifactory.cpp.

{
    return d->findRecursive(d->m_rootNode, tagName);
}

References d, KisKXMLGUIFactoryPrivate::findRecursive(), and KisKXMLGUIFactoryPrivate::m_rootNode.

findActionByName()

QDomElement KisKXMLGUIFactory::findActionByName ( QDomElement & elem, const QString & sName, bool create )

static

Definition at line 666 of file kxmlguifactory.cpp.

{
    const QLatin1String attrName("name");
    for (QDomNode it = elem.firstChild(); !it.isNull(); it = it.nextSibling()) {
        QDomElement e = it.toElement();
        if (e.attribute(attrName) == sName) {
            return e;
        }
    }
 
    if (create) {
        QDomElement act_elem = elem.ownerDocument().createElement(QStringLiteral("Action"));
        act_elem.setAttribute(attrName, sName);
        elem.appendChild(act_elem);
        return act_elem;
    }
    return QDomElement();
}

forgetClient()

void KisKXMLGUIFactory::forgetClient ( KisKXMLGUIClient * client )

private

Internal, called by KisKXMLGUIClient destructor.

Definition at line 379 of file kxmlguifactory.cpp.

{
    d->m_clients.removeAll(client);
}

References d, and KisKXMLGUIFactoryPrivate::m_clients.

makingChanges

void KisKXMLGUIFactory::makingChanges ( bool )

signal

Emitted when the factory is currently making changes to the GUI, i.e. adding or removing clients. makingChanges(true) is emitted before any change happens, and makingChanges(false) is emitted after the change is done. This allows e.g. KisKMainWindow to know that the GUI is being changed programmatically and not by the user (so there is no reason to save toolbar settings afterwards).

Since

4.1.3

plugActionList()

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

Definition at line 545 of file kxmlguifactory.cpp.

{
    d->pushState();
    d->guiClient = client;
    d->actionListName = name;
    d->actionList = actionList;
    d->clientName = client->domDocument().documentElement().attribute(d->attrName);
 
    d->m_rootNode->plugActionList(*d);
 
    // Load shortcuts for these new actions
    d->saveDefaultActionProperties(actionList);
    d->refreshActionProperties(client, actionList, client->domDocument());
 
    d->BuildState::reset();
    d->popState();
}

References KisKXMLGUI::BuildState::actionList, KisKXMLGUI::BuildState::actionListName, KisKXMLGUIFactoryPrivate::attrName, KisKXMLGUI::BuildState::clientName, d, KisKXMLGUIClient::domDocument(), KisKXMLGUI::BuildState::guiClient, KisKXMLGUIFactoryPrivate::m_rootNode, KisKXMLGUI::ContainerNode::plugActionList(), KisKXMLGUIFactoryPrivate::popState(), KisKXMLGUIFactoryPrivate::pushState(), KisKXMLGUIFactoryPrivate::refreshActionProperties(), and KisKXMLGUIFactoryPrivate::saveDefaultActionProperties().

readConfigFile()

QString KisKXMLGUIFactory::readConfigFile ( const QString & filename, const QString & componentName = QString() )

static

Definition at line 109 of file kxmlguifactory.cpp.

{
    QString componentName = _componentName.isEmpty() ? QCoreApplication::applicationName() : _componentName;
    QString xml_file;
 
    if (!QDir::isRelativePath(filename)) {
        xml_file = filename;
    } else {
        // KF >= 5.1 (KisKXMLGUI_INSTALL_DIR)
        xml_file = QStandardPaths::locate(QStandardPaths::AppDataLocation, QStringLiteral("kxmlgui5/") + componentName + QLatin1Char('/') + filename);
        if (!QFile::exists(xml_file)) {
            // KF >= 5.4 (resource file)
            xml_file = QStringLiteral(":/kxmlgui5/") + componentName + QLatin1Char('/') + filename;
        }
 
        bool warn = false;
        if (!QFile::exists(xml_file)) {
            // kdelibs4 / KF 5.0 solution
            xml_file = QStandardPaths::locate(QStandardPaths::AppDataLocation, componentName + QLatin1Char('/') + filename);
            warn = true;
        }
 
        if (!QFile::exists(xml_file)) {
            // kdelibs4 / KF 5.0 solution, and the caller includes the component name
            // This was broken (lead to component/component/ in kdehome) and unnecessary
            // (they can specify it with setComponentName instead)
            xml_file = QStandardPaths::locate(QStandardPaths::AppDataLocation, filename);
            warn = true;
        }
 
        if (warn) {
            qWarning() << "kxmlguifactory: KisKXMLGUI file found at deprecated location" << xml_file << "-- please use ${KisKXMLGUI_INSTALL_DIR} to install these files instead.";
        }
    }
 
    QFile file(xml_file);
    if (xml_file.isEmpty() || !file.open(QIODevice::ReadOnly)) {
        qCritical() << "No such XML file" << filename;
        return QString();
    }
 
    QByteArray buffer(file.readAll());
    return QString::fromUtf8(buffer.constData(), buffer.size());
}

removeClient()

void KisKXMLGUIFactory::removeClient

(

KisKXMLGUIClient *

client

)

Removes the GUI described by the client, by unplugging all provided actions and removing all owned containers (and storing container state information in the given client)

Definition at line 384 of file kxmlguifactory.cpp.

{
    //qDebug(260) << client;
 
    // don't try to remove the client's GUI if we didn't build it
    if (!client || client->factory() != this) {
        return;
    }
 
    if (d->emptyState()) {
        Q_EMIT makingChanges(true);
    }
 
    // remove this client from our client list
    d->m_clients.removeAll(client);
 
    // remove child clients first (create a copy of the list just in case the
    // original list is modified directly or indirectly in removeClient())
    const QList<KisKXMLGUIClient *> childClients(client->childClients());
    Q_FOREACH (KisKXMLGUIClient *child, childClients) {
        removeClient(child);
    }
 
    //qDebug(260) << "calling removeRecursive";
 
    d->pushState();
 
    // cache some variables
 
    d->guiClient = client;
    d->clientName = client->domDocument().documentElement().attribute(d->attrName);
    d->clientBuilder = client->clientBuilder();
 
    client->setFactory(0L);
 
    // if we don't have a build document for that client, yet, then create one by
    // cloning the original document, so that saving container information in the
    // DOM tree does not touch the original document.
    QDomDocument doc = client->xmlguiBuildDocument();
    if (doc.documentElement().isNull()) {
        doc = client->domDocument().cloneNode(true).toDocument();
        client->setXMLGUIBuildDocument(doc);
    }
 
    d->m_rootNode->destruct(doc.documentElement(), *d);
 
    // reset some variables
    d->BuildState::reset();
 
    // This will destruct the KAccel object built around the given widget.
    client->prepareXMLUnplug(d->builder->widget());
 
    d->popState();
 
    if (d->emptyState()) {
        Q_EMIT makingChanges(false);
    }
 
    Q_EMIT clientRemoved(client);
}

References KisKXMLGUIFactoryPrivate::attrName, KisKXMLGUI::BuildState::builder, KisKXMLGUIClient::childClients(), KisKXMLGUIClient::clientBuilder(), KisKXMLGUI::BuildState::clientBuilder, KisKXMLGUI::BuildState::clientName, clientRemoved(), d, KisKXMLGUI::ContainerNode::destruct(), KisKXMLGUIClient::domDocument(), KisKXMLGUIFactoryPrivate::emptyState(), KisKXMLGUIClient::factory(), KisKXMLGUI::BuildState::guiClient, KisKXMLGUIFactoryPrivate::m_clients, KisKXMLGUIFactoryPrivate::m_rootNode, makingChanges(), KisKXMLGUIFactoryPrivate::popState(), KisKXMLGUIClient::prepareXMLUnplug(), KisKXMLGUIFactoryPrivate::pushState(), removeClient(), KisKXMLGUIClient::setFactory(), KisKXMLGUIClient::setXMLGUIBuildDocument(), KisKXMLGUIBuilder::widget(), and KisKXMLGUIClient::xmlguiBuildDocument().

reset()

void KisKXMLGUIFactory::reset

(

)

Use this method to free all memory allocated by the KisKXMLGUIFactory. This deletes the internal node tree and therefore resets the internal state of the class. Please note that the actual GUI is NOT touched at all, meaning no containers are deleted nor any actions unplugged. That is something you have to do on your own. So use this method only if you know what you are doing :-)

(also note that this will call KisKXMLGUIClient::setFactory( 0 ) for all inserted clients)

Definition at line 472 of file kxmlguifactory.cpp.

{
    d->m_rootNode->reset();
 
    d->m_rootNode->clearChildren();
}

References KisKXMLGUI::ContainerNode::clearChildren(), d, KisKXMLGUIFactoryPrivate::m_rootNode, and KisKXMLGUI::ContainerNode::reset().

resetContainer()

void KisKXMLGUIFactory::resetContainer	(	const QString &	containerName,
		bool	useTagName = false )

Use this method to free all memory allocated by the KisKXMLGUIFactory for a specific container, including all child containers and actions. This deletes the internal node subtree for the specified container. The actual GUI is not touched, no containers are deleted or any actions unplugged. Use this method only if you know what you are doing :-)

(also note that this will call KisKXMLGUIClient::setFactory( 0 ) for all clients of the container)

Definition at line 479 of file kxmlguifactory.cpp.

{
    if (containerName.isEmpty()) {
        return;
    }
 
    ContainerNode *container = d->m_rootNode->findContainer(containerName, useTagName);
 
    if (!container) {
        return;
    }
 
    ContainerNode *parent = container->parent;
    if (!parent) {
        return;
    }
 
    //  resetInternal( container );
 
    parent->removeChild(container);
}

References container(), d, KisKXMLGUI::ContainerNode::findContainer(), and KisKXMLGUIFactoryPrivate::m_rootNode.

saveConfigFile()

bool KisKXMLGUIFactory::saveConfigFile ( const QDomDocument & doc, const QString & filename, const QString & componentName = QString() )

static

Definition at line 154 of file kxmlguifactory.cpp.

{
    QString componentName = _componentName.isEmpty() ? QCoreApplication::applicationName() : _componentName;
    QString xml_file(filename);
 
    if (QDir::isRelativePath(xml_file))
        xml_file = QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) +
            QStringLiteral("/kxmlgui5/") + componentName + QLatin1Char('/') + filename;
 
    QFileInfo fileInfo(xml_file);
    QDir().mkpath(fileInfo.absolutePath());
    QFile file(xml_file);
    if (xml_file.isEmpty() || !file.open(QIODevice::WriteOnly)) {
        qCritical() << "Could not write to" << filename;
        return false;
    }
 
    // write out our document
 
    QTextStream ts(&file);
    KisPortingUtils::setUtf8OnStream(ts);
    ts << doc;
 
    file.close();
    return true;
}

References KisPortingUtils::setUtf8OnStream().

unplugActionList()

void KisKXMLGUIFactory::unplugActionList	(	KisKXMLGUIClient *	client,
		const QString &	name )

Definition at line 564 of file kxmlguifactory.cpp.

{
    d->pushState();
    d->guiClient = client;
    d->actionListName = name;
    d->clientName = client->domDocument().documentElement().attribute(d->attrName);
 
    d->m_rootNode->unplugActionList(*d);
 
    d->BuildState::reset();
    d->popState();
}

References KisKXMLGUI::BuildState::actionListName, KisKXMLGUIFactoryPrivate::attrName, KisKXMLGUI::BuildState::clientName, d, KisKXMLGUIClient::domDocument(), KisKXMLGUI::BuildState::guiClient, KisKXMLGUIFactoryPrivate::m_rootNode, KisKXMLGUIFactoryPrivate::popState(), KisKXMLGUIFactoryPrivate::pushState(), and KisKXMLGUI::ContainerNode::unplugActionList().

Friends And Related Symbol Documentation

KisKXMLGUI::BuildHelper

friend class KisKXMLGUI::BuildHelper

friend

Definition at line 53 of file kxmlguifactory.h.

KisKXMLGUIClient

friend class KisKXMLGUIClient

friend

Definition at line 180 of file kxmlguifactory.h.

Member Data Documentation

d

KisKXMLGUIFactoryPrivate* const KisKXMLGUIFactory::d

private

Definition at line 184 of file kxmlguifactory.h.

---

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

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