File indexing completed on 2024-05-12 15:45:39
0001 /* 0002 SPDX-FileCopyrightText: 2013 Christoph Cullmann <cullmann@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KTEXTEDITOR_APPLICATION_H 0008 #define KTEXTEDITOR_APPLICATION_H 0009 0010 #include <ktexteditor_export.h> 0011 0012 #include <QObject> 0013 0014 namespace KTextEditor 0015 { 0016 class Plugin; 0017 class Document; 0018 class MainWindow; 0019 0020 /** 0021 * \class Application application.h <KTextEditor/Application> 0022 * 0023 * This class allows the application that embeds the KTextEditor component to 0024 * allow it access to application wide information and interactions. 0025 * 0026 * For example the component can get the current active main window of the application. 0027 * 0028 * The application must pass a pointer to the Application object to the setApplication method of the 0029 * global editor instance and ensure that this object stays valid for the complete lifetime of the editor. 0030 * 0031 * It must not reimplement this class but construct an instance and pass a pointer to a QObject that 0032 * has the required slots to receive the requests. 0033 * 0034 * KTextEditor::Editor::instance()->application() will always return a non-nullptr object 0035 * to avoid the need for nullptr checks before calling the API. 0036 * 0037 * The same holds for activeMainWindow(), even if no main window is around, you will get a non-nullptr 0038 * interface object that allows to call the functions of the MainWindow without needs for a nullptr 0039 * check around it in the client code. 0040 */ 0041 class KTEXTEDITOR_EXPORT Application : public QObject 0042 { 0043 Q_OBJECT 0044 0045 public: 0046 /** 0047 * Construct an Application wrapper object. 0048 * The passed parent is both the parent of this QObject and the receiver of all interface 0049 * calls via invokeMethod. 0050 * @param parent object the calls are relayed to 0051 */ 0052 Application(QObject *parent); 0053 0054 /** 0055 * Virtual Destructor 0056 */ 0057 ~Application() override; 0058 0059 /** 0060 * Ask app to quit. The app might interact with the user and decide that 0061 * quitting is not possible and return false. 0062 * 0063 * \return true if the app could quit 0064 */ 0065 bool quit(); 0066 0067 // 0068 // MainWindow related accessors 0069 // 0070 public: 0071 /** 0072 * Get a list of all main windows. 0073 * @return all main windows, might be empty! 0074 */ 0075 QList<KTextEditor::MainWindow *> mainWindows(); 0076 0077 /** 0078 * Accessor to the active main window. 0079 * \return a pointer to the active mainwindow, even if no main window is active you 0080 * will get a non-nullptr dummy interface that allows you to call interface functions 0081 * without the need for null checks 0082 */ 0083 KTextEditor::MainWindow *activeMainWindow(); 0084 0085 // 0086 // Document related accessors 0087 // 0088 public: 0089 /** 0090 * Get a list of all documents that are managed by the application. 0091 * This might contain less documents than the editor has in his documents () list. 0092 * @return all documents the application manages, might be empty! 0093 */ 0094 QList<KTextEditor::Document *> documents(); 0095 0096 /** 0097 * Get the document with the URL \p url. 0098 * if multiple documents match the searched url, return the first found one... 0099 * \param url the document's URL 0100 * \return the document with the given \p url or nullptr, if none found 0101 */ 0102 KTextEditor::Document *findUrl(const QUrl &url); 0103 0104 /** 0105 * Open the document \p url with the given \p encoding. 0106 * if the url is empty, a new empty document will be created 0107 * \param url the document's url 0108 * \param encoding the preferred encoding. If encoding is QString() the 0109 * encoding will be guessed or the default encoding will be used. 0110 * \return a pointer to the created document 0111 */ 0112 KTextEditor::Document *openUrl(const QUrl &url, const QString &encoding = QString()); 0113 0114 /** 0115 * Close the given \p document. If the document is modified, user will be asked if he wants that. 0116 * \param document the document to be closed 0117 * \return \e true on success, otherwise \e false 0118 */ 0119 bool closeDocument(KTextEditor::Document *document); 0120 0121 /** 0122 * Close a list of documents. If any of them are modified, user will be asked if he wants that. 0123 * Use this, if you want to close multiple documents at once, as the application might 0124 * be able to group the "do you really want that" dialogs into one. 0125 * \param documents list of documents to be closed 0126 * \return \e true on success, otherwise \e false 0127 */ 0128 bool closeDocuments(const QList<KTextEditor::Document *> &documents); 0129 0130 Q_SIGNALS: 0131 /** 0132 * This signal is emitted when the \p document was created. 0133 * 0134 * @param document document that was created 0135 */ 0136 void documentCreated(KTextEditor::Document *document); 0137 0138 /** 0139 * This signal is emitted before a \p document which should be closed is deleted 0140 * The document is still accessible and usable, but it will be deleted 0141 * after this signal was send. 0142 * 0143 * @param document document that will be deleted 0144 */ 0145 void documentWillBeDeleted(KTextEditor::Document *document); 0146 0147 /** 0148 * This signal is emitted when the \p document has been deleted. 0149 * 0150 * @warning Do not access the data referenced by the pointer, it is already invalid. 0151 * Use the pointer only to remove mappings in hash or maps 0152 * 0153 * @param document document that is deleted 0154 */ 0155 void documentDeleted(KTextEditor::Document *document); 0156 0157 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80) 0158 /** 0159 * This signal is emitted before the batch of documents is being created. 0160 * 0161 * You can use it to pause some updates. 0162 * @deprecated Since 5.80, Deprecated due to lack of usage 0163 */ 0164 KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Deprecated due to lack of usage") 0165 void aboutToCreateDocuments(); 0166 #endif 0167 0168 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80) 0169 /** 0170 * This signal is emitted after the batch of documents is created. 0171 * 0172 * @param documents list of documents that have been created 0173 * @deprecated Since 5.80, use documentCreated(KTextEditor::Document *document) instead 0174 */ 0175 KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentCreated(KTextEditor::Document *document) instead") 0176 void documentsCreated(const QList<KTextEditor::Document *> &documents); 0177 #endif 0178 0179 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80) 0180 /** 0181 * This signal is emitted before the documents batch is going to be deleted 0182 * 0183 * note that the batch can be interrupted in the middle and only some 0184 * of the documents may be actually deleted. See documentsDeleted() signal. 0185 * @deprecated Since 5.80, use documentWillBeDeleted(KTextEditor::Document *document) instead 0186 */ 0187 KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentWillBeDeleted(KTextEditor::Document *document) instead") 0188 void aboutToDeleteDocuments(const QList<KTextEditor::Document *> &); 0189 #endif 0190 0191 #if KTEXTEDITOR_ENABLE_DEPRECATED_SINCE(5, 80) 0192 /** 0193 * This signal is emitted after the documents batch was deleted 0194 * 0195 * This is the batch closing signal for aboutToDeleteDocuments 0196 * @param documents the documents that weren't deleted after all 0197 * @deprecated Since 5.80, use documentDeleted(KTextEditor::Document *document) instead 0198 */ 0199 KTEXTEDITOR_DEPRECATED_VERSION(5, 80, "Use documentDeleted(KTextEditor::Document *document) instead") 0200 void documentsDeleted(const QList<KTextEditor::Document *> &documents); 0201 #endif 0202 0203 // 0204 // Application plugin accessors 0205 // 0206 public: 0207 /** 0208 * Get a plugin for the plugin with with identifier \p name. 0209 * \param name the plugin's name 0210 * \return pointer to the plugin if a plugin with \p name is loaded, otherwise nullptr 0211 */ 0212 KTextEditor::Plugin *plugin(const QString &name); 0213 0214 // 0215 // Signals related to application plugins 0216 // 0217 Q_SIGNALS: 0218 /** 0219 * This signal is emitted when an Plugin was loaded. 0220 * 0221 * @param name name of plugin 0222 * @param plugin the new plugin 0223 */ 0224 void pluginCreated(const QString &name, KTextEditor::Plugin *plugin); 0225 0226 /** 0227 * This signal is emitted when an Plugin got deleted. 0228 * 0229 * @param name name of plugin 0230 * @param plugin the deleted plugin 0231 * 0232 * @warning Do not access the data referenced by the pointer, it is already invalid. 0233 * Use the pointer only to remove mappings in hash or maps 0234 */ 0235 void pluginDeleted(const QString &name, KTextEditor::Plugin *plugin); 0236 0237 private: 0238 /** 0239 * Private d-pointer class is our best friend ;) 0240 */ 0241 friend class ApplicationPrivate; 0242 0243 /** 0244 * Private d-pointer 0245 */ 0246 class ApplicationPrivate *const d; 0247 }; 0248 0249 } // namespace KTextEditor 0250 0251 #endif