diff options
Diffstat (limited to 'doc/kate/advanced.docbook')
| -rw-r--r-- | doc/kate/advanced.docbook | 1159 |
1 files changed, 1159 insertions, 0 deletions
diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook new file mode 100644 index 000000000..e0d552c80 --- /dev/null +++ b/doc/kate/advanced.docbook @@ -0,0 +1,1159 @@ +<chapter id="advanced-editing-tools"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Advanced Editing Tools</title> + +<sect1 id="advanced-editing-tools-comment"> + +<title>Comment/Uncomment</title> + +<para>The Comment and Uncomment commands, available from the +<guimenu>Tools</guimenu> menu allow you to add or remove comment +markers to the selection, or to the current line if no text is selected, +if comments are supported by the format of the file you are +editing.</para> + +<para>The rules for how commenting is done are defined in the syntax +definitions, so if syntax highlighting is not used, commenting/uncommenting +is not possible.</para> + +<para>Some formats define single line comment markers, some multiline +markers and some both. If multiline markers are not available, +commenting out a selection that does not fully include its last line +is not possible.</para> + +<para>If a single line marker is available, commenting single lines is +preferred where applicable, as this helps to avoid problems with +nested comments.</para> + +<para>When removing comment markers, no uncommented text should be +selected. When removing multiline comment markers from a selection, +any whitespace outside the comment markers is ignored.</para> + +<para><indexterm><primary>comment</primary></indexterm> +To place comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut sequence, default is +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para> + +<para><indexterm><primary>uncomment</primary></indexterm> +To remove comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut, default is <keycombo +action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para> + +</sect1> + +<sect1 id="advanced-editing-tools-commandline"> +<title>The Editor Component Command Line</title> + +<para>Kate's editor component has an internal command line, allowing you to +perform various actions from a minimal GUI. The command line is a text entry +in the bottom of the editor area, to show it select +<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice> +or use the keyboard shortcut (default is +<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides +a set of commands as documented below, and additional commands can be provided +by plugins.</para> + +<para>To execute a command, type the command and then press the enter key. The +command line will indicate whether it succeeded and possibly display a message. If +you entered the command line by pressing <keycap>F7</keycap> it will +automatically hide after a few seconds. To clear the message and enter a new +command, press <keycap>F7</keycap> again.</para> + +<para>The command line has a built-in help system, you can type the command +<command>help</command> to get started. To see a list of all available commands +type <command>help list</command>, to view help for a specific command, do +<command>help <replaceable>command</replaceable></command>.</para> + +<para>The command line has a built-in history too, so you can reuse commands already +typed. To navigate the history, use the <keycap>Up</keycap> and +<keycap>Down</keycap> keys. When showing historical commands, the argument part +of the command will be selected, allowing you to easily overwrite the +arguments.</para> + +<sect2 id="advanced-editing-tools-commandline-commands"> +<title>Standard Command Line Commands</title> + +<variablelist> +<title>Argument types</title> + +<varlistentry> +<term>BOOLEAN</term> +<listitem><para>This is used with commands that turn things on or off. +Legal values are <userinput>on</userinput>, <userinput>off</userinput>, +<userinput>true</userinput>, <userinput>false</userinput>, +<userinput>1</userinput>, <userinput>0</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term>INTEGER</term> +<listitem><para>An integer number</para></listitem> +</varlistentry> + +<varlistentry> +<term>STRING</term> +<listitem><para>A string</para></listitem> +</varlistentry> + +</variablelist> + +<sect3 id="advanced-editing-tools-commandline-commands-configure"> +<title>Commands for Configuring the Editor</title> + +<para>These commands are provided by the editor component, and allows you to +configure the active document and view only. This is handy if you want to use +a setting different from the default settings, for example for indentation. +</para> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the tab width to the number <userinput>width</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the indentation width to the number +<userinput>width</userinput>. Used only if you are indenting with +spaces.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the line width for hard wrapping to +<userinput>width</userinput>. This is used if you are having your text wrapped +automatically.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN enable</arg> +</cmdsynopsis></term> +<listitem><para>Sets the visibility of the icon border.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the folding markers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the line numbers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, tabs are replaced with spaces as you type. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, trailing whitespace are removed whenever the cursor +leaves a line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, TAB characters and trailing whitespace will be +visualized by a small dot.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, the editor will indent with +<option>indent-width</option> spaces for each indentation level, rather than +with one TAB character.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, kate will use a mix of TAB and spaces for +indentation. Each indentation level will be <option>indent-width</option> wide, +and more indentation levels will be optimized to use as many TAB characters as +possible.</para> +<para>When executed, this command will additionally set space indentation enabled, +and if the indent width is unspecified it will be set to half of the +<option>tab-width</option> for the document at the time of execution.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN +enable</arg></cmdsynopsis></term> +<listitem><para>Enables dynamic word wrap according to +<userinput>enable</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable +</arg></cmdsynopsis></term> +<listitem><para>When enabled, tabs will be replaced with whitespaces whenever + the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>When enabled, trailing space will be removed from each line +whenever the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-mode</command><arg>name</arg></cmdsynopsis></term> +<listitem><para>Sets the autoindentation mode to <userinput>name</userinput>. +If <userinput>name</userinput> is not known, the mode is set to 'none'. Valid +modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-highlight</command><arg>highlight</arg></cmdsynopsis></term> +<listitem><para>Sets the syntax highlighting system for the document. The +argument must be a valid highlight name, as seen in the +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Highlighting</guisubmenu></menuchoice> +menu. This command provides an autocompletion list for its +argument.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-edit"> +<title>Commands for editing</title> + +<para>These commands modify the current document.</para> + +<variablelist> +<varlistentry> +<term><cmdsynopsis><command>indent</command></cmdsynopsis></term> +<listitem><para>Indents the selected lines or the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term> +<listitem><para>Unindents the selected lines or current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term> +<listitem><para>Cleans up the indentation of the selected lines or current line +according to the indentation settings in the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>comment</command></cmdsynopsis></term> +<listitem><para>Inserts comment markers to make the selection or selected lines +or current line a comment according to the text format as defined by the syntax +highlight definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term> +<listitem><para>Removes comment markers from the selection or selected lines +or current line according to the text format as defined by the syntax highlight +definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term> +<listitem><para>Deletes the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace</command><arg>pattern</arg><arg>replacement</arg></cmdsynopsis></term> +<listitem><para>Replaces text matching <userinput>pattern</userinput> with +<userinput>replacement</userinput>. If you want to include whitespace in the +<userinput>pattern</userinput>, you must quote both the <userinput>pattern</userinput> +and <userinput>replacement</userinput> with single or double quotes. If the +arguments are unquoted, the first word is used as <userinput>pattern</userinput> +and the rest for <userinput>replacement</userinput>. If +<userinput>replacement</userinput> is empty, each occurrence of +<userinput>pattern</userinput> is removed.</para> +<para>You can set flags to configure the search by adding a colon, followed +by one or more letters each representing a configuration, giving the form +<userinput>replace:options pattern replacement</userinput>. Available options +are: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search. If set, you may use +<userinput>\N</userinput> where N is a number to represent captures in the +replacement string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>p</userinput></term> +<listitem><para>Prompt for permission to replace the next occurence.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term> +<listitem><para>Inserts a date/time string as defined by the specified +<userinput>format</userinput>, or the format <quote>yyyy-MM-dd hh:mm:ss</quote> +if none is specified. The following translations are done when interpreting +<userinput>format</userinput>: + +<informaltable> +<tgroup cols="2"> +<tbody> +<row><entry><literal>d</literal></entry><entry>The day as number without a leading zero (1-31).</entry></row> +<row><entry><literal>dd</literal></entry><entry>The day as number with a leading zero (01-31).</entry></row> +<row><entry><literal>ddd</literal></entry><entry>The abbreviated localized day name (e.g. 'Mon'..'Sun').</entry></row> +<row><entry><literal>dddd</literal></entry><entry>The long localized day name (e.g. 'Monday'..'Sunday').</entry></row> +<row><entry><literal>M</literal></entry><entry>The month as number without a leading zero (1-12).</entry></row> +<row><entry><literal>MM</literal></entry><entry>The month as number with a leading zero (01-12).</entry></row> +<row><entry><literal>MMM</literal></entry><entry>The abbreviated localized month name (e.g. 'Jan'..'Dec').</entry></row> +<row><entry><literal>yy</literal></entry><entry>The year as two digit number +(00-99).</entry></row> +<row><entry><literal>yyyy</literal></entry><entry>The year as four digit number (1752-8000).</entry></row> +<row><entry><literal>h</literal></entry><entry>The hour without a leading zero (0..23 or 1..12 if AM/PM display).</entry></row> +<row><entry><literal>hh</literal></entry><entry>The hour with a leading zero (00..23 or 01..12 if AM/PM display).</entry></row> +<row><entry><literal>m</literal></entry><entry>The minute without a leading zero (0..59).</entry></row> +<row><entry><literal>mm</literal></entry><entry>The minute with a leading zero (00..59).</entry></row> +<row><entry><literal>s</literal></entry><entry>The second without a leading zero (0..59).</entry></row> +<row><entry><literal>ss</literal></entry><entry>The second with a leading zero (00..59).</entry></row> +<row><entry><literal>z</literal></entry><entry>The milliseconds without leading zeroes (0..999).</entry></row> +<row><entry><literal>zzz</literal></entry><entry>The milliseconds with leading zeroes (000..999).</entry></row> +<row><entry><literal>AP</literal></entry><entry>Use AM/PM display. AP will be replaced by either "AM" or "PM".</entry></row> +<row><entry><literal>ap</literal></entry><entry>Use am/pm display. ap will be replaced by either "am" or "pm".</entry></row> + +</tbody> +</tgroup> +</informaltable> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>char</command><arg>identifier</arg></cmdsynopsis></term> +<listitem> +<para>This command allows you to insert literal characters by their +numerical identifier, in decimal, octal or hexadecimal form. +To use it launch the Editing Command dialog and type <userinput>char: +[number]</userinput> in the entry box, then hit +<guibutton>OK</guibutton>.</para> + +<example> +<title><command>char</command> examples</title> + +<para>Input: <userinput>char:234</userinput></para> +<para>Output: <computeroutput>ê</computeroutput></para> +<para>Input: <userinput>char:0x1234</userinput></para> +<para>Output: <computeroutput>ሴ</computeroutput></para> +</example> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<indexterm><primary>replace, sed style</primary> +<secondary>search, sed style</secondary></indexterm> +<command>s///[ig]</command> and <command>%s///[ig]</command></term> + +<listitem> +<para>This command does a sed-like search/replace operation on the +current line, or on the whole file (<command>%s///</command>).</para> + +<para>In short, &kate; searches for text matching the +<emphasis>search pattern</emphasis> (the regular expression between +the first and the second slash), and when a match is found the +matching part of the text is replaced with the expression between the +middle and last slash. Parenthesis in the search pattern +create <emphasis>back references</emphasis>, that is the command +remembers which part of the text matched in the parenthesis. These +strings can be reused in the replace pattern, referred to as +<userinput>\1</userinput> for the first set of parenthesis, +<userinput>\2</userinput> for the second and so on.</para> + +<para>To search for a literal <literal>(</literal> or +<literal>)</literal>, you need to escape it using +a backslash character: <userinput>\(, \)</userinput></para> + +<para>If you put an <userinput>i</userinput> at the end of the +expression, the matching will be case insensitive. If you put a +<userinput>g</userinput> at the end, all occurrences of the pattern will be +replaced, otherwise only the first occurrence is replaced.</para> + +<example> + +<title>Replacing text in the current line</title> + +<para>Your friendly compiler just stopped, telling you that the class +<classname>myClass</classname> mentioned in line 3902 in your source file +is not defined.</para> + +<para>"Buckle!" you think, it is of course +<classname>MyClass</classname>. You go to line 3902, and instead of trying +to find the word in the text, you launch the Editing Command Dialog, +enter <userinput>s/myclass/MyClass/i</userinput>, hit the +<guibutton>OK</guibutton> button, save the file and compile +successfully without the error.</para> + +</example> + +<example> +<title>Replacing text in the whole file</title> + +<para>Imagine that you have a file, in which you mention a <quote>Miss +Jensen</quote> several times, when someone comes in and tells you that +she just got married to <quote>Mr. Jones</quote>. You want, of course, +to replace each and every occurrence of <quote>Miss Jensen</quote> +with <quote>Ms Jones</quote>.</para> + +<para>Enter the command line and issue the command +<userinput>%s/Miss Jensen/Ms. Jones/</userinput> and hit enter, you +are done.</para> + +</example> + +</listitem> + +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-navigation"> +<title>Commands for navigation</title> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>goto</command><arg>INT line</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the specified line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>find</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the first occurrence of +<userinput>pattern</userinput> according to the configuration. Following +occurrences can be found using +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice> +(the default shortcut is <keycap>F3</keycap>).</para> +<para>The find command can be configured by appending a colon followed by one or +more options, the form is +<userinput>find:options pattern</userinput>. The +following options are supported: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +</listitem> + +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command provides <quote>incremental (as-you-type)</quote> searching. You +can configure the behavior of the search by appending a colon +followed by one or more options, like this: +<userinput>ifind:options pattern</userinput>. Allowed options are: + +<variablelist> +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +</variablelist> +</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +<sect1 id="advanced-editing-tools-code-folding"> +<title>Using Code Folding</title> + +<para>Code folding allows you to hide parts of a document in the editor, making +it easier to overview large documents. In &kate; the foldable regions are +calculated using rules defined in the syntax highlight definitions and +therefore it is only available in some file formats - typically program source code, +XML markup and similar. Most highlight definition files supporting code folding +also let you manually define foldable regions, typically using the +<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para> + +<para>To use the code folding feature, activate the folding markers using +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Folding +Markers</guimenuitem></menuchoice> menu item if they are not already visible. +The Folding Markers Pane in the left side of the screen displays a graphical +view of the foldable regions, with +/- signs to indicate the possible operation +on a given region. A - means that the region is expanded; clicking on the - will +collapse the region and a + will be displayed instead.</para> + +<para>Four commands are provided to manipulate the state of folding regions, +see the <link linkend="view-code-folding">menu documentation</link> for details. +</para> + +<para>If you do not want to use the code folding feature, you can disable it +completely using the <guilabel>Show folding markers (if available)</guilabel> option in the +<link linkend="appearance-code-folding">Editor Appearance</link> configuration page</para> + +</sect1> + +<sect1 id="advanced-editing-tools-scripting"> + +<title>Scripting the editor with JS</title> + +<sect2 id="advanced-editing-tools-scripting-introduction"> + +<title>Introduction</title> + +<para>Starting with version 2.5, the &kate; editor component supports +scripting with ECMA script, also known as JavaScript.</para> + +<para>Scripts can be used through <link +linkend="advanced-editing-tools-commandline">the built-in command line</link> +only. The requirements are that the scripts are placed in a folder where &kate; +can find them, along with an optional .desktop file that defines the related +properties. The valid folders are named <filename>katepart/scripts</filename> +in the &tde; data folders. You can find the data folders by running the command +<command>tde-config <option>--path</option> <parameter>data</parameter></command>. +You will usually have at least a system and a personal data folder. Of course +scripts in the system data folder are available to all users on the system, +while those in the personal folder are available to you only.</para> + +</sect2> + +<sect2 id="advanced-editing-tools-scripting-reference"> + +<title>The Kate JavaScript API</title> + +<para>Here is the complete set of functions and properties available +in the <type>document</type> and <type>view</type> objects. +In addition, you can use all the standard objects such as +<type>Math</type>, <type>String</type> <type>Regex</type> and so forth.</para> + +<para>When a script is run, the <classname>document</classname> object is the +current document, and the <classname>view</classname> object is the current +view.</para> + +<note><para>Types are not used in JavaScript. In this list, they are +there solely to indicate what sort of arguments the functions expect.</para></note> + +<variablelist id="advanced-editing-tools-scripting-global"> +<title>Global Functions</title> +<varlistentry> +<term><function>debug(<parameter><replaceable>string s</replaceable></parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>parameters</title> +<listitem><para><parameter>s</parameter> the string to output.</para> +</listitem> +</itemizedlist> +<para>Outputs the string to <acronym>STDERR</acronym> using +<function>kdDebug()</function>. A dedicated output area is used for the output, +which will be prefixed by "<emphasis>Kate (KJS Scripts):</emphasis>" +</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist id="advanced-editing-tools-scripting-document"> +<title>The <classname>document</classname> API</title> + +<varlistentry> +<term><function>document.attribute(<parameter><replaceable>uint line</replaceable></parameter>, +<parameter><replaceable>uint column</replaceable></parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line of the position for which +to find the attribute.</para></listitem> +<listitem><para><parameter>column</parameter> the column of the position for +which to find the attribute.</para></listitem> +</itemizedlist> +<para>Returns the numeric ID of the attribute for the document position +[<parameter>line</parameter>, <parameter>column</parameter>]. The attribute +represents the visual appearance or style of the text, and is also used to +calculate the syntax highlight for a specific part of the text in mixed formats +like HTML or PHP.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canBreakAt(<parameter>char c</parameter>, +<parameter>attribute attrib</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>c</parameter> the character to test.</para></listitem> +<listitem><para><parameter>attrib</parameter> the attribute at the position +of <parameter>c</parameter>.</para></listitem> +</itemizedlist> +<para>Returns whether it is allowed to break the line at the character +<parameter>c</parameter> with attribute <parameter>attribute</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canComment(<parameter>attribute start_attrib</parameter>, +<parameter>attribute end_attrib</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>start_attrib</parameter> the attribute at the +start of the range to turn into a comment.</para></listitem> +<listitem><para><parameter>end_attrib</parameter> the attribute at end of +the range to turn into a comment.</para></listitem> +</itemizedlist> +<para>Returns whether <parameter>start_attribute</parameter> and +<parameter>end_attribute</parameter> belongs to the same +syntax highlight system. If they do, it is possible to comment the block. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.clear() function</function></term> +<listitem><para>Clears the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentStart(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentStart string.</para></listitem> +</itemizedlist> +<para>Returns the string required to start a multiline comment for a text with +attribute <parameter>attrib</parameter>, or an empty string if multiline comments are not supported for that +text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentMarker(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentMarker string.</para></listitem> +</itemizedlist> +<para>Returns the string used to mark the rest of the line as a comment for a +text with attribute <parameter>attrib</parameter> or an empty string if single +line comments are not supported for that text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentEnd(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentEnd string.</para></listitem> +</itemizedlist> +<para>Returns the string required to end a multiline comment for a text with +attribute <parameter>attrib</parameter>, or an empty string if multiline +comments are not supported for that text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editBegin() function</function></term> +<listitem> +<para>Starts an editing group. All actions done until the call to editEnd() will +be grouped as a single undo action.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editEnd() function</function></term> +<listitem> +<para>Ends an editing group.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.highlightMode property, read only</function></term> +<listitem> +<para>The name of the document's highlight mode, such as JavaScript or C++. +If no syntax highlight mode is set for the document, the value is <emphasis>none</emphasis>. +Notice that you need to use the English name in cases where it differs from the +translated one.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentMode property, read only</function></term> +<listitem> +<para>The name of the document indent mode, such as +<literal>normal</literal> or <literal>cstyle</literal>. +If no indent mode is set, the value is <emphasis>none</emphasis>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentWidth property, read only</function></term> +<listitem> +<para>The indentation width set for the document. This is used if space +indenting is enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertLine(<parameter>uint line</parameter>, +<parameter>string text</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the document line number.</para> +</listitem> +<listitem><para><parameter>text</parameter> the text to insert.</para></listitem> +</itemizedlist> +<para>Inserts a new line with the text <parameter>text</parameter> at the +line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertText(<parameter>uint line</parameter>, +<parameter>uint column</parameter>, <parameter>string text</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +<listitem><para><parameter>column</parameter> the column number.</para></listitem> +<listitem><para><parameter>text</parameter> the text to insert.</para></listitem> +</itemizedlist> +<para>Inserts the text <parameter>text</parameter> in line +<parameter>line</parameter> at column <parameter>column</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.length() function</term> +<listitem> +<para>Returns the document's size in bytes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.lines() function</function></term> +<listitem> +<para>Returns the number of lines in the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.mixedIndent property, read only</term> +<listitem> +<para>A boolean telling whether the mixed-indent setting is enabled for the +document. If so, indentation is optimized to contain a mix of tab characters and +spaces like in the Emacs editor.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.removeLine(<parameter>uint line</parameter>) function</term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +</itemizedlist> +<para>Removes the document line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.removeText(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Removes the text range from line <parameter>startLine</parameter> and +column <parameter>startColumn</parameter> to line +<parameter>endLine</parameter> and column <parameter>endColumn</parameter>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.setText(<parameter>string text</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>text</parameter> the new document text.</para></listitem> +</itemizedlist> +<para>Sets the entire document content to <parameter>text</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.spaceIndent property, read only</function></term> +<listitem> +<para>A boolean telling whether space-indent is enabled for the document. +If so, the document is indented with indentWidth spaces per level, otherwise +indentation is one tab character per level.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textFull() function</function></term> +<listitem> +<para>Returns the full document text. If the text spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textLine(<parameter>uint line</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +</itemizedlist> +<para>Returns the text at line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textRange(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Returns the specified text range. If the range spans over multiple lines +the linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +</variablelist><!--/ document API --> + +<variablelist id="advanced-editing-tools-scripting-view"> +<title>The <classname>view</classname> API</title> + +<varlistentry> +<term><function>view.clearSelection() function</function></term> +<listitem> +<para>Deselects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumn() function</function></term> +<listitem> +<para>Returns the current cursor column (TAB characters are expanded).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumnReal() function</function></term> +<listitem> +<para>Returns the current real cursor column (a TAB character counts as one).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorLine() function</function></term> +<listitem> +<para>Returns the current cursor line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.hasSelection() function</function></term> +<listitem> +<para>Returns <constant>true</constant> if some text in the view has been selected, +otherwise <constant>false</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.removeSelectedText() function</function></term> +<listitem> +<para>Removes the selected text, if the view has a selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectAll() function</function></term> +<listitem> +<para>Selects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selection() function</function></term> +<listitem> +<para>Returns the selected text. If the selection spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndColumn property, read only</function></term> +<listitem> +<para>Returns the ending column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndLine property, read only</function></term> +<listitem> +<para>Returns the ending line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartColumn property, read only</function></term> +<listitem> +<para>Returns the starting column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartLine property, read only</function></term> +<listitem> +<para>Returns the starting line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPosition(<parameter>uint line</parameter>, +<parameter>uint column</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem> +<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position in the view to (<parameter>line</parameter>, +<parameter>column</parameter>). TAB characters are expanded and +the cursor position is made visible. Both <parameter>line</parameter> +and <parameter>column</parameter> are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPositionReal(<parameter>uint line</parameter>, +<parameter>uint column</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem> +<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position to (<parameter>line</parameter>, +<parameter>column</parameter>). This sets the string position, that is a TAB +character counts for 1, and the cursor position is made visible. Both <parameter>line</parameter> +and <parameter>column</parameter> are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setSelection(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Sets a selection from line <parameter>startLine</parameter> and column +<parameter>startColumn</parameter> to line <parameter>endLine</parameter> +and column <parameter>endColumn</parameter>.</para> +</listitem> +</varlistentry> + +</variablelist> + +<example id="advanced-editing-tools-scripting-example"> + +<title>A sample script</title> +<para>As an example we will create a small script that transforms the selected +text to upper case. We first need to check whether a selection exists: if so we +get the text, change the case and then replace the original text with the new one. +An implementation would look something like this:</para> + +<programlisting> +if (view.hasSelection()) +{ + // uppercase selection + column = view.selectionStartColumn; + line = view.selectionStartLine; + + selection = view.selection().toUpperCase(); + + document.editBegin(); + view.removeSelectedText(); + document.insertText(line, column, selection); + document.editEnd(); +} +</programlisting> + +<para>To group this actions together so that they will be reverted by a single +activation of <guimenuitem>Undo</guimenuitem>, we encapsulate the lines +<programlisting> +view.removeSelectedText() +document.insertText() +</programlisting> in a <emphasis>document.editBegin()</emphasis> - +<emphasis>document.editEnd()</emphasis> block.</para> + +</example> + +<example id="advanced-editing-tools-desktop-example"> +<title>A sample <filename>.desktop</filename> file</title> + +<para>Here is a sample .desktop file that accompanies the above script.</para> + +<programlisting> +# Example of a .desktop file +[Desktop Entry] +Encoding=UTF-8 +Name=Kate Part JavaScript Uppercase Script +Comment=Script to transform the selected text to upper case +X-Kate-Command=uppercase-selection +X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p> +</programlisting> + +<para>As you can see you can define the Encoding, set a Name, a Comment, a help +text using X-Kate-Help and the command line name via X-Kate-Command.</para> + +</example> + +<sect3> +<title>Putting it all together</title> + +<para>&kate; will search the script folders (see <link +linkend="advanced-editing-tools-scripting-introduction">above</link>) for +<filename>.js</filename> files. For every such file found, &kate; will check +whether there is a corresponding <filename>.desktop</filename> file with +the same basename (for example script.js and script.desktop).</para> +<para>If a corresponding <filename>.desktop</filename> file exists, the script +will be registered using the name from the .desktop entry <emphasis>X-Kate-Command</emphasis>.</para> +<para>If a corresponding <filename>.desktop</filename> file can not be found, the script will +be registered with the file basename (i.e. without the ending .js). +If you only need the command name and none of the extra features +that a <filename>.desktop</filename> file would provide, you do not need a +<filename>.desktop</filename> file at all.</para> + +</sect3> + +</sect2> + +</sect1> + +</chapter> |