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

FreeBSD Manual Pages

  
 
  

home | help
JGMENUTUTORIAL(7)					     JGMENUTUTORIAL(7)

NAME
       jgmenututorial -	A step-by-step tutorial	to jgmenu

INTRODUCTION
       This  tutorial  aims  to	 explain  the usage of jgmenu through a	set of
       lessons.

TABLE OF CONTENTS
       o Lesson	1 - Get	started
       o Lesson	2 - Architecture
       o Lesson	3 - Scripting with jgmenu
       o Lesson	4 - Descriptions
       o Lesson	5 - Icons
       o Lesson	6 - Submenus
       o Lesson	7 - XDG	Application Menus
       o Lesson	8 - Config Options
       o Lesson	9 - Apprend/Prepend and	Separators
       o Lesson	10 - CSV generators
       o Lesson	11 - Search

Lesson 1 - Get started
       After installing	jgmenu,	start the menu by running the  following  com-
       mand

	      jgmenu_run

       You  should see a Linux/BSD system menu showing installed applications.
       See lesson 7 for	further	details.

       Create a	config file (~/.config/jgmenu/jgmenurc)	by running

	      jgmenu_run init

       Full  details  of  config  options  are	covered	 in   jgmenu(1)	  (jg-
       menu.1.html).

       By  entering  the  interactive mode and then selecting `t', you can try
       some pre-defined	templates/themes.

	      jgmenu_run init -i

       There are a small number	of configuration options which may need	manual
       intervention in order for jgmenu	to display correctly on	your system.

       position_mode
	      There  are several methods for positioning the menu.  Try	fixed,
	      ipc, center and pointer to see what works	best on	 your  system.
	      See jgmenu(1) for	full details.

       menu_margin_x and menu_margin_y
	      If your are using	position_mode=fixed, you may need to set these
	      two variables.  Depending	on what	window manager and  panel  you
	      use,  jgmenu may be able to automatically	find a suitable	verti-
	      cal and horizontal position, so try without setting these	 vari-
	      ables first.

       menu_halign and menu_valign
	      Again, depending on your system, you may need to manually	speci-
	      fy horizontal and	vertical alignment of the menu,	but try	 with-
	      out first.

Lesson 2 - Architecture
       The design of jgmenu is very modular, providing a lot of	flexibility in
       how it is used.

       When jgmenu is started, two processes are run to	produce	the menu.

	      aaaaaaaaaaaaaaaaaa
	      a	csv-generator  a
	      aaaaaaaaaaaaaaaaaa
		      |
		      V
	      aaaaaaaaaaaaaaaaaa
	      a	graphical menu a
	      aaaaaaaaaaaaaaaaaa

       The first process (csv-generator) produces the  menu  content,  whereas
       the second generates the	graphical menu.

       jgmenu_run(1)  (jgmenu_run.1.html)  is  a  multi-purpose	wrapper	script
       which does the following	is pseudo code:

	      if (jgmenu is already running)
		      show menu
	      else
		      start a new instance of jgmenu

       This makes it suitable for using	with panels and	keyboard shortcuts.

Lesson 3 - Scripting with jgmenu
       From this point onwards,	it is assumed that you understand basic	 shell
       usage including re-direction (e.g.  <, >) and piping (e.g.  |).

       The  syntax  below  (here-document) is used to denote the creation of a
       text file from whatever is between the EOFs.  You  can  of  course  use
       your favourite text editor instead.

	      cat >file	<<EOF
	      foo
	      bar
	      EOF

       There  are  many	 ways to run jgmenu.  In lesson	1, you saw jgmenu as a
       long-running application.  As we	go through the	next  few  lessons  we
       will  run  jgmenu  as  a	 short-lived applications.  This means that it
       starts from scratch every time it is called.

       So let's	get back to basics.  Try the following:

	      echo >foo.txt <<EOF
	      xterm
	      firefox
	      EOF

       If you have not got used	to the here-document syntax yet, it just means
       that  you put the words "xterm" and "firefox" in	a text file (which you
       can of course do	using a	text editor).  Then run	either of the  follow-
       ing

	      cat foo.txt | jgmenu --simple --icon-size=0

	      jgmenu --vsimple --csv-file="foo.txt"

       The  option  --simple make jgmenu short-lived and reads menu items from
       stdin.

       The option --icon-size=0, disables icons	(i.e. it does not just display
       them at zero size, it simply does not load them)

       The  command  line argument --vsimple is	the same as --simple, but also
       disables	icons and ignores jgmenurc (if it exists).

       If you want a menu to be	launched by a single script,  you  could  con-
       struct it like this:

	      cat <<EOF	>menu.sh
	      #!/bin/sh
	      (
	      printf "foo\n"
	      printf "bar\n"
	      )	| jgmenu --vsimple
	      EOF
	      chmod +x menu.sh
	      ./menu.sh

Lesson 4 - Descriptions
       As  you	saw  in	the previous example, each line	fed to stdin becomes a
       menu item.  Any line containing two fields  separated  by  a  comma  is
       parsed as description,command.  Consider	the following CSV menu data:

	      Terminal,xterm
	      File Manager,pcmanfm

       This lets you give a more meaningful description	to each	menu item.

Lesson 5 - Icons
       To  display  icons,  you	need to	populate the third field.  By default,
       jgmenu will obtain the icon theme from xsettings	(if it is running)  or
       tint2rc	(if  it	exists).  When running with the	-simple	argument, make
       sure that icon_theme is set to something	sensible in  your  $HOME/.con-
       fig/jgmenu/jgmenurc.  Consider the following CSV	menu data:

	      Browser,	      firefox,		     firefox
	      File manager,   pcmanfm,		     system-file-manager
	      Terminal,	      xterm,		     utilities-terminal
	      Lock,	      i3lock -c	000000,	     system-lock-screen
	      Exit to prompt, openbox --exit,	     system-log-out
	      Reboot,	      systemctl	-i reboot,   system-reboot
	      Poweroff,	      systemctl	-i poweroff, system-shutdown

       In the third field you can also specify the full	path if	you wish.

Lesson 6 - Submenus
       So  far	we have	looked at producing a single "root" menu only.	jgmenu
       understands a small amount of markup and	enables	submenus by ^tag() and
       ^checkout().  Try this:

	      Terminal,xterm
	      File Manager,pcmanfm
	      Settings,^checkout(settings)

	      ^tag(settings)
	      Set Background Image,nitrogen

       In pseudo-code, build your CSV file as follows:

	      #	the root-menu
	      item0.0
	      item0.1
	      sub1,^checkout(1)
	      sub2,^checkout(2)

	      #	the first sub-menu
	      ^tag(1)
	      item1.0
	      item1.1

	      #	the second sub-menu
	      ^tag(2)
	      item2.0
	      item2.1

       ^root() can be used instead of ^checkout() in order to open the submenu
       in the parent window.

Lesson 7 - XDG Application Menus
       XDG (freedesktop.org) have defined a Linux/BSD Desktop Menu  Specifica-
       tion  which is followed by the big Desktop Environments.	 See menu-spec
       (http://specifications.freedesktop.org/menu-spec/latest/)  for  further
       details.	  In brief, there are three types of files which define	an XDG
       menu:

       .menu  XML file describing menu	categories  and	 directory  structure.
	      Located  in  /etc/xdg/menus/,  or	XDG_CONFIG_{HOME,DIRS} equiva-
	      lent.

       .directory
	      Describe menu directories.  Located in /usr/share/desktop-direc-
	      tories/, or XDG_DATA_{HOME,DIRS} equivalent.

       .desktop
	      Describe applications and	contain	most of	the information	needed
	      to build a menu (e.g.  Name, Exec	command,  Icon	and  Category)
	      Located  in  /usr/share/applications/,  or  XDG_DATA_{HOME,DIRS}
	      equivalent.

       Most desktop applications provided their	own associated .desktop	files,
       whereas	.menu and .directory files are supplied	by menu	packages, such
       as libmenu-cache	(LXDE) and libcargon (XFCE).

       The jgmenu core module jgmenu-apps(1) (jgmenu-apps.1.html)  provides  a
       system menu based on .desktop files and built-in	schema data or a spec-
       ified schema file, rather  than	system	.menu  and  .directory	files.
       Whilst  this  deviates from XDG menu spec, it is	much simpler to	under-
       stand and tweak.	 It also avoids	reliance on menu packages.

       For strict XDG compliance, the optional	module	jgmenu-lx(1)  (jgmenu-
       lx.1.html) can be used.

       See Lesson 10 for generic instructions on modules.

Lesson 8 - Config Options
       In  lesson  1 we	discussed config options position_mode,	menu_margin_x,
       menu_margin_y, menu_halign and menu_valign.

       Here follow a few more options you may wish to explore.	For  full  de-
       tails, see jgmenu(1) (jgmenu.1.html).

       Rofi style:

	      csv_no_dirs=1
	      csv_single_window=1
	      columns=2
	      menu_width=600
	      menu_valign=center
	      menu_halign=center

       Synchronize colours, font and icons with	tint2 panel

	      tint2_look=1

Lesson 9 - Apprend/Prepend and Separators
       When  using  apps,  pmenu  or lx, you can add menu items	to the top and
       bottom of the root menu by editing  append.csv  and/or  prepend.csv  in
       ~/.config/jgmenu.  For example, try the following:

       prepend.csv

	      Browser,	    firefox,		   firefox
	      File manager, pcmanfm,		   system-file-manager
	      Terminal,	    xterm,		   utilities-terminal
	      ^sep()

       append.csv

	      ^sep()
	      Suspend,	    systemctl -i suspend,  system-log-out
	      Reboot,	    systemctl -i reboot,   system-reboot
	      Poweroff,	    systemctl -i poweroff, system-shutdown

       In  these example we have used the markup ^sep(), which inserts a hori-
       zontal separator	line.  Similarly, ^sep(foo) inserts a  text  separator
       displaying "foo"

Lesson 10 - CSV	generators
       In  previous lessons, we	introduced the apps, lx	and pmenu.  These mod-
       ules are	referred to as "CSV generators"	and are	invoked	as follows:

	      jgmenu_run <command>

       Built-in	"CSV generators" include: apps and ob

       Optional	"CSV generators" include: lx and pmenu

       They are	documented by a	man page or a simple -help message.

	      man jgmenu-<command>
	      jgmenu_run <command> --help

       Here follow some	examples of how	they can be used.

       Specify CSV generator in	the config file	by setting csv_cmd in  ~/.con-
       fig/jgmenu/jgmenurc

	      csv_cmd =	pmenu

       Specify CSV generator on	the command line

	      jgmenu --csv-cmd="jgmenu_run pmenu"

       Pipe the	CSV output to jgmenu (using --simple to	read from stdin)

	      jgmenu_run pmenu | jgmenu	--simple

       Create a	pipemenu using ^pipe() markup.	Consider this example

	      Terminal,xterm
	      File Manager,pcmanfm
	      ^pipe(jgmenu_run pmenu)

Lesson 11 - Search
       jgmenu has search support, which	can be invoked by just typing when the
       menu is open.

       A search	box can	be inserted using widgets.  For	example, add  this  to
       ~/.config/jgmenu/prepend.csv:

	      @search,,3,3,150,20,2,left,top,auto,#000000 0,Type to Search

       Make sure you adjust menu padding accordingly, for example

	      menu_padding_top=24

       A  search  can also be invoked by associating a widget with a ^filter()
       command.

AUTHORS
       Johan Malm.

			       21 February, 2020	     JGMENUTUTORIAL(7)

NAME | INTRODUCTION | TABLE OF CONTENTS | Lesson 1 - Get started | Lesson 2 - Architecture | Lesson 3 - Scripting with jgmenu | Lesson 4 - Descriptions | Lesson 5 - Icons | Lesson 6 - Submenus | Lesson 7 - XDG Application Menus | Lesson 8 - Config Options | Lesson 9 - Apprend/Prepend and Separators | Lesson 10 - CSV generators | Lesson 11 - Search | AUTHORS

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

home | help