KTextEditor

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

KDE's Doxygen guidelines are available online.