summaryrefslogtreecommitdiffabout
path: root/microkde/kdeui/kxmlguiclient.h
authorzautrix <zautrix>2004-06-26 19:01:18 (UTC)
committer zautrix <zautrix>2004-06-26 19:01:18 (UTC)
commitb9aad1f15dc600e4dbe4c62d3fcced6363188ba3 (patch) (side-by-side diff)
tree2c3d4004fb21c72cba65793859f9bcd8ffd3a49c /microkde/kdeui/kxmlguiclient.h
downloadkdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.zip
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.gz
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.bz2
Initial revision
Diffstat (limited to 'microkde/kdeui/kxmlguiclient.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kdeui/kxmlguiclient.h361
1 files changed, 361 insertions, 0 deletions
diff --git a/microkde/kdeui/kxmlguiclient.h b/microkde/kdeui/kxmlguiclient.h
new file mode 100644
index 0000000..cd74c8e
--- a/dev/null
+++ b/microkde/kdeui/kxmlguiclient.h
@@ -0,0 +1,361 @@
+/* This file is part of the KDE libraries
+ Copyright (C) 2000 Simon Hausmann <hausmann@kde.org>
+ Copyright (C) 2000 Kurt Granroth <granroth@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License version 2 as published by the Free Software Foundation.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+*/
+#ifndef _KXMLGUICLIENT_H
+#define _KXMLGUICLIENT_H
+
+
+//US #include <qdom.h>
+#include <qptrlist.h>
+#include <qmap.h>
+#include <qstringlist.h>
+
+class QWidget;
+class KAction;
+class KActionCollection;
+class KInstance;
+
+class KXMLGUIClientPrivate;
+class KXMLGUIFactory;
+class KXMLGUIBuilder;
+
+/**
+ *
+ * A KXMLGUIClient can be used with @ref KXMLGUIFactory to create a
+ * GUI from actions and an XML document, and can be dynamically merged
+ * with other KXMLGUIClients.
+ */
+class KXMLGUIClient
+{
+ friend class KEditToolbarWidget; // for setXMLFile(3 args)
+public:
+ /**
+ * Constructs a KXMLGUIClient which can be used with a
+ * @ref KXMLGUIFactory to create a GUI from actions and an XML document, and
+ * which can be dynamically merged with other KXMLGUIClients.
+ */
+ KXMLGUIClient();
+
+ /**
+ * Constructs a KXMLGUIClient which can be used with a @ref 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 @p 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.
+ *
+ */
+ KXMLGUIClient( KXMLGUIClient *parent );
+
+ /**
+ * Destructs the KXMLGUIClient.
+ */
+ virtual ~KXMLGUIClient();
+
+ /**
+ * 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 @ref #actionCollection()
+ * to get the action object.
+ */
+ KAction* action( const char* name ) const;
+
+ /**
+ * Retrieves an action for a given @ref QDomElement. The default
+ * implementation uses the "name" attribute to query the action
+ * object via the other action() method.
+ */
+//US virtual KAction *action( const QDomElement &element ) const;
+
+ /**
+ * Retrieves the entire action collection for the GUI client
+ */
+ virtual KActionCollection* actionCollection() const;
+
+ /**
+ * @return The instance (@ref KInstance) for this part.
+ */
+//US virtual KInstance *instance() const;
+
+ /**
+ * @return The parsed XML in a @ref QDomDocument, set by @ref
+ * setXMLFile() or @ref setXML().
+ * This document describes the layout of the GUI.
+ */
+//US virtual QDomDocument domDocument() const;
+
+ /**
+ * This will return the name of the XML file as set by @ref #setXMLFile().
+ * If @ref #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.
+ *
+ * @return The name of the XML file or QString::null
+ */
+//US virtual QString xmlFile() const;
+
+//US virtual QString localXMLFile() const;
+
+ /**
+ * @internal
+ */
+//US void setXMLGUIBuildDocument( const QDomDocument &doc );
+ /**
+ * @internal
+ */
+//US QDomDocument xmlguiBuildDocument() const;
+
+ /**
+ * This method is called by the @ref KXMLGUIFactory as soon as the client
+ * is added to the KXMLGUIFactory's GUI.
+ */
+//US void setFactory( KXMLGUIFactory *factory );
+ /**
+ * Retrieves a pointer to the @ref KXMLGUIFactory this client is
+ * associated with (will return 0L if the client's GUI has not been built
+ * by a KXMLGUIFactory.
+ */
+//US KXMLGUIFactory *factory() 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.
+ */
+ KXMLGUIClient *parentClient() const;
+
+ /**
+ * 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
+ * arent argument.
+ */
+ void insertChildClient( KXMLGUIClient *child );
+
+ /**
+ * Removes the given @p child from the client's children list.
+ */
+ void removeChildClient( KXMLGUIClient *child );
+
+ /**
+ * Retrieves a list of all child clients.
+ */
+ const QPtrList<KXMLGUIClient> *childClients();
+
+ /**
+ * A client can have an own @ref KXMLGUIBuilder.
+ * Use this method to assign your builder instance to the client (so that the
+ * @ref 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.
+ */
+//US void setClientBuilder( KXMLGUIBuilder *builder );
+
+ /**
+ * Retrieves the client's GUI builder or 0L if no client specific
+ * builder has been assigned via @ref #setClientBuilder()
+ */
+//US KXMLGUIBuilder *clientBuilder() const;
+
+ /**
+ * 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.
+ */
+//US void reloadXML();
+
+ /**
+ * 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 @ref setXMLFile()
+ * ), you put an <ActionList name="xxx"> tag. E.g.
+ * \verbatim
+ * <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>
+ * \endverbatim
+ *
+ * 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
+ * \code
+ * QPtrList<KAction> file_actions;
+ * for( ... )
+ * if( ... )
+ * file_actions.append( cool_action );
+ * unplugActionList( "xxx_file_actionlist" );
+ * plugActionList( "xxx_file_actionlist", file_actions );
+ * \endcode
+ * 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..
+ */
+ void plugActionList( const QString &name, const QPtrList<KAction> &actionList );
+
+ /**
+ * The complement of \ref plugActionList() ...
+ */
+ void unplugActionList( const QString &name );
+
+//US static QString findMostRecentXMLFile( const QStringList &files, QString &doc );
+
+ void addStateActionEnabled(const QString& state, const QString& action);
+
+ void addStateActionDisabled(const QString& state, const QString& action);
+
+ enum ReverseStateChange { StateNoReverse, StateReverse };
+ struct StateChange
+ {
+ QStringList actionsToEnable;
+ QStringList actionsToDisable;
+ };
+
+ StateChange getActionsToChangeForState(const QString& state);
+
+ /// @since 3.1
+//US void beginXMLPlug( QWidget * );
+ /// @since 3.1
+//US void endXMLPlug();
+ /// @since 3.1
+//US void prepareXMLUnplug( QWidget * );
+
+protected:
+ /**
+ * Returns true if client was added to super client list.
+ * Returns false if client was already in list.
+ */
+ //bool addSuperClient( KXMLGUIClient * );
+
+ /**
+ * Sets the instance (@ref KInstance) for this part.
+ *
+ * Call this first in the inherited class constructor.
+ * (At least before @ref setXMLFile().)
+ */
+//US virtual void setInstance( KInstance *instance );
+
+ /**
+ * Sets the name of the rc file containing the XML for the part.
+ *
+ * Call this in the Part-inherited class constructor.
+ *
+ * @param 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.
+ * @param setXML Specify whether to call setXML. Default is true.
+ * and the DOM document at once.
+ **/
+//US virtual void setXMLFile( const QString& file, bool merge = false, bool setXMLDoc = true );
+
+//US virtual void setLocalXMLFile( const QString &file );
+
+ /**
+ * Sets the XML for the part.
+ *
+ * Call this in the Part-inherited class constructor if you
+ * don't call @ref setXMLFile().
+ **/
+//US virtual void setXML( const QString &document, bool merge = false );
+
+ /**
+ * 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
+ * @ref setXMLFile or @ref setXML .
+ */
+//US virtual void setDOMDocument( const QDomDocument &document, bool merge = false );
+
+ /**
+ * 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).
+ */
+//US virtual void conserveMemory();
+
+ /**
+ * 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.
+ *
+ * @param newstate Name of a State in the XMLfile.
+ * @param 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.
+ */
+ virtual void stateChanged(const QString &newstate, ReverseStateChange reverse = StateNoReverse);
+
+ // Use this one for KDE 4.0
+ //virtual void stateChanged(const QString &newstate, bool reverse = false);
+
+private:
+/*US
+ struct DocStruct
+ {
+ QString file;
+ QString data;
+ };
+
+ bool mergeXML( QDomElement &base, const QDomElement &additive,
+ KActionCollection *actionCollection );
+
+ QDomElement findMatchingElement( const QDomElement &base,
+ const QDomElement &additive );
+*/
+ typedef QMap<QString, QMap<QString, QString> > ActionPropertiesMap;
+
+//US static ActionPropertiesMap extractActionProperties( const QDomDocument &doc );
+
+//US static void storeActionProperties( QDomDocument &doc, const ActionPropertiesMap &properties );
+
+//US static QString findVersionNumber( const QString &_xml );
+
+ // Actions to enable/disable on a state change
+ QMap<QString,StateChange> m_actionsStateMap;
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ KXMLGUIClientPrivate *d;
+};
+
+#endif