Help:Menus

From Openbox

(Difference between revisions)
Jump to: navigation, search
(If you have already installed openbox with a working Debian menu: update/correction of menu.xml entry)
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.
+
There are two kings of menus:
 
+
* [[#Static menus|static 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>.
+
* [[#Dynamic menus|dynamic menus]].
  
 
= Static menus =
 
= Static menus =
 +
 +
Static menus are build at Openbox startup based on content of xml files, paths to which specified in configuration file "<code>rc.xml</code>", and not changed at runtime. By default for all of the menus used 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).
  
 
== Syntax ==
 
== Syntax ==
A menu file must be entirely enclosed within <openbox_menu> tags, such as:
+
 
<code><pre>
+
A menu file must be entirely enclosed within "<code><openbox_menu></code>" and "<code></openbox_menu></code>" tags, such as:
 +
 
 +
<pre>
 
<openbox_menu>
 
<openbox_menu>
 
   ...menu stuff here...
 
   ...menu stuff here...
 
</openbox_menu>
 
</openbox_menu>
</pre></code>
+
</pre>
  
 
Inside these tags, menus are specified as follows:
 
Inside these tags, menus are specified as follows:
<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 -->
+
<menu
  <separator label="La la" />
+
  id="[[#ID|ID]]"
 +
  label="[[#TITLE|TITLE]]"
 +
  icon="[[#ICON|ICON]]"
 +
>
 +
 +
  &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>
  
  <!-- this links to a sub menu -->
+
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.
  <menu id="ID" />
+
  
  <!-- this is a small line separator -->
+
<!-- Anchor --><span id="ID"></span>
  <separator />
+
=== Value of attribute "id" ===
  
  <!-- this also links to a sub menu, which is defined inline -->
+
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.
  <menu id="ID" label="TITLE">
+
    <item label="LABEL">
+
      ACTIONS
+
    </item>
+
  </menu>
+
  
  <separator />
+
<!-- Anchor --><span id="TITLE"></span>
 +
=== Value if attribute "title" ===
  
  <item label="LABEL">
+
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.
    ACTIONS
+
 
  </item>
+
<!-- Anchor --><span id="LABEL"></span>
 +
=== Value of attribute "label" ===
 +
 
 +
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.
 +
 
 +
==== 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 "<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>".
 +
 
 +
<!-- Anchor --><span id="ICON"></span>
 +
=== Value of attribute "icon" ===
 +
 
 +
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:
 +
 
 +
<item
 +
  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 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:
 +
 
 +
<pre>
 +
<menu>
 +
  ...
 +
  <showIcons>no</showIcons>
 +
  <!-- Default value is "yes". -->
 +
  ...
 
</menu>
 
</menu>
</pre></code>
+
</pre>
  
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.
+
=== Actions ===
  
=== ID ===
+
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.
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.
+
  
=== TITLE ===
+
<!-- Anchor --><span id="Pipe_menus"></span>
The '''TITLE''' of the menu is shown when you link to the menu as a submenu.  The '''TITLE''' will appear in its parent menu.
+
= Dynamic menus =
  
=== LABEL ===
+
Dynamic menus are menus, what build at run time (on-the-fly) based on output of scripts. These are also called "pipe menus" since the script's output is piped to Openbox, and output used to build the menu. A number of scripts, used to generate dynamic menus, written by various people and available through the [[Openbox:Pipemenus|pipe menus page]].
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.
+
  
==== Specifying menu shortcuts ====
+
A dynamic menu can be created by placing the following code 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>.
+
  
=== ACTIONS ===
+
<menu
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.
+
  id="[[#ID|ID]]"
 +
  label="[[#TITLE|TITLE]]"
 +
  execute="[[#Command|COMMAND]]"
 +
/>
  
= Pipe menus =
+
Thereafter the dynamic menu can be referenced by [[#ID|ID]] just like static menu.
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>:
+
=== Command ===
<code><pre>
+
<menu id="ID" label="TITLE" execute="COMMAND" />
+
</pre></code>
+
  
Thereafter the pipe menu can be referenced just like [[#Syntax|any other menu]].
+
The '''COMMAND''' is the command to be executed by Openbox. Each time action [[Help:Actions#ShowMenu|ShowMenu]] executed Openbox will do the following steps:
 +
* run specified command;
 +
* read output of command;
 +
* parse output of command;
 +
* turned output into the menu;
 +
* show the menu on the screen.
 +
The output of the script should be a xml, something like:
  
=== COMMAND ===
+
  <openbox_pipe_menu>
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:
+
  <item
<code><pre>
+
    label="[[#LABEL|LABEL]]"
<openbox_pipe_menu>
+
    icon="[[#ICON|ICON]]"
  <item label="LABEL">
+
  >
    ACTIONS
+
    [[#Actions|ACTIONS]]
  </item>
+
  </item>
</openbox_pipe_menu>
+
</openbox_pipe_menu>
</pre></code>
+
  
When writing your own pipe menus, make sure to escape xml special characters such as &, etc...
+
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]).
  
 
= The Debian menu =
 
= 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.
 
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.
  
 
== If you have already installed openbox with a working Debian menu ==
 
== If you have already installed openbox with a working Debian menu ==
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>):
+
 
 +
Add the following line to your "<code>~/.config/openbox/menu.xml</code>" file (if it isn't there, copy it from "<code>/etc/xdg/openbox/menu.xml</code>" file):
  
 
   <menu id="/Debian" />
 
   <menu id="/Debian" />
  
You should place the line where you would like it to appear in the root menu. Location matters!
+
You should place the line, where you would like it to appear in the root menu. Location matters!
  
Add one of these lines to your <code>~/.config/openbox/rc.xml</code> between the <code><menu></code> and <code></menu></code> tags, before the entry <code><file>menu.xml</file></code> tags:
+
Add one of following lines to your "<code>~/.config/openbox/rc.xml</code>" file between the "<code><menu></code>" and "<code></menu></code>" tags, before the code "<code><file>menu.xml</file></code>":
  
    <file>/var/lib/openbox/debian-menu.xml</file>
+
  <file>/var/lib/openbox/debian-menu.xml</file>
    <file>debian-menu.xml</file>
+
  <file>debian-menu.xml</file>
  
The second line allows you to copy the debian-menu.xml file from <code>/var/lib/openbox</code> to your local <code>~/.config/openbox</code>, where it becomes static (command <code>update-menus</code> will not affect it). You can then edit it by hand and your changes will be permanent.
+
The second line allows you to copy the "<code>debian-menu.xml</code>" file from "<code>/var/lib/openbox</code>" to your local "<code>~/.config/openbox</code>" directory, where it becomes static (command <code>update-menus</code> will not affect it). You can then edit it by hand and your changes will be permanent.
  
That's all you should have to do, though it's a good idea to run <code>update-menus</code> as root every now and then if you don't have a cron job assigned. It refreshes the list of currently installed apps.
+
That's all you should have to do, though it's a good idea to run command <code>update-menus</code> (from package "<code>menu</code>") as root every now and then, if you don't have a cron job assigned. It refreshes the list of currently installed apps.
  
Then choose <code>reconfigure</code> on your root menu and you should get a Debian submenu within the root menu.
+
Then choose "<code>reconfigure</code>" on your root menu, and you should get a Debian submenu within the root menu.
  
 
== If you haven't had a working debian menu ==
 
== If you haven't had a working debian menu ==
Line 109: Line 187:
 
This is a little trickier, but no big deal.
 
This is a little trickier, but no big deal.
  
Then there's this little humdinger: you'll need to get a copy of an executable script named "openbox" and copy it to <code>/etc/menu-methods</code> (The script actually creates the Debian menu when you run "update-menus.")
+
Then there's this little humdinger: you'll need to get a copy of an executable script named "openbox" and copy it to "<code>/etc/menu-methods</code>" directory. The script actually creates the Debian menu, when you run "<code>update-menus</code>.
 +
 
 +
; Method 1
 +
 
 +
The easiest way is to install Openbox from official debian repository using "<code>apt</code>", "<code>aptitude</code>", "<code>synaptic</code>" or other program. This will normally ensure, that you have all the packages required to create and use the Debian menu.
  
Method 1:
+
After installation copy the script (from "<code>/etc/menu-methods</code>" directory) in a known directory (your home directory will fine), then uninstall the official openbox (with "<code>apt</code>", "<code>aptitude</code>", "<code>synaptic</code>" or other).
  
The easiest way is to install an official debian openbox using apt, aptitude or synaptic. This will normally ensure that you have all the packages required to create and use the Debian menu.  
+
Then, copy the script back to "<code>/etc/menu-methods</code>" directory and finally, issue the command <code>update-menus</code> as root.
  
After installation copy the script (from <code>/etc/menu-methods</code>) in a known directory (your home directory will fine), then uninstall the offical openbox (with apt, aptitude or synaptic).
+
; Method 2
  
Then, copy the script back to <code>/etc/menu-methods</code> and finally, issue the command <code>update-menus</code> as root.
+
If you don't want to do that, download an official Openbox package (.deb) from debian.org, create a dummy directory in "<code>/tmp</code>" and type the command
  
Method 2:
+
  dpkg-deb -x /path/to/official-openbox.deb < /tmp/dummy_dir
  
If you don't want to do that, download an official Openbox package (.deb) from debian.org, create a dummy directory in <code>/tmp</code> and type the command <pre>dpkg-deb -x <officialopenbox.deb> </tmp/dummy_dir></pre>
+
This will unpack a mini-filesystem, that includes the script you need, in "<code>/tmp/dummy_dir/etc/menu-methods</code>" directory. Set its execution permissions, copy the script to "<code>/etc</code>" directory and issue the command <code>update-menus</code> as root. The latter command will create the file "<code>/var/lib/openbox/debian-menu.xml</code>".
  
This will unpack a mini-filesystem that includes the script you need in <code>/tmp/dummy_dir/etc/menu-methods</code>. Set its execution permissions,  copy the script to <code>/etc</code> and issue the command <code>update-menus</code> as root. The latter command will create the file <code>/var/lib/openbox/debian-menu.xml</code>.
+
To set the execution permissions type:
  
To set the execution permissions type: <pre>chmod ug+x /tmp/dummy_dir/etc/openbox</pre>
+
  chmod ug+x /tmp/dummy_dir/etc/openbox
  
The reason to create a dummy directory is that running the <code>dpkg-deb -x</code> command will change the ownership of the directory to root. These could become a bit of a problem later; putting it in a subdirectory of /tmp makes that issue, inoffensive.
+
The reason to create a dummy directory is that running the <code>dpkg-deb -x</code> command will change the ownership of the directory to root. These could become a bit of a problem later; putting it in a subdirectory of "<code>/tmp</code>" makes that issue, inoffensive.
  
 
Also, you should make sure you have the following packages installed before running <code>update-menus</code>:
 
Also, you should make sure you have the following packages installed before running <code>update-menus</code>:
* menu
+
* menu;
* menu-xdg
+
* menu-xdg.
  
Now follow the instructions in '''"If you have already installed openbox with a working Debian menu"''' above.
+
Now follow the instructions, listed [[#If you have already installed openbox with a working Debian menu|above]].

Revision as of 06:28, 10 July 2017

There are two kings of menus:

Contents

Static menus

Static menus are build at Openbox startup based on content of xml files, paths to which specified in configuration file "rc.xml", and not changed at runtime. By default for all of the menus used file "menu.xml", located either at "~/.config/openbox" (user-specific directory) or at "/etc/xdg/openbox" (system-wide directory).

Syntax

A menu file must be entirely enclosed within "<openbox_menu>" and "</openbox_menu>" tags, such as:

<openbox_menu>
  ...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.

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.

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.

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.

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".

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>

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.

Dynamic menus

Dynamic menus are menus, what build at run time (on-the-fly) based on output of scripts. These are also called "pipe menus" since the script's output is piped to Openbox, and output used to build the menu. A number of scripts, used to generate dynamic menus, written by various people and available through the pipe menus page.

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

<menu
  id="ID"
  label="TITLE"
  execute="COMMAND"
/>

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

Command

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

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

The output of the script should be a 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).

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.

If you have already installed openbox with a working Debian menu

Add the following line to your "~/.config/openbox/menu.xml" file (if it isn't there, copy it from "/etc/xdg/openbox/menu.xml" file):

 <menu id="/Debian" />

You should place the line, where you would like it to appear in the root menu. Location matters!

Add one of following lines to your "~/.config/openbox/rc.xml" file between the "<menu>" and "</menu>" tags, before the code "<file>menu.xml</file>":

 <file>/var/lib/openbox/debian-menu.xml</file>
 <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" directory, where it becomes static (command update-menus will not affect it). You can then edit it by hand and your changes will be permanent.

That's all you should have to do, though it's a good idea to run command update-menus (from package "menu") as root every now and then, if you don't have a cron job assigned. It refreshes the list of currently installed apps.

Then choose "reconfigure" on your root menu, and you should get a Debian submenu within the root menu.

If you haven't had a working debian menu

This is a little trickier, but no big deal.

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" directory. The script actually creates the Debian menu, when you run "update-menus.

Method 1

The easiest way is to install Openbox from official debian repository using "apt", "aptitude", "synaptic" or other program. This will normally ensure, that you have all the packages required to create and use the Debian menu.

After installation copy the script (from "/etc/menu-methods" directory) in a known directory (your home directory will fine), then uninstall the official openbox (with "apt", "aptitude", "synaptic" or other).

Then, copy the script back to "/etc/menu-methods" directory and finally, issue the command update-menus as root.

Method 2

If you don't want to do that, download an official Openbox package (.deb) from debian.org, create a dummy directory in "/tmp" and type the command

 dpkg-deb -x /path/to/official-openbox.deb < /tmp/dummy_dir

This will unpack a mini-filesystem, that includes the script you need, in "/tmp/dummy_dir/etc/menu-methods" directory. Set its execution permissions, copy the script to "/etc" directory and issue the command update-menus as root. The latter command will create the file "/var/lib/openbox/debian-menu.xml".

To set the execution permissions type:

 chmod ug+x /tmp/dummy_dir/etc/openbox

The reason to create a dummy directory is that running the dpkg-deb -x command will change the ownership of the directory to root. These could become a bit of a problem later; putting it in a subdirectory of "/tmp" makes that issue, inoffensive.

Also, you should make sure you have the following packages installed before running update-menus:

  • menu;
  • menu-xdg.

Now follow the instructions, listed above.

Personal tools