BlackBox for Windows [menu][styles][core bro@ms]
how to[basics]

basics


 
Quick Start:

  • Open the .zip
  • Extract its contents to a suitable directory (usually c:\Blackbox\ )
  • Download the BlackBox font pack from our website to give your desktop that *nix look
  • If you want to change your wallpaper with each style automatically, also download bsetroot from our website
  • If you want to expand your BlackBox experience with plugins, check the lists on our main page
  • For additional configuration, modify extensions.rc (see below)
  • If you want a certain application visible on every workspace, make sure its exe name (one per line) is in StickyWindows.ini (in the same directory as Blackbox.exe)
  • double-click on Blackbox.exe to start it
  • Enjoy!

(...however, we recommend the installation & configuration info as well!)


 


Mouse Commands:

Desktop / Menu

  • A right click (button 2) on the desktop will pop up the (configurable) main menu, which is used to launch applications and execute commands.
  • A mid click (button 3) on the desktop will pop up the Workspaces menu. Using this menu you can add or remove workspaces, view applications running in each available workspace, view minimized applications (ie. not on any workspace), as well as jump directly to any workspace or application. Left clicking (button 1) on an application in the Workspaces menu will switch to that workspace and raise/focus the application; mid clicking will warp the application to the current workspace and raise/focus it.
  • Shift + Right click on the desktop "emulates" a mid click (ie. pops up the Workspaces menu) for people still living with a 2 button mouse... :)
  • Left clicking on the titlebar of any submenu and then dragging it somewhere else will cause the menu to stay visible ("pinned"), ie. not disappear when you click a menu item. Right clicking the titlebar of a menu will make it disappear.
  • If you happen to have a mouse with more than three buttons, X1 clicking the desktop will open Display Properties, and X2 clicking will open Sounds and Multimedia Properties.
  • Drag'n'drop of an image file onto the desktop will set the image as your wallpaper (tiled mode) using bsetbg.

    Toolbar

  • Left clicking: There are four buttons on the toolbar; the two on the left will switch workspaces, the two on the right will cycle through your visible (non-maximized) applications. If the task you're switching to is on another workspace you will automatically be switched to that workspace.
  • Alt + Left clicking on the buttons that cycle windows will cycle through the windows on the current workspace only
  • Left doubleclick on the toolbar clock will open Date/Time Properties.
  • Right clicking the toolbar will pop up the toolbar menu, which lets you control toolbar settings such as placement and if the toolbar should be always on top.
  • Mid clicking the toolbar will show/hide the Blackbox internal system tray / taskbar.
  • Shift + Mid clicking the toolbar will show/hide any loaded plugins (naturally, this functionality needs to be supported by the plugin).
  • If you happen to have a mouse with more than three buttons, X1 clicking the toolbar will open Display Properties, and X2 clicking will open Sounds and Multimedia Properties.
  • Drag'n'drop of a style file onto the toolbar will make Blackbox use that style.
  • Ctrl + Left clicking will allow the Toolbar to be moved temporarily around the desktop
  • Shift + Left clicking will restore the Toolbar to it's original location

    • Oh, btw, there is also a single hotkey: Ctrl+Alt+F1 can be used to quit Blackbox for Windows... (you need to use a plugin if you want to be able to configure your own hotkeys).

     


    		 Installation:

    Blackbox can be run on top of almost any other shell. However, this will usually result in certain features of the underlying shell being de-activated. Blackbox is designed to be run as the single shell on your system, but it will not *automatically* install itself as the default shell. We do, however, recommend that you do make it such.

    To set Blackbox as your default shell, you could either use the built in -install functionality. If you are running Vista, you will need to exit BlackBox, right-click on blackbox.exe & select "Run as administrator" to install successfully. We also recommend that you consult online resources such as lsdocs.shellfront.org (replace the word "LiteStep" with "Blackbox" everywhere, and you will be fine! <g>).


     


    Configuration:

    On exit or restart, Blackbox will save the running configuration to the file blackbox.rc (or "blackboxrc", depending on which one it finds first) in the Blackbox root directory. This includes all options from the [config] submenu, the currently selected style file, your workspace names etc.

    The only blackbox.rc setting that you might want to edit yourself is:

  • session.menuFile:

    • This tells Blackbox where to look for its menu file - if, for example, you wish to place all your menus in a separate subdirectory.

    Additional configuration can be done via extensions.rc:

  • blackbox.appearance.bullet.unix:
    true|false - sets BB4Win to use (smaller) Blackbox for Unix type bullets
  • blackbox.appearance.metrics.unix:
    true|false - sets BB4win to use Blackbox for Unix sizing and spacing
  • blackbox.desktop.marginBottom: (optional)
  • blackbox.desktop.marginLeft: (optional)
  • blackbox.desktop.marginRight: (optional)
  • blackbox.desktop.marginTop: (optional)
    integer - sets the margins of each part of the desktop area
  • blackbox.editor:
    Path and file name for the default BB4Win editor.
    (Note: if the the path contains spaces, it must be in quotes)

    Note: For the custom Margin settings, if none are set, it defaults to the toolbar height. If one (or more) is set, the ones that are not are set to 0.

     


    Plugins:

    Plugins can be used to add certain features, such as hotkey support, to Blackbox for Windows. To load a plugin, you simply need to add the relative path of the plugin (from your Blackbox directory) to the file plugins.rc (located in the Blackbox directory). For example, if you installed Blackbox into c:\Blackbox, and your plugin (let's say BBKeys.dll) is located in c:\Blackbox\plugins\BBKeys, you should add the line...

    plugins\BBKeys\BBKeys.dll

    ...to plugins.rc. Blackbox will even warn you if it can not find the plugin you've specified. Simple, eh? :)

    [ Please note that some plugins may also have their own configuration files (BBKeys, for instance, uses a file named bbkeys.rc). For more information, try this crazy piece of advice: Read the plugin documentation! <g> ]

    Examples? Sure. Here's how to use BBKeys to control multiamp (the first two plugins to support bro@ms):

    KeyToGrab(Left), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maPrev)
    KeyToGrab(Enter), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maPlay)
    KeyToGrab(Spacebar), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maPause)
    KeyToGrab(Num0), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maStop)
    KeyToGrab(Right), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maNext)
    KeyToGrab(Add), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maOpenFile)
    KeyToGrab(Mul), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maMenu)
    KeyToGrab(Sub), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maPower)
    KeyToGrab(Up), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maVolumeUp)
    KeyToGrab(Down), WithModifier(Ctrl+Win), WithAction(ExecCommand), DoThis(@maVolumeDown)

    ...hopefully, that was self-explanatory... right? :)

     

    		•  Command Line:

    Blackbox supports the following commandline options (switches):

    -help
    Displays command line options and version information in a message box, then exits.
    -nostartup
    Starts Blackbox without running the items in your startup folder
    (-nostartup is used automatically if running on top of Explorer).
    -rc path
    Lets you specify a new blackbox.rc path.
    -searchmenu
    This will open up a file requester to let you search for a menu file to use.
    -searchstyle
    This will open up a file requester to let you search for a style file to use.
    -install
    Lets you install Blackbox as your default shell.
    -uninstall
    This will let you uninstall Blackbox, changing back to Explorer as default shell (you won't need this... <g>)
    -exec @bbCore.<core bro@m>
    This will send a command to the Blackbox shell. A full list of the commands available are listed here. Bro@ms are explained in more detail below.


     


    Customised Command Line (Bro@ms):

    Blackbox & its plugins support broadcast messages (we refer to them as bro@ms ) to communicate with other. A bro@m command can be sent by using an external plugin such as BBKeys, or using the Blackbox menu, and is recognized by the first letter of the command: @.

    This means is that *any* plugin can listen to *any* message sent by *any* source (Blackbox 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). In our opinion, this was a small price to pay to get basic (yet powerful) message handling into Blackbox for Windows.

    Each plugin can have its own set of bro@ms, but several plugins can also listen to (ie. "share") the same bro@m. As an example, there are two "global" bro@ms that should|must be supported by all plugins: @BBShowPlugins and @BBHidePlugins. These are used by Blackbox to enable a TogglePlugins menu command.


     


    Time Format:

    The default toolbar date|time display is:

  • %H:%M | %a %#d %b

    %a = Abbreviated weekday name,
    %A = Full weekday name
    %b = Abbreviated month name,
    %B = Full month name
    %c = Date and time representation appropriate for locale
    %d = Day of month - numerical (01 – 31)
    %H = Hour in 24-hour format (00 – 23)
    %I = Hour in 12-hour format (01 – 12)
    %j = Day of year - numerical (001 – 366)
    %m = Month - numerical (01 – 12)
    %M = Minute - numerical (00 – 59)
    %p = Current locale's A.M./P.M. indicator for 12-hour clock
    %U = Week of year - numerical - with Sunday as first day of week (00 – 53)
    %w = Weekday - numerical (0 – 6; Sunday is 0)
    %W = Week of year - numerical - with Monday as first day of week (00 – 53)
    %x = Date representation for current locale
    %X = Time representation for current locale
    %y = Year without century (00 – 99)
    %Y = Year with century
    %z, %Z = Time-zone name|abbreviation; no characters if time zone is unknown
    %#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y -> Remove leading zeros (if any)

    Characters that do not "begin" with % are copied unchanged to the output buffer.