NAME

pmenu - pie menu utility for X

SYNOPSIS

pmenu [-pw] [-m modifier] [-r button]

DESCRIPTION

pmenu is a pie menu for X, it reads a list of newline-separated items from stdin, shows a pie menu for the user to select one of the items, and outputs the item selected to stdout. The pie menu contains one slice for each item.

The options are as follows:

-m modifier: Use the button click specified by the -r option with the given modifier number to spawn the pie menu. For example, if calling pmenu with the -r 3 -m 4 options, the pie menu will be displayed when clicking any window with the right mouse button and the Mod4 modifier (usually the Super key). this option only makes sense when -r is used.
-p: When -r is used, pass the click to the root window, for the window manage to use it, for example. This option only makes sense when -r is used.
-r: When this option is used, pmenu listens to button presses on the root window, and shows the pie menu when the button (a number between 1 and 3) is pressed on the root window. This option makes menu run continuously, so it should be run in background on a X startup file (like ~/.xinitrc, ~/.xprofile, etc).
-w: Disable pointer warping when a new submenu spawns. This option is useful when using pmenu with a Wacom tablet.
-P: Prefix any relative paths given for images with this text. Must end with a '/' character.

Each item read from stdin has the following format:

ITEM := [TABS] [IMAGE TABS] LABEL [TABS OUTPUT] NEWLINE

That means that each item is composed by tabs, followed by an image specification, followed by more tabs and a label, followed by more tabs and an output, and ended by a newline. Brackets group optional elements.

: The initial tabs indicate the menu hierarchy: items indented with a tab are shown in a submenu of the preceding item not indented. An item without initial tabs is a top-level item.
: The image is a string of the form "IMG:/path/to/image.png". It specifies a image to be shown as icon in the slice.
: The label is the string that will be shown as a item in the menu. If the item includes a icon, then no label is shown on the menu; however, a tooltip with the label pops up when hovering the icon.
: The output is the string that will be output after selecting the item. If an item does not have an output, its label is used as its output. If the output begins with the $ character, than this string represents a command that will be run by pmenu using popen(3) and whose output will be used to generate a submenu.
: The newline terminates the item specification.

USAGE

pmenu is controlled by the mouse, but can also be controlled by the keyboard. Pie slices can be selected using Tab (with and without Shift), Enter and Esc.

Tab: Cycle through the slices in the clockwise direction.
Shift-Tab: Cycle through the items in the anticlockwise direction.
Enter: Select the highlighted item.
Esc: Go to the menu above or exit pmenu.

RESOURCES

pmenu understands the following X resources.

pmenu.font: The font in which the labels should be drawn.
pmenu.background: The background color of non-selected slices in the menu.
pmenu.foreground: The color of the label text of non-selected slices in the menu.
pmenu.selbackground: The background color of selected slices in the menu.
pmenu.selforeground: The color of the label text of selected slices in the menu.
pmenu.border: The color of the border around the menu.
pmenu.separator: The color of the separator between slices in the menu.
pmenu.borderWidth: The size in pixels of the border around the menu.
pmenu.separatorWidth: The size in pixels of the slice separator.
pmenu.diameterWidth: The size in pixels of the pie menu.

EXAMPLES

The following script illustrates the use of pmenu. The output is redirected to sh(1), creating a command to be run by the shell.

#!/bin/sh
cat <<EOF | pmenu | sh &
Applications
	IMG:./firefox.png	Firefox Browser		firefox-esr
	IMG:./chrome.png	Chrome Browser		chromium
	IMG:./vivaldi.png	Vivaldi Browser		vivaldi
	IMG:./gimp.png	        Image Editor		gimp
Terminal (xterm)					xterm
Terminal (urxvt)					urxvt
Terminal (st)						st
Shutdown						poweroff
Reboot							reboot
EOF