JSDoc: Class: VisibilityState

new VisibilityState(element, calculateScrolledopt, nullable, calculateDistanceopt, nullable, autoHandleTooLargeElementsopt, nullable)

Creates a new VisibilityState object.

Parameters:

Name	Type	Attributes	Default	Description
`element`	HTMLElement			the element being described by this state
`calculateScrolled`	Boolean	<optional> <nullable>	false	defines if the state should have scroll information, not available by default due to performance impact (such as scrolledPercent); scrolled information covers the question of how far the element has been scrolled through the viewport starting with the first pixel entering and ending with the last pixel leaving
`calculateDistance`	Boolean	<optional> <nullable>	false	defines if the state should have distance information, not available by default due to performance impact (such as distanceViewports); distance information covers the question of how far away an element currently is from the viewport
`autoHandleTooLargeElements`	Boolean	<optional> <nullable>	true	defines if element, which are larger/higher than the viewport, should be automatically handled, by adding additional means to update values without an interception taking place, because no edge is inside the viewport; this has a performance impact, but beware that setting this to false, will stop updates if no edge is inside the viewport

Source:

viewport.js, line 285

Methods

distancePixels(valueopt, nullable) → {Number}

Gets/sets information about the pixel distance of the element from the viewport, describing how long we still need to scroll, until the first pixel hits the viewport bounds. This value may also be negative, if so, it indicates distance from the top.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Number	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 518

Fires:

