BBInterface

From BB4Win Wiki

NOTE: This documentation is for BBInterface v0.9.71, and as such, not entirely accurate for current versions.

1 Overview
2 Tutorial
3 Controls
4 Scripting
5 Bro@m list
6 Changelog

[edit] Overview

BBInterface is a plugin originally developed by psyci, giving users a powerful tool to design unique desktops. It is driven entirely by bro@ms, allowing maximal interaction between it and other plugins. Combined with such a scripting tool as Tcl-bb, the possibilities are greatly increased. Due to the immense popularity of this plugin, there have been many improvements made to it over time, despite having been abandoned by its original author.

[edit] Tutorial

In this brief tutorial you'll be walked through most of the functions BBInterface (BBI, for short) offers, and you'll be on your way to designing a desktop that suits your needs. For the start of a more extensive tutortial see this tutorial by Jimmy

Once you load BBI up, you'll see a single button appear in the upper left corner of your screen. To access the BBI menu associated to the control, Ctrl-Right Click it. You can use this menu to change all the properties of a control, including appearance and behaviour, and also to modify options global to BBI. Select Interface Operations > Create New Control > Frame. This will create a new control for you to edit, a frame. Frames are capable of having other controls, or even plugins loaded into them. You should also change the default name of the control in Control Options > Control Name to something more descriptive, like RolldownMenu. This is important because this will be the name you'll use to refer to this particular control in bro@ms. To change the position of your newly created frame, use Ctrl-Drag to move it around, and Alt-Drag to resize it. Make it have a title bar by checking Control Options > Has Title Bar, and giving it a title in Control Options > Caption > Static Text.

Add a child control to the frame through the Interface Operations > Create New Child Control > Button option. This will create a button inside this frame. Furthermore, any command given to the parent control will affect its children as well, if applicable. Let's call this button NotepadButton, and give it a purpose. In Control Options > MouseDown > Run/Open, set the program that will be run when the button is clicked, Notepad, for instance. You could set any other program or command here, if you wanted to. Set its caption to something identifiable as well, then test it to see if it works.

Add another button to the frame, label it 'About', and use Control Options > MouseDown > BlackBox Bro@m > @BBInterface Plugin About to execute said bro@m, that will open up the about dialog of BBI. Now you see that using bro@ms in BBI is just as simple as executing programs, just as in the rest of your blackbox shell.

Create a switch button, this time, outside of the menu. This will act like a toggle for your menu, since you can assign an action for both the Pressed and UnPressed states. Set the former to @BBInterface Control SetWindowProperty rolldownmenu Height 75 (or whatever height you'd like your menu to be), and the latter to @BBInterface Control SetWindowProperty rolldownmenu Height 20. This button will now open and close your rolldown menu. ...And that's all, you're set! Try experimenting with BBI yourself, see what you can come up with.

[edit] Controls

'Controls' are the basic elements that make up every BBI setup. With them it's possible to send bro@ms to the shell, and to other BBI elements as well. This allows for creating dynamically changing interfaces, such as a wharf, a sidebar, or a control dock.

[edit] Frame

The most basic element of BBI, serving both as a backdrop for other elements, and as a parent control to group them together. The latter function becomes especially useful when creating larger, more complex elements, since any bro@ms sent to a control are immediately applied to its children. Note that elements inside a frame will be drawn as such: parts that would go over the boundaries of the parent frame won't get drawn. Therefore a nice rolldown effect can be achieved simply by dynamically changing the width/height of said frame. Also consider the OnDrop agent for frames - it allows for adding children to a control simply by drag 'n drop. Frames also play a central role in creating modules.

[edit] Label

Labels are simply for storing text and images. Various formatting options exist for changing the orientation of the caption and the image.

[edit] Button

Buttons do what the name suggests - they trigger actions on various mouse events. Aside from the RightMouseUp event that's available for frames and labels, too, you have access to any mouse press or release action. Different actions can be assigned to different mouse events, but try to keep in mind how they interact. If you want a button to perform a more complex task, you should either use @Scripts or the Load [script] BBI broam. The former is a standard Blackbox feature, the latter is inherent to BBI; by using @BBInterface Plugin Load <file> you could load an entire file, or just a section of it with @BBInterface Plugin Load [section] from <file>.

[edit] Switch Button

Very similar to plain buttons, except that this variety allows on/off states, and assigns actions to these states. Usable for toggling different elements or options.

[edit] Slider

Sliders are commonly used for controlling the volume of audio devices, but using bro@ms, they can basically send their values to any other object. The value itself is determined by what's shown on the slider, and the lower and upper bounds set. The value generated this way will replace the %d in the bro@m specified.

[edit] Modules

Modules are nothing but frames managed through a special interface, allowing them to be loaded and unloaded much like plugins in the shell itself. They're saved in their separate files, so they can help manage larger interfaces. To create a module yourself, first, construct the frame and all its contents you want to have as part of the module. Then, save the frame as an individual script through the Save Control As... option. Now delete the frame (so you'll actually see it load as the module), and add it, then load it through the module menu.

