Murl Engine Lua Addon API  Version 1.0 beta
Murl.Logic.IScrollProcessor

The IScrollProcessor interface.

The ScrollProcessor is used for tracking the inputs of a Graph::IButton node and/or any input provided by the user's logic code.
The ScrollProcessor is used for scroll areas and swipe gestures:

  • Tracking the relative movement of the input.
  • Performing a deceleration when the input is released.
  • Performing an acceleration when the input is repeated.

Additional a position tracking can be used for:

  • Tracking an absolute position.
  • Specifying minimum and maximum bounds.
  • Damping on the bounds.
  • Position animation.
    The ScrollProcessor operates in units of 1, which means the button size is 1 in x and y direction independent of the button's scalefactor.

All values used by the ScrollProcessor simply operates in units of 1. Scaling the results to adequate values applies to the user's logic code.

The ScrollProcessor implements an IProcessor which is typically attached as a child of an user defined logic processor.


Table members

Methods


GetProcessor()

Get the processor interface from a IScrollProcessor object. The ScrollProcessor implements an IProcessor which is typically attached as a child of an user defined logic processor.

Murl.SharedPointer.LogicIProcessor GetProcessor()

Returns
Murl.SharedPointer.LogicIProcessor The processor interface shared pointer.

SetButtonId(buttonId)

Set the path and identifier of the button node to track. The button node can be set alternatively by using SetButtonNode().

SetButtonId(String buttonId)

Parameters
buttonIdThe full path and identifier to a button node.

GetButtonId()

Get the identifier of the button node to track. The identifier contains the path and identifier set by SetButtonId(). If the button node is specified by SetButtonNode() the identifier contains the node identifer only without path.

String GetButtonId()

Returns
String The identifier of the button node.

SetButtonNode(buttonNode)

Set the button node to track. The button node can be set alternatively by using SetButtonId().

Boolean SetButtonNode(Murl.Graph.INode buttonNode)

Parameters
buttonNodeThe button node object.
Returns
Boolean true if successful, false if the node is invalid.

GetButtonNode()

Get the button node to track. If the button node is specified by SetButtonId() the node is valid after Init() or at least one tick has been processed. If using SetButtonNode() the button node is available immediately.

Murl.Graph.IButton GetButtonNode()

Returns
Murl.Graph.IButton The button node object.

SetButtonEnabled(isEnabled)

Set enable or disable the button.

Boolean SetButtonEnabled(Boolean isEnabled)

Parameters
isEnabledtrue for enable, false for disable.
Returns
Boolean true if successful.

IsButtonEnabled()

Check if the button is enabled.

Boolean IsButtonEnabled()

Returns
Boolean true if the button is enabled.

SetDeadZode(distances)

Set the dead zone distances. The dead zone distance specifies the minimum length of the input movement on the corresponding axis. This is useful to filter "short" movements when tapping on the button, use WasButtonReleasedInsideDeadZone(). The dead zone state is available by IsOutsideDeadZone() which is set to true if the input movement exceeds any of the dead zone minimum distances. If the minimum distance is <= 0.0 the corresponding axis is ignored. The deceleration/acceleration is applied only if the input movement is outside the dead zone.
The default value is Vector(0.01, 0.01, 0.01, 0.0) in units.

SetDeadZode(Murl.Math.Vector distances)

Parameters
distancesThe minimum input move distances in units.

GetDeadZone()

Get the minimum dead zone distances.

Murl.Math.Vector GetDeadZone()

Returns
Murl.Math.Vector The minimum dead zone distances in units.

SetAccelerationFactor(accelerationFactor)

Set the acceleration factor. If an input is repeated within the acceleration timeout, the recent velocity of the previous input is multiplied by the acceleration factor and added to the current velocity.
The default value is 16.0.

SetAccelerationFactor(Number accelerationFactor)

Parameters
accelerationFactorThe acceleration factor.

GetAccelerationFactor()

Get the acceleration factor.

Number GetAccelerationFactor()

Returns
Number The acceleration factor.

SetAccelerationTimeout(timeout)

Set the acceleration timeout. The acceleration is applied only if an input is repeated within the acceleration timeout.
The default value is 0.5 seconds.

SetAccelerationTimeout(Number timeout)

Parameters
timeoutThe acceleration timeout in seconds.

GetAccelerationTimeout()

Get the acceleration timeout.

Number GetAccelerationTimeout()

Returns
Number The acceleration timeout in seconds.

SetDecelerationFactor(decelerationFactor)

