UIViewController

Important

This is a preliminary document for an API or technology in development. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein for use on Apple-branded products. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future betas of the API or technology.

The UIViewController class provides the infrastructure for managing the views of your iOS apps. A view controller manages a set of views that make up a portion of your app’s user interface. It is responsible for loading and disposing of those views, for managing interactions with those views, and for coordinating responses with any appropriate data objects. View controllers also coordinate their efforts with other controller objects—including other view controllers—and help manage your app’s overall interface.

You rarely create instances of the UIViewController class directly. Instead, you create instances of UIViewController subclasses and use those objects to provide the specific behaviors and visual appearances that you need.

A view controller’s main responsibilities include the following:

Updating the contents of the views, usually in response to changes to the underlying data.

Responding to user interactions with views.

Resizing views and managing the layout of the overall interface.

A view controller is tightly bound to the views it manages and takes part in the responder chain used to handle events. View controllers are also UIResponder objects and are inserted into the responder chain between the view controller’s root view and that view’s superview, which typically belongs to a different view controller. If none of the view controller’s views handle an event, the view controller has the option of handling the event or passing it along to the superview.

View controllers are rarely used in isolation. Instead, you often use multiple view controllers, each of which owns a portion of your app’s user interface. For example, one view controller might display a table of items while a different view controller displays the selected item from that table. Usually, only the views from one view controller are visible at a time. A view controller may present a different view controller to display a new set of views, or it may act as a container for other view controllers’ content and animate views however it wants.

Subclassing Notes

Every app contains at least one custom subclass of UIViewController. More often, apps contain many custom view controllers. Custom view controllers define the overall behaviors of your app, including the app’s appearance and how it responds to user interactions. The following sections provide a brief overview of some of the tasks your custom subclass performs. For detailed information about using and implementing view controllers, see View Controller Programming Guide for iOS.

View Management

Each view controller manages a view hierarchy, the root view of which is stored in the view property of this class. The root view acts primarily as a container for the rest of the view hierarchy. The size and position of the root view is determined by the object that owns it, which is either a parent view controller or the app’s window. The view controller that is owned by the window is the app’s root view controller and its view is sized to fill the window.

View controllers load their views lazily. Accessing the view property for the first time loads or creates the view controller’s views. There are several ways to specify the views for a view controller:

Specify the view controller and its views in your app’s storyboard file. Storyboards are the preferred way to specify your views. With a storyboard, you specify the views and their connections to the view controller. You also specify the relationships and segues between your view controllers, which makes it easier to see and modify your app's behavior.

Specify the views for a view controller using a nib file. A nib file lets you specify the views of a single view controller but does not let you define segues or relationships between view controllers. The nib file also stores only minimal information about the view controller itself.

To initialize a view controller object using a nib file, create your view controller class programmatically and initialize it using the initWithNibName:bundle: method. When its views are requested, the view controller loads them from the nib file.

Specify the views for a view controller using the loadView method. In that method, create your view hierarchy programmatically and assign the root view of that hierarchy to the view controller’s view property.

All of these techniques have the same end result, which is to create the appropriate set of views and expose them through the view property.

Important

A view controller is the sole owner of its view and any subviews it creates. It is responsible for creating those views and for relinquishing ownership of them at the appropriate times such as when the view controller itself is released. If you use a storyboard or a nib file to store your view objects, each view controller object automatically gets its own copy of these views when the view controller asks for them. However, if you create your views manually, each view controller must have its own unique set of views. You cannot share views between view controllers.

A view controller’s root view is always sized to fit its assigned space. For other views in your view hierarchy, use Interface Builder to specify the Auto Layout constraints that govern how each view is positioned and sized within its superview’s bounds. You can also create constraints programmatically and add them to your views at appropriate times. For more information about how to create constraints, see Auto Layout Guide.

Handling View-Related Notifications

When the visibility of its views changes, a view controller automatically calls its own methods so that subclasses can respond to the change. Use a method like viewWillAppear: to prepare your views to appear onscreen, and use the viewWillDisappear: to save changes or other state information. Use other methods to make appropriate changes.

Figure 1 shows the possible visible states for a view controller’s views and the state transitions that can occur. Not all ‘will’ callback methods are paired with only a ‘did’ callback method. You need to ensure that if you start a process in a ‘will’ callback method, you end the process in both the corresponding ‘did’ and the opposite ‘will’ callback method.

Figure 1Valid State Transitions

Handling View Rotations

In iOS 8, all rotation-related methods are deprecated. Instead, rotations are treated as a change in the size of the view controller’s view and are therefore reported using the viewWillTransitionToSize:withTransitionCoordinator: method. When the interface orientation changes, UIKit calls this method on the window’s root view controller. That view controller then notifies its child view controllers, propagating the message throughout the view controller hierarchy.

In iOS 6 and iOS 7, your app supports the interface orientations defined in your app’s Info.plist file. A view controller can override the supportedInterfaceOrientations method to limit the list of supported orientations. Typically, the system calls this method only on the root view controller of the window or a view controller presented to fill the entire screen; child view controllers use the portion of the window provided for them by their parent view controller and no longer participate directly in decisions about what rotations are supported. The intersection of the app's orientation mask and the view controller's orientation mask is used to determine which orientations a view controller can be rotated into.

