fix up the otk description
[dana/openbox.git] / doc / openbox.1.in
1 .\"
2 .\" Man page for Openbox
3 .\"
4 .\" Copyright (c) 2000 by Wilbert Berendsen <wbsoft@xs4all.nl>
5 .\"
6 .\" This manual page may be freely distributed and modified.
7 .\" Parts of the text are taken from website and several README's
8 .\" by His Great Hughesness himself. Why reinvent wheels?
9 .\"
10 .\" Created with NEdit, tested with ``man'' and ``tkman.''
11 .\" This manpage uses only standard groff and tmac.an macros.
12 .\" To all translators who didn't do manpages earlier (like me ;-):
13 .\" Read the Man-Page-Mini-HOWTO and the LDP manpage ``man 7 man''
14 .\" There's all I needed to know about these macros.
15 .\"
16 .\" Updated for bb 0.61 at Sat Sep  9 06:56:04 CEST 2000
17 .\"
18 .\" ..define sort of <blockquote><pre> macro
19 .de EX
20 .ne 5
21 .if n .sp 1
22 .if t .sp .5
23 .nf
24 .in +.5i
25 ..
26 .de EE
27 .fi
28 .in -.5i
29 .if n .sp 1
30 .if t .sp .5
31 ..
32 .TH openbox 1 "April 8th, 2002" "@VERSION@"
33 .SH NAME
34 openbox \- a window manager for X11
35 .SH SYNOPSIS
36 .BR openbox " \-help | \-version"
37 .br
38 .B openbox 
39 .RI "[ \-rc" " rcfile " "] [ \-display" " display " ]
40 .SH DESCRIPTION
41 .\"
42 .\" First few Paragraphs taken from FILLMEINNOW
43 .\"
44 .\"Openbox is yet another addition to the list of window managers for the Open
45 .\"Group's X Window System, Version 11 Release 6 and above.
46 .\"Openbox is built with C++, sharing no common code with any other window
47 .\"manager (even though the graphics implementation is similar to that of Window
48 .\"Maker).
49 .\".PP
50 .\"From the time the first line of code was written, Openbox has evolved around
51 .\"one premise, minimalism.
52 .\"It's not meant to be Eye Candy, nor the most Featureful, nor the most Adorned
53 .\"for modelling the Widely acclaimed NeXT interface.
54 .\"It is just meant to be
55 .\".BR fast .
56 .\".PP
57 .\"Openbox provides configurable window decorations, a root menu to launch
58 .\"applications, and a toolbar that shows the current workspace name, the focused
59 .\"application name, and the current time.
60 .\"There is also a workspace menu to add or remove workspaces. The `slit' can be
61 .\"used to dock small applications, e.g. most of the bbtools can use the slit.
62 .\".PP
63 .\"Openbox features a special kind of icon handling: When you minimize a window,
64 .\"no icon appears; instead, you can view all minimized applications in the `Icons'
65 .\"submenu of the workspace menu.
66 .\"Your desktop will never get cluttered with icons. As an alternative to icons,
67 .\"shaded windows are provided: A double click on the titlebar of a window will
68 .\"shade it (i.e. the window will disappear; only the titlebar stays visible).
69 .\".PP
70 .\"Openbox uses its own graphics class to render its images on the fly.
71 .\"By using style files, you can determine at a great level how your desktop looks.
72 .\"Openbox currently uses the Blackbox protocol to communicate with other clients
73 .\"such as the pager.  Work is underway to support the new window manager
74 .\"specification that both GNOME and KDE use.
75 .SH OPTIONS
76 Openbox supports the following command line options:
77 .TP
78 .B \-help
79 Display command line options and compiled-in features, then exit.
80 .TP
81 .B \-version
82 Display version info and exit.
83 .TP
84 .BI \-rc \ rcfile
85 Use another rcfile than the default
86 .IR  "~/.openbox/rc" .
87 .TP
88 .BI \-display \ display
89 Start Openbox on the specified display.
90 Programs started by Openbox will have the
91 .B DISPLAY
92 environment variable set to this value, too.
93 .SH RUNNING OPENBOX
94 This program is usually started by the user's startup script, most times called
95 .IR ~/.xinitrc .
96 To run openbox, modify the script by adding
97 .EX 0
98 exec openbox
99 .EE
100 as the last executed command of the script.
101 When Openbox terminates, the X session will terminate too.
102 .PP
103 When started, Openbox will try to find a default menu file in
104 .IR @defaultmenu@ .
105 You can provide a system-wide menu for your users here.
106 .PP
107 On exit or restart, Openbox will save user defaults in the file
108 .I ~/.openbox/rc
109 in the user's home directory.
110 Some resources in this file can be edited by hand.
111 .SH USING OPENBOX
112 Openbox does no keyboard handling by itself; instead, it relies on an external
113 program
114 .IR epist (1)
115 or
116 .IR bbkeys (1)
117 for this.
118 So, in this section, we will discuss all mouse commands.
119 .SS Root window (background):
120 A right click (button 3) will pop up the root menu.
121 With this, you can launch your applications.
122 You can also customize this menu for your needs.  See above for its location.
123 A middle click (button 2) will pop up the workspace menu.
124 You can add or remove a workspace, view
125 applications running on all workspace, inspect your iconified applications,
126 and jump directly to any workspace or application.
127 .PP
128 Left clicking (button 1) on an application in the Workspaces menu will bring
129 you to that workspace and raise/focus that application;
130 middle clicking (button 2) will warp the application to the current workspace.
131 .SS Toolbar:
132 The toolbar consists of three fields: a workspace name, the name of the
133 window that currently has focus, and a clock.
134 A left click on the toolbar will bring it to the foreground, a
135 middle click will hide it behind other windows (if AlwaysOnTop is not set), and
136 the right button will bring up a little menu.
137 .PP
138 Using this menu, you can enter a name for the current workspace (when finished,
139 press Enter).
140 Also, you can choose the toolbar's position, whether or not it
141 should be always on top (i.e. it cannot be obscured by other windows),
142 and whether it should hide itself when the mouse moves away.
143 .PP
144 Note: In Openbox versions below 0.60.0, a right click on the toolbar
145 immediately entered workspace name edit mode.
146 .SS Window Titlebar and Borders:
147 A left click on any part of the window's border will raise it.
148 Dragging then moves the window.
149 Dragging the resize grips at the bottom left and bottom right
150 corners resizes the window.
151 Middle clicking will immediately lower the window.
152 Right clicking on the border or titlebar pops up the window menu,
153 containing these commands:
154 .TP
155 .B Send To...
156 Send window to another workspace.
157 When you select the workspace with the middle button, Openbox will
158 send you, along with the application, to the selected workspace.
159 .TP
160 .B Shade
161 Shade window (display titlebar only).
162 .TP
163 .B Iconify
164 Iconify window.
165 The `icon' can be found in the `Icons' submenu of the workspace menu.  It will
166 *NOT* appear on screen otherwise.
167 .TP
168 .B Maximize
169 (Un)Maximize window.
170 When you click the middle button on this item, the
171 window will maximize only vertically.
172 .TP
173 .B Raise
174 Raise window.
175 .TP
176 .B Lower
177 Lower window.
178 .TP
179 .B Stick
180 (Un)Stick window.
181 A stuck window will always be displayed in the current workspace.
182 .TP
183 .B Kill Client
184 Kill (-SIGKILL) owner of window.  Only use this if the client refuses to close.
185 .TP
186 .B Close
187 Close the application cleanly.
188 .PP
189 When you double click on the titlebar of a window, it will `shade', so
190 that only the titlebar stays visible.
191 Another double click will redisplay the window contents.
192 .SS Window Buttons:
193 The button at the left upper corner of a window is the Minimize button.
194 Clicking with any button causes the window to be iconified.
195 The rightmost button (with the X) closes the application.
196 The other button on the right (if present) maximizes the window in three ways:
197 Button 1 causes full screen maximization, button 2 maximizes the window only
198 vertically, and button 3 only horizontally.
199 .SS Any menu:
200 Clicking button 3 in a menu will popdown the menu.
201 Clicking button 1 on the titlebar of any (sub)menu and then dragging it somewhere
202 else will cause the menu to stay visible, and not disappear when you click on
203 a menu item.
204 .SS Miscellaneous:
205 When you want to drag a window, but cannot see either the bottom handle or its
206 titlebar, you can press Alt + button 1 anywhere in the window and then
207 drag it around.
208 You can also use Alt + button 1 to raise a partially visible window.
209 Finally, Alt + button 2 lowers a window, and Alt + button 3 resizes the window.
210 .SH MENU FILE
211 A default menu file is installed in
212 .IR @defaultmenu@ .
213 Of course, this system-wide menu can be customized for all users at once.
214 But it is also possible to create a personal menu.
215 It is a convention to use the directory
216 .IR "~/.openbox/"
217 in your home directory, and to create a menu file, e.g.
218 .I menu
219 in this directory, or copy the system-wide menu file to this location.
220 Next, we have to tell Openbox to load our menu file instead of the default.
221 This is accomplished by adding (or changing) a resource value in the
222 .I ~/.openbox/rc
223 file, e.g.:
224 .EX
225 session.menuFile:       ~/.openbox/menu
226 .EE
227 For this change to take effect, Openbox has to be restarted.
228 Be sure that your menu is usable, then choose `Restart' from the default
229 Openbox root menu.
230 .SS Menu syntax
231 The menu syntax is very simple and very effective.
232 There are up to three fields in a menu line.
233 They are of the form:
234 .EX
235 [tag] (label or filename) {command or filename}
236 .EE
237 The supported tags are as follows:
238 .TP
239 .B [begin] (label for root menu)
240 This tells Openbox to start parsing the menu file.
241 This tag is required for Openbox to parse your menu file.
242 If it cannot find it, the system default menu is used instead.
243 .TP
244 .B [end]
245 This tells Openbox that it is at the end of a menu.
246 This can either be a submenu or the main root menu.
247 There must be at least one of these tags in your menu to correspond to the
248 required [begin] tag.
249 .TP
250 .B [exec] (label for command) {shell command}
251 Inserts a command item into the menu.
252 When you select the menu item from the menu, Openbox runs `shell command.'
253 .TP
254 .B [exit] (label for exit)
255 Inserts an item that shuts down and exits Openbox.
256 Any running programs are not closed.
257 .TP
258 .B [include] (filename)
259 Parses the file specified by
260 .I filename
261 and includes it with the current menu. The filename can be the full path to a
262  file, or it can begin with
263 .IR ~/ ,
264 which will be expanded into your home directory (e.g.
265 .EX
266 [include] (~/.openbox/stylesmenu)
267 .EE
268 will include
269 .I /home/bhughes/.openbox/stylesmenu
270 in my menu).
271 .TP
272 .B [nop] (label - optional)
273 Insert a non-operational item into the current menu.
274 This can be used to help format the menu into blocks or sections
275 if so desired.
276 .B [nop]
277 does accept a label, but it is not required, and a blank item will be used
278 if none is supplied.
279 .TP 
280 .B [style] (label) {filename}
281 This tells Openbox to insert an item that, when selected, reads the style file
282 named
283 .I filename
284 and applies the new textures, colors, and fonts to the current
285 running session.
286 .TP
287 .B [stylesdir] (directory name)
288 Reads all filenames (directories are ignored) from the specified directory and
289  creates menu items in the current menu for every filename.  Openbox assumes
290  that each file is a valid style file.  When selected by the user, Openbox 
291 applies the selected style file to the current session.
292 The labels that are created in the menu are the filenames of the style files.
293 .TP
294 .B [stylesmenu] (label) {directory name}
295 Creates a submenu entry with
296 .I label 
297 (that is also the title of the new submenu), and inserts in that submenu all
298 filenames in the specified directory, in the same way as the
299 .B [stylesdir]
300 command does.
301 .IP
302 .RB Both\  [stylesdir] \ and\  [stylesmenu]
303 commands make it possible to install style files without editing your menu file.
304 .TP
305 .B [submenu] (label) {title for menu - optional}
306 This tells Openbox to create and parse a new menu.
307 This menu is inserted as a submenu into the parent menu.
308 These menus are parsed recursively, so there is no limit to the number of levels
309 or nested submenus you can have.
310 The title for the new menu is optional; if none is supplied,
311 the new menu's title is the same as the item label.
312 An
313 .B [end]
314 tag is required to end the submenu.
315 .TP
316 .B [reconfig] (label)
317 When selected, this item rereads the current style, menu files and rc file,
318 and applies any changes.
319 This is useful for creating a new style or theme, as you don't have to
320 constantly restart Openbox every time you save your style.
321 However, Openbox automagically rereads the menu whenever it changes.
322 .TP
323 .B [restart] (label) {shell command - optional}
324 This tells Openbox to restart.
325 If `shell command' is supplied, it shuts down and runs the command (which is
326 commonly the name of another window manager).
327 If the command is omitted, Openbox restarts itself.
328 .TP
329 .B [config] (label)
330 Inserts a Openbox generated submenu item containing numerous configuration
331 options concerning window placement, focus style, window moving style, etc.
332 .TP
333 .B [workspaces] (label)
334 This tells Openbox to insert a link to the workspaces menu directly
335 into your menu.
336 This is handy for those users who can't access the
337 workspace menu directly (e.g. if you don't have a 3 button mouse).
338 .PP
339 Any line that starts with a `#' is considered a comment and ignored by Openbox.
340 Also, in the labels/commands/filenames fields,
341 you can escape any character like so:
342 .EX
343 [exec] (\\(my cool\\) \\{XTERM\\}) {xterm -T \\"cool XTERM\\"}
344 .EE
345 Using `\\\\' inserts a literal back-slash into the label/command/filename field.
346 .SS Menu example
347 Now let's put together some things.
348 Here is a short example of a menu file:
349 .PP
350 .nf
351 # Openbox menu file
352 [begin] (Openbox @version@)
353   [exec] (rxvt) {rxvt -ls}
354   [exec] (Mozilla) {mozilla}
355   [exec] (The GIMP) {gimp}
356   [submenu] (Window Manager)
357     [exec] (Edit Menus) {nedit .openbox/Menu}
358     [submenu] (Style) {Which Style?}
359       [stylesdir] (~/.openbox/styles)
360       [stylesmenu] (Openbox Styles) {@pkgdatadir@/styles}
361     [end]
362     [config] (Config Options)
363     [reconfig] (Reconfigure)
364     [restart] (Restart)
365   [end]
366   [exit] (Log Out)
367 [end]
368 # end of menu file
369 .fi
370 .SH STYLES
371 Openbox enables you to use specialized files that contain
372 .IR X (1)
373 resources to specify colors, textures, and fonts and therefore
374 the overall look of your window borders, menus, and the toolbar.
375 .PP
376 The default installation of Openbox provides some of these style files.
377 Usually they are put in
378 .IR @pkgdatadir@/styles .
379 You can study or edit these files to grasp how the Openbox style mechanism
380 works.
381 You can use the
382 .BR [style] ", " [stylesdir] " and " [stylesmenu]
383 menu commands in your menu file to be able to select and change between styles
384 on the fly.
385 .PP
386 You can also create a directory in your home directory (usually named
387 .I ~/.openbox/styles)
388 and put your own style files there.
389 Of course, you may choose any name for this directory, but many downloadable
390 themes will rely on the name
391 .I styles
392 (following the bb.themes.org naming scheme).
393 .PP
394 To understand how the style mechanism works, you should have a little knowledge
395 of how X resources work.
396 .PP
397 X resources consist of a key and a value.
398 The key is constructed of several smaller keys (sometimes referred to as
399 children), delimited by a period (`.').
400 Keys may also contain a star (`*') to serve as a wildcard, which means that one
401 line of typed text will match several keys.
402 This is useful for styles that are based on one or two colors.
403 .PP
404 Openbox allows you to configure its four main components: the toolbar, the
405 slit, the menus, and the window decorations.
406 .PP
407 The little window that shows the x-y position while dragging windows borrows
408 its style from the window's titlebar.
409 .PP
410 Here are some quick examples:
411 .EX
412 toolbar.clock.color:    green
413 .EE
414 This sets the color resource of the toolbar clock to `green'. Another example:
415 .EX
416 menu*color:     rgb:3/4/5
417 .EE
418 This sets the color resource of the menu
419 .I and all of its `children'
420 to `rgb:3/4/5'.
421 (For a description of color names, see
422 .IR X (1).)
423 So this one also applies to
424 .IR menu.title.color " and " menu.frame.color .
425 And with
426 .EX
427 *font:  -b&h-lucida-medium-r-normal-*-*-140-*
428 .EE
429 you set the font resource for all keys to this font name all at once.
430 (For information about the fonts installed on your system, you can use a program like
431 .IR xfontsel "(1), " gtkfontsel ", or " xlsfonts "(1).)"
432 .PP
433 Now what makes Openbox just so spectacular is its ability to render textures
434 on the fly.
435 Texture descriptions are specified in a similar way to the colors shown above
436 e.g.:
437 .ta \w'toolbar.clock.colorTo:\ 'u
438 .EX
439 toolbar.clock:  Raised Gradient Diagonal Bevel1
440 toolbar.clock.color:    rgb:8/6/4
441 toolbar.clock.colorTo:  rgb:4/3/2
442 .EE
443 Don't worry; we will explain right now!
444 A texture description consists of up to five fields, which are as follows:
445 .TP
446 .B Flat / Raised / Sunken
447 gives the component either a flat, raised, or sunken appearance.
448 .TP
449 .B Gradient / Solid
450 tells Openbox to draw either a solid color or a texture with gradient.
451 .TP
452 .B Horizontal / Vertical / Diagonal / Crossdiagonal / Pipecross / Elliptic / Rectangle / Pyramid
453 Select one of these texture types. They only work when
454 .B Gradient
455 is also specified!
456 .TP
457 .B Interlaced
458 tells Openbox to interlace the texture (darken every other line).
459 This option is most commonly used with gradiented textures, but, from Openbox
460 version 0.60.3 on, it also works in solid textures.
461 .TP
462 .B Bevel1 / Bevel2
463 tells Openbox which type of bevel to use.
464 Bevel1 is the default bevel.
465 The shading is placed on the edge of the image.
466 Bevel2 is an alternative.
467 The shading is placed one pixel in from the edge of the image.
468 .PP
469 Instead of a texture description, the option
470 .B ParentRelative
471 is also available, which makes the component appear as a part of its parent, i.e.
472 totally transparent.
473 .PP
474 All gradient textures are composed of two color values: the
475 .IR color " and " colorTo " resources."
476 color represents the initial color, colorTo represents the final color of the
477 gradient.
478 When
479 .B Interlaced 
480 is used in
481 .B Solid
482 mode, the
483 .I colorTo
484 resource is used to specify the interlacing color.
485 .PP
486 Well, here is the complete component list; also, all components together with
487 which kind of value they can contain.
488 Comments are preceded with an exclamation sign (!), which is also used for
489 comments in Openbox style c.q. X resource files.
490 .PP
491 .ta \w'window.button.unfocus.picColor: \ 'u 
492 .nf
493 .\"
494 .\" The comments also to be translated!
495 .\"
496 ! The toolbar itself.
497 toolbar:        Texture
498 toolbar.color:  Color
499 toolbar.colorTo:        Color
500
501 ! The buttons on the toolbar.
502 toolbar.button: Texture or \fIParentRelative\fR
503 toolbar.button.color:   Color
504 toolbar.button.colorTo: Color
505
506 ! Color of the button arrows.
507 toolbar.button.picColor:        Color
508
509 ! Buttons in pressed state.
510 toolbar.button.pressed: Texture \fI(e.g. Sunken)\fR or \fIParentRelative\fR
511 toolbar.button.pressed.color:   Color
512 toolbar.button.pressed.colorTo: Color
513
514 ! Color of pressed button arrows.
515 toolbar.button.pressed.picColor:        Color
516
517 ! The toolbar workspace label.
518 toolbar.label:  Texture or \fIParentRelative\fR
519 toolbar.label.color:    Color
520 toolbar.label.colorTo:  Color
521 toolbar.label.textColor:        Color
522
523 ! The toolbar window label.
524 toolbar.windowLabel:    Texture or \fIParentRelative\fR
525 toolbar.windowLabel.color:      Color
526 toolbar.windowLabel.colorTo:    Color
527 toolbar.windowLabel.textColor:  Color
528
529 ! The toolbar clock.
530 toolbar.clock:  Texture or \fIParentRelative\fR
531 toolbar.clock.color:    Color
532 toolbar.clock.colorTo:  Color
533 toolbar.clock.textColor:        Color
534
535 ! How the toolbar's text should be justified.
536 toolbar.justify:        \fIcenter\fR, \fIleft\fR, or \fIright\fR
537
538 .ta \w'toolbar.font:\ 'u 
539 ! Font to be used for all toolbar components.
540 toolbar.font:   Font \fI(e.g. -*-helvetica-medium-r-normal-*-*-100-*)\fR
541
542 .ta \w'window.button.unfocus.picColor: \ 'u 
543 ! The menu titlebar.
544 menu.title:     Texture
545 menu.title.color:       Color
546 menu.title.colorTo:     Color
547 menu.title.textColor:   Color
548 menu.title.font:        Font
549 menu.title.justify:     \fIcenter\fR, \fIleft\fR, or \fIright\fR
550
551 ! The menu frame.
552 menu.frame:     Texture
553 menu.frame.color:       Color
554 menu.frame.colorTo:     Color
555 menu.frame.textColor:   Color
556 menu.frame.disableColor:        Color
557 menu.frame.font:        Font
558 menu.frame.justify:     \fIcenter\fR, \fIleft\fR, or \fIright\fR
559
560 ! Bullets for submenu items.
561 menu.bullet:    \fIempty\fR, \fItriangle\fR, \fIsquare\fR, or \fIdiamond\fR
562 menu.bullet.position:   \fIright\fR or \fIleft\fR
563
564 ! The highlighted menu item.
565 menu.hilite:    Texture (e.g. \fIRaised\fR)
566 menu.hilite.color:      Color
567 menu.hilite.colorTo:    Color
568 menu.hilite.textColor:  Color
569
570 ! A focused window.
571 window.title.focus:     Texture
572 window.title.focus.color:       Color
573 window.title.focus.colorTo:     Color
574
575 ! An unfocused window.
576 window.title.unfocus:   Texture
577 window.title.unfocus.color:     Color
578 window.title.unfocus.colorTo:   Color
579
580 ! Window label.
581 window.label.focus:     Texture or \fIParentRelative\fR
582 window.label.focus.color:       Color
583 window.label.focus.colorTo:     Color
584 window.label.focus.textColor:   Color
585
586 window.label.unfocus:   Texture or \fIParentRelative\fR
587 window.label.unfocus.color:     Color
588 window.label.unfocus.colorTo:   Color
589 window.label.unfocus.textColor: Color
590
591 ! Handlebar.
592 window.handle.focus:    Texture
593 window.handle.focus.color:      Color
594 window.handle.focus.colorTo:    Color
595
596 window.handle.unfocus:  Texture
597 window.handle.unfocus.color:    Color
598 window.handle.unfocus.colorTo:  Color
599
600 ! Resize grips.
601 window.grip.focus:      Texture
602 window.grip.focus.color:        Color
603 window.grip.focus.colorTo:      Color
604
605 window.grip.unfocus:    Texture
606 window.grip.unfocus.color:      Color
607 window.grip.unfocus.colorTo:    Color
608
609 ! Window buttons.
610 window.button.focus:    Texture or \fIParentRelative\fR
611 window.button.focus.color:      Color
612 window.button.focus.colorTo:    Color
613 window.button.focus.picColor:   Color
614
615 window.button.unfocus:  Texture or \fIParentRelative\fR
616 window.button.unfocus.color:    Color
617 window.button.unfocus.colorTo:  Color
618 window.button.unfocus.picColor: Color
619
620 window.button.pressed:  Texture (e.g. \fISunken\fR)
621 window.button.pressed.color:    Color
622 window.button.pressed.colorTo:  Color
623
624 .ta \w'window.button.pressed.unfocus.colorTo:\ 'u 
625 ! If either the focused, or unfocused pressed button isn't
626 ! defined, it will use the normal pressed: resource
627 window.button.pressed.focus:    Texture (eg. \fISunken\fR)
628 window.button.pressed.focus.color:      Color
629 window.button.pressed.focus.colorTo:    Color
630 window.button.pressed.unfocus:  Texture (eg. \fISunken\fR)
631 window.button.pressed.unfocus.color:    Color
632 window.button.pressed.unfocus.colorTo:  Color
633
634 .ta \w'window.button.unfocus.picColor:\ 'u 
635 ! Frame around window.
636 window.frame.focusColor:        Color
637 window.frame.unfocusColor:      Color
638
639 ! Font and justification for window labels.
640 window.font:    Font
641 window.justify: \fIcenter\fR, \fIleft\fR, or \fIright\fR
642
643 ! Miscellaneous resources.
644
645 ! A border can be drawn around all components.
646 borderWidth:    a number of pixels, e.g. \fI1\fR
647 borderColor:    Color
648
649 bevelWidth:     a number of pixels > 0
650 handleWidth:    a number of pixels > 0
651
652 ! Width of the window frame (from version 0.61 on).
653 ! When not specified, frameWidth defaults to the value of bevelWidth.
654 frameWidth:     a number of pixels >= 0
655
656 ! This command is executed whenever this style is selected.
657 ! Typically it sets the root window to a nice picture.
658 rootCommand: Shell command, e.g. \fIbsetroot -mod 4 4 -fg rgb:  5/6/6 -bg grey20\fR
659
660 ! Some of the bbtools read these old 0.51 resources.
661 menuFont:       Font
662 titleFont:      Font
663 .fi
664 .PP
665 Now, this seems a long list, but, remember, when you create your own style, you
666 can easily set lots of keys with a single command, e.g.
667 .EX
668 .ta \w'*unfocus.textColor:\ 'u
669 *color: slategrey
670 *colorTo:       darkslategrey
671 *unfocus.color: darkslategrey
672 *unfocus.colorTo:       black
673 *textColor:     white
674 *unfocus.textColor:     lightgrey
675 *font:  lucidasans-10
676 .EE
677 This sets already nice defaults for many components.
678 .PP
679 Openbox also lets you pick what the small graphics in the buttons and in the manu look like. It uses the X Bitmap file format (.xbm extension). The style resources are as follows:
680 .EX
681 ! Close, maximize, sticky and iconify
682 ! buttons on a window.
683 window.button.close.mask:       xbm file
684 window.button.max.mask:         xbm file
685 window.button.stick.mask:       xbm file
686 window.button.icon.mask:        xbm file
687
688 ! The icon for submenus in a menu.
689 menu.arrow.mask:                xbm file
690
691 ! The icon for a selected option or workspace
692 ! in the menus.
693 menu.selected.mask:             xbm file
694
695 ! The left and right buttons in the toolbar
696 toolbar.button.left.mask:       xbm file
697 toolbar.button.right.mask:      xbm file
698 .EE
699 If the xbm file value is the path to a .xbm image. If the value is absolute, it uses that file. If the file is just a file name, e.g. `close.xbm', it uses ~/.openbox/buttons/close.xbm.
700 .SH THE SLIT
701 The slit is a special Openbox window frame that can contain dockable
702 applications, e.g. the `bbtools' or WindowMaker's dockapps.
703 When applications are run in the slit, they have no window borders of their own;
704 instead, they are framed in the slit, and they are always visible in the current
705 workspace.
706 You can click button 3 on the edge of the slit window to get a menu to
707 determine its position, whether its contained applications should be grouped
708 horizontally or vertically and whether it should hide itself when the
709 mouse moves away.
710 .PP
711 Most dockable applications use the
712 .B -w
713 option to run in the slit.
714 For example, you could put in your
715 .IR ~/.xinitrc :
716 .EX
717 bbmail -w &
718 bbpager -w &
719 exec openbox
720 .EE
721 Of course, to use the slit, you must have slit support compiled in (this is
722 the default).
723 .SH RESOURCE FILE
724 Usually the
725 .I ~/.openbox/rc
726 resource file is created and maintained by Openbox itself.
727 All options from the
728 .B [config]
729 menu (from 0.60.x on), the last selected style file, your workspace names and
730 so on are saved automatically in this file.
731 However, there are some resources in it you might want to edit yourself:
732 .TP
733 .B session.menuFile:
734 This tells Openbox where to look for its menu file.
735 .TP
736 .B session.screen0.toolbar.widthPercent:
737 This determines the amount (in %) of space the toolbar will take.
738 Default value is:
739 .IR 66 .
740 .TP
741 .B session.screen0.strftimeFormat:
742 This adjusts the way the current time is displayed in the toolbar.
743 The
744 .IR strftime (3)
745 format is used.
746 Default value is:
747 .IR "%I:%M %p" .
748 .TP
749 .B session.autoRaiseDelay:
750 This adjusts the delay (in ms) before focused windows will raise when using the
751 Auto Raise option.
752 Default value is:
753 .IR 250 .
754 .TP
755 .B session.doubleClickInterval:
756 This adjusts the delay (in ms) between mouse clicks for Openbox to consider a double click.
757 Default value is:
758 .IR 250 .
759 .TP
760 .B session.screen0.edgeSnapThreshold:
761 When moving a window across your screen, Openbox is able to have it `snap' to
762 the edges of the screen for easy placement.
763 This variable tells Openbox the distance (in pixels) at which the window will
764 jump to the edge.
765 Default value is:
766 .IR 0 .
767 .TP
768 .B session.cacheMax:
769 This tells Openbox how much memory (in Kb) it may use to store cached pixmaps on
770 the X server.
771 If your machine runs short of memory, you may lower this value.
772 Default value is:
773 .IR 200 .
774 .TP
775 .B session.cacheLife:
776 This tells Openbox how long (in minutes) unused pixmaps may stay in the X
777 server's memory.
778 Default value is:
779 .IR 5 .
780 .TP
781 .B session.titleBarLayout:
782 The order of the elements of window titlebars. This is a string built
783 of the following characters:
784 .IP
785 .nf I: Iconify button
786 L: Label (window title)
787 M: Maximize button
788 S: Sticky button
789 C: Close button 
790 .fi
791 .IP
792 The order in which these character appear in the string is the order they will appear in window titlebars. You can also omit an item to not have it appear in the titlebar at all, except for the label which will always appear.
793 Default value is:
794 .IR ILMC
795 .TP
796 .B session.colorsPerChannel:
797 This tells Openbox how many colors to take from the X server on pseudocolor
798 displays.  A channel would be red, green, or blue.
799 Openbox will allocate this variable ^ 3 colors and make them always available.
800 This value must be between 2 and 6.
801 When you run Openbox on an 8-bit display, you must set this resource to 4.
802 Default value is:
803 .IR 4.
804 .PP
805 When running Openbox in a multiple desktop environment, the
806 .B screen0
807 key can also be
808 .B screen1, 2
809 etc. for any appropriate desktop.
810 .SH ENVIRONMENT
811 .TP
812 .B HOME
813 Openbox uses
814 .RB $ HOME
815 to find its
816 .I .openbox/rc
817 file, and to resolve style file and directory names.
818 .TP
819 .B DISPLAY
820 When no other display was given on the command line, Openbox will start on the
821 display specified by this variable.
822 .SH AUTHOR and CREDITS
823 All of the code was initially written and maintained as Blackbox by Brad Hughes
824 .nh \" hyphenation off
825 (blackbox@alug.org)
826 .hy \" on again
827 and then Jeff Raven
828 .nh
829 (jraven@psu.edu),
830 .hy
831 and then Sean 'Shaleh' Perry
832 .nh
833 (shaleh@debian.org)
834 .hy
835 .hy
836 and is now maintained as Openbox by Ben Jansens
837 .nh
838 (ben@orodu.net)
839 .hy
840 with contributions and patches merged from
841 many individuals around the world.
842 .PP
843 The official Openbox website:
844 .nh
845 .B http://openbox.sunsite.dk/
846 .hy
847 .br
848 Many themes and other contributions:
849 .nh
850 .B http://themes.freshmeat.net/
851 .hy
852 .PP
853 This manpage was put together by Wilbert Berendsen
854 .nh
855 (wbsoft@xs4all.nl).
856 .hy
857 Numerous other languages will be available.
858 .SH SEE ALSO
859 .IR bsetroot (1), \ bbkeys (1), \ xftlsfonts (1), \ epist (1)