labwc-menu(5)

File Formats Manual

labwc-menu(5)

NAME

labwc - menu file

DESCRIPTION

Static menus are built based on the menu.xml file located at "~/.config/labwc" and equivalent XDG Base Directories.

SYNTAX

The menu file must be entirely enclosed within and tags. Inside these tags, menus are specified as follows:



  
    
  



  
  
    
  
  
  
  
  
  
  
    ...some content...

menu.id (when at toplevel)

Define a menu tree. Each menu must be given an id, which is a unique identifier of the menu. This id is used to refer to the menu in a ShowMenu action. Default identifiers are

"root-menu" for the root window context menu
"client-menu" for a window's titlebar context menu
"client-list-combined-menu" for a list of all windows across all workspaces. Will change focus to the app that gets selected or go to workspace without activating any app if "Go there" is selected.
"client-send-to-menu" shows all workspaces and sends current window to that workspace when selected.

menu.id (when nested under other

element)

Link to a submenu defined elsewhere (by a at toplevel).

menu.label

The title of the menu, shown in its parent. A label must be given when defining a menu unless it is the topmost menu element.

Note that Openbox requires a label="" defined for topmost elements too, but for simplicity labwc handles these with or without the label attribute.

menu.icon

An icon to be rendered, shown in its parent. This argument is optional. See menu.item.icon for further details.

menu.item.label

The visible name of the menu item.

menu.item.icon

The name of an icon to be rendered in front of the menu entry. This attribute is optional. The name follows naming conventions of "Icon=" entries in .desktop files. If used, it is recommended to use the name of the icon only rather than a full path. This ensures that the icon will be looked up in the scale of the output where the menu is rendered. E.g. use of icon="vlc" is suggested over using icon="/usr/share/icons/hicolor/16x16/apps/vlc.png".

menu.item.action

See labwc-actions(5). Note: XML CDATA is supported for this node in order to maintain compatibility with obmenu-generator.

menu.separator

Horizontal line.

menu.separator.label

In a "separator" element, the label attribute transforms the separator from a horizontal line to a menu title (heading) with the text specified by label in it.

menu.execute

Command to execute for pipe menu. See details below.

PIPE MENUS

Pipe menus are menus generated dynamically based on output of scripts or binaries. They are so-called because the output of the executable is piped to the labwc menu.

For any

entry in menu.xml, the COMMAND will be executed the first time the item is selected (for example by cursor or keyboard input). The XML output of the command will be parsed and shown as a submenu. The content of pipemenus is cached until the whole menu (not just the pipemenu) is closed.

The content of the output must be entirely enclosed within tags. Inside these, menus are specified in the same way as static (normal) menus, for example:

Inline submenus and nested pipemenus are supported.

Note that it is the responsibility of the pipemenu executable to ensure that ID attributes are unique. Duplicates are ignored.

When writing pipe menu scripts, make sure to escape XML special characters such as "&" ("&"), "<" ("<"), and ">" (">").

A pipemenu can also be used to define the toplevel

element. In this case the entire menu.xml file would be reduced to something like this (replacing obmenu-generator with the menu generator of your choice):

ACCELERATORS / MNEMONICS

Menu accelerators are one-letter mnemonics to quickly select/exec items from the current menu. For each menu item, the accelerator is defined as the first character of the item label, converted to lowercase. A different accelerator can be explicitly defined in menu.xml with the special '_' character before the target letter. Accelerators can be any unicode character and are not limited to ASCII. A usual underscore can be shown by duplicating it.

If the menu only contains a single instance of the pressed accelerator the item will be executed directly. Otherwise, all matching items are cycled through.

Example: The accelerator for an item with the label "e_Macs" is 'm'.

LOCALISATION

Available localisation for the default "client-menu" is only shown if no "client-menu" is present in menu.xml. Any menu definition in menu.xml is interpreted as a user-override.