Help:Menus

From Openbox

(Difference between revisions)
Jump to: navigation, search
(If you have already installed openbox with a working Debian menu)
 
(24 intermediate revisions by 8 users not shown)
Line 1: Line 1:
Menus are not read out of the <code>rc.xml</code> configuration file, but rather out of files specified in the <code>rc.xml</code>. In the default configuration, the <code>menu.xml</code> file is used for all of the menus.
+
[[File:Screenshot of menu of openbox 3.6.1 with "Bear2" theme.png|thumb|200px|Example of openbox menu]]
 +
With regard to Openbox menus, there are two types: ''[[#Static menus|static menus]]'', and ''[[#Pipe menus|dynamic or "pipe menus"]]''.
  
The <code>menu.xml</code> file is located in <code>~/.config/openbox/menu.xml</code> or in the system-wide <code>/etc/xdg/openbox/menu.xml</code>.
+
Both can be configured to extend the functionality of an Openbox installation. While static menus are built from XML files, pipe menus are written in various scripting/programming languages and can be used to provide dynamic menu content like weather, recently accessed files and RSS feeds. Pipe menus can even be combined with command-line ui toolkit utilities like zenity or kdialog to completely replicate the functionality of system tray applets like nm-applet.
  
= Static menus =
+
Menus can further be bound to keybindings to enable the use of multiple menus in an Openbox installation. The only real constraint on your desktop experience is your scripting ability.
 +
== Static menus ==
  
== Syntax ==
+
Static menus are built based on content of XML files, paths to which specified in configuration file "<code>rc.xml</code>". The default menu file, "<code>menu.xml</code>", located either at "<code>~/.config/openbox</code>" (user-specific directory) or at "<code>/etc/xdg/openbox</code>" (system-wide directory) is static by default.
A menu file must be entirely enclosed within <openbox_menu> tags, such as:
+
<code><pre>
+
<openbox_menu>
+
  ...menu stuff here...
+
</openbox_menu>
+
</pre></code>
+
  
Inside these tags, menus are specified as follows:
+
=== Syntax ===
<code><pre>
+
<menu id="ID" label="TITLE">
+
  <!-- this is a menu item, such as a program -->
+
  <item label="LABEL">
+
    ACTIONS
+
  </item>
+
  
  <!-- this is a menu header -->
+
A menu file must be entirely enclosed within "<code><openbox_menu></code>" and "<code></openbox_menu></code>" tags, as well as the appropriate XML declaration like so:
  <separator label="La la" />
+
  
  <!-- this links to a sub menu -->
+
<?xml version="1.0" encoding="utf-8"?>
  <menu id="ID" />
+
<openbox_menu xmlns="http://openbox.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://openbox.org/ file:///usr/share/openbox/menu.xsd">
 +
  ...menu stuff here...
 +
</openbox_menu>
  
  <!-- this is a small line separator -->
+
Inside these tags, menus are specified as follows:
  <separator />
+
  
  <!-- this also links to a sub menu, which is defined inline -->
+
<menu
  <menu id="ID" label="TITLE">
+
  id="[[#ID|ID]]"
    <item label="LABEL">
+
  label="[[#TITLE|TITLE]]"
      ACTIONS
+
  icon="[[#ICON|ICON]]"
    </item>
+
>
  </menu>
+
 +
  &lt;!-- this is a menu item, such as a program -->
 +
  <item
 +
    label="[[#LABEL|LABEL]]"
 +
    icon="[[#ICON|ICON]]"
 +
  >
 +
    [[#Actions|ACTIONS]]
 +
  </item>
 +
 +
  &lt;!-- this is a menu header -->
 +
  <separator
 +
    label="Header"
 +
  />
 +
 +
  &lt;!-- this links to a sub menu -->
 +
  <menu
 +
    id="[[#ID|ID]]"
 +
  />
 +
 +
  &lt;!-- this is a horizontal line -->
 +
  <separator />
 +
 +
  &lt;!-- this also links to a sub menu, which is defined inline -->
 +
  <menu
 +
    id="[[#ID|ID]]"
 +
    label="[[#TITLE|TITLE]]"
 +
    icon="[[#ICON|ICON]]"
 +
  >
 +
    <item
 +
      label="[[#LABEL|LABEL]]"
 +
      icon="[[#ICON|ICON]]"
 +
    >
 +
      [[#Actions|ACTIONS]]
 +
    </item>
 +
  </menu>
 +
 +
  <separator />
 +
 +
  &lt;!-- this is a menu item -->
 +
  <item
 +
    label="[[#LABEL|LABEL]]"
 +
    icon="[[#ICON|ICON]]"
 +
  >
 +
    [[#Actions|ACTIONS]]
 +
  </item>
 +
 +
</menu>
  
  <separator />
+
The example above shows how to put entries into a menu (with "<code><item></code>" and "<code></item></code>" tags), and two methods to add submenus to a menu (with "<code><menu></code>" and "<code></menu></code>" tags). It also shows how to put menu headers and separators (with "<code><separator /></code>" tag) into the menu to group items together without submenus.
  
  <item label="LABEL">
+
<!-- Anchor --><span id="ID"></span>
    ACTIONS
+
==== Value of attribute "id" ====
  </item>
+
</menu>
+
</pre></code>
+
  
The syntax example above shows how to put entries into a menu (with <item>), and two methods to add submenus to a menu (with <menu>). It also shows how to put menu headers and separators (with <separator>) into the menu to group items together without submenus.
+
Each menu must be given an '''<code>id</code>''', which is a unique identifier of the menu. This '''<code>id</code>''' is used to refer to the menu in a [[Help:Actions#ShowMenu|ShowMenu]] action.
  
=== ID ===
+
<!-- Anchor --><span id="TITLE"></span>
Each menu must be given an '''ID''' which is a unique identifier for the menu.  This '''ID''' is used to refer to the menu in a [[Help:Actions#ShowMenu|ShowMenu]] action.
+
==== Value if attribute "title" ====
  
=== TITLE ===
+
The value of attribute '''<code>title</code>''' of the menu is shown, when you link to the menu as a submenu. The '''<code>title</code>''' will appear in its parent menu.
The '''TITLE''' of the menu is shown when you link to the menu as a submenu. The '''TITLE''' will appear in its parent menu.
+
  
=== LABEL ===
+
<!-- Anchor --><span id="LABEL"></span>
The '''LABEL''' in an <item> tag is the visible name of the menu item.  In the <separator> tag, the '''LABEL''' transforms the separator from a small horizontal line to a menu header with the given text in it.
+
==== Value of attribute "label" ====
  
=== ACTIONS ===
+
The value of attribute '''<code>label</code>''' of an "<code>item</code>" element is the visible name of the menu item. In the "<code>separator</code>" element, the '''<code>label</code>''' attribute transforms the separator from a small horizontal line to a menu header with the given text in it.
The '''ACTIONS''' are 0 or more [[Help:Actions#Action_syntax|actions]] which are executed in order when you select the menu item. Typically, in menus, these are [[Help:Actions#Execute|Execute actions]], which run commands.
+
  
= Pipe menus =
+
===== Specifying menu shortcuts =====
Pipe menus are dynamic menus, built on-the-fly from scripts.  These are referred to as "Pipe menus" since the script's output is piped back to Openbox and used for the menu.  There are a number of pipe menus written by various people available through the [[Openbox:Pipemenus|Pipe menus page]].
+
  
A pipe menu can be created by placing the following into a menu file, such as <code>menu.xml</code>:
+
The first character in the label is used for a keyboard shortcut to directly use the menu item. This can be overridden by using the "<code>_</code>" character in front of the character, you wish to use for the shortcut. For example, "<code>The _shortcut</code>" would make "<code>s</code>" the shortcut key for this menu item. If you want a "<code>_</code>" character to appear in the string, you can use two underscores together, such as in "<code>An __ underscore</code>".
<code><pre>
+
<menu id="ID" label="TITLE" execute="COMMAND" />
+
</pre></code>
+
  
Thereafter the pipe menu can be referenced just like [[#Syntax|any other menu]].
+
<!-- Anchor --><span id="ICON"></span>
 +
==== Value of attribute "icon" ====
  
=== COMMAND ===
+
The value of attribute '''<code>icon</code>''' is path to the image file. Image will be drawn left of menu item label or submenu label. Supported formats of images is the same, as formats, supported by libraries "[https://docs.enlightenment.org/api/imlib2/html/ Imlib2]" (xpm, gif, jpeg, png) and "[https://github.com/GNOME/librsvg librsvg]" (svg). Example:
The '''COMMAND''' is the script to be executed, which will create the pipe menu for Openbox. The output from this command is parsed and turned into the menu.  The output from the script should be a menu, something like:
+
<code><pre>
+
<openbox_pipe_menu>
+
  <item label="LABEL">
+
    ACTIONS
+
  </item>
+
</openbox_pipe_menu>
+
</pre></code>
+
  
= The Debian menu =
+
<item
Source installs or prepackaged .debs from openbox.org will not configure your setup to show the Debian menu. There are a few simple steps to get it working.
+
  label="Vim"
 +
  icon="/usr/share/pixmaps/vim-32.xpm"
 +
>
 +
  <action
 +
    name="[[Help:Actions#Execute|Execute]]"
 +
  >
 +
    <execute>x-terminal-emulator -T Vim -e vim</execute>
 +
  </action>
 +
</item>
  
== If you have already installed openbox with a working Debian menu ==
+
If user doesn't want to display icons in menus, he/she can disable icons inside "<code>menu</code>" element in "<code>rc.xml</code>" file:
Add this line to your <code>~/.config/openbox/menu.xml</code> (if it isn't there, copy it from <code/etc/xdg/openbox/menu.xml</code>):
+
  
  <menu id="Debian" />
+
<pre>
 +
<menu>
 +
  ...
 +
  <showIcons>no</showIcons>
 +
  <!-- Default value is "yes". -->
 +
  ...
 +
</menu>
 +
</pre>
  
You should place the line where you would like it to appear in the root menu. Location matters! Also, it
+
==== Actions ====
  
Add these lines to your <code>~/.config/openbox/rc.xml</code> between the <menu> and </menu>, before the entry <code><file>menu.xml</file></code> tags:
+
The '''ACTIONS''' are zero or more [[Help:Actions#Action_syntax|actions]], which are executed in order, when you select the menu item. Typically, in menus, these are [[Help:Actions#Execute|Execute]] actions, which run commands.
  
    <file>/var/lib/openbox/debian-menu.xml</file>
+
<!-- Anchor --><span id="Pipe_menus"></span>
    <file>debian-menu.xml</file>
+
  
The second line allows you to copy the debian-menu.xml file from /var/lib/openbox to your local ~/.config/openbox, where it becomes static (update-menus will not affect it). You can then edit it by hand and your changes will be permanent.
+
== Pipe menus ==
  
That's all you should have to do, though it's a good idea to run update-menus as root every now and then if you don't have a cron job assigned. It refreshes the list of currently installed apps.
+
Pipe menus are menus generated dynamically based on output of scripts, they are so-called since the script's output is piped to the given Openbox menu. A number of scripts used to generate pipe menus are available through the [[Openbox:Pipemenus|pipe menus page]].
  
Then choose "reconfigure" on your root menu and you should get a Debian menu.
+
A pipe menu can be created by placing the following code into a menu file, such as "<code>menu.xml</code>":
  
== If you haven't had a working debian menu ==
+
<?xml version="1.0" encoding="utf-8"?>
 +
<openbox_menu xmlns="http://openbox.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://openbox.org/ file:///usr/share/openbox/menu.xsd">
 +
  ...menu stuff here...
 +
  <menu
 +
    id="[[#ID|ID]]"
 +
    label="[[#TITLE|TITLE]]"
 +
    execute="[[#Command|COMMAND]]"
 +
  />
 +
</openbox_menu>
  
This is a little trickier, but no big deal. First do all the steps listed above.
+
Thereafter the pipe menu can be referenced by [[#ID|ID]] just like static menu.
  
Then there's this little humdinger: you'll need to get a copy of an executable script named "openbox" and copy it to /etc/menu-methods. (The script actually creates the Debian menu when you run "update-menus.")
+
=== Command ===
  
The easiest way is to install an official debian openbox. This will normally ensure that you have all the packages required to create and use the Debian menu.  
+
The '''COMMAND''' is the command to be executed by Openbox. Each time action [[Help:Actions#ShowMenu|ShowMenu]] is executed Openbox will do the following steps:
 +
* run specified command;
 +
* read output of command;
 +
* show the menu on the screen.
  
After installation you can copy that file, then let it get uninstalled by dpkg when you put in the openbox.org deb file. If you're installing from source, you can just "aptitude remove" the official deb and proceed as normal.
+
The stdout (output) of the script should be XML, something like:
  
If you don't want to do that, download an official .deb and type the command dpkg-deb -x <officialopenbox.deb> <directory you want it in, usually . >  
+
<openbox_pipe_menu>
 +
  <item
 +
    label="[[#LABEL|LABEL]]"
 +
    icon="[[#ICON|ICON]]"
 +
  >
 +
    [[#Actions|ACTIONS]]
 +
  </item>
 +
</openbox_pipe_menu>
  
This will unpack a mini-filesystem that includes the script you need in localdir/etc/menu-methods. Copy that script to the real /etc/menu-methods and issue the command "update-menus" as root.  
+
When writing your own scripts, make sure to escape xml special characters, such as "&amp;" ("<code>&amp;amp;</code>"), "&lt;" ("<code>&amp;lt;</code>"), "&gt;" ("<code>&amp;gt;</code>") and other (see more on [https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references Wikipedia]).
  
If you did not install an official openbox .deb, you should make sure you have the following packages installed:
+
= The Debian menu =
* menu
+
* menu-xdg
+
  
As above, choose reconfigure from your root menu and at that point, you should have a brand new Debian menu.
+
Source installs or prepackaged .debs from openbox.org will not configure your setup to show the Debian menu. There are a few [[Help:Menus/Debian-menu|simple steps]] to get it working.

Latest revision as of 23:19, 28 February 2018

(thumbnail)
Example of openbox menu

With regard to Openbox menus, there are two types: static menus, and dynamic or "pipe menus".

Both can be configured to extend the functionality of an Openbox installation. While static menus are built from XML files, pipe menus are written in various scripting/programming languages and can be used to provide dynamic menu content like weather, recently accessed files and RSS feeds. Pipe menus can even be combined with command-line ui toolkit utilities like zenity or kdialog to completely replicate the functionality of system tray applets like nm-applet.

Menus can further be bound to keybindings to enable the use of multiple menus in an Openbox installation. The only real constraint on your desktop experience is your scripting ability.

Contents

[edit] Static menus

Static menus are built based on content of XML files, paths to which specified in configuration file "rc.xml". The default menu file, "menu.xml", located either at "~/.config/openbox" (user-specific directory) or at "/etc/xdg/openbox" (system-wide directory) is static by default.

[edit] Syntax

A menu file must be entirely enclosed within "<openbox_menu>" and "</openbox_menu>" tags, as well as the appropriate XML declaration like so:

<?xml version="1.0" encoding="utf-8"?>
<openbox_menu xmlns="http://openbox.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://openbox.org/ file:///usr/share/openbox/menu.xsd">
  ...menu stuff here...
</openbox_menu>

Inside these tags, menus are specified as follows:

<menu
  id="ID"
  label="TITLE"
  icon="ICON"
>

  <!-- this is a menu item, such as a program -->
  <item
    label="LABEL"
    icon="ICON"
  >
    ACTIONS
  </item>

  <!-- this is a menu header -->
  <separator
    label="Header"
  />

  <!-- this links to a sub menu -->
  <menu
    id="ID"
  />

  <!-- this is a horizontal line -->
  <separator />

  <!-- this also links to a sub menu, which is defined inline -->
  <menu
    id="ID"
    label="TITLE"
    icon="ICON"
  >
    <item
      label="LABEL"
      icon="ICON"
    >
      ACTIONS
    </item>
  </menu>

  <separator />

  <!-- this is a menu item -->
  <item
    label="LABEL"
    icon="ICON"
  >
    ACTIONS
  </item>

</menu>

The example above shows how to put entries into a menu (with "<item>" and "</item>" tags), and two methods to add submenus to a menu (with "<menu>" and "</menu>" tags). It also shows how to put menu headers and separators (with "<separator />" tag) into the menu to group items together without submenus.

[edit] Value of attribute "id"

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.

[edit] Value if attribute "title"

The value of attribute title of the menu is shown, when you link to the menu as a submenu. The title will appear in its parent menu.

[edit] Value of attribute "label"

The value of attribute label of an "item" element is the visible name of the menu item. In the "separator" element, the label attribute transforms the separator from a small horizontal line to a menu header with the given text in it.

[edit] Specifying menu shortcuts

The first character in the label is used for a keyboard shortcut to directly use the menu item. This can be overridden by using the "_" character in front of the character, you wish to use for the shortcut. For example, "The _shortcut" would make "s" the shortcut key for this menu item. If you want a "_" character to appear in the string, you can use two underscores together, such as in "An __ underscore".

[edit] Value of attribute "icon"

The value of attribute icon is path to the image file. Image will be drawn left of menu item label or submenu label. Supported formats of images is the same, as formats, supported by libraries "Imlib2" (xpm, gif, jpeg, png) and "librsvg" (svg). Example:

<item
  label="Vim"
  icon="/usr/share/pixmaps/vim-32.xpm"
>
  <action
    name="Execute"
  >
    <execute>x-terminal-emulator -T Vim -e vim</execute>
  </action>
</item>

If user doesn't want to display icons in menus, he/she can disable icons inside "menu" element in "rc.xml" file:

<menu>
  ...
  <showIcons>no</showIcons>
  <!-- Default value is "yes". -->
  ...
</menu>

[edit] Actions

The ACTIONS are zero or more actions, which are executed in order, when you select the menu item. Typically, in menus, these are Execute actions, which run commands.

[edit] Pipe menus

Pipe menus are menus generated dynamically based on output of scripts, they are so-called since the script's output is piped to the given Openbox menu. A number of scripts used to generate pipe menus are available through the pipe menus page.

A pipe menu can be created by placing the following code into a menu file, such as "menu.xml":

<?xml version="1.0" encoding="utf-8"?>
<openbox_menu xmlns="http://openbox.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://openbox.org/ file:///usr/share/openbox/menu.xsd">
 ...menu stuff here...
 <menu
   id="ID"
   label="TITLE"
   execute="COMMAND"
 />
</openbox_menu>

Thereafter the pipe menu can be referenced by ID just like static menu.

[edit] Command

The COMMAND is the command to be executed by Openbox. Each time action ShowMenu is executed Openbox will do the following steps:

  • run specified command;
  • read output of command;
  • show the menu on the screen.

The stdout (output) of the script should be XML, something like:

<openbox_pipe_menu>
  <item
    label="LABEL"
    icon="ICON"
  >
    ACTIONS
  </item>
</openbox_pipe_menu>

When writing your own scripts, make sure to escape xml special characters, such as "&" ("&amp;"), "<" ("&lt;"), ">" ("&gt;") and other (see more on Wikipedia).

[edit] The Debian menu

Source installs or prepackaged .debs from openbox.org will not configure your setup to show the Debian menu. There are a few simple steps to get it working.

Personal tools