Вы находитесь на странице: 1из 44

UIKit Function Reference

2011-10-12

Apple Inc. 2011 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Cocoa Touch, iPhone, iPod, iPod touch, and Mac are trademarks of Apple Inc., registered in the United States and other countries. iPad is a trademark of Apple Inc. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

Contents
UIKit Function Reference 5
Overview 5 Functions by Task 5 Application Launch 5 Image Manipulation 5 Image and Movie Saving 6 Graphics 6 PDF Creation 7 String Conversions 7 Managing Edge Insets 8 Managing Offsets 8 Interface Orientation Macros 8 Device Orientation Macros 9 Interface Idiom Macro 9 Accessibility 9 Functions 9 CGAffineTransformFromString 9 CGPointFromString 10 CGRectFromString 11 CGSizeFromString 11 NSStringFromCGAffineTransform 12 NSStringFromCGPoint 12 NSStringFromCGRect 13 NSStringFromCGSize 13 NSStringFromUIEdgeInsets 14 NSStringFromUIOffset 14 UIAccessibilityIsClosedCaptioningEnabled 15 UIAccessibilityIsMonoAudioEnabled 15 UIAccessibilityIsVoiceOverRunning 15 UIAccessibilityPostNotification 16 UIAccessibilityRegisterGestureConflictWithZoom 16 UIApplicationMain 16 UIDeviceOrientationIsLandscape 17 UIDeviceOrientationIsPortrait 18 UIDeviceOrientationIsValidInterfaceOrientation 18 UIEdgeInsetsEqualToEdgeInsets 19 UIEdgeInsetsFromString 19 UIEdgeInsetsInsetRect 20 UIEdgeInsetsMake 20 UIGraphicsAddPDFContextDestinationAtPoint 21 UIGraphicsBeginImageContext 22

3
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

CONTENTS

UIGraphicsBeginImageContextWithOptions 22 UIGraphicsBeginPDFContextToData 24 UIGraphicsBeginPDFContextToFile 25 UIGraphicsBeginPDFPage 25 UIGraphicsBeginPDFPageWithInfo 26 UIGraphicsEndImageContext 27 UIGraphicsEndPDFContext 27 UIGraphicsGetCurrentContext 28 UIGraphicsGetImageFromCurrentImageContext 28 UIGraphicsGetPDFContextBounds 29 UIGraphicsPopContext 29 UIGraphicsPushContext 30 UIGraphicsSetPDFContextDestinationForRect 30 UIGraphicsSetPDFContextURLForRect 31 UIImageJPEGRepresentation 31 UIImagePNGRepresentation 32 UIImageWriteToSavedPhotosAlbum 32 UIInterfaceOrientationIsLandscape 33 UIInterfaceOrientationIsPortrait 34 UIOffsetEqualToOffset 34 UIOffsetFromString 35 UIOffsetMake 35 UIRectClip 36 UIRectFill 36 UIRectFillUsingBlendMode 37 UIRectFrame 37 UIRectFrameUsingBlendMode 38 UISaveVideoAtPathToSavedPhotosAlbum 39 UIVideoAtPathIsCompatibleWithSavedPhotosAlbum 40 UI_USER_INTERFACE_IDIOM 40

Document Revision History 43

4
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Framework: Declared in

UIKit/UIKit.h UIAccessibility.h UIAccessibilityZoom.h UIApplication.h UIDevice.h UIGeometry.h UIGraphics.h UIImage.h UIImagePickerController.h

Overview
The UIKit framework defines a number of functions, many of them used in graphics and drawing operations.

Functions by Task

Application Launch
UIApplicationMain (page 16)

This function is called in the main entry point to create the application object and the application delegate and set up the event cycle.

Image Manipulation
UIImageJPEGRepresentation (page 31)

Returns the data for the specified image in JPEG format.


UIImagePNGRepresentation (page 32)

Returns the data for the specified image in PNG format

Overview
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Image and Movie Saving


UIImageWriteToSavedPhotosAlbum (page 32)

Adds the specified image to the users Camera Roll album.


UISaveVideoAtPathToSavedPhotosAlbum (page 39)

Adds the movie at the specified path to the users Camera Roll album.
UIVideoAtPathIsCompatibleWithSavedPhotosAlbum (page 40)

Returns a Boolean value indicating whether the specified video can be saved to users Camera Roll album.

Graphics
UIGraphicsGetCurrentContext (page 28)

Returns the current graphics context.


UIGraphicsPushContext (page 30)

Makes the specified graphics context the current context.


UIGraphicsPopContext (page 29)

Removes the current graphics context from the top of the stack, restoring the previous context.
UIGraphicsBeginImageContext (page 22)

Creates a bitmap-based graphics context and makes it the current context.


UIGraphicsBeginImageContextWithOptions (page 22)

Creates a bitmap-based graphics context with the specified options.


UIGraphicsGetImageFromCurrentImageContext (page 28)

Returns an image based on the contents of the current bitmap-based graphics context.
UIGraphicsEndImageContext (page 27)

Removes the current bitmap-based graphics context from the top of the stack.
UIRectClip (page 36)

Modifies the current clipping path by intersecting it with the specified rectangle.
UIRectFill (page 36)

Fills the specified rectangle with the current color.


UIRectFillUsingBlendMode (page 37)

Fills a rectangle with the current fill color using the specified blend mode.
UIRectFrame (page 37)

Draws a frame around the inside of the specified rectangle.


UIRectFrameUsingBlendMode (page 38)

Draws a frame around the inside of a rectangle using the specified blend mode.

Functions by Task
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

PDF Creation
UIGraphicsBeginPDFContextToData (page 24)

Creates a PDF-based graphics context that targets the specified mutable data object.
UIGraphicsBeginPDFContextToFile (page 25)

Creates a PDF-based graphics context that targets a file at the specified path.
UIGraphicsEndPDFContext (page 27)

Closes a PDF graphics context and pops it from the current context stack.
UIGraphicsBeginPDFPage (page 25)

Marks the beginning of a new page in a PDF context and configures it using default values.
UIGraphicsBeginPDFPageWithInfo (page 26)

Marks the beginning of a new page in a PDF context and configures it using the specified values.
UIGraphicsGetPDFContextBounds (page 29)

Returns the current page bounds.


UIGraphicsAddPDFContextDestinationAtPoint (page 21)

