org.kde.koala

Class KXMLGUIFactory

public class KXMLGUIFactory extends QObject

KXMLGUIFactory, together with KXMLGUIClient 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 KXMLGUIClient represents a part of the GUI, composed from containers and actions. KXMLGUIFactory takes care of building (with the help of a KXMLGUIBuilder) and merging the GUI from an unlimited number of clients. Each client provides XML through a QDomDocument and actions through a KActionCollection . The XML document contains the rules for how to merge the GUI. KXMLGUIFactory 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 KXMLGUIBuilder , which has to be provided with the KXMLGUIFactory constructor. See KXMLGUIFactorySignals for signals emitted by KXMLGUIFactory

UNKNOWN: KXMLGUIFactory, together with KXMLGUIClient objects, can be used to create a GUI of container widgets (like menus, toolbars, etc.

Constructor Summary
protected KXMLGUIFactory(Class dummy)
KXMLGUIFactory(KXMLGUIBuilderInterface builder, QObject parent, String name)
Constructs a KXMLGUIFactory.
KXMLGUIFactory(KXMLGUIBuilderInterface builder, QObject parent)
KXMLGUIFactory(KXMLGUIBuilderInterface builder)
Method Summary
static QDomElementactionPropertiesElement(QDomDocument doc)
Find or create the ActionProperties element, used when saving custom action properties
voidaddClient(KXMLGUIClientInterface client)
Creates the GUI described by the QDomDocument of the client, using the client's actions, and merges it with the previously created GUI.
StringclassName()
intconfigureShortcuts(boolean bAllowLetterShortcuts, boolean bSaveSettings)
Show a standard configure shortcut for every action in this factory.
intconfigureShortcuts(boolean bAllowLetterShortcuts)
intconfigureShortcuts()
QWidgetcontainer(String containerName, KXMLGUIClientInterface client, boolean useTagName)
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.
QWidgetcontainer(String containerName, KXMLGUIClientInterface client)
voiddispose()
Delete the wrapped C++ instance ahead of finalize()
static StringdocumentToXML(QDomDocument doc)
static StringelementToXML(QDomElement elem)
protected voidfinalize()
Deletes the wrapped C++ instance
static QDomElementfindActionByName(QDomElement elem, String sName, boolean create)
Find or create the element for a given action, by name.
booleanisDisposed()
Has the wrapped C++ instance been deleted?
QMetaObjectmetaObject()
static StringreadConfigFile(String filename, boolean never_null, KInstanceInterface instance)
static StringreadConfigFile(String filename, boolean never_null)
static StringreadConfigFile(String filename, KInstanceInterface instance)
static StringreadConfigFile(String filename)
voidremoveClient(KXMLGUIClientInterface 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)
static voidremoveDOMComments(QDomNode node)
Removes all QDomComment objects from the specified node and all its children.
voidreset()
Use this method to free all memory allocated by the KXMLGUIFactory.
voidresetContainer(String containerName, boolean useTagName)
Use this method to free all memory allocated by the KXMLGUIFactory for a specific container, including all child containers and actions.
voidresetContainer(String containerName)
static booleansaveConfigFile(QDomDocument doc, String filename, KInstanceInterface instance)
static booleansaveConfigFile(QDomDocument doc, String filename)
voidunplugActionList(KXMLGUIClientInterface client, String name)

Constructor Detail

KXMLGUIFactory

protected KXMLGUIFactory(Class dummy)

KXMLGUIFactory

public KXMLGUIFactory(KXMLGUIBuilderInterface builder, QObject parent, String name)
Constructs a KXMLGUIFactory. The provided builder KXMLGUIBuilder will be called for creating and removing container widgets, when clients are added/removed from the GUI. Note that the ownership of the given KXMLGUIBuilder object won't be transferred to this KXMLGUIFactory, so you have to take care of deleting it properly.

UNKNOWN: Constructs a KXMLGUIFactory.

KXMLGUIFactory

public KXMLGUIFactory(KXMLGUIBuilderInterface builder, QObject parent)

KXMLGUIFactory

public KXMLGUIFactory(KXMLGUIBuilderInterface builder)

Method Detail

actionPropertiesElement

public static QDomElement actionPropertiesElement(QDomDocument doc)
Find or create the ActionProperties element, used when saving custom action properties

UNKNOWN:

addClient

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

UNKNOWN: Creates the GUI described by the QDomDocument of the client, using the client's actions, and merges it with the previously created GUI.

className

public String className()

configureShortcuts

public int configureShortcuts(boolean bAllowLetterShortcuts, boolean bSaveSettings)
Show a standard configure shortcut for every action in this factory. This slot can be connected dirrectly to the action to configure shortcuts. This is very simple to do that by adding a single line
		 KStdAction.keyBindings( guiFactory(), SLOT("configureShortcuts()"), actionCollection() );
		 

Parameters: bAllowLetterShortcuts Set to false if unmodified alphanumeric keys ('A', '1', etc.) are not permissible shortcuts. bSaveSettings if true, the settings will also be saved back to the uirc file which they were intially read from.

UNKNOWN: Show a standard configure shortcut for every action in this factory.

configureShortcuts

public int configureShortcuts(boolean bAllowLetterShortcuts)

configureShortcuts

public int configureShortcuts()

container

public QWidget container(String containerName, KXMLGUIClientInterface client, boolean useTagName)
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:
		 QPopupMenu popup = (QPopupMenu)(factory().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 null if no container with the given name exists or is not owned by the client.

UNKNOWN: Use this method to get access to a container widget with the name specified with containerName and which is owned by the client.

container

public QWidget container(String containerName, KXMLGUIClientInterface client)

dispose

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

documentToXML

public static String documentToXML(QDomDocument doc)

elementToXML

public static String elementToXML(QDomElement elem)

finalize

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

findActionByName

public static QDomElement findActionByName(QDomElement elem, String sName, boolean create)
Find or create the element for a given action, by name. Used when saving custom action properties

UNKNOWN:

isDisposed

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

metaObject

public QMetaObject metaObject()

readConfigFile

public static String readConfigFile(String filename, boolean never_null, KInstanceInterface instance)

readConfigFile

public static String readConfigFile(String filename, boolean never_null)

readConfigFile

public static String readConfigFile(String filename, KInstanceInterface instance)

readConfigFile

public static String readConfigFile(String filename)

removeClient

public void removeClient(KXMLGUIClientInterface 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)

UNKNOWN: 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)

removeDOMComments

public static void removeDOMComments(QDomNode node)
Removes all QDomComment objects from the specified node and all its children.

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

reset

public void reset()
Use this method to free all memory allocated by the KXMLGUIFactory. 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 KXMLGUIClient.setFactory( null ) for all inserted clients)

UNKNOWN: Use this method to free all memory allocated by the KXMLGUIFactory.

resetContainer

public void resetContainer(String containerName, boolean useTagName)
Use this method to free all memory allocated by the KXMLGUIFactory 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 KXMLGUIClient.setFactory( null ) for all clients of the container)

UNKNOWN: Use this method to free all memory allocated by the KXMLGUIFactory for a specific container, including all child containers and actions.

resetContainer

public void resetContainer(String containerName)

saveConfigFile

public static boolean saveConfigFile(QDomDocument doc, String filename, KInstanceInterface instance)

saveConfigFile

public static boolean saveConfigFile(QDomDocument doc, String filename)

unplugActionList

public void unplugActionList(KXMLGUIClientInterface client, String name)