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

Submenus in favorites menu

E17 still can display submenus in the user-definable favorites menu, though you cannot edit such a structure with the configuration GUI. You have to write the ~/.e/e/applications/menu/favorite.menu file yourself. And beware, do not use Menus->Favorite Menu in the configuration panel anymore then, or your menu will be lost... (unless you have a backup ;-)

The key to submenus is to have some <Menuname> tags in a <Layout> section, as shown in the example below. In the following, the named menus must be defined with their own <Menu> sections, and this section has to be at the same level as the <Layout> that introduced them.

It is also possible to mix simple menu items with submenus ("Subsubmenu 3" example below). The trick here is that simple items, represented by a <Filename> in the <Layout> section, have to be repeated in <Include> to be really included in the menu. A submenu item, however, needs its corresponding <Menu> section.

<?xml version="1.0"?>
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://standards.freedesktop.org/menu-spec/menu-1.0.dtd">
<Menu>
  <Name>(null)</Name>
  <Layout>
    <Menuname>Submenu 1</Menuname>
    <Menuname>Submenu 2</Menuname>
  </Layout>
  <Menu>
    <Name>Submenu 1</Name>
    <Layout>
      <Filename>app1.desktop</Filename>
      <Filename>app2.desktop</Filename>
      <Menuname>Subsubmenu 3</Menuname>
    </Layout>
    <Include>
      <Filename>app1.desktop</Filename>
      <Filename>app2.desktop</Filename>
    </Include>
    <Menu>
      <Name>Subsubmenu 3</Name>
      <Include>
        <Filename>app3.desktop</Filename>
        <Filename>app4.desktop</Filename>
        <Filename>app5.desktop</Filename>
      </Include>
    </Menu>
  </Menu>
  <Menu>
    <Name>Submenu 2</Name>
    <Include>
      <Filename>app6.desktop</Filename>
      <Filename>app7.desktop</Filename>
    </Include>
  </Menu>
</Menu>

A final hint: In menus that do not have submenus, the <Layout> section is not really needed. It's ok to only have an <Include> listing the wanted .desktop files. If <Layout> is omitted the applications will be in some random order.

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.

On the other hand, you might want to have different icons for the same application. For example, you wish to see different border icons for user and root shells, but each xterm instance obviously has the same ICCCM class ("XTerm").

The key to the solution for this task is the fact that Enlightenment not only matches the ICCCM class against StartupWMClass in .desktop files, but also the ICCCM name. (Unfortunately with lower priority... see below.) This means, if you have the following two .desktop files:

xterm_user.desktop:
  [Desktop Entry]
  Type=Application
  Name=Shell (User)
  Icon=/home/me/icons/xterm_user.png
  StartupWMClass=xterm_user
  Exec=xterm -name xterm_user

xterm_root.desktop:
  [Desktop Entry]
  Type=Application
  Name=Shell (Root)
  Icon=/home/me/icons/xterm_root.png
  StartupWMClass=xterm_root
  Exec=xterm -name xterm_root -e su

then the two variants of xterms will have different ICCCM names ("xterm_user" and "xterm_root", resp.), but still the same class ("XTerm"). So, if Enlightenment does not find any .desktop file with StartupWMClass=XTerm, it will start matching ICCCM names and will find one of the .desktop files above and use the icon mentioned in there.

So the crux is the condition "no .desktop file with StartupWMClass=XTerm"... Luckily, my /usr/share/applications does not contain such a file and I've deleted the one created by E at first start, so it works for me (TM;) But admittedly this condition can be tough if you don't want to modify system files.

It might be easier if Enlightenment would match the ICCCM name with priority, i.e. before the class. Or --to resemble E16's icondefs.cfg capabilities-- maybe also match the ICCCM command against the Exec= field of desktop files, which would be even easier in some circumstances.

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. On a new installation of enlightenment-17, the menu "Applications" is empty , so you must install gnome-menus with this version =2.24.2 . In fact newer version like 2.26 or 2.28 , the menu stay empty !

$ emerge =gnome-menus-2.24.2
$ gmenu-simple-editor

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

$ emerge --nodeps  =gnome-menus-2.24.2

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.