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