gtkmenuplus 5 "2019-11-28" "version 1.1.10" "menu configuration file"

NAME

Format of menu configuration files for gtkmenuplus(1).

SYNOPSIS

menu_configuration_file

DESCRIPTION

Gtkmenuplus takes a menu_configuration_file as its primary argument, and constructs a menu from the directives that it reads in the file. This document describes the format of the menu configuration file, and the set of valid directives.

FORMAT

Comments

Anything on a line after the "#" character is considered a comment and is ignored, - "#" included.

The following cases are exceptions in which "#" and the characters that follow it till the end of the line aren't comments:

a backslash "\" comes immediately before "#"
directives cmd=, if=, elseif=
variable evaluation variable_name==
variable assignment of quoted strings that include "#", such as quoted HTML colors, i.e., "#FAF090"
valid shell syntax following the above directives, i.e., if=test ${y#prefix} = abc

Lines whose first non-space character is "#" are ignored.

Lines

Blank lines are ignored.

Each meaningful line in a menu configuration file contains a directive (which may be preceded by whitespace). The case of directives is ignored.

Directives

Seven directives are inherited from myGtkMenu, the ancestor to gtkmenuplus. (M) marks directives whose behaviour in gtkmenuplus differs from that in myGtkMenu.

item=item_description
cmd=command                (M) (command may be null)
icon=path_to_image_file    (M) (path may be null)
separator
submenu=submenu_description
iconsize=size
menupos=x y                (M)
menuposition=x y           (synonym for menupos)

The remaining directives are new in gtkmenuplus:

icondirectory=path_to_icon_directory

format=format_string

tooltip=tooltip_text
tooltipformat=format_string

launcher=path_to_launcher(s)
launchersub=path_to_directory
launcherdirectory=path_to_launcher_directory
launcherdir=path_to_launcher_directory (synonym for launcherdirectory)
launcherargs=arguments
launcherdirfile=launcher_dirfile
launchersubmenu=launcher_dirfile

activationlogfile=logfile_path

include=menu_configuration_file or
include=path_to_directory[/file_glob] [directory_glob]

if=condition
elseif=condition or elif=condition
else
endif or fi

error=message

/path_to/file
~/path_to/file

configure=option_list
onexit
endsubmenu

Notes

For directive=value there may be whitespace between directive and "=". Whitespace between "=" and value is ignored, as is trailing whitespace after value.

A line of item= may be followed by a line of cmd=, icon= and/or tooltip=, in any order.

Variables

variable_name=value
variable_name==expression

Any string preceding "=", aside from the directives listed above, will be taken to be a declaration of a variable, providing it meets the following conditions.

A variable_name may not be the same as any existing environmental variable.

A variable_name must begin with an alphabetic character. All other characters in a variable_name must be alphabetic, numeric or the underscore.

Whitespace between a variable_name and "=" is ignored.

Whitespace following the "=", and trailing whitespace after value or expression is ignored. If you want to include leading or trailing whitespace in a value or expression, enclose it all in single or double quotes, which will be stripped before the value is stored or the expression is evaluated. You can also use quotes if you want a value beginning with "=", e.g.

myvar="  something nice "

If a variable_name is followed by "==", the text after the "==" is interpreted as an expression which is passed to the shell for evaluation; whatever ends up in stdout becomes the variable value.

The value of a variable_name is referenced as $variable_name in any subsequent line of the same file as well as of included files. For instance $variable_name can be all or part of a command (in a cmd= line); of a menu item's item_description (in an item= line); or of the condition on if= or elseif= lines.

If the same variable_name is re-assigned, including in included files, its value is redefined.

Parameters

Additional arguments can optionally follow menu_configuration_file on the gtkmenuplus command line. Such arguments are called positional parameters, and their value can be referenced by $1, $2,... etc, in any line in the menu_configuration_file (except cmd= lines, since $1, $2... may occur in shell one-liners and be confused with gtkmenuplus command line parameter references).

Referencing an unassigned (null) parameter is allowed in an evaluation context, such as if=, elseif= or variable_name==, and produces the value 0 ('false', 'no').

$0 references the menu_configuration_file itself unless gtkmenuplus gets its input from stdin. Reference $0 is invalid in included files.

Paths

The following lines may contain a path or paths:

cmd=command
icondirectory=path_to_icon_directory
icon=path_to_image_file
launcherdirectory=path_to_launcher_directory
launcher=path_to_launcher(s)
launchersub=path_to_directory
include=menu_configuration_file
include=path_to_directory

Paths may be absolute (beginning with "/") or relative. They may begin with the tilde ("~"), which in all cases will be expanded into $HOME, as it would be by the shell.

Relative paths may begin with "./" and/or include "../", begin with the name of a directory or simply name a file. With some exceptions noted below, such paths will be taken to be relative to the path of the directory that contains the menu configuration file as specified on the gtkmenuplus command line.

Note Unlike what the shell does, gtkmenuplus resolves relative paths from the path of the directory that contains $0 rather than from the current working directory. This can be confusing. For that reason it is recommended to invoke gtkmenplus with the full path of the menu_configuration_file. This note applies to the remainder of this section.

Exceptions the following directives resolve relative paths as noted:

icon=         directory in the last non-null icondirectory= line, if any
launcher=     directory in the last non-null launcherdirectory= line, if any
launchersub=  directory in the last non-null launcherdirectory= line, if any
cmd=          assumed to be on the system's PATH.

The command on a cmd=command line in particular may contain multiple paths requiring expansion (typically multiple arguments to the specified executable). After expansion the entire command must be no longer than 1024 (?) characters.

DIRECTIVES

Item

item=item_description

Denotes the item_description to show in the menu. An underscore as part of item description indicates that the next letter is the mnemonic (the keyboard accelerator) for the menu item.

A mnemonic can also be added via global formatting, cf. format=.

If you want to include an underscore in the item description but not use it to indicate a mnemonic, use two consecutive underscores.

An item= line may be immediately followed by any or all of cmd=, icon= and tooltip= lines, in any order.

An item= line marks the end of any menu item or submenu preceding it.

Cmd

cmd=command

Optional. Denotes the command to run.

Must be preceded by an item= line, and possibly by icon= or tooltip= lines. It applies to the menu entry begun by the preceding item= line.

The command that follows cmd= on the line must be a valid (syntax error free) shell command, or nothing.

cmd=, on its own, or an item= not followed by a cmd=, will create a disabled menu item (possibly to use as a menu or section title).

You can use "~" to refer to your home directory, e.g. ~/bin/myScript.sh.

A cmd= line is the only kind of line in which you can't use parameters originating on the gtkmenuplus command line, or as part of an include line, since $1, $2... may occur in shell one-liners and be confused with gtkmenuplus command line parameter references. If you want to use a parameter in a command, set a variable to the parameter e.g.

myParam=$1

and use the variable ($myParam) in the command.

Not everything that can work at a shell prompt will work in cmd=:

You can't specify more than one command on a line (using ;, && or |).
You can't use environmental variables (e.g. $WINEPREFIX, $HOME).

However, you can get the shell to do stuff like that for gtkmenuplus. Either you can make a small script containing the commands you need, or you can make your command a shell invocation with sh -c, e.g.:

 # start two instances of freecell
 cmd=sh -l -c "( sol --freecell &) ; (sol --freecell &)"

You also can have:

 cmd=path_to_a_non_executable_file [path_to_other_non_executable_file ...]

A non_executable_file could for instance be a doc, html, xls or plain text file. path_to_a_non_executable_file can begin with a tilde (for the home directory), or be a relative or absolute path.

If a cmd= begins with a non_executable_file, its MIME type is used to determine which application will be used to execute that file (and any path_to_other_non_executable_files on the same line).

Tooltip

tooltip=tooltip_text

Optional. Adds a tooltip to a menu item or submenu.

Must be preceded by an item=, and possibly by an icon= and/or (if there's a preceding item= line) a cmd= line. It applies to the menu entry begun by the preceding item= line or submenu begun by the preceding submenu= line.

Icon

icon=path_to_image_file | icon_name | NULL

Optional. Denotes an image to show with the menu item or submenu.

Must be preceded by an item=, or submenu= line, and possibly by an icon= and/or (if there's a preceding item= line) a cmd= line.

It applies to the menu entry begun by the preceding item= line or submenu begun by the preceding submenu= line.

If a menu item lacks an icon line, or has an icon= line with nothing following the "=" sign, gtkmenuplus will attempt to find an icon associated with the executable named in the menu item's cmd= line; or, if the cmd= line specifies only a non-executable file, an attempt will be made to locate an icon associated with the default program used to open that file.

There are situations in which gtkmenplus can't automatically determine the icon image for an item= without an icon=. In such cases you need specify the icon explicitly:

any submenu
a menu item where the command on the cmd=command involves sh -c to run multiple shell commands
a menu item where cmd= involves a terminal emulator to run a shell command
a menu item where cmd= involves gtksu, gksudo or equivalent to run a shell command
successive menu items (e.g. ones opening text files) which, based on command or file type would all have the same icon
a cmd= consisting of a URL to something on the net or on another machine. If the net isn't accessible, gtkmenuplus will block while trying to get information about the target file type. It might be better to use a named icon like, .e.g., text-html or applications-internet.

If you do not want an image on your menu item, use the line icon=NULL, or the method described below.

If the most recently encountered "configure=" line in the menu configuration file included the word noicons, any item without an icon=path_to_image_file or icon=icon_name line will not be assigned an image.

A subsequent configure= line containing the word icons will cause gtkmenuplus to revert to its default behaviour of finding icons based on the application or filetype specified on the cmd= line.

The path_to_image_file includes a dotted file extension and follows the rules for paths referred to in menu configuration files (see above):

A path_to_image_file can begin with a tilde, which will be expanded as in bash to $HOME.
It can be absolute.
Or it can be relative. If it doesn't begin with a dot, and the most recent icondirectory=path_to_icon_directory line has a non-null path_to_icon_directory, the path is relative to that. Otherwise it's relative to the path in which the configuration file was found (as specified on the gtkmenuplus command line, unless gtkmenuplus is reading from stdin).

The dotted file extension indicates one of the supported image types: png, svg, xpm or gif.

Tip: To speed execution, all icon files associated with a menu configuration file should be of the same image size.

Instead of a path_to_image_file you can use an icon_name, which is distinguished by not including an extension for the image type.

An icon_name will be recognised if icons matching it are in one of the standard sets of icon directories (e.g. /usr/share/pixmaps/, subdirectories of /usr/share/icons, etc); in particular the icon names listed in freedesktop.org's Icon Naming Specification:

http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

Format

format=formatting

formatting=[ format_string [; format_string [; format_string... ]]]
formatting=[ format_string [, format_string [, format_string... ]]]

Menu items and submenu labels following a format line have the given format_string(s) applied, until the occurrence of the next format=formatting line.

If more than one format_string occurs on a format= line, each format_string is applied in turn to successive following items or submenu labels at the same level as the menu level in which the format= line occurs. Items or submenu labels at any other level in the menu hierachy are not subject to the format_string sequence.

If formatting contains only one format_string, that format_string applies to everything following, no matter where it is in the menu hierarchy.

A format_string consists of a string of whitespace-separated attribute="value" pairs, attributes and their values must be appropriate for placement within a  tag in the Pango Text Attribute Markup Language, see https://developer.gnome.org/pango/stable/PangoMarkupFormat.html for details (the "convenience tags" mentioned there aren't supported).

An additional non-Pango attribute="value" pair is supported, mnemonic, see further down for details.

Examples:

format= font_desc="Sans Italic 12"

format= style="italic" underline="single"

format= foreground="blue"  # color names see /usr/share/X11/rgb.txt

format= weight="bold"      # also possible: "ultralight", "light", "normal",
                           # "ultrabold", "heavy", or a numeric weight

format= size='12800'       # in 1024ths of a point, or one of 'xx-small',
                           # 'x-small', 'small', 'medium', 'large',
                           # 'x-large', 'xx-large'

format= color="RoyalBlue";color="DodgerBlue"  # alternate two shades

A format= with a null format_string causes all subsequent menu and submenu items to revert to default formatting.

As well as using format= lines to modify some menu and submenu entries, global changes (background color, font, etc.) can be made to menus using the built-in "GTK theme" mechanism.

GTK2 and GTK3 differ in the way themes are defined and applied for specific applications. For GTK2 only you can invoke gtkmenuplus as such:

env GTK2_RC_FILES=gtk2_rc_file gtkmenuplus menu_configuration_file

Note: Since version 1.1.3 gtkmenplus unexports variable GTK2_RC_FILES to avoid changing the default theme of any GTK2 application that is being executed.

As yet another formatting method, the text of any menu item or submenu label can be formatted by wrapping it in some text tags, e.g.

<span color="white">some text</span>

Menu items or submenus formatted by inclusion of <span...>... tags or by preceding format= lines mustn't contain "<" or ">" characters. Use < or > instead.

If a format= line is in force, that will apply to all parts of a line containing <span...>... tags not within those tags.

mnemonic=value is a semantic, non-Pango attribute="value" that modifies each formatted item label by inserting a keyboard accelerator key mark (_) before the character that is to act as accelerator. The key is detected only while the menu is being displayed. Menus display mnemonic keys as underlined characters.

Value can be either "1" or an arbitrary non-null quoted string.

"1" inserts _ before the label, unless the label already includes its own mnemonic.
A quoted string inserts _<char><space> before the label, also when the label already includes its own mnemonic. <char> represents a character extracted (sequentially with recycling) from value The sequence is recycled separately for each submenu level.

Examples:

format = mnemonic="1"
launchersub = /usr/share/applications

Turns the first letter of all application menu item labels into a mnemonic, unless the label already includes its own mnemonic.

format = mnemonic="ABC"
submenu = England
  item = London
  item = Birmingham
  item = Liverpool
  item = Manchester
submenu = Scotland
  item = Glasgow
  item = Edingburgh
  item = Aberdeen
  item = Inverness

expands into two submenus with the following labels

_A England
   _A London, _B Birmingham, _C Liverpool, _A Manchester
_B Scotland
   _A Glasgow, _B Edingburgh, _C Aberdeen, _A Inverness

The rules for applying mnemonic="value" are the same rules as for applying global label formatting. menmonic="value" can't be used within  tags and with directive tooltipformat=.

Tooltipformat

tooltipformat=format_string

The text of all tooltips encountered in menu items and submenus is formatted by the preceding tooltipformat=format_string line.

format_string is as for format=>format_string lines.

A null format_string turns off formatting for tooltips in subsequent menu items and submenus.

Launcher

launcher=path_to_launcher(s)

A launcher is a freedesktop.org's .desktop file used to launch an application. It usually includes a name, executable, comment (tooltip) and icon. System desktop files can be located in /usr/share/applications, and /usr/local/share/applications. User's application files can be located in ~/.local/share/applications, or any other directory.

If path_to_launcher is the path of a .desktop file, it will be used to create a menu entry, unless an exclusion case applies (see section Launcher Exclusion Cases).

Any preceding format=format_string line will apply to that entry.

Any preceding launcherargs=arguments line will apply to that entry, that is, the arguments string will be appended to the command entry for the shell to execute. Quote arguments as needed.

If path_to_launcher(s) is a directory path (dirpath), it will be scanned for .desktop files, which will all be used to create successive menu entries.

Any preceding launcherdirfile=launcher_dirfile line will apply to the menu entry of each scanned dirpath.

path_to_launcher(s) can also be a colon-separated list of paths. In this case a single launcher= line effectively expands to multiple launcher=member_path lines, where member_path represents each successive member of path_to_launcher(s). Expansion stops at the end of the list if configure=nolauncherlistfirst is enabled (by default it is). If configure=launcherlistfirst is enabled, expansion stops after the first successful file hit in the list.

Note that each unsuccessful expansion is likely to produce a "File not found" error message, which in turn will display an error box. To prevent such error box from appearing use configure=errorconsoleonly.

path_to_launcher(s) follows the rules for paths referred to in menu configuration files (see above):

It can begin with a tilde, which will be expanded as in bash to $HOME.
It can be absolute.
Or it can be relative. If path_to_launcher(s) doesn't begin with a dot, and the most recent launcherdirectory=path_to_launcher_directory line has a non-null path_to_launcher_directory, it's relative to that.
Otherwise a relative path_to_launcher(s) is relative to the path in which the configuration file was found (as specified on the gtkmenuplus command line, unless gtkmenuplus is reading from stdin).

If you want to refer to all the .desktop files in the directory specified by launcherdirectory= use

launcher=.

or

launcher=*

Launcher Exclusion Cases

A .desktop file is displayed in the menu unless one or more of the following exclusion cases apply:

The file is a regular file and its name doesn't end with ".desktop", i.e., /path/MyEditor.desktop is included; /path/MyEditor is exluded.
The file is a link and the name of its ultimate target doesn't end with ".desktop", i.e.,

/path/MyEditor -> /path/a -> /path/b/geany.desktop # included /path/MyEditor -> /path/edit_app # excluded
The file includes entry "NoDisplay=true" and configure=launchernodisplay is enabled (by default it is).
The file includes a "Categories=List" entry and List isn't empty, and an applicable launcherdirfile= Categories= entry excludes List.
The file doesn't include a "Category=List" entry or List is empty, and configure=launchernullcategory is disabled (by default it's enabled), and a "Category=" list of an applicable launcherdirfile= dirfile doesn't include special category "NULL" (verbatim).
The "Category=" entries of the .desktop file and of an applicable launcherdir= dirfile are defined, and the intersection between their list values is empty. Note that null list elements, such as the null item found between two semicolons in e.g. "Desktop;;System", don't count towards finding an intersection.

Launchersub

launchersub=path_to_directory

It is a recursive version of launcher=. It displays all the .desktop files that it can find in path_to_directory and in the subdirectories under it. Menu entries are created in nested submenus according to the subdirectory level. More information follows further down in this section.

path_to_directory can also be a colon-separated list of paths. In this case a single launchersub= line effectively expands into multiple launchersub=member_path lines, where member_path represents each successive member of path_to_directory. Expansion stops at the end of the list if configure=nolauncherlistfirst is enabled (by default it is). If configure=launcherlistfirst is enabled, expansion stops after the first successful recursive directory hit in the list.

Note that each unsuccessful expansion is likely to produce a "File not found" error message, which in turn will display an error box. To prevent such error box from appearing use configure=errorconsoleonly.

Rules for relative paths, the directives launcherdirfile= and launcherargs=, and Launcher Exclusion Cases all apply to launchersub= as they do to launcher=. Each topic is explained elsewhere in this document.

When launchersub=dirpath is encounted submenus are created automatically for dirpath and each scanned subdirectory.

Up to 5 menu levels are automatically nested (see MAX_SUBMENU_DEPTH).

By default the submenu label is the name of the subdirectory that includes its .desktop files, and the submenu icon is undefined. To specify different values and other properties use directive launcherdirfile=.

If the maximum allowed submenu depth is exceeded, launchersub=dirpath reports a warning and displays the menu. Contrast that with the submenu= directive, which exits with a fatal error if submenu depth is exceeded.

By default subdirectory scanning depth is set to fill at most 5 submenu levels. If launcher files exist in lower subdirectories they will be ignored without warnings.

For menu testing purposes you can force printing warnings by telling gtkmenuplus to scan for launcher files at deeper levels. Then if such files exist and they can't be displayed within the MAX_SUBMENU_DEPTH hard limit, a warning message is printed to the console. To increase the scan depth set environment variable GTKMENUPLUS_SCAN_DEPTH=5 or higher.

Item formatting for the items in dirpath of launchersub=dirpath is set by the most recent format= and tooltipformat= directives that precede launchersub=dirpath. For nested subdirectories, you can control item formatting by specifying format_strings in a file named .desktop.directory. See section Format about format_strings. Several example menus are included in directory "test" of the project repository.

Launcherdirfile

launcherdirfile=launcher_dirfile

After this line is encountered, properties of dirpath in all subsequent launcher=dirpath and launchersub=dirpath lines are read from launcher_dirfile, which stands of "launcher desktop directory file".

A launcher_dirfile is a .desktop file that doesn't include an "Exec=" line, and may include lines "Type=Directory" and "Format=formatting".

It sets the menu entry label, icon, and tooltip for each scanned dirpath.

Formatting is applied to all contained items and cascades to subdirectories of dirpath.

.desktop file entry "Categories=List", if any, is used to filter which .desktop files to display in the menu, as explained in section Launcher Exclusion Cases.

launcherdirfile= followed by no text clears out the launcher_dirpath string for all subsequent launcher=dirpath lines.

There can be multiple launcherdirfiles lines; each one sets the launcher_dirfile for all launcher=dirpath lines that follow, until the next launcherdirfile= line.

launcher_dirfile follows the rules for paths referred to in menu configuration files (see above): tilde expansion and relative paths.

An alternative method to provide settings for launcher{sub}=dirpath lines is to place a hidden file named .desktop.directory in each subdirectory. If this file exists, it overrides the launcher_dirfile specified by launcherdirfile=launcher_dirfile.

Example of launcher_dirfile:

# Note: This file is ignored if its dirpath is used in "launcher=dirpath".
[Desktop Entry]
Encoding=UTF-8
Name=submenu label
Comment=redirected from .desktop.directory (tooltip)
Name[es]=localized label example
Comment[es]=localized tooltip example
Icon=icon_name_no_extension or full_path_to_icon_file_with_extension
Type=Directory
Categories=
# Format applies to contained items, and cascades.
Format=background="purple" etc.
# You can also apply direct (local) formatting to Name= and Comment=
# (label and tooltip), i.e.
# Name=<span>background="green">submenu name</span>

Launchersubmenu

launchersubmenu=launcher_dirfile

launchersubmenu= describes a submenu as an alternative to submenu=.

Label, icon, and tooltip are read from launcher_dirfile instead of being specified through item=, icon=, etc. In all other aspects launchersubmenu works like submenu=.

Launcherargs

launcherargs=arguments

After this line is encountered, in all subsequent launcher{sub}= lines, the arguments string will be appended to the launcher command entry for the shell to execute. Quote arguments as needed.

launcherargs= followed by no text clears out the arguments string for all subsequent launcher= lines.

There can be multiple launcherargs lines; each one sets the arguments for all launcher{sub}= lines that follow, until the next launcherargs= line.

Launcherdir, Launcherdirectory

launcherdirectory=path_to_launcher_directory

launcherdir=path_to_launcher_directory

After this line is encountered, in all subsequent launcher=path_to_launcher(s) lines, if path_to_launcher(s) doesn't begin with a tilde or forward slash, it's assumed to be relative to path_to_launcher_directory.

path_to_launcher_directory follows the rules for paths referred to in menu configuration files (see above).

If path_to_launcher_directory doesn't begin with a tilde or forward slash, it's assumed to be relative to the path in which the configuration file was found (as specified on command line).

launcherdirectory= followed by no text reverts the base path for icons to the path in which the configuration file was found (as specified on command line).

There can be multiple launcherdirectory lines; each one sets the base directory for all launcher= that follow, until the next launcherdirectory= line.

Activationlogfile

activationlogfile=logfile_path

After this line is encountered and logfile_path specifies a valid file path, three things happen:

File logfile_path is created if it doesn't exist.
All parsed menu items and launchers encountered after this line and before an activationlogfile= (null path) line are flagged as "loggable".
Activating a "loggable" entry writes its attributes (item=, cmd=, icon=, tooltip= or, for launchers, "Name=", "Exec=", "Icon=", "Comment=") to the log file logfile_path.

The log file is formatted as a gtkmenuplus menu_configuration_file and can be included in other menu configuration files with include=logfile_path.

If logfile_path doesn't begin with a tilde or forward slash, it's assumed to be relative to the path in which the configuration file was found (as specified on command line).

Generally speaking the log file shouldn't be edited, although some changes are allowed within the limits explained in the project repository (see git commit message 8bd8abf, which documents log file format and application development policies).

Include

First form:

include=menu_configuration_file [parameter1 [parameter2 ...]]

Second form (explained further down):

include=path_to_directory[/file_glob] [directory_glob]

The first form inserts the contents of a menu_configuration_file into the one in which the line occurs, at the point at which it occurs.

menu_configuration_file follows the rules for paths referred to in menu configuration files (see above).

If you want the contents of a menu_configuration_file to appear in a submenu, indent the include= line as well as all the lines of the menu_configuration_file just as you would if the contents of the file were found in the including file.

Be careful not to include recursively, directly or indirectly, a menu_configuration_file in itself.

Parameters can be referred to as $1, $2, etc. anywhere in the included menu_configuration_file. See section Parameter references above for more detail.

The following rules apply as the included menu_configuration_file is processed:

Any paths (see section Paths above) beginning with a dot are taken to be relative to the directory in which the included file lives; this will of course change nothing if the including and included file are in the same directory.

If icondirectory=path_to_icon_directory and/or launcherdirectory=path_to_launcher_directory directives are in force in the including file, the path_to_icon_directory or path_to_launcher_directory remain in force within the included file.

If icondirectory=path_to_icon_directory and/or launcherdirectory=path_to_launcher_directory lines are encountered in an included file, the path_to_icon_directory or path_to_launcher_directory remain in force only within the included file; they revert to the values set in the including file once the included file is processed.

If the most recently encountered configure= line in the menu configuration file included the word formattinglocal, the effects of any format= or tooltipformat= lines that occur within the included menu configuration file will persist only until the end of that included file. Formatting then reverts to that specified by the last encountered format= and tooltipformat= lines in the including file.

This behaviour can be turned off with a configure= line containing the word formattinglocal.

Second form:

include=path_to_directory[/file_glob] [directory_glob]

path_to_directory follows the rules for paths referred to in menu configuration files.

The second form inserts a series of menu entries, one per file, including only those files to which the user has read access matching the file_glob specified (e.g. *.txt, d?t*, [a-f]*.txt). GNU fnmatch(3) extended globbing patterns can be used too.

The generated menu item name will be the file name; if chosen the command executed will be the full path to the file.

There is no recursion into subdirectories under path_to_directory unless there's a directory_glob. If one exists it's applied only to subdirectories within path_to_directory, not to the subdirectories matched further down the directory tree.

Only subdirectories containing a file matching file_glob appear in the generated menu. Subdirectories to which the user doesn't have read access are ignored.

The second form may be immediately followed by any or all of icon=, tooltip= and cmd= lines, in any order. If it is, the icon and tooltip will be applied to each of the menu entries created; if there's a command, it will be prepended to the path associated with the chosen item in the menu generated by the include= line.

Absolute Path

/path_to/file, ~/path_to/file

A line in a menu configuration file can be an absolute path to a file, beginning with a forward slash or tilde. No directive is expected or required, nor is it to be followed by icon=, tooltip= or cmd= lines.

By default, menu items generated from such lines will display the file name prefixed by its immediately containing subdirectory.

Each generated item's tooltip will display the full path to the file, as provided in the menu configuration file, before tilde expansion.

If a previously encountered configure= line includes abspathparts n, the lowest n elements of the path (the filename counts as one element) will be displayed. If n is zero, the whole path will be displayed.

The most likely use of such lines in a menu configuration file is to make it possible to generate a configuration file on the fly and pipe it into gtkmenuplus, with e.g. something like:

{ echo "configure abspathparts 3" ; find ~ -name *.conf } | gtkmenuplus -

Submenu

submenu=submenu_description

It denotes a submenu_description to show in the menu listing. See also launchersubmenu=.

It may be followed by icon= and/or tooltip= lines, which, if they are to relate to a given submenu=, must precede lines with any other directive except if=, elseif=, else or endif.

By default, (but see configure=endsubmenu, below):

The icon= and/or tooltip= must be indented using the tab character. They must be indented by one more tabs than the submenu= line, as must all menu entries in the submenu.
The first line that is not indented with the same number of tabs signals the end of this submenu.
The indentation of lines with directives like iconsize=, menupos=, icondirectory=, format=, tooltipformat=, if=, etc, don't make up part of the definition of a menu item or submenu definition, and therefore is ignored and has no effect on when a submenu ends.

Submenus can be nested up to a maximum of 5 levels. Changing this limit requires recompiling the source code: look for and change the value of MAX_SUBMENU_DEPTH.

A submenu= line marks the end of any menu item or submenu that precede it.

Configure

configure= keywords

Any of the keywords endsubmenu, noendsubmenu, icons, noicons, formattinglocal, noformattinglocal, launchernodisplay, nolaunchernodisplay, launchernullcategory, nolaunchernullcategory, launcherlistfirst, nolauncherlistfirst, errorconsoleonly , noerrorconsoleonly, abspathparts¹, menuposition¹, and iconsize¹ can occur on this line.

(¹) Don't add an equal sign after these keywords: abspathparts and iconsize must be immediately followed by whitespace, then an integer; menuposition must be followed by whitespace, then two whitespace-separated integers.

For the effects of endsubmenu/noendsubmenu, see the endsubmenu line.

For the effects of icons/noicons, see the icon= line.

For the effects of formattinglocal/noformattinglocal, see the include=menu_configuration_file line.

For the effects of launchernodisplay/nolaunchernodisplay and launchernullcategory / nolaunchernullcategory, see Launcher Exclusion Cases in section Launcher, which also applies to the launchersub= line.

For the effects of launcherlistfirst/nolauncherlistfirst see the launcher= and launchersub= lines.

For the effects of abspathparts n, see section Plain File Path.

menuposition x y has the same effect as the menuposition=x y line. Only one x y menu position, specified by either method, may occur in a menu configuration file.

iconsize n has the same effect as the iconsize=size line, overrides the effect of that line, and is overridden by any such following line.

By default when gtkmenuplus is not launched via a CLI, fatal errors are displayed in a message box. errorconsoleonly prevents such message boxes from appearing. noerrorconsoleonly reverts to the default behaviour.

Onexit

onexit=command

Shell command command is executed after the menu gets deactivated. onexit is a hook for a menu script to clean up after the menu ends.

A script can include onexit=command multiple times. Only the last command will be executed. Use onexit= to clear an established command.

If you need to run multiple shell commands, wrap them in a "sh -c" invocation. Note that command is executed regardless of a menu entry being selected, and it isn't synchronized with the execution/termination of an item or launcher.

Endsubmenu

endsubmenu

Once endsubmenu is encountered on a configure= line, indentation of lines no longer signals which menu entries belong to which submenu. Instead indentation is ignored, and everything after a submenu= line belongs to that submenu until the occurrence of an endsubmenu line. Behaviour reverts to default when noendsubmenu occurs on a subsequent configure= line.

Ignoring indentation means that leading whitespace can be used cosmetically, e.g. to mark lines within if=/elseif=/else/endif blocks (and of course to continue to clarify what belongs to which submenu).

Separator

separator

It displays a line in the menu.

A separator marks the end of any menu item or submenu preceding it.

Iconsize

iconsize=size

An optional line that changes the dimensions of the image used for succeeding menu items. There can be multiple iconsize= lines; each one sets the icon size for all menu entries that follow, until the next iconsize= line.

Size must be between 20 and 200.

Standard icons are typically 16, 24, 48 or 96 pixels square.

If no iconsize= is in force size will be 30 unless the gtk framework returns a different size.

To speed execution, all icon files associated with a menu configuration file should be of the image size specified by the most recent iconsize= line.

An iconsize= line marks the end of any menu item or submenu preceding it.

You can get the same result by putting iconsize size on a configure= line.

Menupos, Menuposition

menupos=x y

menuposition=x y

An optional line to force the menu to open at a given x-y position (the program xev can help you find coordinates - see its man page). If no menupos= is encountered, the menu is shown at the mouse cursor position. Only one menupos= is allowed per configuration file.

An menupos= line marks the end of any menu item or submenu preceding it.

You can get the same result by putting menuposition x y on a configure= line.

Icondirectory

icondirectory=path_to_icon_directory

After this line is encountered, in all subsequent icon=path_to_image_file lines, if path_to_image_file, doesn't begin with a tilde or forward slash it's assumed to be relative to path_to_icon_directory.

path_to_icon_directory follows the rules for paths referred to in menu configuration files (see above).

icondirectory= followed by no text reverts the base path for icons to the path in which the configuration file was found (as specified on command line).

There can be multiple icondirectory= lines; each one sets the icon directory for all menu entries that follow, until the next icondirectory= line.

An icondirectory= line marks the end of any menu item or submenu preceding it.

If, Elseif, Else, Endif, Fi

if=condition
elseif=condition or elif=condition
else
endif or fi

condition may be either

A reference to an argument following the menu configuration file on the command line when gtkmenuplus was called, the arguments referred to by the reference $1, $2,... etc, e.g.

if= $2 # referring to the third argument on the gtkmenuplus command line
A valid command that the shell can execute that produces a value on stdout.
A variable previously defined by a previous var= line in the menu configuration file.

In either case the value is expected to be an integer, "yes", "true", "no" or "false", all case insensitive.

If the value (either the result of command execution sent to stdout or received as a parameter) is non-zero, "true" or "yes", the menu entries following the if= up to the following else or endif will be displayed.

If that value is zero, "false" or "no" , the menu entries following the if= up to the following else or endif will not be displayed, but any after a following else line will be.

An if=/[elseif=]/[else]endif block can be embedded within another.

If if=$n or elseif=$n lines are read when there are less than n parameters on the gtkmenuplus command line, all lines from the line up to the matching elseif or endif will be processed into the menu.

If you want to test some condition requiring a call to the shell, and you want to use the same condition in various if= lines in your menu configuration file, you might be best to invoke the shell command within an argument on the command line; that way the shell needs to be invoked only once, instead of multiple times for multiple if= statements.

if=, elseif=, else and endif lines do not mark the end of any menu item or submenu preceding it. So you can have tooltip= or icon= lines apply to any of several item=s that might appear conditionally before them e.g.

if= [ `date +%H` -lt 18 ]; printf $?  # if past 18:00 hours
  item = evening game
  cmd = mahjongg
else
 item = daytime game
 cmd = mines
endif
tooltip = the item you see here depends on the time of day
icon=games_package.png

if=, elseif=, else and endif lines are scoped to each menu configuration file. If you include= a menu configuration file, an endif line must follow an if= line within that file, and won't relate to a if= line in the including file.

error=message can be used to stop menu configuration file processing, the need for which would generally be detected by if=, elseif=, else and endif lines.

Sample conditions in if=condition, elseif=condition or command line parameters:

Show menu entries following the if= line only in PM hours:

if= ! [ `date +%p` = 'PM' ]; printf $?

On the command line:

gtkmenuplus path_to_configuration_file "! [ `date +%p` = 'PM' ]; printf $?"

and then use if= $1 inside the configuration file.

The date command can be used to show menu items on certain days of week, days of the month, week of the year, etc.

Show menu entries following the if= line only if using a particular physical screen:

if= xrandr --current | grep "VGA-0 connected" | wc -l

Show menu entries following the if= line only if firefox is running:

if= xdotool search --name Firefox  | wc -l

Test if a particular memory stick is mounted:

if= ! [ -d '/media/VOL_LABEL'  ]; printf $?

Test if the partition $HOME resides on is more than 90% full:

if=  df $HOME | awk 'NR==2{split($5,A,/%/);print (A[1]+0>90)}'

BUGS

Please report defects in the Issues page of the gtkmenuplus project home.

AUTHOR

step is the current maintainer.

Acknowledgements

Thanks to John Vorthman for providing myGtkMenu code.

The idea of importing .desktop files was borrowed from popdown

Files

menu_configuration_file_format.md

Latest commit

History