There are some constants that you might want to tweak before using the GUI extension. These constants are found on top of the "sprite candy gui.bb" file:

Const GUI_MAXGADGETS% 	= 25
Const GUI_TITLEDRAGONLY%   = False
Const GUI_BLOCKYBAR%	= True
Const GUI_SLIDEDRAG%	= False
		

GUI_TITLEDRAGONLY:
TRUE or FALSE. If set to TRUE, windows can only be dragged by using their title bar (difficult when using windows without a title bar). By default, windows can be dragged by clicking anywhere inside.

GUI_BLOCKYBAR:
TRUE or FALSE. If set to TRUE, progressbars will be increased block-wise, if set to FALSE, progressbars will be increased smoothly.

GUI_SLIDEDRAG:
TRUE or FALSE. If set to TRUE, windows will slide out when being dragged and released.

STEP 2:

Place the GUI extension ("sprite candy gui.bb") within the same folder as the Sprite Candy main lib and include it to your main program directly AFTER including the Sprite Candy main lib:

; INCLUDE SPRITE CANDY (FIRST)
Include "sprite candy.bb"

; INCLUDE GUI EXTENSION (SECOND)
Include "sprite candy gui.bb"
		

STEP 3:

All you need to do then is to create a common Sprite Candy HUD that should be used for the GUI elements then:

Light = CreateLight ()
Cam   = CreateCamera()

; CREATE A HUD FOR THE GUI
MyHUD% = HUD_Create (Cam)

; INIT GUI
GUI_Create MyHUD, "skin.png", "font_title.png", "font.png", "icons.png", 8

; NOW CREATE ANY WINDOWS & GADGETS!
		

GUI_Update ()

This command updates all changes made to the GUI elements and should be called frequently (within your main loop). Place this command directly after HUD_Update.

GUI_Create (  HUD_Handle%,  skin_texture$,  titlebar_font$,  gui_font$,  icon_texture$,  [shadow_offset%]  )

This initializes a new GUI, loading a specified skin graphic, font files and an icon strip graphic. The GUI will be drawn on the specified HUD (this HUD should not be used by any other objects).

HUD_Handle%
The handle of a Sprite Candy HUD created with HUD_Create( ).

skin_texture$
Path to a skin texture that contains all the GUI graphic parts.

titlebar_font$
Path to a Font Candy font texture that should be used as titlebar font. There must also be a same-called .dat file containing the font metrics in Font Candy format. Both files are exported by Font Candy Studio (included with Sprite Candy).

gui_font$
Path to a Font Candy font texture that should be used as gui text font. There must also be a same-called .dat file containing the font metrics in Font Candy format. Both files are exported by Font Candy Studio (included with Sprite Candy).

icon_texture$
Path to texture that contains all icons that you may want to use. The texture width and height must be any power of 2 (for example: 64, 128, 256 etc.). Each icon must be sized 16 x 16 pixels. Icons are placed next to each other, from left to right, and from top to bottom (see graphic). The first icon has the index number 0, the second 1, the third 2 etc. Black pixels will appear transparent.

shadow_offset%
Optional. Default is 0. If set to any value above 0, all created windows contain dropshadows using this offset. Since windows are treated as common Sprite Candy images, you can also add or remove shadows manually at any time, using HUD_SetObjectShadow(), for example.

GUI_LoadSkin (  skin_texture$,  titlebar_font$,  gui_font$,  iconstrip$  )

While GUI_Create is used to initialize the GUI, you can use GUI_LoadSkin at any time to load in a new skin, fonts and icons during runtime ("hot swap").

skin_texture$
Path to a skin texture that contains all the GUI graphic parts.

titlebar_font$
Path to a Font Candy font texture that should be used as titlebar font. There must also be a same-called .dat file containing the font metrics in Font Candy format. Both files are exported by Font Candy Studio (included with Sprite Candy).

