BB Style 0.70 Syntax Tutorial
by snkmchnb (snkmchnb.at.lost-ip.info)

This is my first attempt at a tutorial of any kind and most of the information if not all will be from the Blackbox sourceforge site, http://blackboxwm.sourceforge.net. This tutorial will take you step-by-step in styling for blackbox using the new style syntax and if you've made styles for blackbox before and are used to the old syntax you can skip to the end where I'll have a full template of the new syntax available.

Tip: If you're using fluxbox, openbox, hackedbox, and bb4win these rely on the older style syntax. I suggest you take a look at the style tutorial made by thewayofzen for this syntax. BBLean can use either syntax and xoblite can do the new borders, border colors and border widths from the latest syntax.


1. Texture:

A texture is a description of a particular visual element. It
consists of a text description, colors and a border width. Textures
are specified as follows:

<name>.appearance: description
<name>.backgroundColor: background color for solids
<name>.color1: initial color for gradients and interlaced solids
<name>.color2: target color for gradients and interlaced solids
<name>.borderWidth: width of the texture border in pixels
<name>.borderColor: color of the texture border

The BNF for the appearance is:

<appearance> := parentrelative | [<bevel-type>] [<fill-type>] [interlaced] [border]
<bevel-type> := sunken | flat | raised
<fill-type> := gradient <gradient-type> | solid
<gradient-type> := crossdiagonal | rectangle | pyramid | pipecross |
elliptic | horizontal | vertical | diagonal


Remember this syntax, it's the base for the toolbar, menu, slit and windows.

2. Color:

Ways to define colors such as Hex, HTML and X11 color names (e.g. cornsilk3), rgb or rgbi, or as a device-independent color specification. To keep it simple I'll be doing the tutorial in Hex.


3. Alignment:

Alignment is one of the following: Left, Center and Right. Pretty straight forward.


4. Width/Height/Margin:

All width, height and margin resources are specified in pixels. In
general, width and height specify the full extent, where as margin
specifies the space around another element.
5. Starting a style:

Normally at the top of a style you will see either a commented or syntax defined section giving a description of the style and some information such as name, author, date, etc.

I've seen comments with “;” and “!”, personally I've always used “!” and it works fine. This is normally the way you'll see it done with syntax:



Time to get down to the nitty gritty.

6. Toolbar:

The toolbar is normally on the bottom of the screen but can also be positioned at the top of the screen as well. The toolbar consists of four main elements: label (for workspaces or virtual desktops), buttons, winlabel (active window title) and clock.


A. Toolbar

The toolbar's main appearance is defined with the following syntax:



Now if you recall from above the options for the appearance would be: parentrelative, raised, flat and sunken.

Tip: You will not want to set the toolbar's appearance to be parentrelative due to the fact that it is not a child element of another object. This means that it would not have any colors defined and thus would default to blackbox's default settings, normally flat solid black and white.

The toolbar would be set to either raised, flat or sunken. The next option defined in that same line would be the fill-type (gradient or solid). If gradient is chosen then the gradient-type also needs to be defined. Gradient-types include: crossdiagonal, rectangle, pyramid, pipecross, elliptic, horizontal, vertical, and diagonal.

The interlaced option can also be included which basically darkens every other line in a gradient which can lead into a really nice effect. The final option would be the bevel level; choices are bevel1 and bevel2. Again this is all preference but can help a style pop a little more by giving it a little more definition. The bevel should only be used with either the raised or sunken appearance.


B. Buttons

There are two different declarations for buttons that you have to make for the toolbar (3 for the buttons on the windows), style of buttons when they arn't being used and when the buttons are pressed. The syntax is as follows:



Notice that there is also the sunken part of the syntax which you declare a separate style for the buttons when clicked. Generally this would either be declared as sunken or a different color set to show the action of the buttons being clicked.


C. Clock

The clock resides on the right-most side of the toolbar. The clock and label also have the same size as far as width. The clock's style syntax is as follows:



D. Label

The label is the section of the toolbar that displays the names of workspaces (virtual desktops) you are currently on. The syntax for the label is as follows:




E. Window Label

The window label is located in the center of the toolbar and displays the currently active application which has focus. The windows label style syntax is as follows:




F. Toolbar example

