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 
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  * @ref kte_plugin_hosting
42  */
43 class KTEXTEDITOR_EXPORT Application : public QObject
44 {
45  Q_OBJECT
46 
47 public:
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  //
72 public:
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  //
90 public:
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 
132 Q_SIGNALS:
133  /**
134  * This signal is emitted when the \p document was created.
135  *
136  * @param document document that was created
137  */
138  void documentCreated(KTextEditor::Document *document);
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  */
147  void documentWillBeDeleted(KTextEditor::Document *document);
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  */
157  void documentDeleted(KTextEditor::Document *document);
158 
159  //
160  // Application plugin accessors
161  //
162 public:
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  //
173 Q_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 
193 private:
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
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:19
KTextEditor Plugin interface.
Definition: plugin.h:78
A KParts derived class representing a text document.
Definition: document.h:283
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:50:42 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.