-- data/README.menu for Blackbox 0.51.x - an X11 Window manager
-- Copyright (c) 1997 - 1999 by Brad Hughes, bhughes@tcac.net
--
--  This program is free software; you can redistribute it and/or modify
--  it under the terms of the GNU General Public License as published by
--  the Free Software Foundation; either version 2 of the License, or
--  (at your option) any later version.
--
--  This program is distributed in the hope that it will be useful,
--  but WITHOUT ANY WARRANTY; without even the implied warranty of
--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
--  GNU General Public License for more details.
--
--  You should have received a copy of the GNU General Public License
--  along with this program; if not, write to the Free Software
--  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
--
-- (See the included file COPYING / GPL-2.0)
--

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. ;)

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.