Set the deceleration factor. The deceleration factor is multiplied to the recent movement when the input ends. The deceleration stops if the recent velocity underflows the stop velocity value.
The default value is 0.01.

Boolean SetDecelerationFactor(Number decelerationFactor)

Parameters
decelerationFactorThe deceleration factor per second must be < 1.
Returns
Boolean true if successful, false if decelerationFactor is >= 1.

GetDecelerationFactor()

Get the deceleration factor.

Number GetDecelerationFactor()

Returns
Number The deceleration factor per second.

SetDecelerationTimeout(timeout)

Set the deceleration timeout. Inhibit deceleration if the time between the last and the recent movement exceeds the deceleration timeout.
The default value is 0.1 seconds.

SetDecelerationTimeout(Number timeout)

Parameters
timeoutThe deceleration timeout in seconds.

GetDecelerationTimeout()

Get the deceleration timeout.

Number GetDecelerationTimeout()

Returns
Number The deceleration timeout in seconds.

SetStopVelocity(stopVelocity)

Set the deceleration stop velocity. The deceleration stops if the recent velocity underflows the stop velocity value.
The default value is 0.01 units/second.

SetStopVelocity(Number stopVelocity)

Parameters
stopVelocityThe deceleration stop velocity value.

GetStopVelocity()

Get the deceleration stop velocity.

Number GetStopVelocity()

Returns
Number The deceleration stop velocity in units/seconds.

SetMaxVelocity(maxVelocity)

Set the maximum velocity. The maximum velocity is the highest allowed velocity, which means the current velocity is clamped to the maximum velocity. The velocity is not clamped if the maximum velocity is 0.
The default value is 32.0 units/second.

SetMaxVelocity(Number maxVelocity)

Parameters
maxVelocityThe the maximum velocity in units/second.

GetMaxVelocity()

Get the maximum velocity.

Number GetMaxVelocity()

Returns
Number The maximum velocity in units/second.

IsActive()

Check if the ScrollProcessor is active. The ScrollProcessor is active if the graph button is pressed or the accleration/deceleration is active or the move animation is running.

Boolean IsActive()

Returns
Boolean true if the ScrollProcessor is active.

IsOutsideDeadZone()

Check if the current movement is outside the dead zone. This state reports also true if the deceleration is stopped by a tap, even if the tap's input is probably inside the dead zone. See also SetDeadZode().

Boolean IsOutsideDeadZone()

Returns
Boolean true if the current movement is outside the dead zone.

IsButtonPressed()

Check if the graph button is tracked and pressed.

Boolean IsButtonPressed()

Returns
Boolean true if the graph button is pressed.

WasButtonReleased()

Check if the graph button was released.

Boolean WasButtonReleased()

Returns
Boolean true if the graph button was released.

WasButtonReleasedInsideDeadZone()

Check if the graph button was released inside the dead zone.

Boolean WasButtonReleasedInsideDeadZone()

Returns
Boolean true if the graph button was released inside the dead zone.

GetMovement()

Get the recent movement. The movement is set by the button input or the acceleration/deceleration or the move animation.

Murl.Math.Vector GetMovement()

Returns
Murl.Math.Vector The movement vector in units of the recent tick.

BeginMovement(state)

Begin setting the next movement. This method can be called optionally before applying custom movements using SetMovement(). This enables the deceleration/acceleration behaviour. The movement can be set only if the button is not pressed.

Boolean BeginMovement(Murl.Logic.IState state)

Parameters
stateThe IState object.
Returns
Boolean true if successful, false if the button is pressed.

EndMovement(state)

End setting the next movement. This method can be called optionally after applying custom movements using SetMovement(). This applies the deceleration/acceleration behaviour. The movement can be set only if the button is not pressed.

Boolean EndMovement(Murl.Logic.IState state)

Parameters
stateThe IState object.
Returns
Boolean true if successful, false if the button is pressed.

SetMovement(delta)

Set the next movement. Setting the movement sets the IsActive() state to true in the next tick. The movement can be set only if the button is not pressed. If the button is pressed during the next tick, the next movement is ignored. See also BeginMovement() and EndMovement().

Boolean SetMovement(Murl.Math.Vector delta)

Parameters
deltaThe movement vector in units for the next tick.
Returns
Boolean true if successful, false if the button is pressed.

ResetMovement()

Reset the current movement including all current states.

ResetMovement()


SetPositionEnabled(isEnabled)

Set enable or disable the position tracking. The position tracking can be disabled for implementing endless scrolling by using the relative movement methods only, typically GetMovement().
The default value is true.

SetPositionEnabled(Boolean isEnabled)

