Git commit 74956b9dfe3c9125165086433f12f2955313ac6f by T.C. Hollingsworth. Committed on 19/02/2014 at 23:57. Pushed by hollingsworth into branch 'frameworks'.
add stub development chapter to katepart M +2 -1808 doc/kate/development.docbook C +8 -43 doc/katepart/development.docbook [from: doc/kate/development.docbook - 097% similarity] http://commits.kde.org/kate/74956b9dfe3c9125165086433f12f2955313ac6f diff --git a/doc/kate/development.docbook b/doc/kate/development.docbook index 0f23b0d..415c563 100644 --- a/doc/kate/development.docbook +++ b/doc/kate/development.docbook @@ -26,1820 +26,14 @@ 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 an example, after hitting the return key -the indentation level often increases. -</para> - -<para> -The following sections describe step by step how to create the skeleton for a -simple indenter. As a first step, create a new <filename>*.js</filename> file -called ⪚ <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 a 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]: Minimum 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, ⪚: 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 number 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 as 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 reloading 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 a 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 a 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 a 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]: Minimum 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 number -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, &ie; -<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://qt-project.org/doc/qt-4.8/qt.html#Key-enum";>Qt documentation</ulink> for further details.</para></listitem> -</itemizedlist> -</para> - - -<para> -Developing a command line script requires reloading 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 to all scripts, &ie; indentation -scripts and command line commands. -The <classname>Cursor</classname> and <classname>Range</classname> classes are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>. -If you want to use them in your script, which needs to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the necessary 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 your own functions and prototypes simply -create a new file in &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 a 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, -&ie; 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>, ⪚ 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 number of lines in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isLineModified(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if <replaceable>line</replaceable> currently contains unsaved data. -</para> -<para> - Since: &kde; 5.0 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isLineSaved(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if <replaceable>line</replaceable> was changed, but the document was saved. - Hence, the line currently does not contain any unsaved data. -</para> -<para> - Since: &kde; 5.0 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.isLineTouched(<parameter>int <replaceable>line</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if <replaceable>line</replaceable> currently contains unsaved data or was changed before. -</para> -<para> - Since: &kde; 5.0 -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool document.findTouchedLine(<parameter>int <replaceable>startLine</replaceable></parameter>, <parameter>bool <replaceable>down</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Search for the next touched line starting at <replaceable>line</replaceable>. - The search is performed either upwards or downwards depending on the search direction specified in <replaceable>down</replaceable>. -</para> -<para> - Since: &kde; 5.0 -</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, &ie;, 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> (&ie; - 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 character 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 character 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> -Range document.documentRange(); -</synopsis></term> -<listitem><para> - Returns a range that encompasses the whole document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -Cursor documentEnd(); -</synopsis></term> -<listitem><para> - Returns a cursor positioned at the last column of the last line in the document. -</para></listitem> -</varlistentry> - - -<varlistentry> -<term><synopsis> -bool isValidTextPosition(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>); -bool isValidTextPosition(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); -</synopsis></term> -<listitem><para> - Returns <literal>true</literal>, if the given cursor position is positioned at a valid text position. - A text position is valid only if it locate at the start, in the middle, or the end of a valid line. - Further, a text position is invalid if it is located in a Unicode surrogate. -</para><para> - Since: &kde; 5.0 -</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 is equal 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 the 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 an example, if '(' is passed as character, this function will return the - position of the opening '('. This reference counting, &ie; 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 searching backwards 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> +<!--FIXME: link to katepart js api doc--> </sect1> <sect1 id="dev-part"> <title>Editor Component Extensions</title> -<para><link linkend="editor-component-plugins">Editor Component Extensions</link> -extend KatePart, the Advanced Text Editor component used within many &kde; -applications, such as &kate;, &kwrite;, Kile, and KDevelop. Creating an Editor -Component Plugin will allow you to extend the editor's functionality in any and -all of these programs.</para> - -<para>To get started, see the -<ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins";> -KTextEditor Plugin Tutorial on &kde; TechBase</ulink>. For even more, see the -<ulink url="http://techbase.kde.org/Development/Tutorials/Kate/KTextEditor_Plugins_Advanced";> -Advanced Tutorial, also on TechBase</ulink>.</para> - -<para>You can find the -<ulink url="http://api.kde.org/4.10-api/kdelibs-apidocs/interfaces/ktexteditor/html/";> -complete API documentation in the &kde; API Reference</ulink>.</para> +<!--FIXME: link to katepart ece doc--> </sect1> diff --git a/doc/kate/development.docbook b/doc/katepart/development.docbook similarity index 97% copy from doc/kate/development.docbook copy to doc/katepart/development.docbook index 0f23b0d..69b0090 100644 --- a/doc/kate/development.docbook +++ b/doc/katepart/development.docbook @@ -5,21 +5,18 @@ <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> </chapterinfo> -<title>Extending &kate;</title> +<title>Extending &katepart;</title> <sect1 id="dev-intro"> <title>Introduction</title> -<para>Like any advanced text editor, &kate; offers a variety of ways to extend -its functionality. You can <link linkend="dev-scripting">write simple scripts -to add functionality with JavaScript</link>, add enhanced functionality to the -editor component with <link linkend="dev-part">Editor Component Plugins</link>, -or add even more functionality to the editor itself with -<link linkend="dev-app">&kate; Application Plugins written in C++</link> or -<link linkend="dev-pate">&pate; Plugins written in Python</link>. Finally, once -you have extended &kate;, you are welcome to -<ulink url="http://kate-editor.org/join-us/";>join us</ulink> and share your -enhancements with the world!</para> +<para>Like any advanced text editor component, &katepart; offers a variety of +ways to extend its functionality. You can <link linkend="dev-scripting">write +simple scripts to add functionality with JavaScript</link> or add enhanced +functionality to the editor component with <link linkend="dev-part">Editor +Component Plugins</link>. Finally, once you have extended &katepart;, you are +welcome to <ulink url="http://kate-editor.org/join-us/";>join us</ulink> +and share your enhancements with the world!</para> </sect1> @@ -1843,36 +1840,4 @@ complete API documentation in the &kde; API Reference</ulink>.</para> </sect1> -<sect1 id="dev-app"> -<title>&kate; (C++) Application Plugins</title> - -<para><link linkend="kate-application-plugins">Kate Application Plugins</link> -extend the functionality of the &kate; editor itself in any way you can imagine, -using the same programming language &kate; is written in, C++.</para> - -<para>To get started, see the -<ulink url="http://kate-editor.org/2004/01/06/writing-a-kate-plugin/";>Writing a -&kate; Plugin tutorial on the &kate; website</ulink>. There is also -<ulink url="http://quickgit.kde.org/?p=kate.git&a=tree&f=addons%2Fkate%2Fhelloworld";> -a classic <quote>Hello, world!</quote> example plugin included with the &kate; -source code</ulink>.</para> - -</sect1> - -<sect1 id="dev-pate"> -<title>&pate; Python Plugins</title> - -<para><link linkend="pate">&pate; Plugins</link> also allow you to extend the -functionality of &kate; in any way you like, using the Python programming -language.</para> - -<para>To get started, see the -<ulink url="http://kate-editor.org/2012/07/01/python-plugin-developer-guide-part-1/";> -Python plugin developer guide on the &kate; website</ulink>.</para> - -<para>You can also access the API reference in the -<link linkend="pate-config">&pate; Configuration</link> screen.</para> - -</sect1> - </chapter>
