1JGMENUTUTORIAL(7)                                            JGMENUTUTORIAL(7)
2
3
4

NAME

6       jgmenututorial - A step-by-step tutorial to jgmenu
7

INTRODUCTION

9       This  tutorial  aims  to  explain  the usage of jgmenu through a set of
10       lessons.
11

TABLE OF CONTENTS

13       · Lesson 1 - Get started
14       · Lesson 2 - Architecture
15       · Lesson 3 - Scripting with jgmenu
16       · Lesson 4 - Descriptions
17       · Lesson 5 - Icons
18       · Lesson 6 - Submenus
19       · Lesson 7 - XDG Application Menus
20       · Lesson 8 - Config Options
21       · Lesson 9 - Apprend/Prepend and Separators
22       · Lesson 10 - CSV generators
23       · Lesson 11 - Search
24

Lesson 1 - Get started

26       After installing jgmenu, start the menu by running the  following  com‐
27       mand
28
29              jgmenu_run
30
31       You  should see a Linux/BSD system menu showing installed applications.
32       See lesson 7 for further details.
33
34       Create a config file (~/.config/jgmenu/jgmenurc) by running
35
36              jgmenu_run init
37
38       Full  details  of  config  options  are  covered  in   jgmenu(1)   (jg‐
39       menu.1.html).
40
41       By  entering  the  interactive mode and then selecting `t', you can try
42       some pre-defined templates/themes.
43
44              jgmenu_run init -i
45
46       There are a small number of configuration options which may need manual
47       intervention in order for jgmenu to display correctly on your system.
48
49       position_mode
50              There  are several methods for positioning the menu.  Try fixed,
51              ipc, center and pointer to see what works best on  your  system.
52              See jgmenu(1) for full details.
53
54       menu_margin_x and menu_margin_y
55              If your are using position_mode=fixed, you may need to set these
56              two variables.  Depending on what window manager and  panel  you
57              use,  jgmenu may be able to automatically find a suitable verti‐
58              cal and horizontal position, so try without setting these  vari‐
59              ables first.
60
61       menu_halign and menu_valign
62              Again, depending on your system, you may need to manually speci‐
63              fy horizontal and vertical alignment of the menu, but try  with‐
64              out first.
65

Lesson 2 - Architecture

67       The design of jgmenu is very modular, providing a lot of flexibility in
68       how it is used.
69
70       When jgmenu is started, two processes are run to produce the menu.
71
72              ┌────────────────┐
73              │ csv-generator  │
74              └────────────────┘
75                      |
76                      V
77              ┌────────────────┐
78              │ graphical menu │
79              └────────────────┘
80
81       The first process (csv-generator) produces the  menu  content,  whereas
82       the second generates the graphical menu.
83
84       jgmenu_run(1)  (jgmenu_run.1.html)  is  a  multi-purpose wrapper script
85       which does the following is pseudo code:
86
87              if (jgmenu is already running)
88                      show menu
89              else
90                      start a new instance of jgmenu
91
92       This makes it suitable for using with panels and keyboard shortcuts.
93

Lesson 3 - Scripting with jgmenu

95       From this point onwards, it is assumed that you understand basic  shell
96       usage including re-direction (e.g.  <, >) and piping (e.g.  |).
97
98       The  syntax  below  (here-document) is used to denote the creation of a
99       text file from whatever is between the EOFs.  You  can  of  course  use
100       your favourite text editor instead.
101
102              cat >file <<EOF
103              foo
104              bar
105              EOF
106
107       There  are  many  ways to run jgmenu.  In lesson 1, you saw jgmenu as a
108       long-running application.  As we go through the  next  few  lessons  we
109       will  run  jgmenu  as  a  short-lived applications.  This means that it
110       starts from scratch every time it is called.
111
112       So let's get back to basics.  Try the following:
113
114              echo >foo.txt <<EOF
115              xterm
116              firefox
117              EOF
118
119       If you have not got used to the here-document syntax yet, it just means
120       that  you put the words “xterm” and “firefox” in a text file (which you
121       can of course do using a text editor).  Then run either of the  follow‐
122       ing
123
124              cat foo.txt | jgmenu --simple --icon-size=0
125
126              jgmenu --vsimple --csv-file="foo.txt"
127
128       The  option  --simple make jgmenu short-lived and reads menu items from
129       stdin.
130
131       The option --icon-size=0, disables icons (i.e. it does not just display
132       them at zero size, it simply does not load them)
133
134       The  command  line argument --vsimple is the same as --simple, but also
135       disables icons and ignores jgmenurc (if it exists).
136
137       If you want a menu to be launched by a single script,  you  could  con‐
138       struct it like this:
139
140              cat <<EOF >menu.sh
141              #!/bin/sh
142              (
143              printf "foo\n"
144              printf "bar\n"
145              ) | jgmenu --vsimple
146              EOF
147              chmod +x menu.sh
148              ./menu.sh
149

Lesson 4 - Descriptions

151       As  you  saw  in the previous example, each line fed to stdin becomes a
152       menu item.  Any line containing two fields  separated  by  a  comma  is
153       parsed as description,command.  Consider the following CSV menu data:
154
155              Terminal,xterm
156              File Manager,pcmanfm
157
158       This lets you give a more meaningful description to each menu item.
159

Lesson 5 - Icons

161       To  display  icons,  you need to populate the third field.  By default,
162       jgmenu will obtain the icon theme from xsettings (if it is running)  or
163       tint2rc  (if  it exists).  When running with the –simple argument, make
164       sure that icon_theme is set to something sensible in  your  $HOME/.con‐
165       fig/jgmenu/jgmenurc.  Consider the following CSV menu data:
166
167              Browser,        firefox,               firefox
168              File manager,   pcmanfm,               system-file-manager
169              Terminal,       xterm,                 utilities-terminal
170              Lock,           i3lock -c 000000,      system-lock-screen
171              Exit to prompt, openbox --exit,        system-log-out
172              Reboot,         systemctl -i reboot,   system-reboot
173              Poweroff,       systemctl -i poweroff, system-shutdown
174
175       In the third field you can also specify the full path if you wish.
176

Lesson 6 - Submenus

178       So  far  we have looked at producing a single “root” menu only.  jgmenu
179       understands a small amount of markup and enables submenus by ^tag() and
180       ^checkout().  Try this:
181
182              Terminal,xterm
183              File Manager,pcmanfm
184              Settings,^checkout(settings)
185
186              ^tag(settings)
187              Set Background Image,nitrogen
188
189       In pseudo-code, build your CSV file as follows:
190
191              # the root-menu
192              item0.0
193              item0.1
194              sub1,^checkout(1)
195              sub2,^checkout(2)
196
197              # the first sub-menu
198              ^tag(1)
199              item1.0
200              item1.1
201
202              # the second sub-menu
203              ^tag(2)
204              item2.0
205              item2.1
206
207       ^root() can be used instead of ^checkout() in order to open the submenu
208       in the parent window.
209

Lesson 7 - XDG Application Menus

211       XDG (freedesktop.org) have defined a Linux/BSD Desktop Menu  Specifica‐
212       tion  which is followed by the big Desktop Environments.  See menu-spec
213       (http://specifications.freedesktop.org/menu-spec/latest/)  for  further
214       details.   In brief, there are three types of files which define an XDG
215       menu:
216
217       .menu  XML file describing menu  categories  and  directory  structure.
218              Located  in  /etc/xdg/menus/,  or XDG_CONFIG_{HOME,DIRS} equiva‐
219              lent.
220
221       .directory
222              Describe menu directories.  Located in /usr/share/desktop-direc‐
223              tories/, or XDG_DATA_{HOME,DIRS} equivalent.
224
225       .desktop
226              Describe applications and contain most of the information needed
227              to build a menu (e.g.  Name, Exec command,  Icon  and  Category)
228              Located  in  /usr/share/applications/,  or  XDG_DATA_{HOME,DIRS}
229              equivalent.
230
231       Most desktop applications provided their own associated .desktop files,
232       whereas  .menu and .directory files are supplied by menu packages, such
233       as libmenu-cache (LXDE) and libcargon (XFCE).
234
235       The jgmenu core module jgmenu-apps(1) (jgmenu-apps.1.html)  provides  a
236       system menu based on .desktop files and built-in schema data or a spec‐
237       ified schema file, rather  than  system  .menu  and  .directory  files.
238       Whilst  this  deviates from XDG menu spec, it is much simpler to under‐
239       stand and tweak.  It also avoids reliance on menu packages.
240
241       For strict XDG compliance, the optional  module  jgmenu-lx(1)  (jgmenu-
242       lx.1.html) can be used.
243
244       See Lesson 10 for generic instructions on modules.
245

Lesson 8 - Config Options

247       In  lesson  1 we discussed config options position_mode, menu_margin_x,
248       menu_margin_y, menu_halign and menu_valign.
249
250       Here follow a few more options you may wish to explore.  For  full  de‐
251       tails, see jgmenu(1) (jgmenu.1.html).
252
253       Rofi style:
254
255              csv_no_dirs=1
256              csv_single_window=1
257              columns=2
258              menu_width=600
259              menu_valign=center
260              menu_halign=center
261
262       Synchronize colours, font and icons with tint2 panel
263
264              tint2_look=1
265

Lesson 9 - Apprend/Prepend and Separators

267       When  using  apps,  pmenu  or lx, you can add menu items to the top and
268       bottom of the root menu by editing  append.csv  and/or  prepend.csv  in
269       ~/.config/jgmenu.  For example, try the following:
270
271       prepend.csv
272
273              Browser,      firefox,               firefox
274              File manager, pcmanfm,               system-file-manager
275              Terminal,     xterm,                 utilities-terminal
276              ^sep()
277
278       append.csv
279
280              ^sep()
281              Suspend,      systemctl -i suspend,  system-log-out
282              Reboot,       systemctl -i reboot,   system-reboot
283              Poweroff,     systemctl -i poweroff, system-shutdown
284
285       In  these example we have used the markup ^sep(), which inserts a hori‐
286       zontal separator line.  Similarly, ^sep(foo) inserts a  text  separator
287       displaying “foo”
288

Lesson 10 - CSV generators

290       In  previous lessons, we introduced the apps, lx and pmenu.  These mod‐
291       ules are referred to as “CSV generators” and are invoked as follows:
292
293              jgmenu_run <command>
294
295       Built-in “CSV generators” include: apps and ob
296
297       Optional “CSV generators” include: lx and pmenu
298
299       They are documented by a man page or a simple –help message.
300
301              man jgmenu-<command>
302              jgmenu_run <command> --help
303
304       Here follow some examples of how they can be used.
305
306       Specify CSV generator in the config file by setting csv_cmd in  ~/.con‐
307       fig/jgmenu/jgmenurc
308
309              csv_cmd = pmenu
310
311       Specify CSV generator on the command line
312
313              jgmenu --csv-cmd="jgmenu_run pmenu"
314
315       Pipe the CSV output to jgmenu (using --simple to read from stdin)
316
317              jgmenu_run pmenu | jgmenu --simple
318
319       Create a pipemenu using ^pipe() markup.  Consider this example
320
321              Terminal,xterm
322              File Manager,pcmanfm
323              ^pipe(jgmenu_run pmenu)
324
326       jgmenu has search support, which can be invoked by just typing when the
327       menu is open.
328
329       A search box can be inserted using widgets.  For example, add  this  to
330       ~/.config/jgmenu/prepend.csv:
331
332              @search,,3,3,150,20,2,left,top,auto,#000000 0,Type to Search
333
334       Make sure you adjust menu padding accordingly, for example
335
336              menu_padding_top=24
337
338       A  search  can also be invoked by associating a widget with a ^filter()
339       command.
340

AUTHORS

342       Johan Malm.
343
344
345
346                               21 February, 2020             JGMENUTUTORIAL(7)
Impressum