kdeui Library API Documentation

kxmlguifactory_p.h

00001 /* This file is part of the KDE libraries
00002    Copyright (C) 2001 Simon Hausmann <hausmann@kde.org>
00003 
00004    This library is free software; you can redistribute it and/or
00005    modify it under the terms of the GNU Library General Public
00006    License as published by the Free Software Foundation; either
00007    version 2 of the License, or (at your option) any later version.
00008 
00009    This library is distributed in the hope that it will be useful,
00010    but WITHOUT ANY WARRANTY; without even the implied warranty of
00011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012    Library General Public License for more details.
00013 
00014    You should have received a copy of the GNU Library General Public License
00015    along with this library; see the file COPYING.LIB.  If not, write to
00016    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017    Boston, MA 02111-1307, USA.
00018 */
00019 #ifndef __kxmlguifactory_p_h__
00020 #define __kxmlguifactory_p_h__
00021 
00022 #include <qstringlist.h>
00023 #include <qmap.h>
00024 #include <qdom.h>
00025 #include <qvaluestack.h>
00026 
00027 #include <kaction.h>
00028 
00029 class QWidget;
00030 class KXMLGUIClient;
00031 class KXMLGUIBuilder;
00032 class KXMLGUIFactory;
00033 
00034 namespace KXMLGUI
00035 {
00036 
00037 struct BuildState;
00038 
00039 class ActionList : public QPtrList<KAction>
00040 {
00041 public:
00042     ActionList() {}
00043     ActionList( const QPtrList<KAction> &rhs )
00044         : QPtrList<KAction>( rhs )
00045     {}
00046     ActionList &operator=( const QPtrList<KAction> &rhs )
00047     { QPtrList<KAction>::operator=( rhs ); return *this; }
00048 
00049     void plug( QWidget *container, int index ) const;
00050     void unplug( QWidget *container ) const;
00051 };
00052 
00053 typedef QPtrListIterator<KAction> ActionListIt;
00054 typedef QMap< QString, ActionList > ActionListMap;
00055 
00056 /*
00057  * This structure is used to know to which client certain actions and custom elements
00058  * (i.e. menu separators) belong.
00059  * We do not only use a ContainerClient per GUIClient but also per merging group.
00060  *
00061  * groupName : Used for grouped merging. Specifies the group name to which these actions/elements
00062  * belong to.
00063  * actionLists : maps from action list name to action list.
00064  * mergingName : The (named) merging point.
00065  *
00066  * A ContainerClient always belongs to a ContainerNode.
00067  */
00068 struct ContainerClient
00069 {
00070     KXMLGUIClient *client;
00071     ActionList actions;
00072     QValueList<int> customElements;
00073     QString groupName; //is empty if no group client
00074     ActionListMap actionLists;
00075     QString mergingName;
00076 };
00077 typedef QPtrList<ContainerClient> ContainerClientList;
00078 typedef QPtrListIterator<ContainerClient> ContainerClientListIt;
00079 
00080 class ContainerNode;
00081 
00082 struct MergingIndex
00083 {
00084     int value; // the actual index value, used as index for plug() or createContainer() calls
00085     QString mergingName; // the name of the merging index (i.e. the name attribute of the
00086                          // Merge or DefineGroup tag)
00087     QString clientName; // the name of the client that defined this index
00088 };
00089 typedef QValueList<MergingIndex> MergingIndexList;
00090 
00091 /*
00092  * Here we store detailed information about a container, its clients (client=a guiclient having actions
00093  * plugged into the container), child nodes, naming information (tagname and name attribute) and
00094  * merging index information, to plug/insert new actions/items a the correct position.
00095  *
00096  * The builder variable is needed for using the proper GUIBuilder for destruction ( to use the same for
00097  * con- and destruction ). The builderCustomTags and builderContainerTags variables are cached values
00098  * of what the corresponding methods of the GUIBuilder which built the container return. The stringlists
00099  * is shared all over the place, so there's no need to worry about memory consumption for these
00100  * variables :-)
00101  *
00102  * The mergingIndices list contains the merging indices ;-) , as defined by <Merge>, <DefineGroup>
00103  * or by <ActionList> tags. The order of these index structures within the mergingIndices list
00104  * is (and has to be) identical with the order in the DOM tree.
00105  *
00106  * Beside the merging indices we have the "real" index of the container. It points to the next free
00107  * position.
00108  * (used when no merging index is used for a certain action, custom element or sub-container)
00109  */
00110 struct ContainerNode
00111 {
00112     ContainerNode( QWidget *_container, const QString &_tagName, const QString &_name,
00113                    ContainerNode *_parent = 0L, KXMLGUIClient *_client = 0L,
00114                    KXMLGUIBuilder *_builder = 0L, int id = -1,
00115                    const QString &_mergingName = QString::null,
00116                    const QString &groupName = QString::null,
00117                    const QStringList &customTags = QStringList(),
00118                    const QStringList &containerTags = QStringList() );
00119 
00120     ContainerNode *parent;
00121     KXMLGUIClient *client;
00122     KXMLGUIBuilder *builder;
00123     QStringList builderCustomTags;
00124     QStringList builderContainerTags;
00125     QWidget *container;
00126     int containerId;
00127 
00128     QString tagName;
00129     QString name;
00130 
00131     QString groupName; //is empty if the container is in no group
00132 
00133     ContainerClientList clients;
00134     QPtrList<ContainerNode> children;
00135 
00136     int index;
00137     MergingIndexList mergingIndices;
00138 
00139     QString mergingName;
00140 
00141     void clearChildren() { children.clear(); }
00142     void removeChild( ContainerNode *child );
00143 
00144     MergingIndexList::Iterator findIndex( const QString &name );
00145     ContainerNode *findContainerNode( QWidget *container );
00146     ContainerNode *findContainer( const QString &_name, bool tag );
00147     ContainerNode *findContainer( const QString &name, const QString &tagName,
00148                                   const QPtrList<QWidget> *excludeList,
00149                                   KXMLGUIClient *currClient );
00150 
00151     ContainerClient *findChildContainerClient( KXMLGUIClient *currentGUIClient, 
00152                                                const QString &groupName, 
00153                                                const MergingIndexList::Iterator &mergingIdx );
00154 
00155     void plugActionList( BuildState &state );
00156     void plugActionList( BuildState &state, const MergingIndexList::Iterator &mergingIdxIt );
00157 
00158     void unplugActionList( BuildState &state );
00159     void unplugActionList( BuildState &state, const MergingIndexList::Iterator &mergingIdxIt );
00160 
00161     void adjustMergingIndices( int offset, const MergingIndexList::Iterator &it );
00162 
00163     bool destruct( QDomElement element, BuildState &state );
00164     void destructChildren( const QDomElement &element, BuildState &state );
00165     QDomElement findElementForChild( const QDomElement &baseElement, 
00166                                      ContainerNode *childNode );
00167     void unplugActions( BuildState &state );
00168     void unplugClient( ContainerClient *client );
00169 
00170     void reset();
00171 
00172     int calcMergingIndex( const QString &mergingName,
00173                           MergingIndexList::Iterator &it,
00174                           BuildState &state,
00175                           bool ignoreDefaultMergingIndex );
00176 };
00177 
00178 typedef QPtrList<ContainerNode> ContainerNodeList;
00179 typedef QPtrListIterator<ContainerNode> ContainerNodeListIt;
00180 
00181 class BuildHelper
00182 {
00183 public:
00184     BuildHelper( BuildState &state, 
00185                  ContainerNode *node );
00186 
00187     void build( const QDomElement &element );
00188 
00189 private:
00190     void processElement( const QDomElement &element );
00191 
00192     void processActionOrCustomElement( const QDomElement &e, bool isActionTag );
00193     bool processActionElement( const QDomElement &e, int idx );
00194     bool processCustomElement( const QDomElement &e, int idx );
00195 
00196     void processStateElement( const QDomElement &element );
00197 
00198     void processMergeElement( const QString &tag, const QString &name, const QDomElement &e );
00199 
00200     void processContainerElement( const QDomElement &e, const QString &tag,
00201                                   const QString &name );
00202 
00203 
00204     QWidget *createContainer( QWidget *parent, int index, const QDomElement &element,
00205                               int &id, KXMLGUIBuilder **builder );
00206 
00207     QStringList customTags;
00208     QStringList containerTags;
00209 
00210     QPtrList<QWidget> containerList;
00211 
00212     ContainerClient *containerClient;
00213 
00214     bool ignoreDefaultMergingIndex;
00215 
00216     BuildState &m_state;
00217 
00218     ContainerNode *parentNode;
00219 };
00220 
00221 struct BuildState
00222 {
00223     BuildState() : guiClient( 0 ), builder( 0 ), clientBuilder( 0 ) {}
00224 
00225     void reset();
00226 
00227     QString clientName;
00228 
00229     QString actionListName;
00230     ActionList actionList;
00231 
00232     KXMLGUIClient *guiClient;
00233 
00234     MergingIndexList::Iterator currentDefaultMergingIt;
00235     MergingIndexList::Iterator currentClientMergingIt;
00236 
00237     KXMLGUIBuilder *builder;
00238     QStringList builderCustomTags;
00239     QStringList builderContainerTags;
00240 
00241     KXMLGUIBuilder *clientBuilder;
00242     QStringList clientBuilderCustomTags;
00243     QStringList clientBuilderContainerTags;
00244 };
00245 
00246 typedef QValueStack<BuildState> BuildStateStack;
00247 
00248 }
00249 
00250 #endif
00251 /* vim: et sw=4
00252  */
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 12:58:05 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001