Creates a jump destination in the current page.


UIGraphicsSetPDFContextDestinationForRect (page 30)

Links a rectangle on the current page to the specified jump destination.


UIGraphicsSetPDFContextURLForRect (page 31)

Links a rectangle on the current page to the specified URL.

String Conversions
CGAffineTransformFromString (page 9)

Returns a Core Graphics affine transform structure corresponding to the data in a given string.
CGPointFromString (page 10)

Returns a Core Graphics point structure corresponding to the data in a given string.
CGRectFromString (page 11)

Returns a Core Graphics rectangle structure corresponding to the data in a given string.
CGSizeFromString (page 11)

Returns a Core Graphics size structure corresponding to the data in a given string.
NSStringFromCGAffineTransform (page 12)

Returns a string formatted to contain the data from an affine transform.


NSStringFromCGPoint (page 12)

Returns a string formatted to contain the data from a point.


NSStringFromCGRect (page 13)

Returns a string formatted to contain the data from a rectangle.


NSStringFromCGSize (page 13)

Returns a string formatted to contain the data from a size data structure.

Functions by Task
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

NSStringFromUIEdgeInsets (page 14)

Returns a string formatted to contain the data from an edge insets structure.
NSStringFromUIOffset (page 14)

Returns a string formatted to contain the data from an offset structure.


UIEdgeInsetsFromString (page 19)

Returns a UIKit edge insets structure corresponding to the data in a given string.
UIOffsetFromString (page 35)

Returns a UIKit offset structure corresponding to the data in a given string.

Managing Edge Insets


UIEdgeInsetsMake (page 20)

Creates an edge inset for a button or view.


UIEdgeInsetsEqualToEdgeInsets (page 19)

Compares two edge insets to determine if they are the same.


UIEdgeInsetsInsetRect (page 20)

Adjusts a rectangle by the given edge insets.

Managing Offsets
UIOffsetMake (page 35)

Returns an offset structure from the given components.


UIOffsetEqualToOffset (page 34)

Returns a Boolean value that indicates whether two offsets are equal.

Interface Orientation Macros


UIInterfaceOrientationIsPortrait (page 34)

Returns a Boolean value indicating whether the user interface is currently presented in a portrait orientation.
UIInterfaceOrientationIsLandscape (page 33)

Returns a Boolean value indicating whether the user interface is currently presented in a landscape orientation.

Functions by Task
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Device Orientation Macros


UIDeviceOrientationIsValidInterfaceOrientation (page 18)

Returns a Boolean value indicating whether the specified orientation constant is valid.
UIDeviceOrientationIsPortrait (page 18)

Returns a Boolean value indicating whether the device is in a portrait orientation.


UIDeviceOrientationIsLandscape (page 17)

Returns a Boolean value indicating whether the device is in a landscape orientation.

Interface Idiom Macro


UI_USER_INTERFACE_IDIOM (page 40)

Returns the interface idiom supported by the current device.

Accessibility
UIAccessibilityPostNotification (page 16)

Posts a notification to assistive applications.


UIAccessibilityIsVoiceOverRunning (page 15)

Returns a Boolean value indicating whether VoiceOver is running.


UIAccessibilityIsMonoAudioEnabled (page 15)

Returns a Boolean value indicating whether system audio is set to mono.


UIAccessibilityIsClosedCaptioningEnabled (page 15)

Returns a Boolean value indicating whether closed captioning is enabled.


UIAccessibilityRegisterGestureConflictWithZoom (page 16)

Warns users that application-specific gestures conflict with the system-defined Zoom accessibility gestures.

Functions
CGAffineTransformFromString
Returns a Core Graphics affine transform structure corresponding to the data in a given string.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

CGAffineTransform CGAffineTransformFromString ( NSString *string );

Parameters
string

A string whose contents are of the form {a, b, c, d, tx, ty} where a, b, c, d, tx, and ty are the , floating-point component values of the CGAffineTransform data structure. An example of a valid string is @{1,0,0,1,2.5,3.0} The string is not localized, so items are always separated with a comma. . For information about the position of each value in the transform array, see CGAffineTransform Reference. Return Value A Core Graphics affine transform structure. If the string is not well-formed, the function returns the identity transform. Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromCGAffineTransform function. Availability Available in iOS 2.0 and later. See Also
NSStringFromCGAffineTransform (page 12)

Declared In
UIGeometry.h

CGPointFromString
Returns a Core Graphics point structure corresponding to the data in a given string.
CGPoint CGPointFromString ( NSString *string );

Parameters
string

A string whose contents are of the form {x,y} where x is the x coordinate and y is the y coordinate. , The x and y values can represent integer or float values. An example of a valid string is @{3.0,2.5} . The string is not localized, so items are always separated with a comma. Return Value A Core Graphics structure that represents a point. If the string is not well-formed, the function returns CGPointZero. Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromCGPoint function. Availability Available in iOS 2.0 and later.

10

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

See Also
NSStringFromCGPoint (page 12)

Declared In
UIGeometry.h

CGRectFromString
Returns a Core Graphics rectangle structure corresponding to the data in a given string.
CGRect CGRectFromString ( NSString *string );

Parameters
string

A string whose contents are of the form {{x,y},{w, h}} where x is the x coordinate, y is the y coordinate, , w is the width, and h is the height. These components can represent integer or float values. An example of a valid string is @{{3,2},{4,5}} The string is not localized, so items are always separated with a . comma. Return Value A Core Graphics structure that represents a rectangle. If the string is not well-formed, the function returns CGRectZero. Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromCGRect function. Availability Available in iOS 2.0 and later. See Also
NSStringFromCGRect (page 13)

Declared In
UIGeometry.h

CGSizeFromString
Returns a Core Graphics size structure corresponding to the data in a given string.
CGSize CGSizeFromString ( NSString *string );

Parameters
string

A string whose contents are of the form {w, h} where w is the width and h is the height. The w and , h values can be integer or float values. An example of a valid string is @{3.0,2.5} The string is not . localized, so items are always separated with a comma.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

11

UIKit Function Reference

Return Value A Core Graphics structure that represents a size. If the string is not well-formed, the function returns CGSizeZero. Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromCGSize function. Availability Available in iOS 2.0 and later. See Also
NSStringFromCGSize (page 13)

Declared In
UIGeometry.h

