org.kde.koala
Class KXMLGUIClient

java.lang.Object
  org.kde.koala.KXMLGUIClient

All Implemented Interfaces:

KXMLGUIClientInterface, org.kde.qt.QtSupport

Direct Known Subclasses:

PartBase

public class KXMLGUIClient
extends java.lang.Object
implements org.kde.qt.QtSupport, KXMLGUIClientInterface

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.

Field Summary

static int	StateNoReverse
static int	StateReverse

Constructor Summary

	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.
protected	KXMLGUIClient(java.lang.Class dummy)
	KXMLGUIClient(KXMLGUIClientInterface 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.

Method Summary

KAction	action(org.kde.qt.QDomElement element) Retrieves an action for a given QDomElement.
KAction	action(java.lang.String name) Retrieves an action of the client by name.
KActionCollection	actionCollection() Retrieves the entire action collection for the GUI client.
void	addStateActionDisabled(java.lang.String state, java.lang.String action)
void	addStateActionEnabled(java.lang.String state, java.lang.String action)
void	beginXMLPlug(org.kde.qt.QWidget arg1)
KXMLGUIBuilderInterface	clientBuilder() Retrieves the client's GUI builder or null if no client specific builder has been assigned via setClientBuilder()
protected void	conserveMemory() This function will attempt to give up some memory after the GUI is built.
void	dispose() Delete the wrapped C++ instance ahead of finalize()
org.kde.qt.QDomDocument	domDocument()
void	endXMLPlug()
KXMLGUIFactory	factory() Retrieves a pointer to the KXMLGUIFactory this client is associated with (will return null if the client's GUI has not been built by a KXMLGUIFactory.
protected void	finalize() Deletes the wrapped C++ instance
static java.lang.String	findMostRecentXMLFile(java.lang.String[] files, java.lang.StringBuffer doc)
void	insertChildClient(KXMLGUIClientInterface child) Use this method to make a client a child client of another client.
KInstanceInterface	instance()
boolean	isDisposed() Has the wrapped C++ instance been deleted?
java.lang.String	localXMLFile()
KXMLGUIClientInterface	parentClient() KXMLGUIClients can form a simple child/parent object tree.
void	prepareXMLUnplug(org.kde.qt.QWidget arg1)
void	reloadXML() Forces this client to re-read its XML resource file.
void	removeChildClient(KXMLGUIClientInterface child) Removes the given child from the client's children list.
void	setClientBuilder(KXMLGUIBuilderInterface builder) A client can have an own KXMLGUIBuilder.
protected void	setDOMDocument(org.kde.qt.QDomDocument document)
protected void	setDOMDocument(org.kde.qt.QDomDocument document, boolean merge) Sets the Document for the part, describing the layout of the GUI.
void	setFactory(KXMLGUIFactory factory) This method is called by the KXMLGUIFactory as soon as the client is added to the KXMLGUIFactory's GUI.
protected void	setInstance(KInstanceInterface instance) Sets the instance ( KInstance) for this part.
protected void	setLocalXMLFile(java.lang.String file)
protected void	setXML(java.lang.String document)
protected void	setXML(java.lang.String document, boolean merge) Sets the XML for the part.
protected void	setXMLFile(java.lang.String file)
protected void	setXMLFile(java.lang.String file, boolean merge)
protected void	setXMLFile(java.lang.String file, boolean merge, boolean setXMLDoc) Sets the name of the rc file containing the XML for the part.
void	setXMLGUIBuildDocument(org.kde.qt.QDomDocument doc)
protected void	stateChanged(java.lang.String newstate)
protected void	stateChanged(java.lang.String newstate, int reverse) Actions can collectively be assigned a "State".
void	unplugActionList(java.lang.String name) The complement of plugActionList() ...
java.lang.String	xmlFile() This will return the name of the XML file as set by setXMLFile().
org.kde.qt.QDomDocument	xmlguiBuildDocument()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

StateNoReverse

public static final int StateNoReverse

See Also:

Constant Field Values

StateReverse

public static final int StateReverse

See Also:

Constant Field Values

Constructor Detail

KXMLGUIClient

protected KXMLGUIClient(java.lang.Class dummy)

KXMLGUIClient

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

KXMLGUIClient

public KXMLGUIClient(KXMLGUIClientInterface 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.

Method Detail

action

public KAction action(java.lang.String name)

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.

Specified by:

action in interface KXMLGUIClientInterface

action

public KAction action(org.kde.qt.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.

Specified by:

action in interface KXMLGUIClientInterface

actionCollection

public KActionCollection actionCollection()

Retrieves the entire action collection for the GUI client. If you subclass KXMLGUIClient you should call KActionCollection.setWidget( QWidget ) with this object, or you will encounter subtle bugs with KAction keyboard shortcuts. This is not necessary if your KXMLGUIClient is a KMainWindow.

Specified by:

actionCollection in interface KXMLGUIClientInterface

See Also:

KActionCollection#setWidget(, #org#kde#qt#QWidget*

instance

public KInstanceInterface instance()

Specified by:

instance in interface KXMLGUIClientInterface

Returns:

The instance ( KInstance ) for this GUI client.

domDocument

public org.kde.qt.QDomDocument domDocument()

Specified by:

domDocument in interface KXMLGUIClientInterface

Returns:

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

xmlFile

public java.lang.String xmlFile()

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.

Specified by:

xmlFile in interface KXMLGUIClientInterface

Returns:

The name of the XML file or null

localXMLFile

public java.lang.String localXMLFile()

Specified by:

localXMLFile in interface KXMLGUIClientInterface

setXMLGUIBuildDocument

public void setXMLGUIBuildDocument(org.kde.qt.QDomDocument doc)

Specified by:

setXMLGUIBuildDocument in interface KXMLGUIClientInterface

xmlguiBuildDocument

public org.kde.qt.QDomDocument xmlguiBuildDocument()

Specified by:

xmlguiBuildDocument in interface KXMLGUIClientInterface

setFactory

public void setFactory(KXMLGUIFactory factory)

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

Specified by:

setFactory in interface KXMLGUIClientInterface

factory

public KXMLGUIFactory factory()

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

Specified by:

factory in interface KXMLGUIClientInterface

parentClient

public KXMLGUIClientInterface parentClient()

KXMLGUIClients can form a simple child/parent object tree. This method returns a pointer to the parent client or null if it has no parent client assigned.

Specified by:

parentClient in interface KXMLGUIClientInterface

insertChildClient

public void insertChildClient(KXMLGUIClientInterface 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.

Specified by:

insertChildClient in interface KXMLGUIClientInterface

removeChildClient

public void removeChildClient(KXMLGUIClientInterface child)

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

Specified by:

removeChildClient in interface KXMLGUIClientInterface

setClientBuilder

public void setClientBuilder(KXMLGUIBuilderInterface 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.

Specified by:

setClientBuilder in interface KXMLGUIClientInterface

clientBuilder

public KXMLGUIBuilderInterface clientBuilder()

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

Specified by:

clientBuilder in interface KXMLGUIClientInterface

reloadXML

public void 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. It has no useful effect with non-KParts GUIs, so don't bother using it unless your app is component based.

Specified by:

reloadXML in interface KXMLGUIClientInterface

unplugActionList

public void unplugActionList(java.lang.String name)

The complement of plugActionList() ...

Specified by:

unplugActionList in interface KXMLGUIClientInterface

addStateActionEnabled

public void addStateActionEnabled(java.lang.String state,
                                  java.lang.String action)

Specified by:

addStateActionEnabled in interface KXMLGUIClientInterface

addStateActionDisabled

public void addStateActionDisabled(java.lang.String state,
                                   java.lang.String action)

Specified by:

addStateActionDisabled in interface KXMLGUIClientInterface

beginXMLPlug

public void beginXMLPlug(org.kde.qt.QWidget arg1)

Specified by:

beginXMLPlug in interface KXMLGUIClientInterface

endXMLPlug

public void endXMLPlug()

Specified by:

endXMLPlug in interface KXMLGUIClientInterface

prepareXMLUnplug

public void prepareXMLUnplug(org.kde.qt.QWidget arg1)

Specified by:

prepareXMLUnplug in interface KXMLGUIClientInterface

findMostRecentXMLFile

public static java.lang.String findMostRecentXMLFile(java.lang.String[] files,
                                                     java.lang.StringBuffer doc)

setInstance

protected void setInstance(KInstanceInterface instance)

Sets the instance ( KInstance) for this part. Call this first in the inherited class constructor. (At least before setXMLFile().)

setXMLFile

protected void setXMLFile(java.lang.String file,
                          boolean merge,
                          boolean setXMLDoc)

Sets the name of the rc file containing the XML for the part. Call this in the Part-inherited class constructor.

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

merge - Whether to merge with the global document.

setXMLDoc - Specify whether to call setXML. Default is true. and the DOM document at once.

setXMLFile

protected void setXMLFile(java.lang.String file,
                          boolean merge)

setXMLFile

protected void setXMLFile(java.lang.String file)

setLocalXMLFile

protected void setLocalXMLFile(java.lang.String file)

setXML

protected void setXML(java.lang.String document,
                      boolean merge)

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

setXML

protected void setXML(java.lang.String document)

setDOMDocument

protected void setDOMDocument(org.kde.qt.QDomDocument document,
                              boolean merge)

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 .

setDOMDocument

protected void setDOMDocument(org.kde.qt.QDomDocument document)

conserveMemory

protected void conserveMemory()

This function will attempt to give up some memory after the GUI is built. It should never be used in apps where the GUI may be rebuilt at some later time (components, for instance).

stateChanged

protected void stateChanged(java.lang.String newstate,
                            int reverse)

Actions can collectively be assigned a "State". To accomplish this the respective actions are tagged as \ or \ in a \ \ 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.

stateChanged

protected void stateChanged(java.lang.String newstate)

finalize

protected void finalize()
                 throws java.lang.InternalError

Deletes the wrapped C++ instance

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.InternalError

dispose

public void dispose()

Delete the wrapped C++ instance ahead of finalize()

isDisposed

public boolean isDisposed()

Has the wrapped C++ instance been deleted?