Overview
These functions help a component work with "fractional selection". This notion can be very helpful in modeling components such as carousels (e.g., Carousel, in which the selection state during user interaction may be partway between one item and the next. With fractional selection, we add a real number between 0 and 1 to a selected index to obtain a fractional selection value.
Consider a carousel displaying a set of images. Suppose the image at index 3
is selected. The carousel's selectedIndex state at this point is 3. The
user begins dragging the carousel with their finger. Image 3 moves out of
view, and the image 4 moves into view. When the user is halfway through this
operation, we might say that the fractional selection value is 3.5.
Eventually, the user releases their finger, and the carousel shows the image
4 selected; the selectedIndex is 4.
These functions help components work consistently with fractional selection.
API
dampen(x) static method
Calculate damping as a function of the distance past the minimum/maximum values.
We want to asymptotically approach an absolute minimum of 1 unit below/above the actual minimum/maximum. This requires calculating a hyperbolic function.
We use the formula y = (-1/(x+1))+1.
(See a graph of this
function.)
The only portion of that function we care about is when x is zero or greater.
An important consideration is that the curve be tangent to the diagonal line
x=y at (0, 0). This ensures smooth continuity with the normal drag behavior,
in which the visible sliding is linear with the distance the touchpoint has
been dragged.
Parameters:
- x:
number– The number of dampen
Returns: number
dampenselection, itemCount) static method
Dampen a selection that goes past the beginning or end of a list. This is generally used to produce a visual effect of tension as the user tries to go further in a direction that has no more items.
Example: suppose itemCount is 5, indicating a list of 5 items. The index of
the last item is 4. If the selection parameter is 4.5, the user is trying
to go past this last item. When a damping function is applied, the resulting
value will be less than 4.5 (the actual value will be 4.25). When this
selection state is rendered, the user will see that, each unit distance the
drag travels has less and less visible effect. This is perceived as tension.
Parameters:
- selection:
number– A real number indicating a selection position - itemCount:
number– An integer for the number of items in the list
Returns: number A real number representing the damped selection value.