event:CustomEvent"distancepixels.visibilitystate" - {detail : pixelNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the amount of pixels to scroll until the element hits the viewport bounds

Type: Number

Example

state.distancePixels()
=> -document height ... document height
state.distancePixels(66)
=> 66

distanceViewports(valueopt, nullable) → {Number}

Gets/sets information about the distance of the element from the viewport, measured in viewport heights as a floating point number, describing how long we still need to scroll, until the first pixel hits the viewport bounds. This value may also be negative, if so, it indicates distance from the top.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Number	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 549

Fires:

event:CustomEvent"distanceviewports.visibilitystate" - {detail : viewportNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the amount of viewports to scroll until the element hits the viewport bounds

Type: Number

Example

state.distanceViewports()
=> -document height in viewports ... document height in viewports
state.distanceViewports(6.6)
=> 6.6

fullyInViewport(valueopt, nullable) → {Boolean}

Gets/sets information about the element currently being fully in the viewport or not.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Boolean	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 339

Fires:

event:CustomEvent"fullyenteredviewport.visibilitystate"
event:CustomEvent"fullyleftviewport.visibilitystate"
event:CustomEvent"changed.visibilitystate"

Returns:

true if element is currently in the viewport completely

Type: Boolean

Example

state.fullyInViewport()
=> true/false
state.fullyInViewport(true)
=> true

inViewport(valueopt, nullable) → {Boolean}

Gets/sets information about the element currently being in the viewport or not.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Boolean	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 309

Fires:

event:CustomEvent"enteredviewport.visibilitystate"
event:CustomEvent"leftviewport.visibilitystate"
event:CustomEvent"changed.visibilitystate"

Returns:

true if element is currently in the viewport by any degree

Type: Boolean

Example

state.inViewport()
=> true/false
state.inViewport(true)
=> true

lowerBoundInViewport(valueopt, nullable) → {Boolean}

Gets/sets information about the element's lower bound currently being in the viewport or not.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Boolean	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 399

Fires:

event:CustomEvent"lowerboundenteredviewport.visibilitystate"
event:CustomEvent"lowerboundleftviewport.visibilitystate"
event:CustomEvent"changed.visibilitystate"

Returns:

true if element's lower bound is currently in the viewport

Type: Boolean

Example

state.lowerBoundInViewport()
=> true/false
state.lowerBoundInViewport(true)
=> true

scrolledPercent(valueopt, nullable) → {Number}

Gets/sets information about the percentage the element has already been scrolled through the entirety of the viewport, starting with the first pixel entering from below and ending with the last pixel leaving at the top.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Number	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 487

Fires:

event:CustomEvent"scrolledpercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the percentage scrolled between 0.00 and 100.00

Type: Number

Example

state.scrolledPercent()
=> 0.00 ... 100.00
state.scrolledPercent(66.6)
=> 66.6

startAutoDistanceUpdates(viewportHashObservable, targetFpsopt) → {VisibilityState}

Starts the measurement of pixel and viewport distance for an element, which cannot be measured by just evaluating interceptions (since we do not have any, if element is not intersecting a viewport edge, while off-screen).

This is a feature, that should specifically be activated, since it is a CPU-intensive operation and should only be used for elements, that really need this information.

The range during which this updates should take place is: as long as the element is completely outside of the viewport.

Parameters:

Name	Type	Attributes	Default	Description
`viewportHashObservable`	Basic.Observable			observable, which changes on any change to the viewport, indicating that a new calculation is necessary
`targetFps`	Number	<optional>	VISIBILITY_BASE_FPS	the target amount of frames per second we are aiming for with these updates

Source:

viewport.js, line 658

See:

Basic.Observable

Fires:

event:CustomEvent"distancepixels.visibilitystate" - {detail : pixelNumber}
event:CustomEvent"distancepercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the current state

Type: VisibilityState

Example

state.startAutoDistanceUpdates(new Observable('hash'), 30);

startAutoScrolledPercentUpdates(viewportHashObservable, targetFpsopt, precisionUpdateopt) → {VisibilityState}

Starts the measurement of scrolledPercent for an element, which cannot be measured by just evaluating interceptions (since we do not have any, if element is not intersecting a viewport edge).

This is a feature, that should specifically be activated, since it is a CPU-intensive operation and should only be used for elements, that really need this information.

The range during which this updates should take place is: as long as the element is fully inside the viewport.

Parameters:

Name	Type	Attributes	Default	Description
`viewportHashObservable`	Basic.Observable			observable, which changes on any change to the viewport, indicating that a new calculation is necessary
`targetFps`	Number	<optional>	VISIBILITY_BASE_FPS	the target amount of frames per second we are aiming for with these updates
`precisionUpdate`	Boolean	<optional>	true	since this operation is running a high-precision update to scrolledPercent anyway, we can also update the other properties as well, using the timer precision here, this is especially helpful for effects with positioning, that need razor-sharp in-sync information; set to false to save a few cpu-cycles

Source:

viewport.js, line 590

See:

Basic.Observable

Fires:

event:CustomEvent"scrolledpercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"upperboundenteredviewport.visibilitystate"
event:CustomEvent"upperboundleftviewport.visibilitystate"
event:CustomEvent"lowerboundenteredviewport.visibilitystate"
event:CustomEvent"lowerboundleftviewport.visibilitystate"
event:CustomEvent"visiblepixels.visibilitystate" - {detail : pixelNumber}
event:CustomEvent"visiblepercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the current state

Type: VisibilityState

Example

state.startAutoScrolledPercentUpdates(new Observable('hash'), 30);

startAutoTooLargeUpdates(viewportHashObservable, targetFpsopt) → {VisibilityState}

Starts the measurement of properties for an element larger than the viewport itself, which are not measured, if no intersection is taking place at the moment, because both element bounds are outside the viewport. The is especially necessary, because very large elements also tend to need enormous amounts of thresholds to precisely update values, which, at the end, quickly gets worse, then using a poll in that case. So, using this feature keeps values precise and lets you define a reasonable granularity for all elements, no matter the size.

This is a feature, that should specifically be activated, since it is a CPU-intensive operation and should only be used for elements, that really need this information.

The range during which this updates should take place is: the element is larger than the viewport height and it is currently inside the viewport by any degree.

Parameters:

Name	Type	Attributes	Default	Description
`viewportHashObservable`	Basic.Observable			observable, which changes on any change to the viewport, indicating that a new calculation is necessary
`targetFps`	Number	<optional>	VISIBILITY_BASE_FPS	the target amount of frames per second we are aiming for with these updates

Source:

viewport.js, line 732

See:

Basic.Observable

Fires:

event:CustomEvent"upperboundenteredviewport.visibilitystate"
event:CustomEvent"upperboundleftviewport.visibilitystate"
event:CustomEvent"lowerboundenteredviewport.visibilitystate"
event:CustomEvent"lowerboundleftviewport.visibilitystate"
event:CustomEvent"visiblepixels.visibilitystate" - {detail : pixelNumber}
event:CustomEvent"visiblepercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the current state

Type: VisibilityState

Example

state.startAutoTooLargeUpdates(new Observable('hash'), 30);

stopAutoDistanceUpdates() → {VisibilityState}

Stops the measurement of pixel and viewport distance for an element.

Source:

viewport.js, line 691

Returns:

the current state

Type: VisibilityState

Example

state.stopAutoDistanceUpdates();

stopAutoScrolledPercentUpdates() → {VisibilityState}

Stops the measurement of scrolledPercent for an element.

Source:

viewport.js, line 624

Returns:

the current state

Type: VisibilityState

Example

state.stopAutoScrolledPercentUpdates();

stopAutoTooLargeUpdates() → {VisibilityState}

Stops the measurement of properties for an element larger than the viewport itself, which are not measured, if no intersection is taking place at the moment, because both element bounds are outside the viewport.

Source:

viewport.js, line 755

Returns:

the current state

Type: VisibilityState

Example

state.stopAutoTooLargeUpdates();

toJson() → {Object}

Returns a JSON snapshot of the element's current visibility state.

Source:

viewport.js, line 785

Returns:

with active, inViewport, fullyInViewport, upperBoundInViewport, lowerBoundInViewport, visiblePercent, visiblePixels and (optionally) scrolledPercent, distancePixels and distanceViewports

Type: Object

Example

state.toJson()
=> {
    active : true,
    inViewport : true,
    fullyInViewport : false,
    upperBoundInViewport : true,
    lowerBoundInViewport : false,
    visiblePercent : 10.11,
    visiblePixels : 42
}

upperBoundInViewport(valueopt, nullable) → {Boolean}

Gets/sets information about the element's upper bound currently being in the viewport or not.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Boolean	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 369

Fires:

event:CustomEvent"upperboundenteredviewport.visibilitystate"
event:CustomEvent"upperboundleftviewport.visibilitystate"
event:CustomEvent"changed.visibilitystate"

Returns:

true if element's upper bound is currently in the viewport

Type: Boolean

Example

state.upperBoundInViewport()
=> true/false
state.upperBoundInViewport(true)
=> true

visiblePercent(valueopt, nullable) → {Number}

Gets/sets information about the percentage of the element currently being inside the viewport.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Number	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 428

Fires:

event:CustomEvent"visiblepercent.visibilitystate" - {detail : percentNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the visible percentage between 0.00 and 100.00

Type: Number

Example

state.visiblePercent()
=> 0.00 ... 100.00
state.visiblePercent(66.6)
=> 66.6

visiblePixels(valueopt, nullable) → {Number}

Gets/sets information about the number of vertical pixels of the element currently being inside the viewport.

Parameters:

Name	Type	Attributes	Default	Description
`value`	Number	<optional> <nullable>	null	the value to set, if left out or nullish, the method will just return the current value

Source:

viewport.js, line 457

Fires:

event:CustomEvent"visiblepixels.visibilitystate" - {detail : pixelNumber}
event:CustomEvent"changed.visibilitystate"

Returns:

the visible pixels between 0 and element height

Type: Number

Example

state.visiblePixels()
=> 0 ... element height
state.visiblePixels(66)
=> 66