PCLinuxOS Magazine

Openbox - Edit rc.xml to Gain Control

by Paul Arnote (parnote)

Last November, we covered the lxde-rc.xml file, back when we were covering the LXDE desktop. Since LXDE uses Openbox as its window manager, a lot of the information we covered then is also applicable to the Openbox release of PCLinuxOS.

Openbox uses a file similar to that used by LXDE, called rc.xml. The file, stored in your /home/username/.config/openbox folder, is responsible for helping define various aspects of how your windows are displayed on the screen, mousebindings, keybindings, and many other settings. You will have to enable the display of hidden files in your file manager in order to see the hidden folder.

So that you can tweak, tune and customize your Openbox installation fully and completely, let’s take a look at the different sections of the rc.xml file, as well as some things you can do with it.

Basic File Structure

As you might have already guessed, the rc.xml file uses the XML format, which stands for Extensible Markup Language. XML is very much like HTML. Just like with HTML, the command sets have opening and closing statements, or tags. For example, to make bold text in HTML, you would use some text here, placing the text you want to make bold between the and tags.

In XML, every opening tag has a closing tag. So, if you have a <keybind something something> tag, you will also have a </keybind> tag to close it out. XML commands can also be nested (and most often are), as this excerpt from the rc.xml file shows:

<keybind key="C-A-x">

 <action name="Execute">

 <command>xchat</command>

 </action>

</keybind>

As you can see, the nested commands in XML work from the outside to the middle, then back out again. In the excerpt above, we start with the keybinding tag (<keybind …>), define the keys on the keyboard to use (C-A-x), specify the action to take when those keys are pressed (Execute), specify the command to execute (<command>xchat), then we back our way out, closing out the command tag (</command>), then closing out the action tag (</action>), then closing out the keybind tag (</keybind>). Failure to close out the tags, or closing out the tags in the wrong order, will result in a corrupt XML file. Typos and misspellings will also result in a corrupt XML file. So, double check everything before you save the file! In fact, it would be a prudent decision to make a backup copy of your original, unaltered rc.xml file. This way should something go horribly wrong, you can always restore your computer to a previous working state, simply by replacing the bad rc.xml file with one that you know works.

Fortunately, the text editor that comes installed on the PCLinuxOS Openbox releases is Geany, which is very good at syntax highlighting. While it may not initially seem like a really big deal, syntax highlighting in a text editor can save you hours of debugging time, in the event that you end up with a corrupt XML file. Since the highlighting is done “on the fly,” it’s also easy and quick to see if you have made any mistakes as you are typing the commands.

You may notice comments interspersed throughout the rc.xml file. Comment lines are those that look like this:



If you make additions to your rc.xml file, it would be a great idea to also insert your own comments. Six months after you make changes or additions, you may not remember exactly what you did, unless you left yourself a “calling card” of sorts, in the form of a comment that describes what you did. Also, the comments that are built into the default rc.xml file can go a long way in helping you understand what to do in any given section of the file.

When you open up the rc.xml file, you will notice that the first tag in the file starts off <openbox-config something something>. This means that the last tag in the rc.xml file will be </openbox-config>, to close out the rc.xml file. In between will be all of the other XML tags that define the Openbox options.

First Section: Resistance

Think of the resistance setting as how hard you have to push a window on your screen against the screen edge before it moves that window to the next virtual desktop. The higher the number, the harder you have to “push” before that window will move to the next desktop. Here are the default settings in the installed Openbox:

<resistance>

 <strength>10</strength>

 <screen_edge_strength>20</screen_edge_strength>

</resistance>

The “strength” setting determines how much resistance there is between adjacent windows, before one is allowed to overlap the other. The “screen_edge_strength” setting determines how much resistance there is at the screen edge, before allowing the selected window to move to the next desktop.

On my copy of Openbox, I’ve changed the strength to 50, and the screen_edge_strength setting to 100. This requires me to push fairly hard against the screen edge, before the window moves over to the next desktop. I’ve done this because sometimes I simply want a window positioned at the screen edge, and not moved to another desktop.

Second Section: Focus

The second section of rc.xml deals with how Openbox focuses the windows on your desktop. There are a number of options you can choose from. Here is the “focus” section from my installation of Openbox:

<focus>
 <focusNew>yes</focusNew>

 

 <followMouse>no</followMouse>

 

 <focusLast>no</focusLast>

 

 <underMouse>no</underMouse>

 

 <focusDelay>200</focusDelay>

 

 <raiseOnFocus>no</raiseOnFocus>

 

