# Configuring &kate;

## Overview

&kate; offers several means of tweaking the application to behave as desired. The most important ones are:

The Configuration Dialog

  The main configuration tool, allowing you to configure the &kate; application, the editor component and the usage of plugins.

The Settings Menu

  Allows you to change often used settings, and to launch the configuration dialogs.

The View Menu

  Allows you to split the current frame, as well as to display the icons and line numbers pane for the currently edited document.

The embedded &konsole; is using the configuration defined in the &kcontrolcenter;, and may be configured by clicking the right mouse button and choosing from the Settings sub menu.

## The Main Configuration Dialog

The &kate; configuration dialog displays a tree of topics on the left, and a configuration page corresponding to the selected topic on the right. The tree groups the pages of the dialog into logical groups.

### The &kate; group

This group contains pages to configure the main &kate; application

#### The General Page

Global Options for &kate;

Application Mode

  This group lets you choose between &kate; MDI and &kate; SDI mode, selecting the appropriate button.

  &kate; MDI (Multiple Document Interface), which is the default mode, makes &kate; use a single window for all open files. You can choose the document to edit from the File List (docked into the &kate; window by default) or by selecting the document from the Document menu.

  &kate; SDI (Single Document Interface) will make &kate; open each document in a window of its own, and the File List/File Selector will have a separate window.

  If you change this setting, you will need to restart &kate; for it to take effect.

At Startup

  These options determine how and if &kate; will restore your editing session when launched after a normal shutdown (if restored by the session manager, &kate; will always attempt to restore your session as close as possible to what it was when you last used &kate;).

  Reopen Files

    If this option is enabled, files open when you last closed &kate; will be reopened. Bookmarks will be restored, and the cursor position, icon border and line numbers settings for the last editor used with the document will be reestablished

  Restore View Configuration

    If this option is enabled, &kate; will attempt to restore your frames exactly as you left them.

Restrict to single instance

  Enabling this means you can only have one running instance of &kate; running at any given time. If you attempt to start another one, the current instance will take over and also open files as requested. For example, if you use &kate; for displaying sources for web pages in Konqueror, they will all be opened in an existing instance of &kate; if this option is enabled.

Show Contents While Resizing Frames

  If this option is enabled, the windows will be fully repainted while dragging the frame splitters. If unchecked, a so-called rubber band (indicating the new size of the frame) will be used instead.

Sync Konsole with Active Document

  This will cause the built-in &konsole; to `cd` into the directory of the active document when launched and when a new document gets the focus. If not enabled, you have to do all your navigation in the &konsole; on your own.

Number of Recent Files

  Unsurprisingly, this allows you to decide how long the Open Recent files menu should grow.

#### The Doucment List Page

This page allows you to enable or disable the background shading visualization of your recent activity, and chose which colors to use if enabled. See the section about The Document List for more about this feature.

#### External Tools

In the Tools menu you will find a submenu labeled External Tools. These tools invokes external applications with data related to the current document, for example its URL, directory, text or selection. This page allows you to manage the menu and edit, remove or add new tools.

Each external tool is a shell command which contains macros representing the document data. When activated, the macros are substituted with data from the active document.

##### External Tools Properties

Label

  A friendly label for the External Tools menu.

Script

  The script to execute when the tool is activated. Before passing the script to the shell, the following macros are substituted:

  %URL

    The full URL of the current document, or an empty string if the document is unsaved.

  %URLS

    A space seperated list of the URLs of all open documents (except unsaved ones).

  %directory

    The directory part of the current documents URL or an empty string if the current document is unsaved.

  %filename

    the filename of the current document without the path, or an empty string if the current document is unsaved.

  %line

    The line number of the insertion cursor is in the current document.

  %column

    The column number of the insertion cursor in the current document.

  %selection

    The selected text in the current document, or an empty string if no text is selected

  %text

    The full text of the current document. Beware that this will potentially exceed the maximum command length allowed on your system. Use with care.

Executable

  The main executable i the script. This is mandatory, and is used to test if the command can be run at all. A fully qualified path is allowed in case the executable is not in your `PATH` variable.

Mimetypes

  A semicolon separated list of mimetypes for which this command should be enabled. This is currently unused.

Save

  You can optionally select to have the current or all documents saved prior to executing the script. This is handy if your script reads the file from disk.

Command Line Name

  If you fill this, the tool will be available in the editors command line as `exttool-Command Line Name` (the string you enter here prepended exttool-).

### The Editor Group

This group contains all pages related to the editor component of &kate;. Most of the settings here are defaults, they can be overridden by defining a filetype, by Document Variables or by changing them pr. document during an editing session.

