1/* This file is part of the KDE project
2 Copyright (C) 2005 Christoph Cullmann (cullmann@kde.org)
3 Copyright (C) 2005-2006 Dominik Haumann (dhdev@gmx.de)
4 Copyright (C) 2008 Erlend Hamberg (ehamberg@gmail.com)
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KDELIBS_KTEXTEDITOR_COMMANDINTERFACE_H
23#define KDELIBS_KTEXTEDITOR_COMMANDINTERFACE_H
24
25#include <ktexteditor/ktexteditor_export.h>
26#include <ktexteditor/range.h>
27#include <QtCore/QObject>
28
29class QStringList;
30class KCompletion;
31
32namespace KTextEditor
33{
34
35class Editor;
36class View;
37
38/**
39 * \brief An Editor command line command.
40 *
41 * \section cmd_intro Introduction
42 *
43 * The Command class represents a command for the editor command line. A
44 * command simply consists of a string, for example \e find. To register a
45 * command use CommandInterface::registerCommand(). The Editor itself queries
46 * the command for a list of accepted strings/commands by calling cmds().
47 * If the command gets invoked the function exec() is called, i.e. you have
48 * to implement the \e reaction in exec(). Whenever the user needs help for
49 * a command help() is called.
50 *
51 * \section cmd_information Command Information
52 * To provide reasonable information about a specific command there are the
53 * following accessor functions for a given command string:
54 * - name() returns a label
55 * - description() returns a descriptive text
56 * - category() returns a category into which the command fits.
57 *
58 * These getters allow KTextEditor implementations to plug commands into menus
59 * and toolbars, so that a user can assign shortcuts.
60 *
61 * \section cmd_extension Command Extensions
62 *
63 * If your command needs to interactively react on changes while the user is
64 * typing text - look at the \e ifind command in Kate for example - you have
65 * to additionally derive your command from the class CommandExtension. The
66 * command extension provides methods to give help on \e flags or add a
67 * KCompletion object and process the typed text interactively. Besides that
68 * the class RangeCommand enables you to support ranges so that you can apply
69 * commands on regions of text.
70 *
71 * \see KTextEditor::CommandInterface, KTextEditor::CommandExtension,
72 * KTextEditor::RangeCommand
73 * \author Christoph Cullmann \<cullmann@kde.org\>
74 * \note KDE5: derive from QObject, so qobject_cast works for extension interfaces.
75 */
76class KTEXTEDITOR_EXPORT Command
77{
78 public:
79 /**
80 * Virtual destructor.
81 */
82 virtual ~Command () {}
83
84 public:
85 /**
86 * Return a list of strings a command may begin with.
87 * A string is the start part of a pure text which can be handled by this
88 * command, i.e. for the command s/sdl/sdf/g the corresponding string is
89 * simply \e s, and for char:1212 simply \e char.
90 * \return list of supported commands
91 */
92 virtual const QStringList &cmds () = 0;
93
94 /**
95 * Execute the command for the given \p view and \p cmd string.
96 * Return the success value and a \p msg for status. As example we
97 * consider a replace command. The replace command would return the number
98 * of replaced strings as \p msg, like "16 replacements made." If an error
99 * occurred in the usage it would return \e false and set the \p msg to
100 * something like "missing argument." or such.
101 *
102 * \return \e true on success, otherwise \e false
103 */
104 virtual bool exec (KTextEditor::View *view, const QString &cmd, QString &msg) = 0;
105
106 /**
107 * Shows help for the given \p view and \p cmd string.
108 * If your command has a help text for \p cmd you have to return \e true
109 * and set the \p msg to a meaningful text. The help text is embedded by
110 * the Editor in a Qt::RichText enabled widget, e.g. a QToolTip.
111 * \return \e true if your command has a help text, otherwise \e false
112 */
113 virtual bool help (KTextEditor::View *view, const QString &cmd, QString &msg) = 0;
114};
115
116/**
117 * \brief Extension interface for a Command.
118 *
119 * \ingroup kte_group_command_extensions
120 *
121 * \section cmdext_intro Introduction
122 *
123 * The CommandExtension extends the Command interface allowing to interact
124 * with commands during typing. This allows for completion and for example
125 * the isearch plugin. If you develop a command that wants to complete or
126 * process text as the user types the arguments, or that has flags, you can
127 * have your command inherit this class.
128 *
129 * If your command supports flags return them by reimplementing
130 * flagCompletions(). You can return your own KCompletion object if the
131 * command has available completion data. If you want to interactively react
132 * on changes return \e true in wantsToProcessText() for the given command
133 * and reimplement processText().
134 *
135 * \see KTextEditor::CommandInterface, KTextEditor::Command, KCompletion
136 * \author Christoph Cullmann \<cullmann@kde.org\>
137 */
138class KTEXTEDITOR_EXPORT CommandExtension
139{
140 public:
141 /**
142 * Virtual destructor.
143 */
144 virtual ~CommandExtension() {}
145
146 /**
147 * Fill in a \p list of flags to complete from. Each flag is a single
148 * letter, any following text in the string is taken to be a description
149 * of the flag's meaning, and showed to the user as a hint.
150 * Implement this method if your command has flags.
151 *
152 * This method is called each time the flag string in the typed command
153 * is changed, so that the available flags can be adjusted. When
154 * completions are displayed, existing flags are left out.
155 * \param list flag list
156 */ //### this is yet to be tried
157 virtual void flagCompletions( QStringList&list ) = 0;
158
159 /**
160 * Return a KCompletion object that will substitute the command line
161 * default one while typing the first argument of the command \p cmdname.
162 * The text will be added to the command separated by one space character.
163 *
164 * Implement this method if your command can provide a completion object.
165 *
166 * \param view the view the command will work on
167 * \param cmdname the command name associated with this request.
168 * \return the completion object or NULL, if you do not support a
169 * completion object
170 */
171 virtual KCompletion *completionObject( KTextEditor::View *view,
172 const QString & cmdname ) = 0;
173
174 /**
175 * Check, whether the command wants to process text interactively for the
176 * given command with name \p cmdname.
177 * If you return true, the command's processText() method is called
178 * whenever the text in the command line changed.
179 *
180 * Reimplement this to return true, if your commands wants to process the
181 * text while typing.
182 *
183 * \param cmdname the command name associated with this query.
184 * \return \e true, if your command wants to process text interactively,
185 * otherwise \e false
186 * \see processText()
187 */
188 virtual bool wantsToProcessText( const QString &cmdname ) = 0;
189
190 /**
191 * This is called by the command line each time the argument text for the
192 * command changed, if wantsToProcessText() returns \e true.
193 * \param view the current view
194 * \param text the current command text typed by the user
195 * \see wantsToProcessText()
196 */ // ### yet to be tested. The obvious candidate is isearch.
197 virtual void processText( KTextEditor::View *view, const QString &text ) = 0;
198};
199
200/**
201 * \brief Command extension interface for the Editor.
202 *
203 * \ingroup kte_group_editor_extensions
204 *
205 * \section cmdiface_intro Introduction
206 *
207 * The CommandInterface extends the Editor to support command line commands.
208 * An application or a Plugin can register new commands by using
209 * registerCommand(). To unregister a command call unregisterCommand(). To
210 * check, whether a command with a given name exists use queryCommand().
211 *
212 * \section cmdiface_access Accessing the CommandInterface
213 *
214 * The CommandInterface is supposed to be an extension interface for the
215 * Editor, i.e. the Editor inherits the interface \e provided that the
216 * used KTextEditor library implements the interface. Use qobject_cast to
217 * access the interface:
218 * \code
219 * // editor is of type KTextEditor::Editor*
220 * KTextEditor::CommandInterface *iface =
221 * qobject_cast<KTextEditor::CommandInterface*>( editor );
222 *
223 * if( iface ) {
224 * // the implementation supports the interface
225 * // do stuff
226 * }
227 * \endcode
228 *
229 * \see KTextEditor::Editor, KTextEditor::Command,
230 * KTextEditor::CommandExtension
231 * \author Christoph Cullmann \<cullmann@kde.org\>
232 */
233class KTEXTEDITOR_EXPORT CommandInterface
234{
235 public:
236 /**
237 * Virtual destructor.
238 */
239 virtual ~CommandInterface () {}
240
241 public:
242 /**
243 * Register a the new command \p cmd. The command will be registered for
244 * all documents, i.e. every command is global.
245 *
246 * \param cmd command to register
247 * \return \e true on success, otherwise \e false
248 * \see unregisterCommand()
249 */
250 virtual bool registerCommand (Command *cmd) = 0;
251
252 /**
253 * Unregister the command \p cmd. The command will be unregistered for
254 * all documents.
255 *
256 * \param cmd command to unregister
257 * \return \e true on success, otherwise \e false
258 * \see registerCommand()
259 */
260 virtual bool unregisterCommand (Command *cmd) = 0;
261
262 /**
263 * Query for the command \p cmd.
264 * If the command \p cmd does not exist the return value is NULL.
265 *
266 * \param cmd name of command to query for
267 * \return the found command or NULL if no such command exists
268 */
269 virtual Command *queryCommand (const QString &cmd) const = 0;
270
271 /**
272 * Get a list of all registered commands.
273 * \return list of all commands
274 * \see queryCommand(), commandList()
275 */
276 virtual QList<Command*> commands() const = 0;
277
278 /**
279 * Get a list of available command line strings.
280 * \return command line strings
281 * \see commands()
282 */
283 virtual QStringList commandList() const = 0;
284};
285
286/**
287 * \brief Extension interface for a Command making the exec method take a line
288 * range
289 *
290 * \ingroup kte_group_command_extensions
291 *
292 * \section cmdext_intro Introduction
293 *
294 * The RangeCommand extension extends the Command interface by making it
295 * possible to send a range to a command indicating that it should only do its
296 * work on those lines.
297 *
298 * The method supportsRange() takes a QString reference and should return true
299 * if the given command name supports a range and false if not.
300 *
301 * \see KTextEditor::CommandInterface, KTextEditor::Command, KTextEditor::Range
302 * \author Erlend Hamberg \<ehamberg@gmail.com\>
303 * \since 4.2
304 * \note KDE5: merge with KTextEditor::Command?
305 */
306class KTEXTEDITOR_EXPORT RangeCommand
307{
308 public:
309 /**
310 * Virtual destructor.
311 */
312 virtual ~RangeCommand() {}
313
314 /**
315 * Execute the command for the given \p range on the given \p view and \p
316 * cmd string. Return the success value and a \p msg for status.
317 *
318 * \return \e true on success, otherwise \e false
319 */
320 virtual bool exec (KTextEditor::View *view, const QString &cmd, QString &msg,
321 const KTextEditor::Range &range) = 0;
322
323 /**
324 * Find out if a given command can act on a range. This is used for checking
325 * if a command should be called when the user also gave a range or if an
326 * error should be raised.
327 *
328 * \return \e true if command supports acting on a range of lines, false if
329 * not
330 */
331 virtual bool supportsRange (const QString &cmd) = 0;
332};
333
334}
335
336Q_DECLARE_INTERFACE(KTextEditor::CommandInterface, "org.kde.KTextEditor.CommandInterface")
337
338#endif
339
340// kate: space-indent on; indent-width 2; replace-tabs on;
341