1// -*- mode: c++; c-basic-offset: 2 -*-
2/* This file is part of the KDE libraries
3 Copyright (C) 2000 Kurt Granroth <granroth@kde.org>
4 Copyright (C) 2006 Hamish Rodda <rodda@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License version 2 as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef KEDITTOOLBAR_H
21#define KEDITTOOLBAR_H
22
23#include <kdialog.h>
24
25class KActionCollection;
26
27class KEditToolBarPrivate;
28class KXMLGUIFactory;
29/**
30 * @short A dialog used to customize or configure toolbars.
31 *
32 * This dialog only works if your application uses the XML UI
33 * framework for creating menus and toolbars. It depends on the XML
34 * files to describe the toolbar layouts and it requires the actions
35 * to determine which buttons are active.
36 *
37 * Typically you do not need to use it directly as KXmlGuiWindow::setupGUI
38 * takes care of it.
39 *
40 * If you use plugListAction you need to overload saveNewToolbarConfig()
41 * to plug actions again:
42 *
43 * \code
44 * void MyClass::saveNewToolbarConfig()
45 * {
46 * KXmlGuiWindow::saveNewToolbarConfig();
47 * plugActionList( "list1", list1Actions );
48 * plugActionList( "list2", list2Actions );
49 * }
50 * \endcode
51 *
52 * When created, KEditToolBar takes a KXMLGUIFactory object, and uses it to
53 * find all of the action collections and XML files (there is one of each for the
54 * mainwindow, but there could be more, when adding other XMLGUI clients like
55 * KParts or plugins). The editor aims to be semi-intelligent about where it
56 * assigns any modifications. In other words, it will not write out part specific
57 * changes to your application's main XML file.
58 *
59 * KXmlGuiWindow and KParts::MainWindow take care of creating KEditToolBar correctly
60 * and connecting to its newToolBarConfig slot, but if you really really want to do it
61 * yourself, see the KXmlGuiWindow::configureToolbars() and KXmlGuiWindow::saveNewToolbarConfig() code.
62 *
63 * \image html kedittoolbar.png "KDE Toolbar Editor (KWrite)"
64 *
65 * @author Kurt Granroth <granroth@kde.org>
66 * @maintainer David Faure <faure@kde.org>
67 */
68class KDEUI_EXPORT KEditToolBar : public KDialog
69{
70 Q_OBJECT
71public:
72 /**
73 * Old constructor for apps that do not use components.
74 * This constructor is somewhat deprecated, since it doesn't work
75 * with any KXMLGuiClient being added to the mainwindow.
76 * You really want to use the other constructor.
77 *
78 * You @em must pass along your collection of actions (some of which appear in your toolbars).
79 *
80 * @param collection The collection of actions to work on.
81 * @param parent The parent of the dialog.
82 */
83 explicit KEditToolBar(KActionCollection *collection,
84 QWidget* parent = 0);
85
86 /**
87 * Main constructor.
88 *
89 * The main parameter, @p factory, is a pointer to the
90 * XML GUI factory object for your application. It contains a list
91 * of all of the GUI clients (along with the action collections and
92 * xml files) and the toolbar editor uses that.
93 *
94 * Use this like so:
95 * \code
96 * KEditToolBar edit(factory());
97 * if (edit.exec())
98 * ...
99 * \endcode
100 *
101 * @param factory Your application's factory object
102 * @param parent The usual parent for the dialog.
103 */
104 explicit KEditToolBar( KXMLGUIFactory* factory,
105 QWidget* parent = 0 );
106
107 /// destructor
108 ~KEditToolBar();
109
110 /**
111 * Sets the default toolbar that will be selected when the dialog is shown.
112 * If not set, or QString() is passed in, the global default tool bar name
113 * will be used.
114 * @param toolBarName the name of the tool bar
115 * @see setGlobalDefaultToolBar
116 */
117 void setDefaultToolBar( const QString& toolBarName );
118
119 /**
120 * The name (absolute or relative) of your application's UI resource file
121 * is assumed to be share/apps/appname/appnameui.rc though this can be
122 * overridden by calling this method.
123 *
124 * The global parameter controls whether or not the
125 * global resource file is used. If this is @p true, then you may
126 * edit all of the actions in your toolbars -- global ones and
127 * local one. If it is @p false, then you may edit only your
128 * application's entries. The only time you should set this to
129 * false is if your application does not use the global resource
130 * file at all (very rare).
131 *
132 * @param xmlfile The application's local resource file.
133 * @param global If @p true, then the global resource file will also
134 * be parsed.
135 */
136 void setResourceFile( const QString& file, bool global = true );
137
138 /**
139 * Sets the default toolbar which will be auto-selected for all
140 * KEditToolBar instances. Can be overridden on a per-dialog basis
141 * by calling setDefaultToolBar( const QString& ) on the dialog.
142 * @param toolbarName the name of the tool bar
143 */
144 static void setGlobalDefaultToolBar(const char *toolBarName); // TODO should be const QString&
145
146Q_SIGNALS:
147 /**
148 * Signal emitted when 'apply' or 'ok' is clicked or toolbars were reset.
149 * Connect to it, to plug action lists and to call applyMainWindowSettings
150 * (see sample code in this class's documentation)
151 */
152 void newToolBarConfig();
153
154 QT_MOC_COMPAT void newToolbarConfig();
155
156protected:
157 virtual void showEvent(QShowEvent* event);
158 virtual void hideEvent(QHideEvent* event);
159
160private:
161 friend class KEditToolBarPrivate;
162 KEditToolBarPrivate *const d;
163
164 Q_PRIVATE_SLOT( d, void _k_slotOk() )
165 Q_PRIVATE_SLOT( d, void _k_slotApply() )
166 Q_PRIVATE_SLOT( d, void _k_acceptOK(bool) )
167 Q_PRIVATE_SLOT( d, void _k_slotDefault() )
168
169 Q_DISABLE_COPY(KEditToolBar)
170};
171
172#endif // _KEDITTOOLBAR_H
173