UIImageWriteToSavedPhotosAlbum

UIImageWriteToSavedPhotosAlbum:

Next

UIKit Function Reference

Overview

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

Functions by Task

Application Launch

UIApplicationMain

Image Manipulation

UIImageJPEGRepresentation

UIImagePNGRepresentation

Image and Movie Saving

UIImageWriteToSavedPhotosAlbum

UISaveVideoAtPathToSavedPhotosAlbum

UIVideoAtPathIsCompatibleWithSavedPhotosAlbum

Graphics

UIGraphicsGetCurrentContext

UIGraphicsPushContext

UIGraphicsPopContext

UIGraphicsBeginImageContext

UIGraphicsBeginImageContextWithOptions

UIGraphicsGetImageFromCurrentImageContext

UIGraphicsEndImageContext

UIRectClip

UIRectFill

UIRectFillUsingBlendMode

UIRectFrame

UIRectFrameUsingBlendMode

Creating a Dictionary

NSDictionaryOfVariableBindings

PDF Creation

UIGraphicsBeginPDFContextToData

UIGraphicsBeginPDFContextToFile

UIGraphicsEndPDFContext

UIGraphicsBeginPDFPage

UIGraphicsBeginPDFPageWithInfo

UIGraphicsGetPDFContextBounds

UIGraphicsAddPDFContextDestinationAtPoint

UIGraphicsSetPDFContextDestinationForRect

UIGraphicsSetPDFContextURLForRect

String Conversions

CGAffineTransformFromString

CGPointFromString

CGRectFromString

CGSizeFromString

NSStringFromCGAffineTransform

NSStringFromCGPoint

NSStringFromCGRect

NSStringFromCGSize

NSStringFromUIEdgeInsets

NSStringFromUIOffset

UIEdgeInsetsFromString

UIOffsetFromString

Managing Edge Insets

UIEdgeInsetsMake

UIEdgeInsetsEqualToEdgeInsets

UIEdgeInsetsInsetRect

Managing Offsets

UIOffsetMake

UIOffsetEqualToOffset

Interface Orientation Macros

UIInterfaceOrientationIsPortrait

UIInterfaceOrientationIsLandscape

Device Orientation Macros

UIDeviceOrientationIsValidInterfaceOrientation

UIDeviceOrientationIsPortrait

UIDeviceOrientationIsLandscape

Interface Idiom Macro

UI_USER_INTERFACE_IDIOM

Accessibility

UIAccessibilityPostNotification

UIAccessibilityIsVoiceOverRunning

UIAccessibilityIsClosedCaptioningEnabled

UIAccessibilityRequestGuidedAccessSession

UIAccessibilityIsGuidedAccessEnabled

UIAccessibilityIsInvertColorsEnabled

UIAccessibilityIsMonoAudioEnabled

UIAccessibilityZoomFocusChanged

UIAccessibilityRegisterGestureConflictWithZoom

UIAccessibilityConvertFrameToScreenCoordinates

UIAccessibilityConvertPathToScreenCoordinates

Text Manipulations

NSTextAlignmentToCTTextAlignment

NSTextAlignmentFromCTTextAlignment

Guided Access Restriction State

UIGuidedAccessRestrictionStateForIdentifier

Functions

CGAffineTransformFromString

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

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

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.

See Also

NSStringFromCGPoint

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

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.

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

Declared In

UIGeometry.h

NSDictionaryOfVariableBindings

Creates a dictionary wherein the keys are string representations of the corresponding values’ variable names.

#define NSDictionaryOfVariableBindings(...) _NSDictionaryOfVariableBindings(@"" # __VA_ARGS__, __VA_ARGS__, nil)

Discussion
This macro is particularly useful when creating Autolayout constraints—see Auto Layout Guide. For example, the following code:

NSDictionary *viewsDictionary = NSDictionaryOfVariableBindings(button1, button2);

creates the dictionary