Parameters
isEnabledtrue for enable, false for disable.

IsPositionEnabled()

Check if the position tracking is enabled.

Boolean IsPositionEnabled()

Returns
Boolean true if the position tracking is enabled.

SetMinPosition(position)

Set the minimum position. The default value is Vector(0.0, 0.0, 0.0, 1.0).

SetMinPosition(Murl.Math.Vector position)

Parameters
positionThe minimum position in units.

GetMinPosition()

Get the minimum position.

Murl.Math.Vector GetMinPosition()

Returns
Murl.Math.Vector The minimum position in units.

SetMaxPosition(position)

Set the maximum position. The default value is Vector(1.0, 1.0, 1.0, 1.0).

SetMaxPosition(Murl.Math.Vector position)

Parameters
positionThe maximum position in units.

GetMaxPosition()

Get the maximum position.

Murl.Math.Vector GetMaxPosition()

Returns
Murl.Math.Vector The maximum position in units.

SetMinDampDistance(distance)

Set the damping distance for the minimum position. The damping distance specifies an extra minimum to converge to. The position range is (minimum position - minimum damping distance, minimum position].
The default value is Vector(0.5, 0.5, 0.5, 0.0).

SetMinDampDistance(Murl.Math.Vector distance)

Parameters
distanceThe damping distance for the minimum position in units.

GetMinDampDistance()

Get the damping distance for the minimum position.

Murl.Math.Vector GetMinDampDistance()

Returns
Murl.Math.Vector The damping distance for the minimum position in units.

SetMaxDampDistance(distance)

Set the damping distance for the maximum position. The damping distance specifies an extra maximum to converge to. The position range is [maximum position, maximum position + maximum damping distance).
The default value is Vector(0.5, 0.5, 0.5, 0.0).

SetMaxDampDistance(Murl.Math.Vector distance)

Parameters
distanceThe damping distance for the maximum position in units.

GetMaxDampDistance()

Get the damping distance for the maximum position.

Murl.Math.Vector GetMaxDampDistance()

Returns
Murl.Math.Vector The damping distance for the maximum position in units.

SetDampFactor(dampFactor)

Set the damping factor. The higher the factor, the stronger is the damping (1 + 1 / (-x / f - 1)).
The default value is 1.0.

SetDampFactor(Number dampFactor)

Parameters
dampFactorThe damping factor should be >= 1.0.

GetDampFactor()

Get the damping factor.

Number GetDampFactor()

Returns
Number The damping factor.

SetBounceTime(bounceTime)

Set the bounce time. The bounce time is the duration to move back from the damping area to the minimum / maximum position.

SetBounceTime(Number bounceTime)

Parameters
bounceTimeThe bounce time in seconds.

GetBounceTime()

Get the bounce time.

Number GetBounceTime()

Returns
Number The bounce time in seconds.

SetBounceInterpolation(interpolation)

Set the bounce interpolation. The bounce interpolation is applied when moving back from the damping area to the minimum / maximum position.

SetBounceInterpolation(Murl.IEnums.Interpolation interpolation)

Parameters
interpolationThe bounce interpolation.

GetBounceInterpolation()

Get the bounce interpolation.

Murl.IEnums.Interpolation GetBounceInterpolation()

Returns
Murl.IEnums.Interpolation The bounce interpolation.

GetPosition()

Get the current position.

Murl.Math.Vector GetPosition()

Returns
Murl.Math.Vector The current position in units.

SetPosition(position)

Set the current position. If setting the position simply set the "real" position from input, this method calculates immediately the resulting damped position if necessary, use GetPosition() to get the resulting position.

SetPosition(Murl.Math.Vector position)

Parameters
positionThe current position in units.

MoveToPosition(duration, position, interpolation)

Start a position animation. The position animation starts at the current position and and can be triggered only if the ScrollProcessor is not active.

Boolean MoveToPosition(Number duration, Murl.Math.Vector position, Murl.IEnums.Interpolation interpolation)

Parameters
durationThe animation duration in seconds.
positionThe destination position in units.
interpolationThe interpolation type.
Returns
Boolean true if the animation was started successfully, false if the ScrollProcessor is already active.

IsMoveToPositionRunning()

Check if the position animation is running.

Boolean IsMoveToPositionRunning()

Returns
Boolean true if running.

WasMoveToPositionRunning()

Check if the position animation has stopped running. If the animation is stopped, this state is true within the current logic tick only and will be cleared at the next logic tick.

Boolean WasMoveToPositionRunning()

Returns
Boolean true if stopped.