From aff77c19cc68a3d6499fd285e575fce01e946dc1 Mon Sep 17 00:00:00 2001 From: Waldo Bastian Date: Wed, 29 Mar 2006 00:52:48 +0000 Subject: Added example for installing sub-menu. --- menu/ChangeLog | 8 ++ menu/menu-spec.xml | 264 ++++++++++++++++++++++++++++++++++++----------------- 2 files changed, 187 insertions(+), 85 deletions(-) diff --git a/menu/ChangeLog b/menu/ChangeLog index ace3601..21cc418 100644 --- a/menu/ChangeLog +++ b/menu/ChangeLog @@ -1,3 +1,11 @@ +2006-03-28 Waldo Bastian + + * menu-spec.xml: Added example for installing sub-menu. + +2006-03-21 Waldo Bastian + + * menu-spec.xml: Recommend to use /usr/share for datadir + 2005-03-30 Waldo Bastian * menu-spec.xml: Change semantics and remove restrictions on diff --git a/menu/menu-spec.xml b/menu/menu-spec.xml index 3c37c8d..268fe45 100644 --- a/menu/menu-spec.xml +++ b/menu/menu-spec.xml @@ -1,6 +1,6 @@ + ]> @@ -8,14 +8,14 @@ Desktop Menu Specification Version &version; - 21 March 2006 + 28 March 2006 Waldo Bastian
- bastian@kde.org + waldo.bastian@intel.com
@@ -1906,88 +1906,182 @@ entries: Categories, - How to add your application to the menus - - The short answer for third party applications is: - - - - Install desktop entries to - datadir/applications/ for each menu - item. Please namespace the filename, as in "vendor-foo.desktop", or - use a subdirectory of - datadir/applications/ so you have - "vendor/foo.desktop." Please be sure all desktop entries are valid - (see the - desktop-file-utils package for a validation utility). - - - - - Install an XML menu file to sysconfdir/desktop/menus/applications-merged/ to add any submenus, if your desktop entries aren't already - included in some common categories. - - - - - Install any directory entries needed for your submenus to datadir/desktop-directories/, taking care to namespace and validate - the directory entries. - - - - - - If an application is intended to be installed by root on a system wide - basis then /usr/share should be used as value for - datadir and /etc/xdg should be used as value - for sysconfdir. - In case the /usr/share hierarchy is not writable it is recommended to - use /usr/local/share as value for datadir - instead. - - - If an application is intended to be installed by an unprivileged user - for exclusive use by that user only then - $XDG_DATA_HOME should be used as value - for datadir and - $XDG_CONFIG_HOME should be used as value - for sysconfdir. - If $XDG_DATA_HOME is not set, the default value of - $HOME/.local/share should be used for it. - If $XDG_CONFIG_HOME is not set, the default value of - $HOME/.config should be used for it. - - - Also, at least for a good long while, installing a directory hierarchy to - the old GNOME/KDE specific locations such as /usr/share/applnk and - /usr/share/gnome/apps should work. There are two ways to support - both the old and new menu systems at the same time: - - - - If you add a Categories line to the desktop - entries in the legacy hierarchy, implementations of this - specification will ignore their location in the legacy hierarchy, - and arrange them according to Categories instead. - This allows you to install a single desktop file that works in all - cases, though on the down side it's in a legacy location. - - - - - If you add the line OnlyShowIn=Old; to a desktop - entry, then old legacy implementations that ignore - OnlyShowIn will still show the desktop entry, but - implementations of this specification will not. Thus you can - add an "OnlyShowIn=Old;" entry to the legacy - hierarchy, and a new-style desktop entry to - datadir/applications/, and still get - only one entry in the menus. - - - - + Integrating your application in the menus + + Adding menu items + + The following steps describe how a third party application can add + menu items to the menu system: + + + + Install desktop entries to + datadir/applications/ for each menu + item. Please namespace the filename, as in "vendor-foo.desktop", or + use a subdirectory of + datadir/applications/ so you have + "vendor/foo.desktop." Please be sure all desktop entries are valid + (see the + desktop-file-utils package for a validation utility). + + + + + Install an XML menu file to sysconfdir/desktop/menus/applications-merged/ to add any submenus, if your desktop entries aren't already + included in some common categories. + + + + + Install any directory entries needed for your submenus to datadir/desktop-directories/, taking care to namespace and validate + the directory entries. + + + + + + + Install Locations + + If an application is intended to be installed by root on a system wide + basis then /usr/share is recommended to be used as value for + datadir and /etc/xdg is recommended to be + used as value for sysconfdir. + In case the /usr/share hierarchy is not writable it is recommended to + use /usr/local/share as value for datadir + instead. + + + If an application is intended to be installed by an unprivileged user + for exclusive use by that user only then + $XDG_DATA_HOME should be used as value + for datadir and + $XDG_CONFIG_HOME should be used as value + for sysconfdir. + If $XDG_DATA_HOME is not set, the default value of + $HOME/.local/share should be used for it. + If $XDG_CONFIG_HOME is not set, the default value of + $HOME/.config should be used for it. + + + + Example + + The company ShinyThings Inc. has developed an application named + WebMirror 1.0 and would like to add its own + submenu to the system menus consisting of a WebMirror + menu item and a WebMirror Admin Tool + menu item. The company will use "shinythings" as its vendor id. + For the purpose of this example all menu items will be available + in two languages, English and Dutch. + The language code for Dutch is nl. + + + First the company needs to create two .desktop files that describe + the two menu items: + + + datadir/applications/shinythings-webmirror.desktop: + + [Desktop Entry] + Encoding=UTF-8 + Type=Application + + Exec=webmirror + Icon=webmirror + + Name=WebMirror + Name[nl]=WebSpiegel + + + and + + + datadir/applications/shinythings-webmirror-admin.desktop: + + [Desktop Entry] + Encoding=UTF-8 + Type=Application + + Exec=webmirror-admintool + Icon=webmirror-admintool + + Name=WebMirror Admin Tool + Name[nl]=WebSpiegel Administratie Tool + + + A .directory file needs to be installed to provide a title and icon + for the sub-menu itself: + + + datadir/desktop-directories/shinythings-webmirror.directory: + + [Desktop Entry] + Encoding=UTF-8 + + Icon=webmirror + + Name=WebMirror + Name[nl]=WebSpiegel + + + And finally, a .menu file needs to be provided that links it all + togther: + + + sysconfdir/menus/application-merged/shinythings-webmirror.menu: + + <!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 0.8//EN" + "http://www.freedesktop.org/standards/menu-spec/menu-0.8.dtd"> + <Menu> + <Menu> + <Name>WebMirror</Name> + <Directory>shinythings-webmirror.directory</Directory> + <Include> + <Filename>shinythings-webmirror.desktop</Filename> + <Filename>shinythings-webmirror-admin.desktop</Filename> + </Include> + </Menu> + + + + + + + Backward Compatibility + + For a limited time, installing a directory hierarchy to + the old GNOME/KDE specific locations such as /usr/share/applnk and + /usr/share/gnome/apps will continue to work as way to add your + application to the menu system as well. There are two ways to support + both the old and new menu systems at the same time: + + + + If you add a Categories line to the desktop + entries in the legacy hierarchy, implementations of this + specification will ignore their location in the legacy hierarchy, + and arrange them according to Categories instead. + This allows you to install a single desktop file that works in all + cases, though on the down side it's in a legacy location. + + + + + If you add the line OnlyShowIn=Old; to a desktop + entry, then old legacy implementations that ignore + OnlyShowIn will still show the desktop entry, but + implementations of this specification will not. Thus you can + add an "OnlyShowIn=Old;" entry to the legacy + hierarchy, and a new-style desktop entry to + datadir/applications/, and still get + only one entry in the menus. + + + + + Implementation notes -- cgit v1.2.3-70-g09d2