Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Document last modified: Tue, 15 Jun 2010, 20:28 UTC
Parents: BlackboxDocumentation/

Blackbox Documentation/Blackbox Background

This page explains a wildly popular issue which people seem to ask about again and again: "how do I change the background image?" It also clarifies issues regarding the Blackbox desktop and attempts to explain how you can avoid conflicts with other X applications in regard to the screen background.

1 The root window
2 Controlling the root window
3 Root window conflicts
4 Blackbox and the root window
5 How do I change my freakin' wallpaper?
6 Root window tools
7 Common pitfalls

1) The root window

First of all, we need some info about background setting in X (which is where Blackbox is mostly used). As you may or may not know, on the X desktop there's an "invisible" window present at all times, called the root window. This window is the same size as the screen and stays absolutely below all other windows at all times.

The root window can be used for several main purposes:

So what X applications (such as Blackbox) do is this: they load an image on the root window, or they catch and act upon mouse clicks.

The default appearance of the root window depends on X, can vary from installation to installation and can be controlled from the X configuration file. The most widely encountered default, however, is a black and white dot pattern.

2) Controlling the root window

The issue of controlling the root window has two parts: who loads an image on it, and who catches the mouse clicks.

After an application loads an image or a color pattern on the root window, it will be preserved until another application changes it. There's no way to "protect" the root window in favor of one particular application. In other words, the image on the root window is not an "active" setting that can be monitored, but a "passive" setting that can be set and re-set at any time.

As far as the background image is concerned, it comes down to making sure that the applications you choose to run play nicely together and that only the one you want gets to set the background image. Unlike catching mouse clicks, there's no leeway regarding the background image; someone will set it, and that's it. Whoever set it most recently will have "won".

Catching mouse clicks is a somewhat different issue, in that smart applications will have options that allow mouse clicks to "pass through" to another application. In other words, applications may choose to cut each other some slack.

An example: the RoX "pinboard" is a desktop application which can display wallpapers, show icons/shortcuts and pop-up RoX-specific menus when you click on the desktop. If you use the RoX pinboard with Blackbox, it will override the Blackbox background and the Blackbox root and workspace menus. However, it has options that will allow mouse clicks to get through to Blackbox, which means you get the Blackbox menus instead of the RoX ones.

For completion's sake, you should know that desktop icons are usually implemented as a "trick": they are not part of the root window, they are small semi-transparent windows which hover over the root window but stay below all other windows.

3) Root window conflicts

As you may have guessed, sometimes more than one application will attempt to take control of the root window. This will result in only one of their settings making their way onto the desktop, usually depending on what application applied its changes last (for wallpapers) or first (for mouse clicks).

Sometimes, applications may use really sneaky tricks, such as covering the root window with their own transparent window, to make up for not being able to catch the clicks on the real one.

The solution to all this potential mess is to be careful which desktop applications you use, and to learn the settings that allow you to control their behaviour.

As far as Blackbox is concerned, you should take note of the possibility of such conflicts existing. More to the point, if you find yourself wondering why you see another wallpaper instead of the one your Blackbox style should set, or why your mouse clicks don't produce the Blackbox menus, ask yourself: is an application other than Blackbox messing with the root window?

4) Blackbox and the root window

Being a window manager (ie. a basic, low-level X application), Blackbox deals with the root window as follows:

If you use other desktop applications besides Blackbox, they will provide their own settings for changing the background appearance. Sometimes they will also provide you with options allowing mouse clicks to pass down to Blackbox or not.

5) How do I change my freakin' wallpaper?

In order to change your Blackbox background aka wallpaper, usually one does this by switching styles. Each style contains its own rootCommand, which in turn uses one of the root window tools to load an image or a color pattern.

If you want to make your changes more permanent, you can edit your favorite style and put your preferred root-setting command as its rootCommand. Or, you can edit all the usual styles and put a common, generic command there, such as a shell script called mybg, in which you can put whatever command you want.

Tip: To find out where the current style file is located open your rc file (usually ~/.blackboxrc with a text editor, and look for session.styleFile.
Tip: Starting with version 0.70 final you can edit your rc file (the main Blackbox preferences file) and change the rootCommand there. If set to any non-empty value, the command in the rc file will override that of any style. This is an effective way of always keeping your own background setting.

You can also use one of the tools below to manually change the background, but be aware that these settings are not permanent and will be lost when you restart X or Blackbox.

If you use another desktop application with Blackbox, then go check out its specific settings.

Don't forget to read the common pitfall section below!

6) Root window tools

Quick and dirty examples:

bsetbg -full /path/to/image.jpg
bsetroot -gradient gradientdiagonal -from rgb:9a/97/94 -to rgb:7a/77/74

bsetbg is a tool provided with Blackbox which is designed to allow all Blackbox styles to use a standard command to set the background image/pattern. The command that is actually used depends on the settings in the ~/.bsetbgrc file. This means, for instance, that if you have Enlightenment installed and would prefer to use the Esetroot command to set the background image, you could just change the ~/.bsetbgrc file and every style would then use Esetroot. By running bsetbg -g and redirecting the output to ~/.bsetbgrc, a sample configuration file can be created. Following is a snippet from a simple ~/.bsetbgrc:

CENTER="wmsetbg -e"
FULL="wmsetbg -s -S"
TILE="wmsetbg -t"
DEFAULT="wmsetbg -e"

This is fairly self-explanatory. Simply put your preferred background setting command with the appropriate command line arguments to either center, tile, or stretch the image to the entire screen. The default setting is used if bsetbg isn't passed any arguments. It's also possible to pass bsetbg arguments used by bsetroot.

More information can be found in the manpage*.


There are a couple of "basic" tools for controlling the root window. They are command-line tools that can be run from a terminal. xsetroot comes with X. bsetroot is an enhanced version that comes with Blackbox, and allows you to load images, do gradients and so on. See the man pages for bsetroot* and xsetroot*.


Some image-viewing utilities, such as GQView*, will allow you to throw an image onto the desktop as a wallpaper. Please remember that such modifications are not permanent.

7) Common pitfalls

A rather common mistake is setting a background image in your ~/.xinitrc. This will get overwritten as soon as Blackbox (or another desktop application) starts up and sets their own.

This happens because the wallpaper is never remembered anywhere, as far as X is concerned. If you restart X, it's gone. If you set another wallpaper, it changes as.

Most of the time you see the same wallpaper simply because you use the same desktop application, and that application in turn remembers the wallpaper for you. If you want to control the desktop, control the applications that control the desktop.


eXTReMe Tracker Hosted by SourceForge.net
Document last modified: Tue, 15 Jun 2010, 20:28 UTC
Home | Sitemap | Last changes RSS Feed | Wiki help | Wiki tools | SandBox
Preferences | Edit this page | View source | Page history | Referrers
Hosted by SourceForge. Powered by Wikki Tikki Tavi. About the website. Terms of use.