diff options
Diffstat (limited to 'trunk/gnome2-system-admin-guide/C/menustructure.xml')
| -rw-r--r-- | trunk/gnome2-system-admin-guide/C/menustructure.xml | 1050 |
1 files changed, 0 insertions, 1050 deletions
diff --git a/trunk/gnome2-system-admin-guide/C/menustructure.xml b/trunk/gnome2-system-admin-guide/C/menustructure.xml deleted file mode 100644 index 6c58fcc..0000000 --- a/trunk/gnome2-system-admin-guide/C/menustructure.xml +++ /dev/null @@ -1,1050 +0,0 @@ -<?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> - </highlights> - - <sect1 id="menustructure-1"> - <title>Introduction to Menus</title> - - <indexterm> - <primary>menus</primary> - - <secondary>introduction</secondary> - </indexterm> - - <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. 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> - </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>Menu definition files</para> - </listitem> - - <listitem> - <para>Desktop entry files</para> - </listitem> - - <listitem> - <para>Directory entry files</para> - </listitem> - </itemizedlist> - </sect1> - - <sect1 id="menustructure-13"> - <title>Menu Definition Files</title> - - <indexterm> - <primary>menu definition files</primary> - </indexterm> - - <indexterm> - <primary>.menu files</primary> - - <see>menu definition files</see> - </indexterm> - - <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, it defaults to the - <filename>~/.config/</filename> directory.</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, it defaults to the - <filename>/etc/xdg/</filename> directory.</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 colname="colspec2" colwidth="33.83*" /> - - <colspec colname="colspec3" colwidth="80.00*" /> - - <thead> - <row rowsep="1"> - <entry><para>Element</para></entry> - - <entry><para>Description</para></entry> - </row> - </thead> - - <tbody> - <row> - <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 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> - - <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> - - <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"><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 - 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"><literal><Category></literal></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"><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"><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-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. 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> - - <programlisting>[Desktop Entry] -Encoding=UTF-8 -Name=Calculator -Name[fr]=Calculatrice -... -Comment=Perform calculations -Comment[fr]=Effectue des calculs compliqués -... -Exec=gcalctool -Icon=gnome-calculator -Terminal=false -Type=Application -StartupNotify=true -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*" /> - - <thead> - <row rowsep="1"> - <entry><para>Desktop Entry Key</para></entry> - - <entry><para>Description</para></entry> - </row> - </thead> - - <tbody> - <row> - <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 - <ulink url="http://www.freedesktop.org/Standards/menu-spec"> - http://www.freedesktop.org/Standards/menu-spec</ulink> - </para><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 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>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>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> - </row> - - <row> - <entry><literal>MimeType</literal></entry> - - <entry>Specifies the MIME types that the application can handle.</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> - </row> - - <row> - <entry valign="top"><para> <literal>NoDisplay</literal> </para></entry> - - <entry valign="top"><para>This options means <quote>This application - exists, but don't display it in the menus</quote>.</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> - </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> - <listitem> - <para><literal>Application</literal>: An item that starts an - application.</para> - </listitem> - - <listitem> - <para><literal>Link</literal>: An item that links to a file, - folder, or a remote resource (such as a FTP site, a web - page, a Windows share...).</para> - </listitem> - - <listitem> - <para><literal>FSDevice</literal>: An item that is a file - system device.</para> - </listitem> - - <listitem> - <para><literal>Directory</literal>: An item that is a - Directory.</para> - </listitem> - </itemizedlist></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> - - <literallayout> - <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> - </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>Directory entry files must reside in the - <filename>$XDG_DATA_DIRS/desktop-directories</filename> directory. 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> - - <programlisting>[Desktop Entry] -Name=Graphics -Name[fr]=Graphisme -... -Comment=Graphics applications -Comment[fr]=Applications graphiques -... -Icon=gnome-graphics -Type=Directory -Encoding=UTF-8</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*" /> - - <thead> - <row rowsep="1"> - <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> - </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> - </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> - </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> - </row> - </tbody> - </tgroup> - </table> - </sect1> - - <sect1 id="menustructure-2"> - <title>Editing System Menus</title> - - <anchor id="menustructure-23" /> - - <indexterm> - <primary>menus</primary> - - <secondary>editing</secondary> - </indexterm> - - <para>You can edit menu configuration files and menu data files manually - to customize menus.</para> - - <sect2 id="menustructure-3"> - <title>Adding Menus</title> - - <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>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>Locate the - <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> - file.</para> - </listitem> - - <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>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> - - <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-desktopentry" />.</para> - </listitem> - - <listitem> - <para>Place the desktop entry file in the - <filename>$XDG_DATA_DIRS/applications</filename> folder.</para> - </listitem> - - <listitem> - <para>Locate the - <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> - file.</para> - </listitem> - - <listitem> - <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> - </sect2> - - <sect2 id="menustructure-9"> - <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> - - <orderedlist> - <listitem> - <para>Locate the - <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> - file.</para> - </listitem> - - <listitem> - <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>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>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>Locate the desktop entry in the - <filename>$XDG_DATA_DIRS/applications</filename> - directory that corresponds to the menu item.</para> - </listitem> - - <listitem> - <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>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 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-usermenus"> - <title>Editing User Menus and Menu Merging</title> - - <indexterm> - <primary>menus</primary> - - <secondary>editing user menus</secondary> - </indexterm> - - <para>You can use the following GNOME Desktop applications to edit menus - for users:</para> - - <itemizedlist> - <listitem> - <para>GNOME Menu Editor</para> - </listitem> - </itemizedlist> - - <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> directory 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 the - <filename>$XDG_CONFIG_DIRS/menus</filename> directory 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 the - <filename>$XDG_CONFIG_DIRS/menus</filename> directory.</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> |