#### The Colors Page

This page allows you to change the background and selection background colors of the editor. Initially, &kate; will use the colors as set in the &kcontrolcenter; Look'n'Feel Colors page.

To change a color, press the associated button and select the desired color in the color chooser.

Choosing the background color may render Syntax Highlighted text unreadable. You should use a light color for the background, and a dark color for the selection background.

Otherwise, you will probably need to change the Default Styles.

#### The Fonts Page

This page allows you to choose the default fonts for &kate;. The settings will be used for the &kwrite; and for viewing text files in &konqueror; as well.

The page presents two tabs, one for the editor font and one for the printing font. Select a tab and choose the desired font. The default is to use the &kde; global setting for fixed font.

As it is not currently possible to use individual fonts for documents, nor to change the font for printing from the print dialog, be careful. A fixed-width font is strongly recommended.

#### The Indent Page

This page allows you to change the behavior of indentation.

##### Indent Options

Auto indent

  If checked, &kate; will automatically indent new lines equal to the previous line. If the previous line is blank, the nearest above line with contents is used.

Indent with Spaces

  If checked, &kate; will indent with spaces rather than tabs.

Backspace key indents

  If this is checked, &kate; will unindent equal to the nearest above line with contents when you press the Backspace key if the part of the line preceding the cursor contains only whitespace.

Tab key indents

  If this is checked, &kate; will indent the current line equal to the nearest above line with content when you press the Tab key, if the part of the line preceding the cursor contains only whitespace.

Keep extra spaces

  With this behavior checked, &kate; will leave whitespace behind the cursor after indenting.

#### The Select Page

This page provides options for fine tuning the select behavior of &kate;

##### Select Options

Persistent Selections

  When Persistent Selections is enabled, key input will not cause the selection to be removed/diminished.

  This option partly conflicts with the Overwrite Selection option. If both are enabled, pasting text or pressing any other keys than the arrow keys will cause the selection to be overwritten.

Overwrite Selection

  If this is enabled, any text insertion, whether typed or pasted will cause the selected text to be deleted and replaced with the inserted text.

#### The Edit Page

This page contains miscellaneous options for fine-tuning the behavior of the &kate; editor component.

##### Editor Options

Word Wrap

  Word Wrap as used here means dynamically format the text by breaking lines at an appropriate place, rather than soft wrapping lines in the editor for easier reading.

  If enabled, &kate; will insert a line break as defined by the End of Line setting for the document when the line extends the length set in Wrap Words At option described below.

Wrap Words At

  This option decides the max length of lines if the Word Wrap option is enabled.

Replace Tabs with Spaces

  If enabled, &kate; will replace inserted Tab characters with a number of single whitespace characters as defined in Tab Width.

Remove trailing spaces

  If enabled, &kate; will remove any whitespace at the rear end of a line each time the cursor is moved off that line.

Tab/Indent Width

  Sets the tab width, which is also used to decide the amount of indentation when Auto Indent is enabled, or indentation is otherwise called for.

  Depending on the Indent settings indentation may be caused by pressing the Tab and Backspace keys, and activating the Edit Indent menu entry will call for indent as well.

