.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "JGMENUTUTORIAL" "7" "21 February, 2020" "" ""
.hy
.SH NAME
.PP
jgmenututorial \- A step\-by\-step tutorial to jgmenu
.SH INTRODUCTION
.PP
This tutorial aims to explain the usage of jgmenu through a set of
lessons.
.SH TABLE OF CONTENTS
.IP \[bu] 2
Lesson 1\ \- Get started
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 2\ \- Architecture
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 3\ \- Scripting with jgmenu
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 4\ \- Descriptions
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 5\ \- Icons
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 6\ \- Submenus
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 7\ \- XDG Application Menus
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 8\ \- Config Options
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 9\ \- Apprend/Prepend and Separators
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 10 \- CSV generators
.PD 0
.P
.PD
.IP \[bu] 2
Lesson 11 \- Search
.SH Lesson 1 \- Get started
.PP
After installing jgmenu, start the menu by running the following command
.IP
.nf
\f[C]
jgmenu_run
\f[]
.fi
.PP
You should see a Linux/BSD system menu showing installed applications.
See lesson 7 for further details.
.PP
Create a config file (\f[C]~/.config/jgmenu/jgmenurc\f[]) by running
.IP
.nf
\f[C]
jgmenu_run\ init
\f[]
.fi
.PP
Full details of config options are covered in jgmenu(1) (jgmenu.1.html).
.PP
By entering the interactive mode and then selecting `t', you can try
some pre\-defined templates/themes.
.IP
.nf
\f[C]
jgmenu_run\ init\ \-i
\f[]
.fi
.PP
There are a small number of configuration options which may need manual
intervention in order for jgmenu to display correctly on your system.
.TP
.B \f[C]position_mode\f[]
There are several methods for positioning the menu.
Try \f[C]fixed\f[], \f[C]ipc\f[], \f[C]center\f[] and \f[C]pointer\f[]
to see what works best on your system.
See jgmenu(1) for full details.
.RS
.RE
.TP
.B \f[C]menu_margin_x\f[] and \f[C]menu_margin_y\f[]
If your are using \f[C]position_mode=fixed\f[], 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.
.RS
.RE
.TP
.B \f[C]menu_halign\f[] and \f[C]menu_valign\f[]
Again, depending on your system, you may need to manually specify
horizontal and vertical alignment of the menu, but try without first.
.RS
.RE
.SH Lesson 2 \- Architecture
.PP
The design of jgmenu is very modular, providing a lot of flexibility in
how it is used.
.PP
When jgmenu is started, two processes are run to produce the menu.
.IP
.nf
\f[C]
┌────────────────┐
│\ csv\-generator\ \ │
└────────────────┘
\ \ \ \ \ \ \ \ |
\ \ \ \ \ \ \ \ V
┌────────────────┐
│\ graphical\ menu\ │
└────────────────┘
\f[]
.fi
.PP
The first process (csv\-generator) produces the menu content, whereas
the second generates the graphical menu.
.PP
jgmenu_run(1) (jgmenu_run.1.html) is a multi\-purpose wrapper script
which does the following is pseudo code:
.IP
.nf
\f[C]
if\ (jgmenu\ is\ already\ running)
\ \ \ \ \ \ \ \ show\ menu
else
\ \ \ \ \ \ \ \ start\ a\ new\ instance\ of\ jgmenu
\f[]
.fi
.PP
This makes it suitable for using with panels and keyboard shortcuts.
.SH Lesson 3 \- Scripting with jgmenu
.PP
From this point onwards, it is assumed that you understand basic shell
usage including re\-direction (e.g.
<, >) and piping (e.g.
|).
.PP
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.
.IP
.nf
\f[C]
cat\ >file\ <<EOF
foo
bar
EOF
\f[]
.fi
.PP
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.
.PP
So let's get back to basics.
Try the following:
.IP
.nf
\f[C]
echo\ >foo.txt\ <<EOF
xterm
firefox
EOF
\f[]
.fi
.PP
If you have not got used to the here\-document syntax yet, it just means
that you put the words \[lq]xterm\[rq] and \[lq]firefox\[rq] in a text
file (which you can of course do using a text editor).
Then run either of the following
.IP
.nf
\f[C]
cat\ foo.txt\ |\ jgmenu\ \-\-simple\ \-\-icon\-size=0

jgmenu\ \-\-vsimple\ \-\-csv\-file="foo.txt"
\f[]
.fi
.PP
The option \f[C]\-\-simple\f[] make jgmenu short\-lived and reads menu
items from \f[C]stdin\f[].
.PP
The option \f[C]\-\-icon\-size=0\f[], disables icons (i.e.\ it does not
just display them at zero size, it simply does not load them)
.PP
The command line argument \f[C]\-\-vsimple\f[] is the same as
\f[C]\-\-simple\f[], but also disables icons and ignores jgmenurc (if it
exists).
.PP
If you want a menu to be launched by a single script, you could
construct it like this:
.IP
.nf
\f[C]
cat\ <<EOF\ >menu.sh
#!/bin/sh
(
printf\ "foo\\n"
printf\ "bar\\n"
)\ |\ jgmenu\ \-\-vsimple
EOF
chmod\ +x\ menu.sh
\&./menu.sh
\f[]
.fi
.SH Lesson 4 \- Descriptions
.PP
As you saw in the previous example, each line fed to \f[C]stdin\f[]
becomes a menu item.
Any line containing two fields separated by a comma is parsed as
\f[C]description\f[],\f[C]command\f[].
Consider the following CSV menu data:
.IP
.nf
\f[C]
Terminal,xterm
File\ Manager,pcmanfm
\f[]
.fi
.PP
This lets you give a more meaningful description to each menu item.
.SH Lesson 5 \- Icons
.PP
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 \[en]simple argument, make sure that
\f[C]icon_theme\f[] is set to something sensible in your
$HOME/.config/jgmenu/jgmenurc.
Consider the following CSV menu data:
.IP
.nf
\f[C]
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
\f[]
.fi
.PP
In the third field you can also specify the full path if you wish.
.SH Lesson 6 \- Submenus
.PP
So far we have looked at producing a single \[lq]root\[rq] menu only.
jgmenu understands a small amount of markup and enables submenus by
^tag() and ^checkout().
Try this:
.IP
.nf
\f[C]
Terminal,xterm
File\ Manager,pcmanfm
Settings,^checkout(settings)

^tag(settings)
Set\ Background\ Image,nitrogen
\f[]
.fi
.PP
In pseudo\-code, build your CSV file as follows:
.IP
.nf
\f[C]
#\ 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
\f[]
.fi
.PP
\f[C]^root()\f[] can be used instead of \f[C]^checkout()\f[] in order to
open the submenu in the parent window.
.SH Lesson 7 \- XDG Application Menus
.PP
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:
.TP
.B \f[C]\&.menu\f[]
XML file describing menu categories and directory structure.
Located in \f[C]/etc/xdg/menus/\f[], or XDG_CONFIG_{HOME,DIRS}
equivalent.
.RS
.RE
.TP
.B \f[C]\&.directory\f[]
Describe menu directories.
Located in \f[C]/usr/share/desktop\-directories/\f[], or
XDG_DATA_{HOME,DIRS} equivalent.
.RS
.RE
.TP
.B \f[C]\&.desktop\f[]
Describe applications and contain most of the information needed to
build a menu (e.g.
\f[C]Name\f[], \f[C]Exec\ command\f[], \f[C]Icon\f[] and
\f[C]Category\f[]) Located in \f[C]/usr/share/applications/\f[], or
XDG_DATA_{HOME,DIRS} equivalent.
.RS
.RE
.PP
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).
.PP
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.
.PP
For strict XDG compliance, the optional module
jgmenu\-lx(1) (jgmenu-lx.1.html) can be used.
.PP
See Lesson 10 for generic instructions on modules.
.SH Lesson 8 \- Config Options
.PP
In lesson 1 we discussed config options \f[C]position_mode\f[],
\f[C]menu_margin_x\f[], \f[C]menu_margin_y\f[], \f[C]menu_halign\f[] and
\f[C]menu_valign\f[].
.PP
Here follow a few more options you may wish to explore.
For full details, see jgmenu(1) (jgmenu.1.html).
.PP
Rofi style:
.IP
.nf
\f[C]
csv_no_dirs=1
csv_single_window=1
columns=2
menu_width=600
menu_valign=center
menu_halign=center
\f[]
.fi
.PP
Synchronize colours, font and icons with tint2 panel
.IP
.nf
\f[C]
tint2_look=1
\f[]
.fi
.SH Lesson 9 \- Apprend/Prepend and Separators
.PP
When using \f[C]apps\f[], \f[C]pmenu\f[] or \f[C]lx\f[], 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:
.PP
prepend.csv
.IP
.nf
\f[C]
Browser,\ \ \ \ \ \ firefox,\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ firefox
File\ manager,\ pcmanfm,\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ system\-file\-manager
Terminal,\ \ \ \ \ xterm,\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ utilities\-terminal
^sep()
\f[]
.fi
.PP
append.csv
.IP
.nf
\f[C]
^sep()
Suspend,\ \ \ \ \ \ systemctl\ \-i\ suspend,\ \ system\-log\-out
Reboot,\ \ \ \ \ \ \ systemctl\ \-i\ reboot,\ \ \ system\-reboot
Poweroff,\ \ \ \ \ systemctl\ \-i\ poweroff,\ system\-shutdown
\f[]
.fi
.PP
In these example we have used the markup ^sep(), which inserts a
horizontal separator line.
Similarly, ^sep(foo) inserts a text separator displaying \[lq]foo\[rq]
.SH Lesson 10 \- CSV generators
.PP
In previous lessons, we introduced the \f[C]apps\f[], \f[C]lx\f[] and
\f[C]pmenu\f[].
These modules are referred to as \[lq]CSV generators\[rq] and are
invoked as follows:
.IP
.nf
\f[C]
jgmenu_run\ <command>
\f[]
.fi
.PP
Built\-in \[lq]CSV generators\[rq] include: \f[C]apps\f[] and
\f[C]ob\f[]
.PP
Optional \[lq]CSV generators\[rq] include: \f[C]lx\f[] and
\f[C]pmenu\f[]
.PP
They are documented by a man page or a simple \[en]help message.
.IP
.nf
\f[C]
man\ jgmenu\-<command>
jgmenu_run\ <command>\ \-\-help
\f[]
.fi
.PP
Here follow some examples of how they can be used.
.PP
Specify CSV generator in the config file by setting \f[C]csv_cmd\f[] in
\f[C]~/.config/jgmenu/jgmenurc\f[]
.IP
.nf
\f[C]
csv_cmd\ =\ pmenu
\f[]
.fi
.PP
Specify CSV generator on the command line
.IP
.nf
\f[C]
jgmenu\ \-\-csv\-cmd="jgmenu_run\ pmenu"
\f[]
.fi
.PP
Pipe the CSV output to jgmenu (using \f[C]\-\-simple\f[] to read
from\ \f[C]stdin\f[])
.IP
.nf
\f[C]
jgmenu_run\ pmenu\ |\ jgmenu\ \-\-simple
\f[]
.fi
.PP
Create a pipemenu using ^pipe() markup.
Consider this example
.IP
.nf
\f[C]
Terminal,xterm
File\ Manager,pcmanfm
^pipe(jgmenu_run\ pmenu)
\f[]
.fi
.SH Lesson 11 \- Search
.PP
jgmenu has search support, which can be invoked by just typing when the
menu is open.
.PP
A search box can be inserted using widgets.
For example, add this to ~/.config/jgmenu/prepend.csv:
.IP
.nf
\f[C]
\@search,,3,3,150,20,2,left,top,auto,#000000\ 0,Type\ to\ Search
\f[]
.fi
.PP
Make sure you adjust menu padding accordingly, for example
.IP
.nf
\f[C]
menu_padding_top=24
\f[]
.fi
.PP
A search can also be invoked by associating a widget with a ^filter()
command.
.SH AUTHORS
Johan Malm.