UIViewController Class Reference

Discussion

If the new child view controller is already the child of a container view controller, it is removed from that container before being added.

This method is only intended to be called by an implementation of a custom container view controller. If you override this method, you must call super in your implementation.

Discussion

If you are implementing a custom container controller, use this method to tell the child that its views are about to appear or disappear. Do not invoke viewWillAppear:, viewWillDisappear:, viewDidAppear:, or viewDidDisappear: directly.

Discussion

This method is called when the system is attempting to find a view controller to handle an unwind action. Your custom view controller should implement this method to tell the system that it wants to support an unwind action.

If your view controller returns YES, then a series of steps are performed:

1. The target view controller’s container invokes its segueForUnwindingToViewController:fromViewController:identifier: method to create a segue to unwind the view controller state.

2. The action method is called on the target view controller.

3. The segue is triggered to perform the segue.

new segue is created to transition from the initiating view controller to your view controller. After the segue is created, your action is called and then the segue is invoked,

Discussion

If your app supports state restoration, you should override this method for any view controllers for which you also overrode the encodeRestorableStateWithCoder: method. Your implementation of this method should use any saved state information to restore the view controller to its previous configuration. If your encodeRestorableStateWithCoder: method called super, this method should similarly call super at some point in its implementation.

Discussion

Your view controller can override this method when it wants to react to being added to a container.

If you are implementing your own container view controller, it must call the didMoveToParentViewController: method of the child view controller after the transition to the new controller is complete or, if there is no transition, immediately after calling the addChildViewController: method.

The removeFromParentViewController method automatically calls the didMoveToParentViewController: method of the child view controller after it removes the child.

Discussion

Your app never calls this method directly. Instead, this method is called when the system determines that the amount of available memory is low.

You can override this method to release any additional memory used by your view controller. If you do, your implementation of this method must call the super implementation at some point.

Discussion

Subclasses may override this method to perform additional actions immediately after the rotation. For example, you might use this method to reenable view interactions, start media playback again, or turn on expensive drawing or live updates. By the time this method is called, the interfaceOrientation property is already set to the new orientation.

This method is called regardless of whether your code performs one-step or two-step rotations.

Discussion

Override this method in a subclass to allow or disallow the dismissal of the current input view (usually the system keyboard) when changing from a control that wants the input view to one that does not. Under normal circumstances, when the user taps a control that requires an input view, the system automatically displays that view. Tapping in a control that does not want an input view subsequently causes the current input view to be dismissed but may not in all cases. You can override this method in those outstanding cases to allow the input view to be dismissed or use this method to prevent the view from being dismissed in other cases.

The default implementation of this method returns YES when the modal presentation style of the view controller is set to UIModalPresentationFormSheet and returns NO for other presentation styles. Thus, the system normally does not allow the keyboard to be dismissed for modal forms.

Discussion

The presenting view controller is responsible for dismissing the view controller it presented. If you call this method on the presented view controller itself, it automatically forwards the message to the presenting view controller.

If you present several view controllers in succession, thus building a stack of presented view controllers, calling this method on a view controller lower in the stack dismisses its immediate child view controller and all view controllers above that child on the stack. When this happens, only the top-most view is dismissed in an animated fashion; any intermediate view controllers are simply removed from the stack. The top-most view is dismissed using its modal transition style, which may differ from the styles used by other view controllers lower in the stack.

If you want to retain a reference to the receiver’s presented view controller, get the value in the presentedViewController property before calling this method.

The completion handler is called after the viewDidDisappear: method is called on the presented view controller.

Discussion

If one of the custom views of the navigationItem property is set to the returned object, the associated navigation bar displays an Edit button if editing is NO and a Done button if editing is YES. The default button action invokes the setEditing:animated: method.

Discussion

Subclasses can override this method and use it to save any view-controller specific state information. When deciding what data to save, write the smallest amount of data needed to restore the view controller to its current configuration. The information you save should be data that you could not easily recreate, such as the user’s current selection. You might also save references to any data objects that the view controller was using, but never write the data objects themselves to the coder. Instead, store enough information so that you can retrieve the data objects from your app’s main data structures again.

