E17 and Efreet

A "Cheat Sheet" for the E17 implementation of the desktop menu spec. Might help some folks setup their machine to use the new efreet code. Efreet utilizes your .menu files, .desktop files, and has an impact on your border icons. The samples below are intentionally simplistic. Much more can be accomplished.

The Specifications of Interest

The Desktop Menu Specification can be found here (explains .menu files):

  [1]http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html

The Desktop Entry Specification is here (explains .desktop files):

  [2]http://standards.freedesktop.org/desktop-entry-spec/latest/

The Base Directory Specification

  [3]http://standards.freedesktop.org/basedir-spec/latest/ar01s03.html

Environment Variables

The following is a set of environment variables used within the implementation, as well as their fallback value should you not have that particular variable defined.

Environment Vars Used    Fallback (If undefined)
======================================================
HOME                     "/tmp"
XDG_MENU_PREFIX          ""
XDG_CONFIG_HOME          "$HOME/.config"
XDG_CONFIG_DIRS          "/etc/xdg"
XDG_DATA_HOME            "$HOME/.local/share"
XDG_DATA_DIRS            "/usr/local/share:/usr/share"
XDG_CACHE_HOME           "$HOME/.cache"

Search path for Applications (.desktops):

 $XDG_DATA_HOME/applications: $XDG_DATA_DIRS/applications

Search path for Menus (applications.menu):

 $XDG_CONFIG_HOME/menus/$XDG_MENU_PREFIXapplications.menu: $XDG_CONFIG_DIRS/menus/$XDG_MENU_PREFIXapplications.menu

Note the $XDG_MENU_PREFIX above. This is useful for those gnome-applications.menu or kde-applications.menu files you have laying around. To use the gnome and kde applications menus already present on your machine, you would set $XDG_MENU_PREFIX to "gnome-" and "kde-" repectively.

Samples

What is significant in the below sample files (among other things) is that the .desktops have categories defined that correspond to the categories of the menus in the .menu file. Only menus which do contain menu items will be visible.

Sample "applications.menu"

Be sure to put your applications menu somewhere within the search path mentioned above.

<?xml version="1.0"?>
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">

<Menu>

  <Name>Applications</Name>

  <!-- Read .desktop file from only this location -->
  <!-- Or remove and use the two items below      -->
  <AppDir>/home/ravenlock/.local/share/applications</AppDir>

  <!-- Read standard .directory and .desktop file locations -->
  <!-- by uncommenting these.                               -->
  <!-- <DefaultAppDirs/> -->
  <!-- <DefaultDirectoryDirs/> -->

  <!-- Define a layout                                         -->
  <!-- The Layout is what gives your menu its sort order.      -->
  <!-- Without this section the menu is sorted alphabetically. -->
  <Layout>
          <Menuname>Testing</Menuname>
          <Separator/>
          <Menuname>Testing2</Menuname>
  </Layout>

  <!-- Testing submenu -->
  <Menu>
    <Name>Testing</Name>
    <Include> <Category>TestingCat</Category> </Include>

        <Menu>
            <Name>Testing-sub</Name>
            <Include> <Category>TestingCatSub</Category> </Include>
        </Menu> <!-- End Testing submenu -->

  </Menu> <!-- End Testing submenu -->
  
  <!-- Testing2 submenu -->
  <Menu>
    <Name>Testing2</Name>
    <Include> <Category>TestingCat2</Category> </Include>

        <Menu>
            <Name>Testing-sub2</Name>
            <Include> <Category>TestingCatSub2</Category> </Include>
        </Menu> <!-- End Testing submenu -->

  </Menu> <!-- End Testing2 submenu -->

</Menu> <!-- End Applications -->

Sample .desktop files

Be sure to place your .desktop files in a location within the search path mentioned above.

[Desktop Entry]
Type=Application
Exec=gqview ~/MyDocs/MyPics
StartupWMClass=GQview
Icon=/home/ravenlock/MyDocs/e-icons/gqview.png
Categories=TestingCat
Name=GQview

[Desktop Entry]
Type=Application
Exec=tsclient
StartupWMClass=Tsclient
Icon=/home/ravenlock/MyDocs/e-icons/tsclient.png
Name=Tsclient
Categories=TestingCatSub

Border Icons

Your window border icons are also impacted by the new efreet code. In order for efreet to match an application window to a .desktop file, it uses the StartupWMClass key within the file. Given the above example .desktop files, any applications that run which set their icccm class to GQview or Tsclient will get matched to one of these files and have the border icon set accordingly.

With that said... There is one other thing you might want to be aware of. There may arise a situation in which E may need to decide which .desktop file should be matched to an application, when there exists more than one .desktop file with a StartupWMClass which matches.