</focus>

To start with, the “FocusNew” setting tells Openbox to automatically focus on any new windows that are displayed on your desktop. The “followMouse” setting tells Openbox to change the window focus to the window under your mouse. The default setting here is “yes,” but I have changed that to “no.”

The “focusLast” setting only has an effect when “followMouse” is enabled, or set to “yes.” The default value for “focusLast” is “no.” Changing it to “yes” will automatically re-focus the last active window on a different desktop, instead of allowing the focus to change to whichever window is currently under your mouse pointer.

With the “underMouse” setting, the window focus is moved to the window under the mouse, even if the mouse isn’t moving. The default value is “no.” The “focusDelay” setting selects the number of milliseconds delay before the window is focused when moving a mouse into a window. The default value is 200 ms. The “raiseOnFocus” setting causes the window receiving the focus to be raised to the top, automatically. The default setting is set to “no.” These three settings are dependent on the “followMouse” setting, and if the “followMouse” setting is turned off (set to “no”), then these settings effectively do nothing.

Third Section: Placement

The “Placement” section of the rc.xml file tells Openbox how to place the windows on your desktop. The default values are shown below:

<placement>

 <policy>Smart</policy>

 

 <center>yes</center>

 

 <monitor>Active</monitor>

</placement>

You can choose whether the windows are placed under the mouse, or if Openbox places the windows (the “smart” policy). You can also determine if the windows are centered on your desktop or not, by changing the “center” setting.

Fourth Section: Theme

The “Theme” section of rc.xml tells Openbox what theme to use when displaying your windows, as well as what options (fonts, window decorations, window decoration order, etc.) to use. Below is a snippet of the theme section of the rc.xml file:

<theme>

 <name>Appleish</name>

 <titleLayout>NSLIMC</titleLayout>

 

 <keepBorder>yes</keepBorder>

 <animateIconify>yes</animateIconify>

 

 <name>Liberation Sans</name>

 <size>10</size>

 

 <weight>Bold</weight>

 

 <slant>Normal</slant>

 

 

 ...

The first setting, “name,” tells Openbox which theme I’ve chosen to use. In my case, that is the “Appleish” theme, which I installed via Synaptic.

The next setting, “titleLayout,” tells Openbox which window decorations you want to have displayed on the window title bar, along with the placement of those decorations. Fortunately, there is a “key” provided in the comments of this section of the rc.xml file. Each character can be used only once in any given theme.

The “keepBorder” setting tells Openbox if it should keep the window borders if window decorations are turned off. The default value here is “yes.” The “animateIconify” setting enables a slight animation feature when the windows are minimized to the panel. The default setting is “yes.”

Next, we specify the attributes of the various text parts of the theme. Starting with the title bar of the “ActiveWindow,” we specify the “name” of the font, “size” of the font, “weight” of the font, and the “slant” of the font. We repeat this for each of the following: InactiveWindow, MenuHeader, MenuItem and OnScreenDisplay.

We’ll discuss themes in more depth, a little later, in a separate article.

Fifth Section: Desktops

As you may guess, this section of the rc.xml file specifies the details about your virtual desktops.

<desktops>

 

 <number>4</number>

 <firstdesk>1</firstdesk>

 <names>

 <name>Water</name>

 <name>Fire</name>

 <name>Earth</name>

 <name>Air</name>

 </names>

 <popupTime>500</popupTime>

 

</desktops>

The first setting, “number,” sets the number of virtual desktops available. The “firstdesk” setting specifies which desktop should be displayed when Openbox is first started. Under the “names” setting, you can give a name to each of your virtual desktops. You can give them any name you want. You can call them the names of your children, give them philosophical names, or keep it simple and give them numbers. By default, they are named Water, Fire, Earth and Air. The last setting, “popupTime,” setts the number of milliseconds to show the popup window on your screen, when changing desktops. The default setting is 500 ms, or one-half second.

Sixth Section: Resize

The “Resize” section governs how Openbox displays windows when you are resizing or moving windows. Below is the “resize” section of the rc.xml file, with all the default values displayed:

<resize>

 <drawContents>yes</drawContents>

 <popupShow>NonPixel</popupShow>

 

 <popupPosition>Center</popupPosition>

 

 <popupFixedPosition>

 <x>0</x>

 <y>0</y>

 </popupFixedPosition>

