xde-menu man page

xde-menu — XDG compliant menus for XDE

Synopsis

 xde-menu [ COMMAND ] [ OPTIONS ]
 xde-menugen [ OPTIONS ]
 xde-menu-popmenu [ OPTIONS ]
 xde-menu-monitor [ OPTIONS ]
 xde-menu-replace [ OPTIONS ]
 xde-menu-refresh [ OPTIONS ]
 xde-menu-restart [ OPTIONS ]
 xde-menu-quit [ OPTIONS ]

Description

xde-menu is a command-line program that can be used to generate an XDG compliant menu in a number of formats to support configuration of the root menu for light-weight window managers. It is a menu generator, system tray menu, and pop-up menu that can be used to both generate XDG compliant menus for a number of popular light-weight window managers as well as providing a system tray and pop-up menu.

xde-menu is capable of generating either a complete menu for a number of well-known window managers, or for generating a sub-menu that can be included in the root menu of those window managers.

Options

xde-menu uses getopt_long_only(3), so non-ambiguous option abbreviations are permitted.  xde-menu recognizes the following options:

Command Options

Command options affect the primary operating mode of the program.  Only one command option can be specified. xde-menu recognizes the following command options:

[--menugen, -G]

Specifies that xde-menu is to generate a window manager root-menu and then exit.  No new instance is created: only the root-menu is generated and then the program exits. This option does not cause an error when an instance of xde-menu is running (or not). This is the default when xde-menu is invoked as xde-menugen, or when no command option is specified.

xde-menu is typically used with the --menugen option to generate an initial window manager root menu as part of the initialization sequence of a particular window manager or panel.  The --wmname, --format, --output and --die-on-error options are normally specified in this case.

--monitor, -g

Specifies that xde-menu is not to exit after successfully generating the menu, but to monitor pertinent directories for changes, and regenerate the menu when changes are detected.  This option implies the --output option, without an argument (i.e. the default or detected menu file will be used).

When changes are detected in the application database, the menu is regenerated after an interval of no changes.  When changes are detected to the active window manager, the menu is regenerated, to the location and in the format of the new window manager, after an interval of no changes.

Runs a new instance of xde-menu and specifies that the program is to monitor pertinent directories for changes and regenerate all menus (root, system tray and pop-up) when changes are detected. This option implies the --output option. This option normally requires libinotify(3). This option causes an error when another instance of xde-menu is already running. (See the --replace option, below.) This is the default when xde-menu is invoked as xde-menu-monitor(1).

When performing background operation with the --monitor command option, the program will add a status icon to the system tray.  The status icon will be able to be used to pop up the menu.  Addition of a status icon to the system tray can be avoided using the --notray option.  The status icon can also be removed using the status icon pop-up configuration menu.

xde-menu is typically invoked as an XDG autostart item with the --monitor command option at startup of the X11 session.  The --wmname and --format options can often be unspecified.  An XDG autostart .desktop file is installed when the package installs that will invoke xde-menu and add a status icon to the system tray.

--popmenu, -P

Specifies that xde-menu is to request a running instance to pop-up a menu.  The menu to pop up, the location and invocation of the pop-up is controlled by additional general options.  Depending on the setting of the --button option, this will either pop up the menu at the current pointer position, or will pop up the menu at the centre of the screen. When multiple monitors are present, the menu will pop up at the centre of the monitor in which the pointer currently resides (which is used by most tiling window managers as the “current” monitor).  This option does not cause an error when no current instance of xde-menu is running. This is the default when xde-menu is invoked as xde-menu-popmenu(1).

For pop-up menu operation, an background instance of xde-menu can be asked to pop up an applications or other menu using the --popmenu command option.  The major use of this operation is to pop a menu from another program (such as a panel), or to pop a menu as a result of a button click or button press using window manager bindings.

--refresh, -E

Asks a running instance of xde-menu to refresh the menu.  This is normally not required when xde-menu is run with the --monitor option, as xde-menu then detects when .desktop files, icons, theme files or window managers have changed and automatically refreshes the menus in response.  This option causes an error when no current instance of xde-menu is running.  This is the default when xde-menu is invoked as xde-menu-refresh(1).

--restart, -S

Asks a running instance of xde-menu to restart (re-execute itself with the same options and arguments).  This is useful when the xde-menu executables have been upgraded.  This option causes an error when no current instance of xde-menu is running.  This is the default when xde-menu is invoked as xde-menu-restart(1).

--replace, -R

Replace a currently running instance (that was invoked with the --monitor option).  It is not an error if no other instance is running.  Runs a new instance of xde-menu and specifies that the program is to monitor pertinent directories for changes and regenerate all menus when changes are detected.  This option implies the --output and --monitor option.  This option normally requires libinotify(3).  This option (unlike --monitor) does not cause an error when another instance of xde-menu is already running, and simply replaces all other instances.  This is the default when xde-menu is invoked as xde-menu-replace(1).

--quit, -q

Ask a currently running instance (that was invoked with the --monitor option) to quit.  It is not an error if no other instance is running. This is the default when xde-menu is invoked as xde-menu-quit(1).

--help, -h, -?, --?

Print usage information, including the current values of option defaults, and exit.

--version, -V

Print version information and exit.

--copying, -C

Print copying information and exit.

General Options

--display DISPLAY

Specify the display to use (overriding the DISPLAY environment variable).  The default is the value of the DISPLAY environment variable.

--filename, -c FILENAME

Use a different configuration file from the default.  The default is the file $XDG_CONFIG_HOME/xde-menu/rc.  Any resources not present in the configuration file will be taken from from the /usr/share/X11/app-defaults/XDE-Menu resource file.  Resources present in the display's RESOURCE_MANAGER property will take precedence over any setting in these files.

--notray

Run without installing the menu in the system tray.  This is the default when the program in invoked as xde-menu-generate(1) or when the --menugen option is specified.

This option can be set with the resource xde-menu.systray.

--nogenerate

Do not generate window manager root menus.  This option is invalid when no command option is specified, or when the program is invoked as xde-menugen.  When combined with the --notray option, the program will background itself and service --popmenu requests only.

-x, --exit

