UIDataSourceModelAssociation Protocol Reference

Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 6.0 and later.
Declared in
UIStateRestoration.h
Related sample code

Overview

The UIDataSourceModelAssociation protocol defines an interface for providing persistent references to data objects in your app. Your data source objects can adopt this protocol in order to assist a corresponding table or collection view during the state restoration process. Those classes use the methods of this protocol to ensure that the same data objects (and not just the same row indexes) are scrolled into view and selected.

Before you can implement this protocol, your app must be able to identify data objects consistently between app launches. This requires being able to take some identifying marker of the object and convert that marker into a string that can then be saved with the rest of the app state. For example, a Core Data app could convert a managed object’s ID into a URI that it could then convert into a string.

Currently, only the UITableView and UICollectionView classes support this protocol. You would implement this protocol in any objects you use as the data source for those classes. If you do not adopt the protocol in your data source, the views do not attempt to restore the selected and visible rows.

Tasks

Locating the Data

Instance Methods

indexPathForElementWithModelIdentifier:inView:

Returns the current index of the data object with the specified identifier. (required)

- (NSIndexPath *) indexPathForElementWithModelIdentifier:(NSString *)identifier inView:(UIView *)view
Parameters
identifier

The identifier for the requested data object. Use this identifier to locate the matching object in your data source object. This is the same string that your app’s modelIdentifierForElementAtIndexPath:inView: method returned when encoding the data originally.

view

The view into which the object is being inserted.

Return Value

The current index of the object whose data matches the value in identifier, or nil if the object was not found.

Discussion

During state restoration, view can call this method to locate objects that are not where they were expected to be. This can happen if the number of objects in the table is not the same as during the previous launch cycle. The view uses the information to ensure that the rows with the same data are once again selected or scrolled into view, even if those rows are in a different location now.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIStateRestoration.h

modelIdentifierForElementAtIndexPath:inView:

Returns the string that uniquely identifies the data at the specified location in the view. (required)

- (NSString *) modelIdentifierForElementAtIndexPath:(NSIndexPath *)idx inView:(UIView *)view
Parameters
idx

The index path to the requested data object.

view

The view that contains the data object.

Return Value

A string that uniquely identifies the data object.

Discussion

Use the provided information to locate the requested data object. From that object, extract a string that can be used later to identify the same piece of data again. The string you return must not be based on transient information, such as the pointer to the current object in memory; it must instead be tied to the underlying data. In fact, if two different in-memory objects represent the same piece of data in your app, they must both return the same model identifier string.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIStateRestoration.h