KTextEditor

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

KDE's Doxygen guidelines are available online.