iOS Developer Library

Developer

UIKit Framework Reference UIWindow Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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 becomeKeyWindow or resignKeyWindow 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 Class Reference.

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 1Creating a window for a second screen

Objective-C

  1. - (void)configureExternalDisplayAndShowWithContent:(UIViewController*)rootVC
  2. {
  3. // Configure the content only if a second screen is available.
  4. if ([[UIScreen screens] count] > 1) {
  5. UIScreen* externalScreen = [[UIScreen screens] objectAtIndex:1];
  6. CGRect screenBounds = externalScreen.bounds;
  7. // Configure the window
  8. self.externalWindow = [[UIWindow alloc] initWithFrame:screenBounds];
  9. self.externalWindow.windowLevel = UIWindowLevelNormal;
  10. self.externalWindow.screen = externalScreen;
  11. // Install the root view controller
  12. self.externalWindow.rootViewController = rootVC;
  13. // Show the window, but do not make it key.
  14. self.externalWindow.hidden = NO;
  15. }
  16. else {
  17. // No external display available for configuration.
  18. }
  19. }

Swift

  1. func configureExternalDisplayAndShowWithContent(rootVC : UIViewController) {
  2. let screens = UIScreen.screens()
  3. // Configure the content only if a second screen is available.
  4. if screens.count > 1 {
  5. let externalScreen = screens[1]
  6. let screenBounds = externalScreen.bounds
  7. // Create and configure the window.
  8. self.externalWindow = UIWindow.init(frame: screenBounds)
  9. self.externalWindow!.windowLevel = UIWindowLevelNormal
  10. self.externalWindow!.screen = externalScreen
  11. // Install the root view controller
  12. self.externalWindow!.rootViewController = rootVC
  13. // Show the window, but do not make it key
  14. self.externalWindow!.hidden = false
  15. }
  16. else {
  17. // No external display available for configuration.
  18. }
  19. }

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 keyWindow 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 UIWindowDidBecomeKeyNotification and UIWindowDidResignKeyNotification 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.

  • The root view controller for the window.

    Declaration

    Swift

    var rootViewController: UIViewController?

    Objective-C

    @property(nonatomic, strong) UIViewController *rootViewController

    Discussion

    The root view controller provides the content view of the window. Assigning a view controller to this property (either programmatically or using Interface Builder) installs the view controller’s view as the content view of the window. The new content view is configured to track the window size, changing as the window size changes. If the window has an existing view hierarchy, the old views are removed before the new ones are installed.

    The default value of this property is nil.

    Availability

    Available in iOS 4.0 and later.

  • The position of the window in the z-axis.

    Declaration

    Swift

    var windowLevel: UIWindowLevel

    Objective-C

    @property(nonatomic) UIWindowLevel windowLevel

    Discussion

    Window levels provide a relative grouping of windows along the z-axis. All windows assigned to the same window level appear in front of (or behind) all windows assigned to a different window level. The ordering of windows within a given window level is not guaranteed.

    The default value of this property is UIWindowLevelNormal. For a list of other possible window levels, see UIWindowLevel.

    Availability

    Available in iOS 2.0 and later.

  • The screen on which the window is displayed.

    Declaration

    Swift

    var screen: UIScreen

    Objective-C

    @property(nonatomic, strong) UIScreen *screen

    Discussion

    By default, this property is set to the primary device screen. If additional screens are attached to the device, you can assign a different screen object to display the window on that screen. A window is always displayed on only one screen.

    Moving windows from screen to screen is a relatively expensive operation and should not be done in performance-sensitive code. Instead, it’s recommended that you change the screen before displaying the window the first time. Changing the screen of a window that has not yet been ordered onto the screen has no significant additional cost.

    Availability

    Available in iOS 3.2 and later.

  • A Boolean value that indicates whether the window is the key window for the app. (read-only)

    Declaration

    Swift

    var keyWindow: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isKeyWindow) BOOL keyWindow

    Discussion

    The value of this property is YEStrue when the window is the key window or NOfalse when it is not. The key window receives keyboard and other non-touch related events. Only one window at a time may be the key window.

    Availability

    Available in iOS 2.0 and later.

  • Shows the window and makes it the key window.

    Declaration

    Swift

    func makeKeyAndVisible()

    Objective-C

    - (void)makeKeyAndVisible

    Discussion

    This is a convenience method to show the current window and position it in front of all other windows at the same level or lower. If you only want to show the window, change its hidden property to NOfalse.

    Availability

    Available in iOS 2.0 and later.

  • Makes the receiver the key window.

    Declaration

    Swift

    func makeKeyWindow()

    Objective-C

    - (void)makeKeyWindow

    Discussion

    Use this method to make the window key without changing its visibility. The key window receives keyboard and other non-touch related events. This method causes the previous key window to resign the key status.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func becomeKeyWindow()

    Objective-C

    - (void)becomeKeyWindow

    Discussion

    Never call this method directly. The system calls this method and posts UIWindowDidBecomeKeyNotification to let the window know when it has become key. The default implementation of this method does nothing, but subclasses can override it and use it to perform tasks related to becoming the key window.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func resignKeyWindow()

    Objective-C

    - (void)resignKeyWindow

    Discussion

    Never call this method directly. The system calls this method and posts UIWindowDidResignKeyNotification to let the window know when it is no longer key. The default implementation of this method does nothing, but subclasses can override it and use it to perform tasks related to resigning the key window status.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func convertPoint(_ point: CGPoint, toWindow window: UIWindow?) -> CGPoint

    Objective-C

    - (CGPoint)convertPoint:(CGPoint)point toWindow:(UIWindow *)window

    Parameters

    point

    A point specifying a location in the logical coordinate system of the current window object.

    window

    The window defining the destination coordinate system for point. Specify nil to convert the point to the logical coordinate system of the screen, which is measured in points.

    Return Value

    The point converted to the coordinate system of window.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func convertPoint(_ point: CGPoint, fromWindow window: UIWindow?) -> CGPoint

    Objective-C

    - (CGPoint)convertPoint:(CGPoint)point fromWindow:(UIWindow *)window

    Parameters

    point

    A point specifying a location in the coordinate system of window.

    window

    The source window containing the specified point. Specify nil to convert the point from the logical coordinate system of the screen, which is measured in points.

    Return Value

    The point converted to the coordinate system of the current window.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func convertRect(_ rect: CGRect, toWindow window: UIWindow?) -> CGRect

    Objective-C

    - (CGRect)convertRect:(CGRect)rect toWindow:(UIWindow *)window

    Parameters

    rect

    A rectangle in the current window’s coordinate system.

    window

    The window defining the destination coordinate system for rect. Specify nil to convert the rectangle to the logical coordinate system of the screen, which is measured in points.

    Return Value

    The rectangle converted to the coordinate system of window.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func convertRect(_ rect: CGRect, fromWindow window: UIWindow?) -> CGRect

    Objective-C

    - (CGRect)convertRect:(CGRect)rect fromWindow:(UIWindow *)window

    Parameters

    rect

    A rectangle in the coordinate system of window.

    window

    The source window containing the specified rect. Specify nil to convert the rectangle from the logical coordinate system of the screen, which is measured in points.

    Return Value

    The converted rectangle.

    Availability

    Available in iOS 2.0 and later.

  • Dispatches the specified event to its views.

    Declaration

    Swift

    func sendEvent(_ event: UIEvent)

    Objective-C

    - (void)sendEvent:(UIEvent *)event

    Parameters

    event

    The event to dispatch.

    Discussion

    The UIApplication object calls this method to dispatch events to the window. Window objects dispatch touch events to the view in which the touch occurred, and dispatch other types of events to the most appropriate target object. You can call this method as needed in your app to dispatch custom events that you create. For example, you might call this method to dispatch a custom event to the window’s responder chain.

    Availability

    Available in iOS 2.0 and later.

  • The positioning of windows relative to each other.

    Declaration

    Swift

    typealias UIWindowLevel = CGFloat

    Objective-C

    const UIWindowLevel UIWindowLevelNormal; const UIWindowLevel UIWindowLevelAlert; const UIWindowLevel UIWindowLevelStatusBar; typedef CGFloat UIWindowLevel;

    Constants

    • UIWindowLevelNormal

      UIWindowLevelNormal

      The default level. Use this level for the majority of your content, including for your app’s main window.

      Available in iOS 2.0 and later.

    • UIWindowLevelAlert

      UIWindowLevelAlert

      The level for an alert view. Windows at this level appear on top of windows at the UIWindowLevelNormal level.

      Available in iOS 2.0 and later.

    • UIWindowLevelStatusBar

      UIWindowLevelStatusBar

      The level for a status window. Windows at this level appear on top of windows at the UIWindowLevelAlert level.

      Available in iOS 2.0 and later.

    Discussion

    The stacking of levels takes precedence over the stacking of windows within each level. That is, even the bottom window in a level obscures the top window of the next level down. Levels are listed in order from lowest to highest.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    let UIKeyboardFrameBeginUserInfoKey: String let UIKeyboardFrameEndUserInfoKey: String let UIKeyboardAnimationCurveUserInfoKey: String let UIKeyboardAnimationDurationUserInfoKey: String let UIKeyboardIsLocalUserInfoKey: String

    Objective-C

    NSString *const UIKeyboardFrameBeginUserInfoKey; NSString *const UIKeyboardFrameEndUserInfoKey; NSString *const UIKeyboardAnimationCurveUserInfoKey; NSString *const UIKeyboardAnimationDurationUserInfoKey; NSString *const UIKeyboardIsLocalUserInfoKey; // Deprecated in iOS 3.2 and later. NSString *const UIKeyboardCenterBeginUserInfoKey; NSString *const UIKeyboardCenterEndUserInfoKey; NSString *const UIKeyboardBoundsUserInfoKey;

    Constants

    • UIKeyboardFrameBeginUserInfoKey

      UIKeyboardFrameBeginUserInfoKey

      The key for an NSValue object containing a CGRect that identifies the start frame of the keyboard in screen coordinates. These coordinates do not take into account any rotation factors applied to the window’s contents as a result of interface orientation changes. Thus, you may need to convert the rectangle to window coordinates (using the convertRect:fromWindow: method) or to view coordinates (using the convertRect:fromView: method) before using it.

      Available in iOS 3.2 and later.

    • UIKeyboardFrameEndUserInfoKey

      UIKeyboardFrameEndUserInfoKey

      The key for an NSValue object containing a CGRect that identifies the end frame of the keyboard in screen coordinates. These coordinates do not take into account any rotation factors applied to the window’s contents as a result of interface orientation changes. Thus, you may need to convert the rectangle to window coordinates (using the convertRect:fromWindow: method) or to view coordinates (using the convertRect:fromView: method) before using it.

      Available in iOS 3.2 and later.

    • UIKeyboardAnimationCurveUserInfoKey

      UIKeyboardAnimationCurveUserInfoKey

      The key for an NSNumber object containing a UIViewAnimationCurve constant that defines how the keyboard will be animated onto or off the screen.

      Available in iOS 3.0 and later.

    • UIKeyboardAnimationDurationUserInfoKey

      UIKeyboardAnimationDurationUserInfoKey

      The key for an NSNumber object containing a double that identifies the duration of the animation in seconds.

      Available in iOS 3.0 and later.

    • UIKeyboardIsLocalUserInfoKey

      UIKeyboardIsLocalUserInfoKey

      The key for an NSNumber object containing a Boolean that identifies whether the keyboard belongs to the current app. With multitasking on iPad, all visible apps are notified when the keyboard appears and disappears. The value of this key is YEStrue for the app that caused the keyboard to appear and NOfalse for any other apps.

      Available in iOS 9.0 and later.

    • UIKeyboardCenterBeginUserInfoKey

      The key for an NSValue object containing a CGPoint that is the center of the keyboard in window coordinates before animation. These coordinates actually take into account any rotation factors applied to the window’s contents as a result of interface orientation changes. Thus, the center point of the keyboard is different in portrait versus landscape orientations.

      Use the UIKeyboardFrameBeginUserInfoKey key instead.

      Available in iOS 2.0 and later.

      Deprecated in iOS 3.2.

    • UIKeyboardCenterEndUserInfoKey

      The key for an NSValue object containing a CGPoint that is the center of the keyboard in window coordinates after animation. These coordinates take into account any rotation factors applied to the window’s contents as a result of interface orientation changes. Thus, the center point of the keyboard is different in portrait versus landscape orientations.

      Use the UIKeyboardFrameEndUserInfoKey key instead.

      Available in iOS 2.0 and later.

      Deprecated in iOS 3.2.

    • UIKeyboardBoundsUserInfoKey

      The key for an NSValue object containing a CGRect that identifies the bounds rectangle of the keyboard in window coordinates. This value is sufficient for obtaining the size of the keyboard. If you want to get the origin of the keyboard on the screen (before or after animation) use the values obtained from the user info dictionary through the UIKeyboardCenterBeginUserInfoKey or UIKeyboardCenterEndUserInfoKey constants.

      Use the UIKeyboardFrameBeginUserInfoKey or UIKeyboardFrameEndUserInfoKey key instead.

      Available in iOS 2.0 and later.

      Deprecated in iOS 3.2.

  • Posted when an UIWindow object becomes visible.

    The notification object is the window object that has become visible. This notification does not contain a userInfo dictionary.

    Switching between apps does not generate visibility-related notifications for windows. Window visibility changes reflect changes to the window’s hidden property and reflect only the window’s visibility within the app.

    Declaration

    Swift

    let UIWindowDidBecomeVisibleNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted when an UIWindow object becomes hidden.

    The notification object is the window object that has become hidden. This notification does not contain a userInfo dictionary.

    Switching between apps does not generate visibility-related notifications for windows. Window visibility changes reflect changes to the window’s hidden property and reflect only the window’s visibility within the app.

    Declaration

    Swift

    let UIWindowDidBecomeHiddenNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted whenever a UIWindow object becomes the key window.

    The notification object is the window object that has become key. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let UIWindowDidBecomeKeyNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    The notification object is the window object that has resigned its main window status. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let UIWindowDidResignKeyNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted immediately prior to the display of the keyboard.

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    For more information about using the system keyboard, see Text Programming Guide for iOS.

    Declaration

    Swift

    let UIKeyboardWillShowNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted immediately after the display of the keyboard.

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    For more information about using the system keyboard, see Text Programming Guide for iOS.

    Declaration

    Swift

    let UIKeyboardDidShowNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted immediately prior to the dismissal of the keyboard.

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    For more information about using the system keyboard, see Text Programming Guide for iOS.

    Declaration

    Swift

    let UIKeyboardWillHideNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Posted immediately after the dismissal of the keyboard.

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    For more information about using the system keyboard, see Text Programming Guide for iOS.

    Declaration

    Swift

    let UIKeyboardDidHideNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    Declaration

    Swift

    let UIKeyboardWillChangeFrameNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    The notification object is nil. The userInfo dictionary contains information about the keyboard. Use the keys described in Keyboard Notification User Info Keys to get the location and size of the keyboard from the userInfo dictionary.

    Declaration

    Swift

    let UIKeyboardDidChangeFrameNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.