1XDG-DESKTOP-MENU(1)         xdg-desktop-menu Manual        XDG-DESKTOP-MENU(1)
2
3
4

NAME

6       xdg-desktop-menu - command line tool for (un)installing desktop menu
7       items
8

SYNOPSIS

10       xdg-desktop-menu install [--noupdate] [--novendor] [--mode mode]
11                        directory-file(s) desktop-file(s)
12
13       xdg-desktop-menu uninstall [--noupdate] [--mode mode] directory-file(s)
14                        desktop-file(s)
15
16       xdg-desktop-menu forceupdate [--mode mode]
17
18       xdg-desktop-menu {--help | --manual | --version}
19

DESCRIPTION

21       The xdg-desktop-menu program can be used to install new menu entries to
22       the desktop's application menu.
23
24       The application menu works according to the XDG Desktop Menu
25       Specification at
26       http://www.freedesktop.org/wiki/Specifications/menu-spec
27

COMMANDS

29       install
30           Install one or more applications in a submenu of the desktop menu
31           system.
32
33           desktop-file: A desktop file represents a single menu entry in the
34           menu. Desktop files are defined by the freedesktop.org Desktop
35           Entry Specification. The most important aspects of *.desktop files
36           are summarized below.
37
38           Menu entries can be added to the menu system in two different ways.
39           They can either be added to a predefined submenu in the menu system
40           based on one or more category keywords, or they can be added to a
41           new submenu.
42
43           To add a menu entry to a predefined submenu the desktop file that
44           represents the menu entry must have a Categories= entry that lists
45           one or more keywords. The menu item will be included in an
46           appropriate submenu based on the included keywords.
47
48           To add menu items to a new submenu the desktop-files must be
49           preceded by a directory-file that describes the submenu. If
50           multiple desktop-files are specified, all entries will be added to
51           the same menu. If entries are installed to a menu that has been
52           created with a previous call to xdg-desktop-menu the entries will
53           be installed in addition to any already existing entries.
54
55           directory-file: The *.directory file indicated by directory-file
56           represents a submenu. The directory file provides the name and icon
57           for a submenu. The name of the directory file is used to identify
58           the submenu.
59
60           If multiple directory files are provided each file will represent a
61           submenu within the menu that precedes it, creating a nested menu
62           hierarchy (sub-sub-menus). The menu entries themselves will be
63           added to the last submenu.
64
65           Directory files follow the syntax defined by the freedesktop.org
66           Desktop Entry Specification.
67
68       uninstall
69           Remove applications or submenus from the desktop menu system
70           previously installed with xdg-desktop-menu install.
71
72           A submenu and the associated directory file is only removed when
73           the submenu no longer contains any menu entries.
74
75       forceupdate
76           Force an update of the menu system.
77
78           This command is only useful if the last call to xdg-desktop-menu
79           included the --noupdate option.
80

OPTIONS

82       --noupdate
83           Postpone updating the menu system. If multiple updates to the menu
84           system are made in sequence this flag can be used to indicate that
85           additional changes will follow and that it is not necessary to
86           update the menu system right away.
87
88       --novendor
89           Normally, xdg-desktop-menu checks to ensure that any *.directory
90           and *.desktop files to be installed has a vendor prefix. This
91           option can be used to disable that check.
92
93           A vendor prefix consists of alpha characters ([a-zA-Z]) and is
94           terminated with a dash ("-"). Companies and organizations are
95           encouraged to use a word or phrase, preferably the organizations
96           name, for which they hold a trademark as their vendor prefix. The
97           purpose of the vendor prefix is to prevent name conflicts.
98
99       --mode mode
100           mode can be user or system. In user mode the file is (un)installed
101           for the current user only. In system mode the file is (un)installed
102           for all users on the system. Usually only root is allowed to
103           install in system mode.
104
105           The default is to use system mode when called by root and to use
106           user mode when called by a non-root user.
107
108       --help
109           Show command synopsis.
110
111       --manual
112           Show this manual page.
113
114       --version
115           Show the xdg-utils version information.
116

DESKTOP FILES

