MODULES Uize.Widget.Scrolly

SEARCHEXAMPLESVIEW SOURCE CODE

1. Introduction

The Uize.Widget.Scrolly class provides animated scrolling for the contents of a view port, with support for both horizontal and vertical scrolling.

DEVELOPERS: Chris van Rensburg, Jan Borgersen, original code donated by Zazzle Inc.

The Uize.Widget.Scrolly module defines the Uize.Widget.Scrolly widget class, a subclass of Uize.Widget.

1.1. In a Nutshell

The Uize.Widget.Scrolly class is essentially just a scroller for a node.

It supports horizontal scrolling, vertical scrolling, or both horiztonal and vertical scrolling together in the same instance. User interface and programmatic means are provided for controlling the scroll position of an instance.

1.1.1. Scrolling in Pages

Scroll position is expressed in pages, where one horizontal page is defined as the width of the view implied node, and one vertical page is defined as the height of the view implied node.

A scrolly is scrollable horizontally if the value of its scrollWidth style property is greater than the value of its offsetWidth style property. Similarly, a scrolly is scrollable vertically if the value of its scrollHeight style property is greater than the value of its offsetHeight style property.

1.1.2. How Scrolling is Performed

Scrolling is achieved by setting the values of the scrollLeft and scrollTop properties of the view implied node.

1.1.2.1. Animation

Whenever the values of either the pageX or pageY set-get properties are modified, a fade is initiated in order to animate the scroll position of the view implied node from its current position to the new position represented by the new pageX and pageY values.

The scrolly instance creates an instance of the Uize.Fade class in order to drive the scroll position fade. This fade instance is accessible through the fade instance property, so the properties of the scroll fade can be configured by setting values for the various set-get properties of this fade instance, such as its acceleration, deceleration, duration, and other set-get properties.

If the value of the pageX or pageY set-get properties are modified in the middle of a scroll fade - either by Scrolling With Buttons or by Scrolling Programmatically - then the current animation will be stopped and a new animation will be started to fade the scroll position from its current position to the new scroll position.

1.1.3. Scrolling With Buttons

Instances of the Uize.Widget.Scrolly class are equipped with four scroll buttons: left and right buttons for scrolling horizontally, and up and down buttons for scrolling vertically.

Providing markup for the buttons is optional, and one can provide button HTML for only horizontal scrolling, only vertical scrolling, or both horiztonal and vertical scrolling. If one doesn't provide markup for any of the scroll buttons, there is still the option of Scrolling Programmatically.

1.1.3.1. Shift-click

Clicking the buttons scrolls one page at a time (see Scrolling in Pages), but holding down the shift modifier key when clicking on the buttons will scroll all the way to the extremes.

Holding down shift while clicking on the left button will scroll to the far left (first page, horizontally), effectively setting pageX to 0. Holding down shift while clicking on the right button will scroll to the far right (last page, horizontally), effectively setting pageX to the value of maxPageX. Holding down shift while clicking on the up button will scroll to the top (first page, vertically), effectively setting pageY to 0. Holding down shift while clicking on the down button will scroll to the bottom (last page, vertically), effectively setting pageX to the value of maxPageX.

1.1.4. Scrolling Programmatically

In addition to Scrolling With Buttons, it is also possible to programmatically scroll an instance by setting the values of its pageX and pageY set-get properties.

EXAMPLES

// scroll horizontally

scrolly.set ({pageX:scrolly.get ('pageX') - 1});   // scroll one page left
scrolly.set ({pageX:scrolly.get ('pageX') + 1});   // scroll one page right
scrolly.set ({pageX:0});                           // scroll to first page, horizontally
scrolly.set ({pageX:Infinity});                    // scroll to last page, horizontally


// scroll vertically

scrolly.set ({pageY:scrolly.get ('pageY') - 1});   // scroll one page up
scrolly.set ({pageY:scrolly.get ('pageY') + 1});   // scroll one page down
scrolly.set ({pageY:0});                           // scroll to first page, vertically
scrolly.set ({pageY:Infinity});                    // scroll to last page, vertically

