1 /*
2  * Copyright 2022 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.compose.foundation.gestures.snapping
18 
19 /**
20  * Provides information about the layout that is using a [snapFlingBehavior]. The provider should
21  * give the following information:
22  * 1) Snapping offset: The next snap position offset. This needs to be provided by the layout where
23  *    the snapping is happened and will represent the final settling position of this layout.
24  * 2) Approach offset: An offset to be consumed before snapping to a defined bound. If not
25  *    overridden this will provide a decayed snapping behavior.
26  *
27  * In snapping, the approach offset and the snapping offset can be used to control how a snapping
28  * animation will look in a given layout. The complete snapping animation can be split into 2
29  * phases: approach and snapping.
30  *
31  * Approach: animate to the offset returned by [calculateApproachOffset]. This will use a decay
32  * animation if possible, otherwise the snap animation. Snapping: once the approach offset is
33  * reached, snap to the offset returned by [calculateSnapOffset] using the snap animation.
34  */
35 interface SnapLayoutInfoProvider {
36 
37     /**
38      * Calculate the distance to navigate before settling into the next snapping bound. By default
39      * this is [decayOffset] a suggested offset given by [snapFlingBehavior] to indicate where the
40      * animation would naturally decay if using [velocity]. Returning a value higher than
41      * [decayOffset] is valid and will force [snapFlingBehavior] to use a target based animation
42      * spec to run the approach phase since we won't be able to naturally decay to the proposed
43      * offset. If a value smaller than or equal to [decayOffset] is returned [snapFlingBehavior]
44      * will run a decay animation until it reaches the returned value. If zero is specified, that
45      * means there won't be an approach phase and there will only be snapping.
46      *
47      * @param velocity The current fling movement velocity. You can use this to calculate a velocity
48      *   based offset.
49      * @param decayOffset A suggested offset indicating where the animation would naturally decay
50      *   to.
51      */
calculateApproachOffsetnull52     fun calculateApproachOffset(velocity: Float, decayOffset: Float): Float = decayOffset
53 
54     /**
55      * Given a target placement in a layout, the snapping offset is the next snapping position this
56      * layout can be placed in. The target placement should be in the direction of [velocity].
57      *
58      * @param velocity The current fling movement velocity. This may change throughout the fling
59      *   animation.
60      */
61     fun calculateSnapOffset(velocity: Float): Float
62 }
63