2
Creating a user defined menu:
3
-----------------------------
4
Creating a menu for Blackbox requires a text editor of some sort. Familiarity
5
with your choice of text editor is assumed, since editor preference differs
6
as much (if not more than) window manager preference.
8
First, we need to decide on a location for our custom menu. Your home
9
directory is the most logical solution, since you will most likely not have
10
write access anywhere else. You place the menu file in any directory, and
11
give it any name you choose, as we will later tell Blackbox the path or
12
location for this file.
14
As an example, let's assume that my home directory is `/home/bhughes' (which it
15
is). I've decided to keep all my Blackbox related files in a directory named
16
`blackbox.' After creating the directory, I now have two options for creating
17
my new menu. I can either copy the system default (usually in
18
`/usr/local/share/Blackbox/menu') to this directory, or I can create a new
19
one from scratch. Let's do the latter, for the sake of completeness.
21
I've decided to name the file `rootmenu.' I fire up my favorite text editor
22
and now have a clean file. So let's begin.
27
The menu syntax is very simple and very effective. There are upto three
28
fields in a menu line. They are of the form:
30
[tag] (label or filename) {command or filename}
32
The supported tags are as follows:
34
[begin] (label for root menu)
36
This tells Blackbox to start parsing the menu file. This tag is
37
required for Blackbox to parse your menu file. If it cannot find it,
38
the system default menu is used instead.
42
This tells Blackbox that it is at the end of a menu. This can either
43
be a submenu or the main root menu. There must be at least one
44
of these tags in your menu to correspond to the required [begin] tag.
46
[exec] (label for command) {shell command}
48
This tells Blackbox to insert a command item into the menu. When you
49
select the menu item from the menu, Blackbox runs `shell command.'
51
[exit] (label for exit)
53
This tells Blackbox to insert an item that shuts down and exits
54
Blackbox. Any open windows are reparented to the root window before
59
This tells Blackbox to parse the file specified by `filename' inline
60
with the current menu. `filename' can be the full path to a file
61
(such as /usr/local/share/Blackbox/brueghel/stylesmenu) or it can
62
begin with `~/', which will be expanded into your home directory
63
(e.g. [include] (~/blackbox/stylesmenu) will include
64
/home/bhughes/blackbox/stylesmenu in my menu)
66
[nop] (label - optional)
68
This tells Blackbox to insert a non-operational item into the current
69
menu. This can be used to help format the menu into blocks or sections
70
if so desired (e.g. you could put all your ssh accounts together, add
71
a [nop] and then add all your telnet accounts together). [nop] does
72
accept a label, but it is not required, and a blank item will be used
75
[style] (label) {filename}
77
This tells Blackbox to read `filename' and apply the new textures,
78
colors and fonts to the current running session. The filename is
79
just like the [include] tag, it can be the full path to the file,
80
or it can be of the form `~/path/from/home/dir.' Blackbox also
81
re-reads the entire menu structure from disk, incase the menu has
84
[submenu] (label) {title for menu - optional}
86
This tells Blackbox to create and parse a new menu. This menu is
87
inserted as a submenu into the parent menu. These menus are parsed
88
recursively, so there is no limit to the number of levels or nested
89
submenus you can have. The title for the new menu is optional, if
90
none is supplied, the new menu's title is the same as the item label.
94
This tells Blackbox to reread the current style and menu files and
95
apply any changes. This is useful for creating a new style or theme,
96
as you don't have to constantly restart Blackbox every time you save
99
[restart] (label) {shell command - optional}
101
This tells Blackbox to restart. If `shell command' is supplied, it
102
shuts down and runs the command (which is commonly the name of another
103
window manager). If the command is omitted, Blackbox restarts itself.
107
This tells Blackbox to insert a "link" to the workspaces menu directly
108
into your menu. This is handy for those users who can't access the
109
workspace menu directly (e.g. if you don't have a 3 button mouse, it's
110
rather hard to middle click to show the workspace menu). This is a
111
"link" to the systems workspace menu, so multiple [workspaces] tags
112
will display the same workspace menu, so expect it to move around if
117
This tells Blackbox to insert the ConfigMenu into your menu. From
118
this menu you can configure several options stored in your
119
~/.blackboxrc, and the changes take effect immediately.
121
Comments may be inserted on any line of the file, as long as the first
122
character on the line is a `#.'
124
Also, in the labels/commands/filenames fields, you can escape any character
127
[exec] (\(my cool\) \{XTERM\}) {\(xterm -T \\\"cool XTERM\\\"\)}
129
Using `\\' inserts a literal back-slash into the label/command/filename field.
132
Putting it all together:
133
------------------------
134
Alrighty, so let's see if we can understand the arcane incantation above. It
135
says we have to have a [begin] and an [end] tag, which create our menu and
136
give it a title. Let's do that first:
139
[begin] (Example \[Menu\])
143
Simple enough. Now let's add some items to the list. We always want to have
144
access to a terminal emulator, be it a regular xterm or something else.
145
So we add the item to our menu, and it now looks like this:
148
[begin] (Example \[Menu\])
149
[exec] (xterm) {xterm -ls}
153
Great! Now let's add us some items to run an irc client, netscape, xv and
154
some other common programs. This gives up this:
157
[begin] (Example \[Menu\])
158
[exec] (xterm) {xterm -ls}
159
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
160
[exec] (Netscape Navigator) {netscape}
161
[exec] (xv 3.10a) {xv}
162
[exec] (XEmacs) {xemacs}
163
[exec] (The GIMP) {gimp}
164
[exec] (Video Tune) {xvidtune}
168
Whoa, wait a second. This menu file is beginning to look a little cluttered.
169
Not a problem, just like programmers indent and space their code, we can
170
do this with our menu file, so let's clean it up a bit:
173
[begin] (Example \[Menu\])
174
[exec] (xterm) {xterm -ls}
175
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
177
[exec] (Netscape Navigator) {netscape}
178
[exec] (XEmacs) {xemacs}
180
[exec] (xv 3.10a) {xv}
181
[exec] (The GIMP) {gimp}
183
[exec] (Video Tune) {xvidtune}
187
Ahh... now that looks a little better. Now we decide that we kind of like the
188
spacing in the file, and decide we want to apply it to the menu itself. Now
189
we take advantage of the [nop] tag:
192
[begin] (Example \[Menu\])
193
[exec] (xterm) {xterm -ls}
194
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
198
[exec] (Netscape Navigator) {netscape}
199
[exec] (XEmacs) {xemacs}
203
[exec] (xv 3.10a) {xv}
204
[exec] (The GIMP) {gimp}
208
[exec] (Video Tune) {xvidtune}
212
Now, let's create a submenu to put some items to change between all these
213
themes we downloaded from http://blackbox.themes.org/. Let's assume we
214
untarred the themes into the ~/.blackbox directory like the documentation on
215
the themes.org site recommends.
218
[begin] (Example \[Menu\])
219
[exec] (xterm) {xterm -ls}
220
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
224
[exec] (Netscape Navigator) {netscape}
225
[exec] (XEmacs) {xemacs}
229
[exec] (xv 3.10a) {xv}
230
[exec] (The GIMP) {gimp}
234
[exec] (Video Tune) {xvidtune}
236
[submenu] (Themes) {Themes from blackbox.themes.org}
237
[style] (Blackbox) {~/.blackbox/Styles/blackbox}
238
[style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
239
[style] (Hardware) {~/.blackbox/Styles/hardware}
240
[style] (Nova) {~/.blackbox/Styles/nova}
241
[style] (Orbital) {~/.blackbox/Styles/orbital}
242
[style] (Orbital II) {~/.blackbox/Styles/orbital2}
243
[style] (Seething) {~/.blackbox/Styles/seething}
244
[style] (Zero) {~/.blackbox/Styles/zero}
245
[style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
250
Even better. Now hold on a second, if we have our themes and styles in
251
~/.blackbox why do we have to have our menu in ~/blackbox? Answer: WE DON'T!
252
This is where the choice comes. Do we keep our stuff in two separate
253
directories? Do we put it all in one directory? That is up to you to decide.
254
I personally prefer to keep everything in one directory (but, I use ~/blackbox
255
and have been for a long, long time; long before blackbox.themes.org was
256
even thought of... and again that is *personal* preference, not a hard-fast
259
Now that we've gotten a feel for the menu syntax, we decide to finish off our
260
menu. In addition to the styles we downloaded, we decide we also want to
261
keep a submenu for the default styles that came with Blackbox. All we need
262
to do is [include] the styles file from the share directory for Blackbox.
263
After putting everything together, we have:
267
# custom menu file for Blackbox
269
[begin] (Example \[Menu\])
270
[exec] (xterm) {xterm -ls}
271
[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
275
[exec] (Netscape Navigator) {netscape}
276
[exec] (XEmacs) {xemacs}
280
[exec] (xv 3.10a) {xv}
281
[exec] (The GIMP) {gimp}
285
[exec] (Video Tune) {xvidtune}
289
[submenu] (Themes) {Themes from blackbox.themes.org}
290
[style] (Blackbox) {~/.blackbox/Styles/blackbox}
291
[style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
292
[style] (Hardware) {~/.blackbox/Styles/hardware}
293
[style] (Nova) {~/.blackbox/Styles/nova}
294
[style] (Orbital) {~/.blackbox/Styles/orbital}
295
[style] (Orbital II) {~/.blackbox/Styles/orbital2}
296
[style] (Seething) {~/.blackbox/Styles/seething}
297
[style] (Zero) {~/.blackbox/Styles/zero}
298
[style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
300
# include the default style menu... this is assuming Blackbox was installed
305
[include] (/usr/local/share/Blackbox/styles/stylesmenu)
308
[workspaces] (Workspace list)
310
[submenu] (Restart) {Restart which?}
313
# let's also give us access to some other window managers
315
[restart] (Window Maker) {wmaker}
316
[restart] (Enlightenment) {enlightenment}
317
[restart] (KWM) {kwm}
318
[restart] (TWM) {twm}
323
[reconfig] (Reconfigure)
328
And voila! our menu file is finished. Now we need to tell Blackbox to read
329
this menu file. We do this by editing the file ~/.blackboxrc.
331
NOTE: your ~/.blackboxrc is auotmatically updated every time Blackbox restarts,
332
reconfigures, changes styles or exits. Changes to dynamic data like workspace
333
count, names, etc. is lost. About the only thing you can change and have it
334
preserved is the menu filename, which is what we are about to change.
336
The format of ~/.blackboxrc is in the X resource database format (just like
337
~/.Xdefaults). Since the file is updated automatically, it may be full of
338
stuff or it may not even exist (especially if this is the first time we've
339
ran Blackbox). Don't worry if you have to create ~/.blackboxrc, Blackbox will
340
see the file the next time it starts.
342
What we need to do is change the resource for the menu's filename. This is
343
done by changing (or adding) the line that looks like so:
346
session.menuFile: /path/to/some/file
349
If this resource exists, we change it. If it does not, we add it. Depending
350
on where we put the menu file, our new resource could look like this:
353
session.menuFile: /home/bhughes/blackbox/rootmenu
356
We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't work,
357
we need Blackbox to completely shutdown and reread ALL of it's configuration
358
files, not just the ones that control colors/fonts/etc.)
360
If we've done everything correctly, Blackbox restarts itself and our new menu
361
is now ready for use. If something doesn't work, read over the above example
362
again to make sure you didn't forget a step or leave out the necessary tags.
364
Now that Blackbox has been told where to find it's menu, it does a little more.
365
Blackbox 0.51.x introduces automagic menu updates. As long as you never
366
change session.menuFile, you will never have to restart or reconfigure Blackbox
367
whenever you change your menu. Blackbox watches the timestamps on all the
368
files it reads to build your menu. If any of them change, they are reread and
369
your menu updated. This check is done everytime you open the root menu. Like
370
I said... it is a check, it doesn't reread the menu everytime, it just looks
371
at the modification time and rereads when it changes.
added
removed
data/README.menu