Some guidelines for creating modules:

One frame (and its children) per module only.
Use prefixed names. That will help prevent possible problems if other controls with the same name exists.
Use relative paths, so that others won't have to modify your module just to get it to work. (Unless you're referring to external programs, obviously.)

[edit] Scripting

Okay, so by now, you have a basic understanding of what BBI consists of, and preferably even built a few simpler menus. But there is only so much you can do simply with the default bro@ms provided through the menu. If you'd want to bind more complicated actions to a button, you could be using insanely long @Scripts, if you really wanted to. With the Plugin Load bro@m, however, you can simply load a config file, and have its contents executed, exactly as it happens with the bbinterface.rc upon program startup. For something more interesting, you can use the Plugin Load [section] from <file> command, for loading only a part of one file. Let's say you want an interface that can change its outlook with a press of a button. The straightforward method would be to use different config files, and load them - but how many designs would you like it to take on? And how different would these be? A more elegant method would be to group them in one file, as such:

styles.rc

[style1]
@BBInterface SetWindowProperty ...
...
[style2]
@BBInterface SetWindowProperty ...
...

And truly, you need no more than that, and it works as expected, only loading the appropriate parts of the script.

Another nifty thing you can use, are variables. Just slam some text between to $ signs, and it'll try to get replaced with some meaningful value. If you set it previously with the @BBInterface Set bro@m, you can use those variables, in any possible place. Even for as ridiculous things, as storing a BBI bro@m inside it - if it gets seen by the preprocessor, it'll be replaced no matter what it contains. This allows for some pretty extreme things. However, the most common use would be to shorten scripts - that is, set some variables to given values, and then use those values in some other script. Values that are repeated often are obvious candidates (property values, name of a control, etc.) There are special uses for this syntax, too. $LastControl$ will contain the name of the last created control, $LastPlugin$ will get replaced with the path of the last plugin loaded, $Mouse.X$ and $Mouse.Y$ are the coordinates of the cursor, and finally, $<control>.<property>$ will be either the Width, Height, X, or Y properties of a <control> you provide.

And this variable mumbo-jumbo also needs another thing to work properly - values being calculated from expressions. It wouldn't be much fun not to be able to set one control's properties relative to an other. But, with expressions being evaluated, that is possible. Currently it's only enabled for the Width, Height, X, and Y properties, and the operations themselves are performed in order - no precedence or parenthesising yet. With that said, the common operators of +,-,*,/ are at your disposal, as well as a feature that lets you alter the value of a property, rather than set it directly. Just put a ? (question mark) as the first character of the expression, and the appropriate operators right after it.

[edit] Bro@m list

@BBInterface Control Create <type> [<name>]: Creates a new control of given type <type> with the unique identifier <name>. <type> maybe any one of the following type identifiers: Frame, Label, Button, SwitchButton, Slider. <name> can only include alphanumeric characters and underscores. If omitted, <name> defaults to <type>#, where # is the next available number for a unique control name.
@BBInterface Control CreateChild <parent> <type> [<name>]: Creates a new control of given <type> with the unique identifier <name>, and attaches it to the control named <parent>. Again, the <name> can be omitted.
@BBInterface Control Delete <control>: Destroys the control with given name <control>.
@BBInterface Control Rename <control> <name>: Changes name of <control> to <name>.
@BBInterface Control Clone <control>: This will create a clone of <control>, giving it a name with format<type>#, where <type> is replaced by the name of the cloned control's type, and # is the next available number making the resulting name a valid one.
@BBInterface Control SaveAs <control> <file>: Saves given control <control> into the file specified in <file>. If *browse* is specified as <file>, an open file dialog will be opened for selecting a path and filename.
@BBInterface Control SetWindowProperty <control> AttachTo <parent>: Attaches given <control> to <parent>, just as if it were created with the CreateChild command.
@BBInterface Control SetWindowProperty <control> Detach: Detaches the given <control> from its parent.
@BBInterface Control SetWindowProperty <control> <property> <value>: The proper format of <value> depends on the given <property>. The possible types are bool, in which case proper values are either true or false, int, where any integer number is acceptable, and str, where <value> can only be one of a set of strings. A list of properties, given in the format of "type property Description"

