summaryrefslogtreecommitdiff
path: root/doc/asciidoc/fluxstyle.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/asciidoc/fluxstyle.txt')
-rw-r--r--doc/asciidoc/fluxstyle.txt184
1 files changed, 184 insertions, 0 deletions
diff --git a/doc/asciidoc/fluxstyle.txt b/doc/asciidoc/fluxstyle.txt
new file mode 100644
index 0000000..e4cf1f7
--- /dev/null
+++ b/doc/asciidoc/fluxstyle.txt
@@ -0,0 +1,184 @@
1fluxstyle(1)
2============
3Henrik Kinnunen <fluxgen@fluxbox.org>
4v1.0rc2 26th July 2006
5
6NAME
7----
8fluxstyle - A comprehensive look at styles/themes for fluxbox.
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 how to generate the
22appearance of different components of the window manager. The default
23installation of fluxbox 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 menu.
26
27fluxbox uses it's own graphics class to render its images on the fly. By using
28styles you can determine, at a great level, of configurability what your
29desktop will look like. Since fluxbox was derived from flackbox many often
30wonder if old themes will work on the latest releases of flackbox. Well they
31basically do, but you will have to tune them since the fluxbox 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 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 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 wild card. 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 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 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 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 to interlace the texture (darken every other line). This option
160is most commonly used with gradiented textures, but from fluxbox version
1610.60.3 on, it also works in solid textures.
162
163.Bevel1 | Bevel2
164tells fluxbox 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.