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_APPLICATION_H
8#define KTEXTEDITOR_APPLICATION_H
9
10#include <ktexteditor_export.h>
11
12#include <QObject>
13
14namespace KTextEditor
15{
16class Plugin;
17class Document;
18class MainWindow;
19
20/*!
21 * \class KTextEditor::Application
22 * \inmodule KTextEditor
23 * \inheaderfile KTextEditor/Application
24 *
25 * \brief This class allows the application that embeds the KTextEditor component to
26 * allow it access to application wide information and interactions.
27 *
28 * For example the component can get the current active main window of the application.
29 *
30 * The application must pass a pointer to the Application object to the setApplication method of the
31 * global editor instance and ensure that this object stays valid for the complete lifetime of the editor.
32 *
33 * It must not reimplement this class but construct an instance and pass a pointer to a QObject that
34 * has the required slots to receive the requests.
35 *
36 * KTextEditor::Editor::instance()->application() will always return a non-nullptr object
37 * to avoid the need for nullptr checks before calling the API.
38 *
39 * The same holds for activeMainWindow(), even if no main window is around, you will get a non-nullptr
40 * interface object that allows to call the functions of the MainWindow without needs for a nullptr
41 * check around it in the client code.
42 *
43 * \l kte_plugin_hosting
44 */
45class KTEXTEDITOR_EXPORT Application : public QObject
46{
47 Q_OBJECT
48
49public:
50 /*!
51 * Construct an Application wrapper object.
52 * The passed parent is both the parent of this QObject and the receiver of all interface
53 * calls via invokeMethod.
54 *
55 * \a parent is the object the calls are relayed to
56 *
57 */
58 Application(QObject *parent);
59
60 ~Application() override;
61
62 /*!
63 * Ask app to quit. The app might interact with the user and decide that
64 * quitting is not possible and return false.
65 *
66 * Returns true if the app could quit
67 */
68 bool quit();
69
70 //
71 // MainWindow related accessors
72 //
73public:
74 /*!
75 * Get a list of all main windows.
76 * Returns all main windows, might be empty!
77 */
78 QList<KTextEditor::MainWindow *> mainWindows();
79
80 /*!
81 * Accessor to the active main window.
82 * Returns a pointer to the active mainwindow, even if no main window is active you
83 * will get a non-nullptr dummy interface that allows you to call interface functions
84 * without the need for null checks
85 */
86 KTextEditor::MainWindow *activeMainWindow();
87
88 //
89 // Document related accessors
90 //
91public:
92 /*!
93 * Get a list of all documents that are managed by the application.
94 * This might contain less documents than the editor has in his documents () list.
95 * Returns all documents the application manages, might be empty!
96 */
97 QList<KTextEditor::Document *> documents();
98
99 /*!
100 * Get the document with the URL.
101 * If multiple documents match the searched url, return the first found one.
102 *
103 * \a url is the document's URL
104 *
105 * Returns the document with the given \a url or nullptr, if none found
106 */
107 KTextEditor::Document *findUrl(const QUrl &url);
108
109 /*!
110 * Open the document URL with the given encoding.
111 * If the url is empty, a new empty document will be created
112 *
113 * \a url is the document URL
114 *
115 * \a encoding is the preferred encoding. If encoding is QString() the
116 * encoding will be guessed or the default encoding will be used.
117 *
118 * Returns a pointer to the created document
119 */
120 KTextEditor::Document *openUrl(const QUrl &url, const QString &encoding = QString());
121
122 /*!
123 * Close the given document. If the document is modified, user will be asked for confirmation.
124 *
125 * \a document is the the document to be closed
126 *
127 * Returns \e true on success, otherwise \e false
128 */
129 bool closeDocument(KTextEditor::Document *document);
130
131 /*!
132 * Close a list of documents. If any of them are modified, user will be asked for confirmation.
133 * Use this if you want to close multiple documents at once, as the application might
134 * be able to group the "do you really want that" dialogs into one.
135 *
136 * \a documents is the list of documents to be closed
137 *
138 * Returns \e true on success, otherwise \e false
139 */
140 bool closeDocuments(const QList<KTextEditor::Document *> &documents);
141
142Q_SIGNALS:
143 /*!
144 * This signal is emitted when the \a document was created.
145 *
146 * \a document document that was created
147 */
148 void documentCreated(KTextEditor::Document *document);
149
150 /*!
151 * This signal is emitted before a \a document which should be closed is deleted
152 * The document is still accessible and usable, but it will be deleted
153 * after this signal was send.
154 *
155 * \a document document that will be deleted
156 */
157 void documentWillBeDeleted(KTextEditor::Document *document);
158
159 /*!
160 * This signal is emitted when the \a document has been deleted.
161 *
162 * \warning Do not access the data referenced by the pointer, it is already invalid.
163 * Use the pointer only to remove mappings in hash or maps
164 *
165 * \a document document that is deleted
166 */
167 void documentDeleted(KTextEditor::Document *document);
168
169 //
170 // Application plugin accessors
171 //
172public:
173 /*!
174 * Get a plugin with the specified name.
175 *
176 * \a name is the plugin's name
177 *
178 * Returns pointer to the plugin if a plugin with \a name is loaded, otherwise nullptr
179 */
180 KTextEditor::Plugin *plugin(const QString &name);
181
182 //
183 // Signals related to application plugins
184 //
185Q_SIGNALS:
186 /*!
187 * This signal is emitted when an Plugin was loaded.
188 *
189 * \a name is the name of the plugin
190 *
191 * \a plugin is the new plugin
192 *
193 */
194 void pluginCreated(const QString &name, KTextEditor::Plugin *plugin);
195
196 /*!
197 * This signal is emitted when an Plugin got deleted.
198 *
199 * \a name is the name of the plugin
200 *
201 * \a plugin is the deleted plugin
202 *
203 * \warning Do not access the data referenced by the pointer, it is already invalid.
204 * Use the pointer only to remove mappings in hash or maps
205 */
206 void pluginDeleted(const QString &name, KTextEditor::Plugin *plugin);
207
208private:
209 friend class ApplicationPrivate;
210
211 class ApplicationPrivate *const d;
212};
213
214} // namespace KTextEditor
215
216#endif
217

source code of ktexteditor/src/include/ktexteditor/application.h