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; |
341 | |