AdapterViewProtocol

public 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 methods
abstract Iterable<AdapterViewProtocol.AdaptedData>

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

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

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

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

Public methods

getDataInAdapterView

abstract Iterable<AdapterViewProtocol.AdaptedData> getDataInAdapterView(AdapterView<Adapter> adapterView)

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<Adapter> adapterView

the AdapterView we want to interrogate the contents of.
Returns
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

abstract EspressoOptional<AdapterViewProtocol.AdaptedData> getDataRenderedByView(
    AdapterView<Adapter> adapterView,
    View descendantView
)

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<Adapter> adapterView

the adapterview hosting the data.
View descendantView

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

abstract boolean isDataRenderedWithinAdapterView(
    AdapterView<Adapter> adapterView,
    AdapterViewProtocol.AdaptedData adaptedData
)

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

Parameters
AdapterView<Adapter> adapterView

the AdapterView hosting this data.
AdapterViewProtocol.AdaptedData 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

abstract void makeDataRenderedWithinAdapterView(
    AdapterView<Adapter> adapterView,
    AdapterViewProtocol.AdaptedData data
)

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<Adapter> adapterView

the adapterView hosting the data.
AdapterViewProtocol.AdaptedData data

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.