CTRLMENU(1) General Commands Manual CTRLMENU(1) NAME ctrlmenu – unified menu system for X11 SYNOPSIS ctrlmenu [-dit] [-a keysym] [-r keychord] [-x buttonspec] [file] DESCRIPTION ctrlmenu is a launcher and menu system for X. It reads a text file describing entries in a hierarchical menu, and creates input methods for selecting and entering those entries. When an entry is selected, its respective command is run. If no file argument is given, or if it is a hyphen “-”, ctrlmenu reads from standard input. The options are as follows -a keysym Enable the altkey input. The argument keysym must be the key symbol for the alt key (none by default). Despite its name, this key can be any key. See the section USAGE for more information on the alt key. -d Enable the dockapp. This option makes show a docked menu on the window manager's dock. See the section USAGE for more information on the docked menu. -i Match entries case insensitively on the runner. -t Enable tornoff menus. This option can only be used together with -d and/or -x. See the section USAGE for more information on the tornoff menus. -r keychord The argument keychord must be the keychord to invoke the runner (A-space, by default). The keychord must be a keysym, prefixed with C- (for Control), S- (for Shift), A- (for Alt), W- (for Super/Win). See the section USAGE for more information on the runner. -x buttonspec Enable root menu. This option makes ctrlmenu show the menu when clicking on the desktop or clicking anywhere with a given modifier. The argument buttonspec must be an optional button number (or nothing for button 3, the right button), prefixed with C- (for Control), S- (for Shift), A- (for Alt), W- (for Super/Win), N- (for no modifier, making any press spawn the menu), or nothing (for no modifier, making only presses to the root window spawn the menu). The button spec can be also suffixed with the letter P to indicate that the click to the root window should be passed to other clients. See the section USAGE for more information on the root menu. Each line read from the specified file or stdin can be a separator, a terminal entry, a common meta-entry, or a pipe meta-entry. Any blank around an entry is ignored. The format of an entry is as follows: ENTRY := SEPARATOR | TERMINAL | META | PIPE SEPARATOR := "--\n" TERMINAL := NAME ["--" COMMAND] "\n" META := NAME "{\n" ENTRIES... "}\n" PIPE := NAME "--" COMMAND "{\n" SCRIPT "}\n" Separator A separator is an anonymous, non-selectable entry in the menu. Separators are composed by a line with only two dashes in it. Terminal Entry A terminal entry is a line composed by a name, and an optional command after two dashes. A terminal entry appears as an entry in the menu which, when selected, runs its command (or its name, if the command is not provided). A terminal entry ends in a newline. Common Meta-Entry A common meta-entry is a line composed by a name followed by an open curly bracket, then a sequence of other entries, followed by a close curly bracket. A common meta-entry appears as an entry in the menu which, when selected, opens a submenu. A common meta-entry ends in a newline. Pipe Meta-Entry A pipe meta-entry is a line composed by a name followed two dashes and a command. Then a shell script between curly braces. A pipe meta-entry appears as an entry in the menu which, when selected, runs the corresponding shell script whose output is read for menu entries. Only terminal entries and separators can be read from the running script. A pipe meta-entry ends in a newline. The name can end in a string between braces, which are used for extensions (the only extensions supported are keybinding, descriptions and icons). The format of a name is as follows: NAME := LABEL [ "[" LIST "]" ] LIST := | EXTENSION ":" LIST EXTENSION := KEYBINDING | ICON | DESCRIPTION ICON := "#" PATH KEYBINDING := "!" ("S-" | "C-" | "A-" | "W-") KEYSYM DESCRIPTION := STRING The LABEL is the string that will appear in the menu. The label can contain a underscore (“_”) before a character to indicate that this character should be underlined on the menu, and that pressing the key corresponding to that character selecs the item. The extension list is a colon-separated list of extensions between braces. An icon is the path to an xpm (pixmap) icon to be displayed in the menu before the label. The path must be prefixed with a “#” character to indicate that it is the path to an icon. A keybinding is a sequence of modifiers and a key symbol to be bound for the menu entry. The keybinding must be prefixed with a “!” character to indicate that it is a keybinding. When the corresponding key is pressed along with the given modifiers, the respective entry is selected. A keybinding has the following form. An “S-” prefix indicates that the Shift key modifier is active. An “C-” prefix indicates that the Control key modifier is active. An “A-” prefix indicates that the Alt key modifier is active. An “W-” prefix indicates that the Super (Also known as “windows key”) key modifier is active. The keysym that forms the ending of the keybinding is one of the keysyms listed at the /usr/X11R6/include/X11/keysymdef.h file (/usr/include/X11/keysymdef.h in some systems.) The description is a comment for the item to be piped to the runner application. The description has no prefix and should be the last extension on the extension list. USAGE The following input methods are provided by ctrlmenu Docked Menu The docked menu is an always-visible dockapp window that displays a list of menus on the window manager's dock. The docked menu is only displayed when using the -d command-line option. The docked menu only works on window managers that docks dockapps, such as fluxbox(1). Root Menu The root menu is a menu that pops up when the user right-clicks the desktop. The root menu is only displayed when using the -x command-line option. Tornoff Menu A tornoff menu is a menu that appears as a regular window. A tornoff menu is created after selecting the dashed line at the top of a popped up menu. This dashed line only appears when using the -t command-line option. Alt Key Sequences Each menu entry can be bound to a character. After pressing the alt key (set with the -a command-line option), it is possible to navigate the menus by pressing the letters of entries in sequence. Accelerator key chords Each menu entry can be bound to a key chord. Pressing a key chord enters the entry bound to it. Runner The runner is an interactive filter program (like dmenu(1) or xprompt(1)) that lists and filters its input as the user types for an entry. The runner opens ctrlmenu by pressing a key chord specified with the -r command-line option. Any menu (either the docked menu, the root menu, a tornoff menu or a popped up menu) can be browsed with the mouse, and each entry can then be clicked to be selected. After a submenu is opened, they can be navigated either using the mouse or one of the following keys: Home Select the first item in the menu. End Select the last item in the menu. Down, Tab Cycle through the items in the regular direction. Up, Shift-Tab Cycle through the items in the reverse direction. Right, Enter Select the highlighted item. Left Go to the parent menu. Esc Close any open pop up menu. RESOURCES ctrlmenu understands the following X resources. ctrlmenu.faceName The typeface to write text with. ctrlmenu.menu.background, ctrlmenu.text.background The colors of the background of the menu and the runner. ctrlmenu.menu.foreground, ctrlmenu.text.foreground The colors of the foreground of the menu and the runner. ctrlmenu.menu.selbackground, ctrlmenu.text.selbackground The colors of the background of the menu and the runner for selected entries. ctrlmenu.menu.selforeground, ctrlmenu.text.selforeground The colors of the foreground of the menu and the runner for selected entries. ctrlmenu.menu.altforeground, ctrlmenu.text.altforeground The colors of the foreground of the menu and the runner for alternate (comment) text. ctrlmenu.menu.altselforeground, ctrlmenu.text.altselforeground The colors of the foreground of the menu and the runner for alternate (comment) text in selected entries. ctrlmenu.topShadow The color of the top shadow around the menu ctrlmenu.bottomShadow The color of the bottom shadow around the menu. ctrlmenu.itemHeight The height in pixels of each item in the menus. Default is 24 pixels. ctrlmenu.iconSize The size in pixels of the icon of items. Default is 16 pixels. ctrlmenu.shadowThickness Thickness of the 3D shadow effect. ctrlmenu.gap The gap, in pixels, between the menus. ctrlmenu.maxItems The maximum number of items to be displayed in a menu. If a menu has more items than that value, the menu will feature arrow buttons for scrolling. ctrlmenu.alignment If set to left, center, or right, text is aligned to the left, center, or right of the menu, respectively. By default, text is aligned to the left. ENVIRONMENT The following environment variables affect the execution of ctrlmenu. DISPLAY The display to start ctrlmenu on. ICONPATH A colon-separated list of paths to look for icons. EXAMPLE Consider the following script: #!/bin/sh ctrlmenu -e -x "W-3" <<EOF _Applications { _Web Browser [#./icons/web.xpm] -- firefox _Image Editor [#./icons/web.xpm] -- gimp } _Terminals { Terminal (_xterm) [!A-T] -- xterm Terminal (_urxvt) [!A-U] -- urxvt Terminal (_st) [!A-S] -- st } -- _Users -- finger "" { sed 's/:.*//' /etc/passwd } _System { _Shutdown -- poweroff _Reboot -- reboot } EOF In this example, ctrlmenu is invoked with the -e command-line option, which makes the command of the selected entry to be run in sh(1). It is also invoked with the -x W-3 command-line option, which makes the main menu pop up when right-clicking on the root window (ie', the desktop), or when right-clicking anywhere with the Win (Super) key. This example creates a menu with four entries: “Applications”, “Terminal”, “Users”, and “System”. The first two entries are separated from the last two with a separator. The underline on the names of those entries indicates that pressing the key corresponding to the character after the underline selects the item. For example, pressing “S” opens the “System” submenu, and then pressing “R” selects the “Reboot” entry. On the “Applications” menu, the entries have icons specified between braces and after the “#” character. On the “Terminals” menu, the entries have keybindings specified between braces and after the “!” character. That means that, for example, pressing Alt-T opens xterm(1). The “users” menu is a pipe meta-entry. Selecting it opens a menu whose entries are read from the sed(1) command, which prints the user field of the /etc/passwd file. Selecting an entry in this menu fingers the corresponding user. OpenBSD 7.2 September 28, 2022 OpenBSD 7.2