iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIStoryboardSegue Class Reference

Options
Deployment Target:

On This Page
Language:

UIStoryboardSegue

A UIStoryboardSegue object is responsible for performing the visual transition between two view controllers. In addition, segue objects are used to prepare for the transition from one view controller to another. Segue objects contain information about the view controllers involved in a transition. When a segue is triggered, but before the visual transition occurs, the storyboard runtime calls the current view controller’s prepareForSegue:sender: method so that it can pass any needed data to the view controller that is about to be displayed.

The UIStoryboardSegue class supports the standard visual transitions available in UIKit. You can also subclass to define custom transitions between the view controllers in your storyboard file.

You do not create segue objects directly. Instead, the storyboard runtime creates them when it must perform a segue between two view controllers. You can still initiate a segue programmatically using the performSegueWithIdentifier:sender: method of UIViewController if you want. You might do so to initiate a segue from a source that was added programmatically and therefore not available in Interface Builder.

Subclassing Notes

You can subclass UIStoryboardSegue in situations where you want to provide a custom transition between view controllers in your application. To use your custom segue, create a segue line between the appropriate view controllers in Interface Builder and set its type to Custom in the inspector; you must also specify the class name of the segue to use in the inspector.

When the storyboard runtime detects a custom segue, it creates a new instance of your class, configures it with the view controller objects, asks the view controller source to prepare for the segue, and then performs the segue.

Methods to Override

For custom segues, the main method you need to override is the perform method. The storyboard runtime calls this method when it is time to perform the visual transition from the view controller in sourceViewController to the view controller in destinationViewController. If you need to initialize any variables in your custom segue subclass, you can also override the initWithIdentifier:source:destination: method and initialize them in your custom implementation.

Alternatives to Subclassing

If your segue does not need to store additional information or provide anything other than aperform method, consider using the segueWithIdentifier:source:destination:performHandler: method instead.

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 5.0 and later.
  • Initializes and returns a storyboard segue object for use in performing a segue.

    Declaration

    Swift

    init!(identifier identifier: String?, source source: UIViewController, destination destination: UIViewController)

    Objective-C

    - (instancetype)initWithIdentifier:(NSString *)identifier source:(UIViewController *)source destination:(UIViewController *)destination

    Parameters

    identifier

    The identifier you want to associate with this particular instance of the segue. You can use this identifier to differentiate one type of segue from another at runtime.

    source

    The view controller visible at the start of the segue.

    destination

    The view controller to display after the completion of the segue.

    Return Value

    An initialized segue object.

    Discussion

    This method is the designated initializer for segue objects. If you subclass UIStoryboardSegue, you can override this method and perform any custom initialization in your implementation. Your implementation should call super first and then proceed if that method does not return nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • The source view controller for the segue. (read-only)

    Declaration

    Swift

    var sourceViewController: AnyObject { get }

    Objective-C

    @property(nonatomic, readonly) id sourceViewController

    Discussion

    This property contains the view controller whose contents are displayed at the beginning of the segue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • The destination view controller for the segue. (read-only)

    Declaration

    Swift

    var destinationViewController: AnyObject { get }

    Objective-C

    @property(nonatomic, readonly) id destinationViewController

    Discussion

    This property contains the view controller whose contents should be displayed at the end of the segue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • The identifier for the segue object. (read-only)

    Declaration

    Swift

    var identifier: String? { get }

    Objective-C

    @property(nonatomic, readonly) NSString *identifier

    Discussion

    You assign identifiers to your segues in Interface Builder. An identifier is a string that your application uses to distinguish one segue from another. For example, if you have a source view controller that can segue to two or more different destination view controllers, you would assign different identifiers to each segue so that the source view controller’s prepareForSegue:sender: method could tell them apart and prepare each segue appropriately.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Performs the visual transition for the segue.

    Declaration

    Swift

    func perform()

    Objective-C

    - (void)perform

    Discussion

    Subclasses override this method and use it to perform the animations from the views in sourceViewController to the views in destinationViewController. Typically, you would use UIKit or Core Animation to set up an animation from one set of views to the next. For more complex animations, you might take a snapshot image of the two view hierarchies and manipulate the images instead of the actual view objects.

    Regardless of how you perform the animation, at the end of it, you are responsible for installing the destination view controller (and its views) in the right place so that it can handle events. For example, if you were to implement a custom modal transition, you might perform your animations using snapshot images and then at the end call the presentModalViewController:animated: method (with animations disabled) to set up the appropriate modal relationship between the source and destination view controllers.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Creates a segue that calls a block to perform the segue transition.

    Declaration

    Swift

    convenience init(identifier identifier: String?, source source: UIViewController, destination destination: UIViewController, performHandler performHandler: () -> Void)

    Objective-C

    + (instancetype)segueWithIdentifier:(NSString *)identifier source:(UIViewController *)source destination:(UIViewController *)destination performHandler:(void (^)(void))performHandler

    Parameters

    identifier

    The identifier you want to associate with this particular instance of the segue. You can use this identifier to differentiate one type of segue from another at runtime.

    source

    The view controller visible at the start of the segue.

    destination

    The view controller to display after the completion of the segue.

    performHandler

    A block to be called when the segue’s perform method is called.

    Return Value

    An initialized segue object.

    Discussion

    You use this method as an alternative to creating a subclass. Your perform handler should do all of the work necessary to transition between the source and destination view controllers, exactly as if you were implementing the perform method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

    See Also

    – perform