Button 1.0.1

Author: Maduin (Kevin Schaffer) <kschaffe at kent dot edu>
Released: April 1, 2004

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).

LSBox Support

You can a place button inside of a box using the *ModuleHook mechanism. The hook bang command is !ButtonLSBoxHook. For example, to place a button named ExampleButton inside a box, place the following line into the box's configuration file: 

*ModuleHook !ButtonLSBoxHook ExampleButton

The button will still read it settings from the Litestep configuration file. Make sure that no button's name appears in both a *Button command and a *ModuleHook command at the same time. See the documentation for LSBox for more information.

Changes

License

Copyright 2004 Kevin Schaffer

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA