UIWindow Class Reference

Inherits from
UIView : UIResponder : NSObject
Conforms to
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Multiple Display Programming Guide for iOS
Declared in
UIWindow.h
Related sample code

Overview

The UIWindow class defines an object known as a window that manages and coordinates the views an app displays on a device screen. Unless an app can display content on an external device screen, an app has only one window.

The two principal functions of a window are to provide an area for displaying its views and to distribute events to the views. To change the content your app displays, you can change the window’s root view; you don’t create a new window. A window belongs to a level—typically, UIWindowLevelNormal—that represents where it sits on the z-axis relative to other windows. For example, a system alert window appears above normal app windows.

For more information about how to use windows, see Multiple Display Programming Guide for iOS.

Tasks

Configuring Windows

Making Windows Key

Converting Coordinates

Sending Events

Properties

keyWindow

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

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

If YES, the receiver is the key window for the application; otherwise, NO.

The key window is the one that is designated to receive 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.
See Also
Declared In
UIWindow.h

rootViewController

The root view controller for the window.

@property(nonatomic, retain) 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. 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.
Declared In
UIWindow.h

screen

The screen on which the window is currently displayed.

@property(nonatomic, retain) UIScreen *screen
Discussion

By default, all windows are created on the primary device screen. If additional screens are attached to the device, assigning a different screen object to this property causes the window to be displayed on the new 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.
Related Sample Code
Declared In
UIWindow.h

windowLevel

The receiver’s window level.

@property(nonatomic) UIWindowLevel windowLevel
Discussion

Levels are ordered so that each level groups windows within it in front of those in all preceding groups. For example, alert windows appear in front of all normal-level windows. When a window enters a new level, it’s ordered in front of all its peers in that level. See “UIWindowLevel” for a list of possible values. The default value is 0.0.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIWindow.h

Instance Methods

becomeKeyWindow

Invoked automatically to inform the receiver that it has become the key window; never invoke this method directly.

- (void)becomeKeyWindow
Discussion

This method reestablishes the receiver’s first responder, sends the becomeKeyWindow message to that object if it responds, and posts UIWindowDidBecomeKeyNotification to the default notification center.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIWindow.h

convertPoint:fromWindow:

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

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

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

window

The window with point in its coordinate system. If nil, this method converts 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 receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIWindow.h

convertPoint:toWindow:

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

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

A point specifying a location in the logical coordinate system of the receiver.

window

The window into whose coordinate system point is to be converted. If nil, this method converts 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.
See Also
Declared In
UIWindow.h

convertRect:fromWindow:

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

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

The rectangle in the window's coordinate system.

window

The window with rect in its coordinate system. If nil, this method instead converts 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.
See Also
Declared In
UIWindow.h

convertRect:toWindow:

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

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

A rectangle in the receiver's coordinate system.

window

The window that is the target of the conversion operation. If nil, this method instead converts the rectangle to 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.
See Also
Declared In
UIWindow.h

makeKeyAndVisible

Makes the receiver the key window and makes that window visible.

- (void)makeKeyAndVisible
Discussion

This is a convenience method to make the receiver the main window and displays it in front of other windows. You can also hide and reveal a window using the inherited hidden property of UIView.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIWindow.h

makeKeyWindow

Makes the receiver the main window.

- (void)makeKeyWindow
Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIWindow.h

resignKeyWindow

Invoked automatically when the window resigns key window status; never invoke this method directly.

- (void)resignKeyWindow
Discussion

This method sends resignKeyWindow to the receiver’s first responder and posts UIWindowDidResignKeyNotification to the default notification center.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIWindow.h

sendEvent:

Dispatches events sent to the receiver by the UIApplication object to its views.

- (void)sendEvent:(UIEvent *)event
Parameters
event

The event to process.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIWindow.h

Constants

UIWindowLevel

The positioning of windows relative to each other.

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

The default level.

Available in iOS 2.0 and later.

Declared in UIWindow.h.

UIWindowLevelAlert

The level for an alert view.

Available in iOS 2.0 and later.

Declared in UIWindow.h.

UIWindowLevelStatusBar

The level for a status window.

Available in iOS 2.0 and later.

Declared in UIWindow.h.

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.

Keyboard Notification User Info Keys

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

NSString *const UIKeyboardFrameBeginUserInfoKey;
NSString *const UIKeyboardFrameEndUserInfoKey;
NSString *const UIKeyboardAnimationDurationUserInfoKey;
NSString *const UIKeyboardAnimationCurveUserInfoKey;
   
// Deprecated in iOS 3.2 and later.
NSString *const UIKeyboardCenterBeginUserInfoKey;
NSString *const UIKeyboardCenterEndUserInfoKey;
NSString *const UIKeyboardBoundsUserInfoKey;
Constants
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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

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.

Declared in UIWindow.h.

Notifications

UIWindowDidBecomeVisibleNotification

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.

Availability
Declared In
UIWindow.h

UIWindowDidBecomeHiddenNotification

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.

Availability
Declared In
UIWindow.h

UIWindowDidBecomeKeyNotification

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.

Availability
Declared In
UIWindow.h

UIWindowDidResignKeyNotification

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.

Availability
Declared In
UIWindow.h

UIKeyboardWillShowNotification

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, Web, and Editing Programming Guide for iOS.

Availability
Declared In
UIWindow.h

UIKeyboardDidShowNotification

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, Web, and Editing Programming Guide for iOS.

Availability
Declared In
UIWindow.h

UIKeyboardWillHideNotification

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, Web, and Editing Programming Guide for iOS.

Availability
Declared In
UIWindow.h

UIKeyboardDidHideNotification

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, Web, and Editing Programming Guide for iOS.

Availability
Declared In
UIWindow.h

UIKeyboardWillChangeFrameNotification

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.

Availability
Declared In
UIWindow.h

UIKeyboardDidChangeFrameNotification

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.

Availability
Declared In
UIWindow.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...