Difference between revisions of "Openbox"

From ArchWiki
Jump to: navigation, search
m (Switching between keyboard layouts: fixed link)
(fixed section fragments (interactive))
(Tag: wiki-scripts)
 
(422 intermediate revisions by 64 users not shown)
Line 2: Line 2:
 
[[cs:Openbox]]
 
[[cs:Openbox]]
 
[[de:Openbox]]
 
[[de:Openbox]]
 +
[[el:Openbox]]
 
[[es:Openbox]]
 
[[es:Openbox]]
 
[[fr:Openbox]]
 
[[fr:Openbox]]
Line 13: Line 14:
 
[[sk:Openbox]]
 
[[sk:Openbox]]
 
[[sr:Openbox]]
 
[[sr:Openbox]]
[[tr:Openbox]]
+
[[zh-hans:Openbox]]
[[zh-CN:Openbox]]
+
[[zh-hant:Openbox]]
[[zh-TW:Openbox]]
+
{{Related articles start}}
{{Article summary start}}
+
{{Related|Desktop environment}}
{{Article summary text|A comprehensive guide on the installation and use of the Openbox window manager.}}
+
{{Related|Display manager}}
{{Article summary heading|Overview}}
+
{{Related|File manager functionality}}
{{Article summary text|{{Graphical user interface overview}}}}
+
{{Related|Xdg-menu}}
{{Article summary end}}
+
{{Related|Oblogout}}
Openbox is a lightweight and highly configurable [[Window Manager|window manager]] with extensive standards support. Its features are documented at the [http://openbox.org/ official website]. This article pertains to installing Openbox under Arch Linux.
+
{{Related articles end}}
 +
 
 +
[http://openbox.org/wiki/Main_Page Openbox] is a lightweight, powerful, and highly configurable ''stacking'' [[window manager]] with extensive standards support. It may be built upon and run independently as the basis of a unique [[desktop environment]], or within other integrated desktop environments such as [[KDE]] and [[Xfce]], as an alternative to the window managers they provide. The [[LXDE]] desktop environment is itself built around Openbox.
  
 
== Installation ==
 
== Installation ==
  
Install {{Pkg|openbox}}, available in the [[official repositories]]. After installation, you should copy the default configuration files {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}} to {{ic|~/.config/openbox}}:
+
[[Install]] the {{Pkg|openbox}} package.
 +
 
 +
== Starting ==
 +
 
 +
=== Standalone ===
 +
 
 +
Run {{ic|openbox}} or {{ic|openbox-session}} with [[xinit]]. Note that only {{ic|openbox-session}} provides [[#Autostart]].
 +
 
 +
{{Note|After executing openbox-session, there is only a blank grey screen. Try to move your mouse and '''right click''' to get an openbox menu to make sure that it is actually working.}}
 +
 
 +
=== Other desktop environments ===
 +
 
 +
{{Note|
 +
* When replacing the native window manager of a [[desktop environment]] with Openbox, keep in mind that Openbox does not provide any compositing effects (such as transparency). See [[#Compositing effects]].
 +
* Openbox does work with GNOME applications (but see [[GTK+#Client-side decorations]]). [http://comments.gmane.org/gmane.comp.window-managers.openbox/6595]}}
 +
 
 +
See [[Desktop environment#Use a different window manager]].
 +
 
 +
== Configuration==
 +
 
 +
{{Note|Local configuration files will always override global equivalents.}}
 +
 
 +
Four key files form the basis of the [http://openbox.org/wiki/Configuration openbox configuration], each serving a unique role. They are: {{ic|rc.xml}}, {{ic|menu.xml}}, {{ic|autostart}}, and {{ic|environment}}. Although these files are discussed in more detail below, to start configuring Openbox,  it will first be necessary to create a '''local''' Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the '''global''' {{ic|/etc/xdg/openbox}} profile (applicable to any and all users) as a template:
 +
 
 +
$ cp -R /etc/xdg/openbox ~/.config/
  
{{Note|Do this as a regular user, not as root.}}
+
=== rc.xml ===
  
$ mkdir -p ~/.config/openbox
+
{{Tip|Custom keyboard shortcuts (keybindings) must be added to the {{ic|<keyboard>}} section of this file, and underneath the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading.}}
$ cp /etc/xdg/openbox/{rc.xml,menu.xml,autostart,environment} ~/.config/openbox
 
  
These four files form the basis of your openbox configuration.  Each file addresses a unique aspect of your configuration and the role of each file is as follows:
+
{{ic|~/.config/openbox/rc.xml}} is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:
  
; {{ic|rc.xml}}: This is the main configuration file. It defines keyboard shortcuts, themes, virtual desktops, and more.
+
* Keyboard shortcuts (e.g. starting applications; controlling the volume)
 +
* Theming
 +
* Desktop and Virtual desktop settings, and
 +
* Application Window settings
  
;{{ic|menu.xml}}: This file defines the content of the right-click menu. It defines launchers for applications and other shortcuts. See the [[#Menus]] section.
+
This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.
  
;{{ic|autostart}}: This file is read by openbox-session at startup. It contains the programs that are run at startup. It is typically used to set environment variables, launch panels/docks, set background image or execute other startup scripts. See the [http://openbox.org/wiki/Help:Autostart Openbox Wiki].
+
{{Note|Per-application settings pertaining to fixed placement of applications per monitor will only work if the x & y position have also been defined.}}
  
;{{ic|environment}}: This file is sourced by openbox-session at startup. It contains environment variables to be set in Openbox's context. Any variables you set here will be visible to Openbox itself and anything you start from its menus.
+
=== menu.xml ===
  
== Upgrading to Openbox 3.5 ==
+
{{ic|~/.config/openbox/menu.xml}} defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a '''static menu''' (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of '''dynamic menus''' that will automatically update as well.  
  
If you are upgrading to Openbox 3.5 or later from an earlier release, be aware of these changes:
+
The available options are discussed extensively below in the [[#Menus]] section.
  
* There is a new config file called {{ic|environment}} that you should copy from {{ic|/etc/xdg/openbox}} to {{ic|~/.config/openbox}}.
+
=== Autostart ===
* The config file previously called {{ic|autostart.sh}} is now just called {{ic|autostart}}. You should rename yours to remove the {{ic|.sh}} from the end of the name.
 
* Some of the configuration grammar in {{ic|rc.xml}} has changed. While Openbox appears to understand the old options, it would be wise to compare your configuration to the one in {{ic|/etc/xdg/openbox}} and look for changes that affect you.
 
  
== Openbox as a stand-alone WM ==
+
{{ic|openbox-session}} provides two autostart mechanisms: [[XDG Autostart]] (which only works if {{Pkg|python2-xdg}} is installed) and [http://openbox.org/wiki/Help:Autostart Openbox's own autostart mechanism].
  
Openbox can be used as a stand-alone window manager (WM). This is usually simpler to install and configure than using Openbox with desktop environments. Running openbox alone may reduce your system's CPU and memory load.
+
Openbox's own autostart mechanism:
  
To run Openbox as a stand-alone window manager, append the following to {{ic|~/.xinitrc}}:
+
* sources {{ic|/etc/xdg/openbox/environment}}
exec openbox-session
+
* sources {{ic|~/.config/openbox/environment}}
 +
* runs {{ic|/etc/xdg/openbox/autostart}}
 +
* runs {{ic|~/.config/openbox/autostart}}
  
See [[xinitrc]] for details, such as preserving the logind session.
+
Issues regarding commands in {{ic|~/.config/openbox/autostart}} being executed out of order (or skipped altogether) are often resolved by the addition of small delays. For instance:
  
If you used another window manager previously (such as Xfwm) and now Openbox will not start after logging out of X, try moving the autostart folder:
+
xset -b
  $ mv ~/.config/autostart ~/.config/autostart.bak
+
(sleep 3s && nm-applet) &
 +
  (sleep 3s && conky) &
  
{{Note|{{Pkg|python2-xdg}} is required for Openbox's xdg-autostart}}
+
=== environment ===
  
== Openbox as a WM for desktop environments ==
+
{{ic|~/.config/openbox/environment}} can be used to export and set relevant environmental variables such as to:
  
Openbox can be used as a replacement window manager for full-fledged desktop environments. The method for deploying Openbox depends on the desktop environment.
+
* Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)
 +
* Change language settings, and
 +
* Define other variables to be used (e.g. the fix for GTK theming could be listed here)
  
=== GNOME 2.24 and 2.26 ===
+
=== Themes ===
  
Create {{ic|/usr/share/applications/openbox.desktop}} with the following lines:
+
Install {{Pkg|obconf}} and {{Pkg|lxappearance-obconf}} for a GUI to configure visual settings and theming.
[Desktop Entry]
 
Type=Application
 
Encoding=UTF-8
 
Name=OpenBox
 
Exec=openbox
 
NoDisplay=true
 
# name of loadable control center module
 
X-GNOME-WMSettingsModule=openbox
 
# name we put on the WM spec check window
 
X-GNOME-WMName=OpenBox
 
In gconf, set {{ic|/desktop/gnome/session/required_components/windowmanager}} to {{ic|openbox}}:
 
$ gconftool-2 -s -t string /desktop/gnome/session/required_components/windowmanager openbox
 
Finally, choose the {{ic|GNOME}} session from the GDM sessions menu.
 
  
=== GNOME 2.26 redux ===
+
A good selection of themes are available in the {{Pkg|openbox-themes}} package or the [[AUR]]. Some [[GTK+#Themes]] come with an Openbox theme as well. Both Openbox-specific and Openbox-compatible themes will be installed to the {{ic|/usr/share/themes}} directory and will also be immediately available for selection.
  
'''''If the previous guide for GNOME 2.24 fails:'''''
+
[https://www.box-look.org/browse/ord/latest/ box-look.org] is an excellent and well-established source of themes. [http://www.deviantart.com/ deviantART.com] is another excellent resource. Many more can be found online.
  
If, when attempting to log into a "Gnome/Openbox" session -- and it consistently fails to start, try the following. This is one way of achieving your goal of using Openbox as the WM anytime you open a Gnome session:
+
==== Edit or create ====
  
# Log into your Gnome-only session (it should still be using Metacity as its window manager).
+
{{Tip|It's better to copy a theme to your home directory than to edit those found in {{ic|/usr/share/themes/}}. This will retain the original should anything go wrong and ensure that your changes are not overwritten on update.}}
# Navigate your menus to ''System > Preferences > Startup Applications'' (possibly named 'Session' in older Gnome versions)
 
# Open Startup Application, select '+ Add' and enter the text shown below. Omit the text after #.
 
# Click the 'Add' button for the data entry window. Make sure the checkbox beside your new entry is selected.
 
# Log out from your Gnome session and log back in
 
# You should now be running openbox as your window manager.
 
  
Name:   Openbox Windox Manager          # Can be changed
+
The process of creating new or modifying existing themes is covered extensively at the official [http://openbox.org/wiki/Help:Themes openbox.org] website. {{AUR|obtheme}} is a user-friendly GUI for doing so.
Command: openbox --replace              # Text should not be removed from this line, but possibly added to it
 
Comment: Replaces metacity with openbox  # Can be changed
 
  
This creates a startup list entry which is executed by Gnome each time the user's session is started.
+
=== GUI configuration ===
  
=== KDE ===
+
Several GUI applications are available to quickly and easily configure your Openbox desktop.
  
# If you use KDM, select the "KDE/Openbox" login option.
+
* {{App|ObConf|A GTK2 based configuration tool for the Openbox window manager.|http://openbox.org/wiki/ObConf:About|{{Pkg|obconf}}}}
# Open System Settings > Default Applications (in the Workspace Appearance and Behaviour section), and change the default window manager to Openbox (this will also avoid having to log out and log back in again).
+
* {{App|LXAppearance ObConf|Plugin for LXAppearance to configure Openbox. Note that not all options to configure Openbox are available in this plugin, so you might want to install obconf anyway.|http://lxde.org|{{Pkg|lxappearance-obconf}}}}
# If you use startx, add {{ic|exec openbox-kde-session}} to {{ic|~/.xinitrc}}
+
* {{App|LXInput|LXDE keyboard and mouse configuration|http://lxde.org|{{Pkg|lxinput}}}}
# From the shell:
+
* {{App|LXRandR|LXDE monitor configuration.|http://wiki.lxde.org/en/LXRandR|{{Pkg|lxrandr}}}}
$ xinit /usr/bin/openbox-kde-session
+
* {{App|obkey|Configure Openbox keyboard shortcuts|https://code.google.com/p/obkey/|{{AUR|obkey}}}}
 +
* {{App|ob-autostart|A simple autostart application for Openbox.|http://pastebin.com/012YgXTk|{{AUR|ob-autostart}}}}
 +
* {{App|obapps|Graphical tool for configuring application settings in Openbox.|https://sourceforge.net/projects/obapps/|{{AUR|obapps}}}}
  
=== XFCE4 ===
+
Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the [[#Menus|Menus]] section.
  
Log into a normal XFCE4 session. From your terminal, type:
+
== Openbox reconfiguration ==
$ killall xfwm4 ; openbox & exit
 
  
This kills XFWM4, runs Openbox, and closes the terminal. Log out, being sure to check the ''"Save session for future logins"'' box. On your next login, XFCE4 should use '''Openbox''' as its window manager.
+
{{Tip|where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.}}
  
Alternatively, you can chooose ''Settings > Session and Startup'' from menu, go to the ''Application Autostart'' tab and add {{ic|openbox --replace}} to the list of automatically started applications.
+
Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:
  
To enable exiting from a session using ''xfce4-session'', edit {{ic|~/.config/openbox/menu.xml}}.  If the file is not there, copy it from  {{ic|/etc/xdg/openbox/}}. Look for the following entry:
+
$ openbox --reconfigure
  <item label="Exit Openbox">
 
    <action name="Exit">
 
      <prompt>yes</prompt>
 
    </action>
 
  </item>
 
  
Change it to:
+
Where intending to add this command as a keybind to {{ic|~/.config/openbox/rc.xml}}, it will only be necessary to list the command as {{ic|reconfigure}}. An example has been provided below, using the {{ic|Super}}+{{ic|F11}} keybind:
  <item label="Exit Openbox">
 
    <action name="Execute">
 
      <prompt>yes</prompt>
 
    <command>xfce4-session-logout</command>
 
    </action>
 
  </item>
 
  
Otherwise, choosing "Exit" from the root-menu causes Openbox to terminate its execution, leaving you with no window manager.
+
<keybind key="W-F11">
 +
  <action name="Reconfigure"/>
 +
</keybind>
  
If you have a problem changing virtual desktops with the mouse wheel skipping over desktops, edit {{ic|~/.config/openbox/rc.xml}}. Move the ''mouse binds with...'' actions "DesktopPrevious" and "DesktopNext" from context ''Desktop'' to the context ''Root''. Note that you may need to create a definition for the ''Root'' context as well.
+
== Keybinds ==
  
When using the Openbox root-menu instead of XFCE's menu, you may exit the Xfdesktop with this terminal command:
+
All keybinds must be added to the {{ic|~/.config/openbox/rc.xml}} file, and below the {{ic|<nowiki><!-- Keybindings for running aplications --></nowiki>}} heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at [http://openbox.org/wiki/Help:Bindings openbox.org].  
$ xfdesktop --quit
 
Xfdesktop manages the wallpaper and desktop icons, requiring you to use other utilities such as ROX for these functions.
 
  
(When terminating Xfdesktop, the above issue with the virtual desktops is no longer a problem.)
+
Keybinds can be added to the configuration file using the following syntax:
  
If you want have rc.xml separated than your default openbox session rc.xml
+
<keybind key="'''my-key-combination'''">
 +
  <action name="'''my-action'''">
 +
    '''...'''
 +
  </action>
 +
</keybind>
  
Edit the {{ic|~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xml}} or (to make the change for all XFCE users) {{ic|/etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xfce4-session.xml}}:
+
The action name for running an external command is ''Execute''. Use the following syntax to define an external command to execute:
Replace the xfwm startup command,
 
{{bc|<nowiki>
 
<property name="Client0_Command" type="array">
 
  <value type="string" value="xfwm4"/>
 
</property>
 
</nowiki>}}
 
with the following:
 
{{bc|<nowiki>
 
<property name="Client0_Command" type="array">
 
  <value type="string" value="openbox"/>
 
  <value type="string" value="--config-file"/>
 
  <value type="string" value="~/.config/xfce4/openbox/rc.xml"/>
 
</property>
 
</nowiki>}}
 
  
and also the menu, you can set the separated menu ex: xfce4-menu.xml , change it to your custom xfce4 rc.xml , but notice that the menu must be place at {{ic|~/.config/openbox/}}.
+
<action name="Execute">
 +
  <command>'''my-command'''</command>
 +
</action>
  
== Openbox for multihead users ==
+
See [http://openbox.org/wiki/Help:Actions the Openbox wiki] for a list of all available actions.
  
While Openbox provides better than average multihead support on its own, the {{AUR|openbox-multihead-git}} package from the [[AUR]] provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.
+
{{Tip|The {{AUR|obkey}} utility provides a graphical interface for configuring key bindings. Before using ''obkey'', you should use ''obconf'' to create {{ic|~/.config/openbox/rc.xml}}.}}
  
Openbox Multihead will function like normal Openbox when only a single head is available.
+
While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as {{ic|modifiers}}, {{ic|multimedia}} and {{ic|navigation}}.
  
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, {{AUR|pager-multihead-git}} can be found in the [[AUR]] and is compatible with Openbox Multihead. [http://imgur.com/a/cnZeq#y04nk Screenshots].
+
=== Modifiers ===
  
Finally, a new version of [[PyTyle]] that will work with Openbox Multihead can also be found in the [[AUR]]: {{AUR|pytyle3-git}}.
+
{{ic|Modifier}} keys play an important role in keybindings (e.g. holding down the {{ic|shift}} or {{ic|CTRL / control}} key in combination with another key to undertake an action). Using modifiers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifier with another key is:
  
Both ''pytyle3'' and ''pager-multihead-git'' will work without Openbox Multihead if only one monitor is active.
+
"<modifier>-<key>"
  
== Configuration ==
+
The modifier codes are as follows:
  
There are several options for configuring Openbox settings:
+
* {{ic|S}}: Shift
 +
* {{ic|C}}: Control / CTRL
 +
* {{ic|A}}: Alt
 +
* {{ic|W}}: Super / Windows
 +
* {{ic|M}}: Meta
 +
* {{ic|H}}: Hyper (If it is bound to something)
  
=== Manual configuration ===
+
=== Multimedia keys ===
  
To configure Openbox manually, edit the {{ic|~/.config/openbox/rc.xml}} file with a text editor. The file has explanatory comments throughout, for more details about editing it see the [http://openbox.org/wiki/Help:Configuration Openbox wiki].
+
Where available, it is possible to set the appropriate {{ic|multimedia}} keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the {{ic|function}} keys, and are identified by their appropriate symbols. See [[Extra keyboard keys]] for details.
  
=== ObConf ===
+
The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):
  
[http://openbox.org/wiki/ObConf:About ObConf] is an Openbox configuration tool. It is used to set most common preferences such as themes, virtual desktops, window properties, and desktop margins. It can be installed with the {{Pkg|obconf}} package, available in the [[official repositories]].
+
* {{ic|XF86AudioRaiseVolume}}: Increase volume
 +
* {{ic|XF86AudioLowerVolume}}: Decrease volume
 +
* {{ic|XF86AudioMute}}: Mute / unmute volume
 +
* {{ic|XF86MonBrightnessUp}}: Increase screen brightness
 +
* {{ic|XF86MonBrightnessDown}}: Decrease screen brightness
  
ObConf cannot configure keyboard shortcuts and certain other features. For these features edit {{ic|rc.xml}} manually. Alternatively, you can try {{Pkg|obkey}}, available in the [[official repositories]].
+
For a full list of XF86 multimedia keys, see the [http://wiki.linuxquestions.org/wiki/XF86_keyboard_symbols LinuxQuestions wiki].
  
=== Application customization ===
+
==== Volume control ====
  
Openbox allows per-application customizations. This lets you define rules for a given program. For example:
+
What commands should be used for controlling the volume will depend on whether [[ALSA]], [[PulseAudio]], or [[OSS]] is used for sound.
* Start your web browser on a specific virtual desktop.
 
* Open your terminal program with no window decorations (window chrome).
 
* Make your bit-torrent client open at a given screen position.
 
  
Per-application settings are defined in {{ic|~/.config/openbox/rc.xml}}. Instructions are in the file's comments. More details are found in the [http://openbox.org/wiki/Help:Applications Openbox wiki].
+
*ALSA: see [[Advanced Linux Sound Architecture#Keyboard volume control]].
 +
*PulseAudio: see [[PulseAudio#Keyboard volume control]]
 +
*OSS: see [[OSS#Using multimedia keys with OSS]].
  
== Menus ==
+
=== Navigation keys ===
  
The default Openbox menu includes a variety of menu items to get you started. Many of these items launch applications you do not want, have not installed yet, or never intend to install. You will surely want to customize '''{{ic|menu.xml}}''' at some point. There are a number of ways to do so.
+
These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:
  
{{Note|To reload the menu, either in a terminal, type: "openbox --reconfigure" or right-click-desktop->System->Reconfigure Openbox}}
+
* {{ic|Up}}: Up
 +
* {{ic|Down}}: Down
 +
* {{ic|Left}}: Left
 +
* {{ic|Right}}: Right
  
=== Manual configuration of menus ===
+
== Menus ==
  
You can edit {{ic|~/.config/openbox/menu.xml}} with a text editor. Many of the settings are self-explanatory. The article [http://openbox.org/wiki/Help:Menus Help:Menus] in the Openbox wiki has extensive details.
+
It is possible to employ three types of menu in Openbox: {{ic|static}}, {{ic|pipes}} (dynamic), and {{ic|generators}} (static or dynamic). They may also be used alone or in any combination.
  
=== Icons in the menu ===
+
=== Static ===
  
To add icons next to your menu entries, add {{ic|<showIcons>yes</showIcons>}} to the {{ic|<menu>}} section of the {{ic|rc.xml}} file. Then edit {{ic|menu.xml}} and add {{ic|1=icons="<path>"}} to the menu entries you want to add icons to:
+
As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.
<menu id="apps-menu" label="SomeApp" icon="/home/user/.icons/application.png">
 
  
Finally, {{ic|$ openbox --reconfigure}} to update the menu.
+
Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the {{Pkg|synapse}} or {{Pkg|xfce4-appfinder}} applications).
  
=== MenuMaker ===
+
The {{ic|~/.config/openbox/menu.xml}} file will be the sole source of static desktop menu content.
  
[http://menumaker.sourceforge.net/ MenuMaker] creates XML menus for several window managers including Openbox. MenuMaker searches your computer for executable programs and creates a menu file from the result. It can be configured to exclude certain application types (GNOME, KDE, etc) if you desire. It can be installed with the {{Pkg|menumaker}} package available in the official repositories.
+
==== menumaker ====
  
Once installed, generate a menu file (named {{ic|menu.xml}}) by running the program.
+
{{Pkg|menumaker}} automatically generates {{ic|xml}} menus for several window managers, including Openbox, [[Fluxbox]], [[IceWM]] and [[Xfce]]. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to [[GNOME]] or [[KDE]]), if desired.
$ mmaker -v OpenBox3    #  Will not overwrite an existing menu file.
 
$ mmaker -vf OpenBox3    #  Force option permits overwriting the menu file.
 
$ mmaker --help          #  See the full set of options for MenuMaker.
 
  
MenuMaker creates a comprehensive {{ic|menu.xml}}. You may edit this file by hand or regenerate it after installing software.
+
Once installed and executed, it will automatically generate a new {{ic|~/.config/openbox/menu.xml}} file. To avoid overwriting an existing file, enter:
  
=== Obmenu ===
+
$ mmaker -v OpenBox3
  
[http://obmenu.sourceforge.net/ Obmenu] is a GUI menu editor for Openbox. This is a good choice for those who dislike editing XML code. Obmenu can be installed with the package {{Pkg|obmenu}}, available in the official repositories.
+
Otherwise, to overwrite an existing file, add the {{ic|force}} argument ({{ic|f}}):
  
Once installed, run {{ic|obmenu}} and add and remove applications as desired.
+
$ mmaker -vf OpenBox3
  
==== obm-xdg ====
+
Once a new {{ic|~/.config/openbox/menu.xml}} file has been generated it may then be manually edited, or configured using a GUI menu editor, such as {{Pkg|obmenu}}.
  
{{ic|obm-xdg}} is a command-line tool that comes with Obmenu. It generates a categorized sub-menu of installed GTK/GNOME applications.
+
==== obmenu ====
  
To use obm-xdg with other menus, add the following line to {{ic|~/.config/openbox/menu.xml}}:
+
{{Warning|{{ic|obm-xdg}} - a pipe menu to generate a list of [[GTK+]] and [[GNOME]] applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.}}
<menu execute="obm-xdg" id="xdg-menu" label="xdg"/>
 
  
Then add the following line under your ''root-menu'' entry where you want to have the menu appear:
+
{{Pkg|obmenu}} is a "user-friendly" GUI application to edit {{ic|~/.config/openbox/menu.xml}}, without the need to code in {{ic|xml}}.
<menu id="xdg-menu"/>
 
  
Then run {{ic|$ openbox --reconfigure}} to refresh the Openbox menu. You should now see a sub-menu labeled '''xdg''' in your menu.
+
==== xdg-menu ====
  
To use obm-xdg by itself, create {{ic|~/.config/openbox/menu.xml}} and add these lines:
+
{{Pkg|archlinux-xdg-menu}} will automatically generate a menu based on {{ic|xdg}} files contained within the {{ic|/etc/xdg/}} directory for numerous Window Managers, including Openbox. Review the [[Xdg-menu#OpenBox]] article for further information.
<openbox_menu>
 
  <menu execute="obm-xdg" id="root-menu" label="apps"/>
 
</openbox_menu>
 
  
{{Note|If you do not have GNOME installed, you need to install the package {{pkg|gnome-menus}} for obm-xdg.}}
+
==== logout menu options ====
  
=== Xdg-menu ===
+
{{Tip|The commands provided can also be attached to [[#Keybinds|keybinds]].}}
  
[[Xdg-menu]] can automatically generate a menu for Openbox from XDG files. It can be installed with the {{Pkg|archlinux-xdg-menu}} package available in the [[official repositories]].
+
The {{ic|~/.config/openbox/menu.xml}} file can be edited in order to provide a sub-menu with the same options as provided by [[#oblogout|oblogout]]. The sample script below will provide all of these options, with the exception of the ability to lock the screen:
  
For a guide on using XDG-menu, see the [[Xdg-menu#OpenBox]] article.
+
<menu id="exit-menu" label="Exit">
 +
<item label="Log Out">
 +
<action name="Execute">
 +
<command>openbox --exit</command>
 +
</action>
 +
</item>
 +
<item label="Shutdown">
 +
<action name="Execute">
 +
<command>systemctl poweroff</command>
 +
</action>
 +
</item>
 +
<item label="Restart">
 +
<action name="Execute">
 +
        <command>systemctl reboot</command>
 +
</action>
 +
</item>
 +
<item label="Suspend">
 +
<action name="Execute">
 +
        <command>systemctl suspend</command>
 +
</action>
 +
</item>
 +
<item label="Hibernate">
 +
<action name="Execute">
 +
        <command>systemctl hibernate</command>
 +
</action>
 +
</item>
 +
</menu>
  
==== Python-based XDG-Menu script ====
+
Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):
  
This script is found in Fedora's Openbox package. The latest version of the script can be found [http://pkgs.fedoraproject.org/cgit/openbox.git/tree/xdg-menu here]. Download it and place it anywhere you want.
+
<menu id="exit-menu"/>
  
Open {{ic|menu.xml}} with your text editor and add the following entry. Of course, you can modify the label as you see fit.
+
=== Pipes ===
<menu id="apps-menu" label="xdg-menu" execute="python2 /path/to/xdg-menu"/>
 
  
Save the file and run {{ic|$ openbox --reconfigure}}.
+
{{Tip|It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.}}
  
=== openbox-menu ===
+
This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the [[official repositories]]. More experienced users can also modify and/or create their own custom scripts. Again, {{ic|~/.config/openbox/menu.xml}} may and commonly will contain several pipe menus.
  
[http://mimasgpc.free.fr/openbox-menu_en.html Openbox-menu] uses [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] from the LXDE Project to create dynamic menus for Openbox. It can be installed with the package {{AUR|openbox-menu}}, available in the [[AUR]].
+
==== Examples ====
  
If you get an error while trying to open this menu try [[#Icons in the menu|adding icons]] to the Openbox menu.
+
* {{AUR|openbox-xdgmenu}}: fast xdg-menu converter to xml-pipe-menu
 +
* {{AUR|obfilebrowser}}: Application and file browser
 +
* {{AUR|obdevicemenu}}: Management of removable media with [[Udisks]]
 +
* [https://bbs.archlinux.org/viewtopic.php?pid=1345031 wifi pipe menu]: Wireless networking using [[Netctl]]
  
=== Openbox menu generators ===
+
[http://openbox.org/wiki/Openbox:Pipemenus Openbox.org] also provides a further list of pipe menus.
  
==== obmenugen ====  
+
=== Generators ===
  
Obmenugen creates the menu file from {{ic|.desktop}} files. Obmenugen provides a text file which filters (hides) menu items using basic regular expressions. It can be installed with the package {{AUR|obmenugen}}, available in the AUR.
+
This type of menu is akin to those provided by the taskbars of desktop environments such as [[Xfce]] or [[LXDE]]. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.
  
Basic usage:
+
A menu generator will have to be executed from the {{ic|~/.config/openbox/menu.xml}} file.
$ obmenugen              # Create a menu file
 
$ openbox --reconfigure  # To see the menu you generated
 
  
 
==== obmenu-generator ====
 
==== obmenu-generator ====
  
Obmenu-generator is a pipe/static menu generator for Openbox with icon support. can be installed with the package {{AUR|obmenu-generator}}, available in the AUR.  
+
{{Tip|icons can still be disabled in {{AUR|obmenu-generator}}, even where enabled in {{ic|~/.config/openbox/rc.xml}}.}}
  
The following command generates a pipe menu with icons:
+
{{AUR|obmenu-generator}} is highly recommended despite being an unofficial package. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The [http://trizenx.blogspot.co.uk/2012/02/obmenu-generator.html official homepage] provides further information and screenshots.
$ obmenu-generator -p -i
 
To see a list of options type this:
 
$ obmenu-generator -h
 
  
=== Pipe menus ===
+
Below is an example of how obmenu-generator would be dynamically executed without icons in {{ic|~/.config/openbox/menu.xml}}:
  
Like other window managers, Openbox allows for scripts to dynamically build menus (menus on-the-fly). Examples are system monitors, media player controls, or weather monitors. Pipe menu script examples are found in the [http://openbox.org/wiki/Openbox:Pipemenus Openbox:Pipemenus] page at Openbox's site.
+
<?xml version="1.0" encoding="utf-8"?>
 +
<openbox_menu>
 +
    <menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator">
 +
    </menu>
 +
</openbox_menu>
  
Some interesting pipe menus provided by Openbox users:
+
To automatically iconify entries, the {{ic|-i}} option would be added:
* {{App|obfilebrowser|Pipe menu file browser.|http://xyne.archlinux.ca/projects/obfilebrowser/|{{AUR|obfilebrowser}}}}
 
* {{App|wifi-pipe|Pipe menu for scanning and connecting to wireless hot spots using netcfg.|https://github.com/pbrisbin/wifi-pipe|{{AUR?|wifi-pipe}}}}
 
* {{App|obdevicemenu|Pipe menu for managing removable devices using Udisks.|https://bbs.archlinux.org/viewtopic.php?id&#61;114702|{{AUR|obdevicemenu}}}}
 
  
== Startup programs ==
+
<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i">
  
Openbox supports running programs at startup. This is provided by command '''openbox-session'''.
+
==== openbox-menu ====
  
=== Enabling autostart ===
+
{{Tip|If this menu produces an error, it may be solved by enabling icons in {{ic|~/.config/openbox/rc.xml}}.}}
  
There are two ways to enable autostart:
+
{{AUR|openbox-menu}} uses the [[LXDE]] [http://sourceforge.net/projects/lxde/files/menu-cache/ menu-cache] to create dynamic menus. The [http://fabrice.thiroux.free.fr/openbox-menu_en.html official homepage] provides further information and screenshots.
# When using startx or xinit to begin a session, edit {{ic|~/.xinitrc}}. Change the line that executes '''''openbox''''' to '''openbox-session'''.
 
# When using GDM or KDM, selecting an ''Openbox'' session automatically runs the autostart script.
 
  
=== Autostart script ===
+
=== Menu icons ===
  
Openbox provides a system-wide startup script which applies to all users and is located at {{ic|/etc/xdg/openbox/autostart}}.  A user may also create his own startup script to be executed after the system-wide script by creating the file {{ic|~/.config/openbox/autostart}}.  This file is not provided by default and must be created by the user.
+
To show icons next to menu entries, it will be necessary to ensure they are enabled in the {{ic|<menu>}} section of the {{ic|~/.config/openbox/rc.xml}} file:
  
Further instructions are available in the [http://openbox.org/wiki/Help:Autostart Help:Autostart] article at the official Openbox site.
+
<applicationIcons>yes</applicationIcons>
  
{{Note|
+
Where using a static menu, it will then be necessary to edit the {{ic|~/.config/openbox/menu.xml}} file to provide both the {{ic|icon <nowiki>=</nowiki>}} command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:
* The autostart files used to be named autostart.sh prior to OpenBox 3.5.0. While these scripts will presently still work, users who are upgrading are advised to drop the .sh extension.
 
* All the programs in the autostart file should be run as daemons or run in the background,otherwise the items in {{ic|/etc/xdg/autostart/}} won't be started!
 
}}
 
  
=== Autostart directory ===
+
<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]">
  
Openbox also starts any *.desktop files in {{ic|/etc/xdg/autostart}} - this happens regardless of whether a user startup script is present. {{ic|nm-applet}}, for example, installs a file at this location, and may cause it to run twice for users with the usual {{ic|(sleep 3 && /usr/bin/nm-applet --sm-disable) &}} in their startup script. There is a discussion on managing the effects of this at [https://bbs.archlinux.org/viewtopic.php?pid=993738].
+
=== Desktop menu as a panel menu ===
  
== Themes and appearance ==
+
{{Tip|XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...}}
  
{{Box||See the main article: [[Openbox Themes and Apps#Themes and appearance]]|#E5E5FF|#FCFCFC}}
+
{{Pkg|xdotool}} is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:
  
=== Openbox themes ===
+
* Replace an existing panel menu
 +
* Implement a panel menu where otherwise not provided or possible (e.g. for [[Tint2]])
 +
* Compensate where losing access to the desktop menu due to the use of an application like {{pkg|xfdesktop}} to manage the [[#Desktop icons and wallpapers|desktop]].
  
Themes control the appearance of windows, titlebars, and buttons. They also control menu appearance and on-screen display (OSD). Some Openbox themes can be installed with the package {{Pkg|openbox-themes}}, available in the [[official repositories]].
+
Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in {{ic|~/.config/openbox/rc.xml}}, and again below the {{ic|<nowiki><</nowiki>!-- Keybindings for running aplications --<nowiki>></nowiki>}} heading. For example, the following code will bring up the menu by pressing {{ic|CTRL}} + {{ic|m}}:
  
=== Cursors, icons, wallpapers ===
+
<keybind key="C-m">
 +
    <action name="ShowMenu">
 +
        <menu>root-menu</menu>
 +
    </action>
 +
</keybind>
  
Xcursor themes can be installed with the package {{Pkg|xcursor-themes}}, available in the official repositories, or with other packages from such as {{Pkg|xcursor-bluecurve}}, {{Pkg|xcursor-vanilla-dmz}} or {{Pkg|xcursor-pinux}}. Many other themes can be found in the official repositories or the [[AUR]].
+
Openbox must then be [[#Openbox reconfiguration|reconfigured]]. In this instance, XDoTool will be used to simulate the {{ic|CTRL}} + {{ic|m}} keypress to access the desktop menu with the following command (note the use of {{ic|+}} in place of {{ic|-}}):
  
Icon themes are also available in the repositories, for example {{Pkg|lxde-icon-theme}}, {{Pkg|tangerine-icon-theme}} or {{Pkg|gnome-icon-theme}} can be found in the official repositories with many more in the [[AUR]].
+
xdotool key control+m
  
Wallpapers are easily set with utilities such as [[Nitrogen]], [[feh]] or {{ic|hsetroot}}.
+
How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called {{ic|obpanelmenu.sh}} will be created in the {{ic|~/.config}} folder:
  
Please see [[Openbox Themes and Apps]] for information on these GUI customizations.
+
$ ''text editor'' ~/.config/obpanelmenu.sh
  
== Recommended programs ==
+
Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the {{ic|CTRL}} + {{ic|m}} keypress for this example):
  
{{Box||See the main article: [[Openbox Themes and Apps#Recommended programs]]|#E5E5FF|#FCFCFC}}
+
xdotool key control+m
  
== Tips and tricks ==
+
After the file has been saved and closed, it may then be made into an executable script with the following command:
  
=== Window snap behaviour ===
+
$ chmod +x ~/.config/obpanelmenu.sh
  
Windows 7 and other WMs supports a window behaviour to snap windows when they are moved to the edge of the screen. This effect can also be achieved through an Openbox keybinding, see [http://ubuntuforums.org/showthread.php?t=1796793 here] for more information.  Openbox supports specifying percentages, and [http://openbox.org/wiki/Help:Actions actions]. To simulate Aero Snap:
+
Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste.
  
{{hc|~/.config/openbox/rc.xml|2=
+
=== XDG compliant menu ===
<keybind key="W-Left">
 
    <action name="UnmaximizeFull"/>
 
    <action name="MaximizeVert"/>
 
    <action name="MoveResizeTo">
 
        <width>50%</width>
 
    </action>
 
    <action name="MoveToEdge"><direction>west</direction></action>
 
</keybind>
 
<keybind key="W-Right">
 
    <action name="UnmaximizeFull"/>
 
    <action name="MaximizeVert"/>
 
    <action name="MoveResizeTo">
 
        <width>50%</width>
 
    </action>
 
    <action name="MoveToEdge"><direction>east</direction></action>
 
</keybind>
 
}}
 
  
The only issue with any methods around, is that once maximized to an edge - it stays full (vertically) until you maximize and restore. So you can add the next few lines to simulate the other windows behaviors (maximize, restore).  That will speed up pulling a window from a screen edge as well.
+
A xdg compliant menu is based on the freedesktop.org standard. The menu is defined in menu-files which reside in /etc/xdg/menus. New applications will occur automatically in the menu.
  
{{hc|~/.config/openbox/rc.xml|2=
+
==== Examples ====
<keybind key="W-Down">
 
    <action name="Unmaximize"/>
 
</keybind>
 
<keybind key="W-Up">
 
    <action name="Maximize"/>
 
</keybind>
 
}}
 
  
Then reconfigure Openbox and try it.
+
* [https://github.com/mlde/californium californium]: xdg menu based on the LXQt main menu and easily themable
  
$ openbox --reconfigure
+
== Tips and tricks ==
  
As an alternative/extension you can use [https://github.com/lawl/opensnap opensnap]. It provides Aero Snap like functionality and resizes windows if you drag them to an edge of the screen. It does not provide keyboard shortcuts however.
+
=== Cursor and icon themes ===
  
=== File associations ===
+
See [[Cursor themes]] and [[Icons]] for details.
  
Because Openbox and the applications you use with it are not well-integrated you might run into the issues with your browser. Your browser may not know which program it is supposed to use for certain types of files.
+
=== Desktop icons and wallpapers ===
  
A package in the AUR called {{AUR|gnome-defaults-list}} contains a list of file-types and programs specific to the Gnome desktop. The list is installed to {{ic|/etc/gnome/defaults.list}}.
+
Openbox does not natively support the use of desktop icons or wallpapers.
  
Open this file with your text editor. Here you can replace a given application with the name of the program of your choosing. For example, replace '''totem''' with '''vlc'''  or  '''eog''' with '''mirage'''. Save the file to {{ic|~/.local/share/applications/defaults.list}}.
+
See [[PCManFM#Desktop management|PCManFM]], [[SpaceFM#Desktop management|SpaceFM]] and [[Idesk]].
  
Another way of setting file associations is to install package {{Pkg|perl-file-mimeinfo}} from the official repositories and invoke '''mimeopen''' like this:
+
{{note|You may have to edit {{ic|~/.conkyrc}} and set {{ic|own_window_type}} to {{ic|normal}}.}}
$ mimeopen -d /path/to/file
 
You are asked which application to use when opening {{ic|/path/to/file}}:
 
Please choose a default application for files of type text/plain
 
        1) notepad  (wine-extension-txt)
 
        2) Leafpad  (leafpad)
 
        3) OpenOffice.org Writer  (writer)
 
        4) gVim  (gvim)
 
        5) Other...
 
Your answer becomes the default handler for that type of file. Mimeopen is installed as {{ic|/usr/bin/perlbin/vendor/mimetype}}.
 
  
=== Copy and paste ===
+
See [[List of applications#Wallpaper setters]].
  
From a terminal {{ic|Ctrl+Ins}} for copy and {{ic|Shift+Ins}} for paste.
+
=== Compositing effects ===
  
Also {{ic|Ctrl+Shift+c}} for copy and '''mouse middle-click''' for paste (in terminals).
+
Openbox does not provide native support for [[Wikipedia:Compositing window manager|compositing]], and thus requires an external compositor for this purpose.
  
Other applications most likely use the conventional keyboard shortcuts for copy and paste.
+
Although compositing is not a necessary component, it may specifically avoid issues such as screen distortion with [[#oblogout|oblogout]], and visual glitches with terminal window transparency. See [[Xorg#Composite]] for common choices.
  
=== Window transparency ===
+
=== oblogout ===
  
The program {{Pkg|transset-df}} is available in the official repositories. With ''transset-df'' you can enable window transparency on-the-fly.
+
See the [[Oblogout]] article for an overview on how to use this useful, graphical logout script.
  
For instance by placing the following in the ''<mouse>'' section you can have your mouse adjust window transparency by scrolling while hovering over the title bar:
+
=== Openbox for multihead users ===
{{hc|~/.config/openbox/rc.xml|2=
 
<context name="Titlebar">
 
    . . .
 
    <mousebind button="Up" action="Click">
 
        <action name= "Execute" >
 
        <execute>transset-df -p .2 --inc  </execute>
 
        </action>
 
    </mousebind>
 
    <mousebind button="Down" action="Click">
 
        <action name= "Execute" >
 
        <execute>transset-df -p .2 --dec </execute>
 
        </action>
 
    </mousebind>
 
      . . .
 
</context>
 
}}
 
{{Warning|It appears to work only when no additional actions are defined within the action group.}}
 
  
=== Xprop values for applications ===
+
While Openbox provides better than average multihead support on its own, {{AUR|openbox-multihead-git}} provides a development branch called '''Openbox Multihead''' that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.
  
Xprop can be installed with the package {{Pkg|xorg-xprop}}, available in the official repositories.  
+
Openbox Multihead will function like normal Openbox when only a single head is available.
  
If you use per-application settings frequently, you might find this bash alias handy:
+
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, you can install {{AUR|pager-multihead-git}}{{Broken package link|{{aur-mirror|pager-multihead-git}}}} alongside Openbox Multihead. It will work without Openbox Multihead if only one monitor is active.
  
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'
+
=== Launch a complex command with hotkey ===
  
To use, run {{ic|xp}} and click on the running program that you would like to define with per-app settings. The result displays only the info that Openbox requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:
+
If you need to execute a complex command, use shell functionality.
  
{{hc|$ xp|2=
+
Special character replacement are as follows:
WM_WINDOW_ROLE(STRING) = "roster"
 
WM_CLASS(STRING) = "gajim.py", "Gajim.py"
 
WM_CLASS(STRING) = "NAME", "CLASS"
 
}}
 
==== Xprop for Firefox ====
 
  
For whatever reason, Firefox and like-minded equivalents ignore application rules (e.g. ''<desktop>'') unless {{ic|class&#61;"Firefox*"}} is used. This applies irrespective of whatever values '''xprop''' may report for the program's {{ic|WM_CLASS}}.
+
* {{ic|&}}: &amp;amp;
 +
* {{ic|<}}: &amp;lt;
 +
* {{ic|>}}: &amp;gt;
  
=== Linking the menu to a button ===
+
This example will turn off display immediately and lock screen with {{Pkg|slock}}. It was taken from [https://bbs.archlinux.org/viewtopic.php?pid=903057 this thread].
 +
  <keybind key="W-l">
 +
    <action name="Execute">
 +
      <command>sh -c 'slock &amp;amp; (sleep .5 &amp;amp;&amp;amp; xset dpms force off)'</command>
 +
    </action>
 +
  </keybind>
  
Some people want to link the Openbox menu (or any menu) to an object. This is useful for creating a panel button to pop up a menu. Although Openbox does not provide this, a program called {{Pkg|xdotool}} simulates a keypress. Openbox can be configured to bind that keypress to the ''ShowMenu'' action.
+
Sometimes one need to specify environment variable for application:
 +
  <keybind key="A-F7">
 +
    <action name="Execute">
 +
      <command>sh -c "LC_ALL=C obconf"</command>
 +
    </action>
 +
  </keybind>
  
After installing ''xdotool'', add the following to the ''<keyboard>'' section:
+
Another example will launch application preserving all stdout and stderr output to file:
{{hc|~/.config/openbox/rc.xml|2=
+
  <keybind key="A-f">
<keybind key="A-C-q">
+
     <action name="Execute">
     <action name="ShowMenu">
+
      <command>sh -c sh -c "exec gimp &amp;gt;/tmp/gimp.out 2&amp;gt;&amp;amp;1"</command>
        <menu>root-menu</menu>
 
 
     </action>
 
     </action>
</keybind>
+
  </keybind>
}}
+
 
Then execute {{ic|$ openbox --reconfigure}} or {{ic|$ openbox --restart}} to use the new configuration. The following command summons a menu at your cursor position. The command may given as-is, linked to an object, or placed in a script.
+
=== Switch desktops using the mouse ===
  $ xdotool key ctrl+alt+q
+
 
 +
It is possible to switch desktop by moving the mouse cursor to the edges of the screen. First install {{Pkg|xdotool}} and add the following two lines to your {{ic|~/.xinitrc}}:
 +
 
 +
xdotool behave_screen_edge --delay 500 left set_desktop --relative -- -1 &
 +
  xdotool behave_screen_edge --delay 500 right set_desktop --relative -- +1 &
 +
 
 +
=== Set default applications / file associations ===
 +
 
 +
See the [[Default applications]] article.
 +
 
 +
=== Ad-hoc window transparency ===
  
Of course, change the key shortcut to your liking. Here is a snippet from a [[Tint2]] configuration file which pops up a menu when the clock area is clicked. Each key combination is set to open a menu within Openbox's {{ic|rc.xml}} configuration file. The right‑click menu is different from the left‑click menu:
+
{{Warning|This may not work where other actions are defined within the action group.}}
clock_rclick_command = xdotool key --clearmodifiers "ctrl+XF86PowerOff"
+
The program {{Pkg|transset-df}} can enable window transparency on-the-fly.
clock_lclick_command = xdotool key --clearmodifiers "alt+XF86PowerOff"
 
  
=== Running a terminal emulator as desktop background ===
+
For example, using the following code in the {{ic|<mouse>}} section of the {{ic|~/.config/openbox/rc.xml}} file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:
  
With Openbox, running a terminal as desktop background is easy. You will not need [[Wikipedia:Devil's Pie (software)|devilspie]] here.
+
<context name="Titlebar">
 +
    ...
 +
    <mousebind button="Up" action="Click">
 +
        <action name= "Execute" >
 +
        <execute>transset-df -p .2 --inc  </execute>
 +
        </action>
 +
    </mousebind>
 +
    <mousebind button="Down" action="Click">
 +
        <action name= "Execute" >
 +
        <execute>transset-df -p .2 --dec </execute>
 +
        </action>
 +
    </mousebind>
 +
    ...
 +
</context>
  
The following example shows how to run the terminal emulator [http://en.wikipedia.org/wiki/Rxvt-unicode Urxvt] as desktop background:
+
=== Using obxprop for faster configuration ===
  
First you must enable transparency, open your {{ic|~/.Xdefaults}} file (if it does not exist yet, create it).
+
The {{Pkg|openbox}} package provides a {{ic|obxprop}} binary that can parse relevant values for applications settings in {{ic|rc.xml}}. Officially {{ic|<nowiki>obxprop | grep "^_OB_APP"</nowiki>}} is recommended for this task. Start the process by running the command shown, then click a window to see its properties in the terminal.
URxvt*transparent:true
 
URxvt*scrollBar:false
 
URxvt*geometry:124x24    #I do not use the whole screen, if you want a full screen term do not bother with this and see below.
 
URxvt*borderLess:true
 
URxvt*foreground:Black  #Font color. My wallpaper is White, you may wish to change this to White.
 
  
Then add the following to the ''<applications>'' section:
+
=== Xprop values for applications ===
{{hc|~/.config/openbox/rc.xml|2=
 
<application name="urxvt">
 
    <decor>no</decor>
 
    <focus>yes</focus>
 
    <position>
 
        <x>center</x>
 
        <y>20</y>
 
    </position>
 
    <layer>below</layer>
 
    <desktop>all</desktop>
 
    <maximized>true</maximized> #Only if you want a full size terminal.
 
</application>
 
}}
 
The ''magic'' comes from the {{ic|<layer>below</layer>}} line, which place the application under all others. Here [[Rxvt-unicode|urxvt]] is displayed on all desktops, change it to your convenience.
 
  
{{Tip|Instead of using ''<application name&#61;"urxvt">'', you can use another name ("urxvt-bg" for example), and use the {{ic|-name}} option when starting uxrvt. That way, only the urxvt terminals which you choose to name {{ic|urxvt-bg}} would be captured and modified by the application rule in {{ic|rc.xml}}.  For example:
+
{{Pkg|xorg-xprop}} can be used to relay property values for selected applications. Where frequently using per-application settings, the following [[Bash#Aliases|Bash Alias]] may be useful:
$ urxvt -name urxvt-bg
+
dy:
}}
 
  
==== ToggleShowDesktop exception ====
+
alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'
  
If you use '''ToggleShowDesktop''' to minimize all your application and show the desktop it will also minimize the urxvt window. Several methods are available to bypass this, but none works properly:
+
To use Xorg-XProp, run using the alias given {{ic|xp}}, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the {{ic|WM_WINDOW_ROLE}} and {{ic|WM_CLASS}} (name and class) values:
* one method is explained in this [https://bbs.archlinux.org/viewtopic.php?pid=865844#p865844 forum post]. This involves editing Urxvt's source code.
 
{{Warning|This method seems to have been broken in a recent update, now leading to a memory leak when the patched Urxvt is run.}}
 
* the best method is outlined [https://bbs.archlinux.org/viewtopic.php?pid=929792#p929792 here]. It still has a big disadvantage: it makes ''ToggleShowDesktop'' a one-way action, not restoring the other desktop applications when ''ToggleShowDesktop'' is run for a second time. It does create the opportunity to use a different terminal emulator than Urxvt, however.
 
  
====Another solution====
+
WM_WINDOW_ROLE(STRING) = "roster"
 +
WM_CLASS(STRING) = "gajim.py", "Gajim.py"
 +
WM_CLASS(STRING) = "NAME", "CLASS"
  
Window settings:
+
=== Switching between keyboard layouts ===
  
{{hc|~/.config/openbox/rc.xml|2=
+
See the article section [[Keyboard configuration in Xorg#Switching between keyboard layouts|switching between keyboard layouts]] for instructions.
    <application name="RootTerm">
 
      <decor>no</decor>
 
      <skip_taskbar>yes</skip_taskbar>
 
      <skip_pager>yes</skip_pager>
 
      <layer>normal</layer>
 
      <position>
 
        <x>center</x>
 
        <y>0</y>
 
      </position>
 
      <focus>yes</focus>
 
      <desktop>all</desktop>
 
      <maximized>true</maximized>
 
    </application>
 
}}
 
  
Keyboard binding:
+
=== Set grid layout for virtual desktops ===
  
{{hc|~/.config/openbox/rc.xml|2=
+
Install {{AUR|obsetlayout}}. To set a 2x2 grid for example:
<keybind key="W-d">
 
  <action name="Execute"> <command>~/.config/openbox/toggle_shell.sh</command> </action>
 
</keybind>
 
}}
 
  
And the toggle script:
+
obsetlayout 0 2 2 0
  
{{hc|~/.config/openbox/toggle_shell.sh|2=
+
Run it without arguments to know what the arguments mean.
#!/bin/bash
 
term_id=$(xdotool search --limit 1 --classname RootTerm)
 
wind_id=$(xdotool getwindowfocus)
 
  
if [ $term_id -eq $wind_id ]
+
=== Enable Hot Corners ===
then
 
wind_num=$(xdotool search --all --desktop $(xdotool get_desktop) --name .+ | wc -l)
 
if [ $wind_num -ne 0 ]
 
then
 
xdotool windowminimize $term_id
 
xdotool windowfocus $(xdotool getwindowfocus)
 
echo "hide"
 
fi
 
else
 
xdotool windowactivate $term_id
 
echo "show"
 
fi
 
}}
 
  
Add the following lines to start urxvt on login.
+
[https://github.com/mlde/lead lead] provides hot corners for openbox and other lightweight window managers. Start the application with a entry in the autostart-file:
  
This prevents closing urxvt by accident.
+
mlde.lead &
  
{{hc|~/.config/openbox/autostart|2=
+
Commands can be edited in the configuration file {{ic|~/.config/mlde/lead.conf}}:
...
 
(while :; do urxvt -name RootTerm; done;) &
 
...
 
}}
 
  
=== Switching between keyboard layouts ===
+
[eDP1]
 +
bottom=
 +
bottomLeft=chromium
 +
bottomRight=thunar
 +
left=
 +
right=
 +
top=
 +
topLeft=mlde.californium toggle
 +
topRight=skippy-xd
  
If you don't want to use a separate program for managing keyboard layouts, you can manually configure X to switch layouts on certain key combinations. See [[Keyboard Configuration in Xorg#Switching between keyboard layouts]] for instructions.
+
=== Window snapping ===
  
=== Keyboard volume control ===
+
Many desktop environments and window managers support ''window snapping'' (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of [[#Keybinds|keybinds]] on focused windows.
  
====ALSA====
+
As illustrated in the example below, percentages must be used to determine window sizes (see [http://openbox.org/wiki/Help:Actions openbox.org] for further information). In this instance, The {{ic|super}} key is used in conjunction with the {{ic|navigation}} keys:
  
If you use [[ALSA]] for sound, you can use the {{ic|amixer}} program (part of the {{Pkg|alsa-utils}} package) to adjust the sound volume. You can use Openbox's keybindings to map different shortcuts to actions. If you want to use the multimedia keys, but do not know their names, you could look at the [[Multimedia Keys]] page to find out.
+
<keybind key="W-Left">
 +
    <action name="UnmaximizeFull"/>
 +
    <action name="MaximizeVert"/>
 +
    <action name="MoveResizeTo">
 +
        <width>50%</width>
 +
    </action>
 +
    <action name="MoveToEdge"><direction>west</direction></action>
 +
</keybind>
 +
<keybind key="W-Right">
 +
    <action name="UnmaximizeFull"/>
 +
    <action name="MaximizeVert"/>
 +
    <action name="MoveResizeTo">
 +
        <width>50%</width>
 +
    </action>
 +
    <action name="MoveToEdge"><direction>east</direction></action>
 +
</keybind>
  
For example, add the following in the ''<keyboard>'' section:
+
However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the {{ic|down}} and {{ic|up}} keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:
{{hc|~/.config/openbox/rc.xml|2=
 
<keybind key="W-Up">
 
    <action name="Execute">
 
        <command>amixer set Master 5%+</command>
 
    </action>
 
</keybind>
 
}}
 
This binds {{ic|Super+&uarr;}} to increase your master ALSA volume by 5%. Corresponding binding for volume down:
 
{{hc|~/.config/openbox/rc.xml|2=
 
<keybind key="W-Down">
 
    <action name="Execute">
 
        <command>amixer set Master 5%-</command>
 
    </action>
 
</keybind>
 
}}
 
As another example you can also use the {{ic|XF86Audio*}} keybindings:
 
{{hc|~/.config/openbox/rc.xml|2=
 
<keybind key="XF86AudioRaiseVolume">
 
    <action name="Execute">
 
        <command>amixer set Master 5%+ unmute</command>
 
    </action>
 
</keybind>
 
<keybind key="XF86AudioLowerVolume">
 
    <action name="Execute">
 
        <command>amixer set Master 5%- unmute</command>
 
    </action>
 
</keybind>
 
<keybind key="XF86AudioMute">
 
    <action name="Execute">
 
        <command>amixer set Master toggle</command>
 
    </action>
 
</keybind>
 
}}
 
The above example should work for the majority of multimedia keyboards. It should enable to raise, lower and mute the Master control of your audio device by using the respective multimedia keyboard keys. Notice also that in this example:
 
  
* The "Mute" key should unmute the Master control if it is already in mute mode.
+
<keybind key="W-Down">
* The "Raise" and "Lower" keys should unmute the Master control if it is in mute mode.
+
    <action name="Unmaximize"/>
 +
</keybind>
 +
<keybind key="W-Up">
 +
    <action name="Maximize"/>
 +
</keybind>
  
==== Pulseaudio ====
+
This [http://ubuntuforums.org/showthread.php?t=1796793 Ubuntu forum thread] provides more information. Applications such as {{AUR|opensnap}} are also available to automatically simulate window snapping behaviour without the use of keybinds.
 +
Another option is to use {{AUR|bunsen-utilities-git}} which provides {{ic|bl-aerosnap --left}} and {{ic|bl-aerosnap --right}} commands which will snap active window on left or right edge respectively if it's not snapped and restore it to original size and position otherwise. Just bind these commands to the key combination of your choosing.
  
If you are using [[PulseAudio]] with ALSA as a backend the above keybinding are slightly different as {{ic|amixer}} must be told to use PulseAudio. As always, add the following to the ''<keyboard>'' section to get the proper behaviour:
+
=== Smooth display manager transition ===
{{hc|~/.config/openbox/rc.xml|2=
 
<keybind key="XF86AudioRaiseVolume">
 
    <action name="Execute">
 
        <command>amixer -D pulse set Master 5%+ unmute</command>
 
    </action>
 
</keybind>
 
<keybind key="XF86AudioLowerVolume">
 
    <action name="Execute">
 
        <command>amixer -D pulse set Master 5%- unmute</command>
 
    </action>
 
</keybind>
 
<keybind key="XF86AudioMute">
 
    <action name="Execute">
 
        <command>amixer set Master toggle</command>
 
    </action>
 
</keybind>
 
}}
 
This keybindings should work for most of the systems. Other examples can be found [http://ubuntuforums.org/showthread.php?t=987149 here].
 
  
==== OSS ====
+
{{Note|This has been confirmed to work with [[LightDM]].}}
  
With [[OSS]], you can use keybindings to raise or lower specific mixers. This is useful in cases where you wish to change the volume of a specific application (such as an audio player) without changing the system's volume. Note that the application must be first set up to use its own mixer. In this example, [[MPD]] is [[OSS#Configuring_Applications_for_OSS|configured to have its own mixer]], named {{ic|mpd}}:
+
Users of display managers might experience a flickering during the transition between the display manager and the Openbox desktop. The flickering comes from Openbox setting the root window's color during startup. Therefore there's a brief moment when the display flashes in a grey color, between the display manager's background and the desktop's wallpaper.
{{hc|~/.config/openbox/rc.xml|2=
 
<keybind key="KEY_BINDING">
 
    <action name="Execute">
 
        <command>ossmix -- mpd -1</command>
 
    </action>
 
</keybind>
 
}}
 
This example decreases the volume of the {{ic|mpd}} mixer by one dB. To increase the volume, replace the mixer value ({{ic|-1}}) with a positive one. The {{ic|--}} that appears after {{ic|ossmix}} are added, as listed in {{ic|ossmix}}'s man page, to prevent any negative value from being treated as an argument.
 
  
== Troubleshooting Openbox 3.5 ==
+
Setting the root window's background color can be disabled by editing the Openbox startup script found in {{ic|/usr/lib/openbox/openbox-autostart}}. Simply comment out (or delete) the block starting with {{ic|# Set a background color}}.
  
=== X server crashes ===
+
{{Note|Users who don't specifically set their wallpaper will "inherit" the display manager's background automatically if they disable the root window color adjustment.}}
  
Problems have been detected after upgrade to version 3.5, that the X server might crash in attempt to start Openbox, ending with this error message:
+
== Troubleshooting ==
(metacity:25137): GLib-WARNING **: In call to g_spawn_sync(), exit status of a child process \
 
                    was requested but SIGCHLD action was set to SIG_IGN and ECHILD was received by waitpid(), so exit \
 
                    status can't be returned. This is a bug in the program calling g_spawn_sync(); either do not request \
 
                    the exit status, or do not set the SIGCHLD action.
 
xinit: connection to X server lost
 
waiting for X server to shut down
 
In this particular case, some problem with '''metacity''' package has been identified as the cause of the X server crash issue. To solve the problem reinstall the {{Pkg|metacity}} and [https://aur.archlinux.org/packages.php?K=compiz-decorator-gtk compiz-decorator-gtk] packages. If that does not solve the problem, try removing them.
 
  
Also, plenty of similar cases have been found on the Internet, that not only metacity package might be causing the X server to crash.
+
=== Firefox ===
Thus, whatever else instead of metacity you get in the error output message, try to reinstall it (or remove if necessary) in an attempt to get rid of this X server crash.
 
  
=== Autostarting unwanted applications in 3.5 ===
+
Mozilla based browsers may ignore application rules (e.g. {{ic|<desktop>}}) unless {{ic|1=class="Firefox"}} is used. See [[#Xprop values for applications]].
  
If unwanted applications start with your Openbox session even though they are not listed in your {{ic|~/.config/openbox/autostart}}, check the {{ic|~/.config/autostart/}} directory, it might contain the residues from your previously used desktop environment (GNOME, KDE, etc.), and remove unwanted files.
+
=== Missing themes ===
  
=== SSH agent no longer starting ===
+
If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is compatible with Openbox - there should be an {{ic|openbox-3}} directory and a {{ic|themerc}} file within it. An {{ic|.obt}} ('''O'''pen'''B'''ox '''T'''heme) file may also be present in some instances, which can then be manually loaded in {{Pkg|obconf}}.
  
Whereas Openbox 3.4.x allowed launching an SSH agent from {{ic|~/.config/openbox/autostart}}, with 3.5 that no longer seems to work. You need to put the following code in {{ic|~/.config/openbox/environment}}:
+
A theme may also be not accessible due to wrong permissions. See [[File permissions and attributes]] for more.
  
{{bc|1=
+
=== Stop continuous desktop switching ===
SSHAGENT="/usr/bin/ssh-agent"
 
SSHAGENTARGS="-s"
 
if [ -z "$SSH_AUTH_SOCK" -a -x "$SSHAGENT" ]; then
 
        eval $($SSHAGENT $SSHAGENTARGS)
 
        trap "kill $SSH_AGENT_PID" 0
 
fi
 
}}
 
  
=== Openbox not registering with D-Bus ===
+
By default Openbox switches from the last desktop back to the first desktop on mouse wheel scroll. Use {{ic|<wrap>no</wrap>}} in the {{ic|mousebind}} section to disable this behaviour.
  
Just like with SSH agent, lots of people used to have D-Bus code in {{ic|~/.config/openbox/autostart}} - which no longer works (e.g. Thunar does not see any removable devices anymore).
+
    <context name="Desktop">
 +
      <mousebind button="Up" action="Click">
 +
        <action name="GoToDesktop">
 +
          <to>previous</to>
 +
          <wrap>no</wrap>
 +
        </action>
 +
      </mousebind>
 +
      <mousebind button="Down" action="Click">
 +
        <action name="GoToDesktop">
 +
          <to>next</to>
 +
          <wrap>no</wrap>
 +
        </action>
 +
      </mousebind>
 +
    </context>
  
 
=== Windows load behind the active window ===
 
=== Windows load behind the active window ===
Line 715: Line 621:
  
 
* [http://openbox.org/ Openbox Website] - Official website
 
* [http://openbox.org/ Openbox Website] - Official website
* [http://planetob.openmonkey.com/ Planet Openbox] - Openbox news portal
 
 
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork
 
* [http://www.box-look.org/ Box-Look.org] - A good resource for themes and related artwork
 
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums
 
* [https://bbs.archlinux.org/viewtopic.php?id=93126 Openbox Hacks and Configs Thread] @ Arch Linux Forums
 
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums
 
* [https://bbs.archlinux.org/viewtopic.php?id=45692 Openbox Screenshots Thread] @ Arch Linux Forums
* [http://snott.net/linux/using-gnome3-with-openbox/ Using GNOME 3 with Openbox Tutorial]
+
* [http://urukrama.wordpress.com/openbox-guide/ An Openbox guide]

Latest revision as of 17:26, 22 September 2018

Openbox is a lightweight, powerful, and highly configurable stacking window manager with extensive standards support. It may be built upon and run independently as the basis of a unique desktop environment, or within other integrated desktop environments such as KDE and Xfce, as an alternative to the window managers they provide. The LXDE desktop environment is itself built around Openbox.

Installation

Install the openbox package.

Starting

Standalone

Run openbox or openbox-session with xinit. Note that only openbox-session provides #Autostart.

Note: After executing openbox-session, there is only a blank grey screen. Try to move your mouse and right click to get an openbox menu to make sure that it is actually working.

Other desktop environments

Note:

See Desktop environment#Use a different window manager.

Configuration

Note: Local configuration files will always override global equivalents.

Four key files form the basis of the openbox configuration, each serving a unique role. They are: rc.xml, menu.xml, autostart, and environment. Although these files are discussed in more detail below, to start configuring Openbox, it will first be necessary to create a local Openbox profile (i.e for your specific user account) based on them. This can be done by copying them from the global /etc/xdg/openbox profile (applicable to any and all users) as a template:

$ cp -R /etc/xdg/openbox ~/.config/

rc.xml

Tip: Custom keyboard shortcuts (keybindings) must be added to the <keyboard> section of this file, and underneath the <!-- Keybindings for running aplications --> heading.

~/.config/openbox/rc.xml is the main configuration file, responsible for determining the behaviour and settings of the overall session, including:

  • Keyboard shortcuts (e.g. starting applications; controlling the volume)
  • Theming
  • Desktop and Virtual desktop settings, and
  • Application Window settings

This file is also pre-configured, meaning that it will only be necessary to amend existing content in order to customise behaviour to suit personal preference.

Note: Per-application settings pertaining to fixed placement of applications per monitor will only work if the x & y position have also been defined.

menu.xml

~/.config/openbox/menu.xml defines the type and behaviour of the desktop menu, accessable by right-clicking the background. Although the default provided is a static menu (meaning that it will not automatically update when new applications are installed), it is possible to employ the use of dynamic menus that will automatically update as well.

The available options are discussed extensively below in the #Menus section.

Autostart

openbox-session provides two autostart mechanisms: XDG Autostart (which only works if python2-xdg is installed) and Openbox's own autostart mechanism.

Openbox's own autostart mechanism:

  • sources /etc/xdg/openbox/environment
  • sources ~/.config/openbox/environment
  • runs /etc/xdg/openbox/autostart
  • runs ~/.config/openbox/autostart

Issues regarding commands in ~/.config/openbox/autostart being executed out of order (or skipped altogether) are often resolved by the addition of small delays. For instance:

xset -b
(sleep 3s && nm-applet) &
(sleep 3s && conky) &

environment

~/.config/openbox/environment can be used to export and set relevant environmental variables such as to:

  • Define new pathways (e.g. execute commands that would otherwise require the entire pathway to be listed with them)
  • Change language settings, and
  • Define other variables to be used (e.g. the fix for GTK theming could be listed here)

Themes

Install obconf and lxappearance-obconf for a GUI to configure visual settings and theming.

A good selection of themes are available in the openbox-themes package or the AUR. Some GTK+#Themes come with an Openbox theme as well. Both Openbox-specific and Openbox-compatible themes will be installed to the /usr/share/themes directory and will also be immediately available for selection.

box-look.org is an excellent and well-established source of themes. deviantART.com is another excellent resource. Many more can be found online.

Edit or create

Tip: It's better to copy a theme to your home directory than to edit those found in /usr/share/themes/. This will retain the original should anything go wrong and ensure that your changes are not overwritten on update.

The process of creating new or modifying existing themes is covered extensively at the official openbox.org website. obthemeAUR is a user-friendly GUI for doing so.

GUI configuration

Several GUI applications are available to quickly and easily configure your Openbox desktop.

  • ObConf — A GTK2 based configuration tool for the Openbox window manager.
http://openbox.org/wiki/ObConf:About || obconf
  • LXAppearance ObConf — Plugin for LXAppearance to configure Openbox. Note that not all options to configure Openbox are available in this plugin, so you might want to install obconf anyway.
http://lxde.org || lxappearance-obconf
  • LXInput — LXDE keyboard and mouse configuration
http://lxde.org || lxinput
  • LXRandR — LXDE monitor configuration.
http://wiki.lxde.org/en/LXRandR || lxrandr
  • obkey — Configure Openbox keyboard shortcuts
https://code.google.com/p/obkey/ || obkeyAUR
  • ob-autostart — A simple autostart application for Openbox.
http://pastebin.com/012YgXTk || ob-autostartAUR
  • obapps — Graphical tool for configuring application settings in Openbox.
https://sourceforge.net/projects/obapps/ || obappsAUR

Programs and applications relating to the configuration of Openbox's desktop menu are discussed in the Menus section.

Openbox reconfiguration

Tip: where not already present, it would be worthwhile adding this command to a menu and/or as a keybind for convenience.

Openbox will not always automatically reflect any changes made to its configuration files within a session. As a consequence, it will be necessary to manually reload those files after they have been edited. To do so, enter the following command:

$ openbox --reconfigure

Where intending to add this command as a keybind to ~/.config/openbox/rc.xml, it will only be necessary to list the command as reconfigure. An example has been provided below, using the Super+F11 keybind:

<keybind key="W-F11">
  <action name="Reconfigure"/>
</keybind>

Keybinds

All keybinds must be added to the ~/.config/openbox/rc.xml file, and below the <!-- Keybindings for running aplications --> heading. Although a brief overview has been provided here, a more in-depth explanation of keybindings can be found at openbox.org.

Keybinds can be added to the configuration file using the following syntax:

<keybind key="my-key-combination">
  <action name="my-action">
    ...
  </action>
</keybind>

The action name for running an external command is Execute. Use the following syntax to define an external command to execute:

<action name="Execute">
  <command>my-command</command>
</action>

See the Openbox wiki for a list of all available actions.

Tip: The obkeyAUR utility provides a graphical interface for configuring key bindings. Before using obkey, you should use obconf to create ~/.config/openbox/rc.xml.

While the use of standard alpha-numeric keys for keybindings is self-explanatory, special names are assigned to other types of keys, such as modifiers, multimedia and navigation.

Modifiers

Modifier keys play an important role in keybindings (e.g. holding down the shift or CTRL / control key in combination with another key to undertake an action). Using modifiers helps to prevent conflicting keybinds, whereby two or more actions are linked to the same key or combination of keys. The syntax to use a modifier with another key is:

"<modifier>-<key>"

The modifier codes are as follows:

  • S: Shift
  • C: Control / CTRL
  • A: Alt
  • W: Super / Windows
  • M: Meta
  • H: Hyper (If it is bound to something)

Multimedia keys

Where available, it is possible to set the appropriate multimedia keys to perform their intended functions, such as to control the volume and/or the screen brightness. These will usually be integrated into the function keys, and are identified by their appropriate symbols. See Extra keyboard keys for details.

The volume and brightness multimedia codes are as follows (note that commands will still have to be assigned to them to actually function):

  • XF86AudioRaiseVolume: Increase volume
  • XF86AudioLowerVolume: Decrease volume
  • XF86AudioMute: Mute / unmute volume
  • XF86MonBrightnessUp: Increase screen brightness
  • XF86MonBrightnessDown: Decrease screen brightness

For a full list of XF86 multimedia keys, see the LinuxQuestions wiki.

Volume control

What commands should be used for controlling the volume will depend on whether ALSA, PulseAudio, or OSS is used for sound.

Navigation keys

These are the directional / arrow keys, usually used to move the cursor up, down, left, or right. The (self-explanatory) navigation codes are as follows:

  • Up: Up
  • Down: Down
  • Left: Left
  • Right: Right

Menus

It is possible to employ three types of menu in Openbox: static, pipes (dynamic), and generators (static or dynamic). They may also be used alone or in any combination.

Static

As the name would suggest, this default type of menu does not change in any way, and may be manually edited and/or (re)generated automatically through the use on an appropriate software package.

Fast and efficient, while this type of menu can be used to select applications, it can also be useful to access specific functions and/or perform specific tasks (e.g. desktop configuration), leaving the access of applications to another process (e.g. the synapse or xfce4-appfinder applications).

The ~/.config/openbox/menu.xml file will be the sole source of static desktop menu content.

menumaker

menumaker automatically generates xml menus for several window managers, including Openbox, Fluxbox, IceWM and Xfce. It will search for all installed executable programs and consequently create a menu file for them. It is also possible to configure MenuMaker to exclude certain application types (e.g. relating to GNOME or KDE), if desired.

Once installed and executed, it will automatically generate a new ~/.config/openbox/menu.xml file. To avoid overwriting an existing file, enter:

$ mmaker -v OpenBox3

Otherwise, to overwrite an existing file, add the force argument (f):

$ mmaker -vf OpenBox3

Once a new ~/.config/openbox/menu.xml file has been generated it may then be manually edited, or configured using a GUI menu editor, such as obmenu.

obmenu

Warning: obm-xdg - a pipe menu to generate a list of GTK+ and GNOME applications - is also provided with obmenu. However, it has long-running bugs whereby it may produce an invalid output, or even not function at all. Consequently it has been omitted from discussion.

obmenu is a "user-friendly" GUI application to edit ~/.config/openbox/menu.xml, without the need to code in xml.

xdg-menu

archlinux-xdg-menu will automatically generate a menu based on xdg files contained within the /etc/xdg/ directory for numerous Window Managers, including Openbox. Review the Xdg-menu#OpenBox article for further information.

logout menu options

Tip: The commands provided can also be attached to keybinds.

The ~/.config/openbox/menu.xml file can be edited in order to provide a sub-menu with the same options as provided by oblogout. The sample script below will provide all of these options, with the exception of the ability to lock the screen:

<menu id="exit-menu" label="Exit">
	<item label="Log Out">
		<action name="Execute">
			<command>openbox --exit</command>
		</action>
	</item>
	<item label="Shutdown">
		<action name="Execute">
			<command>systemctl poweroff</command>
		</action>
	</item>
	<item label="Restart">
		<action name="Execute">
		        <command>systemctl reboot</command>
		</action>
	</item>
	<item label="Suspend">
		<action name="Execute">
		        <command>systemctl suspend</command>
		</action>
	</item>
	<item label="Hibernate">
		<action name="Execute">
		        <command>systemctl hibernate</command>
		</action>
	</item>
</menu>

Once the entries have been composed, add the following line to present the sub-menu where desired within the main desktop menu (usually as the last entry):

<menu id="exit-menu"/>

Pipes

Tip: It is entirely feasible for a static menu to contain one or more pipe sub-menus. The functionality of some pipe menus may also rely on the installation of relevant software packages.

This type of menu is in essence a script that provides dynamic, refreshed lists on-the-fly as and when run. These lists may be used for multiple purposes, including to list applications, to provide information, and to provide control functions. Pre-configured pipe menus can be installed, although not from the official repositories. More experienced users can also modify and/or create their own custom scripts. Again, ~/.config/openbox/menu.xml may and commonly will contain several pipe menus.

Examples

Openbox.org also provides a further list of pipe menus.

Generators

This type of menu is akin to those provided by the taskbars of desktop environments such as Xfce or LXDE. Automatically updating on-the-fly, this type of menu can be powerful and very convenient. It may also be possible to add custom categories and menu entries; read the documentation for your intended dynamic menu to determine if and how this can be done.

A menu generator will have to be executed from the ~/.config/openbox/menu.xml file.

obmenu-generator

Tip: icons can still be disabled in obmenu-generatorAUR, even where enabled in ~/.config/openbox/rc.xml.

obmenu-generatorAUR is highly recommended despite being an unofficial package. With the ability to be used as a static or dynamic menu, it is highly configurable, powerful, and versatile. Menu categories and individual entries may also be easily hidden, customised, and/or added with ease. The official homepage provides further information and screenshots.

Below is an example of how obmenu-generator would be dynamically executed without icons in ~/.config/openbox/menu.xml:

<?xml version="1.0" encoding="utf-8"?>
<openbox_menu>
    <menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator">
    </menu>
</openbox_menu>

To automatically iconify entries, the -i option would be added:

<menu id="root-menu" label="OpenBox 3" execute="/usr/bin/obmenu-generator -i">

openbox-menu

Tip: If this menu produces an error, it may be solved by enabling icons in ~/.config/openbox/rc.xml.

openbox-menuAUR uses the LXDE menu-cache to create dynamic menus. The official homepage provides further information and screenshots.

Menu icons

To show icons next to menu entries, it will be necessary to ensure they are enabled in the <menu> section of the ~/.config/openbox/rc.xml file:

<applicationIcons>yes</applicationIcons>

Where using a static menu, it will then be necessary to edit the ~/.config/openbox/menu.xml file to provide both the icon = command, along with the full path and icon name for each entry. An example of the syntax used to provide an icon for a category is:

<menu id="apps-menu" label="[label name]" icon="[pathway to icon]/[icon name]">

Desktop menu as a panel menu

Tip: XDoTool can simulate any keybind for any action, and as such, it may therefore be used for many other purposes...

xdotool is a package that can issue commands to simulate key presses / keybinds, meaning that it is possible to use it to invoke keybind-related actions without having to actually press their assigned keys. As this includes the ability to invoke an assigned keybind for the Openbox desktop menu, it is therefore possible to use XDoTool to turn the Openbox desktop menu into a panel menu. Especially where the desktop menu is heavily customised and feature-rich, this may prove very useful to:

  • Replace an existing panel menu
  • Implement a panel menu where otherwise not provided or possible (e.g. for Tint2)
  • Compensate where losing access to the desktop menu due to the use of an application like xfdesktop to manage the desktop.

Once XDoTool has been installed - if not already present - it will be necessary to create a keybind to access the root menu in ~/.config/openbox/rc.xml, and again below the <!-- Keybindings for running aplications --> heading. For example, the following code will bring up the menu by pressing CTRL + m:

<keybind key="C-m">
    <action name="ShowMenu">
       <menu>root-menu</menu>
    </action>
</keybind>

Openbox must then be reconfigured. In this instance, XDoTool will be used to simulate the CTRL + m keypress to access the desktop menu with the following command (note the use of + in place of -):

xdotool key control+m

How this command may be used as a panel launcher / icon is largely dependent on the features of panel used. While some panels will allow the above command to be executed directly in the process of creating a new launcher, others may require the use of an executable script. As an example, a custom executable script called obpanelmenu.sh will be created in the ~/.config folder:

$ text editor ~/.config/obpanelmenu.sh

Once the empty file has been opened, the appropriate XDoTool command must be added to the empty file (i.e. to simulate the CTRL + m keypress for this example):

xdotool key control+m

After the file has been saved and closed, it may then be made into an executable script with the following command:

$ chmod +x ~/.config/obpanelmenu.sh

Executing it will bring up the Openbox desktop menu. Consequently, where using a panel that supports drag-and-drop functionality to add new launchers, simply drag the executable script onto it before changing the icon to suit personal taste.

XDG compliant menu

A xdg compliant menu is based on the freedesktop.org standard. The menu is defined in menu-files which reside in /etc/xdg/menus. New applications will occur automatically in the menu.

Examples

  • californium: xdg menu based on the LXQt main menu and easily themable

Tips and tricks

Cursor and icon themes

See Cursor themes and Icons for details.

Desktop icons and wallpapers

Openbox does not natively support the use of desktop icons or wallpapers.

See PCManFM, SpaceFM and Idesk.

Note: You may have to edit ~/.conkyrc and set own_window_type to normal.

See List of applications#Wallpaper setters.

Compositing effects

Openbox does not provide native support for compositing, and thus requires an external compositor for this purpose.

Although compositing is not a necessary component, it may specifically avoid issues such as screen distortion with oblogout, and visual glitches with terminal window transparency. See Xorg#Composite for common choices.

oblogout

See the Oblogout article for an overview on how to use this useful, graphical logout script.

Openbox for multihead users

While Openbox provides better than average multihead support on its own, openbox-multihead-gitAUR provides a development branch called Openbox Multihead that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the Xmonad web site. Also, please see README.MULTIHEAD for a more comprehensive description of the new features and configuration options found in Openbox Multihead.

Openbox Multihead will function like normal Openbox when only a single head is available.

A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, you can install pager-multihead-gitAUR[broken link: archived in aur-mirror] alongside Openbox Multihead. It will work without Openbox Multihead if only one monitor is active.

Launch a complex command with hotkey

If you need to execute a complex command, use shell functionality.

Special character replacement are as follows:

  • &: &amp;
  • <: &lt;
  • >: &gt;

This example will turn off display immediately and lock screen with slock. It was taken from this thread.

 <keybind key="W-l">
   <action name="Execute">
     <command>sh -c 'slock &amp; (sleep .5 &amp;&amp; xset dpms force off)'</command>
   </action>
 </keybind>

Sometimes one need to specify environment variable for application:

 <keybind key="A-F7">
   <action name="Execute">
     <command>sh -c "LC_ALL=C obconf"</command>
   </action>
 </keybind>

Another example will launch application preserving all stdout and stderr output to file:

 <keybind key="A-f">
   <action name="Execute">
     <command>sh -c sh -c "exec gimp &gt;/tmp/gimp.out 2&gt;&amp;1"</command>
   </action>
 </keybind>

Switch desktops using the mouse

It is possible to switch desktop by moving the mouse cursor to the edges of the screen. First install xdotool and add the following two lines to your ~/.xinitrc:

xdotool behave_screen_edge --delay 500 left set_desktop --relative -- -1 &
xdotool behave_screen_edge --delay 500 right set_desktop --relative -- +1 &

Set default applications / file associations

See the Default applications article.

Ad-hoc window transparency

Warning: This may not work where other actions are defined within the action group.

The program transset-df can enable window transparency on-the-fly.

For example, using the following code in the <mouse> section of the ~/.config/openbox/rc.xml file will enable control of application window transparency by hovering the mouse-pointer over the title bar and scrolling with the middle button:

<context name="Titlebar">
    ...
    <mousebind button="Up" action="Click">
        <action name= "Execute" >
        <execute>transset-df -p .2 --inc  </execute>
        </action>
    </mousebind>
    <mousebind button="Down" action="Click">
        <action name= "Execute" >
        <execute>transset-df -p .2 --dec </execute>
        </action>
    </mousebind>
    ...
</context>

Using obxprop for faster configuration

The openbox package provides a obxprop binary that can parse relevant values for applications settings in rc.xml. Officially obxprop | grep "^_OB_APP" is recommended for this task. Start the process by running the command shown, then click a window to see its properties in the terminal.

Xprop values for applications

xorg-xprop can be used to relay property values for selected applications. Where frequently using per-application settings, the following Bash Alias may be useful: dy:

alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'

To use Xorg-XProp, run using the alias given xp, and click on the active program desired to define with per-application settins. The results displayed will only be the information that Openbox itself requires, namely the WM_WINDOW_ROLE and WM_CLASS (name and class) values:

WM_WINDOW_ROLE(STRING) = "roster"
WM_CLASS(STRING) = "gajim.py", "Gajim.py"
WM_CLASS(STRING) = "NAME", "CLASS"

Switching between keyboard layouts

See the article section switching between keyboard layouts for instructions.

Set grid layout for virtual desktops

Install obsetlayoutAUR. To set a 2x2 grid for example:

obsetlayout 0 2 2 0

Run it without arguments to know what the arguments mean.

Enable Hot Corners

lead provides hot corners for openbox and other lightweight window managers. Start the application with a entry in the autostart-file:

mlde.lead &

Commands can be edited in the configuration file ~/.config/mlde/lead.conf:

[eDP1]
bottom=
bottomLeft=chromium
bottomRight=thunar
left=
right=
top=
topLeft=mlde.californium toggle
topRight=skippy-xd

Window snapping

Many desktop environments and window managers support window snapping (e.g. Windows 7 Aero snap), whereby they will automatically snap into place when moved to the edge of the screen. This effect can also be simulated in Openbox through the use of keybinds on focused windows.

As illustrated in the example below, percentages must be used to determine window sizes (see openbox.org for further information). In this instance, The super key is used in conjunction with the navigation keys:

<keybind key="W-Left">
    <action name="UnmaximizeFull"/>
    <action name="MaximizeVert"/>
    <action name="MoveResizeTo">
        <width>50%</width>
    </action>
    <action name="MoveToEdge"><direction>west</direction></action>
</keybind>
<keybind key="W-Right">
    <action name="UnmaximizeFull"/>
    <action name="MaximizeVert"/>
    <action name="MoveResizeTo">
        <width>50%</width>
    </action>
    <action name="MoveToEdge"><direction>east</direction></action>
</keybind>

However, it should be noted that once a window has been 'snapped' to an edge, it will remain vertically maximised unless subsequently maximised and then restored. The solution is to implement additional keybinds - in this instance using the down and up keys - to do so. This will also make pulling 'snapped' windows from screen edges faster as well:

<keybind key="W-Down">
   <action name="Unmaximize"/>
</keybind>
<keybind key="W-Up">
   <action name="Maximize"/>
</keybind>

This Ubuntu forum thread provides more information. Applications such as opensnapAUR are also available to automatically simulate window snapping behaviour without the use of keybinds. Another option is to use bunsen-utilities-gitAUR which provides bl-aerosnap --left and bl-aerosnap --right commands which will snap active window on left or right edge respectively if it's not snapped and restore it to original size and position otherwise. Just bind these commands to the key combination of your choosing.

Smooth display manager transition

Note: This has been confirmed to work with LightDM.

Users of display managers might experience a flickering during the transition between the display manager and the Openbox desktop. The flickering comes from Openbox setting the root window's color during startup. Therefore there's a brief moment when the display flashes in a grey color, between the display manager's background and the desktop's wallpaper.

Setting the root window's background color can be disabled by editing the Openbox startup script found in /usr/lib/openbox/openbox-autostart. Simply comment out (or delete) the block starting with # Set a background color.

Note: Users who don't specifically set their wallpaper will "inherit" the display manager's background automatically if they disable the root window color adjustment.

Troubleshooting

Firefox

Mozilla based browsers may ignore application rules (e.g. <desktop>) unless class="Firefox" is used. See #Xprop values for applications.

Missing themes

If for any reason the newly extracted theme cannot be selected, open the theme directory to first ensure that it is compatible with Openbox - there should be an openbox-3 directory and a themerc file within it. An .obt (OpenBox Theme) file may also be present in some instances, which can then be manually loaded in obconf.

A theme may also be not accessible due to wrong permissions. See File permissions and attributes for more.

Stop continuous desktop switching

By default Openbox switches from the last desktop back to the first desktop on mouse wheel scroll. Use <wrap>no</wrap> in the mousebind section to disable this behaviour.

   <context name="Desktop">
     <mousebind button="Up" action="Click">
       <action name="GoToDesktop">
         <to>previous</to>
         <wrap>no</wrap>
       </action>
     </mousebind>
     <mousebind button="Down" action="Click">
       <action name="GoToDesktop">
         <to>next</to>
         <wrap>no</wrap>
       </action>
     </mousebind>
   </context>

Windows load behind the active window

Some application windows (such as Firefox windows) may load behind the currently active window, causing you to need to switch to the window you just created to focus it. To fix this behavior add this to your ~/.config/openbox/rc.xml file, inbetween the <openbox_config> and </openbox_config> tags:

<applications>
  <application class="*">
    <focus>yes</focus>
  </application>
</applications>

See also