home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kxmlguiclient.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  11.8 KB  |  368 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 2000 Simon Hausmann <hausmann@kde.org>
  3.    Copyright (C) 2000 Kurt Granroth <granroth@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License version 2 as published by the Free Software Foundation.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19. #ifndef _KXMLGUICLIENT_H
  20. #define _KXMLGUICLIENT_H
  21.  
  22. #include <qdom.h>
  23. #include <qptrlist.h>
  24. #include <qmap.h>
  25. #include <qstringlist.h>
  26.  
  27. #include <kdelibs_export.h>
  28.  
  29. class QWidget;
  30. class KAction;
  31. class KActionCollection;
  32. class KInstance;
  33. class KXMLGUIClientPrivate;
  34. class KXMLGUIFactory;
  35. class KXMLGUIBuilder;
  36.  
  37. /**
  38.  *
  39.  * A KXMLGUIClient can be used with KXMLGUIFactory to create a
  40.  * GUI from actions and an XML document, and can be dynamically merged
  41.  * with other KXMLGUIClients.
  42.  */
  43. class KDEUI_EXPORT KXMLGUIClient
  44. {
  45.     friend class KEditToolbarWidget; // for setXMLFile(3 args)
  46. public:
  47.   /**
  48.    * Constructs a KXMLGUIClient which can be used with a
  49.    * KXMLGUIFactory to create a GUI from actions and an XML document, and
  50.    * which can be dynamically merged with other KXMLGUIClients.
  51.    */
  52.   KXMLGUIClient();
  53.  
  54.   /**
  55.    * Constructs a KXMLGUIClient which can be used with a KXMLGUIFactory
  56.    * to create a GUI from actions and an XML document,
  57.    * and which can be dynamically merged with other KXMLGUIClients.
  58.    *
  59.    * This constructor takes an additional @p parent argument, which makes
  60.    * the client a child client of the parent.
  61.    *
  62.    * Child clients are automatically added to the GUI if the parent is added.
  63.    *
  64.    */
  65.   KXMLGUIClient( KXMLGUIClient *parent );
  66.  
  67.   /**
  68.    * Destructs the KXMLGUIClient.
  69.    */
  70.   virtual ~KXMLGUIClient();
  71.  
  72.   /**
  73.    * Retrieves an action of the client by name.  If not found, it looks in its child clients.
  74.    * This method is provided for convenience, as it uses actionCollection()
  75.    * to get the action object.
  76.    */
  77.   KAction* action( const char* name ) const;
  78.  
  79.   /**
  80.    * Retrieves an action for a given QDomElement. The default
  81.    * implementation uses the "name" attribute to query the action
  82.    * object via the other action() method.
  83.    */
  84.   virtual KAction *action( const QDomElement &element ) const;
  85.  
  86.   /**
  87.    * Retrieves the entire action collection for the GUI client. If
  88.    * you subclass KXMLGUIClient you should call
  89.    * KActionCollection::setWidget( QWidget* ) with this object, or
  90.    * you will encounter subtle bugs with KAction keyboard shortcuts.
  91.    * This is not necessary if your KXMLGUIClient is a KMainWindow.
  92.    *
  93.    * @see KActionCollection::setWidget( QWidget* )
  94.    */
  95.   virtual KActionCollection* actionCollection() const;
  96.  
  97.   /**
  98.    * @return The instance ( KInstance ) for this GUI client.
  99.    */
  100.   virtual KInstance *instance() const;
  101.  
  102.   /**
  103.    * @return The parsed XML in a QDomDocument, set by
  104.    * setXMLFile() or setXML().
  105.    * This document describes the layout of the GUI.
  106.    */
  107.   virtual QDomDocument domDocument() const;
  108.  
  109.   /**
  110.    * This will return the name of the XML file as set by setXMLFile().
  111.    * If setXML() is used directly, then this will return NULL.
  112.    *
  113.    * The filename that this returns is obvious for components as each
  114.    * component has exactly one XML file.  In non-components, however,
  115.    * there are usually two: the global file and the local file.  This
  116.    * function doesn't really care about that, though.  It will always
  117.    * return the last XML file set.  This, in almost all cases, will
  118.    * be the local XML file.
  119.    *
  120.    * @return The name of the XML file or QString::null
  121.    */
  122.   virtual QString xmlFile() const;
  123.  
  124.   virtual QString localXMLFile() const;
  125.  
  126.   /**
  127.    * @internal
  128.    */
  129.   void setXMLGUIBuildDocument( const QDomDocument &doc );
  130.   /**
  131.    * @internal
  132.    */
  133.   QDomDocument xmlguiBuildDocument() const;
  134.  
  135.   /**
  136.    * This method is called by the KXMLGUIFactory as soon as the client
  137.    * is added to the KXMLGUIFactory's GUI.
  138.    */
  139.   void setFactory( KXMLGUIFactory *factory );
  140.   /**
  141.    * Retrieves a pointer to the KXMLGUIFactory this client is
  142.    * associated with (will return 0L if the client's GUI has not been built
  143.    * by a KXMLGUIFactory.
  144.    */
  145.   KXMLGUIFactory *factory() const;
  146.  
  147.   /**
  148.    * KXMLGUIClients can form a simple child/parent object tree. This
  149.    * method returns a pointer to the parent client or 0L if it has no
  150.    * parent client assigned.
  151.    */
  152.   KXMLGUIClient *parentClient() const;
  153.  
  154.   /**
  155.    * Use this method to make a client a child client of another client.
  156.    * Usually you don't need to call this method, as it is called
  157.    * automatically when using the second constructor, which takes a
  158.    * parent argument.
  159.    */
  160.   void insertChildClient( KXMLGUIClient *child );
  161.  
  162.   /**
  163.    * Removes the given @p child from the client's children list.
  164.    */
  165.   void removeChildClient( KXMLGUIClient *child );
  166.  
  167.   /**
  168.    * Retrieves a list of all child clients.
  169.    */
  170.   const QPtrList<KXMLGUIClient> *childClients();
  171.  
  172.   /**
  173.    * A client can have an own KXMLGUIBuilder.
  174.    * Use this method to assign your builder instance to the client (so that the
  175.    * KXMLGUIFactory can use it when building the client's GUI)
  176.    *
  177.    * Client specific guibuilders are useful if you want to create
  178.    * custom container widgets for your GUI.
  179.    */
  180.   void setClientBuilder( KXMLGUIBuilder *builder );
  181.  
  182.   /**
  183.    * Retrieves the client's GUI builder or 0L if no client specific
  184.    * builder has been assigned via setClientBuilder()
  185.    */
  186.   KXMLGUIBuilder *clientBuilder() const;
  187.  
  188.   /**
  189.    * Forces this client to re-read its XML resource file.  This is
  190.    * intended to be used when you know that the resource file has
  191.    * changed and you will soon be rebuilding the GUI.  It has no
  192.    * useful effect with non-KParts GUIs, so don't bother using it
  193.    * unless your app is component based.
  194.    */
  195.   void reloadXML();
  196.  
  197.   /**
  198.    * ActionLists are a way for XMLGUI to support dynamic lists of
  199.    * actions.  E.g. if you are writing a file manager, and there is a
  200.    * menu file whose contents depend on the mimetype of the file that
  201.    * is selected, then you can achieve this using ActionLists. It
  202.    * works as follows:
  203.    * In your xxxui.rc file ( the one that you set in setXMLFile()
  204.    * ), you put an <p>\<ActionList name="xxx"\></p> tag.  E.g.
  205.    * \verbatim
  206.    * <kpartgui name="xxx_part" version="1">
  207.    * <MenuBar>
  208.    *   <Menu name="file">
  209.    *     ...  <!-- some useful actions-->
  210.    *     <ActionList name="xxx_file_actionlist" />
  211.    *     ...  <!-- even more useful actions-->
  212.    *   </Menu>
  213.    *   ...
  214.    * </MenuBar>
  215.    * </kpartgui>
  216.    * \endverbatim
  217.    *
  218.    * This tag will get expanded to a list of actions.  In the example
  219.    * above ( a file manager with a dynamic file menu ), you would call
  220.    * \code
  221.    * QPtrList<KAction> file_actions;
  222.    * for( ... )
  223.    *   if( ... )
  224.    *     file_actions.append( cool_action );
  225.    * unplugActionList( "xxx_file_actionlist" );
  226.    * plugActionList( "xxx_file_actionlist", file_actions );
  227.    * \endcode
  228.    * every time a file is selected, unselected or ...
  229.    *
  230.    * \note You should not call createGUI() after calling this
  231.    *       function.  In fact, that would remove the newly added
  232.    *       actionlists again...
  233.    * \note Forgetting to call unplugActionList() before
  234.    *       plugActionList() would leave the previous actions in the
  235.    *       menu too..
  236.    */
  237.   void plugActionList( const QString &name, const QPtrList<KAction> &actionList );
  238.  
  239.   /**
  240.    * The complement of plugActionList() ...
  241.    */
  242.   void unplugActionList( const QString &name );
  243.  
  244.   static QString findMostRecentXMLFile( const QStringList &files, QString &doc );
  245.  
  246.   void addStateActionEnabled(const QString& state, const QString& action);
  247.  
  248.   void addStateActionDisabled(const QString& state, const QString& action);
  249.  
  250.   enum ReverseStateChange { StateNoReverse, StateReverse };
  251.   struct StateChange
  252.   {
  253.     QStringList actionsToEnable;
  254.     QStringList actionsToDisable;
  255.   };
  256.  
  257.   StateChange getActionsToChangeForState(const QString& state);
  258.  
  259.   /// @since 3.1
  260.   void beginXMLPlug( QWidget * );
  261.   /// @since 3.1
  262.   void endXMLPlug();
  263.   /// @since 3.1
  264.   void prepareXMLUnplug( QWidget * );
  265.  
  266. protected:
  267.   /**
  268.    * Returns true if client was added to super client list.
  269.    * Returns false if client was already in list.
  270.    */
  271.   //bool addSuperClient( KXMLGUIClient * );
  272.  
  273.   /**
  274.    * Sets the instance ( KInstance) for this part.
  275.    *
  276.    * Call this first in the inherited class constructor.
  277.    * (At least before setXMLFile().)
  278.    */
  279.   virtual void setInstance( KInstance *instance );
  280.  
  281.   /**
  282.    * Sets the name of the rc file containing the XML for the part.
  283.    *
  284.    * Call this in the Part-inherited class constructor.
  285.    *
  286.    * @param file Either an absolute path for the file, or simply the
  287.    *             filename, which will then be assumed to be installed
  288.    *             in the "data" resource, under a directory named like
  289.    *             the instance.
  290.    * @param merge Whether to merge with the global document.
  291.    * @param setXMLDoc Specify whether to call setXML. Default is true.
  292.    *               and the DOM document at once.
  293.    **/
  294.   virtual void setXMLFile( const QString& file, bool merge = false, bool setXMLDoc = true );
  295.  
  296.   virtual void setLocalXMLFile( const QString &file );
  297.  
  298.   /**
  299.    * Sets the XML for the part.
  300.    *
  301.    * Call this in the Part-inherited class constructor if you
  302.    *  don't call setXMLFile().
  303.    **/
  304.   virtual void setXML( const QString &document, bool merge = false );
  305.  
  306.   /**
  307.    * Sets the Document for the part, describing the layout of the GUI.
  308.    *
  309.    * Call this in the Part-inherited class constructor if you don't call
  310.    * setXMLFile or setXML .
  311.    */
  312.   virtual void setDOMDocument( const QDomDocument &document, bool merge = false );
  313.  
  314.   /**
  315.    * This function will attempt to give up some memory after the GUI
  316.    * is built.  It should never be used in apps where the GUI may be
  317.    * rebuilt at some later time (components, for instance).
  318.    */
  319.   virtual void conserveMemory();
  320.  
  321.   /**
  322.    * Actions can collectively be assigned a "State". To accomplish this
  323.    * the respective actions are tagged as \<enable\> or \<disable\> in
  324.    * a \<State\> \</State\> group of the XMLfile. During program execution the
  325.    * programmer can call stateChanged() to set actions to a defined state.
  326.    *
  327.    * @param newstate Name of a State in the XMLfile.
  328.    * @param reverse If the flag reverse is set to StateReverse, the State is reversed.
  329.    * (actions to be enabled will be disabled and action to be disabled will be enabled)
  330.    * Default is reverse=false.
  331.    */
  332.    virtual void stateChanged(const QString &newstate, ReverseStateChange reverse = StateNoReverse);
  333.  
  334.    // Use this one for KDE 4.0
  335.    //virtual void stateChanged(const QString &newstate, bool reverse = false);
  336.  
  337. private:
  338.   struct DocStruct
  339.   {
  340.     QString file;
  341.     QString data;
  342.   };
  343.  
  344.   bool mergeXML( QDomElement &base, const QDomElement &additive,
  345.                  KActionCollection *actionCollection );
  346.  
  347.   QDomElement findMatchingElement( const QDomElement &base,
  348.                                    const QDomElement &additive );
  349.  
  350.   typedef QMap<QString, QMap<QString, QString> > ActionPropertiesMap;
  351.  
  352.   static ActionPropertiesMap extractActionProperties( const QDomDocument &doc );
  353.  
  354.   static void storeActionProperties( QDomDocument &doc, const ActionPropertiesMap &properties );
  355.  
  356.   static QString findVersionNumber( const QString &_xml );
  357.  
  358.   // Actions to enable/disable on a state change
  359.   QMap<QString,StateChange> m_actionsStateMap;
  360.  
  361. protected:
  362.   virtual void virtual_hook( int id, void* data );
  363. private:
  364.   KXMLGUIClientPrivate *d;
  365. };
  366.  
  367. #endif
  368.