INFO

Creating buttons with Sprite Candy is very straightforward. To create a button, create a text or image object first. Then you can declare this object to a 'button', using HUD_AddTextButton( ) or HUD_AddImageButton( ). Button objects will be checked for various mouse events each time you call HUD_CheckButtons( ). With image buttons, you can additionaly define two more image frames that are displayed automatically on mouse over and click events.

Example:

; (ASSUMES THAT YOU'VE ALREADY CREATED A HUD AND A LAYER WITH A FONT ATTACHED)

; CREATE A TEXT OBJECT
MyButton% = HUD_CreateText (Layer1,0,0,  "START GAME","CENTER",0,"CENTER","CENTER")

; ADD TO BUTTON LIST
AddTextButton (MyButton)

; CHECK FOR EVENTS (DO WITHIN A LOOP)
Repeat
	; CHECK BUTTONS
	event$  = HUD_CheckButtons$  (Layer1)
	Button% = HUD_GetActiveButton()

	Select event$
		Case "RELEASE" If Button = MyButton Then ...
		Case "MOVEIN"  If Button = MyButton Then ...
		Case "MOVEOUT" If Button = MyButton Then ...
		Case "CLICK"   If Button = MyButton Then ...
	End Select

	HUD_Update()
Forever

BUTTON COMMANDS

HUD_AddImageButton

HUD_AddTextButton

HUD_AddShapeButton

HUD_CheckButtons

HUD_GetActiveButton

HUD_RemoveButton

HUD_RemoveButtons

HUD_AddImageButton

HUD_AddImageButton ( Image_Handle%, [x1%], [y1%], [x2%], [y2%] )

This command adds an existing image object to the 'button list'. All items in the button list will be checked for mouse events when HUD_CheckButtons( ) is called. The current image content will be used as the 'normal state' image, while you can define two more texture area start coordinates to display a 'mouse hover' and a 'clicked' image, too. Sprite Candy will display these images automatically, depending on the button's mouse event.

Image_Handle%
Handle of an image object. The current image will be used as the 'normal' state image (when the mouse is outside the object).

x1% , y1% , x2% , y2%
x1 and y1 define the start coordinate of the texture area that should be displayed as the 'mouse over' image. x2 and y2 define the texture area that is displayed as a 'clicked' image then.

Hint: Use Sprite Candy effects with buttons to achieve nice results.

HUD_AddTextButton

HUD_AddTextButton ( Text_Handle% )

This command adds an existing text object to the 'button list'. All items in the button list will be checked for mouse events when calling HUD_CheckButtons( ).

Text_Handle%
Handle of a text object, created with HUD_CreateText( ).

HUD_AddShapeButton

HUD_AddShapeButton ( Shape_Handle% )

This command adds an existing shape object (circle, star, rectangle etc.) to the 'button list'. All items in the button list will be checked for mouse events when calling HUD_CheckButtons( ).

Shape_Handle%
Handle of a shape object, created with HUD_CreateShape( ).

HUD_CheckButtons

event$ = HUD_CheckButtons$ ( [Layer_Handle%] )

This command checks all items in the button list for mouse events and returns a string that describes the current mouse event (if one). To retrieve the handle of the used button, call HUD_GetActiveButton( ) directly after calling this function.

Buttons that are set to 'hidden' or placed on a hidden HUD or layer will be ignored. This is useful when doing title screens or menus with several pages where only buttons of the 'active' page should be checked.

The "MOVEIN", "CLICK" and "RELEASE" events are returned once when these events occured, while the "HOLD" and "HOVER" events will be returned as long as the mouse will stay over or hold down the button.

This command returns:

"MOVEIN" - Mouse moved inside the button (once)

"MOVEOUT" - Mouse has just left the button (once)

"HOVER" - Mouse stays above the button (constantly)

"CLICK" - Left mouse button has been clicked (once)

"HOLD" - Left mouse button hold down (constantly)

"RELEASE" - Left mouse button has ben released (once)

" " (Empty) - When no button events occured

Layer_Handle%
If you don't specifiy a layer handle here, ALL existing buttons will be checked for mouse events (as long as they're not set to 'hidden'). When you specify a layer handle, only buttons placed on this layer will be checked.

HUD_GetActiveButton

ObjectHandle% = HUD_GetActiveButton ( )

This command returns the handle of the currently active button. Use it directly after calling HUD_CheckButtons( ).

Returns:
The object handle of the active button after HUD_CheckButtons( ) has been called.

HUD_RemoveButton

HUD_RemoveButton ( Handle% )

This command removes a text or image object from the button list, so this object will not treated as a button anymore. This will not remove (delete) the object itself.

Handle%
The handle of a text or image object that has been added to the button list.

HUD_RemoveButtons

HUD_RemoveButtons ( )

This command disables all existing buttons at once (clears the complete button list).

©2004,2005 Mike Dogan / X-PRESSIVE.COM
X-PRESSIVE.COM is a label and working title of Mike Dogan, est. 1999
All artwork, including graphics, text, images and sounds are property of Mike Dogan, X-PRESSIVE.COM. Trademarks belong to their respective owners. All rights reserved.