At launch time, apps should always set up their interface in a portrait orientation. After the application:didFinishLaunchingWithOptions: method returns, the app uses the view controller rotation mechanism described above to rotate the views to the appropriate orientation prior to showing the window.

Implementing a Container View Controller

A custom UIViewController subclass can also act as a container view controller. A container view controller manages the presentation of content of other view controllers it owns, also known as its child view controllers. A child's view can be presented as-is or in conjunction with views owned by the container view controller.

Your container view controller subclass should declare a public interface to associate its children. The nature of these methods is up to you and depends on the semantics of the container you are creating. You need to decide how many children can be displayed by your view controller at once, when those children are displayed, and where they appear in your view controller's view hierarchy. Your view controller class defines what relationships, if any, are shared by the children. By establishing a clean public interface for your container, you ensure that children use its capabilities logically, without accessing too many private details about how your container implements the behavior.

Your container view controller must associate a child view controller with itself before adding the child's root view to the view hierarchy. This allows iOS to properly route events to child view controllers and the views those controllers manage. Likewise, after it removes a child's root view from its view hierarchy, it should disconnect that child view controller from itself. To make or break these associations, your container calls specific methods defined by the base class. These methods are not intended to be called by clients of your container class; they are to be used only by your container's implementation to provide the expected containment behavior.

Memory Management

Memory is a critical resource in iOS, and view controllers provide built-in support for reducing their memory footprint at critical times. The UIViewController class provides some automatic handling of low-memory conditions through its didReceiveMemoryWarning method, which releases unneeded memory.

State Preservation and Restoration

If you assign a value to the view controller's restorationIdentifier property, the system may ask the view controller to encode itself when the app transitions to the background. When preserved, a view controller preserves the state of any views in its view hierarchy that also have restoration identifiers. View controllers do not automatically save any other state. If you are implementing a custom container view controller, you must encode any child view controllers yourself. Each child you encode must have a unique restoration identifier.

Parameters

The name of the nib file to associate with the view controller. The nib file name should not contain any leading path information. If you specify nil, the nibName property is set to nil.

nibBundle

The bundle in which to search for the nib file. This method looks for the nib file in the bundle's language-specific project directories first, followed by the Resources directory. If this parameter is nil, the method uses the heuristics described below to locate the nib file.

Return Value

A newly initialized UIViewController object.

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.

Declaration

Discussion

This property contains the value specified at initialization time to the initWithNibName:bundle: method. The value of this property may be nil.

If you use a nib file to store your view controller's view, it is recommended that you specify that nib file explicitly when initializing your view controller. However, if you do not specify a nib name, and do not override the loadView method in your custom subclass, the view controller searches for a nib file using other means. Specifically, it looks for a nib file with an appropriate name (without the .nib extension) and loads that nib file whenever its view is requested. Specifically, it looks (in order) for a nib file with one of the following names:

If the view controller class name ends with the word ‘Controller’, as in MyViewController, it looks for a nib file whose name matches the class name without the word ‘Controller’, as in MyView.nib.

It looks for a nib file whose name matches the name of the view controller class. For example, if the class name is MyViewController, it looks for a MyViewController.nib file.

Note

Nib names that include a platform-specific identifier such as ~iphone or ~ipad are loaded only on a device of the corresponding type. For example, a nib name of MyViewController~ipad.nib is loaded only on iPad. If your app supports both platform types, you must provide versions of your nib files for each platform.

Parameters

identifier

The string that identifies the triggered segue. In Interface Builder, you specify the segue’s identifier string in the attributes inspector. This string is used only for locating the segue inside the storyboard.

sender

The object that initiated the segue. This object is made available for informational purposes during the actual segue.

Return Value

YEStrue if the segue should be performed or NOfalse if it should be ignored.

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.

Declaration

Parameters

The segue object containing information about the view controllers involved in the segue.

sender

The object that initiated the segue. You might use this parameter to perform different actions based on which control (or other object) initiated the segue.

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.

Parameters

The string that identifies the triggered segue. In Interface Builder, you specify the segue’s identifier string in the attributes inspector.

This method throws an exception if there is no segue with the specified identifier.

sender

The object that you want to use to initiate the segue. This object is made available for informational purposes during the actual segue.

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.

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.

Parameters

Return Value

A segue object for managing the transitions between the two view controllers.

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

Parameters

Return Value

The view controller that wants to handle the unwind action.

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.

Declaration

Discussion

The view stored in this property represents the root view for the view controller's view hierarchy. The default value of this property is nil.

If you access this property and its value is currently nil, the view controller automatically calls the loadView method and returns the resulting view.

Each view controller object is the sole owner of its view. You must not associate the same view object with multiple view controller objects. The only exception to this rule is that a container view controller implementation may add this view as a subview in its own view hierarchy. Before adding the subview, the container must first call its addChildViewController: method to create a parent-child relationship between the two view controller objects.

