KTextEditor

include/ktexteditor/command.h
1/*
2 SPDX-FileCopyrightText: 2005 Christoph Cullmann <cullmann@kde.org>
3 SPDX-FileCopyrightText: 2005-2006 Dominik Haumann <dhdev@gmx.de>
4 SPDX-FileCopyrightText: 2008 Erlend Hamberg <ehamberg@gmail.com>
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
19class KCompletion;
20
21namespace KTextEditor
22{
23class 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 <cullmann@kde.org>
69 */
70class KTEXTEDITOR_EXPORT Command : public QObject
71{
72 Q_OBJECT
73
74public:
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
87public:
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
179private:
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.
virtual bool help(KTextEditor::View *view, const QString &cmd, QString &msg)=0
Shows help for the given view and cmd string.
const QStringList & cmds() const
Return a list of strings a command may begin with.
virtual bool exec(KTextEditor::View *view, const QString &cmd, QString &msg, const KTextEditor::Range &range=KTextEditor::Range::invalid())=0
Execute the command for the given view and cmd string.
An object representing a section of text, from one Cursor to another.
static constexpr Range invalid() noexcept
Returns an invalid range.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 12:01:51 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.