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.