When running in the foreground and generating window manager root menus, exit the main process immediately after generating menus.  This permits window manager root menus to be generated before launching the window manager, but not waiting longer than necessary.  The default is to run in the foreground and continue to run in the foreground, even after generating window manager root menus.

--verbose[=LEVEL], -v[LEVEL]

When generating output, generate more verbose output.  Increments or sets the output verbosity to LEVEL.  The default level is 1. Normal output is printed to standard output.  This option may be repeated.

--debug[=LEVEL], -D[LEVEL]

Print debugging information to standard error during operation. Increments or sets the debug verbosity to LEVEL.  The default level is 0.  Debugging output is printed to standard error.  This option may be repeated.

Menu Format Options

The following options affect the formatting and output of the window manager root window menu, system tray menu and pop-up menu.  Not all options affect the system tray and pop-up menus.

--wmname, -w WMNAME

Specifies the name of the window manager for which menus are to be generated.  Currently recognized window managers are as follows:

2bwm(1), adwm(1), aewm(1), aewm++(1), afterstep(1), awesome(1), blackbox(1), bspwm(1), ctwm(1), cwm(1), dtwm(1), dwm(1), echinus(1), etwm(1), failsafewm(1), fluxbox(1), flwm(1), fvwm(1), glasswm(1), goomwwm(1), herbstluftwm(1), i3(1), icewm(1), jwm(1), larswm(1), matwm2(1), metacity(1), mvwm(1), mwm(1), openbox(1), pekwm(1), spectrwm(1), twm(1), uwm(1), vtwm(1), waimea(1), wind(1), wm2(1), wmaker(1), wmii(1), wmx(1), xdwm(1) and yeahwm(1).

When unspecified, or when a window manager change is detected, the setting of the _XDE_WM_NAME property on the root window (or the WM_NAME or _NET_WM_NAME property on the window manager check window, or on the window owning the window manager selection, WM_S%d) is examined to determine the window manager name.  This is accomplished by converting the value of either property to all lowercase.  See also, “Environment” and “Properties”.

When the program is running in monitor mode for the active window manager, the window manager name need not be specified explicitly. However, when using the program in --menugen mode to simply generate a root menu without a DISPLAY environment variable, this option (or the --format option) must be specified explicitly.

--format, -f FORMAT

Specify the output format.  Recognized output formats are as follows:

2bwm(1), adwm(1), aewm(1), aewm++(1), afterstep(1), awesome(1), blackbox(1), bspwm(1), ctwm(1), cwm(1), dtwm(1), dwm(1), echinus(1), etwm(1), failsafewm(1), fluxbox(1), flwm(1), fvwm(1), glasswm(1), goomwwm(1), herbstluftwm(1), i3(1), icewm(1), jwm(1), larswm(1), matwm2(1), metacity(1), mvwm(1), mwm(1), openbox(1), pekwm(1), spectrwm(1), twm(1), uwm(1), vtwm(1), waimea(1), wind(1), wm2(1), wmaker(1), wmii(1), wmx(1), xdwm(1), yeahwm(1).

When unspecified, the setting or implied setting of the --wmname option is used.  If the --wmname option is also unspecified, or when a window manager change is detected, the setting of the _XDE_WM_NAME property on the root window (or the WM_NAME or _NET_WM_NAME property on the window manager check window, or on the window owning the window manager selection, WM_S%d) is examined to determine the window manager name.  This is accomplished by converting the first word in the value of either property to all lowercase.  See also, “Environment” and “Properties”.

When the program is running in monitor mode for the active window manager, the format need not be specified explicitly.  However, when using the program in --menugen mode to simply generate a root menu without a DISPLAY environment variable, this option (or the --wmname option) must be specified explicitly.

Note that openbox(1) and wmaker(1) support both an old and new menu format.  The old formats are only selected when explicitly specified as openboxold or wmakerold.

Note also that perlpanel(1) format is not associated with a specific window manager; however, the --wmname option is used to determine which entries to place in the perl panel output and the --desktop option is used to determine which application or system entries to include.

--fullmenu, -F, --nofullmenu, -l

When specified, output a full menu and not only the application sub-menu, or not.  The default is to output a full menu.  This also affects the system tray menu and pop-up menus accordingly.

--desktop, -d DESKTOP

Specify the desktop name for NotShowIn and OnlyShowIn comparisons. The default is the all uppercase string corresponding to the window manager name, (or the desktop name explicitly specified for the window manager and format), unless the XDG_CURRENT_DESKTOP environment variable is defined.

--root-menu, -r MENU

Specify the location of the root menu file.  The default is calculated using XDG environment variables (see “Environment”), and defaults to the file ${XDG_MENU_PREFIX}applications.menu in the $XDG_CONFIG_HOME:$XDG_CONFIG_DIRS search path.  Note, however, that xde-menu supports both applications and system menus using the --menu option.

--output, -o [FILENAME]

Write the window manager root menu output to the file, FILENAME. This is particularly useful with option --die-on-error as the output will not be written at all if an error is encountered.  If the FILENAME is not specified, the setting of the _XDE_WM_MENU property on the root window is examined to determine the location of the menu file.  When the property is not set or not available, the default menu location for the current --wmname or --format will be used.

Note that not all light-weight window managers support a root menu. Note also that at startup, xde-menu will wait several seconds for a window manager to appear if one is not present at initialization and neither the --wmname nor --format options are specified.

--icons, --noicons, -I

Include or do not include icons in the generated menu files.  This option has no effect when it is not possible to generate icons for the menu format.  That is, when the --format is one such as blackbox(1), or waimea(1), it is not possible to place icons in the root menu and this option is therefore ignored.  The default is to place icons in icon capable generated menus.

This option affects system tray menus and pop-up menus as well.  The default for system tray and pop-up menus is to only place icons in the generated menus when the --format also supports icons (to mimic the behaviour of the underlying window manager).  When the window manager --format does not support a root menu, (e.g. dwm(1)), icons will be added to the menu.

--theme THEME

Specify the theme name to use when displaying menus.  The default is to obtain the theme name from the default locations (such as the $HOME/.gtkrc-2.0 file).

