nilix/fluxbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

removed obsolete docs

Browse source
This commit is contained in:
fluxgen 2007-08-11 18:59:55 +00:00
parent 0b2ba10411
commit 3403b14844
2 changed files with 0 additions and 702 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

372
data/README.menu
View file

@ -1,372 +0,0 @@
-- data/README.menu for Blackbox 0.61.x - an X11 Window manager
Creating a user defined menu:
-----------------------------
Creating a menu for Blackbox requires a text editor of some sort. Familiarity
with your choice of text editor is assumed, since editor preference differs
as much (if not more than) window manager preference.
First, we need to decide on a location for our custom menu. Your home
directory is the most logical solution, since you will most likely not have
write access anywhere else. You place the menu file in any directory, and
give it any name you choose, as we will later tell Blackbox the path or
location for this file.
As an example, let's assume that my home directory is `/home/bhughes' (which it
is). I've decided to keep all my Blackbox related files in a directory named
`blackbox.' After creating the directory, I now have two options for creating
my new menu. I can either copy the system default (usually in
`/usr/local/share/Blackbox/menu') to this directory, or I can create a new
one from scratch. Let's do the latter, for the sake of completeness.
I've decided to name the file `rootmenu.' I fire up my favorite text editor
and now have a clean file. So let's begin.
Menu syntax:
------------
The menu syntax is very simple and very effective. There are upto three
fields in a menu line. They are of the form:
[tag] (label or filename) {command or filename}
The supported tags are as follows:
[begin] (label for root menu)
This tells Blackbox to start parsing the menu file. This tag is
required for Blackbox to parse your menu file. If it cannot find it,
the system default menu is used instead.
[end]
This tells Blackbox that it is at the end of a menu. This can either
be a submenu or the main root menu. There must be at least one
of these tags in your menu to correspond to the required [begin] tag.
[exec] (label for command) {shell command}
This tells Blackbox to insert a command item into the menu. When you
select the menu item from the menu, Blackbox runs `shell command.'
[exit] (label for exit)
This tells Blackbox to insert an item that shuts down and exits
Blackbox. Any open windows are reparented to the root window before
Blackbox exits.
[include] (filename)
This tells Blackbox to parse the file specified by `filename' inline
with the current menu. `filename' can be the full path to a file
(such as /usr/local/share/Blackbox/brueghel/stylesmenu) or it can
begin with `~/', which will be expanded into your home directory
(e.g. [include] (~/blackbox/stylesmenu) will include
/home/bhughes/blackbox/stylesmenu in my menu)
[nop] (label - optional)
This tells Blackbox to insert a non-operational item into the current
menu. This can be used to help format the menu into blocks or sections
if so desired (e.g. you could put all your ssh accounts together, add
a [nop] and then add all your telnet accounts together). [nop] does
accept a label, but it is not required, and a blank item will be used
if none is supplied.
[style] (label) {filename}
This tells Blackbox to read `filename' and apply the new textures,
colors and fonts to the current running session. The filename is
just like the [include] tag, it can be the full path to the file,
or it can be of the form `~/path/from/home/dir.' Blackbox also
re-reads the entire menu structure from disk, incase the menu has
changed.
[submenu] (label) {title for menu - optional}
This tells Blackbox to create and parse a new menu. This menu is
inserted as a submenu into the parent menu. These menus are parsed
recursively, so there is no limit to the number of levels or nested
submenus you can have. The title for the new menu is optional, if
none is supplied, the new menu's title is the same as the item label.
[reconfig] (label)
This tells Blackbox to reread the current style and menu files and
apply any changes. This is useful for creating a new style or theme,
as you don't have to constantly restart Blackbox every time you save
your style.
[restart] (label) {shell command - optional}
This tells Blackbox to restart. If `shell command' is supplied, it
shuts down and runs the command (which is commonly the name of another
window manager). If the command is omitted, Blackbox restarts itself.
[workspaces] (label)
This tells Blackbox to insert a "link" to the workspaces menu directly
into your menu. This is handy for those users who can't access the
workspace menu directly (e.g. if you don't have a 3 button mouse, it's
rather hard to middle click to show the workspace menu). This is a
"link" to the systems workspace menu, so multiple [workspaces] tags
will display the same workspace menu, so expect it to move around if
you do so. ;)
[config] (label)
This tells Blackbox to insert the ConfigMenu into your menu. From
this menu you can configure several options stored in your
~/.blackboxrc, and the changes take effect immediately.
Comments may be inserted on any line of the file, as long as the first
character on the line is a `#.'
Also, in the labels/commands/filenames fields, you can escape any character
like so:
[exec] (\(my cool\) \{XTERM\}) {\(xterm -T \\\"cool XTERM\\\"\)}
Using `\\' inserts a literal back-slash into the label/command/filename field.
Putting it all together:
------------------------
Alrighty, so let's see if we can understand the arcane incantation above. It
says we have to have a [begin] and an [end] tag, which create our menu and
give it a title. Let's do that first:
[begin] (Example \[Menu\])
[end]
Simple enough. Now let's add some items to the list. We always want to have
access to a terminal emulator, be it a regular xterm or something else.
So we add the item to our menu, and it now looks like this:
...
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[end]
...
Great! Now let's add us some items to run an irc client, netscape, xv and
some other common programs. This gives up this:
...
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
[exec] (Netscape Navigator) {netscape}
[exec] (xv 3.10a) {xv}
[exec] (XEmacs) {xemacs}
[exec] (The GIMP) {gimp}
[exec] (Video Tune) {xvidtune}
[end]
...
Whoa, wait a second. This menu file is beginning to look a little cluttered.
Not a problem, just like programmers indent and space their code, we can
do this with our menu file, so let's clean it up a bit:
...
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
[exec] (Netscape Navigator) {netscape}
[exec] (XEmacs) {xemacs}
[exec] (xv 3.10a) {xv}
[exec] (The GIMP) {gimp}
[exec] (Video Tune) {xvidtune}
[end]
...
Ahh... now that looks a little better. Now we decide that we kind of like the
spacing in the file, and decide we want to apply it to the menu itself. Now
we take advantage of the [nop] tag:
...
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
[nop]
[exec] (Netscape Navigator) {netscape}
[exec] (XEmacs) {xemacs}
[nop]
[exec] (xv 3.10a) {xv}
[exec] (The GIMP) {gimp}
[nop]
[exec] (Video Tune) {xvidtune}
[end]
...
Now, let's create a submenu to put some items to change between all these
themes we downloaded from http://blackbox.themes.org/. Let's assume we
untarred the themes into the ~/.blackbox directory like the documentation on
the themes.org site recommends.
...
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
[nop]
[exec] (Netscape Navigator) {netscape}
[exec] (XEmacs) {xemacs}
[nop]
[exec] (xv 3.10a) {xv}
[exec] (The GIMP) {gimp}
[nop]
[exec] (Video Tune) {xvidtune}
[submenu] (Themes) {Themes from blackbox.themes.org}
[style] (Blackbox) {~/.blackbox/Styles/blackbox}
[style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
[style] (Hardware) {~/.blackbox/Styles/hardware}
[style] (Nova) {~/.blackbox/Styles/nova}
[style] (Orbital) {~/.blackbox/Styles/orbital}
[style] (Orbital II) {~/.blackbox/Styles/orbital2}
[style] (Seething) {~/.blackbox/Styles/seething}
[style] (Zero) {~/.blackbox/Styles/zero}
[style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
[end]
[end]
...
Even better. Now hold on a second, if we have our themes and styles in
~/.blackbox why do we have to have our menu in ~/blackbox? Answer: WE DON'T!
This is where the choice comes. Do we keep our stuff in two separate
directories? Do we put it all in one directory? That is up to you to decide.
I personally prefer to keep everything in one directory (but, I use ~/blackbox
and have been for a long, long time; long before blackbox.themes.org was
even thought of... and again that is *personal* preference, not a hard-fast
rule).
Now that we've gotten a feel for the menu syntax, we decide to finish off our
menu. In addition to the styles we downloaded, we decide we also want to
keep a submenu for the default styles that came with Blackbox. All we need
to do is [include] the styles file from the share directory for Blackbox.
After putting everything together, we have:
...
# custom menu file for Blackbox
[begin] (Example \[Menu\])
[exec] (xterm) {xterm -ls}
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
[nop]
[exec] (Netscape Navigator) {netscape}
[exec] (XEmacs) {xemacs}
[nop]
[exec] (xv 3.10a) {xv}
[exec] (The GIMP) {gimp}
[nop]
[exec] (Video Tune) {xvidtune}
[nop] (...)
[submenu] (Themes) {Themes from blackbox.themes.org}
[style] (Blackbox) {~/.blackbox/Styles/blackbox}
[style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
[style] (Hardware) {~/.blackbox/Styles/hardware}
[style] (Nova) {~/.blackbox/Styles/nova}
[style] (Orbital) {~/.blackbox/Styles/orbital}
[style] (Orbital II) {~/.blackbox/Styles/orbital2}
[style] (Seething) {~/.blackbox/Styles/seething}
[style] (Zero) {~/.blackbox/Styles/zero}
[style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
# include the default style menu... this is assuming Blackbox was installed
# into /usr/local
[nop]
[include] (/usr/local/share/Blackbox/styles/stylesmenu)
[end]
[workspaces] (Workspace list)
[submenu] (Restart) {Restart which?}
[restart] (Blackbox)
# let's also give us access to some other window managers
[restart] (Window Maker) {wmaker}
[restart] (Enlightenment) {enlightenment}
[restart] (KWM) {kwm}
[restart] (TWM) {twm}
[end]
[nop] (...)
[reconfig] (Reconfigure)
[exit] (Quit!)
[end]
...
And voila! our menu file is finished. Now we need to tell Blackbox to read
this menu file. We do this by editing the file ~/.blackboxrc.
NOTE: your ~/.blackboxrc is auotmatically updated every time Blackbox restarts,
reconfigures, changes styles or exits. Changes to dynamic data like workspace
count, names, etc. is lost. About the only thing you can change and have it
preserved is the menu filename, which is what we are about to change.
The format of ~/.blackboxrc is in the X resource database format (just like
~/.Xdefaults). Since the file is updated automatically, it may be full of
stuff or it may not even exist (especially if this is the first time we've
ran Blackbox). Don't worry if you have to create ~/.blackboxrc, Blackbox will
see the file the next time it starts.
What we need to do is change the resource for the menu's filename. This is
done by changing (or adding) the line that looks like so:
...
session.menuFile: /path/to/some/file
...
If this resource exists, we change it. If it does not, we add it. Depending
on where we put the menu file, our new resource could look like this:
...
session.menuFile: /home/bhughes/blackbox/rootmenu
...
We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't work,
we need Blackbox to completely shutdown and reread ALL of it's configuration
files, not just the ones that control colors/fonts/etc.)
If we've done everything correctly, Blackbox restarts itself and our new menu
is now ready for use. If something doesn't work, read over the above example
again to make sure you didn't forget a step or leave out the necessary tags.
Now that Blackbox has been told where to find it's menu, it does a little more.
Blackbox 0.51.x introduces automagic menu updates. As long as you never
change session.menuFile, you will never have to restart or reconfigure Blackbox
whenever you change your menu. Blackbox watches the timestamps on all the
files it reads to build your menu. If any of them change, they are reread and
your menu updated. This check is done everytime you open the root menu. Like
I said... it is a check, it doesn't reread the menu everytime, it just looks
at the modification time and rereads when it changes.

330
data/README.style
View file

@ -1,330 +0,0 @@
-- data/README.style for Blackbox 0.61.x - an X11 Window manager
Creating a new style (aka "theme"):
-----------------------------------
After getting Blackbox up and running, the next thing you want to do is change
the colors/fonts/etc. on the screen. Blackbox uses a "style" to read its
configuration information. A style in Blackbox consists of X resources placed
in a file. Just like the menu file (see README.menu), the style file can be
put anywhere on the filesystem; as long as you have read access to the file,
Blackbox can use it.
First, we need to decide where to put our style file, and what to name it.
I recommend using the naming scheme described on http://blackbox.themes.org/
when creating styles.
Let's get started. Let's put our new style into a file named `results.'
Following the themes.org naming scheme, this file will go into
.blackbox/Styles. Same as with the menu file, we use our favorite text editor
to create the new style.
X resources consist of a key and a value. The key is constructed of several
smaller keys, delimited by a period (`.'). Keys may also contain a star (`*')
to serve as a wildcard, which means that one line of typed text will match
several keys. This is useful for styles that are based on one or two colors.
Blackbox allows you to configure it's three main components: the toolbar, the
menus and the window decorations. Lets begin by creating a style for our
toolbar.
First we need to define a "texture" for the toolbar and it's components.
Textures tell Blackbox how to mold or shape the colors we supply.
A texture is comprised of the following elements:
Raised / Sunken / Flat give the component a raised, sunken
or flat appearance (respectively)
Solid / Gradient tell Blackbox whether to draw a solid
or gradiented texture
Interlaced tells Blackbox to interlace a
gradient (and gradient ONLY) texture
Bevel1 / Bevel2 tells Blackbox which type of bevel
to use.
NOTE on Bevel1 / Bevel2:
Bevel1 is the default bevel. The shading is placed on the edge of the image.
Bevel2 is an alternative. The shading is placed one pixel in from the edge
of the image.
Now that we understand that, let's define the textures for the toolbar. The
toolbar has a main frame, buttons, two labels and a clock label. The buttons
have 2 states, so we provide textures for both the normal and the pressed
state.
...
toolbar: Raised Diagonal Gradient Bevel1
toolbar.button: Raised Diagonal Gradient Bevel1
toolbar.button.pressed: Sunken Diagonal Interlaced Gradient Bevel1
toolbar.clock: Flat Interlaced Gradient
toolbar.label: Flat Interlaced Gradient
...
NOTE: the texture strings don't have to be capitalized like they did in
previous versions. They are still placed in capitals here, because things like
the bbtools still use the old method.
Next we define colors for the textures. Colors can be any valid X colorname
(from the RGB database) or it can be a color specifier, as described by
'man 1 X.'
Let's see how our file looks after adding colors:
...
toolbar: Raised Diagonal Gradient Bevel1
toolbar.button: Raised Diagonal Gradient Bevel1
toolbar.button.pressed: Sunken Diagonal Interlaced Gradient Bevel1
toolbar.clock: Flat Interlaced Gradient
toolbar.label: Flat Interlaced Gradient
toolbar.color: rgb:8/8/7
toolbar.colorTo: grey20
toolbar.button.color: grey
toolbar.button.colorTo: grey20
toolbar.button.pressed.color: rgb:4/4/38
toolbar.button.pressed.colorTo: rgb:f/f/d
toolbar.clock.color: grey20
toolbar.clock.colorTo: rgb:8/8/7
toolbar.label.color: grey20
toolbar.label.colorTo: rgb:8/8/7
toolbar.textColor: grey85
...
As you have noticed, all textures have a color and a colorTo key. These keys
are required for gradient images. For solids, only color is needed. You will
also notice that we have supplied the color for the text on the toolbar. Not
all textures have a text color, just certain base textures.
Next, let's move onto the menus. Since Blackbox was written in C++, all of
the menus used in it are subclasses of one generic base class. Blackbox reads
the style for the configuration for that base class, which applies to all
the menus used in Blackbox.
The menu has two main parts, the title and the frame. There is nothing
visible under them, so we only configure these two components. The menu frame
and menu title BOTH have a configurable text color, and the menu frame has a
highlight color and the corresponding highlighted text color key. Let's assign
some textures and colors to our menu, and see what our style file looks like
so far:
...
toolbar: Raised Diagonal Gradient Bevel1
toolbar.button: Raised Diagonal Gradient Bevel1
toolbar.button.pressed: Sunken Diagonal Interlaced Gradient Bevel1
toolbar.clock: Flat Interlaced Gradient
toolbar.label: Flat Interlaced Gradient
toolbar.color: rgb:8/8/7
toolbar.colorTo: grey20
toolbar.button.color: grey
toolbar.button.colorTo: grey20
toolbar.button.pressed.color: rgb:4/4/38
toolbar.button.pressed.colorTo: rgb:f/f/d
toolbar.clock.color: grey20
toolbar.clock.colorTo: rgb:8/8/7
toolbar.label.color: grey20
toolbar.label.colorTo: rgb:8/8/7
toolbar.textColor: grey85
menu.title: Raised Diagonal Interlaced Gradient Bevel1
menu.frame: Raised Diagonal Gradient Bevel1
menu.title.color: grey20
menu.title.colorTo: rgb:8/8/7
menu.title.textColor: grey85
menu.frame.color: rgb:8/8/7
menu.frame.colorTo: grey10
menu.frame.textColor: white
menu.frame.highlightColor: grey85
menu.frame.hiTextColor: grey20
...
Next, we need to configure our windows. Windows are like buttons, they have
two states, focused and unfocused. There for we define a separate texture
for unfocused windows and focused windows. The buttons on the titlebar
are focus dependant also, so we need to configure them as well. The buttons
only have one "pressed" state, so we only have to define that once, instead of
having a focus.pressed state and an unfocus.pressed state. The window frame
is the thin border around the client window. Let's be sure to catch it as well.
After adding the window config, our style now looks like this:
...
toolbar: Raised Diagonal Gradient Bevel1
toolbar.button: Raised Diagonal Gradient Bevel1
toolbar.button.pressed: Sunken Diagonal Interlaced Gradient Bevel1
toolbar.clock: Flat Interlaced Gradient
toolbar.label: Flat Interlaced Gradient
toolbar.color: rgb:8/8/7
toolbar.colorTo: grey20
toolbar.button.color: grey
toolbar.button.colorTo: grey20
toolbar.button.pressed.color: rgb:4/4/38
toolbar.button.pressed.colorTo: rgb:f/f/d
toolbar.clock.color: grey20
toolbar.clock.colorTo: rgb:8/8/7
toolbar.label.color: grey20
toolbar.label.colorTo: rgb:8/8/7
toolbar.textColor: grey85
menu.title: Raised Diagonal Interlaced Gradient Bevel1
menu.frame: Raised Diagonal Gradient Bevel1
menu.title.color: grey20
menu.title.colorTo: rgb:8/8/7
menu.title.textColor: grey85
menu.frame.color: rgb:8/8/7
menu.frame.colorTo: grey10
menu.frame.textColor: white
menu.frame.highlightColor: grey85
menu.frame.hiTextColor: grey20
window.focus: Raised Diagonal Interlaced Gradient Bevel1
window.focus.button: Raised Diagonal Gradient Bevel1
window.unfocus: Raised Diagonal Gradient Bevel1
window.unfocus.button: Sunken Diagonal Gradient Bevel1
window.button.pressed: Flat Diagonal Interlaced Gradient
window.frame: Raised Solid Bevel1
window.focus.color: grey
window.focus.colorTo: grey20
window.focus.textColor: grey85
window.focus.button.color: grey
window.focus.button.colorTo: grey20
window.unfocus.color: rgb:8/8/7
window.unfocus.colorTo: grey20
window.unfocus.textColor: grey
window.unfocus.button.color: grey20
window.unfocus.button.colorTo: grey
window.button.pressed.color: rgb:4/4/38
window.button.pressed.colorTo: rgb:f/f/d
window.frame.color: grey85
...
Now all we have to do is finish off the style with a few miscellanous options.
These include the title and menu fonts/justification, border color, bevel and
handle widths, window move style and the root command.
Fonts must be a valid X11 font screen, or a valid font alias. Use a utility
like `xfontsel' (and others) to preview fonts. Also use the utility
`xlsfonts' to spit out all the current X font names and aliases stored in
the X server.
Justification can be one of three things: LeftJustify, CenterJustify or
RightJustify.
The border color is the color applied to the 1 pixel border around the menu
frame/title and the window titlebar/buttons/handle/etc. Setting this color
can have drastic effects on your style, so don't just leave it set to `black'
all the time. ;)
The bevel and handle widths control the size and spacing of decorations in
Blackbox. The larger the number, the more space Blackbox takes up.
The window move style tells Blackbox how to move windows when you drag them
with your mouse. There are two options for it: Opaque or Wire.
The root command is the command run every time the style is loaded (either at
startup or after a reconfigure/style-change). It is used to run a program
like xv, Esetroot, wmsetbg, etc. to set an image/color/pattern on the root
window. Just supply a command and it will be run.
Also, as a note, an X resource file can have comments. Precede the line with
and exclamation mark `!' and the rest of the line will be ignored.
Let's finish off the details and take a look at our finished style:
...
! Results - theme for Blackbox 0.51.x
! by Brad Hughes bhughes@tcac.net
! define the toolbars textures... note that the interlaced option is new
! in 0.51.x
toolbar: Raised Diagonal Gradient Bevel1
toolbar.button: Raised Diagonal Gradient Bevel1
toolbar.button.pressed: Sunken Diagonal Interlaced Gradient Bevel1
toolbar.clock: Flat Interlaced Gradient
toolbar.label: Flat Interlaced Gradient
! toolbar colors
toolbar.color: rgb:8/8/7
toolbar.colorTo: grey20
toolbar.button.color: grey
toolbar.button.colorTo: grey20
toolbar.button.pressed.color: rgb:4/4/38
toolbar.button.pressed.colorTo: rgb:f/f/d
toolbar.clock.color: grey20
toolbar.clock.colorTo: rgb:8/8/7
toolbar.label.color: grey20
toolbar.label.colorTo: rgb:8/8/7
toolbar.textColor: grey85
! menu textures
menu.title: Raised Diagonal Interlaced Gradient Bevel1
menu.frame: Raised Diagonal Gradient Bevel1
! menu colors
menu.title.color: grey20
menu.title.colorTo: rgb:8/8/7
menu.title.textColor: grey85
menu.frame.color: rgb:8/8/7
menu.frame.colorTo: grey10
menu.frame.textColor: white
menu.frame.highlightColor: grey85
menu.frame.hiTextColor: grey20
! window textures
window.focus: Raised Diagonal Interlaced Gradient Bevel1
window.focus.button: Raised Diagonal Gradient Bevel1
window.unfocus: Raised Diagonal Gradient Bevel1
window.unfocus.button: Sunken Diagonal Gradient Bevel1
window.button.pressed: Flat Diagonal Interlaced Gradient
window.frame: Raised Solid Bevel1
! window colors
window.focus.color: grey
window.focus.colorTo: grey20
window.focus.textColor: grey85
window.focus.button.color: grey
window.focus.button.colorTo: grey20
window.unfocus.color: rgb:8/8/7
window.unfocus.colorTo: grey20
window.unfocus.textColor: grey
window.unfocus.button.color: grey20
window.unfocus.button.colorTo: grey
window.button.pressed.color: rgb:4/4/38
window.button.pressed.colorTo: rgb:f/f/d
window.frame.color: grey85
! misc...
borderColor: rgb:2/2/1c
moveStyle: Opaque
menuJustify: CenterJustify
titleJustify: CenterJustify
bevelWidth: 2
handleWidth: 4
menuFont: lucidasans-10
titleFont: lucidasans-bold-10
rootCommand: fbsetroot -mod 4 4 -fg rgb:6/6/5c -bg grey20
...
Alright! Our style is finished. Let's see how the sucker looks. First we
need to tell Blackbox to use the new style. The way to do that is to edit
your menu (refer to README.menu for this) and add:
[style] (Results) {~/.blackbox/Styles/results}
somewhere in our menu. Taking advantage of Blackbox 0.51.x's (and up)
automagic menu updates, all we have to do is close and reopen the root menu
and our new style entry will be visible. Select it and Blackbox will apply
the new style we just created.