It is strongly recommended that you call super at some point during your implementation to give parent classes an opportunity to save information too. The UIViewController class saves a reference to the presented view controller and the storyboard (if any) that was used to create the view controller. The view controller also asks the views in its view hierarchy to save out any relevant information. However, this class does not automatically save references to any contained child view controllers. If you are implementing a custom container view controller, you must encode the child view controller objects yourself if you want them to be preserved.

Your implementation of this method can encode other restorable view and view controller objects that it needs to reference. Encoding a restorable view or view controller writes that object’s restoration identifier to the coder. That identifier is used during the decode process to locate the new version of the object. If the view or view controller defines its own own version of this method, that method is also called at some point so that the object can encode its own state.

Apart from views and view controllers, other objects follow the normal serialization process and must adopt the NSCoding protocol before they can be encoded. Encoding such objects embeds the object’s contents in the archive directly. During the decode process, a new object is created and initialized with the data from the archive.

Discussion

If you are implementing a custom container controller, use this method to tell the child that the view transition is complete.

Discussion

This is the designated initializer for this class.

The nib file you specify is not loaded right away. It is loaded the first time the view controller’s view is accessed. If you want to perform additional initialization after the nib file is loaded, override the viewDidLoad method and perform your tasks there.

If you specify nil for the nibName parameter and you do not override the loadView method, the view controller searches for a nib file using other means. See nibName.

If your app uses a storyboard to define a view controller and its associated views, your app never initializes objects of that class directly. Instead, view controllers are either instantiated by the storyboard—either automatically by iOS when a segue is triggered or programmatically when your app calls the storyboard object’s instantiateViewControllerWithIdentifier: method. When instantiating a view controller from a storyboard, iOS initializes the new view controller by calling its initWithCoder: method instead. iOS automatically sets the nibName property to a nib file stored inside the storyboard.

For more information about how a view controller loads its view, see “The View Controller Life Cycle”.

Discussion

This method returns YES only when called from inside the following methods:

• viewWillDisappear:

• viewDidDisappear:

Discussion

This method returns YES only when called from inside the following methods:

• viewWillAppear:

• viewDidAppear:

Discussion

This method returns YES only when called from inside the following methods:

• viewWillDisappear:

• viewDidDisappear:

Discussion

This method returns YES only when called from inside the following methods:

• viewWillAppear:

• viewDidAppear:

Discussion

Calling this method reports whether the view is loaded. Unlike the view property, it does not attempt to load the view if it is not already in memory.

Discussion

You should never call this method directly. The view controller calls this method when its view property is requested but is currently nil. This method loads or creates a view and assigns it to the view property.

If the view controller has an associated nib file, this method loads the view from the nib file. A view controller has an associated nib file if the nibName property returns a non-nil value, which occurs if the view controller was instantiated from a storyboard, if you explicitly assigned it a nib file using the initWithNibName:bundle: method, or if iOS finds a nib file in the app bundle with a name based on the view controller’s class name. If the view controller does not have an associated nib file, this method creates a plain UIView object instead.

If you use Interface Builder to create your views and initialize the view controller, you must not override this method.

You can override this method in order to create your views manually. If you choose to do so, assign the root view of your view hierarchy to the view property. The views you create should be unique instances and should not be shared with any other view controller object. Your custom implementation of this method should not call super.

If you want to perform any additional initialization of your views, do so in the viewDidLoad method.

Discussion

Apps normally do not need to trigger segues directly. Instead, you configure an object in Interface Builder associated with the view controller, such as a control embedded in its view hierarchy, to trigger the segue. However, you can call this method to trigger a segue programmatically, perhaps in response to some action that cannot be specified in the storyboard resource file. For example, you might call it from a custom action handler used to process shake or accelerometer events.

The view controller that receives this message must have been loaded from a storyboard. If the view controller does not have an associated storyboard, perhaps because you allocated and initialized it yourself, this method throws an exception.

