Button

posted Jul. 08 2004 under

shortcuts

File	Released	Downloads
button-1.0.1.zip	Jul. 08 2004	107
button-1.0.zip	Jul. 08 2004	46

This description was generated from [button-1.0.1.html]

Button 1.0.1

Author: Maduin (Kevin Schaffer)

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.

ButtonAlign left, center, or right
Sets the horizontal alignment of the button's contents. The default is center.
ButtonAlpha number
Sets the button's alpha value (opacity) which is a number between zero (fully transparent) and 255 (fully opaque). This command only works on Windows 2000 and XP.
ButtonAlwaysOnTop
Makes the button always on top so that it remains above application windows. By default a button is pinned to the desktop and remains below application windows.
ButtonBottomBorder number
Sets the number of pixels on the bottom edge to reserve as a border. The default is zero.
ButtonHeight number
Sets the height of the button in pixels. The default is zero.
ButtonIcon filename
Specifies the name of an image file to be used as an icon. Despite the name, the file does not have to be a Windows icon file (.ico); it can be any image file type supported by Litestep. If the file is a Windows icon file then the ButtonIconSize command specifies which size to use. By default a button does not have an icon.
ButtonIconPosition left, right, top, or bottom
Sets the position of the button's icon relative to the text. The default is left.
ButtonIconSize number
Sets the size of a button's icon in pixels if the icon is Windows icon file (.ico). This is necessary because an icon file can contain multiple images of different sizes. If the icon is not an icon file then this command is ignored. The default is 16.
ButtonIconTextGap number
Sets the number of pixels between the button's icon and its text. The default is 4.
ButtonLeftBorder number
Sets the number of pixels on the left edge to reserve as a border. The default is zero.
ButtonRightBorder number
Sets the number of pixels on the right edge to reserve as a border. The default is zero.
ButtonStartHidden
Makes the button initially invisible.
ButtonText text
Sets the text that the button displays. By default a button does not display any text.
ButtonToolTipText text
Sets the text displayed by the button's tool tip. By default a button does not have a tool tip.
ButtonTopBorder number
Sets the number of pixels on the top edge to reserve as a border. The default is zero.
ButtonVertAlign top, center, or bottom
Sets the vertical alignment of the button's contents. The default is center.
ButtonWidth number
Sets the width of the button in pixels. The default is zero.
ButtonX number
Sets the horizontal position of the button. The default is zero.
ButtonY number
Sets the vertical position of the button. The default is zero.

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.

ButtonFont font
Font name in the normal state. The default is Arial.
ButtonFontBold boolean
Whether font is bold in the normal state. The default is false.
ButtonFontColor color
Font color in the normal state. The default is black.
ButtonFontHeight number
Font height (in pixels) in the normal state. The default is 15.
ButtonFontItalic boolean
Whether font is italic in the normal state. The default is false.
ButtonFontShadow boolean
Whether font has a shadow in the normal state. The default is false.
ButtonFontShadowColor color
Font shadow color in the normal state. The default is gray (RGB 128, 128, 128).
ButtonFontShadowOffsetX number
Number of pixels font shadow is offset horizontally from the text in the normal state. The default is 1.
ButtonFontShadowOffsetY number
Number of pixels font shadow is offset vertically from the text in the normal state. The default is 1.
ButtonFontUnderline boolean
Whether font is underlined in the normal state. The default is false.
ButtonHoverFont font
Font name in the hover state.
ButtonHoverFontBold boolean
Whether font is bold in the hover state.
ButtonHoverFontColor color
Font color in the hover state.
ButtonHoverFontHeight number
Font height (in pixels) in the hover state.
ButtonHoverFontItalic boolean
Whether font is italic in the hover state.
ButtonHoverFontShadow boolean
Whether font has a shadow in the hover state.
ButtonHoverFontShadowColor color
Font shadow color in the hover state.
ButtonHoverFontShadowOffsetX number
Number of pixels font shadow is offset horizontally from the text in the hover state.
ButtonHoverFontShadowOffsetY number
Number of pixels font shadow is offset vertically from the text in the hover state.
ButtonHoverFontUnderline boolean
Whether font is underlined in the hover state.
ButtonPressedFont font
Font name in the pressed state.
ButtonPressedFontBold boolean
Whether font is bold in the pressed state.
ButtonPressedFontColor color
Font color in the pressed state.
ButtonPressedFontHeight number
Font height (in pixels) in the pressed state.
ButtonPressedFontItalic boolean
Whether font is italic in the pressed state.
ButtonPressedFontShadow boolean
Whether font has a shadow in the pressed state.
ButtonPressedFontShadowColor color
Font shadow color in the pressed state.
ButtonPressedFontShadowOffsetX number
Number of pixels font shadow is offset horizontally from the text in the pressed state.
ButtonPressedFontShadowOffsetY number
Number of pixels font shadow is offset vertically from the text in the pressed state.
ButtonPressedFontUnderline boolean
Whether font is underlined in the pressed state.
ButtonSkin filename
Background image in the normal state.
ButtonSkinBottomEdge number
Number of pixels on the bottom edge that shouldn't be scaled in the normal state. The default is zero.
ButtonSkinLeftEdge number
Number of pixels on the left edge that shouldn't be scaled in the normal state. The default is zero.
ButtonSkinMode stretch, tile, horizontaltile, or verticaltile
How to scale the background image in the normal state. The default is stretch.
ButtonSkinRightEdge number
Number of pixels on the right edge that shouldn't be scaled in the normal state. The default is zero.
ButtonSkinTopEdge number
Number of pixels on the top edge that shouldn't be scaled in the normal state. The default is zero.
ButtonSkinTransparent boolean
Whether to enable transparency in the normal state.
ButtonHoverSkin filename
Background image in the hover state.
ButtonHoverSkinBottomEdge number
Number of pixels on the bottom edge that shouldn't be scaled in the hover state.
ButtonHoverSkinLeftEdge number
Number of pixels on the left edge that shouldn't be scaled in the hover state.
ButtonHoverSkinMode stretch, tile, horizontaltile, or verticaltile
How to scale the background image in the hover state.
ButtonHoverSkinRightEdge number
Number of pixels on the right edge that shouldn't be scaled in the hover state.
ButtonHoverSkinTopEdge number
Number of pixels on the top edge that shouldn't be scaled in the hover state.
ButtonHoverSkinTransparent boolean
Whether to enable transparency in the hover state.
ButtonPressedSkin filename
Background image in the pressed state.
ButtonPressedSkinBottomEdge number
Number of pixels on the bottom edge that shouldn't be scaled in the pressed state.
ButtonPressedSkinLeftEdge number
Number of pixels on the left edge that shouldn't be scaled in the pressed state.
ButtonPressedSkinMode stretch, tile, horizontaltile, or verticaltile
How to scale the background image in the pressed state.
ButtonPressedSkinRightEdge number
Number of pixels on the right edge that shouldn't be scaled in the pressed state.
ButtonPressedSkinTopEdge number
Number of pixels on the top edge that shouldn't be scaled in the pressed state.
ButtonPressedSkinTransparent boolean
Whether to enable transparency in the pressed state.
ButtonHoverOffsetX number
Number of pixels that the button's content is shifted horizontally in the hover state. The default is zero.
ButtonHoverOffsetY number
Number of pixels that the button's content is shifted vertically in the hover state. The default is zero.
ButtonPressedOffsetX number
Number of pixels that the button's content is shifted horizontally in the pressed state. The default is 1.
ButtonPressedOffsetY number
Number of pixels that the button's content is shifted vertically in the pressed state. The default is 1.

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.

