controllerProperty
property(name, val, dval, init_val, is_v_coo, suffix,
duration, precision, read_on_start,
repeat_start_pos, register_actions,
ease_type, ease_amount, ease_mirror,
half_step, spring_acc, spring_vdamp)
property.messages = [start, start_back, start_reverse, start_new, start_new_back, pos0, pos1]
property.events = [start, half, end, start_back, half_back, end_back, pos0, pos1]
Description
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec nunc tellus, vehicula a leo eu, porttitor consequat erat. Pellentesque finibus arcu dui, vitae malesuada sem finibus et.
Animates any numerical DOM property (or color in format #RGGBB) of the element or its .style
.
On receiving a message, it performs a transition from the current value of the property to a new value
with settings controlling the easing and behavior (spring force, etc.) of the transition.
The last performed transition is remembered and at any time during or after it you can order performing it backwards or repeat it.
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 property()
:
- name
-
Name of the element's property to animate. For example,
scrollTop
. If you want to animate a property of a property, for example,.style
's.top
property, supply"style.top"
and don't forget to set paramsuffix
to"px"
. Default value: "" - val
-
Transition's absolute target (end) value of the property, or the default value
"same"
for a zero transition (target value is the same as the current value).
When supplying a color, the only currently-supported format is"#RRGGBB"
, which must be accompanied by paramsuffix
set to"#"
. Default value: "same" - dval
-
Transition's target (end) value, relative to the current value. Overrides absolute target value if different than zero.
Relative (to current value) colors are also supported, as"#RRGGBB"
, which must be accompanied by paramsuffix
set to"#"
. Default value: 0 - init_val
-
Initial value of the property, set when the controller is initialized.
The default value of
"same"
means that the property is left as is when the controller is initialized. Default value: "same" - is_v_coo
- A boolean flag telling if this is a horizontal or vertical property. The flag is needed when calculating initial or transition target values supplied as percentiges or relative to document, viewport, etc. Default value: false
- suffix
-
String representing the units of the property, appended to the end of the value when applying it onto the element.
If the property is a color, supply
"#"
as suffix. Default value: "" - precision
- How many digits after the float sign to round to when applying the value. Default value: 0
- read_on_start
- If true, then on each starting message, the controller will read from the HTML element the current value of the property and update its inner current value. This is useful when external scripts (or other controllers) change the property's value before this controller receives a starting message. Default value: false
- duration
- Duration of the animation in milliseconds. Default value: 1000
- repeat_start_pos
-
If
true
, then everystart
orstart_back
message will start a forward/reverse transition from the direction's starting position. Iffalse
(by default), then sending these messages when a transition is already started will continue the current transition (if already moving in the same direction), or will start a transition in the opposite direction, but continuing from the current position. This parameter has no effect on thestart_new
orstart_new_back
messages, as they always start a new transition from the current position. Default value: false - register_actions
-
Tells whether to handle the element's
show
,hide
,show_immediately
andhide_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 value will step closer to the required value, where step =half_step
* distance_to_required_value. Values in the range (0
-1
) make sense. Default value: 1 - spring_acc
-
If bigger than
0
, the property value will behave as if attached to a spring. Bigger values ofspring_acc
result in stronger pulling of the "spring" and faster motion (i.e. shorter spring period). Note that setting too high of a value will cause a self-amplifying spring motion of the property's value. What is the highest value before the positive feedback kicks in depends on the value ofspring_vdamp
, but values up to2
are always safe. Default value: 0 - spring_vdamp
-
When spring transition is enabled via parameter
spring_acc
, every frame the current speed of the spring is multiplied by this parameter, effectively slowing the spring motion. Values between0
and1
are reasonable, where smaller values result in faster dying of the spring motion, and a value of1
means absolute elasticity of the spring. Default value: 0.92 - ease_type
-
What kind of 'easing' to be applied on the transition.
Currently supported values:"linear"
- constant speed in all transition parts,"ease"
- slower start and end of transition, elliptical shape,"ease_in"
- slower start, fast and sudden end,"ease_out"
- fast and sudden start, slow end.
- ease_amount
-
Strength of 'easing' to be applied on the transition.
Values in the range (0
-1
] make sense, though values greater than1
(up to 2-3) can also be of use. Default value: 1 - ease_mirror
-
Tells if the easing applied on 'backwards' transition is the same as the forward easing, or mirrored.
If this parameter is set to
true
and parameterease_type
is"ease_in"
, then upon a backwards transition,"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 property()
:
- start
-
Starts a transition 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
andstart_new_back
), then the transition direction will be switched to 'forwards' and the 'forward' transition will continue from the current position to the target position. Message params: none - start_back
- Starts a 'backwards' transition from the current position to the starting position of the current forward transition. 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) transition. Message params: none
- start_new
-
Same as the
start
message, but does not continue a current transition. It always starts a new transition 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 transition.
So, calling
controller.message('start_new_back', {dval: 20})
will cause the property's value to jump 20 units and then start transiting backwards to the current position. Message params: none - pos0
- Position the element in the starting position of the current transition immediately. Message params: none
- pos1
- Position the element in the target position of the current transition 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 property()
:
- start
- Fired upon starting a (forward) transition, as long as not already on the target position. Event params: none
- half
- Fired upon reaching the middle of the current (forward) transition. Event params: none
- end
- Fired upon reaching the end of the current (forward) transition. Event params: none
- start_back
- Fired upon start of backwards transition. Event params: none
- half_back
- Fired upon reaching the middle of the current backwards transition. Event params: none
- end_back
- Fired upon reaching the end of the current backwards transition. 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: Does not apply any transforms.
- CSS: Works with any styling. Modifies the element's style property supplied by parameter
name
. - Events: Does not set event listeners.
Changes Log
- Controller introduced in v.0.80
- Support for color values in format
#RRGGBB
(+suffix
"#"
) added in v.0.81.