Button 1.0

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)

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