This may occur simply because you desire to launch various "applications" from the menu, each with a unique icon in the menu, but actually utilizing one particular binary. For me, firefox is one such example (see below). Another example would be when launching various cli tools from the menu using a command line such as `xterm -e <program>`.

Take the following three .desktop files as an example:

a.desktop
  [Desktop Entry]
  StartupWMClass=Firefox-bin
  Icon=/home/ravenlock/MyDocs/e-icons/firefox.png
  Type=Application
  Exec=firefox
  Name=Firefox Web Browser
  Categories=Browsers

b.desktop
  [Desktop Entry]
  StartupWMClass=Firefox-bin
  Icon=/home/ravenlock/MyDocs/e-icons/ntop.png
  Type=Application
  Exec=firefox http://localhost:3000
  Name=NTop
  Categories=LAN_Utils

c.desktop
  [Desktop Entry]
  StartupWMClass=Firefox-bin
  Icon=/home/ravenlock/MyDocs/e-icons/cups.png
  Type=Application
  Exec=firefox http://localhost:631
  Name=CUPS Administration
  Categories=Control_Panel

Given the above .desktop files... your Firefox application will always have the cups.png icon. This is because efreet prepends each .desktop file it finds to its list of files which have the StartupWMClass of Firefox-bin. And then, when it looks for an icon to use for a border, it uses the first desktop in the list (which was the last added).

The solution is to make sure you have one and only one .desktop file with a StartupWMClass for each unique application. Using the above files again, you would remove the StartupWMClass key from files b.desktop and c.desktop. This would allow you to have a variety of icons in your menus, while guaranteeing that your border icons are what you expect.

Distribution Specific Instructions

Debian/Ubuntu

If you want Ubuntu to generate a menu for you, you first need these packages installed: menu, menu-xdg and xdg-utils. If you have those two packages installed, then a menu file (/etc/xdg/menus/debian-menu.menu) will be generated. For this file to be used by Enlightenment you must create a symlink to it at /etc/xdg/menus/applications.menu

sudo ln -s /etc/xdg/menus/debian-menu.menu /etc/xdg/menus/applications.menu

After you have done this the menu should appear correctly no restart should be necessary.

Alternatively you can set XDG_MENU_PREFIX="debian-" in the environment that e17 is run in.

Archlinux

To use in e17 the archlinux menu, you have, like in ubuntu, to install xdg-menu (you can find it on aur) and then launch (as root or using sudo) the command:

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

Gentoo

When a Gentoo package is installed it doesn't create all of the entries needed for the freedesktop XDG menu to automatically "Just Work™". The easiest way to get menus working is often to,

$ emerge gnome-menus
$ gnome-menu-spec-test

If you don't have GNOME or any of its dependencies, you can emerge gnome-menus with the --nodeps options,

$ emerge --nodeps gnome-menus

If you have glib and GTK+ installed, gnome-menus should compile and setup the XDG structures needed for menus to appear in E17.

KDE Paths

Some environment variables are missing. This,

XDG_CONFIG_DIRS="$XDG_CONFIG_DIRS:/usr/kde/3.5/etc/xdg"
XDG_DATA_DIRS="$XDG_DATA_DIRS:/usr/kde/3.5/share"

should be defined in /etc/env.d/45kdepaths-3.5. Run env-update and restart your session to use the new variables.

The Manual Way

As a last resort, you can compile gnome-menus yourself and use the provided files as templates. Start by downloading a source tarball. Unpack it to a temporary directory,

$ tar xvjf gnome-menus-<version>.tar.bz2 -C /tmp

Run the configure script found in gnome-menus-<version>/ with the --prefix= option, make and last make install,

$ ./configure --prefix=/tmp/xdg_stuff
$ make
$ make install

To have the XDG menus available system-wide. Copy the relevant directories,

$ cp /tmp/etc/xdg /etc/ -R
$ cp /tmp/share/desktop-directories /usr/share/ -R 

Or for per user, create ~/.local/etc and ~/.local/share directories (you might already have these), then,

$ cp /tmp/etc/xdg ~/.local/etc/ -R
$ cp /tmp/share/desktop-directories ~/.local/share -R 

And last, add,

XDG_CONFIG_DIRS="/etc/xdg:$HOME/.local/etc/xdg"
XDG_DATA_DIRS="/usr/share:/usr/local/share:$HOME/.local/share"

export XDG_CONFIG_DIRS XDG_DATA_DIRS

to your ~/.bash_profile, or to whatever you use to export your env. settings on login.

Now restart E17, login and logout if you changed your env. settings, and your menus should appear. Edit the files in /etc/xdg/ and /usr/share/desktop-directories/ to suit your needs and desires.