int X Horizontal position of control.
int Y Vertical position of control.
int Width Width of control.
int Height Height of control.
bool Border Defines whether the control has a border or not.
bool IsVisible Toggles the control's visibility.
str Style Defines appearance of control. Possible values are Toolbar, Inset, None.

The following properties can only be applied to controls without a parent:

bool IsOnAllWorkspaces When set, control will be visible on all workspaces.
bool IsOnTop If set, control stays always on top.
bool IsSlitted Set if the control is to be displayed in the slit.
bool IsToggledWithPlugins If set, control will change its visibility along with other plugins.
bool AutoHide When set, control will automatically be hidden when inactive.
bool IsTransparent Defines whether the control should be drawn with transparency.
int Transparency Amount of transparency, in percent.

@BBInterface Control SetControlProperty <control> <property> <value>: Sets the given <property> of a <control> to the specified <value>. A list of properties, grouped according to the controls they belong to, given in the format of "type property Description".

Frame/Label

VAlign Vertical alignment of the caption, can be one of the following: Center, Top, Bottom, TopWrap. TopWrap allows word wrapping, and use of the '\n' escape sequence for inserting line breaks.
HAlign Horizontal alignment of the caption, can be one of the following: Center, Left, Right.
HasTitleBar Sets whether the control has a title bar. Only applicable for frames.
IsLocked If enabled, the children of the frame can not be repositioned. Not applicable for labels.

Button/SwitchButton

Pressed Sets the state of the button. Only for switch buttons.
VAlign Vertical alignment of the caption, can be one of the following: Center, Top, Bottom, TopWrap. TopWrap allows word wrapping, and use of the '\n' escape sequence for inserting line breaks.
HAlign Horizontal alignment of the caption, can be one of the following: Center, Left, Right.

Slider

Value Sets the value of the slider, in a number between 0 and 1.
Reversed Reverses the way values are displayed.
Vertical If set, the slider will be one of vertical orientation.
Appearance Defines the appearance of the slider. Can be one of the following: Fill Bar,Scroll Bar,Track and Knob.

@BBInterface Control SetAgent <control> <mount> <agent> <params>

Adds an <agent> to a selected <mount> on <control>, with given parameters <params>. Controls of different types have a differing range of mount points, and types of agents that can be assigned to them. Some agents may be fit to more than one type of a mount point. A list of mount points, grouped according to the controls they belong to, in the format "type mount Description".

Frame/Label

text Caption The text to be displayed on the control.
image Image Image attached to the control.
trigger RightMouseUp Executed when a right mouse release event is triggered.
drop OnDrop Executed when a file is dropped onto the control.

Button

text Caption The text to be displayed on the control.
image Image Image attached to the control.
trigger MouseDown Executed when a single or double mouse click is detected.
trigger MouseUp Executed when a left mouse release event is triggered.
trigger RightMouseUp Executed when a right mouse release event is triggered.
drop OnDrop Executed when a file is dropped onto the control.

SwitchButton

text Caption The text to be displayed on the control.
image Image Image attached to the control.
bool Value The current state of the button is communicated to this agent.
trigger Pressed Executed when the switch is turned on.
trigger Unpressed Executed when the switch is turned off.

Slider

scale Value The value of the slider is communicated to this agent.

Agents listed in format "name (types) Description".

Bro@m (trigger,drop,scale) Sends the broam specified in <params>.
Bitmap (image) Loads the image file specified in <params> into the control. If *browse* is given instead of a filename, an open file dialog window will be displayed.
Icon (image) Loads an icon from a file, or possibly from within an executable file, specified in <params> into the control. If *browse* is given instead of a filename, an open file dialog window will be displayed.
TGA (image) Loads the image file specified in <params> into the control. It must be an uncompressed 32bpp TGA. If *browse* is given instead of a filename, an open file dialog window will be displayed.
MixerScale (scale) Handles communication of integer variables to the audio device designated in <params>.
MixerBool (bool) Allows changing a toggleable option of an audio device, defined in <params>.
Run (trigger,drop) Runs the file specified in <params>. If *browse* is given instead of a filename, an open file dialog window will be displayed.
StaticText (text) Writes the text specified in <params> onto the control.
System (trigger) Sends a message to the underlying system or shell. The action to take is specified in <params>.
Winamp (trigger) Allows sending messages to Winamp. The specific message is given in <params>.