118       An application item in the application menu is represented by a
119       *.desktop file. A *.desktop file consists of a [Desktop Entry] header
120       followed by several Key=Value lines.
121
122       A *.desktop file can provide a name and description for an application
123       in several different languages. This is done by adding a language code
124       as used by LC_MESSAGES in square brackets behind the Key. This way one
125       can specify different values for the same Key depending on the
126       currently selected language.
127
128       The following keys are often used:
129
130       Type=Application
131           This is a mandatory field that indicates that the *.desktop file
132           describes an application launcher.
133
134       Name=Application Name
135           The name of the application. For example Mozilla
136
137       GenericName=Generic Name
138           A generic description of the application. For example Web Browser
139
140       Comment=Comment
141           Optional field to specify a tooltip for the application. For
142           example Visit websites on the Internet
143
144       Icon=Icon File
145           The icon to use for the application. This can either be an absolute
146           path to an image file or an icon-name. If an icon-name is provided
147           an image lookup by name is done in the user's current icon theme.
148           The xdg-icon-resource command can be used to install image files
149           into icon themes. The advantage of using an icon-name instead of an
150           absolute path is that with an icon-name the application icon can be
151           provided in several different sizes as well as in several
152           differently themed styles.
153
154       Exec=Command Line
155           The command line to start the application. If the application can
156           open files the %f placeholder should be specified. When a file is
157           dropped on the application launcher the %f is replaced with the
158           file path of the dropped file. If multiple files can be specified
159           on the command line the %F placeholder should be used instead of
160           %f. If the application is able to open URLs in addition to local
161           files then %u or %U can be used instead of %f or %F.
162
163       Categories=Categories
164           A list of categories separated by semi-colons. A category is a
165           keyword that describes and classifies the application. By default
166           applications are organized in the application menu based on
167           category. When menu entries are explicitly assigned to a new
168           submenu it is not necessary to list any categories.
169
170           When using categories it is recommended to include one of the
171           following categories: AudioVideo, Development, Education, Game,
172           Graphics, Network, Office, Settings, System, Utility.
173
174           See Appendix A of the XDG Desktop Menu Specification for
175           information about additional categories:
176           http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html#category-registry
177
178       MimeType=Mimetypes
179           A list of mimetypes separated by semi-colons. This field is used to
180           indicate which file types the application is able to open.
181
182       For a complete overview of the *.desktop file format please visit
183       http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec
184

DIRECTORY FILES

186       The appearance of submenu in the application menu is provided by a
187       *.directory file. In particular it provides the title of the submenu
188       and a possible icon. A *.directory file consists of a [Desktop Entry]
189       header followed by several Key=Value lines.
190
191       A *.directory file can provide a title (name) for the submenu in
192       several different languages. This is done by adding a language code as
193       used by LC_MESSAGES in square brackets behind the Key. This way one can
194       specify different values for the same Key depending on the currently
195       selected language.
196
197       The following keys are relevant for submenus:
198
199       Type=Directory
200           This is a mandatory field that indicates that the *.directory file
201           describes a submenu.
202
203       Name=Menu Name
204           The title of submenu. For example Mozilla
205
206       Comment=Comment
207           Optional field to specify a tooltip for the submenu.
208
209       Icon=Icon File
210           The icon to use for the submenu. This can either be an absolute
211           path to an image file or an icon-name. If an icon-name is provided
212           an image lookup by name is done in the user's current icon theme.
213           The xdg-icon-resource command can be used to install image files
214           into icon themes. The advantage of using an icon-name instead of an
215           absolute path is that with an icon-name the submenu icon can be
216           provided in several different sizes as well as in several
217           differently themed styles.
218

ENVIRONMENT VARIABLES

220       xdg-desktop-menu honours the following environment variables:
221
222       XDG_UTILS_DEBUG_LEVEL
223           Setting this environment variable to a non-zero numerical value
224           makes xdg-desktop-menu do more verbose reporting on stderr. Setting
225           a higher value increases the verbosity.
226
227       XDG_UTILS_INSTALL_MODE
228           This environment variable can be used by the user or administrator
229           to override the installation mode. Valid values are user and
230           system.
231

EXIT CODES

233       An exit code of 0 indicates success while a non-zero exit code
234       indicates failure. The following failure codes can be returned:
235
236       1
237           Error in command line syntax.
238
239       2
240           One of the files passed on the command line did not exist.
241
242       3
243           A required tool could not be found.
244
245       4
246           The action failed.
247
248       5
249           No permission to read one of the files passed on the command line.
250

SEE ALSO

