1JGMENUTUTORIAL(7) JGMENUTUTORIAL(7)
2
6 jgmenututorial - A step-by-step tutorial to jgmenu
7
9 This tutorial aims to explain the usage of jgmenu through a set of
10 lessons.
11
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
26 After installing jgmenu, start the menu by running the following com‐
27 mand
28 jgmenu_run
30 You should see a Linux/BSD system menu showing installed applications.
32 See lesson 7 for further details.
33 Create a config file (~/.config/jgmenu/jgmenurc) by running
35 jgmenu_run init
37 Full details of config options are covered in jgmenu(1) (jg‐
39 menu.1.html).
40 By entering the interactive mode and then selecting `t', you can try
42 some pre-defined templates/themes.
43 jgmenu_run init -i
45 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 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 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 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
67 The design of jgmenu is very modular, providing a lot of flexibility in
68 how it is used.
69 When jgmenu is started, two processes are run to produce the menu.
71 ┌────────────────┐
73 │ csv-generator │
74 └────────────────┘
75 |
76 V
77 ┌────────────────┐
78 │ graphical menu │
79 └────────────────┘
80 The first process (csv-generator) produces the menu content, whereas
82 the second generates the graphical menu.
83 jgmenu_run(1) (jgmenu_run.1.html) is a multi-purpose wrapper script
85 which does the following is pseudo code:
86 if (jgmenu is already running)
88 show menu
89 else
90 start a new instance of jgmenu
91 This makes it suitable for using with panels and keyboard shortcuts.
93
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 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 cat >file <<EOF
103 foo
104 bar
105 EOF
106 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 So let's get back to basics. Try the following:
113 echo >foo.txt <<EOF
115 xterm
116 firefox
117 EOF
118 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 cat foo.txt | jgmenu --simple --icon-size=0
125 jgmenu --vsimple --csv-file="foo.txt"
127 The option --simple make jgmenu short-lived and reads menu items from
129 stdin.
130 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 The command line argument --vsimple is the same as --simple, but also
135 disables icons and ignores jgmenurc (if it exists).
136 If you want a menu to be launched by a single script, you could con‐
138 struct it like this:
139 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
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 Terminal,xterm
156 File Manager,pcmanfm
157 This lets you give a more meaningful description to each menu item.
159
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 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 In the third field you can also specify the full path if you wish.
176
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 Terminal,xterm
183 File Manager,pcmanfm
184 Settings,^checkout(settings)
185 ^tag(settings)
187 Set Background Image,nitrogen
188 In pseudo-code, build your CSV file as follows:
190 # the root-menu
192 item0.0
193 item0.1
194 sub1,^checkout(1)
195 sub2,^checkout(2)
196 # the first sub-menu
198 ^tag(1)
199 item1.0
200 item1.1
201 # the second sub-menu
203 ^tag(2)
204 item2.0
205 item2.1
206 ^root() can be used instead of ^checkout() in order to open the submenu
208 in the parent window.
209
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 .menu XML file describing menu categories and directory structure.
218 Located in /etc/xdg/menus/, or XDG_CONFIG_{HOME,DIRS} equiva‐
219 lent.
220 .directory
222 Describe menu directories. Located in /usr/share/desktop-direc‐
223 tories/, or XDG_DATA_{HOME,DIRS} equivalent.
224 .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 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 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 For strict XDG compliance, the optional module jgmenu-lx(1) (jgmenu-
242 lx.1.html) can be used.
243 See Lesson 10 for generic instructions on modules.
245
247 In lesson 1 we discussed config options position_mode, menu_margin_x,
248 menu_margin_y, menu_halign and menu_valign.
249 Here follow a few more options you may wish to explore. For full de‐
251 tails, see jgmenu(1) (jgmenu.1.html).
252 Rofi style:
254 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 Synchronize colours, font and icons with tint2 panel
263 tint2_look=1
265
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 prepend.csv
272 Browser, firefox, firefox
274 File manager, pcmanfm, system-file-manager
275 Terminal, xterm, utilities-terminal
276 ^sep()
277 append.csv
279 ^sep()
281 Suspend, systemctl -i suspend, system-log-out
282 Reboot, systemctl -i reboot, system-reboot
283 Poweroff, systemctl -i poweroff, system-shutdown
284 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
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 jgmenu_run <command>
294 Built-in “CSV generators” include: apps and ob
296 Optional “CSV generators” include: lx and pmenu
298 They are documented by a man page or a simple –help message.
300 man jgmenu-<command>
302 jgmenu_run <command> --help
303 Here follow some examples of how they can be used.
305 Specify CSV generator in the config file by setting csv_cmd in ~/.con‐
307 fig/jgmenu/jgmenurc
308 csv_cmd = pmenu
310 Specify CSV generator on the command line
312 jgmenu --csv-cmd="jgmenu_run pmenu"
314 Pipe the CSV output to jgmenu (using --simple to read from stdin)
316 jgmenu_run pmenu | jgmenu --simple
318 Create a pipemenu using ^pipe() markup. Consider this example
320 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 A search box can be inserted using widgets. For example, add this to
330 ~/.config/jgmenu/prepend.csv:
331 @search,,3,3,150,20,2,left,top,auto,#000000 0,Type to Search
333 Make sure you adjust menu padding accordingly, for example
335 menu_padding_top=24
337 A search can also be invoked by associating a widget with a ^filter()
339 command.
340
342 Johan Malm.
343 21 February, 2020 JGMENUTUTORIAL(7)