You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1243 lines
46 KiB
1243 lines
46 KiB
15 years ago
|
<chapter id="advanced-editing-tools">
|
||
|
|
<chapterinfo>
|
||
|
|
<authorgroup>
|
||
|
|
<author>&Anders.Lund; &Anders.Lund.mail;</author>
|
||
|
|
<author>&Dominik.Haumann; &Dominik.Haumann.mail;</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 the current line if no text is selected,
|
||
|
|
if comments are supported by the format of the text 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 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 comand then press the return key. The
|
||
|
|
command line will indicate wether it succeded 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, issue the command
|
||
|
|
<command>help</command> to get started. To see a list of all available commands
|
||
|
|
issue <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, 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>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<title>Argument types</title>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term>BOOLEAN</term>
|
||
|
|
<listitem><para>This is used with commands that turns things on or off.
|
||
|
|
Legal values are <userinput>on</userinput>, <userinput>off</userinput>,
|
||
|
|
<userinput>true</userinput>, <userinput>false</userinput>,
|
||
|
|
<userinput>1</userinput> or <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>
|
||
|
|
|
||
|
|
<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 whitespace 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> <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, the text is searched 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 part of the string. Parentheses in the search pattern
|
||
|
|
create <emphasis>back references</emphasis>, that is the command
|
||
|
|
remembers which part of the match matched in the parentheses; these
|
||
|
|
strings can be reused in the replace pattern, referred to as
|
||
|
|
<userinput>\1</userinput> for the first set of parentheses,
|
||
|
|
<userinput>\2</userinput> for the second and so on.</para>
|
||
|
|
|
||
|
|
<para>To search for a literal <literal>(</literal> or
|
||
|
|
<literal>)</literal>, you need to <emphasis>escape</emphasis> 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 return, you
|
||
|
|
are done.</para>
|
||
|
|
|
||
|
|
</example>
|
||
|
|
|
||
|
|
<example>
|
||
|
|
<title>A More Advanced Example</title>
|
||
|
|
|
||
|
|
<para>This example makes use of <emphasis>back references</emphasis>
|
||
|
|
as well as a <emphasis>character class</emphasis> (if you do not know what
|
||
|
|
that is, please refer to the related documentation mentioned
|
||
|
|
below).</para>
|
||
|
|
|
||
|
|
<para>Suppose you have the following line:
|
||
|
|
|
||
|
|
<programlisting>void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b )</programlisting>
|
||
|
|
</para>
|
||
|
|
<para>Now you realize that this is not nice code, and decide that you
|
||
|
|
want to use the <constant>const</constant> keyword for all
|
||
|
|
<quote>address of</quote> arguments, those characterized by the &
|
||
|
|
operator in front of the argument name. You would also like to
|
||
|
|
simplify the white space, so that there is only 1 whitespace character
|
||
|
|
between each word.</para>
|
||
|
|
|
||
|
|
<para>Launch the Editing Command Dialog, and enter:
|
||
|
|
<userinput>s/\s+(\w+)\s+(&)/ const \1 \2/g</userinput> and hit the
|
||
|
|
<guibutton>OK</guibutton> button. The <userinput>g</userinput> at the end of the expression makes
|
||
|
|
the regular expression recompile for each match to save the <emphasis>backreferences</emphasis>.</para>
|
||
|
|
|
||
|
|
<para>Output:
|
||
|
|
|
||
|
|
<computeroutput>void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )</computeroutput></para>
|
||
|
|
|
||
|
|
<para>Mission completed! Now, what happened? Well, we looked for some
|
||
|
|
white space (<literal>\s+</literal>) followed by one or more
|
||
|
|
alphabetic characters (<literal>\w+</literal>) followed by some more
|
||
|
|
whitespace (<literal>\s+</literal>) followed by an ampersand, and in
|
||
|
|
the process saved the alphabetic chunk and the ampersand for reuse in
|
||
|
|
the replace operation. Then we replaced the matching part of our line
|
||
|
|
with one whitespace followed by <quote>const</quote> followed by one
|
||
|
|
whitespace followed by our saved alphabetical chunk
|
||
|
|
(<literal>\1</literal>) followed by one whitespace followed by our
|
||
|
|
saved ampersand (<literal>\2</literal>)</para>
|
||
|
|
|
||
|
|
<para>Now in some cases the alphabetical chunk was
|
||
|
|
<quote>String</quote>, in some <quote>int</quote>, so using the
|
||
|
|
character class <literal>\w</literal> and the <literal>+</literal>
|
||
|
|
quantifier proved a valuable asset.</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. 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>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>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 formats - typically program source code,
|
||
|
|
XML markup and similar. Most highlight definitions supporting code folding
|
||
|
|
also lets 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 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>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>If you do not want to use the code folding feature, you can disable
|
||
|
|
the <guilabel>Show folding markers (if available)</guilabel> option in the
|
||
|
|
<link linkend="config-dialog-editor-appearance">Appearance page of the editor
|
||
|
|
configuration</link></para>
|
||
|
|
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="advanced-editing-tools-scripting">
|
||
|
|
|
||
|
|
<title>Scripting the editor component with Javascript</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 is that the script is placed in a folder where &kate;
|
||
|
|
can find it, along with an optional .desktop file that defines the related
|
||
|
|
properties. The valid folder are named <filename>katepart/scripts</filename>
|
||
|
|
in the &kde; data folders. You can find the data folders by running the command
|
||
|
|
<command>kde-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 for you only.</para>
|
||
|
|
|
||
|
|
<note><para>This feature is experimental and will most likely change during
|
||
|
|
future development.</para>
|
||
|
|
<para>We know that many of you will be disappointed because you can't add
|
||
|
|
your scripts to the menu or assign shortcuts to them. Sorry, sometime
|
||
|
|
in the future that will likely be possible.</para>
|
||
|
|
<para>It is also not possible to pass any arguments to your scripts yet. Be
|
||
|
|
patient, and that may be added in the bright future ;)</para>
|
||
|
|
</note>
|
||
|
|
|
||
|
|
</sect2>
|
||
|
|
|
||
|
|
<sect2 id="advanced-editing-tools-scripting-reference">
|
||
|
|
|
||
|
|
<title>The Kate JavaScript API</title>
|
||
|
|
|
||
|
|
<para>Here is listed the complete set of functions and properties available
|
||
|
|
in the <type>document</type> and <type>view</type> objects.
|
||
|
|
In addition you can of course 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>The types of arguments are of course not used in JavaScript at
|
||
|
|
this time, they are there solely to indicate what sort of value the funcitons
|
||
|
|
expect.</para></note>
|
||
|
|
|
||
|
|
<variablelist id="advanced-editing-tools-scripting-global">
|
||
|
|
<title>Global Functions</title>
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>debug( <parameter><replaceable>string</replaceable></parameter>)
|
||
|
|
[function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>parameters</title>
|
||
|
|
<listitem><para><parameter>string</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 <computeroutput>Kate (KJS Scripts):</computeroutput>
|
||
|
|
</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>line</replaceable>
|
||
|
|
</parameter>, <parameter><replaceable>column</replaceable></parameter> );
|
||
|
|
[function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>uint line</parameter> The line of the position for which
|
||
|
|
to find the attribute.</para></listitem>
|
||
|
|
<listitem><para><parameter>uint 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>uint attribute</parameter> ); [function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>c</parameter> The character to test</para></listitem>
|
||
|
|
<listitem><para><parameter>attribute</parameter> The attribute at the position
|
||
|
|
of <parameter>c</parameter>.</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Returns whether it is allowed to break the line at a character c with
|
||
|
|
attribute attribute. The result is decided by querying the highlight owning
|
||
|
|
attribute for which characters allow breaking the line.</para>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.canComment( <parameter>uint start_attribute</parameter>,
|
||
|
|
<parameter>uint end_attribute</parameter> ); [function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>start_attribute</parameter> The attribute at the
|
||
|
|
start of the range to turn into a comment.</para></listitem>
|
||
|
|
<listitem><para><parameter>end_attribute</parameter> The attribute at end of
|
||
|
|
the range to turn into a comment.</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Returns whether start_attribute and end_attribute belongs to the same
|
||
|
|
syntax highlight system. If they do, it is sane.
|
||
|
|
</para>
|
||
|
|
<example>
|
||
|
|
<title>using canComment</title>
|
||
|
|
<programlisting>
|
||
|
|
if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
|
||
|
|
// 1,0 and 5,0 belongs to the same syntax highlighting system
|
||
|
|
}
|
||
|
|
</programlisting>
|
||
|
|
</example>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.clear(); [function]</function></term>
|
||
|
|
<listitem><para>Clears the document.</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.commentStart( <parameter>uint attribute</parameter> );
|
||
|
|
[function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>attribute</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, or an empty string if multiline comments are not supported for that
|
||
|
|
text.</para>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.commentMarker( <parameter>uint attribute</parameter> );
|
||
|
|
[function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>attribute</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 or an empty string if single line comments are not supported
|
||
|
|
for that text.</para>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.commentEnd( <parameter>uint attribute</parameter> );
|
||
|
|
[function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>attribute</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, 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>Start an editing group. All actions done until the call of editEnd() will
|
||
|
|
be grouped as one undo-action.</para>
|
||
|
|
</listitem>
|
||
|
|
</varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><function>document.editEnd(); [function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<para>Finish 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 None. 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>.
|
||
|
|
Remember that if no indent mode is set, the value is <literal>none</literal>.
|
||
|
|
</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> document line number</para>
|
||
|
|
</listitem>
|
||
|
|
<listitem><para><parameter>text</parameter> 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</para></listitem>
|
||
|
|
<listitem><para><parameter>text</parameter> the text which is to be
|
||
|
|
inserted</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Inserts the text <parameter>text</parameter> in line
|
||
|
|
<parameter>line</parameter> and 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 used by 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> line number</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Removes the document line line.</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> up 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> 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 pr level, otherwise
|
||
|
|
indentation is one tab character pr. 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( uint line ); [function]</function></term>
|
||
|
|
<listitem>
|
||
|
|
<itemizedlist>
|
||
|
|
<title>Parameters</title>
|
||
|
|
<listitem><para><parameter>line</parameter> the line</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Returns the text of 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 (TAB characters counts 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 the view contains selected text,
|
||
|
|
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 line for the
|
||
|
|
cursor.</para></listitem>
|
||
|
|
<listitem><para><parameter>column</parameter> Specifies the column for the
|
||
|
|
cursor.</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Sets the input cursor position in the view to [<parameter>line</parameter>,
|
||
|
|
<parameter>col</parameter>]. This sets the cursor position by visual means,
|
||
|
|
that is the a TAB character counts up to <replaceable>tabwidth</replaceable>
|
||
|
|
depending on the position inside the line. The cursor position is made visible.
|
||
|
|
Both line and column 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 line for the
|
||
|
|
cursor.</para></listitem>
|
||
|
|
<listitem><para><parameter>column</parameter> Specifies the column for the
|
||
|
|
cursor.</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
<para>Sets the input cursor position to [<parameter>line</parameter>,
|
||
|
|
<parameter>col</parameter>]. This sets the string position, that is a TAB
|
||
|
|
character counts for 1. The cursor position is made visible. Both line and
|
||
|
|
column are zero-based.</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> up 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 uppercases the selection.
|
||
|
|
It is obvious that we first need to check whether a selection exists, if so we
|
||
|
|
get the text, change the case and then replace it with the new one. An
|
||
|
|
implementation could look like this:</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 action together so that they will be reverted by a single
|
||
|
|
activation of <guimenuitem>Undo</guimenuitem> we encapsulate the lines
|
||
|
|
<programlisting>view.removeSelectedText()</programlisting> and
|
||
|
|
<programlisting>document.insertText()</programlisting> with a
|
||
|
|
<programlisting>document.editBegin()</programlisting> and
|
||
|
|
<programlisting>document.editEnd()</programlisting>.</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
|
||
|
|
Comment=Script to uppercase the selection
|
||
|
|
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. The entries
|
||
|
|
Name, Comment and X-Kate-Help are automatically translated into other languages
|
||
|
|
by the KDE translation teams, if the files are in KDE's SVN repository.</para>
|
||
|
|
|
||
|
|
</example>
|
||
|
|
|
||
|
|
<sect3>
|
||
|
|
<title>Putting it togeather</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 file it checks whether there is a
|
||
|
|
corresponding <filename>.desktop</filename> file, like for uppercase.js it
|
||
|
|
would look for uppercase.desktop. </para>
|
||
|
|
<para>If a <filename>.desktop</filename> file can not be found the script will
|
||
|
|
be registered in katepart's command line with the filename without the ending
|
||
|
|
.js, so in our example this would be <literal>uppercase</literal>. If the
|
||
|
|
command-name is fine and you don't need the extra features a
|
||
|
|
<filename>.desktop</filename> file provides you do not need a
|
||
|
|
<filename>.desktop</filename> file at all. </para>
|
||
|
|
<para>If a <filename>.desktop</filename> file exists katepart will read the name
|
||
|
|
under which the script will be registered from the .desktop-entry
|
||
|
|
X-Kate-Command, for example X-Kate-Command=uppercase-selection.</para>
|
||
|
|
|
||
|
|
</sect3>
|
||
|
|
|
||
|
|
</sect2>
|
||
|
|
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
</chapter>
|