-- data/README.menu for Blackbox - 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
`/usr/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 up to
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 applications are left running.

[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
    /usr/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.

[sep]

    Inserts a horizontal separator.  This can be used similar to
    [nop] to format and organize your menus.

[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, in case the menu has changed.

[stylesdir] (directory)

    This tells Blackbox to create a [style] entry in the menu for every 
    file in the specified directory. If you put all of your styles
    into a single directory, this saves you having to create [style]
    entries for each one manually.

[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:
------------------------

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, a web
browser and some other common programs.  This gives up this:

    [begin] (Example \[Menu\])
    [exec] (xterm) {xterm -ls}
    [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}
    [exec] (Mozilla Navigator) {mozilla}
    [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] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}

        [exec] (Mozilla Navigator) {mozilla}
        [exec] (XEmacs) {xemacs}

        [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 [sep] tag:

    [begin] (Example \[Menu\])
        [exec] (xterm) {xterm -ls}
        [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}

        [sep]

        [exec] (Mozilla Navigator) {mozilla}
        [exec] (XEmacs) {xemacs}

        [sep]

        [exec] (The GIMP) {gimp}

        [sep]

        [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://themes.freshmeat.net/.  Let's
assume we untarred the themes into the ~/.blackbox directory like the
documentation recommends.

    [begin] (Example \[Menu\])
        [exec] (xterm) {xterm -ls}
        [exec] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}

        [sep]

        [exec] (Mozilla Navigator) {mozilla}
        [exec] (XEmacs) {xemacs}

        [sep]

        [exec] (The GIMP) {gimp}

        [sep]

        [exec] (Video Tune) {xvidtune}

        [submenu] (Themes) {Themes from themes.freshmeat.net}
            [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]

An advantage of keeping styles in a directory of their own, is that you can
use the [stylesdir] menu command to avoid having to add [style] entries
manually. If you put your styles into ~/.blackbox/styles, the above style 
menu can be made like this:

        [submenu] (Themes) {Themes from themes.freshmeat.net}
            [stylesdir] (~/.blackbox/styles)
        [end]

Even better.  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] (openprojects irc) {xterm -e irc fnord irc.openprojects.net}

        [sep]

        [exec] (Mozilla Browser) {mozilla}
        [exec] (XEmacs) {xemacs}

        [sep]

        [exec] (The GIMP) {gimp}

        [sep]

        [exec] (Video Tune) {xvidtune}

        [sep]

        [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

            [sep]

            [include] (/usr/local/share/blackbox/styles/stylesmenu)

    # or, we could use
    #       [stylesdir] (/usr/local/share/blackbox/styles)

        [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]

        [sep]

        [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.

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:    /usr/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 introduced automatic 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 every time you open the root menu.  Like
I said... it is a check, it doesn't reread the menu every time, it
just looks at the modification time and rereads when it changes.