controllerMove

Description

Performs a linear-movement animation, moving the element from its current position to a supplied target position in 3D space. The last performed movement is remembered and at any time during or after it you can order performing it backwards or repeating it.

Applies one translate transform. The taget position can be relative to the element's current position or absolute to its initial position or to the document, parent or viewport. If parameter is_path is set (to true), then no translation is applied but its coordinates are kept for other controllers that read a 'path' from this controller.

Parameters

Visit page Controller # Common Parameters for documentation on the parameters, common to all controllers: id, paused and disabled.

Coordinate/Size Parameters: Note that all parameters representing screen coordinates or sizes also accept relative values as percentages of own/parent/viewport/document size or coordinates relative to own/parent/viewport/document's origin. For more information, visit page Controller # Coordinate Parameters.

Parameters of move():

duration

Duration of the animation in milliseconds. Default value: 1000

dx, dy, dz

The movement's end position, in coordinates relative to the current position. Skip any of these (or supply values 0) if you don't want movement in these dimensions. Default values: 0, 0, 0

x, y, z

The movement's end position, supplied in absolute coordinates (relative to element's initial position). Skip any of these (or supply values "same") if you don't want movement in these dimensions. If both an absolute and a relative coordinate is supplied for any of the 3 axis, then the relative one is used. Default values: "same", "same", "same"

init_x, init_y, init_z

Set initial position (displacement) in coordinates relative to element's layout position. Note that the displacement will be applied immediately (when the controller is enabled), not waiting for the movement to be started with any of the start messages. Default values: 0, 0, 0

is_path

If true, then the controller will not apply the translation tranform, but will keep the coordinates, so that other controllers can use them as a 'path'. Default value: false

anti_perspective

Neutralizes perspective, by "skewing" the Z axis (from every point in 3D space) towards the camera (so it's not perpendicular to the layout surface). This way, moving the element in the Z axis (positive values) will not make it disappear off-screen. Values between 0 and 1 are usually used, denoting the strength of the effect, where value of 1 will make the Z axis point exactly towards the camera.
This parameter can be used to center the element on the screen. For example, move(dz: 50%Z, anti_perspective: 2, start) will move the element right in the middle of the screen, centered, at half the distance to the camera. Default value: 0

repeat_start_pos

If true, then every start or start_back message will start a forward/reverse movement from the direction's starting position. If false (by default), then sending these messages when a movement is already started will continue the current movement (if already moving in the same direction), or will start a movement in the opposite direction, but continuing from the current position. This parameter has no effect on the start_new or start_new_back messages, as they start a new movement from the current position in all cases. Default value: false

register_actions

Tells whether to handle the element's show, hide, show_immediately and hide_immediately actions.
Values: false / true / "500" (i.e. react with 500 milliseconds delay) / "500 elm" (i.e. set event handlers with delay 500ms for HTML element #elm's actions). Default value: false

half_step

If set to less than 1, each frame the current position will step closer to the required position, where step = half_step * distance_to_required_position. This lag can be used to smooth changes in movement direction.
Values in the range (0 - 1) make sense. Default value: 1

spring_acc

If bigger than 0, the position will behave as if attached to a spring. Bigger values result in stronger pulling of the "spring" and faster movement (i.e. shorter spring period). Note that setting too high of a value will cause a self-amplifying spring movement. What is the highest value before the positive feedback kicks in depends on the value of spring_vdamp, but values up to 2 are always safe. Default value: 0

spring_vdamp

When spring motion is enabled via parameter spring_acc, every frame the current speed of the spring is multiplied by this parameter, effectively slowing the movement. Values between 0 and 1 are reasonable, where smaller values result in faster dying of the movement and a value of 1 means absolute elasticity of the spring. Default value: 0.92

ease_type

What kind of 'easing' to be applied on the movement.
Currently supported values:

• "linear" - constant speed in all movement parts,
• "ease" - slower start and end of movement, elliptical shape,
• "ease_in" - slower start, fast and sudden end,
• "ease_out" - fast and sudden start, slow end.

Default value: "ease"

ease_amount

Strength of 'easing' to be applied on the movement.
Values in the range (0 - 1] make sense, though values greater than 1 (up to 2-3) can also be of use. Default value: 1

ease_mirror

Tells if the easing applied on 'backwards' movement is the same as the forward easing, or mirrored. If this parameter is set to true and parameter ease_type is "ease_in", then upon a backwards movement, "ease_out" easing will be applied. Default value: false

Accepted Messages

Visit page Controller # Common Messages for documentation on the messages, accepted by all controllers: pause, unpause, enable, disable, params and remove.

Message Parameters: Note that along the message parameters specific to each message type, every message (not only params) accepts as parameters any of the controller parameters, which are set before the message is executed.

Messages accepted by move():

start

Starts a movement from the current position to the target position. The message has no effect if already in the target position or moving towards it. If currently moving in the 'backwards' direction (from the target to the starting position, ordered with messages start_back and start_new_back), then the movement direction will be switched to 'forwards' and the 'forward' movement will continue from the current position to the target position. Message params: none

start_back

Starts a 'backwards' movement from the current position to the starting position of the current forward movement. The message has no effect if already in the starting position or moving towards it. Message params: none

start_reverse

Start moving in the reverse direction within the current (or last) movement. Message params: none

start_new

Same as the start message, but does not continue a current movement. It always starts a new movement from the current position to the supplied target position. Message params: none

start_new_back

Start the 'backwards' motion (i.e. starting from the end position) of a new movement. So, calling controller.message('start_new_back', {dx: 20}) will cause the element to jump 20 pixels to the left and then start moving backwards to the current position. Message params: none

pos0

Position the element in the starting position of the current movement immediately. Message params: none

pos1

Position the element in the target position of the current movement immediately. Message params: none

Generated Events

Visit page Controller # Common Events for documentation on the events, generated by all controllers: frame, remove, paused, unpaused enabled and disabled.

Events fired by move():

start

Fired upon starting a (forward) movement, as long as not already on the target position. Event params: none

half

Fired upon reaching the middle of the current (forward) movement. Event params: none

end

Fired upon reaching the end of the current (forward) movement. Event params: none

start_back

Fired upon start of backwards movement. Event params: none

half_back

Fired upon reaching the middle of the current backwards movement. Event params: none

end_back

Fired upon reaching the end of the current backwards movement. Event params: none

pos0

Fired upon reaching the starting position when moving backwards, i.e. it is fired when end_back is fired. Event params: none

pos1

Fired upon reaching the target position when moving forward, i.e. it is fired when end is fired. Event params: none

Interaction with DOM

• Transforms: Applies one translate transform.
• CSS: Works with any styling. Does not set any style properties.
• Events: Does not set event listeners.

Changes Log

1. Controller introduced in v.0.80
2. Param anti_perspective added in v.0.81.

Examples

See Also