AdapterViewProtocol

interface AdapterViewProtocol

A sadly necessary layer of indirection to interact with AdapterViews.

Generally any subclass should respect the contracts and behaviors of its superclass. Otherwise it becomes impossible to work generically with objects that all claim to share a supertype - you need special cases to perform the same operation 'owned' by the supertype for each sub-type. The 'is - a' relationship is broken.

Android breaks the Liskov substitution principal with ExpandableListView - you can't use getAdapter(), getItemAtPosition(), and other methods common to AdapterViews on an ExpandableListView because an ExpandableListView isn't an adapterView - they just share a lot of code.

This interface exists to work around this wart (which sadly is copied in other projects too) and lets the implementor translate Espresso's needs and manipulations of the AdapterView into calls that make sense for the given subtype and context.

If you have to implement this to talk to widgets your own project defines - I'm sorry.

Summary

Nested types

A holder that associates a data object from an AdapterView with a token the AdapterViewProtocol can use to force that data object to be rendered as a child or deeper descendant of the adapter view.

A custom function that is applied when getData is executed.

Public functions
(Mutable)Iterable<AdapterViewProtocol.AdaptedData!>!

Returns all data this AdapterViewProtocol can find within the given AdapterView.
EspressoOptional<AdapterViewProtocol.AdaptedData!>!
getDataRenderedByView(
    adapterView: AdapterView<Adapter!>!,
    descendantView: View!
)

Returns the data object this particular view is rendering if possible.
Boolean

Indicates whether or not there now exists a descendant view within adapterView that is rendering this data.
Unit

Requests that a particular piece of data held in this AdapterView is actually rendered by it.

Public functions

getDataInAdapterView

fun getDataInAdapterView(adapterView: AdapterView<Adapter!>!): (Mutable)Iterable<AdapterViewProtocol.AdaptedData!>!

Returns all data this AdapterViewProtocol can find within the given AdapterView.

Any AdaptedData returned by this method can be passed to makeDataRenderedWithinView and the implementation should make the AdapterView bring that data item onto the screen.

Parameters
adapterView: AdapterView<Adapter!>!

the AdapterView we want to interrogate the contents of.
Returns
(Mutable)Iterable<AdapterViewProtocol.AdaptedData!>!

an Iterable of AdaptedDatas representing all data the implementation sees in this view
Throws
java.lang.IllegalArgumentException: java.lang.IllegalArgumentException

if the implementation doesn't know how to manipulate the given adapter view.

getDataRenderedByView

fun getDataRenderedByView(
    adapterView: AdapterView<Adapter!>!,
    descendantView: View!
): EspressoOptional<AdapterViewProtocol.AdaptedData!>!

Returns the data object this particular view is rendering if possible.

Implementations are expected to create a relationship between the data in the AdapterView and the descendant views of the AdapterView that obeys the following conditions:

  • For each descendant view there exists either 0 or 1 data objects it is rendering.
  • For each data object the AdapterView there exists either 0 or 1 descendant views which claim to be rendering it.

For example - if a PersonObject is rendered into: LinearLayout ImageView picture TextView firstName TextView lastName

It would be expected that getDataRenderedByView(adapter, LinearLayout) would return the PersonObject. If it were called instead with the TextView or ImageView it would return Object.absent().

Parameters
adapterView: AdapterView<Adapter!>!

the adapterview hosting the data.
descendantView: View!

a view which is a child, grand-child, or deeper descendant of adapterView
Returns
EspressoOptional<AdapterViewProtocol.AdaptedData!>!

an optional data object the descendant view is rendering.
Throws
java.lang.IllegalArgumentException: java.lang.IllegalArgumentException

if this protocol cannot interrogate this class of adapterView

isDataRenderedWithinAdapterView

fun isDataRenderedWithinAdapterView(
    adapterView: AdapterView<Adapter!>!,
    adaptedData: AdapterViewProtocol.AdaptedData!
): Boolean

Indicates whether or not there now exists a descendant view within adapterView that is rendering this data.

Parameters
adapterView: AdapterView<Adapter!>!

the AdapterView hosting this data.
adaptedData: AdapterViewProtocol.AdaptedData!

the data we are checking the display state for.
Returns
Boolean

true if the data is rendered by a view in the adapterView, false otherwise.

makeDataRenderedWithinAdapterView

fun makeDataRenderedWithinAdapterView(
    adapterView: AdapterView<Adapter!>!,
    data: AdapterViewProtocol.AdaptedData!
): Unit

Requests that a particular piece of data held in this AdapterView is actually rendered by it.

After calling this method it expected that there will exist some descendant view of adapterView for which calling getDataRenderedByView(adapterView, descView).get() == data.data is true.

Note: this need not happen immediately. EG: an implementor handling ListView may call listView.smoothScrollToPosition(data.opaqueToken) - which kicks off an animated scroll over the list to the given position. The animation may be in progress after this call returns. The only guarantee is that eventually - with no further interaction necessary - this data item will be rendered as a child or deeper descendant of this AdapterView.

Parameters
adapterView: AdapterView<Adapter!>!

the adapterView hosting the data.
data: AdapterViewProtocol.AdaptedData!

an AdaptedData instance retrieved by a prior call to getDataInAdapterView
Throws
java.lang.IllegalArgumentException: java.lang.IllegalArgumentException

if this protocol cannot manipulate adapterView or if data is not owned by this AdapterViewProtocol.