UIStateRestoring Protocol Reference

Conforms to
Framework
/System/Library/Framework/UIKit.framework
Availability
Available in iOS 7.0 and later.
Declared in
UIStateRestoration.h

Overview

The UIStateRestoring protocol lets you include any object in your state restoration archives. You can add state restoring objects to an archive directly or by referencing them from another object that is preserved, such as a view controller. The methods of the protocol let you save enough information about the object to find or recreate it during the next launch cycle.

When adopting this protocol in your custom objects, you must also remember to register those objects using the registerObjectForStateRestoration:restorationIdentifier: method of the UIApplication class. You do not need to register views or view controllers explicitly because UIKit registers those objects automatically. View controllers adopt this protocol so that they may be used as the restoration parent of one of your custom objects.

Tasks

Accessing the Object Information

Encoding and Decoding the Object

Properties

objectRestorationClass

The class responsible for creating this object when restoring the app’s state. (read-only)

@property (nonatomic, readonly) Class<UIObjectRestoration> objectRestorationClass;
Discussion

If an object has an associated restoration class, the objectWithRestorationIdentifierPath:coder: method of that class is called during state restoration. That method is responsible for returning the object that matches the provided path identifier information. If this property isnil, the object must already exist and be registered with the state restoration engine so that it can be found implicitly. You can register the object using the registerObjectForStateRestoration:restorationIdentifier: method at launch time.

The restoration class must conform to the UIObjectRestoration protocol.

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

restorationParent

The parent object used to scope the current object. (read-only)

@property (nonatomic, readonly) id<UIStateRestoring> restorationParent;
Discussion

Returning an object from this property lets you use the same restoration identifier for objects with similar behavior but different parents. When registering objects, the registerObjectForStateRestoration:restorationIdentifier: method checks the value of this property, using the value as the containing scope for the object. For example, an object associated with a view controller can make the view controller its parent.

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

Instance Methods

applicationFinishedRestoringState

Called after all objects have had a chance to decode their state.

- (void) applicationFinishedRestoringState
Discussion

Implement this method, as needed, to perform additional configuration of the restored object. This method is called toward the end of the restoration process when all objects have been decoded. You might use this method to restore state that exists between multiple objects or in cases where you have dependencies that make decoding those objects in a specific order difficult.

The order in which this method is called on decoded objects is not guaranteed.

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

decodeRestorableStateWithCoder:

Decodes and restores state-related information for the object.

- (void)decodeRestorableStateWithCoder:(NSCoder *)coder
Parameters
coder

The coder object to use to decode the state of the view.

Discussion

If your app supports state restoration, you can implement this method on any object for which you also overrode the encodeRestorableStateWithCoder: method. Your implementation of this method should read any saved state information from the archive and use it to restore the object to its previous configuration. If your encodeRestorableStateWithCoder: method called super, this method should similarly call super at some point in its implementation.

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

encodeRestorableStateWithCoder:

Encodes state-related information for the object.

- (void)encodeRestorableStateWithCoder:(NSCoder *)coder
Parameters
coder

The coder object to use to encode the state of the object.

Discussion

You can implement this method for any object that has state information you want to preserve. When deciding what data to save, write the smallest amount of data needed to restore the object to its current configuration. The information you save should be data that you could not easily recreate. You can also save references to other objects, such as the view controller that was using the object.

It is strongly recommended that you call super at some point during your implementation to give parent classes an opportunity to save information too.

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

Constants

State Restoration Keys

The following keys are available in restoration archives.

NSString *const UIStateRestorationViewControllerStoryboardKey;
NSString *const UIApplicationStateRestorationBundleVersionKey;
NSString *const UIApplicationStateRestorationUserInterfaceIdiomKey;
NSString *const UIApplicationStateRestorationTimestampKey;
NSString *const UIApplicationStateRestorationSystemVersionKey;
Constants
UIStateRestorationViewControllerStoryboardKey

The value of this key is a UIStoryboard object representing the storyboard from which a view controller was initially obtained. You do not need to write this key to the coder yourself. Each UIViewController class automatically writes this key to the coder during the state preservation process.

Available in iOS 6.0 and later.

Declared in UIStateRestoration.h.

UIApplicationStateRestorationBundleVersionKey

The value of this key is an NSString object that identifies the version of your app (as obtained from the CFBundleVersion key of your app’s Info.plist file) was was present when the state information was saved. You can use the value of this key to help make choices about how to proceed during state restoration. For example, if the key indicates that the state is associated with an older version of your app, you might want to avoid restoring the previous state altogether or modify the restoration process more significantly.

Available in iOS 6.0 and later.

Declared in UIStateRestoration.h.

UIApplicationStateRestorationUserInterfaceIdiomKey

The value of this key is an NSNumber object containing one of the values for the UIUserInterfaceIdiom enum. This value reflects whether the interface that was saved was targeting the iPad or iPhone idiom.

Available in iOS 6.0 and later.

Declared in UIStateRestoration.h.

UIApplicationStateRestorationTimestampKey

The value of this key is an NSDate object containing the date when the restoration archive was saved. The date is specified using coordinated universal time (UTC).

Available in iOS 7.0 and later.

Declared in UIStateRestoration.h.

UIApplicationStateRestorationSystemVersionKey

The value of this key is an NSString object containing the iOS system version that was installed when the archive was saved. The format of this string matches the format of the value in the systemVersion property of the UIDevice class.

Available in iOS 7.0 and later.

Declared in UIStateRestoration.h.