# PDF Editor menu and toolbar system

Configuration of menus and toolbars are in the main configuration file `pdfeditrc`, which is placed in the data directory (by defalt it is configured as `/usr/share/pdfedit`). Format of the file is 'ini file', where sections have heading composed of its name in square brackets, followed by lines in format "`key=value`"

In home directory in file `.pdfedit/pdfeditrc` are user settings. User can redefine any key in any section, thus he have possibility to modify editor menus as he deem appropriate.

## Menus and Toolbars

Menus are stored in gui section. Each menu, menu item, toolbar or toolbar item have a unique name (all these share common namespace) - also, menu items often can be used as toolbar items (as long as they have icon) and toolbar items can be used as menu items (as long as they have text).

### Lists and items

Each item is either a "list", "label" or "item". These are menus and menu items in context of menu, or toolbars, labels and toolbar items in context of toolbar. Toolbar can also contain special items.

Usage is basically the same for menus and toolbars, but there are some differences:

- Lists in menu can contain items (menu items) or lists (submenus). Submenus can be nested to any level, but you cannot create a loop. Program will tell you about the loop and will not start if you do so. List used as toolbar can contain only items and labels
- Menu item does not need icon, toolbar item needs icon
- Caption in menu items will be used as text of the menu items, caption in toolbar items will be used as tooltip

List called `MainMenu` will be used as editor's main menu. Key called `toolbars` contain comma separated list of toolbar names. Only toolbars specified here will be available in editor.

#### Format of one list

    items/name_of_list=list Caption of menu,menu item 1, menu item 2, ....

Number of items in one list is not limited, but note that dimensions of screen where the menu or toolbars will be shown are limited. Each menu items referenced in the list must exist, invalid item will cause editor not to start with an error message. If you want to insert separator in the menu, use "-" (single dash) in place of items's name

    Caption of item

is text that will be shown as menu text/tooltip. All further parameters (comma separated) following caption are items that will be contained in the list.

#### Appending items to list

    items_add/name_of_list=menu item 1, menu item 2, ....

This way you can add items to an existing list. Only one "item_add" field can exist for each list and is used mostly for adding extra items to any of the menus in user configuration file, without having to redefine entire list and its items. This field is composed of comma separated menu items to be appended at end of the menu, syntax of items is same as items in ordinary list.

#### Format of one item

    items/name_of_item=item Caption of item,Command,Keyboard_shortcut,Icon

Elements in this definition are comma separated. If any element should include comma in its content, you must escape the comma by backslash, otherwise the comma would be treated as separator of elements. Also, backslash must be escaped by extra backslash.

    Icon

is name of file with icon image. The icon should may be in PNG, BMP, XBM, XPM or PNM format, although PNG is recommended. Also supported may be JPEG, MNG and GIF - depend on how QT library used to compile the editor is configures. You should not rely on support of these formats when creating menus. Can be omitted or left blank.

    Caption of item

is text that will be shown as caption.

    Command

is any piece of script that will be run when this item is clicked. For longer or more complex commands it is recommended to define them as functions in init.qs and from menu only call them ... These are two special cases:

- if the string used as command is "quit", the editor will quit (close all windows)
- if the string used as command is "closewindow", the editor will close current windows

    Keyboard_shortcut

This specifies keyboard shortcut that will invoke the action. If two different items have the same shortcut, the result is undefined. Can be omitted (if icon is also omitted) or just left blank (no keyboard shortcut). Format is modifiers+key, for example: Ctrl+A, Shift+X, Ctrl+Alt+Z

#### Format of one label

    items/name_of_item=label Caption of label

Label with short description text, usually places before or after other items. Label is valid only in toolbar, menu can not contain a label.

### Special toolbar items

Toolbar can also contain some special items, that provide more functionality than just a button. Such items have always name starting with underscore character and therefore it is advised not to use such names for naming your own items to avoid possible collision. You can insert them into any toolbar just by referencing their name in a list. Some of the items have parameter, in such case, the name of the item should be followed by space, followed by the parameter value. For example, `_color_tool fg` specify `_color_tool` item with parameter `fg`.

#### List of special toolbar items

Name | Description
--- | ---
_revision_tool | Tool to list revisions and change them
_zoom_tool | Tool to change zoom level of currently shown page
_page_tool | Tool to show and change which page is currently shown
_color_tool | Tool to pick named color. Parameter specifies name of the color
_edit_tool | Tool to edit arbitrary text. Parameter specifies name of the text
_number_tool | Tool to edit arbitrary number. Parameter specifies name of the number and it is possilbe in script to specify predefined set of number, that will be available in a drop-down box. User is still able to type in a number not present in the list.
_select_tool | Tool to select text from list of strings. Parameter specifies name of the text and it is possible in script to specify set of strings, that will be available in a drop-down box.

The name must be unique for special toolbar items that have name as parameter. If you create two toolbar items with same name, the results are undefined.

## Icons

Path where to look for icons is defined in `path` section of configuration file. Key `icon` specifies semiciolon separated list of path, which will be searched from first to last intil the icon is found. Path elements may contain variable references in shell style (`$VARIABLE` and `${VARIABLE}`), which will be expanded automatically. Default icon path is `$HOME/.pdfedit/icon`;`/usr/share/pdfedit/icon`. Recommended way for user to install his own icons is doing it in by copying them to `.pdfedit/icon` subdirectory in his home directory.

## Icon themes

PDF Editor support icon themes. Themes can be created by creating subdirectory in any directory from icon path and putting some custom icons there. Theme then can be activated by modifying the `theme/current` key in the `icon` section in configuration - set the key to name of the directory with theme. Or it can be simply specified in 'Icon theme' field in editor's configuration dialog.

Editor look first for icon from theme across all directories in icon path, by appending a theme name to the path - so for example if theme is `hicolor` and one icon directory is `$HOME/.pdfedit/icon`, editor looks in `$HOME/.pdfedit/icon/hicolor` for that directory. If a themed icon is not found, editor looks for a default icon in the icon directory itself (which also correspond to a `default` theme).