PMENU(1)

pmenu(1) — General Commands Manual ✨ okay bestie, this is the pie menu utility for X that’s about to make your menus feel very main character 💅

🥧 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, fr fr. It reads a list of newline-separated items from standard input, shows a pie menu so the user can select one of the items, and writes the selected item into standard output. The pie menu contains one slice for each item. Iconic behavior, no cap.

🎀 The options are as follows:

• -d diameter — specify the diameter in pixels of the pie menu. Big pie energy 🥧
• -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) property. name is used to retrieve resources. If not specified, defaults to the value of the RESOURCES_NAME environment variable, or (if that variable is not set) to the name of the command pmenu was invoked as (that is, the basename(3) of its argv[0]). Yes, -name stays exactly like that bestie 🫶
• -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).

lowkey important: -x makes pmenu keep running continuously, so it’s the one you want in your X11 startup file situation 💖

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, followed 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 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 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 string 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. Keyboard girlies are so valid 🌸

• 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. Resource-core, honestly 🎀

• 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. Very retro-chic 👑

• 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. Submenu inception, slay 🦋

👀 SEE ALSO

xmenu(1)

---

that’s the whole page, bestie — source/version vibes: Debian, May 20, 2023, PMENU(1). go slay your menus 💅🫶