← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-updates

« back to all changes in this revision

Viewing changes to ktexteditor/commandinterface.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2014-12-04 16:49:41 UTC
  • mfrom: (1.6.6)
  • Revision ID: package-import@ubuntu.com-20141204164941-l3qbvsly83hhlw2v
Tags: 4:14.11.97-0ubuntu1
* New upstream release
* Update build-deps and use pkg-kde v3 for Qt 5 build
* kate-data now kate5-data for co-installability

Show diffs side-by-side

added added

removed removed

Lines of Context:
ktexteditor/commandinterface.h
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
 
 
29
 
class QStringList;
30
 
class KCompletion;
31
 
 
32
 
namespace KTextEditor
33
 
{
34
 
 
35
 
class Editor;
36
 
class 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
 
 */
76
 
class 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
 
 */
138
 
class 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
 
 */
233
 
class 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
 
 */
306
 
class 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
 
 
336
 
Q_DECLARE_INTERFACE(KTextEditor::CommandInterface, "org.kde.KTextEditor.CommandInterface")
337
 
 
338
 
#endif
339
 
 
340
 
// kate: space-indent on; indent-width 2; replace-tabs on;