| blob | 870dce684beba16206d2e6a0c486c2a8fb635bf3 |
1 .\"
2 .\" nroff source for blackbox.1 man page
3 .\"
4 .\" Copyright 2002 by R.B. "Brig" Young II <secretsaregood@yahoo.com>
5 .\" Written using gvim, available at http://www.vim.org/
6 .\"
7 .\" See the file COPYING in the source directory
8 .\" root for License specifics and restrictions
9 .\"
10 .\" Updated for Blackbox 0.65.0 release on 18 Sep 2002.
11 .\"
12 .\"
13 .\" Indented preformat macro.
14 .de EX
15 .ne 5
16 .if n .sp 1
17 .if t .sp .5
18 .nf
19 .in +.5i
20 ..
21 .de EE
22 .fi
23 .in -.5i
24 .if n .sp 1
25 .if t .sp .5
26 ..
27 .\"
28 .\" * * * * * Section * * * * *
29 .\"
30 .\" ***** SubSection *****
31 .\"
32 .TH blackbox 1 "September 18, 2002" "0.65.0"
33 .\"
34 .\" * * * * * NAME * * * * *
35 .\"
36 .SH NAME
37 blackbox \- a window manager for X11
38 .\"
39 .\" * * * * * SYNOPSIS * * * * *
40 .\"
41 .SH SYNOPSIS
42 .BR "blackbox" " \-help | \-version"
43 .br
44 .B blackbox
45 .RI "[ \-rc" " rcfile " "] [ \-display" " display " ]
46 .\"
47 .\" * * * * * DESCRIPTION * * * * *
48 .\"
49 .SH DESCRIPTION
51 .\" ----- overview -----
52 Blackbox is a window manager for the Open Group's
53 X Window System, Version 11 Release 6 and above.
54 Its design is meant to be visually minimalist and fast.
55 .PP
56 .\" ----- usage overview -----
57 Blackbox is similar to the NeXT interface and
58 Windowmaker. Applications are launched using a
59 menu which is accessed by right clicking on the
60 root window. Workspaces, a system of virtual
61 desktops are controlled via a menu which is accessed
62 by middle clicking on the root window and by using
63 the toolbar. Individual windows can be controlled by
64 buttons on the title bar and more options are available
65 by right clicking on the title bar.
66 .PP
67 .\" ----- design overview -----
68 Blackbox is able to generate beautiful window
69 decorations on the fly at high speed. Themes,
70 called styles in Blackbox terminology, are very
71 flexible but the use of pixmaps has been
72 purposefully avoided to eliminate dependencies
73 and excess memory usage.
74 .PP
75 .\" ----- bbtools overview -----
76 Blackbox itself does not directly handle key
77 bindings like most other window managers. This
78 task is handled by a separate utility called
79 bbkeys. Although Blackbox has a built-in
80 workspace (paging) system, bbpager, which provides
81 a graphical pager, is popular with many users.
82 bbkeys, bbpager and several other bbtools can be found
83 by going to
84 .EX 0
85 .B http://bbtools.thelinuxcommunity.org/
86 .EE
87 .\" ----- slit overview -----
88 The slit is an edge of the screen which can
89 hold specially designed programs called dock
90 apps (from Windowmaker). In addition, the
91 popular program gkrellm will also run in the slit.
92 There is a huge selection of dockapps available
93 and they run the gamut from must-have gadgets
94 to utterly useless (but cute and/or funny) eye candy.
95 .EX 0
96 .B http://www.bensinclair.com/dockapp/
97 .B http://dockapps.org/
98 .EE
99 .\"
100 .\" * * * * * OPTIONS * * * * *
101 .\"
102 .SH OPTIONS
103 Blackbox supports the following command line options:
104 .TP
105 .\" ----- help -----
106 .B \-help
107 Display command line options, compiled-in features, and exit.
108 .TP
109 .\" ----- version -----
110 .B \-version
111 Display version and exit.
112 .TP
113 .\" ----- rcfile -----
114 .BI \-rc \ rcfile
115 Use an alternate resource file.
116 .TP
117 .\" ----- display -----
118 .BI \-display \ display
119 Start Blackbox on the specified display, and set the
120 .B DISPLAY
121 environment variable to this value for programs
122 started by Blackbox.
123 .PP
124 .\"
125 .\" * * * * * STARTING AND EXITING BLACKBOX * * * * *
126 .\"
127 .SH STARTING AND EXITING BLACKBOX
128 The most common method for starting Blackbox
129 is to place the the command "blackbox" (no quotes)
130 at the end of your
131 .B ~/.xinitrc
132 or
133 .B ~/.xsession
134 file.
135 The advantage of putting Blackbox at the end of the file
136 is that the X Server will shutdown when you exit
137 Blackbox. Blackbox can also be started from
138 the command line of a terminal program like xterm in an
139 X session that does not already have a window manager running.
140 .PP
141 On startup, Blackbox will look for
142 .B ~/.blackboxrc
143 and use the resource
144 .B session.menuFile
145 to determine where to get the menu for the session.
146 If this file is not found Blackbox will use
147 .B @defaultmenu@
148 as the menu file. If that fails as well Blackbox
149 will use a default menu that contains commands
150 to start an xterm as well as restart and exit the window manager.
151 The other resources available in the
152 .B ~/.blackboxrc
153 file are discussed later in this manual under
154 the heading RESOURCE FILE.
156 On exit, Blackbox writes its current configuration to
157 .B ~/.blackboxrc.
158 .EX 0
159 .B NOTE:
160 If ~/.blackboxrc is modified during a Blackbox
161 session, Blackbox must be restarted with the
162 "restart" command on the main menu or the changes
163 will be lost on exit. Restart causes Blackbox to
164 re-read ~/.blackboxrc and apply the changes immediately.
165 .EE
166 Blackbox can be exited by selecting "exit" on
167 the main menu (discussed shortly), killing it
168 gently from a terminal or by the X Window System
169 shutdown hot key combo Ctrl+Alt+BackSpace.
170 .PP
171 .\"
172 .\" * * * * * USING BLACKBOX * * * * *
173 .\"
174 .SH USING BLACKBOX
175 .PP
176 A three button mouse has the following functions
177 when clicking on the root window:
178 .TP
179 .BR "Button Two" " (Middle Button)"
180 Open workspace menu
181 .TP
182 .BR "Button Three" " (Right Button)"
183 Open main menu
184 .TP
185 Note that Button One (Left Button) is not used.
186 .\"
187 .\" ***** MAIN MENU ******
188 .\"
189 .TP
190 .B Main Menu
191 The default installation assumes you have a number
192 of common X Window System programs in their typical
193 locations. The default menu is defined by a plain text
194 file named 'menu'. It is heavily commented and covers a
195 number of details of menu file syntax. This file can also
196 be edited graphically by using the extension program bbconf
197 which makes menu creation very easy. Menu file syntax is
198 discussed later in this manual.
199 .EX 0
200 .\" ----- main menu caveat -----
201 .B Caveat:
202 Menus can run arbitrary command lines, but
203 if you wish to use a complex command line
204 it is best to place it in a shell script.
205 Remember to put #!/bin/sh on the first
206 line and chmod 755 on the file to make it
207 executable.
208 .EE
209 .\"
210 .\" ***** WORKSPACE MENU *****
211 .\"
212 .TP
213 .B Workspace Menu
214 This menu gives the user control of the workspace
215 system. The user can create a new workspace,
216 remove the last workspace or go to an application
217 via either the icon menu or a workspace entry.
218 Workspaces are listed by name. Clicking on the
219 workspace name will take you to that workspace
220 with focus on the program under the mouse. If
221 there are programs already running in the
222 workspace, they will appear in a pop-out menu.
223 Clicking on the application name will jump to
224 the workspace and focus that application. If a
225 middle click is used the window will be brought to
226 the current workspace.
228 Blackbox uses an external program, bbpager,
229 to provide a traditional, graphical paging
230 interface to the workspace system. Many Blackbox
231 users run another extension program - bbkeys -
232 to provide keyboard shortcuts for workspace control.
233 .EX 0
234 .\" ----- workspace caveat -----
235 .B Caveat:
236 To name a workspace the user must right
237 click on the toolbar, select "Edit current
238 workspace name," type the workspace name,
239 And_Press_Enter to finish.
240 .EE
241 Workspaces can also be named in the .blackboxrc
242 file as described in RESOURCES.
243 .\"
244 .\" ***** THE SLIT *****
245 .\"
246 .TP
247 .B The Slit
248 The Slit provides a user positionable window for
249 running utility programs called "dockapps". To
250 learn more about dockapps refer to the web sites
251 mentioned in the Description. Dockapps
252 automatically run in the slit in most cases, but
253 may require a special command switch.
254 Often, -w is used for "withdrawn" into the slit.
256 gkrellm is a very useful and modern dockapp that
257 gives the user near real time information on
258 machine performance. Other dockapps include clocks,
259 notepads, pagers, key grabbers, fishbowls, fire
260 places and many, many others.
262 Only mouse button three is captured by the
263 Blackbox slit. This menu allows the user to change
264 the position of the slit, and sets the state of
265 Always on top, and Auto hide. These all do what
266 the user expects.
268 .EX 3
269 .\" ----- slit caveat -----
270 .B Caveat:
271 When starting Dockapps from an external script
272 a race condition can take place where the shell
273 rapidly forks all of the dockapps, which then
274 take varied and random times to draw themselves
275 for the first time. To get the dockapps to start
276 in a given order, follow each dockapp with
277 sleep 2; This ensures that each dockapp is placed
278 in the correct order by the slit.
279 .EE
280 .EX 8
281 .B i.e.
282 #!/bin/sh
283 speyes -w & sleep 2
284 gkrellm -w & sleep 2
285 .EE
286 .\"
287 .\" ***** THE TOOLBAR *****
288 .\"
289 .TP
290 .B The Toolbar
291 The toolbar provides an alternate method for
292 cycling through multiple workspaces and
293 applications. The left side of the toolbar is
294 the workspace control, the center is the
295 application control, and the right side is a
296 clock. The format of the clock can be controlled
297 as described under RESOURCES.
299 Mouse button 3 raises a menu that allows
300 configuration of the toolbar. It can be
301 positioned either at the top or the bottom
302 of the screen and can be set to auto hide
303 and/or to always be on top.
305 .EX
306 .\" ----- toolbar caveat -----
307 .B Caveat:
308 The toolbar is a permanent fixture. It
309 can only be removed by modifying the source and
310 rebuilding, which is beyond the scope of this
311 document. Setting the toolbar to auto hide is
312 the next best thing.
313 .EE
315 .\"
316 .\" ***** WINDOW DECORATIONS *****
317 .\"
318 .\" ----- overview -----
319 .TP
320 .B Window Decorations
321 Window decorations include handles at the bottom of
322 each window, a title bar, and three control buttons.
323 The handles at the bottom of the window are divided
324 into three sections. The two corner sections are
325 resizing handles The center section is a window
326 moving handle. The bottom center handle and the
327 title bar respond to a number of mouse clicks and
328 key + mouse click combinations. The three buttons
329 in the title bar, left to right, are iconify, maximize,
330 and close. The resize button has special behavior
331 detailed below.
332 .\"
333 .\" ----- mouse buttons -----
334 .\"
335 .TP
336 .BR "Button One" " (Left Button)"
337 Click and drag on titlebar to move or resize from bottom corners.
338 Click the iconify button to move the window to the icon list.
339 Click the maximize button to fully maximize the window.
340 Click the close button to close the window and application.
341 Double-Click the title bar to shade the window.
342 .TP
343 .BR "Alt + Button One" ""
344 Click anywhere on client window and drag to move the window.
345 .TP
346 .BR "Button Two" " (Middle Button)"
347 Click the titlebar to lower the window.
348 Click the maximize button to maximize the window vertically.
349 .TP
350 .BR "Button Three" " (Right Button)"
351 Click on title bar or bottom center handle pulls down a control menu.
352 Click the maximize button to maximize the window horizontally.
353 .TP
354 .BR "Alt + Button Three" ""
355 Click anywhere on client window and drag to resize the window.
357 .TP
358 .\"
359 .\" ----- control menu -----
360 .\"
361 .B The control menu contains:
362 .TP
363 .B Send To ...
364 .EX
365 .BR "Button One" " (Left Button)"
366 Click to send this window to another workspace.
367 .EE
368 .EX
369 .BR "Button Two" " (Middle Button)"
370 Click to send this window to another workspace, change
371 to that workspace and keep the application focused.
372 as well.
373 .TP
374 .B Shade
375 This is the same action as Double-Click with Button One.
376 .TP
377 .B Iconify
378 Hide the window. It can be accessed with the icon menu.
379 .TP
380 .B Maximize
381 Toggle window maximization.
382 .TP
383 .B Raise
384 Bring window to the front above the other windows and
385 focus it.
386 .TP
387 .B Lower
388 Drop the window below the other ones.
389 .TP
390 .B Stick
391 Stick this window to the glass on the inside of
392 the monitor so it does not hide when you change
393 workspaces.
394 .TP
395 .B Kill Client
396 This kills the client program with -SIGKILL (-9)
397 Only use this as a last resort.
398 .TP
399 .B Close
400 Send a close signal to the client application.
401 .\"
402 .\" * * * * * STYLES * * * * *
403 .\"
404 .\" ----- overview -----
405 .SH STYLES
406 Styles are a collection of colors, fonts,
407 and textures that control the appearance of
408 Blackbox. These characteristics are recorded
409 in style files. The default system style files
410 are located in
411 .I @pkgdatadir@/styles.
412 The menu system will identify the style by
413 its filename, and styles can be sorted into
414 different directories at the user's discretion.
416 .\" ----- third party styles -----
417 There are over 700 styles available for
418 Blackbox. The official distribution point for
419 Blackbox styles is
421 .EX
422 .B http://blackbox.themes.org/
423 .EE
425 .\"
426 .\" ----- installing styles -----
427 .\"
428 All themes should install by simply downloading them
429 to
430 .B ~/.blackbox/
431 then unzip it, and de-tar it.
433 On open Unixes this will be:
435 .B tar zxvf stylename.tar.gz
437 On commercial Unixes this will be something like:
439 .B gunzip stylename.tar.gz && tar xvf stylename.tar
441 Check your system manuals for specifics or check with
442 your network administrator.
444 An entry should appear in the styles menu immediately.
445 .EX
446 .B Security Warning
447 Style files can execute shell scripts and other
448 executables. It would is wise to check the
449 rootCommand in the style file and make sure that
450 it is benign.
451 .EE
452 .TP
453 .B Things that go wrong.
454 .TP
455 1. The theme is pre Blackbox 0.51.
456 Style file syntax changed with version 0.51
457 .TP
458 2. The style tarball was formatted incorrectly.
459 Some styles use the directories
460 .B ~/.blackbox/Backgrounds
461 and
462 .B ~/.blackbox/Styles
464 This can fixed by adding a
465 .B [stylemenu] (~/.blackbox/Styles)
466 to your menu file. To be a complete purist, hack
467 the style file with the correct paths and move
468 the files into the correct directories
469 .TP
470 3. The rootCommmand line is broken.
471 The rootCommand line in the style file will run an
472 arbitrary executable. It is important that this
473 executable be set to bsetbg to maintain portability
474 between systems with different graphics software. In
475 addition bsetbg can execute a shell script and do it
476 in a portable fashion as well.
477 .\"
478 .\" ----- style format ------
479 .\"
480 .TP
481 .B The documented method for creating styles is as follows:
482 .\" ----- background image -----
483 .TP
484 1. Create or acquire the background for the style if
485 it will not be using
486 .B bsetroot
487 to draw a patterned background for the root window.
489 .EX
490 .B NOTE:
491 Blackbox runs on a wide variety
492 of systems ranging from PCs with 640x480 256 color
493 displays to ultra high speed workstations with 25"
494 screens and extreme resolution. For best results a
495 style graphic should be at least 1024x768.
496 .EE
497 .\" ----- style file ------
498 .TP
499 2. Create a style file.
500 The best way to do this is to make a copy of a
501 similar style and then edit it.
503 The style file is a list of X resources and other
504 external variables. Manipulating these variables
505 allows users to completely change the appearance
506 of Blackbox. The user can also change the root
507 window image by using the wrapper program
508 .B bsetbg.
510 bsetbg knows how to use a number of programs to
511 set the root window image. This makes styles much
512 more portable since various platforms have different
513 graphics software. For more info see
514 .B bsetbg (1).
515 .\" ----- directory layout
516 .TP
517 3. Background images should be placed in
518 .B ~/.blackbox/backgrounds
519 The style file should be placed in
520 .B ~/.blackbox/styles
521 any other information about the style should
522 be placed in
523 .B ~/.blackbox/about/STYLE_NAME/.
524 This would include README files, licenses, etc.
526 Previous versions of Blackbox put backgrounds
527 and styles in different directories. The
528 directories listed above are the only officially
529 supported directories. However you may put them
530 whereever you like as long as you update your menu
531 file so it knows where to find your styles.
532 .\" ----- tarball -----
533 .TP
534 4. To create a consistent experience and to ensure
535 portability between all systems it is important
536 to use the following format to create your style
537 archive.
539 first create a new directory named
540 after your style
541 .B NEW_STYLE
543 In this directory create the
544 directories
545 .EX
546 .B backgrounds
547 .B styles
548 .B about/NEW_STYLE
549 .EE
550 Next put everything for the theme
551 in these locations. Finally type
553 tar cvzf NEW_STYLE.tar.gz *
555 If you are using commercial Unix you may
556 need to use gzip and tar separately.
558 Now when a user downloads a new style file
559 she knows that all she has to do is put
560 the tarball in her Blackbox directory,
561 unzip->un-tar it and then click on it in her
562 style menu.
563 .TP
564 .B
565 .\" ----- X resources -----
566 .SH Style File Syntax and Details
568 By far the easiest way to create a new style is to
569 use bbconf. bbconf allows complete control of every
570 facet of style files and gives immediate updates of
571 the current style as changes are made.
573 The style file format is not currently documented in
574 a man page. There is a readme document included with
575 the Blackbox source containing this information.
576 .\"
577 .\" * * * * * MENU FILE * * * * *
578 .\"
579 .\" ----- overview -----
580 .SH MENU FILE
581 The default menu file is installed in
582 .B @defaultmenu@.
583 This menu can be customized as a system
584 default menu or the user can create a
585 personal menu.
587 To create a personal menu copy the
588 default menu to a file in your home directory.
589 Then, open
590 .B ~/.blackboxrc
591 and add or modify the resource
592 .BI "session.menuFile:" " ~/.blackbox/menu"
594 Next, edit the new menu file. This can be done
595 during a Blackbox session and the menu will
596 automatically be updated when the code checks
597 for file changes.
599 The default menu included with Blackbox has
600 numerous comments describing the use of all
601 menu commands. Menu commands follow this general
602 form:
604 .BI "[command]" " (label|filename) {shell command|filename}"
605 .\"
606 .\" ----- menu commands -----
607 .\"
608 .TP
609 .B Blackbox menu commands:
610 .TP
611 .BI " # " "string..."
612 Hash (or pound or number sign) is used as the comment delimiter. It can
613 be used as a full line comment or as an end of
614 line comment after a valid command statement.
615 .TP
616 .BI "[begin]" " (string)"
617 This tag is used only once at the beginning of the
618 menu file. "string" is the name or description used
619 at the top of the menu.
620 .TP
621 .BI "[end] " ""
622 This tag is used at the end of the menu file
623 and at the end of a submenu block.
624 .TP
625 .BI "[exec]" " (label string) {command string}"
626 This is a very flexible tag that allows the user
627 to run an arbitrary shell command including shell
628 scripts. If a command is too large to type on the
629 command line by hand it is best to put it in a
630 shell script.
631 .TP
632 .BI "[nop]" " (label string)"
633 This tag is used to put a divider in the menu.
634 .I label string
635 is an optional description.
636 .TP
637 .BI "[submenu]" " (submenu name) {title string}"
638 This creates a sub-menu with the name
639 .I submenu name
640 and if given, the string
641 .I title string
642 will be the title of the pop up menu itself.
643 .TP
644 .BI "[include]" " (filename)"
645 This command inserts
646 .I filename
647 into the menu file at the point at which it is
648 called.
649 .I filename
650 should not contain a begin end pair. This feature
651 can be used to include the system menu or include a
652 piece of menu that is updated by a separate program.
653 .TP
654 .BI "[stylesdir]" " (description) (path)"
655 Causes Blackbox to search
656 .I path
657 for style files. Blackbox lists styles in the menu
658 by their file name as returned by the OS.
659 .TP
660 .BI "[stylesmenu]" " (description) {path}"
661 This command creates a submenu with the name
662 .B description
663 with the contents of
664 .B path.
665 By creating a submenu and then populating it
666 with stylesmenu entries the user can create an
667 organized library of styles.
668 .TP
669 .BI "[workspaces]" " (description)"
670 Inserts a link into the main menu to the workspace
671 menu. If used,
672 .I description
673 is an optional description.
674 .TP
675 .BI "[config]" " (label)"
676 This command causes Blackbox to insert a menu that
677 gives the user control over focus models, dithering
678 and other system preferences.
679 .TP
680 .BI "[reconfig]" " (label) {shell command}"
681 The reconfig command causes Blackbox to reread its
682 configuration files. This does not include
683 .B ~/.blackboxrc
684 which is only reread when Blackbox is restarted. If
685 .I shell command
686 is included Blackbox will run this command or
687 shell script before rereading the files. This can
688 be used to switch between multiple configurations
689 .TP
690 .BI "[restart]" " (label) {shell command}"
691 This command is actually an exit command that
692 defaults to restarting Blackbox. If provided
693 .B shell command
694 is run instead of Blackbox. This can be used
695 to change versions of Blackbox. Not that you would
696 ever want to do this but, it could also be used
697 to start a different window manager.
698 .TP
699 .BI "[exit]" " (label)"
700 Shuts down Blackbox. If Blackbox is the last command in your
701 .B ~/.xinitrc
702 file, this action will also shutdown X.
703 .EX
704 .B Here is a working example of a menu file:
705 .\" ----- menu example -----
706 [begin] (MenuName)
707 [exec] (xterm) {xterm -ls -bg black -fg green}
708 [submenu] (X utilities)
709 [exec] (xcalc) {xcalc}
710 [end]
711 [submenu] (styles)
712 [stylesmenu] (built-in styles) {@pkgdatadir@/styles}
713 [stylesmenu] (custom styles) {~/.blackbox/styles}
714 [end]
715 [workspaces] (workspace list)
716 [config] (configure)
717 [reconfig] (config play desktop) {play-config-blackbox}
718 [reconfig] (config work desktop) {work-config-blackbox}
719 [restart] (start Blackbox beta 7) {blackbox-beta7}
720 [restart] (start Blackbox cvs) {blackbox-cvs}
721 [restart] (restart)
722 [exit] (exit)
723 [end]
724 .EE
725 .\"
726 .\" * * * * * RESOURCE FILE * * * * *
727 .\"
728 .SH RESOURCE FILE
729 .BI "$HOME" "/.blackboxrc"
730 .\" ----- overview -----
731 These options are stored in the ~/.blackboxrc file.
732 They control various features of Blackbox and most
733 can be set from menus. Some of these can
734 only be set by editing .blackboxrc directly.
736 NOTE: Blackbox only reads this file during start
737 up. To make changes take effect during a Blackbox
738 session the user must choose "restart" on the main menu.
739 If you do not do so, your changes will be lost when
740 Blackbox exits.
742 Some resources are named with a <num> after screen. This
743 should be replaced with the number of the screen
744 that is being configured. The default is 0 (zero).
745 .\" ----- resource keys -----
746 .\"
747 .\" ***** MENU CONFIGURABLE FROM SLIT MENU *****
748 .\"
749 .TP 3
750 .IB "Menu Configurable" " (Slit Menu):"
751 Right click (button 3) on the slit border.
752 .TP 3
753 .BI "session.screen<num>.slit.placement" " SEE BELOW"
754 Determines the position of the slit.
755 Certain combinations of slit.placement with
756 slit.direction are not terribly useful, i.e. TopCenter
757 with Vertical direction puts the slit through the
758 middle of your screen. Certainly some will think that
759 is cool if only to be different...
760 .EX
761 .B Default is CenterLeft.
762 [ TopLeft | TopCenter | TopRight |
763 CenterLeft | | CenterRight |
764 BottomLeft | BottomCenter | BottomRight ]
765 .EE
766 .TP 3
767 .BI "session.screen<num>.slit.direction" " [Horizontal|Vertical]"
768 Determines the direction of the slit.
769 .EX
770 .B Default is Vertical.
771 .EE
772 .TP 3
773 .BI "session.screen<num>.slit.onTop" " [True|False]"
774 Determines whether the slit is always visible
775 over windows or if the focused window can hide
776 the slit.
777 .EX
778 .B Default is True.
779 .EE
780 .TP 3
781 .BI "session.screen<num>.slit.autoHide" " [True|False]"
782 Determines whether the slit hides when not in use.
783 The session.autoRaiseDelay time determines how long you
784 must hover to get the slit to raise and how long it
785 stays visible after mouse out.
786 .EX
787 .B Default is False.
788 .EE
789 .\"
790 .\" ***** MENU CONFIGURABLE FROM MAIN MENU *****
791 .\"
792 .TP 3
793 .IB "Menu Configurable" " (Main Menu):"
794 .TP 3
795 .BI "session.screen<num>.focusModel" " SEE BELOW"
796 Sloppy focus (mouse focus) is the conventional X Window
797 behavior and can be modified with AutoRaise or
798 Click-Raise.
800 AutoRaise causes the window to automatically raise after
801 session.autoRaiseDelay milliseconds.
803 ClickRaise causes the window to raise if you click
804 anywhere inside the client area of the window.
806 Sloppy focus alone requires a click on the titlebar,
807 border or lower grip to raise the window.
809 ClickToFocus requires a click on a Blackbox decoration
810 or in the client area to focus and raise the window.
811 ClickToFocus cannot be modified by AutoRaise or
812 ClickRaise.
813 .EX
814 .B Default is SloppyFocus
815 [SloppyFocus [[AutoRaise & ClickRaise] |
816 [AutoRaise | ClickRaise]] |
817 ClickToFocus]
818 .EE
819 .TP 3
820 .BI "session.screen<num>.windowPlacement" " SEE BELOW"
821 RowSmartPlacement tries to fit new windows in empty space
822 by making rows.
823 Direction depends on session.screen<num>.rowPlacementDirection
825 ColSmartPlacement tries to fit new windows in empty space
826 by making columns
827 Direction depends on session.screen<num>.colPlacementDirection
829 CascadePlacement places the new window down and to
830 the right of the most recently created window.
831 .EX
832 .B Default is RowSmartPlacement.
833 [RowSmartPlacement | ColSmartPlacement | CascadePlacement]
834 .EE
835 .TP 3
836 .BI "session.screen<num>.rowPlacementDirection" " [LeftToRight|RightToLeft]"
837 Determines placement direction for new windows.
838 .EX
839 .B Default is LeftToRight.
840 .EE
841 .TP 3
842 .BI "session.screen<num>.colPlacementDirection" " [TopToBottom|BottomToTop]"
843 Determines placement direction for new windows.
844 .EX
845 .B Default is TopToBottom.
846 .EE
847 .TP 3
848 .BI "session.imageDither" " [True|False]"
849 This setting is only used when running in low
850 color modes. Image Dithering helps to show an
851 image properly even if there are not enough
852 colors available in the system.
853 .EX
854 .B Default is False.
855 .EE
856 .TP 3
857 .BI "session.opaqueMove" " [True|False]"
858 Determines whether the window's contents are drawn as it is moved. When
859 False the behavior is to draw a box representing the window.
860 .EX
861 .B Default is False.
862 .EE
863 .TP 3
864 .BI "session.screen<num>.fullMaximization" " [True|False]"
865 Determines if the maximize button will cause an application
866 to maximize over the slit and toolbar.
867 .EX
868 .B Default is False.
869 .EE
870 .TP 3
871 .BI "session.screen<num>.focusNewWindows" " [True|False]"
872 Determines if newly created windows are given focus after
873 they initially draw themselves.
874 .EX
875 .B Default is False.
876 .EE
877 .TP
878 .BI "session.screen<num>.focusLastWindow" " [True|False]"
879 This is actually "when moving between workspaces, remember
880 which window has focus when leaving a workspace and return
881 the focus to that window when I return to that workspace."
882 .EX
883 .B Default is False.
884 .EE
885 .TP
886 .BI "session.screen<num>.disableBindingsWithScrollLock" " [True|False]"
887 When this resource is enabled, turning on scroll lock
888 keeps Blackbox from grabbing the Alt and Ctrl keys
889 that it normally uses for mouse controls. This feature
890 allows users of drawing and modeling programs which use
891 keystrokes to modify mouse actions to maintain their sanity.
892 *NOTE* this has _no_ affect on bbkeys. If you need bbkeys to also
893 behave this way it has a similar option in its config file. Refer
894 to the bbkeys manpage for details.
895 .EX
896 .B Default is False.
897 .EE
898 .\"
899 .\" ***** MENU CONFIGURABLE FROM WORKSPACE MENU *****
900 .\"
901 .TP
902 .IB "Menu Configurable" " (Workspace Menu):"
903 Middle click (button 2) on the root window (AKA Desktop)
904 to reach this menu
905 .TP 3
906 .BI "session.screen<num>.workspaces" " [integer]"
907 Workspaces may be created or deleted by middle clicking
908 on the desktop and choosing "New Workspace" or "Remove
909 Last". After creating a workspace, right click on the
910 toolbar to name it.
911 .EX
912 .B Default is 1
913 .EE
914 .\"
915 .\" ***** MENU CONFIGURABLE FROM TOOLBAR MENU *****
916 .\"
917 .TP
918 .IB "Menu Configurable" " (Toolbar Menu):"
919 .TP 3
920 .BI "session.screen<num>.workspaceNames" " [string[, string...]]"
921 Workspaces are named in the order specified in this
922 resource. Names should be delimited by commas. If there
923 are more workspaces than explicit names, un-named
924 workspaces will be named as "Workspace [number]".
925 .EX
926 .B Default is
927 Workspace 1.
928 .EE
929 .TP 3
930 .BI "session.screen<num>.toolbar.placement" " SEE BELOW"
931 Set toolbar screen position.
932 .EX
933 .B Default is BottomCenter
934 [ TopLeft | TopCenter | TopRight |
935 BottomLeft | BottomCenter | BottomRight ]
936 .EE
937 .TP 3
938 .BI "session.screen<num>.toolbar.onTop" " [True|False]"
939 Determines whether the toolbar is always visible
940 over windows or if the focused window can hide
941 the toolbar.
942 .EX
943 .B Default is True.
944 .EE
945 .TP 3
946 .BI "session.screen<num>.toolbar.autoHide" " [True|False]"
947 Determines whether the toolbar hides when not in use.
948 The session.autoRaiseDelay time determines how long you
949 must hover to get the toolbar to raise, and how long it
950 stays visible after mouse out.
951 .EX
952 .B Default is False.
953 .EE
954 .\"
955 .\" ***** CONFIGURABLE IN BLACKBOXRC ONLY *****
956 .\"
957 .TP 3
958 .IB "Configurable in" " ~/.Blackboxrc only:"
959 .TP 3
960 .BI "session.screen<num>.toolbar.widthPercent" " [1-100]"
961 Percentage of screen used by the toolbar.
962 A number from 1-100 that sets the width of the toolbar.
963 0 (zero) does not cause the toolbar to disappear, instead
964 the toolbar is set to the default. If you want to lose the
965 toolbar there are patches that can remove it.
966 .EX
967 .B Default is 66.
968 .EE
969 .TP 3
970 .BI "session.screen<num>.strftimeFormat" " [string]"
971 A C language date format string, any combination of
972 specifiers can be used. The default is %I:%M %p which
973 generates a 12 hour clock with minutes and an am/pm
974 indicator appropriate to the locale.
975 .EX
976 .IB "24 hours and minutes" " %H:%M"
977 .IB "12 hours and minute" " %I:%M %p"
978 .IB "month/day/year" " %m/%d/%y"
979 .IB "day/month/year" " %d/%m/%y"
980 .EE
981 .EX
982 .B Default is hours:minutes am/pm
983 See
984 .B strftime 3
985 for more details.
986 .EE
987 .TP 3
988 .BI "session.screen<num>.dateFormat" " [American|European]"
989 NOTE: Only used if the strftime() function is not
990 available on your system.
991 .EX
992 .B Default is American, (mon/day/year).
993 .EE
994 .TP 3
995 .BI "session.screen<num>.clockFormat" " [12/24]"
996 .B NOTE:
997 Only used if the strftime() function is not
998 available on your system.
999 .EX 0
1000 .B Default is 12-hour format.
1001 .EE
1002 .TP 3
1003 .BI "session.screen<num>.edgeSnapThreshold" " [integer]"
1004 When set to 0 this turns off edge snap. When set to one
1005 or greater edge snap will cause a window that is being
1006 moved to snap to the nearest screen edge, the slit, or
1007 or the toolbar. Windows will not snap to each other.
1008 The value represents a number in pixels which is the distance
1009 between the window and a screen edge which is required before
1010 the window is snapped to the screen edge. If you prefer this
1011 functionality values between 6 - 10 work nicely.
1012 .EX
1013 .B Default value is 0
1014 .EE
1015 .TP 3
1016 .BI "session.menuFile" " [filepath]"
1017 Full path to the current menu file.
1018 .EX
1019 .B Default is @defaultmenu@
1020 .EE
1021 .TP 3
1022 .BI "session.colorsPerChannel" " [2-6]"
1023 The number of colors taken from the X server for use on
1024 pseudo color displays. This value must be set to 4 for
1025 8 bit displays.
1026 .EX
1027 .B Default is 4.
1028 .EE
1029 .TP 3
1030 .BI "session.doubleClickInterval" " [integer]"
1031 This is the maximum time that Blackbox will wait after
1032 one click to catch a double click. This only applies to
1033 Blackbox actions, such as double click shading, not to the X
1034 server in general.
1035 .EX
1036 .B Default is 250 milliseconds.
1037 .EE
1038 .TP 3
1039 .BI "session.autoRaiseDelay" " [integer]"
1040 This is the time in milliseconds used for auto raise
1041 and auto hide behaviors. More than about 1000 ms is
1042 likely useless.
1043 .EX
1044 .B Default is 250 millisecond.
1045 .EE
1046 .TP 3
1047 .BI "session.cacheLife" " [integer]"
1048 Determines the maximum number of minutes that the X server
1049 will cache unused decorations.
1050 .EX
1051 .B Default is 5 minutes
1052 .EE
1053 .TP 3
1054 .BI "session.cacheMax" " [integer]"
1055 Determines how many kilobytes that Blackbox may take
1056 from the X server for storing decorations. Increasing
1057 this number may enhance your performance if you have
1058 plenty of memory and use lots of different windows.
1059 .EX
1060 .B Default is 200 Kilobytes
1061 .EE
1063 .\"
1064 .\" * * * * * ENVIRONMENT * * * * *
1065 .\"
1066 .SH ENVIRONMENT
1067 .TP
1068 .B HOME
1069 Blackbox uses $HOME to find its .blackboxrc
1070 rc file and its .blackbox directory for menus
1071 and style directories.
1072 .TP
1073 .B DISPLAY
1074 If a display is not specified on the command line,
1075 Blackbox will use the value of $DISPLAY.
1077 .\"
1078 .\" * * * * * FILES * * * * *
1079 .\"
1080 .SH FILES
1081 .TP
1082 .B blackbox
1083 Application binary
1084 .TP
1085 .B ~/.blackboxrc
1086 User's startup and resource file.
1087 .TP
1088 .B @defaultmenu@
1089 Default system wide menu
1091 .\"
1092 .\" * * * * * WEB SITES * * * * *
1093 .\"
1094 .SH WEB SITES
1095 .TP 5
1096 .\" ----- general info -----
1097 .B General info website:
1098 http://blackboxwm.sourceforge.net/
1099 .TP 5
1100 .\" ----- development info -----
1101 .B Development website:
1102 http://sourceforge.net/projects/blackboxwm/
1104 .\"
1105 .\" * * * * * BUGS * * * * *
1106 .\"
1107 .SH BUGS
1108 If you think you have found a bug, please help by going
1109 to the development website and select "Bugs" in the upper
1110 menu. Check the bug list to see if your problem has already
1111 been reported. If it has please read the summary and add any
1112 information that you believe would help. If your bug has not been
1113 submitted select "Submit New" and fill out the form.
1115 .\"
1116 .\" * * * * * AUTHORS AND HISTORY * * * * *
1117 .\"
1118 .SH AUTHORS AND HISTORY
1119 .\" ----- software authors -----
1120 .B Sean "Shaleh" Perry
1121 .I " <shaleh@debian.org>"
1122 is the current maintainer and is actively working
1123 together with Brad to keep Blackbox up-to-date and
1124 stable as a rock.
1126 .BI "Brad Hughes" " <bhughes@trolltech.com>"
1127 originally designed and coded Blackbox in 1997 with
1128 the intent of creating a memory efficient window
1129 manager with no dependencies on external libraries.
1130 Brad's original idea has become a popular alternative
1131 to other window managers.
1133 .BI "Jeff Raven" " <jraven@psu.edu>"
1134 then picked up the torch for the 0.61.x series after
1135 Brad took a full time job at TrollTech.
1137 .\" ----- man page author -----
1138 This manual page was written by:
1139 .B R.B. "Brig" Young
1140 .I " <secretsaregood@yahoo.com>"
1141 he is solely responsible for errors or omissions.
1142 Comments, corrections, and suggestions are welcomed.
1144 .\"
1145 .\" * * * * * SEE ALSO * * * * *
1146 .\"
1147 .SH SEE ALSO
1148 .EX
1149 bsetbg(1), bsetroot(1),
1150 bbkeys(1), bbconf(1)
1151 .EE