KXMLGUIClient Class Reference

#include <kxmlguiclient.h>

Inheritance diagram for KXMLGUIClient:

Public Types
enum	ReverseStateChange { StateNoReverse , StateReverse }

Public Member Functions
	KXMLGUIClient ()
	KXMLGUIClient (KXMLGUIClient *parent)
virtual	~KXMLGUIClient ()
TDEAction *	action (const char *name) const
virtual TDEAction *	action (const TQDomElement &element) const
virtual TDEActionCollection *	actionCollection () const
virtual TDEInstance *	instance () const
virtual TQDomDocument	domDocument () const
virtual TQString	xmlFile () const
virtual TQString	localXMLFile () const
void	setXMLGUIBuildDocument (const TQDomDocument &doc)
TQDomDocument	xmlguiBuildDocument () const
void	setFactory (KXMLGUIFactory *factory)
KXMLGUIFactory *	factory () const
KXMLGUIClient *	parentClient () const
void	insertChildClient (KXMLGUIClient *child)
void	removeChildClient (KXMLGUIClient *child)
const TQPtrList< KXMLGUIClient > *	childClients ()
void	setClientBuilder (KXMLGUIBuilder *builder)
KXMLGUIBuilder *	clientBuilder () const
void	reloadXML ()
void	plugActionList (const TQString &name, const TQPtrList< TDEAction > &actionList)
void	unplugActionList (const TQString &name)
void	addStateActionEnabled (const TQString &state, const TQString &action)
void	addStateActionDisabled (const TQString &state, const TQString &action)
StateChange	getActionsToChangeForState (const TQString &state)
void	beginXMLPlug (TQWidget *)
void	endXMLPlug ()
void	prepareXMLUnplug (TQWidget *)

Static Public Member Functions
static TQString	findMostRecentXMLFile (const TQStringList &files, TQString &doc)

Protected Member Functions
virtual void	setInstance (TDEInstance *instance)
virtual void	setXMLFile (const TQString &file, bool merge=false, bool setXMLDoc=true)
virtual void	setLocalXMLFile (const TQString &file)
virtual void	setXML (const TQString &document, bool merge=false)
virtual void	setDOMDocument (const TQDomDocument &document, bool merge=false)
virtual void	conserveMemory ()
virtual void	stateChanged (const TQString &newstate, ReverseStateChange reverse=StateNoReverse)
virtual void	virtual_hook (int id, void *data)

Friends
class	KEditToolbarWidget

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

Member Enumeration Documentation

ReverseStateChange

enum KXMLGUIClient::ReverseStateChange

Definition at line 250 of file kxmlguiclient.h.

Constructor & Destructor Documentation

KXMLGUIClient() [1/2]

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

KXMLGUIClient() [2/2]

KXMLGUIClient::KXMLGUIClient