NSStringFromCGAffineTransform
Returns a string formatted to contain the data from an affine transform.
NSString * NSStringFromCGAffineTransform ( CGAffineTransform transform );

Parameters
transform

A Core Graphics affine transform structure. Return Value A string that corresponds to transform. See CGAffineTransformFromString (page 9) for a discussion of the string format. Availability Available in iOS 2.0 and later. See Also
CGAffineTransformFromString (page 9)

Declared In
UIGeometry.h

NSStringFromCGPoint
Returns a string formatted to contain the data from a point.
NSString * NSStringFromCGPoint ( CGPoint point );

Parameters
point

A Core Graphics structure representing a point.

12

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Return Value A string that corresponds to point. See CGPointFromString (page 10) for a discussion of the string format. Availability Available in iOS 2.0 and later. See Also
CGPointFromString (page 10)

Declared In
UIGeometry.h

NSStringFromCGRect
Returns a string formatted to contain the data from a rectangle.
NSString * NSStringFromCGRect ( CGRect rect );

Parameters
rect

A Core Graphics structure representing a rectangle. Return Value A string that corresponds to rect. See CGRectFromString (page 11) for a discussion of the string format. Availability Available in iOS 2.0 and later. See Also
CGRectFromString (page 11)

Declared In
UIGeometry.h

NSStringFromCGSize
Returns a string formatted to contain the data from a size data structure.
NSString * NSStringFromCGSize ( CGSize size );

Parameters
size

A Core Graphics structure representing a size. Return Value A string that corresponds to size. See CGSizeFromString (page 11) for a discussion of the string format. Availability Available in iOS 2.0 and later.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

13

UIKit Function Reference

See Also
CGSizeFromString (page 11)

Declared In
UIGeometry.h

NSStringFromUIEdgeInsets
Returns a string formatted to contain the data from an edge insets structure.
NSString * NSStringFromUIEdgeInsets ( UIEdgeInsets insets );

Parameters
insets

A UIKit edge insets data structure. Return Value A string that corresponds to insets. See UIEdgeInsetsFromString (page 19) for a discussion of the string format. Availability Available in iOS 2.0 and later. See Also
UIEdgeInsetsFromString (page 19)

Declared In
UIGeometry.h

NSStringFromUIOffset
Returns a string formatted to contain the data from an offset structure.
NSString *NSStringFromUIOffset( UIOffset offset );

Parameters
offset

A UIKit offset data structure. Return Value A string that corresponds to offset. Availability Available in iOS 5.0 and later. See Also
UIOffsetFromString (page 35)

Declared In
UIGeometry.h

14

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

UIAccessibilityIsClosedCaptioningEnabled
Returns a Boolean value indicating whether closed captioning is enabled.
BOOL UIAccessibilityIsClosedCaptioningEnabled();

Return Value YES if the user has enabled closed captioning in Settings; otherwise, NO. Availability Available in iOS 5.0 and later. Declared In
UIAccessibility.h

UIAccessibilityIsMonoAudioEnabled
Returns a Boolean value indicating whether system audio is set to mono.
BOOL UIAccessibilityIsMonoAudioEnabled();

Return Value YES if mono audio is currently enabled; otherwise, NO. Availability Available in iOS 5.0 and later. Declared In
UIAccessibility.h

UIAccessibilityIsVoiceOverRunning
Returns a Boolean value indicating whether VoiceOver is running.
BOOL UIAccessibilityIsVoiceOverRunning();

Return Value YES if VoiceOver is currently running; otherwise, NO. Discussion You can use this function to customize your applications UI specifically for VoiceOver users. For example, you might want UI elements that usually disappear quickly to persist onscreen for VoiceOver users. Note that you can also listen for the UIAccessibilityVoiceOverStatusChanged notification to find out when VoiceOver starts and stops. Availability Available in iOS 4.0 and later. Declared In
UIAccessibility.h

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

15

UIKit Function Reference

UIAccessibilityPostNotification
Posts a notification to assistive applications.
void UIAccessibilityPostNotification ( UIAccessibilityNotifications notification, id argument );

Parameters
notification

The notification to post (see Notifications in UIAccessibility Protocol Reference for a list of notifications).
argument

The argument specified by the notification. Pass nil unless a notification specifies otherwise. Discussion Your application might need to post accessibility notifications if you have user interface components that change very frequently or that appear and disappear. Availability Available in iOS 3.0 and later. Related Sample Code AccelerometerGraph Formulaic Declared In
UIAccessibility.h

UIAccessibilityRegisterGestureConflictWithZoom
Warns users that application-specific gestures conflict with the system-defined Zoom accessibility gestures.
void UIAccessibilityRegisterGestureConflictWithZoom();

Discussion Use this function if your application uses multifinger gestures that conflict with the gestures used by system Zoom (that is, three-finger gestures). When this is the case, the user is presented with the choice of turning off Zoom or continuing. Availability Available in iOS 5.0 and later. Declared In
UIAccessibilityZoom.h

UIApplicationMain
This function is called in the main entry point to create the application object and the application delegate and set up the event cycle.

16

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

int UIApplicationMain ( int argc, char *argv[], NSString *principalClassName, NSString *delegateClassName );

Parameters
argc

The count of arguments in argv; this usually is the corresponding parameter to main.
argv

A variable list of arguments; this usually is the corresponding parameter to main.


principalClassName

The name of the UIApplication class or subclass. If you specify nil, UIApplication is assumed.
delegateClassName

The name of the class from which the application delegate is instantiated. If principalClassName designates a subclass of UIApplication, you may designate the subclass as the delegate; the subclass instance receives the application-delegate messages. Specify nil if you load the delegate object from your applications main nib file. Return Value Even though an integer return type is specified, this function never returns. When users exits an iPhone application by pressing the Home button, the application moves to the background. Discussion This function instantiates the application object from the principal class and and instantiates the delegate (if any) from the given class and sets the delegate for the application. It also sets up the main event loop, including the applications run loop, and begins processing events. If the applications Info.plist file specifies a main nib file to be loaded, by including the NSMainNibFile key and a valid nib file name for the value, this function loads that nib file. Despite the declared return type, this function never returns. For more information on how this function behaves, see The Core Application Design in iOS Application Programming Guide. Availability Available in iOS 2.0 and later. Related Sample Code International Mountains KMLViewer SimpleNetworkStreams SpeakHere TableViewSuite Declared In
UIApplication.h

