Addressing API Review docs bugs:
->Issue 3370313
->Issue 3370403
->Issue 3370328
->kthx, bye
Change-Id: I2d1962c27b3ba856a0b4632d335271300bab45eb
diff --git a/api/11.xml b/api/11.xml
index 7db0328..70d37b4 100644
--- a/api/11.xml
+++ b/api/11.xml
@@ -240630,6 +240630,17 @@
visibility="public"
>
</method>
+<method name="fyiWillBeAdvancedByHostKThx"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
<method name="getAdapter"
return="android.widget.Adapter"
abstract="false"
@@ -240885,17 +240896,6 @@
visibility="public"
>
</method>
-<method name="willBeAdvancedByHost"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
</class>
<class name="AdapterViewFlipper"
extends="android.widget.AdapterViewAnimator"
diff --git a/api/current.xml b/api/current.xml
index 613f000..0427a2e 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -240651,6 +240651,17 @@
visibility="public"
>
</method>
+<method name="fyiWillBeAdvancedByHostKThx"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
<method name="getAdapter"
return="android.widget.Adapter"
abstract="false"
@@ -240906,17 +240917,6 @@
visibility="public"
>
</method>
-<method name="willBeAdvancedByHost"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
</class>
<class name="AdapterViewFlipper"
extends="android.widget.AdapterViewAnimator"
@@ -260347,7 +260347,7 @@
deprecated="not deprecated"
visibility="public"
>
-<parameter name="arg0" type="T">
+<parameter name="t" type="T">
</parameter>
</method>
</interface>
diff --git a/core/java/android/widget/AdapterViewAnimator.java b/core/java/android/widget/AdapterViewAnimator.java
index c27082f..4c1279ff 100644
--- a/core/java/android/widget/AdapterViewAnimator.java
+++ b/core/java/android/widget/AdapterViewAnimator.java
@@ -981,11 +981,21 @@
// items from the Adapter.
}
+ /**
+ * Called by an {@link android.appwidget.AppWidgetHost} in order to advance the current view when
+ * it is being used within an app widget.
+ */
public void advance() {
showNext();
}
- public void willBeAdvancedByHost() {
+ /**
+ * Called by an {@link android.appwidget.AppWidgetHost} to indicate that it will be
+ * automatically advancing the views of this {@link AdapterViewAnimator} by calling
+ * {@link AdapterViewAnimator#advance()} at some point in the future. This allows subclasses to
+ * perform any required setup, for example, to stop automatically advancing their children.
+ */
+ public void fyiWillBeAdvancedByHostKThx() {
}
@Override
diff --git a/core/java/android/widget/AdapterViewFlipper.java b/core/java/android/widget/AdapterViewFlipper.java
index 7721688..273c258 100644
--- a/core/java/android/widget/AdapterViewFlipper.java
+++ b/core/java/android/widget/AdapterViewFlipper.java
@@ -258,8 +258,14 @@
}
};
+ /**
+ * Called by an {@link android.appwidget.AppWidgetHost} to indicate that it will be
+ * automatically advancing the views of this {@link AdapterViewFlipper} by calling
+ * {@link AdapterViewFlipper#advance()} at some point in the future. This allows
+ * {@link AdapterViewFlipper} to prepare by no longer Advancing its children.
+ */
@Override
- public void willBeAdvancedByHost() {
+ public void fyiWillBeAdvancedByHostKThx() {
mAdvancedByHost = true;
updateRunning(false);
}
diff --git a/core/java/android/widget/Advanceable.java b/core/java/android/widget/Advanceable.java
index bb162de..dc13ebb7 100644
--- a/core/java/android/widget/Advanceable.java
+++ b/core/java/android/widget/Advanceable.java
@@ -34,5 +34,5 @@
* Called by the AppWidgetHost once before it begins to call advance(), allowing the
* collection to do any required setup.
*/
- public void willBeAdvancedByHost();
+ public void fyiWillBeAdvancedByHostKThx();
}
diff --git a/core/java/android/widget/RemoteViewsService.java b/core/java/android/widget/RemoteViewsService.java
index 16126aa..e5a3de2 100644
--- a/core/java/android/widget/RemoteViewsService.java
+++ b/core/java/android/widget/RemoteViewsService.java
@@ -42,7 +42,7 @@
/**
* An interface for an adapter between a remote collection view (ListView, GridView, etc) and
* the underlying data for that view. The implementor is responsible for making a RemoteView
- * for each item in the data set.
+ * for each item in the data set. This interface is a thin wrapper around {@link Adapter}.
*
* @see android.widget.Adapter
* @see android.appwidget.AppWidgetManager
@@ -53,24 +53,72 @@
* multiple RemoteViewAdapters depending on the intent passed.
*/
public void onCreate();
+
/**
* Called when notifyDataSetChanged() is triggered on the remote adapter. This allows a
* RemoteViewsFactory to respond to data changes by updating any internal references.
*
+ * Note: expensive tasks can be safely performed synchronously within this method. In the
+ * interim, the old data will be displayed within the widget.
+ *
* @see android.appwidget.AppWidgetManager#notifyAppWidgetViewDataChanged(int[], int)
*/
public void onDataSetChanged();
+
/**
* Called when the last RemoteViewsAdapter that is associated with this factory is
* unbound.
*/
public void onDestroy();
+ /**
+ * See {@link Adapter#getCount()}
+ *
+ * @return Count of items.
+ */
public int getCount();
+
+ /**
+ * See {@link Adapter#getView(int, android.view.View, android.view.ViewGroup)}.
+ *
+ * Note: expensive tasks can be safely performed synchronously within this method, and a
+ * loading view will be displayed in the interim. See {@link #getLoadingView()}.
+ *
+ * @param position The position of the item within the Factory's data set of the item whose
+ * view we want.
+ * @return A RemoteViews object corresponding to the data at the specified position.
+ */
public RemoteViews getViewAt(int position);
+
+ /**
+ * This allows for the use of a custom loading view which appears between the time that
+ * {@link #getViewAt(int)} is called and returns. If null is returned, a default loading
+ * view will be used.
+ *
+ * @return The RemoteViews representing the desired loading view.
+ */
public RemoteViews getLoadingView();
+
+ /**
+ * See {@link Adapter#getViewTypeCount()}.
+ *
+ * @return The number of types of Views that will be returned by this factory.
+ */
public int getViewTypeCount();
+
+ /**
+ * See {@link Adapter#getItemId(int)}.
+ *
+ * @param position The position of the item within the data set whose row id we want.
+ * @return The id of the item at the specified position.
+ */
public long getItemId(int position);
+
+ /**
+ * See {@link Adapter#hasStableIds()}.
+ *
+ * @return True if the same id always refers to the same object.
+ */
public boolean hasStableIds();
}
diff --git a/core/java/android/widget/StackView.java b/core/java/android/widget/StackView.java
index 2c10077..22edf6d 100644
--- a/core/java/android/widget/StackView.java
+++ b/core/java/android/widget/StackView.java
@@ -347,6 +347,9 @@
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
@android.view.RemotableViewMethod
public void showNext() {
@@ -362,6 +365,9 @@
super.showNext();
}
+ /**
+ * {@inheritDoc}
+ */
@Override
@android.view.RemotableViewMethod
public void showPrevious() {
@@ -474,6 +480,9 @@
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean onInterceptTouchEvent(MotionEvent ev) {
int action = ev.getAction();
@@ -561,6 +570,9 @@
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean onTouchEvent(MotionEvent ev) {
super.onTouchEvent(ev);
@@ -939,6 +951,9 @@
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public void onRemoteAdapterConnected() {
super.onRemoteAdapterConnected();