Discussion

The system calls this method when presenting the view controller full screen. You implement this method when your view controller supports two or more orientations but the content appears best in one of those orientations.

If your view controller implements this method, then when presented, its view is shown in the preferred orientation (although it can later be rotated to another supported rotation). If you do not implement this method, the system presents the view controller using the current orientation of the status bar.

Discussion

The default implementation of this method does nothing. Your view controller overrides this method when it needs to pass relevant data to the new view controller. The segue object describes the transition and includes references to both view controllers involved in the segue.

Because segues can be triggered from multiple sources, you can use the information in the segue and sender parameters to disambiguate between different logical paths in your app. For example, if the segue originated from a table view, the sender parameter would identify the table view cell that the user tapped. You could use that information to set the data on the destination view controller.

Discussion

On iPhone and iPod touch, the presented view is always full screen. On iPad, the presentation depends on the value in the modalPresentationStyle property.

This method sets the presentedViewController property to the specified view controller, resizes that view controller’s view and then adds the view to the view hierarchy. The view is animated onscreen according to the transition style specified in the modalTransitionStyle property of the presented view controller.

The completion handler is called after the viewDidAppear: method is called on the presented view controller.

Discussion

This method is only intended to be called by an implementation of a custom container view controller. If you override this method, you must call super in your implementation.

Discussion

In most cases, the header view is the navigation bar and the footer view is the tab bar. If you are implementing this method in a custom view controller that has its own custom footer view, you can override this method to return that footer view. The view returned from this method should already be part of your view controller’s view hierarchy.

You are responsible for adjusting the size and position of the returned view to match the target orientation. You would make such a change in your view controller’s rotation methods, such as the willAnimateRotationToInterfaceOrientation:duration: method.

Discussion

In most cases, the header view is the navigation bar and the footer view is the tab bar. If you are implementing this method in a custom view controller that has its own custom header view, you can override this method to return that header view. The view returned from this method should already be part of your view controller’s view hierarchy.

You are responsible for adjusting the size and position of the returned view to match the target orientation. You would make such a change in your view controller’s rotation methods, such as the willAnimateRotationToInterfaceOrientation:duration: method.

Discussion

If you implement a custom container view controller that also uses segue unwinding, you must override this method. Your method implementation should instantiate and return a custom segue object that performs whatever animation and other steps that are necessary to unwind the view controllers.

Discussion

Subclasses that use an edit-done button must override this method to change their view to an editable state if editing is YES and a non-editable state if it is NO. This method should invoke super’s implementation before updating its view.

Discussion

View controllers that are managed by a navigation controller can use this method to specify toolbar items for the navigation controller’s built-in toolbar. You can set the toolbar items for your view controller before your view controller is displayed or after it is already visible.

Discussion

This method is called to determine whether to automatically forward appearance-related containment callbacks to child view controllers.

The default implementation returns YES. Subclasses of the UIViewController class that implement containment logic may override this method to control how these methods are forwarded. If you override this method and return NO, you are responsible for telling the child when its views are going to appear or disappear. You do this by calling the child view controller’s beginAppearanceTransition:animated: and endAppearanceTransition methods.

Discussion

This method is called to determine whether to automatically forward rotation-related containment callbacks to child view controllers.

The default implementation returns YES. Subclasses of the UIViewController class that implement containment logic may override this method to control how these methods are forwarded. If you override this method and return NO, you are responsible for forwarding the following methods to child view controllers at the appropriate times:

• willRotateToInterfaceOrientation:duration:

• willAnimateRotationToInterfaceOrientation:duration:

• didRotateFromInterfaceOrientation:

Discussion

Your view controller overrides this method when it wants to control whether a segue should be performed. The default behavior is to permit all segues to be triggered.

Discussion

When the user changes the device orientation, the system calls this method on the root view controller or the topmost presented view controller that fills the window. If the view controller supports the new orientation, the window and view controller are rotated to the new orientation. This method is only called if the view controller’s shouldAutorotate method returns YES.