UIDeviceOrientationIsLandscape
Returns a Boolean value indicating whether the device is in a landscape orientation.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

17

UIKit Function Reference

#define UIDeviceOrientationIsLandscape(orientation) \ ((orientation) == UIDeviceOrientationLandscapeLeft || \ (orientation) == UIDeviceOrientationLandscapeRight)

Parameters
orientation

Specify the value of the orientation property of the UIDevice class. Return Value Returns YES if the device orientation is landscape, otherwise returns NO. Availability Available in iOS 2.0 and later. Related Sample Code AlternateViews Declared In
UIDevice.h

UIDeviceOrientationIsPortrait
Returns a Boolean value indicating whether the device is in a portrait orientation.
#define UIDeviceOrientationIsPortrait(orientation) \ ((orientation) == UIDeviceOrientationPortrait || \ (orientation) == UIDeviceOrientationPortraitUpsideDown)

Parameters
orientation

Specify the value of the orientation property of the UIDevice class. Return Value Returns YES if the device orientation is portrait, otherwise returns NO. Availability Available in iOS 2.0 and later. Declared In
UIDevice.h

UIDeviceOrientationIsValidInterfaceOrientation
Returns a Boolean value indicating whether the specified orientation constant is valid.
#define UIDeviceOrientationIsValidInterfaceOrientation(orientation) \ ((orientation) == UIDeviceOrientationPortrait || \ (orientation) == UIDeviceOrientationPortraitUpsideDown || \ (orientation) == UIDeviceOrientationLandscapeLeft || \ (orientation) == UIDeviceOrientationLandscapeRight)

Parameters
orientation

Specify the orientation constant to check.

18

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Return Value Returns YES if the specified orientation constant is valid or NO if it is not valid. Availability Available in iOS 2.0 and later. Declared In
UIApplication.h

UIEdgeInsetsEqualToEdgeInsets
Compares two edge insets to determine if they are the same.
BOOL UIEdgeInsetsEqualToEdgeInsets ( UIEdgeInsets insets1, UIEdgeInsets insets2 );

Parameters
insets1

An edge inset to compare with insets2.


insets2

An edge inset to compare with insets1. Return Value YES if the edge insets are the same; otherwise, NO. Availability Available in iOS 2.0 and later. See Also
UIEdgeInsetsMake (page 20)

Declared In
UIGeometry.h

UIEdgeInsetsFromString
Returns a UIKit edge insets structure corresponding to the data in a given string.
UIEdgeInsets UIEdgeInsetsFromString ( NSString *string );

Parameters
string

A string whose contents are of the form {top, left, bottom, right} where top, left, bottom, right are , the floating-point component values of the UIEdgeInsets structure. An example of a valid string is @{3.0,8.0,3.0,5.0} The string is not localized, so items are always separated with a comma. . Return Value An edge insets data structure. If the string is not well-formed, the function returns UIEdgeInsetsZero.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

19

UIKit Function Reference

Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromUIEdgeInsets function. Availability Available in iOS 2.0 and later. See Also
NSStringFromUIEdgeInsets (page 14)

Declared In
UIGeometry.h

UIEdgeInsetsInsetRect
Adjusts a rectangle by the given edge insets.
CGRect UIEdgeInsetsInsetRect ( CGRect rect, UIEdgeInsets insets );

Parameters
rect

The rectangle to be adjusted.


insets

The edge insets to be applied to the adjustment. Return Value A rectangle that is adjusted by the UIEdgeInsets structure passed in insets. Discussion This inline function increments the origin of rect and decrements the size of rect by applying the appropriate member values of the UIEdgeInsets structure. Availability Available in iOS 2.0 and later. See Also
UIEdgeInsetsMake (page 20)

Declared In
UIGeometry.h

UIEdgeInsetsMake
Creates an edge inset for a button or view.

20

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

UIEdgeInsets UIEdgeInsetsMake ( CGFloat top, CGFloat left, CGFloat bottom, CGFloat right );

Parameters
top

The inset at the top of an object.


left

The inset on the left of an object


bottom

The inset on the bottom of an object.


right

The inset on the right of an object. Return Value An inset for a button or view Discussion An inset is a margin around the drawing rectangle where each side (left, right, top, and bottom) can have a different value. Availability Available in iOS 2.0 and later. See Also
UIEdgeInsetsEqualToEdgeInsets (page 19)

Declared In
UIGeometry.h

UIGraphicsAddPDFContextDestinationAtPoint
Creates a jump destination in the current page.
void UIGraphicsAddPDFContextDestinationAtPoint ( NSString *name, CGPoint point );

Parameters
name

The name of the destination point. The name you assign is local to the PDF document and is what you use when creating links to this destination.
point

A point on the current page of the PDF context. Discussion This function marks the specified point in the current page as the destination of a jump. When the user taps a link that takes them to this jump destination, the PDF document scrolls until the specified point is visible. If the current graphics context is not a PDF context, this function does nothing.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

21

UIKit Function Reference

For information on how to create links to this destination, see the UIGraphicsSetPDFContextDestinationForRect (page 30) function. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIGraphicsBeginImageContext
Creates a bitmap-based graphics context and makes it the current context.
void UIGraphicsBeginImageContext ( CGSize size );

Parameters
size

The size of the new bitmap context. This represents the size of the image returned by the UIGraphicsGetImageFromCurrentImageContext function. Discussion This function is equivalent to calling the UIGraphicsBeginImageContextWithOptions (page 22) function with the opaque parameter set to NO and a scale factor of 1.0. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. Related Sample Code iPhoneCoreDataRecipes LazyTableImages MapCallouts PhotoLocations ZoomingPDFViewer Declared In
UIGraphics.h

UIGraphicsBeginImageContextWithOptions
Creates a bitmap-based graphics context with the specified options.

22

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

void UIGraphicsBeginImageContextWithOptions( CGSize size, BOOL opaque, CGFloat scale );

Parameters
size

The size (measured in points) of the new bitmap context. This represents the size of the image returned by the UIGraphicsGetImageFromCurrentImageContext function. To get the size of the bitmap in pixels, you must multiply the width and height values by the value in the scale parameter.
opaque

