Enter and exit full screen (iOS)

Full-screen mode enables viewers to expand the player to fill up the entire device screen.

When using JWPlayerViewController or JWPlayerObjCViewController, full screen can be entered and exited in several ways.

Approach	Description
Automatic	Full screen engaged automatically when device orientation changes from portait to landscape if `forceFullScreenOnLandscape` on `JWPlayerViewController` is `true`
Manual	Full screen engaged by viewer tapping the full screen icon ( )
Programmatic	Full screen engaged by calling `transitionToFullScreen` and `dismissFullScreen` methods on the view controller

📘
If you are only using JWPlayerView, you must implement full screen capability yourself or display the view in full screen with your own interface.

Programmatically enter and exit full screen

The transitionToFullScreen and dismissFullScreen methods can be used on either the JWPlayerViewController or JWPlayerObjCViewController to enter and exit full screen programmatically.

The following recipe shows how to use these methods in a class that has a full-screen toggle to enter and exit full-screen mode.

transitionToFullScreen()

Transitions the player to full-screen mode

If the player is already in full-screen mode, this method does not perform any actions. The completion closure will not be executed.

public func transitionToFullScreen(animated: Bool, completion: (() -> Void)? = nil)

- (void)transitionToFullScreenAnimated:(BOOL)animated completion:(void (^)(void))completion;

Argument	Description
`animated` Bool	Determines if the player should animate into full screen
`completion`	Closure called after the player has transitioned to full-screen mode

dismissFullScreen()

Transitions the player away from full-screen mode

If the player is not in full-screen mode this method does not perform any actions. The completion closure will not be executed.

public func dismissFullScreen(animated: Bool, completion: (() -> Void)? = nil)

- (void)dismissFullScreenAnimated:(BOOL)animated completion:(void (^)(void))completion;

Argument	Description
`animated` Bool	Determines if the player should animate away from full-screen mode
`completion` Closure	Closure called after the player has transitioned away from full-screen mode

Respond to Full-Screen Events

Use JWPlayerViewControllerFullScreenDelegate to respond to fullscreen transitions. Assign the delegate to the view controller's fullScreenDelegate property.

📘
As of iOS SDK 4.28.0, new optional dismiss callbacks include a JWFullScreenExitReason parameter. The existing callbacks remain available. For each dismissal phase, the callback without a reason is called before the corresponding callback with a reason.

class CustomPlayerViewController: JWPlayerViewController, JWPlayerViewControllerFullScreenDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set the JWPlayerViewControllerFullScreenDelegate to self
        fullScreenDelegate = self
    }

    // MARK: - JWPlayerViewControllerFullScreenDelegate

    func playerViewControllerWillGoFullScreen(_ controller: JWPlayerViewController) -> JWFullScreenViewController? {
        return nil
    }

    func playerViewControllerDidGoFullScreen(_ controller: JWPlayerViewController) {

    }

    func playerViewControllerWillDismissFullScreen(_ controller: JWPlayerViewController) {

    }

    func playerViewControllerDidDismissFullScreen(_ controller: JWPlayerViewController) {

    }

    func playerViewControllerWillDismissFullScreen(
        _ controller: JWPlayerViewController,
        reason: JWFullScreenExitReason
    ) {
        // Prepare for dismissal using the reported reason.
    }

    func playerViewControllerDidDismissFullScreen(
        _ controller: JWPlayerViewController,
        reason: JWFullScreenExitReason
    ) {
        switch reason {
        case .userTappedDismissButton:
            print("Dedicated dismiss button")
        case .userTappedToggleButton:
            print("Fullscreen toggle")
        case .external:
            print("Programmatic dismissal")
        default:
            print("Other fullscreen exit reason")
        }
    }
}

// CustomViewController.h
@interface CustomViewController : JWPlayerObjCViewController <JWPlayerViewControllerFullScreenDelegate>

@end

// CustomViewController.m

@implementation CustomViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Set the JWPlayerViewControllerFullScreenDelegate to self
    self.fullScreenDelegate = self;
}

#pragma mark JWPlayerViewControllerFullScreenDelegate

- (JWFullScreenViewController * _Nullable)playerViewControllerWillGoFullScreen:(JWPlayerViewController * _Nonnull)controller {
    return nil;
}

- (void)playerViewControllerDidGoFullScreen:(JWPlayerViewController * _Nonnull)controller {

}

- (void)playerViewControllerWillDismissFullScreen:(JWPlayerViewController * _Nonnull)controller {

}

- (void)playerViewControllerDidDismissFullScreen:(JWPlayerViewController * _Nonnull)controller {

}

