All posts by Christoph Cullmann

Dr.-Ing. Christoph Cullmann is a Senior Software Engineer at AbsInt Angewandte Informatik GmbH. His work is focused on static analysis of both binary and source programs and the WCET analysis of embedded systems. In his spare time, he works on the KDE project and maintains the Kate editor application and component.

Kate Developer Sprint 2008

In April there will be a Kate Developer Sprint, similar to previous sprints for Decibel, Akonadi, KDevelop and others. This is a great opportunity as developers interested in development of KDE’s text editor will discuss what to do to make Kate the best text editor on earth. This also means lots of polishing so that Kate in KDE 4.1 will shine even more! The meeting will take place from 2008-04-11 till 2008-04-13. The location is hosted by basysKom in Darmstadt, Germany. Many thanks goes especially to the KDE e.V. for their financial support. If you are interested in Kate development, join our mailing list. More to come, stay tuned!

The event is organized by Dominik Haumann, and is supported by the kde.ev.

On the agenda is discussing Kates future development and improving scripting capabilities amongst others.

Kate Modes & Filetypes

Modes allow the user to override the default configuration for documents of specified mimetypes or file extensions. When the editor loads a document and the mimetype or file extensions match for one of the defined filetypes, KatePart will read the configuration from the mode and apply the modelines defined. If more filetypes match, the one with the highest priority will be used.

To create a filetype, go into the settings dialog available in Kate via Settings > Configure Kate > Open/Save > Modes/Filetypes, then press the New button and fill in the properties. To remove an existing filetype, select it from the dropdown list and press the Delete button. To edit an existing mode, select it from the dropdown list.

Some Available Properties

  • Name
    This is a user friendly name that will be displayed in the menu Tools > Mode.
  • Section
    A submenu of Tools > Mode in which to place this filetype. If the section does not already exist, it will automatically be created.
  • Variables
    This is where the actual configuration goes. Variables set here will overwrite the default configuration values. Be aware that this line must begin with kate: and end with a semicolon. For a full list of available variables refer to modelines.
  • 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.

Example

As an example we will create a new mode configuration for C++ and Java files. It should use the C Style indenter and indent with 4 spaces (no tabs). The configuration could look like this:

Name: C++ and Java settings
Section: Sources
Variables: kate: space-indent on; indent-width 4; mixed-indent off; indent-mode cstyle;
File Extensions: *.cpp;*.java
Mimetypes: text/x-c++hdr;text/x-c++src;text/x-java
Priority: 10

.kateconfig Files

Kate allows you to specify local document variables by setting the corresponding modelines. The hidden file .kateconfig provides exactly the same functionality, but for all files in the directory.

Enable the Feature

To use a .kateconfig file you first have to enable the feature by invoking Settings > Configure Kate. In the config page Open/Save you can find the option Search depth for config file, which defaults to Do not use a config file. Change the value to an appropriate number,

  • 0 means look in the current folder
  • 1 means look in the current folder, and if there is no .kateconfig file, look in the parent folder
  • etc…

In short – Kate will search the number of given folder levels upwards for a .kateconfig file and load the settings from it.

Fill the .kateconfig File

The .kateconfig file simply contains modelines.

The following example will cause all documents to indent with 4 spaces with a tab width of 4. Tabs will be replaced during editing text and the end-of-line symbol is a linefeed (\n).

kate: space-indent on; tab-width 4; indent-width 4; replace-tabs on; eol unix;

Final Note

Right now it is not possible to specify different settings for different filetypes/mimetypes. We are aware of this problem and hope to provide a fix in near future, perhaps for KDE 4.

Kate Modelines

Kate Part’s modelines – also called Kate document variables – are Kate Part’s implementation of document variables, similar to Emacs and vim modelines.

Document variables can be used to set Kate settings local to a file. This is for example for using another indenter than the one defined in the GUI settings. Or assume you work on two projects, the first indents with spaces and the second with tabs, then you can simply add a modeline that contains the specific document variables that set the specific indentation properties.

The following contents is mainly from the Kate Handbook.

Modeline Format

A modeline in the Kate Part has the following format:

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