{ @"button1" = button1, @"button2 = button2 }.

Availability

Available in iOS 6.0 and later.

Related Sample Code

PrefsInCloud

ViewTransitions

Declared In

NSLayoutConstraint.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

for a discussion of the string format.

Availability

Available in iOS 2.0 and later.

See Also

CGAffineTransformFromString

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.

Return Value
A string that corresponds to point. See

CGPointFromString

for a discussion of the string format.

Availability

Available in iOS 2.0 and later.

See Also

CGPointFromString

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

for a discussion of the string format.

Availability

Available in iOS 2.0 and later.

See Also

CGRectFromString

Related Sample Code

AdvancedURLConnections

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

for a discussion of the string format.

Availability

Available in iOS 2.0 and later.

See Also

CGSizeFromString

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

for a discussion of the string format.

Availability

Available in iOS 2.0 and later.

See Also

UIEdgeInsetsFromString

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

Declared In

UIGeometry.h

NSTextAlignmentFromCTTextAlignment

Converts a Core Text alignment constant value to the matching constant value used by UIKit.

NSTextAlignment NSTextAlignmentFromCTTextAlignment(CTTextAlignment ctTextAlignment);

Parameters
ctTextAlignment
The Core text alignment constant you want to convert.

Return Value
The UIKit text alignment that corresponds to the value specified in ctTextAlignment.

Discussion
Use this function when you need to map between the Core Text and UIKit constants for text alignment.

Availability

Available in iOS 6.0 and later.

Declared In

NSText.h

NSTextAlignmentToCTTextAlignment

Converts a UIKit text alignment constant value to the matching constant value used by Core Text.

CTTextAlignment NSTextAlignmentToCTTextAlignment(NSTextAlignment nsTextAlignment);

Parameters
nsTextAlignment
The UIKit text alignment constant you want to convert.

Return Value
The Core Text alignment that corresponds to the value specified in nsTextAlignment.

Discussion
Use this function when you need to map between the UIKit and Core Text constants for text alignment.

Availability

Available in iOS 6.0 and later.

Declared In

NSText.h

UIAccessibilityConvertFrameToScreenCoordinates

Converts the specified rectangle from view coordinates to screen coordinates.

CGRect UIAccessibilityConvertFrameToScreenCoordinates(CGRect rect, UIView *view)

Parameters
rect
A rectangle specified in the coordinate system of the specified view.

view
The view that contains the specified rectangle. This parameter must not be

nil

.

Return Value
The rectangle in screen coordinates.

Discussion
Use this function to convert accessibility frame rectangles to screen coordinates.

Availability

Available in iOS 7.0 and later.

Declared In

UIAccessibility.h

UIAccessibilityConvertPathToScreenCoordinates

Converts the specified path object to screen coordinates and returns a new path object with the results.

UIBezierPath *UIAccessibilityConvertPathToScreenCoordinates(UIBezierPath *path, UIView *view)

Parameters
path
The path object that you want to convert. The coordinate values used to create this path object should be relative to the coordinate system of the specifiedview. This parameter must not be

nil

.

view
The view whose coordinate system was used to define the path. This parameter must not be

nil

.

Return Value
A new path object that has the same shape as path but whose points are specified in screen coordinates.

Discussion
This function adjusts the points of the path you provide to values that the accessibility system can use. You can use it to convert path objects in use by your app’s user interface before handing them to the accessibility system.

Availability

Available in iOS 7.0 and later.

Declared In

UIAccessibility.h

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

UIAccessibilityIsGuidedAccessEnabled

Returns a Boolean value indicating whether Guided Access is enabled.

BOOL UIAccessibilityIsGuidedAccessEnabled();

Return Value

YES

if the user has enabled Guided Access in Settings; otherwise,

NO

.

Availability

Available in iOS 6.0 and later.

Declared In

UIAccessibility.h

UIAccessibilityIsInvertColorsEnabled

Returns a Boolean value indicating whether inverted colors is enabled.

BOOL UIAccessibilityIsInvertColorsEnabled();

Return Value

YES

if the user has enabled inverted colors in Settings; otherwise,

NO

.

Availability

Available in iOS 6.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 application’s 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

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

CoreTextPageViewer

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 multi-finger 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

UIAccessibilityRequestGuidedAccessSession

Transitions the app to or from Single App mode asynchronously.

void UIAccessibilityRequestGuidedAccessSession(BOOL enable, void(^completionHandler)(BOOL didSucceed))

Parameters
enable
Specify

YES

to put the device into Single App mode for this app or

NO

to exit Single App mode.

completionHandler
The block that notifies your app of the success or failure of the operation. This block takes the following parameter:

didSucceed
If

YES

, the app transitioned to or from Single App mode successfully. If

NO

, the app or device is not eligible for Single App mode or there was some other error.

Discussion
You can use this method to lock your app into Single App mode and to release it from that mode later. For example, a test-taking app might enter this mode at the beginning of a test and exit it when the user completes the test. Entering Single App mode is supported only for devices that are supervised using Mobile Device Management (MDM), and the app itself must be enabled for this mode by MDM. You must balance each call to enter Single App mode with a call to exit that mode.

Because entering or exiting Single App mode might take some time, this method executes asynchronously and notifies you of the results using thecompletionHandler block.

Availability

Available in iOS 7.0 and later.

See Also

UIAccessibilityIsGuidedAccessEnabled

Declared In

UIAccessibility.h

UIAccessibilityZoomFocusChanged

Notifies the system that the app’s focus has changed to a new location.

void UIAccessibilityZoomFocusChanged(
UIAccessibilityZoomType type,
CGRect frame,
UIView *view
);

Parameters
type
A

Introduction

constant that identifies the type of Zoom.

frame
The frame that is currently zoomed, in screen coordinates.

view
The view that contains the zoomed frame.

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.

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 application’s main nib file.

Return Value
Even though an integer return type is specified, this function never returns. When users exits an iOS application by pressing the Home button, the application moves to the background.

Discussion
This function instantiates the application object from the principal class 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 application’s run loop, and begins processing events. If the application’s

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 ““Core App Objects”” in iOS App Programming Guide.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Handling Touches Using Responder Methods and Gesture Recognizers

iAdInterstitialSuite

iAdSuite

Inter-App Audio Examples

TableView Fundamentals for iOS

Declared In

UIApplication.h

UIDeviceOrientationIsLandscape

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

#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

RosyWriter

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.

Related Sample Code

RosyWriter

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.

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

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

.

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

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

Declared In

UIGeometry.h

UIEdgeInsetsMake

Creates an edge inset for a button or view.

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

Related Sample Code

MultipeerGroupChat

UIKit Printing with UIPrintInteractionController and UIViewPrintFormatter

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.

For information on how to create links to this destination, see the

UIGraphicsSetPDFContextDestinationForRect

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

function with the opaque parameter set to

NO

and a scale factor of

1.0

.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

Related Sample Code

AirDrop Examples

CoreTextPageViewer

Inter-App Audio Examples

iPhoneCoreDataRecipes

MapCallouts

Declared In

UIGraphics.h

UIGraphicsBeginImageContextWithOptions

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

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, specify

YES

to ignore the alpha channel and optimize the bitmap’s 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 device’s 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 bitmap is treated as fully opaque and its 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.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 4.0 and later.

See Also

UIGraphicsGetCurrentContext

UIGraphicsGetImageFromCurrentImageContext

UIGraphicsEndImageContext

Related Sample Code

AirDrop Examples

iAdSuite

Inter-App Audio Examples

LazyTableImages

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

or

UIGraphicsBeginPDFPageWithInfo

function. You can also use these functions to define additional pages later.

After creating it, you can get the PDF context using the

UIGraphicsGetCurrentContext

function.

Availability

Available in iOS 3.2 and later.

See Also

UIGraphicsEndPDFContext

Declared In

UIGraphics.h

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

or

UIGraphicsBeginPDFPageWithInfo

function. You can also use these functions to define additional pages later.

After creating it, you can get the PDF context using the

UIGraphicsGetCurrentContext

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.

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

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

function before you issue any drawing commands.

Availability

Available in iOS 3.2 and later.

Declared In

UIGraphics.h

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.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

See Also

UIGraphicsBeginImageContext

Related Sample Code

Inter-App Audio Examples

MapCallouts

MVCNetworking

SquareCam

TheElements

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

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

function.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

See Also

UIGraphicsPushContext

UIGraphicsPopContext

Related Sample Code

AccelerometerGraph

Inter-App Audio Examples

Large Image Downsizing

MotionGraphs

Teslameter

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

.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

See Also

UIGraphicsBeginImageContext

Related Sample Code

AirDrop Examples

Inter-App Audio Examples

iPhoneCoreDataRecipes

MapCallouts

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

function.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

See Also

UIGraphicsPushContext

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

function.

In iOS 4 and later, you may call this function from any thread of your app.

Availability

Available in iOS 2.0 and later.

See Also

UIGraphicsPopContext

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

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.

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

UIGuidedAccessRestrictionStateForIdentifier

Returns the restriction state for the specified guided access restriction.

UIGuidedAccessRestrictionState UIGuidedAccessRestrictionStateForIdentifier(NSString *restrictionIdentifier);

Parameters
restrictionIdentifier
The string that uniquely identifies the guided access restriction.

Return Value
The current state of the guided access restriction. The initial state of all restrictions is

UIGuidedAccessRestrictionStateAllow

.

Availability

Available in iOS 7.0 and later.

Declared In

UIGuidedAccessRestrictions.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).

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 object’s 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

MultipeerGroupChat

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 object’s 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

Core Data Transformable Attributes

iPhoneCoreDataRecipes

MVCNetworking

Declared In

UIImage.h

UIImageWriteToSavedPhotosAlbum

Adds the specified image to the user’s Camera Roll album.

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.