Warning, /office/kile/doc/scripting.docbook is written in an unsupported language. File is not indexed.

 <chapter id="id_scripting">
 <title>Scripting</title>
 
 <sect1 id="id_scripting_kile">
 <title>Scripting in &kile;</title>
 
 <para>&kile;'s scripting feature allows the execution of <ulink url="http://en.wikipedia.org/wiki/ECMAScript">ECMAScript</ulink> code, widely known as &javascript;. You will find a lot of tutorials, which provide information about objects (variables), functions and properties supported by &javascript;.</para>
 
 <para>Scripting support can be enabled in the configuration dialog of &kile;: <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
 <guimenuitem>Kile</guimenuitem><guilabel>Scripting</guilabel></menuchoice>.
 <screenshot>
         <screeninfo>Enable or disable scripting support</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-support.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Enable or disable scripting support</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </para>
 
 <para> If scripting is enabled, an additional scripting panel is visible in the sidebar, where scripts can be managed:
 <screenshot>
         <screeninfo>Scripting panel in the sidebar</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-panel.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting panel in the sidebar</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </para>
 
 <para>
 This widget contains six icons, which offer different tasks:
 <itemizedlist>
 <listitem><para>Run the selected script.</para></listitem>
 <listitem><para>Create a new script.</para></listitem>
 <listitem><para>Open the selected script in the editor.</para></listitem>
 <listitem><para>Configure a key sequence for the selected script.</para></listitem>
 <listitem><para>Remove an assigned key sequence.</para></listitem>
 <listitem><para>Refresh the list of available scripts, which are all found in <filename>$<envar>KDEDIR</envar>/share/apps/kile/scripts/</filename>.</para></listitem>
 </itemizedlist>
 </para>
 
 </sect1>
 
 <sect1 id="id_execute_script">
 <title>Executing a Script</title>
 
 <para>You can execute a script in three different ways:</para>
 
 <procedure>
 <step><para>Select the desired script and click on the <guilabel>Execute</guilabel> button on the left side of the script management widget.</para>
 <screenshot>
         <screeninfo>Scripting: execute button</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-execbutton.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting: execute button</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </step>
 
 <step><para>Use a keyboard shortcut.</para>
 <screenshot>
         <screeninfo>Scripting: keyboard shortcut</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-shortcut.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting: keyboard shortcut</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 <para>You can assign a keyboard shortcut to a script using the <guilabel>Configure</guilabel> button in the script management widget.</para>
 <screenshot>
         <screeninfo>Scripting: configure sequence dialog</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-configure.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting: configure sequence dialog</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </step>
 
 <step><para>Use an editor key sequence. The script will be executed, if you type the assigned key sequence in the editor.</para>
 <screenshot>
         <screeninfo>Scripting: editor key sequence</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-keysequence1.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting: editor key sequence</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 <para>This method can be extended to a rather sophisticated kind of code completion. Let us assume that you have a written a script, which simply inserts the &latex; command <userinput>\textbf{}</userinput> into the current document.</para>
 
 <programlisting>
 document.insertText("\\textbf{%C}");
 </programlisting>
 
 <para>If you now type the assigned key sequence <userinput>bfx</userinput> in your text document, this key sequence will be removed and the script will be executed. It will insert <userinput>\textbf{}</userinput> and the cursor is placed between the braces.</para>
 <screenshot>
         <screeninfo>Scripting: typing an editor key sequence</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="scripting-keysequence2.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Scripting: typing an editor key sequence</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 <para>What a comfortable and powerful method of code completion.</para>
 </step>
 </procedure>
 
 </sect1>
 
 <sect1 id="id_scripting_api">
 <title>API Reference</title>
 
 <para>The scripting API presented here is available in all scripts. Before the contents of a script is loaded, &kile; first adds several prototypes and functions to the scripting context. This convenience API contains prototypes like text cursors and text ranges and is located in the folder <filename>KILE_APP_DIR/script-plugins/</filename>.</para>
 
 <para>&kile; scripts differ slightly from <ulink url="http://kate-editor.org">&kate;</ulink> scripts, which use another design, as they also can be started from the command line. But all functions of the &kate; scripting API are also available in &kile;'s scripting API, so porting &javascript; code from &kate; to &kile; should be very easy. But as &kile; is a very rich featured &latex; editor, its own scripting API offers many more possibilities than &kate;'s one.</para>
 
 <para><emphasis>Remark: </emphasis>Description of API calls, which are also available in &kate; scripting, have been taken from &kate;'s documentation.</para>
 
 
 <sect2 id="id_scripting_api_global">
 <title>Global Functions</title>
 
 <para>This section lists global functions.</para>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void debug(<parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Prints <parameter>text</parameter> to <literal>stdout</literal> in the console. The printed text is colored to distinguish it from other debug output.
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect2>
 
 
 <sect2 id="id_scripting_api_cursor">
 <title>The Cursor Prototype</title>
 
 <para>As &kile; 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.</para>
 
 <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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Cursor(<parameter>Cursor <replaceable>other</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Copy constructor: Returns a copy of the cursor <parameter>other</parameter>.
 </para><para>
         Example: <function>var copy = new Cursor(other);</function>
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int Cursor.compareTo(<parameter>Cursor <replaceable>other</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Compares this cursor to the cursor <parameter>other</parameter>. Returns
 <itemizedlist>
 <listitem><para><literal>-1</literal>, if this cursor is located before the cursor <parameter>other</parameter>,</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 <parameter>other</parameter>.</para></listitem>
 </itemizedlist>
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>other</parameter> are equal, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String Cursor.toString();
 </synopsis></term>
 <listitem><para>
 Returns the cursor as a string of the form <literal>Cursor(line,column)</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect2>
 
 
 <sect2 id="id_scripting_api_range">
 <title>The Range Prototype</title>
 
 <para>As &kile; is a text editor, all the scripting API is based on cursors and ranges whenever possible. As 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.</para>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range();
 </synopsis></term>
 <listitem><para>
 Constructor: Calling <literal>new Range()</literal> returns a Range at <literal>(0,0) - (0,0)</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 from cursor <parameter>start</parameter> to cursor <parameter>end</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 (<literal>startLine</literal>, <literal>startColumn</literal>) to (<literal>endLine</literal>, <literal>endColumn</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range(<parameter>Range <replaceable>other</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Copy constructor: Returns a copy of Range <literal>other</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool Range.invalid();
 </synopsis></term>
 <listitem><para>
 Returns the Range from (-1,-1) to (-1,-1).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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 <parameter>other</parameter>, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool Range.containsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if <parameter>column</parameter> is in the half open interval <literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool Range.containsLine(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if <parameter>line</parameter> is in the half open interval <literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>other</parameter> share a common region, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool Range.overlapsLine(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if <parameter>line</parameter> is in the interval <literal>[start.line, end.line]</literal>, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool Range.overlapsColumn(<parameter>int <replaceable>column</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if <parameter>column</parameter> is in the interval <literal>[start.column, end.column]</literal>, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>other</parameter> are equal, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String Range.toString();
 </synopsis></term>
 <listitem><para>
 Returns the range as a string of the form <literal>Range(Cursor(line,column) - Cursor(line,column))</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect2>
 
 
 <sect2 id="id_scripting_api_view">
 <title>The View API</title>
 
 <para>Whenever a script is being executed, there is a global object (variable) <userinput>view</userinput> representing the current active editor view. All functions of <literal>view</literal> work with cursor positions or selected text. The following is a list of all available <userinput>view</userinput> functions.</para>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.backspace();
 </synopsis></term>
 <listitem><para>
 Programmatically performs the equivalent of pressing the backspace key.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Cursor view.cursorPosition();
 </synopsis></term>
 <listitem><para>
 Returns the current cursor position in the view.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>line</parameter>, <parameter>column</parameter> or to the given <parameter>cursor</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.cursorLeft();
 </synopsis></term>
 <listitem><para>
 Moves the cursor one position backward in the text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.cursorRight();
 </synopsis></term>
 <listitem><para>
 Moves the cursor one position forward in the text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.cursorUp();
 </synopsis></term>
 <listitem><para>
 Moves the cursor one line up in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.cursorDown();
 </synopsis></term>
 <listitem><para>
 Moves the cursor one line down in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int view.cursorLine();
 </synopsis></term>
 <listitem><para>
 Returns the line which the cursor is currently located at.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int view.cursorColumn();
 </synopsis></term>
 <listitem><para>
 Returns the column which the cursor is currently located at.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.setCursorLine(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Set the cursor line to the given <parameter>line</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.setCursorColumn(<parameter>int <replaceable>column</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Set the cursor column to the given <parameter>column</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Cursor view.virtualCursorPosition();
 </synopsis></term>
 <listitem><para>
 Get the current <emphasis>virtual</emphasis> cursor position. <emphasis>Virtual</emphasis> means the tabulator character (TAB) counts <emphasis>multiple</emphasis> characters, as configured by the user (e.g. one TAB is 8 spaces). The virtual cursor position provides access to the user visible values of the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range view.selectionRange();
 </synopsis></term>
 <listitem><para>
 Returns the selected text range. The returned range is invalid if there is no selected text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.setSelection(<parameter>Range <replaceable>range</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Set the selected text to the given <parameter>range</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectAll();
 </synopsis></term>
 <listitem><para>
 Selects the entire text in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.clearSelection();
 </synopsis></term>
 <listitem><para>
 Clears the text selection without removing the text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectLine();
 </synopsis></term>
 <listitem><para>
 Selects the text in the current line.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectLine(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Selects the text in the given <parameter>line</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectLines(<parameter>int <replaceable>from</replaceable></parameter>, <parameter>int <replaceable>to</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Selects the entire text from line <parameter>from</parameter> to line <parameter>to</parameter>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectWord();
 </synopsis></term>
 <listitem><para>
 Selects the current word. If no word is found at the current cursor position, nothing is done.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectLatexCommand();
 </synopsis></term>
 <listitem><para>
 Selects the current &latex; command. If no command is found at the current cursor position, nothing is done.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectEnvironment(<parameter>bool <replaceable>inside = false</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Selects the entire text of the current &latex; environment. If <parameter>inside</parameter> is <literal>false</literal>, the environment text including the surrounding &latex; tags <userinput>\begin{...}...\end{...}</userinput> will be selected, else without these tags. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectTexgroup(<parameter>bool <replaceable>inside = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Selects the text of the current &latex; group. If <parameter>inside</parameter> is <literal>true</literal>, only the texgroup without the surrounding braces will be selected. If no parameter is given, <parameter>inside</parameter> is set to <literal>true</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectMathgroup();
 </synopsis></term>
 <listitem><para>
 Selects the text of the current math group.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void view.selectParagraph(bool wholeLines = true);
 </synopsis></term>
 <listitem><para>
 Selects the entire text of the current &latex; paragraph. If <parameter>wholeLines</parameter> is <literal>true</literal>, the first and the last lines of the paragraph will be included in the selection entirely (including the end-of-line character); otherwise, the selection will only contain non-whitespace characters.
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect2>
 
 
 <sect2 id="id_scripting_api_document">
 <title>The Document API</title>
 
 <para>Whenever a script is being executed, there is a global object (variable) <userinput>document</userinput> representing the current active document. The following is a list of all available <userinput>document</userinput> functions.</para>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertText(<parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Inserts the <parameter>text</parameter> at the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertText(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
 void document.insertText(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Inserts the <parameter>text</parameter> at the given cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.replaceText(<parameter>Range <replaceable>range</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Replace the text of the given range with the specified text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int document.lines();
 </synopsis></term>
 <listitem><para>
 Returns the number of lines in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int document.length();
 </synopsis></term>
 <listitem><para>
 Returns the number of characters in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.documentRange();
 </synopsis></term>
 <listitem><para>
 Returns a range which encompasses the whole document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Cursor document.documentEnd();
 </synopsis></term>
 <listitem><para>
 Returns the current cursor position of the document's end.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <literal>\n</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.setText(<parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Sets the entire document text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.clear();
 </synopsis></term>
 <listitem><para>
 Removes the entire text in the document.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.line();
 </synopsis></term>
 <listitem><para>
 Returns the current text line as string.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int document.lineLength();
 </synopsis></term>
 <listitem><para>
 Returns the length of the current line.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int document.lineLength(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the <parameter>line</parameter>'s length.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.insertLine(<parameter>String <replaceable>s</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Inserts text in the current 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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.insertLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>s</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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.removeLine();
 </synopsis></term>
 <listitem><para>
 Removes the current text line. Returns <literal>true</literal> on success, or <literal>false</literal>, if the document is in read-only mode.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.replaceLine(<parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Replace the text of the current line with the specified text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.replaceLine(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Replace the text of the given line with the specified text.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.truncateLine();
 </synopsis></term>
 <listitem><para>
 Truncate the current 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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.word();
 </synopsis></term>
 <listitem><para>
 Returns the word at the current cursor position. If no word is found at this cursor position, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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. If no word is found at this cursor position, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.wordRange();
 </synopsis></term>
 <listitem><para>
 Returns the range of the word at the given cursor position. If no word is found, <literal>Range.invalid()</literal> is returned, which can be tested with <literal>Range.isValid()</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.latexCommand();
 </synopsis></term>
 <listitem><para>
 Returns the &latex; command at the current cursor position. If no command is found at this cursor position, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.latexCommandAt(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>int <replaceable>column</replaceable></parameter>);
 String document.latexCommandAt(<parameter>Cursor <replaceable>cursor</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the &latex; command at the given cursor position. If no command is found at this cursor position, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.latexCommandRange();
 </synopsis></term>
 <listitem><para>
 Returns the range of the &latex; command at the given cursor position. If no &latex; command is found, <literal>Range.invalid()</literal> is returned, which can be tested with <literal>Range.isValid()</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.firstChar(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the first character in the given <parameter>line</parameter> 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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.lastChar(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the last character in the given <parameter>line</parameter> that is not a whitespace. If the line is empty or only contains whitespace characters, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertBullet();
 </synopsis></term>
 <listitem><para>
         Insert a &kile; <emphasis>bullet</emphasis>. Remember that you can easily jump to the next or previous bullet. This will also highlight this bullet so that it will be deleted automatically, when you enter your first letter.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.nextBullet();
 </synopsis></term>
 <listitem><para>
 Jump to the next bullet in the text if there is one.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.previousBullet();
 </synopsis></term>
 <listitem><para>
 Jump to the previous bullet in the text if there is one.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.hasEnvironment();
 </synopsis></term>
 <listitem><para>
 Returns  <literal>true</literal> if a surrounding &latex; environment is found, else <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.environment(<parameter>bool <replaceable>inside = false</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the entire text of the surrounding &latex; environment. If <parameter>inside</parameter> is <literal>false</literal>, the environment text including the surrounding &latex; tags <userinput>\begin{...}...\end{...}</userinput> will be returned, else without these tags. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>. If no environment is found, the returned string is empty.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.environmentRange(<parameter>bool <replaceable>inside = false</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the range of the surrounding &latex; environment. If <parameter>inside</parameter> is <literal>false</literal>, the range including the surrounding &latex; tags <userinput>\begin{...}...\end{...}</userinput> will be returned, else without these tags. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>. If no environment is found, <literal>Range.invalid()</literal> is returned, which can be tested with <literal>Range.isValid()</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.environmentName();
 </synopsis></term>
 <listitem><para>
 Returns the name of the surrounding &latex; environment or an empty string.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.removeEnvironment(<parameter>bool <replaceable>inside = false</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Removes the text of the surrounding &latex; environment. If <parameter>inside</parameter> is <literal>false</literal>, the environment text including the surrounding &latex; tags <userinput>\begin{...}...\end{...}</userinput> will be removed, else without these tags. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.closeEnvironment();
 </synopsis></term>
 <listitem><para>
 Insert a closing environment tag, if an opened &latex; environment is found at the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.closeAllEnvironments();
 </synopsis></term>
 <listitem><para>
 Insert closing environment tags for all opened &latex; environments, which were found at the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.hasTexgroup();
 </synopsis></term>
 <listitem><para>
 Returns  <literal>true</literal> if a surrounding &latex; group is found at the current cursor position, else <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.texgroup(<parameter>bool <replaceable>inside = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the text of the surrounding &latex; group. If <parameter>inside</parameter> is <literal>false</literal>, the text of this &latex; group including the surrounding braces <userinput>{...}</userinput> will be returned, else without them. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>. The returned string is empty, if no surrounding &latex; group is found at the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.texgroupRange(<parameter>bool <replaceable>inside = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns the range of the surrounding &latex; group. If <parameter>inside</parameter> is <literal>false</literal>, the range including the surrounding braces <userinput>{...}</userinput> will be returned, else without them. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>. If no group is found, <literal>Range.invalid()</literal> is returned, which can be tested with <literal>Range.isValid()</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.removeTexgroup(<parameter>bool <replaceable>inside = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Removes the text of the surrounding &latex; group. If <parameter>inside</parameter> is <literal>false</literal>, the text of this &latex; group including the surrounding braces <userinput>{...}</userinput> will be removed, else without them. If no parameter is given, <parameter>inside</parameter> is set to <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.hasMathgroup();
 </synopsis></term>
 <listitem><para>
 Returns  <literal>true</literal> if a surrounding &latex; mathgroup is found at the current cursor position, else <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.mathgroup();
 </synopsis></term>
 <listitem><para>
 Returns the text of the surrounding &latex; mathgroup. The returned string is empty, if no surrounding &latex; mathgroup is found at the current cursor position.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.mathgroupRange();
 </synopsis></term>
 <listitem><para>
 Returns the range of the surrounding &latex; mathgroup. If there is no surrounding mathgroup, <literal>Range.invalid()</literal> is returned, which can be tested with <literal>Range.isValid()</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.removeMathgroup();
 </synopsis></term>
 <listitem><para>
 Removes the text of the surrounding &latex; mathgroup.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String document.paragraph();
 </synopsis></term>
 <listitem><para>
 Returns the text of the current &latex; paragraph.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Range document.paragraphRange();
 </synopsis></term>
 <listitem><para>
 Returns the range of the surrounding &latex; paragraph.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.removeParagraph();
 </synopsis></term>
 <listitem><para>
 Removes the text of the current &latex; paragraph.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>text</parameter> matches at the corresponding cursor position, otherwise <literal>false</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.startsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>pattern</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if the line starts with <parameter>pattern</parameter>, otherwise <literal>false</literal>. The argument <parameter>skipWhiteSpaces</parameter> controls whether leading whitespaces are ignored.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 bool document.endsWith(<parameter>int <replaceable>line</replaceable></parameter>, <parameter>String <replaceable>pattern</replaceable></parameter>, <parameter>bool <replaceable>skipWhiteSpaces = true</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Returns <literal>true</literal>, if the line ends with <parameter>pattern</parameter>, otherwise <literal>false</literal>. The argument <parameter>skipWhiteSpaces</parameter> controls whether trailing whitespaces are ignored.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>line</parameter>. If there are only whitespaces in the line, the return value is <literal>-1</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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 <parameter>line</parameter>. If there are only whitespaces in the line, the return value is <literal>-1</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoBeginEnv();
 </synopsis></term>
 <listitem><para>
 Go to the start of a surrounding &latex; environment.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoEndEnv();
 </synopsis></term>
 <listitem><para>
 Go to the end of a surrounding &latex; environment.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoBeginTexgroup();
 </synopsis></term>
 <listitem><para>
 Go to the start of a surrounding &latex; group.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoEndTexgroup();
 </synopsis></term>
 <listitem><para>
 Go to the end of a surrounding &latex; group.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoNextParagraph();
 </synopsis></term>
 <listitem><para>
 Go to the next &latex; paragraph.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoPrevParagraph();
 </synopsis></term>
 <listitem><para>
 Go to the previous &latex; paragraph.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoNextSectioning();
 </synopsis></term>
 <listitem><para>
 Go to the next &latex; section.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoPrevSectioning();
 </synopsis></term>
 <listitem><para>
 Go to the previous &latex; section.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.gotoLine(<parameter>int <replaceable>line</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
         Go to the given <literal>line</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertChapter();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\chapter</userinput> command (see also <literal>document.insertSection()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertSection();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\section</userinput> command. As with choosing the menu entry <menuchoice><guimenu>LaTeX</guimenu><guisubmenu>Sectioning</guisubmenu><guimenuitem>section</guimenuitem></menuchoice> a dialog will appear, where you can choose the title and an optional label for this sectioning command.
 <screenshot>
         <screeninfo>Dialog: insert chapter command</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="dialog-insertsection.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Dialog: insert chapter command</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertSubsection();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\subsection</userinput> command (see also <literal>document.insertSection()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertSubsubsection();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\subsubsection</userinput> command (see also <literal>document.insertSection()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertParagraph();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\paragraph</userinput> command (see also <literal>document.insertSection()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertSubparagraph();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\subparagraph</userinput> command (see also <literal>document.insertSection()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertLabel();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\label</userinput> command.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertReference();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\ref</userinput> command. As with choosing the menu entry <menuchoice><guimenu>&latex;</guimenu><guisubmenu>References</guisubmenu><guimenuitem>ref</guimenuitem></menuchoice> a dialog will appear, where you can choose from already defined labels, which are listed in a combobox.
 <screenshot>
         <screeninfo>Dialog: insert a reference command</screeninfo>
         <mediaobject>
         <imageobject>
         <imagedata fileref="dialog-insertreference.png" format="PNG" />
         </imageobject>
         <textobject>
                 <phrase>Dialog: insert a reference command</phrase>
         </textobject>
         </mediaobject>
 </screenshot>
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertPageref();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\pageref</userinput> command (see also <literal>document.insertReference()</literal>).
 </para></listitem>
 </varlistentry></variablelist>
 
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertCitation();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\cite</userinput> command.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertIndex();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\index</userinput> command.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertFootnote();
 </synopsis></term>
 <listitem><para>
 Insert a <userinput>\footnote</userinput> command.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.comment();
 </synopsis></term>
 <listitem><para>
 Inserts comment markers to make the selection or current line a comment.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.uncomment();
 </synopsis></term>
 <listitem><para>
 Removes comment markers from the selection or current line.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.uppercase();
 </synopsis></term>
 <listitem><para>
 Put the selected text or the letter after the cursor in uppercase.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.lowercase();
 </synopsis></term>
 <listitem><para>
 Put the selected text or the letter after the cursor in lowercase.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.capitalize();
 </synopsis></term>
 <listitem><para>
 Capitalize the selected text or the current word.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.joinLines();
 </synopsis></term>
 <listitem><para>
 Joins the lines of the current selection. Two succeeding text lines are always separated with a single space.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertIntelligentNewline();
 </synopsis></term>
 <listitem><para>
 Insert a smart newline (see <xref linkend="editing_smartnewline" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.insertIntelligentTabulator();
 </synopsis></term>
 <listitem><para>
 Insert a smart tabulator (see <xref linkend="editing_tabulator" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><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></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 StringList document.labelList();
 </synopsis></term>
 <listitem><para>
 Returns all defined labels as a <literal>StringList</literal>, which can be used in &javascript; as an array of strings.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 StringList document.bibitemList();
 </synopsis></term>
 <listitem><para>
 Returns all defined bibitems as a <literal>StringList</literal>, which can be used in &javascript; as an array of strings.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void document.refreshStructure();
 </synopsis></term>
 <listitem><para>
 Refresh the structure view (see <xref linkend="navigating" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect2>
 
 
 <sect2 id="id_scripting_api_kile">
 <title>The &kile; API</title>
 
 <para>The global object (variable) <userinput>kile</userinput> is used to handle top level interactions with the outside world, input message and dialog interfaces. These API calls are divided into subobjects to structure this part of the scripting API. Conceptually <userinput>kile</userinput> is a bit like <userinput>window</userinput> in a browser API.
 <itemizedlist>
 <listitem><para><literal>kile.alert</literal>: &nbsp; message boxes</para></listitem>
 <listitem><para><literal>kile.input</literal>: &nbsp; get user input</para></listitem>
 <listitem><para><literal>kile.wizard</literal>: &nbsp; call one of &kile;'s wizards</para></listitem>
 <listitem><para><literal>kile.script</literal>: &nbsp; get info about a running script</para></listitem>
 <listitem><para><literal>kile.file</literal>: &nbsp; file operations like read and write.</para></listitem>
 </itemizedlist>
 </para>
 
 
 <sect3 id="id_scripting_api_kile_alert">
 <title>Alert</title>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.alert.information(<parameter>String <replaceable>text</replaceable></parameter>, <parameter>String <replaceable>caption</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Display an <emphasis>Information</emphasis> dialog. <parameter>text</parameter> is the message string and <parameter>caption</parameter> the title of the message box. The default title is the script name.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.alert.sorry(<parameter>String <replaceable>text</replaceable></parameter>, <parameter>String <replaceable>caption</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Display a <emphasis>Sorry</emphasis> dialog. <parameter>text</parameter> is the message string and <parameter>caption</parameter> the title of the message box. The default title is the script name.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.alert.error(<parameter>String <replaceable>text</replaceable></parameter>, <parameter>String <replaceable>caption</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Display an <emphasis>Error</emphasis> dialog. <parameter>text</parameter> is the message string and <parameter>caption</parameter> the title of the message box. The default title is the script name.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.alert.question(<parameter>String <replaceable>text</replaceable></parameter>, <parameter>String <replaceable>caption</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Display a simple <emphasis>question</emphasis> dialog. <parameter>text</parameter> is the message string and <parameter>caption</parameter> the title of the message box. The default title is the script name. The returned string is either <literal>yes</literal> or <literal>no</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.alert.warning(<parameter>String <replaceable>text</replaceable></parameter>, <parameter>String <replaceable>caption</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Display a simple <emphasis>warning</emphasis> dialog. <parameter>text</parameter> is the message string and <parameter>caption</parameter> the title of the message box. The default title is the script name. The returned string is either <literal>continue</literal> or <literal>cancel</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 </sect3>
 
 
 <sect3 id="id_scripting_api_kile_input">
 <title>Input</title>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.input.getListboxItem(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>, <parameter>StringList <replaceable>list</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to let the user select an item from a list, which is shown as a listbox. <parameter>caption</parameter> is the text that is displayed in the title bar, <parameter>label</parameter> is the text that appears as the label for the list and <parameter>list</parameter> is the string list which is inserted into the list.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.input.getComboboxItem(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>, <parameter>StringList <replaceable>list</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to let the user select an item from a list, which is shown as a combobox. <parameter>caption</parameter> is the text that is displayed in the title bar, <parameter>label</parameter> is the text that appears as the label for the list and <parameter>list</parameter> is the string list which is inserted into the list.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.input.getText(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to get a string from the user. <parameter>caption</parameter> is the text that is displayed in the title bar and <parameter>label</parameter> the text that appears as a label for the line edit.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.input.getLatexCommand(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to get a &latex; command from the user. This means that only lower- and uppercase letters are allowed. <parameter>caption</parameter> is the text that is displayed in the title bar and <parameter>label</parameter> the text that appears as a label for the line edit.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int kile.input.getInteger(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>, <parameter>int <replaceable>min = INT_MIN</replaceable></parameter>, <parameter>int <replaceable>max = INT_MAX</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to get an integer from the user. <parameter>caption</parameter> is the text that is displayed in the title bar. <parameter>label</parameter> is the text that appears as the label for the spin box. <parameter>min</parameter> and <parameter>max</parameter> are the minimum and maximum allowable values the user may choose. Default values are <literal>INT_MIN</literal> and <literal>INT_MAX</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 int kile.input.getPosInteger(<parameter>String <replaceable>caption</replaceable></parameter>, <parameter>String <replaceable>label</replaceable></parameter>, <parameter>int <replaceable>min = 1</replaceable></parameter>, <parameter>int <replaceable>max = INT_MAX</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Function to get a positive integer from the user. <parameter>caption</parameter> is the text that is displayed in the title bar. <parameter>label</parameter> is the text that appears as the label for the spin box. <parameter>min</parameter> and <parameter>max</parameter> are the minimum and maximum allowable values the user may choose. Default values are <literal>1</literal> and <literal>INT_MAX</literal>.
 </para></listitem>
 </varlistentry></variablelist>
 </sect3>
 
 
 <sect3 id="id_scripting_api_kile_wizard">
 <title>Wizard</title>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.tabular();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Tabular wizard</emphasis>, which helps to write a tabular environment (see <xref linkend="wizard_array" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.array();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Array wizard</emphasis>, which helps to write an array environment (see <xref linkend="wizard_array" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.tabbing();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Tabbing wizard</emphasis>, which helps to write a tabbing environment (see <xref linkend="wizard_array" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.floatEnvironment();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Floats wizard</emphasis>, which helps to insert floating elements (see <xref linkend="wizard_float" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.mathEnvironment();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Math wizard</emphasis>, which helps to insert math environments (see <xref linkend="wizard_math" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 void kile.wizard.postscript();
 </synopsis></term>
 <listitem><para>
 Calls the <emphasis>Postscript Tools wizard</emphasis>, which may help to manipulate or rearrange Postscript documents (see <xref linkend="wizard_postscript" role="select: title pageabbrv"/>).
 </para></listitem>
 </varlistentry></variablelist>
 </sect3>
 
 
 <sect3 id="id_scripting_api_kile_script">
 <title>Script</title>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.script.name();
 </synopsis></term>
 <listitem><para>
 Returns the basename of a running script (without path and extension).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.script.caption();
 </synopsis></term>
 <listitem><para>
 Returns a string, which can be used as a caption of alert boxes. It looks like <userinput>Script: scriptname.js</userinput>.
 </para></listitem>
 </varlistentry></variablelist>
 </sect3>
 
 
 <sect3 id="id_scripting_api_kile_file">
 <title>File</title>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Object kile.file.read(<parameter>String <replaceable>filename</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Read the contents of a text file. It is used like
 </para><para>
 Example: <function>var res = kile.file.read("path/to/file.txt");</function>
 </para><para>
 The return value <userinput>res</userinput> is an object (better: a map) with three properties:
 </para><para>
 <itemizedlist>
 <listitem><para><guilabel>status:</guilabel>&nbsp; Gives the status code of the operation, which can be 0 (no error), 1 (access failed) or 2 (access denied). So, if no error occurred, the value of <userinput>res.status</userinput> or <userinput>res["status"]</userinput> will be 0.</para></listitem>
 <listitem><para><guilabel>result:</guilabel>&nbsp; Contains the text of the given file.</para></listitem>
 <listitem><para><guilabel>message:</guilabel>&nbsp; Contains an error message, if an error occurred.</para></listitem>
 </itemizedlist>
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Object kile.file.read();
 </synopsis></term>
 <listitem><para>
 The same as <literal>read(filename)</literal>, but no filename is given. A dialog will appear to select the file to read.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Object kile.file.write(<parameter>String <replaceable>filename</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Write the given text into a file. It is used like
 </para><para>
 Example: <function>var res = kile.file.write("path/to/file.txt","Some text...");</function>
 </para><para>
 The return value <userinput>res</userinput> is an object (better: a map) with two properties: <literal>status</literal> and <literal>message</literal> (see <literal>read()</literal> for more information).
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 Object kile.file.write(<parameter>String <replaceable>text</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 The same as <literal>write(filename,text)</literal>, but no filename is given. A dialog will appear to choose a filename.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.file.getOpenFileName(<parameter>String <replaceable>startDir</replaceable></parameter>, <parameter>String <replaceable>filter</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Creates a modal file dialog and return the selected filename or an empty string if none is chosen. Note that with this method the user must select an existing filename.
 </para><para>
 Parameters:
 </para><para>
 <itemizedlist>
 <listitem><para><guilabel>startDir:</guilabel>&nbsp; Starting directory of the open dialog.</para></listitem>
 <listitem><para><guilabel>filter:</guilabel>&nbsp; A shell glob or a mime-type-filter that specifies which files to display. Refer to the KFileDialog documentation for more information on this parameter.</para></listitem>
 </itemizedlist>
 </para><para>
 Both parameters are optional. If you omit <literal>filter</literal>, all files will be displayed. If additionally <literal>startDir</literal> is omitted, the dialog will take the current document directory as starting point.
 </para></listitem>
 </varlistentry></variablelist>
 
 <variablelist><varlistentry>
 <term><synopsis>
 String kile.file.getSaveFileName(<parameter>String <replaceable>startDir</replaceable></parameter>, <parameter>String <replaceable>filter</replaceable></parameter>);
 </synopsis></term>
 <listitem><para>
 Creates a modal file dialog and returns the selected filename or an empty string if none is chosen. Note that with this method the user need not select an existing filename.
 See <literal>getOpenFileName()</literal> for an explanation of the parameters.
 </para></listitem>
 </varlistentry></variablelist>
 
 </sect3>
 
 </sect2>
 
 </sect1>
 
 
 <sect1 id="id_scripting_examples">
 <title>Examples</title>
 
 <para>Some examples may help you to understand how to use the scripting API. These examples and some more are found in the scripting directory of &kile;: <filename>KILE_APP_DIR/scripts/</filename>. Each script contains a short description.</para>
 
 <sect2 id="id_scripting_example1">
 <title>Example 1: replace environment name</title>
 
 <para>Replace a surrounding &latex; environment with another, where the relative cursor position will not be changed. <userinput>\begin{abc}...\end{abc}</userinput> for example can be changed to <userinput>\begin{xyz}...\end{xyz}</userinput>.</para>
 
 <programlisting>
 var range = document.environmentRange(false);
 if ( range.isValid() ) {
         var envname = kile.input.getLatexCommand("Enter Environment","New environment name:");
         if ( envname != '' ) {
                 replaceEnvCommand(envname,range);
         }
 }
 else {
         kile.alert.sorry("No surrounding LaTeX environment found.");
 }
 
 function replaceEnvCommand(newEnv,r)
 {
         var c = view.cursorPosition();
 
         var envname = document.environmentName();
 
         if ( envname != "" ) {
                 var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                 var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);
 
                 document.editBegin();
                 document.replaceText(endRange,"\\end{"+newEnv+"}");
                 document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                 document.editEnd();
         }
 }
 </programlisting>
 </sect2>
 
 <sect2 id="id_scripting_example2">
 <title>Example 2: replace a &latex; font command</title>
 
 <para>Replace a surrounding &latex; font command with another font command, when the cursor is placed inside the texgroup. The relative cursor position will not be changed. <userinput>\textbf{abc}</userinput> for example can be changed to <userinput>\textit{abc}</userinput>.</para>
 
 <programlisting>
 var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                              "\\textsc","\\textrm","\\textsf","\\emph");
 
 var range = document.texgroupRange(false);
 if ( range.isValid() ) {
         replaceFontCommand(range);
 }
 else {
         kile.alert.sorry("No surrounding TeX group found.");
 }
 
 function replaceFontCommand(r)
 {
         var c = view.cursorPosition();
 
         document.editBegin();
         view.setCursorPosition(r.start);
         var cmd = document.latexCommand();
         var index = fontCommands.indexOf(cmd);
         if ( index >= 0 ) {
                 var cmdRange = document.latexCommandRange();
                 if ( cmdRange.isValid() ) {
                         var newcommand = kile.input.getListboxItem("Choose",
                                                     "Choose font command:",buildCmdList(cmd));
                         if ( newcommand != "" ) {
                                 document.replaceText(cmdRange,newcommand);
                                 c.column = c.column - (cmd.length - newcommand.length);
                         }
                 }
 /               view.setCursorPosition(c);
         }
         else {
                 kile.alert.sorry("No surrounding font command found.");
         }
         document.editEnd();
 }
 
 function buildCmdList(current)
 {
         var result = new Array();
         for ( i=0; i&lt;fontCommands.length; ++i ) {
                 if ( fontCommands[i] != current ) {
                         result.push(fontCommands[i]);
                 }
         }
         return result;
 }
 </programlisting>
 
 </sect2>
 
 <sect2 id="id_scripting_example3">
 <title>Example 3: surround selected text</title>
 
 <para>Surround selected text with a TeX command, where the relative cursor position will not be changed. <userinput>abc</userinput> for example can be changed to <userinput>\texcommand{abc}</userinput>.</para>
 
 <programlisting>
 var range = view.selectionRange();
 
 if ( range.isValid() ) {
         var cmd = kile.input.getLatexCommand("Choose","Choose surrounding LaTeX command:");
         if ( cmd != "" ) {
                 surroundTexCommand("\\"+cmd,range);
         }
 }
 else {
         kile.alert.sorry("No selection found.");
 }
 
 function surroundTexCommand(cmd,r)
 {
         var c = view.cursorPosition();
 
         document.editBegin();
         view.clearSelection();
         document.insertText(r.end,"}");
         document.insertText(r.start,cmd+"{");
 
         c.column = c.column + cmd.length + 2;
         view.setCursorPosition(c);
         document.editEnd();
 }
 </programlisting>
 </sect2>
 
 </sect1>
 
 </chapter>