1/*
2 * This file is part of the KDE project.
3 *
4 * Copyright (C) 2013 Christoph Cullmann <cullmann@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 as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22#ifndef KTEXTEDITOR_MAINWINDOW_H
23#define KTEXTEDITOR_MAINWINDOW_H
24
25#include <ktexteditor_export.h>
26
27#include <QObject>
28
29class QEvent;
30class QIcon;
31class QUrl;
32class QWidget;
33
34class KXMLGUIFactory;
35
36namespace KTextEditor
37{
38
39class Plugin;
40class Document;
41class View;
42
43/**
44 * This class allows the application that embeds the KTextEditor component to
45 * allow it to access parts of its main window.
46 *
47 * For example the component can get a place to show view bar widgets (e.g. search&replace, goto line, ...).
48 * This is useful to e.g. have one place inside the window to show such stuff even if the application allows
49 * the user to have multiple split views available per window.
50 *
51 * The application must pass a pointer to the MainWindow object to the createView method on view creation
52 * and ensure that this main window stays valid for the complete lifetime of the view.
53 *
54 * It must not reimplement this class but construct an instance and pass a pointer to a QObject that
55 * has the required slots to receive the requests.
56 */
57class KTEXTEDITOR_EXPORT MainWindow : public QObject
58{
59 Q_OBJECT
60
61public:
62 /**
63 * Construct an MainWindow wrapper object.
64 * The passed parent is both the parent of this QObject and the receiver of all interface
65 * calls via invokeMethod.
66 * @param parent object the calls are relayed to
67 */
68 MainWindow(QObject *parent);
69
70 /**
71 * Virtual Destructor
72 */
73 virtual ~MainWindow();
74
75 //
76 // Accessors to some window properties and contents
77 //
78public:
79 /**
80 * Get the toplevel widget.
81 * \return the real main window widget, nullptr if not available
82 */
83 QWidget *window();
84
85 /**
86 * Accessor to the XMLGUIFactory.
87 * \return the mainwindow's KXMLGUIFactory, nullptr if not available
88 */
89 KXMLGUIFactory *guiFactory();
90
91 //
92 // Signals related to the main window
93 //
94Q_SIGNALS:
95 /**
96 * This signal is emitted for every unhandled ShortcutOverride in the window
97 * @param e responsible event
98 */
99 void unhandledShortcutOverride(QEvent *e);
100
101 //
102 // View access and manipulation interface
103 //
104public:
105 /**
106 * Get a list of all views for this main window.
107 * @return all views, might be empty!
108 */
109 QList<KTextEditor::View *> views();
110
111 /**
112 * Access the active view.
113 * \return active view, nullptr if not available
114 */
115 KTextEditor::View *activeView();
116
117 /**
118 * Activate the view with the corresponding \p document.
119 * If none exist for this document, create one
120 * \param document the document
121 * \return activated view of this document,
122 * return nullptr if not possible
123 */
124 KTextEditor::View *activateView(KTextEditor::Document *document);
125
126 /**
127 * Open the document \p url with the given \p encoding.
128 * \param url the document's url
129 * \param encoding the preferred encoding. If encoding is QString() the
130 * encoding will be guessed or the default encoding will be used.
131 * \return a pointer to the created view for the new document, if a document
132 * with this url is already existing, its view will be activated,
133 * return nullptr if not possible
134 */
135 KTextEditor::View *openUrl(const QUrl &url, const QString &encoding = QString());
136
137 /**
138 * Close selected view
139 * \param view the view
140 * \return true if view was closed
141 */
142 bool closeView(KTextEditor::View *view);
143
144 /**
145 * Split current view space according to @orientation
146 * \param orientation in which line split the view
147 */
148 void splitView(Qt::Orientation orientation);
149
150 /**
151 * Close the split view that contains the given view.
152 * \param view the view.
153 * \return true if the split view was closed.
154 */
155 bool closeSplitView(KTextEditor::View *view);
156
157 /**
158 * \returns true if the given views \param view1 and \param view2 share
159 * the same split view, false otherwise.
160 */
161 bool viewsInSameSplitView(KTextEditor::View *view1, KTextEditor::View *view2);
162
163 //
164 // Signals related to view handling
165 //
166Q_SIGNALS:
167 /**
168 * This signal is emitted whenever the active view changes.
169 * @param view new active view
170 */
171 void viewChanged(KTextEditor::View *view);
172
173 /**
174 * This signal is emitted whenever a new view is created
175 * @param view view that was created
176 */
177 void viewCreated(KTextEditor::View *view);
178
179 //
180 // Interface to allow view bars to be constructed in a central place per window
181 //
182public:
183 /**
184 * Try to create a view bar for the given view.
185 * @param view view for which we want an view bar
186 * @return suitable widget that can host view bars widgets or nullptr
187 */
188 QWidget *createViewBar(KTextEditor::View *view);
189
190 /**
191 * Delete the view bar for the given view.
192 * @param view view for which we want an view bar
193 */
194 void deleteViewBar(KTextEditor::View *view);
195
196 /**
197 * Add a widget to the view bar.
198 * @param view view for which the view bar is used
199 * @param bar bar widget, shall have the viewBarParent() as parent widget
200 */
201 void addWidgetToViewBar(KTextEditor::View *view, QWidget *bar);
202
203 /**
204 * Show the view bar for the given view
205 * @param view view for which the view bar is used
206 */
207 void showViewBar(KTextEditor::View *view);
208
209 /**
210 * Hide the view bar for the given view
211 * @param view view for which the view bar is used
212 */
213 void hideViewBar(KTextEditor::View *view);
214
215 //
216 // ToolView stuff, here all stuff belong which allows to
217 // add/remove and manipulate the toolview of this main windows
218 //
219public:
220 /**
221 * Toolview position.
222 * A toolview can only be at one side at a time.
223 */
224 enum ToolViewPosition {
225 Left = 0, /**< Left side. */
226 Right = 1, /**< Right side. */
227 Top = 2, /**< Top side. */
228 Bottom = 3 /**< Bottom side. */
229 };
230
231 /**
232 * Create a new toolview with unique \p identifier at side \p pos
233 * with \p icon and caption \p text. Use the returned widget to embedd
234 * your widgets.
235 * \param plugin which owns this tool view
236 * \param identifier unique identifier for this toolview
237 * \param pos position for the toolview, if we are in session restore,
238 * this is only a preference
239 * \param icon icon to use in the sidebar for the toolview
240 * \param text translated text (i18n()) to use in addition to icon
241 * \return created toolview on success, otherwise NULL
242 */
243 QWidget *createToolView(KTextEditor::Plugin *plugin, const QString &identifier, KTextEditor::MainWindow::ToolViewPosition pos, const QIcon &icon, const QString &text);
244
245 /**
246 * Move the toolview \p widget to position \p pos.
247 * \param widget the toolview to move, where the widget was constructed
248 * by createToolView().
249 * \param pos new position to move widget to
250 * \return \e true on success, otherwise \e false
251 */
252 bool moveToolView(QWidget *widget, KTextEditor::MainWindow::ToolViewPosition pos);
253
254 /**
255 * Show the toolview \p widget.
256 * \param widget the toolview to show, where the widget was constructed
257 * by createToolView().
258 * \return \e true on success, otherwise \e false
259 * \todo add focus parameter: bool showToolView (QWidget *widget, bool giveFocus );
260 */
261 bool showToolView(QWidget *widget);
262
263 /**
264 * Hide the toolview \p widget.
265 * \param widget the toolview to hide, where the widget was constructed
266 * by createToolView().
267 * \return \e true on success, otherwise \e false
268 */
269 bool hideToolView(QWidget *widget);
270
271 //
272 // Application plugin accessors
273 //
274public:
275 /**
276 * Get a plugin view for the plugin with with identifier \p name.
277 * \param name the plugin's name
278 * \return pointer to the plugin view if a plugin with \p name is loaded and has a view for this mainwindow,
279 * otherwise NULL
280 */
281 QObject *pluginView(const QString &name);
282
283 //
284 // Signals related to application plugins
285 //
286Q_SIGNALS:
287 /**
288 * This signal is emitted when the view of some Plugin is created for this main window.
289 *
290 * @param name name of plugin
291 * @param pluginView the new plugin view
292 */
293 void pluginViewCreated(const QString &name, QObject *pluginView);
294
295 /**
296 * This signal is emitted when the view of some Plugin got deleted.
297 *
298 * @param name name of plugin
299 * @param pluginView the deleted plugin view
300 *
301 * Warning !!! DO NOT ACCESS THE DATA REFERENCED BY THE POINTER, IT IS ALREADY INVALID
302 * Use the pointer only to remove mappings in hash or maps
303 */
304 void pluginViewDeleted(const QString &name, QObject *pluginView);
305
306private:
307 /**
308 * Private d-pointer class is our best friend ;)
309 */
310 friend class MainWindowPrivate;
311
312 /**
313 * Private d-pointer
314 */
315 class MainWindowPrivate *const d;
316};
317
318} // namespace KTextEditor
319
320#endif
321