</resize>

The “drawContents” setting tells Openbox to redraw the program inside the window whenever you are resizing or moving the window. The “popupShow” setting, set to “NonPixel,” only displays a popup window on the screen when the resizing window specifies that it is being resized more than one pixel. The popup window shows the screen coordinates for the resized window, along with the pixel size of the window. This usually applies to terminals. You can also set the “popupShow” setting to always be displayed, or to never be displayed.

The “popupPosition” setting allows you to specify the location where the popup window will appear. With the default setting of “center,” the popup window is displayed at the center of the window being resized or moved. The other choices are “top,” where the popup window is displayed above window’s title bar, or “fixed,” where the popup window is displayed at a location defined by “popupFixedPosition.” The latter accounts for the two settings, x and y, under the “popupFixedPosition” setting.

Seventh Section: Margins

The “margins” section of the rc.xml file literally creates margins on your screen.

<margins>

 <top>1</top>

 <bottom>2</bottom>

 <left>2</left>

 <right>2</right>

</margins>

Specify the number of pixels you want to have as a screen margin in the top, bottom, left and right settings, and no items (except for wallpaper) will be drawn in those areas of your screen.

Eighth Section: Dock

Openbox makes good use of items from other desktops and window managers, and allows you to use any number of dockapps that are available for WindowMaker, Xfce, KDE, Gnome, and many others. You can find a whole slew of dockapps available for use with Openbox at dockapps.org. The “dock” section of the rc.xml file helps govern their placement, and is in effect only if you are running a dockapp.

<dock>

 <position>TopLeft</position>

 

 <floatingX>0</floatingX>

 <floatingY>0</floatingY>

 <noStrut>yes</noStrut>

 <stacking>Above</stacking>

 

 <direction>Horizontal</direction>

 

 <autoHide>no</autoHide>

 <hideDelay>300</hideDelay>

 

 <showDelay>300</showDelay>

 

 <moveButton>Middle</moveButton>

 

</dock>

The “position” setting allows you to set where the dockapp appears. The default value is TopLeft. Other possibilities are TopRight, BottomLeft, BottomRight, Top, Bottom, Left, Right or Floating. If you select floating, then the next two settings, floatingX and floatingY set the horizontal and vertical positioning, respectively.

The “noStrut” setting allows windows to be placed over the dockapp. The “stacking” setting determines which layer of the desktop to place the dockapp. You can decide if your dockapps are positioned in a vertical or horizontal row with the “direction” setting.

By toggling the “autoHide” setting (the default is “no”), you can cause your dockapps to automatically hide until you mouse over their position. If the “autoHide” setting is activated, then the “hideDelay” and “showDelay” settings are activated. The setting for both are in milliseconds, and the default value is 300 ms.

Finally, the “moveButton” setting determines which mouse button to use to move the dockapp to a new location on your desktop. The default value is “Middle.”

Ninth Section: Keyboard

The “keyboard” section is typically the largest section of the rc.xml file, and one where you can make some very interesting changes in the functionality of Openbox. Below is an excerpt from the first few lines of the keyboard section of my rc.xml file:

<keyboard>

 

 <keybind key="C-A-Left">

 <action name="DesktopLeft">

 <dialog>no</dialog>

 <wrap>yes</wrap>

 </action>

 </keybind>

 <keybind key="C-A-Right">

 <action name="DesktopRight">

 <dialog>no</dialog>

 <wrap>yes</wrap>

 </action>

 </keybind>

 <keybind key="C-F1">

 <action name="Desktop">

 <desktop>1</desktop>

 </action>

 </keybind>

I previously covered keybindings fairly thoroughly in the November, 2010 article LXDE: Meet The Heart & Soul – lxde-rc.xml. Since LXDE uses Openbox as its window manager, the information in that article applies equally to the Openbox rc.xml file. Instead of repeating all of that information here, I’ll simply refer you to that article for a more complete discussion of keybindings.

One thing that I did find in my installation of Openbox were keybindings that were either duplicated, or that are assigned to keystroke combinations that typically are reserved for other functions. For example, for the “DesktopLeft” and “DesktopRight” settings in my excerpt above, the default values are defined as C-Left (Control key + Left cursor key) and C-Right (Control key + Right cursor key), respectively. However, those keystroke combinations are typically reserved for use in word processing programs to move your cursor through your document one word at a time. Thus, I changed my keybindings for “DesktopLeft” and “DesktopRight” to C-A-Left (Control key + Alt key + Left cursor key) and C-A-Right (Control key + Alt key + Right arrow key). This preserves the proper functioning of the original keystroke combination for use in my word processing programs.

