Implements visibility events for EpoxyRecyclerView/EpoxyViewHolder.

epoxy-adapter/build.gradle

@@ -1,4 +1,5 @@
 apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
 
 android {
   compileSdkVersion rootProject.COMPILE_SDK_VERSION
@@ -25,6 +26,7 @@ dependencies {
 
   annotationProcessor project(':epoxy-processor')
 
+  testImplementation rootProject.deps.kotlin
   testCompile rootProject.deps.junit
   testCompile rootProject.deps.robolectric
   testCompile rootProject.deps.mockito

epoxy-adapter/src/main/java/com/airbnb/epoxy/EpoxyModel.java

@@ -1,13 +1,16 @@
 package com.airbnb.epoxy;
 
+import android.support.annotation.FloatRange;
 import android.support.annotation.LayoutRes;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
+import android.support.annotation.Px;
 import android.view.LayoutInflater;
 import android.view.View;
 import android.view.ViewGroup;
 
 import com.airbnb.epoxy.EpoxyController.ModelInterceptorCallback;
+import com.airbnb.epoxy.VisibilityState.Visibility;
 
 import java.util.List;
 
@@ -155,6 +158,26 @@ public void bind(@NonNull T view, @NonNull EpoxyModel<?> previouslyBoundModel) {
   public void unbind(@NonNull T view) {
   }
 
+  /**
+   * TODO link to the wiki
+   * @see OnVisibilityStateChanged annotation
+   */
+  public void onVisibilityStateChanged(@Visibility int visibilityState, @NonNull T view) {
+  }
+
+  /**
+   * TODO link to the wiki
+   * @see OnVisibilityChanged annotation
+   */
+  public void onVisibilityChanged(
+      @FloatRange(from = 0.0f, to = 100.0f) float percentVisibleHeight,
+      @FloatRange(from = 0.0f, to = 100.0f) float percentVisibleWidth,
+      @Px int visibleHeight,
+      @Px int visibleWidth,
+      @NonNull T view
+  ) {
+  }
+
   public long id() {
     return id;
   }

epoxy-adapter/src/main/java/com/airbnb/epoxy/EpoxyModelWithHolder.java

@@ -1,6 +1,10 @@
 package com.airbnb.epoxy;
 
+import android.support.annotation.FloatRange;
 import android.support.annotation.NonNull;
+import android.support.annotation.Px;
+
+import com.airbnb.epoxy.VisibilityState.Visibility;
 
 import java.util.List;
 
@@ -40,6 +44,24 @@ public void unbind(@NonNull T holder) {
     super.unbind(holder);
   }
 
+
+  @Override
+  public void onVisibilityStateChanged(@Visibility int visibilityState, @NonNull T view) {
+    super.onVisibilityStateChanged(visibilityState, view);
+  }
+
+  @Override
+  public void onVisibilityChanged(
+      @FloatRange(from = 0, to = 100) float percentVisibleHeight,
+      @FloatRange(from = 0, to = 100) float percentVisibleWidth,
+      @Px int visibleHeight, @Px int visibleWidth,
+      @NonNull T view) {
+    super.onVisibilityChanged(
+        percentVisibleHeight, percentVisibleWidth,
+        visibleHeight, visibleWidth,
+        view);
+  }
+
   @Override
   public boolean onFailedToRecycleView(T holder) {
     return super.onFailedToRecycleView(holder);

epoxy-adapter/src/main/java/com/airbnb/epoxy/EpoxyViewHolder.java

@@ -1,11 +1,14 @@
 
 package com.airbnb.epoxy;
 
+import android.support.annotation.FloatRange;
 import android.support.annotation.Nullable;
+import android.support.annotation.Px;
 import android.support.v7.widget.RecyclerView;
 import android.view.View;
 
 import com.airbnb.epoxy.ViewHolderState.ViewState;
+import com.airbnb.epoxy.VisibilityState.Visibility;
 
 import java.util.List;
 
@@ -82,6 +85,25 @@ public void unbind() {
     payloads = null;
   }
 
+  public void visibilityStateChanged(@Visibility int visibilityState) {
+    assertBound();
+    // noinspection unchecked
+    epoxyModel.onVisibilityStateChanged(visibilityState, objectToBind());
+  }
+
+  public void visibilityChanged(
+      @FloatRange(from = 0.0f, to = 100.0f) float percentVisibleHeight,
+      @FloatRange(from = 0.0f, to = 100.0f) float percentVisibleWidth,
+      @Px int visibleHeight,
+      @Px int visibleWidth
+  ) {
+    assertBound();
+    // noinspection unchecked
+    epoxyModel.onVisibilityChanged(percentVisibleHeight, percentVisibleWidth, visibleHeight,
+        visibleWidth, objectToBind());
+  }
+
+
   public List<Object> getPayloads() {
     assertBound();
     return payloads;

epoxy-adapter/src/main/java/com/airbnb/epoxy/EpoxyVisibilityItem.java

@@ -0,0 +1,177 @@
+package com.airbnb.epoxy;
+
+import android.graphics.Rect;
+import android.support.annotation.NonNull;
+import android.support.annotation.Px;
+import android.support.v7.widget.RecyclerView;
+import android.view.View;
+
+/**
+ * This class represent an item in the {@link android.support.v7.widget.RecyclerView} and it is
+ * being reused with multiple model via the update method. There is 1:1 relationship between an
+ * EpoxyVisibilityItem and a child within the {@link android.support.v7.widget.RecyclerView}.
+ *
+ * It contains the logic to compute the visibility state of an item. It will also invoke the
+ * visibility callbacks on {@link com.airbnb.epoxy.EpoxyViewHolder}
+ *
+ * This class should remain non-public and is intended to be used by {@link EpoxyVisibilityTracker}
+ * only.
+ */
+class EpoxyVisibilityItem {
+
+  private static final int NOT_NOTIFIED = -1;
+
+  private final Rect localVisibleRect = new Rect();
+
+  private int adapterPosition = RecyclerView.NO_POSITION;
+
+  @Px
+  private int sizeInScrollingDirection;
+
+  private int sizeNotInScrollingDirection;
+
+  private boolean verticalScrolling;
+
+  private float percentVisibleSize = 0.f;
+
+  private int visibleSize;
+
+  private int viewportSize;
+
+  private boolean fullyVisible = false;
+  private boolean visible = false;
+  private boolean focusedVisible = false;
+
+  /** Store last value for de-duping */
+  private int lastVisibleSizeNotified = NOT_NOTIFIED;
+
+  /**
+   * Update the visibility item according the current layout.
+   *
+   * @param view        the current {@link com.airbnb.epoxy.EpoxyViewHolder}'s itemView
+   * @param parent      the {@link android.support.v7.widget.RecyclerView}
+   * @param vertical    true if it scroll vertically
+   * @return true if the view has been measured
+   */
+  boolean update(@NonNull View view, @NonNull RecyclerView parent,
+      boolean vertical, boolean detachEvent) {
+    view.getLocalVisibleRect(localVisibleRect);
+    this.verticalScrolling = vertical;
+    if (vertical) {
+      sizeInScrollingDirection = view.getMeasuredHeight();
+      sizeNotInScrollingDirection = view.getMeasuredWidth();
+      viewportSize = parent.getMeasuredHeight();
+      visibleSize = detachEvent ? 0 : localVisibleRect.height();
+    } else {
+      sizeNotInScrollingDirection = view.getMeasuredHeight();
+      sizeInScrollingDirection = view.getMeasuredWidth();
+      viewportSize = parent.getMeasuredWidth();
+      visibleSize = detachEvent ? 0 : localVisibleRect.width();
+    }
+    percentVisibleSize = detachEvent ? 0 : 100.f / sizeInScrollingDirection * visibleSize;
+    if (visibleSize != sizeInScrollingDirection) {
+      fullyVisible = false;
+    }
+    return sizeInScrollingDirection > 0;
+  }
+
+  int getAdapterPosition() {
+    return adapterPosition;
+  }
+
+  void reset(int newAdapterPosition) {
+    fullyVisible = false;
+    visible = false;
+    focusedVisible = false;
+    adapterPosition = newAdapterPosition;
+    lastVisibleSizeNotified = NOT_NOTIFIED;
+  }
+
+  void handleVisible(@NonNull EpoxyViewHolder epoxyHolder, boolean detachEvent) {
+    if (visible && checkAndUpdateInvisible(detachEvent)) {
+      epoxyHolder.visibilityStateChanged(VisibilityState.INVISIBLE);
+    } else if (!visible && checkAndUpdateVisible()) {
+      epoxyHolder.visibilityStateChanged(VisibilityState.VISIBLE);
+    }
+  }
+
+  void handleFocus(EpoxyViewHolder epoxyHolder, boolean detachEvent) {
+    if (focusedVisible && checkAndUpdateUnfocusedVisible(detachEvent)) {
+      epoxyHolder.visibilityStateChanged(VisibilityState.UNFOCUSED_VISIBLE);
+    } else if (!focusedVisible && checkAndUpdateFocusedVisible()) {
+      epoxyHolder.visibilityStateChanged(VisibilityState.FOCUSED_VISIBLE);
+    }
+  }
+
+  void handleFullImpressionVisible(EpoxyViewHolder epoxyHolder, boolean detachEvent) {
+    if (!fullyVisible && checkAndUpdateFullImpressionVisible()) {
+      epoxyHolder
+          .visibilityStateChanged(VisibilityState.FULL_IMPRESSION_VISIBLE);
+    }
+  }
+
+  void handleChanged(EpoxyViewHolder epoxyHolder) {
+    if (visibleSize != lastVisibleSizeNotified) {
+      if (verticalScrolling) {
+        epoxyHolder.visibilityChanged(percentVisibleSize, 100.f, visibleSize,
+            sizeNotInScrollingDirection);
+      } else {
+        epoxyHolder.visibilityChanged(100.f, percentVisibleSize,
+            sizeNotInScrollingDirection, visibleSize);
+      }
+      lastVisibleSizeNotified = visibleSize;
+    }
+  }
+
+  /**
+   * @return true when at least one pixel of the component is visible
+   */
+  private boolean checkAndUpdateVisible() {
+    return visible = visibleSize > 0;
+  }
+
+  /**
+   * @param detachEvent true if initiated from detach event
+   * @return true when when the component no longer has any pixels on the screen
+   */
+  private boolean checkAndUpdateInvisible(boolean detachEvent) {
+    boolean invisible = visibleSize <= 0 || detachEvent;
+    if (invisible) {
+      visible = false;
+    }
+    return !visible;
+  }
+
+  /**
+   * @return true when either the component occupies at least half of the viewport, or, if the
+   * component is smaller than half the viewport, when it is fully visible.
+   */
+  private boolean checkAndUpdateFocusedVisible() {
+    return focusedVisible =
+        sizeInScrollingDirection >= viewportSize / 2 || (visibleSize == sizeInScrollingDirection
+            && sizeInScrollingDirection < viewportSize / 2);
+  }
+
+  /**
+   * @param detachEvent true if initiated from detach event
+   * @return true when the component is no longer focused, i.e. it is not fully visible and does
+   * not occupy at least half the viewport.
+   */
+  private boolean checkAndUpdateUnfocusedVisible(boolean detachEvent) {
+    boolean unfocusedVisible = detachEvent
+        || !(sizeInScrollingDirection >= viewportSize / 2 || (
+        visibleSize == sizeInScrollingDirection && sizeInScrollingDirection < viewportSize / 2));
+    if (unfocusedVisible) {
+      focusedVisible = false;
+    }
+    return !focusedVisible;
+  }
+
+  /**
+   * @return true when the entire component has passed through the viewport at some point.
+   */
+  private boolean checkAndUpdateFullImpressionVisible() {
+    return fullyVisible = visibleSize == sizeInScrollingDirection;
+  }
+}
+