A Boolean flag indicating whether the bitmap is opaque. If you know the bitmap is fully opaque, you can specify YES for this parameter to optimize the bitmap storage. Specifying NO means that the bitmap must include an alpha channel to handle any partially transparent pixels.
scale

The scale factor to apply to the bitmap. If you specify a value of 0.0, the scale factor is set to the scale factor of the devices main screen. Discussion You use this function to configure the drawing environment for rendering into a bitmap. The format for the bitmap is as follows:

For bitmaps created in iOS 3.2 and later, the drawing environment uses the premultiplied ARGB format to store the bitmap data. If the opaque parameter is YES, the bitmaps alpha channel is ignored. For bitmaps created in iOS 3.1.x and earlier, the drawing environment uses the premultiplied RGBA format to store the bitmap data.

The environment also uses the default coordinate system for UIKit views, where the origin is in the upper-left corner and the positive axes extend down and to the right of the origin. The supplied scale factor is also applied to the coordinate system and resulting images. The drawing environment is pushed onto the graphics context stack immediately. While the context created by this function is the current context, you can call the UIGraphicsGetImageFromCurrentImageContext function to retrieve an image object based on the current contents of the context. When you are done modifying the context, you must call the UIGraphicsEndImageContext function to clean up the bitmap drawing environment and remove the graphics context from the top of the context stack. You should not use the UIGraphicsPopContext function to remove this type of context from the stack. In most other respects, the graphics context created by this function behaves like any other graphics context. You can change the context by pushing and popping other graphics contexts. You can also get the bitmap context using the UIGraphicsGetCurrentContext function. You should call this function from the main thread of your application only. Availability Available in iOS 4.0 and later. See Also
UIGraphicsGetCurrentContext (page 28) UIGraphicsGetImageFromCurrentImageContext (page 28)

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

23

UIKit Function Reference

UIGraphicsEndImageContext (page 27)

Declared In
UIGraphics.h

UIGraphicsBeginPDFContextToData
Creates a PDF-based graphics context that targets the specified mutable data object.
void UIGraphicsBeginPDFContextToData ( NSMutableData *data, CGRect bounds, NSDictionary *documentInfo );

Parameters
data

The data object to receive the PDF output data.


bounds

A rectangle that specifies the default size and location of PDF pages. (This value is used as the default media box for each new page.) The origin of the rectangle should typically be (0, 0). Specifying an empty rectangle (CGRectZero) sets the default page size to 8.5 by 11 inches (612 by 792 points).
documentInfo

A dictionary that specifies additional information to be associated with the PDF file. You can use these keys to specify additional metadata and security information for the PDF, such as the author of the PDF or the password for accessing it. The keys in this dictionary are the same keys you pass to the CGPDFContextCreate function and are described in the Auxiliary Dictionary Keys section of CGPDFContext Reference. The dictionary is retained by the new context, so on return you may safely release it. Specify nil if you do not want to associate any additional information with the PDF document. Discussion After creating the graphics context, this function makes it the current drawing context. Any subsequent drawing commands are therefore captured and turned into PDF data. When you are done drawing, you must call the UIGraphicsEndPDFContext function to close the PDF graphics context. You can use all of the same drawing routines that you would normally use to draw the contents of your application. The graphics context converts all drawing commands into PDF drawing commands automatically. However, before you issue any drawing commands to a PDF context, you must start a new page by calling the UIGraphicsBeginPDFPage (page 25) or UIGraphicsBeginPDFPageWithInfo (page 26) function. You can also use these functions to define additional pages later. After creating it, you can get the PDF context using the UIGraphicsGetCurrentContext (page 28) function. Availability Available in iOS 3.2 and later. See Also
UIGraphicsEndPDFContext (page 27)

Declared In
UIGraphics.h

24

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

UIGraphicsBeginPDFContextToFile
Creates a PDF-based graphics context that targets a file at the specified path.
BOOL UIGraphicsBeginPDFContextToFile ( NSString *path, CGRect bounds, NSDictionary *documentInfo );

Parameters
path

A POSIX-style path string identifying the location of the resulting PDF file. The specified path may be relative or a full path name. If a file does not exist at the specified path, one is created; otherwise, the contents of any existing file are deleted. The directories in the path must exist.
bounds

A rectangle that specifies the default size and location of PDF pages. (This value is used as the default media box for each new page.) The origin of the rectangle should typically be (0, 0). Specifying an empty rectangle (CGRectZero) sets the default page size to 8.5 by 11 inches (612 by 792 points).
documentInfo

A dictionary that specifies additional information to be associated with the PDF file. You can use these keys to specify additional metadata and security information for the PDF, such as the author of the PDF or the password for accessing it. The keys in this dictionary are the same keys you pass to the CGPDFContextCreate function and are described in the Auxiliary Dictionary Keys section of CGPDFContext Reference. The dictionary is retained by the new context, so on return you may safely release it. Specify nil if you do not want to associate any additional information with the PDF document. Return Value YES if the PDF context was created successfully or NO if it was not. Discussion After creating the graphics context, this function makes it the current drawing context. Any subsequent drawing commands are therefore captured and turned into PDF data. When you are done drawing, you must call the UIGraphicsEndPDFContext function to close the PDF graphics context. You can use all of the same drawing routines that you would normally use to draw the contents of your application. However, before you issue any drawing commands to a PDF context, you must start a new page by calling the UIGraphicsBeginPDFPage (page 25) or UIGraphicsBeginPDFPageWithInfo (page 26) function. You can also use these functions to define additional pages later. After creating it, you can get the PDF context using the UIGraphicsGetCurrentContext (page 28) function. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIGraphicsBeginPDFPage
Marks the beginning of a new page in a PDF context and configures it using default values.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

25

UIKit Function Reference

void UIGraphicsBeginPDFPage ( void );

Discussion This function ends any previous page before beginning a new one. It sets the media box of the new page to the rectangle you specified when you created the PDF context. If the current graphics context is not a PDF context, this function does nothing. You must call this function or the UIGraphicsBeginPDFPageWithInfo (page 26) function before you issue any drawing commands. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIGraphicsBeginPDFPageWithInfo
Marks the beginning of a new page in a PDF context and configures it using the specified values.
void UIGraphicsBeginPDFPageWithInfo ( CGRect bounds, NSDictionary *pageInfo );

Parameters
bounds

