KTextEditor

include/ktexteditor/command.h
1 /*
2  SPDX-FileCopyrightText: 2005 Christoph Cullmann <[email protected]>
3  SPDX-FileCopyrightText: 2005-2006 Dominik Haumann <[email protected]>
4  SPDX-FileCopyrightText: 2008 Erlend Hamberg <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KTEXTEDITOR_COMMAND_H
10 #define KTEXTEDITOR_COMMAND_H
11 
12 #include <KCompletion>
13 #include <ktexteditor/range.h>
14 #include <ktexteditor_export.h>
15 
16 #include <QObject>
17 #include <QStringList>
18 
19 class KCompletion;
20 
21 namespace KTextEditor
22 {
23 class View;
24 
25 /**
26  * \class Command command.h <KTextEditor/Command>
27  *
28  * \brief An Editor command line command.
29  *
30  * \section cmd_intro Introduction
31  *
32  * The Command class represents a command for the editor command line. A
33  * command simply consists of a string, for example \e find. The command
34  * auto-registers itself at the Editor. The Editor itself queries
35  * the command for a list of accepted strings/commands by calling cmds().
36  * If the command gets invoked the function exec() is called, i.e. you have
37  * to implement the \e reaction in exec(). Whenever the user needs help for
38  * a command help() is called.
39  *
40  * \section cmd_information Command Information
41  * To provide reasonable information about a specific command there are the
42  * following accessor functions for a given command string:
43  * - name() returns a label
44  * - description() returns a descriptive text
45  * - category() returns a category into which the command fits.
46  *
47  * These getters allow KTextEditor implementations to plug commands into menus
48  * and toolbars, so that a user can assign shortcuts.
49  *
50  * \section cmd_completion Command Completion
51  *
52  * The Command optionally can show a completion popup to help the user select
53  * a valid entry as first parameter to the Command. To this end, return a
54  * valid completion item by reiplementing completionObject().
55  *
56  * The returned completion object is deleted automatically once it is not needed
57  * anymore. Therefore neither delete the completion object yourself nor return
58  * the same completion object twice.
59  *
60  * \section cmd_interactive Interactive Commands
61  *
62  * In case the Command needs to interactively process the text of the parameters,
63  * override wantsToProcessText() by returning @e true and reimplement processText().
64  *
65  * A typical example of an iterative command would be the incremental search.
66  *
67  * \see KTextEditor::CommandInterface
68  * \author Christoph Cullmann <[email protected]>
69  */
70 class KTEXTEDITOR_EXPORT Command : public QObject
71 {
72  Q_OBJECT
73 
74 public:
75  /**
76  * Constructor with \p parent.
77  * Will register this command for the commands names given in \p cmds at the global editor instance.
78  */
79  Command(const QStringList &cmds, QObject *parent = nullptr);
80 
81  /**
82  * Virtual destructor.
83  * Will unregister this command at the global editor instance.
84  */
85  ~Command() override;
86 
87 public:
88  /**
89  * Return a list of strings a command may begin with.
90  * This is the same list the command was constructed with.
91  * A string is the start part of a pure text which can be handled by this
92  * command, i.e. for the command s/sdl/sdf/g the corresponding string is
93  * simply \e s, and for char:1212 simply \e char.
94  * \return list of supported commands
95  */
96  inline const QStringList &cmds() const
97  {
98  return m_cmds;
99  }
100 
101  /**
102  * Find out if a given command can act on a range. This is used for checking
103  * if a command should be called when the user also gave a range or if an
104  * error should be raised.
105  *
106  * \return \e true if command supports acting on a range of lines, \e false
107  * not. The default implementation returns \e false.
108  */
109  virtual bool supportsRange(const QString &cmd);
110 
111  /**
112  * Execute the command for the given \p view and \p cmd string.
113  * Return the success value and a \p msg for status. As example we
114  * consider a replace command. The replace command would return the number
115  * of replaced strings as \p msg, like "16 replacements made." If an error
116  * occurred in the usage it would return \e false and set the \p msg to
117  * something like "missing argument." or such.
118  *
119  * If a non-invalid range is given, the command shall be executed on that range.
120  * supportsRange() tells if the command supports that.
121  *
122  * \return \e true on success, otherwise \e false
123  */
124  virtual bool exec(KTextEditor::View *view, const QString &cmd, QString &msg, const KTextEditor::Range &range = KTextEditor::Range::invalid()) = 0;
125 
126  /**
127  * Shows help for the given \p view and \p cmd string.
128  * If your command has a help text for \p cmd you have to return \e true
129  * and set the \p msg to a meaningful text. The help text is embedded by
130  * the Editor in a Qt::RichText enabled widget, e.g. a QToolTip.
131  * \return \e true if your command has a help text, otherwise \e false
132  */
133  virtual bool help(KTextEditor::View *view, const QString &cmd, QString &msg) = 0;
134 
135  /**
136  * Return a KCompletion object that will substitute the command line
137  * default one while typing the first argument of the command \p cmdname.
138  * The text will be added to the command separated by one space character.
139  *
140  * Override this method if your command can provide a completion object.
141  * The returned completion object is deleted automatically once it is not needed
142  * anymore. Therefore neither delete the completion object yourself nor return
143  * the same completion object twice.
144  *
145  * The default implementation returns a null pointer (\e nullptr).
146  *
147  * \param view the view the command will work on
148  * \param cmdname the command name associated with this request.
149  * \return a valid completion object or \e nullptr, if a completion object is
150  * not supported
151  */
152  virtual KCompletion *completionObject(KTextEditor::View *view, const QString &cmdname);
153 
154  /**
155  * Check, whether the command wants to process text interactively for the
156  * given command with name \p cmdname.
157  * If you return true, the command's processText() method is called
158  * whenever the text in the command line changed.
159  *
160  * Reimplement this to return true, if your commands wants to process the
161  * text while typing.
162  *
163  * \param cmdname the command name associated with this query.
164  * \return \e true, if your command wants to process text interactively,
165  * otherwise \e false
166  * \see processText()
167  */
168  virtual bool wantsToProcessText(const QString &cmdname);
169 
170  /**
171  * This is called by the command line each time the argument text for the
172  * command changed, if wantsToProcessText() returns \e true.
173  * \param view the current view
174  * \param text the current command text typed by the user
175  * \see wantsToProcessText()
176  */
177  virtual void processText(KTextEditor::View *view, const QString &text);
178 
179 private:
180  /**
181  * the command list this command got constructed with
182  */
183  const QStringList m_cmds;
184 
185  /**
186  * Private d-pointer
187  */
188  class CommandPrivate *const d;
189 };
190 
191 }
192 
193 #endif
An Editor command line command.
const QStringList & cmds() const
Return a list of strings a command may begin with.
An object representing a section of text, from one Cursor to another.
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
constexpr static Range invalid() Q_DECL_NOEXCEPT
Returns an invalid range.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 4 2023 03:52:10 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.