The lines can be in a comment, in C++ for example in /*...*/ sections. Multiple modelines are supported, i.e. modelines can be split over several lines for better visibility. Variable names are single words (no whitespace), and anything up to the next semicolon is the value. The trailing semicolon (;) is required.

Here is an example of how a modeline could look like, forcing indentation settings for a C++, Java or JavaScript file:

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

NOTE: Only the first and last 10 lines in a file are searched for modelines.

There are variables to support almost all options in Kate Part, and additionally plugins can use variables, in which case it should be documented in the plugin’s documentation.

How Kate Part uses Variables

When reading settings, Kate Part looks in the following places in the order

  1. the global configuration, i.e. settings made in the user interface
  2. the Modes & Filetypes configuration
  3. the .kateconfig file
  4. the modelines in the document itself

This means Kate Part’s modelines have actually the 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.

Available Modelines

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 modelines are, in detail:

  • auto-brackets [BOOL]
    Set auto insertion of brackets on or off.
  • auto-center-lines [INT]
    Set the number of autocenter lines.
  • auto-insert-doxygen [BOOL]
    Turn insertion of the leading asterisk in doxygen comments on or off. This has no effect unless you use the cstyle auto-indenter.
  • background-color [STRING]
    Sets the document background color. The value must be something that can be evaluated to a valid color, for example #ff0000.
  • backspace-indents [BOOL]Turn backspace indenting on or off.
  • block-selection [BOOL]
    Turn block selection on or off.
  • bom | byte-order-marker [BOOL] (new in Kate 3.4/KDE 4.4)
    Enable/disable the byte order marker when saving files in unicode format (utf-8/utf-16/utf-32).
  • bracket-highlight-color [STRING]
    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-color [STRING]
    Sets 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] (new in Kate 3.4/KDE 4.4)Sets the default dictionary used for spell checking.
  • dynamic-word-wrap [BOOL]
    Turns dynamic word wrap on or off.
  • eol | end-of-line [STRING]
    Sets the end of line mode. Valid settings are unix, mac and dos
  • folding-markers [BOOL]
    Set the display of folding markers on or off.
  • font-size [INT]Sets the point size of the document font.
  • font [STRING]
    Sets 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 you can find in the menus. For instance, for C++ you write C++.
  • icon-bar-color [STRING]
    Sets 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, python, lilypond, lisp are recognized. See the section Using Automatic Indenting for details.
  • indent-width [INT]
    Sets the indentation width.
  • keep-extra-spaces [BOOL]
    Set weather to keep extra spaces when calculating indentation width.
  • keep-indent-profile [BOOL] (Removed in Kate 3, i.e. since KDE4)
    If enabled, prevents unindenting a block if at least one line has no indentation.
  • line-numbers [BOOL]
    Set the display of line numbers on or off.
  • mixed-indent [BOOL]
    Set mixed indentation ala Emacs on or off.
    DEPRECATED for Kate 3.0 From version 3.0 this variable is ignored, set replace-tabs on; instead for that version.
  • overwrite-mode [BOOL]
    Set overwrite mode on or off.
  • persistent-selection [BOOL]
    Set persistent selection on or off.
  • remove-trailing-space [BOOL]
    Set dynamic end of line cleanup on or off.
  • replace-tabs-save [BOOL]
    Set tab->space conversion on save on or off.
  • replace-tabs [BOOL]
    Set dynamic tab->space conversion on or off.
  • replace-trailing-space-save [BOOL]
    Set end of line cleanup on save on or off.
  • 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.
  • space-indent [BOOL]
    Set indentation with spaces on or off.
    DEPRECATED for Kate 3.0 — From Kate 3.0 mixed-indent is the default behavior, set replace-tabs on; to achieve space-only indentation.
  • tab-indents [BOOL]
    Set the TAB key indentation on or off.
  • tab-width [INT]
    Set the tab display width.
  • undo-steps [INT]
    Set the number of undo steps to remember.
  • word-wrap-column [INT]
    Set the hard word wrap width.
  • word-wrap-marker-color [STRING]
    Set the work wrap marker color. The value must be something that can be evaluated to a valid color, for example #ff0000.
  • word-wrap [BOOL]
    Set hard word wrapping on or off.
  • wrap-cursor [BOOL]
    Set cursor wrapping on or off.