File indexing completed on 2024-07-21 03:44:52

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
0004     SPDX-FileCopyrightText: 2006 Hamish Rodda <rodda@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KEDITTOOLBAR_H
0010 #define KEDITTOOLBAR_H
0011 
0012 #include <QDialog>
0013 #include <memory>
0014 
0015 #include <kxmlgui_export.h>
0016 
0017 class KActionCollection;
0018 
0019 class KEditToolBarPrivate;
0020 class KXMLGUIFactory;
0021 /**
0022  * @class KEditToolBar kedittoolbar.h KEditToolBar
0023  *
0024  * @short A dialog used to customize or configure toolbars.
0025  *
0026  * This dialog only works if your application uses the XML UI
0027  * framework for creating menus and toolbars.  It depends on the XML
0028  * files to describe the toolbar layouts and it requires the actions
0029  * to determine which buttons are active.
0030  *
0031  * Typically you do not need to use it directly as KXmlGuiWindow::setupGUI
0032  * takes care of it.
0033  *
0034  * If you use KXMLGUIClient::plugActionList() you need to overload
0035  * KXmlGuiWindow::saveNewToolbarConfig() to plug actions again:
0036  *
0037  * \code
0038  * void MyClass::saveNewToolbarConfig()
0039  * {
0040  *   KXmlGuiWindow::saveNewToolbarConfig();
0041  *   plugActionList( "list1", list1Actions );
0042  *   plugActionList( "list2", list2Actions );
0043  * }
0044  * \endcode
0045  *
0046  * When created, KEditToolBar takes a KXMLGUIFactory object, and uses it to
0047  * find all of the action collections and XML files (there is one of each for the
0048  * mainwindow, but there could be more, when adding other XMLGUI clients like
0049  * KParts or plugins). The editor aims to be semi-intelligent about where it
0050  * assigns any modifications. In other words, it will not write out part specific
0051  * changes to your application's main XML file.
0052  *
0053  * KXmlGuiWindow and KParts::MainWindow take care of creating KEditToolBar correctly
0054  * and connecting to its newToolBarConfig slot, but if you really really want to do it
0055  * yourself, see the KXmlGuiWindow::configureToolbars() and KXmlGuiWindow::saveNewToolbarConfig() code.
0056  *
0057  * \image html kedittoolbar.png "KEditToolBar (example: usage in KWrite)"
0058  *
0059  * @author Kurt Granroth <granroth@kde.org>
0060  * @maintainer David Faure <faure@kde.org>
0061  */
0062 class KXMLGUI_EXPORT KEditToolBar : public QDialog
0063 {
0064     Q_OBJECT
0065 public:
0066     /**
0067      * Old constructor for apps that do not use components.
0068      * This constructor is somewhat deprecated, since it doesn't work
0069      * with any KXMLGuiClient being added to the mainwindow.
0070      * You really want to use the other constructor.
0071      *
0072      * You @em must pass along your collection of actions (some of which appear in your toolbars).
0073      *
0074      * @param collection The collection of actions to work on.
0075      * @param parent The parent of the dialog.
0076      */
0077     explicit KEditToolBar(KActionCollection *collection, QWidget *parent = nullptr);
0078 
0079     /**
0080      * Main constructor.
0081      *
0082      * The main parameter, @p factory, is a pointer to the
0083      * XML GUI factory object for your application.  It contains a list
0084      * of all of the GUI clients (along with the action collections and
0085      * xml files) and the toolbar editor uses that.
0086      *
0087      * Use this like so:
0088      * \code
0089      * KEditToolBar edit(factory());
0090      * if (edit.exec())
0091      * ...
0092      * \endcode
0093      *
0094      * @param factory Your application's factory object
0095      * @param parent The usual parent for the dialog.
0096      */
0097     explicit KEditToolBar(KXMLGUIFactory *factory, QWidget *parent = nullptr);
0098 
0099     /// destructor
0100     ~KEditToolBar() override;
0101 
0102     /**
0103      * Sets the default toolbar that will be selected when the dialog is shown.
0104      * If not set, or QString() is passed in, the global default tool bar name
0105      * will be used.
0106      * @param toolBarName the name of the tool bar
0107      * @see setGlobalDefaultToolBar
0108      */
0109     void setDefaultToolBar(const QString &toolBarName);
0110 
0111     /**
0112      * The name (absolute or relative) of your application's UI resource file
0113      * is assumed to be share/apps/appname/appnameui.rc though this can be
0114      * overridden by calling this method.
0115      *
0116      * The global parameter controls whether or not the
0117      * global resource file is used.  If this is @c true, then you may
0118      * edit all of the actions in your toolbars -- global ones and
0119      * local one.  If it is @c false, then you may edit only your
0120      * application's entries.  The only time you should set this to
0121      * false is if your application does not use the global resource
0122      * file at all (very rare).
0123      *
0124      * @param file The application's local resource file.
0125      * @param global If @c true, then the global resource file will also
0126      *               be parsed.
0127      */
0128     void setResourceFile(const QString &file, bool global = true);
0129 
0130     /**
0131      * Sets the default toolbar which will be auto-selected for all
0132      * KEditToolBar instances. Can be overridden on a per-dialog basis
0133      * by calling setDefaultToolBar( const QString& ) on the dialog.
0134      *
0135      * @param  toolBarName  the name of the tool bar
0136      * @since 6.0
0137      */
0138     static void setGlobalDefaultToolBar(const QString &toolBarName);
0139 
0140 Q_SIGNALS:
0141     /**
0142      * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset.
0143      * Connect to it, to plug action lists and to call applyMainWindowSettings
0144      * (see sample code in this class's documentation)
0145      */
0146     void newToolBarConfig();
0147 
0148 protected:
0149     void showEvent(QShowEvent *event) override;
0150     void hideEvent(QHideEvent *event) override;
0151 
0152 private:
0153     friend class KEditToolBarPrivate;
0154     std::unique_ptr<KEditToolBarPrivate> const d;
0155 
0156     Q_DISABLE_COPY(KEditToolBar)
0157 };
0158 
0159 #endif // _KEDITTOOLBAR_H