Syntax: menu (command, path, [hotkey], [id])

This is a very powerful command, which is used to add a new entry to the menu or to modify an existing entry. It determines which command is executed when the menu entry is activated, which icon is shown in the menu and which hotkey is used. Each menu entry can be disabled or hidden, can be assigned a unique id and can also join a menu group.

You normally do not need this command within a Kwave script!


command: A text command (including parameters) or a command list that will be executed when the menu entry gets activated. If a menu entry does not have a corresponding command (for example if it is a sub menu and not menu entry), you should use the special command ignore().
path: The path within the menu, using a / as separator. The last part of the path can be a sub command which modifies some property of the menu entry (see below). The last portion of the path (that is not a sub command) produces a menu entry, the parts before produce the main menu entry or sub menus that lead to it. Main menu entries or sub menus are automatically created when a menu entry is created, you do not need them manually.
hotkey: A bitmask that consists of a combination of predefined keys and modifiers, concatenated with a +. The key can be either a digit, an upper case letter, a function key (F1 ... F12) or any other key name understood by the Qt class QKeySequence, including key names for predefined actions (like for example ::Copy). Typical modifiers are SHIFT, ALT and CTRL.
id: A unique id that can be internally used to identify this menu entry or menu / sub menu. Only uppercase letters, digits and _ should be used and it should start with ID_. It is in your own responsibility to make sure that the same id is not used twice.

Sub Commands

#checkable: Makes the menu entry checkable, so that it can be switched on or off.
#disabled: Disables the menu, sub menu or menu entry.
#enabled: Enables the menu, sub menu or menu entry.
#exclusive(group): Adds the menu entry to an exclusive group (one of many selection). The group that is given as parameter should not be used for any other purpose. Only one entry within that group can be selected at a time.

Adds the menu, sub menu or menu entry to one or more a groups, so that the application can enable/disable a bunch of menu entries without need to know all their unique ids. Multiple groups can be passed as a list with a , as separator. Group names have to start with a @. The following groups are predefined:


Only enabled when the clipboard is not empty.


Only enabled when the current signal contains at least one label.


Enabled when the current signal is not closed (the signal might be empty or zero length).


Enabled when the selection is not empty (more than one sample is selected).


Enabled when there is some signal loaded and it is not empty or zero length.

#hidden: Hides the menu, sub menu or menu entry.
#icon(name): Assigns an icon to the menu entry. The icon name should correspond to an icon file (without path and file extension) that is installed on the system or with Kwave.
#listmenu(id,command): Inserts a placeholder for a list of menu entries into a sub menu. The unique id specified in this sub command is used to add/remove or clear the list of menu entries. The command parameter has to contain %1 as parameter, which will be replaced with the text of the menu entry when it is activated. This sub command is internally used for the list of recent files, list of tracks and window list.
#separator: Inserts a separator into a sub menu.


Syntax: msgbox(text)

Shows a message box with some text and the two buttons OK (returns without error code) and Cancel (returns and error code). You can use this command to give the user a possibility to abort a running script.


text:A message that will be shown in the message box, should contain a question that can be answered with OK or Cancel.