.\" Generated by scdoc 1.11.3
.\" 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" "2024-05-11"
.PP
.SH NAME
.PP
labwc - menu files
.PP
.SH DESCRIPTION
.PP
Static menus are built based on content of XML files located at
"~/.\&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
<menu id="">

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

  <!-- A submenu defined elsewhere -->
  <menu id="" />

  <!-- Horizontal line >
  <separator />

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

  <!-- Pipemenu -->
  <menu id="" label="" 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
.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.\&
.PP
.RE
\fBmenu.\&item.\&label\fR
.RS 4
The visible name of the menu item.\&
.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.\&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
.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)