pmenu.1

.Dd May 20, 2023
.Dt PMENU 1
.Os
.Sh NAME
.Nm pmenu
.Nd pie menu utility for X
.Sh SYNOPSIS
.Nm pmenu
.Op Fl ew
.Op Fl d Ar diameter
.Op Fl N Ar name
.Op Fl x Ar mod-button
.Sh DESCRIPTION
.Nm
is a pie menu for X11,
it reads a list of newline-separated items from standard input,
shows a pie menu for the user to select one of the items,
and writes the selected item into standard output.
The pie menu contains one slice for each item.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d Ar diameter
Specify the diameter in pixels of the pie menu.
.It Fl e
Run the output string on shell rather than writing it into standard output.
.It Fl N name
Specify the
.Ic res_name
member of the
.Xr XClassHint 3
propperty.
.Ar name
is used to retrieve resources.
If not specified, defaults to the value of the
.Ev RESOURCES_NAME
environment variable, or (if tha variable is not set)
to the name of the command
.Nm
was invoked as
(that is, the
.Xr basename 3
of its
.Ic "argv[0]" ) .
.It Fl w
Disable pointer warping when a new submenu spawns.
This option is useful when using
.Nm
with a Wacom tablet.
.It Fl x Ar mod-button
This option requires an argument of the form
.Ar mod-button
or
.Ar button ;
where
.Ar mod
is
.Ic Mod1
to
.Ic Mod5 ,
or
.Ic Alt
(equivalent to
.Ic Mod1 ) ,
or
.Ic Super
(equivalent to
.Ic Mod 4 ) ;
and
.Ar button
is the number of a mouse button.
When this option is used,
.Nm
listens to button presses on the root window,
and shows the pie menu when the given button is pressed,
together with the given modifier, on the root window.
For example, invoking
.Nm
with the option
.Fl x Cm Super-3
makes a menu open when clicking with the third mouse button on the root window,
or when clicking with the third mouse button together with the Super (Mod4) modifier on any window.
This option makes
.Nm
run continuously; so it should be used when
.Nm
is invoked in background on a X11 startup file (like
.Pa "~/.xinitrc" ) .
.El
.Pp
Each item read from standard input has the following format:
.Bd -literal -offset indent
ITEM := [TABS] [IMAGE TAB] LABEL [TAB OUTPUT] NEWLINE
.Ed
.Pp
That means that each item is composed by tabs,
followed by an image specification,
fllowed by a tab and a label,
followed by a tab and an output string,
and ended by a newline.
Brackets group optional elements.
.Bl -bullet
.It
The initial tabs indicate the menu hierarchy:
items indented with a tab are shown in a submenu of thepreceding item not indented.
An item without initial tabs is a top-level item.
.It
The image is a string of the form
.Qq Ic "IMG:/path/to/image.png" .
It specifies the path to an image file to be shown as icon in the slice.
If the path does not begin with
.Qq Pa "/" ,
.Qq Pa "./" ,
or
.Qq Pa "../" ,
the file is searched on the paths specified in the
.Ev ICONPATH
environment variable.
.It
The label is the string that will be shown as an item in the menu.
If the item includes an icon, then no label is shown on the menu;
however, a tooltip with the label pops up when hovering the icon.
.It
The output string is the string that will be output after selecting the item.
If an item does not have an output string, its label is used as its output string.
If the output strings begins with the
.Qq Ic "$"
character, then this string represents a command that will be run by
.Nm
using
.Xr popen 3
and whose output will be used to generate a submenu.
.It
The newline terminates the item specification
.El
.Sh USAGE
.Nm
is controlled by the mouse, but can also be controlled by the keyboard.
Pie slices can be selected using
.Ic Tab
(with and without
.Ic Shift ) ,
.Ic Enter
and
.Ic Esc .
.Bl -tag -width Ds
.It Ic Tab
Cycle through the slices in the clockwise direction.
.It Ic Shift-Tab
Cycle through the slices in the counterclockwise direction.
.It Ic Enter
Select the highlighted item.
.It Ic Esc
Close a menu.
.El
.Sh RESOURCES
.Nm
understands the following X resources.
They must be prefixed with either the
.Qq Ic PMenu
class or the name given with the
.Fl N
command-line option, followed by a period.
.Bl -tag -width Ds
.It Ic activeBackground
Background color for selected slices.
.It Ic activeForeground
Text color for selected slices.
.It Ic background
Background color.
.It Ic borderColor
Color of the border around pie menus.
.It Ic borderWidth
Size in pixels of the border around pie menus.
.It Ic diameterWidth
The size in pixels of the pie menu.
.It Ic faceName
Font for drawing text.
If the value is prefixed with
.Qq Ic "xft:"
(case insensitive), then
.Nm
uses the
.Xr Xft 3
library for drawing text;
and fallback fonts can be specified by delimiting the fonts with commas.
If the value is prefixed with
.Qq Ic "x:"
or
.Qq Ic "x11:"
(case insensitive), then
.Nm
uses the X11 library for drawing text;
if only one font is specified, regular X11 fonts are used;
if two or more fonts are specified (delimited with commas), a
.Ft XFontSet
is used (but that is not reliable, and depends on the locale,
so it is better to not use more than one X11 font).
.It Ic faceSize
The size, in points, of the font.
This only affects Xft fonts.
.It Ic foreground
Text color.
.El
.Pp
The resources below can be used to implement a motif/3D look.
.Bl -tag -width Ds
.It Ic shadowThickness
Size in pixels of the 3D border.
.It Ic topShadowColor , bottomShadowColor , middleShadowColor
Colors for a Motif-like (3D) pie menu.
.Ic topShadowColor
is the light, top color of the border;
.Ic bottomShadowColor
is the dark, bottom color of the border;
and
.Ic middleShadowColor
is the background color.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
.Bl -tag -width Ds
.It Ev DISPLAY
The display to start
.Nm
on.
.It Ev ICONPATH
A colon-separated list of directories used to search for the location of image files.
.El
.Sh EXAMPLES
The following script illustrates the use of
.Nm .
The output is redirected to
.Xr sh 1 ,
creating a command to be run by the shell.
.Bd -literal -offset indent
#!/bin/sh

<<EOF pmenu | sh &
Apps
	Firefox	firefox
	Chrome	chromium
	Vivaldi	vivaldi
	Gimp	gimp
Terms
	xterm	xterm
	urxvt	urxvt
	st	st
Halt	poweroff
Reboot	reboot
EOF
.Ed
.Pp
For example, by selecting
.Dq "Apps" ,
a new menu appears.
Selecting
.Dq "Firefox"
in the new menu opens Firefox.
.Sh SEE ALSO
.Xr xmenu 1