Class

UIWindow

The backdrop for your app’s user interface and the object that dispatches events to your views.

Overview

Windows work with your view controllers to handle events and to perform many other tasks that are fundamental to your app’s operation. UIKit handles most window-related interactions, working with other objects as needed to implement many app behaviors.

You use windows only when you need to do the following:

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

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

Normally, Xcode provides your app's main window. 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. If your app does not use storyboards, you must create this window yourself.

Most apps need only one window, which displays the app’s content on the device’s main screen. Although you can create additional windows on the device’s main screen, extra windows are commonly used to display content on an external screen, as described in Displaying Content on a Connected Screen.

You also use UIWindow 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.

Windows do not have any visual appearance of their own. Instead, a window hosts one or more views, which are managed by the window's root view controller. You configure the root view controller in your storyboards, adding whatever views are appropriate for your interface.

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 to display a window on a specific screen, see UIScreen.

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.

Topics

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.

typealias UIWindowLevel

The positioning of windows relative to each other.

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

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.

See Also

Windows

protocol UICoordinateSpace

A set of methods for converting between different frames of reference on a screen.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software