Package icyllis.modernui.widget

Class EdgeEffect

java.lang.Object
icyllis.modernui.widget.EdgeEffect
public class EdgeEffect extends Object
This class performs the graphical effect used at the edges of scrollable widgets when the user scrolls beyond the content bounds in 2D space.

EdgeEffect is stateful. Custom widgets using EdgeEffect should create an instance for each edge that should show the effect, feed it input data using the methods onAbsorb(int), onPull(float), and onRelease(), and draw the effect using draw(Canvas) in the widget's overridden View.draw(Canvas) method. If isFinished() returns false after drawing, the edge effect's animation is not yet complete and the widget should schedule another drawing pass to continue the animation.

When drawing, widgets should draw their main content and child views first, usually by invoking super.draw(canvas) from an overridden draw method. (This will invoke onDraw and dispatch drawing to child views as needed.) The edge effect may then be drawn on top of the view's content using the draw(Canvas) method.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final BlendMode
    DEFAULT_BLEND_MODE
    The default blend mode used by EdgeEffect.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EdgeEffect()
    Construct a new EdgeEffect with a theme appropriate for the provided context.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    draw(Canvas canvas)
    Draw into the provided canvas.
    void
    finish()
    Immediately finish the current animation.
    BlendMode
    getBlendMode()
    Returns the blend mode.
    int
    getColor()
    Return the color of this edge effect in argb.
    float
    getDistance()
    Returns the pull distance needed to be released to remove the showing effect.
    int
    getMaxHeight()
    Return the maximum height that the edge effect will be drawn at given the original input size.
    boolean
    isFinished()
    Reports if this EdgeEffect's animation is finished.
    void
    onAbsorb(int velocity)
    Call when the effect absorbs an impact at the given velocity.
    void
    onPull(float deltaDistance)
    A view should call this when content is pulled away from an edge by the user.
    void
    onPull(float deltaDistance, float displacement)
    A view should call this when content is pulled away from an edge by the user.
    float
    onPullDistance(float deltaDistance, float displacement)
    A view should call this when content is pulled away from an edge by the user.
    void
    onRelease()
    Call when the object is released after being pulled.
    void
    setBlendMode(BlendMode blendMode)
    Set or clear the blend mode.
    void
    setColor(int color)
    Set the color of this edge effect in argb.
    void
    setSize(int width, int height)
    Set the size of this edge effect in pixels.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_BLEND_MODE

      public static final BlendMode DEFAULT_BLEND_MODE
      The default blend mode used by EdgeEffect.

  • Constructor Details

    • EdgeEffect

      public EdgeEffect()
      Construct a new EdgeEffect with a theme appropriate for the provided context.

  • Method Details

    • setSize

      public void setSize(int width, int height)
      Set the size of this edge effect in pixels.
      Parameters:
      width - Effect width in pixels
      height - Effect height in pixels

    • isFinished

      public boolean isFinished()
      Reports if this EdgeEffect's animation is finished. If this method returns false after a call to draw(Canvas) the host widget should schedule another drawing pass to continue the animation.
      Returns:
      true if animation is finished, false if drawing should continue on the next frame.

    • finish

      public void finish()
      Immediately finish the current animation. After this call isFinished() will return true.

    • onPull

      public void onPull(float deltaDistance)
      A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always View.invalidate() after this and draw the results accordingly.

      Views using EdgeEffect should favor onPull(float, float) when the displacement of the pull point is known.

      Parameters:
      deltaDistance - Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.

    • onPull

      public void onPull(float deltaDistance, float displacement)
      A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always View.invalidate() after this and draw the results accordingly.
      Parameters:
      deltaDistance - Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.
      displacement - The displacement from the starting side of the effect of the point initiating the pull. In the case of touch this is the finger position. Values may be from 0-1.

    • onPullDistance

      public float onPullDistance(float deltaDistance, float displacement)
      A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always View.invalidate() after this and draw the results accordingly. This works similarly to onPull(float, float), but returns the amount of deltaDistance that has been consumed. If the getDistance() is currently 0 and deltaDistance is negative, this function will return 0 and the drawn value will remain unchanged.

      This method can be used to reverse the effect from a pull or absorb and partially consume some of a motion: 

           if (deltaY invalid input: '<' 0) {
         float consumed = edgeEffect.onPullDistance(deltaY / getHeight(), x / getWidth());
         deltaY -= consumed * getHeight();
         if (edgeEffect.getDistance() == 0f) edgeEffect.onRelease();
     }
      Parameters:
      deltaDistance - Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.
      displacement - The displacement from the starting side of the effect of the point initiating the pull. In the case of touch this is the finger position. Values may be from 0-1.
      Returns:
      The amount of deltaDistance that was consumed, a number between 0 and deltaDistance.

    • getDistance

      public float getDistance()
      Returns the pull distance needed to be released to remove the showing effect. It is determined by the onPull(float, float) deltaDistance and any animating values, including from onAbsorb(int) and onRelease().

      This can be used in conjunction with onPullDistance(float, float) to release the currently showing effect.

      Returns:
      The pull distance that must be released to remove the showing effect.

    • onRelease

      public void onRelease()
      Call when the object is released after being pulled. This will begin the "decay" phase of the effect. After calling this method the host view should View.invalidate() and thereby draw the results accordingly.

    • onAbsorb

      public void onAbsorb(int velocity)
      Call when the effect absorbs an impact at the given velocity. Used when a fling reaches the scroll boundary.

      When using a OverScroller, the method getCurrVelocity will provide a reasonable approximation to use here.

      Parameters:
      velocity - Velocity at impact in pixels per second.

    • setColor

      public void setColor(@ColorInt int color)
      Set the color of this edge effect in argb.
      Parameters:
      color - Color in argb

    • setBlendMode

      public void setBlendMode(@Nullable BlendMode blendMode)
      Set or clear the blend mode. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).

      Pass null to clear any previous blend mode.

      Parameters:
      blendMode - May be null. The blend mode to be installed in the paint
      See Also:

    • getColor

      @ColorInt public int getColor()
      Return the color of this edge effect in argb.
      Returns:
      The color of this edge effect in argb

    • getBlendMode

      @Nullable public BlendMode getBlendMode()
      Returns the blend mode. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).
      Returns:
      BlendMode

    • draw

      public boolean draw(@Nonnull Canvas canvas)
      Draw into the provided canvas. Assumes that the canvas has been rotated accordingly and the size has been set. The effect will be drawn the full width of X=0 to X=width, beginning from Y=0 and extending to some factor invalid input: '<' 1.f of height.
      Parameters:
      canvas - Canvas to draw into
      Returns:
      true if drawing should continue beyond this frame to continue the animation

    • getMaxHeight

      public int getMaxHeight()
      Return the maximum height that the edge effect will be drawn at given the original input size.
      Returns:
      The maximum height of the edge effect