Scripting the editor component with Javascript
Prev
Next

Scripting the editor component with Javascript

Introduction

Starting with version 2.5, the Kate editor component supports scripting with ECMA script, also known as JavaScript.

Scripts can be used through the built in command line only. The requirements is that the script is placed in a folder where Kate can find it, along with an optional .desktop file that defines the related properties. The valid folder are named katepart/scripts in the KDE data folders. You can find the data folders by running the command kde-config --path data You will usually have at least a system and a personal data folder. Of course scripts in the system data folder are available to all users on the system, while those in the personal folder are available for you only.

Note

This feature is experimental and will most likely change during future development.

We know that many of you will be disappointed because you can't add your scripts to the menu or assign shortcuts to them. Sorry, sometime in the future that will likely be possible.

It is also not possible to pass any arguments to your scripts yet. Be patient, and that may be added in the bright future ;)

The Kate JavaScript API

Here is listed the complete set of functions and properties available in the document and view objects. In addition you can of course use all the standard objects such as Math, String Regex and so forth.

When a script is run, the document object is the current document, and the view object is the current view.

Note

The types of arguments are of course not used in JavaScript at this time, they are there solely to indicate what sort of value the funcitons expect.

Global Functions

debug( string) [function]

parameters

  • string the string to output

Outputs the string to STDERR using kdDebug(). A dedicated output area is used for the output, which will be prefixed Kate (KJS Scripts):

The document API

document.attribute( line , column ); [function]

Parameters

  • uint line The line of the position for which to find the attribute.

  • uint column The column of the position for which to find the attribute.

Returns the numeric ID of the attribute for the document position [line,column]. The attribute represents the visual appearance or style of the text, and is also used to calculate the syntax highlight for a specific part of the text in mixed formats like HTML or PHP.

document.canBreakAt( Char c, uint attribute ); [function]

Parameters

  • c The character to test

  • attribute The attribute at the position of c.

Returns whether it is allowed to break the line at a character c with attribute attribute. The result is decided by querying the highlight owning attribute for which characters allow breaking the line.

document.canComment( uint start_attribute, uint end_attribute ); [function]

Parameters

  • start_attribute The attribute at the start of the range to turn into a comment.

  • end_attribute The attribute at end of the range to turn into a comment.

Returns whether start_attribute and end_attribute belongs to the same syntax highlight system. If they do, it is sane.

Example 6.5. using canComment

if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
    // 1,0 and 5,0 belongs to the same syntax highlighting system
}
document.clear(); [function]

Clears the document.

document.commentStart( uint attribute ); [function]

Parameters

  • attribute The attribute of the text for which to get the commentStart string.

Returns the string required to start a multiline comment for a text with attribute, or an empty string if multiline comments are not supported for that text.

document.commentMarker( uint attribute ); [function]

Parameters

  • attribute The attribute of the text for which to get the commentMarker string

Returns the string used to mark the rest of the line as a comment for a text with attribute or an empty string if single line comments are not supported for that text.

document.commentEnd( uint attribute ); [function]

Parameters

  • attribute The attribute of the text for which to get the commentEnd string

Returns the string required to end a multiline comment for a text with attribute, or an empty string if multiline comments are not supported for that text.

document.editBegin(); [function]

Start an editing group. All actions done until the call of editEnd() will be grouped as one undo-action.

document.editEnd(); [function]

Finish an editing group.

document.highlightMode; [property:read only]

The name of the document's highlight mode, such as JavaScript or C++. If no syntax highlight mode is set for the document, the value is None. Notice that you need to use the English name in cases where it differs from the translated one.

document.indentMode; [property:read only]

The name of the document indent mode, such as normal or cstyle. Remember that if no indent mode is set, the value is none.

document.indentWidth; [property:read only]

The indentation width set for the document. This is used if space indenting is enabled.

document.insertLine( uint line, string text ); [function]

Parameters

  • line document line number

  • text text to insert

Inserts a new line with the text text at the line line.

document.insertText( uint line, uint column, string text ); [function]

Parameters

  • line the line number

  • column the column

  • text the text which is to be inserted

Inserts the text text in line line and column column.

document.length(); [function]

Returns the document's size in bytes.

document.lines(); [function]

Returns the number of lines in the document.

document.mixedIndent; [property:read only]

A boolean telling whether the mixed-indent setting is enabled for the document. If so, indentation is optimized to contain a mix of tab characters and spaces like used by the Emacs editor.

document.removeLine( uint line ); [function]

Parameters

  • line line number

Removes the document line line.

document.removeText( uint startLine, uint startColumn, uint endLine, uint endColumn ); [function]

Parameters

  • startLine specifies the beginning line

  • startColumn specifies the beginning column

  • endLine specifies the ending line

  • endColumn specifies the ending column

Removes the text range from line startLine and column startColumn up to line endLine and column endColumn.

document.setText( string text ); [function]

Parameters

  • text document text

Sets the entire document content to text.

document.spaceIndent; [property:read only]

A boolean telling whether space-indent is enabled for the document. If so, the document is indented with indentWidth spaces pr level, otherwise indentation is one tab character pr. level.

document.textFull(); [function]

Returns the full document text. If the text spans over multiple lines the linefeed character is \n.

document.textLine( uint line ); [function]

Parameters

  • line the line

Returns the text of line line.

document.textRange( uint startLine, uint startColumn, uint endLine, uint endColumn ); [function]

Parameters

  • startLine specifies the beginning line

  • startColumn specifies the beginning column

  • endLine specifies the ending line

  • endColumn specifies the ending column

Returns the specified text range. If the range spans over multiple lines the linefeed character is \n.

The view API

view.clearSelection(); [function]

Deselects all text.

view.cursorColumn(); [function]

Returns the current cursor column (TAB characters are expanded).

view.cursorColumnReal(); [function]

Returns the current real cursor column (TAB characters counts one).

view.cursorLine(); [function]

Returns the current cursor line.

view.hasSelection(); [function]

Returns true if the view contains selected text, otherwise false.

view.removeSelectedText(); [function]

Removes the selected text, if the view has a selection.

view.selectAll(); [function]

Selects all text.

view.selection(); [function]

Returns the selected text. If the selection spans over multiple lines the linefeed character is \n.

view.selectionEndColumn; [property:read only]

Returns the ending column of the selection.

view.selectionEndLine; [property:read only]

Returns the ending line of the selection.

view.selectionStartColumn; [property:read only]

Returns the starting column of the selection.

view.selectionStartLine; [property:read only]

Returns the starting line of the selection.

view.setCursorPosition( uint line, uint column ); [function]

Parameters

  • line Specifies the line for the cursor.

  • column Specifies the column for the cursor.

Sets the input cursor position in the view to [line, col]. This sets the cursor position by visual means, that is the a TAB character counts up to tabwidth depending on the position inside the line. The cursor position is made visible. Both line and column are zero-based.

view.setCursorPositionReal( uint line, uint column ); [function]

Parameters

  • line Specifies the line for the cursor.

  • column Specifies the column for the cursor.

Sets the input cursor position to [line, col]. This sets the string position, that is a TAB character counts for 1. The cursor position is made visible. Both line and column are zero-based.

view.setSelection( uint startLine, uint startColumn, uint endLine, uint endColumn ); [function]

Parameters

  • startLine specifies the beginning line

  • startColumn specifies the beginning column

  • endLine specifies the ending line

  • endColumn specifies the ending column

Sets a selection from line startLine and column startColumn up to line endLine and column endColumn.

Example 6.6. A sample script

As an example we will create a small script that uppercases the selection. It is obvious that we first need to check whether a selection exists, if so we get the text, change the case and then replace it with the new one. An implementation could look like this:

if ( view.hasSelection() )
{
  // uppercase selection
  column = view.selectionStartColumn;
  line = view.selectionStartLine;

  selection = view.selection().toUpperCase();

  document.editBegin();
  view.removeSelectedText();
  document.insertText( line, column, selection );
  document.editEnd();
}

To group this action together so that they will be reverted by a single activation of Undo we encapsulate the lines

view.removeSelectedText()
and
document.insertText()
with a
document.editBegin()
and
document.editEnd()
.

Example 6.7. A sample .desktop file

Here is a sample .desktop file that accompanies the above script.

# Example of a .desktop file
[Desktop Entry]
Encoding=UTF-8
Name=Kate Part JavaScript Uppercase
Comment=Script to uppercase the selection
X-Kate-Command=uppercase-selection
X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

As you can see you can define the Encoding, set a Name, a Comment, a help text using X-Kate-Help and the command line name via X-Kate-Command. The entries Name, Comment and X-Kate-Help are automatically translated into other languages by the KDE translation teams, if the files are in KDE's SVN repository.

Putting it togeather

Kate will search the script folders (see above) for *.js files. For every file it checks whether there is a corresponding .desktop file, like for uppercase.js it would look for uppercase.desktop.

If a .desktop file can not be found the script will be registered in katepart's command line with the filename without the ending .js, so in our example this would be uppercase. If the command-name is fine and you don't need the extra features a .desktop file provides you do not need a .desktop file at all.

If a .desktop file exists katepart will read the name under which the script will be registered from the .desktop-entry X-Kate-Command, for example X-Kate-Command=uppercase-selection.

Prev
Next
Home


Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team