1Hackedbox(1) Hackedbox(1)
2
6 Hackedbox
7
9 Hackedbox -help | -version
10 Hackedbox [ -rc rcfile ] [ -display display ]
11
13 Hackedbox is a stripped down version of Blackbox - The X11 Window Man‐
14 ager (http://blackboxwm.sourceforge.net/ ). The toolbar and Slit have
15 been removed. The goal of Hackedbox is to be a small 'feature-set' win‐
16 dow manager, with no bloat. There are no plans to add any functional‐
17 ity, only bugfixes and speed enhancements whenever possible.
18 Hackedbox provides configurable window decorations,and a root menu to
20 launch applications. There is also a workspace menu to add or remove
21 workspaces.
22 Hackedbox features a special kind of icon handling: When you minimize a
24 window, no icon appears; instead, you can view all minimized applica‐
25 tions in the `Icons' submenu of the workspace menu. Your desktop will
26 never get cluttered with icons. As an alternative to icons, shaded win‐
27 dows are provided: A double click on the titlebar of a window will
28 shade it (i.e. the window will disappear; only the titlebar stays visi‐
29 ble). By using style files, you can determine at a great level how
30 your desktop looks.
31
33 Hackedbox supports the following command line options:
34 -help Display command line options and compiled-in features, then
36 exit.
37 -version
39 Display version info and exit.
40 -rc rcfile
42 Use another rcfile than the default ~/.hackedboxrc .
43 -display display
45 Start Hackedbox on the specified display. Programs started by
46 Hackedbox will have the DISPLAY environment variable set to this
47 value, too.
48
50 This program is usually started by the user's startup script, most
51 times called ~/.xinitrc . To run hackedbox, modify the script by
52 adding
53 exec hackedbox
54 as the last executed command of the script. When Hackedbox terminates,
55 the X session will terminate too.
56 When started, Hackedbox will try to find a default menu file in
58 ~/.hackedbox/menu . You can provide a system-wide menu for your users
59 here.
60 On exit or restart, Hackedbox will save user defaults in the file
62 ~/.hackedbox/rc in the user's home directory. Some resources in this
63 file can be edited by hand.
64
66 Hackedbox does no keyboard handling by itself; instead, it relies on an
67 external program epist(1) for this. So, in this section, we will dis‐
68 cuss all mouse commands.
69 Root window (background):
71 A right click (button 3) will pop up the root menu. With this, you can
72 launch your applications. You can also customize this menu for your
73 needs. See above for its location. A middle click (button 2) will pop
74 up the workspace menu. You can add or remove a workspace, view appli‐
75 cations running on all workspace, inspect your iconified applications,
76 and jump directly to any workspace or application.
77 Left clicking (button 1) on an application in the Workspaces menu will
79 bring you to that workspace and raise/focus that application; middle
80 clicking (button 2) will warp the application to the current workspace.
81 Window Titlebar and Borders:
83 A left click on any part of the window's border will raise it. Drag‐
84 ging then moves the window. Dragging the resize grips at the bottom
85 left and bottom right corners resizes the window. Middle clicking will
86 immediately lower the window. Right clicking on the border or titlebar
87 pops up the window menu, containing these commands:
88 Send To...
90 Send window to another workspace. When you select the workspace
91 with the middle button, Hackedbox will send you, along with the
92 application, to the selected workspace.
93 Shade Shade window (display titlebar only).
95 Iconify
97 Iconify window. The `icon' can be found in the `Icons' submenu
98 of the workspace menu. It will *NOT* appear on screen other‐
99 wise.
100 Maximize
102 (Un)Maximize window. When you click the middle button on this
103 item, the window will maximize only vertically.
104 Raise Raise window.
106 Lower Lower window.
108 Stick (Un)Stick window. A stuck window will always be displayed in
110 the current workspace.
111 Kill Client
113 Kill (-SIGKILL) owner of window. Only use this if the client
114 refuses to close.
115 Close Close the application cleanly.
117 When you double click on the titlebar of a window, it will `shade', so
119 that only the titlebar stays visible. Another double click will redis‐
120 play the window contents.
121 Window Buttons:
123 The button at the left upper corner of a window is the Minimize button.
124 Clicking with any button causes the window to be iconified. The right‐
125 most button (with the X) closes the application. The other button on
126 the right (if present) maximizes the window in three ways: Button 1
127 causes full screen maximization, button 2 maximizes the window only
128 vertically, and button 3 only horizontally.
129 Any menu:
131 Clicking button 3 in a menu will popdown the menu. Clicking button 1
132 on the titlebar of any (sub)menu and then dragging it somewhere else
133 will cause the menu to stay visible, and not disappear when you click
134 on a menu item.
135 Miscellaneous:
137 When you want to drag a window, but cannot see either the bottom handle
138 or its titlebar, you can press Alt + button 1 anywhere in the window
139 and then drag it around. You can also use Alt + button 1 to raise a
140 partially visible window. Finally, Alt + button 2 lowers a window, and
141 Alt + button 3 resizes the window.
142
144 A default menu file is installed in ~/.hackedbox/menu . Of course,
145 this system-wide menu can be customized for all users at once. But it
146 is also possible to create a personal menu. It is a convention to cre‐
147 ate a directory ~/.hackedbox/ in your home directory, and to create a
148 menu file, e.g. menu in this directory, or copy the system-wide menu
149 file to this location. Next, we have to tell Hackedbox to load our
150 menu file instead of the default. This is accomplished by adding (or
151 changing) a resource value in the ~/.hackedbox/rc file, e.g.:
152 session.menuFile: ~/.hackedbox/menu
153 For this change to take effect, Hackedbox has to be restarted. Be sure
154 that your menu is usable, then choose `Restart' from the default
155 Hackedbox root menu.
156 Menu syntax
158 The menu syntax is very simple and very effective. There are up to
159 three fields in a menu line. They are of the form:
160 [tag] (label or filename) {command or filename}
161 The supported tags are as follows:
162 [begin] (label for root menu)
164 This tells Hackedbox to start parsing the menu file. This tag
165 is required for Hackedbox to parse your menu file. If it cannot
166 find it, the system default menu is used instead.
167 [end] This tells Hackedbox that it is at the end of a menu. This can
169 either be a submenu or the main root menu. There must be at
170 least one of these tags in your menu to correspond to the
171 required [begin] tag.
172 [exec] (label for command) {shell command}
174 Inserts a command item into the menu. When you select the menu
175 item from the menu, Hackedbox runs `shell command.'
176 [exit] (label for exit)
178 Inserts an item that shuts down and exits Hackedbox. Any run‐
179 ning programs are not closed.
180 [include] (filename)
182 Parses the file specified by filename and includes it with the
183 current menu. The filename can be the full path to a
184 file, or it can begin with ~/ , which will be expanded into
185 your home directory (e.g.
186 [include] (~/hackedbox/stylesmenu)
187 will include /home/bhughes/hackedbox/stylesmenu in my menu).
188 [nop] (label - optional)
190 Insert a non-operational item into the current menu. This can
191 be used to help format the menu into blocks or sections if so
192 desired. [nop] does accept a label, but it is not required, and
193 a blank item will be used if none is supplied.
194 [style] (label) {filename}
196 This tells Hackedbox to insert an item that, when selected,
197 reads the style file named filename and applies the new tex‐
198 tures, colors, and fonts to the current running session.
199 [stylesdir] (directory name)
201 Reads all filenames (directories are ignored) from the specified
202 directory and
203 creates menu items in the current menu for every filename.
204 Hackedbox assumes
205 that each file is a valid style file. When selected by the
206 user, Hackedbox applies the selected style file to the current
207 session. The labels that are created in the menu are the file‐
208 names of the style files.
209 [stylesmenu] (label) {directory name}
211 Creates a submenu entry with label (that is also the title of
212 the new submenu), and inserts in that submenu all filenames in
213 the specified directory, in the same way as the [stylesdir] com‐
214 mand does.
215 Both [stylesdir] and [stylesmenu] commands make it possible to
217 install style files without editing your menu file.
218 [submenu] (label) {title for menu - optional}
220 This tells Hackedbox to create and parse a new menu. This menu
221 is inserted as a submenu into the parent menu. These menus are
222 parsed recursively, so there is no limit to the number of levels
223 or nested submenus you can have. The title for the new menu is
224 optional; if none is supplied, the new menu's title is the same
225 as the item label. An [end] tag is required to end the submenu.
226 [reconfig] (label)
228 When selected, this item rereads the current style and menu
229 files and applies any changes. This is useful for creating a
230 new style or theme, as you don't have to constantly restart
231 Hackedbox every time you save your style. However, Hackedbox
232 automagically rereads the menu whenever it changes.
233 [restart] (label) {shell command - optional}
235 This tells Hackedbox to restart. If `shell command' is sup‐
236 plied, it shuts down and runs the command (which is commonly the
237 name of another window manager). If the command is omitted,
238 Hackedbox restarts itself.
239 [config] (label)
241 Inserts a Hackedbox generated submenu item containing numerous
242 configuration options concerning window placement, focus style,
243 window moving style, etc.
244 [workspaces] (label)
246 This tells Hackedbox to insert a link to the workspaces menu
247 directly into your menu. This is handy for those users who
248 can't access the workspace menu directly (e.g. if you don't have
249 a 3 button mouse).
250 Any line that starts with a `#' is considered a comment and ignored by
252 Hackedbox. Also, in the labels/commands/filenames fields, you can
253 escape any character like so:
254 [exec] (\(my cool\) \{XTERM\}) {xterm -T \"cool XTERM\"}
255 Using `\\' inserts a literal back-slash into the label/command/filename
256 field.
257 Menu example
259 Now let's put together some things. Here is a short example of a menu
260 file:
261 # Hackedbox menu file
263 [begin] (Hackedbox @version@)
264 [exec] (rxvt) {rxvt -ls}
265 [exec] (Mozilla) {mozilla}
266 [exec] (The GIMP) {gimp}
267 [submenu] (Window Manager)
268 [exec] (Edit Menus) {nedit .hackedbox/Menu}
269 [submenu] (Style) {Which Style?}
270 [stylesdir] (~/.hackedbox/styles)
271 [stylesmenu] (Hackedbox Styles) {@pkgdatadir@/styles}
272 [end]
273 [config] (Config Options)
274 [reconfig] (Reconfigure)
275 [restart] (Restart)
276 [end]
277 [exit] (Log Out)
278 [end]
279 # end of menu file
280
282 Hackedbox enables you to use specialized files that contain X(1)
283 resources to specify colors, textures, and fonts and therefore the
284 overall look of your window and the borders, menus.
285 The default installation of Hackedbox provides some of these style
287 files. Usually they are put in @pkgdatadir@/styles . You can study or
288 edit these files to grasp how the Hackedbox style mechanism works. You
289 can use the [style], [stylesdir] and [stylesmenu] menu commands in your
290 menu file to be able to select and change between styles on the fly.
291 You can also create a directory in your home directory (usually named
293 ~/.hackedbox/styles) and put your own style files there. Of course,
294 you may choose any name for this directory, but many downloadable
295 themes will rely on the name styles (following the bb.themes.org naming
296 scheme).
297 To understand how the style mechanism works, you should have a little
299 knowledge of how X resources work.
300 X resources consist of a key and a value. The key is constructed of
302 several smaller keys (sometimes referred to as children), delimited by
303 a period (`.'). Keys may also contain a star (`*') to serve as a wild‐
304 card, which means that one line of typed text will match several keys.
305 This is useful for styles that are based on one or two colors.
306 Hackedbox allows you to configure its four main components: the menus,
308 and the window decorations.
309 The little window that shows the x-y position while dragging windows
311 borrows its style from the window's titlebar.
312 Here are some quick examples:
314 toolbar.clock.color: green
315 This sets the color resource of the toolbar clock to `green'. Another
316 example:
317 menu*color: rgb:3/4/5
318 This sets the color resource of the menu and all of its `children' to
319 `rgb:3/4/5'. (For a description of color names, see X(1).) So this
320 one also applies to menu.title.color and menu.frame.color . And with
321 *font: -b&h-lucida-medium-r-normal-*-*-140-*
322 you set the font resource for all keys to this font name all at once.
323 (For information about the fonts installed on your system, you can use
324 a program like xfontsel [4m(1), gtkfontsel , or xlsfonts [4m(1).)
325 Now what makes Hackedbox just so spectacular is its ability to render
327 textures on the fly. Texture descriptions are specified in a similar
328 way to the colors shown above e.g.:
329 toolbar.clock: Raised Gradient Diagonal Bevel1
330 toolbar.clock.color: rgb:8/6/4
331 toolbar.clock.colorTo: rgb:4/3/2
332 Don't worry; we will explain right now! A texture description consists
333 of up to five fields, which are as follows:
334 Flat / Raised / Sunken
336 gives the component either a flat, raised, or sunken appearance.
337 Gradient / Solid
339 tells Hackedbox to draw either a solid color or a texture with
340 gradient.
341 Horizontal / Vertical / Diagonal / Crossdiagonal / Pipecross / Elliptic
343 / Rectangle / Pyramid
344 Select one of these texture types. They only work when Gradient
345 is also specified!
346 Interlaced
348 tells Hackedbox to interlace the texture (darken every other
349 line). This option is most commonly used with gradiented tex‐
350 tures, but, from Hackedbox version 0.60.3 on, it also works in
351 solid textures.
352 Bevel1 / Bevel2
354 tells Hackedbox which type of bevel to use. Bevel1 is the
355 default bevel. The shading is placed on the edge of the image.
356 Bevel2 is an alternative. The shading is placed one pixel in
357 from the edge of the image.
358 Instead of a texture description, the option ParentRelative is also
360 available, which makes the component appear as a part of its parent,
361 i.e. totally transparent.
362 All gradient textures are composed of two color values: the color and
364 colorTo resources. color represents the initial color, colorTo repre‐
365 sents the final color of the gradient. When Interlaced is used in
366 Solid mode, the colorTo resource is used to specify the interlacing
367 color.
368 Well, here is the complete component list; also, all components
370 together with which kind of value they can contain. Comments are pre‐
371 ceded with an exclamation sign (!), which is also used for comments in
372 Hackedbox style c.q. X resource files.
373 ! The menu titlebar.
375 menu.title: Texture
376 menu.title.color: Color
377 menu.title.colorTo: Color
378 menu.title.textColor: Color
379 menu.title.font: Font
380 menu.title.justify: center, left, or right
381 ! The menu frame.
383 menu.frame: Texture
384 menu.frame.color: Color
385 menu.frame.colorTo: Color
386 menu.frame.textColor: Color
387 menu.frame.disableColor: Color
388 menu.frame.font: Font
389 menu.frame.justify: center, left, or right
390 ! Bullets for submenu items.
392 menu.bullet: empty, triangle, square, or diamond
393 menu.bullet.position: right or left
394 ! The highlighted menu item.
396 menu.hilite: Texture (e.g. Raised)
397 menu.hilite.color: Color
398 menu.hilite.colorTo: Color
399 menu.hilite.textColor: Color
400 ! A focused window.
402 window.title.focus: Texture
403 window.title.focus.color: Color
404 window.title.focus.colorTo: Color
405 ! An unfocused window.
407 window.title.unfocus: Texture
408 window.title.unfocus.color: Color
409 window.title.unfocus.colorTo: Color
410 ! Window label.
412 window.label.focus: Texture or ParentRelative
413 window.label.focus.color: Color
414 window.label.focus.colorTo: Color
415 window.label.focus.textColor: Color
416 window.label.unfocus: Texture or ParentRelative
418 window.label.unfocus.color: Color
419 window.label.unfocus.colorTo: Color
420 window.label.unfocus.textColor: Color
421 ! Handlebar.
423 window.handle.focus: Texture
424 window.handle.focus.color: Color
425 window.handle.focus.colorTo: Color
426 window.handle.unfocus: Texture
428 window.handle.unfocus.color: Color
429 window.handle.unfocus.colorTo: Color
430 ! Resize grips.
432 window.grip.focus: Texture
433 window.grip.focus.color: Color
434 window.grip.focus.colorTo: Color
435 window.grip.unfocus: Texture
437 window.grip.unfocus.color: Color
438 window.grip.unfocus.colorTo: Color
439 ! Window buttons.
441 window.button.focus: Texture or ParentRelative
442 window.button.focus.color: Color
443 window.button.focus.colorTo: Color
444 window.button.focus.picColor: Color
445 window.button.unfocus: Texture or ParentRelative
447 window.button.unfocus.color: Color
448 window.button.unfocus.colorTo: Color
449 window.button.unfocus.picColor: Color
450 window.button.pressed: Texture (e.g. Sunken)
452 window.button.pressed.color: Color
453 window.button.pressed.colorTo: Color
454 ! Frame around window.
456 window.frame.focusColor: Color
457 window.frame.unfocusColor: Color
458 ! Font and justification for window labels.
460 window.font: Font
461 window.justify: center, left, or right
462 ! Miscellaneous resources.
464 ! A border can be drawn around all components.
466 borderWidth: a number of pixels, e.g. 1
467 borderColor: Color
468 bevelWidth: a number of pixels > 0
470 handleWidth: a number of pixels > 0
471 ! Width of the window frame (from version 0.61 on).
473 ! When not specified, frameWidth defaults to the value of bevelWidth.
474 frameWidth: a number of pixels >= 0
475 ! This command is executed whenever this style is selected.
478 ! Typically it sets the root window to a nice picture.
479 rootCommand: Shell command, e.g. hsetroot -mod 4 4 -fg rgb:5/6/6 -bg grey20
480 ! Some of the bbtools read these old 0.51 resources.
482 menuFont: Font
483 titleFont: Font
484 Now, this seems a long list, but, remember, when you create your own
486 style, you can easily set lots of keys with a single command, e.g.
487 *color: slategrey
488 *colorTo: darkslategrey
489 *unfocus.color: darkslategrey
490 *unfocus.colorTo: black
491 *textColor: white
492 *unfocus.textColor: lightgrey
493 *font: lucidasans-10
494 This sets already nice defaults for many components.
495
497 Usually the ~/.hackedbox/rc resource file is created and maintained by
498 hackedbox itself. All options from the [config] menu (from 0.60.x on),
499 the last selected style file, your workspace names and so on are saved
500 automatically in this file. However, there are some resources in it
501 you might want to edit yourself:
502 session.menuFile:
504 This tells Hackedbox where to look for its menu file.
505 session.autoRaiseDelay:
507 This adjusts the delay (in ms) before focused windows will raise
508 when using the Auto Raise option. Default value is: R 250 .
509 session.doubleClickInterval:
511 This adjusts the delay (in ms) between mouse clicks for Hacked‐
512 box to consider a double click. Default value is: R 250 .
513 session.screen0.edgeSnapThreshold:
515 When moving a window across your screen, Hackedbox is able to
516 have it `snap' to the edges of the screen for easy placement.
517 This variable tells Hackedbox the distance (in pixels) at which
518 the window will jump to the edge. Default value is: R 0 .
519 session.cacheMax:
521 This tells Hackedbox how much memory (in Kb) it may use to store
522 cached pixmaps on the X server. If your machine runs short of
523 memory, you may lower this value. Default value is: R 200 .
524 session.cacheLife:
526 This tells Hackedbox how long (in minutes) unused pixmaps may
527 stay in the X server's memory. Default value is: R 5 .
528 session.colorsPerChannel:
530 This tells Hackedbox how many colors to take from the X server
531 on pseudocolor displays. A channel would be red, green, or
532 blue. Hackedbox will allocate this variable ^ 3 colors and make
533 them always available. This value must be between 2 and 6.
534 When you run Hackedbox on an 8-bit display, you must set this
535 resource to 4. Default value is: R 4.
536 When running Hackedbox in a multiple desktop environment, the screen0
538 key can also be screen1, 2 etc. for any appropriate desktop.
539
541 HOME Hackedbox uses $HOME to find its .hackedbox/rc file, and to
542 resolve style file and directory names.
543 DISPLAY
545 When no other display was given on the command line, Hackedbox
546 will start on the display specified by this variable.
547
549 All of the code is now maintained by Larry Owen (larry@scrudgeware.org)
550 The official Hackedbox website:
552 http://scrudgeware.org/projects/Hackedbox
553
555 epist(1)
556Larry Owen 0.8.5 Hackedbox(1)