ctrlmenu.1

.Dd September 28, 2022
.Dt CTRLMENU 1
.Os
.Sh NAME
.Nm ctrlmenu
.Nd unified menu system for X11
.Sh SYNOPSIS
.Nm
.Op Fl dit
.Op Fl a Ar keysym
.Op Fl r Ar keychord
.Op Fl x Ar buttonspec
.Op Ar file
.Sh DESCRIPTION
.Nm
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.
.Pp
If no
.Ar file
argument is given, or if it is a hyphen
.Dq "\-" ,
.Nm
reads from standard input.
.Pp
The options are as follows
.Bl -tag -width Ds
.It Fl a Ar keysym
Enable the altkey input.
The argument
.Ar 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
.Sx USAGE
for more information on the alt key.
.It Fl d
Enable the dockapp.
This option makes
.Dn
show a docked menu on the window manager's dock.
See the section
.Sx USAGE
for more information on the docked menu.
.It Fl i
Match entries case insensitively on the runner.
.It Fl t
Enable tornoff menus.
This option can only be used together with
.Fl d
and/or
.Fl x .
See the section
.Sx USAGE
for more information on the tornoff menus.
.It Fl r Ar keychord
The argument
.Ar keychord
must be the keychord to invoke the runner
.Ns ( Cm "A\-space" ,
by default).
The keychord must be a keysym, prefixed with
.Sy C-
(for Control),
.Sy S-
(for Shift),
.Sy A-
(for Alt),
.Sy W-
(for Super/Win).
See the section
.Sx USAGE
for more information on the runner.
.It Fl x Ar buttonspec
Enable root menu.
This option makes
.Nm
show the menu when clicking on the desktop
or clicking anywhere with a given modifier.
The argument
.Ar buttonspec
must be an optional button number
(or nothing for button 3, the right button),
prefixed with
.Sy "C\-"
(for Control),
.Sy "S\-"
(for Shift),
.Sy "A\-"
(for Alt),
.Sy "W\-"
(for Super/Win),
.Sy "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
.Sy "P"
to indicate that the click to the root window should be passed to other clients.
See the section
.Sx USAGE
for more information on the root menu.
.El
.Pp
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:
.Pp
.Bd -literal -offset indent
ENTRY       := SEPARATOR | TERMINAL | META | PIPE
SEPARATOR   := "--\en"
TERMINAL    := NAME ["--" COMMAND] "\en"
META        := NAME "{\en" ENTRIES... "}\en"
PIPE        := NAME "--" COMMAND "{\en" SCRIPT "}\en"
.Ed
.Pp
.Bl -tag -width Ds
.It Separator
A separator is an anonymous, non-selectable entry in the menu.
Separators are composed by a line with only two dashes in it.
.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.
.It 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.
.It 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.
.El
.Pp
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:
.Pp
.Bd -literal -offset indent
NAME        := LABEL [ "[" LIST "]" ]
LIST        := | EXTENSION ":" LIST
EXTENSION   := KEYBINDING | ICON | DESCRIPTION
ICON        := "#" PATH
KEYBINDING  := "!" ("S-" | "C-" | "A-" | "W-") KEYSYM
DESCRIPTION := STRING
.Ed
.Pp
The
.Sy LABEL
is the string that will appear in the menu.
The label can contain a underscore
.Pq Dq "_"
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.
.Pp
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
.Dq "#"
character to indicate that it is the path to an icon.
.Pp
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
.Dq "!"
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
.Dq "S-"
prefix indicates that the
.Ic "Shift"
key modifier is active.
An
.Dq "C-"
prefix indicates that the
.Ic "Control"
key modifier is active.
An
.Dq "A-"
prefix indicates that the
.Ic "Alt"
key modifier is active.
An
.Dq "W-"
prefix indicates that the
.Ic "Super"
(Also known as
.Dq "windows key" )
key modifier is active.
The keysym that forms the ending of the keybinding is one of the keysyms listed at
the
.Pa "/usr/X11R6/include/X11/keysymdef.h"
file
.Pq Pa "/usr/include/X11/keysymdef.h" No in some systems.
.Pp
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.
.Sh USAGE
The following input methods are provided by
.Nm
.Bl -tag -width Ds
.It 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
.Fl d
command-line option.
The docked menu only works on window managers that docks dockapps,
such as
.Xr fluxbox 1 .
.It 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
.Fl x
command-line option.
.It 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
.Fl t
command-line option.
.It Alt Key Sequences
Each menu entry can be bound to a character.
After pressing the alt key (set with the
.Fl a
command-line option),
it is possible to navigate the menus by pressing the letters of entries in sequence.
.It Accelerator key chords
Each menu entry can be bound to a key chord.
Pressing a key chord enters the entry bound to it.
.It Runner
The runner is an interactive filter program (like
.Xr dmenu 1
or
.Xr xprompt 1 )
that lists and filters its input as the user types for an entry.
The runner opens
.Nm
by pressing a key chord specified with the
.Fl r
command-line option.
.El
.Pp
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:
.Bl -tag -width Ds
.It Ic "Home"
Select the first item in the menu.
.It Ic "End"
Select the last item in the menu.
.It Ic "Down, Tab"
Cycle through the items in the regular direction.
.It Ic "Up, Shift-Tab"
Cycle through the items in the reverse direction.
.It Ic "Right, Enter"
Select the highlighted item.
.It Ic "Left"
Go to the parent menu.
.It Ic "Esc"
Close any open pop up menu.
.El
.Sh RESOURCES
.Nm
understands the following X resources.
.Bl -tag -width Ds
.It Ic "ctrlmenu.faceName"
The typeface to write text with.
.It Ic "ctrlmenu.menu.background" , Ic "ctrlmenu.text.background"
The colors of the background of the menu and the runner.
.It Ic "ctrlmenu.menu.foreground" , Ic "ctrlmenu.text.foreground"
The colors of the foreground of the menu and the runner.
.It Ic "ctrlmenu.menu.selbackground" , Ic "ctrlmenu.text.selbackground"
The colors of the background of the menu and the runner for selected entries.
.It Ic "ctrlmenu.menu.selforeground" , Ic "ctrlmenu.text.selforeground"
The colors of the foreground of the menu and the runner for selected entries.
.It Ic "ctrlmenu.menu.altforeground" , Ic "ctrlmenu.text.altforeground"
The colors of the foreground of the menu and the runner for alternate (comment) text.
.It Ic "ctrlmenu.menu.altselforeground" , Ic "ctrlmenu.text.altselforeground"
The colors of the foreground of the menu and the runner for alternate (comment) text in selected entries.
.It Ic "ctrlmenu.topShadowColor"
The color of the top shadow around the menu
.It Ic "ctrlmenu.bottomShadowColor"
The color of the bottom shadow around the menu.
.It Ic "ctrlmenu.itemHeight"
The height in pixels of each item in the menus.
Default is 24 pixels.
.It Ic "ctrlmenu.iconSize"
The size in pixels of the icon of items.
Default is 16 pixels.
.It Ic "ctrlmenu.shadowThickness"
Thickness of the 3D shadow effect.
.It Ic "ctrlmenu.gap"
The gap, in pixels, between the menus.
.It Ic "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.
.It Ic "ctrlmenu.alignment"
If set to
.Sy "left" Ns ,
.Sy "center" Ns ,
or
.Sy "right" Ns ,
text is aligned to the left, center, or right of the menu, respectively.
By default, text is aligned to the left.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm Ns .
.Bl -tag -width Ds
.It DISPLAY
The display to start
.Nm
on.
.It ICONPATH
A colon-separated list of paths to look for icons.
.El
.Sh EXAMPLE
Consider the following script:
.Bd -literal -offset indent
#!/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
.Ed
.Pp
In this example,
.Nm
is invoked with the
.Fl e
command-line option, which makes the command of the selected entry to be run in
.Xr sh 1 .
It is also invoked with the
.Fl x Cm "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.
.Pp
This example creates a menu with four entries:
.Dq "Applications" ,
.Dq "Terminal" ,
.Dq "Users" ,
and
.Dq "System" .
The first two entries are separated from the last two with a separator.
.Pp
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
.Dq "S"
opens the
.Dq "System"
submenu,
and then pressing
.Dq "R"
selects the
.Dq "Reboot"
entry.
.Pp
On the
.Dq Applications
menu, the entries have icons specified between braces and after the
.Dq "#"
character.
.Pp
On the
.Dq "Terminals"
menu, the entries have keybindings specified between braces and after the
.Dq "!"
character.
That means that, for example, pressing
.Ic "Alt-T"
opens
.Xr xterm 1 .
.Pp
The
.Dq "users"
menu is a pipe meta-entry.
Selecting it opens a menu whose entries are read from the
.Xr sed 1
command, which prints the user field of the
.Pa "/etc/passwd"
file.
Selecting an entry in this menu fingers the corresponding user.
.El