Adding debian version 3.5.0-4.
[debian/openbox.git] / debian / docs / config.html
1 <a href="toc.html">Table of Contents</a>
2
3 <h1>Configuring Openbox</h1>
4
5 <h2><a name="locations"></a>File locations</h2>
6
7 <p>
8 When looking for its configuration files (<b>rc.xml</b>, <b>menu.xml</b>), Openbox follows the <a href="http://www.freedesktop.org/standards/basedir-spec/">freedesktop.org base-dir specification</a>. You can read the short specification for all the details. However, the end default result will be as follows.
9 </p>
10
11 <p>
12 First Openbox will try for your config files in <b>$HOME/.config/openbox/</b>. If it is unable to find them there, then it will try the system configuration dir (use <b>./configure --sysconfdir</b> to modify this when configuring the Openbox build. If you installed Openbox from a distribution package, then it will most likely be looking in <b>/etc/xdg/openbox/</b>. If you built Openbox yourself and do not specify --sysconfdir, then it will be looking in <b>/usr/local/etc/xdg/openbox</b>.
13 </p>
14
15 <h2><a name="options"></a>Options</h2>
16
17 <p>
18 Most users will want to use the ObConf tool to configure Openbox. You can
19 launch the tool by running:
20 </p>
21
22 <blockquote>
23 % <b>obconf</b>
24 </blockquote>
25
26 <p>
27 See <a href="http://openbox.org/obconf">the ObConf webpage</a> to get this handy tool.
28 </p>
29
30 <p>
31 If you don't want/have ObConf, you can edit the configuration by hand. The
32 recommended procedure for this is to copy the system config to
33 <b>$HOME/.config/openbox/</b> and edit that to your liking.
34 </p>
35
36 <h2><a name="menus"></a>Menus</h2>
37
38 <p>
39 Menus are searched for in the directories given in the <a href="#locations">File locations</a> section.
40 </p>
41
42 <p>
43 You can specify the names of the menu files to load in the <b>rc.xml</b>'s <b>menu</b> section. Absolute paths can also be used to look outside of the default search paths. For example:
44 </p>
45
46 <blockquote>
47 &lt;menu&gt;<br />
48 &nbsp;&nbsp;&lt;file&gt;mymenu.xml&lt;/file&gt;<br />
49 &nbsp;&nbsp;&lt;file&gt;myothermenu.xml&lt;/file&gt;<br />
50 &nbsp;&nbsp;&lt;file&gt;/etc/system/openboxmenu.xml&lt;/file&gt;<br />
51 &lt;/menu&gt;
52 </blockquote>
53
54 <p>
55 If no menus are specified in the <b>rc.xml</b>, Openbox will look for <b>menu.xml</b>.
56 </p>
57
58 <h2><a name="themes"></a>Themes</h2>
59
60 <p>
61 First off, the theme format is not backwards compatible with Openbox2/Blackbox/Fluxbox themes. The <b>themeupdate.py</b> script included in the Openbox distribution can be used to aid in porting Openbox2/Blackbox/Fluxbox themes over.
62 </p>
63
64 <h3>Paths</h3>
65
66 <p>
67 Themes are searched for in the data directories specified in the <b>base-dir spec</b> mentioned in the <a href="#locations">File locations</a> section. In addition to these paths, Openbox also looks in <b>$HOME/.themes/</b> for backwards compatibility with existing applications. This means, by default, the following directories will be searched in order: <b>$HOME/.themes/</b>, <b>$HOME/.local/share/themes/</b>, <b>$PREFIX/share/themes/</b>. This means that Openbox themes can now be bundled with other themes (such as GTK+ themes).
68 </p>
69
70 <h3>Structure</h3>
71
72 <p>
73 Each theme is self-contained within its own directory. The theme file itself is a file named <b>themerc</b> inside the theme's <b>openbox-3</b> directory. So for a theme named "Foo", its directory layout might look like this:
74 </p>
75 <blockquote>
76 <b>Foo/openbox-3/themerc</b><br />
77 Foo/openbox-3/max.xbm<br />
78 Foo/openbox-3/close.xbm
79 </blockquote>
80 <p>
81 We'll get to the xbms later.
82 </p>
83
84 <h3>Fonts</h3>
85
86 <p>
87 Fonts are each specified through a single .font property. Different fonts can be specified for focused and unfocused windows. The available font properties are:
88 </p>
89 <ul>
90 <li>window.label.focus.font</li>
91 <li>window.label.unfocus.font</li>
92 <li>menu.title.font</li>
93 <li>menu.items.font</li>
94 </ul>
95 <p>
96 This property is an Xft/Fontconfig font string. It is highly recommended that when specifying this, you specify the size of the font by pixelsize, not by pointsize. Some details on building the required font string can be found in this <a href="http://keithp.com/~keithp/render/Xft.tutorial">Xft tutorial</a>.
97 </p>
98
99 <p>
100 There are a couple extensions to the font string's options for openbox:
101 </p>
102 <ul>
103 <li>shadow [boolean] (defaults to off)</li>
104 <li>shadowoffset [integer] (defaults to 1)</li>
105 <li>shadowtint [integer] (defaults to 25%)</li>
106 </ul>
107
108 <p>
109 Example:
110 </p>
111 <blockquote>
112 window.focus.font: arial,sans:bold:pixelsize=12:shadow=y
113 </blockquote>
114
115 <h3>Titlebar Button Bitmaps</h3>
116
117 <p>
118 A number of X Bitmap (xbm) files are used to specify the look of the titlebar buttons. These buttons are all found
119 under the <b>Theme/openbox-3/</b> directory. The following names are looked for:
120 </p>
121
122 <ul>
123 <li>max.xbm - maximized button</li>
124 <li>max_toggled.xbm - maximized button toggled</li>
125 <li>max_disabled.xbm - maximized button disabled</li>
126 <li>max_hover.xbm - maximized button while being hovered over</li>
127 <li>max_pressed.xbm - maximized button while being pressed</li>
128 <li>iconify.xbm - iconify button</li>
129 <li>iconify_disabled.xbm - iconify button disabled</li>
130 <li>iconify_hover.xbm - iconify button while being hovered over</li>
131 <li>iconify_pressed.xbm - iconify button while being pressed</li>
132 <li>desk.xbm - all-desktops button</li>
133 <li>desk_toggled.xbm - all-desktops button toggled</li>
134 <li>desk_disabled.xbm - all-desktops button disabled</li>
135 <li>desk_hover.xbm - all-desktops button while being hovered over</li>
136 <li>desk_pressed.xbm - all-desktops button while being pressed</li>
137 <li>shade.xbm - shade button</li>
138 <li>shade_toggled.xbm - shade button toggled</li>
139 <li>shade_disabled.xbm - shade button disabled</li>
140 <li>shade_hover.xbm - shade button while being hovered over</li>
141 <li>shade_pressed.xbm - shade button while being pressed</li>
142 <li>close.xbm - close button</li>
143 <li>close_disabled.xbm - close button disabled</li>
144 <li>close_hover.xbm - close button while being hovered over</li>
145 <li>close_pressed.xbm - close button while being pressed</li>
146 <li>bullet.xbm - submenu bullet in menus</li>
147 </ul>
148
149 <h3>Background</h3>
150
151 <p>
152 Themes do not provide a means for setting the background. There are many tools around for setting the root image (xsetroot, Esetroot, Rox, Gnome, Kde, etc!) so there is no point in rewriting those for Openbox.
153 </p>
154
155 <h3>Etc</h3>
156
157 <p>
158 A more detailed description and list of all the theme elements will be forthcoming. In the meantime, examples found in the distribution can be used for documentation.
159 </p>
160
161 <a href="toc.html">Table of Contents</a>