@BBInterface Control RemoveAgent <control> <agent>: Removes <agent> from <control>.

@BBInterface Control SetAgentProperty <control> <agent> <property> <value>: Sets a <property> of an <agent> on given <control> to <value>. List of agents and their properties:

Bitmap

Scale Allows proportional scaling of an image, from 1 to 500 percent of the original.
VAlign Vertical alignment of the image, can be one of the following: Center, Top, Bottom.
HAlign Horizontal alignment of the image, can be one of the following: Center, Left, Right.

Icon

Size The size of the icon in pixels.
VAlign Vertical alignment of the image, can be one of the following: Center, Top, Bottom.
HAlign Horizontal alignment of the image, can be one of the following: Center, Left, Right.

Bro@m

MinValue If the bro@m is used as a scale, this specifies the minimal value that the %d will take in the command string.
MaxValue Same as above, except this specifies the maximal value.

Run

Arguments The arguments that will be passed to the executable.
WorkingDir The working directory that will be used when running the executable.

@BBInterface Plugin Edit: Opens the main configuration file (BBInterface.rc) for editing through the default blackbox editor.
@BBInterface Plugin Save: Saves the current configuration to the default config file.
@BBInterface Plugin SaveAs [<file>]: Saves the configuration to the given <file>, or opens up a file dialog window if <file> is omitted.
@BBInterface Plugin Revert: Reloads the configuration from the disk.
@BBInterface Plugin Load [<file>]: Loads the configuration from given <file>, opening up a file dialog window if necessary.
@BBInterface Plugin Load [section] from <file>: Loads a script, identified by the [section] tag in square brackets, from <file>.
@BBInterface Plugin SetPluginProperty <property> <value>: Sets a global <property> to given <value>. A list of properties in the format "type property Description".

bool SnapWindows If turned on, controls automatically snap to nearby desktop elements.
int SnapDistance Changes the distance inside which snapping occurs.
int SnapPadding The distance of snapped elements can be set with this.
int IconSaturation Sets the saturation of unselected icons.
int IconHue Sets the hue of unselected icons.
bool ClickRaise If set to true, controls are brought to the front when clicked on.
str DeskDropCommand Specifies the bro@m to be executed when a file is dropped on the desktop.
bool SuppressErrors Error messages are disabled, unless this is set to false.
bool ZeroControlsAllowed When turned off, the LastControl element doesn't get created when zero controls would be left.
bool UseTooltip Displays a tooltip with the name of the control the mouse is above, if enabled.
bool ClearConfigurationOnLoad When loading a config file, it will replace the current one, instead of being added on to it.
bool ModuleAutoSave Toggles whether modules should be saved when they're unloaded.

@BBInterface Plugin AddModule [<file>]: Adds a new <file> to the modules list. If no filename is given, an open file dialog window will be opened.
@BBInterface Plugin LoadModule <name>: Loads or unloads a module with given <name>. The name of a module is that of the first control created within, assumed to be the parent of the rest.
@BBInterface Plugin EditModule <name>: Opens the module with the given <name> in the default editor.
@BBInterface Set <name> <value>: Sets the variable with given <name> to contain <value>. Thereafter, every occurence of $<name>$ will be replaced with <value>.
@BBInterface Plugin About: Pops up a messagebox with information about the plugin.
@BBInterface Plugin About LastControl: Opens up a messagebox with info regarding the LastControl.
@BBInterface Plugin About QuickHelp: Provides info on basic operation of the plugin.

[edit] Changelog

[26-Feb-2006] - v0.9.71 - pkt-zer0
 - max. controls limit removed
 - hash table lookup for faster data access
 - caption and image alignment
 - module system added
[31-Jan-2006] - v0.9.62y - ysuke
 - support for PNG,JPG,GIF,TIF,etc (GDI+ supported formats)
 - menu item to adjust icon size
 - menu item to adjust image scale
[25-Feb-2005] - v0.9.62u - kana
 - tooltip 
 - clear configuration on load
[07-Feb-2005] - v0.9.62 - grischka
 - fixed a problem with distorted icons
[21-Nov-2004] - v0.9.6 - grischka
 - snap controls
 - load plugins
 - autohide
 - save control as...
 - clone control
 - send broam from slider
 - lock childs on frames
 - support for Drop on Desktop command 
 - OnDrop agent for buttons and frames
 - load [section] from script

Retrieved from "http://wiki.bb4win.org/wiki/BBInterface"

Category: Plugins