Jump to content

# xdg-menu

From ArchWiki

xdg-menu is a tool that generates XDG Desktop Menus for the following window managers:

- awesome
- Blackbox
- Fluxbox
- FVWM
- IceWM
- JWM
- Openbox
- twm
- Window Maker

KDE, GNOME, Xfce and Enlightenment are already XDG compatible.

## Installation

Install the archlinux-xdg-menu package.

## Menu hierarchy

- Applications
  - Accessibility
  - Accessories
  - Development
  - Education
  - Games
  - Graphics
  - Internet
  - Multimedia
  - Office
  - Other
  - Science
  - Settings
  - System

## Configuration

xdg_menu relies on three sets of information to generate menus: a root menu or in other words an XML menu template generally passed on the command line, information cached when it was last run, and a series of configuration files.

- You can find some XML menu templates in `/etc/xdg/menus`.
- If altering the code in xdg_menu to change layout, make sure you delete everything in `~/.xdg_menu_cache` or you will spend hours trying to figure out why your changes to the perl script do not take.
- You can find individual application configurations in `/usr/share/applications`.

Other configuration file directories can be found under `/usr/share`. In most cases you will not need to touch these. However if you want to change how your menu is layed out you can alter the menu template for minor changes. Major changes require tweaking the actual xdg_menu perl script. If you find that applications do not appear or that they are called strange things, then you will need to look at the .desktop file in `/usr/share/applications`. Check the desktop entry specification.

### Adding desktop entries from other directories

By default, the Xdg-menu will be populated with applications which install their desktop entries to `/usr/share/applications`. To add applications to the menu which install their desktop entry to a user folder such as `~/.local/share/applications`, edit the `/etc/xdg/menus/arch-applications.menu` file and add an `<AppDir>` tag for the relevant directory, see below:

    /etc/xdg/menus/arch-applications.menu

    <Menu>

      <Name>Applications</Name>
      <Directory>Arch-Applications.directory</Directory>
      <DefaultAppDirs/>
      <AppDir>/home/username/.local/share/applications</AppDir>
      <DefaultDirectoryDirs/>
      <DefaultMergeDirs/>
      ...

## Usage

### xdg_menu

    xdg_menu [--format <format>] [--desktop <desktop>]
             [--charset <charset>] [--language <language>]
    	 [--root-menu <root-menu>] [--die-on-error]
    	 [--fullmenu] [--help]

    	format - output format
    	         possible formats: twm, WindowMaker, fvwm2, icewm, ion3
    	                           blackbox, fluxbox, openbox,
    				   xfce4, openbox3, openbox3-pipe, awesome
    				   readable
    		 default: WindowMaker

     	fullmenu  - output a full menu and not only a submenu

    	desktop - desktop name for NotShowIn and OnlyShowIn
    		 default: the same as format

    	charset - output charset
    		 default: <locale>

    	language - output language
    		 default: <locale>

    	root-menu - location of root menu file
    		 default: /etc/xdg/menus/arch-applications.menu

    	die-on-error - abort execution on any error,
    		 default: try to continue

    	verbose - print debugging information

    	help - print this text

### update-menus

update-menus updates WM's menus from XDG data and can be configured to do it automaticaly.

This is a script wrapper around xdg_menu that relies on `/etc/update-menus.conf`

To use it, you need to install the archlinux-xdg-menu package (xdg_menu)

In `/etc/update-menus.conf`, you have to select from a list of window managers for which the menu should be generated. Comments with # are allowed.

All generated menus are placed in `/var/cache/xdg-menu/`. See wm-specific #Examples section of this page to get more information.

## Examples

### Awesome

#### With xdg_menu

Generate the menu:

    $ xdg_menu --format awesome > ~/.config/awesome/xdg_menu.lua

Then, edit file `~/.config/awesome/rc.lua` as shown below.

- Add a require statement for your new `menu.lua` file.
- Add an entry to your `awful.menu` object for your new menu which calls `xdg-menu`.

    ...
    xdg_menu = require("xdg_menu")
    ...

    ...
    mymainmenu = awful.menu({ items = { { "awesome", myawesomemenu, beautiful.awesome_icon },
                                        { "Applications", xdgmenu },
                                        { "open terminal", terminal }
                                      }
                            })
    ...

### Blackbox

#### With xdg_menu

Generate the menu:

    $ xdg_menu --format blackbox > ~/.blackbox/xdg_menu

Change file `~/blackbox/menu` to include the generated menu. For example, add this line:

    [include] (xdg_menu)

#### With update-menus

- Uncomment blackbox in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Change file `~/blackbox/menu` to include the generated menu:

    [include] (/var/cache/xdg-menu/blackbox/boxrc)

