Button 1.0 beta 1

Description

Button is a Litestep module that lets you create skinnable push buttons and place them anywhere on your desktop. Buttons can change their appearance and run commands in response to user mouse actions.

Loading the Module

Add a new LoadModule line to the Litestep configuration file, similar to the following: 

LoadModule "c:\path\to\button.dll"

Of course, just loading the module doesn't do anything. You must create one or more buttons and configure them.

Creating a Button

You can create buttons automatically when Litestep loads or you can create them manually as Litestep is running. To create a button automatically you specify its name in a *Button command in the Litestep configuration file. Example: 

*Button MyButton
*Button ExampleButton
*Button Button1

These three commands create three buttons named MyButton, ExampleButton, and Button1 respectively. Note that each button must have its own *Button command. To create a button manually you specify its name in a call to the !ButtonCreate bang command. Example: 

!ButtonCreate AnotherButton

This creates a button named AnotherButton.

Destroying a Button

There is technically no need to explicitly destroy buttons. When Litestep shuts down or recycles, all buttons are automatically destroyed regardless of how they were created. However, it is possible to explicitly destroy a button using the !ButtonDestroy bang command. !ButtonDestroy works for all buttons whether they are created automatically or manually.

Configuration

The following configuration commands must be placed in the Litestep configuration file. See the Litestep documentation for information on how to modify this file.

In the command names given below Button is a placeholder for the button's name. So to set the text for a button named ExampleButton, the command you would actually put in step.rc would be ExampleButtonText.

Fonts and Skins

A button has three visual states: normal, hover and pressed. When the mouse is outside the button it is in the normal state. When the mouse is inside the button it is in the hover state. When the mouse is inside the button and a mouse button is pressed it is in the pressed state.

Buttons can have different fonts and skins for each state. By default the settings for the hover and pressed states inherit the values from the normal state. So, for example, if you don't specify a font to use in the pressed state, then when pressed the button will use the normal font. This even works on a per-setting basis. If you want to make the font underlined when in the hover state you need only add the ButtonHoverFontUnderline command; the font name, color, etc. will be inherited from the normal state settings.

Events

Events allow you execute programs or bang commands based on user interaction with the button. The following work the same as configuration settings. Each one takes the name of a program or bang commands as its value. When the event is triggered, the program or bang command is executed. Note that in the case of mouse clicks, assigning an action to both the click and the double click event will not work.

Bang Commands

Bang commands allow you to manipulate buttons while Litestep is running through scripts or other modules. See the Litestep documentation for more information about bang commands and how to use them.

Unlike configuration commands, the bang command names are exactly as they are listed below. The first parameter to every bang command is the name of the button that is the target of that command. Commands directed at buttons that don't exist are ignored (expect for !ButtonCreate, obviously).