Because accessing this property can cause the view to be loaded automatically, you can use the isViewLoaded method to determine if the view is currently in memory. Unlike this property, the isViewLoaded property does not force the loading of the view if it is not currently in memory.

The UIViewController class can automatically set this property to nil during low-memory conditions and also when the view controller itself is finally released.

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

Availability

Declaration

Swift

funcloadView()

Objective-C

- (void)loadView

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.

Availability

Available in iOS 2.0 and later.

See Also

Declaration

Swift

funcviewDidLoad()

Objective-C

- (void)viewDidLoad

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.

See Also

Declaration

Discussion

Set the title to a human-readable string that describes the view. If the view controller has a valid navigation item or tab-bar item, assigning a value to this property updates the title text those objects.

Declaration

Discussion

The value in this property is used primarily when displaying the view controller’s content in a popover but may also be used in other situations. Changing the value of this property while the view controller is being displayed in a popover animates the size change; however, the change is not animated if you specify a width or height of 0.0.

Declaration

Discussion

The presentation style determines how a modally presented view controller is displayed onscreen. In a horizontally compact environment, modal view controllers are always presented full-screen. In a horizontally regular environment, there are several different presentation options. For a list of possible presentation styles, and their compatibility with the available transition styles, see the Modal Presentation Styles constant descriptions.

Declaration

Discussion

The default value of this property is NOfalse. Setting it to YEStrue causes an owning popover controller to disallow interactions outside this view controller while it is displayed. You can use this behavior to ensure that the popover is not dismissed by taps outside the popover controller.

Declaration

Parameters

vc

The view controller to display.

sender

The object that initiated the request.

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.

Declaration

Parameters

vc

The current view controller.

sender

The object being acted upon.

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.

Parameters

The view controller to display over the current view controller’s content.

flag

Pass YEStrue to animate the presentation; otherwise, pass NOfalse.

completion

The block to execute after the presentation finishes. This block has no return value and takes no parameters. You may specify nil for this parameter.

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.

Parameters

The block to execute after the view controller is dismissed. This block has no return value and takes no parameters. You may specify nil for this parameter.

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.

Declaration

Discussion

When using the UIModalPresentationCurrentContext or UIModalPresentationOverCurrentContext style to present a view controller, this property controls which existing view controller in your view controller hierarchy is actually covered by the new content. When a context-based presentation occurs, UIKit starts at the presenting view controller and walks up the view controller hierarchy. If it finds a view controller whose value for this property is YEStrue, it asks that view controller to present the new view controller. If no view controller defines the presentation context, UIKit asks the window’s root view controller to handle the presentation.

The default value for this property is NOfalse. Some system-provided view controllers, such as UINavigationController, change the default value to YEStrue.

Declaration

Discussion

When a view controller’s definesPresentationContext property is YEStrue, it can replace the transition style of the presented view controller with its own. When the value of this property to YEStrue, the current view controller’s transition style is used instead of the style associated with the presented view controller. When the value of this property is NOfalse, UIKit uses the transition style of the presented view controller. The default value of this property is NOfalse.

Declaration

Return Value

YEStrue to prevent the dismissal of the input view or NOfalse if the input view may be dismissed.

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.

Declaration

Discussion

When the view controller’s modalPresentationStyle property is UIModalPresentationCustom, UIKit uses the object in this property to facilitate transitions and presentations for the view controller. The transitioning delegate object is a custom object that you provide and that conforms to the UIViewControllerTransitioningDelegate protocol. Its job is to vend the animator objects used to animate this view controller’s view onscreen and an optional presentation controller to provide any additional chrome and animations.

Declaration

Return Value

The transition coordinator object associated with a currently active transition or nil if no transition is in progress.

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.

Parameters

action

The requested action.

sender

The object sending the request.

Return Value

The view controller that handles the specified action or nil if no view controller handles the action.

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.

Declaration

Discussion

If the view controller or one of its ancestors is managed by a presentation controller, this property contains that object. This property is nil if the view controller is not managed by a presentation controller.

If you have not yet presented the current view controller, accessing this property creates a presentation controller based on the current value in the modalPresentationStyle property. Always set the value of that property before accessing any presentation controllers.

Declaration

Discussion

If the view controller or one of its ancestors is managed by a popover presentation controller, this property contains that object. This property is nil if the view controller is not managed by a popover presentation controller.

If you created the view controller but have not yet presented it, accessing this property creates a popover presentation controller when the value in the modalPresentationStyle property is UIModalPresentationPopover. If the modal presentation style is a different value, this property is nil.

Declaration

Parameters

animated

If YEStrue, the view is being added to the window using an animation.

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.

Declaration

Parameters

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.

Availability

See Also

Called to notify the view controller that its view is about to layout its subviews.

Declaration

Swift

funcviewWillLayoutSubviews()

Objective-C

- (void)viewWillLayoutSubviews

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.

Availability

Called to notify the view controller that its view has just laid out its subviews.

Declaration

Swift

funcviewDidLayoutSubviews()

Objective-C

- (void)viewDidLayoutSubviews

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.

Declaration

Discussion

