UIButton

Kind: global class
Npmpackage:

UIButton
- new UIButton()
- .togglable : boolean
- .bg : element
- .icon : array
- .state : element
- .onClick()
- .onOver()
- .onOut()
- .toString() ⇒ string
- ._onClick()
- ._onOver()
- ._onOut()

new UIButton()

This is a display object class, extending UIComponent. It is a DOM element that has a child handling system for toggling the active state. By extending UIComponent this has all of its native properties and methods. See UIComponent for more info.
Import from ad-ui

// importing into an ES6 class
import { UIButton } from 'ad-ui'

Note:
When adding a bg element or icons, there is no need to set the width and height at the css level. The UIButton will inherit the dimensions of the children. However, if either the width or height is set, that will be the size of the UIButton. The hit state is the UIButton itself so keep in mind that even if the content is very large, if the css sets the width and height to a smaller amount, there will be a small hit area for clicks, rollovers and rollouts.

Sample 1:

// Create a simple button on the Main container that passes in an image to the bg and 2 images 
// as the icons for the different states of the button.  Notice no width or height is set.
T.myButton = new UIButton({
	id : 'my-btn',
	target : T,
	css : {
		x : 30,
		y : 10
	},
	bg : 'btnBg',
	icon : [ 
		'btnPlay',
		'btnPause'
	],
	onClick : handleMyButtonClick
});
function handleMyButtonClick ( event ){
	console.log( event.target, 'clicked' )
}
// referenced later anywhere outside the class by
View.main.myButton

Sample 2:

// create the same button as above, but more customized images 
// for the bg and the different states
T.myButton = new UIButton({
	id : 'my-btn',
	target : T,
	css : {
		x : 30,
		y : 10
	},
	bg : new UIImage({
		source : 'btnBg',
		css : {
			width : 120,
			height : 40,
		}
	}),
	icon : [ 
		new UIImage({
			source : 'btnPause',
			css : {
				x : 20,
				y : 10,
				width : 80,
				height : 20,
				backgroundColor : 'rgba(0,100,100,.5)'
			}
		}),
		new UIImage({
			source : 'btnPause',
			css : {
				x : 20,
				y : 10,
				width : 80,
				height : 20,
				backgroundColor : 'rgba(0,100,100,.5)'
			}
		}) 
	],
	onClick : handleMyButtonClick
});

Sample 3:

// create a button with a textfield passed in as the icon state of the button
// also it is aligned inline rather than with Align.set()
T.myButton = new UIButton({
	id : 'my-btn',
	target : T,
	css : {
		width : 100,
		height : 40,
		backgroundColor : '#ff0000'
	},
	bg : 'btnBg',
	icon: [
		new UITextField ({
			css : {
				width : 150,
				height : 40,
				color : '#ffffff'
			},
			fontSize : 12,
			fontFamily : 'template_font',
			format : TextFormat.INLINE_FIT,
			alignText : Align.CENTER,
			text : 'CLICK FOR MORE'
		})
	],
	align : {
		x : Align.CENTER,
		y : {
			type : Align.BOTTOM,
			offset : -30
		}
	}
	onClick : handleMyButtonClick
});

Sample Extension:

// When needing to make a custom button, use this template then add code accordingly
function UIButtonExtend( arg ){
	var U = new UIButton ( arg );
	U._onClick = function ( event ){
		// extended click method
	}
function handleBaseEnabled ( event ){
	var listener = U.enabled ? 'addEventListener' : 'removeEventListener' ;
	// handle other listeners
}

U.addEventListener ( UIEvent.ENABLED, handleBaseEnabled )

U.enabled = true;
return U;

}

UIButton.togglable : `boolean`

A Boolean to set whether or not the button will toggle between the different states of the button, which switches the visiblity of the child elements

Kind: static property of UIButton

UIButton.bg : `element`

Getter : The bottom most element of a UIButton. This allows for a background image to be set with a UIImage, or any other UIComponent natively. It is set in the constructor as the bg: param. This allows public access to that element to that element as a getter, without allowing to overwrite the content.

Example 1
Internally create a UIImage as the background:

var myButton = new UIButton({
	bg : 'btnBg'
});

Example 2
Pass in a UIImage to add custom css to the elements:

var myButton = new UIButton({
	bg : new UIImage({
		source : 'btnBg',
		css : {
			width : 80,
			height : 20,
			backgroundColor : 'rgba(0,100,100,.5)'
		}
	})
});

Kind: static property of UIButton

UIButton.icon : `array`

Getter : An Array of the icons, which are set as an array in the constructor as the icon:[] param. This allows public access to those icons as getters, without allowing to overwrite the array content. When clicking the button, it will auto toggle between 0 and 1, however this can be set to any other state that is avaiable. When instantiating, pass in the elements as either strings for the name of images to create UIImages or use other dom elements such as UIComponents to create custom style.

Example 1
Internally creates 2 UIImages as the icons, aka states, of the button:

var myButton = new UIButton({
	icon : [ 
		'btnPlay',
		'btnPause'
	]
})

Example 2
Pass in 2 UIImages as the icons of the button, to add custom css to the elements:

var myButton = new UIButton({
	icon : [ 
		new UIImage({
			source : 'btnPause',
			css : {
				x : 20,
				y : 10,
				width : 80,
				height : 20,
				backgroundColor : 'rgba(0,100,100,.5)'
			}
		}),
		new UIImage({
			source : 'btnPause',
			css : {
				x : 20,
				y : 10,
				width : 80,
				height : 20,
				backgroundColor : 'rgba(0,100,100,.5)'
			}
		}) 
	]
})

Kind: static property of UIButton

UIButton.state : `element`

Getter|Setter : A Number representing the index of which icon is being displayed, aka the state of the button. These are set as an array in the constructor as the icon:[] param. When clicking the button, it will auto toggle between 0 and 1, however this can be set to any other state that is avaiable.

Example
Internally creates 3 UIImages as the icons of the button, which will toggle between 'btnPlay' and 'btnPause', but can manually set to show 'btnAlt' by setting state to 2:

var myButton = new UIButton({
	icon : [
		'btnPlay',
		'btnPause',
		'btnAlt'
	]
})
myButton.state = 2 	// sets the button to 'btnAlt'

Kind: static property of UIButton

UIButton.onClick()

A Method that will be called on click of the button. This is set in the constructor or can be manually assigned. It is a shorthand for calling Gesture.addEventListener( myButton, GestureEvent.CLICK, handleClick );