PMENU(1)

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

For example, by selecting “Applications”, a new menu will appear. Selecting “Firefox Browser” in the new menu opens firefox.

SEE ALSO
xmenu(1)