### Fluxbox

#### With xdg_menu

Generate the menu:

    $ xdg_menu --format fluxbox > ~/.fluxbox/xdg_menu

Change file `~/fluxbox/menu` to include the generated menu. For example, add this line:

    [include] (xdg_menu)

#### With update-menus

- Uncomment fluxbox in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Change file `~/fluxbox/menu` to include generated menu:

    [include] (/var/cache/xdg-menu/fluxbox/boxrc)

### Fvwm

#### With xdg_menu

Generate the menu:

    $ xdg_menu --format fvwm2 > ~/.fvwm/xdg_menu

Change file `~/.fvwm/config` to read the generated menu and add it into the root menu:

    read xdg_menu
    ...
    AddToMenu MenuFvwmRoot  "Fvwm" Title
    ...
    +                       "&0. Applications" Popup xdg_menu
    ...

#### With update-menus

- Uncomment fvwm2 in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Change file `.fvwm` to read the generated menu and add it into the root menu:

    read /var/cache/xdg-menu/fvwm2/fvwm2rc
    ...
    AddToMenu MenuFvwmRoot  "Fvwm" Title
    ...
    +                       "&0. Applications" Popup xdg_menu
    ...

### IceWM

#### With xdg_menu

Add the following line to `~/.icewm/menu`:

    includeprog xdg_menu --format icewm

Or just run the following command to add below the Programs menu:

    $ xdg_menu --format icewm >> ~/.icewm/programs

#### With update-menus

- Uncomment icewm in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Add the following line to `~/.icewm/menu`:

    include "/var/cache/xdg-menu/icewm/programs"

Or just make a symlink to `/var/cache/xdg-menu/icewm/programs` in `~/.icewm/programs` to add below the Programs menu.

### JWM

#### With xdg_menu

Add the following line below the `<RootMenu>` element in `~/.jwmrc`:

    <Include>exec: xdg_menu --format jwm --fullmenu</Include>

#### With update-menus

- Uncomment jwm in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Add the following line below the `<RootMenu>` element in `~/.jwmrc`:

    <Include>/var/cache/xdg-menu/jwm/menu.xml</Include>

### Openbox

Using xdg_open as a pipe menu gives you the added benefit of having a menu that automatically updates when you install new applications.

Add the following line below the `<menu id="root-menu">` element in `~/.config/openbox/menu.xml`:

    <menu id="applications" label="Applications" execute="xdg_menu --format openbox3-pipe" />

A very basic example:

    <?xml version="1.0" encoding="UTF-8"?>

    <openbox_menu xmlns="http://openbox.org/3.4/menu">

    <menu id="root-menu" label="Openbox 3">
      <menu id="applications" label="Applications" execute="xdg_menu --format openbox3-pipe" />
      <separator />
      <item label="Log Out">
        <action name="Exit">
          <prompt>yes</prompt>
        </action>
      </item>
    </menu>

    </openbox_menu>

#### With update-menus

- Uncomment openbox in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Add the following line below the `<menu id="root-menu">` element in `~/.config/openbox/menu.xml`:

    <menu id="applications" label="Applications" execute="cat /var/cache/xdg-menu/openbox/menu.xml"/>

### twm

#### With xdg_menu

Use:

    $ xdg_menu --format twm > my-twm-menu

And add it into `~/.twmrc` manually. In the case of twm derivatives with m4 preprocessing such as vtwm or ctwm it can be included by adding:

    sinclude(`/PATH/TO/my-twm-menu')

To `*twmrc`.

#### With update-menus

- Uncomment twm in `/etc/update-menus.conf`.
- Add in `/etc/X11/twm/system.twmrc` a file applications menu (add it into `defops menu`):

     "apps"          f.menu "Applications"

- Run `update-menus` as root.
- Run `twm -f /var/cache/xdg-menu/twm/twmrc`.

Tip You will also want to add your other customizations to `/etc/X11/twm/system.twmrc`.

### WindowMaker

#### With xdg_menu

Use:

    $ xdg_menu --format WindowMaker > my-wm-menu

And add:

    #include "my-wm-menu"

Into your WindowMaker menu file.

You can also use the WPrefs "Application Menu Definitions", and add the xdg command as a parameter in a "Generated Submenu" object.

#### With update-menus

- Uncomment WindowMaker in `/etc/update-menus.conf`.
- Run `update-menus` as root.
- Add:

    #include "/var/cache/xdg-menu/WindowMaker/wmrc"

Into your menu file.

## See also

- Sawfish#Menus
- https://github.com/gapan/xdgmenumaker

Category:

- Freedesktop.org

xdg-menu
Add topic