http://docs.kde.org/
PrevConfigure KatePartNext

Configuring With Document Variables

KatePart variables is KatePart's implementation of document variables, similar to Emacs and vi modelines. In katepart, the lines have the following format: kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ] The lines can of course 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: replace-tabs on; indent-width 4; indent-mode cstyle;

Note

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

Additionally, document variables can be placed in a file called .kateconfig in any directory, and the configured settings will be applied as if the modelines were entered on every file in the directory and its subdirectories. Document variables in .kateconfig use the same syntax as in modelines, but with extended options.

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

KatePart has support for reading configurations from .editorconfig files, when the editorconfig library is installed. KatePart automatically searches for a .editorconfig whenever you open a file. It gives priority to .kateconfig files, though.

How KatePart 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 .kateconfig.

  • Document variables in the document itself.

  • Settings made during editing from menu or command line.

As you can see, document variables are only overridden by changes made at runtime. 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 KatePart version 5.38. More variables may be added in the future. There are 3 possible 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-brackets [BOOL]

Enable automatic insertion of brackets.

auto-center-lines [INT]

Set the number of autocenter lines.

background-color [STRING]

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

backspace-indents [BOOL]

Enable or disable unindenting when Backspace is pressed.

block-selection [BOOL]

Turn block selection on or off.

bom | byte-order-mark | byte-order-marker [BOOL]

Enable/disable the byte order mark (BOM) when saving files in Unicode format (utf8, utf16, utf32).

Since: Kate 3.4 (KDE 4.4)

bracket-highlight-color [STRING]

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

current-line-color [STRING]

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

default-dictionary [STRING]

Sets the default dictionary used for spellchecking.

Since: Kate 3.4 (KDE 4.4)

dynamic-word-wrap [BOOL]

Turns dynamic word wrap on or off.

eol | end-of-line [STRING]

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

folding-markers [BOOL]

Set the display of folding markers on or off.

folding-preview [BOOL]

Enable folding preview in the editor border.

font-size [INT]

Set the point size of the document font.

font [STRING]

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

hl | syntax [STRING]

Set the syntax highlighting. Valid strings are all the names available in the menus. For instance, for C++ simply write C++.

icon-bar-color [STRING]

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

icon-border [BOOL]

Set the display of the icon border on or off.

indent-mode [STRING]

Set the auto-indentation mode. The options none, normal, cstyle, haskell, lilypond, lisp, python, ruby and xml are recognized. See the section the section called “Using automatic indenting” for details.

indent-pasted-text [BOOL]

Enable/disable adjusting indentation of text pasted from the clipboard.

Since: Kate 3.11 (KDE 4.11)

indent-width [INT]

Set the indentation width.

keep-extra-spaces [BOOL]

Set whether to keep extra spaces when calculating indentation width.

line-numbers [BOOL]

Set the display of line numbers on or off.

newline-at-eof [BOOL]

Add an empty line at the end of the file (EOF) when saving the document.

Since: Kate 3.9 (KDE 4.9)

overwrite-mode [BOOL]

Set overwrite mode on or off.

persistent-selection [BOOL]

Set persistent selection on or off.

replace-tabs-save [BOOL]

Set tab to space conversion on save on or off.

replace-tabs [BOOL]

Set dynamic tab to space conversion on or off.

remove-trailing-spaces [STRING]

Removes trailing spaces when saving the document. Valid options are:

  • none, - or 0: never remove trailing spaces.

  • modified, mod, + or 1: remove trailing spaces only in modified lines. The modified lines are marked by the line modification system.

  • all, * or 2: remove trailing spaces in the entire document.

scrollbar-minimap [BOOL]

Show scrollbar minimap.

scrollbar-preview [BOOL]

Show scrollbar preview.

scheme [STRING]

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

selection-color [STRING]

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

show-tabs [BOOL]

Set the visual tab character on or off.

smart-home [BOOL]

Set smart home navigation on or off.

tab-indents [BOOL]

Set Tab key indentation on or off.

tab-width [INT]

Set the tab character display width.

undo-steps [INT]

Set the number of undo steps to remember.

Note: Deprecated since Kate 3 in KDE4. This variable is ignored. The maximal count of undo steps is unlimited.

word-wrap-column [INT]

Set the static word wrap width.

word-wrap-marker-color [STRING]

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

word-wrap [BOOL]

Set static word wrapping on or off.

Extended Options in .kateconfig files

KatePart always search for a .kateconfig file for local files (not remote files). In addition, it is possible to set options based on wildcards (file extensions) as follows:

kate: tab-width 4; indent-width 4; replace-tabs on;
kate-wildcard(*.xml): indent-width 2;
kate-wildcard(Makefile): replace-tabs off;

In this example, all files use a tab-width of 4 spaces, an indent-width of 4 spaces, and tabs are replaced expanded to spaces. However, for all *.xml files, the indent width is set to 2 spaces. And Makefiles use tabs, i.e. tabs are not replaced with spaces.

Wildcards are semicolon separated, i.e. you can also specify multiple file extensions as follows: 

kate-wildcard(*.json;*.xml): indent-width 2;

Further, you can also use the MIME type to match certain files, e.g. to indent all C++ source files with 4 spaces, you can write: 

kate-mimetype(text/x-c++src): indent-width 4;

Note

Next to the support in .kateconfig files, wildcard and MIME type dependent document variables are also supported in the files itself as comments.