| OLD | NEW |
|---|
| (Empty) | |
| 1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859
-1"><title>xdg-desktop-menu</title><meta name="generator" content="DocBook XSL S
tylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vli
nk="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="xdg-deskto
p-menu"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p
>xdg-desktop-menu — command line tool for (un)installing desktop menu item
s</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"
><p><code class="command">xdg-desktop-menu</code> install [<code class="optio
n">--noupdate</code>] [<code class="option">--novendor</code>] [<code class="opt
ion">--mode <em class="replaceable"><code>mode</code></em></code>] <em class="r
eplaceable"><code>directory-file(s)</code></em> <em class="replaceable"><code>
desktop-file(s)</code></em> </p></div><div class="cmdsynopsis"><p><code class="c
ommand">xdg-desktop-menu</code> uninstall [<code class="option">--noupdate</c
ode>] [<code class="option">--mode <em class="replaceable"><code>mode</code></em
></code>] <em class="replaceable"><code>directory-file(s)</code></em> <em cla
ss="replaceable"><code>desktop-file(s)</code></em> </p></div><div class="cmdsyno
psis"><p><code class="command">xdg-desktop-menu</code> forceupdate [<code cla
ss="option">--mode <em class="replaceable"><code>mode</code></em></code>]</p></d
iv><div class="cmdsynopsis"><p><code class="command">xdg-desktop-menu</code> {
<code class="option">--help</code> | <code class="option">--manual</code> |
<code class="option">--version</code> }</p></div></div><div class="refsect1" l
ang="en"><a name="description"></a><h2>Description</h2><p> |
| 2 The xdg-desktop-menu program can be used to install new menu entries |
| 3 to the desktop's application menu. |
| 4 </p><p> |
| 5 The application menu works according to the |
| 6 XDG Desktop Menu Specification at |
| 7 http://www.freedesktop.org/Standards/menu-spec |
| 8 </p></div><div class="refsect1" lang="en"><a name="commands"></a><h2>Command
s</h2><div class="variablelist"><dl><dt><span class="term">install</span></dt><d
d><p> |
| 9 Install one or more applications in a submenu of |
| 10 the desktop menu system. |
| 11 </p><p><em class="replaceable"><code>desktop-file</code></em>: |
| 12 A desktop file represents a single menu entry in the menu. |
| 13 Desktop files are defined by the freedesktop.org Desktop Entry |
| 14 Specification. The most important aspects of *.desktop |
| 15 files are summarized below. |
| 16 </p><p> |
| 17 Menu entries can be added to the menu system in two different |
| 18 ways. They can either be added to a predefined submenu in the |
| 19 menu system based on one or more category keywords, or they can |
| 20 be added to a new submenu. |
| 21 </p><p> |
| 22 To add a menu entry to a predefined submenu the desktop file |
| 23 that represents the menu entry must have a Categories= entry |
| 24 that lists one or more keywords. The menu item will be included |
| 25 in an appropriate submenu based on the included keywords. |
| 26 </p><p> |
| 27 To add menu items to a new submenu the desktop-files must be |
| 28 preceded by a directory-file that describes the submenu. |
| 29 If multiple desktop-files are specified, all entries will |
| 30 be added to the same menu. If entries are installed to a menu |
| 31 that has been created with a previous call to |
| 32 <span><strong class="command">xdg-desktop-menu</strong></span> the e
ntries will be |
| 33 installed in addition to any already existing entries. |
| 34 </p><p><em class="replaceable"><code>directory-file</code></em>: |
| 35 The *.directory file indicated by |
| 36 <em class="replaceable"><code>directory-file</code></em> represents
a submenu. |
| 37 The directory file provides the name and icon for a submenu. The |
| 38 name of the directory file is used to identify the submenu. |
| 39 </p><p> |
| 40 If multiple directory files are provided each file will |
| 41 represent a submenu within the menu that preceeds it, creating |
| 42 a nested menu hierarchy (sub-sub-menus). |
| 43 The menu entries themselves will be added to the last submenu. |
| 44 </p><p> |
| 45 Directory files follow the syntax defined by the freedesktop.org |
| 46 Desktop Entry Specification. |
| 47 </p></dd><dt><span class="term">uninstall</span></dt><dd><p> |
| 48 Remove applications or submenus from the desktop menu system |
| 49 previously installed with <span><strong class="command">xdg-desktop-
menu install</strong></span>. |
| 50 </p><p> |
| 51 A submenu and the associated directory file is only removed |
| 52 when the submenu no longer contains any menu entries. |
| 53 </p></dd><dt><span class="term">forceupdate</span></dt><dd><p> |
| 54 Force an update of the menu system. |
| 55 </p><p> |
| 56 This command is only useful if the last call to |
| 57 xdg-desktop-menu included the <code class="option">--noupdate</code>
option. |
| 58 </p></dd></dl></div></div><div class="refsect1" lang="en"><a name="opt
ions"></a><h2>Options</h2><div class="variablelist"><dl><dt><span class="term"><
code class="option">--noupdate</code></span></dt><dd> |
| 59 Postpone updating the menu system. If multiple updates to the |
| 60 menu system are made in sequence this flag can be used to |
| 61 indicate that additional changes will follow and that it is not |
| 62 necassery to update the menu system right away. |
| 63 </dd><dt><span class="term"><code class="option">--novendor</code></sp
an></dt><dd><p> |
| 64 Normally, xdg-desktop-menu checks to ensure that any *.directory |
| 65 and *.desktop files to be installed has a vendor prefix. |
| 66 This option can be used to disable that check. |
| 67 </p><p> |
| 68 A vendor prefix consists of alpha characters ([a-zA-Z]) and is |
| 69 terminated with a dash ("-"). |
| 70 Companies and organizations are encouraged to use a word |
| 71 or phrase, preferably the organizations name, for which they hold |
| 72 a trademark as their vendor prefix. |
| 73 The purpose of the vendor prefix is to prevent name conflicts. |
| 74 </p></dd><dt><span class="term"><code class="option">--mode</code> <em
class="replaceable"><code>mode</code></em></span></dt><dd><p><em class="replace
able"><code>mode</code></em> can be |
| 75 <span class="emphasis"><em>user</em></span> or <span class="emphasis
"><em>system</em></span>. |
| 76 In user mode the file is (un)installed for the current user |
| 77 only. In system mode the file is (un)installed for all users |
| 78 on the system. Usually only root is allowed to install in |
| 79 system mode. |
| 80 </p><p> |
| 81 The default is to use system mode when called by root |
| 82 and to use user mode when called by a non-root user. |
| 83 </p></dd><dt><span class="term"><code class="option">--help</code></sp
an></dt><dd> |
| 84 Show command synopsis. |
| 85 </dd><dt><span class="term"><code class="option">--manual</code></span
></dt><dd> |
| 86 Show this manualpage. |
| 87 </dd><dt><span class="term"><code class="option">--version</code></spa
n></dt><dd> |
| 88 Show the xdg-utils version information. |
| 89 </dd></dl></div></div><div class="refsect1" lang="en"><a name="desktop
files"></a><h2>Desktop Files</h2><p> |
| 90 An application item in the application menu is represented by a |
| 91 *.desktop file. A *.desktop file consists of a |
| 92 <span class="emphasis"><em>[Desktop Entry]</em></span> header followed by
several |
| 93 <em class="replaceable"><code>Key</code></em>=<em class="replaceable"><cod
e>Value</code></em> lines. |
| 94 </p><p> |
| 95 A *.desktop file can provide a name and description for an application |
| 96 in several different languages. This is done by adding a language |
| 97 code as used by LC_MESSAGES in square brackets behind the |
| 98 <em class="replaceable"><code>Key</code></em>. This way one can specify di
fferent |
| 99 values for the same <em class="replaceable"><code>Key</code></em> dependin
g on the |
| 100 currently selected language. |
| 101 </p><p> |
| 102 The following keys are often used: |
| 103 </p><div class="variablelist"><dl><dt><span class="term">Value=1.0</span></d
t><dd> |
| 104 This is a mandatory field to indicate that the *.desktop file |
| 105 follows the 1.0 version of the specification. |
| 106 </dd><dt><span class="term">Type=Application</span></dt><dd> |
| 107 This is a mandatory field that indicates that the *.desktop file |
| 108 describes an application launcher. |
| 109 </dd><dt><span class="term">Name=<em class="replaceable"><code>Applica
tion Name</code></em></span></dt><dd> |
| 110 The name of the application. |
| 111 For example <span class="emphasis"><em>Mozilla</em></span> |
| 112 </dd><dt><span class="term">GenericName=<em class="replaceable"><code>
Generic Name</code></em></span></dt><dd> |
| 113 A generic description of the application. |
| 114 For example <span class="emphasis"><em>Web Browser</em></span> |
| 115 </dd><dt><span class="term">Comment=<em class="replaceable"><code>Comm
ent</code></em></span></dt><dd> |
| 116 Optional field to specify a tooltip for the application. |
| 117 For example <span class="emphasis"><em>Visit websites on the Interne
t</em></span> |
| 118 </dd><dt><span class="term">Icon=<em class="replaceable"><code>Icon Fi
le</code></em></span></dt><dd> |
| 119 The icon to use for the application. This can either be |
| 120 an absolute path to an image file or an icon-name. |
| 121 If an icon-name is provided an image lookup by name is done |
| 122 in the user's current icon theme. The <span><strong class="command">
xdg-icon-resource</strong></span> |
| 123 command can be used to install image files into icon themes. |
| 124 The advantage of using an icon-name instead of an absolute |
| 125 path is that with an icon-name the application icon can be |
| 126 provided in several different sizes as well as in several |
| 127 differently themed styles. |
| 128 </dd><dt><span class="term">Exec=<em class="replaceable"><code>Command
Line</code></em></span></dt><dd> |
| 129 The command line to start the application. If the application |
| 130 can open files the %f placeholder should be specified. When |
| 131 a file is dropped on the application launcher the %f is replaced |
| 132 with the file path of the dropped file. If multiple files |
| 133 can be specified on the command line the %F placeholder should |
| 134 be used instead of %f. If the application is able to open URLs |
| 135 in addition to local files then %u or %U can be used instead |
| 136 of %f or %F. |
| 137 </dd><dt><span class="term">Categories=<em class="replaceable"><code>C
ategories</code></em></span></dt><dd><p> |
| 138 A list of categories separated by semi-colons. A category is |
| 139 a keyword that describes and classifies the application. |
| 140 By default applications are organized in the application menu |
| 141 based on category. When menu entries are explicitly assigned |
| 142 to a new submenu it is not necassery to list any categories. |
| 143 </p><p> |
| 144 When using categories it is recommended to include |
| 145 one of the following categories: |
| 146 AudioVideo, Development, Education, Game, Graphics, Network, |
| 147 Office, Settings, System, Utility. |
| 148 </p><p> |
| 149 See Appendix A of the XDG Desktop Menu Specification |
| 150 for information about additional categories. |
| 151 http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html |
| 152 </p></dd><dt><span class="term">MimeType=<em class="replaceable"><code
>Mimetypes</code></em></span></dt><dd> |
| 153 A list of mimetypes separated by semi-colons. This field is |
| 154 used to indicate which file types the application is able to |
| 155 open. |
| 156 </dd></dl></div><p> |
| 157 For a complete oveview of the *.desktop file format please |
| 158 visit http://www.freedesktop.org/wiki/Standards/desktop-entry-spec |
| 159 </p></div><div class="refsect1" lang="en"><a name="directoryfiles"></a><h2>D
irectory Files</h2><p> |
| 160 The appearance of submenu in the application menu is |
| 161 provided by a *.directory file. In particular it provides the title |
| 162 of the submenu and a possible icon. A *.directory file consists of a |
| 163 <span class="emphasis"><em>[Desktop Entry]</em></span> header followed by
several |
| 164 <em class="replaceable"><code>Key</code></em>=<em class="replaceable"><cod
e>Value</code></em> lines. |
| 165 </p><p> |
| 166 A *.directory file can provide a title (name) for the submenu |
| 167 in several different languages. This is done by adding a language |
| 168 code as used by LC_MESSAGES in square brackets behind the |
| 169 <em class="replaceable"><code>Key</code></em>. This way one can specify di
fferent |
| 170 values for the same <em class="replaceable"><code>Key</code></em> dependin
g on the |
| 171 currently selected language. |
| 172 </p><p> |
| 173 The following keys are relevqnt for submenus: |
| 174 </p><div class="variablelist"><dl><dt><span class="term">Value=1.0</span></d
t><dd> |
| 175 This is a mandatory field to indicate that the *.directory file |
| 176 follows the 1.0 version of the Desktop Entry specification. |
| 177 </dd><dt><span class="term">Type=Directory</span></dt><dd> |
| 178 This is a mandatory field that indicates that the *.directory file |
| 179 describes a submenu. |
| 180 </dd><dt><span class="term">Name=<em class="replaceable"><code>Menu Na
me</code></em></span></dt><dd> |
| 181 The title of submenu. |
| 182 For example <span class="emphasis"><em>Mozilla</em></span> |
| 183 </dd><dt><span class="term">Comment=<em class="replaceable"><code>Comm
ent</code></em></span></dt><dd> |
| 184 Optional field to specify a tooltip for the submenu. |
| 185 </dd><dt><span class="term">Icon=<em class="replaceable"><code>Icon Fi
le</code></em></span></dt><dd> |
| 186 The icon to use for the submenu. This can either be |
| 187 an absolute path to an image file or an icon-name. |
| 188 If an icon-name is provided an image lookup by name is done |
| 189 in the user's current icon theme. |
| 190 The <span><strong class="command">xdg-icon-resource</strong></span> |
| 191 command can be used to install image files into icon themes. |
| 192 The advantage of using an icon-name instead of an absolute |
| 193 path is that with an icon-name the submenu icon can be |
| 194 provided in several different sizes as well as in several |
| 195 differently themed styles. |
| 196 </dd></dl></div></div><div class="refsect1" lang="en"><a name="env_var
s"></a><h2>Environment Variables</h2><p> |
| 197 xdg-desktop-menu honours the following environment variables: |
| 198 </p><div class="variablelist"><dl><dt><span class="term">XDG_UTILS_DEBUG_LEV
EL</span></dt><dd> |
| 199 Setting this environment variable to a non-zero numerical value |
| 200 makes xdg-desktop-menu do more verbose reporting on stderr. |
| 201 Setting a higher value increases the verbosity. |
| 202 </dd><dt><span class="term">XDG_UTILS_INSTALL_MODE</span></dt><dd> |
| 203 This environment variable can be used by the user or |
| 204 administrator to override the installation mode. |
| 205 Valid values are <span class="emphasis"><em>user</em></span> and |
| 206 <span class="emphasis"><em>system</em></span>. |
| 207 </dd></dl></div></div><div class="refsect1" lang="en"><a name="exitcod
es"></a><h2>Exit Codes</h2><p> |
| 208 An exit code of 0 indicates success while a non-zero exit code |
| 209 indicates failure. The following failure codes can be returned: |
| 210 </p><div class="variablelist"><dl><dt><span class="term"><code class="option
">1</code></span></dt><dd> |
| 211 Error in command line syntax. |
| 212 </dd><dt><span class="term"><code class="option">2</code></span></dt><
dd> |
| 213 One of the files passed on the command line did not exist. |
| 214 </dd><dt><span class="term"><code class="option">3</code></span></dt><
dd> |
| 215 A required tool could not be found. |
| 216 </dd><dt><span class="term"><code class="option">4</code></span></dt><
dd> |
| 217 The action failed. |
| 218 </dd><dt><span class="term"><code class="option">5</code></span></dt><
dd> |
| 219 No permission to read one of the files passed on the command |
| 220 line. |
| 221 </dd></dl></div></div><div class="refsect1" lang="en"><a name="seealso
"></a><h2>See Also</h2><p><span class="citerefentry"><span class="refentrytitle"
>xdg-desktop-icon</span>(1)</span>, |
| 222 <span class="citerefentry"><span class="refentrytitle">xdg-icon-resource</
span>(1)</span>, |
| 223 <span class="citerefentry"><span class="refentrytitle">xdg-mime</span>(1)<
/span> |
| 224 </p></div><div class="refsect1" lang="en"><a name="examples"></a><h2>Example
s</h2><p> |
| 225 The company ShinyThings Inc. has developed an application named |
| 226 "WebMirror" and would like to add it to the application menu. |
| 227 The company will use "shinythings" as its vendor id. |
| 228 In order to add the application to the menu there needs to be a |
| 229 .desktop file with a suitable <span class="emphasis"><em>Categories</em></
span> entry: |
| 230 </p><pre class="programlisting"> |
| 231 shinythings-webmirror.desktop: |
| 232 |
| 233 [Desktop Entry] |
| 234 Encoding=UTF-8 |
| 235 Type=Application |
| 236 |
| 237 Exec=webmirror |
| 238 Icon=webmirror |
| 239 |
| 240 Name=WebMirror |
| 241 Name[nl]=WebSpiegel |
| 242 |
| 243 Categories=Network;WebDevelopment; |
| 244 </pre><p> |
| 245 </p><p>Now the xdg-desktop-menu tool can be used to add the |
| 246 shinythings-webmirror.desktop file to the desktop application menu: |
| 247 </p><pre class="programlisting"> |
| 248 xdg-desktop-menu install ./shinythings-webmirror.desktop |
| 249 </pre><p> |
| 250 </p><p> |
| 251 Note that for the purpose of this example the menu items are available |
| 252 in two languages, English and Dutch. |
| 253 The language code for Dutch is nl. |
| 254 </p><p> |
| 255 In the next example the company ShinyThings Inc. will add its own |
| 256 submenu to the desktop application menu consisting of a |
| 257 "WebMirror" menu item and a "WebMirror Admin Tool" menu item. |
| 258 </p><p> |
| 259 First the company needs to create two .desktop files that describe |
| 260 the two menu items. Since the items are to be added to a new submenu |
| 261 it is not necassery to include a Categories= line: |
| 262 </p><pre class="programlisting"> |
| 263 shinythings-webmirror.desktop: |
| 264 |
| 265 [Desktop Entry] |
| 266 Encoding=UTF-8 |
| 267 Type=Application |
| 268 |
| 269 Exec=webmirror |
| 270 Icon=shinythings-webmirror |
| 271 |
| 272 Name=WebMirror |
| 273 Name[nl]=WebSpiegel |
| 274 |
| 275 |
| 276 shinythings-webmirror-admin.desktop: |
| 277 |
| 278 [Desktop Entry] |
| 279 Encoding=UTF-8 |
| 280 Type=Application |
| 281 |
| 282 Exec=webmirror-admintool |
| 283 Icon=shinythings-webmirror-admintool |
| 284 |
| 285 Name=WebMirror Admin Tool |
| 286 Name[nl]=WebSpiegel Administratie Tool |
| 287 </pre><p> |
| 288 </p><p> |
| 289 In addition a .directory file needs to be created to provide a title and i
con |
| 290 for the sub-menu itself: |
| 291 </p><pre class="programlisting"> |
| 292 shinythings-webmirror.directory: |
| 293 |
| 294 [Desktop Entry] |
| 295 Encoding=UTF-8 |
| 296 |
| 297 Icon=shinythings-webmirror-menu |
| 298 |
| 299 Name=WebMirror |
| 300 Name[nl]=WebSpiegel |
| 301 </pre><p> |
| 302 </p><p> |
| 303 These file can now be installed with: |
| 304 </p><pre class="programlisting"> |
| 305 xdg-desktop-menu install ./shinythings-webmirror.directory \ |
| 306 ./shinythings-webmirror.desktop ./shinythings-webmirror-admin.desktop |
| 307 </pre><p> |
| 308 </p><p> |
| 309 The menu entries could also be installed one by one: |
| 310 </p><pre class="programlisting"> |
| 311 xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \ |
| 312 ./shinythings-webmirror.desktop |
| 313 xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \ |
| 314 ./shinythings-webmirror-admin.desktop |
| 315 xdg-desktop-menu forceupdate |
| 316 </pre><p> |
| 317 </p><p> |
| 318 Although the result is the same it is slightly more efficient to |
| 319 install all files at the same time. |
| 320 </p><p> |
| 321 The *.desktop and *.directory files reference icons with the names |
| 322 webmirror, webmirror-admin and webmirror-menu which should also be |
| 323 installed. In this example the icons are installed in two different |
| 324 sizes, once with a size of 22x22 pixels and once with a size |
| 325 of 64x64 pixels: |
| 326 </p><pre class="programlisting"> |
| 327 xdg-icon-resource install --size 22 ./wmicon-22.png shinythings-webmirror |
| 328 xdg-icon-resource install --size 22 ./wmicon-menu-22.png shinythings-webmirror-m
enu |
| 329 xdg-icon-resource install --size 22 ./wmicon-admin-22.png shinythings-webmirror-
admin |
| 330 xdg-icon-resource install --size 64 ./wmicon-64.png shinythings-webmirror |
| 331 xdg-icon-resource install --size 64 ./wmicon-menu-64.png shinythings-webmirror-m
enu |
| 332 xdg-icon-resource install --size 64 ./wmicon-admin-64.png shinythings-webmirror-
admin |
| 333 </pre><p> |
| 334 </p></div></div></body></html> |
| OLD | NEW |
|---|
Chromium Code Reviews
