&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;

# Working with the &kappname; editor

## Overview

The &kappname; editor is the editing area of the &kappname; window. This editor is shared between &kate; and &kwrite;, and it can also be used in &konqueror; for displaying text files from your local computer, or from the network.

The editor is composed of the following components:

The editing area

  This is where the text of your document is located.

The Scrollbars

  The scrollbars indicate the position of the visible part of the document text, and can be used to move around the document. Dragging the scrollbars will not cause the insertion cursor to be moved.

  The scrollbars are displayed and hidden as required.

The Icon Border

  The icon border is a small pane on the left side of the editor, displaying a small icon next to marked lines.

  You can set or remove a bookmark in a visible line by clicking the &LMB; in the icon border next to that line.

  The display of the icon border can be toggled using the View Show Icon Border menu item.

The Line Numbers Pane

  The Line numbers pane shows the line numbers of all visible lines in the document.

  The display of the Line Numbers Pane can be toggled using the View Show Line Numbers menu item.

The Folding Pane

  The folding pane allows you to collapse or expand foldable blocks of lines. The calculation of the foldable regions is done according to rules in the syntax highlight definition for the document.

### Also in this Chapter:

- Navigating in the Text

- Working with the Selection

- Copying and Pasting Text

- Finding and Replacing Text

- Using Bookmarks

- Automatically Wrapping Text

- Using automatic indenting

## Navigating in the Text

Moving around in the text in &kappname; is similar to most graphical text editors. You move the cursor using the arrow keys and the &PgUp;, &PgDn;, &Home; and &End; keys in combination with the &Ctrl; and &Shift; modifiers. The &Shift; key is always used to generate a selection, while the &Ctrl; key has different effects on different keys:

- For the &Up; and &Down; keys it means scroll rather than move the cursor.

- For the &Left; and &Right; keys it means skip words rather than characters.

- For the &PgUp; and &PgDn; keys it means move to the visible edge of the view rather than browse.

- For the &Home; and &End; keys it means move to the beginning or end of the document rather than the beginning or end of the line.

&kappname; also provides you with a way to quickly jump to a matching brace or parenthesis: place the cursor on the inside of a parenthesis or brace character, and press &Ctrl;6 to jump to the matching parenthesis or brace.

In addition you can use bookmarks to quickly jump to positions that you define on your own.

## Working with the Selection

There are two basic ways of selecting text in &kappname;: using the mouse, and using the keyboard.

To select using the mouse, hold down the &LMB; while dragging the mouse cursor from where the selection should start, to the desired end point. The text gets selected as you drag.

Double-clicking a word will select that word.

Triple-clicking in a line will select the entire line.

If &Shift; is held down while clicking, text will be selected:

- If nothing is already selected, from the text cursor position to the mouse cursor position.

- If there is a selection, from and including that selection to the mouse cursor position.

When selecting text by dragging the mouse, the selected text is copied to the clipboard, and can be pasted by clicking the middle mouse button in the editor, or in any other application to which you want to paste the text.

To select using the keyboard, hold down the &Shift; key while using the navigation keys (Arrow keys, &PgUp;, &PgDn;, &Home; and &End;, possibly in combination with &Ctrl; to extend the move of the text cursor).

See also the section Navigating in the Text in this chapter.

To Copy the current selection, use the Edit Copy menu item or the keyboard shortcut (defaults to &Ctrl;C).

To Deselect the current selection, use the Edit Deselect menu item, or the keyboard shortcut (default is &Ctrl;&Shift;A), or click with the &LMB; in the editor.

### Using Block Selection

When Block Selection is enabled, you can make vertical selections in the text, meaning selecting limited columns from multiple lines. This is handy for working with tab separated lines for example.

Block Selection can be toggled using the Edit Block Selection Mode menu item. The default keyboard shortcut is &Ctrl;&Shift;B .

### Using Overwrite Selection

If Overwrite Selection is enabled, typing or pasting text into the selection will cause the selected text to be replaced. If not enabled, new text will be added at the position of the text cursor.

Overwrite Selection is enabled by default.

To change the setting for this option, use the Cursor & Selection page of the Configuration Dialog.

### Using Persistent Selection

When Persistent Selection is enabled, typing characters or moving the cursor will not cause the Selection to become deselected. This means that you can move the cursor away from the selection and type text.

Persistent Selection is disabled by default.

Persistent Selection can be enabled in the Cursor & Selection page of the Configuration Dialog.

If Persistent Selection and Overwrite Selection are both enabled, typing or pasting text when the text cursor is inside the selection will cause it to be replaced and deselected.