A rectangle that specifies the size and location of the new PDF page. This rectangle corresponds to the media box rectangle for the page.
pageInfo

A dictionary that specifies additional page-related information, such as the boxes that define different parts of the page. For a list of keys you can include in this dictionary, see Box Dictionary Keys in CGPDFContext Reference. The dictionary is retained by the new page, so you may release it after this function returns. Specify nil if you do not want to associate any additional information with the page. Discussion This function ends any previous page before beginning a new one. It sets the media box of the new page to the value in the kCGPDFContextMediaBox key of the pageInfo dictionary, or to the value in the bounds parameter if the dictionary does not contain the key. If the current graphics context is not a PDF context, this function does nothing. You must call this function or the UIGraphicsBeginPDFPageWithInfo (page 26) function before you issue any drawing commands. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

26

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

UIGraphicsEndImageContext
Removes the current bitmap-based graphics context from the top of the stack.
void UIGraphicsEndImageContext ( void );

Discussion You use this function to clean up the drawing environment put in place by the UIGraphicsBeginImageContext function and to remove the corresponding bitmap-based graphics context from the top of the stack. If the current context was not created using the UIGraphicsBeginImageContext function, this function does nothing. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. See Also
UIGraphicsBeginImageContext (page 22)

Related Sample Code iPhoneCoreDataRecipes LazyTableImages MapCallouts TheElements ZoomingPDFViewer Declared In


UIGraphics.h

UIGraphicsEndPDFContext
Closes a PDF graphics context and pops it from the current context stack.
void UIGraphicsEndPDFContext ( void );

Discussion You must call this function after you finish drawing to a PDF graphics context. This function closes the current open page and removes the PDF context from the graphics context stack. It also releases the CGContextRef associated with the PDF context. If the current graphics context is not a PDF context, this function does nothing. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

27

UIKit Function Reference

UIGraphicsGetCurrentContext
Returns the current graphics context.
CGContextRef UIGraphicsGetCurrentContext ( void );

Return Value The current graphics context. Discussion The current graphics context is nil by default. Prior to calling its drawRect: method, view objects push a valid context onto the stack, making it current. If you are not using a UIView object to do your drawing, however, you must push a valid context onto the stack manually using the UIGraphicsPushContext (page 30) function. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. See Also
UIGraphicsPushContext (page 30) UIGraphicsPopContext (page 29)

Related Sample Code AccelerometerGraph PhotoScroller SpeakHere Teslameter ZoomingPDFViewer Declared In


UIGraphics.h

UIGraphicsGetImageFromCurrentImageContext
Returns an image based on the contents of the current bitmap-based graphics context.
UIImage * UIGraphicsGetImageFromCurrentImageContext ( void );

Return Value A image object containing the contents of the current bitmap graphics context. Discussion You should call this function only when a bitmap-based graphics context is the current graphics context. If the current context is nil or was not created by a call to UIGraphicsBeginImageContext, this function returns nil. You should call this function from the main thread of your application only.

28

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Availability Available in iOS 2.0 and later. See Also


UIGraphicsBeginImageContext (page 22)

Related Sample Code iPhoneCoreDataRecipes LazyTableImages MapCallouts TheElements ZoomingPDFViewer Declared In


UIGraphics.h

UIGraphicsGetPDFContextBounds
Returns the current page bounds.
CGRect UIGraphicsGetPDFContextBounds ( void );

Return Value The current page bounds associated with the PDF context or CGRectZero if the current context is not a PDF context. Discussion If a page has not yet been started, this function returns the default media box you specified when you created the PDF context; otherwise, it returns the page bounds for the current page. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIGraphicsPopContext
Removes the current graphics context from the top of the stack, restoring the previous context.
void UIGraphicsPopContext ( void );

Discussion Use this function to balance calls to the UIGraphicsPushContext (page 30) function. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

29

UIKit Function Reference

See Also
UIGraphicsPushContext (page 30)

Declared In
UIGraphics.h

UIGraphicsPushContext
Makes the specified graphics context the current context.
void UIGraphicsPushContext ( CGContextRef context );

Parameters
context

The graphics context to make the current context. Discussion You can use this function to save the previous graphics state and make the specified context the current context. You must balance calls to this function with matching calls to the UIGraphicsPopContext (page 29) function. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. See Also
UIGraphicsPopContext (page 29)

Declared In
UIGraphics.h

UIGraphicsSetPDFContextDestinationForRect
Links a rectangle on the current page to the specified jump destination.
void UIGraphicsSetPDFContextDestinationForRect ( NSString *name, CGRect rect );

Parameters
name

A named destination in the PDF document. This is the same name you used when creating the jump destination using the UIGraphicsAddPDFContextDestinationAtPoint (page 21) function.
rect

A rectangle on the current page of the PDF context. Discussion You use this function to create live links within a PDF document. Tapping the specified rectangle in the PDF document causes the document to display the contents at the associated jump destination.

30

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

If the current graphics context is not a PDF context, this function does nothing. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIGraphicsSetPDFContextURLForRect
Links a rectangle on the current page to the specified URL.
void UIGraphicsSetPDFContextURLForRect ( NSURL *url, CGRect rect );

Parameters
url

The URL to open.


rect

A rectangle on the current page of the PDF context. Discussion You use this function to create external links within a PDF document. If the URL you specify is a type handled by a different application, tapping the rectangle opens that application. If the current graphics context is not a PDF context, this function does nothing. Availability Available in iOS 3.2 and later. Declared In
UIGraphics.h

UIImageJPEGRepresentation
Returns the data for the specified image in JPEG format.
NSData * UIImageJPEGRepresentation ( UIImage *image, CGFloat compressionQuality );

Parameters
image

The original image data.


compressionQuality

The quality of the resulting JPEG image, expressed as a value from 0.0 to 1.0. The value 0.0 represents the maximum compression (or lowest quality) while the value 1.0 represents the least compression (or best quality).

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

31

UIKit Function Reference

Return Value A data object containing the JPEG data, or nil if there was a problem generating the data. This function may return nil if the image has no data or if the underlying CGImageRef contains data in an unsupported bitmap format. Discussion If the image objects underlying image data has been purged, calling this function forces that data to be reloaded into memory. Availability Available in iOS 2.0 and later. Declared In
UIImage.h

