diff options
Diffstat (limited to 'gnome2-system-admin-guide/C/menustructure.xml')
| -rw-r--r-- | gnome2-system-admin-guide/C/menustructure.xml | 1310 |
1 files changed, 811 insertions, 499 deletions
diff --git a/gnome2-system-admin-guide/C/menustructure.xml b/gnome2-system-admin-guide/C/menustructure.xml index 7e761e8..75f088b 100644 --- a/gnome2-system-admin-guide/C/menustructure.xml +++ b/gnome2-system-admin-guide/C/menustructure.xml @@ -1,251 +1,388 @@ +<?xml version="1.0" encoding="UTF-8"?> <chapter id="menustructure-0"> <title>Customizing Menus</title> + + <anchor id="menustructure-22" /> + + <anchor id="menustructure-TBL-12" /> + + <anchor id="menustructure-TBL-17" /> + <highlights> - <para>The information in this chapter describes how the GNOME -Desktop implements menus and how you can customize menus.</para> + <para>The information in this chapter describes how the GNOME Desktop + implements menus and how you can customize menus.</para> </highlights> + <sect1 id="menustructure-1"> <title>Introduction to Menus</title> + <indexterm> <primary>menus</primary> + <secondary>introduction</secondary> </indexterm> - <para>The way in which the GNOME Desktop implements menus enables you to do -the following:</para> + + <para>The GNOME Desktop implements menus according to the <ulink + url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu + specification</ulink>. By supporting this specification, GNOME allows you + to:</para> + <itemizedlist> <listitem> - <para>Customize the menu hierarchy easily. The menu hierarchy is -not based on the file system hierarchy. You can edit a small number of files -to customize the menu hierarchy. You do not need to modify your applications -or move files.</para> + <para>Customize the menu hierarchy easily. You can edit a small number + of files to customize the menu hierarchy. You do not need to modify + your applications or move files.</para> </listitem> + <listitem> - <para>Install applications easily. You do not need to provide information -about the menu hierarchy to applications when you install the applications.</para> + <para>Install applications easily. You do not need to provide + information about the menu hierarchy to applications when you install + the applications.</para> </listitem> + <listitem> <para>Configure menus so that users cannot modify the menus.</para> </listitem> </itemizedlist> + <para>Menus in the GNOME Desktop use the following components:</para> + <itemizedlist> <listitem> - <para>File abstraction layer</para> - </listitem> - <listitem> - <para>Vfolders</para> + <para>Menu definition files</para> </listitem> + <listitem> <para>Desktop entry files</para> </listitem> + <listitem> <para>Directory entry files</para> </listitem> </itemizedlist> </sect1> - <sect1 id="menustructure-22"> - <title>File Abstraction Layer</title> + + <sect1 id="menustructure-13"> + <title>Menu Definition Files</title> + <indexterm> - <primary>menus</primary> - <secondary>file abstraction layer</secondary> + <primary>menu definition files</primary> </indexterm> + <indexterm> - <primary>file abstraction layer, and menus</primary> + <primary>.menu files</primary> + + <see>menu definition files</see> </indexterm> - <para>The <literal>gnome-vfs</literal> file abstraction layer -provides a simplified and generalized way for applications to interact with -files. The file abstraction layer also provides <firstterm>Uniform Resource -Identifier</firstterm> (URI) locations that map to particular menu configuration -files. To add a menu or a menu item for all users, you must add the menu or -menu item to one of the URI locations. <xref linkend="menustructure-TBL-12"/> -lists the menus to which you can add items, and the URI locations that correspond -to the menus.</para> - <table frame="topbot" id="menustructure-TBL-12"> - <title>Menus and URI Locations</title> + + <para>Menu files define the hierarchy of menus that are used in the GNOME + menu bar. By modifying these files, you can customize menus for all users, + or for a single user depending on the location of the + <filename>applications.menu</filename> file that you modify.</para> + + <para>Menu files must reside at + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>. If + <envar>$XDG_CONFIG_DIRS</envar><footnote> + <para>$XDG_CONFIG_DIRS is the environment variable defined in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + base directory specification</ulink>.</para> + </footnote> is not set, then the default path + <filename>/etc/xdg/</filename> is used. This also implies that a user + specific version may be located at + <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename> + which is searched first. If <envar>$XDG_CONFIG_HOME</envar> is not set, + then the default path <filename>~/.config/</filename> is used. Directories + which appear first in <envar>$XDG_CONFIG_DIRS</envar> are given precedence + when there are several <filename>applications.menu</filename> files. The + first file found is used and subsequent files are ignored.</para> + + <para>If you are confused about the order in which paths are searched, + here is a simple list for resolving the location of + <filename>applications.menu</filename>:</para> + + <orderedlist> + <listitem> + <para>Search each directory in <envar>$XDG_CONFIG_HOME</envar> in + order to find <filename>/menus/applications.menu</filename>. If + <envar>$XDG_CONFIG_HOME</envar> is not set, default to + <filename>~/.config/</filename></para> + </listitem> + + <listitem> + <para>Search each directory in <envar>$XDG_CONFIG_DIRS</envar> in + order to find <filename>/menus/applications.menu</filename>. If + <filename>$XDG_CONFIG_DIRS</filename> is not set, default to + <filename>/etc/xdg/</filename></para> + </listitem> + + <listitem> + <para>Use the first <filename>applications.menu</filename> file + found.</para> + </listitem> + </orderedlist> + + <para>You can see an example of a <filename>.menu</filename> file in <xref + linkend="example-menu" />. In this example, the top level menu is named + <literal>Applications</literal>, which is specified using the + <literal><Name></literal> element. The + <literal>Applications</literal> menu contains a single submenu, but + several submenus are allowed. Each submenu may also have an + <literal><Include></literal> element. The purpose of the + <literal><Include></literal> element is to perform a filter on the + set of available desktop entries using matching rules.</para> + + <para>For example, the <literal><Category></literal> element is a + basic matching rule that selects a <link + linkend="menustructure-desktopentry"><emphasis>desktop + entry</emphasis></link> only if the <link + linkend="category-key"><literal>Categories</literal> key</link> contains + the content of the <literal><Category></literal> element. In the + example, the <literal>Accessories</literal> menu will include a + <emphasis>desktop entry</emphasis> only if it contains + <quote>Utility</quote> but not <quote>System</quote> in the Categories + key. For more information on the Categories key, see <xref + linkend="menustructure-desktopentry" />.</para> + + <example id="example-menu"> + <title>Example of a <filename>.menu</filename> file</title> + + <para><programlisting><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" + "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"> +<Menu> + <Name>Applications</Name> + <Directory>Applications.directory</Directory> + + <!-- Read standard .directory and .desktop file locations --> + <DefaultAppDirs/> + <DefaultDirectoryDirs/> + + <!-- Accessories submenu --> + <Menu> + <Name>Accessories</Name> + <Directory>Accessories.directory</Directory> + <Include> + <And> + <Category>Utility</Category> + <Not> + <Category>System</Category> + </Not> + </And> + </Include> + </Menu> <!-- End Accessories --> + + <!-- possibly more submenus --> + +</Menu> <!-- End Applications --> +</programlisting></para> + </example> + + <para><xref linkend="menustructure-xmlmenu" /> describes some of the + elements in <filename>.menu</filename> files. For a more detailed + description, please see the <ulink + url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu + specification</ulink>.</para> + + <table frame="topbot" id="menustructure-xmlmenu"> + <title>Menu Definition File Elements</title> + <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colwidth="50*"/> - <colspec colwidth="50*"/> + <colspec colname="colspec2" colwidth="33.83*" /> + + <colspec colname="colspec3" colwidth="80.00*" /> + <thead> <row rowsep="1"> - <entry> - <para>Menu</para> - </entry> - <entry> - <para>URI Locations</para> - </entry> + <entry><para>Element</para></entry> + + <entry><para>Description</para></entry> </row> </thead> + <tbody> <row> - <entry valign="top"> - <para><guimenu>Applications</guimenu> menu for all -users</para> - </entry> - <entry valign="top"> - <para> - <literal>applications-all-users:///</literal> - </para> - </entry> + <entry colname="colspec2" + valign="top"><para><literal><Menu></literal> </para></entry> + + <entry colname="colspec3" valign="top"><para>The root element + which may contain nested <literal><Menu></literal> elements + that define submenus. How these elements are nested determines the + menu structure.</para></entry> </row> + <row> - <entry valign="top"> - <para><guimenu>Desktop Preferences</guimenu> menu for all users</para> - </entry> - <entry valign="top"> - <para> - <literal>preferences-all-users:///</literal> - </para> - </entry> + <entry colname="colspec2" + valign="top"><para><literal><Name></literal> </para></entry> + + <entry colname="colspec3" valign="top"><para>Specifies the name of + the menu. Every <literal><Menu></literal> element must + contain a <literal><Name></literal> element.</para></entry> </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1 id="menustructure-13"> - <title>Vfolders and Menus</title> - <indexterm> - <primary>menus</primary> - <secondary>vfolders</secondary> - </indexterm> - <indexterm> - <primary>vfolders</primary> - </indexterm> - <para>In general terms, -a <firstterm>vfolder</firstterm> is a virtual representation of items that -reside in a physical location or physical locations on your system. For example, -a vfolder might represent the contents of several directories. A vfolder is -an abstraction from one or more physical locations. In terms of menus in the -GNOME Desktop, a vfolder is a representation in a menu of items that might -be physically located in several directories. </para> - <para><indexterm><primary>menus</primary><secondary>vfolder information files</secondary></indexterm><indexterm><primary>vfolder information files</primary></indexterm>A <firstterm>vfolder information file</firstterm> is an XML file -that describes a vfolder. Vfolder information files specify the structure -of your menus. Vfolder information files specify the names of your menus, -and the order in which applications appear in your menus. Vfolder information -files have a <filename>.vfolder-info</filename> file extension. </para> - <para>The following is an excerpt from a vfolder information file:</para> - <literallayout><?xml version="1.0"?> -<VFolderInfo> -. -. -. - <Folder> - <Name>Applications</Name> - <Desktop>Applications.directory</Desktop> - <Folder> - <Name>Accessories</Name> - <DontShowIfEmpty/> - <Desktop>Accessories.directory</Desktop> - <Query> - <And> - <Keyword>Application</Keyword> - <Keyword>Utility</Keyword> - </And> - </Query> - </Folder> -. -. -. - </Folder> -</VFolderInfo></literallayout> - <para><xref linkend="menustructure-TBL-17"/> describes some of the elements -in vfolder information files.</para> - <table frame="topbot" id="menustructure-TBL-17"> - <title>Vfolder Information File Elements</title> - <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec2" colwidth="33.83*"/> - <colspec colname="colspec3" colwidth="66.17*"/> - <thead> - <row rowsep="1"> - <entry> - <para>Element</para> - </entry> - <entry> - <para>Description</para> - </entry> + + <row> + <entry colname="colspec2" + valign="top"><para><literal><Directory></literal> + </para></entry> + + <entry colname="colspec3" valign="top"><para>Specifies the name of + the directory entry file that specifies the name, comment, and + icon for the menu. If this element is not specified, then the + <literal><Name></literal> element is to be used to display + the menu name.</para><para>By default, + <filename>.directory</filename> files are searched for in the + location + <filename>$XDG_DATA_DIRS/desktop-directories/</filename> + as set forth in the <citetitle>XDG menu + specification.</citetitle></para></entry> </row> - </thead> - <tbody> + + <row> + <entry + colname="colspec2"><literal><DefaultAppDirs></literal></entry> + + <entry colname="colspec3">This is an instruction which indicates + that all the available desktop entries from + <filename>$XDG_DATA_DIRS/applications/</filename> + should be scanned. If this instruction is not included, then these + locations are not scanned for desktop entries.</entry> + </row> + + <row> + <entry + colname="colspec2"><literal><DefaultDirectoryDirs></literal></entry> + + <entry colname="colspec3">This is an instruction which indicates + that all the available directory entries from + <filename>$XDG_DATA_DIRS/desktop-directories/</filename> + should be scanned. If the instruction is not included, then these + locations are not scanned for directory entries.</entry> + </row> + + <row> + <entry colname="colspec2" + valign="top"><para><literal><Include></literal></para></entry> + + <entry colname="colspec3">Contains a list of matching rules by + which the contents of a menu are generated. May include the + <literal><Filename></literal>, + <literal><Category></literal>, + <literal><And></literal>, <literal><Or></literal>, + <literal><Not></literal>, or <literal><All></literal> + matching rules. If more than one rule is present, the rules are + logically ORed so that <emphasis>desktop entries</emphasis> that + match any rule are included.</entry> + </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Folder></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Contains the elements that define -the name, content, and structure of the menu.</para> - </entry> + <entry + colname="colspec2"><literal><Exclude></literal></entry> + + <entry colname="colspec3">The opposite of + <literal><Include></literal> since any <emphasis>desktop + entries</emphasis> that are matched in this element are excluded + from the previous set of included elements. For this reason, this + element must appear after the <literal><Include></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Name></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Specifies the name of the menu.</para> - </entry> + <entry + colsep="colspec2"><literal><Filename></literal></entry> + + <entry colname="colspec3">A matching rule that selects a + <emphasis>desktop entry</emphasis> when the Desktop File-Id + matches the contents of the <literal><Filename></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Desktop></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Specifies the name of the directory -entry file that specifies the name, comment, and icon for the menu.</para> - </entry> + <entry colname="colspec2"><Category></entry> + + <entry colname="colspec3">A matching rule that selects a + <emphasis>desktop entry</emphasis> when the Categories key matches + the contents of the <literal><Category></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Query></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Specifies a query to run on desktop -entry files. If a desktop entry file matches the requirements in the query, -the menu item is displayed in the menu. </para> - <para>The query in the excerpt -searches for desktop entry files that contain the keywords <literal>Application</literal> and <literal>Utility</literal> in the <literal>Categories</literal> -key. Desktop entry files that match are displayed in the <guimenu>Applications</guimenu> menu.</para> - <para>This element is optional.</para> - </entry> + <entry colname="colspec2"><literal><And></literal></entry> + + <entry colname="colspec3">A matching rule that selects a + <emphasis>desktop entry</emphasis> when it is selected by + <emphasis>all</emphasis> the nested matching rules in the + <literal><And></literal> element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><DontShowIfEmpty/></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>If this -element is present, the menu is not displayed if the menu does not contain -any items.</para> - <para>This element is optional.</para> - </entry> + <entry colname="colspec2"><literal><Or></literal></entry> + + <entry colname="colspec3">A matching rule that selects a + <emphasis>desktop entry</emphasis> when it is selected by + <emphasis>any</emphasis> of the nested matching rules in the + <literal><Or></literal> element.</entry> + </row> + + <row> + <entry colname="colspec2"><literal><Not></literal></entry> + + <entry colname="colspec3">A matching rule that does not select a + <emphasis>desktop entry</emphasis> when it is selected by + <emphasis>any</emphasis> of the nested matching rules in the + <literal><Not></literal> element.</entry> + </row> + + <row> + <entry colname="colspec2"><literal><All></literal></entry> + + <entry colname="colspec3">A matching rule which selects all + <emphasis>desktop entries</emphasis>.</entry> </row> </tbody> </tgroup> </table> </sect1> - <sect1 id="menustructure-6"> + + <sect1 id="menustructure-desktopentry"> <title>Desktop Entry Files</title> + + <anchor id="menustructure-6" /> + <indexterm> <primary>desktop entry files</primary> </indexterm> + <indexterm> <primary>.desktop files</primary> + <see>desktop entry files</see> </indexterm> - <para>A <firstterm>desktop entry file</firstterm> is a data file that provides information about -an item in a menu. The desktop entry file specifies the details for the item -such as a name, a command to run, an icon, and so on. The desktop entry file -also contains keywords which determine the location of the item in the menu -hierarchy. Desktop entry files have a <filename>.desktop</filename> file extension.</para> + + <para>A <firstterm>desktop entry file</firstterm> is a data file that + provides information about an item in a menu. The desktop entry file + specifies the details for the item such as a name, a command to run, an + icon, and so on. It also contains keywords which determine the location of + the item in the menu hierarchy.</para> + + <para>Desktop entry files must reside in the + <filename>$XDG_DATA_DIRS/applications</filename> directory and must have a + <filename>.desktop</filename> file extension. If + <envar>$XDG_DATA_DIRS</envar><footnote> + <para>$XDG_DATA_DIRS is the environment variable defined in the <ulink + url="http://www.freedesktop.org/Standards/basedir-spec">XDG base + directory specification</ulink>.</para> + </footnote> is not set, then the default path is + <filename>/usr/share/</filename> is used. This also implies that user + specific desktop entries may be located at + <filename>$XDG_DATA_HOME/applications/</filename> which is + searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then the + default path <filename>~/.local/share</filename> is used. Desktop entries + are collected from all directories in the <envar>$XDG_DATA_DIRS</envar> + environment variable. Directories which appear first in + <envar>$XDG_CONFIG_DIRS</envar> are given precedence when there are + several <filename>.desktop</filename> files with the same name.</para> + <para>The following is a sample desktop entry file:</para> - <literallayout>[Desktop Entry] + + <programlisting>[Desktop Entry] Encoding=UTF-8 Name=Calculator Comment=Perform calculations @@ -253,467 +390,642 @@ Exec=gcalctool Icon=gcalctool.png Terminal=false Type=Application -Categories=GNOME;Application;Utility; -X-GNOME-DocPath=gcalctool/gcalctool.xml</literallayout> - <para><xref linkend="menustructure-TBL-7"/> describes the most important keys -in desktop entry files.</para> +Categories=GTK;GNOME;Application;Utility;</programlisting> + + <para><xref linkend="menustructure-TBL-7" /> describes the most important + keys in desktop entry files. To get more information about desktop entry + files, see the <ulink + url="http://www.freedesktop.org/Standards/desktop-entry-spec">XDG Desktop + Entry Specification</ulink>.</para> + <table frame="topbot" id="menustructure-TBL-7"> <title>Desktop Entry Keys</title> + <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec0" colwidth="25.25*"/> - <colspec colname="colspec1" colwidth="74.75*"/> + <colspec colname="colspec0" colwidth="25.25*" /> + + <colspec colname="colspec1" colwidth="74.75*" /> + <thead> <row rowsep="1"> - <entry> - <para>Desktop Entry Key</para> - </entry> - <entry> - <para>Description</para> - </entry> + <entry><para>Desktop Entry Key</para></entry> + + <entry><para>Description</para></entry> </row> </thead> + <tbody> <row> - <entry valign="top"> - <para> - <literal>Encoding</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the encoding of the desktop entry file. </para> - </entry> + <entry valign="top"><para> <literal>Encoding</literal> + </para></entry> + + <entry valign="top"><para>Specifies the encoding of the desktop + entry file. </para></entry> </row> + <row> - <entry valign="top"> - <para> - <literal>Name</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the name of the item. This name is displayed -on the item in the menu. </para> - </entry> + <entry valign="top"><para> <literal>Name</literal> </para></entry> + + <entry valign="top"><para>Specifies the name of the item. This + name is displayed on the item in the menu. </para></entry> </row> + <row> - <entry valign="top"> - <para> - <literal>Comment</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a short description of the item. The comment -is displayed as a tooltip when you point to the item in the menu. </para> - </entry> + <entry valign="top"><para> <literal>Comment</literal> + </para></entry> + + <entry valign="top"><para>Specifies a short description of the + item. The comment is displayed as a tooltip when you point to the + item in the menu. </para></entry> </row> + <row> - <entry valign="top"> - <para> - <literal>Exec</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a command to execute when you choose the item -from the menu. </para> - </entry> + <entry valign="top"><para> <literal>Exec</literal> </para></entry> + + <entry valign="top"><para>Specifies a command to execute when you + choose the item from the menu. </para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Icon</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies the filename of an -icon that represents the item. Does not specify the path to the filename, -or the file extension. </para> - </entry> + <entry colname="colspec0" valign="top"><para> + <literal>Icon</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies the + filename of an icon that represents the item. Does not specify the + path to the filename, or the file extension. </para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Terminal</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies whether the command -in the <literal>Exec</literal> key runs in a terminal window. If the value -is <literal>true</literal> the command runs in a terminal window. </para> - <para>If the command does not create a window in which to run, the value of this -key must be <literal>true</literal>.</para> - </entry> + <entry colname="colspec0" valign="top"><para> + <literal>Terminal</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies whether the + command in the <literal>Exec</literal> key runs in a terminal + window. If the value is <literal>true</literal> the command runs + in a terminal window. </para><para>If the command does not create + a window in which to run, the value of this key must be + <literal>true</literal>.</para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Type</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies the type of item. This -value is one of the following: </para> - <itemizedlist> + <entry colname="colspec0" valign="top"><para> + <literal>Type</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies the type of + item. This value is one of the following: </para><itemizedlist> + <listitem> + <para><literal>Application</literal>: An item that starts an + application.</para> + </listitem> + <listitem> - <para><literal>Application</literal>: Enter this option for an -item that starts an application.</para> + <para><literal>Link</literal>: An item that links to a file, + folder, or FTP site.</para> </listitem> + <listitem> - <para><literal>Link</literal>: Enter this option for an item that -links to a file, folder, or FTP site.</para> + <para><literal>FSDevice</literal>: An item that is a file + system device.</para> </listitem> - </itemizedlist> - </entry> + + <listitem> + <para><literal>Directory</literal>: An item that is a + Directory.</para> + </listitem> + </itemizedlist></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Categories</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies the keywords that describe -the item. The keywords are separated with semicolons (;). To see a list of -the standard category keywords, see the desktop menu specification at the -following URL: </para> - <literallayout> - <ulink url="http://www.freedesktop.org">http://www.freedesktop.org</ulink> - </literallayout> - <para>The vfolder information -files map the keywords to menus.</para> - </entry> + <entry colname="colspec0" id="category-key" valign="top"><para> + <literal>Categories</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies the + keywords that describe the item. The keywords are separated with + semicolons (;). To see a list of the standard category keywords, + see the desktop menu specification at the following URL: + </para><literallayout> + <ulink url="http://www.freedesktop.org/Standards/menu-spec">http://www.freedesktop.org/Standards/menu-spec</ulink> + </literallayout><para><link linkend="menustructure-13">Menu + Definition Files</link> map desktop entries to menus by using + matching rules against the Categories key.</para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>X-GNOME-DocPath</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies -the help file to display when you choose <guimenuitem>Help on <replaceable>application-name</replaceable></guimenuitem> from the menu item popup menu.</para> - </entry> + <entry><literal>MimeType</literal></entry> + + <entry>Specifies the MIME types </entry> </row> </tbody> </tgroup> </table> - <para>For more information on the keys in desktop entry files, see the desktop -entry specification at the following URL: </para> + + <para>For more information on the keys in desktop entry files, see the + desktop entry specification at the following URL:</para> + <literallayout> - <ulink url="http://www.freedesktop.org">http://www.freedesktop.org</ulink> + <ulink url="http://www.freedesktop.org/Standards/desktop-entry-spec">http://www.freedesktop.org/Standards/desktop-entry-spec</ulink> </literallayout> + <note> <para>Panel launchers and desktop objects also use desktop entry files. -The desktop entry files for launchers and desktop objects provide the same -information as for items in a menu. For example, the desktop entry files provide -the command to run when a user chooses the launcher or object.</para> + The desktop entry files for launchers and desktop objects provide the + same information as for items in a menu. For example, the desktop entry + files provide the command to run when a user chooses the launcher or + object.</para> </note> </sect1> + <sect1 id="menustructure-14"> <title>Directory Entry Files</title> + <indexterm> <primary>directory entry files</primary> </indexterm> + <indexterm> <primary>.directory files</primary> + <see>directory entry files</see> </indexterm> - <para>A <firstterm>directory entry file</firstterm> is a data file that provides -information about a menu. The directory entry file specifies the details for -the menu such as a name, a tooltip, and an icon. Directory entry files have -a <filename>.directory</filename> file extension.</para> + + <para>A <firstterm>directory entry file</firstterm> is a data file that + provides information about a menu. The directory entry file specifies the + details for the menu such as a name, a tooltip, and an icon. Directory + entry files have a <filename>.directory</filename> file extension.</para> + + <para>Directory entry files must reside at + <filename>$XDG_DATA_DIRS/desktop-directories/</filename>. If + <envar>$XDG_DATA_DIRS</envar> is not set, then the default path is + <filename>/usr/share/</filename> is used. This also implies that user + specific directory entries may be located at + <filename>$XDG_DATA_HOME/desktop-directories/</filename> + which is searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then + the default path <filename>~/.local/share/</filename> is used. Directory + entries are collected from all directories in the + <envar>$XDG_DATA_DIRS</envar> environment variable. Directories which + appear first in <envar>$XDG_DATA_DIRS</envar> are given precedence when + there are several <filename>.directory</filename> files with the same + name.</para> + <para>The following is a sample directory entry file:</para> - <literallayout>[Desktop Entry] + + <programlisting>[Desktop Entry] Name=Accessories Comment=Accessories menu Icon=gnome-util.png -Type=Directory</literallayout> - <para><xref linkend="menustructure-TBL-15"/> describes the most important keys -in directory entry files.</para> +Type=Directory</programlisting> + + <para><xref linkend="menustructure-TBL-15" /> describes the most important + keys in directory entry files.</para> + <table frame="topbot" id="menustructure-TBL-15"> <title>Directory Entry Keys</title> + <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec0" colwidth="27.07*"/> - <colspec colname="colspec1" colwidth="72.93*"/> + <colspec colname="colspec0" colwidth="27.07*" /> + + <colspec colname="colspec1" colwidth="72.93*" /> + <thead> <row rowsep="1"> - <entry> - <para>Directory Entry Key</para> - </entry> - <entry> - <para>Description</para> - </entry> + <entry><para>Directory Entry Key</para></entry> + + <entry><para>Description</para></entry> </row> </thead> + <tbody> <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Name</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies the name of the menu. -This name is displayed on the menu. </para> - </entry> + <entry colname="colspec0" valign="top"><para> + <literal>Name</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies the name of + the menu. This name is displayed on the menu. </para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Comment</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies a short description -of the menu. The comment is displayed as a tooltip when you point to the menu. </para> - </entry> + <entry colname="colspec0" valign="top"><para> + <literal>Comment</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies a short + description of the menu. The comment is displayed as a tooltip + when you point to the menu. </para></entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>Icon</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies the filename of an -icon that represents the menu. Does not specify the path to the filename, -or the file extension. </para> - </entry> + <entry colname="colspec0" valign="top"><para> + <literal>Icon</literal> </para></entry> + + <entry colname="colspec1" valign="top"><para>Specifies the + filename of an icon that represents the menu. Does not specify the + path to the filename, or the file extension. </para></entry> </row> + <row> - <entry valign="top"> - <para> - <literal>Type</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the type of menu. The value of this key is always <literal>Directory</literal>.</para> - </entry> + <entry valign="top"><para> <literal>Type</literal> </para></entry> + + <entry valign="top"><para>Specifies the type of menu. The value of + this key is always <literal>Directory</literal>.</para></entry> </row> </tbody> </tgroup> </table> </sect1> + <sect1 id="menustructure-2"> - <title>Editing Menus</title> + <title>Editing System Menus</title> + + <anchor id="menustructure-23" /> + <indexterm> <primary>menus</primary> + <secondary>editing</secondary> </indexterm> - <para>You use the following GNOME Desktop components to edit menus:</para> - <itemizedlist> - <listitem> - <para><application>Nautilus</application> file manager</para> - </listitem> - <listitem> - <para>Menus on panels</para> - </listitem> - </itemizedlist> - <para>When you use the file manager to add menus or menu items for all users, -you must add the menu or menu item to a URI location. <xref linkend="menustructure-TBL-12"/> -lists the menus to which you can add items, and the URI locations that correspond -to the menus.</para> - <para>When you use panels to customize menus for all users, you use the menu -item popup menu. For more information, see <citetitle>Working With Menus</citetitle> -in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> - <para>You can also use menu configuration files and menu data files to customize -menus.</para> + + <para>You can edit menu configuration files and menu data files manually + to customize menus.</para> + <sect2 id="menustructure-3"> <title>Adding Menus</title> - <para>You can add menus for all users in the following ways: </para> - <itemizedlist> + + <anchor id="menustructure-19" /> + + <anchor id="menustructure-20" /> + + <indexterm> + <primary>menus</primary> + + <secondary>adding</secondary> + </indexterm> + + <para>To add a menu for all users, perform the following steps:</para> + + <orderedlist> <listitem> - <para>Use the file manager.</para> + <para>Create a directory entry file for the item that you want to + add. Place the directory entry file in the + <filename>$XDG_DATA_DIRS/desktop-directories/</filename> + directory. For more information on directory entry files, see <xref + linkend="menustructure-14" />.</para> </listitem> + <listitem> - <para>Modify the menu configuration files and menu data files.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> - </itemizedlist> - <sect3 id="menustructure-19"> - <title>To Add a Menu Using the File Manager</title> - <indexterm> - <primary>menus</primary> - <secondary>adding using file manager</secondary> - </indexterm> - <indexterm> - <primary>file manager</primary> - <secondary>adding menus -with</secondary> - </indexterm> - <para>To add a menu for all users, perform the -following steps:</para> - <orderedlist> - <listitem> - <para>In a file manager window, access the location where you want -to add the menu. For example, to add a menu to the <guimenu>Applications</guimenu> -menu, type <literal>applications-all-users:///</literal> in the <guilabel>Location</guilabel> field, then press <keycap>Return</keycap>.</para> - </listitem> - <listitem> - <para>Choose <menuchoice><guimenu>File</guimenu><guimenuitem>New Folder</guimenuitem></menuchoice>. An untitled folder is added to the -view pane. The name of the folder is selected.</para> - </listitem> - <listitem> - <para>Type a name for the folder, then press <keycap>Return</keycap>. -The vfolder information file for the location that you accessed in step 1 -is automatically updated with the details of the new menu. The name of the -folder is displayed as the name of the menu.</para> - </listitem> - </orderedlist> - <para>The next time that users log in, the menu is in the assigned location.</para> - </sect3> - <sect3 id="menustructure-20"> - <title>To Add a Menu Using Menu Files</title> - <indexterm> - <primary>menus</primary> - <secondary>adding using menu files</secondary> - </indexterm> - <para>To add a menu for all users, perform the following steps:</para> - <orderedlist> - <listitem> - <para>Create a directory entry file for the item that you want to -add. Create the directory entry file in the <filename>/usr/share/gnome/vfolders</filename> directory. For more information on directory entry files, see <xref linkend="menustructure-14"/>. </para> - </listitem> - <listitem> - <para>Locate the vfolder information file for the location where -you want to add the menu. For example, to add a menu to the <guimenu>Applications</guimenu> menu, locate the file <filename>/etc/gnome-vfs-2.0/vfolders/applications-all-users.vfolder-info</filename>. </para> - </listitem> - <listitem> - <para>In the vfolder information file, add a <literal><Folder></literal> element for the new menu. For more information on vfolder information -files, see <xref linkend="menustructure-13"/>.</para> - </listitem> - </orderedlist> - <para>The next time that users log in, the menu is in the assigned location.</para> - </sect3> + + <listitem> + <para>In the <filename>.menu</filename> file, add a + <literal><Menu></literal> element for the new menu. For more + information on <filename>.menu</filename> files, see <xref + linkend="menustructure-13" />.</para> + </listitem> + + <listitem> + <para>Create a <literal><Name></literal> element below + <literal><Menu></literal>. The content of the element should + contain the name for the menu.</para> + </listitem> + + <listitem> + <para>Create a <literal><Directory></literal> element below + <literal><Menu></literal>. The content of the element should + contain the name of the directory entry file.</para> + </listitem> + + <listitem> + <para>See <xref linkend="menustructure-4" /> for how to add an item + to the menu.</para> + </listitem> + </orderedlist> + + <para>The next time that users log in, the menu should appear in the + menu bar.</para> + + <note> + <title>Missing Menu?</title> + + <para>If you did not specify any matching rules in the + <literal><Include></literal> element, or if the rule did not + match any desktop entries, then you may not see the menu in the menu + bar.</para> + </note> </sect2> + <sect2 id="menustructure-4"> - <title>To Add an Item to a Menu</title> + <title>Adding an Item to a Menu</title> + <indexterm> <primary>menus</primary> + <secondary>adding items to</secondary> </indexterm> + <para>To add an item to a menu for all users, perform the following -steps:</para> + steps:</para> + <orderedlist> <listitem> - <para>Create a desktop entry file for the item that you want to -add. For more information on desktop entry files, see <xref linkend="menustructure-6"/>. </para> + <para>Create a desktop entry file for the item that you want to add. + For more information on desktop entry files, see <xref + linkend="menustructure-desktopentry" />.</para> </listitem> + <listitem> - <para>Open a file manager window. Choose <menuchoice><guimenu>File</guimenu><guimenuitem>New Window</guimenuitem></menuchoice> to open a second -file manager window.</para> + <para>Place the desktop entry file in the folder + <filename>$XDG_DATA_DIRS/applications/</filename></para> </listitem> + <listitem> - <para>In one window, access the location where you want to add the -menu item. For example, to add a menu item to the <guimenu>Preferences</guimenu> -menu, type <literal>preferences-all-users:///</literal> in the <guilabel>Location</guilabel> field, then press <keycap>Return</keycap>.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> + <listitem> - <para>In the other window, select the desktop entry file that you -created for the menu item. Drag the desktop entry file to the location where -you want to add the menu item.</para> - <para>Alternatively, you can copy the desktop entry file, then paste the file -into the location where you want to add the menu item.</para> + <para>Verify that a <literal><Menu></literal> element contains + an <literal><Include></literal> element with a matching rule + that selects the desktop entry file made in step 1.</para> </listitem> </orderedlist> - <para>The next time that users log in, the menu item is in the assigned location.</para> + + <para>The next time that users log in, the menu item is in the assigned + location.</para> </sect2> + <sect2 id="menustructure-9"> - <title>To Edit the Properties of a Menu</title> + <title>Editing the Properties of a Menu</title> + <indexterm> <primary>menus</primary> + <secondary>editing properties of</secondary> </indexterm> - <para>To edit the properties of a menu for all users, perform -the following steps:</para> + + <para>To edit the properties of a menu for all users, perform the + following steps:</para> + <orderedlist> <listitem> - <para>From a panel, open the menu that you want to edit. Right-click -on any item in the menu.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> + <listitem> - <para>Choose <menuchoice><guimenu>Entire menu</guimenu><guimenuitem>Properties</guimenuitem></menuchoice>. A <guilabel>Launcher Properties</guilabel> dialog is displayed.</para> + <para>Find the <literal><Menu></literal> entry in this file + that corresponds to the menu you want to modify. Note the filename + of the directory entry in the <literal><Directory></literal> + element.</para> </listitem> + <listitem> - <para>Modify the properties of the menu in the <guilabel>Launcher Properties</guilabel> dialog. For more information on the elements in the <guilabel>Launcher Properties</guilabel> dialog, see <citetitle>Working With Panels</citetitle> in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> - </listitem> - <listitem> - <para>Click <guibutton>OK</guibutton>.</para> + <para>Locate the directory entry for this menu. Modify the contents + to change the properties of the menu. For more information on + <filename>.directory</filename> files, see <xref + linkend="menustructure-14" />.</para> </listitem> </orderedlist> </sect2> + <sect2 id="menustructure-10"> - <title>To Edit a Menu Item</title> + <title>Editing a Menu Item</title> + <indexterm> <primary>menus</primary> + <secondary>editing menu items</secondary> </indexterm> + <para>To edit a menu item, perform the following steps:</para> + <orderedlist> <listitem> - <para>From a panel, open the menu that contains the item that you -want to edit. Right-click on the item that you want to edit.</para> - </listitem> - <listitem> - <para>Choose <guimenuitem>Properties</guimenuitem>. A <guilabel>Launcher Properties</guilabel> dialog is displayed.</para> - </listitem> - <listitem> - <para>Modify the properties of the menu item in the <guilabel>Launcher Properties</guilabel> dialog. For more information on the elements in the <guilabel>Launcher Properties</guilabel> dialog, see <citetitle>Working With Panels</citetitle> in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> + <para>Locate the desktop entry in + <filename>$XDG_DATA_DIRS/applications/</filename> + corresponding to the menu item.</para> </listitem> + <listitem> - <para>Click <guibutton>OK</guibutton>.</para> + <para>Edit the desktop entry to change the properties of the menu + item. For more information on desktop entry files, see <xref + linkend="menustructure-desktopentry" />.</para> </listitem> </orderedlist> </sect2> + <sect2 id="menustructure-11"> - <title>To Delete an Item from a Menu</title> + <title>Deleting an Item from a Menu</title> + <indexterm> <primary>menus</primary> + <secondary>deleting menu items</secondary> </indexterm> - <para>To delete an item from a menu, from a panel, open the menu -that contains the item that you want to delete. Right-click on the item that -you want to delete. Choose <guimenuitem>Remove this item</guimenuitem>. </para> - <para>The next time that users log in, the menu item is not displayed in the -menu.</para> + + <para>To delete an item from a menu for all users:</para> + + <orderedlist> + <listitem> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> + </listitem> + + <listitem> + <para>Find the <literal><Menu></literal> element in this file + that contains the desktop entry you want to delete.</para> + </listitem> + + <listitem> + <para>Insert an <literal><Exclude></literal> element after the + closing tag for the <literal><Include></literal> element. Make + sure this is in the <literal><Menu></literal> element + determined in step 2.</para> + </listitem> + + <listitem> + <para>Insert the <literal><Filename></literal> matching rule + as a subelement of <literal><Exclude></literal> to + specifically exclude a desktop entry.</para> + </listitem> + </orderedlist> + + <para>The next time that users log in, the menu item is not displayed in + the menu. <xref linkend="menustructure-deleteitem" /> shows how this + done in the <filename>applications.menu</filename> file. The desktop + entry for <filename>dasher.desktop</filename> is explicitly excluded + from showing up in the accessibility menu.</para> + + <example id="menustructure-deleteitem"> + <title>Deleting an Item from a Menu</title> + + <programlisting><!-- ... --> + + <Menu> + <Name>Accessibility</Name> + <Directory>Accessibility.directory</Directory> + <Include> + <And> + <Category>Accessibility</Category> + <Not><Category>Settings</Category></Not> + </And> + </Include> + <Exclude> + <Filename>dasher.desktop</Filename> + </Exclude> + </Menu> + +<!-- ... --> +</programlisting> + </example> </sect2> </sect1> - <sect1 id="menustructure-23"> - <title>To Configure Menus That Users Cannot Modify</title> + + <sect1 id="menustructure-usermenus"> + <title>Editing User Menus and Menu Merging</title> + <indexterm> <primary>menus</primary> - <secondary>configuring menus that users -cannot modify</secondary> + + <secondary>editing user menus</secondary> </indexterm> - <para>Users cannot modify a menu if the -following conditions are true:</para> + + <para>You can use the following GNOME Desktop applications to edit menus + for users:</para> + <itemizedlist> <listitem> - <para>A vfolder information file that corresponds to the menu is -present in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>The vfolder information file has the same name as the URI -location that corresponds to the menu.</para> - </listitem> - <listitem> - <para>The user permissions for the vfolder information file are -set to read only. </para> + <para>GNOME Menu Editor</para> </listitem> </itemizedlist> - <para>To configure a menu so that users cannot modify the menu, perform the -following steps:</para> - <orderedlist> - <listitem> - <para>Create a vfolder information file for the menu that you want -to configure in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>Give the vfolder information file the name of the URI location -that corresponds to the menu that you want to configure. For example, to configure -the <guimenu>Applications</guimenu> menu, create a vfolder information called <filename>applications.vfolder-info</filename> in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>Set the permissions on the vfolder information file to read -only.</para> - </listitem> - </orderedlist> + + <para>A simple menu editor is available for users to edit their menus. For + more information, see <ulink + url="ghelp:user-guide?goseditmainmenu-1">Working With Menus</ulink> in the + <ulink url="ghelp:user-guide">GNOME User Guide</ulink>. Alternatively, you + can manually create and edit a user menu file.</para> + + <para>To manually create a custom menu for a user, the + <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename> + must exist. In the case that <envar>$XDG_CONFIG_HOME</envar> is not set, + the default <filename>~/.config/</filename> is used. Since this is the + first location that is searched for the + <filename>applications.menu</filename> file, it takes precedence over all + other menu files.</para> + + <para>User menus can contain all the elements described in <xref + linkend="menustructure-13" />. For a complete list of the elements + allowed, see the <ulink + url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu + specification</ulink>.</para> + + <para>Since user menu files take precedence over the system menu file, it + will completely replace the system menu unless it explicitly + <emphasis>merges</emphasis> the system menu. Information on menu merging + is available in the following subsections.</para> + + <sect2> + <title>Merging the System Menu</title> + + <indexterm> + <primary>menus</primary> + + <secondary>merging the system menu</secondary> + </indexterm> + + <para>Often, a user only wants to add or delete menu items in addition + to the standard system menu. To support single changes like these, it is + recommended that you use the <literal><MergeFile></literal> + element with the attribute <literal>type="parent"</literal> within the + user's <filename>applications.menu</filename> file.</para> + + <para>The <literal><MergeFile></literal> element allows a menu to + be merged with the contents of the user's menu file. When you specify + the attribute <literal>type="parent"</literal>, then the contents of the + <literal><MergeFile></literal> element are ignored and the next + <filename>applications.menu</filename> file in + <filename>$XDG_CONFIG_DIRS/menus/</filename> is used for + merging.</para> + + <note> + <title>Older Specifications</title> + + <para>Older specifications did not include the <literal>type</literal> + attribute and simply required the location of the menu file to be + merged as the content of the <literal><MergeFile></literal> + element. As a result, you may still see a location specified in the + contents of <literal><MergeFile></literal>, even when + <literal>type="parent"</literal>.</para> + </note> + + <para>The merging is performed as follows:</para> + + <itemizedlist> + <listitem> + <para>The children of the root <literal><Menu></literal> + element in the merged menu file<footnote> + <para>Merged menu file refers to the next + <filename>applications.menu</filename> in + <filename>$XDG_CONFIG_DIRS/menus/</filename></para> + </footnote> are substituted for the + <literal><MergeFile></literal> element in the base menu + file.</para> + </listitem> + + <listitem> + <para>All child <literal><Menu></literal> elements with the + same name are consolidated into a single + <literal><Menu></literal> element. This is by done appending + all child elements of each <literal><Menu></literal> element + with the same name into the <emphasis>last</emphasis> occurrence of + the menu element.</para> + </listitem> + </itemizedlist> + + <para><xref linkend="menustructure-systemmerge" /> shows an example of a + user menu file explicitly merging the system menu file.</para> + + <example id="menustructure-systemmerge"> + <title>Merging the System Menu</title> + + <programlisting><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" + "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"> + +<Menu> + <Name>Applications</Name> + <MergeFile type="parent">/etc/xdg/menus/applications.menu</MergeFile> + <Menu> + <Name>Accessibility</Name> + <Exclude> + <Filename>dasher.desktop</Filename> + </Exclude> + </Menu> +</Menu> +</programlisting> + </example> + </sect2> + + <sect2> + <title>Merging Arbitrary Menus</title> + + <indexterm> + <primary>menus</primary> + + <secondary>merging arbitrary menus</secondary> + </indexterm> + + <para>Arbitrary menu files can be merged in much the same way as system + menus. The difference is that the <literal>type</literal> attribute must + be set to <literal>path</literal> or must be excluded from the + <literal><MergeFile></literal> element in order to do this type of + merge.</para> + + <para>The merge is performed in the same way except that the location of + the <emphasis>merged menu file</emphasis> is specified in the contents + of the <literal><MergeFile></literal> element.</para> + </sect2> </sect1> </chapter> |