File indexing completed on 2024-05-26 07:50:14

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Simon Hausmann <hausmann@kde.org>
0004     SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KXMLGUICLIENT_H
0010 #define KXMLGUICLIENT_H
0011 
0012 #include <kxmlgui_export.h>
0013 
0014 #include <QStringList>
0015 #include <memory>
0016 
0017 class QDomDocument;
0018 class QDomElement;
0019 class QWidget;
0020 
0021 class QAction;
0022 class KActionCollection;
0023 class KXMLGUIClientPrivate;
0024 class KXMLGUIFactory;
0025 class KXMLGUIBuilder;
0026 
0027 namespace KDEPrivate
0028 {
0029 class KEditToolBarWidget;
0030 }
0031 
0032 /**
0033  * @class KXMLGUIClient kxmlguiclient.h KXMLGUIClient
0034  *
0035  * A KXMLGUIClient can be used with KXMLGUIFactory to create a
0036  * GUI from actions and an XML document, and can be dynamically merged
0037  * with other KXMLGUIClients.
0038  */
0039 class KXMLGUI_EXPORT KXMLGUIClient
0040 {
0041     friend class KDEPrivate::KEditToolBarWidget; // for setXMLFile(3 args)
0042 public:
0043     /**
0044      * Constructs a KXMLGUIClient which can be used with a
0045      * KXMLGUIFactory to create a GUI from actions and an XML document, and
0046      * which can be dynamically merged with other KXMLGUIClients.
0047      */
0048     KXMLGUIClient();
0049 
0050     /**
0051      * Constructs a KXMLGUIClient which can be used with a KXMLGUIFactory
0052      * to create a GUI from actions and an XML document,
0053      * and which can be dynamically merged with other KXMLGUIClients.
0054      *
0055      * This constructor takes an additional @p parent argument, which makes
0056      * the client a child client of the parent.
0057      *
0058      * Child clients are automatically added to the GUI if the parent is added.
0059      *
0060      */
0061     explicit KXMLGUIClient(KXMLGUIClient *parent);
0062 
0063     /**
0064      * Destructs the KXMLGUIClient.
0065      *
0066      * If the client was in a factory, the factory is NOT informed about the client
0067      * being removed. This is a feature, it makes window destruction fast (the xmlgui
0068      * is not updated for every client being deleted), but if you want to simply remove
0069      * one client and to keep using the window, make sure to call factory->removeClient(client)
0070      * before deleting the client.
0071      */
0072     virtual ~KXMLGUIClient();
0073 
0074     /**
0075      * Retrieves an action of the client by name.  If not found, it looks in its child clients.
0076      * This method is provided for convenience, as it uses actionCollection()
0077      * to get the action object.
0078      *
0079      * @since 6.0
0080      */
0081     QAction *action(const QString &name) const;
0082 
0083     /**
0084      * Retrieves an action for a given QDomElement. The default
0085      * implementation uses the "name" attribute to query the action
0086      * object via the other action() method.
0087      */
0088     virtual QAction *action(const QDomElement &element) const;
0089 
0090     /**
0091      * Retrieves the entire action collection for the GUI client.
0092      */
0093     virtual KActionCollection *actionCollection() const;
0094 
0095     /**
0096      * @return The component name for this GUI client.
0097      */
0098     virtual QString componentName() const;
0099 
0100     /**
0101      * @return The parsed XML in a QDomDocument, set by
0102      * setXMLFile() or setXML().
0103      * This document describes the layout of the GUI.
0104      */
0105     virtual QDomDocument domDocument() const;
0106 
0107     /**
0108      * This will return the name of the XML file as set by setXMLFile().
0109      * If setXML() is used directly, then this will return an empty string.
0110      *
0111      * The filename that this returns is obvious for components as each
0112      * component has exactly one XML file.  In non-components, however,
0113      * there are usually two: the global file and the local file.  This
0114      * function doesn't really care about that, though.  It will always
0115      * return the last XML file set.  This, in almost all cases, will
0116      * be the local XML file.
0117      *
0118      * @return The name of the XML file or QString()
0119      */
0120     virtual QString xmlFile() const;
0121 
0122     virtual QString localXMLFile() const;
0123 
0124     /**
0125      * @internal
0126      */
0127     void setXMLGUIBuildDocument(const QDomDocument &doc);
0128     /**
0129      * @internal
0130      */
0131     QDomDocument xmlguiBuildDocument() const;
0132 
0133     /**
0134      * This method is called by the KXMLGUIFactory as soon as the client
0135      * is added to the KXMLGUIFactory's GUI.
0136      */
0137     void setFactory(KXMLGUIFactory *factory);
0138     /**
0139      * Retrieves a pointer to the KXMLGUIFactory this client is
0140      * associated with (will return nullptr if the client's GUI has not been built
0141      * by a KXMLGUIFactory.
0142      */
0143     KXMLGUIFactory *factory() const;
0144 
0145     /**
0146      * KXMLGUIClients can form a simple child/parent object tree. This
0147      * method returns a pointer to the parent client or nullptr if it has no
0148      * parent client assigned.
0149      */
0150     KXMLGUIClient *parentClient() const;
0151 
0152     /**
0153      * Use this method to make a client a child client of another client.
0154      * Usually you don't need to call this method, as it is called
0155      * automatically when using the second constructor, which takes a
0156      * parent argument.
0157      */
0158     void insertChildClient(KXMLGUIClient *child);
0159 
0160     /**
0161      * Removes the given @p child from the client's children list.
0162      */
0163     void removeChildClient(KXMLGUIClient *child);
0164 
0165     /**
0166      * Retrieves a list of all child clients.
0167      */
0168     QList<KXMLGUIClient *> childClients();
0169 
0170     /**
0171      * A client can have an own KXMLGUIBuilder.
0172      * Use this method to assign your builder instance to the client (so that the
0173      * KXMLGUIFactory can use it when building the client's GUI)
0174      *
0175      * Client specific guibuilders are useful if you want to create
0176      * custom container widgets for your GUI.
0177      */
0178     void setClientBuilder(KXMLGUIBuilder *builder);
0179 
0180     /**
0181      * Retrieves the client's GUI builder or nullptr if no client specific
0182      * builder has been assigned via setClientBuilder()
0183      */
0184     KXMLGUIBuilder *clientBuilder() const;
0185 
0186     /**
0187      * Forces this client to re-read its XML resource file.  This is
0188      * intended to be used when you know that the resource file has
0189      * changed and you will soon be rebuilding the GUI. This will only have
0190      * an effect if the client is then removed and re-added to the factory.
0191      *
0192      * This method is only for child clients, do not call it for a mainwindow!
0193      * For a mainwindow, use loadStandardsXmlFile + setXmlFile(xmlFile()) instead.
0194      */
0195     void reloadXML();
0196 
0197     /**
0198      * ActionLists are a way for XMLGUI to support dynamic lists of
0199      * actions.  E.g. if you are writing a file manager, and there is a
0200      * menu file whose contents depend on the mimetype of the file that
0201      * is selected, then you can achieve this using ActionLists. It
0202      * works as follows:
0203      * In your xxxui.rc file ( the one that you set in setXMLFile() / pass to setupGUI()
0204      * ), you put a tag <tt>\<ActionList name="xxx"\></tt>.
0205      *
0206      * Example:
0207      * \code
0208      * <gui name="xxx_part" version="1">
0209      * <MenuBar>
0210      *   <Menu name="file">
0211      *     ...  <!-- some useful actions-->
0212      *     <ActionList name="xxx_file_actionlist" />
0213      *     ...  <!-- even more useful actions-->
0214      *   </Menu>
0215      *   ...
0216      * </MenuBar>
0217      * </gui>
0218      * \endcode
0219      *
0220      * This tag will get expanded to a list of actions.  In the example
0221      * above ( a file manager with a dynamic file menu ), you would call
0222      * \code
0223      * QList<QAction*> file_actions;
0224      * for( ... )
0225      *   if( ... )
0226      *     file_actions.append( cool_action );
0227      * unplugActionList( "xxx_file_actionlist" );
0228      * plugActionList( "xxx_file_actionlist", file_actions );
0229      * \endcode
0230      * every time a file is selected, unselected or ...
0231      *
0232      * \note You should not call KXmlGuiWindow::createGUI() after calling this
0233      *       function.  In fact, that would remove the newly added
0234      *       actionlists again...
0235      * \note Forgetting to call unplugActionList() before
0236      *       plugActionList() would leave the previous actions in the
0237      *       menu too..
0238      * \see unplugActionList()
0239      */
0240     void plugActionList(const QString &name, const QList<QAction *> &actionList);
0241 
0242     /**
0243      * Unplugs the action list \p name from the XMLGUI.
0244      * Calling this removes the specified action list, i.e. this is the
0245      * complement to plugActionList(). See plugActionList() for a more
0246      * detailed example.
0247      * \see plugActionList()
0248      */
0249     void unplugActionList(const QString &name);
0250 
0251     static QString findMostRecentXMLFile(const QStringList &files, QString &doc);
0252 
0253     void addStateActionEnabled(const QString &state, const QString &action);
0254 
0255     void addStateActionDisabled(const QString &state, const QString &action);
0256 
0257     enum ReverseStateChange { StateNoReverse, StateReverse };
0258     struct StateChange {
0259         QStringList actionsToEnable;
0260         QStringList actionsToDisable;
0261     };
0262 
0263     StateChange getActionsToChangeForState(const QString &state);
0264 
0265     void beginXMLPlug(QWidget *);
0266     void endXMLPlug();
0267     void prepareXMLUnplug(QWidget *);
0268 
0269     /**
0270      * Sets a new xmlFile() and localXMLFile(). The purpose of this public
0271      * method is to allow non-inherited objects to replace the ui definition
0272      * of an embedded client with a customized version. It corresponds to the
0273      * usual calls to setXMLFile() and setLocalXMLFile().
0274      *
0275      * @param xmlfile The xml file to use. Contrary to setXMLFile(), this
0276      *                must be an absolute file path.
0277      * @param localxmlfile The local xml file to set. This should be the full path
0278      *                    to a writeable file, usually using QStandardPaths::writableLocation.
0279      *                    You can set this to QString(), but no user changes to shortcuts / toolbars
0280      *                    will be possible in this case.
0281      * @param merge Whether to merge with the global document
0282      *
0283      * @note If in any doubt whether you need this or not, use setXMLFile()
0284      *       and setLocalXMLFile(), instead of this function.
0285      * @note Just like setXMLFile(), this function has to be called before
0286      *       the client is added to a KXMLGUIFactory in order to have an
0287      *       effect.
0288      *
0289      * @see setLocalXMLFile()
0290      * @since 4.4
0291      */
0292     void replaceXMLFile(const QString &xmlfile, const QString &localxmlfile, bool merge = false);
0293 
0294     /**
0295      * Returns the version number of the given xml data (belonging to an xml rc file)
0296      *
0297      * @since 5.73
0298      */
0299     static QString findVersionNumber(const QString &xml);
0300 
0301 protected:
0302     /**
0303      * Sets the component name for this part.
0304      *
0305      * Call this first in the inherited class constructor.
0306      * (At least before setXMLFile().)
0307      * @param componentName the name of the directory where the XMLGUI files will be found
0308      * @param componentDisplayName a user-visible name (e.g. for the toolbar editor)
0309      */
0310     virtual void setComponentName(const QString &componentName, const QString &componentDisplayName);
0311 
0312     /**
0313      * Sets the name of the rc file containing the XML for the part.
0314      *
0315      * Call this in the inherited class constructor, for parts and plugins.
0316      * @note For mainwindows, don't call this, pass the name of the xml file
0317      * to KXmlGuiWindow::setupGUI() or KXmlGuiWindow::createGUI().
0318      *
0319      * @param file Either an absolute path for the file, or simply the
0320      *             filename. See below for details.
0321      *             If you pass an absolute path here, make sure to also call
0322      *             setLocalXMLFile, otherwise toolbar editing won't work.
0323      * @param merge Whether to merge with the global document.
0324      * @param setXMLDoc Specify whether to call setXML. Default is true.
0325      *
0326      * The preferred way to call this method is with a simple filename for the @p file argument.
0327      *
0328      * Since KF 5.1, the file will then be assumed to be installed in DATADIR/kxmlgui5/, under a directory
0329      * named after the component name.
0330      * You should use ${KDE_INSTALL_KXMLGUIDIR}/componentname in your CMakeLists.txt file, to install
0331      * the .rc file(s).
0332      *
0333      * Since KF 5.4, the file will then be assumed to be installed in a Qt resource in :/kxmlgui5/,
0334      * under a directory named after the component name.
0335      **/
0336     virtual void setXMLFile(const QString &file, bool merge = false, bool setXMLDoc = true);
0337 
0338     /**
0339      * Return the full path to the ui_standards.rc, might return a resource path.
0340      * @return full path to ui_standards.rc, always non-empty.
0341      * @since 5.16
0342      */
0343     static QString standardsXmlFileLocation();
0344 
0345     /**
0346      * Load the ui_standards.rc file. Usually followed by setXMLFile(xmlFile, true), for merging.
0347      * @since 4.6
0348      */
0349     void loadStandardsXmlFile();
0350 
0351     /**
0352      * Set the full path to the "local" xml file, the one used for saving
0353      * toolbar and shortcut changes. You normally don't need to call this,
0354      * if you pass a simple filename to setXMLFile.
0355      */
0356     virtual void setLocalXMLFile(const QString &file);
0357 
0358     /**
0359      * Sets the XML for the part.
0360      *
0361      * Call this in the Part-inherited class constructor if you
0362      *  don't call setXMLFile().
0363      **/
0364     virtual void setXML(const QString &document, bool merge = false);
0365 
0366     /**
0367      * Sets the Document for the part, describing the layout of the GUI.
0368      *
0369      * Call this in the Part-inherited class constructor if you don't call
0370      * setXMLFile() or setXML().
0371      *
0372      * @warning Using this method is not recommended. Many code paths
0373      * lead to reloading from the XML file on disk. And editing toolbars requires
0374      * that the result is written to disk anyway, and loaded from there the next time.
0375      *
0376      * For application-specific changes to a client's XML, it is a better idea to
0377      * save the modified dom document to an app/default-client.xml and define a local-xml-file
0378      * to something specific like app/local-client.xml, using replaceXMLFile().
0379      * See kdepimlibs/kontactinterface/plugin.cpp for an example.
0380      */
0381     virtual void setDOMDocument(const QDomDocument &document, bool merge = false);
0382 
0383     /**
0384      * Actions can collectively be assigned a "State". To accomplish this
0385      * the respective actions are tagged as \<enable\> or \<disable\> in
0386      * a \<State\> \</State\> group of the XMLfile. During program execution the
0387      * programmer can call stateChanged() to set actions to a defined state.
0388      *
0389      * @param newstate Name of a State in the XMLfile.
0390      * @param reverse If the flag reverse is set to StateReverse, the State is reversed.
0391      * (actions to be enabled will be disabled and action to be disabled will be enabled)
0392      * Default is reverse=false.
0393      */
0394     virtual void stateChanged(const QString &newstate, ReverseStateChange reverse = StateNoReverse);
0395 
0396     // KDE5 TODO: virtual void loadActionLists() {}, called when the guiclient is added to the xmlgui factory
0397 
0398 protected:
0399     virtual void virtual_hook(int id, void *data);
0400 
0401 private:
0402     // TODO  Post KF 5.79 make std::unique_ptr, when there is a Konsole released with bug:432421 fixed
0403     // std::unique_ptr<KXMLGUIClientPrivate> const d;
0404     KXMLGUIClientPrivate *const d;
0405 };
0406 
0407 #endif