gui_font$
Path to a Font Candy font texture that should be used as gui text font. There must also be a same-called .dat file containing the font metrics in Font Candy format. Both files are exported by Font Candy Studio (included with Sprite Candy).

iconstrip$
Path to texture that contains all window icons that you may want to use. The icon strip texture image should be 16 pixels high, the width must be any power of 2 (for example: 128, 256, 512 etc.). Icons are placed in one row, next to each other (without spacing). Each icon must be sized 16x16 pixels. Black pixels will appear transparent.

WindowHandle% =  GUI_CreateWindow% (  caption$,  x%,  y%,  width%,  height%,  flags%,  [xAlign$%],  [yAlign$],  [icon%]  )

This will create a new window and return a handle to it. The created window will automatically appear on top of all existing windows.

HINTS: Windows can be used exactly like Sprite Candy images, so you can apply FX effects to it, rotate, scale or position it, exactly like any other Sprite Candy image). Some examples:

GUI_SetWindowTitle (  WindowHandle%,  icon%,  caption$  )

Use this command to change a window's title caption or title bar icon at any time.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

icon%
Determines the window title bar icon. Remember the loaded icon strip containing different icon images placed in one row. '0' will use the first (leftmost) icon, '1' will use the second and so on. You can use '-1' to show no icon at all.

caption$
A string representing the window title bar caption.

txt$ =   GUI_GetWindowTitle$ (  WindowHandle%  )

Returns the current window title bar caption.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

GUI_WindowToFront (  WindowHandle%  )

Puts a window to front.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

num% =   GUI_CountWindows% (  )

Returns the number of currently existing windows.

size% =   GUI_GetWindowTexSize% (  WindowHandle%,   [getHeight%]  )

Returns the actual width or height of the texture used by the specified window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

getHeight%

size% =   GUI_GetWindowSize% (  WindowHandle%,   [getHeight%]  )

Returns the total screen size of a window (including frame or title bar).

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

getHeight%

BufferHandle% =   GUI_GetWindowBuffer% (  WindowHandle%  )

Returns the Blitz buffer handle of a window's texture. Can be used to draw directly to a window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

WindowHandle% =   GUI_GetTopWindow% (  )

Returns the handle of the currently topmost (active) window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

WindowHandle% =   GUI_GetClosedWindow% (  )

Use this command to detect if a window has been closed by the user (by clicking a window's close button). This enables you to perform some actions before removing this window.

WindowHandle% =   GUI_GetDraggedWindow% (  )

Returns the handle of the currently dragged GUI window (if any). Useful to check if and what window is currently dragged.

GadgetHandle% =  GUI_AddFrame% (  WindowHandle%,  [disabled%],  [x%],  [y%],  [width%],  [height%]  )

Creates a rectangle-shaped frame.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

disabled%

GadgetHandle% =  GUI_AddLabel% (  WindowHandle%,  x%,  y%,  width%,  height%,  text$,  [alignment$],  [border%],  [disabled%]  )

Creates a text label.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%, height%
Position and size of the gadget within the window's inner area.

text$
The caption of the label. The text will be wrapped automatically (using the specified text alignment) if a text line exceeds the gadget's width. You can use the pipe char ( | ) to create lines breaks anywhere within the text.

alignment$

GadgetHandle% =  GUI_AddButton% (  WindowHandle%,  x%,  y%,  width%,  text$,  [disabled%]  )

Adds a clickbutton to a window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the button is determined automatically, according to the height of the button graphics in the current skin image.

text$
You guess it ;-)

disabled%

GadgetHandle% =  GUI_AddCheckBox% (  WindowHandle%,  x%,  y%,  width%,  text$,  [selected%],  [disabled%]  )

Adds a checkbox to a window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the checkbox is determined automatically, according to the line height of the font used.

text$
The checkbox caption.

selected%

GadgetHandle% =  GUI_AddCheckButton% (  WindowHandle%,  ResourceID%,  x%,  y%,  [clipx%], [clipy%], [clipw%], [cliph%],  [border%],  [disabled%]  )

