UIViewController

Discussion

This is the designated initializer for this class. When using a storyboard to define your view controller and its associated views, you never initialize your view controller class directly. Instead, view controllers are instantiated by the storyboard €”either automatically when a segue is triggered or programmatically when your app calls the instantiateViewControllerWithIdentifier: method of a storyboard object. When instantiating a view controller from a storyboard, iOS initializes the new view controller by calling its initWithCoder: method instead of this method and sets the nibName property to a nib file stored inside the storyboard.

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 as described in the nibName property.

For more information about how a view controller loads its view, see Resource Management in View Controllers.

Discussion

Subclasses can override this method and use it to perform segues conditionally based on current conditions. If you do not implement this method, all segues are performed.

Discussion

The default implementation of this method does nothing. Subclasses override this method and use it to configure the new view controller prior to it being displayed. The segue object contains information about the transition, including references to both view controllers that are involved.

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 then use that information to set the data on the destination view controller.

Discussion

Normally, segues are initiated automatically and not using this method. However, you can use this method in cases where the segue could not be configured in your storyboard file. For example, you might call it from a custom action handler used in response to shake or accelerometer events.

The current view controller must have been loaded from a storyboard. If its storyboard property is nil, perhaps because you allocated and initialized the view controller yourself, this method throws an exception.

Discussion

UIKit calls this method when searching for the destination of an unwind segue. The default implementation returns the contents of the childViewControllers property minus the view controller returned by the childViewControllerContainingSegueSource: method. You can override this method as needed in your custom container view controllers to change the search order. For example, a navigation controller reverses the order so that the search starts with the view controller at the top of the navigation stack.

Discussion

Container view controllers call this method to identify the child view controller that is the source of the unwind segue. Typically, you call this method from your allowedChildViewControllersForUnwindingFromSource: method so that you can remove the corresponding view controller from the returned list of children.

Discussion

When an unwind segue is triggered, UIKit uses this method and the allowedChildViewControllersForUnwindingFromSource: method to locate a suitable view controller to handle the unwind segue.

The default implementation of this method returns YEStrue when the current view controller implements the action method and is not the same view controller as the one in the fromViewController parameter. You can override this method as needed to change the default behavior. For example, you might return NOfalse if the current view controller does not make a suitable return target when unwinding from the specified view controller.

Discussion

During the execution of an unwind segue, UIKit calls this method on any view controllers in the unwind path to give them an opportunity to reconfigure themselves. Container view controllers must implement this method and use to to display the view controller in the subsequentVC parameter. For example, a tab bar controller selects the tab containing the specified view controller. Noncontainer view controllers should not override this method.

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

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

You do not need to override this method for view controllers that are not containers.

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

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

Calling this method loads the view controller’s view from its storyboard file, or creates the view as needed based on the established rules.

Discussion

You use this method to decouple the need to display a view controller from the process of actually presenting that view controller onscreen. Using this method, a view controller does not need to know whether it is embedded inside a navigation controller or split-view controller. It calls the same method for both. The UISplitViewController and UINavigationController classes override this method and handle the presentation according to their design. For example, a navigation controller overrides this method and uses it to push vc onto its navigation stack.

The default implementation of this method calls the targetViewControllerForAction:sender: method to locate an object in the view controller hierarchy that overrides this method. It then calls the method on that target object, which displays the view controller in an appropriate way. If the targetViewControllerForAction:sender: method returns nil, this method uses the window’s root view controller to present vc modally.

You can override this method in custom view controllers to display vc yourself. Use this method to display vc in a primary context. For example, a container view controller might use this method to replace its primary child. Your implementation should adapt its behavior for both regular and compact environments.

Discussion

You use this method to decouple the need to display a view controller from the process of actually presenting that view controller onscreen. Using this method, a view controller does not need to know whether it is embedded inside a navigation controller or split-view controller. It calls the same method for both. In a regular environment, the UISplitViewController class overrides this method and installs vc as its detail view controller; in a compact environment, the split view controller’s implementation of this method calls showViewController:sender: instead.

The default implementation of this method calls the targetViewControllerForAction:sender: method to locate an object in the view controller hierarchy that overrides this method. It then calls the method on that target object, which displays the view controller in an appropriate way. If the targetViewControllerForAction:sender: method returns nil, this method uses the window’s root view controller to present vc modally.

You can override this method in custom view controllers to display vc yourself. Use this method to display vc in a secondary context. For example, a container view controller might use this method to replace its secondary child. Your implementation should adapt its behavior for both regular and compact environments.

Discussion

In a horizontally regular environment, the view controller is presented in the style specified by the modalPresentationStyle property. In a horizontally compact environment, the view controller is presented full screen by default. If you associate an adaptive delegate with the presentation controller associated with the object in viewControllerToPresent, you can modify the presentation style dynamically.