Override this method to report all of the orientations that the view controller supports. The default values for a view controller’s supported interface orientations is set to UIInterfaceOrientationMaskAll for the iPad idiom and UIInterfaceOrientationMaskAllButUpsideDown for the iPhone idiom.

The system intersects the view controller’s supported orientations with the app's supported orientations (as determined by the Info.plist file or the app delegate's application:supportedInterfaceOrientationsForWindow: method) to determine whether to rotate.

Discussion

This method adds the second view controller’s view to the view hierarchy and then performs the animations defined in your animations block. After the animation completes, it removes the first view controller’s view from the view hierarchy.

This method is only intended to be called by an implementation of a custom container view controller. If you override this method, you must call super in your implementation.

Discussion

You may override this method in a subclass in order to add constraints to the view or its subviews. If you override this method, your implementation must invoke super’s implementation.

Discussion

A custom container view controller should override this method and use it to search its children for a view controller to handle the unwind action. It does this by invoking the canPerformUnwindSegueAction:fromViewController:withSender: method on each child. If a view controller wants to handle the action, your method should return it. If none of the container’s children want to handle the unwind action, invoke the super’s implementation and return the result of that method.

Discussion

You can override this method to perform additional tasks associated with presenting the view. If you override this method, you must call super at some point in your implementation.

Discussion

You can override this method to perform additional tasks associated with dismissing or hiding the view. If you override this method, you must call super at some point in your implementation.

Discussion

When a view’s bounds change, the view adjusts the position of its subviews. Your view controller can override this method to make changes after the view lays out its subviews. The default implementation of this method does nothing.

Discussion

This method is called after the view controller has loaded its view hierarchy into memory. This method is called regardless of whether the view hierarchy was loaded from a nib file or created programmatically in the loadView method. You usually override this method to perform additional initialization on views that were loaded from nib files.

Discussion

This method is called before the receiver’s view is about to be added to a view hierarchy and before any animations are configured for showing the view. You can override this method to perform custom tasks associated with displaying the view. For example, you might use this method to change the orientation or style of the status bar to coordinate with the orientation or style of the view being presented. If you override this method, you must call super at some point in your implementation.

For more information about the how views are added to view hierarchies by a view controller, and the sequence of messages that occur, see “Responding to Display-Related Notifications”.

Discussion

This method is called in response to a view being removed from a view hierarchy. This method is called before the view is actually removed and before any animations are configured.

Subclasses can override this method and use it to commit editing changes, resign the first responder status of the view, or perform other relevant tasks. For example, you might use this method to revert changes to the orientation or style of the status bar that were made in the viewDidDisappear: method when the view was first presented. If you override this method, you must call super at some point in your implementation.

Discussion

When a view’s bounds change, the view adjusts the position of its subviews. Your view controller can override this method to make changes before the view lays out its subviews. The default implementation of this method does nothing.

Discussion

This method is called from within the animation block used to rotate the view. You can override this method and use it to configure additional animations that should occur during the view rotation. For example, you could use it to adjust the zoom level of your content, change the scroller position, or modify other animatable properties of your view.

By the time this method is called, the interfaceOrientation property is already set to the new orientation, and the bounds of the view have been changed. Thus, you can perform any additional layout required by your views in this method.

Discussion

Your view controller can override this method when it needs to know that it has been added to a container.

If you are implementing your own container view controller, it must call the willMoveToParentViewController: method of the child view controller before calling the removeFromParentViewController method, passing in a parent value of nil.

When your custom container calls the addChildViewController: method, it automatically calls the willMoveToParentViewController: method of the view controller to be added as a child before adding it.

Discussion

Subclasses may override this method to perform additional actions immediately prior to the rotation. For example, you might use this method to disable view interactions, stop media playback, or temporarily turn off expensive drawing or live updates. You might also use it to swap the current view for one that reflects the new interface orientation. When this method is called, the interfaceOrientation property still contains the view’s original orientation.

This method is called regardless of whether your code performs one-step or two-step rotations.