KTextEditor

mainwindow.h
1/*
2 SPDX-FileCopyrightText: 2013 Christoph Cullmann <cullmann@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_MAINWINDOW_H
8#define KTEXTEDITOR_MAINWINDOW_H
9
10#include <ktexteditor_export.h>
11
12#include <QObject>
13#include <QWidgetList>
14
15class QEvent;
16class QIcon;
17class QUrl;
18class QWidget;
19
20class KXMLGUIFactory;
21
22namespace KTextEditor
23{
24class Plugin;
25class Document;
26class View;
27
28/**
29 * \class MainWindow mainwindow.h <KTextEditor/MainWindow>
30 *
31 * This class allows the application that embeds the KTextEditor component to
32 * allow it to access parts of its main window.
33 *
34 * For example the component can get a place to show view bar widgets (e.g. search&replace, goto line, ...).
35 * This is useful to e.g. have one place inside the window to show such stuff even if the application allows
36 * the user to have multiple split views available per window.
37 *
38 * The application must pass a pointer to the MainWindow object to the createView method on view creation
39 * and ensure that this main window stays valid for the complete lifetime of the view.
40 *
41 * It must not reimplement this class but construct an instance and pass a pointer to a QObject that
42 * has the required slots to receive the requests.
43 *
44 * @ref kte_plugin_hosting
45 */
46class KTEXTEDITOR_EXPORT MainWindow : public QObject
47{
48 Q_OBJECT
49
50public:
51 /**
52 * Construct an MainWindow wrapper object.
53 * The passed parent is both the parent of this QObject and the receiver of all interface
54 * calls via invokeMethod.
55 * @param parent object the calls are relayed to
56 */
57 MainWindow(QObject *parent);
58
59 /**
60 * Virtual Destructor
61 */
62 ~MainWindow() override;
63
64 //
65 // Accessors to some window properties and contents
66 //
67public:
68 /**
69 * Get the toplevel widget.
70 * \return the real main window widget, nullptr if not available
71 */
72 QWidget *window();
73
74 /**
75 * Accessor to the XMLGUIFactory.
76 * \return the mainwindow's KXMLGUIFactory, nullptr if not available
77 */
78 KXMLGUIFactory *guiFactory();
79
80 //
81 // Signals related to the main window
82 //
83Q_SIGNALS:
84 /**
85 * This signal is emitted for every unhandled ShortcutOverride in the window
86 * @param e responsible event
87 */
89
90 //
91 // View access and manipulation interface
92 //
93public:
94 /**
95 * Get a list of all views for this main window.
96 *
97 * It is beneficial if the list is sorted by most recently used,
98 * as the library will e.g. try to use the most recent used url() by walking over this
99 * list for save and other such things.
100 *
101 * @return all views, might be empty!
102 */
104
105 /**
106 * Access the active view.
107 * \return active view, nullptr if not available
108 */
109 KTextEditor::View *activeView();
110
111 /**
112 * Activate the view with the corresponding \p document.
113 * If none exist for this document, create one
114 * \param document the document
115 * \return activated view of this document,
116 * return nullptr if not possible
117 */
118 KTextEditor::View *activateView(KTextEditor::Document *document);
119
120 /**
121 * Open the document \p url with the given \p encoding.
122 * \param url the document's url
123 * \param encoding the preferred encoding. If encoding is QString() the
124 * encoding will be guessed or the default encoding will be used.
125 * \return a pointer to the created view for the new document, if a document
126 * with this url is already existing, its view will be activated,
127 * return nullptr if not possible
128 */
129 KTextEditor::View *openUrl(const QUrl &url, const QString &encoding = QString());
130
131 /**
132 * Close selected view
133 * \param view the view
134 * \return true if view was closed
135 */
136 bool closeView(KTextEditor::View *view);
137
138 /**
139 * Split current view space according to \p orientation
140 * \param orientation in which line split the view
141 */
142 void splitView(Qt::Orientation orientation);
143
144 /**
145 * Close the split view that contains the given view.
146 * \param view the view.
147 * \return true if the split view was closed.
148 */
149 bool closeSplitView(KTextEditor::View *view);
150
151 /**
152 * \returns \c true if the given views \p view1 and \p view2 share
153 * the same split view, false otherwise.
154 */
155 bool viewsInSameSplitView(KTextEditor::View *view1, KTextEditor::View *view2);
156
157 //
158 // Signals related to view handling
159 //
160Q_SIGNALS:
161 /**
162 * This signal is emitted whenever the active view changes.
163 * @param view new active view
164 */
166
167 /**
168 * This signal is emitted whenever a new view is created
169 * @param view view that was created
170 */
172
173 //
174 // Interface to allow view bars to be constructed in a central place per window
175 //
176public:
177 /**
178 * Try to create a view bar for the given view.
179 * @param view view for which we want an view bar
180 * @return suitable widget that can host view bars widgets or nullptr
181 */
182 QWidget *createViewBar(KTextEditor::View *view);
183
184 /**
185 * Delete the view bar for the given view.
186 * @param view view for which we want an view bar
187 */
188 void deleteViewBar(KTextEditor::View *view);
189
190 /**
191 * Add a widget to the view bar.
192 * @param view view for which the view bar is used
193 * @param bar bar widget, shall have the viewBarParent() as parent widget
194 */
195 void addWidgetToViewBar(KTextEditor::View *view, QWidget *bar);
196
197 /**
198 * Show the view bar for the given view
199 * @param view view for which the view bar is used
200 */
201 void showViewBar(KTextEditor::View *view);
202
203 /**
204 * Hide the view bar for the given view
205 * @param view view for which the view bar is used
206 */
207 void hideViewBar(KTextEditor::View *view);
208
209 //
210 // ToolView stuff, here all stuff belong which allows to
211 // add/remove and manipulate the toolview of this main windows
212 //
213public:
214 /**
215 * Toolview position.
216 * A toolview can only be at one side at a time.
217 */
219 Left = 0, /**< Left side. */
220 Right = 1, /**< Right side. */
221 Top = 2, /**< Top side. */
222 Bottom = 3 /**< Bottom side. */
223 };
224
225 /**
226 * Create a new toolview with unique \p identifier at side \p pos
227 * with \p icon and caption \p text. Use the returned widget to embedd
228 * your widgets.
229 * \param plugin which owns this tool view
230 * \param identifier unique identifier for this toolview
231 * \param pos position for the toolview, if we are in session restore,
232 * this is only a preference
233 * \param icon icon to use in the sidebar for the toolview
234 * \param text translated text (i18n()) to use in addition to icon
235 * \return created toolview on success, otherwise NULL
236 */
237 QWidget *createToolView(KTextEditor::Plugin *plugin,
238 const QString &identifier,
240 const QIcon &icon,
241 const QString &text);
242
243 /**
244 * Move the toolview \p widget to position \p pos.
245 * \param widget the toolview to move, where the widget was constructed
246 * by createToolView().
247 * \param pos new position to move widget to
248 * \return \e true on success, otherwise \e false
249 */
250 bool moveToolView(QWidget *widget, KTextEditor::MainWindow::ToolViewPosition pos);
251
252 /**
253 * Show the toolview \p widget.
254 * \param widget the toolview to show, where the widget was constructed
255 * by createToolView().
256 * \return \e true on success, otherwise \e false
257 * \todo add focus parameter: bool showToolView (QWidget *widget, bool giveFocus );
258 */
259 bool showToolView(QWidget *widget);
260
261 /**
262 * Hide the toolview \p widget.
263 * \param widget the toolview to hide, where the widget was constructed
264 * by createToolView().
265 * \return \e true on success, otherwise \e false
266 */
267 bool hideToolView(QWidget *widget);
268
269 //
270 // Application plugin accessors
271 //
272public:
273 /**
274 * Shows the @p plugin's config page. The @p page specifies which
275 * config page will be shown, see KTextEditor::Plugin::configPages().
276 *
277 * \return \e true on success, otherwise \e false
278 * \since 5.63
279 */
280 bool showPluginConfigPage(KTextEditor::Plugin *plugin, int page);
281
282 /**
283 * Get a plugin view for the plugin with with identifier \p name.
284 * \param name the plugin's name
285 * \return pointer to the plugin view if a plugin with \p name is loaded and has a view for this mainwindow,
286 * otherwise NULL
287 */
288 QObject *pluginView(const QString &name);
289
290 //
291 // Signals related to application plugins
292 //
293Q_SIGNALS:
294 /**
295 * This signal is emitted when the view of some Plugin is created for this main window.
296 *
297 * @param name name of plugin
298 * @param pluginView the new plugin view
299 */
300 void pluginViewCreated(const QString &name, QObject *pluginView);
301
302 /**
303 * This signal is emitted when the view of some Plugin got deleted.
304 *
305 * @warning Do not access the data referenced by the pointer, it is already invalid.
306 * Use the pointer only to remove mappings in hash or maps
307 *
308 * @param name name of plugin
309 * @param pluginView the deleted plugin view
310 */
311 void pluginViewDeleted(const QString &name, QObject *pluginView);
312
313 //
314 // Custom widget handling
315 //
316public:
317 /**
318 * Add a widget to the main window.
319 * This is useful to show non-KTextEditor::View widgets in the main window.
320 * The host application should try to manage this like some KTextEditor::View (e.g. as a tab) and provide
321 * the means to close it.
322 * \param widget widget to add
323 * \return success, if false, the plugin needs to take care to show the widget itself, otherwise
324 * the main window will take ownership of the widget
325 * \since 5.98
326 */
327 bool addWidget(QWidget *widget);
328
329 /**
330 * \brief remove this \p widget from this mainwindow. The widget will be deleted afterwards
331 * \param widget the widget to be removed
332 * \return true on success
333 * \since 6.0
334 */
335 bool removeWidget(QWidget *widget);
336
337 /**
338 * \brief returns the list of non-KTextEditor::View widgets in this main window.
339 * \see addWidget
340 * \since 6.0
341 */
342 QWidgetList widgets();
343
344 /**
345 * \brief returns the currently active widget. It can be a non-KTextEditor::View widget or a KTextEditor::View
346 * \since 6.0
347 */
348 QWidget *activeWidget();
349
350 /**
351 * \brief activate @p widget. If the widget is not present in the window, it will be added to the window
352 * \param widget the widget to activate
353 * \since 6.0
354 */
355 void activateWidget(QWidget *widget);
356
357 //
358 // Signals related to widgets
359 //
360Q_SIGNALS:
361 /**
362 * \brief The @p widget was added to this window.
363 * \param widget the widget that got added
364 * \since 6.0
365 */
366 void widgetAdded(QWidget *widget);
367
368 /**
369 * \brief The @p widget was removed from this window.
370 * \param widget the widget that got removed
371 * \since 6.0
372 */
373 void widgetRemoved(QWidget *widget);
374
375 //
376 // Message output
377 //
378public:
379 /**
380 * Display a message to the user.
381 * The host application might show this inside a dedicated output view.
382 *
383 * \param message incoming message we shall handle
384 * \return true, if the host application was able to handle the message, else false
385 * \since 5.98
386 *
387 * details of message format:
388 *
389 * message text, will be trimmed before output
390 *
391 * message["text"] = i18n("your cool message")
392 *
393 * the text will be split in lines, all lines beside the first can be collapsed away
394 *
395 * message type, we support at the moment
396 *
397 * message["type"] = "Error"
398 * message["type"] = "Warning"
399 * message["type"] = "Info"
400 * message["type"] = "Log"
401 *
402 * this is take from https://microsoft.github.io/language-server-protocol/specification#window_showMessage MessageType of LSP
403 *
404 * will lead to appropriate icons/... in the output view
405 *
406 * a message should have some category, like Git, LSP, ....
407 *
408 * message["category"] = i18n(...)
409 *
410 * will be used to allow the user to filter for
411 *
412 * one can additionally provide a categoryIcon
413 *
414 * message["categoryIcon"] = QIcon(...)
415 *
416 * the categoryIcon icon QVariant must contain a QIcon, nothing else!
417 *
418 * A string token can be passed to allow to replace messages already send out with new ones.
419 * That is useful for e.g. progress output
420 *
421 * message["token"] = "yourmessagetoken"
422 *
423 */
424 bool showMessage(const QVariantMap &message);
425
426private:
427 /**
428 * Private d-pointer class is our best friend ;)
429 */
430 friend class MainWindowPrivate;
431
432 /**
433 * Private d-pointer
434 */
435 class MainWindowPrivate *const d;
436};
437
438} // namespace KTextEditor
439
440#endif
A KParts derived class representing a text document.
Definition document.h:284
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition mainwindow.h:47
void viewChanged(KTextEditor::View *view)
This signal is emitted whenever the active view changes.
void widgetRemoved(QWidget *widget)
The widget was removed from this window.
void unhandledShortcutOverride(QEvent *e)
This signal is emitted for every unhandled ShortcutOverride in the window.
void pluginViewCreated(const QString &name, QObject *pluginView)
This signal is emitted when the view of some Plugin is created for this main window.
void pluginViewDeleted(const QString &name, QObject *pluginView)
This signal is emitted when the view of some Plugin got deleted.
void viewCreated(KTextEditor::View *view)
This signal is emitted whenever a new view is created.
void widgetAdded(QWidget *widget)
The widget was added to this window.
ToolViewPosition
Toolview position.
Definition mainwindow.h:218
KTextEditor Plugin interface.
Definition plugin.h:79
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Orientation
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:53:31 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.