PMENU(1)

NAME
pmenu - pie menu utility for X

SYNOPSIS
pmenu [-ew] [-d diameter] [-N name] [-x mod-button]

DESCRIPTION
pmenu 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.

The options are as follows:

-d diameter
    Specify the diameter in pixels of the pie menu.

-e  Run the output string on shell rather than writing it into standard output.

-N -name
    Specify the res_name member of the XClassHint(3) propperty. name is used to retrieve resources. If not specified, defaults to the value of the RESOURCES_NAME environment variable, or (if tha variable is not set) to the name of the command pmenu was invoked as (that is, the basename(3) of its argv[0]).

-w  Disable pointer warping when a new submenu spawns. This option is useful when using pmenu with a Wacom tablet.

-x mod-button
    This option requires an argument of the form mod-button or button; where mod is Mod1 to Mod5, or Alt (equivalent to Mod1), or Super (equivalent to Mod 4); and button is the number of a mouse button. When this option is used, pmenu 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 pmenu with the option -x 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 pmenu run continuously; so it should be used when pmenu is invoked in background on a X11 startup file (like ~/.xinitrc).

Each item read from standard input has the following format:

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

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.

•   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.

•   The image is a string of the form "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 "/", "./", or "../", the file is searched on the paths specified in the ICONPATH environment variable.

•   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.

•   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 "$" character, then 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 slices in the counterclockwise direction.

Enter
    Select the highlighted item.

Esc Close a menu.

RESOURCES
pmenu understands the following X resources. They must be prefixed with either the "PMenu" class or the name given with the -N command-line option, followed by a period.

activeBackground
    Background color for selected slices.

activeForeground
    Text color for selected slices.

background
    Background color.

borderColor
    Color of the border around pie menus.

borderWidth
    Size in pixels of the border around pie menus.

diameterWidth
    The size in pixels of the pie menu.

faceName
    Font for drawing text. If the value is prefixed with "xft:" (case insensitive), then pmenu uses the Xft(3) library for drawing text; and fallback fonts can be specified by delimiting the fonts with commas. If the value is prefixed with "x:" or "x11:" (case insensitive), then pmenu 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 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).

faceSize
    The size, in points, of the font. This only affects Xft fonts.

foreground
    Text color.

The resources below can be used to implement a motif/3D look.

shadowThickness
    Size in pixels of the 3D border.

topShadowColor, bottomShadowColor, middleShadowColor
    Colors for a Motif-like (3D) pie menu. topShadowColor is the light, top color of the border; bottomShadowColor is the dark, bottom color of the border; and middleShadowColor is the background color.

ENVIRONMENT
The following environment variables affect the execution of pmenu.

DISPLAY
    The display to start pmenu on.

ICONPATH
    A colon-separated list of directories used to search for the location of image files.

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
    <<EOF pmenu | sh &
    Apps
    	Firefox	firefox
    	Chrome	chromium
    	Vivaldi	vivaldi
    	Gimp	gimp
    Terms
    	xterm	xterm
    	urxvt	urxvt
    	st	st
    Halt	poweroff
    Reboot	reboot
    EOF

For example, by selecting “Apps”, a new menu appears. Selecting “Firefox” in the new menu opens Firefox.

SEE ALSO
xmenu(1)