• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • kdelibs API Reference
  • KDE Home
  • Contact Us
 

KDEUI

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
KXMLGUIClient Class Reference

#include <kxmlguiclient.h>

Inheritance diagram for KXMLGUIClient:
Inheritance graph
[legend]

Classes

struct  StateChange
 

Public Types

enum  ReverseStateChange { StateNoReverse, StateReverse }
 

Public Member Functions

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

Static Public Member Functions

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

Protected Member Functions

void loadStandardsXmlFile ()
 
virtual void setComponentData (const KComponentData &componentData)
 
virtual void setDOMDocument (const QDomDocument &document, bool merge=false)
 
virtual void setLocalXMLFile (const QString &file)
 
virtual void setXML (const QString &document, bool merge=false)
 
virtual 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)
 

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 46 of file kxmlguiclient.h.

Member Enumeration Documentation

enum KXMLGUIClient::ReverseStateChange
Enumerator
StateNoReverse 
StateReverse 

Definition at line 262 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 82 of file kxmlguiclient.cpp.

KXMLGUIClient::KXMLGUIClient ( KXMLGUIClient *  parent)
explicit

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

KXMLGUIClient::~KXMLGUIClient ( )
virtual

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.

Definition at line 93 of file kxmlguiclient.cpp.

Member Function Documentation

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

QAction * 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 138 of file kxmlguiclient.cpp.

KActionCollection * KXMLGUIClient::actionCollection ( ) const
virtual

Retrieves the entire action collection for the GUI client.

Definition at line 128 of file kxmlguiclient.cpp.

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

Definition at line 687 of file kxmlguiclient.cpp.

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

Definition at line 675 of file kxmlguiclient.cpp.

void KXMLGUIClient::beginXMLPlug ( QWidget *  w)

Definition at line 732 of file kxmlguiclient.cpp.

QList< KXMLGUIClient * > KXMLGUIClient::childClients ( )

Retrieves a list of all child clients.

Definition at line 635 of file kxmlguiclient.cpp.

KXMLGUIBuilder * KXMLGUIClient::clientBuilder ( ) const

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

Definition at line 647 of file kxmlguiclient.cpp.

KComponentData KXMLGUIClient::componentData ( ) const
virtual
Returns
The componentData ( KComponentData ) for this GUI client.

Definition at line 144 of file kxmlguiclient.cpp.

QDomDocument KXMLGUIClient::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 149 of file kxmlguiclient.cpp.

void KXMLGUIClient::endXMLPlug ( )

Definition at line 739 of file kxmlguiclient.cpp.

KXMLGUIFactory * KXMLGUIClient::factory ( ) const

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

Definition at line 602 of file kxmlguiclient.cpp.

QString KXMLGUIClient::findMostRecentXMLFile ( const QStringList &  files,
QString &  doc 
)
static

Definition at line 668 of file kxmlguiclient.cpp.

KXMLGUIClient::StateChange KXMLGUIClient::getActionsToChangeForState ( const QString &  state)

Definition at line 699 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 parent argument.

Definition at line 612 of file kxmlguiclient.cpp.

void KXMLGUIClient::loadStandardsXmlFile ( )
protected

Load the ui_standards.rc file.

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

Since
4.6

Definition at line 192 of file kxmlguiclient.cpp.

QString KXMLGUIClient::localXMLFile ( ) const
virtual

Definition at line 159 of file kxmlguiclient.cpp.

KXMLGUIClient * KXMLGUIClient::parentClient ( ) const

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

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

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

void KXMLGUIClient::prepareXMLUnplug ( QWidget *  w)

Definition at line 743 of file kxmlguiclient.cpp.

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.

Definition at line 174 of file kxmlguiclient.cpp.

void KXMLGUIClient::removeChildClient ( KXMLGUIClient *  child)

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

Definition at line 620 of file kxmlguiclient.cpp.

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

Parameters
xmlfileThe xml file to use. Contrary to setXMLFile(), this must be an absolute file path.
localxmfileThe local xml file to set. This should be the full path to a writeable file, usually inside KStandardDirs::localkdedir(). You can set this to QString(), but no user changes to shortcuts / toolbars will be possible in this case.
See also
setLocalXMLFile()
Parameters
mergeWhether 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 KXMLGUIFactory in order to have an effect.
Since
4.4

Definition at line 247 of file kxmlguiclient.cpp.

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

void KXMLGUIClient::setComponentData ( const KComponentData &  componentData)
protectedvirtual

Returns true if client was added to super client list.

Returns false if client was already in list. Sets the componentData ( KComponentData) for this part.

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

Definition at line 184 of file kxmlguiclient.cpp.

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

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

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

void KXMLGUIClient::setLocalXMLFile ( const QString &  file)
protectedvirtual

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

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

Sets the XML for the part.

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

Definition at line 257 of file kxmlguiclient.cpp.

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

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
fileEither 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 componentData. If you pass an absolute path here, make sure to also call setLocalXMLFile, otherwise toolbar editing won't work.
mergeWhether to merge with the global document.
setXMLDocSpecify whether to call setXML. Default is true.

Definition at line 203 of file kxmlguiclient.cpp.

void KXMLGUIClient::setXMLGUIBuildDocument ( const QDomDocument &  doc)

Definition at line 587 of file kxmlguiclient.cpp.

void KXMLGUIClient::stateChanged ( const QString &  newstate,
KXMLGUIClient::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
newstateName of a State in the XMLfile.
reverseIf 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 705 of file kxmlguiclient.cpp.

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

Definition at line 660 of file kxmlguiclient.cpp.

void KXMLGUIClient::virtual_hook ( int  id,
void *  data 
)
protectedvirtual

Definition at line 750 of file kxmlguiclient.cpp.

QString KXMLGUIClient::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()

Definition at line 154 of file kxmlguiclient.cpp.

QDomDocument KXMLGUIClient::xmlguiBuildDocument ( ) const

Definition at line 592 of file kxmlguiclient.cpp.


The documentation for this class was generated from the following files:
  • kxmlguiclient.h
  • kxmlguiclient.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Jun 22 2020 13:24:03 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KDEUI

Skip menu "KDEUI"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages

kdelibs API Reference

Skip menu "kdelibs API Reference"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDEWebKit
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUnitConversion
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver

Search



Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal