Blackbox Documentation/Blackbox Windows
This section documents the way windows look and act under Blackbox. For those who don't know, applications under X only render the inside of the windows ie. the inner rectangle; the window manager's job (in our case, Blackbox) is to add window decorations (described below under "window appearance") to it, as well as react to certain mouse and keyboard actions (described below under window behavior).
- This page does not talk about using Blackbox under the Windows operating system. If that's what you wanted then see RelatedProjects.
- 1 Window appearance
- 2 Common window behavior
- 2.1 Raising and lowering windows
- 2.2 Moving a window
- 2.3 Resizing a window
- 2.4 Send to workspace
- 2.5 Shading a window
- 2.6 Minimizing a window
- 2.7 Iconifying a window
- 2.8 Maximizing a window
- 2.9 Closing a window
- 2.2 Moving a window
- 3 Focus models
- 4 Special window features
- 2 Common window behavior
Blackbox decorates windows with:
- a titlebar above the window
- a handle below the window, with resize grips
- two bars framing the left and right side of the window
- a window menu
The titlebar is the most prominent of the window decorations. It contains buttons for the most common window actions, a label to display the window title (aka caption), and access to the window menu. The titlebar is laid out in the following order, from left to right:
- iconify, label, maximize, close
The iconify button looks like an arrow with a horizontal bar under it; the maximize button looks like a box; the close button is an X. The label takes up most of the space. However, the window title may too long to display in its entirety, in which case Blackbox will ellide the text (replace the middle part or even the entire title with three dots).
The handle at the bottom of the window contains 2 size grips, one on each side. The centre part (the actual handle) is usually the biggest and can be used to drag and drop the entire window around. The grips are smaller; grabbing and dragging them will resize the window down-and-left or down-and-right, respectivelly.
The handle and the grips can be styled separately and usually style makers will take care to allow you to tell them apart easily.
The left and right sides of the window are bordered by two frames. The frames are basically two bars rendered in a solid color. Their thickness can be controlled from the style. They are useful for visually separating the window contents from the desktop background or from other windows.
Clicking with the secondary (right) mouse button on either frame will open the root Blackbox menu. (Not the window menu!) This is a very useful feature, because very often with a fully maximized window you have no way of reaching an empty piece of desktop to activate the root menu.
The window menu contains the following actions:
- send to workspace
- occupy all workspaces
- always on top
- always on bottom
- kill client
Window behavior is best described in terms of various actions that the user can perform. The current set of actions available for windows in Blackbox is:
- changing stacking order
- send to workspace
- change stacking layer (raising and lowering)
- switch to fullscreen
- remove decorations
Changing the stacking order of windows is easy. To raise a window above all other windows, press the left mouse button on the titlebar. If the ClickToFocus focus model is used, or the ClickRaise option is enabled, clicking anywhere inside the window will also raise the window. Alternatively, you can press the left mouse button anywhere inside the window while holding the Alt key down to raise a window, regardless of which focus model is used. To lower a window below all other windows, click the third (middle) mouse button on the titlebar. Alternatively, you can press the middle mouse button anywhere inside the window while holding the Alt key down to lower a window.
Note that some windows may ignore raise/lower actions, if they are already set always on top or always on bottom.
You can move windows around on the screen in several different ways using the mouse. To start the move operation, do one of the following:
- Press the left mouse button on the titlebar.
- Press the left mouse button on the handle.
- Press the left mouse button anywhere in the window while holding the Alt key down.
- Note: these actions will also raise the window (see above).
Next, move the mouse to the desired location and release the left mouse button.
You can resize windows on the screen in several different ways using the mouse. The start the resize operation, do one of the following:
- Press the left mouse button on one of the size grips.
- Press the right mouse button anywhere in the window while holding the Alt key down.
- Note: these actions will also raise the window (see above).
The resize direction is determined by the location of the mouse when the resize operation started:
- NorthWest - The mouse is in the top-left corner of the window. Resizing will move the top-left corner of the window.
- NorthEast - The mouse is in the top-right corner of the window. Resizing will move the top-right corner of the window.
- SouthEast - The mouse is in the bottom-right corner of the window. Resizing will move the bottom-right corner of the window.
- SouthWest - The mouse is in the bottom-left corner of the window. Resizing will move the bottom-left corner of the window.
Next, give the window the desired size by moving the mouse and release the mouse button.
Some applications may choose to make certain windows a fixed size. Such windows can be recognized by the lack of resize grips; they only have a handle at the bottom. These windows cannot be resized.
You can relocate a window on another workspace. To do this you open the window menu and choose a workspace from the appropriate submenu. Left-clicking on the workspace name will send the window there. Middle-clicking on the workspace name will send the window there and also take you to that workspace.
For omnipresent windows this menu does not make sense, so it is disabled until they are not omnipresent anymore.
You can shade a window by double-clicking on the titlebar with the primary (left) mouse button. Shading actions are usually available for keyboard handlers as well. "Shading" means reducing the window to just the titlebar. It is a quick method of clearing up some screen space without having to iconify the window or send it to another workspace. Repeat the double-click on the title-bar to unshade the window.
You can also toggle shading via the window menu.
- FIXME: How does a shaded window deal with struts?
A shaded window will continue to function just like a normal window does. All the usual window actions, except for resize, still apply when the window is shaded. The application contained in the window will keep doing its job; it isn't "frozen" or anything, it's just hidden. However, for some applications this may have some benefits. TVTime, for instance, detects when the main display is being obscured and stops updating it, thus saving CPU.
If you are more used to others desktops, it must be mentioned that there is no minimization under X Window. There is iconifying, instead.
The two are not the same thing, but you can emulate minimization with the aid of 3rd party addon panels or taskbars. In fact, most of the popular desktop environments for X Window (such as Gnome or KDE) employ this trick to let users believe they use minimization. You can do the same for Blackbox, through the said 3rd-party addons.
The difference between the two is rather subtle. The core of the difference comes from the fact that X Window has built-in workspace support, while other window engines, such as Microsoft Windows, do not. Both of them make the window dissapear. However, when you have several workspaces to work with, there are additional things to consider.
You are strongly adviced to read the iconify section to find out more about how iconifying works.
You can iconify a window by clicking on the iconify button, found on the titlebar. The default location of the button is at the left end of the titlebar. The default image on the button looks like an arrow with a horizontal line under it. (This is worth mentioning because later versions of Blackbox may add the ability to change the button position or even the image on it.)
Some windows will not offer an iconify button. The application maker is able to set certain flags on a window, and has requested that the window not be iconified. You may use 3rd-party tools to force the window to iconify, but standards compliant applications such as Blackbox and keyboard handlers will not honour iconification for such windows.
In order to retrieve an iconified window, Blackbox offers the workspace menu.
There are other tools out there which will implement the equivalent of a taskbar. Such tools will show both iconified and regular (both raised and lowered) windows in the taskbar.
You have to be careful though. A taskbar may seem more familiar, but it's easy to mistake lowered windows for iconified windows, both in how they look and in how you handle them. Those tools usually have an additional way of marking iconified windows. fbpanel, for instance, adds square brackets around the iconified window title, whereas RoX actually transforms the iconified windows into icons on the desktop.
- An interesting side-effect of a taskbar tool is that iconifying a window will get you two benefits: first, it puts it out of the way; second, iconified windows are iconified for all workspaces, so even when you change workspace they still show on the taskbar, thus effectively implementing a kind of "sticky" effect.
You can maximize a window by clicking on the maximize button on the window titlebar (the one that looks like a square). When a window is maximized the picture on the button will change to resemble two overlapping squares, indicating that pressing it again will return the window to it's previous size and position.
Window maximization honours struts.
- Note: Some applications are unable to cover the entire screen even when the available space is free of struts. Terminal applications (such as xterm), for instance, have to always provide an exact number of character columns and lines; they may be unable to accomodate such an exact number either vertically or horizontally, and may therefore come up short in either direction.
There are three kinds of maximization available. In all three cases, the maximize button picture will change as described above.
- Full maximization: obtained via primary (left) click on the maximize button. Key handler tools also offer it, and call it simply maximization.
- Horizontal maximization: obtained via secondary (right) click on the maximize button. Key handler tools also offer it, and refer to it as horizontal maximization.
- Vertical maximization: obtained via third (middle) click on the maximize button. Key handler tools also offer it, and refer to it as vertical maximization.
You can also toggle maximization via the window menu. Unlike the maximize button, however, the menu item does full maximization no matter what button you use to click on it.
Some application windows will not have a maximize button. The application maker may have decided that the window is not to be resized in any way, which forbids Blackbox from offering the possibility of maximization as well.
You can close a window by clicking on the close button on the window titlebar or by clicking on the Close item in the window menu.
Please note that "closing" a window simply means that Blackbox will signal the application enclosed in that window that its termination was requested. Usually application respect this signal. What they actually do may differ from window to window; clicking "close" on the main application window will probably close it, whereas doing it on a preferences window will simply close the preferences.
Blackbox offers an alternative menu item called Kill Client. This will attempt to forcefully close the enclosed application. It's generally not a good idea to use this. Applications expect to be told to quit nicely, so they can do some last minute cleanups before they die. But sometimes an application will freeze and this remains the only simple method to remove the window and terminate the application.
- Note: In order to kill a rebel window, one can also open up a terminal and kill the offending application using the kill or killall commands. You can attempt to identify the application in the window using tools such as top, xrestop, xprop or xwininfo.
Some windows will not have a close button, and the corresponding window menu item will be inactive. For some reason, the application maker has set a flag telling Blackbox not to offer the possibility of termination. It's awkward, but it happens. The bitmap X application is an example of such an application and you have to exit it by pressing the Q or Control+C keys or by the File/Quit menu entry. Usually such applications will provide a means of termination in their interface. Of course, you can always use Kill Client.
Blackbox implements two alternative focus models, which can be toggled from the configuration menu or from the main configuration file. There are also various focus-related options which are available in both those places.
Under both focus models, some rules apply the same. For instance, some dialog windows (the modal ones) will forbid the main application window to regain focus for as long as they are open.
This focus model is perhaps most familiar to modern day computer users and is used by other popular desktop environments such as the Mac or Windows.
Under this model, the window which is "on top" at some point will have focus (save for always-on-top interference). You grant focus to another window by clicking on it with the mouse or by explicitly switching to it via keyboard. Mouse movements have no effect on window focus.
This focus model ties window focus to mouse movements: simply moving the mouse over a window will grant it focus. There are options determining whether the window will automatically raise too, or whether clicking on the window contents will raise it (clicking on a window's decorations always raises it).
The sloppy model allows for some very interesting usage patterns. For instance, you can focus and type in a window without having to bring it to front for this.
Struts is a part of the standard which allows windows to reserve the space they occupy so that no other windows will overlap them.
Various applications spend their lives attached to the screen edges. Examples: panels, taskbars, the Blackbox slit and toolbar. They will announce via struts that the desktop space usable by normal windows should shrink so that those windows do not overlap with the special edge apps.
Blackbox honours struts. Regular windows, for instance, will maximize only as far as the currently usable desktop space allows, and will resize automatically and on-the-fly when the struts protected area changes (when a side panel appears or dissapears, for example).
This doesn't mean that usable space is actively enforced ie. that you cannot drag a window over a panel. No, struts is simply a recommendations. Blackbox uses it when deciding where to (not) place new windows, and when calculating the size and position for maximized windows.
Decorations means all the extra things that Blackbox may add to a window: titlebar and buttons, frames, grip and handles. These can be toggled off, leaving only the actual contents of the window showing, or back on again.
Blackbox doesn't offer a method of doing this by hand but it supports it, and various key handling applications such as bbkeys implement it. You can use such applications to assign a keyboard shortcut for toggling the decorations for the currently active window.
This is useful, for instance, if you want to have a small non-decorated TV viewer sitting in the corner of your desktop. Or you can use it to turn decorations off for applications such as VMWare, Win4Lin or the VNC Viewer.
Applications which have a use for fullscreen mode will provide the means to switch a window to and back from this mode. Most common examples are multimedia applications, such as TV viewers or movie players.
Blackbox itself doesn't provide a window menu option to enable fullscreen mode (mainly because it wouldn't be able to provide one to turn it off, because the window bar would be gone). But if you want to toggle it manually, there are some addons which can do the trick.
Now, what the EWMH standard calls fullscreen mode makes for a rather particular kind of window. It doesn't simply mean "remove decorations and make the window as big as possible". It has two special meanings, from two separate points of view.
- From the application point-of-view, the window will lose most of the interface elements (which, exactly, depends on that application). Remember, this is intended mainly to allow for undisturbed access to the window contents, with as little interference as possible. This usually means you will only see the TV show, the images you were browsing, or the movie that is playing. There are shortcuts or mouse actions that will exit the fullscreen mode; F, ESC or a mouse click are good bets. However, some poorly designed applications may lack an intuitive way of switching off this mode, so you'd be well advised to make a note of how you toggle it on and off before you enter it.
- From the window manager point-of-view, a window in fullscreen mode is granted some special attributes which override the usual window behaviour:
- It covers the entire screen, regardless of struts.
- It covers everything else, even always-on-top windows. This includes panels, the toolbar or the slit, even if they have the always-on-top preferences activated.
- If at any time another window receives focus (regardless of how this happened), the fullscreen window will receive the always-on-bottom flag and will keep it until focused again, at which point it will resume fullscreen behaviour.
- Fullscreen mode is restricted to the workspace the window is on. The other workspaces are not affected.
- FIXME: what comes out of the combination fullscreen+omnipresent?
- FIXME: what happens if I turn decorations on for a fullscreen window?
- Note: For some applications, their so called "fullscreen mode" is not actually real fullscreen as specified by the standard. A popular such example is Firefox, which will toggle decorations, remove most interface elements and maximize the window disregarding struts, but will fail to set the EWMH flag which would grant it the special fullscreen mode attributes. It's understandable, since you still need various Firefox dialog windows to show, and you definitely don't want the side effects that the real mode would produce.
You can set a window in sticky mode via the window menu, by checking the Occupy all workspaces item. This will make the window actually exist on all workspaces simultaneously, with the same position and size.
When the sticky mode is turned off, the window will revert to being present only on one workspace, the one you were viewing when the mode was switched off.
This is useful for keeping an application around at all times. Coupled with always-on-top and decoration toggling, it can provide a very useful feature. It can allowing you for instance to keep a TV viewer or a newsreader in the corner of your screen at all times, but keep interference with other windows to a minimum.
You can toggle the always-on-top and always-on-bottom modes from the window menu. They cannot be in effect at the same time, so switching one of them on will switch the other off.
A window in the always-on-top mode will stay above all other windows on the workspace. Similarly, in always-on-bottom mode it will stay below all other windows, regardless of focus.
- Note: Even in always-on-bottom mode, windows will still not go below the root window or below the desktop icons, if you have any.
If two windows are both in always-on-top or always-on-bottom mode, they are considered "equal" and which one is on top is determined by the usual rules related to focus model.
Windows in always-on-top mode will cover applications in struts, such as panels, toolbar or slit.
The snapping features activate when the related configuration directives are enabled, or set to numbers greater than zero. Please remember that the numbers must be integers. There are two such preferences; one sets the amount of pixels for snapping to other windows, one take care of snapping to screen, struts and center.
Snapping means that when a window's edge comes within a certain distance (measured in pixels) of another window's edge, or of the screen edge, or of a struts edge, the window will "jump" and stick perfectly against that other edge.
Starting with Blackbox 0.70.1 there's also center snapping. It activates at the same time edge snapping does and uses the same pixel setting. When activated, the center of all windows will attempt to snap against two lines (one vertical, one horizontal) crossing the screen at the center (like a crosshair). As a side effect, windows will snap against the screen center too.
The reverse of snapping is called resistance and is activated automatically for the same amount of pixels. This means that when attempting to drag a window away from the thing it snapped against, it will not move unless you pull for that amount of pixels.
Together, snapping and resistance allow you to align windows perfectly, without requiring lots of patience, good eyesight or ungodly perseverance. It is considered a good accesibility feature to have.
The value 10 (ten) seems to be a widely preferred setting for snapping distance. Use the value 20 (twenty) if you favor more aggressive snapping. Of course, you can adjust the value to your own liking.