starling-framework/lib/starling/utils/ButtonBehavior.d.ts

A fast, productive library for 2D cross-platform development.

import DisplayObject from "../display/DisplayObject";
import Point from "openfl/geom/Point";
declare namespace starling.utils {
	/**
	 *  A utility class that can help with creating button-like display objects.
	 *  *
	 *  *  <p>When reacting to touch input, taps can easily be recognized through standard touch
	 *  *  events via <code>TouchPhase.ENDED</code>. However, you often want a more elaborate kind of
	 *  *  input handling, like that provide by Starling's <em>Button</em> class and its
	 *  *  <em>TRIGGERED</em> event. It allows users to cancel a tap by moving the finger away from
	 *  *  the object, for example; and it supports changing its appearance depending on its state.</p>
	 *  *
	 *  *  <p>Here is an example: a class that extends <em>TextField</em> and uses
	 *  *  <em>ButtonBehavior</em> to add TRIGGER events and state-based coloring.</p>
	 *  *
	 *  *  <listing>
	 *  *  public class TextButton extends TextField
	 *  *  {
	 *  *      private var _behavior:ButtonBehavior;
	 *  *      private var _tint:uint = 0xffaaff;
	 *  *      
	 *  *      public function TextButton(width:int, height:int, text:String="",
	 *  *                                 format:TextFormat=null, options:TextOptions=null)
	 *  *      {
	 *  *          super(width, height, text, format, options);
	 *  *          _behavior = new ButtonBehavior(this, onStateChange);
	 *  *      }
	 *  *      
	 *  *      private function onStateChange(state:String):void
	 *  *      {
	 *  *          if (state == ButtonState.DOWN) format.color = _tint;
	 *  *          else format.color = 0xffffff;
	 *  *      }
	 *  *      
	 *  *      public override function hitTest(localPoint:Point):DisplayObject
	 *  *      {
	 *  *          return _behavior.hitTest(localPoint);
	 *  *      }
	 *  *  }</listing>
	 *  *
	 *  *  <p>Instances of this class will now dispatch <em>Event.TRIGGERED</em> events (just like
	 *  *  conventional buttons) and they will change their color when being touched.</p>
	 *  
	 */
	export class ButtonBehavior {
		/**
		 *  Create a new ButtonBehavior.
		 * 	 *
		 * 	 * @param target           The object on which to listen for touch events.
		 * 	 * @param onStateChange    This callback will be executed whenever the button's state ought
		 * 	 *                         to change. <code>function(state:String):void</code>
		 * 	 * @param minHitAreaSize   If the display area of 'target' is smaller than a square of this
		 * 	 *                         size, its hit area will be extended accordingly.
		 * 	 * @param abortDistance    The distance you can move away your finger before triggering
		 * 	 *                         is aborted.
		 * 	 
		 */
		constructor(target: DisplayObject, onStateChange: Function, minHitAreaSize?: number, abortDistance?: number);
		/**
		 *  Forward your target's <code>hitTests</code> to this method to make sure that the hit
		 * 	 *  area is extended to <code>minHitAreaSize</code>. 
		 */
		hitTest(localPoint: Point): DisplayObject;
		/**
		 *  The current state of the button. The corresponding strings are found
		 * 	 *  in the ButtonState class. 
		 */
		get state(): string;
		set state(value: string)
		/**
		 *  The target on which this behavior operates. 
		 */
		get target(): DisplayObject;
		get_target(): DisplayObject;
		/**
		 *  The callback that is executed whenever the state changes.
		 * 	 *  Format: <code>function(state:String):void</code>
		 * 	 
		 */
		get onStateChange(): Function;
		set onStateChange(value: Function)
		get_onStateChange(): Function;
		set_onStateChange(value: Function): Function;
		/**
		 *  Indicates if the mouse cursor should transform into a hand while it's over the button.
		 * 	 *  @default true 
		 */
		get useHandCursor(): boolean;
		set useHandCursor(value: boolean)
		get_useHandCursor(): boolean;
		set_useHandCursor(value: boolean): boolean;
		/**
		 *  Indicates if the button can be triggered. 
		 */
		get enabled(): boolean;
		set enabled(value: boolean)
		get_enabled(): boolean;
		set_enabled(value: boolean): boolean;
		/**
		 *  The target's hit area will be extended to have at least this width / height. 
		 * 	 *  Note that for this to work, you need to forward your hit tests to this class. 
		 */
		get minHitAreaSize(): number;
		set minHitAreaSize(value: number)
		get_minHitAreaSize(): number;
		set_minHitAreaSize(value: number): number;
		/**
		 *  The distance you can move away your finger before triggering is aborted. 
		 */
		get abortDistance(): number;
		set abortDistance(value: number)
		get_abortDistance(): number;
		set_abortDistance(value: number): number;
	}
}
export default starling.utils.ButtonBehavior;