Class

UIWindow

A UIWindow object provides the backdrop for your app’s user interface and provides important event-handling behaviors. Windows do not have any visual appearance of their own, but they are crucial to the presentation of your app’s views. Every view that appears onscreen is enclosed by a window, and each window is independent of the other windows in your app. Events received by your app are initially routed to the appropriate window object, which in turn forwards those events to the appropriate view. Windows work with your view controllers to implement orientation changes and to perform many other tasks that are fundamental to your app’s operation.

Overview

Windows are a fundamental part of your app, but you interact with them only minimally in your code. UIKit handles most window-related interactions, working with other objects as needed to implement many app behaviors. However, you need to do the following in your app:

  • Provide a main window to display your app’s content.

  • Create additional windows (as needed) to display additional content.

Providing your app’s main window is easy because Xcode does it for you. New iOS projects use storyboards to define the app’s views. Storyboards require the presence of a window property on the app delegate object, which the Xcode templates automatically provide. Thus with no effort on your part, new projects have a main window in which to display their view controller content.

Most apps need only one window, which displays the app’s content on the device’s main screen. You can create additional windows and display them on the device’s main screen, but extra windows are more commonly used to display content on an attached external display.

Aside from providing window objects for your app’s content, you also use window objects for a handful of other tasks:

  • Setting the z-axis level of your window, which affects the visibility of the window relative to other windows.

  • Showing windows and making them the target of keyboard events.

  • Converting coordinate values to and from the window’s coordinate system.

  • Changing the root view controller of a window.

  • Changing the screen on which the window is displayed.

You should rarely need to subclass UIWindow. The kinds of behaviors you might implement in a window can usually be implemented in a higher-level view controller more easily. One of the few times you might want to subclass is to override the becomeKey() or resignKey() methods to implement custom behaviors when a window’s key status changes.

For information about how view controllers present their content in a window, see View Controller Programming Guide for iOS. For information about how to display a window on a specific screen, see UIScreen.

Creating Additional Windows for Your App

Aside from your app’s main window (which Xcode usually provides), you are responsible for creating and configuring any additional windows used by your app. The most common usage for extra windows is to display content on a connected external display, but you can also display multiple windows on the same screen.

When creating windows, always set the window’s initial size and specify the screen on which it is displayed. You should also specify the root view controller that provides the content you want to display. Although you can add subviews directly to a window, providing a root view controller is a better way to manage the window’s content. Using a root view controller maintains a separation between the window object and the content your app displays in that window.

Listing 1 shows a sample method that configures a custom window for a view controller that displays content on a secondary screen. The example assumes that the object that implements this method uses an externalWindow variable to store a reference to the window.

Listing 1

Creating a window for a second screen

func configureExternalDisplayAndShowWithContent(rootVC : UIViewController) {
    let screens = UIScreen.screens()
    
    // Configure the content only if a second screen is available.
    if screens.count > 1 {
        let externalScreen = screens[1]
        let screenBounds = externalScreen.bounds
        
        // Create and configure the window.
        self.externalWindow = UIWindow.init(frame: screenBounds)
        self.externalWindow!.windowLevel = UIWindowLevelNormal
        self.externalWindow!.screen = externalScreen
        
        // Install the root view controller
        self.externalWindow!.rootViewController = rootVC
        
        // Show the window, but do not make it key
        self.externalWindow!.hidden = false
    }
    else {
        // No external display available for configuration.
    }
}

Understanding Keyboard Interactions

Whereas touch events are delivered to the window where they occurred, events that do not have a relevant coordinate value are delivered to the key window. Only one window at a time can be the key window, and you can use a window’s isKeyWindow property to determine its status. Most of the time, your app’s main window is the key window, but UIKit may designate a different window as needed.

If you need to know which window is key, observe the UIWindowDidBecomeKey and UIWindowDidResignKey notifications. The system sends those notifications in response to key window changes in your app. To force a window become key, or to force a window to resign the key status, call the appropriate methods of this class.

Symbols

Configuring the Window

var rootViewController: UIViewController?

The root view controller for the window.

var windowLevel: UIWindowLevel

The position of the window in the z-axis.

var screen: UIScreen

The screen on which the window is displayed.

Making Windows Key

var isKeyWindow: Bool

A Boolean value that indicates whether the window is the key window for the app.

func makeKeyAndVisible()

Shows the window and makes it the key window.

func makeKey()

Makes the receiver the key window.

func becomeKey()

Called automatically to inform the window that it has become the key window.

func resignKey()

Called automatically to inform the window that it is no longer the key window.

Converting Coordinates

func convert(CGPoint, to: UIWindow?)

Converts a point from the current window’s coordinate system to the coordinate system of another window.

func convert(CGPoint, from: UIWindow?)

Converts a point from the coordinate system of a given window to the coordinate system of the current window.

func convert(CGRect, to: UIWindow?)

Converts a rectangle from the current window’s coordinate system to the coordinate system of another window.

func convert(CGRect, from: UIWindow?)

Converts a rectangle from the coordinate system of another window to coordinate system of the current window.

Sending Events

func sendEvent(UIEvent)

Dispatches the specified event to its views.

Constants

UIWindowLevel

The positioning of windows relative to each other.

Keyboard Notification User Info Keys

Keys used to get values from the user information dictionary of keyboard notifications.

Notifications

static let UIWindowDidBecomeVisible: NSNotification.Name

Posted when an UIWindow object becomes visible.

static let UIWindowDidBecomeHidden: NSNotification.Name

Posted when an UIWindow object becomes hidden.

static let UIWindowDidBecomeKey: NSNotification.Name

Posted whenever a UIWindow object becomes the key window.

static let UIWindowDidResignKey: NSNotification.Name

Posted whenever a UIWindow object resigns its status as main window.

static let UIKeyboardWillShow: NSNotification.Name

Posted immediately prior to the display of the keyboard.

static let UIKeyboardDidShow: NSNotification.Name

Posted immediately after the display of the keyboard.

static let UIKeyboardWillHide: NSNotification.Name

Posted immediately prior to the dismissal of the keyboard.

static let UIKeyboardDidHide: NSNotification.Name

Posted immediately after the dismissal of the keyboard.

static let UIKeyboardWillChangeFrame: NSNotification.Name

Posted immediately prior to a change in the keyboard’s frame.

static let UIKeyboardDidChangeFrame: NSNotification.Name

Posted immediately after a change in the keyboard’s frame.