ignore the openbox3 binary
[dana/openbox.git] / data / README.style
1 Creating a new style (aka "theme"):
2 -----------------------------------
3 After getting Openbox up and running, the next thing you want to do is change
4 the colors/fonts/etc. on the screen.  Openbox uses a "style" to read its
5 configuration information.  A style in Openbox consists of X resources placed
6 in a file.  Just like the menu file (see README.menu), the style file can be
7 put anywhere on the filesystem; as long as you have read access to the file,
8 Openbox can use it.
9
10 First, we need to decide where to put our style file, and what to name it.
11 I recommend using the naming scheme described on http://bb.classic.themes.org/
12 when creating styles.
13
14 Let's get started.  Let's put our new style into a file named `results.'
15 Following the themes.org naming scheme, this file will go into
16 .openbox/styles.  Same as with the menu file, we use our favorite text editor
17 to create the new style.
18
19 X resources consist of a key and a value.  The key is constructed of several
20 smaller keys, delimited by a period (`.').  Keys may also contain a star (`*')
21 to serve as a wildcard, which means that one line of typed text will match
22 several keys.  This is useful for styles that are based on one or two colors.
23
24 Openbox allows you to configure it's three main components: the toolbar, the
25 menus and the window decorations.  Lets begin by creating a style for our
26 toolbar.
27
28 First we need to define a "texture" for the toolbar and it's components.
29 Textures tell Openbox how to mold or shape the colors we supply.
30
31 A texture is comprised of the following elements:
32
33         Raised / Sunken / Flat          give the component a raised, sunken
34                                         or flat appearance (respectively)
35
36         Solid / Gradient                tell Openbox whether to draw a solid
37                                         or gradiented texture
38
39         Interlaced                      tells Openbox to interlace a
40                                         gradient (and gradient ONLY) texture
41
42         Bevel1 / Bevel2                 tells Openbox which type of bevel
43                                         to use.
44
45 NOTE on Bevel1 / Bevel2:
46
47 Bevel1 is the default bevel.  The shading is placed on the edge of the image.
48 Bevel2 is an alternative.  The shading is placed one pixel in from the edge
49 of the image.
50
51 Now that we understand that, let's define the textures for the toolbar.  The
52 toolbar has a main frame, buttons, two labels and a clock label.  The buttons
53 have 2 states, so we provide textures for both the normal and the pressed
54 state.
55
56 ...
57 toolbar:                        Raised Diagonal Gradient Bevel1
58 toolbar.button:                 Raised Diagonal Gradient Bevel1
59 toolbar.button.pressed:         Sunken Diagonal Interlaced Gradient Bevel1
60 toolbar.clock:                  Flat Interlaced Gradient
61 toolbar.label:                  Flat Interlaced Gradient
62 ...
63
64 NOTE: the texture strings don't have to be capitalized like they did in
65 previous versions.  They are still placed in capitals here, because things like
66 the bbtools still use the old method.
67
68 Next we define colors for the textures.  Colors can be any valid X colorname
69 (from the RGB database) or it can be a color specifier, as described by
70 'man 1 X.'
71
72 Let's see how our file looks after adding colors:
73
74 ...
75 toolbar:                        Raised Diagonal Gradient Bevel1
76 toolbar.button:                 Raised Diagonal Gradient Bevel1
77 toolbar.button.pressed:         Sunken Diagonal Interlaced Gradient Bevel1
78 toolbar.clock:                  Flat Interlaced Gradient
79 toolbar.label:                  Flat Interlaced Gradient
80
81 toolbar.color:                  rgb:8/8/7
82 toolbar.colorTo:                grey20
83 toolbar.button.color:           grey
84 toolbar.button.colorTo:         grey20
85 toolbar.button.pressed.color:   rgb:4/4/38
86 toolbar.button.pressed.colorTo: rgb:f/f/d
87 toolbar.clock.color:            grey20
88 toolbar.clock.colorTo:          rgb:8/8/7
89 toolbar.label.color:            grey20
90 toolbar.label.colorTo:          rgb:8/8/7
91 toolbar.textColor:              grey85
92 ...
93
94 As you have noticed, all textures have a color and a colorTo key.  These keys
95 are required for gradient images.  For solids, only color is needed.  You will
96 also notice that we have supplied the color for the text on the toolbar.  Not
97 all textures have a text color, just certain base textures.
98
99 Next, let's move onto the menus.  Since Openbox was written in C++, all of
100 the menus used in it are subclasses of one generic base class.  Openbox reads
101 the style for the configuration for that base class, which applies to all
102 the menus used in Openbox.
103
104 The menu has two main parts, the title and the frame.  There is nothing
105 visible under them, so we only configure these two components.  The menu frame
106 and menu title BOTH have a configurable text color, and the menu frame has a
107 highlight color and the corresponding highlighted text color key. Let's assign
108 some textures and colors to our menu, and see what our style file looks like
109 so far:
110
111 ...
112 toolbar:                        Raised Diagonal Gradient Bevel1
113 toolbar.button:                 Raised Diagonal Gradient Bevel1
114 toolbar.button.pressed:         Sunken Diagonal Interlaced Gradient Bevel1
115 toolbar.clock:                  Flat Interlaced Gradient
116 toolbar.label:                  Flat Interlaced Gradient
117
118 toolbar.color:                  rgb:8/8/7
119 toolbar.colorTo:                grey20
120 toolbar.button.color:           grey
121 toolbar.button.colorTo:         grey20
122 toolbar.button.pressed.color:   rgb:4/4/38
123 toolbar.button.pressed.colorTo: rgb:f/f/d
124 toolbar.clock.color:            grey20
125 toolbar.clock.colorTo:          rgb:8/8/7
126 toolbar.label.color:            grey20
127 toolbar.label.colorTo:          rgb:8/8/7
128 toolbar.textColor:              grey85
129
130 menu.title:                     Raised Diagonal Interlaced Gradient Bevel1
131 menu.frame:                     Raised Diagonal Gradient Bevel1
132
133 menu.title.color:               grey20
134 menu.title.colorTo:             rgb:8/8/7
135 menu.title.textColor:           grey85
136 menu.frame.color:               rgb:8/8/7
137 menu.frame.colorTo:             grey10
138 menu.frame.textColor:           white
139 menu.frame.highlightColor:      grey85
140 menu.frame.hiTextColor:         grey20
141 ...
142
143 Next, we need to configure our windows.  Windows are like buttons, they have
144 two states, focused and unfocused.  There for we define a separate texture
145 for unfocused windows and focused windows.  The buttons on the titlebar
146 are focus dependant also, so we need to configure them as well.  The buttons
147 only have one "pressed" state, so we only have to define that once, instead of
148 having a focus.pressed state and an unfocus.pressed state.  The window frame
149 is the thin border around the client window. Let's be sure to catch it as well.
150
151 After adding the window config, our style now looks like this:
152
153 ...
154
155 toolbar:                        Raised Diagonal Gradient Bevel1
156 toolbar.button:                 Raised Diagonal Gradient Bevel1
157 toolbar.button.pressed:         Sunken Diagonal Interlaced Gradient Bevel1
158 toolbar.clock:                  Flat Interlaced Gradient
159 toolbar.label:                  Flat Interlaced Gradient
160
161 toolbar.color:                  rgb:8/8/7
162 toolbar.colorTo:                grey20
163 toolbar.button.color:           grey
164 toolbar.button.colorTo:         grey20
165 toolbar.button.pressed.color:   rgb:4/4/38
166 toolbar.button.pressed.colorTo: rgb:f/f/d
167 toolbar.clock.color:            grey20
168 toolbar.clock.colorTo:          rgb:8/8/7
169 toolbar.label.color:            grey20
170 toolbar.label.colorTo:          rgb:8/8/7
171 toolbar.textColor:              grey85
172
173 menu.title:                     Raised Diagonal Interlaced Gradient Bevel1
174 menu.frame:                     Raised Diagonal Gradient Bevel1
175
176 menu.title.color:               grey20
177 menu.title.colorTo:             rgb:8/8/7
178 menu.title.textColor:           grey85
179 menu.frame.color:               rgb:8/8/7
180 menu.frame.colorTo:             grey10
181 menu.frame.textColor:           white
182 menu.frame.highlightColor:      grey85
183 menu.frame.hiTextColor:         grey20
184
185 window.focus:                   Raised Diagonal Interlaced Gradient Bevel1
186 window.focus.button:            Raised Diagonal Gradient Bevel1
187 window.unfocus:                 Raised Diagonal Gradient Bevel1
188 window.unfocus.button:          Sunken Diagonal Gradient Bevel1
189 window.button.pressed:          Flat Diagonal Interlaced Gradient
190 window.frame:                   Raised Solid Bevel1
191
192 window.focus.color:             grey
193 window.focus.colorTo:           grey20
194 window.focus.textColor:         grey85
195 window.focus.button.color:      grey
196 window.focus.button.colorTo:    grey20
197 window.unfocus.color:           rgb:8/8/7
198 window.unfocus.colorTo:         grey20
199 window.unfocus.textColor:       grey
200 window.unfocus.button.color:    grey20
201 window.unfocus.button.colorTo:  grey
202 window.button.pressed.color:    rgb:4/4/38
203 window.button.pressed.colorTo:  rgb:f/f/d
204 window.frame.color:             grey85
205 ...
206
207 Now all we have to do is finish off the style with a few miscellanous options.
208 These include the title and menu fonts/justification, border color, bevel and
209 handle widths, window move style and the root command.
210
211 Fonts must be a valid X11 font screen, or a valid font alias.  Use a utility
212 like `xfontsel' (and others) to preview fonts.  Also use the utility
213 `xlsfonts' to spit out all the current X font names and aliases stored in
214 the X server.
215
216 Justification can be one of three things:  LeftJustify, CenterJustify or
217 RightJustify.
218
219 The border color is the color applied to the 1 pixel border around the menu
220 frame/title and the window titlebar/buttons/handle/etc.  Setting this color
221 can have drastic effects on your style, so don't just leave it set to `black'
222 all the time.  ;)
223
224 The bevel and handle widths control the size and spacing of decorations in
225 Openbox.  The larger the number, the more space Openbox takes up.
226
227 The window move style tells Openbox how to move windows when you drag them
228 with your mouse.  There are two options for it: Opaque or Wire.
229
230 The root command is the command run every time the style is loaded (either at
231 startup or after a reconfigure/style-change).  It is used to run a program
232 like xv, Esetroot, wmsetbg, etc. to set an image/color/pattern on the root
233 window.  Just supply a command and it will be run.
234
235 Also, as a note, an X resource file can have comments.  Precede the line with
236 and exclamation mark `!' and the rest of the line will be ignored.
237
238 Let's finish off the details and take a look at our finished style:
239
240 ...
241 ! Results - theme for Openbox
242 ! by Brad Hughes bhughes@tcac.net
243
244 toolbar:                        Raised Diagonal Gradient Bevel1
245 toolbar.button:                 Raised Diagonal Gradient Bevel1
246 toolbar.button.pressed:         Sunken Diagonal Interlaced Gradient Bevel1
247 toolbar.clock:                  Flat Interlaced Gradient
248 toolbar.label:                  Flat Interlaced Gradient
249
250 ! toolbar colors
251 toolbar.color:                  rgb:8/8/7
252 toolbar.colorTo:                grey20
253 toolbar.button.color:           grey
254 toolbar.button.colorTo:         grey20
255 toolbar.button.pressed.color:   rgb:4/4/38
256 toolbar.button.pressed.colorTo: rgb:f/f/d
257 toolbar.clock.color:            grey20
258 toolbar.clock.colorTo:          rgb:8/8/7
259 toolbar.label.color:            grey20
260 toolbar.label.colorTo:          rgb:8/8/7
261 toolbar.textColor:              grey85
262
263 ! menu textures
264 menu.title:                     Raised Diagonal Interlaced Gradient Bevel1
265 menu.frame:                     Raised Diagonal Gradient Bevel1
266
267 ! menu colors
268 menu.title.color:               grey20
269 menu.title.colorTo:             rgb:8/8/7
270 menu.title.textColor:           grey85
271 menu.frame.color:               rgb:8/8/7
272 menu.frame.colorTo:             grey10
273 menu.frame.textColor:           white
274 menu.frame.highlightColor:      grey85
275 menu.frame.hiTextColor:         grey20
276
277 ! window textures
278 window.focus:                   Raised Diagonal Interlaced Gradient Bevel1
279 window.focus.button:            Raised Diagonal Gradient Bevel1
280 window.unfocus:                 Raised Diagonal Gradient Bevel1
281 window.unfocus.button:          Sunken Diagonal Gradient Bevel1
282 window.button.pressed:          Flat Diagonal Interlaced Gradient
283 window.frame:                   Raised Solid Bevel1
284
285 ! window colors
286 window.focus.color:             grey
287 window.focus.colorTo:           grey20
288 window.focus.textColor:         grey85
289 window.focus.button.color:      grey
290 window.focus.button.colorTo:    grey20
291 window.unfocus.color:           rgb:8/8/7
292 window.unfocus.colorTo:         grey20
293 window.unfocus.textColor:       grey
294 window.unfocus.button.color:    grey20
295 window.unfocus.button.colorTo:  grey
296 window.button.pressed.color:    rgb:4/4/38
297 window.button.pressed.colorTo:  rgb:f/f/d
298 window.frame.color:             grey85
299
300 ! misc...
301 borderColor:                    rgb:2/2/1c
302
303 moveStyle:                      Opaque
304
305 menuJustify:                    CenterJustify
306 titleJustify:                   CenterJustify
307
308 bevelWidth:                     2
309 handleWidth:                    4
310
311 menuFont:                       lucidasans-10
312 titleFont:                      lucidasans-bold-10
313
314 rootCommand:                    bsetroot -mod 4 4 -fg rgb:6/6/5c -bg grey20
315 ...
316
317 Alright!  Our style is finished.  Let's see how the sucker looks.  First we
318 need to tell Openbox to use the new style.  The way to do that is to edit
319 your menu (refer to README.menu for this) and add:
320
321 [style] (Results) {~/.openbox/styles/results}
322
323 somewhere in our menu.  Taking advantage of Openbox' automagic menu updates,
324 all we have to do is close and reopen the root menu and our new style entry
325 will be visible.  Select it and Openbox will apply the new style we just
326 created.