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