Another dubious keybinding (for me, at least) is the definition of the C-w (Control key + “w” key) to execute the “ShowMenu” function, that brings up a menu displaying all of the desktops and the applications running on each one. I typically use the C-w key to close out child windows in an application, like individual tabs in my web browsers. I simply changed my keybindings so that C-A-w executes the “ShowMenu” function, preserving the use of C-w for what I normally use it for.

Additionally, many keybindings are defined to use the Super key (a.k.a. the Windows key). However, my IBM T23 does not have a Super key, so those keystroke combinations are impossible for me to use. Instead, I changed those keybindings that use the Super key to keybindings that use Control + Alt.

One real beauty of the “keyboard” section of the rc.xml file is that I can change the keystroke combinations used so that they are more closely tailored to how I tend to work with my computer, and to better fit the configuration of my hardware. For the predefined keybindings that use the the Super key to launch programs I never or rarely use, or that perform tasks that I customarily don’t perform from the keyboard, I simply left them unchanged.

Another real beauty of the “keyboard” section is that if there is a bash script you like to routinely run, you can assign it a keybinding so that it is only a keystroke or two away from execution.

I recommend that you study how the keybinding section is set up. It won’t take long before you catch on to the format and start coming up with your own custom keybindings. If you want more information on keybindings, you can visit the Openbox Wiki entry on keybindings, where there is a complete breakdown of all of the keybinding settings. We’ll also be mentioning keybindings later on, in other Openbox articles in The PCLinuxOS Magazine.

Tenth Section: Mouse

Under the “mouse” section of the rc.xml file, you can control most of the settings for how your mouse functions under Openbox. Below is an excerpt from the rc.xml file on my Openbox installation (this section is too long to print in its entirety):

<mouse>

 <dragThreshold>8</dragThreshold>

 

 <doubleClickTime>200</doubleClickTime>

 

 <screenEdgeWarpTime>400</screenEdgeWarpTime>

 

 <context name="Frame">

 <mousebind button="A-Left" action="Press">

 <action name="Focus"/>

 <action name="Raise"/>

 </mousebind>

 <mousebind button="C-A-Left" action="Click">

 <action name="Unshade"/>

 </mousebind>

 <mousebind button="A-Left" action="Drag">

 <action name="Move"/>

 </mousebind>

 <mousebind button="A-Right" action="Press">

 <action name="Focus"/>

 <action name="Raise"/>

 <action name="Unshade"/>

 </mousebind>

Some basic mouse settings, like how fast a double click of the mouse has to occur before it is recognized as a double click, the number of pixels to move the mouse before it is recognized that you are dragging a window or other screen element, or how much time you have to push a window against a screen edge before it warps to the adjacent desktop, are taken care up right up front.

The bulk of the “mouse” section deals with mousebindings. Mousebindings are very, very similar to keybindings, and define what action to take when different mouse buttons are pushed, in combination with certain key presses, depending on the context in which Openbox detected them. The latter is determined by the “context name” setting.

For a full discussion of the settings you can make, check out the Openbox Wiki page on mousebindings. Most users probably won’t find much of a reason to mess around with the mousebindings – unless you are a tweak-aholic, or unless you have the latest, greatest gaming mouse with 56 button combinations.

Eleventh Section: Menu

As you might imagine, the “menu” section controls the behavior of menus on Openbox. Below is the entire menu section from the rc.xml file on my Openbox installation:

<menu>

 

 

 <file>menu.xml</file>

 <hideDelay>200</hideDelay>

 <middle>no</middle>

 <submenuShowDelay>100</submenuShowDelay>

 <applicationIcons>yes</applicationIcons>

</menu>

The first setting, “file,” specifies which file contains the data used to create the application menu in Openbox, which is accessible via a right click on the desktop. You can have multiple menu files, but as the comments above indicate, you have to insure that there are no clashes between menu ids across all of the menu files. Typically, the menu file being specified here resides in your /home/username/.config/openbox folder. There is another menu.xml file in etc/xdg/openbox, but to be totally honest, I cannot see that it is used or where it fits into the picture.

