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