Provided by: jgmenu_4.4.1-2build1_amd64 
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
• 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
Lesson 1 - Get started
After installing jgmenu, start the menu by running the following command
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) (jgmenu.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 vertical and horizontal position, so try without
setting these variables first.
menu_halign and menu_valign
Again, depending on your system, you may need to manually specify horizontal and
vertical alignment of the menu, but try without 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.
┌────────────────┐
│ csv-generator │
└────────────────┘
|
V
┌────────────────┐
│ graphical menu │
└────────────────┘
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 following
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 construct 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/.config/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 Specification 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} equivalent.
.directory
Describe menu directories. Located in /usr/share/desktop-directories/, 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 specified schema file, rather than system
.menu and .directory files. Whilst this deviates from XDG menu spec, it is much simpler
to understand 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 details, 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 horizontal 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 modules 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 ~/.config/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)