Adds a "toggle button" or "on/off button" to a window. These buttons are the same like checkboxes, but you can use your own images here -one for the "normal" state, and another one for the "pressed" state. Useful to create application toolbars etc.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

ResourceID%
Sprite Candy image resource handle, loaded with HUD_LoadImageResource ( ).

x%, y%
Position of the gadget inside the window.

clipx%, clipy%, clipw%, cliph%
The first two parameters define the start position of the texture area that the image should display (in pixels). If you do not specify x or y, the start position will be 0,0. The second two parameters define the width and height of the texture area to display (in pixels), counted from the start position. The created image will have the same size as the texture area it displays. If no width and height parameters are specified, they will be set to the total width or height of the loaded image resource.

border%

GadgetHandle% =  GUI_AddImageButton% (  WindowHandle%,  ResourceID%,  x%,  y%,  [clipx%], [clipy%], [clipw%], [cliph%],  [border%],  [disabled%]  )

Image buttons use images instead of text captions. The images can be placed on a regular Sprite Candy resource image. The image buttons' height may not exceed the height of the button images of the currently loaded skin. If the used image is higher than that, it will be cropped automatically.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

ResourceID%
Sprite Candy image resource handle, loaded with HUD_LoadImageResource ( ).

x%, y%
Position of the gadget inside the window.

clipx%, clipy%, clipw%, cliph%
The first two parameters define the start position of the texture area that the image should display (in pixels). If you do not specify x or y, the start position will be 0,0. The second two parameters define the width and height of the texture area to display (in pixels), counted from the start position. The created image will have the same size as the texture area it displays. If no width and height parameters are specified, they will be set to the total width or height of the loaded image resource.

border%

GadgetHandle% =  GUI_AddRadioBox% (  WindowHandle%,  x%,  y%,  width%,  groupname$,  text$,  [selected%],  [disabled%]  )

Adds a radio box (radio button) to a window.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the gadget is determined automatically, according to the line height of the font used.

groupname$
Any string defining the name of a radio button group (example: "GROUP_1"). Radio buttons using the same group name will be treated as a group.

text$
The gadget caption.

selected%