When scrolling left or right by incrementing or decrementing the value of the pageX set-get property, and when scrolling up or down by incrementing or decrementing the value of the pageY set-get property, it is not necessary to worry about detecting the first and last page boundaries, since a conformer for the pageX and pageY set-get properties takes care of this for you and makes sure that the values are always within bounds. This is why it is also possible to scroll to the last page by specifying the value Infinity, since this value will be constrained to the value of maxPageX when setting pageX and the value of maxPageY when setting pageY.

1.1.5. State Summary

For the convenience of application code, a full complement of read-only set-get properties provides a state summary for scrolly instances.

This state summary is provided through the isScrollableX and isScrollableY boolean read-only properties, and the maxPageX, and maxPageY integer read-only properties. These various state properties can be used in the implementation of subclasses, in other widget classes that use the Uize.Widget.Scrolly class, or in application code that uses scrollies.

1.1.6. The HTML

The following example HTML shows a typical way that the HTML markup for an instance could be implemented.

EXAMPLE HTML

The above example HTML is for a scrolly instance that is attached as the child widget named "myScrolly" to the page widget instance with the idPrefix of 'page'. Therefore, the idPrefix of the left child widget is 'page_myScrolly_left', and the idPrefix of the scrolly's view implied node is 'page_myScrolly-view'.

2. Instance Properties

2.1. fade

An instance of the Uize.Fade class that is used to animate the scrolling of the contents of the view implied node.

The fade instance is created during the construction of the Uize.Widget.Scrolly instance, so the fade properties can be modified immediately after the scrolly is created. The behavior of the animation can be controlled by setting values for the various set-get properties of the fade instance, such as its acceleration, deceleration, duration, and other set-get properties.

EXAMPLE

page.addChild ('myScrolly',Uize.Widget.Scrolly).fade.set ({duration:1000});

In the above example, an instance of the Uize.Widget.Scrolly class is added as a child widget of a page widget instance, and then its fade duration is set to 1000 (ie. one second). Because the addChild instance method returns a reference to the child widget being added, and because the fade instance is created during construction of the Uize.Widget.Scrolly instance, the set instance method can be called in a chained fashion.

3. Child Widgets

3.1. down

An instance of the Uize.Widget.Button class, that is wired up so that clicking on it will scroll the view implied node down by one page.

Clicking this button has the effect of incrementing the value of the pageY set-get property. The markup for this button is optional. The enabled state of this button is managed by the Uize.Widget.Scrolly class, so that it is disabled whenever it is not possible to scroll down, such as when the view implied node is already scrolled all the way to the bottom (ie. the value of pageY is equal to the value of maxPageY).

NOTES

see the related pageY set-get property
see the companion up child widget, and the related left and right child widgets

3.2. left

An instance of the Uize.Widget.Button class, that is wired up so that clicking on it will scroll the view implied node left by one page.

Clicking this button has the effect of decrementing the value of the pageX set-get property. The markup for this button is optional. The enabled state of this button is managed by the Uize.Widget.Scrolly class, so that it is disabled whenever it is not possible to scroll left, such as when the view implied node is already scrolled all the way to the left (ie. the value of pageX is 0).

NOTES

see the related pageX set-get property
see the companion right child widget, and the related up and down child widgets

3.3. right

An instance of the Uize.Widget.Button class, that is wired up so that clicking on it will scroll the view implied node right by one page.

Clicking this button has the effect of incrementing the value of the pageX set-get property. The markup for this button is optional. The enabled state of this button is managed by the Uize.Widget.Scrolly class, so that it is disabled whenever it is not possible to scroll right, such as when the view implied node is already scrolled all the way to the right (ie. the value of pageX is equal to the value of maxPageX).

NOTES

see the related pageX set-get property
see the companion left child widget, and the related up and down child widgets

3.4. up

An instance of the Uize.Widget.Button class, that is wired up so that clicking on it will scroll the view implied node up by one page.

Clicking this button has the effect of decrementing the value of the pageY set-get property. The markup for this button is optional. The enabled state of this button is managed by the Uize.Widget.Scrolly class, so that it is disabled whenever it is not possible to scroll up, such as when the view implied node is already scrolled all the way to the top (ie. the value of pageY is 0).

NOTES

see the related pageY set-get property
see the companion down child widget, and the related left and right child widgets

4. Implied Nodes

4.1. view

