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.
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
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
number– The number of dampen
dampenListSelection(selection, 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.
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.
number– A real number indicating a selection position
number– An integer for the number of items in the list
number A real number representing the damped selection value.