- (void)playerViewControllerWillDismissFullScreen:(JWPlayerViewController * _Nonnull)controller
                                           reason:(JWFullScreenExitReason)reason {
    // Prepare for dismissal using the reported reason.
}

- (void)playerViewControllerDidDismissFullScreen:(JWPlayerViewController * _Nonnull)controller
                                          reason:(JWFullScreenExitReason)reason {
    switch (reason) {
        case JWFullScreenExitReasonUserTappedDismissButton:
            NSLog(@"Dedicated dismiss button");
            break;
        case JWFullScreenExitReasonUserTappedToggleButton:
            NSLog(@"Fullscreen toggle");
            break;
        case JWFullScreenExitReasonExternal:
            NSLog(@"Programmatic dismissal");
            break;
        default:
            NSLog(@"Other fullscreen exit reason");
            break;
    }
}

@end

playerViewControllerWillGoFullScreen()

Called before the player is enlarged to the size of the screen

This method returns the JWFullScreenViewController that will be used for full screen. If nil is returned, the default JWFullScreenViewController will be used.

func playerViewControllerWillGoFullScreen(_ controller: JWPlayerViewController) -> JWFullScreenViewController? {
        return nil
    }

- (JWFullScreenViewController * _Nullable)playerViewControllerWillGoFullScreen:(JWPlayerViewController * _Nonnull)controller {
    return nil;
}

Argument	Description
`controller` JWPlayerViewController	`JWPlayerViewController` emitting the event

playerViewControllerDidGoFullScreen()

Called after the player has enlarged to the size of the screen

func playerViewControllerDidGoFullScreen(_ controller: JWPlayerViewController) {}

- (void)playerViewControllerDidGoFullScreen:(JWPlayerViewController * _Nonnull)controller {}

Argument	Description
`controller` JWPlayerViewController	`JWPlayerViewController` emitting the event

playerViewControllerWillDismissFullScreen()

Called before the player exits fullscreen

In iOS SDK 4.28.0 and later, playerViewControllerWillDismissFullScreen(_:reason:) also reports what caused the dismissal. See JWFullScreenExitReason for possible values.

func playerViewControllerWillDismissFullScreen(_ controller: JWPlayerViewController) {}

func playerViewControllerWillDismissFullScreen(
    _ controller: JWPlayerViewController,
    reason: JWFullScreenExitReason
) {}

- (void)playerViewControllerWillDismissFullScreen:(JWPlayerViewController * _Nonnull)controller {
    
}

- (void)playerViewControllerWillDismissFullScreen:(JWPlayerViewController * _Nonnull)controller
                                           reason:(JWFullScreenExitReason)reason {
    
}

Argument	Description
`controller` JWPlayerViewController	`JWPlayerViewController` emitting the event
`reason` JWFullScreenExitReason	Cause of the full-screen dismissal

playerViewControllerDidDismissFullScreen()

Called after the player exits fullscreen

In iOS SDK 4.28.0 and later, playerViewControllerDidDismissFullScreen(_:reason:) also reports what caused the dismissal. See JWFullScreenExitReason for possible values.

func playerViewControllerDidDismissFullScreen(_ controller: JWPlayerViewController) {}

func playerViewControllerDidDismissFullScreen(
    _ controller: JWPlayerViewController,
    reason: JWFullScreenExitReason
) {}

- (void)playerViewControllerDidDismissFullScreen:(JWPlayerViewController * _Nonnull)controller {
    
}

- (void)playerViewControllerDidDismissFullScreen:(JWPlayerViewController * _Nonnull)controller
                                          reason:(JWFullScreenExitReason)reason {
    
}

Argument	Description
`controller` JWPlayerViewController	`JWPlayerViewController` emitting the event
`reason` JWFullScreenExitReason	Cause of the full-screen dismissal

Customize the JWFullScreenController

📘
Be mindful of the following when customizing the JWFullScreenController:

As of SDK version 4.19.0, the JWFullScreenViewController conforms to UIViewControllerTransitioningDelegate. To use custom transition animations, override the UIViewControllerTransitioningDelegate methods.

JWFullScreenController is only customizable with JWPlayerViewController.

You have the option to use your own subclass of JWFullScreenController rather than the default.

Complete the following steps to use a custom JWFullScreenController:

Override the playerViewControllerWillGoFullScreen method.
Use your custom CustomJWFullScreenViewController to subclass JWFullScreenViewController.
```
class CustomJWFullScreenViewController: JWFullScreenViewController {

}
```

Return an instance of your custom JWFullScreenController.

    func playerViewControllerWillGoFullScreen(_ controller: JWPlayerViewController) -> JWFullScreenViewController? {
            // Return instance of your subclassed full screen view controller
return CustomJWFullScreenViewController()
    }