A node of any type, whose scrollLeft and scrollTop style properties are maintained by the Uize.Widget.Scrolly class as the values of the pageX and pageY set-get properties are modified.

The overflow CSS style property for this node should be set to hidden, either in an inline style attribute, an inline stylesheet, or an external stylesheet.

5. Set-get Properties

5.1. isScrollableX

A read-only boolean (whose value is managed by the Uize.Widget.Scrolly class), indicating whether or not the contents of the view implied node is wide enough to make it horizontally scrollable.

NOTES

this property is read-only
see the companion isScrollableY set-get property
the initial value is false, and it is updated each time the value of maxPageX changes

5.2. isScrollableY

A read-only boolean (whose value is managed by the Uize.Widget.Scrolly class), indicating whether or not the contents of the view implied node is tall enough to make it vertically scrollable.

NOTES

this property is read-only
see the companion isScrollableX set-get property
the initial value is false, and it is updated each time the value of maxPageY changes

5.3. maxPageX

A read-only integer (whose value is managed by the Uize.Widget.Scrolly class), indicating the maximum possible value for the pageX set-get property.

The value of this property can be used as an indication of the number of horizontal pages for the contents of the view implied node. For example, a value of 0 indicates that there is only one page horizontally (ie. the maximum value for pageX is 0). A value of 5, on the other hand, indicates that there are six pages horizontally, where those six pages are represented by the values 0 through 5 for the pageX set-get property.

NOTES

this property is read-only
the initial value is undefined, and it is later updated upon wiring the instance's UI, every time the updateUi instance method is called, and every time a value is set for the pageX set-get property
see the companion maxPageY set-get property

5.4. maxPageY

A read-only integer (whose value is managed by the Uize.Widget.Scrolly class), indicating the maximum possible value for the pageY set-get property.

The value of this property can be used as an indication of the number of vertical pages for the contents of the view implied node. For example, a value of 0 indicates that there is only one page vertically (ie. the maximum value for pageY is 0). A value of 5, on the other hand, indicates that there are six pages vertically, where those six pages are represented by the values 0 through 5 for the pageY set-get property.

NOTES

this property is read-only
the initial value is undefined, and it is later updated upon wiring the instance's UI, every time the updateUi instance method is called, and every time a value is set for the pageY set-get property
see the companion maxPageX set-get property

5.5. pageX

An integer, representing the current horizontal scroll position of the view implied node as a page number (see Scrolling in Pages) in the X-axis.

5.5.1. Conformed

When setting the value for this property, the value is conformed in a number of ways.

1. The value will be coerced to a number type by invoking the valueOf Intrinsic Method. This means that one can specify a string value that is a valid formatted number, or an object (such as an instance of a Uize subclass) that implements the value interface.
2. Values that cannot be successfully coerced to a number type (such as null, NaN, etc.) will result in the property not changing its value.
3. The value will be constrained so that it cannot go below 0 and cannot go above the value of the maxPageX set-get property.

NOTES

see the companion pageY set-get property
the initial value is 0

5.6. pageY

An integer, representing the current vertical scroll position of the view implied node as a page number (see Scrolling in Pages) in the Y-axis.

5.6.1. Conformed

When setting the value for this property, the value is conformed in a number of ways.

1. The value will be coerced to a number type by invoking the valueOf Intrinsic Method. This means that one can specify a string value that is a valid formatted number, or an object (such as an instance of a Uize subclass) that implements the value interface.
2. Values that cannot be successfully coerced to a number type (such as null, NaN, etc.) will result in the property not changing its value.
3. The value will be constrained so that it cannot go below 0 and cannot go above the value of the maxPageY set-get property.

NOTES

see the companion pageX set-get property
the initial value is 0

5.7. showButtonsWhenNotScrollable

A boolean, specifying whether or not the scroll buttons should be displayed in a given axis when it is not possible to scroll in that axis.

When showButtonsWhenNotScrollable is set to false, the scroll buttons for a given axis will be hidden when it is not possible to scroll in that axis. If it is possible to scroll in the axis, then the buttons will be displayed and one of them may be disabled. When showButtonsWhenNotScrollable is set to true and it is not possible to scroll in a given axis, then the scroll buttons will be displayed for that axis but will both be disabled.

NOTES

see the related left, right, up, and down child widgets
the initial value is true