UIImagePNGRepresentation
Returns the data for the specified image in PNG format
NSData * UIImagePNGRepresentation ( UIImage *image );

Parameters
image

The original image data. Return Value A data object containing the PNG data, or nil if there was a problem generating the data. This function may return nil if the image has no data or if the underlying CGImageRef contains data in an unsupported bitmap format. Discussion If the image objects underlying image data has been purged, calling this function forces that data to be reloaded into memory. Availability Available in iOS 2.0 and later. Related Sample Code iPhoneCoreDataRecipes PhotoLocations Declared In
UIImage.h

UIImageWriteToSavedPhotosAlbum
Adds the specified image to the users Camera Roll album.

32

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

void UIImageWriteToSavedPhotosAlbum ( UIImage *image, id completionTarget, SEL completionSelector, void *contextInfo );

Parameters
image

The image to write to the Camera Roll album.


completionTarget

Optionally, the object whose selector should be called after the image has been written to the Camera Roll album.
completionSelector

The method selector, of the completionTarget object, to call. This optional method should conform to the following signature:
- (void) image: (UIImage *) image didFinishSavingWithError: (NSError *) error contextInfo: (void *) contextInfo;

contextInfo

An optional pointer to any context-specific data that you want passed to the completion selector. Discussion When used with an image picker controller, you would typically call this function within your imagePickerController:didFinishPickingMediaWithInfo: delegate method implementation. The use of the completionTarget, completionSelector, and contextInfo parameters is optional and necessary only if you want to be notified asynchronously when the function finishes writing the image to the users Camera Roll or Saved Photos album. If you do not want to be notified, pass nil for these parameters. When used on an iOS device without a camera, this method adds the image to the Saved Photos album rather than to the Camera Roll album. Availability Available in iOS 2.0 and later. See Also
UISaveVideoAtPathToSavedPhotosAlbum (page 39)

Declared In
UIImagePickerController.h

UIInterfaceOrientationIsLandscape
Returns a Boolean value indicating whether the user interface is currently presented in a landscape orientation.
#define UIInterfaceOrientationIsLandscape(orientation) \ ((orientation) == UIInterfaceOrientationLandscapeLeft || \ (orientation) == UIInterfaceOrientationLandscapeRight)

Parameters
orientation

Specify the orientation constant to check.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

33

UIKit Function Reference

Return Value Returns YES if the interface orientation is landscape, otherwise returns NO. Discussion The interface orientation can be different than the device orientation. You typically use this macro in your view controller code to check the current orientation. Availability Available in iOS 2.0 and later. Related Sample Code AlternateViews Declared In
UIApplication.h

UIInterfaceOrientationIsPortrait
Returns a Boolean value indicating whether the user interface is currently presented in a portrait orientation.
#define UIInterfaceOrientationIsPortrait(orientation) \ ((orientation) == UIInterfaceOrientationPortrait || \ (orientation) == UIInterfaceOrientationPortraitUpsideDown)

Parameters
orientation

Specify the orientation constant to check. Return Value Returns YES if the interface orientation is portrait, otherwise returns NO. Discussion The interface orientation can be different than the device orientation. You typically use this macro in your view controller code to check the current orientation. Availability Available in iOS 2.0 and later. Declared In
UIApplication.h

UIOffsetEqualToOffset
Returns a Boolean value that indicates whether two offsets are equal.
BOOL UIOffsetEqualToOffset(UIOffset offset1, UIOffset offset2) { return offset1.horizontal == offset2.horizontal && offset1.vertical == offset2.vertical; }

Parameters
offset1

The offset to compare with offset2.

34

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

offset2

The offset to compare with offset1. Return Value YES if offset1 and offset2 are equal, otherwise NO. Availability Available in iOS 5.0 and later. Declared In
UIGeometry.h

UIOffsetFromString
Returns a UIKit offset structure corresponding to the data in a given string.
UIOffset UIOffsetFromString( NSString *string );

Parameters
string

A string containing a representation of an offset. Return Value An edge insets data structure. If the string is not well-formed, the function returns UIOffsetZero. Discussion In general, you should use this function only to convert strings that were previously created using the NSStringFromUIOffset function. Availability Available in iOS 5.0 and later. Declared In
UIGeometry.h

UIOffsetMake
Returns an offset structure from the given components.
UIOffset UIOffsetMake(CGFloat horizontal, CGFloat vertical) { UIOffset offset = {horizontal, vertical}; return offset; }

Parameters
horizontal

The horizontal offset.


vertical

The vertical offset. Return Value An offset structure with offsets horizontal and vertical.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

35

UIKit Function Reference

Availability Available in iOS 5.0 and later. Declared In


UIGeometry.h

UIRectClip
Modifies the current clipping path by intersecting it with the specified rectangle.
void UIRectClip ( CGRect rect );

Parameters
rect

The rectangle to intersect with the clipping region. If the width or height of the rectangle are less than 0, this function does not change the clipping path. Discussion Each call to this function permanently shrinks the clipping path of the current graphics context using the specified rectangle. You cannot use this function to expand the clipping region path. If the current graphics context is nil, this function does nothing. If you need to return the clipping path to its original shape in your drawing code, you should save the current graphics context before calling this function. To save the current state of the graphics context, call the CGContextSaveGState function before making your modifications. When you are ready to restore the original clipping region, you can then use the CGContextRestoreGState function to restore the previous graphics state. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. See Also
UIGraphicsPushContext (page 30) UIGraphicsPopContext (page 29)

Declared In
UIGraphics.h

UIRectFill
Fills the specified rectangle with the current color.
void UIRectFill ( CGRect rect );

Parameters
rect

The rectangle defining the area in which to draw.

36

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Discussion Fills the specified rectangle using the fill color of the current graphics context and the kCGBlendModeCopy blend mode. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. Related Sample Code CopyPasteTile PVRTextureLoader Declared In
UIGraphics.h

UIRectFillUsingBlendMode
Fills a rectangle with the current fill color using the specified blend mode.
void UIRectFillUsingBlendMode ( CGRect rect, CGBlendMode blendMode );

Parameters
rect

The rectangle defining the area in which to draw.


blendMode

The blend mode to use during drawing. Discussion This function draws the rectangle in the current graphics context. If the current graphics context is nil, this function does nothing. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. Declared In
UIGraphics.h

UIRectFrame
Draws a frame around the inside of the specified rectangle.

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