Now since the buttons, clock, label and window label are part of the toolbar, they would be considered child elements of the toolbar and would be able to be parentrelative of the toolbar, or inherit the style that of the toolbar. Here is an example of how I've done my toolbar:



Notice that the .backgroundColor parts of elements above a “!” in front of it. This is due to the fact that I'm using a gradient instead of solid color. You can also do a solid by declaring a gradient but using the same color for color one. Since I'm also doing gradients here the .backgroundColor is not needed but I'm keeping all of the syntax included for good practice.


7. Menu

The menu is comprised of 3 main elements, the title, frame and active portions.

A. Title

The menu title is the top-most element you'll see in the menu. It generally will be the name of a submenu. Style syntax for the menu title is as follows:




B. Frame

The menu frame is the main part of the menu where all of the applications and submenus are located. Syntax for the menu frame is as follows:



C. Active

The active sections of the menu is what is currently being selected in the menu or hovered over with the mouse. Its settings are changed using:



D. Menu example



8. Slit

Some people may not know what the slit is so I'm going to give a little run down before I give the style syntax for it. The slit is basically a container for dock apps (plugins in windows) and attaches to the edges of the screen.

Note: The slit in the Windows variants the slit does not recognize the new style syntax.



9. Windows

There are two main parts of windows when styling, focused and unfocused. The elements that are defined for both parts are title, label, button, handle and grip. These elements, most of the time, are styled to mimic the toolbar elements respectfully.

A. Title

The window title is the main part of the window which contains the buttons and label. Syntax for the window title is as follows:



B. Label

The window label displays the name of the application running. Syntax for the label is as follows:



C. Buttons

As stated above the window buttons are styled pretty much the same as buttons on the toolbar but you also have to define the unfocused buttons as well. Style syntax for window buttons are as follows:



F. Frames

At the left and right sides of the windows are the window frames. The window frames are used to open the root blackbox menu and to also separate the window contents from the background. The frames style syntax is as follows:



E. Grips

The window grips are the two smaller sections at the bottom of the window, one on each end. The grips are used to resize the window. Style syntax for the grips is as follows:



F.HANDLES

The window handle is at the bottom of the window in the center of the grips. The handle is used to move the window around just as you would with the top of the window. The handle's style syntax is as follows:



G. Window example



10. Wildcards

Wildcards can be used if you want multiple elements to have the same style as it were. One of the greatly used wildcards used is for font:

You can manipulate the wildcards to be a little more specific if you only want it for lets say, unfocused text color you would do:



I'll give a small list of wildcards that can be used:



I personally don't use the wildcards, I would rather have all of the syntax declared for every element but to each his own.

11. Rootcommand

Rootcommand

When styles are loaded rootcommand executes whatever command follows it if declared in the style. Two common uses of rootcommand involve bsetroot or bsetbg.

A. bsetroot

bsetroot is a utility that implements simple backgrounds. Common use of rootcommand with bsetroot is declared as follows:



Some other options for bsetroot are as follows:

-solid color
Sets the root window to specified color.
-mod x y
Creates a modula pattern. You must specify -bg and -fg colors.
-gradient texturestring
Renders the specified texture string to the root window.
Select one of these texture types, they only apply when -gradient is specifed. You must also specify both a -from and a -to color.
texturestring may be one of the following:
horizontal, vertical, diagonal, crossdiagonal, pipecross, elliptic, rectangle and pyramid.
-display display
Tells Bsetroot to connect to the specified display.

-bg, -background color
Background color. Needed for -mod patterns.

-fg, -foreground color
Foreground color. Needed for -mod patterns.

-from color
Start color for rendering textures. Needed for -gradient operation mode.

-to color
ending color for rendering textures. Needed for -gradient operation mode.

-help
version info and short help text.

B. bsetbg

bsetbg is basically to display images as wallpaper.
OPTIONS
-f, -full image
image is stretched to fill the entire desktop.
-t, -tile image
image is tiled on the desktop.
-c, -center image
image is centered on the desktop.
-e, -exec program options fallback-arg image
This option tells bsetbg to run a separate command by executing program with options, where options are arguments to program.
If a fallback-arg is supplied (-full, -tile, or -center as described above), bsetbg will assume that the last argument is a filename. In the case that program exits non-zero or isn't available on the target system, bsetbg will try to handle the file with the fallback argument.
See the examples section for more information on -exec.
-p, -post list
Specifies a list of arguments to pass to the $POST_COMMAND.
-d, -debug
Debugging mode. bsetbg will print commands without executing them.
-g, -generate list
Output a list of default configuration values, suitable for redirecting into ~/.bsetbgrc. Any arguments that are supplied will be considered applications to search for in the system path, overriding bsetbg's internal defaults.
-app imageApp
Use this flag to specify which image application to use. This application may be one of the pre-defined list or any application capable of displaying an image on the root window. This flag may be used in conjunction with passing application specific parameters to the application, in which case they should be enclosed in double quotes.
-v, -version
Output version number.
-h, -help
Output a brief usage message.
12. Style Template

