KDE 4.7 PyKDE API Reference

- KDE's Python API

# KXMLGUIClient Class Reference

`from PyKDE4.kdeui import *`

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

## Enumerations

ReverseStateChange | { StateNoReverse, StateReverse }

## Methods

| __init__ (self, KXMLGUIClient other)
| __init__ (self)
| __init__ (self, KXMLGUIClient parent)
QAction | action (self, QString name)
QAction | action (self, QDomElement element)
KActionCollection | actionCollection (self)
| addStateActionDisabled (self, QString state, QString action)
| addStateActionEnabled (self, QString state, QString action)
| beginXMLPlug (self, QWidget a0)
[KXMLGUIClient] | childClients (self)
KXMLGUIBuilder | clientBuilder (self)
KComponentData | componentData (self)
QDomDocument | domDocument (self)
| endXMLPlug (self)
KXMLGUIFactory | factory (self)
KXMLGUIClient.StateChange | getActionsToChangeForState (self, QString state)
| insertChildClient (self, KXMLGUIClient child)
| loadStandardsXmlFile (self)
QString | localXMLFile (self)
KXMLGUIClient | parentClient (self)
| plugActionList (self, QString name, [QAction] actionList)
| prepareXMLUnplug (self, QWidget a0)
| reloadXML (self)
| removeChildClient (self, KXMLGUIClient child)
| replaceXMLFile (self, QString xmlfile, QString localxmlfile, bool merge=0)
| setClientBuilder (self, KXMLGUIBuilder builder)
| setComponentData (self, KComponentData componentData)
| setDOMDocument (self, QDomDocument document, bool merge=0)
| setFactory (self, KXMLGUIFactory factory)
| setLocalXMLFile (self, QString file)
| setXML (self, QString document, bool merge=0)
| setXMLFile (self, QString file, bool merge=0, bool setXMLDoc=1)
| setXMLGUIBuildDocument (self, QDomDocument doc)
| stateChanged (self, QString newstate, KXMLGUIClient.ReverseStateChange reverse=KXMLGUIClient.StateNoReverse)
| unplugActionList (self, QString name)
QString | xmlFile (self)
QDomDocument | xmlguiBuildDocument (self)

## Static Methods

QString | findMostRecentXMLFile (QStringList files, QString doc)

## Method Documentation

__init__ | ( | self, |
|  | KXMLGUIClient | other
| ) |  |  |

__init__ | ( |  | self ) |

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.

__init__ | ( | self, |
|  | KXMLGUIClient | parent
| ) |  |  |

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.

QAction action | ( | self, |
|  | QString | name
| ) |  |  |

Retrieves an action for a given QDomElement. The default implementation uses the "name" attribute to query the action object via the other action() method.

QAction action | ( | self, |
|  | QDomElement | element
| ) |  |  |

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

Retrieves the entire action collection for the GUI client.

addStateActionDisabled | ( | self, |
|  | QString | state,
|  | QString | action
| ) |  |  |

addStateActionEnabled | ( | self, |
|  | QString | state,
|  | QString | action
| ) |  |  |

beginXMLPlug | ( | self, |
|  | QWidget | a0
| ) |  |  |

[KXMLGUIClient] childClients | ( |  | self ) |

Retrieves a list of all child clients.

KXMLGUIBuilder clientBuilder | ( |  | self ) |

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

KComponentData componentData | ( |  | self ) |

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

QDomDocument domDocument | ( |  | self ) |

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

endXMLPlug | ( |  | self ) |

KXMLGUIFactory factory | ( |  | self ) |

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.

KXMLGUIClient.StateChange getActionsToChangeForState | ( | self, |
|  | QString | state
| ) |  |  |

insertChildClient | ( | self, |
|  | 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.

loadStandardsXmlFile | ( |  | self ) |

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

Since:
  4.6

QString localXMLFile | ( |  | self ) |

KXMLGUIClient parentClient | ( |  | self ) |

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.

plugActionList | ( | self, |
|  | QString | name,
|  | [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 <tt><ActionList name="xxx"></tt>.

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

Note:
  Forgetting to call unplugActionList() before plugActionList() would leave the previous actions in the menu too..

See also:
  unplugActionList()

prepareXMLUnplug | ( | self, |
|  | QWidget | a0
| ) |  |  |

reloadXML | ( |  | self ) |

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.

removeChildClient | ( | self, |
|  | KXMLGUIClient | child
| ) |  |  |

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

replaceXMLFile | ( | self, |
|  | QString | xmlfile,
|  | QString | localxmlfile,
|  | bool | merge=0
| ) |  |  |

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.

  localxmfile

  The 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:

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

setClientBuilder | ( | self, |
|  | 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.

setComponentData | ( | self, |
|  | KComponentData | componentData
| ) |  |  |

Sets the componentData ( KComponentData) for this part.

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

setDOMDocument | ( | self, |
|  | QDomDocument | document,
|  | bool | merge=0
| ) |  |  |

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.

setFactory | ( | self, |
|  | KXMLGUIFactory | factory
| ) |  |  |

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

setLocalXMLFile | ( | self, |
|  | QString | file
| ) |  |  |

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.

setXML | ( | self, |
|  | QString | document,
|  | bool | merge=0
| ) |  |  |

Sets the XML for the part.

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

setXMLFile | ( | self, |
|  | QString | file,
|  | bool | merge=0,
|  | bool | setXMLDoc=1
| ) |  |  |

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, 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.
  | merge | Whether to merge with the global document.
  | setXMLDoc | Specify whether to call setXML. Default is true.

setXMLGUIBuildDocument | ( | self, |
|  | QDomDocument | doc
| ) |  |  |

Internal:

stateChanged | ( | self, |
|  | QString | newstate,
|  | KXMLGUIClient.ReverseStateChange | reverse=KXMLGUIClient.StateNoReverse
| ) |  |  |

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.

unplugActionList | ( | self, |
|  | 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()

QString xmlFile | ( |  | self ) |

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

QDomDocument xmlguiBuildDocument | ( |  | self ) |

Internal:

## Static Method Documentation

QString findMostRecentXMLFile | ( | QStringList | files,
|  | QString | doc
| ) |  |  |

## Enumeration Documentation

ReverseStateChange

Enumerator:

  StateNoReverse |
  StateReverse |