KTextEditor

application.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_APPLICATION_H
8 #define KTEXTEDITOR_APPLICATION_H
9 
10 #include <ktexteditor_export.h>
11 
12 #include <QObject>
13 
14 namespace KTextEditor
15 {
16 class Plugin;
17 class Document;
18 class 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 class KTEXTEDITOR_EXPORT Application : public QObject
42 {
43  Q_OBJECT
44 
45 public:
46  /**
47  * Construct an Application wrapper object.
48  * The passed parent is both the parent of this QObject and the receiver of all interface
49  * calls via invokeMethod.
50  * @param parent object the calls are relayed to
51  */
52  Application(QObject *parent);
53 
54  /**
55  * Virtual Destructor
56  */
57  ~Application() override;
58 
59  /**
60  * Ask app to quit. The app might interact with the user and decide that
61  * quitting is not possible and return false.
62  *
63  * \return true if the app could quit
64  */
65  bool quit();
66 
67  //
68  // MainWindow related accessors
69  //
70 public:
71  /**
72  * Get a list of all main windows.
73  * @return all main windows, might be empty!
74  */
76 
77  /**
78  * Accessor to the active main window.
79  * \return a pointer to the active mainwindow, even if no main window is active you
80  * will get a non-nullptr dummy interface that allows you to call interface functions
81  * without the need for null checks
82  */
83  KTextEditor::MainWindow *activeMainWindow();
84 
85  //
86  // Document related accessors
87  //
88 public:
89  /**
90  * Get a list of all documents that are managed by the application.
91  * This might contain less documents than the editor has in his documents () list.
92  * @return all documents the application manages, might be empty!
93  */
95 
96  /**
97  * Get the document with the URL \p url.
98  * if multiple documents match the searched url, return the first found one...
99  * \param url the document's URL
100  * \return the document with the given \p url or nullptr, if none found
101  */
102  KTextEditor::Document *findUrl(const QUrl &url);
103 
104  /**
105  * Open the document \p url with the given \p encoding.
106  * if the url is empty, a new empty document will be created
107  * \param url the document's url
108  * \param encoding the preferred encoding. If encoding is QString() the
109  * encoding will be guessed or the default encoding will be used.
110  * \return a pointer to the created document
111  */
112  KTextEditor::Document *openUrl(const QUrl &url, const QString &encoding = QString());
113 
114  /**
115  * Close the given \p document. If the document is modified, user will be asked if he wants that.
116  * \param document the document to be closed
117  * \return \e true on success, otherwise \e false
118  */
119  bool closeDocument(KTextEditor::Document *document);
120 
121  /**
122  * Close a list of documents. If any of them are modified, user will be asked if he wants that.
123  * Use this, if you want to close multiple documents at once, as the application might
124  * be able to group the "do you really want that" dialogs into one.
125  * \param documents list of documents to be closed
126  * \return \e true on success, otherwise \e false
127  */
128  bool closeDocuments(const QList<KTextEditor::Document *> &documents);
129 
130 Q_SIGNALS:
131  /**
132  * This signal is emitted when the \p document was created.
133  *
134  * @param document document that was created
135  */
136  void documentCreated(KTextEditor::Document *document);
137 
138  /**
139  * This signal is emitted before a \p document which should be closed is deleted
140  * The document is still accessible and usable, but it will be deleted
141  * after this signal was send.
142  *
143  * @param document document that will be deleted
144  */
145  void documentWillBeDeleted(KTextEditor::Document *document);
146 
147  /**
148  * This signal is emitted when the \p document has been deleted.
149  *
150  * @warning Do not access the data referenced by the pointer, it is already invalid.
151  * Use the pointer only to remove mappings in hash or maps
152  *
153  * @param document document that is deleted
154  */
155  void documentDeleted(KTextEditor::Document *document);
156 
157 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80)
158  /**
159  * This signal is emitted before the batch of documents is being created.
160  *
161  * You can use it to pause some updates.
162  * @deprecated Since 5.80, Deprecated due to lack of usage
163  */
164  KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Deprecated due to lack of usage")
165  void aboutToCreateDocuments();
166 #endif
167 
168 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80)
169  /**
170  * This signal is emitted after the batch of documents is created.
171  *
172  * @param documents list of documents that have been created
173  * @deprecated Since 5.80, use documentCreated(KTextEditor::Document *document) instead
174  */
175  KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentCreated(KTextEditor::Document *document) instead")
176  void documentsCreated(const QList<KTextEditor::Document *> &documents);
177 #endif
178 
179 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80)
180  /**
181  * This signal is emitted before the documents batch is going to be deleted
182  *
183  * note that the batch can be interrupted in the middle and only some
184  * of the documents may be actually deleted. See documentsDeleted() signal.
185  * @deprecated Since 5.80, use documentWillBeDeleted(KTextEditor::Document *document) instead
186  */
187  KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentWillBeDeleted(KTextEditor::Document *document) instead")
188  void aboutToDeleteDocuments(const QList<KTextEditor::Document *> &);
189 #endif
190 
191 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80)
192  /**
193  * This signal is emitted after the documents batch was deleted
194  *
195  * This is the batch closing signal for aboutToDeleteDocuments
196  * @param documents the documents that weren't deleted after all
197  * @deprecated Since 5.80, use documentDeleted(KTextEditor::Document *document) instead
198  */
199  KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentDeleted(KTextEditor::Document *document) instead")
200  void documentsDeleted(const QList<KTextEditor::Document *> &documents);
201 #endif
202 
203  //
204  // Application plugin accessors
205  //
206 public:
207  /**
208  * Get a plugin for the plugin with with identifier \p name.
209  * \param name the plugin's name
210  * \return pointer to the plugin if a plugin with \p name is loaded, otherwise nullptr
211  */
212  KTextEditor::Plugin *plugin(const QString &name);
213 
214  //
215  // Signals related to application plugins
216  //
217 Q_SIGNALS:
218  /**
219  * This signal is emitted when an Plugin was loaded.
220  *
221  * @param name name of plugin
222  * @param plugin the new plugin
223  */
224  void pluginCreated(const QString &name, KTextEditor::Plugin *plugin);
225 
226  /**
227  * This signal is emitted when an Plugin got deleted.
228  *
229  * @param name name of plugin
230  * @param plugin the deleted plugin
231  *
232  * @warning Do not access the data referenced by the pointer, it is already invalid.
233  * Use the pointer only to remove mappings in hash or maps
234  */
235  void pluginDeleted(const QString &name, KTextEditor::Plugin *plugin);
236 
237 private:
238  /**
239  * Private d-pointer class is our best friend ;)
240  */
241  friend class ApplicationPrivate;
242 
243  /**
244  * Private d-pointer
245  */
246  class ApplicationPrivate *const d;
247 };
248 
249 } // namespace KTextEditor
250 
251 #endif
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
KTextEditor Plugin interface.
Definition: plugin.h:78
A KParts derived class representing a text document.
Definition: document.h:185
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Mar 23 2023 03:59:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.