JGMENU(1)

✨ NAME ✨

jgmenu — A simple X11 menu 💖

Bestie, this is the whole vibe: a lil graphical menu for Linux/BSD that reads your menu data as CSV and pops it onto an X11 window. That's it. That's the girl. 👑

---

🌸 SYNOPSIS 🌸

jgmenu [--no-spawn] [--checkout=<tag>] [--config-file=<file>]
       [--icon-size=<size>] [--at-pointer] [--hide-on-startup]
       [--simple] [--vsimple] [--csv-file=<file>]
       [--csv-cmd=<command>] [--die-when-loaded]
       [--center] [--persistent]

okay so here's the starter pack, the "just tell me what to type" moment 🫶

• jgmenu_run — Launch menu
• jgmenu_run init — Create config file ~/.config/jgmenu/jgmenurc
• jgmenu_run init -i — Interactive setup
• man jgmenututorial — Step-by-step tutorial

---

🦋 DESCRIPTION 🦋

jgmenu is a simple menu for Linux/BSD. It reads CSV menu data from a file and generates a graphical menu on an X11 window. No cap, that's literally the entire personality.

💫 Fields 💫

Each line of CSV menu data is parsed into the following fields using comma as a field separator:

1. description
2. command
3. icon
4. working directory
5. metadata

For example:

printf "Terminal,xterm\\nWeb Browser,firefox" | jgmenu --vsimple

🎀 Special Characters at beginning of line 🎀

• # — Ignore line
• . — A line beginning with a dot followed by a space, will source the file specified by the string following the dot
• @ — Treat as widget

🍓 Special Characters in fields 🍓

• , — As commas are used as field separators, individual fields can only contain commas if they are triple quoted. For example:

