.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "labwc-menu" "5" "2025-12-20"
.PP
.SH NAME
.PP
labwc - menu file
.PP
.SH DESCRIPTION
.PP
Static menus are built based on the menu.\&xml file located at
"\(ti/.\&config/labwc" and equivalent XDG Base Directories.\&
.PP
.SH SYNTAX
.PP
The menu file must be entirely enclosed within <openbox_menu> and
</openbox_menu> tags.\&  Inside these tags, menus are specified as follows:
.PP
.nf
.RS 4
<!-- A toplevel menu -->
<menu id="external_menu_settings" label="External Settings" icon="preferences-other">
  <item label="Display setting">
    <action name="Execute" command="wdisplays" />
  </item>
</menu>

<!-- Another toplevel menu -->
<menu id="">

  <!-- A menu entry with an action, for example to execute an application -->
  <item label="" icon="">
    <action></action>
  </item>

  <!-- A submenu defined elsewhere, uses external label and icon attributes -->
  <menu id="external_menu_settings" />

  <!-- Horizontal line -->
  <separator />

  <!-- An inline submenu -->
  <menu id="" label="" icon="">
    \&.\&.\&.some content\&.\&.\&.
  </menu>

  <!-- Title -->
  <separator label="" />

  <!-- Pipemenu -->
  <menu id="" label="" icon="" execute="COMMAND" />

</menu>
.fi
.RE
.PP
\fBmenu.\&id\fR (when at toplevel)
.RS 4
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
.RS 4
.PD 0
.IP \(bu 4
"root-menu" for the root window context menu
.IP \(bu 4
"client-menu" for a window'\&s titlebar context menu
.IP \(bu 4
"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.\&
.IP \(bu 4
"client-send-to-menu" shows all workspaces and sends current
window to that workspace when selected.\&
.PD
.PP
.RE
.RE
\fBmenu.\&id\fR (when nested under other \fB<menu>\fR element)
.RS 4
Link to a submenu defined elsewhere (by a \fB<menu id="">\fR at toplevel).\&
.PP
.RE
\fBmenu.\&label\fR
.RS 4
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.\&
.PP
Note that Openbox requires a label="" defined for topmost elements too,
but for simplicity labwc handles these with or without the label
attribute.\&
.PP
.RE
\fBmenu.\&icon\fR
.RS 4
An icon to be rendered, shown in its parent.\& This argument is optional.\&
See \fBmenu.\&item.\&icon\fR for further details.\&
.PP
.RE
\fBmenu.\&item.\&label\fR
.RS 4
The visible name of the menu item.\&
.PP
.RE
\fBmenu.\&item.\&icon\fR
.RS 4
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".\&
.PP
.RE
\fBmenu.\&item.\&action\fR
.RS 4
See labwc-actions(5).\& Note: XML CDATA is supported for this node in
order to maintain compatibility with obmenu-generator.\&
.PP
.RE
\fBmenu.\&separator\fR
.RS 4
Horizontal line.\&
.PP
.RE
\fBmenu.\&separator.\&label\fR
.RS 4
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.\&
.PP
.RE
\fBmenu.\&execute\fR
.RS 4
Command to execute for pipe menu.\& See details below.\&
.PP
.RE
.SH PIPE MENUS
.PP
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.\&
.PP
For any \fB<menu id="" label="" execute="COMMAND"/>\fR 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.\&
.PP
The content of the output must be entirely enclosed within \fB<openbox_pipe_menu>\fR
tags.\& Inside these, menus are specified in the same way as static (normal)
menus, for example:
.PP
.nf
.RS 4
<openbox_pipe_menu>
  <item label="Terminal">
    <action name="Execute" command="xterm"/>
  </item>
</openbox_pipe_menu>
.fi
.RE
.PP
Inline submenus and nested pipemenus are supported.\&
.PP
Note that it is the responsibility of the pipemenu executable to ensure that
ID attributes are unique.\& Duplicates are ignored.\&
.PP
When writing pipe menu scripts, make sure to escape XML special characters such
as "&" ("&amp;"), "<" ("&lt;"), and ">" ("&gt;").\&
.PP
A pipemenu can also be used to define the toplevel \fB<menu>\fR 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):
.PP
.nf
.RS 4
<?xml version="1\&.0"?>
<openbox_menu>
  <menu id="root-menu" label="" execute="obmenu-generator"/>
</openbox_menu>
.fi
.RE
.PP
.SH LOCALISATION
.PP
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.\&
.PP
.SH SEE ALSO
.PP
labwc(1), labwc-actions(5), labwc-config(5), labwc-theme(5)