# User-Configurable Menu

## Configuration

&kile; supports a user-configurable menu, which will appear as a part of &kile;'s menu. This menu can be configured using &kile;'s configuration dialog with Settings Configure Kile User Menu.

Configure the user menu
Configure the user menu

You have two options where to place this menu:

- either the menu User Menu will appear in the main menu bar between the menus LaTeX and Wizard and the configuration wizard Edit User Menu in the Wizard menu

  User Menu is placed in the main menu
  User Menu is placed in the main menu

- or both items will appear at the bottom of the LaTeX menu.

  User Menu as a part of the LaTeX menu
  User Menu as a part of the LaTeX menu

Already existing user-defined tags from older versions of &kile; are automatically transformed into the new user-configurable menu. The tags are saved in a file called `usertags.xml` and like all menu definition files, they can be found in the local user menu directory of &kile;: `KILE_APP_DIR/usermenu/`, &eg; `/home/user/.kde/share/apps/kile/usermenu/`.

You can use different menu definition files for different tasks. Call the user menu wizard Wizard Edit User Menu or LaTeX Edit User Menu to install or edit a menu definition file.

## Wizard

You can create new or change existing menus with a comfortable user menu configuration wizard found at Wizard Edit User Menu.

User Menu Wizard
User Menu Wizard

On the left side you will see an existing menu-tree. Like a standard menu, three different kinds of menu items are available:

- standard menu entries, which are assigned to an action

- submenus, which contain more menu items

- separators, to get a visible structure of all entries.

To modify this menu, use the six buttons on the left side. More possible actions are available in the context menu of already existing menu items.

User-Defined Menutree
User-Defined Menutree

Each standard menu item is assigned to one of three action types, where each of them has different attributes, which could be set:

- Text: &kile; gives you the ability to make your own tags. A tag is similar to a shortcut that launches some command or writes frequently-used texts, &eg; Joe Sixpack often uses the sentences `Hi, I have been inserted ...`. This tag will be inserted at the current cursor position, when this action is called (see above). Metachars are also available (see ).

- Insert file contents: Inserts the complete contents of a given file.

  Insert file contents
  Insert file contents

- Execute an external program: The output of this program can be inserted into the opened document. Metachar `%M` is also possible in the command line of this program, as the selected text will be saved in a temporary file. Use `%M` for the filename of this temporary file.

  Execute an external program
  Execute an external program

If some important information for an action is missing, menu items are colored red. This may be a nonexisting file

Nonexisting file
Nonexisting file

or a missing title for the menu entry, which will be shown with question marks as `???`.

Missing title of a menu entry
Missing title of a menu entry

If you open the context menu of such a red colored menu item, you will get an additional option for more information concerning this error.

Additional info
Additional info

More information may also be available using the What's this feature of most widgets.

## Placeholders

### Insert Text

There are some placeholders you can use in your user-defined tags: `%C`, `%B`, `%M`, `%E`, `%R` and `%T`.

- `%C`: this is where the cursor will be placed after the insertion of a user-defined tag.

  Cursor Position (%C)
  Cursor Position (%C)

- `%B`: will be replaced by a bullet (see ).

  Bullet (%B)
  Bullet (%B)

- `%M`: will be replaced by the selected text.

  Selected Text (%M)
  Selected Text (%M)

- `%E`: denotes the indentation depth of text inside an environment.

  Indentation of environment text (%E)
  Indentation of environment text (%E)

- `%R`: will call a reference-dialog to choose a label which has already been defined. This can be used to refer to a predefined label, which you can choose from a drop-down list (see also LaTeX References ref or LaTeX References pageref).

  References (%R)
  References (%R)

- `%T`: will call a citation-dialog to choose an already defined citation. The same as using LaTeX References cite a list with all the citation keys pops up.

  Citation Keys (%T)
  Citation Keys (%T)

Let's consider another example, with the following macro `\frac{%M}{%C}`. First, we select a number in our text, let's say `42`. Now we invoke this macro and obtain `\frac{42}{}` with the cursor located within the second pair of brackets.

### Insert File Contents

If you want to insert the contents of a text file, you could use the same placeholders.

### Execute A Program

If you want to execute an external program, only the `%M` for selected text is recognized in the command line. The selection will be saved in a temporary file and the placeholder `%M` is replaced with this filename.

Execute an external program (%M)
Execute an external program (%M)

Another placeholder is `%S`, which is replaced by the complete base name of the current document without the path. This base name consists of all characters in the file up to (but not including) the last '.' character.

## Parameter

Most menu entries may have additional self-explaining parameters, which may be checked. If some of these parameters are not available for some kind of action, they are disabled.

User Menu Parameter
User Menu Parameter

Here is one example for executing an external program:

Parameter example
Parameter example

You can see that a `perl` script is called, which should work with current selection. The Needs selected text parameter is checked to assure a selection. The output of this script will be inserted (Insert the output of the chosen program) and replace the current selection (Replace selected text), but not selected itself.

Of course you can also call your own programs or scripts. For example select a list of numbers, separated by spaces, and call a script or Perl program, which transforms this selection into &latex; code for a matrix. Whatever your ideas may be, you can realize them using the following usermenu entry.

Parameter example 2
Parameter example 2

## Menu Definition Files

You can install different menus at runtime for different tasks. When you call the user menu wizard, the current menu definition file is loaded. If you modify it and close the dialog with OK, your changes will be saved and installed as the new user menu. Closing the dialog with Cancel will discard all changes.

Menu Definition Files
Menu Definition Files

You are also free to save the modified file in the user menu directory or to load another menu definition file and install it. All user menu definition files must be saved in the local user menu directory of &kile;: `KILE_APP_DIR/usermenu/`.

Look at the example menu definition file `example.xml` to see more menu entries with their parameters.