GadgetHandle% =  GUI_AddProgBar% (  WindowHandle%,  x%,  y%,  width%,  [value#],  [disabled%]  )

Adds a progress bar to a window. You can alter this gadget's progress bar by calling GUI_SetGadgetValue ( ) with a value from 0.0 (0 percent) to 1.0 (100 percent)

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the gadget is determined automatically, according to the height of the progressbar graphics of the current skin.

value#
Initial value of the progress bar, may range from 0.0 (0 percent) to 1.0 (100 percent).

disabled%

GadgetHandle% =  GUI_AddSliderH% (  WindowHandle%,  x%,  y%,  width%,  steps%,  [showMarkers%],  [initialStep%],  [disabled%]  )

Adds a horizontal slider to a window. You can manually set the slider position using GUI_SetGadgetValue ( ), using a step number, and receive the slider's current position by calling GUI_GetGadgetValue.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the gadget is determined automatically, according to the height of the slider button graphic of the current skin.

steps%
Specifies the number of steps (positions) of the slider.

showMarkers%

GadgetHandle% =  GUI_AddSliderV% (  WindowHandle%,  x%,  y%,  height%,  steps%,  [showMarkers%],  [initialStep%],  [disabled%]  )

Adds a vertical slider to a window. You can manually set the slider position using GUI_SetGadgetValue ( ), using a step number, and receive the slider's current position by calling GUI_GetGadgetValue.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, height%
Position and height of the gadget. The width of the gadget is determined automatically, according to the width of the slider button graphic of the current skin.

steps%
Specifies the number of steps (positions) of the slider.

showMarkers%

GadgetHandle% =  GUI_AddTextField% (  WindowHandle%,  x%,  y%,  width%,  max_chars%,  [allowed_chars$],  [initial_text$],  [password%],  [disabled%]  )

Adds an input text field to a window. Text can be set or read using GUI_SetGadgetText ( ) and GUI_GetGadgetText ( ).

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%, width%
Position and width of the gadget. The height of the gadget is determined automatically, according to the height of the textfield graphic of the current skin.

max_chars%
Specifies the maximum number of chars that can be entered by the user.

allowed_chars$
A string containing all accepted chars. A string like "0123456789_ " (note the space at the end) will cause the gadget to accept numbers only, together with an underscore and a space char. If you do not specify a string here (or use an empty string), a default string will be used that includes all uppercase and undercase chars, numbers and the most common punctuation marks.

initial_text%
You can set an initial text by specifying a string here.

password%

GadgetHandle% =  GUI_AddImage% (  WindowHandle%,  ResourceID%|ImageHandle%,  x%,  y%,  [clipx%],  [clipy%],  [clipw%],  [cliph%],  [maskMode%],  [border%],  [disabled%]  )

Adds an image to a window. You must specify a Sprite Candy texture resource loaded with HUD_LoadImageResource ( ). You can then either draw the complete image to the window or a clipped rectangle (image area).

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

ResourceID% | ImageHandle%
Sprite Candy image resource handle, loaded with HUD_LoadImageResource ( ) or a common Blitz image handle.

x%, y%
Position of the gadget inside the window.

clipx%, clipy%, clipw%, cliph%
The first two parameters define the start position of the texture area that the image should display (in pixels). If you do not specify x or y, the start position will be 0,0. The second two parameters define the width and height of the texture area to display (in pixels), counted from the start position. The created image will have the same size as the texture area it displays. If no width and height parameters are specified, they will be set to the total width or height of the loaded image resource.

maskMode%

GadgetHandle% =  GUI_AddColorPicker% (  WindowHandle%,  x%,  y%,  width%,  height%,  [disabled%]  )

Adds a color picker gadget to a window. The user can pick any color by clicking on the gradient image. Additionally, the brightness of the picked color can be adjusted by moving the slider on the right side of the gadget. The RGB value of the selected color can be retrieved using GUI_GetGadgetValue ( MyColorPicker ). This returns a combined RGB value (like the Blitz command ReadPixel, for example).

Here's an example on how to extract the red,green and blue components from a combined RGB value:

R% =(GUI_GetGadgetValue( MyPicker ) AND $FF0000)/$10000
G% =(GUI_GetGadgetValue( MyPicker ) AND $FF00)/$100
B% = GUI_GetGadgetValue( MyPicker ) AND $FF

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

x%, y%
Position of the gadget inside the window.

width%, height%%
The width and height of the gadget.

disabled%

coord% =  GUI_GetColorPickerCoords% (  GadgetHandle%,  what%  )

Returns the current coordinates of the color picker haircross and the gadget's brightness slider. This is useful to "remember" the current color selection at any time. A previously selected color can be restored by passing these three coordinates to GUI_SetColorPickerCoords ( ).

GadgetHandle%
Handle of a color picker gadget created with GUI_CreateColorPicker( ).

what%

GUI_GetSolorPickerCoords% (  GadgetHandle%,  x%,  y%,  y2%  )

Sets the color picker haircross and the gadget's brightness slider to specified positions. This is useful to restore a previously selected color.

GadgetHandle%
Handle of a color picker gadget created with GUI_CreateColorPicker( ).

x%, y%
The x and y coordinates of the color selection haircross, where 0,0 is the top left corner of the gadget.

y2%
The y coordinate of the brightness slider, where 0 is the top of the slider.

GadgetHandle% =  GUI_GetClickedGadget% (  )

Returns the handle of the last gadget used (or -1 if no gadget has been clicked). Use this command within your main loop (using a SELECT statement, for example) to execute individual actions for the clicked gadget. Calling this function will reset this flag again, so it should be used once per frame only (alternatively, use a variable to store the returned handle).

GadgetHandle% =  GUI_GetMouseX% (  WindowHandle%,  [inner_area%]  )

Returns the current mouse x-position (in pixels) as seen from the specified window. If inner_area is set to TRUE, for example, and the mouse is placed on the top left corner of the inner window area, the returned coordinate will be 0. This command also works with rotated or scaled windows.

inner_area%

GadgetHandle% =  GUI_GetMouseY% (  WindowHandle%,  [inner_area%]  )

Returns the current mouse y-position (in pixels) as seen from the specified window. If inner_area is set to TRUE, for example, and the mouse is placed on the top left corner of the inner window area, the returned coordinate will be 0. This command also works with rotated or scaled windows.

inner_area%

GUI_SetVolume (  volume#  )

Sets the sound effects volume of the GUI sounds (GUI sounds are specified in the current skin's .cfg file). The parameter's value may range from 0.0 (silent) to 1.0 (maximum).

GUI_SetGadgetText (  GadgetHandle%,  text$,  [alignment$]  )

Changes a gadget's caption. Can be used to change the text of a clickbutton, a checkbox or a textfield, for example.

GadgetHandle%
Handle of a GUI gadget.

alignment$
Specifies the alignment of the gadget's text. This parameter will be ignored by most gadgets, except labels, for example.

txt$ =  GUI_GetGadgetText$ (  GadgetHandle%,  [get_wrapped$]  )

Returns a gadget's current text or caption.

GadgetHandle%
Handle of a GUI gadget.

get_wrapped$
Some gadgets (labels, for example) use automatic text wrapping. When used with these gadgets, this command can also return the wrapped text, which will include new line chars - Chr(13) - where a text line had to be wrapped according to the gadget's width.

GUI_SetGadgetValue (  GadgetHandle%,  value#  )

Sets a gadget's value. The purpose of this command depends on the type of the specified gadget. Used to change the state of checkboxes, radio buttons, sliders and progress bars, for example.

GadgetHandle%
Handle of a GUI gadget.

value#

value# =  GUI_GetGadgetValue# (  GadgetHandle%  )

Returns a gadget's value, which depends on the type of the specified gadget. Used to detect the state of checkboxes and radio buttons, the value of a progress bar, or the current step of a slider gadget, for example.

GadgetHandle%
Handle of a GUI gadget.

value#

size% =  GUI_GetGadgetSize% (  GadgetHandle%,  flag%  )

Returns a gadget's width or height.

GadgetHandle%
Handle of a GUI gadget.

flag%

x%|y% =  GUI_GetGadgetPos% (  GadgetHandle%,  [getY%]  )

Returns a gadget's x- or y-position on the window.

GadgetHandle%
Handle of a GUI gadget.

getY%

GUI_SetGadgetShape (  GadgetHandle%,  x%,  y%,  w%,  h%  )

Modifies the position and size of a gadget.

GadgetHandle%
Handle of a GUI gadget.

x%, y%, w%, h%
Position and size of the gadget. For some gadgets, the width or height is determined automatically, according to the size of the current skin graphics.

state% =  GUI_GadgetEnabled% (  GadgetHandle%  )

Returns TRUE if a gadget is currently enabled or FALSE if a gadget is disabled.

GadgetHandle%
Handle of a GUI gadget.

GUI_EnableGadget (  GadgetHandle%|WindowHandle%,  state%,  [showCursor%]  )

Enables or disables a gadget at any time.

GadgetHandle% | WindowHandle%
Handle of a GUI gadget or a GUI window. If a window handle is passed, this command will disable ALL gadgets inside the specified window at once.

state%

GUI_ShowGadget (  GadgetHandle%,  state%  )

Show or hide a gadget.

GadgetHandle%
Handle of a GUI gadget.

state%

state% =  GUI_GadgetVisible% (  GadgetHandle%  )

Returns TRUE if a gadget is visible or FALSE if a gadget has been set to "hidden".

GadgetHandle%
Handle of a GUI gadget.

Textfield% =  GUI_GetActiveTextfield% (  )

Returns the handle of the currently focussed text field (if there is any) or FALSE, if there is currently no text field focussed.

state% =  GUI_MouseOverWindow% (  [WindowHandle%]  )

Returns True if the mouse is hovering over any window or False if the mouse does not touch any GUI window. This function is useful if you want to create an editor, for example, and need to check whether the mouse is currently over or outside any window. You can optionally specify a window handle to check this certain window only. If no window handle parameter is specified, all windows will be checked.

WindowHandle%
Optional. Handle of a Sprite Candy window created with GUI_CreateWindow( ).

state% =  GUI_GadgetExists% (  [GadgetHandle%]  )

Returns True if the specified gadget exists or False if this gadget does not exist.

state% =  GUI_WindowExists% (  [WindowHandle%]  )

Returns True if the specified window exists or False if this window does not exist.

GUI_Confirm% (  windowTitle$,  text$,  buttonText1$,  buttonText2$,  [height%],  [icon%]  )

Creates a two-button confirmation dialogs window. You can specifiy the title caption, text, and the button captions. This is a modal window. All other windows are blocked until the user presses one of the two buttons (f.e. "Yes" and "No" or "Okay" and "Cancel").

windowTitle$
Window title text.

text$
Text that will be displayed inside the window.

buttonText1$, buttonText2$
Captions of the two buttons. For example "Yes" and "No", or "Okay" and "Cancel".

height%
Optional. Height of the confirmation window. Default is 100 pixels.

icon%
Optional (Default: 0). Determines the window title bar icon. Remember the loaded icon strip containing different icon images placed in one row. '0' will use the first (leftmost) icon, '1' will use the second and so on. You can use '-1' to show no icon at all.

clickedButtonText$ =  GUI_Confirmed% (  windowTitle$  )

This commands cecks if the specified confirmation window has been answered. If so, it will return the clicked button's text caption. If the specified dialog window is still unanswered, an empty string is returned.

windowTitle$
The window title text that has been used to create the confirmation window that should be checked. If this confirmation windows has been answered, this command returns a string with the clicked button's text caption (f.e. "Yes" or "No").

GUI_Notify% (  windowTitle$,  text$,  buttonText$,  [height%],  [icon%]  )

Creates a one-button message box window. You can specifiy the title caption, text, and the button caption. This is a modal window. All other windows are blocked until the user presses the window's button (f.e. "Okay").

windowTitle$
Window title text.

text$
Text that will be displayed inside the window.

buttonText$
Button caption. For example "Yes" or "Okay".

height%
Optional. Height of the message window. Default is 100 pixels.

icon%
Optional (Default: 0). Determines the window title bar icon. Remember the loaded icon strip containing different icon images placed in one row. '0' will use the first (leftmost) icon, '1' will use the second and so on. You can use '-1' to show no icon at all.

GUI_Remove (  )

Removes the complete GUI and releases the loaded skin textures. You will have to initialize a new GUI (GUI_Create) before creating any new windows.

GUI_RemoveWindow (  WindowHandle%  )

Removes (deletes) a window including all its gadgets.

WindowHandle%
Handle of a Sprite Candy window created with GUI_CreateWindow( ).

GUI_Clear (  )

Removes (deletes) ALL existing windows and gadgets. The GUI itself will not be removed, so you can still add new windows.

GUI_RemoveGadget (  GadgetHandle%  )

Removes (deletes) a specified gadget.

GadgetHandle%
Handle of a GUI gadget.

GUI_ClearWindow (  WindowHandle%  )

Removes (deletes) all gadgets of the specified window. The window itself will not be removed.

WindowHandle%
Handle of a window created with GUI_CreateWindow.