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