org.kde.koala

Class KEditToolbarWidget

public class KEditToolbarWidget extends QWidget implements KXMLGUIClientInterface

This is the widget that does all of the work for the KEditToolbar dialog. In most cases, you will want to use the dialog instead of this widget directly. Typically, you would use this widget only if you wanted to embed the toolbar editing directly into your existing configure or preferences dialog. This widget only works if your application uses the XML UI framework for creating menus and toolbars. It depends on the XML files to describe the toolbar layouts and it requires the actions to determine which buttons are active. See KEditToolbarWidgetSignals for signals emitted by KEditToolbarWidget

Version: $Id: KEditToolbarWidget.java 473384 2005-10-23 14:17:09Z rdale $

Author: Kurt Granroth

UNKNOWN: A widget used to customize or configure toolbars.

Constructor Summary
protected KEditToolbarWidget(Class dummy)
KEditToolbarWidget(KActionCollection collection, String xmlfile, boolean global, QWidget parent)
Constructor.
KEditToolbarWidget(KActionCollection collection, String xmlfile, boolean global)
KEditToolbarWidget(KActionCollection collection, String xmlfile)
KEditToolbarWidget(KActionCollection collection)
KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file, boolean global, QWidget parent)
KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file, boolean global)
KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file)
KEditToolbarWidget(String defaultToolbar, KActionCollection collection)
KEditToolbarWidget(KXMLGUIFactory factory, QWidget parent)
Constructor for KParts based apps.
KEditToolbarWidget(KXMLGUIFactory factory)
KEditToolbarWidget(String defaultToolbar, KXMLGUIFactory factory, QWidget parent)
KEditToolbarWidget(String defaultToolbar, KXMLGUIFactory factory)
Method Summary
KActionaction(String name)
Retrieves an action of the client by name.
KActionaction(QDomElement element)
Retrieves an action for a given QDomElement.
KActionCollectionactionCollection()
voidaddStateActionDisabled(String state, String action)
voidaddStateActionEnabled(String state, String action)
voidbeginXMLPlug(QWidget arg1)
StringclassName()
KXMLGUIBuilderInterfaceclientBuilder()
Retrieves the client's GUI builder or null if no client specific builder has been assigned via setClientBuilder()
protected voidconserveMemory()
This function will attempt to give up some memory after the GUI is built.
voiddispose()
Delete the wrapped C++ instance ahead of finalize()
QDomDocumentdomDocument()
voidendXMLPlug()
KXMLGUIFactoryfactory()
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 voidfinalize()
Deletes the wrapped C++ instance
static StringfindMostRecentXMLFile(String[] files, StringBuffer doc)
protected voidinitKPart(KXMLGUIFactory factory)
protected voidinitNonKPart(KActionCollection collection, String file, boolean global)
voidinsertChildClient(KXMLGUIClientInterface child)
Use this method to make a client a child client of another client.
KInstanceInterfaceinstance()
booleanisDisposed()
Has the wrapped C++ instance been deleted?
protected voidloadActionList(QDomElement elem)
protected voidloadToolbarCombo(String defaultToolbar)
protected voidloadToolbarCombo()
StringlocalXMLFile()
QMetaObjectmetaObject()
KXMLGUIClientInterfaceparentClient()
KXMLGUIClients can form a simple child/parent object tree.
voidprepareXMLUnplug(QWidget arg1)
voidrebuildKXMLGUIClients()
Remove and readd all KMXLGUIClients to update the GUI
voidreloadXML()
Forces this client to re-read its XML resource file.
voidremoveChildClient(KXMLGUIClientInterface child)
Removes the given child from the client's children list.
booleansave()
Save any changes the user made.
voidsetClientBuilder(KXMLGUIBuilderInterface builder)
A client can have an own KXMLGUIBuilder.
protected voidsetDOMDocument(QDomDocument document, boolean merge)
Sets the Document for the part, describing the layout of the GUI.
protected voidsetDOMDocument(QDomDocument document)
voidsetFactory(KXMLGUIFactory factory)
This method is called by the KXMLGUIFactory as soon as the client is added to the KXMLGUIFactory's GUI.
protected voidsetInstance(KInstanceInterface instance)
Sets the instance ( KInstance) for this part.
protected voidsetLocalXMLFile(String file)
protected voidsetupLayout()
protected voidsetXML(String document, boolean merge)
Sets the XML for the part.
protected voidsetXML(String document)
protected voidsetXMLFile(String file, boolean merge, boolean setXMLDoc)
Sets the name of the rc file containing the XML for the part.
protected voidsetXMLFile(String file, boolean merge)
protected voidsetXMLFile(String file)
voidsetXMLGUIBuildDocument(QDomDocument doc)
protected voidslotActiveSelected(QListViewItem item)
protected voidslotChangeIcon()
protected voidslotDownButton()
protected voidslotDropped(KListView list, QDropEvent e, QListViewItem after)
protected voidslotInactiveSelected(QListViewItem item)
protected voidslotInsertButton()
protected voidslotRemoveButton()
protected voidslotToolbarSelected(String text)
protected voidslotUpButton()
protected voidstateChanged(String newstate, int reverse)
Actions can collectively be assigned a "State".
protected voidstateChanged(String newstate)
voidunplugActionList(String name)
The complement of plugActionList() ...
protected voidupdateLocal(QDomElement elem)
StringxmlFile()
This will return the name of the XML file as set by setXMLFile().
QDomDocumentxmlguiBuildDocument()

