File indexing completed on 2024-04-14 11:13:27

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 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
0149     /**
0150      * This allows you to enable or disable the context menu.
0151      *
0152      * @param enable If false, then the context menu will be disabled
0153      * @deprecated Since 5.0, use setContextMenuPolicy()
0154      */
0155     KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::setContextMenuPolicy(Qt::ContextMenuPolicy)")
0156     void setContextMenuEnabled(bool enable = true);
0157 #endif
0158 
0159 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
0160     /**
0161      * Returns the context menu enabled flag
0162      * @return true if the context menu is disabled
0163      * @deprecated Since 5.0, use contextMenuPolicy()
0164      */
0165     KXMLGUI_DEPRECATED_VERSION(5, 0, "Use QWidget::contextMenuPolicy()")
0166     bool contextMenuEnabled() const;
0167 #endif
0168 
0169     /**
0170      * Save the toolbar settings to group @p cg.
0171      */
0172     void saveSettings(KConfigGroup &cg);
0173 
0174     /**
0175      * Read the toolbar settings from group @p cg
0176      * and apply them.
0177      */
0178     void applySettings(const KConfigGroup &cg);
0179 
0180 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(5, 0)
0181     /**
0182      * Sets the XML gui client.
0183      * @deprecated Since 5.0, use addXMLGUIClient()
0184      */
0185     KXMLGUI_DEPRECATED_VERSION(5, 0, "Use KToolBar::addXMLGUIClient(KXMLGUIClient *)")
0186     void setXMLGUIClient(KXMLGUIClient *client);
0187 #endif
0188 
0189     /**
0190      * Adds an XML gui client that uses this toolbar
0191      * @since 4.8.1
0192      */
0193     void addXMLGUIClient(KXMLGUIClient *client);
0194 
0195     /**
0196      * Removes an XML gui client that uses this toolbar
0197      * @since 4.8.5
0198      */
0199     void removeXMLGUIClient(KXMLGUIClient *client);
0200 
0201     /**
0202      * Load state from an XML @param element, called by KXMLGUIBuilder.
0203      */
0204     void loadState(const QDomElement &element);
0205 
0206     /**
0207      * Save state into an XML @param element, called by KXMLGUIBuilder.
0208      */
0209     void saveState(QDomElement &element) const;
0210 
0211     /**
0212      * Reimplemented to support context menu activation on disabled tool buttons.
0213      */
0214     bool eventFilter(QObject *watched, QEvent *event) override;
0215 
0216     /**
0217      * Returns whether the toolbars are currently editable (drag & drop of actions).
0218      */
0219     static bool toolBarsEditable();
0220 
0221     /**
0222      * Enable or disable toolbar editing via drag & drop of actions.  This is
0223      * called by KEditToolBar and should generally be set to disabled whenever
0224      * KEditToolBar is not active.
0225      */
0226     static void setToolBarsEditable(bool editable);
0227 
0228     /**
0229      * Returns whether the toolbars are locked (i.e., moving of the toobars disallowed).
0230      */
0231     static bool toolBarsLocked();
0232 
0233     /**
0234      * Allows you to lock and unlock all toolbars (i.e., disallow/allow moving of the toobars).
0235      */
0236     static void setToolBarsLocked(bool locked);
0237 
0238     /**
0239      * Emits a D-Bus signal to tell all toolbars in all applications, that the user settings have
0240      * changed.
0241      * @since 5.0
0242      */
0243     static void emitToolbarStyleChanged();
0244 
0245 protected Q_SLOTS:
0246     virtual void slotMovableChanged(bool movable);
0247 
0248 protected:
0249     void contextMenuEvent(QContextMenuEvent *) override;
0250     void actionEvent(QActionEvent *) override;
0251 
0252     // Draggable toolbar configuration
0253     void dragEnterEvent(QDragEnterEvent *) override;
0254     void dragMoveEvent(QDragMoveEvent *) override;
0255     void dragLeaveEvent(QDragLeaveEvent *) override;
0256     void dropEvent(QDropEvent *) override;
0257     void mousePressEvent(QMouseEvent *) override;
0258     void mouseMoveEvent(QMouseEvent *) override;
0259     void mouseReleaseEvent(QMouseEvent *) override;
0260 
0261 private:
0262     friend class KToolBarPrivate;
0263     std::unique_ptr<class KToolBarPrivate> const d;
0264 
0265     Q_PRIVATE_SLOT(d, void slotAppearanceChanged())
0266     Q_PRIVATE_SLOT(d, void slotContextRight())
0267     Q_PRIVATE_SLOT(d, void slotContextTextRight())
0268 };
0269 
0270 #endif