## Copying and Pasting Text

To copy text, select it and use the Edit Copy menu item. Additionally, selecting text with the mouse will cause selected text to be copied to the X selection.

To paste the text currently in the clipboard, use the Edit Paste menu item.

Additionally, text selected with the mouse may be pasted by clicking the &MMB; at the desired position.

If you are using the &kde; desktop, you can retrieve earlier copied text from any application using the &klipper; icon in the system tray.

## Finding and Replacing Text

### The Search and Replace Bars

&kappname; has an incremental search bar and a power search and replace bar, which offers the means of entering a replacement string along with a few extra options.

The bars offer the following common options:

Find

  This is where to enter the search string. The interpretation of the string depends on some of the options described below.

Match case

  If enabled, the search will be limited to entries that match the case (upper or lower) of each of the characters in the search pattern.

The power search and replace bar offers some additional options:

Plain Text

  Literally match any occurrence of the search string.

Whole Words

  If selected, the search will only match if there is a word boundary at both ends of the string matching, meaning not an alphanumeric character - either some other visible character or a line end.

Escape Sequences

  If selected, the Add menuitem at the bottom of the context menu of the text boxes will be enabled and allows you to add escape sequences to the search pattern from a predefined list.

Regular Expression

  If selected, the search string is interpreted as a regular expression. The Add menuitem at the bottom of the context menu of the text boxes will be enabled and allows you to add regular expression items to the search pattern from a predefined list.

  See Regular Expressions for more on these.

Search in the selection only

  If checked, the search and replace will be performed within the selected text only.

Find all

  Clicking this button highlights all matches in the document and shows the number of found matches in a small popup.

### Finding Text

To find text, launch the incremental search bar with &Ctrl;F or from the Edit Find... menu item.

This opens the incremental search bar at the bottom of the editor window. On the left side of the bar is a button with an icon to close the bar, followed by a small text box for entering the search pattern.

When you start entering the characters of your search pattern, the search starts immediately. If there is a match in the text this is highlighted and the background color of the entry field changes to light green. If the search pattern does not match any string in the text, this is indicated by a light red background color of the entry field.

Use the or button to jump to the next or previous match in the document.

Matches in the document are highlighted even when you close the search bar. To clear this highlighting, press the &Esc; key.

You can choose whether the search should be case sensitive. Selecting will limit finds to entries that match the case (upper or lower) of each of the characters in the search pattern.

Click on the button at the right side of the incremental search bar to switch to the power search and replace bar.

To repeat the last find operation, if any, without calling the incremental search bar, use F3 Edit Find Next or &Shift;F3 Edit Find Previous.

### Replacing Text

To replace text, launch the power search and replace bar using the Edit Replace command, or the &Ctrl;R shortcut.

On the upper left side of the bar is a button with an icon to close the bar, followed by a small combo box for entering the search pattern. The box remembers recently used patterns.

You can control the search mode by selecting the options Plain Text, Whole Words, Escape Sequences or Regular Expression from the drop down box.

If Escape sequences or Regular expression are selected, the Add... menuitem at the bottom of the context menu of the text boxes will be enabled and allows you to add escape sequences or regular expression items to the search or replace pattern from predefined lists.

Use the or button to jump to the next or previous match in the document.

Enter the text to replace with in the text box labeled Replace and click the Replace button to replace only the highlighted text or the Replace All button to replace the search text in the whole document.

You can modify the search and replace behavior by selecting different options at the bottom of the bar. Selecting will limit finds to entries that match the case (upper or lower) of each of the characters in the search pattern. will search and replace within the current selection only. The Find All button highlights all matches in the document and shows the number of found matches in a small popup.

Click on the button at the right side of the power search and replace bar to switch to the incremental search bar.

If you are using a regular expression to find the text to replace, you can employ backreferences to reuse text captured in parenthesized subpatterns of the expression.

See Regular Expressions for more on those.

You can do `find`, `replace` and `ifind` (incremental search) from the command line.

## Using Bookmarks

The bookmarks feature allows you to mark certain lines, to be able to easily find them again.

You can set or remove a bookmark in a line in two ways:

- Move the insertion cursor to the line and activate the Bookmarks Set Bookmark (&Ctrl;B) command.

- Click in the Icon Border next to the line.

Bookmarks are available in the Bookmarks menu. The individual bookmarks are available as menu items, labeled with the line number of the line with the bookmark, and the first few characters of the text in the line. To move the insertion cursor to the beginning of a bookmarked line, open the menu and select the bookmark.