foo,“““^pipe(find .  -printf `%f,display %p,%p\n')”“”

• < > & — The description field is parsed as pango markup, so <, >, and & need to be escaped as <, >, and & respectively.
• " — Unlike most CSV implementations, a single instance of a double quote (") is not considered a special character. The reason for this is to let users write commands with double quotes without having to escape them.
• """ — Use three quotes """ to begin and to end a fully quoted value. The primary use case for this is when a comma is needed within a value.

🧚 Markup 🧚

The syntax ^foo(bar) is used to carry out action foo with argument bar. We refer to bar as the inner value.

The following markup is supported in the description field

• sep() — Define a separator. If an inner value is provided, the separator will appear as a title. If no inner value is provided, the separator will simply be a horizontal line

The following markup is supported in the command field

• ^tag() — Define the beginning of a new menu structure node.

The lines following ^tag(whatever) will not show in the top level menu, but can be opened by using ^checkout() or ^root().

item0.0
item0.1
submenu1,^checkout(1)
submenu2,^root(2)

^tag(1)
item1.0
item1.1

^tag(2)
item2.0
item2.1

• ^checkout() — Open the tag specified by the inner value as a submenu in a new window
• ^root() — Open the tag specified by the inner value in the root window, replacing the current menu
• ^sub() — Draw a submenu arrow. This can be useful for creating submenus with stay_alive=0. For example:

item0.0
item0.1
submenu1,^sub(echo "item1.0" | jgmenu --simple)

• ^back() — Check-out parent menu
• ^term() — Run program in terminal
• ^pipe() — Execute sub-process and checkout a menu based on its stdout.
• ^filter() — Invoke search
• ^quit() — Quit

💅 Icons 💅

Icons will be displayed if the third field is populated, for example:

Terminal,xterm,utilities-terminal
Firefox,firefox,firefox

---

🌈 OPTIONS 🌈

• --no-spawn — Redirect command to stdout rather than execute it.
• --checkout=<tag> — Checkout submenu on startup.
• --config-file=<file> — Read config file.
• --icon-size=<size> — Specify icon size (22 by default). If set to 0, icons will not be loaded.
• --at-pointer — Launch menu at mouse pointer.
• --hide-on-startup — Start menu is hidden state.
• --simple — Ignore tint2 settings; Run in short-lived mode (i.e. exit after mouse click or enter/escape); read menu items from stdin.
• --vsimple — Same as --simple, but also disables icons and ignores jgmenurc.
• --csv-file=<file> — Specify menu file (in jgmenu flavoured CSV format). If file cannot be opened, input is reverted to stdin.
• --csv-cmd=<command> — Specify command to produce menu data, for example jgmenu_run pmenu
• --die-when-loaded — Open menu and then exit(0). Useful for debugging and testing.
• --center — Center align menu horizontally and vertically.
• --persistent — Same as the persistent config option. See config option section below for details.

---

💖 USER INTERFACE 💖

• Up, Down — Select previous/next item
• Left. Right — Move to parent/sub menu
• PgUp, PgDn — Scroll up/down
• Home, End — Select first/last item
• Enter — Select an item or open a submenu
• F5 — Restart
• F8 — Print node tree to stderr
• F9 — exit(1)
• F10 — exit(0)
• Backspace — Return to parent menu

Type any string to invoke a search. Words separated by space will be searched for using OR logic (i.e. the match of either word is sufficient to display an item). 🔍✨

---

⭐ WIDGETS ⭐

Lines beginning with @ in jgmenu flavoured CSV files are parsed in accordance with the following syntax:

@type,action,x,y,w,h,r,halign,valign,fgcol,bgcol,content

• type — The widget type, which can be one of the following:
  • rect — Rectangle with a 1px thick border drawn using fgcol
  • search — Search box showing the current filter (what the user has typed) or the specified text if no filter has been invoked.
  • icon — Icon
• action — The action to take when selected. This can either be a shell command or a menu action such ^root().
• x, y — Horizontal and vertical margin of widget
• w, h — Width and height of widget
• r — Corner radius
• fgcol, bgcol — Foreground and background colours using syntax rrggbb #aa fgcol accepts auto to use the jgmenurc’s color_norm_fg
• content — icon_path for icon widgets text for all other widget types
• halign, valign — Horizontal and vertical alignment of widget. This has not yet been implemented, but defaults to top and left

---

🫶 CONFIGURATION FILE 🫶

If no file is specified using the –config-file= option, the XDG Base Directory Specification is adhered to. I.e:

• Global config in ${XDG_CONFIG_DIRS:-/etc/xdg}
• User config override in ${XDG_CONFIG_HOME:-$HOME/.config}

For most users ~/.config/jgmenu/jgmenurc is appropriate.

Global config variables are set in the following order (i.e. bottom of list has higher precedence):

• built-in defaults (config.c)
• tint2rc config file (can be specified by TINT2_CONFIG environment variable)
• jgmenurc config file (can be specified by –config-file=)
• command line arguments

🦄 Syntax 🦄

Lines beginning with # are ignored.

All other lines are recognised as setting variables in the format

key = value

White spaces are mostly ignored.

🌸 Values 🌸

Unless otherwise specified, values as treated as simple strings.

Here follow some specific types:

• boolean — When a variable takes a boolean value, only 0 and 1 are accepted. 0 means false; 1 means true.
• integer — When a variable takes an integer value, only numerical values are accepted. The only valid characters are digits (0-9) and minus-sign. All integer variables relating to geometry and position are interpreted as pixel values unless otherwise specified.
• color — When a variable takes a color value, only the syntax #rrggbb aaa is recognised, where rr, gg and bb represent hexadecimal values (00-ff) for the colours red, green and blue respectively; and aaa stands for the alpha channel value expressed as a percentage (0-100) (i.e. 100 means no transparency and 0 means fully transparent.) For example #ff0000 100 represents red with no transparency, whereas #000088 50 means dark blue with 50% transparency.
• pathname — When a variable takes a pathname value, it is evaluated as a string. If the first character is tilde (~), it will be replaced by the the environment variable $HOME just as a shell would expand it.

👑 Variables 👑

• verbosity = integer (default 0) — General verbosity: (0) warnings only; (1) basic info; (2) more info; (3) max info

Additional specific topics: (4) IPC

Note: Some IPC messages need environment variable JGMENU_VERBOSITY=4 too

• stay_alive = boolean (default 1) — If set to 1, the menu will “hide” rather than “exit” when the following events occur: clicking on menu item; clicking outside the menu; pressing escape. When in the hidden mode, a USR1 signal will “un-hide” the menu.
• persistent = boolean (default 0) — If set to 1, the menu will not exit nor hide when the following events occur: clicking on menu item; clicking outside the menu; pressing escape. Use in conjunction with the ^quit() markup.
• hide_on_startup = boolean (default 0) — If set to 1, jgmenu start in “hidden” mode. This is useful for starting jgmenu during the boot process and then sending a killall -SIGUSR1 jgmenu to show the menu.
• csv_cmd = string (default apps) — Defines the command to produce the jgmenu flavoured CSV for jgmenu. Accpetable keyword include apps, pmenu, lx, and ob. If a value is given other than these keywords, it will be executed in a shell (so be careful!). If left blank, jgmenu will read from stdin. Examples:

csv_cmd = lx
csv_cmd = jgmenu_run lx --no-dirs
csv_cmd = cat ~/mymenu.csv

• tint2_look = boolean (default 0) — Read tint2rc and parse config options for colours, dimensions and alignment.
• position_mode = (fixed | ipc | pointer | center) (default fixed) — Define menu positioning mode.
  • fixed — Align to margin_{x,y} and respect _NET_WORKAREA.
  • ipc — Use IPC to read environment variables set by panel. See Inter-Process Communication for further info.
• pointer — launch at the pointer, whilst respecting both _NET_WORKAREA and edge_snap_x. Bestie behaviour, honestly 🫶
• center — launch at the center of the screen and straight-up ignore _NET_WORKAREA. This one takes precedence over menu_{v,h}align. Periodt. 👑

---

• edge_snap_x = integer (default 30) — how close (in pixels) you can get to the left hand edge before the menu just snaps to it. Heads up though: this only applies in at_pointer mode. 💅
• terminal_exec = string (default x-terminal-emulator) — the terminal to use for commands with ^term() markup.
• terminal_args = string (default -e) — okay so these two variables team up to build the string that launches programs needing a terminal. With the default values, that string becomes:

x-terminal-emulator -e 'some_command with arguments'

And terminal_args must finish with -e or an equivalent, where -e refers to the meaning of -e in xterm -e. No cap. 🔥

• monitor = integer (default 0) — pick a particular monitor as an index starting from 1. If it's 0, the menu launches on whichever monitor the mouse is on. Main character mouse energy 🐭
• hover_delay = integer (default 100) — the time (in milliseconds) from hovering over an item until a submenu opens. Impatient? Lower it. 😌
• hide_back_items = boolean (default 1) — if enabled, all ^back() items get suppressed. As a general rule: set it to 1 for a multi-window menu, and 0 when you're in single-window mode.
• columns = integer (default 1) — number of columns in which to show menu items.
• tabs = integer (default 120) — the position, in pixels, of the first tab.
• menu_margin_x = integer (default 0) — distance between the menu (that's the X11 window, bestie) and the edge of the screen. See the note on _NET_WORKAREA under the menu_{v,h}align variables. 📏
• menu_margin_y = integer (default 0) — the vertical equivalent of menu_margin_x.
• menu_width = integer (default 200) — the minimum menu width. The actual width will adjust to fit the longest item in the current (sub)menu. But if a filter is applied (e.g. by the user typing) the menu width will not adjust. She's committed to the bit. 💅
• menu_height_min = integer (default 0) — set the minimum height of the root menu. If menu_height_min and menu_height_max are set to the same value, the menu height will be fixed at that value. If set to zero, they'll be ignored.
• menu_height_max = integer (default 0) — "Minimum height of the root menu. See menu_height_min". Yes, it literally says minimum here 🙈 the docs said what they said, we don't make the rules.
• menu_height_mode = (static | dynamic) (default static) — mode of menu height.
  • static — the height of the initial root menu will be used for any subsequent ^root() action.
  • dynamic — the root menu height gets re-calculated every time a new tag is opened using ^root().
• menu_padding_top = integer (default 5) — distance between top border and item/widget.
• menu_padding_right = integer (default 5) — distance between right border and item/widget.
• menu_padding_bottom = integer (default 5) — distance between bottom border and item/widget.
• menu_padding_left = integer (default 5) — distance between left border and item/widget.
• menu_radius = integer (default 1) — radius of the menu's rounded corners. Rounded corners are so cute, obsessed 🎀
• menu_border = integer (default 0) — thickness of the menu border.
• menu_halign = (left | right | center) (default left) — horizontal alignment of the menu. If it's not set, jgmenu will try to guess the alignment by reading _NET_WORKAREA, which is a freedesktop EWMH root window property. And here's the tea: not all Window Managers and Panels respect _NET_WORKAREA. The following do: openbox, xfwm4, tint2 and polybar. The following do NOT: awesome, i3, bspwm and plank. Noted 📝
• menu_valign = (top | bottom | center) (default bottom) — vertical alignment of the menu. See menu_halign.
• menu_gradient_pos = (none | top | right | bottom | left | top_left | top_right | bottom_left | bottom_right ) (default none) — start position of the menu window gradient. The end position is at the opposite side or corner. The colours color_menu_bg and color_menu_bg_to specify the start (from) and the finish (to). It's giving sunset 🌅
• sub_spacing = integer (default 1) — horizontal space between windows. A negative value results in each submenu window overlapping its parent window. Chaotic, love that for you 💀
• sub_padding_top = integer (default auto) — same as menu_padding_top but it applies to submenu windows only. It understands the keyword auto, which means the smallest of the four menu_padding_* variables will be used.
• sub_padding_right = integer (default auto) — see sub_padding_top.
• sub_padding_bottom = integer (default auto) — see sub_padding_top.
• sub_padding_left = integer (default auto) — see sub_padding_top.
• sub_hover_action = integer (default 1) — open a submenu when hovering over an item. Note that this only works in multi-window mode.
• item_margin_x = integer (default 3) — horizontal distance between items and the edge of the menu.
• item_margin_y = integer (default 3) — vertical distance between items and the edge of the menu.
• item_height = integer (default 25) — height of menu items.
• item_padding_x = integer (default 4) — horizontal distance between the item edge and its content (e.g. text or icon).
• item_radius = integer (default 1) — radius of rounded corners of items.
• item_border = integer (default 0) — thickness of item border.
• item_halign = (left | right) (default left) — horizontal alignment of menu items. If you set it to right, you should change the arrow_string option too. Just saying 👀
• sep_height = integer (default 5) — height of a separator without text (as defined by ^sep()). Separators with text use item_height.
• sep_halign = (left | center | right) (default left) — horizontal alignment of separator text.
• sep_markup = string (unset by default) — if specified, <span $sep_markup>foo</span> will be passed to pango for ^sep(foo).

See the following link for pango attributes: https://docs.gtk.org/Pango/pango_markup.html

Keywords include (but are not limited to):

• font
• size (x-small, small, medium, large, x-large) - style (normal, oblique, italic)
• weight (ultralight, light, normal, bold, ultrabold, heavy
• foreground (using format #rrggbb or a colour name)
• underline (none, single, double)

Example:

sep_markup = font="Sans Italic 12" foreground="blue"

• font = string (unset by default) — font description for menu items. font accepts a string such as Cantarell 10 or UbuntuCondensed 11. The font description without a specified size unit is interpreted as points. If px is added, it will be read as pixels. Using "points" enables consistency with other applications. Slay ✨
• font_fallback = string (default xtg) — same as icon_theme_fallback, except that the xsettings variable Gtk/FontName is read.
• icon_size = integer (default 22) — size of icons in pixels. If set to 0, icons will be disabled. 😭
• icon_text_spacing = integer (default 10) — distance between icon and text within a menu item.
• icon_norm_alpha = integer (default 100) — opacity of menu item icons, expressed as a percentage (0-100).
• icon_sel_alpha = integer (default 100) — opacity of the currently selected menu item's icon, expressed as a percentage (0-100).
• icon_theme = string (unset by default) — name of icon theme. E.g. Adwaita, breeze, Paper, Papirus and Numix. See ls /usr/share/icons/ (or similar) for the available icon themes on your system.
• icon_theme_fallback = string (default xtg) — fallback sources of the icon theme, in order of precedence, where the left-most letter designates the source with the highest precedence. The following characters are acceptable: x=xsettings Net/IconThemeName; t=tint2; g=gtk3.0. icon_theme takes priority if set. And in order to increase consistency with tint2, xsettings variables will only be read if the tint2rc variable launcher_icon_theme_override is 0.
• arrow_string = string (default ▸) — the string used to indicate that an item will open a submenu. See jgmenuunicode(7) for examples.
• arrow_width = integer (default 15) — width allowed for arrow_string. Set to 0 to hide the arrow.
• search_empty_string = string (default <empty>) — the string to show when no entries match a search. It's giving "she's not here" 💀
• color_menu_bg = color (default #000000 100) — background colour of the menu window. If gradients are enabled, this will be the 'from' color.
• color_menu_bg_to = color (default #000000 100) — background 'to' colour of the menu window, for use with gradients.
• color_menu_border = color (default #eeeeee 8) — border colour of the menu window.
• color_norm_bg = color (default #000000 0) — background colour of menu items, except the one currently selected.
• color_norm_fg = color (default #eeeeee 100) — font (foreground) colour of menu items, except the one currently selected.
• color_sel_bg = color (default #ffffff 20) — background color of the currently selected menu item.
• color_sel_fg = color (default #eeeeee 100) — font (foreground) color of the currently selected menu item.
• color_sel_border = color (default #eeeeee 8) — border color of the currently selected menu item.
• color_sep_fg = color (default #ffffff 20) — font (foreground) colour of separators without text.
• color_title_fg = color (default #eeeeee 50) — font (foreground) colour of separators with text. The font colour can be overridden by sep_markup.
• color_title_bg = color (default #000000 0) — background colour of separators with text.
• color_title_border = color (default #000000 0) — border colour of separators with text.
• color_scroll_ind = color (default #eeeeee 40) — colour of the scroll indicator lines (the little ones that show whether there are menu items above or below the ones you can actually see). 🌈

---

🌈 CSV generator variables 🌈

The following variables begin with csv_, which denotes that they set environment variables which are used by the CSV generators. Teamwork, honestly 🫶

• csv_name_format = string (default %n (%g)) — defines the format of the name field for CSV generators. Supported by apps and lx. It understands the following two fields:
  • %n — Application name
• %g — the application's generic name. And if there's no generic name, or it's literally identical to the name? Then %n gets used instead, with zero formatting. no drama. 💅

---

• csv_single_window = boolean (default 0) — flip this on and csv-generators will spit out ^root() instead of ^checkout(). Translation: you get a single window menu where the submenus show up in the same window instead of spawning new ones. Supported by apps and pmenu. one window, one vibe 🪟
• csv_no_dirs = boolean (default 0) — set it and csv-generators will output applications with no directory structure at all. just flat. Supported by apps, pmenu and lx. no folders, we die like icons 🍓
• csv_i18n = string (no default) — tells it to look for a translation file in the file or directory you name. See jgmenu-i18n(1) for the full tea. Supported by apps and ob. 🌈
• csv_no_duplicates = boolean (default 0) — keeps applications from showing up in more than one directory. one app, one home, periodt. Supported by apps. 💖

---

💬 INTER-PROCESS COMMUNICATION (IPC) 💬

IPC is how you get jgmenu to line up with a panel launcher in real-time — like, live, as it happens. Right now this is supported by tint2 and xfce-panel. Here's how the whole thing goes down:

jgmenu_run reads the environment variables listed below and passes them through a unix socket to the long-running instance of jgmenu. so they're literally gossiping over a socket, love that for them 🫶

If position_mode=ipc, jgmenu aligns to those variables every single time it's launched.

These four environment variables are the ones that define the extremities of the panel: TINT2_BUTTON_PANEL_X1, TINT2_BUTTON_PANEL_X2, TINT2_BUTTON_PANEL_Y1, TINT2_BUTTON_PANEL_Y2.

              (X1,Y1)
              ╔══════════════════════╗
              ║ panel                ║
              ╚══════════════════════╝
                               (X2,Y2)

The next batch of environment variables define where the launcher sits. And heads up — these get interpreted differently depending on panel alignment, so read carefully bestie:

In the case of a horizontal panel:

• TINT2_BUTTON_ALIGNED_X1 and TINT2_BUTTON_ALIGNED_X2 define the launcher button's horizontal extremities to align to.
• TINT2_BUTTON_ALIGNED_Y1 and TINT2_BUTTON_ALIGNED_Y2 define the edge of the panel to align to. These shall be the same.

In the case or a vertical panel, the same rules apply with X and Y reversed. 🔄

And if none of the above variables are set? Then menu_margin_x and menu_margin_y get used instead. fallback queens 👑

---

🎨 DIAGRAMS 🎨

General Notes

margin — refers to space outside an object.

padding — refers to space inside an object (between border and content).

Vertical Menu

              ╔════════════════════════╗
              ║            1           ║
              ╟────────────────────────╢
              ║            2           ║
              ╟────────────────────────╢
              ║          item          ║
              ╟────────────────────────╢
              ║            2           ║
              ╟────────────────────────╢
              ║          item          ║
              ╟────────────────────────╢
              ║            2           ║
              ╟────────────────────────╢
              ║            3           ║
              ╚════════════════════════╝

1. menu_padding_top
2. item_margin_y
3. menu_padding_bottom

Horizontal Menu

              ╔═╤═╤════════════════╤═╤═╗
              ║ │ │                │ │ ║
              ║ │ ├────────────────┤ │ ║
              ║ │ │icon   text    >│ │ ║
              ║ │ ├────────────────┤ │ ║
              ║2│1│                │1│3║
              ║ │ ├────┬─┬───────┬─┤ │ ║
              ║ │ │ 4  │5│       │6│ │ ║
              ║ │ ├────┴─┴───────┴─┤ │ ║
              ║ │ │                │ │ ║
              ║ │ │                │ │ ║
              ╚═╧═╧════════════════╧═╧═╝

1. item_margin_x
2. padding_left
3. padding_right
4. icon_size
5. icon_to_text_spacing
6. arrow_width

External to menu

              screen
              ╔════════════════════════╗
              ║    2                   ║
              ║ ┌──────┐               ║
              ║ │ root │ ┌──────┐      ║
              ║1│ menu │ │ sub  │      ║
              ║ │      │3│ menu │      ║
              ║ └──────┘ │      │      ║
              ║          └──────┘      ║
              ║                        ║
              ║                        ║
              ║                        ║
              ╚════════════════════════╝

1. menu_margin_x
2. menu_margin_y
3. sub_spacing

---

🪝 HOOKS 🪝

A hook in jgmenu is a rule which optionally triggers a command and then performs a restart if a file or directory has changed since the last time the instance of jgmenu was mapped (= made visible — normally by running jgmenu_run). so it's like, "hey bestie, something moved, time for a glow-up" ✨

Hooks are specified in the file $HOME/.config/jgmenu/hooks are take the format

<file>,<command>

For example, to synchronise with the GTK theme, use this hook:

~/.config/gtk-3.0/settings.ini,jgmenu_run gtktheme

Leave the <command> empty to just restart. (yes, a lil restart-and-refresh moment, no command needed 🧚)

A number of restart-hooks are built-in by default, for example ~/.config/jgmenu/{jgmenurc,append.csv,prepend.csv} and /usr/share/applications.

To list all the built-in hooks, use the keyword print in the hook file (on a line on its own). In order to remove all the built-in hooks, use the keyword clear. so print = show me everything, clear = burn it all down 🔥

---

🚀 STARTUP SCRIPT 🚀

Unless the --vsimple argument is used, the file ~/.config/jgmenu/startup is executed on initial startup. that's your lil main-character entrance 💅

---

👀 SEE ALSO 👀

• jgmenu_run(1)
• jgmenututorial(7)
• jgmenuunicode(7)

The jgmenu source code and documentation can be downloaded from https://github.com/johanmalm/jgmenu/ — go get it, it's giving open source excellence 🫶

---

👑 AUTHORS 👑

Johan Malm. (the icon, the legend, the whole entire vibe ⭐)

---

and that's a wrap on JGMENU(1) bestie 💖 this page is from the jgmenu manual set, dated 2 January, 2021 — go forth and menu, you absolute legend 🌸🦋🎀