1/* 2 * Copyright (C) 2011 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 */ 16package androidx.core.widget; 17 18import android.content.Context; 19import android.graphics.Canvas; 20import android.os.Build; 21import android.widget.EdgeEffect; 22 23import androidx.annotation.NonNull; 24 25/** 26 * Helper for accessing {@link android.widget.EdgeEffect}. 27 * 28 * This class is used to access {@link android.widget.EdgeEffect} on platform versions 29 * that support it. When running on older platforms it will result in no-ops. It should 30 * be used by views that wish to use the standard Android visual effects at the edges 31 * of scrolling containers. 32 */ 33public final class EdgeEffectCompat { 34 private EdgeEffect mEdgeEffect; 35 36 /** 37 * Construct a new EdgeEffect themed using the given context. 38 * 39 * <p>Note: On platform versions that do not support EdgeEffect, all operations 40 * on the newly constructed object will be mocked/no-ops.</p> 41 * 42 * @param context Context to use for theming the effect 43 * 44 * @deprecated Use {@link EdgeEffect} constructor directly. 45 */ 46 @Deprecated 47 public EdgeEffectCompat(Context context) { 48 mEdgeEffect = new EdgeEffect(context); 49 } 50 51 /** 52 * Set the size of this edge effect in pixels. 53 * 54 * @param width Effect width in pixels 55 * @param height Effect height in pixels 56 * 57 * @deprecated Use {@link EdgeEffect#setSize(int, int)} directly. 58 */ 59 @Deprecated 60 public void setSize(int width, int height) { 61 mEdgeEffect.setSize(width, height); 62 } 63 64 /** 65 * Reports if this EdgeEffectCompat's animation is finished. If this method returns false 66 * after a call to {@link #draw(Canvas)} the host widget should schedule another 67 * drawing pass to continue the animation. 68 * 69 * @return true if animation is finished, false if drawing should continue on the next frame. 70 * 71 * @deprecated Use {@link EdgeEffect#isFinished()} directly. 72 */ 73 @Deprecated 74 public boolean isFinished() { 75 return mEdgeEffect.isFinished(); 76 } 77 78 /** 79 * Immediately finish the current animation. 80 * After this call {@link #isFinished()} will return true. 81 * 82 * @deprecated Use {@link EdgeEffect#finish()} directly. 83 */ 84 @Deprecated 85 public void finish() { 86 mEdgeEffect.finish(); 87 } 88 89 /** 90 * A view should call this when content is pulled away from an edge by the user. 91 * This will update the state of the current visual effect and its associated animation. 92 * The host view should always {@link android.view.View#invalidate()} if this method 93 * returns true and draw the results accordingly. 94 * 95 * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to 96 * 1.f (full length of the view) or negative values to express change 97 * back toward the edge reached to initiate the effect. 98 * @return true if the host view should call invalidate, false if it should not. 99 * 100 * @deprecated Use {@link #onPull(EdgeEffect, float, float)}. 101 */ 102 @Deprecated 103 public boolean onPull(float deltaDistance) { 104 mEdgeEffect.onPull(deltaDistance); 105 return true; 106 } 107 108 /** 109 * A view should call this when content is pulled away from an edge by the user. 110 * This will update the state of the current visual effect and its associated animation. 111 * The host view should always {@link android.view.View#invalidate()} if this method 112 * returns true and draw the results accordingly. 113 * 114 * Views using {@link EdgeEffect} should favor {@link EdgeEffect#onPull(float, float)} when 115 * the displacement of the pull point is known. 116 * 117 * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to 118 * 1.f (full length of the view) or negative values to express change 119 * back toward the edge reached to initiate the effect. 120 * @param displacement The displacement from the starting side of the effect of the point 121 * initiating the pull. In the case of touch this is the finger position. 122 * Values may be from 0-1. 123 * @return true if the host view should call invalidate, false if it should not. 124 * 125 * @deprecated Use {@link EdgeEffect#onPull(float)} directly. 126 */ 127 @Deprecated 128 public boolean onPull(float deltaDistance, float displacement) { 129 onPull(mEdgeEffect, deltaDistance, displacement); 130 return true; 131 } 132 133 /** 134 * A view should call this when content is pulled away from an edge by the user. 135 * This will update the state of the current visual effect and its associated animation. 136 * The host view should always {@link android.view.View#invalidate()} after call this method 137 * and draw the results accordingly. 138 * 139 * @param edgeEffect The EdgeEffect that is attached to the view that is getting pulled away 140 * from an edge by the user. 141 * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to 142 * 1.f (full length of the view) or negative values to express change 143 * back toward the edge reached to initiate the effect. 144 * @param displacement The displacement from the starting side of the effect of the point 145 * initiating the pull. In the case of touch this is the finger position. 146 * Values may be from 0-1. 147 * 148 * @see {@link EdgeEffect#onPull(float, float)} 149 */ 150 public static void onPull(@NonNull EdgeEffect edgeEffect, float deltaDistance, 151 float displacement) { 152 if (Build.VERSION.SDK_INT >= 21) { 153 edgeEffect.onPull(deltaDistance, displacement); 154 } else { 155 edgeEffect.onPull(deltaDistance); 156 } 157 } 158 159 /** 160 * Call when the object is released after being pulled. 161 * This will begin the "decay" phase of the effect. After calling this method 162 * the host view should {@link android.view.View#invalidate()} if this method 163 * returns true and thereby draw the results accordingly. 164 * 165 * @return true if the host view should invalidate, false if it should not. 166 * 167 * @deprecated Use {@link EdgeEffect#onRelease()} directly. 168 */ 169 @Deprecated 170 public boolean onRelease() { 171 mEdgeEffect.onRelease(); 172 return mEdgeEffect.isFinished(); 173 } 174 175 /** 176 * Call when the effect absorbs an impact at the given velocity. 177 * Used when a fling reaches the scroll boundary. 178 * 179 * <p>When using a {@link android.widget.Scroller} or {@link android.widget.OverScroller}, 180 * the method <code>getCurrVelocity</code> will provide a reasonable approximation 181 * to use here.</p> 182 * 183 * @param velocity Velocity at impact in pixels per second. 184 * @return true if the host view should invalidate, false if it should not. 185 * 186 * @deprecated Use {@link EdgeEffect#onAbsorb(int)} directly. 187 */ 188 @Deprecated 189 public boolean onAbsorb(int velocity) { 190 mEdgeEffect.onAbsorb(velocity); 191 return true; 192 } 193 194 /** 195 * Draw into the provided canvas. Assumes that the canvas has been rotated 196 * accordingly and the size has been set. The effect will be drawn the full 197 * width of X=0 to X=width, beginning from Y=0 and extending to some factor < 198 * 1.f of height. 199 * 200 * @param canvas Canvas to draw into 201 * @return true if drawing should continue beyond this frame to continue the 202 * animation 203 * 204 * @deprecated Use {@link EdgeEffect#draw(Canvas)} directly. 205 */ 206 @Deprecated 207 public boolean draw(Canvas canvas) { 208 return mEdgeEffect.draw(canvas); 209 } 210} 211