File indexing completed on 2024-02-25 04:05:11

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Reginald Stadlbauer <reggie@kde.org>
0004     SPDX-FileCopyrightText: 1997, 1998 Stephan Kulow <coolo@kde.org>
0005     SPDX-FileCopyrightText: 1997, 1998 Sven Radej <radej@kde.org>
0006     SPDX-FileCopyrightText: 1997, 1998 Mark Donohoe <donohoe@kde.org>
0007     SPDX-FileCopyrightText: 1997, 1998 Matthias Ettrich <ettrich@kde.org>
0008     SPDX-FileCopyrightText: 1999, 2000 Kurt Granroth <granroth@kde.org>
0009     SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org>
0010 
0011     SPDX-License-Identifier: LGPL-2.0-only
0012 */
0013 
0014 #ifndef KTOOLBAR_H
0015 #define KTOOLBAR_H
0016 
0017 #include <kxmlgui_export.h>
0018 
0019 #include <QToolBar>
0020 #include <memory>
0021 
0022 class QDomElement;
0023 
0024 class KConfigGroup;
0025 class KConfig;
0026 class KMainWindow;
0027 class KXMLGUIClient;
0028 
0029 /**
0030  * @class KToolBar ktoolbar.h KToolBar
0031  *
0032  * @short Floatable toolbar with auto resize.
0033  *
0034  * A KDE-style toolbar.
0035  *
0036  * KToolBar can be used as a standalone widget, but KMainWindow
0037  * provides easy factories and management of one or more toolbars.
0038  *
0039  * KToolBar uses a global config group to load toolbar settings on
0040  * construction. It will reread this config group on a
0041  * KApplication::appearanceChanged() signal.
0042  *
0043  * KToolBar respects Kiosk settings (see the KAuthorized namespace in the
0044  * KConfig framework).  In particular, system administrators can prevent users
0045  * from moving toolbars with the "movable_toolbars" action, and from showing or
0046  * hiding toolbars with the "options_show_toolbar" action.  For example, to
0047  * disable both, add the following the application or global configuration:
0048  * @verbatim
0049    [KDE Action Restrictions][$i]
0050    movable_toolbars=false
0051    options_show_toolbar=false
0052    @endverbatim
0053  *
0054  * If you can't depend on KXmlGui but still want to integrate better with KDE,
0055  * you can use QToolBar and:
0056  * - Set ToolButtonStyle to Qt::ToolButtonFollowStyle, this will make QToolBar
0057  *   use the settings for "Main Toolbar"
0058  * - Additionally set QToolBar::setProperty("otherToolbar", true) to use settings
0059  *   for "Other toolbars"; settings from "Other toolbars" will only work on widget
0060  *   styles derived from KStyle
0061  *
0062  * @author Reginald Stadlbauer <reggie@kde.org>
0063  * @author Stephan Kulow <coolo@kde.org>
0064  * @author Sven Radej <radej@kde.org>
0065  * @author Hamish Rodda <rodda@kde.org>
0066  */
0067 class KXMLGUI_EXPORT KToolBar : public QToolBar
0068 {
0069     Q_OBJECT
0070 
0071 public:
0072     /**
0073      * Constructor.
0074      *
0075      * This constructor takes care of adding the toolbar to the mainwindow,
0076      * if @p parent is a QMainWindow.
0077      *
0078      * Normally KDE applications do not call this directly, they either
0079      * call KMainWindow::toolBar(), or they use XML-GUI and specify
0080      * toolbars using XML.
0081      *
0082      * @param parent      The standard toolbar parent (usually a KMainWindow)
0083      * @param isMainToolBar  True for the "main toolbar", false for other toolbars. Different settings apply.
0084      * @param readConfig  whether to apply the configuration (global and application-specific)
0085      */
0086     explicit KToolBar(QWidget *parent, bool isMainToolBar = false, bool readConfig = true);
0087     // KDE5: remove. The one below is preferred so that all debug output from init() shows the right objectName already,
0088     // and so that isMainToolBar() and iconSizeDefault() return correct values during loading too.
0089 
0090     /**
0091      * Constructor.
0092      *
0093      * This constructor takes care of adding the toolbar to the mainwindow,
0094      * if @p parent is a QMainWindow.
0095      *
0096      * Normally KDE applications do not call this directly, they either
0097      * call KMainWindow::toolBar(), or they use XML-GUI and specify
0098      * toolbars using XML.
0099      *
0100      * @param objectName  The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position,
0101      *                    and so that KToolBar can find out if it's the main toolbar.
0102      * @param parent      The standard toolbar parent (usually a KMainWindow)
0103      * @param readConfig  whether to apply the configuration (global and application-specific)
0104      */
0105     explicit KToolBar(const QString &objectName, QWidget *parent, bool readConfig = true);
0106 
0107     /**
0108      * Alternate constructor with additional arguments, e.g. to choose in which area
0109      * the toolbar should be auto-added. This is rarely used in KDE. When using XMLGUI
0110      * you can specify this as an xml attribute instead.
0111      *
0112      * @param objectName  The QObject name of this toolbar, required so that QMainWindow can save and load the toolbar position
0113      * @param parentWindow The window that should be the parent of this toolbar
0114      * @param area        The position of the toolbar. Usually Qt::TopToolBarArea.
0115      * @param newLine     If true, start a new line in the dock for this toolbar.
0116      * @param isMainToolBar  True for the "main toolbar", false for other toolbars. Different settings apply.
0117      * @param readConfig  whether to apply the configuration (global and application-specific)
0118      */
0119     KToolBar(const QString &objectName,
0120              QMainWindow *parentWindow,
0121              Qt::ToolBarArea area,
0122              bool newLine = false,
0123              bool isMainToolBar = false,
0124              bool readConfig = true); // KDE5: remove, I don't think anyone is using this.
0125 
0126     /**
0127      * Destroys the toolbar.
0128      */
0129     ~KToolBar() override;
0130 
0131     /**
0132      * Returns the main window that this toolbar is docked with.
0133      */
0134     KMainWindow *mainWindow() const;
0135 
0136     /**
0137      * Convenience function to set icon size
0138      */
0139     void setIconDimensions(int size);
0140 
0141     /**
0142      * Returns the default size for this type of toolbar.
0143      *
0144      * @return the default size for this type of toolbar.
0145      */
0146     int iconSizeDefault() const; // KDE5: hide from public API. Doesn't make sense to export this, and it isn't used.
0147 
0148     /**
0149      * Save the toolbar settings to group @p cg.
0150      */
0151     void saveSettings(KConfigGroup &cg);
0152 
0153     /**
0154      * Read the toolbar settings from group @p cg
0155      * and apply them.
0156      */
0157     void applySettings(const KConfigGroup &cg);
0158 
0159     /**
0160      * Adds an XML gui client that uses this toolbar
0161      * @since 4.8.1
0162      */
0163     void addXMLGUIClient(KXMLGUIClient *client);
0164 
0165     /**
0166      * Removes an XML gui client that uses this toolbar
0167      * @since 4.8.5
0168      */
0169     void removeXMLGUIClient(KXMLGUIClient *client);
0170 
0171     /**
0172      * Load state from an XML @param element, called by KXMLGUIBuilder.
0173      */
0174     void loadState(const QDomElement &element);
0175 
0176     /**
0177      * Save state into an XML @param element, called by KXMLGUIBuilder.
0178      */
0179     void saveState(QDomElement &element) const;
0180 
0181     /**
0182      * Reimplemented to support context menu activation on disabled tool buttons.
0183      */
0184     bool eventFilter(QObject *watched, QEvent *event) override;
0185 
0186     /**
0187      * Returns whether the toolbars are currently editable (drag & drop of actions).
0188      */
0189     static bool toolBarsEditable();
0190 
0191     /**
0192      * Enable or disable toolbar editing via drag & drop of actions.  This is
0193      * called by KEditToolBar and should generally be set to disabled whenever
0194      * KEditToolBar is not active.
0195      */
0196     static void setToolBarsEditable(bool editable);
0197 
0198     /**
0199      * Returns whether the toolbars are locked (i.e., moving of the toobars disallowed).
0200      */
0201     static bool toolBarsLocked();
0202 
0203     /**
0204      * Allows you to lock and unlock all toolbars (i.e., disallow/allow moving of the toobars).
0205      */
0206     static void setToolBarsLocked(bool locked);
0207 
0208     /**
0209      * Emits a D-Bus signal to tell all toolbars in all applications, that the user settings have
0210      * changed.
0211      * @since 5.0
0212      */
0213     static void emitToolbarStyleChanged();
0214 
0215 protected Q_SLOTS:
0216     virtual void slotMovableChanged(bool movable);
0217 
0218 protected:
0219     void contextMenuEvent(QContextMenuEvent *) override;
0220     void actionEvent(QActionEvent *) override;
0221 
0222     // Draggable toolbar configuration
0223     void dragEnterEvent(QDragEnterEvent *) override;
0224     void dragMoveEvent(QDragMoveEvent *) override;
0225     void dragLeaveEvent(QDragLeaveEvent *) override;
0226     void dropEvent(QDropEvent *) override;
0227     void mousePressEvent(QMouseEvent *) override;
0228     void mouseMoveEvent(QMouseEvent *) override;
0229     void mouseReleaseEvent(QMouseEvent *) override;
0230 
0231 private:
0232     friend class KToolBarPrivate;
0233     std::unique_ptr<class KToolBarPrivate> const d;
0234 
0235     Q_PRIVATE_SLOT(d, void slotAppearanceChanged())
0236     Q_PRIVATE_SLOT(d, void slotContextRight())
0237     Q_PRIVATE_SLOT(d, void slotContextTextRight())
0238 };
0239 
0240 #endif