UIIconButton

(Engine-Level Function)

Description: Draws a push-button capable of displaying a supplied image within a window. Returns TRUE when selected.
Returns: Boolean
Usage: Steady State only.
Function Groups: Graphics
Related to: GUIBitmap | GUIButton
Format: \System.UIIconButton(0 { Left }, 20 { Bottom }, 20 { Right }, 0 { Top }, <Icon Display>[, <Hover Display>, <UIState>, <UICallbackInfo>]);
Parameters:  
Left
Required Double. A value that provides the left side reference coordinate.
Bottom
Required Double. A value that provides the bottom side reference coordinate. The top and bottom references are measured down from the top of the screen.
Right
Required Double. A value that provides the right side reference coordinate.
Top
Required Double. A value that provides the top side reference coordinate.
IconDisplay

Required. Image and styling to display in the foreground of the button.

May be a string name referencing an icon within our standard library ("star," for example) or a string file path to a preferred Image file (absolute or relative to the root of your application). Supported image formats include, SVG, BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, and TIF.

Alternatively, an acceptable parm may be an instance of either UIDisplaySet for both content and styling, or UIStateSet to specify content alone.

HoverDisplay

Optional. Image and styling to display in the background of the button. Functionally identical to IconDisplay, except that its image and styling are only revealed upon the mouse pointer hovering over the button.

May be a string name referencing an icon within our standard library or a string file path to a preferred Image file (absolute or relative to the root of your application). Supported image formats include, SVG, BMP, EMF, WMF, APM, CUT, PCX, JPG, PNG, and TIF.

Alternatively, an acceptable parm may be an instance of either UIDisplaySet for both content and styling, or UIStateSet to specify content alone.

State

Optional instance of the UIState struct. Allows fine control over the available component states and how the user may interact with the component.

If not set, a default UIState instance is created internally with the following settings:

UIState Struct
Enabled TRUE
Selected FALSE
Visible TRUE
UpValue 0
CallbackInfo
Optional. May be supplied as a String component ID or an instance of UICallbackInfo, which requires the component context (commonly the page or module it's drawn from) in addition to the component ID. If nothing is provided, no callbacks will be made for a click interaction.
Comments:

Left, Bottom, Right, and Top may be entered as variables or expressions, as long as they evaluate to numeric values. They can be updated dynamically as part of the Steady State component of the function.

Example:

[
	{ Structs declared }
	HoverStyle; 
	ButtonState;
]
						
Init [
	If 1 Main;
	[
	   { Struct instantiated with icon name and UIStyle } 
	   HoverStyle = \UIStateSet(
			  "circle"              { Icon  }, 
			  \UIStyle( "<CD2A2A>") { Color }
			);
		
	   { Struct instantiated describing button behavior }	
	   ButtonState = \UIState(
			   TRUE  { Enabled  }, 
			   FALSE { Selected },
			   TRUE  { Visible  }
			 );
	 ]
]
			
Main [
			
   { Styled icon button }
  \System.UIIconButton(
    40 { Left }, 20 { Bottom }, 60  { Right }, 0 { Top }, 
    "star" { Icon }, HoverStyle { Icon Displayed on Hover },
    ButtonState
   );
]