Auto Brackets

  If this is enabled, &kate; will automatically insert a right bracket immediately to the right of the cursor when a left bracket is inserted from the keyboard. The supported bracket types are (, {, [and <

Group undos

  If enabled, &kate; will group any number of similar editing actions (for example typing, backspacing, pasting) in one entry in the undo history, so they can all be undone at once.

Show Tabs

  If enabled, &kate; will draw a small dot at the start of a Tab character in the editor to indicate its presence.

Smart Home

  This will make &kate; move the cursor to the first non-whitespace character of the current line rather than to the absolute beginning, when the Home key (or other key assigned to that function) is pressed.

Wrap Cursor

  If enabled, moving the cursor past the end of a line will cause it to continue to the next/previous line if any.

  If not enabled, the cursor cannot be moved right of the beginning of the line, but it may be moved past the end of line, and when text is inserted &kate; will automatically insert whitespace up to that position. This is sometimes very handy for programmers, for example.

#### The Keyboard Page

Here you can configure the keyboard shortcuts for the internal commands of the &kate; editor component. These includes commands for moving around in the document and selecting text. For keys related to copying and pasting text, see The Configure Keys Dialog

You may change the keys for a command, or add an alternate key.

##### To change the key(s) for a command, follow this procedure:

1. Select the command for which you want to configure the keys.

2. Choose the None option in the pane below the list if you don't want a key for this command.

   Choose the Default option to use the default key(s) for the command

   Choose the Custom option to select a custom key for the command, or set an alternate one.

3. If you choose the Custom option, the key entering button at the right of the pane will be enabled. To set a key, press it. The &kde; Define Shortcut Dialog will appear. In this dialog:

4. 1. Choose whether to set the default or alternate key. Default does not mean that you change the application default for this action, rather it sets the custom standard key for it.

   2. Press the desired key sequence, it will be visualized for you in the dialog for your confirmation.

      If you are of an adventurous nature, try playing around with the Multikey option. Using it will allow you to have &Emacs;-like key sequences (one key enters a group, the next performs the action), apart from the fact that instead of just doing the job, &kde; will pop up a menu to choose from in an undefined and most likely inappropriate place. You will now be in no doubt as to whether pressing the next key in the sequence will work, or you have to type the menu accelerator (both will work).

#### The Filetypes Page

This page allow you to override the default configuration for documents of specified mimetypes. When the editor loads a document, it will try if it matches the file masks or mimetypes for one of the defined filetypes, and if so apply the variables defined. If more filetypes matches, the one with the highest priority will be used. Please see the section Configuring With Document Variables for how to specify variables.

To create a filetype, press the New button and fill in the properties.

To remove an existing filtype, select it from the dropdown list and press the Delete button.

To edit an existing filtype, select it from the dropdown list.

##### Filetype Properties

Name

  This is a friendly name that can be displayed in the Tools Filetypes menu.

Section

  A submenu of Tools Filetypes in which to place this filtype. If the section does not allready exist, it will be created for you.

Variables

  This is where the actual configuration goes. Variables set here will overwrite the default configuration values. Please refer to Configuring With Document Variables for the available variables.

File Extensions

  A semicolon separated list of filename globs used to determine if a document matches this filetype.

Mimetypes

  A semicolon separated list of mime types, used to determine if a document matches this filetype.

Priority

  If a document matches several filetypes, the one with the highest priority will be chosen.

#### The Spelling Page

This page allows you to configure how &kspell; behaves with &kate;

#### The Highlighting Page

This page allows you to fine tune the color and syntax type selection of &kate;

For more in depth information on the syntax highlighting system, see ??

The page consists of two tabs, one for setting the Default styles and one for managing the Highlight Modes. Both tabs display a list of contexts in which the default colors and font are used to visualize the look of each style. The context name is painted using the current properties of the context.

The list has four or five columns, each with the following purpose:

Context

  Displays the context name, painted using the style properties for the context.

Bold

  The state of this checkbox decides if the context should be rendered using a boldface font.

Italic

  The state of this checkbox decides if the context should be rendered using italic font.

Normal

  This button displays the color for drawing the style in normal mode, when the text is not selected that is. To change the color, click the button.

Selected

  This button displays the color for drawing the style when the text is selected. To change the color, click the button.

Using Default

  This checkbox, only available in the Highlight Modes tab shows if the style is using its default values. It will automatically become unchecked if you change any properties of the style. Check it to reset a style to using defaults.

##### The Default Styles Tab

To change any of the default styles, set its properties as desired.

##### The Highlight Modes Tab

Here you can change the most important properties of each available highlight mode. First, use the Highlight dropdown to choose a mode to work on.

Highlight modes are initially chosen based on the &MIME; type and extension of the file. To change the list for the current selection, edit the File Extensions and Mime Types entries. Alternatively, press the wizard button to the right of the Mime Types entry. This will show a dialog displaying all available &MIME; types to choose from. Using it will edit the &MIME; types as well as the file extensions.

The &MIME; type chooser dialog displays a tree of available &MIME; types, with a description and the patterns for the &MIME; type. To include a &MIME; type, check the box beside it.

You can change the style properties of any context as described above.

At the bottom of the tab, below the highlight properties, you see a button labeled Download. Pressing it will attempt to connect to the &kate; website and fetch a list of available syntax highlight modes which you can update or add.

### The Plugins Group

This group contains pages related to plugins. Apart from the Manager configuration page, some plugins provide individual configuration options. For information on these, see the documentation for the individual plugins.

#### The Plugin Manager Page

This page provides the means of loading/unloading plugins, and minimal information about individual plugins.

To load an unloaded plugin, select it in the Available Plugins pane and use the arrow buttons to move it to the Loaded Plugins pane.

To unload a loaded plugin, select it in the Loaded Plugins pane and use the arrow buttons to move it to the Available buttons pane.

To view a minimal description and information about a plugin, select it and the information will be available below the lists.

## Configuring With Document Variables

Kate variables is kateparts implementation of document variables, similar to emacs and vi modelines. In katepart, the lines has the format

`kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]`

the lines can of cause be in a comment, if the file is in a format with comments. Variable names are single words (no whitespace), and anything up to the next semicolon is the value. The semicolon is required.

Here is an example variable line, forcing indentation settings for a C++, java or javascript file:

    // kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;

Only the first and last 10 lines are searched for variable lines.

There are variables to support almost all configurations in katepart, and aditionally plugins can use variables, in which case it should be documented in the plugin's documentation.

### How kate uses variables

When reading configuration, katepart looks in the following places (in that order):

- The global configuration.

- Optional session data.

- The "Filetype" configuration.

- Document variables in the document itself.

- Settings made during editing from menu or command line.

As you can understand document variables has the next highest precedence. Whenever a document is saved, the document variables are reread, and will overwrite changes made using menu items or the command line.

Any variable not listed below is stored in the document and can be queried by other objects such as plugins, which can use them for their own purpose. For example the variable indent mode uses document variables for its configuration.

The variables listed here documents &kate; version 2.4. More variables may be added in the future. There are defied 3 types of values for variables, with the following valid expressions:

- BOOL - on|off|true|false|1|0

- INTEGER - any integer number

- STRING - anything else

#### Available Variables

    auto-bracketsBOOL

  Set auto insertion of brackets on or off.

    auto-center-linesINT

  Set the number of autocenter lines.

    auto-insert-doxygenBOOL

  Turn insertion of the leading asterisk in doxygen comments on or off. This has no effect unless you use the cstyle auto-indenter.

    background-colorSTRING

  Sets the document background color. The value must be something that can be evaluated to a valid color, for example "#ff0000".

    backspace-indentsBOOL

  Turn backspace indenting on or off.

    block-selectionBOOL

  Turn block selection on or off.

    bracket-highlight-colorSTRING

  Sets the color for the bracket highlight. The value must be something that can be evaluated to a valid color, for example "#ff0000"

    current-line-colorSTRING

  Sets the color for the current line. The value must be something that can be evaluated to a valid color, for example "#ff0000".

    dynamic-word-wrapBOOL

  Turns dynamic word wrap on or off.

    eol | end-of-lineSTRING

  Sets the end of line mode. Valid settings are unix, mac and dos

    encodingSTRING

  Sets the document encoding. The value must be a valid encoding name, like utf-8.

    font-sizeINT

  Sets the point size of the document font.

    fontSTRING

  Sets the font of the document. The value should be a valid font name, for example courier.

    icon-bar-colorSTRING

  Sets the icon bar color. The value must be something that can be evaluated to a valid color, for example `#ff0000`.

    icon-borderBOOL

  Set the display of the icon border on or off.

    folding-markersBOOL

  Set the display of folding markers on or off.

    indent-modeSTRING

  Set the auto-indentation mode. The options none, normal, cstyle, csands, python, xml are recognized. See the section Using Automatic Indenting for details.

    indent-widthINT

  Sets the indentation width.

    keep-extra-spacesBOOL

  Set wheather to keep extra spaces when calculating indentation width.

    keep-indent-profileBOOL

  If enabled, prevents unindenting a block if at least one line has no indentation.

    line-numbersBOOL

  Set the display of line numbers on or off.

    mixed-indentBOOL

  Sets mixed indentation ala Emacs on or off.

    overwrite-modeBOOL

  Set overwrite mode on or off.

    persistent-selectionBOOL

  Set persistent selection on or off.

    remove-trailing-spaceBOOL

  Set dynamic end of line cleanup on or off.

    replace-tabs-saveBOOL

  Set tab->space conversion on save on or off.

    replace-tabsBOOL

  Set dynamic tab->space conversion on or off.

    replace-trailing-space-saveBOOL

  Set end of line cleanup on save on or off.

    schemeSTRING

  Set the color scheme. The string must be the name of a color scheme that exists in your configuration to have any effect.

    selection-colorSTRING

  Set the selection color. The value must be something that can be evaluated to a valid color, for example "#ff0000".

    show-tabsBOOL

  Set the visual TAB character on or off.

    smart-homeBOOL

  Set smart home navigation on or off.

    space-indentBOOL

  Set indentation with spaces on or off.

    tab-indentsBOOL

  Set the TAB key indentation on or off.

    tab-widthINT

  Sets the tab display width.

    undo-stepsINT

  Sets the number of undo steps to remember.

    word-wrap-columnINT

  Set the hard word wrap width.

    word-wrap-marker-colorSTRING

  Sets the work wrap marker color. The value must be something that can be evaluated to a valid color, for example "#ff0000".

    word-wrapBOOL

  Set hard word wrapping on or off.

    wrap-cursorBOOL

  Set cursor wrapping on or off.