ButtonOnEnter action
Executes action when the mouse enters the button.
ButtonOnLeave action
Executes action when the mouse leaves the button.
ButtonOnLeftClick action
Executes action when the user clicks the button with the left mouse button.
ButtonOnLeftDoubleClick action
Executes action when the user double clicks the button with the left mouse button.
ButtonOnMiddleClick action
Executes action when the user clicks the button with the middle mouse button.
ButtonOnMiddleDoubleClick action
Executes action when the user double clicks the button with the middle mouse button.
ButtonOnRightClick action
Executes action when the user clicks the button with the right mouse button.
ButtonOnRightDoubleClick action
Executes action when the user double clicks the button with the right mouse button.

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

!ButtonAlwaysOnTop name
Makes the button always on top so that it remains above application windows.
!ButtonCreate name
Creates a new button.
!ButtonDestroy name
Destroys a button, releasing any resources that it was using.
!ButtonHide name
Hides the button, making it invisible.
!ButtonMoveBy name dx dy
Moves the button horizontally dx pixels and vertically dy pixels relative to its current location.
!ButtonMoveTo name x y
Moves the button to the absolute coordinates (x, y).
!ButtonPinToDesktop name
Pins the button to the desktop so that it remains below application windows. This is the opposite of always on top.
!ButtonResizeBy name dx dy
Resizes the button horizontally dx pixels and vertically dy pixels relative to its current size.
!ButtonResizeTo name width height
Resizes the button so that its size is width pixels by height pixels.
!ButtonSetAlpha name number
Sets the button's alpha value (opacity) which is a number between zero (fully transparent) and 255 (fully opaque). This command only works on Windows 2000 and XP.
!ButtonSetIcon name filename iconsize
Sets the button's icon. The filename and iconsize parameters are both optional. If you don't specify a filename then the button will not have an icon. If the file is a Windows icon file (.ico) then the iconsize parameter determines its size. If iconsize is omitted the value of ButtonIconSize is used. If the file isn't an icon file then iconsize is ignored.
!ButtonSetText name text
Sets the button's text. The text parameter is optional and if omitted the button will not have any text.
!ButtonSetToolTipText name text
Sets the button's tool tip text. The text parameter is optional and if omitted the button will not have a tool tip.
!ButtonShow name
Shows a button, making it visible.
!ButtonToggle name
Switches a button between the visible and invisible states.
!ButtonToggleAlwaysOnTop name
Switches a button between the always on top and pinned to desktop states.

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

Version 1.0 released April 1, 2004
- Added support for font shadows (_ButtonFontShadow_, etc.)
- Added support for non-rectangular skins (_ButtonSkinTransparent_, etc.)
- Added support for LSBox hooks (_!ButtonLSBoxHook_)