--icon-theme, -t THEME

Specify the icon theme name to use when generating icons.  The default is to obtain the icon theme name from the default locations (such as the $HOME/.gtkrc-2.0 file).

--launch, -L, --nolaunch, -0

Specifies whether to use xdg-launch(1) to launch the desktop files directly or not.  This option will only be honoured when the xdg-launch(1) program is available and accessible.  Also, some window managers (e.g. openbox(1)) provide their own desktop startup launching and some don't.  So, the default setting may depend on the active window manager.

When specified and available, rather than launching programs itself, xde-menu will pass the appropriate command to xdg-launch(1).  Note that if a terminal emulation program was also specified with environment variables or X resources, these preferences will be passed to xdg-launch(1) in environment variables.

--style, -s STYLE

Specify which format of window manager menu specification output to generate.  STYLE can be one of the following:

fullmenu

The default: output a full menu suitable for use as the root menu specification for the window manager.

appmenu

Output a complete menu; however, only output the applications portion of the menu (no styles, window manager controls, logout, etc.), suitable to reference as an “Applications” menu.

entries

Only output the entries for the menu but not the enclosing menu itself: this is useful for some pipe menu commands.

This option does not affect the system tray nor pop-up menus.

--menu, -M MENUNAME

Specifies the filename stem of the root menu filename. This defaults to "applications.“ Another useful value is ”system.“ Other possible values include ”information“ and ”settings.“ The special value ”all" specifies that menus are to be generated for all known stems. This option only affects the automatic determination of the root menu file. When the root menu file is specified with the --root-menu option, the filename is determined verbatim.

--excluded

Include applications that are otherwise excluded in the menu specification.  This option will normally make applications that specify multiple categories appear in all categories rather than just the one category.

--nodisplay

Include applications that are marked no-display.  Applications that are marked no-display are typically marked thus because they only a mime type for the mime type database, or because they are only to be displayed by applications that understand them (e.g. some window manager applications).

--unallocated

Include applications that would be excluded because they were previously allocated a location in the menu.

--empty

Include empty sub-menus.  This is not a particularly useful feature for generation of the pop-up menu.  For window manager root menus, it typically does not matter, as most window managers suppress empty sub-menus.

--separators

Include all separators in the generated menu, whether required or not. This option is the only way to achieve multiple separators between items.  Without this option, only one separator will occur between any two items, and no separator will occur at the beginning or end of a menu.

--sort

Sort the entries by display name instead of name.

--actions

Provide a sub-menu for selecting actions for an application in those applications that have actions.

--tooltips

Include verbose tool-tips for application menu items.

POP-Up Menu Options

The following options are only valid when the --popmenu command option has been specified or implied.  These options only affect the pop-up menu.

--screen SCREEN

Specify the screen number, SCREEN, to use when positioning the menu. The default is either specified by the DISPLAY environment variable (when that variable specifies a screen); otherwise, all screens will be considered, and the screen containing the selected monitor will be used.

--Monitor MONITOR

Specify the monitor number, MONITOR, to use when positioning the menu.

--timestamp, -T TIMESTAMP

Provides the X11 server time stamp of the event that caused the pop-up. This is the X11 server time stamp of the button or key press that invoked the pop-up.  When the program is launched with startup notification, the time stamp will be take from the DESKTOP_STARTUP_ID environment variable.

--button, -b BUTTON

Specifies the button that was used to invoke the pop-up.  Defaults to Button3 (3).  This should be the button that was used to pop the menu.  A window manager that invokes this command in response to a button press should release its passive grab on the button before invoking the pop-up menu so that the popped up menu can grab the button. A BUTTON of zero (0) means that the program was invoked with a key press instead of a button.

--keypress, -k KEYSPEC

Specifies the key specification that was used to invoke the pop-up. Defaults to none.  This should be the key that was used to pop the menu. A window manager that invokes this command in response to a key press should release its passive grab on the key before invoking the pop-up menu so that the popped up menu can grab the keyboard.  A KEYSPEC of none means that the program was invoked with an unknown key press.

--pointer, -p

An alternate way of specifying --button=1.

--keyboard, -K

An alternate way of specifying --keypress with no option argument.

--which, -i {active|focused|pointer|MONITOR}

Specifies the monitor on which to pop the menu.  The default is to determine the monitor based on other options (such as the --button option).  The option argument can be one of the following (case insensitive, may be abbreviated):

default

When unspecified or specified as default, the default monitor selection algorithm is used as follows:

  1. When the --button or --pointer option is specified and non-zero, select the monitor containing the pointer.
  2. When neither --button nor --pointer option is specified, or --button is specified as zero, or --keypress or --keyboard is specified, select the monitor with the keyboard focus.
  3. When there is no monitor with the keyboard focus, select the monitor with the active window.
  4. When there is no active window and no window with the keyboard focus, select the monitor containing (or nearest to) the pointer.
active

Use the monitor containing the active client.

focused

Use the monitor containing the window with the keyboard focus (focused client).

pointer

Use the monitor containing (or closest to) the pointer.

MONITOR

Use the specified monitor number, MONITOR, indexed from zero (0), specifying the screen and monitor on which to pop the menu.  When there is one screen and multiple monitors (typical case for Xinerama or RANDR multi-head setups), MONITOR specifies the monitor, indexed from zero (0).  When there are multiple screens, the --screen option specifies the screen and MONITOR specifies the monitor.

--where, -W {default|pointer|center|topleft|bottomright|WHERE}

Specifies the position for the pop-up menu.  This can be one of the following values (case insensitive, may be abbreviated):

default

Place the menu automatically based on other information, such as the button or key pressed to invoke the menu.  This is the default when unspecified.  The default placement algorithm is as follows:

  1. If --button is specified and non-zero, or --pointer is specified, place the menu at the pointer regardless of the screen and monitor currently containing the pointer.  If the pointer is positioned outside an active monitor, fall back to the behaviour as if --button or --pointer was not specified.
  2. If --button is unspecified or zero (0), or --keyboard is specified, place the menu in the centre (considering work area) of the screen and monitor which currently contains the keyboard focus or active window.
pointer

