KTextEditor.Command

KDE 4.9 PyKDE API Reference

- KDE's Python API

# Command Class Reference

`from PyKDE4.ktexteditor import *`

Namespace: KTextEditor

## Detailed Description

An Editor command line command.

Introduction

The Command class represents a command for the editor command line. A command simply consists of a string, for example find. To register a command use CommandInterface.registerCommand(). The Editor itself queries the command for a list of accepted strings/commands by calling cmds(). If the command gets invoked the function exec() is called, i.e. you have to implement the reaction in exec(). Whenever the user needs help for a command help() is called.

Command Information To provide reasonable information about a specific command there are the following accessor functions for a given command string: - name() returns a label - description() returns a descriptive text - category() returns a category into which the command fits.

These getters allow KTextEditor implementations to plug commands into menus and toolbars, so that a user can assign shortcuts.

Command Extensions

If your command needs to interactively react on changes while the user is typing text - look at the ifind command in Kate for example - you have to additionally derive your command from the class CommandExtension. The command extension provides methods to give help on flags or add a KCompletion object and process the typed text interactively. Besides that the class RangeCommand enables you to support ranges so that you can apply commands on regions of text.

See also:
  KTextEditor.CommandInterface, KTextEditor.CommandExtension, KTextEditor.RangeCommand

Author:
  Christoph Cullmann <cullmann@kde.org>

Note:
  KDE5: derive from QObject, so qobject_cast works for extension interfaces.

## Methods
QStringList | cmds (self)
bool | exec_ (self, KTextEditor.View view, QString cmd, QString msg)
bool | help (self, KTextEditor.View view, QString cmd, QString msg)

## Method Documentation

QStringList cmds | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Return a list of strings a command may begin with. A string is the start part of a pure text which can be handled by this command, i.e. for the command s/sdl/sdf/g the corresponding string is simply s, and for char:1212 simply char.

Returns:
  list of supported commands

bool exec_ | ( | self, |
|  | KTextEditor.View | view,
|  | QString | cmd,
|  | QString | msg
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Execute the command for the given view and cmd string. Return the success value and a msg for status. As example we consider a replace command. The replace command would return the number of replaced strings as msg, like "16 replacements made." If an error occurred in the usage it would return false and set the msg to something like "missing argument." or such.

Returns:
  true on success, otherwise false

bool help | ( | self, |
|  | KTextEditor.View | view,
|  | QString | cmd,
|  | QString | msg
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Shows help for the given view and cmd string. If your command has a help text for cmd you have to return true and set the msg to a meaningful text. The help text is embedded by the Editor in a Qt.RichText enabled widget, e.g. a QToolTip.

Returns:
  true if your command has a help text, otherwise false