1/* This file is part of the KDE project
2 Copyright (C) 2001 Christoph Cullmann <cullmann@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef _KATE_MAINWINDOW_INCLUDE_
20#define _KATE_MAINWINDOW_INCLUDE_
21
22#include <kate_export.h>
23
24#include <QtCore/QObject>
25#include <QtGui/QPixmap>
26
27#include <kxmlguifactory.h>
28#include <kurl.h>
29
30class QWidget;
31
32namespace KTextEditor
33{
34 class View;
35 class Document;
36}
37
38namespace Kate
39{
40 class PluginConfigPageInterface;
41 class Plugin;
42 class PluginView;
43
44 /**
45 * \brief Interface to a mainwindow.
46 *
47 * \section mainwindow_intro Introduction
48 * The class MainWindow represents a toplevel window, with menu bar,
49 * statusbar etc, get it with window(). A mainwindow usually has an active
50 * View, access it with activeView(). To set another active view use
51 * activateView().
52 *
53 * \section mainwindow_toolviews Toolviews
54 *
55 * It is possible to embedd new toolviews into a mainwindow. To create a
56 * toolview use createToolView(), then you can move, hide or show the toolview
57 * by using moveToolView(), hideToolView() or showToolView().
58 *
59 * With guiFactory() you can access the KXMLGUIFactory framework and add
60 * gui clients.
61 *
62 * To access a mainwindow use the Application object.
63 * You should never have to create an instance of this class yourself.
64 *
65 * \author Christoph Cullmann \<cullmann@kde.org\>
66 * \see KXMLGUIFactory
67 */
68 class KATEINTERFACES_EXPORT MainWindow : public QObject
69 {
70 friend class PrivateMainWindow;
71
72 Q_OBJECT
73
74 public:
75 /**
76 * Constructor.
77 *
78 * Create a new mainwindow. You as a plugin developer should never have
79 * to create a new mainwindow yourself. Access the mainwindows via the
80 * global Application.
81 * \param mainWindow internal usage
82 * \internal
83 */
84 MainWindow (void *mainWindow);
85 /**
86 * Virtual destructor.
87 */
88 virtual ~MainWindow ();
89
90 public: /*these are slots for kjs*/
91 /**
92 * Accesstor to the XMLGUIFactory.
93 * \return the mainwindow's KXMLGUIFactory.
94 */
95 KXMLGUIFactory *guiFactory() const;
96
97 /**
98 * Get the toplevel widget.
99 * \return the kate main window.
100 */
101 class QWidget *window() const;
102
103 /**
104 * Access the widget (in the middle of the four sidebars) in which the
105 * editor component and the KateTabBar are embedded. This widget is a
106 * KVBox, so other child widgets can be embedded themselves under the
107 * editor widget.
108 *
109 * \return the central widget
110 */
111 class QWidget *centralWidget() const;
112
113 /**
114 * Get a list of all views.
115 * @return all views
116 */
117 const QList<KTextEditor::View *> &views () const;
118
119 /*
120 * View stuff, here all stuff belong which allows to
121 * access and manipulate the KTextEditor::View's we have in this windows
122 */
123 public:
124 /**
125 * Access the active view.
126 * \return active view
127 */
128 KTextEditor::View *activeView ();
129
130 /**
131 * Activate the view with the corresponding \p document.
132 * If none exist for this document, create one
133 * \param document the document
134 * \return activated view of this document
135 */
136 KTextEditor::View *activateView ( KTextEditor::Document *document );
137
138 /**
139 * Open the document \p url with the given \p encoding.
140 * \param url the document's url
141 * \param encoding the preferred encoding. If encoding is QString() the
142 * encoding will be guessed or the default encoding will be used.
143 * \return a pointer to the created view for the new document, if a document
144 * with this url is already existing, its view will be activated
145 */
146 KTextEditor::View *openUrl (const KUrl &url, const QString &encoding = QString());
147
148 //
149 // SIGNALS !!!
150 //
151#ifndef Q_MOC_RUN
152#undef signals
153#define signals public
154#endif
155 signals:
156#ifndef Q_MOC_RUN
157#undef signals
158#define signals protected
159#endif
160
161 /**
162 * This signal is emitted whenever the active view changes.
163 */
164 // TODO: KDE5 add View* parameter:
165 // void viewChanged (KTextEditor::View* view);
166 void viewChanged ();
167
168 /**
169 * This signal is emitted whenever a new view is created
170 * @since 4.2
171 */
172 void viewCreated(KTextEditor::View * view);
173
174 /**
175 * This signal is emitted for every unhandled ShortcutOverride in a view
176 */
177 void unhandledShortcutOverride (QEvent *e);
178
179 /**
180 * This signal is emitted when a Plugin::View is created for this main window.
181 *
182 * @param name name of plugin
183 * @param pluginView the new plugin view
184 */
185 void pluginViewCreated (const QString &name, Kate::PluginView *pluginView);
186
187 /**
188 * This signal is emitted when the Plugin::View got deleted.
189 *
190 * @param name name of plugin
191 * @param pluginView the deleted plugin view
192 *
193 * Warning !!! DO NOT ACCESS THE DATA REFERENCED BY THE POINTER, IT IS ALREADY INVALID
194 * Use the pointer only to remove mappings in hash or maps
195 */
196 void pluginViewDeleted (const QString &name, Kate::PluginView *pluginView);
197
198 /*
199 * ToolView stuff, here all stuff belong which allows to
200 * add/remove and manipulate the toolview of this main windows
201 */
202 public:
203 /**
204 * Toolview position.
205 * A toolview can only be at one side at a time.
206 */
207 enum Position {
208 Left = 0, /**< Left side. */
209 Right = 1, /**< Right side. */
210 Top = 2, /**< Top side. */
211 Bottom = 3 /**< Bottom side. */
212 };
213
214 /**
215 * Create a new toolview with unique \p identifier at side \p pos
216 * with \p icon and caption \p text. Use the returned widget to embedd
217 * your widgets.
218 * \param identifier unique identifier for this toolview
219 * \param pos position for the toolview, if we are in session restore,
220 * this is only a preference
221 * \param icon icon to use in the sidebar for the toolview
222 * \param text translated text (i18n()) to use in addition to icon
223 * \return created toolview on success, otherwise NULL
224 * @deprecated
225 */
226 QWidget *createToolView (const QString &identifier, MainWindow::Position pos, const QPixmap &icon, const QString &text);
227
228 /**
229 * Create a new toolview with unique \p identifier at side \p pos
230 * with \p icon and caption \p text. Use the returned widget to embedd
231 * your widgets.
232 * \param plugin which owns this tool view
233 * \param identifier unique identifier for this toolview
234 * \param pos position for the toolview, if we are in session restore,
235 * this is only a preference
236 * \param icon icon to use in the sidebar for the toolview
237 * \param text translated text (i18n()) to use in addition to icon
238 * \return created toolview on success, otherwise NULL
239 */
240 QWidget *createToolView (Kate::Plugin* plugin, const QString &identifier, MainWindow::Position pos, const QPixmap &icon, const QString &text);
241
242 /**
243 * Move the toolview \p widget to position \p pos.
244 * \param widget the toolview to move, where the widget was constructed
245 * by createToolView().
246 * \param pos new position to move widget to
247 * \return \e true on success, otherwise \e false
248 */
249 bool moveToolView (QWidget *widget, MainWindow::Position pos);
250
251 /**
252 * Show the toolview \p widget.
253 * \param widget the toolview to show, where the widget was constructed
254 * by createToolView().
255 * \return \e true on success, otherwise \e false
256 * \todo add focus parameter: bool showToolView (QWidget *widget, bool giveFocus );
257 */
258 bool showToolView (QWidget *widget);
259
260 /**
261 * Hide the toolview \p widget.
262 * \param widget the toolview to hide, where the widget was constructed
263 * by createToolView().
264 * \return \e true on success, otherwise \e false
265 */
266 bool hideToolView (QWidget *widget);
267
268 /**
269 * This function is used by a plugin to open the kate configuration dialog
270 * at one of its own config pages.
271 * \param configpageinterface the plugin config page interface of the plugin which requests the settings dialog
272 * \param id the positional id of the page within the configuration
273 */
274 void showPluginConfigPage(Kate::PluginConfigPageInterface *configpageinterface,uint id);
275
276 /**
277 * Get a plugin view with identifier \p name.
278 * \param name the plugin's name
279 * \return pointer to the plugin view if a plugin with \p name is loaded and has a view for this mainwindow,
280 * otherwise NULL
281 */
282 PluginView *pluginView (const QString &name);
283
284 private:
285 class PrivateMainWindow *d;
286 };
287}
288
289#endif
290// kate: space-indent on; indent-width 2; replace-tabs on;
291
292