The “hideDelay” setting causes the menu to immediately disappear if you click longer than the specified length of time (default is 200 ms). If you are a “slow mouse clicker,” you may want to specify a longer time. Just remember that 1000 ms equals 1 second, so 500 ms would be one-half of a second. Clicking and releasing the menu for a time less than that specified will cause the menu to continue being displayed when you release the mouse button.

The “middle” setting causes the menus to be center aligned vertically, as opposed to being top aligned. The “submenuShowDelay” and “submenuHideDelay” (not shown) determine the time delay before showing, and subsequently hiding, a submenu. Both values must be less than the “hideDelay” setting, or they are ignored.

With the “applicationsIcons” setting, you can tell Openbox whether or not to show the application icons on the desktop and in the application menu. I have found that this setting has no effect with the right click Openbox application menu, as I’ve never seen any application icons displayed in that menu, regardless of the setting. However, it may play a role when you use a bona fide application launch menu, like that which you get when using the LXDE panel (lxpanel).

One setting not included in the menu section of the rc.xml file on my Openbox installation is the “manageDesktops” setting. This allows you to add or subtract desktops as you need, on the fly, right from the right click Openbox menu. If you are working along, and all of a sudden discover that having another it would help your productivity to have an additional desktop desktop, you can add it right there, on the spot, from the right click Openbox menu. Apparently, the default value for this setting is “yes,” since I have that ability in my right click Openbox menu, despite its absence from the menu section of my rc.xml file.

Twelfth Section: Applications

Under the “applications” section, you can define the behavior of individual applications in Openbox. Below is a copy of the “applications” section of my rc.xml file:

<applications>

 <application name="draklive-install">

 <maximized>true</maximized>

 </application>

 <application name="tint2">

 <layer>below</layer>

 </application>

 … (example deleted)

</applications>

This section of your rc.xml file can easily become quite a bit larger than what is shown here. With the settings in this section, I can specify positioning, desktops, display states, layers and a whole host of other options, for each of the applications you typically run.

Call me a creature of habit if you will, but I’ve gotten into the habit of having my web browser window on desktop 1, and my open IRC chat client on desktop 3. I do this on all of my computers, all running different versions of PCLinuxOS. It just one thing that helps keep me organized when I have several applications open at the same time.

So, if I click on a link in IRC, I really don’t want Firefox to open up on desktop 3. It puts a chink in my routine. With the settings in the “applications” section of my rc.xml file, it’s very easy to restrict Firefox to opening only on desktop 1.

In order to provide Openbox the information it needs, it’s a good idea to run a command line program, called obxprop. When you run obxprop, the cursor will change to a cross-hair. Move your cursor over the window you want information on, and click your cursor. Immediately, you will be presented with a lot of information, as in the image below:

You are looking for the information highlighted in the red box. You need to specify either the _OB_APP_CLASS or _OB_APP_NAME, or both in order for Openbox to find the proper application. You can shorten the output by entering obxprop | grep "^_OB_APP" to list only the information needed by Openbox.

Now that you have the information that Openbox needs, you can start to set up your application specific controls. First, we need to tell Openbox which application we want to make rules for. We do this by specifying the name and/or class of the application, with the information provided by obxprop.

<application name="chromium-browser" class=”Chromium-browser>

Let’s say we always want Chromium to start up on desktop 1. We next need to enter the following:

<desktop>1</desktop>

If we wanted to make sure that it always opened up maximized, we’d enter another line:

<maximized>true</maximized>

Finally, we close out the “application” tag:

</application>

You can also use wildcard characters in the name and class fields. A “*” matches any number of characters, while a “?” matches any single character.

There are several options available when making application specific settings or rules. Refer to the Openbox Wiki section on per application settings to see examples on how to apply those rules and settings. You can also take a look at your rc.xml file to see some examples of how to set up application specific rules and settings.

Thirteenth Section: Coordinates

This section of the rc.xml file is not included in my Openbox installation. As such, this section can be considered to be optional, since everything works just fine without it. If you are interested in learning more about the coordinates section of the rc.xml file, I’ll refer you to the coordinates section of the Openbox Wiki.

Summary

As you can see, the rc.xml file exerts a lot of control over the behavior of Openbox. Once you get the hang of the XML format of the file, making changes is very easy. Because it is so easy to make changes, and because it offers so many options, you have a lot of leeway in customizing the behavior of your Openbox installation. You can truly tailor and trim your Openbox installation to be uniquely yours.