Release candidate status:
The new xoblite bb5 documentation is still
very much a work in progress, i.e. not yet
finalized but will be updated continuously.
Welcome to xoblite.
xoblite™ is an advanced "extended shell" for Microsoft® Windows® 10/11, part of the Blackbox for Windows family.
Seeking to supercharge your day-to-day computer user interface and experience, among its many features are...
• A range of *box unique Design options, including state-of-the-art new 8-colour gradient options for Styles as well as a sophisticated style Designer Mode,
built-in support for Themes including provisions to allow for their portability, as well as built-in Wallpapers previewing and handling.
• A flexible user configurable Menu providing quick and easy access to key applications, configurations options, design options, and more.
• An advanced Toolbar with support for both horizontal and vertical orientation, a built-in scrollable Taskbar with active task previewing, etc.
• A classic bb4win-style Dock, a shared container window typically used to hold multiple smaller sized plugins.
• A helpful Console providing immediate feedback on executed actions, miscellaneous useful information and statistics, powerful logging for developers, etc.
• A clean Desktop with optional embedded time/date/weekday/indicator widgets and user configurable mouse click actions. Make it yours!
• Built-in support for user configurable Hotkeys, including support for advanced use cases such as @Script command script triggering.
• Support for multiple Workspaces, the *box equivalent of virtual desktops, including the possibility to have a separate wallpaper per workspace.
• A sophisticated development API for Plugins to further extend the capabilities beyond the core shell, showcased by a couple of 1st party bundled ones! :D
• A range of powerful Global options, including support for HiDPI 2x, adaptive screen relative positioning of UI elements including multi-monitor support,
support for per pixel alpha transparency features as well as optional rounded corners on most UI elements, built-in support for optional shell related sound effects, etc.
...and much, much more! → Download it now! =]
Oh, and by the way folks, let's get this one sorted out right away as well: It's xoblite, written using all lowercase letters, and it's
pronounced /ksɒblaɪt/ ("ksoblait"), not Ex-Oh-Bee-Light nor Zob-Lite. "bb" in the version obviously stands for "Blackbox". Got it? :)
Enjoy! :D
PS. (...and - while very much outdated of course - you can still find the old Blackbox for Windows 0.0.70 documentation here, and the legacy xoblite history page here.)
----------
xoblite™ bb5
© 2002-2024 Karl Henrik Henriksson [qwilk/@xoblite]
© 2001-2004 The Blackbox for Windows Development Team
Contains a heavily modified version of the BImage rendering engine used in the original "Blackbox" window manager for the X Window System
© 1997-2000 Bradley T Hughes, © 2001-2002 Sean 'Shaleh' Perry
Any trademarks referred to herein are property of their respective owners.
Always get the latest releases here, and nowhere else!
• Latest major release (full distribution): xoblite bb5 RC4 (0.20.12.13), released December 13th 2020. (MD5: a511c8d6a15cb64423ec3982c9b3dd79)
• Latest minor update (core binaries only): xoblite bb5 RC4+ (0.21.2.14), released February 14th 2021 (changes). (MD5: 1b739e242b78fd75d6668bb74cfe4278)
Quick start:
(1) Download the latest release(s) from the link(s) above.
(2) Unzip the xoblite .zip file(s) to a folder of your choice (c:\Blackbox is commonly used but not required).
(3) Hide your Explorer desktop icons (i.e. right click on the Explorer desktop -> View -> Deselect "Show desktop icons").
(4) If you so wish, hide your Explorer taskbar (nb. you can always quickly bring it up from hidden when needed by hitting the Win key),
and maybe also disable "Show taskbar on all displays" (on multi-monitor systems).
(5) Doubleclick on Blackbox.exe in the previously selected folder to start xoblite.
(note: if a Windows Defender warning pops up on first launch, but you trust this "unknown" author,
click "More info" and then "Run anyway" to continue. Note that xoblite does not require any administrator privileges.)
Done!
Next steps? A good place to start would be to right click on the Desktop to bring up xoblite's main Menu, and then explore all its options. Good luck! :D
----------
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Configuration files
xoblite.rc + menu.rc + hotkeys.rc
xoblite.rc is the primary configuration file (see example here) for xoblite bb4 and later, replacing the two configuration files blackbox.rc and extensions.rc used by previous versions.
Backwards compatibility is maintained; xoblite will automatically look for a blackbox.rc and extensions.rc if a xoblite.rc is not found, and will also parse both old *box and new xoblite .rc syntaxes automatically.
The xoblite.rc located in the same folder as the .exe takes on a special role, being the configuration file for the default Theme, as well as also containing Global (i.e. non-theme specific) settings.
The xoblite.rc of other themes only contains theme-specific settings (i.e. even if they were to include universal settings, these would be ignored).
Descriptions of the available xoblite.rc configuration parameters can be found listed in each section of this documentation, but most parameters are configurable via the Menu, i.e. requiring no manual editing.
Supporting secondary configuration files include:
menu.rc which specifies the contents of the main Menu (see example here).
hotkeys.rc which specifies the Hotkeys to be registered by xoblite at startup/restart (see example here).
Starting from xoblite bb5 RC5, all the .rc configuration files are now supplied in UTF-8 format, i.e. supporting Unicode for most user facing parameters (nb. previously they were parsed ANSI-only for legacy/historic reasons).
[documentation work in progress]
Broadcast messages ("bro@ms")
Since the early days of Blackbox for Windows, plugins have had the option to support broadcast messages (we refer to them as "bro@ms") to communicate with other plugins
and the *box shell itself (naturally, the *box shell can also communicate with these plugins). A bro@m command can be sent e.g. by using Hotkeys, or from the Menu, and is
recognized by the first letter of the command: @.
If you're an old dinosaur that tried out LiteStep way back in the past, you may at first find bro@ms similar to LiteStep !bangs. However, although they share some similarities,
the way they are handled is quite different. While !bangs are registered by a LiteStep module at startup and unregistered at exit, bro@ms are just that - broadcast messages.
What this means is that *any* plugin can listen to *any* message sent by *any* source (the *box shell or other plugins/tools). The upside of this is a much simplified handling and
the possibility for two plugins to listen to (ie. "share") the same bro@m. The downside is a very small extra overhead (= a few extra strcmp's for you coders out there),
but everyone agreed this was a small price to pay to get basic (yet powerful) message handling into Blackbox for Windows.
As a sidenote, it is also possible to send broadcast messages via the Windows command line using the -broam switch:
Example: Blackbox.exe -broam @xoblite Menu Show
[documentation work in progress]
Command scripting ("@Script")
xoblite provides built-in support for command scripting through a special kind of broadcast message known as @Script.
The script is enclosed in [] square brackets, and each command within - executed sequentially - is separated by a | pipe character, giving the following syntax:
Syntax: @Script [Command1|Command2|...|CommandN]
Example: @Script [@xoblite Global ToggleDesignerMode|@xoblite Random Wallpaper|Pause 3000|explorer.exe /e,c:\]
Like regular bro@m commands, @Script scripted commands can be sent e.g. by using Hotkeys, or from the Menu.
Commands within a script are not limited only to bro@ms however; they can also be any regular command, as well as Pause <milliseconds>, as in the example above.
[documentation work in progress]
Environment variables ("$Variables$")
Several types of environment variables can be used as part of paths or as shortcuts:
Blackbox related: $Blackbox$ $CurrentTheme$ $Desktop$ $ProgramFiles$ $UserProfile$ $UserAppData$ $StartMenu$ $CommonStartMenu$ ...
System related: %SystemDrive% %SystemRoot% %windir% ...
Applications related / URI shortcuts: mailto: ms-settings: ms-windows-store: ... (a good summary of these can be found e.g. here).
[documentation work in progress]
Description
xoblite supports a range of *box unique design options, including state-of-the-art new 8-colour gradient options for Styles as well as a sophisticated style Designer Mode,
built-in support for Themes including provisions to allow for their portability, as well as built-in Wallpapers previewing and handling. Finally, while adding Sounds to your theme is optional, it can often add to the user experience.
[documentation work in progress]
Configuration options (bro@ms → settings)
Description
All Blackbox shells use configuration files called "styles" to control the look of their different UI elements. These styles contain information about what textures, colours,
fonts etc should be used for each element. Furthermore, plugins can read these style settings through an API exposed by the shell, making it possible to get the same
look for all Blackbox user interface elements, whether they belong to the core shell or dynamically loaded plugins.
For instructions on how to use the xoblite Designer Mode functionality, which takes care of all the manual style editing and configuration work for you, see here.
This said, style resources consist of a key and a value. The key is constructed of several smaller keys (sometimes referred to as children), delimited by a period ('.') character.
Example:
toolbar.windowLabel.appearance: Flat Gradient SuperHorizontal
toolbar.windowLabel.color1: #040f8e
toolbar.windowLabel.color2: #12b4fe
toolbar.windowLabel.color3: #24d2d5
toolbar.windowLabel.color4: #589f33
toolbar.windowLabel.color5: #ec9b0d
toolbar.windowLabel.color6: #af3708
toolbar.windowLabel.color7: #500903
toolbar.windowLabel.color8: #160000
toolbar.windowLabel.font: Segoe UI/15/Bold
toolbar.windowLabel.alignment: Center
toolbar.windowLabel.textColor: #ffffff
toolbar.windowLabel.marginWidth: 1
toolbar.windowLabel.borderWidth: 0
For further information and details, see also the original bb4nix 0.70 style syntax documentation available here, however note that xoblite supports a superset of this syntax.
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite SetStyle <path> → xoblite.styleFile: <path>
Applies the specified style.
@xoblite Random Style → xoblite.styleFile: <path>
Applies a random style.
Description
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite SetTheme <theme> → xoblite.selected.theme: <theme>
Applies the specified theme.
Description
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite Random Wallpaper
Applies a random wallpaper (nb. a matching new rootCommand is not saved to the current style automatically; this must be done manually if/when needed).
Description
[documentation work in progress]
Configuration options (bro@ms → settings)
Description
The toolbar is the second of the classic *box UI elements; originally the only one to be always visible on an otherwise *very* minimalistic desktop... :)
The toolbar can be either horizontally (as in classic *box) or vertically (unique for xoblite) oriented, to support different use cases.
The toolbar has three main functions:
• Leftmost/topmost we have the so called toolbar label, showing the current workspace name/number. The current workspace can be changed using the leftmost pair of <> buttons.
• Center we can select between several display modes, including the classic toolbar windowLabel (which simply shows the currently active window, like in the early days of *box) as well as several Taskbar modes. The current display mode can be changed using the rightmost pair of <> buttons.
• Rightmost/bottommost we have the configurable (in xoblite.rc) format toolbar clock.
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite Toolbar <Toggle/Show/Hide> → xoblite.toolbar.hidden: <true/false>
This controls toolbar visibility, and is a per-theme setting.
@xoblite Toolbar Placement <...> → xoblite.toolbar.placement: <...>
This controls toolbar placement, and is a per-theme setting.
Pre-defined placements are TopLeft/CenterLeft/BottomLeft, TopCenter/BottomCenter and TopRight/CenterRight/BottomRight.
Manual positioning using screen relative coordinates is also supported, e.g. Manual x10 y10, Manual x-10 y-10, and so on. This can also be combined with screen centered x/y positioning by specifying "xC" or "yC" respectively, e.g. Manual xC y-20, and so on.
By using @xoblite Toolbar MoveToMouse, the toolbar can also be temporarily moved (i.e. the position will not be saved to xoblite.rc) to be centered under the mouse, which is really useful for e.g. mouse-button-to-hotkey-to-bro@m binding → super-flexible access to the toolbar/taskbar! :D
@xoblite Toolbar Orientation <Vertical/Horizontal> or @xoblite Toolbar ToggleOrientation → xoblite.toolbar.vertical: <true/false>
This controls toolbar orientation, and is a per-theme setting.
@xoblite Toolbar Transparency <0-255> → xoblite.toolbar.transparency.alpha: <0-255>
@xoblite Toolbar Transparency <Label/Clock/ActiveTask> <0-255> → xoblite.toolbar.label.transparency.alpha: <0-255> / xoblite.toolbar.clock.transparency.alpha: <0-255> / xoblite.taskbar.active.transparency.alpha: <0-255>
These control toolbar alpha transparency, and are per-theme settings.
The first setting controls the transparency of the toolbar itself, cf. regular window level alpha transparency.
The others make it possible to control the transparency of individual toolbar elements using more sophisticated per pixel alpha transparency.
@xoblite Toolbar ToggleRoundedCorners → xoblite.toolbar.rounded: <true/false>
This controls whether the toolbar should have rounded corners or not, and is a per-theme setting.
Note that the rounding of corners is by definition largely non-styling-aware, and hence it typically looks best with Flat/Solid style settings (YMMV though, as always ;) ).
@xoblite Toolbar ToggleAlwaysOnTop → xoblite.toolbar.onTop: <true/false>
This controls toolbar "always on top" state, and is a per-theme setting.
Deprecated, pending removal or subject to change:
@xoblite Toolbar ToggleSnapToEdges
Description
The taskbar is one of several Toolbar modes that can be selected from e.g. the Configuration/Toolbar menu.
[documentation work in progress]
When you click on a task button, one of several possible actions is executed as per the table below:
Mouse
button | Keyboard
modifier | Action |
|---|
Left
(#1) | None
Alt
Ctrl
Shift
| → Bring the window to the front (i.e. put it at the top of the z-order).
→ Move the window to the next workspace.
→ Toggle the window "stickiness" (visibility on all workspaces).
→ Toggle the window's process priority Default<->High
(an indicator will be shown around the task button for High priority tasks). |
Right
(#2) | None
Alt
Ctrl
Shift | → Minimize the window.
→ Minimize all windows (not just the one clicked).
→
→ |
Mid
(#3) | None
Alt
Ctrl
Shift | → Maximize/restore ("zoom") the window.
→
→
→ |
X1
(#4) | None
Alt
Ctrl
Shift | → Move the window to the previous workspace.
→
→
→ |
X2
(#5) | None
Alt
Ctrl
Shift | → Move the window to the next workspace.
→
→
→ |
Configuration options (bro@ms → xoblite.rc settings)
@xoblite Taskbar Mode <Bars/Icons/Bars+Icons> → xoblite.taskbar.mode: <Bars/Icons/Bars+Icons>
This controls the toolbar's taskbar display mode, and is a per-theme setting.
@xoblite Taskbar IconSaturation <0-255> → xoblite.taskbar.saturation: <0-255>
@xoblite Taskbar IconHue <0-255> → xoblite.taskbar.hue: <0-255>
These control the icon saturation+hue for the toolbar's taskbar display mode, and are per-theme settings.
@xoblite Taskbar ToggleActiveSatHue → xoblite.taskbar.active.SatHue: <true/false>
This controls whether icon saturation+hue as per above should be applied also to the currently active task, and is a per-theme setting.
@xoblite Taskbar ToggleInactiveBackground → xoblite.taskbar.inactive.background: <true/false>
This controls whether or not a background is drawn for inactive tasks on the the toolbar's taskbar, and is a per-theme setting.
@xoblite Taskbar ToggleCurrentOnly → xoblite.taskbar.currentOnly: <true/false>
This controls whether the toolbar's taskbar shall display tasks only on the current workspace, or all tasks on all workspaces, and is a per-theme setting.
@xoblite Taskbar ToggleFlashing → xoblite.taskbar.flashing: <true/false>
This controls whether the toolbar's taskbar allows task flashing or not, and is a per-theme setting.
@xoblite Taskbar ToggleTooltips → xoblite.taskbar.tooltips: <true/false>
This controls whether the toolbar's taskbar should display tooltips or not, and is a per-theme setting.
Control options (bro@ms only)
@xoblite Window Toggle Sticky
Toggles the "stickiness" of the currently active task's window, i.e. whether it should be visible on all workspaces ("sticky") or only on a single workspace ("non-sticky").
@xoblite Window Workspace <Next/Previous>
Moves the currently active task's window to the next/previous workspace.
@xoblite Window Workspace <1-N>
Moves the currently active task's window to the specified workspace (if it exists).
@xoblite Window Zoom
Zooms (i.e. maximizes/restores) the currently active task's window.
@xoblite Window Shade
Shades/unshades the currently active task's window.
@xoblite Window Lower
Lowers the currently active task's window in the z-order.
@xoblite Window Grow Width
Increases the width of the active task's window to the full width of the screen.
@xoblite Window Grow Height
Increases the height of the active task's window to the full height of the screen.
@xoblite Window Quit
Quits the currently active task's window.
Description
The dock (nb. formerly known as the "slit" for legacy reasons) is the third of the classic *box UI elements, and is pretty much a flexible "container window" for Plugins.
[documentation work in progress]
Configuration options (bro@ms → settings)
Description
[documentation work in progress]
Configuration options (bro@m → setting)
@xoblite ... <Toggle/Show/Hide>
Description
The new lighter-weight desktop introduced in xoblite bb5 is actually "only" an almost fully transparent window hovering at the bottom of the z-order,
above the Windows desktop (nb. hide your Explorer desktop icons first though!), while allowing for *box mouse clicks, file drops, etc anywhere as per usual.
It automatically responds to related screen / work area changes, updating itself dynamically on e.g. screen resolution changes or when the Explorer task's windowbar placement changes.
Being almost fully (read: non-detectably) transparent, this also allows the regular Windows wallpaper to show through, while making it possible to super-impose things like workspace indicators etc.
xoblite bb5 also integrates the functionality of key legacy wallpaper-related applications, bsetbg.exe and bsetroot.exe to improve overall security,
i.e. all style rootCommand's are now being parsed by the shell itself rather than being [possibly unknowingly] handed off to an [possibly arbitrary] external application.
Drag'n'drop of the following file types to the desktop is also supported:
• Drop a *box plugin .dll file to load it.
• Drop a .png, .jpg/jpeg or .bmp image file to set it as wallpaper (optionally holding down Ctrl to center, Alt to tile, Shift to span, or as default stretch the image).
• Drop a style file to apply it.
A list of the default actions upon mouse clicks on the desktop can be found below. It is also possible to override the default primary actions with user configurable ones,
in which case holding down the Alt key while clicking on the desktop will fall back to the default primary action. For more information, see configuration options below.
----------
Default primary desktop mouse click actions in case your mouse has at least 3 buttons :
• Left clicking anywhere on the desktop closes all non-pinned menus.
• Right clicking anywhere on the desktop brings up the Main menu (i.e. the one defined by menu.rc).
• Mid clicking anywhere on the desktop brings up the Styles menu.
• X1 clicking anywhere on the desktop brings up the Themes menu.
• X2 clicking anywhere on the desktop brings up the Workspaces menu.
• Mousewheel down anywhere on the desktop changes to the next Workspace. This change is also reflected by the workspace indicators near the top center of the desktop.
• Mousewheel up anywhere on the desktop changes to the previous Workspace. This change is also reflected by the workspace indicators near the top center of the desktop.
• Alt+X1 clicking anywhere on the desktop applies a random wallpaper.
• Alt+X2 clicking anywhere on the desktop applies a random style.
• Shift+X1/X2 clicking anywhere on the desktop provides direct access to the Configuration menu, normally (when using the default menu.rc) a submenu to the Main menu.
----------
Default secondary desktop Modifier+Mid mouse click actions in case your mouse has only 3 buttons :
• Alt+Mid clicking anywhere on the desktop brings up the Themes menu.
• Ctrl+Mid clicking anywhere on the desktop brings up the Workspaces menu.
• Shift+Mid clicking anywhere on the desktop provides direct access to the Configuration menu, normally (when using the default menu.rc) a submenu to the Main menu.
• Ctrl+Alt+Mid clicking anywhere on the desktop applies a random wallpaper.
• Shift+Alt+Mid clicking anywhere on the desktop applies a random style.
----------
Default secondary desktop Modifier+Right mouse click actions in case your mouse has only 2 buttons :
• Alt+Right clicking anywhere on the desktop brings up the Styles menu.
• Ctrl+Right clicking anywhere on the desktop brings up the Themes menu.
• Shift+Right clicking anywhere on the desktop brings up the Workspaces menu.
• Ctrl+Alt+Right clicking anywhere on the desktop applies a random wallpaper.
• Shift+Alt+Right clicking anywhere on the desktop applies a random style.
• Ctrl+Alt+Shift+Right clicking anywhere on the desktop provides direct access to the Configuration menu, normally (when using the default menu.rc) a submenu to the Main menu.
----------
Configuration options (bro@ms → settings)
@xoblite Desktop Clock <Regular/Text/Disabled> → xoblite.desktop.clock: <Regular/Text/Disabled>
This controls the visibility and style of the [still somewhat experimental] desktop clock, and is a per-theme setting.
xoblite.desktop.rclick.override: <action> / xoblite.desktop.mclick.override: <action> / xoblite.desktop.x1click.override: <action> / xoblite.desktop.x2click.override: <action>
User configurable overrides (e.g. command, bro@m, @Script...) for the default primary actions upon Right/Mid/X1/X2 mouse clicks on the desktop, all of which are per-theme settings.
Description
Syntax: *Hotkey <Modifier(s)> <Key> <Command>
Example: *Hotkey CtrlAltWin A @xoblite About
Modifier(s):
• Any combination of Ctrl Alt Shift Win, e.g. "CtrlAltWin"
• Note that many Win-only hotkeys are often already pre-registered/hard-coded by the system nowadays, and hence can not be used.
Key:
• Regular keys: A-Z, 0-9
• Locale specific keys: OEM1-OEM8, OEM102
• Arrow keys: Up, Down, Left, Right
• Function keys: F1-F12, F13-F24
• Numeric keypad: Num0-Num9, ...
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite Edit Hotkeys
Opens the hotkeys .rc file for editing.
Description
Workspaces are the *box equivalent of virtual desktops.
[documentation work in progress]
Configuration options (bro@ms → settings)
xoblite.workspaces: <1-N>
This controls how many workspaces there shall be in total, and is a global setting. The default is 4.
xoblite.workspaces.names: <name1,name2,name3...nameN>
This specifies individual names for each workspace, and is a global setting. If not defined, workspaces are automatically named "Workspace #N" instead.
@xoblite Workspaces Next
Switches to the next workspace.
@xoblite Workspaces Previous
Switches to the previous workspace.
@xoblite Workspaces ToggleFollowActive → xoblite.workspaces.followActive: <true/false>
This controls whether the choice of workspace should follow the active task or not, and is a global setting.
@xoblite Workspaces GatherWindows
Gather all task's windows to the current workspace.
Description
Plugins further extend the capabilities beyond the core shell in a modular fashion.
Downloads and documentation for some of my own plugins - including the ones bundled with xoblite - can be found here.
[documentation work in progress]
Third party authors can create plugin DLLs using a sophisticated plugin development API, typically using Microsoft Visual Studio Community Edition.
More information will be provided here later, but in the meanwhile experienced *box developers can download the xoblite includes (BBApi.h, Blackbox.lib) here.
Configuration options (bro@ms → settings)
@xoblite LoadPlugin <path>
Loads the plugin specified.
@xoblite UnloadPlugin <path>
Unloads the plugin specified.
@xoblite Plugins <Toggle/Show/Hide> → xoblite.plugins.hidden: <true/false>
This controls the visibility of (non-docked) plugins, and is a per-theme setting.
Description
Some functions and their associated settings are "global" ones, e.g. they apply to more than one UI element, are targeting the overall shell level, or apply regardless of the chosen theme. They are listed here.
[documentation work in progress]
Configuration options (bro@ms → settings)
@xoblite About
@xoblite CheckForUpdates
