# The Configuration Dialogue

The configuration dialogue is the main tool for setting parameters required by &kapp;, or adjusting the user's preferences. The dialogue is displayed the first time &kapp; is run, and can be invoked later by using the Settings Configure KScope... menu command.

The dialogue is composed of several pages, each of which handles a different set of parameters.

## The Programmes Page

&kapp; serves as a front-end to several console-based programmes: Cscope, Ctags and Dot (which is part of the Graphviz suite). Since &kapp; invokes these programmes directly, without using a shell, it cannot determine their paths. Therefore, it is required to inform &kapp; of the paths where the relevant executable files reside. Note that &kapp; needs the full path to each programme, along with the name of the executable.

Another parameter required by &kapp; is whether Cscope supports the `-v` command line option. This is a relatively new feature, added to Cscope in version 15.5. It allows &kapp; to display accurate progress information during time-consuming operations, such as building the cross-reference database, or running a long query. It is highly recommended that you upgrade Cscope to a version that supports the `-v` option, as the user experience of &kapp; is much improved with it. However, if you choose to use an older version of Cscope, make sure the check-box for using the `-v` option is cleared.

You can determine whether your version of Cscope supports this option by running ``cscope` `-h``.

The easiest way to configure programme paths is by using the automated script provided with &kapp;. This script can be activated by clicking the Guess... button. Once invoked, the script looks for the required programmes (using the shell's `which` utility). The script also makes sure that the found executables adhere to the standards required by &kapp; (e.g., that Ctags is the one provided by Exuberant-Ctags and that Dot supports the `-Tplain` command-line option). &kapp; uses the results of the script to adjust the values in the dialogue's controls.

The script will not override paths already set by the user. Instead, it will only verify the validity of these paths. For the script to determine paths automatically, the relevant text fields in the dialogue need to be cleared.

The Programmes page The Programmes page

Cscope Path

  The full path of the Cscope executable. The name of this executable must be `cscope`.

Use verbose mode (-v)

  Instructs Cscope to produce verbose progress output, by appending `-v` to the command line.

Ctags Path

  The full path of the Ctags executable. The name of this executable must contain the string `ctags`.

Dot Path

  The full path of the Dot executable. The name of this executable must be `dot`.

Guess

  Runs a script which attempts to determine the previous values automatically. This script should work in most cases, by may fail to correctly obtain some or all of the values.

If the file names on your system do not conform to the limitations described above, please create symbolic links to the executables.

## The Colours Page

The Colours page The Colours page

The Colours page allows you to configure &kapp; to look the way you want it to, by changing the foreground and background colours of some of &kapp;'s GUI elements. The elements that can be modified are:

- The project's file list (to the right of the editing area)

- The editor's symbol (or tag) list (to the left of each editor window)

- The query results window

- The call graph's background and nodes

To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click Enter).

The editor's own colours are determined by the settings of the embedded editor, and are not controlled by &kapp;.

## The Fonts Page

The Fonts page The Fonts page

The Fonts page allows you to determine the fonts used by any of &kapp;'s windows (see The Colours Page section for a description of these windows.)

To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click Enter).

As with the colour scheme, the fonts used by the embedded editor are not determined by &kapp;.

## The Options Page

This page allows the user to configure certain parameters that affect the behaviour of &kapp;.

The Options page The Options page

External Editor

  Specifies a command line for invoking an external editor application. &kapp; will replace the escape sequence %F with the file path, and the sequence %L with the current line number.

Read-Only Mode

  If set, the embedded editor will be work in read-only mode, i.e., &kapp; will not allow any changes to the displayed source files (but you can still use the external editor).

Open Last Project on Start-Up

  Determines whether &kapp; should automatically attempt to load the last active project when started.

Automatic Tag Highlighting

  If set, &kapp; will highlight tags in the tag list based on the current position of the text cursor.

Brief Tab Captions for Query Pages

  This option allows some space to be saved by using shortcuts for the page titles in the query window.

Warn When a File is Modified Outside &kapp;

  If set, &kapp; will issue a warning whenever a file is changed on the hard drive, while it is open for editing in &kapp;. This option will only work in conjunction with the Kate text editor).

Automatically Sort Files in the File List

  By default, &kapp; will sort the files in the project's file list whenever a project is loaded. However, such behaviour may not be suitable for large projects on older machines, causing &kapp; to hang for long periods when loading such projects. Uncheck this option to avoid automatic sorting.

System Profile

  Allows the choice between a fast and a slow system configuration. The fast profile will take certain actions automatically which are not appropriate for a slower system (for example, automatic database rebuilds and auto-completion are enabled by default for fast systems and disabled for slow systems). Note that the terms "fast" and "slow" do not necessarily refer to the particular machine which runs &kapp;, but rather to the complete environment (e.g., a fast machine may still be using a relatively slow file server).

Editor Popup Menu

  Provides two choices for the embedded editor's context menu:

  - Embedded: A menu with Cscope actions is included as a sub-menu of the editor's own context menu.

  - &kapp; Only: Only Cscope actions are available through the context menu.

  The second choice provides quicker access to Cscope commands, but the editor's menu is discarded.