To quickly move between bookmarks or to the next/previous bookmark, use the Bookmarks Next (&Alt;&PgDn;) or Bookmarks Previous (&Alt;&PgUp;) commands.

## Automatically Wrapping text

This feature allows you to have the text formatted in a very simple way: the text will be wrapped, so that no lines exceed a maximum number of characters per line, unless there is a longer string of non-whitespace characters.

To enable/disable it, check/uncheck the Static Word Wrap checkbox in the edit page of the configuration dialog.

To set the maximum line width (maximum characters per line), use the Wrap Words At option in the Editing page of the configuration dialog.

If enabled, it has the following effects:

- While typing, the editor will automatically insert a hard line break after the last whitespace character at a position before the maximum line width is reached.

- While loading a document, the editor will wrap the text in a similar way, so that no lines are longer than the maximum line width, if they contain any whitespace allowing that.

There is currently no way to set word wrap for document types, or even to enable or disable the feature on a per document level. This will be fixed in a future version of &kappname;.

## Using automatic indenting

&kappname;s editor component supports a variety of autoindenting modes, designed for different text formats. You can pick from the available modes using the Tools Indentation menu. The autoindent modules also provide a function Tools Format Indentation which will recalculate the indentation of the selected or current line. Thus, you may reindent your entire document by selecting all the text and activating that action.

All the indent modes use the indentation related settings in the active document.

You can set all sorts of configuration variables, including those related to indentation using Document Variables and File types.

### Available Autoindent Modes

None

  Selecting this mode turns automatic indenting off entirely.

Normal

  This indenter simply keeps the indentation similar to the previous line with any content other than whitespace. You can combine this with using the indent and unindent actions for indenting to your own taste.

C Style

  An indenter for C and similar languages, such as C++, C#, &Java;, &javascript; and so on. This indenter will not work with scripting languages such as Perl or PHP.

Haskell

  An indenter for the functional programming language Haskell.

Lilypond

  An indenter for the Lilypond notation language for music.

Lisp

  An indenter specifically for the Lisp scripting language and Lisp dialects.

Python

  An indenter specifically for the python scripting language.

XML Style

  An indenter specifically for XML like languages.

## Line Modification Indicators

&kappname;'s line modification indicators let you easily see what you have recently changed in a file. By default, saved changes are indicated by a green bar to the left of a document, while unsaved changes are indicated by an orange bar.

Line Modification Indicators in action.

You can change the colors used in the Fonts & Colors configuration panel, or you can disable this feature completely in the Borders tab of the Appearance configuration panel.

## The Scrollbar Minimap

&kappname;'s Scrollbar Minimap displays a preview of documents in place of the scrollbar. The currently visible portion of the document is highlighted.

The Scrollbar Minimap shows a preview of the &kate; source code.

You can temporarily enable or disable the minimap by selecting View View Scrollbar Minimap or permanently in the Appearance section of &kappname;'s configuration.

## Multiple cursors

Multiple cursor support was introduced with version 5.93 of katepart.

### Creating multiple cursors

- To create them via mouse, use &Alt; + &LMB;. The modifier is configurable, see Configure multicursor modifier

- To create via keyboard, press &Ctrl;&Alt;&Up; to create cursor above primary cursor and &Ctrl;&Alt;&Down; to create cursor below. These shortcuts are also configurable

- To create cursors out of a selection, first select some text and then press &Shift;&Alt;I. This will create a cursor at the end of each line in selection.

- Use &Alt;J to find the next occurrence of the word under cursor and select it + create a cursor. If you want to skip the current word under cursor, press &Alt;K and it will mark the currently selected word as skipped. When you press &Alt;J again it will unselect the current word and move to the next word.

- Use &Ctrl;&Alt;&Shift;J to find all occurrences of the word under cursor and select them with a cursor at the end of each selection. You can use &Alt;J to cycle through the selected words and use &Alt;K to unselect any word as mentioned in the previous paragraph.

### Working with multiple cursors

Once you have created a few cursors, you can perform most of the editing operations on them as you would on a single cursor. For example, typing a letter will type it for each cursor. Similarly you can perform text transforms &eg;, capitalization for all the positions or selections.

Sometimes you will want to remove cursors. To do so, you can &Alt; + &LMB; on the cursor that you want to remove. If you just want to remove cursors on lines that are empty, there is a ready-made action for it that will do it for you. To invoke the action, open the Command Bar using &Ctrl;&Alt;I and look for Remove cursors from empty lines and hit &Enter;. You can also configure a shortcut for this action.