Constructor Detail

KEditToolbarWidget

protected KEditToolbarWidget(Class dummy)

KEditToolbarWidget

public KEditToolbarWidget(KActionCollection collection, String xmlfile, boolean global, QWidget parent)
Constructor. This is the only entry point to this class. You must pass along your collection of actions (some of which appear in your toolbars). The other three parameters are optional. The second parameter, xmlfile, is the name (absolute or relative) of your application's UI resource file. If it is left blank, then the resource file: share/apps/appname/appnameui.rc is used. This is the same resource file that is used by the default createGUI function in KMainWindow so you're usually pretty safe in leaving it blank. The third parameter, global, controls whether or not the global resource file is used. If this is true, then you may edit all of the actions in your toolbars -- global ones and local one. If it is false, then you may edit only your application's entries. The only time you should set this to false is if your application does not use the global resource file at all (very rare) The last parameter, parent, is the standard parent stuff.

Parameters: collection The collection of actions to work on xmlfile The application's local resource file global If true, then the global resource file will also be parsed parent This widget's parent

UNKNOWN: Constructor.

KEditToolbarWidget

public KEditToolbarWidget(KActionCollection collection, String xmlfile, boolean global)

KEditToolbarWidget

public KEditToolbarWidget(KActionCollection collection, String xmlfile)

KEditToolbarWidget

public KEditToolbarWidget(KActionCollection collection)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file, boolean global, QWidget parent)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file, boolean global)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KActionCollection collection, String file)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KActionCollection collection)

KEditToolbarWidget

public KEditToolbarWidget(KXMLGUIFactory factory, QWidget parent)
Constructor for KParts based apps. The first parameter, factory, is a pointer to the XML GUI factory object for your application. It contains a list of all of the GUI clients (along with the action collections and xml files) and the toolbar editor uses that. The second parameter, parent, is the standard parent Use this like so:
		 KEditToolbar edit(factory());
		 if ( edit.exec() )
		 ...
		 

Parameters: factory Your application's factory object parent This widget's parent

UNKNOWN: Constructor for KParts based apps.

KEditToolbarWidget

public KEditToolbarWidget(KXMLGUIFactory factory)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KXMLGUIFactory factory, QWidget parent)

KEditToolbarWidget

public KEditToolbarWidget(String defaultToolbar, KXMLGUIFactory factory)

Method Detail

action

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

UNKNOWN: Retrieves an action of the client by name.

action

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

UNKNOWN: Retrieves an action for a given QDomElement.

actionCollection

public KActionCollection actionCollection()

UNKNOWN:

addStateActionDisabled

public void addStateActionDisabled(String state, String action)

addStateActionEnabled

public void addStateActionEnabled(String state, String action)

beginXMLPlug

public void beginXMLPlug(QWidget arg1)

