1JGMENU(1) JGMENU(1)
2
6 jgmenu - A simple X11 menu
7
9 jgmenu [--no-spawn] [--checkout=<tag>] [--config-file=<file>]
10 [--icon-size=<size>] [--at-pointer] [--hide-on-startup]
11 [--simple] [--vsimple] [--csv-file=<file>]
12 [--csv-cmd=<command>] [--die-when-loaded]
13 [--center] [--persistent]
14 Use these commands to get started
16 jgmenu_run
18 Launch menu
19 jgmenu_run init
21 Create config file ~/.config/jgmenu/jgmenurc
22 jgmenu_run init -i
24 Interactive setup
25 man jgmenututorial
27 Step-by-step tutorial
28
30 jgmenu is a simple menu for Linux/BSD. It reads CSV menu data from a
31 file and generates a graphical menu on an X11 window.
32 Fields
34 Each line of CSV menu data is parsed into the following fields using
35 comma as a field separator:
36 (1) description
38 (2) command
39 (3) icon
40 (4) working directory
41 (5) metadata
42 (6) execute without “sh -c” wrapper
43 For example:
45 printf "Terminal,xterm\\nWeb Browser,firefox" | jgmenu --vsimple
47 Special Characters at beginning of line
49 # Ignore line
50 . A line beginning with a dot followed by a space, will source the
52 file specified by the string following the dot
53 @ Treat as widget
55 Special Characters in fields
57 , As commas are used as field separators, individual fields can
58 only contain commas if they are triple quoted. For example:
59 foo,""“^pipe(find . -printf `%f,display %p,%p\n')”""
61 < > & The description field is parsed as pango markup, so <, >, and &
63 need to be escaped as <, >, and & respectively.
64 Markup
66 The syntax ^foo(bar) is used to carry out action foo with argument bar.
67 We refer to bar as the inner value.
68 The following markup is supported in the description field
70 sep() Define a separator. If an inner value is provided, the separa‐
72 tor will appear as a title. If no inner value is provided, the
73 separator will simply be a horizontal line
74 The following markup is supported in the command field
76 ^tag() Define the beginning of a new menu structure node.
78 The lines following ^tag(whatever) will not show in the top lev‐
80 el menu, but can be opened by using ^checkout() or ^root().
81 item0.0
83 item0.1
84 submenu1,^checkout(1)
85 submenu2,^root(2)
86 ^tag(1)
88 item1.0
89 item1.1
90 ^tag(2)
92 item2.0
93 item2.1
94 ^checkout()
96 Open the tag specified by the inner value as a submenu in a new
97 window
98 ^root()
100 Open the tag specified by the inner value in the root window,
101 replacing the current menu
102 ^sub() Draw a submenu arrow. This can be useful for creating submenus
104 with stay_alive=0. For example:
105 item0.0
107 item0.1
108 submenu1,^sub(echo "item1.0" | jgmenu --simple)
109 ^back()
111 Check-out parent menu
112 ^term()
114 Run program in terminal
115 ^pipe()
117 Execute sub-process and checkout a menu based on its stdout.
118 ^filter()
120 Invoke search
121 ^quit()
123 Quit
124 Icons
126 Icons will be displayed if the third field is populated, for example:
127 Terminal,xterm,utilities-terminal
129 Firefox,firefox,firefox
130
132 --no-spawn
133 Redirect command to stdout rather than execute it.
134 --checkout=<tag>
136 Checkout submenu on startup.
137 --config-file=<file>
139 Read config file.
140 --icon-size=<size>
142 Specify icon size (22 by default). If set to 0, icons will not
143 be loaded.
144 --at-pointer
146 Launch menu at mouse pointer.
147 --hide-on-startup
149 Start menu is hidden state.
150 --simple
152 Ignore tint2 settings; Run in short-lived mode (i.e. exit after
153 mouse click or enter/escape); read menu items from stdin.
154 --vsimple
156 Same as --simple, but also disables icons and ignores jgmenurc.
157 --csv-file=<file>
159 Specify menu file (in jgmenu flavoured CSV format). If file
160 cannot be opened, input is reverted to stdin.
161 --csv-cmd=<command>
163 Specify command to produce menu data, for example jgmenu_run
164 pmenu
165 --die-when-loaded
167 Open menu and then exit(0). Useful for debugging and testing.
168 --center
170 Center align menu horizontally and vertically.
171 --persistent
173 Same as the persistent config option. See config option section
174 below for details.
175
177 Up, Down
178 Select previous/next item
179 Left. Right
181 Move to parent/sub menu
182 PgUp, PgDn
184 Scroll up/down
185 Home, End
187 Select first/last item
188 Enter Select an item or open a submenu
190 F5 Restart
192 F8 Print node tree to stderr
194 F9 [22mexit(1)
196 F10 [22mexit(0)
198 Backspace
200 Return to parent menu
201 Type any string to invoke a search. Words separated by space will be
203 searched for using OR logic (i.e. the match of either word is suffi‐
204 cient to display an item).
205
207 Lines beginning with `@' in jgmenu flavoured CSV files are parsed in
208 accordance with the following syntax:
209 @type,action,x,y,w,h,r,halign,valign,fgcol,bgcol,content
211 type The widget type, which can be one of the following:
213 rect Rectangle with a 1px thick border drawn using fgcol
215 search Search box showing the current filter (what the user has
217 typed) or the specified text if no filter has been in‐
218 voked.
219 icon Icon
221 action The action to take when selected. This can either be a shell
223 command or a menu action such ^root().
224 x, y Horizontal and vertical margin of widget
226 w, h Width and height of widget
228 r Corner radius
230 fgcol, bgcol
232 Foreground and background colours using syntax rrggbb #aa fgcol
233 accepts auto to use the jgmenurc’s color_norm_fg
234 content
236 icon_path for icon widgets text for all other widget types
237 halign, valign
239 Horizontal and vertical alignment of widget. This has not yet
240 been implemented, but defaults to top and left
241
243 If no file is specified using the –config-file= option, the XDG Base
244 Directory Specification is adhered to. I.e:
245 · Global config in ${XDG_CONFIG_DIRS:-/etc/xdg}
247 · User config override in ${XDG_CONFIG_HOME:-$HOME/.config}
248 For most users ~/.config/jgmenu/jgmenurc is appropriate.
250 Global config variables are set in the following order (i.e. bottom of
252 list has higher precedence):
253 · built-in defaults (config.c)
255 · tint2rc config file (can be specified by TINT2_CONFIG environment
256 variable)
257 · jgmenurc config file (can be specified by –config-file=)
258 · command line arguments
259 Syntax
261 Lines beginning with # are ignored.
262 All other lines are recognised as setting variables in the format
264 key = value
266 White spaces are mostly ignored.
268 Values
270 Unless otherwise specified, values as treated as simple strings.
271 Here follow some specific types:
273 boolean
275 When a variable takes a boolean value, only 0 and 1 are accept‐
276 ed. 0 means false; 1 means true.
277 integer
279 When a variable takes an integer value, only numerical values
280 are accepted. The only valid characters are digits (0-9) and
281 minus-sign. All integer variables relating to geometry and po‐
282 sition are interpreted as pixel values unless otherwise speci‐
283 fied.
284 color When a variable takes a color value, only the syntax #rrggbb aaa
286 is recognised, where rr, gg and bb represent hexadecimal values
287 (00-ff) for the colours red, green and blue respectively; and
288 aaa stands for the alpha channel value expressed as a percentage
289 (0-100) (i.e. 100 means no transparency and 0 means fully trans‐
290 parent.) For example #ff0000 100 represents red with no trans‐
291 parency, whereas #000088 50 means dark blue with 50% transparen‐
292 cy.
293 pathname
295 When a variable takes a pathname value, it is evaluated as a
296 string. If the first character is tilde (~), it will be re‐
297 placed by the the environment variable $HOME just as a shell
298 would expand it.
299 Variables
301 verbosity = integer (default 0)
302 General verbosity: (0) warnings only; (1) basic info; (2) more
303 info; (3) max info
304 Additional specific topics: (4) IPC
306 Note: Some IPC messages need environment variable JGMENU_VER‐
308 BOSITY=4 too
309 stay_alive = boolean (default 1)
311 If set to 1, the menu will “hide” rather than “exit” when the
312 following events occur: clicking on menu item; clicking outside
313 the menu; pressing escape. When in the hidden mode, a USR1 sig‐
314 nal will “un-hide” the menu.
315 persistent = boolean (default 0)
317 If set to 1, the menu will not exit nor hide when the following
318 events occur: clicking on menu item; clicking outside the menu;
319 pressing escape. Use in conjunction with the ^quit() markup.
320 hide_on_startup = boolean (default 0)
322 If set to 1, jgmenu start in “hidden” mode. This is useful for
323 starting jgmenu during the boot process and then sending a kil‐
324 lall -SIGUSR1 jgmenu to show the menu.
325 csv_cmd = string (default apps)
327 Defines the command to produce the jgmenu flavoured CSV for jg‐
328 menu. Accpetable keyword include apps, pmenu, lx, and ob. If a
329 value is given other than these keywords, it will be executed in
330 a shell (so be careful!). If left blank, jgmenu will read from
331 stdin. Examples:
332 csv_cmd = lx
334 csv_cmd = jgmenu_run lx --no-dirs
335 csv_cmd = cat ~/mymenu.csv
336 tint2_look = boolean (default 0)
338 Read tint2rc and parse config options for colours, dimensions
339 and alignment.
340 position_mode = (fixed | ipc | pointer | center) (default fixed)
342 Define menu positioning mode.
343 fixed Align to margin_{x,y} and respect _NET_WORKAREA.
345 ipc Use IPC to read environment variables set by panel. See
347 Inter-Process Communication for further info.
348 pointer
350 Launch at pointer whilst respecting both _NET_WORKAREA
351 and edge_snap_x.
352 center Launch at center of screen and ignore _NET_WORKAREA.
354 Take precedence over menu_{v,h}align.
355 edge_snap_x = integer (default 30)
357 Specify the distance (in pixels) from the left hand edge, within
358 which the menu will snap to the edge. Note that this only ap‐
359 plies in at_pointer mode.
360 terminal_exec = string (default x-terminal-emulator)
362 Define terminal to use for commands with ^term() markup
363 terminal_args = string (default -e)
365 The values of these two variables are used to build a string to
366 launch programs requiring a terminal to run. With the default
367 values, the string would become: x-terminal-emulator -e
368 'some_command with arguments'. terminal_args must finish with
369 -e or equivalent, where -e refers to the meaning of -e in xterm
370 -e.
371 monitor = integer (default 0)
373 Specify a particular monitor as an index starting from 1. If 0,
374 the menu will be launched on the monitor where the mouse is.
375 hover_delay = integer (default 100)
377 Time (in milliseconds) from hovering over an item until a sub‐
378 menu is opened.
379 hide_back_items = boolean (default 1)
381 If enabled, all ^back() items will be suppressed. As a general
382 rule, it should be set to 1 for a multi-window menu, and 0 when
383 in single-window mode.
384 columns = integer (default 1)
386 Number of columns in which to show menu items
387 tabs = integer (default 120)
389 Specify the position is pixels of the first tab
390 menu_margin_x = integer (default 0)
392 Distance between the menu (=X11 window) and the edge of the
393 screen. See note on _NET_WORKAREA under menu_{v,h}align vari‐
394 ables.
395 menu_margin_y = integer (default 0)
397 Vertical equilvalent of menu_margin_x
398 menu_width = integer (default 200)
400 Minimum menu width of the menu. The menu width will adjust to
401 the longest item in the current (sub)menu. If a filter is ap‐
402 plied (e.g. by the user typing) the menu width will not adjust.
403 menu_height_min = integer (default 0)
405 Set the minimum height of the root menu. If menu_height_min and
406 menu_height_max these are set to the same value, the menu height
407 will be fixed at that value. If set to zero, they will be ig‐
408 nored.
409 menu_height_max = integer (default 0)
411 Minimum height of the root menu. See menu_height_min
412 menu_height_mode = (static | dynamic) (default static)
414 Mode of menu height
415 static Height of the initial root menu will be used for any sub‐
417 sequent ^root() action
418 dynamic
420 Root menu height will be re-calculated every time a new
421 tag is opened using ^root().
422 menu_padding_top = integer (default 5)
424 Distance between top border and item/widget
425 menu_padding_right = integer (default 5)
427 Distance between right border and item/widget
428 menu_padding_bottom = integer (default 5)
430 Distance between bottom border and item/widget
431 menu_padding_left = integer (default 5)
433 Distance between left border and item/widget
434 menu_radius = integer (default 1)
436 Radius of rounded corners of menu
437 menu_border = integer (default 0)
439 Thickness of menu border
440 menu_halign = (left | right | center) (default left)
442 Horizontal alignment of menu. If not set, jgmenu will try to
443 guess the alignment reading _NET_WORKAREA, which is a freedesk‐
444 top EWMH root window property. Not all Window Managers and Pan‐
445 els respect _NET_WORKAREA. The following do: openbox, xfwm4,
446 tint2 and polybar. The following do NOT: awesome, i3, bspwm and
447 plank
448 menu_valign = (top | bottom | center) (default bottom)
450 Vertical alignment of menu. See menu_halign.
451 menu_gradient_pos = (none | top | right | bottom | left | top_left |
453 top_right | bottom_left | bottom_right ) (default none)
454 Start position of menu window gradient. The end position is at
455 the opposite side or corner. Colors color_menu_bg and col‐
456 or_menu_bg_to specify the start (from) and finish (to).
457 sub_spacing = integer (default 1)
459 Horizontal space between windows. A negative value results in
460 each submenu window overlapping its parent window.
461 sub_padding_top = integer (default auto)
463 Same as menu_padding_top but applies to submenu windows only.
464 It understands the keyword auto which means that the smallest of
465 the four menu_padding_* variables will be used.
466 sub_padding_right = integer (default auto)
468 See sub_padding_top
469 sub_padding_bottom = integer (default auto)
471 See sub_padding_top
472 sub_padding_left = integer (default auto)
474 See sub_padding_top
475 sub_hover_action = integer (default 1)
477 Open submenu when hovering over item (only works in multi-window
478 mode).
479 item_margin_x = integer (default 3)
481 Horizontal distance between items and the edge of the menu.
482 item_margin_y = integer (default 3)
484 Vertical distance between items and the edge of the menu.
485 item_height = integer (default 25)
487 Height of menu items.
488 item_padding_x = integer (default 4)
490 Horizontal distance between item edge and its content (e.g. text
491 or icon)
492 item_radius = integer (default 1)
494 Radius of rounded corners of items
495 item_border = integer (default 0)
497 Thickness of item border
498 item_halign = (left | right) (default left)
500 Horizontal alignment of menu items. If set to right, the option
501 arrow_string should be changed too.
502 sep_height = integer (default 5)
504 Height of separator without text (defined by ^sep()). Separa‐
505 tors with text use item_height
506 sep_halign = (left | center | right) (default left)
508 Horizontal alignment of separator text
509 sep_markup = string (unset by default)
511 If specified, <span $sep_markup>foo</span> will be passed to
512 pango for ^sep(foo).
513 See the following link for pango attributes: <https://develop‐
515 er.gnome.org/pango/stable/pango-Markup.html>
516 Keywords include (but are not limited to):
518 · font
520 · size (x-small, small, medium, large, x-large) - style (normal,
522 oblique, italic)
523 · weight (ultralight, light, normal, bold, ultrabold, heavy
525 · foreground (using format #rrggbb or a colour name)
527 · underline (none, single, double)
529 Example:
531 sep_markup = font="Sans Italic 12" foreground="blue"
533 font = string (unset by default)
535 Font description for menu items. font accepts a string such as
536 Cantarell 10 or UbuntuCondensed 11. The font description with‐
537 out a specified size unit is interpreted as points. If px is
538 added, it will be read as pixels. Using “points” enables consis‐
539 tency with other applications.
540 font_fallback = string (default xtg)
542 Same as icon_theme_fallback, except that the xsettings variable
543 Gtk/FontName is read.
544 icon_size = integer (default 22)
546 Size of icons in pixels. If set to 0, icons will be disabled.
547 icon_text_spacing = integer (default 10)
549 Distance between icon and text within a menu item
550 icon_norm_alpha = integer (default 100)
552 Opacity of menu item icons, expressed as a percentage (0-100).
553 icon_sel_alpha = integer (default 100)
555 Opacity of the currently selected menu item’s icon, expressed as
556 a percentage (0-100).
557 icon_theme = string (unset by default)
559 Name of icon theme. E.g. Adwaita, breeze, Paper, Papirus and
560 Numix. See ls /usr/share/icons/ (or similar) for available icon
561 themes on your system.
562 icon_theme_fallback = string (default xtg)
564 Fallback sources of the icon theme in order of precedence, where
565 the left-most letter designates the source with highest prece‐
566 dence. The following characters are acceptable: x=xsettings
567 Net/IconThemeName; t=tint2; g=gtk3.0. icon_theme takes priority
568 if set. In order to increase consistency with tint2, xsettings
569 variables will only be read if the tint2rc variable launch‐
570 er_icon_theme_override is 0.
571 arrow_string = string (default ▸)
573 String to be used to indicate that an item will open submenu.
574 See jgmenuunicode(7) for examples
575 arrow_width = integer (default 15)
577 Width allowed for arrow_string. Set to 0 to hide arrow.
578 color_menu_bg = color (default #000000 100)
580 Background colour of menu window. If gradients are enabled,
581 this will be the `from' color.
582 color_menu_bg_to = color (default #000000 100)
584 Background `to' colour of menu window - for use with gradients
585 color_menu_border = color (default #eeeeee 8)
587 Border colour of menu window
588 color_norm_bg = color (default #000000 0)
590 Background colour of menu items, except the one currently se‐
591 lected.
592 color_norm_fg = color (default #eeeeee 100)
594 Font (foreground) colour of menu items, except the one currently
595 selected.
596 color_sel_bg = color (default #ffffff 20)
598 Background color of the currently selected menu item.
599 color_sel_fg = color (default #eeeeee 100)
601 Font (foreground) color of the currently selected menu item.
602 color_sel_border = color (default #eeeeee 8)
604 Border color of the currently selected menu item.
605 color_sep_fg = color (default #ffffff 20)
607 Font (foreground) colour of separators without text
608 color_title_fg = color (default #eeeeee 50)
610 Font (foreground) colour of separators with text. The font
611 colour can be overridden by sep_markup
612 color_title_bg = color (default #000000 0)
614 Background colour of separators with text.
615 color_title_border = color (default #000000 0)
617 Border colour of separators with text.
618 color_scroll_ind = color (default #eeeeee 40)
620 Colour of scroll indicator lines (which show if there are menu
621 items above or below those which are visible).
622 CSV generator variables
624 The following variables begin with csv_ which denotes that they set en‐
625 vironment variables which are used by the CSV generators.
626 csv_name_format = string (default %n (%g))
628 Defines the format of the name field for CSV generators. Sup‐
629 ported by apps and lx. It understands the following two fields:
630 %n Application name
632 %g Application generic name. If a generic name does not ex‐
634 ist or is the same as the name, %n will be used without
635 any formatting.
636 csv_single_window = boolean (default 0)
638 If set, csv-generators will output ^root() instead of ^check‐
639 out(). This results in a single window menu, where submenus ap‐
640 pear in the same window. This is supported by apps and pmenu.
641 csv_no_dirs = boolean (default 0)
643 If set, csv-generators will output applications without any di‐
644 rectory structure. This is supported by apps, pmenu and lx.
645 csv_i18n = string (no default)
647 Look for a translation file in the specified file or directory.
648 See `jgmenu-i18n(1) for further details. Supported by apps and
649 ob.
650 csv_no_duplicates = boolean (default 0)
652 Restrict applications to appear in one directory only. Support‐
653 ed by apps.
654
656 IPC can be used to align jgmenu to a panel launcher in real-time. This
657 is currently supported by tint2 and xfce-panel. It works as follows:
658 jgmenu_run reads the environment variables listed below and passes them
660 via a unix socket to the long-running instance of jgmenu.
661 If position_mode=ipc, jgmenu aligns to these variables every times it
663 is launched.
664 The following four environment variables define the extremities of the
666 panel: TINT2_BUTTON_PANEL_X1, TINT2_BUTTON_PANEL_X2, TINT2_BUTTON_PAN‐
667 EL_Y1, TINT2_BUTTON_PANEL_Y2.
668 (X1,Y1)
670 ╔══════════════════════╗
671 ║ panel ║
672 ╚══════════════════════╝
673 (X2,Y2)
674 The following environment variables define the position of the launch‐
676 er. These are interpreted differently depending on panel alignment.
677 In the case of a horizontal panel:
679 · TINT2_BUTTON_ALIGNED_X1 and TINT2_BUTTON_ALIGNED_X2 define the
681 launcher button’s horizontal extremities to align to.
682 · TINT2_BUTTON_ALIGNED_Y1 and TINT2_BUTTON_ALIGNED_Y2 define the edge
684 of the panel to align to. These shall be the same.
685 In the case or a vertical panel, the same rules apply with X and Y re‐
687 versed.
688 If the above variables are not set, menu_margin_x and menu_margin_y are
690 used.
691
693 General Notes
694 margin Refers to space outside an object
695 padding
697 Refers to space inside an object (between border and content)
698 Vertical Menu
700 ╔════════════════════════╗
701 ║ 1 ║
702 ╟────────────────────────╢
703 ║ 2 ║
704 ╟────────────────────────╢
705 ║ item ║
706 ╟────────────────────────╢
707 ║ 2 ║
708 ╟────────────────────────╢
709 ║ item ║
710 ╟────────────────────────╢
711 ║ 2 ║
712 ╟────────────────────────╢
713 ║ 3 ║
714 ╚════════════════════════╝
715 1. menu_padding_top
717 2. item_margin_y
718 3. menu_padding_bottom
719 Horizontal Menu
721 ╔═╤═╤════════════════╤═╤═╗
722 ║ │ │ │ │ ║
723 ║ │ ├────────────────┤ │ ║
724 ║ │ │icon text >│ │ ║
725 ║ │ ├────────────────┤ │ ║
726 ║2│1│ │1│3║
727 ║ │ ├────┬─┬───────┬─┤ │ ║
728 ║ │ │ 4 │5│ │6│ │ ║
729 ║ │ ├────┴─┴───────┴─┤ │ ║
730 ║ │ │ │ │ ║
731 ║ │ │ │ │ ║
732 ╚═╧═╧════════════════╧═╧═╝
733 1. item_margin_x
735 2. padding_left
736 3. padding_right
737 4. icon_size
738 5. icon_to_text_spacing
739 6. arrow_width
740 External to menu
742 screen
743 ╔════════════════════════╗
744 ║ 2 ║
745 ║ ┌──────┐ ║
746 ║ │ root │ ┌──────┐ ║
747 ║1│ menu │ │ sub │ ║
748 ║ │ │3│ menu │ ║
749 ║ └──────┘ │ │ ║
750 ║ └──────┘ ║
751 ║ ║
752 ║ ║
753 ║ ║
754 ╚════════════════════════╝
755 1. menu_margin_x
757 2. menu_margin_y
758 3. sub_spacing
759
761 A hook in jgmenu is a rule which optionally triggers a command and then
762 performs a restart if a file or directory has has changed since the
763 last time the instance of jgmenu was mapped (=made visible - normally
764 by running jgmenu_run).
765 Hooks are specified in the file $HOME/.config/jgmenu/hooks are take the
767 format
768 <file>,<command>
770 For example, to synchronise with the GTK theme, use this hook:
772 ~/.config/gtk-3.0/settings.ini,jgmenu_run gtktheme
774 Leave the <command> empty to just restart.
776 A number of restart-hooks are built-in by default, for example ~/.con‐
778 fig/jgmenu/{jgmenurc,append.csv,prepend.csv} and /usr/share/applica‐
779 tions.
780 To list all the built-in hooks, use the keyword print in the hook file
782 (on a line on its own). In order to remove all the built-in hooks, use
783 the keyword clear.
784
786 Unless the --vsimple argument is used, the file ~/.config/jgmenu/start‐
787 up is executed on initial startup.
788
790 · jgmenu_run(1)
791 · jgmenututorial(7)
793 · jgmenuunicode(7)
795 The jgmenu source code and documentation can be downloaded from
797 <https://github.com/johanmalm/jgmenu/>
798
800 Johan Malm.
801 2 January, 2021 JGMENU(1)