The bottomLayoutGuide property comes into play when a view controller is frontmost onscreen. It indicates the lowest vertical extent for content that you don't want to appear behind a translucent or transparent UIKit bar (such as a tab bar or toolbar). This property implements the UILayoutSupport protocol and you can employ it as a constraint item when using the NSLayoutConstraint class.

The value of this property is, specifically, the value of the length property of the object returned when you query this property. This value is constrained by either the view controller or by its enclosing container view controller (such as a navigation or tab bar controller), as follows:

A view controller not within a container view controller constrains this property to indicate the top of the tab bar or toolbar, if one of these is visible, or else to indicate the bottom edge of the view controller's view.

A view controller within a container view controller does not set this property’s value. Instead, the container view controller constrains the value to indicate the top of the tab bar or toolbar, if one of these is visible, or else to indicate the bottom edge of the view controller's view.

If a container view controller's toolbar or tab bar is visible and opaque, the container lays out the frontmost view controller's view so its bottom edge abuts the top of the bar. In this case, the value of this property is 0.

When laying out a storyboard scene, the Bottom Layout Guide object is available in the Interface Builder outline view as a child of the View Controller object. Adding a bottom layout guide using Interface Builder provides backward layout compatibility to iOS 6.

As an example of how to programmatically use this property with Auto Layout, say you want to position a control such that its bottom edge is 20 points above the bottom layout guide. This scenario applies to any of the scenarios listed above. Use code similar to the following:

[self.viewlayoutSubviews];// You must call this method here or the system raises an exception

Important

If you define Auto Layout constraints in a storyboard file as well as programmatically, it is your responsibility to ensure the constraints do not conflict. If they do conflict, the system may throw a runtime exception.

To use a bottom layout guide without using constraints, obtain the guide’s position relative to the bottom bound of the containing view. In the case of using a view controller subclass, obtain the numbers you need as follows:

-(void)viewDidLayoutSubviews{

CGRectviewBounds=self.view.bounds;

CGFloatbottomBarOffset=self.bottomLayoutGuide.length;

}

In the case of using a view subclass, obtain the numbers you need as follows:

-(void)layoutSubviews{

[superlayoutSubviews];// You must call super here or the system raises an exception

Declaration

Discussion

The topLayoutGuide property comes into play when a view controller is frontmost onscreen. It indicates the highest vertical extent for content that you don't want to appear behind a translucent or transparent UIKit bar (such as a status or navigation bar). This property implements the UILayoutSupport protocol and you can employ it as a constraint item when using the NSLayoutConstraint class.

The value of this property is, specifically, the value of the length property of the object returned when you query this property. This value is constrained by either the view controller or by its enclosing container view controller (such as a navigation or tab bar controller), as follows:

A view controller not within a container view controller constrains this property to indicate the bottom of the status bar, if visible, or else to indicate the top edge of the view controller's view.

A view controller within a container view controller does not set this property's value. Instead, the container view controller constrains the value to indicate:

The bottom of the navigation bar, if a navigation bar is visible

The bottom of the status bar, if only a status bar is visible

The top edge of the view controller's view, if neither a status bar nor navigation bar is visible

If a container navigation controller's navigation bar is visible and opaque, the navigation controller lays out the frontmost view controller's view so its top edge abuts the bottom of the navigation bar. In this case, the value of this property is 0.

When laying out a storyboard scene, the Top Layout Guide object is available in the Interface Builder outline view as a child of the View Controller object. Adding a top layout guide using Interface Builder provides backward compatibility to iOS 6.

As an example of how to programmatically use this property with Auto Layout, say you want to position a control such that its top edge is 20 points below the top layout guide. This scenario applies to any of the scenarios listed above. Use code similar to the following:

[self.viewlayoutSubviews];// You must call this method here or the system raises an exception

Important

If you define Auto Layout constraints in a storyboard file as well as programmatically, it is your responsibility to ensure the constraints do not conflict. If they do conflict, the system may throw a runtime exception.

To use a top layout guide without using constraints, obtain the guide’s position relative to the top bound of the containing view. In the case of using a view controller subclass, obtain the numbers you need as follows:

-(void)viewDidLayoutSubviews{

CGRectviewBounds=self.view.bounds;

CGFloattopBarOffset=self.topLayoutGuide.length;

}

In the case of using a view subclass, obtain the numbers you need as follows:

-(void)layoutSubviews{

[superlayoutSubviews];// You must call super here or the system raises an exception

Declaration

Discussion

This property is applied only to view controllers that are embedded in a container such as UINavigationController. The window’s root view controller does not react to this property. The default value of this property is UIRectEdgeAll.

Declaration

Discussion

The default value of this property is YEStrue, which allows the view controller to adjust its scroll view insets in response to the screen areas consumed by the status bar, navigation bar, and toolbar or tab bar. Set to NOfalse if you want to manage scroll view inset adjustments yourself, such as when there is more than one scroll view in the view hierarchy.

Declaration

Return Value

A bit mask specifying which orientations are supported. See UIInterfaceOrientationMask for valid bit-mask values. The value returned by this method must not be 0.

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.

Declaration

Return Value

The interface orientation with which to present the view controller.

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.

Availability

Declaration

Swift

classfuncattemptRotationToDeviceOrientation()

Objective-C

+ (void)attemptRotationToDeviceOrientation

Discussion

Some view controllers may want to use app-specific conditions to determine what interface orientations are supported. If your view controller does this, when those conditions change, your app should call this class method. The system immediately attempts to rotate to the new orientation.

Declaration

Parameters

childController

The view controller to be added as a child.

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.

Parameters

A view controller whose view is currently visible in the parent's view hierarchy.

toViewController

A child view controller whose view is not currently in the view hierarchy.

duration

The total duration of the animations, in seconds. If you pass zero, the changes are made without animating them.

options

A mask of options indicating how you want to perform the animations. For a list of valid constants, see UIViewAnimationOptions.

animations

A block object containing the changes to commit to the views. Here you programmatically change any animatable properties of the views in your view hierarchy. This block takes no parameters and has no return value. This parameter must not be NULL.

completion

A block to be called when the animation completes.

The block takes the following parameters:

finished

YEStrue if the animation finished; NOfalse if it was skipped.

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.

Declaration

Return Value

YEStrue if appearance methods are forwarded or NOfalse if they are not.

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.

Parameters

collection

The new traits to apply to the child view controller.

childViewController

The child view controller who’s trait collection is to be changed.

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.

Declaration

Parameters

parent

The parent view controller, or nil if there is no parent.

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.

Declaration

Parameters

parent

The parent view controller, or nil if there is no parent.

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.

Declaration

Discussion

When you present a view controller modally (either explicitly or implicitly) using the presentViewController:animated:completion: method, the view controller that was presented has this property set to the view controller that presented it. If the view controller was not presented modally, but one of its ancestors was, this property contains the view controller that presented the ancestor. If neither the current view controller or any of its ancestors were presented modally, the value in this property is nil.

Declaration

Discussion

When you present a view controller modally (either explicitly or implicitly) using the presentViewController:animated:completion: method, the view controller that called the method has this property set to the view controller that it presented. If the current view controller did not present another view controller modally, the value in this property is nil.

Declaration

Discussion

If the recipient is a child of a container view controller, this property holds the view controller it is contained in. If the recipient has no parent, the value in this property is nil.

Prior to iOS 5.0, if a view did not have a parent view controller and was being presented, the presenting view controller would be returned. On iOS 5, this behavior no longer occurs. Instead, use the presentingViewController property to access the presenting view controller.

Declaration

Discussion

If the view controller or one of its ancestors is a child of a navigation controller, this property contains the owning navigation controller. This property is nil if the view controller is not embedded inside a navigation controller.

Declaration

Discussion

If the view controller or one of its ancestors is a child of a split view controller, this property contains the owning split view controller. This property is nil if the view controller is not embedded inside a split view controller.

Declaration

Discussion

If the view controller or one of its ancestors is a child of a tab bar controller, this property contains the owning tab bar controller. This property is nil if the view controller is not embedded inside a tab bar controller.

Declaration

Discussion

This property indicates whether the view controller and its contents should be preserved and is used to identify the view controller during the restoration process. The value of this property is nil by default, which indicates that the view controller should not be saved. Assigning a string object to the property lets the system know that the view controller should be saved. In addition, the contents of the string are your way to identify the purpose of the view controller.

During subsequent launches, UIKit asks your app for help in recreating the view controllers that were installed the last time your app ran. When it asks for a specific view controller, UIKit provides your app with this restoration identifier and the restoration identifiers of any parent view controllers in the view controller hierarchy. Your app must use this information to create or locate the appropriate view controller object.

Important

Simply setting the value of this property is not enough to ensure that the view controller is preserved and restored. All parent view controllers must also have a restoration identifier. For more information about the preservation and restoration process, see View Controller Programming Guide for iOS.

Declaration

Discussion

If a view controller has an associated restoration class, the viewControllerWithRestorationIdentifierPath:coder: method of that class is called during state restoration. That method is responsible for returning the view controller object that matches the indicated view controller. If you do not specify a restoration class for your view controller, the state restoration engine asks your app delegate to provide the view controller object instead.

Declaration

Parameters

coder

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

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.

Important

This method is not a substitute for saving your app's data structures persistently to disk. You should continue to save your app's actual data to iCloud or the local file system using existing techniques. This method is intended only for saving configuration state or other information related to your app's user interface. You should consider any data you write to the coder as purgeable and be prepared for it to be unavailable during subsequent launches.

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.

Parameters

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.

Availability

See Also

Called on restored view controllers after other object decoding is complete.

Declaration

Swift

funcapplicationFinishedRestoringState()

Objective-C

- (void)applicationFinishedRestoringState

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.

Declaration

Discussion

The view controller can check this property to see if it participates in an extension request. If no extension context is set for the current view controller, the system walks up the view controller hierarchy to find a parent view controller that has a non nilextensionContext value.

Return Value

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.

Declaration

Return Value

The view controller whose status bar style should be used.

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.

Availability

Indicates to the system that the view controller status bar attributes have changed.

Declaration

Swift

funcsetNeedsStatusBarAppearanceUpdate()

Objective-C

- (void)setNeedsStatusBarAppearanceUpdate

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.

Declaration

Discussion

This is a unique instance of UINavigationItem created to represent the view controller when it is pushed onto a navigation controller. The first time the property is accessed, the UINavigationItem object is created. Therefore, you should not access this property if you are not using a navigation controller to display the view controller. To ensure the navigation item is configured, you can either override this property and add code to create the bar button items when first accessed or create the items in your view controller's initialization code.

Avoid tying the creation of bar button items in your navigation item to the creation of your view controller's view. The navigation item of a view controller may be retrieved independently of the view controller's view. For example, when pushing two view controllers onto a navigation stack, the topmost view controller becomes visible, but the other view controller's navigation item may be retrieved in order to present its back button.

The default behavior is to create a navigation item that displays the view controller's title.

Declaration

Discussion

A view controller added as a child of a navigation controller can display an optional toolbar at the bottom of the screen. The value of this property on the topmost view controller determines whether the toolbar is visible. If the value of this property is YEStrue, the toolbar is hidden. If the value of this property is NOfalse, the bar is visible.

Declaration

Parameters

toolbarItems

The toolbar items to display in a built-in toolbar.

animated

If YEStrue, animate the change of items in the toolbar.

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.

Declaration

Discussion

This property contains an array of UIBarButtonItem objects and works in conjunction with a UINavigationController object. If this view controller is embedded inside a navigation controller interface, and the navigation controller displays a toolbar, this property identifies the items to display in that toolbar.

You can set the value of this property explicitly or use the setToolbarItems:animated: method to animate changes to the visible set of toolbar items.

Declaration

Discussion

This is a unique instance of UITabBarItem created to represent the view controller when it is a child of a tab bar controller. The first time the property is accessed, the UITabBarItem is created. Therefore, you should not access this property if you are not using a tab bar controller to display the view controller. To ensure the tab bar item is configured, you can either override this property and add code to create the bar button items when first accessed or create the items in your view controller's initialization code.

The default value is a tab bar item that displays the view controller's title.

Declaration

Discussion

If YEStrue, the view controller currently allows editing; otherwise, NOfalse.

If the view is editable and the associated navigation controller contains an edit-done button, then a Done button is displayed; otherwise, an Edit button is displayed. Clicking either button toggles the state of this property. Add an edit-done button by setting the custom left or right view of the navigation item to the value returned by the editButtonItem method. Set the editing property to the initial state of your view. Use the setEditing:animated: method as an action method to animate the transition of this state if the view is already displayed.

Declaration

Parameters

editing

If YEStrue, the view controller should display an editable view; otherwise, NOfalse.

If YEStrue and one of the custom views of the navigationItem property is set to the value returned by the editButtonItem method, the associated navigation controller displays a Done button; otherwise, an Edit button.

animated

If YEStrue, animates the transition; otherwise, does not.

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.

Declaration

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.

Availability

See Also

Deprecation Statement

Views are no longer purged under low-memory conditions and so this method is never called.

Declaration

Objective-C

- (void)viewWillUnload

Discussion

In iOS 5 and earlier, when a low-memory condition occurred and the current view controller's views were not needed, the system could opt to remove those views from memory. This method was called prior to releasing the actual views so you could perform any cleanup prior to the view being deallocated. For example, you could use this method to remove views as observers of notifications or record the state of the views so it can be reestablished when the views are reloaded.

In iOS 6 and later, clearing references to views is no longer necessary. As a result, any other cleanup related to those views, such as removing them as observers, is also not necessary.

At the time this method is called, the view property is still valid (it has not yet been set to nil).

Availability

Deprecation Statement

Views are no longer purged under low-memory conditions and so this method is never called.

Declaration

Objective-C

- (void)viewDidUnload

Discussion

In iOS 5 and earlier, when a low-memory condition occurred and the current view controller's views were not needed, the system could opt to call this method after the view controller's view had been released. This method was your chance to perform any final cleanup. If your view controller stored separate references to the view or its subviews, you could use this method to release those references. You could also use this method to remove references to any objects that you created to support the view but that are no longer needed now that the view is gone. You would not use this method to release user data or any other information that cannot be easily recreated.

In iOS 6 and later, clearing references to views and other objects in your view controller is unnecessary.

Deprecation Statement

Declaration

Discussion

This property contains the desired size for the view controller when it is displayed in a popover. By default, the width is set to 320 points and the height is set to 1100 points. You can change these values as needed.

The recommended width for popovers is 320 points. If needed, you can return a width value as large as 600 points, but doing so is not recommended.

If the popover controller displaying the view controller sets its popoverContentSize property, the popover controller overrides the values set in the view controller's contentSizeForViewInPopover property.

Parameters

If YEStrue, animates the view as it's presented; otherwise, does not.

Discussion

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

Sets the modalViewController property to the specified view controller. Resizes its view and attaches it to the view hierarchy. The view is animated according to the transition style specified in the modalTransitionStyle property of the controller in the modalViewController parameter.

Deprecation Statement

Declaration

Objective-C

- (void)dismissModalViewControllerAnimated:(BOOL)animated

Parameters

animated

If YEStrue, this method animates the view as it's dismissed; otherwise, it does not. The style of animation is determined by the value in the modalTransitionStyle property of the view controller being dismissed.

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, however, it automatically forwards the message to the presenting view controller.

If you present several view controllers in succession, and thus build 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 modalViewController property before calling this method.

Deprecation Statement

Declaration

Objective-C

@property(nonatomic,assign)BOOLwantsFullScreenLayout

Discussion

When a view controller presents its view, it normally shrinks that view so that its frame does not overlap the device’s status bar. Setting this property to YEStrue causes the view controller to size its view so that it fills the entire screen, including the area under the status bar. (Of course, for this to happen, the window hosting the view controller must itself be sized to fill the entire screen, including the area underneath the status bar.) You would typically set this property to YEStrue in cases where you have a translucent status bar and want your view's content to be visible behind that view.

If this property is YEStrue, the view is not resized in a way that would cause it to underlap a tab bar but is resized to underlap translucent toolbars. Regardless of the value of this property, navigation controllers always allow views to underlap translucent navigation bars.

The default value of this property is NOfalse, which causes the view to be laid out so it does not underlap the status bar.

Declaration

Parameters

The orientation of the app's user interface after the rotation. The possible values are described in UIInterfaceOrientation.

Return Value

YEStrue if the view controller auto-rotates its view to the specified orientation; otherwise, NOfalse.

Discussion

By default, this method returns YEStrue for the UIInterfaceOrientationPortrait orientation only. If your view controller supports additional orientations, override this method and return YEStrue for all orientations it supports.

Your implementation of this method should simply return YEStrue or NOfalse based on the value in the interfaceOrientation parameter. Do not attempt to get the value of the interfaceOrientation property or check the orientation value reported by the UIDevice class. Your view controller is either capable of supporting a given orientation or it is not.

Deprecation Statement

Declaration

Return Value

The header view or nil if there is no header view. If the current view controller is a tab bar controller, this method returns the header view of the view controller in the selected tab. If the current view controller is a navigation controller, this method returns the associated navigation bar.

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.

Deprecation Statement

Declaration

Return Value

The footer view.

If the view controller is a tab bar controller, returns a view containing the tab bar. If the view controller is a navigation controller, returns the top view controller's footer view. The default implementation returns nil.

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.

Parameters

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. Your implementation of this method must call super at some point during its execution.

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

Parameters

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.

Note

The animations used to slide the header and footer views in and out of position are performed in separate animation blocks.

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.

Parameters

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. Your implementation of this method must call super at some point during its execution.

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

Declaration

Parameters

The state of the app's user interface orientation before the rotation. The possible values are described in UIInterfaceOrientation.

duration

The duration of the first half of the pending rotation, measured in seconds.

Discussion

The default implementation of this method does nothing.

This method is called from within the animation block used to rotate the view and slide the header and footer views out. You can override this method and use it to configure additional animations that should occur during the first half of 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.

At the time this method is called, the interfaceOrientation property is still set to the old orientation.

Declaration

Parameters

toInterfaceOrientation

The state of the app's user interface orientation after the rotation. The possible values are described in the UIInterfaceOrientation enum.

Discussion

This method is called during two-step rotation animations only. Subclasses can override this method and use it to adjust their views between the first and second half of the animations. This method is called outside of any animation transactions and while any header or footer views are offscreen.

Declaration

Parameters

The state of the app's user interface orientation before the rotation. The possible values are described in the UIInterfaceOrientation enum.

duration

The duration of the second half of the pending rotation, measured in seconds.

Discussion

The default implementation of this method does nothing.

This method is called from inside the animation block used to finish the view rotation and slide the header and footer views back into position. You can override this method and use it to configure additional animations that should occur during the second half of 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.

At the time this method is invoked, the interfaceOrientation property is set to the new orientation.

Declaration

Discussion

This property reflects the value of the searchDisplayController outlet that you set in Interface Builder. If you create your search display controller programmatically, this property is set automatically by the search display controller when it is initialized.

Return Value

Discussion

This method is called to determine whether to automatically forward rotation-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 forwarding the following methods to child view controllers at the appropriate times:

Declaration

Return Value

A Boolean value that indicates whether appearance and rotation methods are forwarded.

Discussion

This method is called to determine whether to automatically forward containment callbacks to the 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 forwarding the following methods to child view controllers at the appropriate times:

Constants

A presentation style in which the presented view covers the screen. The views belonging to the presenting view controller are removed after the presentation completes.

Available in iOS 3.2 and later.

PageSheet

UIModalPresentationPageSheet

In a horizontally regular environment, a presentation style that partially covers the underlying content. The presented view's width is set to the width of the screen in a portrait orientation and the the height is set to the height of the screen. Any uncovered areas are dimmed to prevent the user from interacting with them. (In portrait orientations, this option is essentially the same as UIModalPresentationFullScreen.)

In a horizontally compact environment, this option behaves the same as UIModalPresentationFullScreen.

Available in iOS 3.2 and later.

FormSheet

UIModalPresentationFormSheet

In a horizontally regular environment, a presentation style that displays the content centered in the screen. The width and height of the content area are smaller than the screen size and a dimming view is placed underneath the content. If the device is in a landscape orientation and the keyboard is visible, the position of the view is adjusted upward so that the view remains visible. All uncovered areas are dimmed to prevent the user from interacting with them.

In a horizontally compact environment, this option behaves the same as UIModalPresentationFullScreen.

Available in iOS 3.2 and later.

CurrentContext

UIModalPresentationCurrentContext

A presentation style where the content is displayed over a view controller’s content whose definesPresentationContext property is YEStrue. UIKit may walk up the view controller hierarchy to find a view controller that wants to define the presentation context. The views belonging to the presenting view controller are removed after the presentation completes.

When presenting a view controller in a popover, this presentation style is supported only if the transition style is UIModalTransitionStyleCoverVertical. Attempting to use a different transition style triggers an exception. However, you may use other transition styles (except the partial curl transition) if the parent view controller is not in a popover.

Available in iOS 3.2 and later.

Custom

UIModalPresentationCustom

A custom view presentation style that is managed by a custom presentation controller and one or more custom animator objects. All of these objects are provided by the presented view controller’s transitioning delegate, which is an object that conforms to the UIViewControllerTransitioningDelegate protocol. Before presenting a view controller using this style, set the view controller’s transitioningDelegate property to your custom transitioning delegate.

Available in iOS 7.0 and later.

OverFullScreen

UIModalPresentationOverFullScreen

A view presentation style in which the presented view covers the screen. The views beneath the presented content are not removed from the view hierarchy when the presentation finishes. So if the presented view controller does not fill the screen with opaque content, the underlying content shows through.

Available in iOS 8.0 and later.

OverCurrentContext

UIModalPresentationOverCurrentContext

A presentation style where the content is displayed over a view controller’s content whose definesPresentationContext property is YEStrue. UIKit may walk up the view controller hierarchy to find a view controller that wants to define the presentation context. The views beneath the presented content are not removed from the view hierarchy when the presentation finishes. So if the presented view controller does not fill the screen with opaque content, the underlying content shows through.

When presenting a view controller in a popover, this presentation style is supported only if the transition style is UIModalTransitionStyleCoverVertical. Attempting to use a different transition style triggers an exception. However, you may use other transition styles (except the partial curl transition) if the parent view controller is not in a popover.

Available in iOS 8.0 and later.

Popover

UIModalPresentationPopover

In a horizontally regular environment, a presentation style where the content is displayed in a popover view. The background content is dimmed and taps outside the popover cause the popover to be dismissed. If you do not want taps to dismiss the popover, you can assign one or more views to the passthroughViews property of the associated UIPopoverPresentationController object, which you can get from the popoverPresentationController property.

In a horizontally compact environment, this option behaves the same as UIModalPresentationFullScreen.

Available in iOS 8.0 and later.

None

UIModalPresentationNone

A presentation style that indicates no adaptations should be made. Do not use this style to present a view controller. Instead, return it from the adaptivePresentationStyleForPresentationController: method of an adaptive delegate when you do not want a presentation controller to adapt the style of an already presented view controller.

Constants

When the view controller is presented, its view slides up from the bottom of the screen. On dismissal, the view slides back down. This is the default transition style.

Available in iOS 3.0 and later.

FlipHorizontal

UIModalTransitionStyleFlipHorizontal

When the view controller is presented, the current view initiates a horizontal 3D flip from right-to-left, resulting in the revealing of the new view as if it were on the back of the previous view. On dismissal, the flip occurs from left-to-right, returning to the original view.

Available in iOS 3.0 and later.

CrossDissolve

UIModalTransitionStyleCrossDissolve

When the view controller is presented, the current view fades out while the new view fades in at the same time. On dismissal, a similar type of cross-fade is used to return to the original view.

Available in iOS 3.0 and later.

PartialCurl

UIModalTransitionStylePartialCurl

When the view controller is presented, one corner of the current view curls up to reveal the presented view underneath. On dismissal, the curled up page unfurls itself back on top of the presented view. A view controller presented using this transition is itself prevented from presenting any additional view controllers.

This transition style is supported only if the parent view controller is presenting a full-screen view and you use the UIModalPresentationFullScreen modal presentation style. Attempting to use a different form factor for the parent view or a different presentation style triggers an exception.

Declaration

Constants

UIViewControllerHierarchyInconsistencyException

UIViewControllerHierarchyInconsistencyException

Raised if the view controller hierarchy is inconsistent with the view hierarchy.

When a view controller's view is added to the view hierarchy, the system walks up the view hierarchy to find the first parent view that has a view controller. That view controller must be the parent of the view controller whose view is being added. Otherwise, this exception is raised. This consistency check is also performed when a view controller is added as a child by calling the addChildViewController: method.

It is also allowed for a view controller that has no parent to add its view to the view hierarchy. This is generally not recommended, but is useful in some special cases.

When a view controller is using showViewController:sender: or showDetailViewController:sender:, it may need to know when a split view controller higher in the view hierarchy has changed. This notification is sent when a split view controller expands or collapses. The object of this notification is the view controller that caused the change.