className

public String className()

clientBuilder

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

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

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

UNKNOWN: This function will attempt to give up some memory after the GUI is built.

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()

domDocument

public QDomDocument domDocument()

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

UNKNOWN:

endXMLPlug

public void endXMLPlug()

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.

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

finalize

protected void finalize()
Deletes the wrapped C++ instance

findMostRecentXMLFile

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

initKPart

protected void initKPart(KXMLGUIFactory factory)

initNonKPart

protected void initNonKPart(KActionCollection collection, String file, boolean global)

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.

UNKNOWN: Use this method to make a client a child client of another client.

instance

public KInstanceInterface instance()

Returns: The instance ( KInstance ) for this GUI client.

UNKNOWN:

isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?

loadActionList

protected void loadActionList(QDomElement elem)

loadToolbarCombo

protected void loadToolbarCombo(String defaultToolbar)

loadToolbarCombo

protected void loadToolbarCombo()

localXMLFile

public String localXMLFile()

metaObject

public QMetaObject metaObject()

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.

UNKNOWN: KXMLGUIClients can form a simple child/parent object tree.

prepareXMLUnplug

public void prepareXMLUnplug(QWidget arg1)

rebuildKXMLGUIClients

public void rebuildKXMLGUIClients()
Remove and readd all KMXLGUIClients to update the GUI

UNKNOWN: Remove and readd all KMXLGUIClients to update the GUI

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.

UNKNOWN: Forces this client to re-read its XML resource file.

removeChildClient

public void removeChildClient(KXMLGUIClientInterface child)
Removes the given child from the client's children list.

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

save

public boolean save()
Save any changes the user made. The file will be in the user's local directory (usually $HOME/.kde/share/apps/\). The filename will be the one specified in the constructor.. or the made up one if the filename was NULL.

Returns: The status of whether or not the save succeeded.

UNKNOWN: Save any changes the user made.

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.

UNKNOWN: A client can have an own KXMLGUIBuilder.

setDOMDocument

protected void setDOMDocument(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 .

UNKNOWN: Sets the Document for the part, describing the layout of the GUI.

setDOMDocument

protected void setDOMDocument(QDomDocument document)

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.

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

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

UNKNOWN: Sets the instance ( KInstance) for this part.

setLocalXMLFile

protected void setLocalXMLFile(String file)

setupLayout

protected void setupLayout()

setXML

protected void setXML(String document, boolean merge)
Sets the XML for the part. Call this in the Part-inherited class constructor if you don't call setXMLFile().

UNKNOWN: Sets the XML for the part.

setXML

protected void setXML(String document)

setXMLFile

protected void setXMLFile(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.

UNKNOWN: Sets the name of the rc file containing the XML for the part.

setXMLFile

protected void setXMLFile(String file, boolean merge)

setXMLFile

protected void setXMLFile(String file)

setXMLGUIBuildDocument

public void setXMLGUIBuildDocument(QDomDocument doc)

UNKNOWN:

slotActiveSelected

protected void slotActiveSelected(QListViewItem item)

slotChangeIcon

protected void slotChangeIcon()

slotDownButton

protected void slotDownButton()

slotDropped

protected void slotDropped(KListView list, QDropEvent e, QListViewItem after)

slotInactiveSelected

protected void slotInactiveSelected(QListViewItem item)

slotInsertButton

protected void slotInsertButton()

slotRemoveButton

protected void slotRemoveButton()

slotToolbarSelected

protected void slotToolbarSelected(String text)

slotUpButton

protected void slotUpButton()

stateChanged

protected void stateChanged(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.

UNKNOWN: Actions can collectively be assigned a "State".

stateChanged

protected void stateChanged(String newstate)

unplugActionList

public void unplugActionList(String name)
The complement of plugActionList() ...

UNKNOWN: The complement of plugActionList() .

updateLocal

protected void updateLocal(QDomElement elem)

xmlFile

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

Returns: The name of the XML file or null

UNKNOWN: This will return the name of the XML file as set by setXMLFile().

xmlguiBuildDocument

public QDomDocument xmlguiBuildDocument()

UNKNOWN: