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.
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 ;)
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.
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.
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
.
Returns the document's size in bytes.
document.lines(); [function]
Returns the number of lines in the document.
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.
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 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.
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.
Would you like to make a comment or contribute an update to this page?
Send feedback to the KDE Docs Team