iPhone Application Programming Guide General 2009-01-06 Apple Inc © 2009 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 Apple’s copyright notice The Apple logo is a trademark of Apple Inc Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws 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 Every effort has been made to ensure that the information in this document is accurate Apple is not responsible for typographical errors Apple Inc Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Bonjour, Carbon, Cocoa, iPod, iTunes, Mac, Mac OS, Macintosh, Objective-C, Pages, Quartz, Safari, Sand, and Xcode are trademarks of Apple Inc., registered in the United States and other countries Finder, iPhone, and Multi-Touch are trademarks of Apple Inc NeXT is a trademark of NeXT Software, Inc., registered in the United States and other countries Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc in the U.S and other countries OpenGL is a registered trademark of Silicon Graphics, Inc Simultaneously published in the United States and Canada 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 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 Introduction Introduction 11 Who Should Read This Document? 12 Organization of This Document 12 Providing Feedback 12 See Also 13 Chapter The Core Application 15 Core Application Architecture 15 The Application Life Cycle 15 The Event-Handling Cycle 18 Fundamental Design Patterns 20 The Application Runtime Environment 21 Fast Launch, Short Use 21 The Application Sandbox 21 The Virtual Memory System 22 The Automatic Sleep Timer 22 The Application Bundle 23 The Information Property List 25 Application Icon and Launch Images 27 Nib Files 28 Handling Critical Application Tasks 29 Initialization and Termination 29 Responding to Interruptions 29 Observing Low-Memory Warnings 31 Customizing Your Application’s Behavior 32 Launching in Landscape Mode 32 Communicating with Other Applications 33 Implementing Custom URL Schemes 34 Displaying Application Preferences 37 Internationalizing Your Application 37 Tuning for Performance and Responsiveness 39 Using Memory Efficiently 40 Floating-Point Math Considerations 41 Reducing Power Consumption 42 Tuning Your Code 43 Chapter Window and Views 45 What Are Windows and Views? 45 The Role of UIWindow 45 2009-01-06 | © 2009 Apple Inc All Rights Reserved CONTENTS The Role of UIView 46 UIKit View Classes 47 The Role of View Controllers 50 View Architecture and Geometry 50 The View Interaction Model 50 The View Rendering Architecture 52 View Coordinate Systems 55 The Relationship of the Frame, Bounds, and Center 56 Coordinate System Transformations 57 Content Modes and Scaling 58 Autoresizing Behaviors 60 Creating and Managing the View Hierarchy 61 Creating a View Object 63 Adding and Removing Subviews 63 Converting Coordinates in the View Hierarchy 65 Tagging Views 66 Modifying Views at Runtime 66 Animating Views 67 Responding to Layout Changes 69 Redrawing Your View’s Content 69 Hiding Views 70 Creating a Custom View 70 Initializing Your Custom View 70 Drawing Your View’s Content 71 Responding to Events 72 Cleaning Up After Your View 73 Chapter Event Handling 75 Events and Touches 75 Event Delivery 77 Responder Objects and the Responder Chain 77 Regulating Event Delivery 78 Handling Multi-Touch Events 79 The Event-Handling Methods 79 Handling Single and Multiple Tap Gestures 80 Detecting Swipe Gestures 81 Handling a Complex Multi-Touch Sequence 82 Event-Handling Techniques 83 Chapter Graphics and Drawing 85 The UIKit Graphics System 85 The View Drawing Cycle 85 Coordinates and Coordinate Transforms 86 Graphics Contexts 87 2009-01-06 | © 2009 Apple Inc All Rights Reserved CONTENTS Points Versus Pixels 87 Color and Color Spaces 88 Supported Image Formats 88 Drawing Tips 89 Deciding When to Use Custom Drawing Code 89 Improving Drawing Performance 89 Maintaining Image Quality 90 Drawing with Quartz and UIKit 90 Configuring the Graphics Context 91 Creating and Drawing Images 92 Creating and Drawing Paths 94 Creating Patterns, Gradients, and Shadings 94 Drawing with OpenGL ES 94 Setting Up a Rendering Surface 95 Best Practices 96 Implementation Details 98 For More Information 102 Applying Core Animation Effects 102 About Layers 103 About Animations 103 Chapter Text and Web 105 About Text and Web Support 105 Text Views 105 Web View 107 Keyboards and Input Methods 108 Managing the Keyboard 110 Receiving Keyboard Notifications 110 Displaying the Keyboard 112 Dismissing the Keyboard 112 Moving Content That Is Located Under the Keyboard 113 Drawing Text 115 Chapter Files and Networking 117 File and Data Management 117 Commonly Used Directories 117 Backup and Restore 118 Getting Paths to Application Directories 119 Reading and Writing File Data 121 File Access Guidelines 124 Saving State Information 125 Case Sensitivity 125 Networking 125 Tips for Efficient Networking 126 2009-01-06 | © 2009 Apple Inc All Rights Reserved CONTENTS Using Wi-Fi 126 Chapter Multimedia Support 127 Using Sound in iPhone OS 127 The Basics: Hardware Codecs, Audio Formats, and Audio Sessions 128 Playing Audio 131 Recording Audio 137 Parsing Streamed Audio 138 Audio Unit Support in iPhone OS 139 Best Practices for iPhone Audio 139 Playing Video Files 141 Chapter Device Support 143 Accessing Accelerometer Events 143 Choosing an Appropriate Update Interval 144 Isolating the Gravity Component from Acceleration Data 145 Isolating Instantaneous Motion from Acceleration Data 145 Getting the Current Device Orientation 146 Getting the User’s Current Location 146 Taking Pictures with the Camera 148 Picking a Photo from the Photo Library 150 Chapter Application Preferences 151 Guidelines for Preferences 151 The Preferences Interface 152 The Settings Bundle 153 The Settings Page File Format 154 Hierarchical Preferences 155 Localized Resources 156 Adding and Modifying the Settings Bundle 156 Adding the Settings Bundle 156 Preparing the Settings Page for Editing 157 Configuring a Settings Page: A Tutorial 157 Creating Additional Settings Page Files 161 Accessing Your Preferences 161 Debugging Preferences for Simulated Applications 162 Document Revision History 163 2009-01-06 | © 2009 Apple Inc All Rights Reserved Figures, Tables, and Listings Chapter The Core Application 15 Figure 1-1 Figure 1-2 Figure 1-3 Figure 1-4 Figure 1-5 Figure 1-6 Figure 1-7 Figure 1-8 Table 1-1 Table 1-2 Table 1-3 Table 1-4 Table 1-5 Table 1-6 Table 1-7 Listing 1-1 Listing 1-2 Listing 1-3 Chapter Application life cycle 16 The event and drawing cycle 18 Processing events in the main run loop 19 The Properties pane of a target’s Info window 25 The information property list editor 26 The flow of events during an interruption 30 Defining a custom URL scheme in the Info.plist file 35 The Language preference view 38 Design patterns used by iPhone applications 20 A typical application bundle 23 Important keys in the Info.plist file 26 Responsibilities of the application delegate 29 Keys and values of the CFBundleURLTypes property 34 Tips for reducing your application’s memory footprint 40 Tips for allocating memory 41 The main function of an iPhone application 16 Handling a URL request based on a custom scheme 35 The contents of a language-localized subdirectory 38 Window and Views 45 Figure 2-1 Figure 2-2 Figure 2-3 Figure 2-4 Figure 2-5 Figure 2-6 Figure 2-7 Figure 2-8 Figure 2-9 Figure 2-10 Figure 2-11 Table 2-1 Table 2-2 Listing 2-1 Listing 2-2 Listing 2-3 Listing 2-4 View class hierarchy 48 UIKit interactions with your view objects 51 View coordinate system 55 Relationship between a view's frame and bounds 56 Altering a view's bounds 57 View scaled using the scale-to-fill content mode 58 Content mode comparisons 59 View autoresizing mask constants 61 Layered views in the Clock application 62 View hierarchy for the Clock application 62 Converting values in a rotated view 66 Autoresizing mask constants 60 Animatable properties 67 Creating a window with views 64 Initializing a view subclass 71 A drawing method 72 Implementing the dealloc method 73 2009-01-06 | © 2009 Apple Inc All Rights Reserved FIGURES, TABLES, AND LISTINGS Chapter Event Handling 75 Figure 3-1 Figure 3-2 Listing 3-1 Listing 3-2 Listing 3-3 Chapter Graphics and Drawing 85 Table 4-1 Table 4-2 Table 4-3 Table 4-4 Chapter Text classes in the UICatalog application 106 A web view 108 Several different keyboard types 109 Several different keyboards and input methods 110 Relative keyboard sizes in portrait and landscape modes 111 Adjusting content to accommodate the keyboard 113 Handling the keyboard notifications 114 Files and Networking 117 Table 6-1 Table 6-2 Listing 6-1 Listing 6-2 Listing 6-3 Listing 6-4 Listing 6-5 Chapter Supported image formats 88 Tips for improving drawing performance 89 Core graphics functions for modifying graphics state 91 Usage scenarios for images 93 Text and Web 105 Figure 5-1 Figure 5-2 Figure 5-3 Figure 5-4 Figure 5-5 Figure 5-6 Listing 5-1 Chapter A multi-touch sequence and touch phases 76 Relationship of a UIEvent object and its UITouch objects 76 Detecting a double-tap gesture 80 Tracking a swipe gesture in a view 81 Handling a complex multi-touch sequence 82 Directories of an iPhone application 117 Commonly used search path constants 120 Getting a file-system path to the application’s Documents/ directory 120 Converting a property-list object to an NSData object and writing it to storage 122 Reading a property-list object from the application’s Documents directory 122 Writing data to the application’s Documents directory 123 Reading data from the application’s Documents directory 124 Multimedia Support 127 Figure 7-1 Table 7-1 Table 7-2 Table 7-3 Table 7-4 Listing 7-1 Listing 7-2 Media player interface with transport controls 141 Features provided by the audio session interface 129 Handling audio interruptions 131 Supported audio units 139 Audio tips 139 Initializing an audio session 130 Setting an audio session category 130 2009-01-06 | © 2009 Apple Inc All Rights Reserved FIGURES, TABLES, AND LISTINGS Listing 7-3 Listing 7-4 Listing 7-5 Listing 7-6 Listing 7-7 Listing 7-8 Listing 7-9 Listing 7-10 Listing 7-11 Listing 7-12 Chapter Device Support 143 Table 8-1 Listing 8-1 Listing 8-2 Listing 8-3 Listing 8-4 Listing 8-5 Listing 8-6 Listing 8-7 Chapter Creating a sound ID object 132 Playing a system sound 132 Triggering vibration 133 Configuring an AVAudioPlayer object 133 Implementing an AVAudioPlayer delegate method 134 Controlling an AVAudioPlayer object 134 Creating an audio queue object 135 Setting the playback level directly 136 The AudioQueueLevelMeterState structure 137 Playing full-screen movies 141 Common update intervals for acceleration events 144 Configuring the accelerometer 143 Receiving an accelerometer event 144 Isolating the effects of gravity from accelerometer data 145 Getting the instantaneous portion of movement from accelerometer data 145 Initiating and processing location updates 147 Displaying the interface for taking pictures 149 Delegate methods for the image picker 149 Application Preferences 151 Figure 9-1 Figure 9-2 Figure 9-3 Table 9-1 Table 9-2 Table 9-3 Listing 9-1 Organizing preferences using child panes 155 Formatted contents of the Root.plist file 157 A root Settings page 158 Preference element types 152 Contents of the Settings.bundle directory 153 Root-level keys of a preferences Settings Page file 154 Accessing preference values in an application 162 2009-01-06 | © 2009 Apple Inc All Rights Reserved FIGURES, TABLES, AND LISTINGS 10 2009-01-06 | © 2009 Apple Inc All Rights Reserved ... View Controller Programming Guide for iPhone OS provides information on the use of view controllers in creating interfaces for iPhone applications ■ Table View Programming Guide for iPhone OS provides... titled iPhone OS Programming Guide The iPhone SDK provides the tools and resources needed to create native iPhone applications that appear as icons on the user’s Home screen Unlike a web application, ... Management Programming Guide for Cocoa For specific memory-management guidelines related to autorelease pools in iPhone applications, see “Allocating Memory Wisely” (page 41) The UIApplicationMain