This concludes my tutorial on blackbox styling with the new 0.70 syntax. Here is the full style template that I've created:

I think your pressed buttons need an .appearance Nice tut!

Great work, snk - and a much needed one...

Lets not forget:

With rootCommand you can also use it to load commands as well

For example:



Path and file is the location of the scripted txt file that BroamRelay will read.

That will give you the option of launching various broams during style change

If you wish to still put a wallpaper and other commands into the bsetroot you can still call this in the BroamRelay txt file.

For example



That would typically launch all your broams and then execute your background settings.
This example is made for bblean. I'm not sure what is used to launch programs in Xoblite.

The reason for doing it this way is, say you want to have a Theme based style that loads various elements into your style. This is a good way of doing this.
A sidebar for example. If you want to change the icon pictures you would put the BBInterface picture changes in the Broam relay file and follow that with your bsetroot call to load the rest of your background information.

thanks guys i went back and added the ".appearance" to the toolbar.pressed, thanks for catching that NC-17.

as far as the note you made about rootCommand, Nightbreed, i agree that you can do that but i only wanted to go over the main uses of it so it would better fit both *nix/windows at the same time without showing a bias of some sort, but good idea

I wanted to give some info on styles...

Some interesting things with Wildcards for one that some may not know of.
Wildcards don't always have to be at the end or beginning of the definition.
For example, you can also use:

window.*.borderColor:
or
window.*.unfocus.borderColor: <-- that would effect all the borders on unfocused windows. Without effecting other parts of the style

so if you are creating a style this can help in cutting down alot of typing.

Another thing..
If you have the following lines in a style:

window.frame.focusColor:
window.frame.unfocusColor:

They aren't needed any longer. They don't do anything. So you would use:

window.frame.focus.borderColor:
window.frame.unfocus.borderColor:

Remember, if you are having trouble setting borders to individual window elements check to make sure you have the focus and unfocus defined. Also make sure you have border defined in the initial call of the element.
i.e.,
window.button.pressed: flat gradient elliptic border

if that's not there, it wont get bordered. Again, if you are trying to give all the window elements the same borderColor or borderWidth a simple:

window.*.borderColor:
window.*.borderWidth:

Would define all of those for you. So play around with different possitions of the wildcard, I'm sure you can come up with other time saving places for it

Peace...

I need to learn this now that I'm running unix blackbox.

One thing I can't figure out--I'm using kroeger fonts and they're huge. Is there anything on font size in the new syntax?

Same thing that went for the old syntax: fontHeight. And fontWeight, of course, to define normal, bold, etc.

Thanks pitkon.

I found this:

Oops, you were talking about unix. Sorry! Yup, this is a rather complicated unix way of defining fonts. I have come across a whole line that goes like this:
verdana -30 *** -b -s**---* or something... lol... Looks more like Nixon transcriptions than an actual style line

Here's some examples:

toolbar.font: -microsoft-verdana-bold-r-normal-*-*-120-*-*-p-*-iso8859-2

(from Wonderland style, by FuZZy


toolbar.font: -microsoft-Verdana-medium-r-normal--12-0-0-0-p-0-iso8859-10

(from Air style, by Albertas Agejevas)

cthu1hu, if you grab one of the last 2 styles I posted on boxshots.org and look at the style syntax used in them, it's done so I can use them in BBwm since I use the global font overide in bbLean. You could just copy/paste that section then change the font info.

As a general rule, youl'll need to reduce the font size that you use on Windows by a factor of 2 for TTF's eg: Verdana 10 --> Verdana 8, I'm not sure about FON's

bevel2 isn't supported in blackbox unix?

What are the bevel types?

menu.title.marginWidth:
is actually 12px + the number you set in the style file.
just a heads up