File indexing completed on 2024-12-08 12:26:00
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 */ 0137 static void setGlobalDefaultToolBar(const char *toolBarName); // TODO should be const QString& 0138 0139 Q_SIGNALS: 0140 /** 0141 * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset. 0142 * Connect to it, to plug action lists and to call applyMainWindowSettings 0143 * (see sample code in this class's documentation) 0144 */ 0145 void newToolBarConfig(); 0146 0147 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(4, 0) 0148 /** 0149 * @deprecated Since 4.0, use newToolBarConfig() 0150 */ 0151 KXMLGUI_DEPRECATED_VERSION(4, 0, "Use KEditToolBar::newToolBarConfig()") 0152 QT_MOC_COMPAT void newToolbarConfig(); 0153 #endif 0154 0155 protected: 0156 void showEvent(QShowEvent *event) override; 0157 void hideEvent(QHideEvent *event) override; 0158 0159 private: 0160 friend class KEditToolBarPrivate; 0161 std::unique_ptr<KEditToolBarPrivate> const d; 0162 0163 Q_DISABLE_COPY(KEditToolBar) 0164 }; 0165 0166 #endif // _KEDITTOOLBAR_H