252       xdg-desktop-icon(1), xdg-icon-resource(1), xdg-mime(1), Desktop entry
253       specification[1], Desktop menu specification[2]
254

EXAMPLES

256       The company ShinyThings Inc. has developed an application named
257       "WebMirror" and would like to add it to the application menu. The
258       company will use "shinythings" as its vendor id. In order to add the
259       application to the menu there needs to be a .desktop file with a
260       suitable Categories entry:
261
262           shinythings-webmirror.desktop:
263
264             [Desktop Entry]
265             Encoding=UTF-8
266             Type=Application
267
268             Exec=webmirror
269             Icon=webmirror
270
271             Name=WebMirror
272             Name[nl]=WebSpiegel
273
274             Categories=Network;WebDevelopment;
275
276       Now the xdg-desktop-menu tool can be used to add the
277       shinythings-webmirror.desktop file to the desktop application menu:
278
279           xdg-desktop-menu install ./shinythings-webmirror.desktop
280
281       Note that for the purpose of this example the menu items are available
282       in two languages, English and Dutch. The language code for Dutch is nl.
283
284       In the next example the company ShinyThings Inc. will add its own
285       submenu to the desktop application menu consisting of a "WebMirror"
286       menu item and a "WebMirror Admin Tool" menu item.
287
288       First the company needs to create two .desktop files that describe the
289       two menu items. Since the items are to be added to a new submenu it is
290       not necessary to include a Categories= line:
291
292           shinythings-webmirror.desktop:
293
294             [Desktop Entry]
295             Encoding=UTF-8
296             Type=Application
297
298             Exec=webmirror
299             Icon=shinythings-webmirror
300
301             Name=WebMirror
302             Name[nl]=WebSpiegel
303
304
305           shinythings-webmirror-admin.desktop:
306
307             [Desktop Entry]
308             Encoding=UTF-8
309             Type=Application
310
311             Exec=webmirror-admintool
312             Icon=shinythings-webmirror-admintool
313
314             Name=WebMirror Admin Tool
315             Name[nl]=WebSpiegel Administratie Tool
316
317       In addition a .directory file needs to be created to provide a title
318       and icon for the sub-menu itself:
319
320           shinythings-webmirror.directory:
321
322             [Desktop Entry]
323             Encoding=UTF-8
324
325             Icon=shinythings-webmirror-menu
326
327             Name=WebMirror
328             Name[nl]=WebSpiegel
329
330       These file can now be installed with:
331
332           xdg-desktop-menu install ./shinythings-webmirror.directory \
333                 ./shinythings-webmirror.desktop ./shinythings-webmirror-admin.desktop
334
335       The menu entries could also be installed one by one:
336
337           xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \
338                 ./shinythings-webmirror.desktop
339           xdg-desktop-menu install --noupdate ./shinythings-webmirror.directory \
340                 ./shinythings-webmirror-admin.desktop
341           xdg-desktop-menu forceupdate
342
343       Although the result is the same it is slightly more efficient to
344       install all files at the same time.
345
346       The *.desktop and *.directory files reference icons with the names
347       webmirror, webmirror-admin and webmirror-menu which should also be
348       installed. In this example the icons are installed in two different
349       sizes, once with a size of 22x22 pixels and once with a size of 64x64
350       pixels:
351
352           xdg-icon-resource install --size 22 ./wmicon-22.png shinythings-webmirror
353           xdg-icon-resource install --size 22 ./wmicon-menu-22.png shinythings-webmirror-menu
354           xdg-icon-resource install --size 22 ./wmicon-admin-22.png shinythings-webmirror-admin
355           xdg-icon-resource install --size 64 ./wmicon-64.png shinythings-webmirror
356           xdg-icon-resource install --size 64 ./wmicon-menu-64.png shinythings-webmirror-menu
357           xdg-icon-resource install --size 64 ./wmicon-admin-64.png shinythings-webmirror-admin
358
359

AUTHORS

361       Kevin Krammer
362           Author.
363
364       Jeremy White
365           Author.
366
368       Copyright © 2006
369

NOTES

371        1. Desktop entry specification
372           http://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/
373
374        2. Desktop menu specification
375           http://www.freedesktop.org/wiki/Specifications/menu-spec/
376
377
378
379xdg-utils 1.0                     07/29/2020               XDG-DESKTOP-MENU(1)
Impressum