Packagestarling.utils
Classpublic class ButtonBehavior
InheritanceButtonBehavior Inheritance Object

A utility class that can help with creating button-like display objects.

When reacting to touch input, taps can easily be recognized through standard touch events via TouchPhase.ENDED. However, you often want a more elaborate kind of input handling, like that provide by Starling's Button class and its TRIGGERED 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.

Here is an example: a class that extends TextField and uses ButtonBehavior to add TRIGGER events and state-based coloring.

      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);
          }
      }

Instances of this class will now dispatch Event.TRIGGERED events (just like conventional buttons) and they will change their color when being touched.


Public Properties
 PropertyDefined By
  abortDistance : Number
The distance you can move away your finger before triggering is aborted.
ButtonBehavior
  enabled : Boolean
Indicates if the button can be triggered.
ButtonBehavior
  minHitAreaSize : Number
The target's hit area will be extended to have at least this width / height.
ButtonBehavior
  onStateChange : Function
The callback that is executed whenever the state changes.
ButtonBehavior
  state : String
The current state of the button.
ButtonBehavior
  target : DisplayObject
[read-only] The target on which this behavior operates.
ButtonBehavior
  useHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the button.
ButtonBehavior
Public Methods
 MethodDefined By
  
ButtonBehavior(target:DisplayObject, onStateChange:Function, minHitAreaSize:Number = 44, abortDistance:Number = 50)
Create a new ButtonBehavior.
ButtonBehavior
  
hitTest(localPoint:Point):DisplayObject
Forward your target's hitTests to this method to make sure that the hit area is extended to minHitAreaSize.
ButtonBehavior
Property Detail
abortDistanceproperty
abortDistance:Number

The distance you can move away your finger before triggering is aborted.


Implementation
    public function get abortDistance():Number
    public function set abortDistance(value:Number):void
enabledproperty 
enabled:Boolean

Indicates if the button can be triggered.


Implementation
    public function get enabled():Boolean
    public function set enabled(value:Boolean):void
minHitAreaSizeproperty 
minHitAreaSize:Number

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.


Implementation
    public function get minHitAreaSize():Number
    public function set minHitAreaSize(value:Number):void
onStateChangeproperty 
onStateChange:Function

The callback that is executed whenever the state changes. Format: function(state:String):void


Implementation
    public function get onStateChange():Function
    public function set onStateChange(value:Function):void
stateproperty 
state:String

The current state of the button. The corresponding strings are found in the ButtonState class.


Implementation
    public function get state():String
    public function set state(value:String):void
targetproperty 
target:DisplayObject  [read-only]

The target on which this behavior operates.


Implementation
    public function get target():DisplayObject
useHandCursorproperty 
useHandCursor:Boolean

Indicates if the mouse cursor should transform into a hand while it's over the button.

The default value is true.


Implementation
    public function get useHandCursor():Boolean
    public function set useHandCursor(value:Boolean):void
Constructor Detail
ButtonBehavior()Constructor
public function ButtonBehavior(target:DisplayObject, onStateChange:Function, minHitAreaSize:Number = 44, abortDistance:Number = 50)

Create a new ButtonBehavior.

Parameters
target:DisplayObject — The object on which to listen for touch events.
 
onStateChange:Function — This callback will be executed whenever the button's state ought to change. function(state:String):void
 
minHitAreaSize:Number (default = 44) — If the display area of 'target' is smaller than a square of this size, its hit area will be extended accordingly.
 
abortDistance:Number (default = 50) — The distance you can move away your finger before triggering is aborted.
Method Detail
hitTest()method
public function hitTest(localPoint:Point):DisplayObject

Forward your target's hitTests to this method to make sure that the hit area is extended to minHitAreaSize.

Parameters

localPoint:Point

Returns
DisplayObject




Mon Jul 26 2021, 10:58 AM +02:00