Git commit ef6d65286d40906938b904b2a30a9cf402e0ec7a by T.C. Hollingsworth. Committed on 19/05/2013 at 23:15. Pushed by hollingsworth into branch 'master'.
move scripting docs from advanced.docbook to development.docbook M +1 -1710 doc/kate/advanced.docbook M +1706 -0 doc/kate/development.docbook M +3 -3 doc/kate/menus.docbook M +1 -1 doc/kwrite/menus.docbook M +1 -1 part/snippet/editsnippet.cpp http://commits.kde.org/kate/ef6d65286d40906938b904b2a30a9cf402e0ec7a diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook index 045b16b..edc333d 100644 --- a/doc/kate/advanced.docbook +++ b/doc/kate/advanced.docbook @@ -237,7 +237,7 @@ argument.</para></listitem> <varlistentry> <term><cmdsynopsis><command>reload-scripts</command></cmdsynopsis></term> -<listitem><para>Reload all <link linkend="advanced-editing-tools-scripting">JavaScript +<listitem><para>Reload all <link linkend="dev-scripting">JavaScript scripts</link> used by Kate, including indenters and command line scripts.</para></listitem> </varlistentry> @@ -905,1713 +905,4 @@ configuration.</para> </sect1> -<sect1 id="advanced-editing-tools-scripting"> -<title>Extending &kappname; with Scripts</title> - -<para> -Since &kappname; 3.4 in KDE 4.4 the &kappname; editor component is easily extensible by -writing scripts. The scripting language is ECMAScript (widely known as JavaScript). -&kappname; supports two kinds of scripts: indentation and command line scripts. -</para> - -<sect2 id="advanced-editing-tools-scripting-indentation"> -<title>Indentation Scripts</title> - -<para> -Indentation scripts - also referred as indenters - automatically indent the -source code while typing text. As example, after hitting the return-key code -the indentation level often increases. -</para> - -<para> -The following sections describe step by step how to create the skeleton for a -simple indenter. As first step, create a new <filename>*.js</filename> file -called e.g. <filename>javascript.js</filename> in the local home folder -<filename>$KDEHOME/share/apps/katepart/script/indentation</filename>. -</para> - -<sect3 id="advanced-editing-tools-scripting-indentation-header"> -<title>The Indentation Script Header</title> -<para> -The header of the file <filename>javascript.js</filename> is embedded in a -comment and is of the following form - -<programlisting> -/* kate-script - * name: JavaScript - * author: Example Name <example.name at some.address.org> - * license: BSD - * revision: 1 - * kate-version: 3.4 - * required-syntax-style: javascript - * indent-languages: javascript - * priority: 0 - * i18n-catalog: mycatalog - * - * A line without colon ':' stops header parsing. That is, you can add optional - * text here such as a detailed license. - */ -</programlisting> - -Each entry is explained in detail now: -<itemizedlist> -<listitem><para> -<literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script. -</para></listitem> -<listitem><para> -<literal>name</literal> [required]: This is the indenter name that appears in the menu -<menuchoice><guimenu>Tools</guimenu><guimenuitem>Indentation</guimenuitem></menuchoice> -and in the configuration dialog. -</para></listitem> -<listitem><para> -<literal>author</literal> [optional]: The author's name and contact information. -</para></listitem> -<listitem><para> -<literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3. -</para></listitem> -<listitem><para> -<literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified. -</para></listitem> -<listitem><para> -<literal>kate-version</literal> [required]: Minimal required &kappname; version. -</para></listitem> -<listitem><para> -<literal>required-syntax-style</literal> [optional]: Comma separated list of required syntax highlighting styles. This is important for indenters that rely on specific highlight information in the document. If a required syntax style is specified, the indenter is available only when the appropriate highlighter is active. This prevents <quote>undefined behavior</quote> caused by using the indenter without the expected highlighting schema. For instance, the Ruby indenter makes use of this in the files <filename>ruby.js</filename> and <filename>ruby.xml</filename>. -</para></listitem> -<listitem><para> -<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, e.g.: c++, java. -</para></listitem> -<listitem><para> -<literal>priority</literal> [optional]: If several indenters are suited for a certain highlighted file, the priority decides which indenter is chosen as default indenter. -</para></listitem> -<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party indenters.</para></listitem> -</itemizedlist> -</para> - -<para> -&kappname; reads all pairs of the form -<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> -until it cannot find a colon anymore. This implies that the header can contain -arbitrary text such as a license as shown in the example. -</para> - -</sect3> - -<sect3 id="advanced-editing-tools-scripting-indentation-body"> -<title>The Indenter Source Code</title> -<para> -Having specified the header this section explains how the indentation scripting -itself works. The basic skeleton of the body looks like this: - -<programlisting> -// required katepart js libraries, e.g. range.js if you use Range -require ("range.js"); - -triggerCharacters = "{}/:;"; -function indent(line, indentWidth, ch) -{ - // called for each newline (ch == '\n') and all characters specified in - // the global variable triggerCharacters. When calling <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice> - // the variable ch is empty, i.e. ch == ''. - // - // see also: Scripting API - return -2; -} -</programlisting> - -The function <function>indent()</function> has three parameters: -<itemizedlist> -<listitem><para><literal>line</literal>: the line that has to be indented</para></listitem> -<listitem><para><literal>indentWidth</literal>: the indentation width in amount of spaces</para></listitem> -<listitem><para><literal>ch</literal>: either a newline character (<literal>ch == '\n'</literal>), the trigger character specified in <literal>triggerCharacters</literal> or empty if the user invoked the action <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>.</para></listitem> -</itemizedlist> -The return value of the <function>indent()</function> function specifies how -the line will be indented. If the return value is a simple integer number, it -is interpreted as follows: -<itemizedlist> -<listitem><para>return value <literal>-2</literal>: do nothing</para></listitem> -<listitem><para>return value <literal>-1</literal>: keep indentation (searches for previous non-blank line)</para></listitem> -<listitem><para>return value <literal> 0</literal>: numbers >= 0 specify the indentation depth in spaces</para></listitem> -</itemizedlist> -Alternatively, an array of two elements can be returned: -<itemizedlist> -<listitem><para><literal>return [ indent, align ];</literal></para></listitem> -</itemizedlist> -In this case, the first element is the indentation depth like above with the -same meaning of the special values. However, the second element is an absolute -value representing a column for <quote>alignment</quote>. If this value is higher than the -indent value, the difference represents a number of spaces to be added after -the indentation of the first parameter. Otherwise, the second number is ignored. -Using tabs and spaces for indentation is often referred to as <quote>mixed mode</quote>. -</para> - -<para> -Consider the following example: Assume using tabs to indent, and tab width is set -to 4. Here, <tab> represents a tab and '.' a space: -<programlisting> -1: <tab><tab>foobar("hello", -2: <tab><tab>......."world"); -</programlisting> -When indenting line 2, the <function>indent()</function> function returns [8, 15]. As result, two -tabs are inserted to indent to column 8, and 7 spaces are added to align the -second parameter under the first, so that it stays aligned if the file is viewed -with a different tab width. -</para> - -<para> -A default KDE installation ships &kappname; with several indenters. The -corresponding JavaScript source code can be found in <filename>$KDEDIR/share/apps/katepart/script/indentation</filename>. -</para> - -<para> -Developing an indenter requires to reload the scripts to see whether the changes -behave appropriately. Instead of restarting the application, simply switch to -the command line and invoke the command <command>reload-scripts</command>. -</para> - -<para> -If you develop useful scripts please consider contributing to the &kappname; Project -by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. -</para> - -</sect3> -</sect2> - -<sect2 id="advanced-editing-tools-scripting-command-line"> -<title>Command Line Scripts</title> - -<para> -As it is hard to satisfy everyone's needs, &kappname; supports little helper tools -for quick text manipulation through the -<link linkend="advanced-editing-tools-commandline">built-in command line</link>. -For instance, the command -<command>sort</command> is implemented as script. This section explains how to create -<filename>*.js</filename> files to extend &kappname; with arbitrary helper scripts. -</para> - -<para> -Command line scripts are located in the same folder as indentation scripts. -So as first step, create a new <filename>*.js</filename> file called -<filename>myutils.js</filename> in the local home folder -<filename>$KDEHOME/share/apps/katepart/script/commands</filename>. -</para> - -<sect3 id="advanced-editing-tools-scripting-command-line-header"> -<title>The Command Line Script Header</title> -<para> -The header of each command line script is embedded in a comment and is of the -following form - -<programlisting> -/* kate-script - * author: Example Name <example.name at some.address.org> - * license: BSD - * revision: 1 - * kate-version: 3.4 - * functions: sort, format-paragraph - * i18n-catalog: mycatalog - * - * A line without colon ':' stops header parsing. That is, you can add optional - * text here such as a detailed license. - */ -</programlisting> - -Each entry is explained in detail now: -<itemizedlist> -<listitem><para><literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.</para></listitem> -<listitem><para><literal>author</literal> [optional]: The author's name and contact information.</para></listitem> -<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.</para></listitem> -<listitem><para><literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.</para></listitem> -<listitem><para><literal>kate-version</literal> [required]: Minimal required &kappname; version.</para></listitem> -<listitem><para><literal>functions</literal> [required]: Comma separated list of commands in the script.</para></listitem> -<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem> -</itemizedlist> -</para> - -<para> -&kappname; reads all pairs of the form -<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> -until it cannot find a colon -anymore. This implies that the header can contain arbitrary text such as a license -as shown in the example. The value of the key functions is a comma separated list -of command line commands. This means a single script contains an arbitrary amount -of command line commands. Each function is available through &kappname;'s -<link linkend="advanced-editing-tools-commandline">built-in command line</link>. -</para> -</sect3> - -<sect3 id="advanced-editing-tools-scripting-command-line-body"> -<title>The Script Source Code</title> - -<para> -All functions specified in the header have to be implemented in the script. -For instance, the script file from the example above needs to implement the two -functions <command>sort</command> and <command>format-paragraph</command>. -All functions have the following syntax: - -<programlisting> -// required katepart js libraries, e.g. range.js if you use Range -require ("range.js"); - -function <name>(arg1, arg2, ...) -{ - // ... implementation, see also: Scripting API -} -</programlisting> -</para> - -<para> -Arguments in the command line are passed to the function as -<parameter>arg1</parameter>, <parameter>arg2</parameter>, etc. -In order to provide documentation for each command, simply implement the -'<function>help</function>' function as follows: - -<programlisting> -function help(cmd) -{ - if (cmd == "sort") { - return i18n("Sort the selected text."); - } else if (cmd == "...") { - // ... - } -} -</programlisting> - -Executing <command>help sort</command> in the command line then calls this help function with -the argument <parameter>cmd</parameter> set to the given command, i.e. -<parameter>cmd == "sort"</parameter>. &kappname; then presents the returned text as -documentation to the user. Make sure to -<link linkend="advanced-editing-tools-scripting-api-i18n">translate the strings</link>. -</para> - -<sect4 id="advanced-editing-tools-scripting-command-line-shortcuts"> -<title>Binding Shortcuts</title> -<para>In order to be able to assign shortcuts, the script needs to provide a -function called <literal>action</literal> as follows: -<programlisting> -function action(cmd) -{ - var a = new Object(); - if (cmd == "sort") { - a.text = i18n("Sort Selected Text"); - a.icon = ""; - a.category = ""; - a.interactive = false; - a.shortcut = ""; - } else if (cmd == "moveLinesDown") { - // same for next action - } - return a; -} -</programlisting> -The parameter <literal>cmd</literal> of the function specifies the command for -which a shortcut is requested. There are several fields you have to specify in -the returned javascript object: -<itemizedlist> -<listitem><para><literal>a.text</literal> [required]: The text appears in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>. Make sure to use <literal>i18n</literal> for translation.</para></listitem> -<listitem><para><literal>a.icon</literal> [optional]: The icon appears next to the text in the menu. All KDE icon names can be used here.</para></listitem> -<listitem><para><literal>a.category</literal> [optional]: If a category is specified, the script appears in a submenu. Make sure to use <literal>i18n</literal> for translation.</para></listitem> -<listitem><para><literal>a.interactive</literal> [optional]: If the script needs user input, set this to <literal>true</literal>.</para></listitem> -<listitem><para><literal>a.shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: Ctrl+Alt+t. See the <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum";>Qt documentation</ulink> for further details.</para></listitem> -</itemizedlist> -</para> - - -<para> -Developing a command line script requires to reload the scripts to see whether -the changes behave appropriately. Instead of restarting the application, simply -switch to the command line and invoke the command <command>reload-scripts</command>. -</para> - -<para> -If you develop useful scripts please consider contributing to the &kappname; Project -by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. -</para> - -</sect4> -</sect3> -</sect2> - -<sect2 id="advanced-editing-tools-scripting-api"> -<title>Scripting API</title> - -<para> -The scripting API presented here is available in all scripts, i.e. indentation -scripts and command line commands. -The <classname>Cursor</classname> and <classname>Range</classname> are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>. -If you want to use them in your script, which is required to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the needed library by using: - -<programlisting> -// required katepart js libraries, e.g. range.js if you use Range -require ("range.js"); -</programlisting> -</para> - -<para> -To extend the standard scripting API with own functions and prototypes simply -create a new file in the KDE's local configuration folder -<filename>$KDEHOME/share/apps/katepart/libraries</filename> and include it into your script using: - -<programlisting> -require ("myscriptnamehere.js"); -</programlisting> - -</para> - -<para> -To extend existing prototypes like <classname>Cursor</classname> or -<classname>Range</classname>, the recommended way is to -<emphasis>not</emphasis> modify the global <filename>*.js</filename> files. -Instead, change the <classname>Cursor</classname> prototype in JavaScript after the <filename>cursor.js</filename> is included into your -script via <literal>require</literal>. -</para> - -<sect3 id="advanced-editing-tools-scripting-api-prototypes"> -<title>Cursors and Ranges</title> - -<para> -As &kappname; is a text editor, all the scripting API is based on cursors and -ranges whenever possible. A Cursor is a simple <literal>(line, column)</literal> -tuple representing a text position in the document. A Range spans text from a -starting cursor position to an ending cursor position. The API is explained in -detail in the next sections. -</para> - -<sect4 id="advanced-editing-tools-scripting-api-cursors"> -<title>The Cursor Prototype</title> - -<variablelist><varlistentry> -<term><synopsis> -Cursor(); -</synopsis></term> -<listitem><para> -Constructor. Returns a Cursor at position <literal>(0, 0)</literal>.</para> -<para>Example: <function>var cursor = new Cursor();</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Constructor. Returns a Cursor at position (line, column). -</para> -<para>Example: <function>var cursor = new Cursor(3, 42);</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor(<parameter>Cursor <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Copy constructor. Returns a copy of the cursor <replaceable>other</replaceable>. -</para> -<para>Example: <function>var copy = new Cursor(other);</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor Cursor.clone(); -</synopsis></term> -<listitem><para> -Returns a clone of the cursor.</para> -<para>Example: <function>var clone = cursor.clone();</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor.setPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Sets the cursor position to <replaceable>line</replaceable> and <replaceable>column</replaceable>.</para> -<para> -Since: KDE 4.11 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Cursor.isValid(); -</synopsis></term> -<listitem><para> -Check whether the cursor is valid. The cursor is invalid, if line and/or -column are set to <literal>-1</literal>. -</para> -<para> -Example: <function>var valid = cursor.isValid();</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor Cursor.invalid(); -</synopsis></term> -<listitem><para> -Returns an new invalid cursor located at <literal>(-1, -1)</literal>. -</para> -<para>Example: <function>var invalidCursor = cursor.invalid();</function> -</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -int Cursor.compareTo(<parameter>Cursor <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Compares this cursor to the cursor <replaceable>other</replaceable>. Returns -<itemizedlist> -<listitem><para><literal>-1</literal>, if this cursor is located before the cursor <replaceable>other</replaceable>,</para></listitem> -<listitem><para><literal>0</literal>, if both cursors equal and</para></listitem> -<listitem><para><literal>+1</literal>, if this cursor is located after the cursor <replaceable>other</replaceable>.</para></listitem> -</itemizedlist> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Cursor.equals(<parameter>Cursor <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if this cursor and the cursor <replaceable>other</replaceable> are -equal, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String Cursor.toString(); -</synopsis></term> -<listitem><para> -Returns the cursor as a string of the form <quote><literal>Cursor(line, column)</literal></quote>. -</para></listitem> -</varlistentry></variablelist> - -</sect4> - - -<sect4 id="advanced-editing-tools-scripting-api-ranges"> -<title>The Range Prototype</title> - -<variablelist><varlistentry> -<term><synopsis> -Range(); -</synopsis></term> -<listitem><para> -Constructor. Calling <literal>new Range()</literal> returns a Range at (0, 0) - (0, 0). -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range(<parameter>Cursor <replaceable>start</replaceable></parameter>, <parameter>Cursor <replaceable>end</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Constructor. Calling <literal>new Range(<replaceable>start</replaceable>, <replaceable>end</replaceable>)</literal> returns the Range (<replaceable>start</replaceable>, <replaceable>end</replaceable>). -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>startColumn</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>, <parameter>int <replaceable>endColumn</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Constructor. Calling <literal>new Range(<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>, <replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>)</literal> -returns the Range from (<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>) to (<replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>). -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range(<parameter>Range <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Copy constructor. Returns a copy of Range <replaceable>other</replaceable>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range Range.clone(); -</synopsis></term> -<listitem><para> -Returns a clone of the range. -</para> -<para>Example: <function>var clone = range.clone();</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.isEmpty(); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if the start and end cursors are equal. -</para> -<para>Example: <function>var empty = range.isEmpty();</function> -</para> -<para> -Since: KDE 4.11 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.isValid(); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if both start and end cursor are valid, otherwise <literal>false</literal>. -</para> -<para>Example: <function>var valid = range.isValid();</function> -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range Range.invalid(); -</synopsis></term> -<listitem><para> -Returns the Range from (-1, -1) to (-1, -1). -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.contains(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if this range contains the cursor position, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.contains(<parameter>Range <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if this range contains the Range <replaceable>other</replaceable>, -otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.containsColumn(<parameter>int <replaceable>column</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the half open interval -<literal>[start.column, end.column)</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.containsLine(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the half open interval -<literal>[start.line, end.line)</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.overlaps(<parameter>Range <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if this range and the range <replaceable>other</replaceable> share -a common region, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.overlapsLine(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the interval -<literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.overlapsColumn(<parameter>int <replaceable>column</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the interval -<literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.onSingleLine(); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if the range starts and ends at the same line, -i.e. if <replaceable>Range.start.line == Range.end.line</replaceable>. -</para> -<para> -Since: KDE 4.9 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool Range.equals(<parameter>Range <replaceable>other</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if this range and the Range <replaceable>other</replaceable> are -equal, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String Range.toString(); -</synopsis></term> -<listitem><para> -Returns the range as a string of the form <quote><literal>Range(Cursor(line, column), Cursor(line, column))</literal></quote>. -</para></listitem> -</varlistentry></variablelist> - -</sect4> -</sect3> - -<sect3 id="advanced-editing-tools-scripting-api-global"> -<title>Global Functions</title> -<para>This section lists all global functions.</para> - - -<sect4 id="advanced-editing-tools-scripting-api-includes"> -<title>Reading & Including Files</title> - -<variablelist><varlistentry> -<term><synopsis> -String read(<parameter>String <replaceable>file</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/files</literal> directory and return its content as a string. -</para></listitem> -</varlistentry></variablelist> - -<variablelist><varlistentry> -<term><synopsis> -void require(<parameter>String <replaceable>file</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/libraries</literal> directory and evaluate it. -<literal>require</literal> is internally guarded against multiple inclusions of the same <replaceable>file</replaceable>. -</para> -<para> - Since: KDE 4.10 -</para> -</listitem> -</varlistentry></variablelist> - -</sect4> - -<sect4 id="advanced-editing-tools-scripting-api-debug"> -<title>Debugging</title> - -<variablelist><varlistentry> -<term><synopsis> -void debug(<parameter>String <replaceable>text</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Prints <replaceable>text</replaceable> to <literal>stdout</literal> in the -console launching the application. -</para></listitem> -</varlistentry></variablelist> - -</sect4> - -<sect4 id="advanced-editing-tools-scripting-api-i18n"> -<title>Translation</title> - -<para>In order to support full localization, there are several functions to translate -strings in scripts, namely <literal>i18n</literal>, <literal>i18nc</literal>, -<literal>i18np</literal> and <literal>i18ncp</literal>. These functions behave -exactly like <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n";> -KDE's translation functions</ulink>. -</para> - -<para>The translation functions translate the wrapped strings through KDE's -translation system to the language used in the application. Strings in scripts -being developed in the official &kappname; sources are automatically extracted and -translatable. In other words, as a &kappname; developer you do not have to bother with -message extraction and translation. However, for 3rd-party scripts developed -outside of KDE, you have to extract and translate the messages yourself. Along -with your scripts you have to also distribute a translation catalog, that -includes all translated strings. Further, your script header then must -explicitly state the catalog to load by specifying -<literal>i18n-catalog</literal>. -</para> - -<variablelist><varlistentry> -<term><synopsis> -void i18n(<parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); -</synopsis></term> -<listitem><para> -Translates <replaceable>text</replaceable> into the language used by the application. -The arguments <replaceable>arg1</replaceable>, ..., are optional and used to -replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -void i18nc(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); -</synopsis></term> -<listitem><para> -Translates <replaceable>text</replaceable> into the language used by the -application. Additionally, the string <replaceable>context</replaceable> is -visible to translators so they can provide a better translation. -The arguments <replaceable>arg1</replaceable>, ..., are optional and used to -replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -void i18np(<parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); -</synopsis></term> -<listitem><para> -Translates either <replaceable>singular</replaceable> or -<replaceable>plural</replaceable> into the language used by the application, -depending on the given <replaceable>number</replaceable>. -The arguments <replaceable>arg1</replaceable>, ..., are optional and used to -replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -void i18ncp(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); -</synopsis></term> -<listitem><para> -Translates either <replaceable>singular</replaceable> or -<replaceable>plural</replaceable> into the language used by the application, -depending on the given <replaceable>number</replaceable>. Additionally, the -string <replaceable>context</replaceable> is visible to translators so they -can provide a better translation. The arguments <replaceable>arg1</replaceable>, -..., are optional and used to replace the placeholders <literal>%1</literal>, -<literal>%2</literal>, etc.</para></listitem> -</varlistentry></variablelist> - -</sect4> -</sect3> - -<sect3 id="advanced-editing-tools-scripting-api-view"> -<title>The View API</title> -<para>Whenever a script is being executed, there is a global variable -<quote><literal>view</literal></quote> representing the current active editor -view. The following is a list of all available View functions. - -<variablelist><varlistentry> -<term><synopsis> -<function>Cursor view.cursorPosition()</function> -</synopsis></term> -<listitem><para>Returns the current cursor position in the view.</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.setCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -void view.setCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Set the current cursor position to either (line, column) or to the given cursor. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor view.virtualCursorPosition(); -</synopsis></term> -<listitem><para> -Returns the virtual cursor position with each tab counting the corresponding amount of spaces depending on the current tab width. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.setVirtualCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -void view.setVirtualCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Set the current virtual cursor position to (line, column) or to the given cursor. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String view.selectedText(); -</synopsis></term> -<listitem><para> -Returns the selected text. If no text is selected, the returned string is empty. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool view.hasSelection(); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if the view has selected text, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Range view.selection(); -</synopsis></term> -<listitem><para> -Returns the selected text range. The returned range is invalid if there is no -selected text. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.setSelection(<parameter>Range <replaceable>range</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Set the selected text to the given range. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.removeSelectedText(); -</synopsis></term> -<listitem><para> -Remove the selected text. If the view does not have any selected text, this -does nothing. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.selectAll(); -</synopsis></term> -<listitem><para> -Selects the entire text in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void view.clearSelection(); -</synopsis></term> -<listitem><para> -Clears the text selection without removing the text. -</para></listitem> -</varlistentry></variablelist> -</para> -</sect3> - -<sect3 id="advanced-editing-tools-scripting-api-document"> -<title>The Document API</title> -<para> -Whenever a script is being executed, there is a global variable -<quote><literal>document</literal></quote> representing the current active -document. The following is a list of all available Document functions. - -<variablelist><varlistentry> -<term><synopsis> -String document.fileName(); -</synopsis></term> -<listitem><para> -Returns the document's filename or an empty string for unsaved text buffers. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.url(); -</synopsis></term> -<listitem><para> -Returns the document's full url or an empty string for unsaved text buffers. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.mimeType(); -</synopsis></term> -<listitem><para> -Returns the document's mime type or the mime type <literal>application/octet-stream</literal> -if no appropriate mime type could be found. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.encoding(); -</synopsis></term> -<listitem><para> -Returns the currently used encoding to save the file. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -String document.highlightingMode(); -</synopsis></term> -<listitem><para> -Returns the global highlighting mode used for the whole document. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -String document.highlightingModeAt(<parameter>Cursor <replaceable>pos</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Returns the highlighting mode used at the given position in the document. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -Array document.embeddedHighlightingModes(); -</synopsis></term> -<listitem><para> -Returns an array of highlighting modes embedded in this document. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><synopsis> -bool document.isModified(); -</synopsis></term> -<listitem><para> -Returns <literal>true</literal>, if the document has unsaved changes (modified), otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.text(); -</synopsis></term> -<listitem><para> -Returns the entire content of the document in a single text string. Newlines -are marked with the newline character <quote><literal>\n</literal></quote>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.text(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>); -String document.text(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>); -String document.text(<parameter>Range <replaceable>range</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the text in the given range. It is recommended to use the cursor - and range based version for better readability of the source code. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.line(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the given text line as string. The string is empty if the requested - line is out of range. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.wordAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -String document.wordAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the word at the given cursor position. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term> -<synopsis> -Range document.wordRangeAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -Range document.wordRangeAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis> -</term> -<listitem><para> -Return the range of the word at the given cursor position. The returned range -is invalid (see Range.isValid()), if the text position is after the end of a -line. If there is no word at the given cursor, an empty range is returned. -</para> -<para> - Since: KDE 4.9 -</para> -</listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.charAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -String document.charAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the character at the given cursor position. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.firstChar(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the first character in the given <replaceable>line</replaceable> - that is not a whitespace. The first character is at column 0. If the line - is empty or only contains whitespace characters, the returned string is - empty. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.lastChar(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the last character in the given <replaceable>line</replaceable> - that is not a whitespace. If the line is empty or only contains whitespace - characters, the returned string is empty. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isSpace(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isSpace(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the character at the given cursor position is a whitespace, - otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.matchesAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); -bool document.matchesAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the given <replaceable>text</replaceable> matches at the - corresponding cursor position, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.startsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the line starts with <replaceable>text</replaceable>, otherwise <literal>false</literal>. - The argument <replaceable>skipWhiteSpaces</replaceable> controls whether leading whitespaces are ignored. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.endsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the line ends with <replaceable>text</replaceable>, otherwise <literal>false</literal>. - The argument <replaceable>skipWhiteSpaces</replaceable> controls whether trailing whitespaces are ignored. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.setText(<parameter>String <replaceable>text</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Sets the entire document text. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.clear(); -</synopsis></term> -<listitem><para> - Removes the entire text in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.truncate(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.truncate(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Truncate the given line at the given column or cursor position. Returns <literal>true</literal> - on success, or <literal>false</literal> if the given line is not part of the document range. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.insertText(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); -bool document.insertText(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Inserts the <replaceable>text</replaceable> at the given cursor position. - Returns <literal>true</literal> on success, or <literal>false</literal>, if the document is in read-only mode. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.removeText(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>); -bool document.removeText(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>); -bool document.removeText(<parameter>Range <replaceable>range</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Removes the text in the given range. Returns <literal>true</literal> on success, or <literal>false</literal>, if - the document is in read-only mode. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.insertLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Inserts text in the given line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the - document is in read-only mode or the line is not in the document range. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.removeLine(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Removes the given text line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the - document is in read-only mode or the line is not in the document range. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.wrapLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.wrapLine(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> -Wraps the line at the given cursor position. Returns <literal>true</literal> on success, -otherwise <literal>false</literal>, e.g. if line < 0. -</para> -<para> - Since: KDE 4.9 -</para> -</listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void document.joinLines(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Joins the lines from <replaceable>startLine</replaceable> to <replaceable>endLine</replaceable>. - Two succeeding text lines are always separated with a single space. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.lines(); -</synopsis></term> -<listitem><para> - Returns the amount of lines in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.length(); -</synopsis></term> -<listitem><para> - Returns the number of characters in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.lineLength(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the <replaceable>line</replaceable>'s length. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void document.editBegin(); -</synopsis></term> -<listitem><para> - Starts an edit group for undo/redo grouping. Make sure to always call - <function>editEnd()</function> as often as you call - <function>editBegin()</function>. Calling <function>editBegin()</function> - internally uses a reference counter, i.e., this call can be nested. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -void document.editEnd(); -</synopsis></term> -<listitem><para> - Ends an edit group. The last call of <function>editEnd()</function> (i.e. - the one for the first call of <function>editBegin()</function>) finishes - the edit step. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.firstColumn(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the first non-whitespace column in the given <replaceable>line</replaceable>. - If there are only whitespaces in the line, the return value is <literal>-1</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.lastColumn(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the last non-whitespace column in the given <replaceable>line</replaceable>. - If there are only whitespaces in the line, the return value is <literal>-1</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.prevNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -int document.prevNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the column with a non-whitespace characters starting at the given - cursor position and searching backwards. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.nextNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -int document.nextNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the column with a non-whitespace characters starting at the given - cursor position and searching forwards. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.prevNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the next non-empty line containing non-whitespace characters - searching backwards. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.nextNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the next non-empty line containing non-whitespace characters - searching forwards. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isInWord(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the - given <replaceable>attribute</replaceable> can be part of a word, otherwise - <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.canBreakAt(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the given - <replaceable>attribute</replaceable> is suited to wrap a line, otherwise - <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.canComment(<parameter>int <replaceable>startAttribute</replaceable></parameter>, <parameter>int <replaceable>endAttribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if a range starting and ending with the given attributes is - suited to be commented out, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.commentMarker(<parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the comment marker for single line comments for a given <replaceable>attribute</replaceable>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.commentStart(<parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the comment marker for the start of multi-line comments for a given - <replaceable>attribute</replaceable>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.commentEnd(<parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the comment marker for the end of multi-line comments for a given - <replaceable>attribute</replaceable>. -</para></listitem> -</varlistentry> - - - -<varlistentry> -<term><synopsis> -int document.attribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -int document.attribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the attribute at the given cursor position. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isAttribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); -bool document.isAttribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute at the given cursor position equals <replaceable>attribute</replaceable>, - otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.attributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -String document.attributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the attribute name as human readable text. This equals to the - <literal>itemData</literal> name in the syntax highlighting files. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isAttributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>); -bool document.isAttributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute name at a certain cursor position matches - the given <replaceable>name</replaceable>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.variable(<parameter>String <replaceable>key</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the value of the requested document variable <replaceable>key</replaceable>. - If the document variable does not exist, the return value is an empty string. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -String document.setVariable(<parameter>String <replaceable>key</replaceable></parameter>, <parameter>String <replaceable>value</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Set the value of the requested document variable <replaceable>key</replaceable>. - Returns the value of set variable. -</para> -<para> - See also: <link linkend="config-variables">Kate document variables</link> -</para> -<para> - Since: KDE 4.8 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.firstVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the virtual column of the first non-whitespace character in the given - line or <literal>-1</literal>, if the line is empty or contains only whitespace characters. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.lastVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the virtual column of the last non-whitespace character in the given - line or <literal>-1</literal>, if the line is empty or contains only whitespace characters. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.toVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -int document.toVirtualColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -Cursor document.toVirtualCursor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Converts the given <quote>real</quote> cursor position to a virtual cursor position, - either returning an int or a Cursor object. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.fromVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>virtualColumn</replaceable></parameter>); -int document.fromVirtualColumn(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>); -Cursor document.fromVirtualCursor(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Converts the given virtual cursor position to a <quote>real</quote> cursor position, - either returning an int or a Cursor object. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor document.anchor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>); -Cursor document.anchor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Searches backward for the given character starting from the given cursor. - As example, if '(' is passed as character, this function will return the - position of the opening '('. This reference counting, i.e. other '(...)' - are ignored. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor document.rfind(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>); -Cursor document.rfind(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>); -</synopsis></term> -<listitem><para> - Find backward the given text with the appropriate <replaceable>attribute</replaceable>. - The argument <replaceable>attribute</replaceable> is ignored if it is set to - <literal>-1</literal>. The returned cursor is invalid, if the text could not be found. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -int document.defStyleNum(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -int document.defStyleNum(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns the default style used at the given cursor position. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isCode(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isCode(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute at the given cursor position is not equal - to all of the following styles: <literal>dsComment</literal>, - <literal>dsString</literal>, <literal>dsRegionMarker</literal>, - <literal>dsChar</literal>, <literal>dsOthers</literal>. -</para></listitem> -</varlistentry> - - - -<varlistentry> -<term><synopsis> -bool document.isComment(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isComment(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute of the character at the cursor position - is <literal>dsComment</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isString(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isString(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute of the character at the cursor position - is <literal>dsString</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isRegionMarker(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isRegionMarker(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute of the character at the cursor position - is <literal>dsRegionMarker</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isChar(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isChar(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute of the character at the cursor position - is <literal>dsChar</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isOthers(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the attribute of the character at the cursor position - is <literal>dsOthers</literal>, otherwise <literal>false</literal>. -</para></listitem> -</varlistentry></variablelist> -</para> - -</sect3> -</sect2> -</sect1> </chapter> diff --git a/doc/kate/development.docbook b/doc/kate/development.docbook index fabd96c..aa23036 100644 --- a/doc/kate/development.docbook +++ b/doc/kate/development.docbook @@ -26,6 +26,1712 @@ enhancements with the world!</para> <sect1 id="dev-scripting"> <title>Scripting with JavaScript</title> +<para> +Since &kappname; 3.4 in KDE 4.4 the &kappname; editor component is easily extensible by +writing scripts. The scripting language is ECMAScript (widely known as JavaScript). +&kappname; supports two kinds of scripts: indentation and command line scripts. +</para> + +<sect2 id="dev-scripting-indentation"> +<title>Indentation Scripts</title> + +<para> +Indentation scripts - also referred as indenters - automatically indent the +source code while typing text. As example, after hitting the return-key code +the indentation level often increases. +</para> + +<para> +The following sections describe step by step how to create the skeleton for a +simple indenter. As first step, create a new <filename>*.js</filename> file +called e.g. <filename>javascript.js</filename> in the local home folder +<filename>$KDEHOME/share/apps/katepart/script/indentation</filename>. +</para> + +<sect3 id="dev-scripting-indentation-header"> +<title>The Indentation Script Header</title> +<para> +The header of the file <filename>javascript.js</filename> is embedded in a +comment and is of the following form + +<programlisting> +/* kate-script + * name: JavaScript + * author: Example Name <example.name at some.address.org> + * license: BSD + * revision: 1 + * kate-version: 3.4 + * required-syntax-style: javascript + * indent-languages: javascript + * priority: 0 + * i18n-catalog: mycatalog + * + * A line without colon ':' stops header parsing. That is, you can add optional + * text here such as a detailed license. + */ +</programlisting> + +Each entry is explained in detail now: +<itemizedlist> +<listitem><para> +<literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script. +</para></listitem> +<listitem><para> +<literal>name</literal> [required]: This is the indenter name that appears in the menu +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Indentation</guimenuitem></menuchoice> +and in the configuration dialog. +</para></listitem> +<listitem><para> +<literal>author</literal> [optional]: The author's name and contact information. +</para></listitem> +<listitem><para> +<literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3. +</para></listitem> +<listitem><para> +<literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified. +</para></listitem> +<listitem><para> +<literal>kate-version</literal> [required]: Minimal required &kappname; version. +</para></listitem> +<listitem><para> +<literal>required-syntax-style</literal> [optional]: Comma separated list of required syntax highlighting styles. This is important for indenters that rely on specific highlight information in the document. If a required syntax style is specified, the indenter is available only when the appropriate highlighter is active. This prevents <quote>undefined behavior</quote> caused by using the indenter without the expected highlighting schema. For instance, the Ruby indenter makes use of this in the files <filename>ruby.js</filename> and <filename>ruby.xml</filename>. +</para></listitem> +<listitem><para> +<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, e.g.: c++, java. +</para></listitem> +<listitem><para> +<literal>priority</literal> [optional]: If several indenters are suited for a certain highlighted file, the priority decides which indenter is chosen as default indenter. +</para></listitem> +<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party indenters.</para></listitem> +</itemizedlist> +</para> + +<para> +&kappname; reads all pairs of the form +<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> +until it cannot find a colon anymore. This implies that the header can contain +arbitrary text such as a license as shown in the example. +</para> + +</sect3> + +<sect3 id="dev-scripting-indentation-body"> +<title>The Indenter Source Code</title> +<para> +Having specified the header this section explains how the indentation scripting +itself works. The basic skeleton of the body looks like this: + +<programlisting> +// required katepart js libraries, e.g. range.js if you use Range +require ("range.js"); + +triggerCharacters = "{}/:;"; +function indent(line, indentWidth, ch) +{ + // called for each newline (ch == '\n') and all characters specified in + // the global variable triggerCharacters. When calling <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice> + // the variable ch is empty, i.e. ch == ''. + // + // see also: Scripting API + return -2; +} +</programlisting> + +The function <function>indent()</function> has three parameters: +<itemizedlist> +<listitem><para><literal>line</literal>: the line that has to be indented</para></listitem> +<listitem><para><literal>indentWidth</literal>: the indentation width in amount of spaces</para></listitem> +<listitem><para><literal>ch</literal>: either a newline character (<literal>ch == '\n'</literal>), the trigger character specified in <literal>triggerCharacters</literal> or empty if the user invoked the action <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>.</para></listitem> +</itemizedlist> +The return value of the <function>indent()</function> function specifies how +the line will be indented. If the return value is a simple integer number, it +is interpreted as follows: +<itemizedlist> +<listitem><para>return value <literal>-2</literal>: do nothing</para></listitem> +<listitem><para>return value <literal>-1</literal>: keep indentation (searches for previous non-blank line)</para></listitem> +<listitem><para>return value <literal> 0</literal>: numbers >= 0 specify the indentation depth in spaces</para></listitem> +</itemizedlist> +Alternatively, an array of two elements can be returned: +<itemizedlist> +<listitem><para><literal>return [ indent, align ];</literal></para></listitem> +</itemizedlist> +In this case, the first element is the indentation depth like above with the +same meaning of the special values. However, the second element is an absolute +value representing a column for <quote>alignment</quote>. If this value is higher than the +indent value, the difference represents a number of spaces to be added after +the indentation of the first parameter. Otherwise, the second number is ignored. +Using tabs and spaces for indentation is often referred to as <quote>mixed mode</quote>. +</para> + +<para> +Consider the following example: Assume using tabs to indent, and tab width is set +to 4. Here, <tab> represents a tab and '.' a space: +<programlisting> +1: <tab><tab>foobar("hello", +2: <tab><tab>......."world"); +</programlisting> +When indenting line 2, the <function>indent()</function> function returns [8, 15]. As result, two +tabs are inserted to indent to column 8, and 7 spaces are added to align the +second parameter under the first, so that it stays aligned if the file is viewed +with a different tab width. +</para> + +<para> +A default KDE installation ships &kappname; with several indenters. The +corresponding JavaScript source code can be found in <filename>$KDEDIR/share/apps/katepart/script/indentation</filename>. +</para> + +<para> +Developing an indenter requires to reload the scripts to see whether the changes +behave appropriately. Instead of restarting the application, simply switch to +the command line and invoke the command <command>reload-scripts</command>. +</para> + +<para> +If you develop useful scripts please consider contributing to the &kappname; Project +by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. +</para> + +</sect3> +</sect2> + +<sect2 id="dev-scripting-command-line"> +<title>Command Line Scripts</title> + +<para> +As it is hard to satisfy everyone's needs, &kappname; supports little helper tools +for quick text manipulation through the +<link linkend="advanced-editing-tools-commandline">built-in command line</link>. +For instance, the command +<command>sort</command> is implemented as script. This section explains how to create +<filename>*.js</filename> files to extend &kappname; with arbitrary helper scripts. +</para> + +<para> +Command line scripts are located in the same folder as indentation scripts. +So as first step, create a new <filename>*.js</filename> file called +<filename>myutils.js</filename> in the local home folder +<filename>$KDEHOME/share/apps/katepart/script/commands</filename>. +</para> + +<sect3 id="dev-scripting-command-line-header"> +<title>The Command Line Script Header</title> +<para> +The header of each command line script is embedded in a comment and is of the +following form + +<programlisting> +/* kate-script + * author: Example Name <example.name at some.address.org> + * license: BSD + * revision: 1 + * kate-version: 3.4 + * functions: sort, format-paragraph + * i18n-catalog: mycatalog + * + * A line without colon ':' stops header parsing. That is, you can add optional + * text here such as a detailed license. + */ +</programlisting> + +Each entry is explained in detail now: +<itemizedlist> +<listitem><para><literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.</para></listitem> +<listitem><para><literal>author</literal> [optional]: The author's name and contact information.</para></listitem> +<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.</para></listitem> +<listitem><para><literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.</para></listitem> +<listitem><para><literal>kate-version</literal> [required]: Minimal required &kappname; version.</para></listitem> +<listitem><para><literal>functions</literal> [required]: Comma separated list of commands in the script.</para></listitem> +<listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem> +</itemizedlist> +</para> + +<para> +&kappname; reads all pairs of the form +<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> +until it cannot find a colon +anymore. This implies that the header can contain arbitrary text such as a license +as shown in the example. The value of the key functions is a comma separated list +of command line commands. This means a single script contains an arbitrary amount +of command line commands. Each function is available through &kappname;'s +<link linkend="advanced-editing-tools-commandline">built-in command line</link>. +</para> +</sect3> + +<sect3 id="dev-scripting-command-line-body"> +<title>The Script Source Code</title> + +<para> +All functions specified in the header have to be implemented in the script. +For instance, the script file from the example above needs to implement the two +functions <command>sort</command> and <command>format-paragraph</command>. +All functions have the following syntax: + +<programlisting> +// required katepart js libraries, e.g. range.js if you use Range +require ("range.js"); + +function <name>(arg1, arg2, ...) +{ + // ... implementation, see also: Scripting API +} +</programlisting> +</para> + +<para> +Arguments in the command line are passed to the function as +<parameter>arg1</parameter>, <parameter>arg2</parameter>, etc. +In order to provide documentation for each command, simply implement the +'<function>help</function>' function as follows: + +<programlisting> +function help(cmd) +{ + if (cmd == "sort") { + return i18n("Sort the selected text."); + } else if (cmd == "...") { + // ... + } +} +</programlisting> + +Executing <command>help sort</command> in the command line then calls this help function with +the argument <parameter>cmd</parameter> set to the given command, i.e. +<parameter>cmd == "sort"</parameter>. &kappname; then presents the returned text as +documentation to the user. Make sure to +<link linkend="dev-scripting-api-i18n">translate the strings</link>. +</para> + +<sect4 id="dev-scripting-command-line-shortcuts"> +<title>Binding Shortcuts</title> +<para>In order to be able to assign shortcuts, the script needs to provide a +function called <literal>action</literal> as follows: +<programlisting> +function action(cmd) +{ + var a = new Object(); + if (cmd == "sort") { + a.text = i18n("Sort Selected Text"); + a.icon = ""; + a.category = ""; + a.interactive = false; + a.shortcut = ""; + } else if (cmd == "moveLinesDown") { + // same for next action + } + return a; +} +</programlisting> +The parameter <literal>cmd</literal> of the function specifies the command for +which a shortcut is requested. There are several fields you have to specify in +the returned javascript object: +<itemizedlist> +<listitem><para><literal>a.text</literal> [required]: The text appears in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>. Make sure to use <literal>i18n</literal> for translation.</para></listitem> +<listitem><para><literal>a.icon</literal> [optional]: The icon appears next to the text in the menu. All KDE icon names can be used here.</para></listitem> +<listitem><para><literal>a.category</literal> [optional]: If a category is specified, the script appears in a submenu. Make sure to use <literal>i18n</literal> for translation.</para></listitem> +<listitem><para><literal>a.interactive</literal> [optional]: If the script needs user input, set this to <literal>true</literal>.</para></listitem> +<listitem><para><literal>a.shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: Ctrl+Alt+t. See the <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum";>Qt documentation</ulink> for further details.</para></listitem> +</itemizedlist> +</para> + + +<para> +Developing a command line script requires to reload the scripts to see whether +the changes behave appropriately. Instead of restarting the application, simply +switch to the command line and invoke the command <command>reload-scripts</command>. +</para> + +<para> +If you develop useful scripts please consider contributing to the &kappname; Project +by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. +</para> + +</sect4> +</sect3> +</sect2> + +<sect2 id="dev-scripting-api"> +<title>Scripting API</title> + +<para> +The scripting API presented here is available in all scripts, i.e. indentation +scripts and command line commands. +The <classname>Cursor</classname> and <classname>Range</classname> are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>. +If you want to use them in your script, which is required to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the needed library by using: + +<programlisting> +// required katepart js libraries, e.g. range.js if you use Range +require ("range.js"); +</programlisting> +</para> + +<para> +To extend the standard scripting API with own functions and prototypes simply +create a new file in the KDE's local configuration folder +<filename>$KDEHOME/share/apps/katepart/libraries</filename> and include it into your script using: + +<programlisting> +require ("myscriptnamehere.js"); +</programlisting> + +</para> + +<para> +To extend existing prototypes like <classname>Cursor</classname> or +<classname>Range</classname>, the recommended way is to +<emphasis>not</emphasis> modify the global <filename>*.js</filename> files. +Instead, change the <classname>Cursor</classname> prototype in JavaScript after the <filename>cursor.js</filename> is included into your +script via <literal>require</literal>. +</para> + +<sect3 id="dev-scripting-api-prototypes"> +<title>Cursors and Ranges</title> + +<para> +As &kappname; is a text editor, all the scripting API is based on cursors and +ranges whenever possible. A Cursor is a simple <literal>(line, column)</literal> +tuple representing a text position in the document. A Range spans text from a +starting cursor position to an ending cursor position. The API is explained in +detail in the next sections. +</para> + +<sect4 id="dev-scripting-api-cursors"> +<title>The Cursor Prototype</title> + +<variablelist><varlistentry> +<term><synopsis> +Cursor(); +</synopsis></term> +<listitem><para> +Constructor. Returns a Cursor at position <literal>(0, 0)</literal>.</para> +<para>Example: <function>var cursor = new Cursor();</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Constructor. Returns a Cursor at position (line, column). +</para> +<para>Example: <function>var cursor = new Cursor(3, 42);</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor(<parameter>Cursor <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Copy constructor. Returns a copy of the cursor <replaceable>other</replaceable>. +</para> +<para>Example: <function>var copy = new Cursor(other);</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor Cursor.clone(); +</synopsis></term> +<listitem><para> +Returns a clone of the cursor.</para> +<para>Example: <function>var clone = cursor.clone();</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor.setPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Sets the cursor position to <replaceable>line</replaceable> and <replaceable>column</replaceable>.</para> +<para> +Since: KDE 4.11 +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Cursor.isValid(); +</synopsis></term> +<listitem><para> +Check whether the cursor is valid. The cursor is invalid, if line and/or +column are set to <literal>-1</literal>. +</para> +<para> +Example: <function>var valid = cursor.isValid();</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor Cursor.invalid(); +</synopsis></term> +<listitem><para> +Returns an new invalid cursor located at <literal>(-1, -1)</literal>. +</para> +<para>Example: <function>var invalidCursor = cursor.invalid();</function> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +int Cursor.compareTo(<parameter>Cursor <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Compares this cursor to the cursor <replaceable>other</replaceable>. Returns +<itemizedlist> +<listitem><para><literal>-1</literal>, if this cursor is located before the cursor <replaceable>other</replaceable>,</para></listitem> +<listitem><para><literal>0</literal>, if both cursors equal and</para></listitem> +<listitem><para><literal>+1</literal>, if this cursor is located after the cursor <replaceable>other</replaceable>.</para></listitem> +</itemizedlist> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Cursor.equals(<parameter>Cursor <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if this cursor and the cursor <replaceable>other</replaceable> are +equal, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String Cursor.toString(); +</synopsis></term> +<listitem><para> +Returns the cursor as a string of the form <quote><literal>Cursor(line, column)</literal></quote>. +</para></listitem> +</varlistentry></variablelist> + +</sect4> + + +<sect4 id="dev-scripting-api-ranges"> +<title>The Range Prototype</title> + +<variablelist><varlistentry> +<term><synopsis> +Range(); +</synopsis></term> +<listitem><para> +Constructor. Calling <literal>new Range()</literal> returns a Range at (0, 0) - (0, 0). +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range(<parameter>Cursor <replaceable>start</replaceable></parameter>, <parameter>Cursor <replaceable>end</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Constructor. Calling <literal>new Range(<replaceable>start</replaceable>, <replaceable>end</replaceable>)</literal> returns the Range (<replaceable>start</replaceable>, <replaceable>end</replaceable>). +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>startColumn</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>, <parameter>int <replaceable>endColumn</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Constructor. Calling <literal>new Range(<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>, <replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>)</literal> +returns the Range from (<replaceable>startLine</replaceable>, <replaceable>startColumn</replaceable>) to (<replaceable>endLine</replaceable>, <replaceable>endColumn</replaceable>). +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range(<parameter>Range <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Copy constructor. Returns a copy of Range <replaceable>other</replaceable>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range Range.clone(); +</synopsis></term> +<listitem><para> +Returns a clone of the range. +</para> +<para>Example: <function>var clone = range.clone();</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.isEmpty(); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if the start and end cursors are equal. +</para> +<para>Example: <function>var empty = range.isEmpty();</function> +</para> +<para> +Since: KDE 4.11 +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.isValid(); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if both start and end cursor are valid, otherwise <literal>false</literal>. +</para> +<para>Example: <function>var valid = range.isValid();</function> +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range Range.invalid(); +</synopsis></term> +<listitem><para> +Returns the Range from (-1, -1) to (-1, -1). +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.contains(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if this range contains the cursor position, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.contains(<parameter>Range <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if this range contains the Range <replaceable>other</replaceable>, +otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.containsColumn(<parameter>int <replaceable>column</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the half open interval +<literal>[start.column, end.column)</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.containsLine(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the half open interval +<literal>[start.line, end.line)</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.overlaps(<parameter>Range <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if this range and the range <replaceable>other</replaceable> share +a common region, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.overlapsLine(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if <replaceable>line</replaceable> is in the interval +<literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.overlapsColumn(<parameter>int <replaceable>column</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if <replaceable>column</replaceable> is in the interval +<literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.onSingleLine(); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if the range starts and ends at the same line, +i.e. if <replaceable>Range.start.line == Range.end.line</replaceable>. +</para> +<para> +Since: KDE 4.9 +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool Range.equals(<parameter>Range <replaceable>other</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if this range and the Range <replaceable>other</replaceable> are +equal, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String Range.toString(); +</synopsis></term> +<listitem><para> +Returns the range as a string of the form <quote><literal>Range(Cursor(line, column), Cursor(line, column))</literal></quote>. +</para></listitem> +</varlistentry></variablelist> + +</sect4> +</sect3> + +<sect3 id="dev-scripting-api-global"> +<title>Global Functions</title> +<para>This section lists all global functions.</para> + + +<sect4 id="dev-scripting-api-includes"> +<title>Reading & Including Files</title> + +<variablelist><varlistentry> +<term><synopsis> +String read(<parameter>String <replaceable>file</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/files</literal> directory and return its content as a string. +</para></listitem> +</varlistentry></variablelist> + +<variablelist><varlistentry> +<term><synopsis> +void require(<parameter>String <replaceable>file</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Will search the given <replaceable>file</replaceable> relative to the <literal>katepart/script/libraries</literal> directory and evaluate it. +<literal>require</literal> is internally guarded against multiple inclusions of the same <replaceable>file</replaceable>. +</para> +<para> + Since: KDE 4.10 +</para> +</listitem> +</varlistentry></variablelist> + +</sect4> + +<sect4 id="dev-scripting-api-debug"> +<title>Debugging</title> + +<variablelist><varlistentry> +<term><synopsis> +void debug(<parameter>String <replaceable>text</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Prints <replaceable>text</replaceable> to <literal>stdout</literal> in the +console launching the application. +</para></listitem> +</varlistentry></variablelist> + +</sect4> + +<sect4 id="dev-scripting-api-i18n"> +<title>Translation</title> + +<para>In order to support full localization, there are several functions to translate +strings in scripts, namely <literal>i18n</literal>, <literal>i18nc</literal>, +<literal>i18np</literal> and <literal>i18ncp</literal>. These functions behave +exactly like <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n";> +KDE's translation functions</ulink>. +</para> + +<para>The translation functions translate the wrapped strings through KDE's +translation system to the language used in the application. Strings in scripts +being developed in the official &kappname; sources are automatically extracted and +translatable. In other words, as a &kappname; developer you do not have to bother with +message extraction and translation. However, for 3rd-party scripts developed +outside of KDE, you have to extract and translate the messages yourself. Along +with your scripts you have to also distribute a translation catalog, that +includes all translated strings. Further, your script header then must +explicitly state the catalog to load by specifying +<literal>i18n-catalog</literal>. +</para> + +<variablelist><varlistentry> +<term><synopsis> +void i18n(<parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); +</synopsis></term> +<listitem><para> +Translates <replaceable>text</replaceable> into the language used by the application. +The arguments <replaceable>arg1</replaceable>, ..., are optional and used to +replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +void i18nc(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); +</synopsis></term> +<listitem><para> +Translates <replaceable>text</replaceable> into the language used by the +application. Additionally, the string <replaceable>context</replaceable> is +visible to translators so they can provide a better translation. +The arguments <replaceable>arg1</replaceable>, ..., are optional and used to +replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +void i18np(<parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); +</synopsis></term> +<listitem><para> +Translates either <replaceable>singular</replaceable> or +<replaceable>plural</replaceable> into the language used by the application, +depending on the given <replaceable>number</replaceable>. +The arguments <replaceable>arg1</replaceable>, ..., are optional and used to +replace the placeholders <literal>%1</literal>, <literal>%2</literal>, etc.</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +void i18ncp(<parameter>String <replaceable>context</replaceable></parameter>, <parameter>String <replaceable>singular</replaceable></parameter>, <parameter>String <replaceable>plural</replaceable></parameter>, <parameter>int <replaceable>number</replaceable></parameter>, <replaceable>arg1</replaceable>, ...); +</synopsis></term> +<listitem><para> +Translates either <replaceable>singular</replaceable> or +<replaceable>plural</replaceable> into the language used by the application, +depending on the given <replaceable>number</replaceable>. Additionally, the +string <replaceable>context</replaceable> is visible to translators so they +can provide a better translation. The arguments <replaceable>arg1</replaceable>, +..., are optional and used to replace the placeholders <literal>%1</literal>, +<literal>%2</literal>, etc.</para></listitem> +</varlistentry></variablelist> + +</sect4> +</sect3> + +<sect3 id="dev-scripting-api-view"> +<title>The View API</title> +<para>Whenever a script is being executed, there is a global variable +<quote><literal>view</literal></quote> representing the current active editor +view. The following is a list of all available View functions. + +<variablelist><varlistentry> +<term><synopsis> +<function>Cursor view.cursorPosition()</function> +</synopsis></term> +<listitem><para>Returns the current cursor position in the view.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.setCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +void view.setCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Set the current cursor position to either (line, column) or to the given cursor. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor view.virtualCursorPosition(); +</synopsis></term> +<listitem><para> +Returns the virtual cursor position with each tab counting the corresponding amount of spaces depending on the current tab width. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.setVirtualCursorPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +void view.setVirtualCursorPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Set the current virtual cursor position to (line, column) or to the given cursor. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String view.selectedText(); +</synopsis></term> +<listitem><para> +Returns the selected text. If no text is selected, the returned string is empty. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool view.hasSelection(); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if the view has selected text, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Range view.selection(); +</synopsis></term> +<listitem><para> +Returns the selected text range. The returned range is invalid if there is no +selected text. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.setSelection(<parameter>Range <replaceable>range</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Set the selected text to the given range. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.removeSelectedText(); +</synopsis></term> +<listitem><para> +Remove the selected text. If the view does not have any selected text, this +does nothing. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.selectAll(); +</synopsis></term> +<listitem><para> +Selects the entire text in the document. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void view.clearSelection(); +</synopsis></term> +<listitem><para> +Clears the text selection without removing the text. +</para></listitem> +</varlistentry></variablelist> +</para> +</sect3> + +<sect3 id="dev-scripting-api-document"> +<title>The Document API</title> +<para> +Whenever a script is being executed, there is a global variable +<quote><literal>document</literal></quote> representing the current active +document. The following is a list of all available Document functions. + +<variablelist><varlistentry> +<term><synopsis> +String document.fileName(); +</synopsis></term> +<listitem><para> +Returns the document's filename or an empty string for unsaved text buffers. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.url(); +</synopsis></term> +<listitem><para> +Returns the document's full url or an empty string for unsaved text buffers. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.mimeType(); +</synopsis></term> +<listitem><para> +Returns the document's mime type or the mime type <literal>application/octet-stream</literal> +if no appropriate mime type could be found. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.encoding(); +</synopsis></term> +<listitem><para> +Returns the currently used encoding to save the file. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +String document.highlightingMode(); +</synopsis></term> +<listitem><para> +Returns the global highlighting mode used for the whole document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +String document.highlightingModeAt(<parameter>Cursor <replaceable>pos</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Returns the highlighting mode used at the given position in the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +Array document.embeddedHighlightingModes(); +</synopsis></term> +<listitem><para> +Returns an array of highlighting modes embedded in this document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><synopsis> +bool document.isModified(); +</synopsis></term> +<listitem><para> +Returns <literal>true</literal>, if the document has unsaved changes (modified), otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.text(); +</synopsis></term> +<listitem><para> +Returns the entire content of the document in a single text string. Newlines +are marked with the newline character <quote><literal>\n</literal></quote>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.text(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>); +String document.text(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>); +String document.text(<parameter>Range <replaceable>range</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the text in the given range. It is recommended to use the cursor + and range based version for better readability of the source code. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.line(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the given text line as string. The string is empty if the requested + line is out of range. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.wordAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +String document.wordAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the word at the given cursor position. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term> +<synopsis> +Range document.wordRangeAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +Range document.wordRangeAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis> +</term> +<listitem><para> +Return the range of the word at the given cursor position. The returned range +is invalid (see Range.isValid()), if the text position is after the end of a +line. If there is no word at the given cursor, an empty range is returned. +</para> +<para> + Since: KDE 4.9 +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.charAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +String document.charAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the character at the given cursor position. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.firstChar(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the first character in the given <replaceable>line</replaceable> + that is not a whitespace. The first character is at column 0. If the line + is empty or only contains whitespace characters, the returned string is + empty. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.lastChar(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the last character in the given <replaceable>line</replaceable> + that is not a whitespace. If the line is empty or only contains whitespace + characters, the returned string is empty. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isSpace(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isSpace(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the character at the given cursor position is a whitespace, + otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.matchesAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); +bool document.matchesAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the given <replaceable>text</replaceable> matches at the + corresponding cursor position, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.startsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the line starts with <replaceable>text</replaceable>, otherwise <literal>false</literal>. + The argument <replaceable>skipWhiteSpaces</replaceable> controls whether leading whitespaces are ignored. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.endsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the line ends with <replaceable>text</replaceable>, otherwise <literal>false</literal>. + The argument <replaceable>skipWhiteSpaces</replaceable> controls whether trailing whitespaces are ignored. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.setText(<parameter>String <replaceable>text</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Sets the entire document text. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.clear(); +</synopsis></term> +<listitem><para> + Removes the entire text in the document. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.truncate(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.truncate(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Truncate the given line at the given column or cursor position. Returns <literal>true</literal> + on success, or <literal>false</literal> if the given line is not part of the document range. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.insertText(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); +bool document.insertText(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Inserts the <replaceable>text</replaceable> at the given cursor position. + Returns <literal>true</literal> on success, or <literal>false</literal>, if the document is in read-only mode. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.removeText(<parameter>int <replaceable>fromLine</replaceable></parameter>, <parameter>int <replaceable>fromColumn</replaceable></parameter>, <parameter>int <replaceable>toLine</replaceable></parameter>, <parameter>int <replaceable>toColumn</replaceable></parameter>); +bool document.removeText(<parameter>Cursor <replaceable>from</replaceable></parameter>, <parameter>Cursor <replaceable>to</replaceable></parameter>); +bool document.removeText(<parameter>Range <replaceable>range</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Removes the text in the given range. Returns <literal>true</literal> on success, or <literal>false</literal>, if + the document is in read-only mode. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.insertLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Inserts text in the given line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the + document is in read-only mode or the line is not in the document range. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.removeLine(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Removes the given text line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the + document is in read-only mode or the line is not in the document range. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.wrapLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.wrapLine(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> +Wraps the line at the given cursor position. Returns <literal>true</literal> on success, +otherwise <literal>false</literal>, e.g. if line < 0. +</para> +<para> + Since: KDE 4.9 +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void document.joinLines(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>int <replaceable>endLine</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Joins the lines from <replaceable>startLine</replaceable> to <replaceable>endLine</replaceable>. + Two succeeding text lines are always separated with a single space. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.lines(); +</synopsis></term> +<listitem><para> + Returns the amount of lines in the document. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.length(); +</synopsis></term> +<listitem><para> + Returns the number of characters in the document. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.lineLength(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the <replaceable>line</replaceable>'s length. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void document.editBegin(); +</synopsis></term> +<listitem><para> + Starts an edit group for undo/redo grouping. Make sure to always call + <function>editEnd()</function> as often as you call + <function>editBegin()</function>. Calling <function>editBegin()</function> + internally uses a reference counter, i.e., this call can be nested. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +void document.editEnd(); +</synopsis></term> +<listitem><para> + Ends an edit group. The last call of <function>editEnd()</function> (i.e. + the one for the first call of <function>editBegin()</function>) finishes + the edit step. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.firstColumn(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the first non-whitespace column in the given <replaceable>line</replaceable>. + If there are only whitespaces in the line, the return value is <literal>-1</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.lastColumn(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the last non-whitespace column in the given <replaceable>line</replaceable>. + If there are only whitespaces in the line, the return value is <literal>-1</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.prevNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +int document.prevNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the column with a non-whitespace characters starting at the given + cursor position and searching backwards. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.nextNonSpaceColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +int document.nextNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the column with a non-whitespace characters starting at the given + cursor position and searching forwards. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.prevNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the next non-empty line containing non-whitespace characters + searching backwards. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.nextNonEmptyLine(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the next non-empty line containing non-whitespace characters + searching forwards. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isInWord(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the + given <replaceable>attribute</replaceable> can be part of a word, otherwise + <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.canBreakAt(<parameter>String <replaceable>character</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the given <replaceable>character</replaceable> with the given + <replaceable>attribute</replaceable> is suited to wrap a line, otherwise + <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.canComment(<parameter>int <replaceable>startAttribute</replaceable></parameter>, <parameter>int <replaceable>endAttribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if a range starting and ending with the given attributes is + suited to be commented out, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.commentMarker(<parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the comment marker for single line comments for a given <replaceable>attribute</replaceable>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.commentStart(<parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the comment marker for the start of multi-line comments for a given + <replaceable>attribute</replaceable>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.commentEnd(<parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the comment marker for the end of multi-line comments for a given + <replaceable>attribute</replaceable>. +</para></listitem> +</varlistentry> + + + +<varlistentry> +<term><synopsis> +int document.attribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +int document.attribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the attribute at the given cursor position. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isAttribute(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); +bool document.isAttribute(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute at the given cursor position equals <replaceable>attribute</replaceable>, + otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.attributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +String document.attributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the attribute name as human readable text. This equals to the + <literal>itemData</literal> name in the syntax highlighting files. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isAttributeName(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>); +bool document.isAttributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>name</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute name at a certain cursor position matches + the given <replaceable>name</replaceable>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.variable(<parameter>String <replaceable>key</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the value of the requested document variable <replaceable>key</replaceable>. + If the document variable does not exist, the return value is an empty string. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +String document.setVariable(<parameter>String <replaceable>key</replaceable></parameter>, <parameter>String <replaceable>value</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Set the value of the requested document variable <replaceable>key</replaceable>. + Returns the value of set variable. +</para> +<para> + See also: <link linkend="config-variables">Kate document variables</link> +</para> +<para> + Since: KDE 4.8 +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.firstVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the virtual column of the first non-whitespace character in the given + line or <literal>-1</literal>, if the line is empty or contains only whitespace characters. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.lastVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the virtual column of the last non-whitespace character in the given + line or <literal>-1</literal>, if the line is empty or contains only whitespace characters. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.toVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +int document.toVirtualColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +Cursor document.toVirtualCursor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Converts the given <quote>real</quote> cursor position to a virtual cursor position, + either returning an int or a Cursor object. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.fromVirtualColumn(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>virtualColumn</replaceable></parameter>); +int document.fromVirtualColumn(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>); +Cursor document.fromVirtualCursor(<parameter>Cursor <replaceable>virtualCursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Converts the given virtual cursor position to a <quote>real</quote> cursor position, + either returning an int or a Cursor object. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor document.anchor(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>); +Cursor document.anchor(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>Char <replaceable>character</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Searches backward for the given character starting from the given cursor. + As example, if '(' is passed as character, this function will return the + position of the opening '('. This reference counting, i.e. other '(...)' + are ignored. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +Cursor document.rfind(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>); +Cursor document.rfind(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>); +</synopsis></term> +<listitem><para> + Find backward the given text with the appropriate <replaceable>attribute</replaceable>. + The argument <replaceable>attribute</replaceable> is ignored if it is set to + <literal>-1</literal>. The returned cursor is invalid, if the text could not be found. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +int document.defStyleNum(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +int document.defStyleNum(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns the default style used at the given cursor position. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isCode(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isCode(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute at the given cursor position is not equal + to all of the following styles: <literal>dsComment</literal>, + <literal>dsString</literal>, <literal>dsRegionMarker</literal>, + <literal>dsChar</literal>, <literal>dsOthers</literal>. +</para></listitem> +</varlistentry> + + + +<varlistentry> +<term><synopsis> +bool document.isComment(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isComment(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute of the character at the cursor position + is <literal>dsComment</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isString(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isString(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute of the character at the cursor position + is <literal>dsString</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isRegionMarker(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isRegionMarker(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute of the character at the cursor position + is <literal>dsRegionMarker</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isChar(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isChar(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute of the character at the cursor position + is <literal>dsChar</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><synopsis> +bool document.isOthers(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); +bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); +</synopsis></term> +<listitem><para> + Returns <literal>true</literal>, if the attribute of the character at the cursor position + is <literal>dsOthers</literal>, otherwise <literal>false</literal>. +</para></listitem> +</varlistentry></variablelist> +</para> + +</sect3> +</sect2> + </sect1> <sect1 id="dev-part"> diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook index 2d7fb4a..36ab004 100644 --- a/doc/kate/menus.docbook +++ b/doc/kate/menus.docbook @@ -864,7 +864,7 @@ enabled by default.</para> </menuchoice></term> <listitem><para>This opens a tool view that allows you to run Javascript code interactively. For more information, see -<link linkend="advanced-editing-tools-scripting">Extending &kate; with Scripts</link>. +<link linkend="dev-scripting">Extending &kate; with Scripts</link>. </para></listitem> </varlistentry> @@ -1363,7 +1363,7 @@ the endianness (byte order) of a text file or stream, for more information see <guisubmenu>Scripts</guisubmenu></menuchoice></term> <listitem> <para>This submenu contains a list of all scripted actions. The list can easily be -modified by <link linkend="advanced-editing-tools-scripting-command-line">writing +modified by <link linkend="dev-scripting-command-line">writing own scripts</link>. This way, &kate; can be extended with user-defined tools. </para> @@ -1396,7 +1396,7 @@ that with <computeroutput><div></div></computeroutput>. </menuchoice></term> <listitem><para> Wraps the selected text with the tag provided on the -<link linkend="advanced-editing-tools-scripting-command-line">command line</link>. +<link linkend="dev-scripting-command-line">command line</link>. </para></listitem> </varlistentry> diff --git a/doc/kwrite/menus.docbook b/doc/kwrite/menus.docbook index 55235a3..5a88bc4 100644 --- a/doc/kwrite/menus.docbook +++ b/doc/kwrite/menus.docbook @@ -520,7 +520,7 @@ Component Command Line</ulink>.</para> </menuchoice> (Power user mode)</term> <listitem><para>This opens a tool view that allows you to run Javascript code interactively. For more information, see -<ulink url="help:/kate/advanced-editing-tools-scripting.html">Extending &kate; with Scripts</ulink> +<ulink url="help:/kate/dev-scripting.html">Extending &kate; with Scripts</ulink> </para></listitem> </varlistentry> diff --git a/part/snippet/editsnippet.cpp b/part/snippet/editsnippet.cpp index 08c6de0..5090e06 100644 --- a/part/snippet/editsnippet.cpp +++ b/part/snippet/editsnippet.cpp @@ -196,7 +196,7 @@ void EditSnippet::slotSnippetDocumentation() void EditSnippet::slotScriptDocumentation() { - KToolInvocation::invokeHelp("advanced-editing-tools-scripting-api", "kate"); + KToolInvocation::invokeHelp("dev-scripting-api", "kate"); } void EditSnippet::reject()
