2 .\" Man page for Openbox
4 .\" Copyright (c) 2000 by Wilbert Berendsen <wbsoft@xs4all.nl>
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?
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.
16 .\" Updated for bb 0.61 at Sat Sep 9 06:56:04 CEST 2000
18 .\" ..define sort of <blockquote><pre> macro
32 .TH openbox 1 "April 8th, 2002" "@VERSION@"
34 openbox \- a window manager for X11
36 .BR openbox " \-help | \-version"
39 .RI "[ \-rc" " rcfile " "] [ \-display" " display " ]
42 .\" First few Paragraphs taken from FILLMEINNOW
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
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
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.
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).
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.
76 Openbox supports the following command line options:
79 Display command line options and compiled-in features, then exit.
82 Display version info and exit.
85 Use another rcfile than the default
88 .BI \-display \ display
89 Start Openbox on the specified display.
90 Programs started by Openbox will have the
92 environment variable set to this value, too.
94 This program is usually started by the user's startup script, most times called
96 To run openbox, modify the script by adding
100 as the last executed command of the script.
101 When Openbox terminates, the X session will terminate too.
103 When started, Openbox will try to find a default menu file in
105 You can provide a system-wide menu for your users here.
107 On exit or restart, Openbox will save user defaults in the file
109 in the user's home directory.
110 Some resources in this file can be edited by hand.
112 Openbox does no keyboard handling by itself; instead, it relies on an external
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.
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.
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.
138 Using this menu, you can enter a name for the current workspace (when finished,
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.
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:
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.
161 Shade window (display titlebar only).
165 The `icon' can be found in the `Icons' submenu of the workspace menu. It will
166 *NOT* appear on screen otherwise.
170 When you click the middle button on this item, the
171 window will maximize only vertically.
181 A stuck window will always be displayed in the current workspace.
184 Kill (-SIGKILL) owner of window. Only use this if the client refuses to close.
187 Close the application cleanly.
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.
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.
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
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
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.
211 A default menu file is installed in
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 Openbox looks for a menu in your home directory under the location
216 .IR "~/.openbox/menu" .
217 You can copy the system-wide menu file to this location or create it by hand.
218 The next time you start/restart Openbox, it will use your custom menu file
219 instead of the system-wide one.
220 Be sure that your menu is usable, then choose `Restart' from the default
221 Openbox root menu to see your new menu in action.
223 The menu syntax is very simple and very effective.
224 There are up to three fields in a menu line.
225 They are of the form:
227 [tag] (label or filename) {command or filename}
229 The supported tags are as follows:
231 .B [begin] (label for root menu)
232 This tells Openbox to start parsing the menu file.
233 This tag is required for Openbox to parse your menu file.
234 If it cannot find it, the system default menu is used instead.
237 This tells Openbox that it is at the end of a menu.
238 This can either be a submenu or the main root menu.
239 There must be at least one of these tags in your menu to correspond to the
240 required [begin] tag.
242 .B [exec] (label for command) {shell command}
243 Inserts a command item into the menu.
244 When you select the menu item from the menu, Openbox runs `shell command.'
246 .B [exit] (label for exit)
247 Inserts an item that shuts down and exits Openbox.
248 Any running programs are not closed.
250 .B [include] (filename)
251 Parses the file specified by
253 and includes it with the current menu. The filename can be the full path to a
254 file, or it can begin with
256 which will be expanded into your home directory (e.g.
258 [include] (~/.openbox/stylesmenu)
261 .I /home/bhughes/.openbox/stylesmenu
264 .B [nop] (label - optional)
265 Insert a non-operational item into the current menu.
266 This can be used to help format the menu into blocks or sections
269 does accept a label, but it is not required, and a blank item will be used
272 .B [style] (label) {filename}
273 This tells Openbox to insert an item that, when selected, reads the style file
276 and applies the new textures, colors, and fonts to the current
279 .B [stylesdir] (directory name)
280 Reads all filenames (directories are ignored) from the specified directory and
281 creates menu items in the current menu for every filename. Openbox assumes
282 that each file is a valid style file. When selected by the user, Openbox
283 applies the selected style file to the current session.
284 The labels that are created in the menu are the filenames of the style files.
286 .B [stylesmenu] (label) {directory name}
287 Creates a submenu entry with
289 (that is also the title of the new submenu), and inserts in that submenu all
290 filenames in the specified directory, in the same way as the
294 .RB Both\ [stylesdir] \ and\ [stylesmenu]
295 commands make it possible to install style files without editing your menu file.
297 .B [submenu] (label) {title for menu - optional}
298 This tells Openbox to create and parse a new menu.
299 This menu is inserted as a submenu into the parent menu.
300 These menus are parsed recursively, so there is no limit to the number of levels
301 or nested submenus you can have.
302 The title for the new menu is optional; if none is supplied,
303 the new menu's title is the same as the item label.
306 tag is required to end the submenu.
308 .B [reconfig] (label)
309 When selected, this item rereads the current style, menu files and rc file,
310 and applies any changes.
311 This is useful for creating a new style or theme, as you don't have to
312 constantly restart Openbox every time you save your style.
313 However, Openbox automagically rereads the menu whenever it changes.
315 .B [restart] (label) {shell command - optional}
316 This tells Openbox to restart.
317 If `shell command' is supplied, it shuts down and runs the command (which is
318 commonly the name of another window manager).
319 If the command is omitted, Openbox restarts itself.
322 Inserts a Openbox generated submenu item containing numerous configuration
323 options concerning window placement, focus style, window moving style, etc.
325 .B [workspaces] (label)
326 This tells Openbox to insert a link to the workspaces menu directly
328 This is handy for those users who can't access the
329 workspace menu directly (e.g. if you don't have a 3 button mouse).
331 Any line that starts with a `#' is considered a comment and ignored by Openbox.
332 Also, in the labels/commands/filenames fields,
333 you can escape any character like so:
335 [exec] (\\(my cool\\) \\{XTERM\\}) {xterm -T \\"cool XTERM\\"}
337 Using `\\\\' inserts a literal back-slash into the label/command/filename field.
339 Now let's put together some things.
340 Here is a short example of a menu file:
344 [begin] (Openbox @version@)
345 [exec] (rxvt) {rxvt -ls}
346 [exec] (Mozilla) {mozilla}
347 [exec] (The GIMP) {gimp}
348 [submenu] (Window Manager)
349 [exec] (Edit Menus) {nedit .openbox/Menu}
350 [submenu] (Style) {Which Style?}
351 [stylesdir] (~/.openbox/styles)
352 [stylesmenu] (Openbox Styles) {@pkgdatadir@/styles}
354 [config] (Config Options)
355 [reconfig] (Reconfigure)
363 Openbox enables you to use specialized files that contain
365 resources to specify colors, textures, and fonts and therefore
366 the overall look of your window borders, menus, and the toolbar.
368 The default installation of Openbox provides some of these style files.
369 Usually they are put in
370 .IR @pkgdatadir@/styles .
371 You can study or edit these files to grasp how the Openbox style mechanism
374 .BR [style] ", " [stylesdir] " and " [stylesmenu]
375 menu commands in your menu file to be able to select and change between styles
378 You can also create a directory in your home directory (usually named
379 .I ~/.openbox/styles)
380 and put your own style files there.
381 Of course, you may choose any name for this directory, but many downloadable
382 themes will rely on the name
384 (following the bb.themes.org naming scheme).
386 To understand how the style mechanism works, you should have a little knowledge
387 of how X resources work.
389 X resources consist of a key and a value.
390 The key is constructed of several smaller keys (sometimes referred to as
391 children), delimited by a period (`.').
392 Keys may also contain a star (`*') to serve as a wildcard, which means that one
393 line of typed text will match several keys.
394 This is useful for styles that are based on one or two colors.
396 Openbox allows you to configure its four main components: the toolbar, the
397 slit, the menus, and the window decorations.
399 The little window that shows the x-y position while dragging windows borrows
400 its style from the window's titlebar.
402 Here are some quick examples:
404 toolbar.clock.color: green
406 This sets the color resource of the toolbar clock to `green'. Another example:
408 menu*color: rgb:3/4/5
410 This sets the color resource of the menu
411 .I and all of its `children'
413 (For a description of color names, see
415 So this one also applies to
416 .IR menu.title.color " and " menu.frame.color .
419 *font: -b&h-lucida-medium-r-normal-*-*-140-*
421 you set the font resource for all keys to this font name all at once.
422 (For information about the fonts installed on your system, you can use a program like
423 .IR xfontsel "(1), " gtkfontsel ", or " xlsfonts "(1).)"
425 Now what makes Openbox just so spectacular is its ability to render textures
427 Texture descriptions are specified in a similar way to the colors shown above
429 .ta \w'toolbar.clock.colorTo:\ 'u
431 toolbar.clock: Raised Gradient Diagonal Bevel1
432 toolbar.clock.color: rgb:8/6/4
433 toolbar.clock.colorTo: rgb:4/3/2
435 Don't worry; we will explain right now!
436 A texture description consists of up to five fields, which are as follows:
438 .B Flat / Raised / Sunken
439 gives the component either a flat, raised, or sunken appearance.
442 tells Openbox to draw either a solid color or a texture with gradient.
444 .B Horizontal / Vertical / Diagonal / Crossdiagonal / Pipecross / Elliptic / Rectangle / Pyramid
445 Select one of these texture types. They only work when
450 tells Openbox to interlace the texture (darken every other line).
451 This option is most commonly used with gradiented textures, but, from Openbox
452 version 0.60.3 on, it also works in solid textures.
455 tells Openbox which type of bevel to use.
456 Bevel1 is the default bevel.
457 The shading is placed on the edge of the image.
458 Bevel2 is an alternative.
459 The shading is placed one pixel in from the edge of the image.
461 Instead of a texture description, the option
463 is also available, which makes the component appear as a part of its parent, i.e.
466 All gradient textures are composed of two color values: the
467 .IR color " and " colorTo " resources."
468 color represents the initial color, colorTo represents the final color of the
476 resource is used to specify the interlacing color.
478 Well, here is the complete component list; also, all components together with
479 which kind of value they can contain.
480 Comments are preceded with an exclamation sign (!), which is also used for
481 comments in Openbox style c.q. X resource files.
483 .ta \w'window.button.unfocus.picColor: \ 'u
486 .\" The comments also to be translated!
488 ! The toolbar itself.
491 toolbar.colorTo: Color
493 ! The buttons on the toolbar.
494 toolbar.button: Texture or \fIParentRelative\fR
495 toolbar.button.color: Color
496 toolbar.button.colorTo: Color
498 ! Color of the button arrows.
499 toolbar.button.picColor: Color
501 ! Buttons in pressed state.
502 toolbar.button.pressed: Texture \fI(e.g. Sunken)\fR or \fIParentRelative\fR
503 toolbar.button.pressed.color: Color
504 toolbar.button.pressed.colorTo: Color
506 ! Color of pressed button arrows.
507 toolbar.button.pressed.picColor: Color
509 ! The toolbar workspace label.
510 toolbar.label: Texture or \fIParentRelative\fR
511 toolbar.label.color: Color
512 toolbar.label.colorTo: Color
513 toolbar.label.textColor: Color
515 ! The toolbar window label.
516 toolbar.windowLabel: Texture or \fIParentRelative\fR
517 toolbar.windowLabel.color: Color
518 toolbar.windowLabel.colorTo: Color
519 toolbar.windowLabel.textColor: Color
522 toolbar.clock: Texture or \fIParentRelative\fR
523 toolbar.clock.color: Color
524 toolbar.clock.colorTo: Color
525 toolbar.clock.textColor: Color
527 ! How the toolbar's text should be justified.
528 toolbar.justify: \fIcenter\fR, \fIleft\fR, or \fIright\fR
530 .ta \w'toolbar.font:\ 'u
531 ! Font to be used for all toolbar components.
532 toolbar.font: Font \fI(e.g. -*-helvetica-medium-r-normal-*-*-100-*)\fR
534 .ta \w'window.button.unfocus.picColor: \ 'u
537 menu.title.color: Color
538 menu.title.colorTo: Color
539 menu.title.textColor: Color
540 menu.title.font: Font
541 menu.title.justify: \fIcenter\fR, \fIleft\fR, or \fIright\fR
545 menu.frame.color: Color
546 menu.frame.colorTo: Color
547 menu.frame.textColor: Color
548 menu.frame.disableColor: Color
549 menu.frame.font: Font
550 menu.frame.justify: \fIcenter\fR, \fIleft\fR, or \fIright\fR
552 ! Bullets for submenu items.
553 menu.bullet: \fIempty\fR, \fItriangle\fR, \fIsquare\fR, or \fIdiamond\fR
554 menu.bullet.position: \fIright\fR or \fIleft\fR
556 ! The highlighted menu item.
557 menu.hilite: Texture (e.g. \fIRaised\fR)
558 menu.hilite.color: Color
559 menu.hilite.colorTo: Color
560 menu.hilite.textColor: Color
563 window.title.focus: Texture
564 window.title.focus.color: Color
565 window.title.focus.colorTo: Color
567 ! An unfocused window.
568 window.title.unfocus: Texture
569 window.title.unfocus.color: Color
570 window.title.unfocus.colorTo: Color
573 window.label.focus: Texture or \fIParentRelative\fR
574 window.label.focus.color: Color
575 window.label.focus.colorTo: Color
576 window.label.focus.textColor: Color
578 window.label.unfocus: Texture or \fIParentRelative\fR
579 window.label.unfocus.color: Color
580 window.label.unfocus.colorTo: Color
581 window.label.unfocus.textColor: Color
584 window.handle.focus: Texture
585 window.handle.focus.color: Color
586 window.handle.focus.colorTo: Color
588 window.handle.unfocus: Texture
589 window.handle.unfocus.color: Color
590 window.handle.unfocus.colorTo: Color
593 window.grip.focus: Texture
594 window.grip.focus.color: Color
595 window.grip.focus.colorTo: Color
597 window.grip.unfocus: Texture
598 window.grip.unfocus.color: Color
599 window.grip.unfocus.colorTo: Color
602 window.button.focus: Texture or \fIParentRelative\fR
603 window.button.focus.color: Color
604 window.button.focus.colorTo: Color
605 window.button.focus.picColor: Color
607 window.button.unfocus: Texture or \fIParentRelative\fR
608 window.button.unfocus.color: Color
609 window.button.unfocus.colorTo: Color
610 window.button.unfocus.picColor: Color
612 window.button.pressed: Texture (e.g. \fISunken\fR)
613 window.button.pressed.color: Color
614 window.button.pressed.colorTo: Color
616 .ta \w'window.button.pressed.unfocus.colorTo:\ 'u
617 ! If either the focused, or unfocused pressed button isn't
618 ! defined, it will use the normal pressed: resource
619 window.button.pressed.focus: Texture (eg. \fISunken\fR)
620 window.button.pressed.focus.color: Color
621 window.button.pressed.focus.colorTo: Color
622 window.button.pressed.unfocus: Texture (eg. \fISunken\fR)
623 window.button.pressed.unfocus.color: Color
624 window.button.pressed.unfocus.colorTo: Color
626 .ta \w'window.button.unfocus.picColor:\ 'u
627 ! Frame around window.
628 window.frame.focusColor: Color
629 window.frame.unfocusColor: Color
631 ! Font and justification for window labels.
633 window.justify: \fIcenter\fR, \fIleft\fR, or \fIright\fR
635 ! Miscellaneous resources.
637 ! A border can be drawn around all components.
638 borderWidth: a number of pixels, e.g. \fI1\fR
641 bevelWidth: a number of pixels > 0
642 handleWidth: a number of pixels > 0
644 ! Width of the window frame (from version 0.61 on).
645 ! When not specified, frameWidth defaults to the value of bevelWidth.
646 frameWidth: a number of pixels >= 0
648 ! This command is executed whenever this style is selected.
649 ! Typically it sets the root window to a nice picture.
650 rootCommand: Shell command, e.g. \fIbsetroot -mod 4 4 -fg rgb: 5/6/6 -bg grey20\fR
652 ! Some of the bbtools read these old 0.51 resources.
657 Now, this seems a long list, but, remember, when you create your own style, you
658 can easily set lots of keys with a single command, e.g.
660 .ta \w'*unfocus.textColor:\ 'u
662 *colorTo: darkslategrey
663 *unfocus.color: darkslategrey
664 *unfocus.colorTo: black
666 *unfocus.textColor: lightgrey
669 This sets already nice defaults for many components.
671 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:
673 ! Close, maximize, sticky and iconify
674 ! buttons on a window.
675 window.button.close.mask: xbm file
676 window.button.max.mask: xbm file
677 window.button.stick.mask: xbm file
678 window.button.icon.mask: xbm file
680 ! The icon for submenus in a menu.
681 menu.arrow.mask: xbm file
683 ! The icon for a selected option or workspace
685 menu.selected.mask: xbm file
687 ! The left and right buttons in the toolbar
688 toolbar.button.left.mask: xbm file
689 toolbar.button.right.mask: xbm file
691 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.
693 The slit is a special Openbox window frame that can contain dockable
694 applications, e.g. the `bbtools' or WindowMaker's dockapps.
695 When applications are run in the slit, they have no window borders of their own;
696 instead, they are framed in the slit, and they are always visible in the current
698 You can click button 3 on the edge of the slit window to get a menu to
699 determine its position, whether its contained applications should be grouped
700 horizontally or vertically and whether it should hide itself when the
703 Most dockable applications use the
705 option to run in the slit.
706 For example, you could put in your
713 Of course, to use the slit, you must have slit support compiled in (this is
718 resource file is created and maintained by Openbox itself.
721 menu (from 0.60.x on), the last selected style file, your workspace names and
722 so on are saved automatically in this file.
724 For a complete description of all of the resource file's options, see the
726 .IT http://icculus.org/openbox/rc.php
736 files, and to resolve style file and directory names.
739 When no other display was given on the command line, Openbox will start on the
740 display specified by this variable.
741 .SH AUTHOR and CREDITS
742 All of the code was initially written and maintained as Blackbox by Brad Hughes
743 .nh \" hyphenation off
750 and then Sean 'Shaleh' Perry
755 and is now maintained as Openbox by Ben Jansens
759 with contributions and patches merged from
760 many individuals around the world.
762 The official Openbox website:
764 .B http://icculus.org/openbox
767 Many themes and other contributions:
769 .B http://themes.freshmeat.net/
772 This manpage was put together by Wilbert Berendsen
776 Numerous other languages will be available.
778 .IR epist (1), \ bsetbg(1), \ bsetroot (1), \ xftlsfonts (1), \ bbkeys (1)
projects / dana / openbox.git / blob