Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JGMENU(1)							     JGMENU(1)

NAME
       jgmenu -	A simple X11 menu

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]

       Use these commands to get started

       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.

   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
       (6) execute without "sh -c" wrapper

       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 &lt;, &gt;,	and &amp; respectively.

   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 separa-
	      tor 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 lev-
	      el 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	suffi-
       cient 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  in-
		     voked.

	      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:

       o Global	config in ${XDG_CONFIG_DIRS:-/etc/xdg}
       o 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):

       o built-in defaults (config.c)
       o tint2rc config	file (can be  specified	 by  TINT2_CONFIG  environment
	 variable)
       o jgmenurc config file (can be specified	by -config-file=)
       o 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 accept-
	      ed.  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  po-
	      sition  are  interpreted as pixel	values unless otherwise	speci-
	      fied.

       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	trans-
	      parent.)	For  example #ff0000 100 represents red	with no	trans-
	      parency, whereas #000088 50 means	dark blue with 50% transparen-
	      cy.

       pathname
	      When  a  variable	 takes	a pathname value, it is	evaluated as a
	      string.  If the first character is tilde (~),  it	 will  be  re-
	      placed  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_VER-
	      BOSITY=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 sig-
	      nal 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  kil-
	      lall -SIGUSR1 jgmenu to show the menu.

       csv_cmd = string	(default apps)
	      Defines  the command to produce the jgmenu flavoured CSV for jg-
	      menu.  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	 pointer  whilst respecting both _NET_WORKAREA
		     and edge_snap_x.

	      center Launch at center  of  screen  and	ignore	_NET_WORKAREA.
		     Take precedence over menu_{v,h}align.

       edge_snap_x = integer (default 30)
	      Specify the distance (in pixels) from the	left hand edge,	within
	      which the	menu will snap to the edge.  Note that this  only  ap-
	      plies in at_pointer mode.

       terminal_exec = string (default x-terminal-emulator)
	      Define terminal to use for commands with ^term() markup

       terminal_args = string (default -e)
	      The  values of these two variables are used to build a string to
	      launch programs requiring	a terminal to run.  With  the  default
	      values,	the   string   would  become:  x-terminal-emulator  -e
	      'some_command with arguments'.  terminal_args must  finish  with
	      -e  or equivalent, where -e refers to the	meaning	of -e in xterm
	      -e.

       monitor = integer (default 0)
	      Specify a	particular monitor as an index starting	from 1.	 If 0,
	      the menu will be launched	on the monitor where the mouse is.

       hover_delay = integer (default 100)
	      Time  (in	 milliseconds) from hovering over an item until	a sub-
	      menu is opened.

       hide_back_items = boolean (default 1)
	      If enabled, all ^back() items will be suppressed.	 As a  general
	      rule,  it	should be set to 1 for a multi-window menu, and	0 when
	      in single-window mode.

       columns = integer (default 1)
	      Number of	columns	in which to show menu items

       tabs = integer (default 120)
	      Specify the position is pixels of	the first tab

       menu_margin_x = integer (default	0)
	      Distance between the menu	(=X11 window)  and  the	 edge  of  the
	      screen.	See  note on _NET_WORKAREA under menu_{v,h}align vari-
	      ables.

       menu_margin_y = integer (default	0)
	      Vertical equilvalent of menu_margin_x

       menu_width = integer (default 200)
	      Minimum menu width of the	menu.  The menu	width will  adjust  to
	      the  longest  item in the	current	(sub)menu.  If a filter	is ap-
	      plied (e.g. by the user typing) the menu width will not adjust.

       menu_height_min = integer (default 0)
	      Set the minimum height of	the root menu.	If menu_height_min and
	      menu_height_max these are	set to the same	value, the menu	height
	      will be fixed at that value.  If set to zero, they will  be  ig-
	      nored.

       menu_height_max = integer (default 0)
	      Minimum height of	the root menu.	See menu_height_min

       menu_height_mode	= (static | dynamic) (default static)
	      Mode of menu height

	      static Height of the initial root	menu will be used for any sub-
		     sequent ^root() action

	      dynamic
		     Root menu height will be 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	rounded	corners	of menu

       menu_border = integer (default 0)
	      Thickness	of menu	border

       menu_halign = (left | right | center) (default left)
	      Horizontal  alignment  of	 menu.	If not set, jgmenu will	try to
	      guess the	alignment reading _NET_WORKAREA, which is a  freedesk-
	      top EWMH root window property.  Not all Window Managers and Pan-
	      els respect _NET_WORKAREA.  The following	 do:  openbox,	xfwm4,
	      tint2 and	polybar.  The following	do NOT:	awesome, i3, bspwm and
	      plank

       menu_valign = (top | bottom | center) (default bottom)
	      Vertical alignment of 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 menu window gradient.	The end	position is at
	      the opposite side	or  corner.   Colors  color_menu_bg  and  col-
	      or_menu_bg_to specify the	start (from) and finish	(to).

       sub_spacing = integer (default 1)
	      Horizontal  space	 between windows.  A negative value results in
	      each submenu window overlapping its parent window.

       sub_padding_top = integer (default auto)
	      Same as menu_padding_top but applies to  submenu	windows	 only.
	      It understands the keyword auto which means that 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 submenu when	hovering over item (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 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 set to right, the	option
	      arrow_string should be changed too.

       sep_height = integer (default 5)
	      Height  of  separator without text (defined by ^sep()).  Separa-
	      tors 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://develop-
	      er.gnome.org/pango/stable/pango-Markup.html>

	      Keywords include (but are	not limited to):

	      o	font

	      o	size (x-small, small, medium, large, x-large) -	style (normal,
		oblique, italic)

	      o	weight (ultralight, light, normal, bold, ultrabold, heavy

	      o	foreground (using format #rrggbb or a colour name)

	      o	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	 with-
	      out  a  specified	 size unit is interpreted as points.  If px is
	      added, it	will be	read as	pixels.	Using "points" enables consis-
	      tency with other applications.

       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	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  highest	prece-
	      dence.   The  following  characters  are acceptable: x=xsettings
	      Net/IconThemeName; t=tint2; g=gtk3.0.  icon_theme	takes priority
	      if  set.	In order to increase consistency with tint2, xsettings
	      variables	will only be read  if  the  tint2rc  variable  launch-
	      er_icon_theme_override is	0.

       arrow_string = string (default )
	      String  to  be  used to indicate that an item will open submenu.
	      See jgmenuunicode(7) for examples

       arrow_width = integer (default 15)
	      Width allowed for	arrow_string.  Set to 0	to hide	arrow.

       color_menu_bg = color (default #000000 100)
	      Background colour	of menu	window.	  If  gradients	 are  enabled,
	      this will	be the `from' color.

       color_menu_bg_to	= color	(default #000000 100)
	      Background `to' colour of	menu window - for use with gradients

       color_menu_border = color (default #eeeeee 8)
	      Border colour of menu window

       color_norm_bg = color (default #000000 0)
	      Background  colour  of  menu items, except the one currently se-
	      lected.

       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	scroll indicator lines (which show if there  are  menu
	      items above or below those which are visible).

   CSV generator variables
       The following variables begin with csv_ which denotes that they set en-
       vironment variables which are used by the CSV generators.

       csv_name_format = string	(default %n (%g))
	      Defines the format of the	name field for CSV  generators.	  Sup-
	      ported by	apps and lx.  It understands the following two fields:

	      %n     Application name

	      %g     Application generic name.	If a generic name does not ex-
		     ist or is the same	as the name, %n	will be	 used  without
		     any formatting.

       csv_single_window = boolean (default 0)
	      If  set,	csv-generators	will output ^root() instead of ^check-
	      out().  This results in a	single window menu, where submenus ap-
	      pear in the same window.	This is	supported by apps and pmenu.

       csv_no_dirs = boolean (default 0)
	      If  set, csv-generators will output applications without any di-
	      rectory structure.  This is supported by apps, pmenu and lx.

       csv_i18n	= string (no default)
	      Look for a translation file in the specified file	or  directory.
	      See  `jgmenu-i18n(1) for further details.	 Supported by apps and
	      ob.

       csv_no_duplicates = boolean (default 0)
	      Restrict applications to appear in one directory only.  Support-
	      ed by apps.

Inter-Process Communication (IPC)
       IPC can be used to align	jgmenu to a panel launcher in real-time.  This
       is currently supported by tint2 and xfce-panel.	It works as follows:

       jgmenu_run reads	the environment	variables listed below and passes them
       via a unix socket to the	long-running instance of jgmenu.

       If  position_mode=ipc,  jgmenu aligns to	these variables	every times it
       is launched.

       The following four environment variables	define the extremities of  the
       panel:  TINT2_BUTTON_PANEL_X1, TINT2_BUTTON_PANEL_X2, TINT2_BUTTON_PAN-
       EL_Y1, TINT2_BUTTON_PANEL_Y2.

	      (X1,Y1)

	       panel

			       (X2,Y2)

       The following environment variables define the position of the  launch-
       er.  These are interpreted differently depending	on panel alignment.

       In the case of a	horizontal panel:

       o TINT2_BUTTON_ALIGNED_X1   and	 TINT2_BUTTON_ALIGNED_X2   define  the
	 launcher button's horizontal extremities to align to.

       o 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 re-
       versed.

       If the above variables are not set, menu_margin_x and menu_margin_y are
       used.

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  has  changed  since  the
       last  time  the instance	of jgmenu was mapped (=made visible - normally
       by running jgmenu_run).

       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.

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

       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.

STARTUP	SCRIPT
       Unless the --vsimple argument is	used, the file ~/.config/jgmenu/start-
       up is executed on initial startup.

SEE ALSO
       o jgmenu_run(1)

       o jgmenututorial(7)

       o jgmenuunicode(7)

       The jgmenu  source  code	 and  documentation  can  be  downloaded  from
       <https://github.com/johanmalm/jgmenu/>

AUTHORS
       Johan Malm.

				2 January, 2021			     JGMENU(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USER INTERFACE | WIDGETS | CONFIGURATION FILE | Inter-Process Communication (IPC) | DIAGRAMS | HOOKS | STARTUP SCRIPT | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=jgmenu&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help