new ScrollScene(options)
A ScrollScene defines where the controller should react and how.
Parameters:
Name | Type | Argument | Description | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
<optional> |
Options for the Scene. The options can be updated at any time. Properties
|
- Source:
Example
// create a standard scene and add it to a controller new ScrollScene() .addTo(controller); // create a scene with custom options and assign a handler to it. var scene = new ScrollScene({ duration: 100, offset: 200, triggerHook: "onEnter", reverse: false });
Scene Control Methods
-
addTo(controller) → {ScrollScene}
-
Add the scene to a controller.
This is the equivalent toScrollMagic.addScene(scene)
.Parameters:
Name Type Description controller
ScrollMagic The controller to which the scene should be added.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// add a scene to a ScrollMagic controller scene.addTo(controller);
-
destroy(reset) → {null}
-
Destroy the scene and everything.
Parameters:
Name Type Argument Default Description reset
boolean <optional>
false If
true
the pin and tween (if existent) will be reset.- Source:
Returns:
Null to unset handler variables.
{ null }Example
// destroy the scene without resetting the pin and tween to their initial positions scene = scene.destroy(); // destroy the scene and reset the pin and tween scene = scene.destroy(true);
-
progress(progress) → {number}
-
Get or Set the scene's progress.
Usually it shouldn't be necessary to use this as a setter, as it is set automatically by scene.update().
The order in which the events are fired depends on the duration of the scene:- Scenes with
duration == 0
:
Scenes that have no duration by definition have no ending. Thus theend
event will never be fired.
When the trigger position of the scene is passed the events are always fired in this order:enter
,start
,progress
when scrolling forward
andprogress
,start
,leave
when scrolling in reverse - Scenes with
duration > 0
:
Scenes with a set duration have a defined start and end point.
When scrolling past the start position of the scene it will fire these events in this order:enter
,start
,progress
When continuing to scroll and passing the end point it will fire these events:progress
,end
,leave
When reversing through the end point these events are fired:enter
,end
,progress
And when continuing to scroll past the start position in reverse it will fire:progress
,start
,leave
In between start and end theprogress
event will be called constantly, whenever the progress changes.
In short:
enter
events will always trigger before the progress update andleave
envents will trigger after the progress update.start
andend
will always trigger at their respective position.Please review the event descriptions for details on the events and the event object that is passed to the callback.
Parameters:
Name Type Argument Description progress
number <optional>
The new progress value of the scene
[0-1]
.- Source:
Fires:
ScrollScene.event:enter
, when used as setterScrollScene.event:start
, when used as setterScrollScene.event:progress
, when used as setterScrollScene.event:end
, when used as setterScrollScene.event:leave
, when used as setter
Returns:
-
{ number }get
- Current scene progress. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current scene progress var progress = scene.progress(); // set new scene progress scene.progress(0.3);
- Scenes with
-
refresh() → {ScrollScene}
-
Updates dynamic scene variables like the trigger element position or the duration. This method is automatically called in regular intervals from the controller. See
ScrollMagic
optionrefreshInterval
.You can call it to minimize lag, for example when you intentionally change the position of the triggerElement. If you don't it will simply be updated in the next refresh interval of the container, which is usually sufficient.
- Since:
- 1.1.0
- Source:
Fires:
ScrollScene.event:shift
, if the trigger element position or the duration changedScrollScene.event:change
, if the duration changed
Returns:
Parent object for chaining.
{ ScrollScene }Example
scene = new ScrollScene({triggerElement: "#trigger"}); // change the position of the trigger $("#trigger").css("top", 500); // immediately let the scene know of this change scene.refresh();
-
remove() → {ScrollScene}
-
Remove the scene from its parent controller.
This is the equivalent toScrollMagic.removeScene(scene)
. The scene will not be updated anymore until you readd it to a controller. To remove the pin or the tween you need to call removeTween() or removePin() respectively.- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// remove the scene from its parent controller scene.remove();
-
removeClassToggle(reset) → {ScrollScene}
-
Remove the class binding from the scene.
Parameters:
Name Type Argument Default Description reset
boolean <optional>
false If
false
and the classes are currently active, they will remain on the element. Iftrue
they will be removed.- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// remove class binding from the scene without reset scene.removeClassToggle(); // remove class binding and remove the changes it caused scene.removeClassToggle(true);
-
removePin(reset) → {ScrollScene}
-
Remove the pin from the scene.
Parameters:
Name Type Argument Default Description reset
boolean <optional>
false If
false
the spacer will not be removed and the element's position will not be reset.- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// remove the pin from the scene without resetting it (the spacer is not removed) scene.removePin(); // remove the pin from the scene and reset the pin element to its initial position (spacer is removed) scene.removePin(true);
-
removeTween(reset) → {ScrollScene}
-
Remove the tween from the scene.
Parameters:
Name Type Argument Default Description reset
boolean <optional>
false If
true
the tween will be reset to its initial values.- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// remove the tween from the scene without resetting it scene.removeTween(); // remove the tween from the scene and reset it to initial position scene.removeTween(true);
-
setClassToggle(element, classes) → {ScrollScene}
-
Define a css class modification while the scene is active.
When the scene triggers the classes will be added to the supplied element and removed, when the scene is over. If the scene duration is 0 the classes will only be removed if the user scrolls back past the start position.Parameters:
Name Type Description element
string | object A Selector targeting one or more elements, a DOM object or a jQuery object that is supposed to be modified.
classes
string One or more Classnames (separated by space) that should be added to the element during the scene.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// add the class 'myclass' to the element with the id 'my-elem' for the duration of the scene scene.setClassToggle("#my-elem", "myclass"); // add multiple classes to multiple elements defined by the selector '.classChange' scene.setClassToggle(".classChange", "class1 class2 class3");
-
setPin(element, settings) → {ScrollScene}
-
Pin an element for the duration of the tween.
If the scene duration is 0 the element will only be unpinned, if the user scrolls back past the start position.
NOTE: The optionpushFollowers
has no effect, when the scene duration is 0.Parameters:
Name Type Argument Description element
string | object A Selector targeting an element, a DOM object or a jQuery object that is supposed to be pinned.
settings
object <optional>
settings for the pin
Properties
Name Type Argument Default Description pushFollowers
boolean <optional>
true If
true
following elements will be "pushed" down for the duration of the pin, iffalse
the pinned element will just scroll past them.
Ignored, when duration is0
.spacerClass
string <optional>
"scrollmagic-pin-spacer" Classname of the pin spacer element, which is used to replace the element.
pinnedClass
string <optional>
"" Classname that should be added to the pinned element during pin phase (and removed after).
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// pin element and push all following elements down by the amount of the pin duration. scene.setPin("#pin"); // pin element and keeping all following elements in their place. The pinned element will move past them. scene.setPin("#pin", {pushFollowers: false});
-
setTween(TweenMaxObject) → {ScrollScene}
-
Add a tween to the scene.
If you want to add multiple tweens, wrap them into one TimelineMax object and add it.
The duration of the tween is streched to the scroll duration of the scene, unless the scene has a duration of0
.Parameters:
Name Type Description TweenMaxObject
object A TweenMax, TweenLite, TimelineMax or TimelineLite object that should be animated in the scene.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// add a single tween scene.setTween(TweenMax.to("obj"), 1, {x: 100}); // add multiple tweens, wrapped in a timeline. var timeline = new TimelineMax(); var tween1 = TweenMax.from("obj1", 1, {x: 100}); var tween2 = TweenMax.to("obj2", 1, {y: 100}); timeline .add(tween1) .add(tween2); scene.addTween(timeline);
-
update(immediately) → {ScrollScene}
-
Updates the Scene in the parent Controller to reflect the current state.
This is the equivalent toScrollMagic.updateScene(scene, immediately)
.
The update method calculates the scene's start and end position (based on the trigger element, trigger hook, duration and offset) and checks it against the current scroll position of the container.
It then updates the current scene state accordingly (or does nothing, if the state is already correct) – Pins will be set to their correct position and tweens will be updated to their correct progress. This means an update doesn't necessarily result in a progress change. Theprogress
event will be fired if the progress has indeed changed between this update and the last.
NOTE: This method gets called constantly whenever ScrollMagic detects a change. The only application for you is if you change something outside of the realm of ScrollMagic, like moving the trigger or changing tween parameters.Parameters:
Name Type Argument Default Description immediately
boolean <optional>
false If
true
the update will be instant, iffalse
it will wait until next tweenmax tick (better performance).- Source:
Fires:
Returns:
Parent object for chaining.
{ ScrollScene }Example
// update the scene on next tick scene.update(); // update the scene immediately scene.update(true);
Scene Parameters (getter / setter)
-
duration(newDuration) → {number}
-
Get or Set the duration option value. As a setter it also accepts a function returning a numeric value.
This is particularly useful for responsive setups.The duration is updated using the supplied function every time
ScrollScene.refresh()
is called, which happens periodically from the controller (see ScrollMagic optionrefreshInterval
).
NOTE: Be aware that it's an easy way to kill performance, if you supply a function that has high CPU demand.
Even for size and position calculations it is recommended to use a variable to cache the value. (see example)
This counts double if you use the same function for multiple scenes.Parameters:
Name Type Argument Description newDuration
number | function <optional>
The new duration of the scene.
- Source:
Fires:
ScrollScene.event:change
, when used as setterScrollScene.event:shift
, when used as setter
Returns:
-
{ number }get
- Current scene duration. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current duration value var duration = scene.duration(); // set a new duration scene.duration(300); // use a function to automatically adjust the duration to the window height. var durationValueCache; function getDuration () { return durationValueCache; } function updateDuration (e) { durationValueCache = $(window).innerHeight(); } $(window).on("resize", updateDuration); // update the duration when the window size changes $(window).triggerHandler("resize"); // set to initial value scene.duration(getDuration); // supply duration method
-
enabled(newState) → {boolean|ScrollScene}
-
Get or Set the current enabled state of the scene.
This can be used to disable this scene without removing or destroying it.Parameters:
Name Type Argument Description newState
boolean <optional>
The new enabled state of the scene
true
orfalse
.- Source:
Returns:
Example
// get the current value var enabled = scene.enabled(); // disable the scene scene.enabled(false);
-
loglevel(newLoglevel) → {number}
-
Get or Set the loglevel option value.
Parameters:
Name Type Argument Description newLoglevel
number <optional>
The new loglevel setting of the scene.
[0-3]
- Source:
Fires:
ScrollScene.event:change
, when used as setter
Returns:
-
{ number }get
- Current loglevel. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current loglevel var loglevel = scene.loglevel(); // set new loglevel scene.loglevel(3);
-
offset(newOffset) → {number}
-
Get or Set the offset option value.
Parameters:
Name Type Argument Description newOffset
number <optional>
The new offset of the scene.
- Source:
Fires:
ScrollScene.event:change
, when used as setterScrollScene.event:shift
, when used as setter
Returns:
-
{ number }get
- Current scene offset. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current offset var offset = scene.offset(); // set a new offset scene.offset(100);
-
reverse(newReverse) → {boolean}
-
Get or Set the reverse option value.
Parameters:
Name Type Argument Description newReverse
boolean <optional>
The new reverse setting of the scene.
- Source:
Fires:
ScrollScene.event:change
, when used as setter
Returns:
-
{ boolean }get
- Current reverse option value. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current reverse option var reverse = scene.reverse(); // set new reverse option scene.reverse(false);
-
triggerElement(newTriggerElement) → {string|object}
-
Get or Set the triggerElement option value. Does not fire
ScrollScene.shift
, because changing the trigger Element doesn't necessarily mean the start position changes. This will be determined inScrollScene.refresh()
, which is automatically triggered.Parameters:
Name Type Argument Description newTriggerElement
string | object <optional>
The new trigger element for the scene.
- Source:
Fires:
ScrollScene.event:change
, when used as setter
Returns:
-
{ string | object }get
- Current triggerElement. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current triggerElement var triggerElement = scene.triggerElement(); // set a new triggerElement using a selector scene.triggerElement("#trigger"); // set a new triggerElement using a jQuery Object scene.triggerElement($("#trigger")); // set a new triggerElement using a DOM object scene.triggerElement(document.getElementById("trigger"));
-
triggerHook(newTriggerHook) → {number}
-
Get or Set the triggerHook option value.
Parameters:
Name Type Argument Description newTriggerHook
number | string <optional>
The new triggerHook of the scene. See
ScrollScene
parameter description for value options.- Source:
Fires:
ScrollScene.event:change
, when used as setterScrollScene.event:shift
, when used as setter
Returns:
-
{ number }get
- Current triggerHook (ALWAYS numerical). -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current triggerHook value var triggerHook = scene.triggerHook(); // set a new triggerHook using a string scene.triggerHook("onLeave"); // set a new triggerHook using a number scene.triggerHook(0.7);
-
tweenChanges(newTweenChanges) → {boolean}
-
Get or Set the tweenChanges option value.
Parameters:
Name Type Argument Description newTweenChanges
boolean <optional>
The new tweenChanges setting of the scene.
- Source:
Fires:
ScrollScene.event:change
, when used as setter
Returns:
-
{ boolean }get
- Current tweenChanges option value. -
{ ScrollScene }set
- Parent object for chaining.
Example
// get the current tweenChanges option var tweenChanges = scene.tweenChanges(); // set new tweenChanges option scene.tweenChanges(true);
Scene Properties (getter)
-
parent() → {ScrollMagic}
-
Get the parent controller.
- Source:
Returns:
Parent controller or
{ ScrollMagic }undefined
Example
// get the parent controller of a scene var controller = scene.parent();
-
scrollOffset() → {number}
-
Get the current scroll offset for the start of the scene.
Mind, that the scrollOffset is related to the size of the container, iftriggerHook
is bigger than0
(or"onLeave"
).
This means, that resizing the container or changing thetriggerHook
will influence the scene's start offset.- Source:
Returns:
The scroll offset (of the container) at which the scene will trigger. Y value for vertical and X value for horizontal scrolls.
{ number }Example
// get the current scroll offset for the start and end of the scene. var start = scene.scrollOffset(); var end = scene.scrollOffset() + scene.duration(); console.log("the scene starts at", start, "and ends at", end);
-
state() → {string}
-
Get the current state.
- Source:
Returns:
{ string }"BEFORE"
,"DURING"
or"AFTER"
Example
// get the current state var state = scene.state();
-
triggerOffset()
-
Get the trigger offset of the scene (including the value of the
offset
option).- Deprecated:
- Method is deprecated since 1.1.0. You should now use
ScrollScene.triggerPosition
- Method is deprecated since 1.1.0. You should now use
- Source:
-
triggerPosition() → {number}
-
Get the trigger position of the scene (including the value of the
offset
option).- Source:
Returns:
Start position of the scene. Top position value for vertical and left position value for horizontal scrolls.
{ number }Example
// get the scene's trigger position var triggerPosition = scene.triggerPosition();
Event Handling
-
off(name, callback) → {ScrollScene}
-
Remove one or more event listener.
Parameters:
Name Type Argument Description name
string The name or names of the event that should be removed.
callback
function <optional>
A specific callback function that should be removed. If none is passed all callbacks to the event listener will be removed.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
function callback (event) { console.log("Event fired! (" + event.type + ")"); } // add listeners scene.on("change update", callback); // remove listeners scene.off("change update", callback);
-
on(name, callback) → {ScrollScene}
-
Add one ore more event listener.
The callback function will be fired at the respective event, and an object containing relevant data will be passed to the callback.Parameters:
Name Type Description name
string The name or names of the event the callback should be attached to.
callback
function A function that should be executed, when the event is dispatched. An event object will be passed to the callback.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
function callback (event) { console.log("Event fired! (" + event.type + ")"); } // add listeners scene.on("change update progress start end enter leave", callback);
-
trigger(name, vars) → {ScrollScene}
-
Trigger an event.
Parameters:
Name Type Argument Description name
string The name of the event that should be triggered.
vars
object <optional>
An object containing info that should be passed to the callback.
- Source:
Returns:
Parent object for chaining.
{ ScrollScene }Example
this.trigger("change");
Debuging
-
addIndicators(options)
-
Add Indicators for a ScrollScene.
REQUIRES ScrollMagic Debug Extension:jquery.scrollmagic.debug.js
The indicators can only be added AFTER the scene has been added to a controller.Parameters:
Name Type Argument Description options
object <optional>
An object containing one or more options for the indicators.
Properties
Name Type Argument Default Description parent
string | object <optional>
undefined A selector, DOM Object or a jQuery object that the indicators should be added to.
If undefined, the scene's container will be used.zindex
number <optional>
-1 CSS zindex for the indicator container.
indent
number <optional>
0 Additional position offset for the indicators (useful, when having multiple scenes starting at the same time).
suffix
number <optional>
"" This string will be attached to the start and end indicator (useful for identification when working with multiple scenes).
colorTrigger
string <optional>
blue CSS color definition for the trigger indicator.
colorStart
string <optional>
green CSS color definition for the start indicator.
colorEnd
string <optional>
red CSS color definition for the end indicator.
- Source:
Example
// add basic indicators scene.addIndicators() // passing options scene.addIndicators({zindex: 100, colorEnd: "#FFFFFF"});
Events
-
change
-
Scene change event.
Fires whenvever a property of the scene is changed.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
what
string Indicates what value has been changed
newval
mixed The new value of the changed property
Example
scene.on("change", function (event) { console.log("Scene Property \"" + event.what + "\" changed to " + event.newval); });
-
destroy
-
Scene destroy event.
Fires whenvever the scene is destroyed. This can be used to tidy up custom behaviour used in events.- Since:
- 1.1.0
- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
reset
boolean Indicates if the destroy method was called with reset
true
orfalse
.
Example
scene.on("enter", function (event) { // add custom action $("#my-elem").left("200"); }) .on("destroy", function (event) { // reset my element to start position if (event.reset) { $("#my-elem").left("0"); } });
-
end
-
Scene end event.
Fires whenever the scroll position its the ending point of the scene.
It will also fire when scrolling back up from after the scene and going over its end position. If you want something to happen only when scrolling down/right, use the scrollDirection parameter passed to the callback.For details on this event and the order in which it is fired, please review the
ScrollScene.progress
method.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
progress
number Reflects the current progress of the scene
state
string The current state of the scene
"BEFORE"
,"DURING"
or"AFTER"
scrollDirection
string Indicates which way we are scrolling
"PAUSED"
,"FORWARD"
or"REVERSE"
Example
scene.on("end", function (event) { alert("Hit end point of scene."); });
-
enter
-
Scene enter event.
Fires whenever the scene enters the "DURING" state.
Keep in mind that it doesn't matter if the scene plays forward or backward: This event always fires when the scene enters its active scroll timeframe, regardless of the scroll-direction.For details on this event and the order in which it is fired, please review the
ScrollScene.progress
method.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
progress
number Reflects the current progress of the scene
state
string The current state of the scene
"BEFORE"
,"DURING"
or"AFTER"
scrollDirection
string Indicates which way we are scrolling
"PAUSED"
,"FORWARD"
or"REVERSE"
Example
scene.on("enter", function (event) { alert("Entered a scene."); });
-
leave
-
Scene leave event.
Fires whenever the scene's state goes from "DURING" to either "BEFORE" or "AFTER".
Keep in mind that it doesn't matter if the scene plays forward or backward: This event always fires when the scene leaves its active scroll timeframe, regardless of the scroll-direction.For details on this event and the order in which it is fired, please review the
ScrollScene.progress
method.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
progress
number Reflects the current progress of the scene
state
string The current state of the scene
"BEFORE"
,"DURING"
or"AFTER"
scrollDirection
string Indicates which way we are scrolling
"PAUSED"
,"FORWARD"
or"REVERSE"
Example
scene.on("leave", function (event) { alert("Left a scene."); });
-
progress
-
Scene progress event.
Fires whenever the progress of the scene changes.For details on this event and the order in which it is fired, please review the
ScrollScene.progress
method.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
progress
number Reflects the current progress of the scene
state
string The current state of the scene
"BEFORE"
,"DURING"
or"AFTER"
scrollDirection
string Indicates which way we are scrolling
"PAUSED"
,"FORWARD"
or"REVERSE"
Example
scene.on("progress", function (event) { console.log("Scene progress changed."); });
-
shift
-
Scene shift event.
Fires whenvever the start or end scroll offset of the scene change. This happens explicitely, when one of these values change:offset
,duration
ortriggerHook
. It will fire implicitly when thetriggerElement
changes, if the new element has a different position (most cases). It will also fire implicitly when the size of the container changes and the triggerHook is anything other thanonLeave
.- Since:
- 1.1.0
- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
reason
string Indicates why the scene has shifted
Example
scene.on("shift", function (event) { console.log("Scene moved, because the " + event.reason + " has changed.)"); });
-
start
-
Scene start event.
Fires whenever the scroll position its the starting point of the scene.
It will also fire when scrolling back up going over the start position of the scene. If you want something to happen only when scrolling down/right, use the scrollDirection parameter passed to the callback.For details on this event and the order in which it is fired, please review the
ScrollScene.progress
method.- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
progress
number Reflects the current progress of the scene
state
string The current state of the scene
"BEFORE"
,"DURING"
or"AFTER"
scrollDirection
string Indicates which way we are scrolling
"PAUSED"
,"FORWARD"
or"REVERSE"
Example
scene.on("start", function (event) { alert("Hit start point of scene."); });
-
update
-
Scene update event.
Fires whenever the scene is updated (but not necessarily changes the progress).- Source:
Properties:
Name Type Description event
object The event Object passed to each callback
Properties
Name Type Description type
string The name of the event
target
ScrollScene The ScrollScene object that triggered this event
startPos
number The starting position of the scene (in relation to the conainer)
endPos
number The ending position of the scene (in relation to the conainer)
scrollPos
number The current scroll position of the container
Example
scene.on("update", function (event) { console.log("Scene updated."); });