(

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.

Definition at line 72 of file kxmlguiclient.cpp.

~KXMLGUIClient()

KXMLGUIClient::~KXMLGUIClient ( )

virtual

Destructs the KXMLGUIClient.

Definition at line 78 of file kxmlguiclient.cpp.

Member Function Documentation

action() [1/2]

TDEAction * 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 93 of file kxmlguiclient.cpp.

action() [2/2]

TDEAction * KXMLGUIClient::action ( const TQDomElement &  element ) const

virtual

Retrieves an action for a given TQDomElement.

The default implementation uses the "name" attribute to query the action object via the other action() method.

Definition at line 117 of file kxmlguiclient.cpp.

actionCollection()

TDEActionCollection * KXMLGUIClient::actionCollection ( ) const

virtual

Retrieves the entire action collection for the GUI client.

If you subclass KXMLGUIClient you should call TDEActionCollection::setWidget( TQWidget* ) with this object, or you will encounter subtle bugs with TDEAction keyboard shortcuts. This is not necessary if your KXMLGUIClient is a TDEMainWindow.

See also

TDEActionCollection::setWidget( TQWidget* )

Reimplemented in KEditToolbarWidget.

Definition at line 107 of file kxmlguiclient.cpp.

addStateActionDisabled()

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

Definition at line 881 of file kxmlguiclient.cpp.

addStateActionEnabled()

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

Definition at line 869 of file kxmlguiclient.cpp.

beginXMLPlug()

void KXMLGUIClient::beginXMLPlug

(

TQWidget *

w

)

Since

3.1

Definition at line 926 of file kxmlguiclient.cpp.

childClients()

const TQPtrList< KXMLGUIClient > * KXMLGUIClient::childClients

(

)

Retrieves a list of all child clients.

Definition at line 588 of file kxmlguiclient.cpp.

clientBuilder()

KXMLGUIBuilder * KXMLGUIClient::clientBuilder

(

)

const

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

Definition at line 600 of file kxmlguiclient.cpp.

conserveMemory()

void KXMLGUIClient::conserveMemory ( )

protectedvirtual

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

Definition at line 534 of file kxmlguiclient.cpp.

domDocument()

TQDomDocument KXMLGUIClient::domDocument ( ) const

virtual

Returns

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

Definition at line 128 of file kxmlguiclient.cpp.

endXMLPlug()

void KXMLGUIClient::endXMLPlug

(

)

Since

3.1

Definition at line 934 of file kxmlguiclient.cpp.

factory()

KXMLGUIFactory * KXMLGUIClient::factory

(

)

const

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.

Definition at line 555 of file kxmlguiclient.cpp.

findMostRecentXMLFile()

TQString KXMLGUIClient::findMostRecentXMLFile ( const TQStringList &  files, TQString &  doc  )

static

Definition at line 621 of file kxmlguiclient.cpp.

getActionsToChangeForState()

KXMLGUIClient::StateChange KXMLGUIClient::getActionsToChangeForState

(

const TQString &

state

)

Definition at line 893 of file kxmlguiclient.cpp.

insertChildClient()

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

instance()

TDEInstance * KXMLGUIClient::instance ( ) const

virtual

Returns

The instance ( TDEInstance ) for this GUI client.

Definition at line 123 of file kxmlguiclient.cpp.

localXMLFile()

TQString KXMLGUIClient::localXMLFile ( ) const

virtual

Definition at line 138 of file kxmlguiclient.cpp.

parentClient()

KXMLGUIClient * KXMLGUIClient::parentClient

(

)

const

KXMLGUIClients can form a simple child/parent object tree.

This method returns a pointer to the parent client or 0L if it has no parent client assigned.

Definition at line 560 of file kxmlguiclient.cpp.

plugActionList()

void KXMLGUIClient::plugActionList	(	const TQString &	name,
		const TQPtrList< TDEAction > &	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() ), you put an

<ActionList name="xxx">

tag. E.g.

* <kpartgui name="xxx_part" version="1">
* <MenuBar>
*   <Menu name="file">
*     ...  <!-- some useful actions-->
*     <ActionList name="xxx_file_actionlist" />
*     ...  <!-- even more useful actions-->
*   </Menu>
*   ...
* </MenuBar>
* </kpartgui>
* 

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

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

Definition at line 605 of file kxmlguiclient.cpp.

prepareXMLUnplug()

void KXMLGUIClient::prepareXMLUnplug

(

TQWidget *

)

Since

3.1

Definition at line 942 of file kxmlguiclient.cpp.

reloadXML()

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

Definition at line 150 of file kxmlguiclient.cpp.

removeChildClient()

void KXMLGUIClient::removeChildClient

(

KXMLGUIClient *

child

)

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

Definition at line 573 of file kxmlguiclient.cpp.

setClientBuilder()

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

setDOMDocument()

void KXMLGUIClient::setDOMDocument ( const TQDomDocument &  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 .

Definition at line 224 of file kxmlguiclient.cpp.

setFactory()

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

setInstance()

void KXMLGUIClient::setInstance ( TDEInstance *  instance )

protectedvirtual

Returns true if client was added to super client list.

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

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

Definition at line 157 of file kxmlguiclient.cpp.

setLocalXMLFile()

void KXMLGUIClient::setLocalXMLFile ( const TQString &  file )

protectedvirtual

Definition at line 212 of file kxmlguiclient.cpp.

setXML()

void KXMLGUIClient::setXML ( const TQString &  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 217 of file kxmlguiclient.cpp.

setXMLFile()

void KXMLGUIClient::setXMLFile ( const TQString &  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 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.

Definition at line 165 of file kxmlguiclient.cpp.

setXMLGUIBuildDocument()

void KXMLGUIClient::setXMLGUIBuildDocument

(

const TQDomDocument &

doc

)

Definition at line 540 of file kxmlguiclient.cpp.

stateChanged()

void KXMLGUIClient::stateChanged ( const TQString &  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

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.

Definition at line 899 of file kxmlguiclient.cpp.

unplugActionList()

void KXMLGUIClient::unplugActionList

(

const TQString &

name

)

The complement of plugActionList() ...

Definition at line 613 of file kxmlguiclient.cpp.

virtual_hook()

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

protectedvirtual

Definition at line 950 of file kxmlguiclient.cpp.

xmlFile()

TQString 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 TQString::null

Definition at line 133 of file kxmlguiclient.cpp.

xmlguiBuildDocument()

TQDomDocument KXMLGUIClient::xmlguiBuildDocument

(

)

const

Definition at line 545 of file kxmlguiclient.cpp.

Friends And Related Function Documentation

KEditToolbarWidget

friend class KEditToolbarWidget

friend

Definition at line 45 of file kxmlguiclient.h.

---

The documentation for this class was generated from the following files:

• kxmlguiclient.h
• kxmlguiclient.cpp