Place the northwest corner of the menu under the mouse pointer.  This will always succeed.  This is the default when --button is specified and non-zero.

center

Place the menu in the centre of the root window on the current screen and monitor.  This is the default when --button is unspecified or zero, or --keyboard is specified.

topleft

Place the menu in the top-left corner of the current screen and monitor work area (considering panels and docks).

bottomright

Place the menu in the bottom-right corner of the current screen and monitor work area (considering panels and docks).

WHERE

Place the menu at the location specified by WHERE, which should be a string containing a screen geometry that can be parsed by XParseGeometry(3).  This is useful when the menu is launched from a menu button in an external program and the menu should be positioned adjacent to the button.  The geometry should be the geometry of the widget against which the menu should be placed.  When the width and height of the geometry are zero (or unspecified), it describes the point at which the menu should be placed.

Workspace Options

Often, light-weight window managers will have a workspace and window menu as part of their root menus (e.g. blackbox(1), fluxbox(1), openbox(1)).  This provides the same mechanism for the GTK2 menu for window managers that do not support a root menu, or for those that would simply like a consistent look and feel in the root menu.  The following options affect how work spaces and clients are shown in such a menu:

--order, -O ORDER

Specifies the order, ORDER, in which clients are shown, as follows:

client

Clients are listed in client order.  This is the same order that it presented in the _NET_CLIENT_LIST property on the root window of EWMH compliant window managers.

stacking

Clients are listed in stacking order.  This is the same order that is presented in the _NET_CLIENT_LIST_STACKING property on the root window of EWMH compliant window managers.

When unspecified, the default is client order (or whichever order is supported when the window manager does not support both).

This option can be set with the resource xde-menu.order.

--normal, -n

This option can be set with the resource xde-menu.normal.

--hidden, -H

When listing clients, also list hidden clients.  The default is to skip hidden clients or clients that have the skip-window-list attribute.

This option can be set with the resource xde-menu.hidden.

--minimized, -m

When listing clients, also list minimized clients.  The default is to skip minimized clients or clients that have the skip-window-list attribute.

This option can be set with the resource xde-menu.minimized.

--all-monitors, -a

When listing clients, also list clients displayed on monitors other than the current one.  This includes clients on workspaces that are currently visible on a monitor.

This option can be set with the resource xde-menu.allmonitors.

--all-workspaces, -A

When list clients, also list clients displayed on workspaces other than the current one.  As clients are listed, the current workspace may change as clients from other workspaces are listed.

This option can be set with the resource xde-menu.allworkspaces.

--noactivate, -N

When selecting clients, do not activate them.  The default is to activate the selected client.  When neither --raise nor --focus are specified, this results in linly highlighting the menu selection. Activation of the window will still occur; however, when the window is selected (e.g. a modifier key is released).

This option can be set with the resource xde-menu.activate.

--raise, -U

When selecting clients, raise the window.  The default is to only activate the selected client and not to explicitly raise it.  Some window managers raise windows when activated (others do not).  This provides a modicum of control.

This option can be set with the resource xde-menu.raise.

Session Management Options

X session management options are not used by another user other than the X11 Session Manager.  The following options are used by X session management:

-clientId CLIENTID

Specifies the X Session Management client identifier, CLIENTID, of the previously running session of xde-menu.

-restore SAVEFILE

Specifies the X Session Management file name of a file, SAVEFILE, to which to session information was saved for restoration.

Usage

xde-menu currently uses libwnck+ or libwnck both to identify the window manager and to provide the window manager actions menu.  The range and format of window manager actions provided by libwnck+ is superior to libwnck.  This use means that xde-menu does not currently provide any support for window managers that do not have a modicum of compliance to the EWMH/NetWM specifications.  That may change in the future.

To locate the menu under a button that was pressed in, for example, an external panel, where the button has geometry “55x20+30+0”, specify the --where='55x20+30+0' option.  This will properly position the menu under the button.

Window Managers

The following window managers and menu environments are supported by xde-menu:

--wmname=2bwm --format=2bwm

Like dwm(1), 2bwm(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu. This can be used to invoke the GTK+ version of the root menu (i.e. pop-up menu).

2bwm(1) does not provide a user-settable style mechanism.  Therefore, theme sub-menus provide only for the selection of XDE themes.

--wmname=adwm --format=adwm

Like dwm(1), adwm(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu. This can be used to invoke the GTK+ version of the root menu (i.e. pop-up menu).

adwm(1) provides a user-settable style mechanism.  Therefore, both style and theme sub-menus can be generated.

--wmname=aewm --format=aewm

aewm(1) is not tested, but should work fine.

--wmname=aewm++ --format=aewm++

aemw++(1) is barely ICCCM compliant and will likely not work well.

--wmname=afterstep --format=afterstep

No support has yet been included for afterstep(1).  Only generic applications menu and XDE theme sub-menus will currently be generated. The afterstep(1) root menu is not supported.

--wmname=awesome --format=awesome

No support has yet been included for awesome(1).  Only generic applications menu and XDE theme sub-menus will currently be generated. The awesome(1) root menu is not supported.

--wmname=blackbox --format=blackbox

blackbox(1) provides a root menu that is formatted similar to fluxbox(1) and the older openbox(1) (openboxold) menu style. The primary difference is that blackbox(1) does not support the display of icons.

Sub-menus of user-settable blackbox(1) styles and corresponding XDE themes can be generated.

--wmname=bspwm --format=bspwm

bspwm(1) has fairly good EWMH/NetWM support and should work fine, but is untested.

--wmname=ctwm --format=ctwm

ctwm(1) provides a root menu that is formatted similar to twm(1). This root menu format does not support the display of icons.

ctwm(1) when launched with XDE configuration files supports user-settable styles.  Sub-menus of user-settable ctwm(1) styles and corresponding XDE themes can be generated.

--wmname=cwm --format=cwm

cwm(1) only provides a rudimentary root menu (with no ability to generate sub-menus); however, it has the ability to specify command actions in response to key bindings or mouse buttons and can easily be configured to launch the GTK+ menu.

cwm(1) does not really have a user-settable style system; however, the colors of some things can be changed using the configuration file and the window manager can be restarted.  xde-style(1) does not fully support cwm(1) yet, so sub-menus of user-settable cwm(1) styles are not generated; however, XDE themes are.

--wmname=dtwm --format=dtwm

dtwm(1) provides a root menu that is formatted similar to twm(1). This root menu format does not support the display of icons.

dtwm(1) does not really have a user-settable style system.  Current support is only for setting XDE themes.

--wmname=dwm --format=dwm

dwm(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu.  This is used to invoke the GTK+ version of the root menu.

--wmname=echinus --format=echinus

Like dwm(1), echinus(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu.  This is used to invoke the GTK+ version of the root menu.

--wmname=etwm --format=etwm

etwm(1) provides a root menu that is formatted similar to twm(1). This root menu format does not support the display of icons.

--wmname=failsafewm --format=failsafewm

failsafewm(1) is not supported.

--wmname=fluxbox --format=fluxbox

fluxbox(1) provides a root menu that is formatted similar to blackbox(1).  This root menu, however, provides additional support for the display of icons.

--wmname=flwm --format=flwm

flwm(1) uses a directory of executables instead of a file format in the identical fashion to the wmx(1) window manager on which it is based.  It does not support the use of icons in menu items.  In fact, this is an alias for wmx as the two formats are completely compatible and interoperable.

--wmname=fvwm --format=fvwm

fvwm(1) provides a root menu using its own unique menu format. Although at one time fvwm(1) used a dtwm(1)-like menu format, it now uses its own unique perl(1) interface.  fvwm(1) supports the use of icons in menu items.

--wmname=glasswm --format=glasswm

glasswm(1) provides only some ICCCM support and is not supported.

--wmname=goomwwm --format=goomwwm

goomwwm(1) provides EWMH/NetWM support and should work well, but is untested.

--wmname=herbstluftwm --format=herbstluftwm

herbstluftwm(1) provides EWMH/NetWM support and should work well, but is untested.

--wmname=i3 --format=i3

i3(1) provides EWMH/NetWM support and should work well, but is untested.

--wmname=icewm --format=icewm

icewm(1) provides a programs menu using its own unique menu format. It support the display of icons in menu items.  icewm(1) does not provide the ability to specify the entire root menu: some items in the root menu are fixed by window manager and do not appear in the menu file.

--wmname=jwm --format=jwm

jwm(1) provides a root menu using its own XML-based menu format.  It support the display of icons in menu items.  jwm(1) recently had a rework of its configuration files.  Unless you are on the most current versions, your mileage may vary.

--wmname=larswm --format=larswm

larswm(1) is barely ICCCM compliant and is, therefore, not supported.

--wmname=matwm2 --format=matwm2

Like dwm(1), matwm2(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu.  This is used to invoke the GTK+ version of the root menu.

--wmname=metacity --format=metacity

metacity(1) does not provide a root menu; however, it has ample facility for launching the GTK+ menu.

--wmname=mvwm --format=mvwm

mvwm(1) is a derivative of fvwm(1) and should work well.

--wmname=mwm --format=mwm

mwm(1) is the old pre-openmotif window manager that was intended on providing the capabilities of the dtwm(1) OSF/Motif/CDE window manager.  It provides a root menu following a similar configuration file format to twm(1), ctwm(1), etwm(1) and vtwm(1).  It does not have the ability to display icons in menu items.

Like dtwm(1), mwm(1) does not really have a user-settable style system.  Current support is only for setting XDE themes.

--wmname=openbox --format=openbox or --format=openboxold

Two formats are supported for the openbox(1) window manager: the newer openbox-3 XML format (openbox) and the older fluxbox(1)-like menu format (openboxold). The default for the openbox(1) window manager is the newer style; however, it still supports both formats.  Both formats support the use of icons in menu items.

--wmname=pekwm --format=pekwm

pekwm(1) provides a root menu that is formatted using its own file format.  It supports dynamic menus and provides support for displaying icons in menu elements.

--format=perlpanel

perlpanel(1) can read a fluxbox(1) or blackbox(1) style menu and generate a GTK+ menu from it.  This format generates a fluxbox(1)-like menu for use by perlpanel(1).  (Note that this format can be specified in addition to other formats, in which case, this format will be generated as well.)  The menu file is typically stored in ~/.perlpanel/menu, ~/.config/perlpanel/menu or /usr/share/perlpanel/menu, independent of which window manager is currently running.

--wmname=spectrwm --format=spectrwm

Like dwm(1), spectrwm(1) does not provide a root menu; however, it does provide a mechanism for invoking an external root menu.  This is used to invoke the GTK+ version of the root menu.

--wmname=twm --format=twm

twm(1) provides a root menu that uses its own format.  ctwm(1), etwm(1) and vtwm(1) share this format.  The format does not support the display of icons in the root menu.

--wmname=uwm --format=uwm

uwm(1) provides a root menu that uses its own format.  The format supports the use of icons in menu items.

--wmname=vtwm --format=vtwm

vtwm(1) provides a root menu that is formatted similar to twm(1). This root menu format does not support the display of icons.

--wmname=waimea --format=waimea

waimea(1) provides a root menu that is formatted similar to blackbox(1).  As with blackbox(1), this root menu does not support the display of icons.

--wmname=wind --format=wind

wind(1) does not have a root menu: it doesn't have any menus at all. wind(1) window manager is difficult to support: the window manager has no mechanism for launching a menu.  However, an external key-binder such as bbkeys(1) can be used to launch the menu.  Also, it appears that wind(1) does not grab button clicks on the root window.

--wmname=wm2 --format=wm2

wm2(1) uses a directory of executables instead of a file format in the identical fashion to flwm(1) (which as based on wmx(1), a derivative of wm2(1)).  It does not support the use of icons in menu items.  In fact, this is an alias for flwm as the two formats are completely compatible and interoperable.

However, wm2(1) barely provides ICCCM support and is, therefore, poorly supported.  Use its EWMH compliant derivative, wmx(1), or its derivative flwm(1).

--wmname=wmaker --format=wmaker or --format=wmakerold

Two formats are supported for the wmaker(1) window manager: the newer window maker lisp-based menu (wmaker) and the older line-based menu (wmakerold).  The default for the wmaker(1) window manager is the newer style; however, it still supports both formats.  Neither format supports the use of icons in menu items.

--wmname=wmii --format=wmii

wmii(1) provides EWMH/NetWM support and should work well, but is currently untested.

--wmname=wmx --format=wmx

wmx(1) uses a directory of executables instead of a file format in the identical fashion to flwm(1) (which was based on wmx(1)).  It does not support the use of icons in menu items.  In fact, this is an alias for flwm as the two formats are completely compatible and interoperable.

--wmname=xdwm --format=xdwm

xdwm(1) provides EWMH/NetWM support and should work well, but is currently untested.

--wmname=yeahwm --format=yeahwm

yeahwm(1) does not have a root menu: it doesn't have any menus at all.  Therefore, the GTK+ menu must be used.   yeahwm(1) is another window manager that is difficult to support without an external key binder (such as bbkeys(1)).  Mouse button clicks on the root window are intercepted by the window manager.  Support is unlikely.

Terminal Programs

For desktop entries that set Terminal=true, when they may also set StartupWMClass to a class name specific to the program being executed.  Most terminal programs (and xterm(1) specifically) can set the WMCLASS name and class to something other than that of the terminal program (i.e. instead of xterm.XTerm).  When the desktop entries do so, xde-menu will set the name attribute on the terminal to the name specified when the terminal is launched, if possible.  This also permits, for terminal emulation programs such as xterm(1), the ability to set special terminal resources by application.  Because not many desktop entry files do this, when no StartupWMClass is specified, the APPID or BINARY will be used instead and StartupWMClass will be automatically populated.

This procedure provides additional assistance to window managers when terminal emulation programs do not properly observe startup notification.  (For example, xterm(1) does not properly observe startup notification, even though it properly observes X11 Session Management, whereas many other terminal emulators support both.)

It is possible to change the default terminal emulation program used when these applications are launched by using environment variables (see “Environment”) or X resources (see “X Resources”).

Terminal programs that are known to xde-menu are: uxterm(1), xterm(1), st(1), aterm(1), rxvt(1), alacritty(1), which do not support startup notification, but do support setting the resource name; pterm(1), Eterm(1), urxvt(1), urxvt-tabbed(1), termit(1), gnome-terminal(1), termite(1), mate-terminal(1), terminology(1), kitty(1), which do support startup notification and do support setting the resource name; roxterm(1), lxterminal(1), xfce4-terminal(1), lilyterm(1), tilix(1), guake(1), terminator(1), which do support startup notification but do not support setting the resource name; x-terminal-emulator(1), deepin-terminal(1), tilda(1), which do support startup notification but do not support setting the resource name, nor setting the window title; qterminal(1), konsole(1), which do not support startup notification, nor setting the resource name, nor setting the window title; and koi8rxterm(1) which is language specific.

When the TERMINAL environment variable is set to one of these terminals (a terminal known to xde-menu), it will automatically determine the corresponding XDG_TERMINAL and XDG_TERMRESN commands when they are not specified.  See “X Resources” and “Environment” below.  When no terminal environment variables are specified, terminal programs will be detected in the user's PATH in the order specified above.  Note that terminix(1) and hyper(1) are currently unknown. XDG_TERMINAL and XDG_TERMRESN must currently be specified to use those or other unknown terminals.

See “X Resources” and “Environment” below for more information on selecting the terminal to use for launching applications that need one.

X Resources

Most values that affect the look and feel of xde-menu may also be specified as X resources in the RESOURCE_MANAGER database associated with the X server.  All of these resources can have the specific resource name and class (xde-menu, XDE-Menu). xde-menu specific resource defaults are contained in the /usr/share/X11/app-defautls/XDE-Menu file, in accordance with the convention for naming applications defaults files after their resource class.  See also “Files”.

xde-menu uses a standard X11 resource file for runtime configuration. xde-menu uses the following X11 Resource Manager resources (note that the window manager name, WMNAME, can optionally be specified before the resource, where indicated, to alter behaviour for only a given window manager):

xde-menu[.WMNAME].debug: INTEGER

Same values as --debug option: an integer between zero (0) and six(6), inclusive.

xde-menu[.WMNAME].verbose: INTEGER

Same values as --verbose option: an integer between zero (0) and six (6), inclusive.

xde-menu[.WMNAME].timeout: TIME

Specifies the amount of time for the pop-up to persist in milliseconds. Not used. No option equivalent.

xde-menu[.WMNAME].iconsize: UNSIGNED INTEGER

Specifies the size of icons. Not used. No option equivalent.

xde-menu[.WMNAME].fontsize: DOUBLE

Specifies the point size of fonts. Not used. No option equivalent.

xde-menu[.WMNAME].border: INTEGER

Specifies the border around the pop-up in pixels. Not used. No option equivalent.

xde-menu[.WMNAME].rootmenu: PATH

Same values as --root-menu option: path to the root menu file.

xde-menu[.WMNAME].fileout: {true|false}

Truth value specifying whether to output the window manager root menu.

xde-menu[.WMNAME].menufile: PATH

Same values as --output option: path to the window manager root menu file.

xde-menu[.WMNAME].filename: PATH

Same values as --filename option: path to the configuration file to use.

xde-menu[.WMNAME].noicons: {true|false}

Truth value specifying whether to include icons in the applications and window list menus.

xde-menu[.WMNAME].theme: NAME

Same values as --theme option: name of the XDE (GTK2+) theme name. This resource should not be specified in a resource file and will not be written by a save operation.

-xde-menu[.WMNAME].icontheme: NAME

Same values as --icon-theme option: name of the XDE (GTK2+) icon theme name.  This resource should not be specified in a resource file and will not be written by a save operation.

xde-menu[.WMNAME].launch: {true|false}

Truth value specifying whether to use xdg-launch(1), if available. Same as the --launch and --nolaunch options.

xde-menu[.WMNAME].runhist: PATH

Specifies the location of the run history file.  The default is $XDG_CONFIG_HOME/run-history.

xde-menu[.WMNAME].recapps: PATH

Specifies the location of the recent applications file.  The default is $XDG_CONFIG_HOME/recent-applications.

xde-menu[.WMNAME].recently: PATH

Specifies the location of the recently used files list.  The default is $XDG_DATA_HOME/recently-used, and if that file does not exist, $HOME/.recently-used.

xde-menu[.WMNAME].recent: PATH

Specifies the location of the recently used applications list.  The default is $XDG_DATA_HOME/recent-applications, and if that file does not exist, $HOME/.recent-applications.

xde-menu[.WMNAME].maximum: INTEGER

Same as the --maximum option to xde-recent(1): specifies the maximum number of recent applications or files to display in the recent files and applications menus.  The minimum value is one, and the maximum is 100.  The default value when unspecified is 50.  Specified as zero (0) when there is no limit on the number to display.

xde-menu[.WMNAME].menu: FILESTEM

Specifies the stem name of the menu used when determining the root menu file for which to build the menu.  The default is applications.  This resource should typically not be used in the resource file and will not be written by a save operation.

xde-menu[.WMNAME].button: UNSIGNED INTEGER

Same as the --button and --pointer options: specifies the button that was pressed to launch the menu (or zero (0) when no button was pressed to launch the menu).  This resource should not be used in a resource file and will not be written by a save operation.

xde-menu[.WMNAME].keypress: KEYSPEC

Same as the --keypress and --keyboard options: specifies that the menu was launched as a result of a key press instead of a button click. This resource should not be used in a resource file and will not be written by a save operation.

xde-menu[.WMNAME].which: {default|active|focused|pointer|SCREEN}

Same as the --which option: specifies which screen to use when posting the menu. This resource should not be used in a resource file and will not be written by a save operation.

xde-menu[.WMNAME].where: {default|pointer|center|topleft|bottomright|GEOMETRY}

Same as the --where option: specifies where on the screen to post the menu. This resource should not be used in a resource file and will not be written by a save operation.

xde-menu[.WMNAME].normal: {true|false}

Truth value specifying whether to include normal windows in client lists.

xde-menu[.WMNAME].hidden: {true|false}

Truth value specifying whether to include hidden windows in client lists.

xde-menu[.WMNAME].minimized: {true|false}

Truth value specifying whether to include minimized windows in client lists.

xde-menu[.WMNAME].allmonitors: {true|false}

Truth value indicating whether to include windows from all monitors in client lists.

xde-menu[.WMNAME].allworkspaces: {true|false}

Truth value indicating whether to include windows from all work spaces in client lists.

xde-menu[.WMNAME].activate: {true|false}

Truth value specifying whether to activate selected windows from client lists.

xde-menu[.WMNAME].raise: {true|false}

Truth value specifying whether to raise selected windows from client lists.

xde-menu[.WMNAME].systray: {true|false}

Truth value specifying whether to install a status icon in the system tray.

xde-menu[.WMNAME].generate: {true|false}

Truth value specifying whether to generate window manager root menus when supported.

xde-menu[.WMNAME].excluded: {true|false}

Truth value specifying whether to include excluded applications in the applications menu.

xde-menu[.WMNAME].nodisplay: {true|false}

Truth value specifying whether to include no-display applications in the applications menu.

xde-menu[.WMNAME].unallocated: {true|false}

Truth value specifying whether to include unassigned applications in the applications menu.

xde-menu[.WMNAME].separators: {true|false}

Truth value specifying whether to include all separators in the applications menus.

xde-menu[.WMNAME].sort: {true|false}

Truth value specifying whether to sort applications by display name in the applications menu.

xde-menu[.WMNAME].tooltips: {true|false}

Truth value specifying whether to include verbose tooltips for applications in the applications menu.

xde-menu[.WMNAME].actions: {true|false}

Truth value specifying whether to offer desktop actions in the applications menu for applications that provide actions.

xde-menu[.WMNAME].exit: {true|false}

Truth value specifying whether to exit once the window manager root window has been generated.

xde-menu[.WMNAME].termname: TERMINAL-NAME

Word specifying the name of the terminal emulation program executable to be used to launch, or pass to xdg-launch(1), for applications that need terminals.

xde-menu[.WMNAME].terminal: EXEC-COMMAND

String specifying the terminal emulation program command to be used to launch, or pass to xdg-launch(1), for applications that need terminals.  This command can contain Exec line substitutions.

xde-menu[.WMNAME].termresn: EXEC-COMMAND

String specifying the terminal emulation program command to be used when a resource name is available and can be set to launch, or pass to xdg-launch(1), for applications that need terminals.  This command can contain Exec line substitutions; however, their % must be escaped with an additional %, and somewhere in the command line there must appear a printf(3) style unescaped %s expression to be substituted with the resource name.

Environment

The following environment variables are significant to the operation of xde-menu:

$XDG_CURRENT_DESKTOP

Specifies the current desktop.  When the --format is not specified, the format defaults to the value of this environment variable converted to lower-case.  When the --desktop is not specified, the desktop defaults to the value of this environment variable.

$XDG_MENU_PREFIX

Specifies the prefix to apply to the default menu name to derive the root menu unless specified with the --root-menu option.  When unspecified, this variable defaults to a null string.

xde-menu finds the root menu using the following logic:

  1. If a file name is specified using the --root-menu option, (and the window manager has not changed since xde-menu was launched), that file name is used as the root menu.
  2. If the window manager has changed since xde-menu was launched, any --root-menu option that was specified at launch is ignored.
  3. If the file specified by --root-menu is not found or unspecified, the file name ${XDG_MENU_PREFIX}applications.menu is sought in each of the sub-directories name menu in the path $XDG_CONFIG_HOME:$XDG_CONFIG_DIRS in accordance with the XDG menu specification.

    Note that the stem applications can be changed using the --menu option.

  4. If not found, the file name applications.menu is sought in each of the menu sub-directories in the path $XDG_CONFIG_HOME:$XDG_CONFIG_DIRS in accordance with the XDG menu specification.

    Note that the stem applications can be changed using the --menu option.

$XDG_CONFIG_HOME

Specifies the user XDG configuration directory.  When unspecified, defaults to $HOME/.config in accordance with XDG specifications.

$XDG_CONFIG_DIRS

Specifies the system XDG configuration directories.  When unspecified, defaults to /etc/xdg in accordance with XDG specifications.

$XDG_DATA_HOME

Specifies the user XDG data directory.  When unspecified, defaults to $HOME/.local/share in accordance with XDG specifications.

$XDG_DATA_DIRS

Specifies the system XDG data directory search path.  When unspecified, defaults to /usr/local/share:/usr/share in accordance with XDG specifications.

$XDG_ICON_THEME

Specifies the name of the icon theme.  When not specified, the icon theme will be determined from configuration sources (e.g. the $HOME/.gtkrc-2.0 file).

$XDG_TERMINAL

Used by xde-menu, or passed to xdg-launch(1), as the command to prefix to the Exec line of terminal applications to launch applications within a terminal.

$XDG_TERMRESN

Used by xde-menu, or passed to xdg-launch(1), as the command to prefix to the exec line of terminal applications to launch applications within a terminal when a resource name is available to be set on the terminal.  (Not necessarily defined for all terminal types).

$TERMINAL

Use by xde-menu, or passed to xdg-launch(1), as the name of the preferred terminal program to run.  If this terminal is known to xde-menu, it will automatically determine the corresponding XDG_TERMINAL and XDG_TERMRESN commands when they are not specified. See “Terminal Programs”, above, for a list of known terminal emulation programs.

Properties

The following X11 window properties are significant to the operation of xde-menu:

_XDE_WM_NAME

When available and set on the root window, specifies the window manager name used to derive the --wmname and --format options when the options are unspecified or when the window manager has changed since the xde-menu command was launched.

_NET_WM_NAME

When _XDE_WM_NAME is unavailable, and this property is set properly on the window manager EWMH/NetWM check window, the first word of the property will be used to derive the --wmname and --format options when the options are unspecified or when the window manager has changed since the xde-menu command was launched.

_XDE_WM_STYLE

When set on the root window, or XDE check window, used to determine the location of the window manager style file.

_XDE_WM_STYLENAME

When set on the root window, or XDE check window, used to determine the name of the style set for the window manager.

_XDE_WM_THEME

When set on the root window, or XDE check window, used to determine the name of the theme set for XDE.

_XDE_WM_THEMEFILE

When set on the root window or XDE check window, used to determine the file to use for the theme set for XDE.

Files

Resources for configuration and tweaking the run-time operation of xde-menu are looked up in the order, below.  Resources that are read later only have an effect if the resource was not already set by some previous file.  The locations are as follows:

RESOURCE_MANAGER

The first place that resource configuration is examined is from the RESOURCE_MANAGER property on the root window of the screen on which the menu is to be displayed.

$XDG_CONFIG_HOME/xde-menu/WMNAME/rc

The location of the window-manager specific user configuration file. The window manager name component, WMNAME, in the path, above, is the all uppercase window manager name.  This location is used when there is no user file specified.

$XDG_CONFIG_HOME/xde-menu/rc

The default location of the generic user configuration file.  This is used when there is no user file specified.

/usr/share/X11/app-defaults/XDE-Menu

The default location of the generic system configuration file.  This is used when there is no user file available or to provide defaults when one is available.

The following file locations are scanned for recent files and applications:

$XDG_CONFIG_HOME/xde/recent-applications

This is the location of a simple recent applications file maintained by the xde-app(1) launcher application.

$XDG_DATA_HOME/recently-used
$HOME/.recently-used

These are the locations (in order of preference) of a simple XML formatted recently used files list maintained by legacy applications (as well as xdg-launch(1)).

$XDG_DATA_HOME/recent-applications
$HOME/.recent-applications

These are the locations (in order of preference) of a simple XML formatted recently used applications list maintained by legacy applications (as well as xdg-launch(1)).

$XDG_DATA_HOME/recently-used.xbel

This is the location of the current XBEL formatted recently used files list maintained by current applications (as well as xdg-launch(1)).

$XDG_DATA_HOME/recent-applications.xbel

This is the location of the current XBEL formatted recently used applications lists maintained by current applications (as well as xdg-launch(1)).

History

xde-menu was written for a number of reasons:

  1. Existing lightweight menu generators that read XDG .desktop files (e.g. fbmenugen(1), menutray(1)) do not conform to the XDG menu generation specifications and in particular are incapable of merging menus.

    Many existing light-weight window manager generators that read XDG .desktop files do not conform to the XDG menu generation specifications and, in particular, are incapable of merging menus.

  2. Existing XDG menu generators (such as the SuSE xdg_menu(1) perl script) do not properly merge default merge directories and do not observe <Layout> commands.  Also, they are poor at including icons in the generated menus.  They, of course, do not generate system tray nor pop-up menus either.
  3. Existing XDG menu generators run once and keep cache information, or have a regenerate command placed in the menu.  They do not monitor XDG directories for changes and update menus on changes.
  4. The lxpanel(1) and pcmanfm(1) menu generators do not have any of the above deficiencies; however, they do not create window manager specific sub-menus.  Also, they are buggy and generally fail to display a menu at all when they have a problem.  They do not handle the <FileName> tag within a <Layout> tag.
  5. None of the menu-generating facilities that I have found can handle an NFS-mounted home directory.  I find this annoying: XDG menus are host specific.

This program largely incorporates the perl versions of the xdg-traymenu(1p) and xdg-menugen(1p) programs.  The reason for incorporating both together was to reduce the amount of time that is taken to read and cache .desktop file information.

Author

Brian Bidulock <mailto:bidulock@openss7.org>.

See Also

xde-style(1), xde-menugen(1), xdg-traymenu(1p), xdg-menugen(1p), xde-identify(1), inotify(7).

Referenced By

icewm(1), icewm-menu(5).

The man pages xde-menugen(1), xde-menu-monitor(1), xde-menu-popmenu(1), xde-menu-quit(1), xde-menu-refresh(1), xde-menu-replace(1) and xde-menu-restart(1) are aliases of xde-menu(1).

2019-09-05 xde-menu 0.11