372 lines
12 KiB
Text
372 lines
12 KiB
Text
-- 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.
|