Debian Codegraph @

data/README.menu

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