The object on which you call this method may not always be the one that handles the presentation. Each presentation style has different rules governing its behavior. For example, a full-screen presentation must be made by a view controller that itself covers the entire screen. If the current view controller is unable to fulfill a request, it forwards the request up the view controller hierarchy to its nearest parent, which can then handle or forward the request.

Before displaying the view controller, this method resizes the presented view controller'€™s view based on the presentation style. For most presentation styles, the resulting view is then animated onscreen using the transition style in the modalTransitionStyle property of the presented view controller. For custom presentations, the view is animated onscreen using the presented view controller’s transitioning delegate. For current context presentations, the view may be animated onscreen using the current view controller’s transition style.

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

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, UIKit asks the presenting view controller to handle the dismissal.

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 view controller'€™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

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 YEStrue when the modal presentation style of the view controller is set to UIModalPresentationFormSheet and returns NOfalse for other presentation styles. Thus, the system normally does not allow the keyboard to be dismissed for modal forms.

Discussion

When a presentation or dismissal is in progress, this method returns the transition coordinator object associated with that transition. If there is no in-progress transition associated with the current view controller, UIKit checks the view controller’s ancestors for a transition coordinator object and returns that object if it exists. You can use this object to create additional animations and synchronize them with the transition animations.

Container view controllers can override this method but in most cases should not need to. If you do override this method, first call super to see if there is an appropriate transition coordinator to return, and, if there is, return it.

For more information about the role of transition coordinators, see UIViewControllerTransitionCoordinator Protocol Reference.

Discussion

This method returns the current view controller if that view controller overrides the method indicated by the action parameter. If the current view controller does not override that method, UIKit walks up the view hierarchy and returns the first view controller that does override it. If no view controller handles the action, this method returns nil.

A view controller can selectively respond to an action by returning an appropriate value from its canPerformAction:withSender: method.

Discussion

This method is called before the view controller'€™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

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

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

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 before the view lays out its subviews. The default implementation of this method does nothing.

Discussion

When the bounds change for a view controller'€™s view, the view adjusts the positions of its subviews and then the system calls this method. However, this method being called does not indicate that the individual layouts of the view'€™s subviews have been adjusted. Each subview is responsible for adjusting its own layout.

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

Override this method to optimize changes to your constraints.

To schedule a change, call setNeedsUpdateConstraints on the view. The system then calls your implementation of updateViewConstraints before the layout occurs. This lets you verify that all necessary constraints for your content are in place at a time when your properties are not changing.

Your implementation must be as efficient as possible. Do not deactivate all your constraints, then reactivate the ones you need. Instead, your app must have some way of tracking your constraints, and validating them during each update pass. Only change items that need to be changed. During each update pass, you must ensure that you have the appropriate constraints for the app’s current state.

Do not call setNeedsUpdateConstraints inside your implementation. Calling setNeedsUpdateConstraints schedules another update pass, creating a feedback loop.

Discussion

This method returns YEStrue only when called from inside the viewWillDisappear: and viewDidDisappear: methods.

Discussion

This method returns YEStrue only when called from inside the viewWillAppear: and viewDidAppear: methods.

Discussion

This method returns YEStrue only when called from inside the viewWillAppear: and viewDidAppear: methods.

Discussion

This method returns YEStrue only when called from inside the viewWillDisappear: and viewDidDisappear: methods.

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 YEStrue.

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

The system calls this method when presenting the view controller full screen. When your view controller supports two or more orientations but the content appears best in one of those orientations, override this method and return the preferred orientation.

If your view controller implements this method, your view controller’s 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

This method provides default behavior when you do not overwrite the splitViewController:collapseSecondaryViewController:ontoPrimaryViewController: method. The primary view controller associated with the split view controller is displayed.

Discussion

This method provides default behavior when you do not overwrite the splitViewController:separateSecondaryViewControllerFromPrimaryViewController: method. The previous secondary view controller is returned.

Discussion

This method creates a parent-child relationship between the current view controller and the object in the childController parameter. This relationship is necessary when embedding the child view controller’s view into the current view controller’s content. 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

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

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

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

The default implementation returns YEStrue. 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 NOfalse, 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

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

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

Discussion

Normally, traits are passed unmodified from the parent view controller to its child view controllers. When implementing a custom container view controller, you can use this method to change the traits of any embedded child view controllers to something more appropriate for your layout. Making such a change alters other view controller behaviors associated with that child. For example, modal presentations behave differently in a horizontally compact versus horizontally regular environment. You might also make such a change to force the same set of traits on the child view controller regardless of the actual trait environment.

Discussion

Use this method to retrieve the trait collection for a child view controller. You can then modify the trait collection for the designated child view controller and set it using the setOverrideTraitCollection:forChildViewController: 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

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

Do not call this method directly. The system calls this method during the state preservation process to give your view controller or view-controller subclass a chance to save state-related 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. A UIViewController object saves a reference to the presented view controller and to 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 any relevant information. However, a view controller does not automatically save references to 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 objects €”views, view controllers, and objects that adopt the UIStateRestoring protocol, €”using the encodeObject:forKey: method of the provided coder object. Encoding a restorable object writes that object'€™s restoration identifier to the coder. That identifier is then 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.

For objects that are not restorable, encoding the object writes its data (and not a restoration identifier) to the archive. Such objects must adopt the NSCoding protocol. During decoding, the system creates a new object that is initialized with the data from the archive.

Discussion

Do not call this method directly. The system calls this method during the state restoration process so that you can restore your view controller to its previous state.

If your app supports state restoration, 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

After other object decoding has completed, the system calls this method. This allows a view controller to complete setup after other state restoration, relying on the system to ensure that the states of all objects from the restoration archive have been decoded.

Discussion

A preview, or peek in end-user terminology, provides additional content related to the view the user pressed (that is, related to the sourceView view).

Calling this method does three things:

• Registers the previewing view controller (the one that receives this method call) to participate with 3D Touch preview and commit

• Designates the source view, from the receiver’s view hierarchy, as the view to respond to a forceful touch

• Designates a delegate object for mediating the presentation of the preview (peek) and commit (pop) views as a user requests them in turn by pressing more deeply

You can designate more than one source view for a single registered view controller, but you cannot designate a single view as a source view more than once.

The lifetime of this method’s returned context object is managed by the system. If you need to explicitly unregister a view controller, pass its context object to the unregisterForPreviewingWithContext: method. If you do not unregister a view controller, the system automatically unregisters it when the view controller is deallocated.

Discussion

The system calls this method automatically when a 3D Touch-registered view controller is deallocated.

In some circumstances, you must explicitly call this method. This is the case if a registered view controller’s view hierarchy changes state, or if presenting a preview is otherwise no longer possible. In such cases, call this method.

Discussion

This property is for use with a preview (peek) view controller which you present in your implementation of the previewingContext:viewControllerForLocation: delegate method..

Implement this method to provide quick actions for such a preview. When the user swipes upward on the preview, the system presents these quick action items in a sheet below the preview.

The default implementation of this method returns an empty array.

For guidance on appropriate items to include as preview quick actions, read the material on 3D Touch in the iOS Technologies chapter of iOS Human Interface Guidelines.

For more information on preview quick actions, see UIPreviewActionItem Protocol Reference and UIPreviewAction Class Reference.

Discussion

If your container view controller derives derives the hidden state of the status bar from one of its child view controllers, implement this method to specify which child view controller you want to control the hidden/unhidden state. If you return nil or do not override this method, the status bar hidden/unhidden state for self is used.

If you change the return value from this method, call the setNeedsStatusBarAppearanceUpdate method.

Discussion

If your container view controller derives its status bar style from one of its child view controllers, implement this method and return that child view controller. If you return nil or do not override this method, the status bar style for self is used. If the return value from this method changes, call the setNeedsStatusBarAppearanceUpdate method.

Discussion

You can override the preferred status bar style for a view controller by implementing the childViewControllerForStatusBarStyle method.

If the return value from this method changes, call the setNeedsStatusBarAppearanceUpdate method.

Discussion

If you change the return value for this method, call the setNeedsStatusBarAppearanceUpdate method. To specify that a child view controller should control preferred status bar hidden/unhidden state, implement the childViewControllerForStatusBarHidden method.

By default, this method returns NOfalse with one exception. For apps linked against iOS 8 or later, this method returns YEStrue if the view controller is in a vertically compact environment.

Discussion

This property comes into play only when you actively change the status bar’s show/hide state by changing the return value of the prefersStatusBarHidden method.

Discussion

Call this method if the view controller's status bar attributes, such as hidden/unhidden status or style, change. If you call this method within an animation block, the changes are animated along with the rest of the animation block.

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

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

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 NOfalse and a Done button if editing is YEStrue. The default button action invokes the setEditing:animated: method.

Discussion

This method lets you easily add key commands to the view controller without overriding the keyCommands property. The key commands you add to a view controller are applied to the active responder chain. When the user performs a key command, UIKit searches the responder chain (starting with the first responder) for an object capable of handling the specified action.

Discussion

This method lets you easily remove key commands without overriding the keyCommands property.

Discussion

This method can be called at any time to request an ad. If an ad is available, the framework presents it immediately. If there is no ad available, nothing happens.

Use this method along with a presentation style of ADInterstitialPresentationPolicyManual for a view controller that is on screen for long periods of time and internally manages significant state changes, such as game levels. This allows you to decide precisely when it’s possible for an ad to appear in your app.

Discussion

Implement this method on a custom view controller to allow the view controller to selectively prevent presentation of an interstitial ad. When using the automatic presentation policy, the system invokes this method when the framework is about to present an interstitial ad.