37

UIKit Function Reference

void UIRectFrame ( CGRect rect );

Parameters
rect

The rectangle defining the area in which to draw. Discussion This function draws a frame around the inside of rect in the fill color of the current graphics context and using the kCGBlendModeCopy blend mode. The width is equal to 1.0 in the current coordinate system. Since the frame is drawn inside the rectangle, it is visible even if drawing is clipped to the rectangle. If the current graphics context is nil, this function does nothing. Because this function does not draw directly on the line, but rather inside it, it uses the current fill color (not stroke color) when drawing. You should call this function from the main thread of your application only. Availability Available in iOS 2.0 and later. Related Sample Code CopyPasteTile Declared In
UIGraphics.h

UIRectFrameUsingBlendMode
Draws a frame around the inside of a rectangle using the specified blend mode.
void UIRectFrameUsingBlendMode ( CGRect rect, CGBlendMode blendMode );

Parameters
rect

The rectangle defining the area in which to draw.


blendMode

The blend mode to use during drawing. Discussion This function draws a frame around the inside of rect in the fill color of the current graphics context and using the specified blend mode. The width is equal to 1.0 in the current coordinate system. Since the frame is drawn inside the rectangle, it is visible even if drawing is clipped to the rectangle. If the current graphics context is nil, this function does nothing. Because this function does not draw directly on the line, but rather inside it, it uses the current fill color (not stroke color) when drawing. You should call this function from the main thread of your application only.

38

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Availability Available in iOS 2.0 and later. Declared In


UIGraphics.h

UISaveVideoAtPathToSavedPhotosAlbum
Adds the movie at the specified path to the users Camera Roll album.
void UISaveVideoAtPathToSavedPhotosAlbum ( NSString *videoPath, id completionTarget, SEL completionSelector, void *contextInfo );

Parameters
videoPath

The filesystem path to the movie file you want to save to the Camera Roll album.
completionTarget

Optionally, the object whose selector should be called after the movie has been written to the Camera Roll album.
completionSelector

The method selector, of the completionTarget object, to call. This optional method should conform to the following signature:
- (void) video: (NSString *) videoPath didFinishSavingWithError: (NSError *) error contextInfo: (void *) contextInfo;

contextInfo

An optional pointer to any context-specific data that you want passed to the completion selector. Discussion When used with an image picker controller, you would typically call this function within your imagePickerController:didFinishPickingMediaWithInfo: delegate method implementation. Before calling this function, call the UIVideoAtPathIsCompatibleWithSavedPhotosAlbum function to determine if it is possible to save movies to the Camera Roll album. For a code example, refer to Camera Programming Topics for iOS. The use of the completionTarget, completionSelector, and contextInfo parameters is optional and necessary only if you want to be notified asynchronously when the function finishes writing the movie to the users Camera Roll or Saved Photos album. If you do not want to be notified, pass nil for these parameters. When used on an iOS device without a camera, this method adds the movie to the Saved Photos album rather than to the Camera Roll album. Availability Available in iOS 3.1 and later. See Also
UIImageWriteToSavedPhotosAlbum (page 32)

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

39

UIKit Function Reference

UIVideoAtPathIsCompatibleWithSavedPhotosAlbum (page 40)

Declared In
UIImagePickerController.h

UIVideoAtPathIsCompatibleWithSavedPhotosAlbum
Returns a Boolean value indicating whether the specified video can be saved to users Camera Roll album.
BOOL UIVideoAtPathIsCompatibleWithSavedPhotosAlbum ( NSString *videoPath );

Parameters
videoPath

The filesystem path to the movie file you want to save. Return Value YES if the video can be saved to the Camera Roll album or NO if it cannot. Discussion Not all devices are able to play video files placed in the users Camera Roll album. Before attempting to save a video, call this function and check its return value to ensure that saving the video is supported for the current device. For a code example, refer to Camera Programming Topics for iOS. When used on an iOS device without a camera, this method indicates whether the specified movie can be saved to the Saved Photos album rather than to the Camera Roll album. Availability Available in iOS 3.1 and later. See Also
UISaveVideoAtPathToSavedPhotosAlbum (page 39)

Declared In
UIImagePickerController.h

UI_USER_INTERFACE_IDIOM
Returns the interface idiom supported by the current device.
#define UI_USER_INTERFACE_IDIOM() \ ([[UIDevice currentDevice] respondsToSelector:@selector(userInterfaceIdiom)] ? \ [[UIDevice currentDevice] userInterfaceIdiom] : \ UIUserInterfaceIdiomPhone)

Return Value
UIUserInterfaceIdiomPhone if the device is an iPhone or iPod touch or UIUserInterfaceIdiomPad

if the device is an iPad. Availability Available in iOS 3.2 and later.

40

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

UIKit Function Reference

Declared In
UIDevice.h

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

41

UIKit Function Reference

42

Functions
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

REVISION HISTORY

Document Revision History

This table describes the changes to UIKit Function Reference. Date 2011-10-12 2010-11-15 Notes Updated for iOS v5.0. Improved descriptions of the UIImageWriteToSavedPhotosAlbum (page 32), UISaveVideoAtPathToSavedPhotosAlbum (page 39), and UIVideoAtPathIsCompatibleWithSavedPhotosAlbum (page 40) functions. Updated the threading and multitasking guidance for several functions. Added an accessibility function that allows you to determine if VoiceOver is running. Added the UIGraphicsBeginImageContextWithOptions (page 22) function. 2010-02-25 2009-08-04 Updated for iOS 3.2. Updated for iOS 3.1. Added description for the UISaveVideoAtPathToSavedPhotosAlbum (page 39) function. Added descriptions for the UIInterfaceOrientationIsPortrait (page 34) and UIInterfaceOrientationIsLandscape (page 33) macros. 2009-05-26 2009-05-19 Added an accessibility notification function. Added orientation macros and modified the description of the UIApplicationMain function. Added the interface orientation macros that were previously in the UIApplication class reference. Added device-related macro functions. First version of this document.

2010-09-15 2010-05-06

2008-11-12

2008-10-15 2008-04-03

43
2011-10-12 | 2011 Apple Inc. All Rights Reserved.

REVISION HISTORY

Document Revision History

44
2011-10-12 | 2011 Apple Inc. All Rights Reserved.