jgmenu - How a graphical menu is built

damo · 2020-03-01 23:51:41

How jgmenu builds a graphical menu

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 │ --> │ graphical menu │
└───────────────┘     └────────────────┘

The first process produces the menu content, whereas the second generates the graphical menu.

jgmenu_run is a multi-purpose wrapper script which does the following in 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.

csv generators

USAGE:  jgmenu_run pmenu|lx|apps|ob

lx generates jgmenu flavoured CSV menu data for freedesktop.org defined application menus, using LXDE's libmenu-cache.
pmenu The original python script to generate jgmenu flavoured CSV menu data based on .desktop and .directory files found on the system, but ignoring any .menu files.
apps generates jgmenu flavoured CSV menu data for system applications using built-in schema data or a specified schema file to map categories to directories, rather than system .directory files.
ob converts existing openbox XML menu data to jgmenu flavoured CSV, but doesn't generate menu data for system applications.

To illustrate what a csv-generator is, let's use a very simplistic case of a system application menu:

#!/bin/bash
for f in /usr/share/applications/*.desktop; do
  app=$(grep '^Exec=' $f)
  echo ${app#*=}
done

The output generated by this must be processed to make it csv-formatted in a way that can be used by jgmenu, which is packaged with a number of csv-generators (also referred to as modules). The modules apps, pmenu, and lx produce 'system application' menus, and you can add menu items to the top and bottom of the root menu by editing prepend.csv and/or append.csv.

They produce menu csv structured like this:

┌──────────────────────────────┐
│ prepend.csv content          │
├──────────────────────────────┤<-- This is where "^tag(apps)" must appear
│ (supplied by csv-generator..)|    if you want to show System Applications
│ Graphics,^checkout(Graphics) │    
│ System,^checkout(System)     │        
│ etc.                         │
│                              │
├──────────────────────────────┤
│ append.csv content           │
├──────────────────────────────┤
│ (supplied by csv-generator..)|
| ^tag(Graphics)               |
│ gimp                         │
│ etc.                         │
│                              │
│ ^tag(System)                 │
│ xterm                        │
│ etc.                         │
└──────────────────────────────┘

Let's ignore append.csv and focus on prepend.csv. We could just populate prepend.csv with a few apps, to produce a menu like this:

┌──────────────────────────────┐
│ xterm                        │
│ firefox                      │
├──────────────────────────────┤
│ Graphics,^checkout(Graphics) │
│ System,^checkout(System)     │
│ etc.                         │
│                              │
│ ^tag(Graphics)               │
│ gimp                         │
│ etc.                         │
│                              │
│ ^tag(System)                 │
│ xterm                        │
│ etc.                         │
└──────────────────────────────┘

In the new BunsenLabs menu, we've put a ^tag(apps) line at the end of the prepend.csv file. In order to understand this trick, you have to realise that the process which draws the graphics menu merely reads lines from the csv-generator and is completely oblivious to how the csv-generator actually does its job.

In the example below, jgmenu will interpret the ^tag(apps) line as the node-definition for the 'system application' menu (beginning with "Graphics").

The result of this ^tag() line is therefore that the 'system applications' is cut off from the root-menu and becomes a submenu by using ^checkout() or ^root().

┌──────────────────────────────┐
│ xterm                        │
│ firefox                      │
│ applications,^checkout(apps) │
│                              │
│ ^tag(apps)                   │
├──────────────────────────────┤
│ Graphics,^checkout(Graphics) │
│ System,^checkout(System)     │
│ etc.                         │
│                              │
│ ^tag(Graphics)               │
│ gimp                         │
│ etc.                         │
│                              │
│ ^tag(System)                 │
│ xterm                        │
│ etc.                         │
└──────────────────────────────┘

Does ^tag(apps) have to come at the end?

Yes. Although it doesn't have to be "apps", it just needs to correspond with the "Applications, ^checkout(whatever)" line further up in prepend.csv, where you want it to appear in the menu.
It's a hack to avoid showing the "desktop-directories" in the root menu.
Above the ^tag(apps) line, we can add anything we want - just as we have in the new BunsenLabs menu.
Below it you can add anything that you want to appear at the top of the Applications submenu.

Sourcing of files works just like it should in a shell script - i.e. the content of the sourced file replaces the lines which does the sourcing (the line beginning with a dot). So, as long as the net result of any sourcing leaves the last line of the prepend.csv file as that magic ^tag() line, you can source files in any way/order you want.

Extracting Applications csv data

It is possible to create a menu displaying only the Applications data, by the use of an environment variable to disregard prepend.csv and append.csv. Either show an apps-only menu directly, or save the csv to a file which could then be sourced by jgmenu --simple.

JGMENU_NO_PEND can be set for apps or lx:

JGMENU_NO_PEND=1 jgmenu_run apps|lx | jgmenu --simple
.
or
.
JGMENU_NO_PEND=1 jgmenu_run apps|lx > mymenu.csv

#1 2020-03-01 23:51:41