File indexing completed on 2024-05-12 15:45:40
0001 /* 0002 SPDX-FileCopyrightText: 2005-2014 Christoph Cullmann <cullmann@kde.org> 0003 SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <dhaumann@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KTEXTEDITOR_EDITOR_H 0009 #define KTEXTEDITOR_EDITOR_H 0010 0011 #include <ktexteditor_export.h> 0012 0013 #include <QObject> 0014 #include <QVector> 0015 0016 // theme support 0017 #include <KSyntaxHighlighting/Theme> 0018 0019 class KAboutData; 0020 class KConfig; 0021 0022 namespace KSyntaxHighlighting 0023 { 0024 class Repository; 0025 } 0026 0027 /** 0028 * The KTextEditor namespace contains all the public API that is required 0029 * to use the KTextEditor component. Using the KTextEditor interfaces is 0030 * described in the article \ref index. 0031 * 0032 * @warning All classes that are \e not part of the KTextEditor namespace 0033 * are internal and subject to change. We mean it! 0034 */ 0035 namespace KTextEditor 0036 { 0037 class Application; 0038 class Command; 0039 class Document; 0040 class View; 0041 class EditorPrivate; 0042 class ConfigPage; 0043 0044 /** 0045 * \class Editor editor.h <KTextEditor/Editor> 0046 * 0047 * \brief Accessor interface for the KTextEditor framework. 0048 * 0049 * Topics: 0050 * - \ref editor_intro 0051 * - \ref editor_config 0052 * - \ref editor_commands 0053 * 0054 * \section editor_intro Introduction 0055 * 0056 * The Editor part can either be accessed through the static accessor Editor::instance() 0057 * or through the KParts component model (see \ref kte_design_part). 0058 * The Editor singleton provides general information and configuration methods 0059 * for the Editor, for example KAboutData by using aboutData(). 0060 * 0061 * The Editor has a list of all opened documents. Get this list with documents(). 0062 * To create a new Document call createDocument(). The signal documentCreated() 0063 * is emitted whenever the Editor created a new document. 0064 * 0065 * \section editor_config Editor Configuration 0066 * 0067 * The config dialog can be shown with configDialog(). 0068 * Instead of using the config dialog, the config pages can also be embedded 0069 * into the application's config dialog. To do this, configPages() returns the 0070 * number of config pages that exist and configPage() returns the requested 0071 * page. The configuration are saved automatically by the Editor. 0072 * 0073 * \note It is recommended to embed the config pages into the main application's 0074 * config dialog instead of using a separate config dialog, if the config 0075 * dialog does not look cluttered then. This way, all settings are grouped 0076 * together in one place. 0077 * 0078 * \section editor_commands Command Line Commands 0079 * 0080 * With Commands it is possible to add new commands to the command line. 0081 * These Command%s then are added to all document View%s. 0082 * Common use cases include commands like \e find or setting document variables. 0083 * The list of all registered commands can be obtained either through commandList() 0084 * or through commands(). Further, a specific command can be obtained through 0085 * queryCommand(). For further information, read the Command API documentation. 0086 * 0087 * \see KTextEditor::Document, KTextEditor::ConfigPage, KTextEditor::Command 0088 * \author Christoph Cullmann \<cullmann@kde.org\> 0089 */ 0090 class KTEXTEDITOR_EXPORT Editor : public QObject 0091 { 0092 Q_OBJECT 0093 0094 protected: 0095 /** 0096 * Constructor. 0097 * 0098 * Create the Editor object and pass it the internal 0099 * implementation to store a d-pointer. 0100 * 0101 * @param impl d-pointer to use 0102 */ 0103 Editor(EditorPrivate *impl); 0104 0105 /** 0106 * Virtual destructor. 0107 */ 0108 ~Editor() override; 0109 0110 public: 0111 /** 0112 * Accessor to get the Editor instance. 0113 * 0114 * @note This object will stay alive until QCoreApplication terminates. 0115 * You shall not delete it yourself. 0116 * There is only ONE Editor instance of this per process. 0117 * 0118 * \return Editor controller, after initial construction, will 0119 * live until QCoreApplication is terminating. 0120 */ 0121 static Editor *instance(); 0122 0123 public: 0124 /** 0125 * Set the global application object. 0126 * This will allow the editor component to access 0127 * the hosting application. 0128 * @param application application object 0129 * if the argument is a nullptr, this will reset the application back to a dummy interface 0130 */ 0131 virtual void setApplication(KTextEditor::Application *application) = 0; 0132 0133 /** 0134 * Current hosting application, if any set. 0135 * @return current application object or a dummy interface that allows you to call the functions 0136 * will never return a nullptr 0137 */ 0138 virtual KTextEditor::Application *application() const = 0; 0139 0140 /* 0141 * Methods to create and manage the documents. 0142 */ 0143 public: 0144 /** 0145 * Create a new document object with \p parent. 0146 * 0147 * For each created document, the signal documentCreated() is emitted. 0148 * 0149 * \param parent parent object 0150 * \return new KTextEditor::Document object 0151 * \see documents(), documentCreated() 0152 */ 0153 virtual Document *createDocument(QObject *parent) = 0; 0154 0155 /** 0156 * Get a list of all documents of this editor. 0157 * \return list of all existing documents 0158 * \see createDocument() 0159 */ 0160 virtual QList<Document *> documents() = 0; 0161 0162 Q_SIGNALS: 0163 /** 0164 * The \p editor emits this signal whenever a \p document was successfully 0165 * created. 0166 * \param editor pointer to the Editor singleton which created the new document 0167 * \param document the newly created document instance 0168 * \see createDocument() 0169 */ 0170 void documentCreated(KTextEditor::Editor *editor, KTextEditor::Document *document); 0171 0172 /* 0173 * General Information about this editor. 0174 */ 0175 public: 0176 /** 0177 * Get the about data of this Editor part. 0178 * \return about data 0179 */ 0180 virtual const KAboutData &aboutData() const = 0; 0181 0182 /** 0183 * Get the current default encoding for this Editor part. 0184 * \return default encoding 0185 */ 0186 QString defaultEncoding() const; 0187 0188 /* 0189 * Configuration management. 0190 */ 0191 public: 0192 /** 0193 * Show the editor's config dialog, changes will be applied to the 0194 * editor and the configuration changes are saved. 0195 * 0196 * \note Instead of using the config dialog, the config pages can be 0197 * embedded into your own config dialog by using configPages() and 0198 * configPage(). 0199 * \param parent parent widget 0200 */ 0201 virtual void configDialog(QWidget *parent) = 0; 0202 0203 /** 0204 * Get the number of available config pages. 0205 * If a number < 1 is returned, it does not support config pages. 0206 * \return number of config pages 0207 * \see configPage() 0208 */ 0209 virtual int configPages() const = 0; 0210 0211 /** 0212 * Get the config page with the \p number, config pages from 0 to 0213 * configPages()-1 are available if configPages() > 0. 0214 * Configuration changes done over this widget are automatically 0215 * saved. 0216 * \param number index of config page 0217 * \param parent parent widget for config page 0218 * \return created config page or NULL, if the number is out of bounds 0219 * \see configPages() 0220 */ 0221 virtual ConfigPage *configPage(int number, QWidget *parent) = 0; 0222 0223 Q_SIGNALS: 0224 /** 0225 * This signal is emitted whenever the editor configuration is changed. 0226 * 0227 * \param editor the editor which's config has changed 0228 * 0229 * \since 5.79 0230 */ 0231 void configChanged(KTextEditor::Editor *editor); 0232 0233 public: 0234 /** 0235 * Get the current global editor font. 0236 * Might change during runtime, configChanged() will be emitted in that cases. 0237 * Individual views might have set different fonts, can be queried with the "font" key via \see KTextEditor::ConfigInterface::configValue(). 0238 * 0239 * \return current global font for all views 0240 * 0241 * \since 5.80 0242 */ 0243 QFont font() const; 0244 0245 /** 0246 * Get the current global theme. 0247 * Might change during runtime, configChanged() will be emitted in that cases. 0248 * Individual views might have set different themes, \see KTextEditor::View::theme(). 0249 * 0250 * \return current global theme for all views 0251 * 0252 * \since 5.79 0253 */ 0254 KSyntaxHighlighting::Theme theme() const; 0255 0256 public: 0257 /** 0258 * Get read-only access to the syntax highlighting repository the editor uses. 0259 * Might be reloaded during runtime, repositoryReloaded() will be emitted in that cases. 0260 * 0261 * \return syntax repository used by the editor 0262 * 0263 * \since 5.79 0264 */ 0265 const KSyntaxHighlighting::Repository &repository() const; 0266 0267 Q_SIGNALS: 0268 /** 0269 * This signal is emitted whenever the editor syntax repository is reloaded. 0270 * Can be used to e.g. re-instantiate syntax definitions that got invalidated by 0271 * the repository reload. 0272 * 0273 * \param editor the editor which's repository was reloaded 0274 * 0275 * \since 5.79 0276 */ 0277 void repositoryReloaded(KTextEditor::Editor *editor); 0278 0279 public: 0280 /** 0281 * Query for the command \p cmd. 0282 * If the command \p cmd does not exist the return value is NULL. 0283 * 0284 * \param cmd name of command to query for 0285 * \return the found command or NULL if no such command exists 0286 */ 0287 virtual Command *queryCommand(const QString &cmd) const = 0; 0288 0289 /** 0290 * Get a list of all registered commands. 0291 * \return list of all commands 0292 * \see queryCommand(), commandList() 0293 */ 0294 virtual QList<Command *> commands() const = 0; 0295 0296 /** 0297 * Get a list of available command line strings. 0298 * \return command line strings 0299 * \see commands() 0300 */ 0301 virtual QStringList commandList() const = 0; 0302 0303 public: 0304 /** 0305 * Function that is called to expand a variable in @p text. 0306 */ 0307 // TODO KF6: Use std::function to allow captures (context via closure) 0308 // using ExpandFunction = std::function<QString(const QStringView &text, KTextEditor::View *view)>; 0309 using ExpandFunction = QString (*)(const QStringView &text, KTextEditor::View *view); 0310 0311 /** 0312 * Registers a variable called @p name for exact matches. 0313 * For instance, a variable called "CurrentDocument:Path" could be 0314 * registered which then expands to the path the current document. 0315 * 0316 * @return true on success, false if the variable could not be registered, 0317 * e.g. because it already was registered previously. 0318 * 0319 * @since 5.57 0320 */ 0321 bool registerVariableMatch(const QString &name, const QString &description, ExpandFunction expansionFunc); 0322 0323 /** 0324 * Registers a variable for arbitrary text that matches the specified 0325 * prefix. For instance, a variable called "ENV:" could be registered 0326 * which then expands arbitrary environment variables, e.g. ENV:HOME 0327 * would expand to the user's home directory. 0328 * 0329 * @note A colon ':' is used as separator for the prefix and the text 0330 * after the colon that should be evaluated. 0331 * 0332 * @return true on success, false if a prefix could not be registered, 0333 * e.g. because it already was registered previously. 0334 * 0335 * @since 5.57 0336 */ 0337 bool registerVariablePrefix(const QString &prefix, const QString &description, ExpandFunction expansionFunc); 0338 0339 /** 0340 * Unregisters a variable that was previously registered with 0341 * registerVariableMatch(). 0342 * 0343 * @return true if the variable was successfully unregistered, and 0344 * false if the variable did not exist. 0345 * 0346 * @since 5.57 0347 */ 0348 bool unregisterVariableMatch(const QString &variable); 0349 0350 // TODO KF6: merge "unregisterVariableMatch()" and "unregisterVariablePrefix()" into 0351 // a single function "unregisterVariable(const QString& name)". 0352 /** 0353 * Unregisters a prefix of variable that was previously registered with 0354 * registerVariableMatch(). 0355 * 0356 * @return true if the variable was successfully unregistered, and 0357 * false if the variable did not exist. 0358 * 0359 * @since 5.57 0360 */ 0361 bool unregisterVariablePrefix(const QString &variable); 0362 0363 /** 0364 * Expands a single @p variable, writing the expanded value to @p output. 0365 * 0366 * @return true on success, otherwise false. 0367 * 0368 * @since 5.57 0369 */ 0370 bool expandVariable(const QString &variable, KTextEditor::View *view, QString &output) const; 0371 0372 // TODO KF6: turn expandText into: QString expandText(text, view) to avoid output argument 0373 /** 0374 * Expands arbitrary @p text that may contain arbitrary many variables. 0375 * On success, the expanded text is written to @p output. 0376 * 0377 * @since 5.57 0378 */ 0379 void expandText(const QString &text, KTextEditor::View *view, QString &output) const; 0380 0381 /** 0382 * Adds a QAction to the widget in @p widgets that whenever focus is 0383 * gained. When the action is invoked, a non-modal dialog is shown that 0384 * lists all @p variables. If @p variables is non-empty, then only the 0385 * variables in @p variables are listed. 0386 * 0387 * The supported QWidgets in the @p widgets argument currently are: 0388 * - QLineEdit 0389 * - QTextEdit 0390 * 0391 * @since 5.63 0392 */ 0393 void addVariableExpansion(const QVector<QWidget *> &widgets, const QStringList &variables = QStringList()) const; 0394 0395 private: 0396 /** 0397 * private d-pointer, pointing to the internal implementation 0398 */ 0399 EditorPrivate *const d; 0400 }; 0401 0402 } 0403 0404 #endif