aboutsummaryrefslogtreecommitdiff
path: root/doc/asciidoc/fluxbox-style.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/asciidoc/fluxbox-style.txt')
-rw-r--r--doc/asciidoc/fluxbox-style.txt484
1 files changed, 484 insertions, 0 deletions
diff --git a/doc/asciidoc/fluxbox-style.txt b/doc/asciidoc/fluxbox-style.txt
new file mode 100644
index 0000000..ab325ae
--- /dev/null
+++ b/doc/asciidoc/fluxbox-style.txt
@@ -0,0 +1,484 @@
1fluxstyle(1)
2============
3Henrik Kinnunen <fluxgen@fluxbox(1).org>
4v1.0rc2 3rd October 2006
5
6NAME
7----
8fluxstyle - A comprehensive look at styles/themes for fluxbox(1).
9
10SYNOPSIS
11--------
12
13DESCRIPTION
14-----------
15What is a Style?
16
17Styles, sometimes referred to as Themes, are a graphical overlay for the
18fluxbox(1) window manager. If you wanted to get to know fluxbox, the styles
19would be the 'look' of the 'look and feel'.
20
21Styles are simple ASCII text files that tell fluxbox(1) how to generate the
22appearance of different components of the window manager. The default
23installation of fluxbox(1) is shipped with many classic examples that show a
24great deal of what one could do. To use one of the standard styles navigate to
25the 'System Styles' menu under your main fluxbox(1) menu.
26
27fluxbox(1) uses its own graphics class to render its images on the fly. By
28using styles you can determine, at a great level of configurability, what your
29desktop will look like. Since fluxbox(1) was derived from blackbox many often
30wonder if old themes will work on the latest releases of fluxbox(1). Well they
31basically do, but you will have to tune them since the fluxbox(1) code has
32changed quite a bit since the initial grab.
33
34STRUCTURE
35---------
36A style is made up of a few major components which then have their own
37sub-directives. The major components are as follows:
38
39The 'window.\*' directives control the appearance of the window frames,
40window.tab.* controls the appearance of the window tabs, 'menu.\*' controls
41the appearance of the popup menu that you see when you right click on the
42desktop. 'toolbar.\*' is the bar you will see at the top or bottom of your
43screen. Finally the 'slit.\*' has options you can use to customize the
44appearance of the slit. However if you don't set the slit directives
45specifically, the slit's appearance is controlled by the toolbar
46directives instead.
47
48To understand how the style mechanism works, it is nice to know a little about
49how X11 resources work. X11 resources consist of a key and a value. The key is
50constructed of several smaller keys (sometimes referred to as children),
51delimited by a period (.). Keys may also contain an asterisk (\*)
52to serve as a wildcard, which means that one line of text will match
53several keys. This is useful for styles that are based on one or two
54colors.
55
56A more complete reference to this can be found in X(7), section 'RESOURCES'.
57
58LOCATION
59--------
60There are many places to store your styles, the most common is in your
61'~/.fluxbox/styles' directory. The initial installation will place the default
62styles in '/usr/share/fluxbox/styles' providing a basic usable configuration.
63
64When creating your own style, create a directory (normally the name of your
65style) in '~/.fluxbox/styles/' (If the 'styles' directory doesn't exist,
66create that also). While there isn't an official structure, it is
67common to create a directory named after your style and place your
68pixmaps directory (if required) in there along with a file called
69theme.cfg (may also be named style.cfg). This file is where you will
70construct your style using the components covered later in this manual
71page. An example of steps taken when beginning a style project of your
72own may look like:
73
74 $ cd
75 $ mkdir -p ~/.fluxbox/styles/YourStyle/pixmaps
76 $ cd ~/.fluxbox/styles/YourStyle
77 $ nano theme.cfg
78
79Output of a packaged style should look like the following:
80
81 $ cd
82 $ tar -tjvf YourStyle.tar.bz2
83 .fluxbox/styles/YourStyle/theme.cfg
84 .fluxbox/styles/YourStyle/pixmaps
85 .fluxbox/styles/YourStyle/pixmaps/stick.xpm
86 ...
87
88Of course, all of these are just preferences, fluxbox(1) allows for the
89customization of many things, including how you handle your styles. Just
90remember, however, that if you plan to distribute your style you may find
91some community bickering if you don't follow practices. :)
92
93CREATING YOUR STYLE
94-------------------
95As discussed above, fluxbox(1) allows you to configure its four main components:
96the toolbar, menus, slit and window decorations. Remember that you can
97customize the slit with its own directives, otherwise the slit will take the
98appearance of the toolbar.
99
100Here are some quick examples to illustrate basic syntax:
101
102 toolbar.clock.color: green
103
104This sets the color resource of the toolbar clock to 'green'. Another example:
105
106 menu*color: rgb:3/4/5
107
108This sets the color resource of the menu and all of its 'children' to
109`rgb:3/4/5'. (For a description of color names, see X(1).) So this one also
110applies to 'menu.title.color' and 'menu.frame.color'. And with
111
112 *font: -b&h-lucida-medium-r-normal-*-*-140-*
113
114you set the font resource for all keys to this font name all at once (For
115information about the fonts installed on your system, you can use a
116program like xfontsel(1), gtkfontsel, or xlsfonts(1).)
117
118In the last example you will notice the wildcard (\*) before font. In a Fluxbox
119style you can set a value with a wildcard. The example means that every font
120in the style will be what is specified. You can do this with any
121component/value. For example if you wanted all of the text to be one color you
122would do:
123
124 *textColor: rgb:3/4/5
125
126This means that you can setup a very simple style with very few properties.
127See the EXAMPLES below for an example of this in practice. fluxbox(1) also allows
128you to override wildcards in your style. Lets take our example above and add
129an override for the toolbar.clock.textColor component:
130
131 *textColor: rgb:3/4/5
132 toolbar.clock.textColor: rgb:255/0/0
133
134With that all of the text will be 'rgb:3/4/5' except the toolbar clock text
135which will be 'rgb:255/0/0'.
136
137Now what makes fluxbox(1) so spectacular is its ability to render textures on the
138fly. A texture is a fillpattern that you see on some styles. Texture
139descriptions are specified directly to the key that they should apply to,
140e.g.:
141
142 toolbar.clock: Raised Gradient Diagonal Bevel1
143 toolbar.clock.color: rgb:8/6/4
144 toolbar.clock.colorTo: rgb:4/3/2
145
146Don't worry, we will explain what these mean. A texture description consists
147of up to five fields, which are as follows:
148
149.Flat | Raised | Sunken
150gives the component either a flat, raised or sunken appearance.
151
152.Gradient | Solid
153tells fluxbox(1) to draw either a solid color or a gradient texture.
154
155.Horizontal | Vertical | Diagonal | Crossdiagonal | Pipecross | Elliptic | Rectangle | Pyramid
156Select one of these texture types. They only work when *Gradient* is specified.
157
158.Interlaced
159tells fluxbox(1) to interlace the texture (darken every other line). This option
160is most commonly used with gradiented textures, but it also works in solid
161textures.
162
163.Bevel1 | Bevel2
164tells fluxbox(1) which type of bevel to use. Bevel1 is the default bevel. The
165shading is placed on the edge of the image. Bevel2 is an alternative. The
166shading is placed one pixel in from the edge of the image.
167
168Instead of a texture description, also the option *ParentRelative* is available,
169which makes the component appear as a part of its parent, e.g. totally
170transparent.
171
172Or for even more possibilities Pixmap. If pixmap texture is specified (it
173might not be necessary on every occasion) the pixmap file is specified
174in a separate pixmap resource.
175
176 toolbar.clock: pixmap
177 toolbar.clock.pixmap: clock_background.xpm
178
179This feature might need some investigation, reports say that sometimes the
180resources color and colorTo must be set and then they may not be set.
181
182All gradiented textures are composed of two color values: the 'color' and
183'colorTo' resources. When *Interlaced* is used in *Solid* mode, the 'colorTo'
184resource is used to find the interlacing color.
185
186A WORD ABOUT FONTS
187------------------
188We should comment about fonts before we move on to the complete component
189list. fluxbox(1) supports different options for text. These options currently
190include bold, halo and shadow. To set these do this: fontname-size:options for
191any of the font components in the style file. For example:
192
193 menu.title.font: sans-8:bold,shadow
194
195The latest versions of fluxbox(1) (> 0.9.8) also support different values for
196these text options. The possibilities are as follows:
197
198 --------
199 Shadow color=<colorname> offsetx=<integer> offsety=<integer> Halo color=<colorâ\u20acname>
200 --------
201
202For the case of completeness, here are some real world examples:
203
204 *.font: Verdana-10:bold,shadow:offsetx=2;offsety=4;color=green
205 *.font: Verdana-10:halo:color=blue
206
207Of course this could all be placed on one line. Also note that for the offset
208options, negative integers are allowed.
209
210FONT PROBLEMS
211~~~~~~~~~~~~~
212If you have problems installing fonts or getting them to work, you should read
213the docs page at xfree.org. Here is a link to one of these:
214http://xfree.org/4.3.0/fonts2.html#3[]
215
216FULL COMPONENT LIST
217-------------------
218Here is the exhaustive component list for fluxbox(1) styles. Each one is listed
219with their type of value required. Comments in a style file are preceded
220with an exclamation point (!) which we also use here so that these can be
221pasted into a new theme.cfg to be customized appropiately. Please note that
222in order to keep styles consistent it is often the practice of stylists
223to provide all of the theme-items in their style file even if they are not
224used. This allows the user the ease of changing different components.
225
226WINDOW OPTIONS
227--------------
228Many, many things you can do with window design in fluxbox(1), below are your
229options. Have fun.
230
231 -----------------------------------------
232 window.bevelWidth: <integer>
233 window.borderColor: <color>
234 window.borderWidth: <integer>
235 window.button.focus: <texture type>
236 window.button.focus.color: <color>
237 window.button.focus.colorTo: <color>
238 window.button.focus.picColor: <color>
239 window.button.focus.pixmap: <filename>
240 window.button.pressed: <texture type>
241 window.button.pressed.color: <color>
242 window.button.pressed.colorTo: <color>
243 window.button.pressed.pixmap: <filename>
244 window.button.unfocus: <texture type>
245 window.button.unfocus.color: <color>
246 window.button.unfocus.colorTo: <color>
247 window.button.unfocus.picColor: <color>
248 window.button.unfocus.pixmap: <filename>
249 window.close.pixmap: <filename>
250 window.close.pressed.pixmap: <filename>
251 window.close.unfocus.pixmap: <filename>
252 window.font: <font>
253 window.frame.focusColor: <color>
254 window.frame.unfocusColor: <color>
255 window.grip.focus: <texture type>
256 window.grip.focus.color: <color>
257 window.grip.focus.colorTo: <color>
258 window.grip.focus.pixmap: <filename>
259 window.grip.unfocus: <texture type>
260 window.grip.unfocus.color: <color>
261 window.grip.unfocus.colorTo: <color>
262 window.grip.unfocus.pixmap: <filename>
263 window.handle.focus: <texture type>
264 window.handle.focus.color: <color>
265 window.handle.focus.colorTo: <color>
266 window.handle.focus.pixmap: <filename>
267 window.handle.unfocus: <texture type>
268 window.handle.unfocus.color: <color>
269 window.handle.unfocus.colorTo: <color>
270 window.handle.unfocus.pixmap: <filename>
271 window.handleWidth: <integer>
272 window.iconify.pixmap: <filename>
273 window.iconify.pressed.pixmap: <filename>
274 window.iconify.unfocus.pixmap: <filename>
275 window.justify: <{Left|Right|Center}>
276 window.label.active: <texture type>
277 window.label.active.textColor: <color>
278 window.label.focus: <texture type>
279 window.label.focus.color: <color>
280 window.label.focus.colorTo: <color>
281 window.label.focus.pixmap: <filename>
282 window.label.unfocus: <texture type>
283 window.label.unfocus.color: <color>
284 window.label.unfocus.colorTo: <color>
285 window.label.unfocus.pixmap: <filename>
286 window.label.focus.textColor: <color>
287 window.label.unfocus.textColor: <color>
288 window.maximize.pixmap: <filename>
289 window.maximize.pressed.pixmap: <filename>
290 window.maximize.unfocus.pixmap: <filename>
291 window.roundCorners: <{Top|Bottom}{Left|Right}>
292 window.shade.pixmap: <filename>
293 window.shade.pressed.pixmap: <filename>
294 window.shade.unfocus.pixmap: <filename>
295 window.stick.pixmap: <filename>
296 window.stick.pressed.pixmap: <filename>
297 window.stick.unfocus.pixmap: <filename>
298 window.stuck.pixmap: <filename>
299 window.stuck.unfocus.pixmap: <filename>
300 window.title.focus: <texture type>
301 window.title.focus.color: <color>
302 window.title.focus.colorTo: <color>
303 window.title.focus.pixmap: <filename>
304 window.title.height: <integer>
305 window.title.unfocus: <texture type>
306 window.title.unfocus.color: <color>
307 window.title.unfocus.colorTo: <color>
308 window.title.unfocus.pixmap: <filename>
309 -----------------------------------------
310
311MENU OPTIONS
312------------
313Everything you need to make your menu look pretty.
314
315 -----------------------------------------
316 menu.bevelWidth: <integer>
317 menu.borderColor: <color>
318 menu.borderWidth: <integer>
319 menu.bullet: <{empty|square|triangle|diamond}>
320 menu.bullet.position: <{left|right}>
321 menu.frame: <texture type>
322 menu.frame.color: <color>
323 menu.frame.colorTo: <color>
324 menu.frame.disableColor: <color>
325 menu.frame.font: <font>
326 menu.frame.justify: <{Left|Right|Center}>
327 menu.frame.pixmap: <filename>
328 menu.frame.textColor: <color>
329 menu.hilite: <texture type>
330 menu.hilite.color: <color>
331 menu.hilite.colorTo: <color>
332 menu.hilite.pixmap: <filename>
333 menu.hilite.textColor: <color>
334 menu.itemHeight: <integer>
335 menu.title: <texture type>
336 menu.title.color: <color>
337 menu.title.colorTo: <color>
338 menu.title.font: <font>
339 menu.title.pixmap: <filename>
340 menu.title.textColor: <color>
341 menu.title.justify: <{Left|Right|Center}>
342 menu.titleHeight: <integer>
343 menu.roundCorners: <{Top|Bottom}{Left|Right}>
344 menu.selected.pixmap: <filename>
345 menu.submenu.pixmap: <filename>
346 menu.unselected.pixmap: <filename>
347 -----------------------------------------
348
349BACKGROUND
350------------
351Rarely are you going to want to use this option. There is a command that is
352similar that is used in the init file. It is bad style to use this in your
353style, as it forces the user to use your background. So note that it is good
354practice to leave this blank or out of the style altogether.
355
356 background: centered|aspect|tiled|fullscreen|random|solid|gradient <texture>
357 background.pixmap: <file (or directory for random)>
358 background.color: <color>
359 background.colorTo: <color>
360
361SLIT
362----
363Here are all of the options for the slit.
364
365 -----------------------------------------
366 slit: <texture type>
367 slit.bevelWidth: <integer>
368 slit.borderColor: <color>
369 slit.borderWidth: <integer>
370 slit.color: <color>
371 slit.colorTo: <color>
372 slit.pixmap: <filename>
373 -----------------------------------------
374
375TOOLBAR OPTIONS
376---------------
377Below you will find all of the configuration possibilities for the toolbar.
378The list is pretty extensive and offers you many options to make your toolbar
379look just the way you want it.
380
381 -----------------------------------------
382 toolbar: <texture type>
383 toolbar.bevelWidth: <integer (0-255)>
384 toolbar.borderColor: <color>
385 toolbar.borderWidth: <integer>
386 toolbar.button.scale: <integer>
387 toolbar.color: <color>
388 toolbar.colorTo: <color>
389 toolbar.clock: <texture type>
390 toolbar.clock.borderColor: <color>
391 toolbar.clock.borderWidth: <integer>
392 toolbar.clock.font: <font>
393 toolbar.clock.justify: <{Left|Right|Center}>
394 toolbar.clock.pixmap: <filename>
395 toolbar.clock.color: <color>
396 toolbar.clock.colorTo: <color>
397 toolbar.clock.textColor: <color>
398 toolbar.height: <integer>
399 toolbar.iconbar.focused: <texture type>
400 toolbar.iconbar.focused.color: <color>
401 toolbar.iconbar.focused.colorTo:<color>
402 toolbar.iconbar.focused.pixmap: <filename>
403 toolbar.iconbar.unfocused: <texture type>
404 toolbar.iconbar.unfocused.color: <color>
405 toolbar.iconbar.unfocused.colorTo: <color>
406 toolbar.iconbar.unfocused.pixmap: <filename>
407 toolbar.iconbar.empty: <texture type>
408 toolbar.iconbar.empty.color: <color>
409 toolbar.iconbar.empty.colorTo: <color>
410 toolbar.iconbar.empty.pixmap: <filename>
411 toolbar.iconbar.focused.borderColor: <color>
412 toolbar.iconbar.focused.borderWidth: <integer>
413 toolbar.iconbar.unfocused.borderColor: <color>
414 toolbar.iconbar.unfocused.borderWidth: <integer>
415 toolbar.iconbar.borderColor: <color>
416 toolbar.iconbar.borderWidth: <integer>
417 toolbar.iconbar.focused.font: <font>
418 toolbar.iconbar.focused.justify: <{Left|Right|Center}>
419 toolbar.iconbar.focused.textColor: <color>
420 toolbar.iconbar.unfocused.font: <font>
421 toolbar.iconbar.unfocused.justify: <{Left|Right|Center}>
422 toolbar.iconbar.unfocused.textColor: <color>
423 toolbar.pixmap: <filename>
424 toolbar.shaped: <boolean>
425 toolbar.workspace.font: <font>
426 toolbar.workspace.justify: <{Left|Right|Center}>
427 toolbar.workspace.textColor: <color>
428 toolbar.workspace: <texture type>
429 toolbar.workspace.borderColor: <color>
430 toolbar.workspace.borderWidth: <integer>
431 toolbar.workspace.color: <color>
432 toolbar.workspace.colorTo: <color>
433 toolbar.workspace.pixmap: <filename>
434 -----------------------------------------
435
436EXAMPLES
437--------
438This list may seem intimidating, but remember, when you create your own style
439you can easily set a majority of these keys with a single component. For an
440example of this:
441
442 -----------------------------------------
443 *color: slategrey
444 *colorTo: darkslategrey
445 *unfocus.color: darkslategrey
446 *unfocus.colorTo: black
447 *textColor: white
448 *unfocus.textColor: lightgrey
449 *font: lucidasans-10
450 -----------------------------------------
451
452This sets nice defaults for many components.
453
454COLOR FORMATS
455-------------
456These are the color formats for styles:
457
458 #000000 (Hexadecimal)
459 rgb:<0-255>/<0-255>/<0-255>
460
461See /usr/X11R6/lib/X11/rgb.txt for an explaination.
462
463AUTHOR and CREDITS
464------------------
465Blackbox was written and maintained by Brad Hughes <blackbox@alug.org>
466and Jeff Raven <jraven@psu.edu>.
467
468fluxbox(1) is written and maintained by Henrik Kinnunen <fluxgen@fluxbox.org>
469with contributions and patches merged from many individuals around the world.
470
471The Official fluxbox(1) website: http://www.fluxbox.org[]
472You can find a lot of styles here: http://fluxmod.org/[]
473
474This manpage was composed from various resources including the official
475documentation, fluxbox(1) man page and numerous other resources by Curt
476"Asenchi" Micol. If you notice any errors or problems with this page, please
477contact him here: <asenchi@asenchi.com> and using the great contributions of
478<grubert@users.sourceforge.net>. Numerous other languages could be available
479if someone jumps in.
480
481SEE ALSO
482--------
483fluxbox(1) fbsetbg(1) fbsetroot(1)
484