File indexing completed on 2024-12-01 03:44:32

 /*
     This file is part of the KDE libraries
     SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
     SPDX-FileCopyrightText: 2006 Hamish Rodda <rodda@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-only
 */
 
 #ifndef KEDITTOOLBAR_H
 #define KEDITTOOLBAR_H
 
 #include <QDialog>
 #include <memory>
 
 #include <kxmlgui_export.h>
 
 class KActionCollection;
 
 class KEditToolBarPrivate;
 class KXMLGUIFactory;
 /**
  * @class KEditToolBar kedittoolbar.h KEditToolBar
  *
  * @short A dialog used to customize or configure toolbars.
  *
  * This dialog only works if your application uses the XML UI
  * framework for creating menus and toolbars.  It depends on the XML
  * files to describe the toolbar layouts and it requires the actions
  * to determine which buttons are active.
  *
  * Typically you do not need to use it directly as KXmlGuiWindow::setupGUI
  * takes care of it.
  *
  * If you use KXMLGUIClient::plugActionList() you need to overload
  * KXmlGuiWindow::saveNewToolbarConfig() to plug actions again:
  *
  * \code
  * void MyClass::saveNewToolbarConfig()
  * {
  *   KXmlGuiWindow::saveNewToolbarConfig();
  *   plugActionList( "list1", list1Actions );
  *   plugActionList( "list2", list2Actions );
  * }
  * \endcode
  *
  * When created, KEditToolBar takes a KXMLGUIFactory object, and uses it to
  * find all of the action collections and XML files (there is one of each for the
  * mainwindow, but there could be more, when adding other XMLGUI clients like
  * KParts or plugins). The editor aims to be semi-intelligent about where it
  * assigns any modifications. In other words, it will not write out part specific
  * changes to your application's main XML file.
  *
  * KXmlGuiWindow and KParts::MainWindow take care of creating KEditToolBar correctly
  * and connecting to its newToolBarConfig slot, but if you really really want to do it
  * yourself, see the KXmlGuiWindow::configureToolbars() and KXmlGuiWindow::saveNewToolbarConfig() code.
  *
  * \image html kedittoolbar.png "KEditToolBar (example: usage in KWrite)"
  *
  * @author Kurt Granroth <granroth@kde.org>
  * @maintainer David Faure <faure@kde.org>
  */
 class KXMLGUI_EXPORT KEditToolBar : public QDialog
 {
     Q_OBJECT
 public:
     /**
      * Old constructor for apps that do not use components.
      * This constructor is somewhat deprecated, since it doesn't work
      * with any KXMLGuiClient being added to the mainwindow.
      * You really want to use the other constructor.
      *
      * You @em must pass along your collection of actions (some of which appear in your toolbars).
      *
      * @param collection The collection of actions to work on.
      * @param parent The parent of the dialog.
      */
     explicit KEditToolBar(KActionCollection *collection, QWidget *parent = nullptr);
 
     /**
      * Main constructor.
      *
      * The main parameter, @p factory, is a pointer to the
      * XML GUI factory object for your application.  It contains a list
      * of all of the GUI clients (along with the action collections and
      * xml files) and the toolbar editor uses that.
      *
      * Use this like so:
      * \code
      * KEditToolBar edit(factory());
      * if (edit.exec())
      * ...
      * \endcode
      *
      * @param factory Your application's factory object
      * @param parent The usual parent for the dialog.
      */
     explicit KEditToolBar(KXMLGUIFactory *factory, QWidget *parent = nullptr);
 
     /// destructor
     ~KEditToolBar() override;
 
     /**
      * Sets the default toolbar that will be selected when the dialog is shown.
      * If not set, or QString() is passed in, the global default tool bar name
      * will be used.
      * @param toolBarName the name of the tool bar
      * @see setGlobalDefaultToolBar
      */
     void setDefaultToolBar(const QString &toolBarName);
 
     /**
      * The name (absolute or relative) of your application's UI resource file
      * is assumed to be share/apps/appname/appnameui.rc though this can be
      * overridden by calling this method.
      *
      * The global parameter controls whether or not the
      * global resource file is used.  If this is @c true, then you may
      * edit all of the actions in your toolbars -- global ones and
      * local one.  If it is @c false, then you may edit only your
      * application's entries.  The only time you should set this to
      * false is if your application does not use the global resource
      * file at all (very rare).
      *
      * @param file The application's local resource file.
      * @param global If @c true, then the global resource file will also
      *               be parsed.
      */
     void setResourceFile(const QString &file, bool global = true);
 
     /**
      * Sets the default toolbar which will be auto-selected for all
      * KEditToolBar instances. Can be overridden on a per-dialog basis
      * by calling setDefaultToolBar( const QString& ) on the dialog.
      *
      * @param  toolBarName  the name of the tool bar
      * @since 6.0
      */
     static void setGlobalDefaultToolBar(const QString &toolBarName);
 
 Q_SIGNALS:
     /**
      * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset.
      * Connect to it, to plug action lists and to call applyMainWindowSettings
      * (see sample code in this class's documentation)
      */
     void newToolBarConfig();
 
 protected:
     void showEvent(QShowEvent *event) override;
     void hideEvent(QHideEvent *event) override;
 
 private:
     friend class KEditToolBarPrivate;
     std::unique_ptr<KEditToolBarPrivate> const d;
 
     Q_DISABLE_COPY(KEditToolBar)
 };
 
 #endif // _KEDITTOOLBAR_H