Apple iPod_nano_5th_gen_UserGuide.pdf Apple sur FNAC.COM - Pour voir la liste complète des manuels APPLE, cliquez ici

 

 

TELECHARGER LE PDF sur : http://manuals.info.apple.com/en_US/iPod_nano_5th_gen_UserGuide.pdf

 

 

Voir également d'autres Guides APPLE :

Apple-Keynote2_UserGuide.pdf-Japon

Apple-Welcome_to_Tiger.pdf-Japon

Apple-XsanAdminGuide_j.pdf-Japon

Apple-PowerBookG4_UG_15GE.PDF-Japon

Apple-Xsan_Migration.pdf-Japon

Apple-Xserve_Intel_DIY_TopCover_JA.pdf-Japon

Apple-iPod_nano_6thgen_User_Guide_J.pdf-Japon

Apple-Aperture_Photography_Fundamentals.pdf-Japon

Apple-nikeipod_users_guide.pdf-Japon

Apple-QuickTime71_UsersGuide.pdf-Japon

Apple-iMacG5_iSight_UG.pdf-Japon

Apple-Aperture_Performing_Adjustments_j.pdf-Japon

Apple-iMacG5_17inch_HardDrive.pdf-Japon

Apple-iPod_shuffle_Features_Guide_J.pdf-Japon

Apple-MacBook_Air_User_Guide.pdf-Japon

Apple-MacBook_UsersGuide.pdf-Japon

Apple-iPad_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-Apple_AirPort_Networks_Early2009_H.pd-Norge-Norvege

Apple-iPod_classic_120GB_no.pdf-Norge-Norvege

Apple-StoreKitGuide.pdf-Japon

Apple-Xserve_Intel_DIY_ExpansionCardRiser_JA.pdf-Japon

Apple-iMacG5_Battery.pdf-Japon

Apple-Logic_Pro_8_Getting_Started.pdf-Japon

Apple-PowerBook-handbok-Norge-Norveg

Apple-iWork09_formler_og_funksjoner.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacPro_HardDrive_DIY.pdf-Japon

Apple-iPod_Fifth_Gen_Funksjonsoversikt.pdf-Norge-Norvege

Apple-MacBook_13inch_white_Early2009_H.pdf-Norge-Norvege

Apple-GarageBand_09_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2009_H.pdf-Norge-Norvege

Apple-imac_mid2011_ug_h.pdf-Norge-Norvege

Apple-iDVD_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iMac_Mid2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_13inch_Mid2009_H.pdf-Norge-Norvege

/Apple-iPhone_3G_Viktig_produktinformasjon_H-Norge-Norvege

Apple-MacBook_13inch_Mid2010_UG_H.pdf-Norge-Norvege

Apple-macbook_air_13inch_mid2011_ug_no.pdf-Norge-Norvege

Apple-Mac_mini_Early2009_UG_H.pdf-Norge-Norvege

Apple-ipad2_brukerhandbok.pdf-Norge-Norvege

Apple-iPhoto_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_Brukerhandbok_Late2008.pdf-Norge-Norvege

Apple-Pages09_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_13inch_Late2009_UG_H.pdf-Norge-Norvege

Apple-iPhone_3GS_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple-MacBook_13inch_Aluminum_Late2008_H.pdf-Norge-Norvege

Apple-Wireless_Keyboard_Aluminum_2007_H-Norge-Norvege

Apple-NiPod_photo_Brukerhandbok_N0190269.pdf-Norge-Norvege

Apple-MacBook_Pro_13inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacBook_Pro_17inch_Mid2010_H.pdf-Norge-Norvege

Apple-Velkommen_til_Snow_Leopard.pdf-Norge-Norvege.htm

Apple-TimeCapsule_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iPhone_3GS_Hurtigstart.pdf-Norge-Norvege

Apple-Snow_Leopard_Installeringsinstruksjoner.pdf-Norge-Norvege

Apple-iMacG5_iSight_UG.pdf-Norge-Norvege

Apple-iPod_Handbok_S0342141.pdf-Norge-Norvege

Apple-ipad_brukerhandbok.pdf-Norge-Norvege

Apple-GE_Money_Bank_Handlekonto.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iPod_nano_6thgen_Brukerhandbok.pdf-Norge-Norvege

Apple-iPod_touch_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_Air_13inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Early2011_H.pdf-Norge-Norvege

Apple-Numbers09_Brukerhandbok.pdf-Norge-Norvege

Apple-Welcome_to_Leopard.pdf-Japon

Apple-PowerMacG5_UserGuide.pdf-Norge-Norvege

Apple-iPod_touch_2.1_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering-klargjoring.pdf-Norge-Norvege

Apple-MacOSX10.3_Welcome.pdf-Norge-Norvege

Apple-iPod_shuffle_3rdGen_UG_H.pdf-Norge-Norvege

Apple-iPhone_4_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple_TV_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iMovie_08_Komme_i_gang.pdf-Norge-Norvege

Apple-iPod_classic_160GB_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering_10.6.pdf-Norge-Norvege

Apple-Network-Services-Location-Manager-Veiledning-for-nettverksadministratorer-Norge-Norvege

Apple-iOS_Business_Mar12_FR.pdf

Apple-PCIDualAttachedFDDICard.pdf

Apple-Aperture_Installing_Your_Software_f.pdf

Apple-User_Management_Admin_v10.4.pdf

Apple-Compressor-4-ユーザーズマニュアル Japon

Apple-Network_Services_v10.4.pdf

Apple-iPod_2ndGen_USB_Power_Adapter-DE

Apple-Mail_Service_v10.4.pdf

Apple-AirPort_Express_Opstillingsvejledning_5.1.pdf

Apple-MagSafe_Airline_Adapter.pdf

Apple-L-Apple-Multiple-Scan-20-Display

Apple-Administration_du_service_de_messagerie_10.5.pdf

Apple-System_Image_Admin.pdf

Apple-iMac_Intel-based_Late2006.pdf-Japon

Apple-iPhone_3GS_Finger_Tips_J.pdf-Japon

Apple-Power-Mac-G4-Mirrored-Drive-Doors-Japon

Apple-AirMac-カード取り付け手順-Japon

Apple-iPhone開発ガイド-Japon

Apple-atadrive_pmg4mdd.j.pdf-Japon

Apple-iPod_touch_2.2_User_Guide_J.pdf-Japon

Apple-Mac_OS_X_Server_v10.2.pdf

Apple-AppleCare_Protection_Plan_for_Apple_TV.pdf

Apple_Component_AV_Cable.pdf

Apple-DVD_Studio_Pro_4_Installation_de_votre_logiciel

Apple-Windows_Services

Apple-Motion_3_New_Features_F

Apple-g4mdd-fw800-lowerfan

Apple-MacOSX10.3_Welcome

Apple-Print_Service

Apple-Xserve_Setup_Guide_F

Apple-PowerBookG4_17inch1.67GHzUG

Apple-iMac_Intel-based_Late2006

Apple-Installation_de_votre_logiciel

Apple-guide_des_fonctions_de_l_iPod_nano

Apple-Administration_de_serveur_v10.5

Apple-Mac-OS-X-Server-Premiers-contacts-Pour-la-version-10.3-ou-ulterieure

Apple-boot_camp_install-setup

Apple-iBookG3_14inchUserGuideMultilingual

Apple-mac_pro_server_mid2010_ug_f

Apple-Motion_Supplemental_Documentation

Apple-imac_mid2011_ug_f

Apple-iphone_guide_de_l_utilisateur

Apple-macbook_air_11inch_mid2011_ug_fr

Apple-NouvellesfonctionnalitesdeLogicExpress7.2

Apple-QT_Streaming_Server

Apple-Web_Technologies_Admin

Apple-Mac_Pro_Early2009_4707_UG

Apple-guide_de_l_utilisateur_de_Numbers08

Apple-Decouverte_d_Aperture_2

Apple-Guide_de_configuration_et_d'administration

Apple-mac_integration_basics_fr_106.

Apple-iPod_shuffle_4thgen_Guide_de_l_utilisateur

Apple-ARA_Japan

Apple-081811_APP_iPhone_Japanese_v5.4.pdf-Japan

Apple-Recycle_Contract120919.pdf-Japan

Apple-World_Travel_Adapter_Kit_UG

Apple-iPod_nano_6thgen_User_Guide

Apple-RemoteSupportJP

Apple-Mac_mini_Early2009_UG_F.pdf-Manuel-de-l-utilisateur

Apple-Compressor_3_Batch_Monitor_User_Manual_F.pdf-Manuel-de-l-utilisateur

Apple-Premiers__contacts_avec_iDVD_08

Apple-Mac_mini_Intel_User_Guide.pdf

Apple-Prise_en_charge_des_surfaces_de_controle_Logic_Express_8

Apple-mac_integration_basics_fr_107.pdf

Apple-Final-Cut-Pro-7-Niveau-1-Guide-de-preparation-a-l-examen

Apple-Logic9-examen-prep-fr.pdf-Logic-Pro-9-Niveau-1-Guide-de-preparation-a-l-examen

Apple-aperture_photography_fundamentals.pdf-Manuel-de-l-utilisateu

Apple-emac-memory.pdf-Manuel-de-l-utilisateur

Apple-Apple-Installation-et-configuration-de-votre-Power-Mac-G4

Apple-Guide_de_l_administrateur_d_Xsan_2.pdf

Apple-premiers_contacts_avec_imovie6.pdf

Apple-Tiger_Guide_Installation_et_de_configuration.pdf

Apple-Final-Cut-Pro-7-Level-One-Exam-Preparation-Guide-and-Practice-Exam

Apple-Open_Directory.pdf

Apple-Nike_+_iPod_User_guide

Apple-ard_admin_guide_2.2_fr.pdf

Apple-systemoverviewj.pdf-Japon

Apple-Xserve_TO_J070411.pdf-Japon

Apple-Mac_Pro_User_Guide.pdf

Apple-iMacG5_iSight_UG.pdf

Apple-premiers_contacts_avec_iwork_08.pdf

Apple-services_de_collaboration_2e_ed_10.4.pdf

Apple-iPhone_Bluetooth_Headset_Benutzerhandbuch.pdf

Apple-Guide_de_l_utilisateur_de_Keynote08.pdf

APPLE/Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-iPod_shuffle_3rdGen_UG_F.pdf

Apple-iPod_classic_160Go_Guide_de_l_utilisateur.pdf

Apple-iBookG4GettingStarted.pdf

Apple-Administration_de_technologies_web_10.5.pdf

Apple-Compressor-4-User-Manual-fr

Apple-MainStage-User-Manual-fr.pdf

Apple-Logic_Pro_8.0_lbn_j.pdf

Apple-PowerBookG4_15inch1.67-1.5GHzUserGuide.pdf

Apple-MacBook_Pro_15inch_Mid2010_CH.pdf

Apple-LED_Cinema_Display_27-inch_UG.pdf

Apple-MacBook_Pro_15inch_Mid2009_RS.pdf

Apple-macbook_pro_13inch_early2011_f.pdf

Apple-iMac_Mid2010_UG_BR.pdf

Apple-iMac_Late2009_UG_J.pdf

Apple-iphone_user_guide-For-iOS-6-Software

Apple-iDVD5_Getting_Started.pdf

Apple-guide_des_fonctionnalites_de_l_ipod_touch.pdf

Apple_iPod_touch_User_Guide

Apple_macbook_pro_13inch_early2011_f

Apple_Guide_de_l_utilisateur_d_Utilitaire_RAID

Apple_Time_Capsule_Early2009_Setup_F

Apple_iphone_4s_finger_tips_guide_rs

Apple_iphone_upute_za_uporabu

Apple_ipad_user_guide_ta

Apple_iPod_touch_User_Guide

apple_earpods_user_guide

apple_iphone_gebruikershandleiding

apple_iphone_5_info

apple_iphone_brukerhandbok

apple_apple_tv_3rd_gen_setup_tw

apple_macbook_pro-retina-mid-2012-important_product_info_ch

apple_Macintosh-User-s-Guide-for-Macintosh-PowerBook-145

Apple_ipod_touch_user_guide_ta

Apple_TV_2nd_gen_Setup_Guide_h

Apple_ipod_touch_manual_del_usuario

Apple_iphone_4s_finger_tips_guide_tu

Apple_macbook_pro_retina_qs_th

Apple-Manuel_de_l'utilisateur_de_Final_Cut_Server

Apple-iMac_G5_de_lutilisateur

Apple-Cinema_Tools_4.0_User_Manual_F

Apple-Personal-LaserWriter300-User-s-Guide

Apple-QuickTake-100-User-s-Guide-for-Macintosh

Apple-User-s-Guide-Macintosh-LC-630-DOS-Compatible

Apple-iPhone_iOS3.1_User_Guide

Apple-iphone_4s_important_product_information_guide

Apple-iPod_shuffle_Features_Guide_F

Liste-documentation-apple

Apple-Premiers_contacts_avec_iMovie_08

Apple-macbook_pro-retina-mid-2012-important_product_info_br

Apple-macbook_pro-13-inch-mid-2012-important_product_info

Apple-macbook_air-11-inch_mid-2012-qs_br

Apple-Manuel_de_l_utilisateur_de_MainStage

Apple-Compressor_3_User_Manual_F

Apple-Color_1.0_User_Manual_F

Apple-guide_de_configuration_airport_express_4.2

Apple-TimeCapsule_SetupGuide

Apple-Instruments_et_effets_Logic_Express_8

Apple-Manuel_de_l_utilisateur_de_WaveBurner

Apple-Macmini_Guide_de_l'utilisateur

Apple-PowerMacG5_UserGuide

Disque dur, ATA parallèle Instructions de remplacement

Apple-final_cut_pro_x_logic_effects_ref_f

Apple-Leopard_Installationshandbok

Manuale Utente PowerBookG4

Apple-thunderbolt_display_getting_started_1e

Apple-Compressor-4-Benutzerhandbuch

Apple-macbook_air_11inch_mid2011_ug

Apple-macbook_air-mid-2012-important_product_info_j

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-Manuel_de_l_utilisateur_d_Utilitaire_de_reponse_d_impulsion

Apple-Aperture_2_Raccourcis_clavier

AppleTV_Setup-Guide

Apple-livetype_2_user_manual_f

Apple-imacG5_17inch_harddrive

Apple-macbook_air_guide_de_l_utilisateur

Apple-MacBook_Early_2008_Guide_de_l_utilisateur

Apple-Keynote-2-Guide-de-l-utilisateur

Apple-PowerBook-User-s-Guide-for-PowerBook-computers

Apple-Macintosh-Performa-User-s-Guide-5200CD-and-5300CD

Apple-Macintosh-Performa-User-s-Guide

Apple-Workgroup-Server-Guide

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPad-User-Guide-For-iOS-5-1-Software

Apple-Boot-Camp-Guide-d-installation-et-de-configuration

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Guide de l’utilisateur ipad Pour le logiciel iOS 5.1

PowerBook G4 Premiers Contacts APPLE

Guide de l'Utilisateur iphone pour le logiciel ios 5.1 APPLE

Guide de l’utilisateur ipad Pour le logiciel iOS 4,3

Guide de l’utilisateur iPod nano 5ème génération

Guide de l'utilisateur iPod Touch 2.2 APPLE

Guide de l’utilisateur QuickTime 7  Mac OS X 10.3.9 et ultérieur Windows XP et Windows 2000

Guide de l'utilisateur MacBook 13 pouces Mi 2010

Guide de l’utilisateur iPhone (Pour les logiciels iOS 4.2 et 4.3)

Guide-de-l-utilisateur-iPod-touch-pour-le-logiciel-ios-4-3-APPLE

Guide-de-l-utilisateur-iPad-2-pour-le-logiciel-ios-4-3-APPLE

Guide de déploiement en entreprise iPhone OS

Guide-de-l-administrateur-Apple-Remote-Desktop-3-1

Guide-de-l-utilisateur-Apple-Xserve-Diagnostics-Version-3X103

Guide-de-configuration-AirPort-Extreme-802.11n-5e-Generation

Guide-de-configuration-AirPort-Extreme-802-11n-5e-Generation

Guide-de-l-utilisateur-Capteur-Nike-iPod

Guide-de-l-utilisateur-iMac-21-5-pouces-et-27-pouces-mi-2011-APPLE

Guide-de-l-utilisateur-Apple-Qadministrator-4

Guide-d-installation-Apple-TV-3-eme-generation

User-Guide-iPad-For-ios-5-1-Software

iPod nano User Guide2 2 Contents Chapter 1 4 iPod nano Basics 4 iPod nano at a Glance 5 Using iPod nano Controls 9 Using iPod nano Menus 12 About the iPod nano Internal Speaker 13 Connecting and Disconnecting iPod nano 16 About the iPod nano Battery Chapter 2 19 Setting Up iPod nano 20 Setting Up Your iTunes Library 20 Importing Music to iTunes 21 Adding More Details to Your iTunes Library 21 Organizing Your Music 22 Importing Video to iTunes 24 Adding Music, Videos, and Other Content to iPod nano 24 Connecting iPod nano to a Computer for the First Time 25 Syncing Music Automatically 27 Syncing Videos Automatically 28 Adding Podcasts to iPod nano 29 Adding iTunes U Content to iPod nano 29 Adding Audiobooks to iPod nano 30 Adding Other Content to iPod nano 30 Managing iPod nano Manually 32 Setting Up VoiceOver Chapter 3 33 Listening to Music 33 Playing Music and Other Audio 39 Using Genius on iPod nano 47 Playing Podcasts 48 Playing iTunes U Content 48 Listening to Audiobooks Chapter 4 49 Watching Videos 49 Watching Videos on iPod nanoContents 3 50 Watching Videos on a TV Connected to iPod nano Chapter 5 52 Using the Video Camera 53 Recording Video 54 Playing Recorded Videos 55 Deleting Recorded Videos 55 Importing Recorded Videos to Your Computer Chapter 6 58 Listening to FM Radio 60 Tuning the FM radio 61 Pausing Live Radio 64 Tagging Songs to Sync to iTunes 65 Using the Radio Menu Chapter 7 67 Photo Features 69 Viewing Photos 71 Adding Photos from iPod nano to a Computer Chapter 8 72 More Settings, Extra Features, and Accessories 72 Using iPod nano as a Pedometer 74 Recording Voice Memos 77 Using Extra Settings 81 Syncing Contacts, Calendars, and To-Do Lists 83 Mono Audio 83 Using Spoken Menus for Accessibility 84 Using iPod nano as an External Disk 84 Storing and Reading Notes 85 Learning About iPod nano Accessories Chapter 9 86 Tips and Troubleshooting 86 General Suggestions 92 Updating and Restoring iPod Software Chapter 10 93 Safety and Cleaning 93 Important Safety Information 96 Important Handling Information Chapter 11 97 Learning More, Service, and Support Index 1001 4 1 iPod nano Basics Read this chapter to learn about the features of iPod nano, how to use its controls, and more. iPod nano at a Glance Get to know the controls on iPod nano: Headphones port Menu Previous/Rewind Play/Pause Hold switch 30-pin connector Click Wheel Next/Fast-forward Center button Lens Microphone Chapter 1 iPod nano Basics 5 What’s New in iPod nano  Larger, 2.2-inch display  Polished aluminum finish  A built-in video camera that lets you record video with special effects  An FM radio that lets you pause live radio and tag songs for purchase from the iTunes Store (radio tagging may not be available in some countries)  Internal speaker and microphone  A pedometer that records your workout history Using iPod nano Controls The controls on iPod nano are easy to find and use. Press any button to turn on iPod nano. The first time you turn on iPod nano, the language menu appears. Use the Click Wheel to scroll to your language, and then press the Center button to choose it. The main menu appears in your language. Use the Click Wheel and Center button to navigate through onscreen menus, play songs, change settings, and get information. Move your thumb lightly around the Click Wheel to select a menu item. To choose the item, press the Center button. To go back to the previous menu, press Menu.6 Chapter 1 iPod nano Basics Here’s what else you can do with iPod nano controls. To Do this Turn on iPod nano Press any button. Turn off iPod nano Press and hold Play/Pause (’). Turn on the backlight Press any button or use the Click Wheel. Disable iPod nano controls (so nothing happens if you press them accidentally) Slide the Hold switch to HOLD (an orange bar appears). Reset iPod nano (if it isn’t responding) Slide the Hold switch to HOLD and back again. Press Menu and the Center button at the same time for about 6 seconds, until the Apple logo appears. Choose a menu item Use the Click Wheel to scroll to the item and press the Center button to choose. Go back to the previous menu Press Menu. Go directly to the main menu Press and hold Menu. Access additional options Press and hold the Center button until a menu appears. Browse for a song From the main menu, choose Music. Browse for a video From the main menu, choose Videos. Play a song or video Select the song or video and press the Center button or Play/Pause (’). iPod nano must be ejected from your computer to play songs and videos. Pause a song or video Press Play/Pause (’) or unplug your headphones. Change the volume From the Now Playing screen, use the Click Wheel. Play all the songs in a playlist or album Select the playlist or album and press Play/Pause (’). Play all songs in random order From the main menu, choose Shuffle Songs. Skip to a random song Shake iPod nano. Enable or disable Shake for shuffling songs Choose Settings > Playback, choose Shake, and then select Shuffle or Off. Skip to any point in a song or video From the Now Playing screen, press the Center button to show the scrubber bar (the playhead on the bar shows the current location), and then scroll to any point in the song or video. Skip to the next song or chapter in an audiobook or podcast Press Next/Fast-forward (‘). Start a song or video over Press Previous/Rewind (]). Fast-forward or rewind a song, video, or paused radio Press and hold Next/Fast-forward (‘) or Previous/Rewind (]). Add a song to the On-The-Go playlist Play or select a song, and then press and hold the Center button until a menu appears. Select “Add to On-The-Go,” and then press the Center button.Chapter 1 iPod nano Basics 7 Play the previous song or chapter in an audiobook or podcast Press Previous/Rewind (]) twice. Create a Genius playlist Play or select a song, and then press and hold the Center button until a menu appears. Select Start Genius, and then press the Center button (Start Genius appears in the Now Playing screen only if there’s Genius data for the selected song). Save a Genius playlist Create a Genius playlist, select Save Playlist then press the Center button. Play a saved Genius playlist From the Playlist menu, select a Genius playlist, and then press Play/Pause (’). Play a Genius Mix From the Music menu, choose Genius Mixes. Select a mix and then press Play/Pause (’). Record video Choose Video Camera from the main menu. Press the Center button to start or stop recording. Record video with special effects Before recording video, press and hold the Center button to display effects, then use the Click Wheel to browse and press the Center button to select. Press the Center button again to start recording. Play back recorded video Press the Center button to stop recording, then press Menu to enter the Camera Roll screen. Choose a video and press the Center button to play. Watch recorded video From the Videos menu, choose Camera Videos, then select a video and press Play/Pause (’). Listen to FM radio Choose Radio from the main menu. Tune to an FM station Use the Click Wheel to browse the radio dial. Seek FM stations When the radio dial is visible, press Next/Fast-forward (‘) or Previous/Rewind (]) to skip to the next or previous station. Not available if you save any stations as favorites. Scan FM stations When the radio dial is visible, press and hold Next/Fast-forward (‘). Press the Center button to stop scanning. Save an FM station as a favorite Press and hold the Center button until a menu appears, and then choose Add to Favorites. Pause and resume live radio From any screen, press Play/Pause (’) while listening to the radio. Press Play/Pause (’) again to resume playing. Changing the radio station clears paused radio. Switch between the radio dial and the Live Pause screen Press the Center button. Tag a song on the radio Press and hold the Center button to tag songs marked with a tag symbol. Sync with iTunes to preview and purchase tagged songs. Use the pedometer From the Extras menu, choose Fitness, and then choose Pedometer. Press the Center button to start or stop a session. To Do this8 Chapter 1 iPod nano Basics Disabling iPod nano Controls If you don’t want to turn iPod nano on or activate controls accidentally, you can disable them with the Hold switch. The Hold switch disables all Click Wheel controls, and also disables functions that are activated by movement, such as shaking to shuffle and rotating to enter or exit Cover Flow. To disable iPod nano controls: m Slide the Hold switch to HOLD (an orange bar appears). If you disable the controls while using iPod nano, the song, playlist, podcast, or video that’s playing continues to play, and if the pedometer is turned on it continues counting steps. To stop or pause, slide the Hold switch to enable the controls again. Record a voice memo From the Extras menu, choose Voice Memos. Press Play/Pause (’) to start or stop recording. Press the Center button to add a chapter markers. Find the iPod nano serial number From the main menu choose Settings > About and press the Center button until you see the serial number, or look on the back of iPod nano. To Do thisChapter 1 iPod nano Basics 9 Using iPod nano Menus When you turn on iPod nano, you see the main menu. Choose menu items to perform functions or go to other menus. Icons along the top of the screen show iPod nano status. Display item Function Menu title Displays the title of the current menu. The menu title doesn’t appear when the Lock icon appears. Pedometer icon Appears when the pedometer is on. Play icon The Play (“) icon appears when a song, video, or other item is playing. The Pause (1) icon appears when the item is paused. Battery icon The Battery icon shows the approximate remaining battery charge. Lock icon The Lock icon appears when the Hold switch is set to HOLD. This indicates that the iPod nano controls are disabled. When the Lock icon appears, it replaces the menu title. Menu items Use the Click Wheel to scroll through menu items. Press the Center button to choose an item. An arrow next to a menu item indicates that it leads to another menu or screen. Preview panel Displays album art, photos, and other information relating to the menu item selected. Menu title Pedometer icon Battery icon Menu items Preview panel Play icon Lock icon10 Chapter 1 iPod nano Basics Adding or Removing Items on the Main Menu You might want to add often-used items to the iPod nano main menu. For example, you can add a Songs item to the main menu, so you don’t have to choose Music before you choose Songs. To add or remove items on the main menu: 1 Choose Settings > General > Main Menu. 2 Select each item you want to appear in the main menu. A checkmark indicates which items have been added. Turning Off the Preview Panel The preview panel at the bottom of the main menu displays album art, photo thumbnails, available storage, and other information. You can turn it off to allow more space for menu items. To turn the preview panel on or off: m Choose Settings > General > Main Menu > Preview Panel, and then press the Center button to select On or Off. The preview panel displays art for a category only if iPod nano contains at least five items with art in the category. Setting the Font Size in Menus iPod nano can display text in two different sizes, standard and large. To set the font size: m Choose Settings > General > Font Size, and then press the Center button to select Standard or Large. Setting the Language iPod nano can use different languages. To set the language: m Choose Settings > Language, and then choose a language.Chapter 1 iPod nano Basics 11 Setting the Backlight Timer You can set the backlight to illuminate the screen for a certain amount of time when you press a button or use the Click Wheel. The default is 10 seconds. To set the backlight timer: m Choose Settings > General > Backlight, and then choose the time you want. Choose “Always On” to prevent the backlight from turning off (choosing this option decreases battery performance). Setting the Screen Brightness You can adjust the brightness of the iPod nano screen. To set the screen brightness: m Choose Settings > General > Brightness, and then use the Click Wheel to adjust the brightness. You can also set the brightness during a slideshow or video. Press the Center button until the brightness slider appears, and then use the Click Wheel to adjust the brightness. Turning Off the Click Wheel Sound When you scroll through menu items, you can hear a clicking sound through the earphones or headphones and through the iPod nano internal speaker. If you like, you can turn off the Click Wheel sound. To turn off the Click Wheel sound: m Choose Settings > General and set Clicker to Off. To turn the Click Wheel sound on again, set Clicker to On. Scrolling Quickly Through Long Lists You can scroll quickly through a long list by moving your thumb quickly on the Click Wheel. Note: Not all languages are supported. To scroll quickly: 1 Move your thumb quickly on the Click Wheel, to display a letter of the alphabet on the screen. 2 Use the Click Wheel to navigate through the alphabet until you find the first letter of the item you’re looking for. Items beginning with a symbol or number appear after the letter Z. 3 Lift your thumb momentarily to return to normal scrolling. 4 Use the Click Wheel to navigate to the item you want.12 Chapter 1 iPod nano Basics Getting Information About iPod nano You can get details about your iPod nano, such as the amount of space available, the number of songs, videos, photos, and other items, and the serial number, model, and software version. To get information about iPod nano: m Choose Settings > About, and press the Center button to cycle through the screens of information. Resetting All Settings You can reset all the items on the Settings menu to their default setting. To reset all settings: m Choose Settings > Reset Settings, and then choose Reset. About the iPod nano Internal Speaker With the iPod nano internal speaker, you can listen to any audio on iPod nano without earphones or headphones — except for the built-in FM radio, which uses the earphone or headphone cord as an antenna. Connecting earphones or headphones to iPod nano disables the internal speaker. Any audio that’s playing continues to play, but only through the earphones or headphones. If you disconnect the earphones or headphones while audio is playing, the audio pauses. To resume listening through the internal speaker, press Play/Pause (’). If you disconnect the earphones or headphones while the radio is playing or paused, the radio stops and any paused radio is cleared. If you choose Video Camera or Voice Memos while audio is playing, the audio turns off.Chapter 1 iPod nano Basics 13 Connecting and Disconnecting iPod nano You connect iPod nano to your computer to add music, videos, photos, and files to iPod nano, to import recorded videos and voice memos to your computer, and to charge the battery. Disconnect iPod nano when you’re done. Important: The battery doesn’t charge when your computer is in sleep. Connecting iPod nano To connect iPod nano to your computer: m Plug the included Dock Connector to USB Cable into a high-powered USB 2.0 port on your computer, and then connect the other end to iPod nano. If you have an iPod dock, you can connect the cable to a USB 2.0 port on your computer, connect the other end to the dock, and then put iPod nano in the dock. Note: The USB port on most keyboards doesn’t provide enough power to charge iPod nano. Connect iPod nano to a USB 2.0 port on your computer. By default, iTunes syncs songs on iPod nano automatically when you connect it to your computer. When iTunes is finished, you can disconnect iPod nano. You can sync songs while your battery is charging. If you connect iPod nano to a different computer and it’s set to sync music automatically, iTunes prompts you before syncing any music. If you click Yes, the songs and other audio files already on iPod nano will be erased and replaced with songs and other audio files on the computer iPod nano is connected to. For information about adding music to iPod nano and using iPod nano with more than one computer, see Chapter 2, “Setting Up iPod nano,” on page 19. Disconnecting iPod nano It’s important not to disconnect iPod nano while it’s syncing. You can see if it’s OK to disconnect iPod nano by looking at the iPod nano screen. Don’t disconnect iPod nano if you see the “Connected” or “Synchronizing” message, or you could damage files on iPod nano.14 Chapter 1 iPod nano Basics If you see one of these messages, you must eject iPod nano before disconnecting it: If you see the main menu or a large battery icon, you can disconnect iPod nano. If you set iPod nano to manage songs manually (see “Managing iPod nano Manually” on page 30) or enable iPod nano for disk use (see “Using iPod nano as an External Disk” on page 84), you must always eject iPod nano before disconnecting it. If you accidentally disconnect iPod nano without ejecting it, reconnect iPod nano to your computer and sync again.Chapter 1 iPod nano Basics 15 To eject iPod nano: m In iTunes, click the Eject (C) button next to iPod nano in the device list on the left side of the iTunes window. You can safely disconnect iPod nano while either of these messages is displayed: If you’re using a Mac, you can also eject iPod nano by dragging the iPod nano icon on the desktop to the Trash. If you’re using a Windows PC, you can also eject iPod nano in My Computer or by clicking the Safely Remove Hardware icon in the Windows system tray and selecting iPod nano. To disconnect iPod nano: 1 Unplug your earphones or headphones, if they’re attached. 2 Disconnect the cable from iPod nano. If iPod nano is in the dock, simply remove it. 16 Chapter 1 iPod nano Basics About the iPod nano Battery iPod nano has an internal, non–user-replaceable battery. For best results, the first time you use iPod nano, let it charge for about three hours or until the battery icon in the status area of the display shows that the battery is fully charged. If iPod nano isn’t used for a while, the battery might need to be charged. Note: iPod nano continues to use battery power after it’s been turned off. The iPod nano battery is 80-percent charged in about one and a half hours, and fully charged in about three hours. If you charge iPod nano while adding files, playing music, watching videos, or viewing a slideshow, it might take longer. Charging the iPod nano Battery You can charge the iPod nano battery in two ways:  Connect iPod nano to your computer.  Use the Apple USB Power Adapter, available separately. To charge the battery using your computer: m Connect iPod nano to a USB 2.0 port on your computer. The computer must be turned on and not in sleep. If the battery icon on the iPod nano screen shows the Charging screen, the battery is charging. If it shows the Charged screen, the battery is fully charged. If you don’t see the Charging screen, iPod nano might not be connected to a high-power USB port. Try another USB port on your computer. Chapter 1 iPod nano Basics 17 Important: If a “Charging, Please Wait” or “Connect to Power” message appears on the iPod nano screen, the battery needs to be charged before iPod nano can communicate with your computer. See “If iPod nano displays a “Connect to Power” message” on page 88. If you want to charge iPod nano when you’re away from your computer, you can purchase the Apple USB Power Adapter. To charge the battery using the Apple USB Power Adapter: 1 Connect the AC plug adapter to the power adapter (they might already be connected). 2 Connect the Dock Connector to USB Cable to the power adapter, and plug the other end of the cable into iPod nano. 3 Plug the power adapter into a working power outlet. Understanding Battery States When iPod nano isn’t connected to a power source, a battery icon in the top-right corner of the iPod nano screen shows approximately how much charge is left. Apple USB Power Adapter (your adapter may look different) iPod USB cable Battery less than 20% charged Battery about halfway charged Battery fully charged18 Chapter 1 iPod nano Basics When iPod nano is connected to a power source, the battery icon changes to show that the battery is charging or fully charged. You can disconnect and use iPod nano before it’s fully charged. Note: Rechargeable batteries have a limited number of charge cycles and might eventually need to be replaced. Battery life and number of charge cycles vary by use and settings. For information, go to www.apple.com/batteries. Improving Battery Performance with Energy Saver Energy Saver can extend the time between battery charges by turning off the iPod nano screen when you aren’t using the controls. Energy Saver is turned on by default. To turn Energy Saver on or off: m Choose Settings > Playback > Energy Saver, and then select On or Off. If you turn Energy Saver off, iPod nano displays the following information after the backlight turns off: Turning off Energy Saver increases the rate of battery consumption. Battery charging (lightning bolt) Battery fully charged (plug)2 19 2 Setting Up iPod nano You use iTunes on your computer to set up iPod nano to play your music, video, and other media content. No setup is needed to record video or listen to FM radio. Using iTunes iTunes is the free software application you use to set up, organize, and manage your content on iPod nano. iTunes can sync music, audiobooks, podcasts, and more with iPod nano. If you don’t already have iTunes installed on your computer, you can download it at www.apple.com/downloads. iPod nano requires iTunes 9 or later. iTunes is available for Mac and Windows. You can use iTunes to import music from CDs and the Internet, buy songs and other audio and video from the iTunes Store, create personal compilations of your favorite songs (called playlists), sync them to iPod nano, and adjust iPod nano settings. iTunes also has a feature called Genius that creates playlists and mixes of songs from your iTunes library that go great together. You can sync Genius playlists that you create in iTunes to iPod nano, and you can create Genius playlists and listen to Genius Mixes on iPod nano. To use Genius, you need an iTunes Store account. iTunes has many other features. You can burn your own CDs that play in standard CD players (if your computer has a recordable CD drive); listen to streaming Internet radio; watch videos and TV shows; rate songs according to preference; and much more. 20 Chapter 2 Setting Up iPod nano For information about using these iTunes features, open iTunes and choose Help > iTunes Help. If you already have iTunes 9 or later installed on your computer and you’ve set up your iTunes library, you can skip ahead to “Adding Music, Videos, and Other Content to iPod nano” on page 24. If you want to get started recording video or listening to FM radio, you can set up iPod nano at a later time. To learn how to record video, see “Using the Video Camera” on page 52. For information about the FM radio, see “Listening to FM Radio” on page 58. Setting Up Your iTunes Library To listen to music and watch videos on iPod nano, you first need to get that music and video into iTunes on your computer. Importing Music to iTunes There are three ways of getting music and other audio into iTunes. Purchase Songs and Download Podcasts Using the iTunes Store If you have an Internet connection, you can easily purchase and download songs, albums, and audiobooks online using the iTunes Store. You can also subscribe to and download podcasts, and you can download free educational content from iTunes U. To purchase music online using the iTunes Store, you set up a free iTunes account in iTunes, find the songs you want, and then buy them. If you already have an iTunes account (also called an Apple ID), you can use that account to sign in to the iTunes Store and buy songs. You don’t need an iTunes Store account to download or subscribe to podcasts. To enter the iTunes Store, open iTunes and click iTunes Store below Store on the left side of the iTunes window. Add Songs Already on Your Computer to Your iTunes Library If you have songs on your computer encoded in file formats that iTunes supports, you can easily add the songs to iTunes. To learn how to get songs from your computer into iTunes, open iTunes and choose Help > iTunes Help. Using iTunes for Windows, you can convert nonprotected WMA files to AAC or MP3 format. This can be useful if you have a library of music encoded in WMA format. For more information, open iTunes and choose Help > iTunes Help.Chapter 2 Setting Up iPod nano 21 Import Music From Your Audio CDs Into iTunes iTunes can import music and other audio from your audio CDs. If you have an Internet connection, iTunes gets the names of the songs on the CD from the Internet (if available) and lists them in the iTunes window. When you add the songs to iPod nano, the song information is included. To learn how to import music from your CDs into iTunes, open iTunes and choose Help > iTunes Help. Adding More Details to Your iTunes Library Once you import your music into iTunes, you can add more details to your iTunes library. Most of these additional details appear on iPod nano when you add songs. Enter Song Names and Other Information If you don’t have an Internet connection, if song information isn’t available for music you import, or if you want to include additional information (such as composer names), you can enter the information manually. To learn how to enter song information, open iTunes and choose Help > iTunes Help. Add Lyrics You can enter song lyrics in plain text format into iTunes so that you can view the song lyrics on iPod nano while the song is playing. To learn how to enter lyrics, open iTunes and choose Help > iTunes Help. For more information, see “Viewing Lyrics on iPod nano” on page 37. Add Album Artwork Music you purchase from the iTunes Store includes album artwork, which iPod nano can display. You can add album artwork automatically for music you’ve imported from CDs, if the CDs are available from the iTunes Store. You can add album artwork manually if you have the album art on your computer. To learn more about adding album artwork, open iTunes and choose Help > iTunes Help. For more information, see “Viewing Album Artwork on iPod nano” on page 37. Organizing Your Music In iTunes, you can organize songs and other items into lists, called playlists, in any way you want. For example, you can create playlists with songs to listen to while exercising, or playlists with songs for a particular mood. You can create Smart Playlists that update automatically based on rules you define. When you add songs to iTunes that match the rules, they automatically get added to the Smart Playlist. 22 Chapter 2 Setting Up iPod nano You can turn on Genius in iTunes and create playlists of songs that go great together. Genius can also organize your music library automatically by sorting and grouping it into collections called Genius Mixes. You can create as many playlists as you like, using any of the songs in your iTunes library. Adding a song to a playlist or later removing it doesn’t remove it from your library. To learn how to set up playlists in iTunes, open iTunes and choose Help > iTunes Help. Note: To create playlists on iPod nano when iPod nano isn’t connected to your computer, see “Creating On-The-Go Playlists on iPod nano” on page 41. Turning On Genius in iTunes Genius finds songs in your library that go great together in order to create Genius playlists and Genius Mixes. A Genius playlist starts with a song that you select. To create the Genius playlist, iTunes then compiles a collection of songs that go great with the one you selected. Genius Mixes are pre-selected compilations of songs that go great together, and are created for you by iTunes using songs from your library. Genius Mixes are designed to provide a different listening experience each time you play one. iTunes creates up to 12 Genius Mixes, depending on the variety of music in your iTunes library. To use Genius on iPod nano to create Genius playlists and Genius Mixes, you first need to turn on Genius in iTunes. To learn about turning on and using Genius in iTunes, open iTunes and choose Help > iTunes Help. Genius playlists and Genius Mixes created in iTunes can be synced to iPod nano like any iTunes playlist. Genius Mixes can’t be added to iPod nano manually. See “Syncing Genius Playlists and Genius Mixes to iPod nano” on page 26. Genius is a free service, but an iTunes Store account is required to use it (if you don’t have an account, you can set one up when you turn on Genius). Importing Video to iTunes There are several ways to import video into iTunes, described below. Purchase or Rent Videos and Download Video Podcasts from the iTunes Store To purchase videos—movies, TV shows, and music videos—or rent movies online from the iTunes Store (part of iTunes and available in some countries only), you sign in to your iTunes Store account, find the videos you want, and then buy or rent them.Chapter 2 Setting Up iPod nano 23 A rented movie expires 30 days after you rent it or 24 hours after you begin playing it (48 hours outside the U.S.), whichever comes first. Expired rentals are deleted automatically. These terms apply to U.S. rentals. Rental terms vary among countries. To enter the iTunes Store, open iTunes and click iTunes Store below Store on the left side of the iTunes window. You can view movie trailers or TV show previews by clicking the Preview button next to them. Purchased videos appear when you select Movies or TV Shows (under Library) or Purchased (under Store) in the source list. Rented videos appear when you select Rented Movies (under Library). Some items have other options, such as TV shows that let you buy a Season Pass for all episodes. Video podcasts appear along with other podcasts in the iTunes Store. You can subscribe to them and download them just as you would other podcasts. You don’t need an iTunes Store account to download podcasts. See “Purchase Songs and Download Podcasts Using the iTunes Store” on page 20. Create Versions of Your Own Videos to Work with iPod nano You can view other video files on iPod nano, such as videos you create in iMovie on a Mac or videos you download from the Internet. Import the video into iTunes, convert it for use with iPod nano, if necessary, and then add it to iPod nano. iTunes supports many of the video formats that QuickTime supports. For more information, see “If you can’t add a song or other item to iPod nano” on page 89. Some videos may be ready for use with iPod nano after you import them to iTunes. If you try to add a video to iPod nano (see “Syncing Videos Automatically” on page 27), and a message says the video can’t play on iPod nano, then you must convert the video for use with iPod nano. Depending on the length and content of a video, converting it for use with iPod nano can take several minutes to several hours. When you create a version of a video for use with iPod nano, the original video also remains in your iTunes library. For more about converting video for iPod nano, open iTunes and choose Help > iTunes Help, or go to www.info.apple.com/kbnum/n302758.24 Chapter 2 Setting Up iPod nano Adding Music, Videos, and Other Content to iPod nano After your music and video are imported and organized in iTunes, you can easily add them to iPod nano. To manage how music, videos, photos, and other content are added to iPod nano from your computer, you connect iPod nano to your computer, and then use iTunes to choose iPod nano settings. Connecting iPod nano to a Computer for the First Time The first time you connect iPod nano to your computer (after installing iTunes), iTunes opens automatically and the iPod nano Setup Assistant appears: To use the iPod nano Setup Assistant: 1 Enter a name for iPod nano. This is the name that will appear in the device list on the left side of the iTunes window. 2 Select your settings. Automatic syncing and VoiceOver are selected by default. If you don’t want to enable VoiceOver at this time, deselect Enable VoiceOver. If you change your mind, you can enable VoiceOver any time you connect iPod nano to your computer. See “Setting Up VoiceOver” on page 32. 3 Click Done. If you selected to enable VoiceOver during setup, follow any onscreen instructions for downloading and installing the VoiceOver Kit. For more information, see “Using VoiceOver in iPod nano” on page 44. To learn how to set up VoiceOver in iPod nano, see “Setting Up VoiceOver” on page 32.Chapter 2 Setting Up iPod nano 25 You can change the device name and settings any time you connect iPod nano to your computer. After you click Done, the Summary pane appears. If you selected automatic syncing, iPod nano begins syncing. Adding Content Automatically or Manually There are two ways to add content to iPod nano:  Automatic syncing: When you connect iPod nano to your computer, iPod nano is automatically updated to match the items in your iTunes library. You can sync all your songs, playlists, videos, and podcasts, or, if your entire iTunes library doesn’t fit on iPod nano, you can sync only selected items. You can sync iPod nano automatically with only one computer at a time.  Manually managing iPod nano: When you connect iPod nano, you can drag items individually to iPod nano and delete them individually from iPod nano. You can add songs from more than one computer without erasing songs from iPod nano. When you manage music yourself, you must always eject iPod nano from iTunes before you disconnect it. Syncing Music Automatically By default, iPod nano is set to sync all songs and playlists when you connect it to your computer. This is the simplest way to add music to iPod nano. You just connect iPod nano to your computer, let it add songs, audiobooks, videos, and other items automatically, and then disconnect it and go. If you added any songs to iTunes since the last time you connected iPod nano, they are synced with iPod nano. If you deleted songs from iTunes, they are removed from iPod nano. To sync music with iPod nano: m Connect iPod nano to your computer. If iPod nano is set to sync automatically, the update begins. Important: If you connect iPod nano to a computer that it’s not synced with, a message asks if you want to sync songs automatically. If you accept, all songs, audiobooks, and videos are erased from iPod nano and replaced with songs and other items from that computer. While music is being synced from your computer to iPod nano, the iTunes status window shows progress, and you see a sync icon next to the iPod nano icon in the device list.26 Chapter 2 Setting Up iPod nano When the update is done, a message in iTunes says “iPod sync is complete.” A bar at the bottom of the iTunes window displays how much disk space is used by different types of content. If there isn’t enough space on iPod nano for all your music, you can set iTunes to sync only selected songs and playlists. Only the songs and playlists you specify are synced with iPod nano. Syncing Music From Selected Playlists, Artists, and Genres to iPod nano You can set iTunes to sync selected playlists, artists, and genres to iPod nano if the music in your iTunes library doesn’t all fit on iPod nano. Only the music from the playlists, artists, and genres you select is synced to iPod nano. To set iTunes to sync music from selected playlists, artists, and genres to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Music tab. 2 Select “Sync music,” and then choose “Selected playlists, artists, and genres.” 3 Select the playlists you want. 4 To include music videos, select “Include music videos.” 5 To set iTunes to automatically fill any remaining space on iPod nano, select “Automatically fill free space with songs.” 6 Click Apply. If “Sync only checked songs and videos” is selected in the Summary pane, iTunes syncs only items that are checked. Syncing Genius Playlists and Genius Mixes to iPod nano You can set iTunes to sync Genius playlists and Genius Mixes to iPod nano. Genius Mixes can only be synced automatically. You can’t add Genius Mixes to iPod nano if you manage your content manually. Genius playlists can be added manually to iPod nano. If you select any Genius Mixes to sync, iTunes may select and sync additional songs from your library that you didn’t select.Chapter 2 Setting Up iPod nano 27 To set iTunes to sync Genius playlists and selected Genius Mixes to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Music tab. 2 Select “Sync music,” and then choose “Selected playlists, artists, and genres.” 3 Under Playlists, select the Genius playlists and Genius Mixes you want. 4 Click Apply. If you choose to sync your entire music library, iTunes syncs all your Genius playlists and Genius Mixes. If “Sync only checked songs and videos” is selected in the Summary pane, iTunes syncs only items that are checked. Adding Videos to iPod nano You add movies and TV shows to iPod nano much the same way you add songs. You can set iTunes to sync all movies and TV shows to iPod nano automatically when you connect iPod nano, or you can set iTunes to sync only selected playlists. Alternatively, you can manage movies and TV shows manually. Using this option, you can add videos from more than one computer without erasing videos already on iPod nano. Note: Music videos are managed with songs, under the Music tab in iTunes. See “Adding Music, Videos, and Other Content to iPod nano” on page 24. Important: You can view a rented movie on only one device at a time. For example, if you rent a movie from the iTunes Store and add it to iPod nano, you can only view it on iPod nano. If you transfer the movie back to iTunes, you can only view it there and not on iPod nano. All standard time limits apply to rented movies added to iPod nano. Syncing Videos Automatically By default, iPod nano is set to sync all movies and TV shows when you connect it to your computer. This is the simplest way to add videos to iPod nano. You just connect iPod nano to your computer, let it add videos and other items automatically, and then disconnect it and go. If you added any videos to iTunes since the last time you connected iPod nano, they’re added to iPod nano. If you deleted videos from iTunes, they’re removed from iPod nano. If there isn’t enough space on iPod nano for all your videos, you can set iTunes to sync only the videos you specify. You can sync selected videos or selected playlists that contain videos. The settings for syncing movies and TV shows are unrelated. Movie settings don’t affect TV show settings, and vice versa.28 Chapter 2 Setting Up iPod nano To set iTunes to sync movies to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Movies tab. 2 Select “Sync movies.” 3 Select the movies or playlists you want. All, recent, or unwatched movies: Select “Automatically include … movies” and choose the option you want from the pop-up menu. Selected movies or playlists: Select the movies or playlists you want. 4 Click Apply. If “Sync only checked songs and videos” is selected in the Summary pane, iTunes syncs only movies that are checked. To set iTunes to sync TV shows to iPod nano: 1 In iTunes, select iPod nano in the device list and click the TV Shows tab. 2 Select “Sync TV Shows.” 3 Select the shows, episodes, and playlists you want. All, most recent, or unwatched episodes: Select “Automatically include … episodes of … ” and choose the options you want from the pop-up menus. Episodes on selected playlists: Select the playlists you want. 4 Click Apply. If “Sync only checked songs and videos” is selected in the Summary pane, iTunes syncs only TV show that are checked. Adding Podcasts to iPod nano The settings for adding podcasts to iPod nano are unrelated to the settings for adding songs and videos. Podcast settings don’t affect song or video settings, and vice versa. You can set iTunes to automatically sync all or selected podcasts, or you can add podcasts to iPod nano manually. To set iTunes to update the podcasts on iPod nano automatically: 1 In iTunes, select iPod nano in the device list and click the Podcasts tab. 2 In the Podcasts pane, select “Sync Podcasts.”Chapter 2 Setting Up iPod nano 29 3 Select the podcasts, episodes, and playlists you want, and set your sync options. 4 Click Apply. When you set iTunes to sync iPod nano podcasts automatically, iPod nano is updated each time you connect it to your computer. If you select “Sync only checked songs and videos” in the Summary pane, iTunes syncs only items that are checked in your Podcasts and other libraries. Adding Video Podcasts to iPod nano You add video podcasts to iPod nano the same way you add other podcasts (see “Adding Podcasts to iPod nano” on page 28). If a podcast has video, the video plays when you choose it from the Podcasts menu. Adding iTunes U Content to iPod nano The settings for adding iTunes U content to iPod nano are unrelated to the settings for adding other content. iTunes U settings don’t affect other settings, and vice versa. You can set iTunes to automatically sync all or selected iTunes U content, or you can add iTunes U content to iPod nano manually. To set iTunes to update the iTunes U content on iPod nano automatically: 1 In iTunes, select iPod nano in the device list and click the iTunes U tab. 2 In the iTunes U pane, select “Sync iTunes U.” 3 Select the collections, items, and playlists you want, and set your sync options. 4 Click Apply. When you set iTunes to sync iTunes U content automatically, iPod nano is updated each time you connect it to your computer. If you select “Sync only checked songs and videos” in the Summary pane, iTunes syncs only items that are checked in your iTunes U and other libraries. Adding Audiobooks to iPod nano You can purchase and download audiobooks from the iTunes Store or audible.com, or import audiobooks from CDs, and listen to them on iPod nano. Use iTunes to add audiobooks to iPod nano. If you sync iPod nano automatically, all audiobooks in your iTunes library are included in a playlist named Audiobooks, which you can sync to iPod nano. If you manage your content on iPod nano manually, you can add audiobooks one at a time.30 Chapter 2 Setting Up iPod nano To sync audiobooks to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Music tab. 2 Select Sync Music, and then do one of the following:  Select “Entire music library.”  Select “Selected playlists, artists, and genres,” and then select Audiobooks (below Playlists). 3 Click Apply. The update begins automatically. Adding Other Content to iPod nano You can also use iTunes to sync photos, games, contacts, and more to iPod nano. You can set iTunes to sync your content automatically, or you can manage your content on iPod nano manually. For more information about adding other types of content to iPod nano, see:  “Adding Photos from Your Computer to iPod nano” on page 67  “To sync games automatically to iPod nano:” on page 76  “Syncing Contacts, Calendars, and To-Do Lists” on page 81  “Mono Audio” on page 83 Managing iPod nano Manually If you manage iPod nano manually, you can add and remove individual songs (including music videos) and videos (including movies and TV shows). You can also add music and video from multiple computers to iPod nano without erasing items already on iPod nano. You can’t manually add Genius Mixes to iPod nano, but you can manually add Genius playlists. Setting iPod nano to manually manage music and video turns off the automatic sync options in the Music, Movies, TV Shows, Podcasts, iTunes U, Photos, Contacts, and Games panes. You can’t manually manage some and automatically sync others at the same time. If you set iTunes to manage content manually, you can reset it later to sync automatically.Chapter 2 Setting Up iPod nano 31 To set iTunes to manage content on iPod nano manually: 1 In iTunes, select iPod nano in the device list and click the Summary tab. 2 In the Options section, select “Manually manage music and video.” 3 Click Apply. When you manually manage content on iPod nano, you must always eject iPod nano from iTunes before you disconnect it. When you connect a manually-managed iPod nano to a computer, it appears in the device list on the left side of the iTunes window. To add a song, video, or other item to iPod nano: 1 In iTunes, click Music or another item below Library on the left side of the iTunes window. 2 Drag a song or other item to iPod nano in the device list. To remove a song, video, or other item from iPod nano: 1 In iTunes, select iPod nano in the device list. 2 Select a song or other item on iPod nano, and then press the Delete or Backspace key on your keyboard. If you remove a song or other item from iPod nano, it isn’t deleted from your iTunes library. To create a new playlist on iPod nano: 1 In iTunes, select iPod nano in the device list, and then click the Add (+) button or choose File > New Playlist. 2 Type a name for the playlist. 3 Click an item, such as Music, in the Library list, and then drag songs or other items to the playlist. To add items to or remove items from a playlist on iPod nano: m Drag an item to a playlist on iPod nano to add the item. Select an item in a playlist and press the Delete key on your keyboard to delete the item. To reset iTunes to sync music, video, and podcasts automatically: 1 In iTunes, select iPod nano in the device list and click the Summary tab. 2 Deselect “Manually manage music and videos.” 3 Select the Music, Movies, TV Shows, and Podcasts tabs, and select your sync options. 4 Click Apply. The update begins automatically.32 Chapter 2 Setting Up iPod nano Setting Up VoiceOver VoiceOver announces the title and artist of the song you’re listening to, on demand. If you have the Apple Earphones with Remote and Mic or the In-Ear Headphones with Remote and Mic, you can also use VoiceOver to navigate playlists. Note: VoiceOver isn’t available in all languages. You set VoiceOver options in the Summary pane in iTunes. When you first set up iPod nano, VoiceOver is enabled by default. Follow any onscreen instructions to download and install the VoiceOver Kit. If you don’t want VoiceOver enabled when you set up iPod nano, deselect Enable VoiceOver in the Setup Assistant. If you change your mind, you can enable VoiceOver at a later time. To enable VoiceOver at a later time: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the device list and click the Summary tab. 3 Under Voice Feedback, select Enable VoiceOver. 4 Click Apply. 5 Follow the onscreen instructions to download and install the VoiceOver Kit. 6 Click Apply. When syncing is finished, VoiceOver is enabled. If your computer has a system voice that you want to use instead of the built-in voice that comes with VoiceOver, select “Use system voice instead of built-in voice” under Voice Feedback in the Summary pane. You can disable VoiceOver any time you connect iPod nano to your computer. To disable VoiceOver: 1 In iTunes, select iPod nano in the device list and click the Summary tab. 2 Under Voice Feedback, deselect Enable VoiceOver. 3 Click Apply. When syncing is finished, VoiceOver is disabled.3 33 3 Listening to Music Read this chapter to learn about listening on the go. After you set up iPod nano, you can listen to songs, podcasts, audiobooks, and more. Playing Music and Other Audio When a song is playing, the Now Playing screen appears. The following table describes the elements on the Now Playing screen. Screen item Function Shuffle icon Appears if iPod nano is set to shuffle songs or albums. Repeat icon Appears if iPod nano is set to repeat all songs. The Repeat Once (!) icon appears if iPod nano is set to repeat one song. Play icon Appears when song is playing. The Pause (1) icon appears when song is paused. Battery icon Shows the approximate remaining battery charge. Song information Displays the song title, artist, and album title. Album art Shows the album art, if it’s available. Progress bar Shows the elapsed and remaining times for the song that’s playing. Progress bar Click the Center button to see the scrubber bar, Genius or shuffle slider, song rating and lyrics. Album art Shuffle icon Repeat icon Play icon Battery icon Song information34 Chapter 3 Listening to Music Press the Center button to click through these additional items in the Now Playing screen: Use the Click Wheel and Center button to browse for a song or music video. When you play music videos from the Music menu, you only hear the music. When you play them from the Videos menu, you also see the video. To browse for and play a song: m Choose Music, browse for a song or music video, and then press Play/Pause (’). To change the playback volume: m When you see the progress bar, use the Click Wheel to change the volume. If you don’t see the progress bar, press the Center button until it appears. To listen to a different part of a song: 1 Press the Center button until you see the scrubber bar. 2 Use the Click Wheel to move the playhead along the scrubber bar. Screen item Function Scrubber bar Lets you quickly navigate to a different part of the track. Genius slider Creates a Genius playlist based on the current song. The slider doesn’t appear if Genius information isn’t available for the current song. Shuffle slider Lets you shuffle songs or albums directly from the Now Playing screen. Song rating Lets you rate the song. Lyrics Displays the lyrics of the song that’s playing. Lyrics don’t appear if you didn’t enter them in iTunes.Chapter 3 Listening to Music 35 To create a Genius playlist from the current song: 1 Press the Center button until you see the Genius slider. 2 Use the Click Wheel to move the slider to Start. The Genius slider doesn’t appear if Genius information isn’t available for the current song. To shuffle songs from the Now Playing screen: 1 Press the Center button until you see the shuffle slider. 2 Use the Click Wheel to move the slider to Songs or Albums.  Choose Songs to play all songs on iPod nano at random.  Choose Albums to play all songs in the current album in order. iPod nano then randomly selects another album and plays through it in order.36 Chapter 3 Listening to Music To just listen to a music video: m Choose Music and browse for a music video. When you play the video, you hear it but don’t see it. When you play a playlist that includes video podcasts, you hear the podcasts but don’t see them. To return to the previous menu: m From any screen, press Menu. Rating Songs You can assign a rating to a song (from 1 to 5 stars) to indicate how much you like it. You can use song ratings to help you create Smart Playlists automatically in iTunes. To rate a song: 1 Start playing the song. 2 From the Now Playing screen, press the Center button until the five rating bullets appear. 3 Use the Click Wheel to assign a rating. The ratings you assign to songs on iPod nano are transferred to iTunes when you sync. Note: You can’t assign ratings to video podcasts.Chapter 3 Listening to Music 37 Viewing Lyrics on iPod nano If you enter lyrics for a song in iTunes (see “Add Lyrics” on page 21) and then add the song to iPod nano, you can view the lyrics on iPod nano. Lyrics don’t appear unless you enter them. To view lyrics on iPod nano while a song is playing: m On the Now Playing screen, press the Center button until you see the lyrics. You can scroll through the lyrics as the song plays. Viewing Album Artwork on iPod nano iTunes displays album artwork on iPod nano, if the artwork is available. Artwork appears on iPod nano in Cover Flow, in the album list, and when you play a song from the album. To see album artwork on iPod nano: m Hold iPod nano horizontally to view Cover Flow, or play a song that has album artwork and view it in the Now Playing screen. For more information about album artwork, open iTunes and choose Help > iTunes Help. Browsing Music Using Cover Flow You can browse your music collection using Cover Flow, a visual way to flip through your library. Cover Flow displays your albums alphabetically by artist name. You can activate Cover Flow from the main menu, any music menu, or the Now Playing screen.38 Chapter 3 Listening to Music To use Cover Flow: 1 Rotate iPod nano 90 degrees to the left or right. Cover Flow appears. 2 Use the Click Wheel to move through your album art. 3 Select an album and press the Center button. 4 Use the Click Wheel to select a song, and then press the Center button to play it. You can also browse quickly through your albums in Cover Flow by moving your thumb quickly on the Click Wheel. Note: Not all languages are supported. To browse quickly in Cover Flow: 1 Move your thumb quickly on the Click Wheel, to display a letter of the alphabet on the screen. 2 Use the Click Wheel to navigate through the alphabet until you find the first letter of the artist you’re looking for. Albums by artists beginning with a symbol or number appear after the letter Z. 3 Lift your thumb momentarily to return to normal browsing. 4 Select an album and press the Center button. 5 Use the Click Wheel to select a song, and then press the Center button to play it. To turn Cover Flow on or off: 1 From the main menu, choose Settings > General > Rotate. 2 Press the Center button to select Cover Flow or Off.Chapter 3 Listening to Music 39 Accessing Additional Commands Some additional iPod nano commands can be accessed directly from the Now Playing screen and some menus. To access additional commands: m Press and hold the Center button until a menu appears, select a command, and then press the Center button again. If a menu doesn’t appear, no additional commands are available. Using Genius on iPod nano Even when iPod nano isn’t connected to your computer, Genius can automatically create instant playlists of songs that go great together. You can also play Genius Mixes, which are pre-selected compilations of songs that go great together. To use Genius, you need to set up Genius in the iTunes Store, and then sync iPod nano to iTunes. You can also create Genius playlists in iTunes and add them to iPod nano, and you can sync Genius Mixes to iPod nano. To learn how to set up Genius in iTunes, open iTunes and choose Help > iTunes Help. Genius is a free service, but you need an iTunes Store account to use it.40 Chapter 3 Listening to Music To make a Genius playlist on iPod nano: 1 Select a song, and then press and hold the Center button until a menu appears. You can select a song from a menu or playlist, or you can start from the Now Playing screen. 2 Choose Start Genius. Start Genius doesn’t appear in the menu of additional commands, if any of the following apply:  You haven’t set up Genius in iTunes and then synced iPod nano with iTunes.  Genius doesn’t recognize the song you selected.  Genius recognizes the song, but there aren’t at least ten similar songs in your library. 3 Press the Center button. The new playlist appears. 4 To keep the playlist, choose Save Playlist. The playlist is saved with the song title and artist of the song you used to make the playlist. 5 To change the playlist to a new one based on the same song, choose Refresh. If you refresh a saved playlist, the new playlist replaces the previous one. You can’t recover the previous playlist. You can also start Genius from the Now Playing screen by pressing the Center button until you see the Genius slider, and then using the Click Wheel to move the slider to the right. The Genius slider won’t appear if Genius information isn’t available for the current song. Genius playlists saved on iPod nano are synced back to iTunes when you connect iPod nano to your computer. To play a Genius playlist: m Choose Music > Playlists and choose the playlist. Playing Genius Mixes Genius Mixes are created for you by iTunes and contain songs from your library that go great together. Genius Mixes are designed to provide a different listening experience each time you play one. iTunes creates up to 12 Genius Mixes, depending on the variety of music in your iTunes library. To find out how to sync Genius Mixes to iPod nano, see “Syncing Genius Playlists and Genius Mixes to iPod nano” on page 26.Chapter 3 Listening to Music 41 To play a Genius Mix: 1 Choose Music > Genius Mixes. 2 Use Next/Fast-forward (‘) or Previous/Rewind (]) to browse the Genius Mixes. The dots at the bottom of the screen indicate how many Genius Mixes are synced to iPod nano. 3 To start playing a Genius Mix, press the Center button or Play/Pause (’) when you see its screen. The Speaker ( ) icon appears when the selected Genius Mix is playing. Creating On-The-Go Playlists on iPod nano You can create On-The-Go Playlists on iPod nano when iPod nano isn’t connected to your computer. To create an On-The-Go playlist: 1 Select a song, and then press and hold the Center button until a menu appears. 2 Choose “Add to On-The-Go.” 3 To add more songs, repeat steps 1 and 2.42 Chapter 3 Listening to Music 4 Choose Music > Playlists > On-The-Go to browse and play your list of songs. You can also add a group of songs. For example, to add an album, highlight the album title, press and hold the Center button until a menu appears, and then choose “Add to On-The-Go.” To play songs in the On-The-Go playlist: m Choose Music > Playlists > On-The-Go, and then choose a song. To remove a song from the On-The-Go playlist: 1 Select a song in the playlist and hold down the Center button until a menu appears. 2 Choose “Remove from On-The-Go,” and then press the Center button. To clear the entire On-The-Go playlist: m Choose Music > Playlists > On-The-Go > Clear Playlist, and then click Clear. To save the On-The-Go playlist on iPod nano: m Choose Music > Playlists > On-The-Go > Save Playlist. The first playlist is saved as “New Playlist 1” in the Playlists menu. The On-The-Go playlist is cleared and ready to reuse. You can save as many playlists as you like. After you save a playlist, you can no longer remove songs from it. To copy On-The-Go playlists from iPod nano to your computer: m If iPod nano is set to sync songs automatically (see “Syncing Music Automatically” on page 25) and you create an On-The-Go playlist, the playlist is automatically synced to iTunes when you connect iPod nano. The new On-The-Go playlist appears in the list of playlists in iTunes. You can rename, edit, or delete the new playlist, just as you would any playlist. Browsing Songs by Album or Artist When you’re listening to a song, you can browse more songs by the same artist or all the songs in the current album. To browse songs by album: 1 From the Now Playing screen, press and hold the Center button until a menu appears. 2 Choose Browse Album, and then press the Center button. You see all the songs from the current album that are on iPod nano. You can select a different song or return to the Now Playing screen. To browse songs by artist: 1 From the Now Playing screen, press and hold the Center button until a menu appears. 2 Choose Browse Artist, and then press the Center button. You see all the songs by that artist that are on iPod nano. You can select a different song or return to the Now Playing screen.Chapter 3 Listening to Music 43 Setting iPod nano to Shuffle Songs You can set iPod nano to play songs, albums, or your entire library in random order. To set iPod nano to shuffle and play all your songs: m Choose Shuffle Songs from the iPod nano main menu. iPod nano begins playing songs from your entire music library in random order, skipping audiobooks and podcasts. To set iPod nano to always shuffle songs or albums: 1 Choose Settings from the iPod nano main menu. 2 Set Shuffle to either Songs or Albums. When you set iPod nano to shuffle songs, iPod nano shuffles songs within whatever list (for example, album or playlist) you choose to play. When you set iPod nano to shuffle albums, it plays all the songs on an album in order, and then randomly selects another album and plays through it in order. You can also set iPod nano to shuffle songs directly from the Now Playing screen. To set iPod nano to shuffle songs from the Now Playing screen: 1 From the Now Playing screen, press the Center button until the shuffle slider appears. 2 Use the Click Wheel to set iPod nano to shuffle songs or albums. You can skip ahead to a random song by shaking iPod nano. To shuffle songs while a song is playing or paused: m Shake iPod nano from side to side. A new song starts to play. Shaking to shuffle doesn’t change your shuffle settings.44 Chapter 3 Listening to Music To disable shaking: m Choose Settings > Playback > Shake and select Off. To turn shaking on again, choose Settings > Playback > Shake, and then select Shuffle. Shaking is also disabled when the Hold switch is in the HOLD position, when the iPod nano built-in radio is playing, or when the display is off. If iPod nano is off, you can’t turn it on by shaking it. Setting iPod nano to Repeat Songs You can set iPod nano to repeat a song over and over, or repeat songs within the list you choose to play. To set iPod nano to repeat songs: m Choose Settings from the iPod nano main menu.  To repeat all songs in the list, set Repeat to All.  To repeat one song over and over, set Repeat to One. Using VoiceOver in iPod nano With VoiceOver, iPod nano can announce the title and artist of the song you’re listening to. VoiceOver is available in selected languages. To use VoiceOver, install the VoiceOver Kit and enable the VoiceOver feature in iTunes. For more information, see “Setting Up VoiceOver” on page 32. To hear the current song announcement: m From the Now Playing screen, press the Center button. You hear the current song title and artist name. If you’re listening to an audiobook, you hear the book title and author’s name. If you have the Apple Earphones with Remote and Mic or the In-Ear Headphones with Remote and Mic (available at store.apple.com or your local Apple Store), you can also use VoiceOver to navigate through playlists. For more information, see the documentation for those accessories. Searching Music You can search iPod nano for songs, playlists, album titles, artist names, audio podcasts, and audiobooks. The search feature doesn’t search videos, notes, calendar items, contacts, or lyrics. Note: Not all languages are supported. To search for music: 1 From the Music menu, choose Search. 2 Enter a search string by using the Click Wheel to navigate the alphabet and pressing the Center button to enter each character.Chapter 3 Listening to Music 45 iPod nano starts searching as soon as you enter the first character, displaying the results on the search screen. For example, if you enter “b,” iPod nano displays all music items containing the letter “b.” If you enter “ab,” iPod nano displays all items containing that sequence of letters. To enter a space character, press Next/Fast-forward (‘). To delete the previous character, press Previous/Rewind (]). 3 Press Menu to display the results list, which you can navigate by using the Click Wheel. Items appear in the results list with icons identifying their type: song, video, artist, album, audiobook, or podcast. To return to Search (if Search is highlighted in the menu), press the Center button. Customizing the Music Menu You can add items to or remove them from the Music menu, just as you do with the main menu. For example, you can add a Compilations item to the Music menu, so you can easily choose compilations that are put together from various sources. To add or remove items in the Music menu: 1 Choose Settings > General > Music Menu. 2 Select each item you want to appear in the Music menu. A checkmark indicates which items have been added. To revert to the original Music menu settings, choose Reset Menu. Setting the Maximum Volume Limit You can set a limit for the maximum volume on iPod nano and assign a combination to prevent the setting from being changed. To set the maximum volume limit for iPod nano: 1 Choose Settings > Playback > Volume Limit. The volume control shows the current volume. 2 Use the Click Wheel to select the maximum volume limit. 3 Press the Center button to set the maximum volume limit. 4 If you don’t want to require a combination to change the maximum volume, choose Done. To require a combination to change the maximum volume: 1 After setting the maximum volume, choose Lock. 2 In the screen that appears, enter a combination. To enter a combination:  Use the Click Wheel to select a number for the first position. Press the Center button to confirm your choice and move to the next position. 46 Chapter 3 Listening to Music  Use the same method to set the remaining numbers of the combination. You can use Next/Fast-forward (‘) to move to the next position and Previous/Rewind (]) to move to the previous position. Press the Center button in the final position to confirm the entire combination. The volume of songs and other audio may vary depending on how the audio was recorded or encoded. See “Setting Songs to Play at the Same Volume Level” on page 46 for information about how to set a relative volume level in iTunes and on iPod nano. The volume level may also vary if you use different earphones or headphones. Accessories that connect using the Dock Connector don’t support volume limits. If you set a combination, you must enter it before you can change or remove the maximum volume limit. To change the maximum volume limit: 1 Choose Settings > Playback > Volume Limit. 2 If you set a combination, enter it by using the Click Wheel to select the numbers and pressing the Center button to confirm them. A triangle on the volume bar indicates the current volume limit. 3 Use the Click Wheel to change the maximum volume limit. 4 Press Play/Pause (’) to accept the change. To remove the maximum volume limit: 1 If you’re currently listening to iPod nano, press Play/Pause (’). 2 Choose Settings > Playback > Volume Limit. 3 If you set a combination, enter it by using the Click Wheel to select the numbers and pressing the Center button to confirm each number. 4 Use the Click Wheel to move the volume limit to the maximum level on the volume bar. This removes any restriction on volume. 5 Press Play/Pause (’) to accept the change. If you forget the combination, you can restore iPod nano. See “Updating and Restoring iPod Software” on page 92. Setting Songs to Play at the Same Volume Level iTunes can automatically adjust the volume of songs, so they play at the same relative volume level. You can set iPod nano to use the iTunes volume settings. To set iTunes to play songs at the same sound level: 1 In iTunes, choose iTunes > Preferences if you’re using a Mac, or choose Edit > Preferences if you’re using a Windows PC. 2 Click Playback and select Sound Check, and then click OK.Chapter 3 Listening to Music 47 To set iPod nano to use the iTunes volume settings: m Choose Settings > Playback and set Sound Check to On. If you haven’t activated Sound Check in iTunes, setting it on iPod nano has no effect. Using the Equalizer You can use equalizer presets to change the sound on iPod nano to suit a particular music genre or style. For example, to make rock music sound better, set the equalizer to Rock. To use the equalizer to change the sound on iPod nano: m Choose Settings > Playback > EQ, and then choose an equalizer preset. If you assigned an equalizer preset to a song in iTunes and the iPod nano equalizer is set to Off, the song plays using the iTunes setting. See iTunes Help for more information. Crossfading Between Songs You can set iPod nano to fade out at the end of each song and fade in at the beginning of the song following it. To turn on crossfading: m Choose Settings > Playback > Audio Crossfade and select On. Note: Songs that are grouped for gapless playback play without gaps even when crossfading is on. Playing Podcasts Podcasts are free, downloadable shows available at the iTunes Store. Podcasts are organized by shows, episodes within shows, and chapters within episodes. If you stop playing a podcast and return to it later, the podcast begins playing where you left off. To play a podcast: 1 From the main menu, choose Podcasts, and then choose a show. Shows appear in reverse chronological order so you can play the most recent one first. You see a blue dot next to shows and episodes you haven’t played yet. 2 Choose an episode to play it. The Now Playing screen displays the show, episode, and date information, along with elapsed and remaining time. Press the Center button to see more information about the podcast. If the podcast has chapters, you can press Next/Fast-forward (‘) or Previous/Rewind (]) to skip to the next chapter or the beginning of the current chapter in the podcast.48 Chapter 3 Listening to Music If a podcast includes artwork, you also see a picture. Podcast artwork can change during an episode. For more information about podcasts, open iTunes and choose Help > iTunes Help. Then search for “podcasts.” Playing iTunes U Content iTunes U is a part of the iTunes Store featuring free lectures, language lessons, audiobooks, and more, which you can download and enjoy on iPod nano. iTunes U content is organized by collections, items within collections, authors, and providers. If you stop listening to iTunes U content and return to it later, the collection or item begins playing where you left off. To play iTunes U content: 1 From the main menu, choose iTunes U, and then choose a collection. Items within a collection appear in reverse chronological order so you can listen to the most recent one first. You see a blue dot next to collections and items you haven’t watched or listened to yet. 2 Choose an item to play it. For more information about iTunes U, open iTunes and choose Help > iTunes Help. Then search for “iTunes U.” Listening to Audiobooks To listen to audiobooks on iPod nano, choose Audiobooks from the Music menu. Choose an audiobook, and then press Play/Pause (’). If you stop listening to an audiobook on iPod nano and return to it later, the audiobook begins playing where you left off. iPod nano skips audiobooks when set to shuffle. If the audiobook you’re listening to has chapters, you can press Next/Fast-forward (‘) or Previous/Rewind (]) to skip to the next chapter or the beginning of the current chapter. You can also choose the audiobook from the Audiobooks menu, and then choose a chapter, or choose Resume to begin playing where you left off. You can play audiobooks at speeds faster or slower than normal. Setting the play speed affects only audiobooks purchased from the iTunes Store or audible.com. To set audiobook play speed: m Choose Settings > Playback > Audiobooks and choose a speed, or press and hold the Center button from the Now Playing window, and then choose a speed.4 49 4 Watching Videos You can use iPod nano to watch TV shows, movies, video podcasts, and more. Read this chapter to learn about watching videos on iPod nano and on your TV. You can view and listen to videos on iPod nano. If you have a compatible AV cable (available separately at www.apple.com/ipodstore), you can watch videos from iPod nano on your TV. Watching Videos on iPod nano Videos you add to iPod nano appear in the Videos menus. Music videos also appear in Music menus. Videos recorded with the iPod nano built-in video camera appear in the Videos menu, under Camera Videos. To watch a video on iPod nano: 1 Choose Videos and browse for a video. To browse for a video recorded with the iPod nano built-in video camera, choose Camera Videos. 2 Select a video and then press Play/Pause (’). To watch the video, hold iPod nano horizontally. You can rotate iPod nano to either the left or right. 50 Chapter 4 Watching Videos To watch videos recorded in portrait (vertical) format with the built-in video camera, hold iPod nano vertically. Watching Video Podcasts To watch a video podcast: m From the main menu, choose Podcasts and then choose a video podcast. For more information, see “Playing Podcasts” on page 47. Watching Videos Downloaded from iTunes U To watch an iTunes U video: m From the main menu, choose iTunes U and then choose a video. For more information, see “Playing iTunes U Content” on page 48. Watching Videos on a TV Connected to iPod nano If you have an AV cable from Apple, you can watch videos on a TV connected to your iPod nano. First you set iPod nano to display videos on a TV, then connect iPod nano to your TV, and then play a video. Use the Apple Component AV Cable, the Apple Composite AV Cable, or the Apple AV Connection Kit. Other similar RCA-type cables might not work. You can purchase the cables at www.apple.com/ipodstore or your local Apple Store. To set iPod nano to display videos on a TV: m Choose Videos > Settings, and then set TV Out to Ask or On. If you set TV Out to Ask, iPod nano gives you the option of displaying videos on TV or on iPod nano every time you play a video. If you set TV Out to On, iPod nano displays videos only on TV. If you try to play a video when iPod nano isn’t connected to a TV, iPod nano displays a message instructing you to connect to one. You can also set video to display full screen or widescreen, and set video to display on PAL or NTSC devices. To set TV settings: m Choose Videos > Settings, and then follow the instructions below. To set Do this Video to display on a TV Set TV Out to Ask or On. Video to display on a PAL or NTSC TV Set TV Signal to PAL or NTSC. PAL and NTSC refer to TV broadcast standards. Your TV might use either of these, depending on the region where it was purchased. If you aren’t sure which your TV uses, check the documentation that came with your TV. The format of your external TV Set TV Screen to Widescreen for 16:9 format or Standard for 4:3 format.Chapter 4 Watching Videos 51 To use the Apple Component AV Cable to connect iPod nano to your TV: 1 Plug the green, blue, and red video connectors into the component video (Y, Pb, and Pr) input ports on your TV. If you use the Apple Composite AV cable, plug the yellow video connector into the video input port on your TV. Your TV must have RCA video and audio ports. 2 Plug the white and red audio connectors into the left and right analog audio input ports on your TV. 3 Plug the 30-pin connector into your iPod nano or Universal Dock. 4 Plug the USB connector into your Apple USB Power Adapter or your computer to keep your iPod nano charged. 5 Turn on iPod nano and your TV or receiver to start playing. Make sure you set TV Out on iPod nano to On or Ask. The ports on your TV or receiver may differ from the ports in the illustration. To watch a video on your TV: 1 Connect iPod nano to your TV (see above). 2 Turn on your TV and set it to display from the input ports connected to iPod nano. For more information, see the documentation that came with your TV. 3 On iPod nano, choose Videos and browse for a video. Video to fit to your screen Set “Fit to Screen” to On. If you set “Fit to Screen” to Off, widescreen videos display in letterbox format on iPod nano or a standard (4:3) TV screen. Alternate audio to play Set Alternate Audio to On. Captions to display Set Captions to On. Subtitles to display Set Subtitles to On. To set Do this USB Power Adapter iPod Left audio (white) 30-pin connector Television Video in (Y, Pb, Pr) Right audio (red) USB connector5 52 5 Using the Video Camera With the built-in iPod nano video camera, you can record high-quality video with sound wherever you go. You can even record video with special effects. You can watch your recorded videos on iPod nano, and you can transfer them to your computer to edit and share. To use iPod nano as a video camera, choose Video Camera from the main menu. The display screen becomes a viewfinder. You can record video in landscape or portrait mode. In either mode, your current recording time appears in the upper right corner of the display.Chapter 5 Using the Video Camera 53 The lens and microphone are on the back of iPod nano, so you can use the display to see the video you’re recording. Be careful not to block the lens or microphone. Recording Video To record video: 1 Choose Video Camera from the main menu. 2 When you’re ready to begin recording, press the Center button. Press the Center button again to stop recording. When video is recording, a blinking red light appears in the upper right corner of the display, next to the recording time. Recording time depends on the available disk space and battery level. A recorded video can be up to 2 GB in size. Once a recorded video takes up 2 GB of disk space, recording stops. To resume recording, press the Center button. Recording Video with Special Effects You can record video with a variety of special effects on iPod nano. Note: Video effects can only be selected before recording. iPod nano can’t add effects to or remove effects from recorded videos. You can’t change video effects settings while recording. To record video with special effects: 1 Choose Video Camera from the main menu.54 Chapter 5 Using the Video Camera 2 Press and hold the Center button to display the video effects palette. 3 Use the Click Wheel to browse the effects, and press the Center button to select one. The viewfinder screen appears with the selected effect. 4 Press the Center button again to start recording with video effects. 5 Press the Center button to stop recording. If you exit the Video Camera screen to play back your video, video effects are turned off. To resume recording with a video effect, repeat steps 2 through 4. Playing Recorded Videos iPod nano saves your recorded videos to the Camera Roll. To go to the Camera Roll screen, press Menu from the Video Camera viewfinder screen. iPod nano lets you access your recorded videos from the Camera Roll screen, so you can watch what you just recorded without leaving the Video Camera application. Your recorded videos can also be played from the Videos menu. To play back a video you just recorded: 1 Press the Center button to stop recording. 2 Press Menu to enter the Camera Roll screen. 3 Choose the recording, and then press the Center button to play. You can also access a complete list of recorded videos on iPod nano from the Videos menu. To play a recorded video from the Videos menu: 1 Choose Videos in the main menu. 2 Choose Camera Videos to display a list of recorded videos. 3 Use the Click Wheel to scroll to the video you want to play, and then press Play/Pause (’) to start and stop playback. Playback stops automatically at the end of the video.Chapter 5 Using the Video Camera 55 Deleting Recorded Videos Removing unwanted videos clears disk space for new videos. Recorded videos can be deleted one at a time, or all at once. To delete a recorded video: 1 Go to Videos > Camera Videos and select a video from the list, or select a video from the Camera Roll screen. 2 Press and hold the Center button until a menu appears. 3 Choose Delete, or Delete All. Importing Recorded Videos to Your Computer You can import your recorded videos to your computer. If you have a Mac with iPhoto, you can easily share your recorded videos and add background music to them. iPod nano formats recorded videos as VGA video H.264 w/AAC 30 fps files. To import your recorded videos to your computer, iPod nano must be enabled for disk use. To enable iPod nano for disk use: 1 Connect iPod nano to your computer. 2 In iTunes, click iPod nano in the device list and click the Summary tab. 3 Select “Enable disk use.” In addition to appearing in iTunes, iPod nano also appears on your computer as an external disk, with the same name you gave it during initial setup. On a Mac, iPod nano appears in the Finder and on the Desktop. On a PC, iPod nano appears in Windows Explorer and My Computer. Your recorded videos are stored in the DCIM folder on iPod nano, and can be copied to your computer when iPod nano is connected to it. See the documentation that came with your computer for more information about copying files. After you copy your recorded videos to your computer, you can watch them on a Mac using QuickTime Player. You can watch them on a PC using QuickTime or Windows Media Player. To clear disk space on iPod nano after you’ve copied your recorded videos to your computer, delete them from the DCIM folder.56 Chapter 5 Using the Video Camera Importing Recorded Videos to a Mac with iPhoto Installed If your computer is a Mac with iPhoto 6.0.6 or later installed, you can use iPhoto to import your recorded videos from iPod nano to your Mac and post them on MobileMe. You can also add music by editing your recorded videos in QuickTime Player. To use iPhoto to import your recorded videos, iPod nano must be enabled for disk use. To import videos to your Mac using iPhoto: 1 Connect iPod nano to your computer. 2 Open iPhoto if it doesn’t open automatically. 3 Click iPod nano in the iPhoto device list. 4 Select the videos to import, and then click Selected or Import All. 5 Select Delete Photos or Keep Photos. Your recorded videos appear in your iPhoto library in Events and Photos, and in the list of recent imports. To share recorded videos using iPhoto: 1 Follow the instructions to import your recorded videos to iPhoto. 2 In iPhoto, select a recorded video. 3 Click MobileMe at the bottom of the iPhoto window. 4 Follow the onscreen instructions. You need a MobileMe account in order to share your recorded videos using MobileMe, and you need to set up iPhoto to publish to your account. For more information about online sharing, open iPhoto and choose Help > iPhoto Help. Sharing Recorded Videos from a Mac or PC After you import your recorded videos to your computer, you can post them on YouTube using a Mac or PC. To post recorded videos on Facebook: 1 Go to www.facebook.com and log in if necessary. 2 Click the video icon to the left of the Share button at the top of your Facebook homepage, and then click “Upload a Video.” 3 Follow the onscreen instructions to select and upload your video. To post recorded videos on YouTube: 1 Go to www.youtube.com and log in if necessary. 2 Click the Upload button at the top right of your YouTube homepage. 3 Follow the onscreen instructions to select and upload your video. If you have a Mac with iPhoto 8.1 or later and Mac OS X v10.6.1 or later, you can also export your recorded videos directly to YouTube.Chapter 5 Using the Video Camera 57 To post recorded videos on YouTube using iPhoto 8.1 or later and Mac OS X v10.6.1 or later: 1 In iPhoto, double-click the video you want to post. The video opens in QuickTime Player. 2 In QuickTime Player, choose Share > YouTube. 3 Enter your YouTube name and password, and then click Sign In. 4 Enter a description and tags. If you want to restrict access to your video, select “Make this movie personal.” 5 Click Next, and then click Share. When the export is complete, click the link that appears to go to your video page on YouTube. Accounts are required to upload videos to Facebook or YouTube. For more information, visit the websites. Adding Music to Your Recorded Videos You can use QuickTime Player to add music to your recorded videos. Select a recorded video in iPhoto, and then click Edit at the bottom of the iPhoto window. The recorded video opens in QuickTime Player, where you can add a music track to your recorded video. To learn how to add music to your recorded videos with QuickTime Player, choose Help > QuickTime Player Help, and see the instructions for extracting, adding, and moving tracks. To add music to your recorded videos with a Windows PC, see the documentation that came with your computer or photo application.6 58 6 Listening to FM Radio iPod nano has a built-in FM radio that displays station and song information, lets you pause live radio, and tags songs that you can preview and purchase in iTunes. To listen to FM radio, connect earphones or headphones to iPod nano, and then choose Radio from the main menu. iPod nano uses the earphone or headphone cord as the radio antenna. You must connect earphones or headphones to iPod nano in order to receive a radio signal. The radio doesn’t play through the iPod nano speaker. After you choose Radio from the main menu, the radio screen appears. When the radio dial is visible, you can use the Click Wheel or press Next/Fast-forward (‘) or Previous/Rewind (]) to tune to a station. Important: Radio frequencies shown in this chapter are for illustration purposes only and are not available in all areas.Chapter 6 Listening to FM Radio 59 When you tune to a station that supports RDS (Radio Data System), song, artist, and station information appear in the display. After you tune to a station, the progress bar replaces the radio dial. The progress bar fills up as you continue to listen to the station. Display item Function RDS data Displays the current station, song, and artist. Radio dial Tunes the FM radio. Favorite station markers Indicate that the current station is in the Favorites list. Radio signal icon Appears when the radio is on and receiving a signal. Station frequency Displays the number of the station that the radio is tuned to. Tag icon Appears if the current song supports iTunes Tagging. Progress bar Indicates the length of the radio buffer. Radio signal icon Progress bar Radio dial RDS data Station frequency Favorite station marker RDS data Tag icon Favorite station marker60 Chapter 6 Listening to FM Radio Tuning the FM radio You can tune the FM radio by browsing stations, seeking or scanning available stations, or saving your favorite stations and tuning to them directly. To browse radio stations: 1 Choose Radio from the main menu. If you don’t see the radio dial, press the Center button until it appears. 2 Use the Click Wheel to browse the radio dial. To seek available stations: 1 Choose Radio from the main menu. If you don’t see the radio dial, press the Center button until it appears. 2 Press Next/Fast-forward (‘) or Previous/Rewind (]) to seek the next or previous available station. Repeat to continue seeking. The station seeking function isn’t available if any favorite stations are set. If favorites are set, pressing Next/Fast-forward (‘) or Previous/Rewind (]) tunes the radio to favorite stations. To scan available stations: 1 Choose Radio from the main menu. If you don’t see the radio dial, press the Center button until it appears. 2 Press and hold Next/Fast-forward (‘) or Previous/Rewind (]) to scan available stations. You hear a five-second preview of each station before advancing to the next one. 3 To stop scanning and listen to the current station, press the Center button. 103.5FM 100 106 102 104Chapter 6 Listening to FM Radio 61 To save your favorite stations: 1 Tune to a station you want to save. 2 Press and hold the Center button until a menu appears. 3 Choose “Add to Favorites” and then press the Center button. To tune to a favorite station: 1 Choose Radio from the main menu. If you don’t see the radio dial, press the Center button until it appears. 2 Press Next/Fast-forward (‘) or Previous/Rewind (]) to tune to the next or previous favorite station. Repeat to continue tuning. Pausing Live Radio You can pause a radio broadcast, and resume playing it from the same point up to 15 minutes later. To pause live radio: m While the radio is playing, press Play/Pause (’) from any screen. 103.5FM62 Chapter 6 Listening to FM Radio The Pause (1) icon appears, and the time at which you paused is displayed above the progress bar. As Live Pause continues, a yellow triangle indicates the point where the radio was paused. The progress bar continues to fill up, indicating the time that’s passed since you paused. When you press Play/Pause (’) again, the program resumes from the same point.Chapter 6 Listening to FM Radio 63 You can also navigate forward or back along the progress bar. To fast-forward or rewind, press and hold Next/Fast-forward (‘) or Previous/Rewind (]), or use the Click Wheel. To skip forward or back in one-minute intervals, press Next/Fast-forward (‘) or Previous/Rewind (]). You can navigate through paused radio only when the progress bar appears, not the radio dial. To switch between the progress bar and radio dial: m Press the Center button. The progress bar is completely filled when Live Pause reaches the 15-minute limit. As long as your paused radio isn’t cleared, you can navigate through the 15 most recent minutes of the station you’re listening to. Anything older than 15 minutes is cleared to make room for the continuing broadcast. If you pause without resuming for 15 minutes, iPod nano goes to sleep and clears your paused radio. Paused radio is cleared if any of the following occurs:  You change stations. If you try to change stations while Live Pause is active, a warning appears and gives you the option to cancel.  You turn off iPod nano.  You exit Radio to play other media content, use the video camera, or record a voice memo.  The battery is very low on power and needs to be charged.  You pause the radio for 15 minutes without resuming play. You can disable Live Pause from the Radio menu, to conserve battery life. To disable Live Pause: 1 From the Radio screen, press Menu. 2 Choose Live Pause, and then press the Center button to select Off. To enable Live Pause again, select On.64 Chapter 6 Listening to FM Radio Tagging Songs to Sync to iTunes If you’re tuned to a radio station that supports iTunes Tagging, you can save a list of songs that you can preview and purchase later at the iTunes Store. Songs that can be tagged are marked with a tag icon next to the song title. To tag a song: 1 Press and hold the Center button until a menu appears. 2 Choose Tag, and then press the Center button. Your tagged songs appear in the Radio menu under Tagged Songs. The next time you sync iPod nano to iTunes, your tagged songs are synced and removed from iPod nano. They appear in Tunes, where you can preview and purchase them from the iTunes Store. Note: This feature may not be available for all radio stations. To preview and purchase tagged songs in iTunes: 1 Click Tagged below Store on the left side of the iTunes window. 2 Click the View button for the song you want. 3 To preview the song, double-click it or click the preview button. To buy the song, click the Buy button. Tag iconChapter 6 Listening to FM Radio 65 Using the Radio Menu To go to the Radio menu, press Menu from the radio screen. The Radio menu contains the following items. Menu item What it does Play Radio Turns the radio on, and returns iPod nano to the radio screen. Stop Radio Turns the radio off, and clears paused radio (appears only if the radio is on). Favorites Displays a list of the stations you’ve saved as favorites. Choose a station and press the Center button to play. Tagged Songs Displays a list of songs you’ve tagged for preview and purchase since you last synced with iTunes. Recent Songs Displays a list of recently played songs. Radio Regions Lets you set the radio for the region you’re in. Live Pause Enables or disables Live Pause.66 Chapter 6 Listening to FM Radio About Radio Regions iPod nano can be used in many countries to receive FM radio signals. iPod nano comes with five preset signal ranges, identified by region: The Americas, Asia, Australia, Europe, and Japan. To select a radio region: m Choose Radio Regions from the Settings menu, and then choose your region. The Radio Regions menu also appears in the Radio menu. Region settings are determined by international radio standards, not actual geographic regions. If you live in a country not listed in the Radio Regions menu, choose a region that best matches the radio frequency specifications in your country. The following table specifies the radio frequency range of each region in the Radio Regions menu, along with the increments between stations (indicated by the ± sign). Important: iPod nano is intended for the reception of public broadcasts only. Listening to transmissions that are not intended for the public is illegal in some countries and violators may be prosecuted. Check and obey the laws and regulations in the areas where you plan to use iPod nano. Radio region Radio frequency specifications Americas 87.5—107.9 MHz / ± 200 kHz Asia 87.5—108.0 MHz / ± 100 kHz Australia 87.5—107.9 MHz / ± 200 kHz Europe 87.5—108.0 MHz / ± 100 kHz Japan 76.0—90.0 MHz / ± 100 kHz7 67 7 Photo Features Read this chapter to learn about importing and viewing photos. You can import digital photos to your computer and add them to iPod nano. You can view your photos on iPod nano or as a slideshow on your TV. Importing Photos If your computer is a Mac, you can import photos from a digital camera to your computer using iPhoto. You can import other digital images into iPhoto, such as images you download from the web. For more information about importing, organizing, and editing your photos, open iPhoto and choose Help > iPhoto Help. iPhoto is available for purchase as part of the iLife suite of applications at www.apple.com/ilife or your local Apple Store. iPhoto might already be installed on your Mac, in the Applications folder. To import photos to a Windows PC, follow the instructions that came with your digital camera or photo application. Adding Photos from Your Computer to iPod nano If you have a Mac and iPhoto 7.1.5 or later, you can sync iPhoto albums automatically (for Mac OS X v10.4.11, iPhoto 6.0.6 or later is required). If you have a PC or Mac, you can add photos to iPod nano from a folder on your hard disk. Adding photos to iPod nano the first time might take some time, depending on how many photos are in your photo library. To sync photos from a Mac to iPod nano using iPhoto: 1 In iTunes, select iPod nano in the device list and click the Photos tab. 2 Select “Sync photos from: …” and then choose iPhoto from the pop-up menu. 3 Select your sync options:68 Chapter 7 Photo Features  If you want to add all your photos, select “All photos, albums, events, and faces.”  If you want to add selected photos, select “Selected albums, events, and faces, and automatically include … “ and choose an option from the pop-up menu. Then select the albums, events, and faces you want to add (Faces is supported only by iPhoto 8.1 or later).  If you want to add videos from iPhoto, select “Include videos.” 4 Click Apply. Each time you connect iPod nano to your computer, photos are synced automatically. To add photos from a folder on your hard disk to iPod nano: 1 Drag the images to a folder on your computer. If you want images to appear in separate photo albums on iPod nano, create folders within the main image folder and drag images to the new folders. 2 In iTunes, select iPod nano in the device list and click the Photos tab. 3 Select “Sync photos from …” 4 Choose “Choose Folder …” from the pop-up menu and select theimage folder. 5 Click Apply. Adding Full-Resolution Image Files to iPod nano When you add photos to iPod nano, iTunes optimizes the photos for viewing. Full-resolution image files aren’t transferred by default. Adding full-resolution image files is useful, for example if you want to move them from one computer to another, but isn’t necessary for viewing the images at full quality on iPod nano. To add full-resolution image files to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Photos tab. 2 Select “Include full-resolution photos.” 3 Click Apply. iTunes copies the full-resolution versions of the photos to the Photos folder on iPod nano. To delete photos from iPod nano: 1 In iTunes, select iPod nano in the device list and click the Photos tab. 2 Select “Sync photos from: …”  On a Mac, choose iPhoto from the pop-up menu.  On a Windows PC, choose Photoshop Album or Photoshop Elements from the pop-up menu. 3 Choose “Selected albums” and deselect the albums you no longer want on iPod nano. 4 Click Apply.Chapter 7 Photo Features 69 Viewing Photos You can view photos on iPod nano manually or as a slideshow. If you have an optional AV cable from Apple (for example, the Apple Component AV Cable), you can connect iPod nano to your TV and view photos as a slideshow with music. Viewing Photos on iPod nano To view photos on iPod nano: 1 On iPod nano, choose Photos > All Photos. Or choose Photos and a photo album to see only the photos in the album. Thumbnail views of the photos might take a moment to appear. 2 Select the photo you want and press the Center button. 3 To view photos, hold iPod nano vertically for portrait format, or horizontally for landscape format. From any photo-viewing screen, use the Click Wheel to scroll through photos (if you’re viewing a slideshow, the Click Wheel controls music volume only). Press Next/Fastforward (‘) or Previous/Rewind (]) to skip to the next or previous screen of photos. Press and hold Next/Fast-forward (‘) or Previous/Rewind (]) to skip to the last or first photo in the library or album.70 Chapter 7 Photo Features Viewing Slideshows You can view a slideshow, with music and transitions if you choose, on iPod nano. If you have an optional AV cable from Apple, you can view the slideshow on your TV. To set slideshow settings: m Choose Photos > Settings, and then follow these instructions: To view a slideshow on iPod nano: m Select any photo, album, or roll, and press Play/Pause (’). Or select any full-screen photo and press the Center button. To pause, press Play/Pause (’). To skip to the next or previous photo, press Next/Fast-forward (‘) or Previous/Rewind (]). When you view a slideshow, you can use the Click Wheel to control the music volume and adjust the brightness. You can’t use the Click Wheel to scroll through photos during a slideshow. If you view a slideshow of an album that includes videos, the slideshow pauses when it reaches a video. If music is playing, it continues to play. If you play the video, the music pauses while the video is playing, and then resumes. To play the video, press Play/Pause (’). To resume the slideshow, press Next/Fast-Forward (‘). To adjust the brightness during a slideshow: 1 Press the Center button until the brightness indicator appears. 2 Use the Click Wheel to adjust the brightness. To set Do this How long each slide is shown Choose Time Per Slide and pick a time. The music that plays during slideshows Choose Music and choose a playlist or Now Playing. If you’re using iPhoto, you can choose From iPhoto to copy the iPhoto music setting. Only the songs that you’ve added to iPod nano play. Slides to repeat Set Repeat to On. Slides to display in random order Set Shuffle Photos to On. Slides to display with transitions Choose Transitions and choose a transition type. Random includes all transition types except Ken Burns. Slideshows to display on iPod nano Set TV Out to Ask or Off. Slideshows to display on TV Set TV Out to Ask or On. If you set TV Out to Ask, iPod nano gives you the option of showing slideshows on TV or on iPod nano every time you start a slideshow. Slides to show on a PAL or NTSC TV Set TV Signal to PAL or NTSC. PAL and NTSC refer to TV broadcast standards. Your TV might use either of these, depending on the region where it was purchased. If you aren’t sure which your TV uses, check the documentation that came with your TV.Chapter 7 Photo Features 71 To connect iPod nano to your TV: 1 Connect the optional Apple Component or Composite AV cable to iPod nano. Use the Apple Component AV Cable, Apple Composite AV Cable, or Apple AV Connection Kit. Other similar RCA-type cables might not work. You can purchase the cables at www.apple.com/ipodstore. 2 Connect the audio connectors to the ports on your TV. Make sure you set TV Out on iPod nano to Ask or On. Your TV must have RCA video and audio ports. The ports on your TV or receiver may differ from the ports in the illustration. To view a slideshow on your TV: 1 Connect iPod nano to your TV (see page 51). 2 Turn on your TV and set it to display from the input ports connected to iPod nano. See the documentation that came with your TV for more information. 3 Use iPod nano to play and control the slideshow. Adding Photos from iPod nano to a Computer If you add full-resolution photos from your computer to iPod nano using the previous steps, they’re stored in a Photos folder on iPod nano. You can connect iPod nano to a computer and put these photos on the computer. iPod nano must be enabled for disk use (see “Using iPod nano as an External Disk” on page 84). To add photos from iPod nano to a computer: 1 Connect iPod nano to the computer. 2 Drag image files from the Photos folder or DCIM folder on iPod nano to the desktop or to a photo editing application on the computer. You can also use a photo editing application, such as iPhoto, to add photos stored in the Photos folder. See the documentation that came with the application for more information. To delete photos from the Photos folder on iPod nano: 1 Connect iPod nano to the computer. 2 Navigate to the Photos folder on iPod nano and delete the photos you no longer want.8 72 8 More Settings, Extra Features, and Accessories iPod nano can do a lot more than play songs. And you can do a lot more with it than listen to music. Read this chapter to find out more about the extra features of iPod nano, including how to use it as a pedometer; record voice memos; use it as an external disk, alarm, or sleep timer; play games; show the time of day in other parts of the world; display notes; and sync contacts, calendars, and to-do lists. Learn about how to use iPod nano as a stopwatch and to lock the screen, and about the accessories available for iPod nano. Using iPod nano as a Pedometer You can use iPod nano as a pedometer to count your steps and record your workouts. For more accurate results, keep iPod nano in your pocket or in the iPod nano Armband while using the pedometer. To use iPod nano as a pedometer: 1 From the Extras menu, choose Fitness and then choose Pedometer. 2 If you’re using the pedometer for the first time, enter your weight using the Click Wheel, and then press the Center button to begin a session. 3 At the end of the session, press the Center button to stop.Chapter 8 More Settings, Extra Features, and Accessories 73 To customize the pedometer settings: 1 From the Extras menu, choose Fitness and then choose Settings. 2 Choose from the following options: To view your workout history: 1 From the Extras menu, choose Fitness and then choose History. 2 Select a date from the calendar. Use the Click Wheel to select a day. Press Next/Fastforward (‘) or Previous/Rewind (]) to navigate through the months. 3 Press the Center button to display your workout history for the selected date. If you had multiple workout sessions on the selected date, choose a session. iPod nano displays your step goal, workout duration, start and end times, calories burned, and totals for the week and month. To view a bar graph of one of your workout sessions, choose a session, and then rotate iPod nano to landscape mode. The Pedometer menu item appears in the main menu when the pedometer is on, so you can stop your session quickly. The preview panel below the main menu displays your step count when you scroll to the Pedometer menu item. To set iPod nano to count your steps throughout the day, choose Pedometer in the Settings menu and select Always On. The Pedometer records your daily totals, so you can track your history without turning the pedometer off at the end of each day. The Pedometer menu item appears continuously in the main menu. To start sessions quickly, you can also add the Pedometer menu item to the main menu manually. See“Adding or Removing Items on the Main Menu” on page 10. With the Nike + iPod Sport Kit (available separately), iPod nano can also monitor and record your speed, distance, time elapsed, and calories burned, and track your cardio workouts on Nike + iPod-compatible gym equipment. To Do this Choose a pedometer mode Select Pedometer, and press the Center button to switch between Manual and Always On. Set a workout goal Choose Daily Step Goal, and then choose a goal from the list, or choose Custom and then use the Click Wheel to set a goal. Set your weight Choose Weight, use the Click Wheel to set your weight, and then press the Center button to enter. Set the pedometer orientation Choose Screen Orientation, and then choose Vertical, Left, or RIght.74 Chapter 8 More Settings, Extra Features, and Accessories When you sync iPod nano with iTunes, you can upload your pedometer and other workout information to the Nike+ website, where you can track your history, compete with your friends, and more. You’ll need a Nike+ account, which you can set up when you sync. To upload your workout information to Nike+: 1 Connect iPod nano to your computer and open iTunes (if it doesn’t open automatically). If you’re syncing workout information for the first time, a message appears: 2 Click Send, and then follow the onscreen instructions to set up your Nike+ account. Once you set up your account, a new tab appears in the iTunes window: 3 Click the Nike + iPod tab, and select “Automatically send workout data to Nike+” if it isn’t selected already. 4 Click Apply. To view and share your information at Nike+, click “Visit Nike+” in the Nike + iPod pane when iPod nano is connected to your computer, or go to www.nike.com and then log in to your account. Recording Voice Memos You can record voice memos using the built-in microphone in iPod nano or an optional iPod nano–compatible microphone (available for purchase at www.apple.com/ ipodstore). You can set chapter marks while you record, store voice memos on iPod nano and sync them with your computer, and add labels to voice memos. Voice memos can be up to two hours long. If you record for more than two hours, iPod nano automatically starts a new voice memo to continue your recording.Chapter 8 More Settings, Extra Features, and Accessories 75 To record a voice memo: 1 From the Extras menu, choose Voice Memos. The Record screen appears. 2 Press Play/Pause (’) or the Center button to begin recording. Be careful not to block the microphone, which is on the back of iPod nano. 3 To pause recording, press Play/Pause (’). Choose Resume to continue recording or press Play/Pause (’) again. 4 When you finish, press Menu and then choose “Stop and Save.” Your saved recording is listed by date and time. To set chapter marks: m While recording, press the Center button whenever you want to set a chapter mark. During playback, you can go directly to the next chapter by pressing the Next/Fastforward button. Press Previous/Rewind (]) once to go to the start of the current chapter, and twice to go to the start of the previous chapter. To label a recording: 1 From the Extras menu, choose Voice Memos and then press Menu. 2 Choose Voice Memos, and then choose a recording. 3 Choose Label, and then choose a label for the recording. You can choose Podcast, Interview, Lecture, Idea, Meeting, or Memo. To remove a label from a recording, choose None. To play a recording: 1 From the Extras menu, choose Voice Memos and then press Menu. 2 Choose Voice Memos, and then choose a recording. 3 Choose Play and then press the Center button.76 Chapter 8 More Settings, Extra Features, and Accessories To delete a recording: 1 From the Extras menu, choose Voice Memos and then press Menu. 2 Choose Voice Memos, and then choose a recording. 3 Choose Delete and then press the Center button. To sync voice memos with your computer: Voice memos are saved in a Recordings folder on iPod in the WAV file format. If you enable iPod nano for disk use, you can drag voice memos from the folder to copy them to your computer. If iPod nano is set to sync songs automatically (see “Syncing Music Automatically” on page 25) voice memos on iPod nano are automatically synced to a playlist in iTunes called Voice Memos (and removed from iPod nano) when you connect iPod nano. The Voice Memos playlist appears below Playlists on the left side of the iTunes window. Playing Games iPod nano comes with three games: Klondike, Maze, and Vortex. To play a game: m Choose Extras > Games and choose a game. When you play a game created for previous versions of iPod nano, you’re first shown how iPod nano controls work in the game you’re about to play. You can purchase additional games from the iTunes Store (in some countries) to play on iPod nano. After purchasing games in iTunes, you can add them to iPod nano by syncing them automatically or by managing them manually. Many games can be played in portrait or landscape mode. To buy a game: 1 In iTunes, select iTunes Store under Store on the left side of the iTunes window. 2 Choose iPod Games in the iTunes Store. 3 Select the game you want and click Buy Game. To sync games automatically to iPod nano: 1 In iTunes, select iPod nano in the device list and click the Games tab. 2 Select “Sync games.” 3 Click “All games” or “Selected games.” If you click “Selected games,” also select the games you want to sync. 4 Click Apply.Chapter 8 More Settings, Extra Features, and Accessories 77 Using Extra Settings You can set the date and time, clocks in different time zones, and alarm and sleep features on iPod nano. You can use iPod nano as a stopwatch or to play games, and you can lock the iPod nano screen. Setting and Viewing the Date and Time The date and time are set automatically from your computer’s clock when you connect iPod nano, but you can change the settings. To set date and time options: 1 Choose Settings > Date & Time. 2 Choose one or more of the following options: Adding Clocks for Other Time Zones To add clocks for other time zones: 1 Choose Extras > Clocks. 2 On the Clocks screen, click the Center button and choose Add. 3 Choose a region and then choose a city. The clocks you add appear in a list. The last clock you added appears last. To delete a clock: 1 Choose Extras > Clocks. 2 Choose the clock. 3 Press the Center button. 4 Choose Delete. To Do this Set the date Choose Date. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Set the time Choose Time. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Specify the time zone Choose Time Zone and use the Click Wheel to select a city in another time zone. Display the time in 24-hour format Choose 24 Hour Clock and press the Center button to turn the 24-hour format on or off. Display the time in the title bar Choose Time in Title and press the Center button to turn the option on or off. 78 Chapter 8 More Settings, Extra Features, and Accessories Setting Alarms You can set an alarm for any clock on iPod nano. To use iPod nano as an alarm clock: 1 Choose Extras > Alarms. 2 Choose Create Alarm and set one or more of the following options: If you sync calendar events with alarms to iPod nano, the events appear in the Alarms menu. To delete an alarm: 1 Choose Extras > Alarms. 2 Choose the alarm and then choose Delete. Setting the Sleep Timer You can set iPod nano to turn off automatically after playing music or other content for a specific period of time. To set the sleep timer: 1 Choose Extras > Alarms. 2 Choose Sleep Timer and choose how long you want iPod nano to play. To Do this Turn the alarm on Choose Alarm and choose On. Set the date Choose Date. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Set the time Choose Time. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Set a repeat option Choose Repeat and choose an option (for example, “weekdays”). Choose a sound Choose Alerts or a playlist. If you choose Alerts, select Beep to hear the alarm through the internal speaker. If you choose a playlist, connect iPod nano to speakers, earphones, or headphones to hear the alarm. Name the alarm Choose Label and choose an option (for example, “Wake up”).Chapter 8 More Settings, Extra Features, and Accessories 79 Using the Stopwatch You can use the stopwatch as you exercise to track your overall time and, if you’re running on a track, your lap times. You can play music while you use the stopwatch. To use the stopwatch: 1 Choose Extras > Stopwatch. 2 Press Play/Pause (’) to start the timer. 3 Press the Center button to record lap times. The two most recent lap times appear above the overall time. All lap times are recorded in the log. 4 Press Play/Pause (’) to stop the overall timer. To start the timer again, press Play/Pause (’). To start a new stopwatch session, press Menu and then choose New Timer. To review or delete a logged stopwatch session: 1 Choose Extras > Stopwatch. The current log and a list of saved sessions appear. 2 Choose a log to view session information. iPod nano stores stopwatch sessions with dates, times, and lap statistics. You see the date and time the session started; the total time of the session; the shortest, longest, and average lap times; and the last several lap times. 3 Press the Center button and choose Delete Log to delete the chosen log, or Clear Logs to delete all current logs. Locking the iPod nano Screen You can set a combination to prevent iPod nano from being used by someone without your permission. If you lock iPod nano while it isn’t connected to a computer, you must then enter a combination to unlock and use it. This combination is different from the Hold button, which just prevents iPod nano buttons from being pressed accidentally. The combination prevents another person from using iPod nano.80 Chapter 8 More Settings, Extra Features, and Accessories To set a combination for iPod nano: 1 Choose Extras > Screen Lock. 2 On the New Combination screen, enter a combination:  Use the Click Wheel to select a number for the first position. Press the Center button to confirm your choice and move to the next position.  Use the same method to set the remaining numbers of the combination. Press Next/ Fast-forward (‘) to move to the next position, or Previous/Rewind (]) to move to the previous position. Press the Center button in the final position. 3 On the Confirm Combination screen, enter the combination to confirm it, or press Menu to exit without locking the screen. When you finish, you return to the Screen Lock screen, where you can lock the screen or reset the combination. Press Menu to exit without locking the screen. To lock the iPod nano screen: m Choose Extras > Screen Lock > Lock. If you just finished setting your combination, Lock will already be selected on the screen. Just press the Center button to lock iPod. When the screen is locked, you see a picture of a lock. You might want to add the Screen Lock menu item to the main menu so that you can quickly lock the iPod nano screen. See “Adding or Removing Items on the Main Menu” on page 10. When you see the lock on the screen, you can unlock the iPod nano screen in two ways:  Press the Center button to enter the combination on iPod nano. Use the Click Wheel to select the numbers and press the Center button to confirm them. If you enter the wrong combination, the lock remains. Try again.  Connect iPod nano to the primary computer you use it with, and iPod nano automatically unlocks. If you try these methods and you still can’t unlock iPod nano, you can restore iPod nano. See “Updating and Restoring iPod Software” on page 92. To change a combination you’ve already set: 1 Choose Extras > Screen Lock > Reset Combination. 2 On the Enter Combination screen, enter the current combination. 3 On the New Combination screen, enter and confirm a new combination. If you can’t remember the current combination, the only way to clear it and enter a new one is to restore the iPod nano software. See “Updating and Restoring iPod Software” on page 92.Chapter 8 More Settings, Extra Features, and Accessories 81 Syncing Contacts, Calendars, and To-Do Lists iPod nano can store contacts, calendar events, and to-do lists for viewing on the go. You can use iTunes to sync the contact and calendar information on iPod nano with Address Book and iCal. If you’re using Windows XP, and you use Windows Address Book or Microsoft Outlook 2003 or later to store your contact information, you can use iTunes to sync the address book information on iPod nano. If you use Microsoft Outlook 2003 or later to keep a calendar, you can also sync calendar information. To sync contacts or calendar information using Mac OS X: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the device list and click the Contacts tab. 3 Do one of the following:  To sync contacts, in the Contacts section, select “Sync Address Book contacts,” and select an option:  To sync all contacts automatically, select “All contacts.”  To sync selected groups of contacts automatically, select “Selected groups” and select the groups you want to sync.  To copy contacts’ photos to iPod nano, when available, select “Include contacts’ photos.” When you click Apply, iTunes updates iPod nano with the Address Book contact information you specified.  To sync calendars, in the Calendars section, select “Sync iCal calendars,” and choose an option:  To sync all calendars automatically, choose “All calendars.”  To sync selected calendars automatically, choose “Selected calendars” and select the calendars you want to sync. When you click Apply, iTunes updates iPod nano with the calendar information you specified. 82 Chapter 8 More Settings, Extra Features, and Accessories To sync contacts or calendars using Windows Address Book or Microsoft Outlook for Windows: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the device list and click the Contacts tab. 3 Do one of the following:  To sync contacts, in the Contacts section, select “Sync contacts from” and choose Windows Address Book or Microsoft Outlook from the pop-up menu. Then select which contact information you want to sync.  To sync calendars from Microsoft Outlook, in the Calendars section, select “Sync calendars from Microsoft Outlook.” 4 Click Apply. You can also add contact and calendar information to iPod nano manually. iPod nano must be enabled as an external disk (see “Using iPod nano as an External Disk” on page 84). To add contact information manually: 1 Connect iPod nano and open your favorite email or contacts application. You can add contacts using Palm Desktop, Microsoft Outlook, Microsoft Entourage, and Eudora, among others. 2 Drag contacts from the application’s address book to the Contacts folder on iPod nano. In some cases, you might need to export contacts and then drag the exported file or files to the Contacts folder. See the documentation for your email or contacts application. To add appointments and other calendar events manually: 1 Export calendar events from any calendar application that uses the standard iCal format (filenames end in .ics) or vCal format (filenames end in .vcs). 2 Drag the files to the Calendars folder on iPod nano. To add to-do lists to iPod nano manually, save them in a calendar file with an .ics or .vcs extension. To view contacts on iPod nano: m Choose Extras > Contacts. To sort contacts by first or last name: m Choose Settings > General > Sort Contacts, and then select First or Last. To view calendar events: m Choose Extras > Calendars > All Calendars, and then choose a calendar. To view to-do lists: m Choose Extras > Calendars > To Do’s.Chapter 8 More Settings, Extra Features, and Accessories 83 Mono Audio Mono Audio combines the sound of the left and right channels into a monaural signal that’s played through both sides. This enables users with a hearing impairment in one ear to hear both channels with the other ear. To turn Mono Audio on or off: m Choose Settings > Playback > Mono Audio, and then select On or Off. Using Spoken Menus for Accessibility iPod nano features optional spoken menus, enabling visually impaired users to browse through their iPod nano content more easily. iTunes generates spoken menus using voices that are included in your computer’s operating system or that you may have purchased from third parties. Not all voices from computer operating systems or third parties are compatible with spoken menus, and not all languages are supported. To use spoken menus, VoiceOver must be enabled on iPod nano. For more information, see “Setting Up VoiceOver” on page 32. You must enable spoken menus in iTunes before you can activate them on iPod nano. To enable spoken menus in iTunes: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the device list and click the Summary tab. 3 Select “Enable spoken menus.” In Mac OS X, if you have VoiceOver turned on in Universal Access preferences, this option is selected by default. 4 Click Apply. After iPod nano syncs with iTunes, spoken menus are enabled and activated on your iPod nano. iPod nano takes longer to sync if spoken menus are being enabled. To deactivate spoken menus on iPod nano: m Choose Settings > General > Spoken Menus and then choose Off. To turn spoken menus on again, choose Settings > General > Spoken Menus, and then choose On. If VoiceOver is enabled, turning off spoken menus doesn’t disable VoiceOver. Note: The Spoken Menus option appears in the Settings menu on iPod nano only if spoken menus have been enabled in iTunes.84 Chapter 8 More Settings, Extra Features, and Accessories Using iPod nano as an External Disk You can use iPod nano as an external disk to store data files. You won’t see songs you add using iTunes in the Mac Finder or in Windows Explorer. And if you copy music files to iPod nano in the Mac Finder or Windows Explorer, you won’t be able to play them on iPod nano. Important: To import photos and recorded videos from iPod nano to your computer, external disk use must be enabled. To enable iPod nano as an external disk: 1 In iTunes, select iPod nano in the device list and click the Summary tab. 2 In the Options section, select “Enable disk use.” 3 Click Apply. When you use iPod nano as an external disk, the iPod nano disk icon appears on the desktop on a Mac, or as the next available drive letter in Windows Explorer on a Windows PC. Drag files to and from iPod nano to copy them. You can also click Summary and select “Manually manage music and videos” in the Options section to use iPod nano as an external disk. If you use iPod nano primarily as an external disk, you might want to keep iTunes from opening automatically when you connect iPod nano to your computer. To prevent iTunes from opening automatically when you connect iPod nano to your computer: 1 In iTunes, select iPod nano in the device list and click the Summary tab. 2 In the Options section, deselect “Open iTunes when this iPod is connected.” 3 Click Apply. Storing and Reading Notes You can store and read text notes on iPod nano, if it’s enabled as an external disk (see “Using iPod nano as an External Disk” on page 84). 1 Save a document in any word-processing application as a text (.txt) file. 2 Place the file in the Notes folder on iPod nano. To view notes: m Choose Extras > Notes.Chapter 8 More Settings, Extra Features, and Accessories 85 Learning About iPod nano Accessories iPod nano comes with some accessories, and many other accessories are available. To purchase iPod nano accessories, go to www.apple.com/ipodstore. Available accessories include:  iPod nano Armband  Apple Earphones with Remote and Mic  Apple In-Ear Headphones with Remote and Mic  Apple USB Power Adapter  Apple Component AV Cable  Apple Composite AV Cable  Apple Universal Dock  Nike + iPod Sport Kit  iPod Socks To use the earphones included with iPod nano: m Plug the earphones into the Headphones port. Then place the earbuds in your ears as shown. WARNING: Permanent hearing loss may occur if earbuds or headphones are used at high volume. You can adapt over time to a higher volume of sound that may sound normal but can be damaging to your hearing. If you experience ringing in your ears or muffled speech, stop listening and have your hearing checked. The louder the volume, the less time is required before your hearing could be affected. Hearing experts suggest that to protect your hearing:  Limit the amount of time you use earbuds or headphones at high volume.  Avoid turning up the volume to block out noisy surroundings.  Turn the volume down if you can’t hear people speaking near you. For information about setting a maximum volume limit on iPod, see “Setting the Maximum Volume Limit” on page 45. The earphone cord is adjustable.9 86 9 Tips and Troubleshooting Most problems with iPod nano can be solved quickly by following the advice in this chapter. General Suggestions Most problems with iPod nano can be solved by resetting it. First, make sure iPod nano is charged. To reset iPod nano: 1 Toggle the Hold switch on and off (slide it to HOLD and then back again). 2 Press and hold Menu and the Center button for at least 6 seconds, until the Apple logo appears. If iPod nano won’t turn on or respond  Make sure the Hold switch isn’t set to HOLD.  The iPod nano battery might need to be recharged. Connect iPod nano to your computer or to an Apple USB Power Adapter and let the battery recharge. Look for the lightning bolt icon on the iPod nano screen to verify that iPod nano is receiving a charge. To charge the battery, connect iPod nano to a USB 2.0 port on your computer.  Try the 5 Rs, one by one, until iPod nano responds. The 5 Rs: Reset, Retry, Restart, Reinstall, Restore Remember these five basic suggestions if you have a problem with iPod nano. Try these steps one at a time until your issue is resolved. If one of the following doesn’t help, read on for solutions to specific problems.  Reset iPod nano. See “General Suggestions,” below.  Retry with a different USB port if you cannot see iPod nano in iTunes.  Restart your computer, and make sure you have the latest software updates installed.  Reinstall iTunes software from the latest version on the web.  Restore iPod nano. See “Updating and Restoring iPod Software” on page 92.Chapter 9 Tips and Troubleshooting 87 If you want to disconnect iPod nano, but you see the message “Connected” or “Sync in Progress”  If iPod nano is syncing music, wait for it to complete.  Select iPod nano in the iTunes device list and click the Eject (C) button.  If iPod nano disappears from the device list in iTunes, but you still see the “Connected” or “Sync in Progress” message on the iPod nano screen, disconnect iPod nano.  If iPod nano doesn’t disappear from the device list in iTunes, drag the iPod nano icon from the desktop to the Trash if you’re using a Mac. If you’re using a Windows PC, eject the device in My Computer or click the Safely Remove Hardware icon in the system tray and select iPod nano. If you still see the “Connected” or “Sync in Progress” message, restart your computer and eject iPod nano again. If iPod nano isn’t playing music  Make sure the Hold switch isn’t set to HOLD.  Make sure the headphone connector is pushed in all the way.  Make sure the volume is adjusted properly. A maximum volume limit might have been set. You can change or remove it by using Settings > Volume Limit. See “Setting the Maximum Volume Limit” on page 45.  iPod nano might be paused. Try pressing Play/Pause (’).  Make sure you’re using iTunes 9.0 or later (available at www.apple.com/downloads). Songs purchased from the iTunes Store using earlier versions of iTunes won’t play on iPod nano until you upgrade iTunes.  If you’re using the Apple Universal Dock, make sure the iPod nano is seated firmly in the dock and make sure all cables are connected properly. If the internal speaker continues to play audio after you connect earphones or headphones to iPod nano  Disconnect and then reconnect the earphones or headphones. If the internal speaker doesn’t start playing audio after you disconnect earphones or headphones from iPod nano  Any audio that’s playing pauses automatically when you disconnect earphones or headphones from iPod nano. Press Play/Pause (’) to resume.  The FM radio doesn’t play through the internal speaker, because iPod nano uses the earphone or headphone cord as the radio antenna.88 Chapter 9 Tips and Troubleshooting If you connect iPod nano to your computer and nothing happens  Make sure you’ve installed the latest iTunes software from www.apple.com/downloads.  Try connecting to a different USB port on your computer. Note: A USB 2.0 port is recommended to connect iPod nano. USB 1.1 is significantly slower than USB 2.0. If you have a Windows PC that doesn’t have a USB 2.0 port, in some cases you can purchase and install a USB 2.0 card. For more information, go to www.apple.com/ipod.  iPod nano might need to be reset (see page 86).  If you’re connecting iPod nano to a portable computer using the Apple Dock Connector to USB 2.0 Cable, connect the computer to a power outlet before connecting iPod nano.  Make sure you have the required computer and software. See “If you want to doublecheck the system requirements” on page 91.  Check the cable connections. Unplug the cable at both ends and make sure no foreign objects are in the USB ports. Then plug the cable back in securely. Make sure the connectors on the cables are oriented correctly. They can be inserted only one way.  Try restarting your computer.  If none of the previous suggestions solves your problems, you might need to restore iPod nano software. See “Updating and Restoring iPod Software” on page 92. If iPod nano displays a “Connect to Power” message This message may appear if iPod nano is exceptionally low on power and the battery needs to be charged before iPod nano can communicate with your computer. To charge the battery, connect iPod nano to a USB 2.0 port on your computer. Leave iPod nano connected to your computer until the message disappears and iPod nano appears in iTunes or the Finder. Depending on how depleted the battery is, you may need to charge iPod nano for up to 30 minutes before it will start up. To charge iPod nano more quickly, use the optional Apple USB Power Adapter. If iPod nano displays a “Use iTunes to restore” message  Make sure you have the latest version of iTunes on your computer (download it from www.apple.com/downloads).  Connect iPod nano to your computer. When iTunes opens, follow the onscreen prompts to restore iPod nano.  If restoring iPod nano doesn’t solve the problem, iPod nano may need to be repaired. You can arrange for service at the iPod Service & Support website: www.apple.com/support/ipodChapter 9 Tips and Troubleshooting 89 If songs or data sync more slowly over USB 2.0  If you sync a large number of songs or amount of data using USB 2.0 and the iPod nano battery is low, iPod nano syncs the information at a reduced speed in order to conserve battery power.  If you want to sync at higher speeds, you can stop syncing and keep the iPod nano connected so that it can recharge, or connect it to the optional iPod USB 2.0 Power Adapter. Let iPod nano charge for about an hour, and then resume syncing your music or data. If you can’t add a song or other item to iPod nano The song may have been encoded in a format that iPod nano doesn’t support. The following audio file formats are supported by iPod nano. These include formats for audiobooks and podcasting:  AAC (M4A, M4B, M4P, up to 320 Kbps)  Apple Lossless (a high-quality compressed format)  MP3 (up to 320 Kbps)  MP3 Variable Bit Rate (VBR)  WAV  AA (audible.com spoken word, formats 2, 3, and 4)  AIFF A song encoded using Apple Lossless format has full CD-quality sound, but takes up only about half as much space as a song encoded using AIFF or WAV format. The same song encoded in AAC or MP3 format takes up even less space. When you import music from a CD using iTunes, it’s converted to AAC format by default. Using iTunes for Windows, you can convert nonprotected WMA files to AAC or MP3 format. This can be useful if you have a library of music encoded in WMA format. iPod nano doesn’t support WMA, MPEG Layer 1, MPEG Layer 2 audio files, or audible.com format 1. If you have a song in iTunes that isn’t supported by iPod nano, you can convert it to a supported format. For information, see iTunes Help. If iPod nano displays a “Connect to iTunes to activate Genius” message You haven’t turned on Genius in iTunes, or you haven’t synced iPod nano since you turned on Genius in iTunes. See “Turning On Genius in iTunes” on page 22.90 Chapter 9 Tips and Troubleshooting If iPod nano displays a “Genius is not available for the selected song” message Genius is on but is unable to make a Genius playlist using the selected song. New songs are added to the iTunes Store Genius database all the time, so try again soon. If iPod nano can’t receive a radio signal You haven’t connected earphones or headphones. Make sure the connection is complete, and try moving around the earphone or headphone cord. If you accidentally set iPod nano to use a language you don’t understand You can reset the language: 1 Press and hold Menu until the main menu appears. 2 Use the Click Wheel to find the menu item that causes the iPod nano device name to appear in the preview panel, and then choose it. That’s the Settings menu. 3 Choose the last menu item (Reset Settings). 4 Choose the first item (Reset) and select a language. Other iPod nano settings, such as song repeat, are also reset. Your synced content is not deleted or modified. If you can’t find the Reset Settings menu item, you can restore iPod nano to its original state and choose a language. See “Updating and Restoring iPod Software” on page 92. If you can’t see videos or photos on your TV  Use RCA-type cables made specifically for iPod nano, such as the Apple Component or Apple Composite AV cables, to connect iPod nano to your TV. Other similar RCAtype cables won’t work.  Make sure your TV is set to display images from the correct input source (see the documentation that came with your TV).  Make sure all cables are connected correctly (see “Watching Videos on a TV Connected to iPod nano” on page 50).  Make sure the yellow end of the Apple Composite AV Cable is connected to the video port on your TV.  If you’re trying to view a video, choose Videos > Settings and set TV Out to On, and then try again. If you’re trying to view a slideshow, choose Photos > Slideshow Settings and set TV Out to On, and then try again.  If that doesn’t work, choose Videos > Settings (for video) or Photos > Settings (for a slideshow) and set TV Signal to PAL or NTSC, depending on which type of TV you have. Try both settings.Chapter 9 Tips and Troubleshooting 91 If you want to double-check the system requirements To use iPod nano, you must have:  One of the following computer configurations:  A Mac with a USB 2.0 port  A Windows PC with a USB 2.0 port or a USB 2.0 card installed  One of the following operating systems:  Mac OS X v10.4.11 or later  Windows Vista  Windows XP Home or Professional with Service Pack 3 or later  iTunes 9 or later (iTunes can be downloaded from www.apple.com/downloads) If your Windows PC doesn’t have a USB 2.0 port, you can purchase and install a USB 2.0 card. For more information about cables and compatible USB cards, go to www.apple.com/ipod. On a Mac, iPhoto 7.1.5 or later is recommended for adding photos and albums to iPod nano. iPhoto 8.1 or later is required to use all iPod nano photo features. This software is optional. iPhoto might already be installed on your Mac. Check the Applications folder. On both Mac and Windows PC, iPod nano can sync digital photos from folders on your computer’s hard disk. If you want to use iPod nano with a Mac and a Windows PC If you’re using iPod nano with a Mac and you want to use it with a Windows PC, you must restore the iPod software for use with the PC (see “Updating and Restoring iPod Software” on page 92). Restoring the iPod software erases all data from iPod nano, including all songs. You cannot switch from using iPod nano with a Mac to using it with a Windows PC without erasing all data on iPod nano. If you lock the iPod nano screen and can’t unlock it Normally, if you can connect iPod nano to the computer it’s authorized to work with, iPod nano automatically unlocks. If the computer authorized to work with iPod nano is unavailable, you can connect iPod nano to another computer and use iTunes to restore iPod software. See the next section for more information. If you want to change the screen lock combination and you can’t remember the current combination, you must restore the iPod software and then set a new combination.92 Chapter 9 Tips and Troubleshooting Updating and Restoring iPod Software You can use iTunes to update or restore iPod software. It’s recommended that you update iPod nano to use the latest software. You can also restore the software, which puts iPod nano back to its original state.  If you choose to update, the software is updated, but your settings and songs aren’t affected.  If you choose to restore, all data is erased from iPod nano, including songs, videos, files, contacts, photos, calendar information, and any other data. All iPod nano settings are restored to their original state. To update or restore iPod nano: 1 Make sure you have an Internet connection and have installed the latest version of iTunes from www.apple.com/downloads. 2 Connect iPod nano to your computer. 3 In iTunes, select iPod nano in the device list and click the Summary tab. The Version section tells you whether iPod nano is up to date or needs a newer version of the software. 4 Click Update to install the latest version of the software. 5 If necessary, click Restore to restore iPod nano to its original settings (this erases all data from iPod nano). Follow the onscreen instructions to complete the restore process.10 93 10 Safety and Cleaning Read the following important safety and handling information before using iPod nano to avoid injury. Keep this safety information and the iPod nano User Guide handy for future reference. For downloadable versions of the iPod nano User Guide and the latest safety information, visit support.apple.com/manuals/ipod. Important Safety Information Handling iPod nano Do not drop, disassemble, open, crush, bend, deform, puncture, shred, microwave, incinerate, paint, or insert foreign objects into iPod nano. Avoiding water and wet locations Do not use iPod nano in rain, or near washbasins or other wet locations. Take care not to spill any food or liquid on iPod nano. In case iPod nano gets wet, unplug all cables, turn iPod nano off, and slide the Hold switch to HOLD before cleaning, and allow it to dry thoroughly before turning it on again. Do not attempt to dry iPod nano with an external heat source such as a microwave oven or hair dryer. An iPod nano that has been damaged as a result of exposure to liquids is not serviceable. ± Read all safety information below and operating instructions before using iPod to avoid injury. WARNING: Failure to follow these safety instructions could result in fire, electric shock, or other injury or damage.94 Chapter 10 Safety and Cleaning Repairing iPod nano Never attempt to repair iPod nano yourself. iPod nano does not contain any user-serviceable parts. If iPod nano has been submerged in water, punctured, or subjected to a severe fall, do not use it until you take it to an Apple Authorized Service Provider. For service information, choose iPod Help from the Help menu in iTunes or go to www.apple.com/support/ipod. The rechargeable battery in iPod nano should be replaced only by an Apple Authorized Service Provider. For more information about batteries, go to www.apple.com/batteries. Charging iPod nano To charge iPod nano, only use the included Apple Dock Connector to USB Cable with an Apple USB Power Adapter, or a high-power USB port on another device that is compliant with the USB 2.0 standard; another Apple branded product or accessory designed to work with iPod; or a third-party accessory certified to use the Apple “Made for iPod” logo. Read all safety instructions for any products and accessories before using with iPod nano. Apple is not responsible for the operation of third party accessories or their compliance with safety and regulatory standards. When you use the Apple USB Power Adapter (sold separately at www.apple.com/ ipodstore) to charge iPod nano, make sure that the power adapter is fully assembled before you plug it into a power outlet. Then insert the Apple USB Power Adapter firmly into the power outlet. Do not connect or disconnect the Apple USB Power Adapter with wet hands. Do not use any power adapter other than an Apple iPod power adapter to charge your iPod. The Apple USB Power Adapter may become warm during normal use. Always allow adequate ventilation around the Apple USB Power Adapter and use care when handling. Unplug the Apple USB Power Adapter if any of the following conditions exist:  The power cord or plug has become frayed or damaged.  The adapter is exposed to rain, liquids, or excessive moisture.  The adapter case has become damaged.  You suspect the adapter needs service or repair.  You want to clean the adapter. Avoiding hearing damage Permanent hearing loss may occur if the internal speaker, earbuds or headphones are used at high volume. Set the volume to a safe level. You can adapt over time to a higher volume of sound that may sound normal but can be damaging to your hearing. If you experience ringing in your ears or muffled speech, stop listening and have your hearing checked. The louder the volume, the less time is required before your hearing could be affected. Hearing experts suggest that to protect your hearing:  Limit the amount of time you use earbuds or headphones at high volume.  Avoid turning up the volume to block out noisy surroundings.Chapter 10 Safety and Cleaning 95  Turn the volume down if you can’t hear people speaking near you. For information about how to set a maximum volume limit on iPod nano, see “Setting the Maximum Volume Limit” on page 45. Driving and riding safely Use of iPod nano alone, or with headphones (even if used in only one ear) while operating a vehicle is not recommended and is illegal in some areas. Check and obey the laws and regulations on the use of mobile devices like iPod nano in areas where you drive or ride. Be careful and attentive while driving or riding a bicycle. Stop using iPod nano if you find it disruptive or distracting while operating any type of vehicle, or performing any other activity that requires your full attention. Seizures, blackouts, and eye strain A small percentage of people may be susceptible to blackouts or seizures (even if they have never had one before) when exposed to flashing lights or light patterns such as when playing games or watching video. If you have experienced seizures or blackouts or have a family history of such occurrences, please consult a physician before playing games (if available) or watching videos on your iPod nano. Discontinue use and consult a physician if you experience: headaches, blackouts, seizures, convulsion, eye or muscle twitching, loss of awareness, involuntary movements, or disorientation. To reduce risk of headaches, blackouts, seziures, and eyestrain, avoid prolonged use, hold iPod nano some distance from your eyes, use iPod nano in a well lit room, and take frequent breaks. Glass parts The outside cover of the display on iPod nano is made of glass. This glass could break if iPod nano is dropped on a hard surface or receives a substantial impact. If the glass chips or cracks, do not touch or attempt to remove the broken glass. Stop using iPod nano until the glass is replaced by an Apple Authorized Service Provider. Glass cracked due to misuse or abuse is not covered under the warranty. Repetitive motion When you perform repetitive activities such as playing games on iPod nano, you may experience occasional discomfort in your hands, arms, shoulders, neck, or other parts of your body. Take frequent breaks and if you have discomfort during or after such use, stop use and see a physician. Exercising Before starting any exercise program, you should have a complete physical examination by your physician. Do a warmup or stretching exercise before beginning any workout. Be careful and attentive while exercising. Slow down, if necessary, before adjusting your device while running. Stop exercising immediately if you feel pain, or feel faint, dizzy, exhausted, or short of breath. By exercising, you assume the risks inherent in physical exercise, including any injury that may result from such activity.96 Chapter 10 Safety and Cleaning Important Handling Information Carrying iPod nano iPod nano contains sensitive components, including, in some cases, a hard drive. Do not bend, drop, or crush iPod nano. If you are concerned about scratching iPod nano, you can use one of the many cases sold separately. Using connectors and ports Never force a connector into a port. Check for obstructions on the port. If the connector and port don’t join with reasonable ease, they probably don’t match. Make sure that the connector matches the port and that you have positioned the connector correctly in relation to the port. Operating iPod nano in acceptable temperatures Operate iPod nano in a place where the temperature is always between 0º and 35º C (32º to 95º F). In low-temperature conditions, iPod nano play time may temporarily shorten and battery charge time may temporarily lengthen. Store iPod nano in a place where the temperature is always between -20º and 45º C (-4º to 113º F). Don’t leave iPod nano in your car, because temperatures in parked cars can exceed this range. When you’re using iPod nano or charging the battery, it is normal for iPod nano to get warm. The exterior of iPod nano functions as a cooling surface that transfers heat from inside the unit to the cooler air outside. Keeping the outside of iPod nano clean To clean iPod nano, unplug all cables, turn iPod nano off, and slide the Hold switch to HOLD. Then use a soft, slightly damp, lintfree cloth. Avoid getting moisture in openings. Don’t use window cleaners, household cleaners, aerosol sprays, solvents, alcohol, ammonia, or abrasives to clean iPod nano. Disposing of iPod nano properly For information about the proper disposal of iPod nano, including other important regulatory compliance information, see “Regulatory Compliance Information” on page 98. NOTICE: Failure to follow these handling instructions could result in damage to iPod nano or other property.11 97 11 Learning More, Service, and Support You can find more information about using iPod nano in onscreen help and on the web. The following table describes where to get more iPod-related software and service information. To learn about Do this Service and support, discussions, tutorials, and Apple software downloads Go to: www.apple.com/support/ipodnano Using iTunes Open iTunes and choose Help > iTunes Help. For an online iTunes tutorial (available in some areas only), go to: www.apple.com/support/itunes Using iPhoto (on Mac OS X) Open iPhoto and choose Help > iPhoto Help. Using iCal (on Mac OS X) Open iCal and choose Help > iCal Help. The latest information on iPod nano Go to: www.apple.com/ipodnano Registering iPod nano To register iPod nano, install iTunes on your computer and connect iPod nano. Finding the iPod nano serial number Look at the back of iPod nano or choose Settings > About and press the Center button. In iTunes (with iPod nano connected to your computer), select iPod nano in the device list and click the Settings tab. Obtaining warranty service First follow the advice in this booklet, the onscreen help, and online resources. Then go to: www.apple.com/support/ipodnano98 Regulatory Compliance Information FCC Compliance Statement This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or TV reception is suspected. Radio and TV Interference This computer equipment generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and TV reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or TV reception, try to correct the interference by using one or more of the following measures:  Turn the TV or radio antenna until the interference stops.  Move the computer to one side or the other of the TV or radio.  Move the computer farther away from the TV or radio.  Plug the computer in to an outlet that is on a different circuit from the TV or radio. (That is, make certain the computer and the TV or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/TV technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product. This product was tested for EMC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, TV sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple Authorized Reseller. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only): Apple Inc. Corporate Compliance 1 Infinite Loop, MS 26-A Cupertino, CA 95014 Industry Canada Statement This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la classe B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. VCCI Class B Statement Korea Class B Statement (૶ ૺૺဧ ઠધබ 99 Russia European Community Battery Replacement The rechargeable battery in iPod nano should be replaced only by an authorized service provider. For battery replacement services go to: www.apple.com/support/ipod/service/battery Disposal and Recycling Information Your iPod must be disposed of properly according to local laws and regulations. Because this product contains a battery, the product must be disposed of separately from household waste. When your iPod reaches its end of life, contact Apple or your local authorities to learn about recycling options. For information about Apple’s recycling program, go to: www.apple.com/environment/recycling Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd. China: Taiwan: European Union—Disposal Information: This symbol means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Apple and the Environment At Apple, we recognize our responsibility to minimize the environmental impacts of our operations and products. For more information, go to: www.apple.com/environment © 2009 Apple Inc. All rights reserved. Apple, the Apple logo, iCal, iLife, iPhoto, iPod, iPod nano, iPod Socks, iTunes, Mac, Macintosh, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, the FireWire logo, and Shuffle are trademarks of Apple Inc. iTunes Store is a service mark of Apple Inc., registered in the U.S. and other countries. NIKE is a trademark of NIKE, Inc. and its affiliates and is used under license. Other company and product names mentioned herein may be trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. All understandings, agreements, or warranties, if any, take place directly between the vendors and the prospective users. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. 019-1716/2009-11Index 100 Index A accessibility using spoken menus 83 accessing additional options 6, 39 accessories for iPod 85 adding album artwork 21 adding menu items 10, 45 adding music disconnecting iPod 13 from more than one computer 25, 27 manually 30 methods 24 On-The-Go playlists 42 tutorial 97 adding other content 30 adding photos about 67 all or selected photos 67, 68 from computer to iPod 67 from iPod to computer 71 full-resolution image 68 address book, syncing 81 alarms deleting 78 setting 78 album, browsing by 42 album artwork adding 21 viewing 37 Apple USB Power Adapter 16 charging the battery 17 artist, browsing by 42 audiobooks 48 adding to iPod nano 29 setting play speed 48 automatic syncing 25, 27 AV cables 50, 51, 71 B backlight setting timer 11 turning on 6, 11 battery charge states when disconnected 17 charging 16 Energy Saver 18 improving performance 18 rechargeable 18 replacing 18 very low 88 viewing charge status 16 brightness setting 11 browsing by album 42 by artist 42 quickly 11, 38 songs 6, 34 videos 6 with Cover Flow 37, 38 buttons Center 5 disabling with Hold switch 6 Eject 15 C calendar events, syncing 81 Camera Roll 54 Center button, using 5, 34 Charging, Please Wait message 88 charging the battery about 16 using the Apple USB Power Adapter 17 using your computer 16 when battery very low 88 cleaning iPod 96 Click Wheel browsing songs 34 turning off the Click Wheel sound 11 using 5 clocks adding for other time zones 77 settings 77 close captions 51 compilations 45 component AV cable 50, 51, 71Index 101 composite AV cable 50, 51, 71 computer adding photos to iPod 67 charging the battery 16 connecting iPod 13 getting photos from iPod 71 problems connecting iPod 88 requirements 91 connecting iPod about 13 charging the battery 16 to a TV 51, 71 contacts sorting 82 syncing 81 controls disabling with Hold switch 8 using 5 converting unprotected WMA files 89 Cover Flow 37, 38 crossfading 47 customizing the Music menu 45 D data files, storing on iPod 84 date and time setting 77 viewing 77 determining battery charge 17 diamond icon on scrubber bar 6 digital photos. See photos disconnecting iPod about 13 during music update 13 ejecting first 14 instructions 15 troubleshooting 87 disk, using iPod as 84 displaying time in title bar 77 downloading See also adding; syncing E Eject button 15 ejecting before disconnecting 13, 14 Energy Saver 18 external disk, using iPod as 55, 84 F fast-forwarding a song or video 6 file formats, supported 89 finding your iPod serial number 8 fit video to screen 51 font size setting 10 full-resolution images 68 G games 76 buying games 76 Genius creating a playlist 7, 40 Genius slider 35 playing a playlist 7, 40, 41 saving a playlist 7, 40 syncing to iPod nano 26 turning on in iTunes 22 using on iPod nano 39 Genius Mixes playing 7, 40 syncing to iPod nano 26 getting help 97 getting information about your iPod 12 getting started with iPod 91 H hearing loss warning 85 help, getting 97 Hold switch 6, 8 I iCal, getting help 97 images. See photos importing video 22 importing contacts, calendars, and to-do lists. See syncing iPhoto getting help 97 importing camera videos 56 recommended version 91 iPod Dock 13 iPod Dock Connector 13 iPod Updater application 92 iTunes ejecting iPod 15 getting help 97 setting not to open automatically 84 Sound Check 47 iTunes U 29, 48, 50 L language resetting 90 specifying 10 letterbox 51 lightning bolt on battery icon 16 Live Pause 61 navigating 63 locating your iPod serial number 8102 Index locking iPod screen 79, 80 lyrics adding 21 viewing on iPod 37 M Mac OS X operating system 91 main menu adding or removing items 10 opening 5 returning to 6 settings 10, 45 using 9 Managing iPod manually 25 managing iPod manually 30 manually adding 30 maximum volume limit, setting 45 memos, recording 74 menu items adding or removing 10, 45 choosing 6 returning to main menu 6 returning to previous menu 6 modifying playlists 31 movies See also videos music iPod not playing 87 rating 36 setting for slideshows 70 tutorial 97 See also adding music; songs Music menu, customizing 45 music videos syncing 26 N navigating quickly 11 notes, storing and reading 84 Now Playing screen moving to any point in a song or video 6 scrubber bar 6 NTSC TV 50, 70 O On-The-Go playlists copying to computer 42 making 39, 41 rating songs 36 saving 42 operating system requirements 91 organizing your music 21 P PAL TV 50, 70 pausing a song 6 a video 6 Pedometer 72 settings 73 workout history 73 phone numbers, syncing 81 photo library 67 photos adding to iPod nano 67 deleting 68, 71 full-resolution 68 importing 67 syncing 67, 68 viewing on iPod 69 viewing slideshows 70 playing games 76 songs 6 videos 6 playlists adding songs 6, 31 making on iPod 39, 41 modifying 31 On-The-Go 39, 41 plug on battery icon 16 podcasting 47 podcasts listening 47 updating 28 ports RCA video and audio 51, 71 USB 91 preview panel 10 previous menu, returning to 6 problems. See troubleshooting Q quick navigation 11 R Radio 58 antenna 58, 90 Live Pause 61 Radio menu 65 screens 59 tagging songs 64 tuning 60 random play 6 rating songs 36 RCA video and audio ports 51, 71 rechargeable batteries 18 recorded videos adding music 57 deleting from iPod nano 55Index 103 importing to your computer 55 playing 54 sharing with iPhoto 56 recording voice memos 74 registering iPod 97 relative volume, playing songs at 46 removing menu items 10, 45 repairing iPod 94 replacing battery 18 replaying a song or video 6 requirements computer 91 operating system 91 reset all settings 12 resetting iPod 6, 86 resetting the language 90 restore message 88 restoring iPod software 92 rewinding a song or video 6 S Safely Remove Hardware icon 15 safety considerations setting up iPod 93 saving On-The-Go playlists 42 screen brightness, setting 11 screen lock 79 scrolling quickly 11 scrubber bar 6 searching iPod 44 Select button. See Center button serial number 8, 12 serial number, locating 97 service and support 97 sets of songs. See playlists setting combination for iPod 79 settings about your iPod 12 alarm 78 audiobook play speed 48 backlight timer 11 brightness 11 Click Wheel sound 11 date and time 77 font size 10 language 10 main menu 10, 45 PAL or NTSC TV 50, 70 playing songs at relative volume 46 repeating songs 44 reset all 12 shuffle songs 43 sleep timer 78 slideshow 70 TV 50 volume limit 45 setup 24 shake to shuffle 43 shuffle 35 shuffling songs on iPod 6, 43 sleep mode and charging the battery 16 sleep timer, setting 78 slideshows background music 70 random order 70 settings 70 viewing on iPod 70 software getting help 97 iPhoto 91 iPod Updater 92 updating 92 songs adding to On-The-Go playlists 6 browsing 6 browsing and playing 34 fast-forwarding 6 pausing 6 playing 6 playing at relative volume 46 rating 36 repeating 44 replaying 6 rewinding 6 shuffling 6, 43 skipping ahead 6 viewing lyrics 21 See also music sorting contacts 82 Sound Check 47 spoken menus 83 standard TV 50 stopwatch 79 storing data files on iPod 84 notes on iPod 84 supported operating systems 91 suppressing iTunes from opening 84 syncing address book 81 music 24 music videos 26 photos 67, 68 to-do lists 81 See also adding system requirements 91 T tagging songs 64104 Index previewing and purchasing 64 time, displaying in title bar 77 timer, setting for backlight 11 time zones, clocks for 77 title bar, displaying time 77 to-do lists, syncing 81 transitions for slides 70 troubleshooting connecting iPod to computer 88 cross-platform use 91 disconnecting iPod 87 iPod not playing music 87 iPod won’t respond 86 resetting iPod 86 restore message 88 safety considerations 93 setting incorrect language 90 slow syncing of music or data 89 software update and restore 92 TV slideshows 90 unlocking iPod screen 91 turning iPod on and off 6 tutorial 97 TV connecting to iPod 51, 71 PAL or NTSC 50, 70 settings 50 viewing slideshows 51, 71 TV shows See also videos U unlocking iPod screen 80, 91 unresponsive iPod 86 unsupported audio file formats 89 updating and restoring software 92 USB 2.0 port recommendation 91 slow syncing of music or data 89 USB port on keyboard 13 Use iTunes to restore message in display 88 V Video Camera 52 importing recorded videos 55 playing recorded videos 54 recording video 53 sharing recorded videos 56 special effects 53 video captions 51 video podcasts viewing on a TV 50 videos adding to iPod 27 browsing 6 fast-forwarding 6 importing from video camera 55 pausing 6 playing 6 playing recorded 54 renting 22 replaying 6 rewinding 6 skipping ahead 6 viewing on a TV 50 viewing on iPod 49 viewing album artwork 37 viewing lyrics 37 viewing photos 69 viewing slideshows on a TV 51, 71 on iPod 70 settings 70 troubleshooting 90 Voice Memos recording 74 syncing with your computer 76 VoiceOver setting up 32 using 44 volume changing 6 setting maximum limit 45 W warranty service 97 widescreen TV 50 Windows supported operating systems 91 troubleshooting 91 WMA files, converting 89 iPod touch Features Guide2 1 Contents Chapter 1 4 Getting Started 4 What You Need 4 Setting Up iPod touch 5 Getting Music, Videos, and Other Content onto iPod touch 9 Disconnecting iPod touch from Your Computer Chapter 2 10 Basics 10 iPod touch at a Glance 12 Home Screen 15 iPod touch Buttons and Touchscreen 21 Connecting to the Internet 22 Charging the Battery 23 Cleaning iPod touch Chapter 3 24 Music and Video 24 Syncing Content from Your iTunes Library 25 Playing Music 30 Watching Videos 32 Setting a Sleep Timer 33 Changing the Buttons on the Music Screen Chapter 4 34 Photos 34 Syncing Photos from Your Computer 35 Viewing Photos 37 Using a Photo as Wallpaper Chapter 5 39 iTunes Wi-Fi Music Store 39 Browsing and Searching 42 Purchasing Songs and Albums 43 Syncing Purchased Content 44 Verifying purchases 44 Changing Your iTunes Store Account InformationContents 3 Chapter 6 45 Applications 45 Safari 50 Calendar 53 Mail 58 Contacts 60 YouTube 63 Stocks 64 Maps 69 Weather 70 Clock 72 Calculator 73 Notes Chapter 7 74 Settings 74 Wi-Fi 75 Brightness 75 General 79 Music 80 Video 80 Photos 81 Mail 83 Safari 84 Contacts 84 Restoring or Transferring Your iPod touch Settings Appendix A 86 Tips and Troubleshooting 86 General Suggestions 89 Updating and Restoring iPod touch Software 90 Using iPod touch Accessibility Features Appendix B 91 Learning More, Service, and Support Index 931 4 1 Getting Started What You Need To use iPod touch, you need:  A Mac or a PC with a USB 2.0 port and one of the following operating systems:  Mac OS X version 10.4.10 or later  Windows XP Home or Professional with Service Pack 2 or later  Windows Vista Home Premium, Business, Enterprise, or Ultimate edition  iTunes 7.6 or later, available at www.apple.com/itunes  iTunes Store account (to purchase music over Wi-Fi)  An Internet connection Setting Up iPod touch Before you can use any of the iPod touch features, you must use iTunes to set up iPod touch. You can also register iPod touch and create an iTunes Store account (available in some countries) if you don’t already have one. Set up iPod touch 1 Download and install the latest version of iTunes from www.apple.com/itunes. 2 Connect iPod touch to a USB 2.0 port on your Mac or PC using the included cable. · To avoid injury, read all operating instructions in this guide and safety information in the Important Product Information Guide at www.apple.com/ support/manuals/ipod before using iPod touch.Chapter 1 Getting Started 5 The USB port on most keyboards doesn’t provide enough power. Unless your keyboard has a high-powered USB 2.0 port, you must connect iPod touch to a USB 2.0 port on your computer. 3 Follow the onscreen instructions in iTunes to set up iPod touch and sync your music, video, photos, and other content. Your computer must be connected to the Internet. By default, iTunes automatically syncs all songs and videos in your iTunes library to iPod touch. If you have more content in your library than will fit on iPod touch, iTunes alerts you that it can’t sync your content. You’ll need to use iTunes to select some of your songs, videos, and other content to sync. The following section tells you how. Getting Music, Videos, and Other Content onto iPod touch iPod touch lets you enjoy music, videos, photos, and much more, with its great sound and stunning 3.5-inch widescreen display. You get media and other content onto iPod touch by connecting iPod touch to your computer and using iTunes to sync your iTunes library and other information on your computer. You can set iTunes to sync any or all of the following:  Music and audiobooks  Movies  TV Shows6 Chapter 1 Getting Started  Podcasts  Photos  Contacts—names, phone numbers, addresses, email addresses, and so on  Calendars—appointments and events  Email account settings  Webpage bookmarks Music, movies, TV shows, and podcasts are synced from your iTunes library. If you don’t already have content in iTunes, the iTunes Store (part of iTunes and available in some countries) makes it easy to purchase or subscribe to content and download it to iTunes. You can also get music into iTunes from your CDs. To learn about iTunes and the iTunes Store, open iTunes and choose Help > iTunes Help. Photos, contacts, calendars, and webpage bookmarks are synced from applications on your computer, as described below. Email account settings are only synced from your computer’s email application to iPod touch. This allows you to customize your email accounts on iPod touch without affecting email account settings on your computer. You can set iPod touch to sync with only a portion of what’s on your computer. For example, you might want to sync certain playlists, the most recent unwatched movie, the most recent episodes of your favorite TV shows, and all unplayed podcasts. The sync settings make it easy to get just what you want onto iPod touch. You can adjust sync settings whenever iPod touch is connected to your computer. Important: You cannot connect and sync more than one iPod at a time. Disconnect one before connecting another. You should be logged in to your own user account on the computer before connecting iPod touch. On a PC, if you sync more than one iPod to the same user account, use the same sync settings for each. Syncing iPod touch You use the iPod touch settings panes in iTunes to specify the iTunes content and other information you want to sync to iPod touch. Sync iPod touch 1 Connect iPod touch to your computer, and open iTunes (if it doesn’t open automatically).Chapter 1 Getting Started 7 The USB port on most keyboards doesn’t provide enough power. You must connect iPod touch to a USB 2.0 port on your computer, unless your keyboard has a highpowered USB 2.0 port. 2 Select iPod touch in the iTunes source list (below Devices, on the left). 3 Configure the sync settings in each of the settings panes. 4 Click Apply in the lower-right corner of the screen. The following sections provide an overview of each of the iPod touch settings panes. For more information, open iTunes and choose Help > iTunes Help. Summary Pane Select “Open iTunes when this iPod is connected” to have iTunes open and sync iPod touch automatically whenever you connect it to your computer. Deselect this option if you want to sync only by clicking the Sync button in iTunes. For more information about preventing automatic syncing, see page 9. Select “Sync only checked songs and videos” if you want to sync only items that are checked in your iTunes library. Select “Manually manage music and videos” to turn off syncing in the Music, Movies, and TV Shows settings panes. Music, Movies, TV Shows, and Podcasts Panes Use these panes to specify the iTunes library content that you want to sync. You can sync all music, movies, TV shows, and podcasts, or select the specific playlists and items you want on iPod touch. Audiobooks and music videos are synced along with music. 8 Chapter 1 Getting Started If you want to watch rented movies on iPod touch, transfer them to iPod touch using the Movies pane in iTunes. If there’s not enough room on iPod touch for all the content you’ve specified, iTunes asks if you want to create a special playlist and set it to sync with iPod touch. Then iTunes randomly fills the playlist. Photos Pane You can sync photos from iPhoto 4.0.3 or later on a Mac, or from Adobe Photoshop Album 2.0 or later or Adobe Photoshop Elements 3.0 or later on a PC. You can also sync photos from any folder on your computer that contains images. Info Pane The Info pane lets you configure the sync settings for your contacts, calendars, and web browser bookmarks. Contacts You can sync contacts with applications such as Mac OS X Address Book, Microsoft Entourage, and Yahoo! Address Book on a Mac, or with Yahoo! Address Book, Windows Address Book (Outlook Express), or Microsoft Outlook 2003 or 2007 on a PC. (On a Mac, you can sync contacts on your computer with more than one application. On a PC, you can sync contacts with only one application.) If you sync with Yahoo! Address Book, you only need to click Configure to enter your new login information when you change your Yahoo! ID or password after you’ve set up syncing. Note: Syncing won’t delete any contact in Yahoo! Address Book that contains a Messenger ID, even if you’ve deleted the contact from your address book on your computer. To delete a contact with a Messenger ID, log in to your Yahoo! account and delete the contact using Yahoo! Address Book online. Calendars You can sync calendars from applications such as iCal and Microsoft Entourage on a Mac, or Microsoft Outlook on a PC. (On a Mac, you can sync calendars on your computer with more than one application on your computer. On a PC, you can sync calendars with only one application.) Mail Accounts You can sync email account settings from Mail on a Mac, and from Microsoft Outlook 2003 or 2007 or Outlook Express on a PC. Account settings are only transferred from your computer to iPod touch. Changes you make to an email account on iPod touch don’t affect the account on your computer.Chapter 1 Getting Started 9 The password for your Yahoo! email account isn’t saved on your computer. If you sync a Yahoo! email account, you must enter the password on iPod touch. From the Home screen choose Settings > Mail, choose your Yahoo! account, then enter your password in the password field. Web Browser You can sync bookmarks from Safari on a Mac, or Safari or Microsoft Internet Explorer on a PC. Advanced These options let you replace the information on iPod touch with the information on your computer during the next sync. Preventing Automatic Syncing You may want to prevent iPod touch from syncing automatically if you prefer to add items manually, or when you connect iPod touch to a computer other than the one you sync with. Turn off automatic syncing for iPod touch m Connect iPod touch to your computer, then select iPod touch in the iTunes source list (below Devices, on the left) and click the Summary tab. Deselect “Open iTunes when this iPod is connected.” You can still use iTunes to sync manually by clicking the Sync button. Prevent automatic syncing one time, without changing settings m Open iTunes. Then, as you connect iPod touch to your computer, press and hold Command-Option (if you’re using a Mac) or Shift-Control (if you’re using a PC) until you see iPod touch in the iTunes source list (below Devices, on the left). Sync manually m Select iPod touch in the iTunes source list, then click Sync in the lower-right corner of the window. Or, if you’ve changed any sync settings, click Apply. Disconnecting iPod touch from Your Computer Unless iPod touch is syncing with your computer, you can disconnect it from your computer at any time. When iPod touch is syncing with your computer, it shows “Sync in progress.” If you disconnect iPod touch before it finishes syncing, some data may not be transferred. When iPod touch finishes syncing, iTunes shows “iPod sync is complete.” To cancel a sync so you can disconnect iPod touch, drag the “slide to cancel” slider.2 10 2 Basics iPod touch at a Glance Sleep/Wake button Headphones port Dock connector Wi-Fi antenna Home button Touch screen Application icons Status barChapter 2 Basics 11 Status Icons The icons in the status bar at the top of the screen give information about iPod touch: Item What you can do with it Stereo headphones Listen to music and videos. Dock connector to USB cable Use the cable to connect iPod touch to your computer to sync and charge, or to the Apple USB Power Adapter (available separately) to charge. The cable can be used with the optional dock or plugged directly into iPod touch. Stand Stand up iPod touch for viewing videos or photo slideshows. Polishing cloth Wipe the iPod touch screen. Stand Stereo headphones Dock connector to USB cable Polishing cloth iPod Status icon What it means Wi-Fi Shows that iPod touch is connected to a Wi-Fi network. The more bars, the stronger the connection. See page 21. ¥ Lock Shows that iPod touch is locked. See page 15. Play Shows that a song is playing. See page 26. Alarm Shows that an alarm is set. See page 71. Battery Shows the battery level or charging status. See page 22.12 Chapter 2 Basics Home Screen Press the Home button at any time to see the applications on iPod touch. Tap any application icon to get started. iPod touch Applications The following applications are included with iPod touch: Music Listen to your songs, podcasts, and audiobooks. Videos Watch movies, music videos, video podcasts, and TV shows. Photos View photos transferred from your computer. View them in portrait or landscape mode. Zoom in on any photo for a closer look. Watch a slideshow. Use photos as wallpaper. iTunes Search the iTunes Wi-Fi Music Store music catalog, or browse, preview, and purchase new releases, top-ten songs and albums, and more.1 In select Starbucks locations,2 find out what song is playing in the café, then buy it instantly. Browse, preview, and purchase other songs from featured Starbucks Collections. Safari Browse websites over a Wi-Fi connection. Rotate iPod touch sideways for viewing in landscape orientation. Double-tap to zoom in or out—Safari automatically fits sections to the screen for easy reading. Add Safari Web Clips to the Home screen for fast access to favorite websites. Calendar View your iCal, Microsoft Entourage, or Microsoft Outlook calendar synced from your computer. Mail Send and receive email using your existing email accounts. iPod touch works with the most popular email systems—including Yahoo! Mail, Google email, AOL, and .Mac Mail—as well as most industry-standard POP3 and IMAP email systems. Contacts Get contact information synced from Mac OS X Address Book, Yahoo! Address Book, Windows Address Book (Outlook Express), or Microsoft Outlook. Add, change, or delete contacts, which get synced back to your computer. YouTube Play videos from YouTube’s online collection.3 Search for any video, or browse featured, most viewed, most recently updated, and top-rated videos.Chapter 2 Basics 13 Customizing the Home Screen Layout You can customize the layout of icons on the Home screen—including the Dock icons along the bottom of the screen. If you want, arrange them over multiple Home screens. Rearrange icons 1 Touch and hold any Home screen icon until all the icons begin to wiggle. 2 Arrange the icons by dragging them. 3 Press the Home button to save your arrangement. You can also add links to your favorite webpages on the Home screen. See “Adding Safari Web Clips to the Home Screen” on page 49. Stocks Watch your favorite stocks, updated automatically from the Internet. Maps See a street map, satellite, or hybrid view of locations around the world. Zoom in for a closer look. Find your current approximate location. Get detailed driving directions and see current highway traffic conditions. Find businesses in the area.4 Weather Get current weather conditions and a six-day forecast. Store your favorite cities for a quick weather report anytime. Clock View the time in cities around the world—create clocks for your favorites. Set one or more alarms. Use the stopwatch, or set a countdown timer. Calculator Add, subtract, multiply, and divide. Notes Jot notes on the go—reminders, grocery lists, brilliant ideas. Send them in email. Settings Adjust all iPod touch settings in one convenient place. Join Wi-Fi networks. Set your wallpaper and screen brightness, and settings for music, video, photos, and more. Set auto-lock and a passcode for security. 1 Not available in all areas. 2 In the U.S. only. 3 Not available in all areas. 4 Some features or services not available in all areas.14 Chapter 2 Basics Create additional Home screens m While arranging icons, drag a button to the edge of the screen until a new screen appears. You can flick to return to the original screen and drag more icons to the new screen. You can create up to nine screens. The number of dots at the bottom shows the number of screens you have, and indicates which screen you are viewing. Switch to another Home screen m Flick left or right. Reset your Home screen to the default layout m Choose Settings > General > Reset and tap Reset Home Screen Layout.Chapter 2 Basics 15 iPod touch Buttons and Touchscreen A few simple buttons and a high-resolution touchscreen make it easy to learn and use iPod touch. Locking iPod touch and Turning It On or Off When you’re not using iPod touch, you can lock it. When iPod touch is locked, nothing happens if you touch the screen. By default, if you don’t touch the screen for a minute, iPod touch locks automatically. Locking iPod touch does not stop music playback, so you can lock iPod touch and continue to listen to music. To temporarily display playback controls when iPod touch is locked, double-click the Home button. For information about locking iPod touch with a passcode, see “Passcode Lock” on page 77. Sleep/Wake button To Do this Lock iPod touch Press the Sleep/Wake button. Unlock iPod touch Press the Home button or the Sleep/Wake button, then drag the slider. Turn iPod touch completely off Press and hold the Sleep/Wake button for a few seconds until the red slider appears, then drag the slider. Turn iPod touch on Press and hold the Sleep/Wake button until the Apple logo appears. Display playback controls when iPod touch is locked Double-click the Home button.16 Chapter 2 Basics Using the Touchscreen The controls on the touchscreen change dynamically depending on the task you are performing. m Tap any application to open it. m Press the Home button below the display at any time to return to the Home screen and see all the applications. m Drag up or down to scroll. Dragging your finger to scroll doesn’t choose or activate anything on the screen.Chapter 2 Basics 17 m Flick to scroll quickly. You can wait for scrolling to stop, or tap or touch anywhere on the screen to stop it immediately. Tapping or touching to stop scrolling doesn’t choose or activate anything on the screen. m Some lists have an index along the right side. Tap a letter to jump to items starting with that letter. Drag your finger along the index to scroll quickly through the list. m Tap an item in the list to choose it. Depending on the list, tapping an item can do different things—for example, it may open a new list, play a song, or show someone’s contact information. m The back button in the upper-left corner shows the name of the previous list. Tap it to go back. Index18 Chapter 2 Basics m When viewing photos, web pages, email, or maps, you can zoom in and out. Pinch your fingers together or apart. For photos and web pages, you can double-tap (tap twice quickly) to zoom in, then double-tap again to zoom out. For maps, double-tap to zoom in and tap once with two fingers to zoom out. Onscreen Keyboard You can use the onscreen keyboard to enter text, such as contact information. The intelligent keyboard automatically suggests corrections as you type (some languages only), to help prevent mistyped words. iPod touch provides keyboards in multiple languages, and supports the following keyboard formats:  QWERTY  QWERTZ  AZERTY  QZERTY  Japanese IME See “Keyboard” on page 78 for information about turning on keyboards for different languages and other keyboard settings.Chapter 2 Basics 19 Entering text Start by typing with just your index finger. As you get more proficient, you can type more quickly by using your thumbs. 1 Tap a text field, such as in a note or new contact, to bring up the keyboard. 2 Tap keys on the keyboard. As you type, each letter appears above your thumb or finger. If you touch the wrong key, you can slide your finger to the correct key. The letter is not entered until you release your finger from the key. To Do this Type uppercase Tap the Shift key before tapping a letter. Quickly type a period and space Double-tap the space bar. Turn caps lock on Enable caps lock (see page 78), then double-tap the Shift key. The Shift key turns blue, and all letters you type are uppercase. Tap the Shift key again to turn caps lock off. Shows numbers, punctuation, or symbols Tap the Number key. Tap the Symbol key to see additional punctuation and symbols.20 Chapter 2 Basics Accepting or Rejecting Dictionary Suggestions iPod touch has dictionaries for English, English (UK), French, French (Canada), German, Japanese, Spanish, Italian, and Dutch. The appropriate dictionary is activated automatically when you select a keyboard on iPod touch. iPod touch uses the active dictionary to suggest corrections or complete the word you’re typing. If you’re using a keyboard that doesn’t have a dictionary, iPod touch won’t make suggestions. You don’t need to interrupt your typing to accept the suggested word.  To use the suggested word, type a space, punctuation mark, or return character.  To reject the suggested word, finish typing the word as you want it, then tap the “x” to dismiss the suggestion before typing anything else. Each time you reject a suggestion for the same word, iPod touch becomes more likely to accept your word. Editing text m Touch and hold to see a magnified view, then drag to position the insertion point. Suggested wordChapter 2 Basics 21 Connecting to the Internet iPod touch connects to the Internet via Wi-Fi networks. iPod touch can join AirPort and other Wi-Fi networks at home, at work, or at Wi-Fi hotspots around the world. When joined to a Wi-Fi network that is connected to the Internet, iPod touch connects to the Internet automatically whenever you use Mail, Safari, YouTube, Stocks, Maps, Weather, or the iTunes Wi-Fi Music Store. Many Wi-Fi networks can be used free of charge. Some Wi-Fi networks require a fee. To join a Wi-Fi network at a hotspot where charges apply, you can usually open Safari to see a webpage that allows you to sign up for service. Joining a Wi-Fi Network The Wi-Fi settings let you turn on Wi-Fi and join Wi-Fi networks. Turn on Wi-Fi m Choose Settings > Wi-Fi and turn Wi-Fi on. Join a Wi-Fi network m Choose Settings > Wi-Fi, wait a moment as iPod touch detects networks in range, then select a network. If necessary, enter a password and tap Join (networks that require a password appear with a lock icon). Once you’ve joined a Wi-Fi network manually, iPod touch will automatically connect to it whenever the network is in range. If more than one previously used network is in range, iPod touch joins the one last used. When iPod touch is connected to a Wi-Fi network, the Wi-Fi icon in the status bar at the top of the screen shows connection strength. The more bars you see, the stronger the connection. For more information about joining Wi-Fi networks and configuring Wi-Fi settings, see page 74.22 Chapter 2 Basics Charging the Battery iPod touch has an internal rechargeable battery. Charge the battery and sync iPod touch m Connect iPod touch to your computer (not your keyboard) using the included cable. Note: If iPod touch is connected to a computer that’s turned off or in sleep or standby mode, the iPod touch battery may drain instead of charge. An icon in the upper-right corner of the screen shows battery charging status. If you charge the battery while syncing or using iPod touch, it may take longer to charge. You can also charge iPod touch using the Apple USB Power Adapter, available separately. WARNING: For important safety information about charging iPod touch, see the Important Product Information Guide at www.apple.com/support/manuals/ipod. Charging ChargedChapter 2 Basics 23 Important: If iPod touch is very low on power, it may display one of the following images indicating that iPod touch needs to charge for up to ten minutes before you can use it. If iPod touch is extremely low on power, the display may be blank for up to two minutes before one of the low-battery images appears. Rechargeable batteries have a limited number of charge cycles and may eventually need to be replaced. The iPod touch battery is not user replaceable; it can be replaced only by an authorized service provider. For more information, go to: www.apple.com/batteries Cleaning iPod touch Use the polishing cloth that came with iPod touch to gently wipe the glass screen and the case. You can also use a soft, slightly damp, lint-free cloth. Unplug and turn off iPod touch (press and hold the Sleep/Wake button, then drag the onscreen red slider). Avoid getting moisture in openings. Don’t use window cleaners, household cleaners, aerosol sprays, solvents, alcohol, ammonia, or abrasives to clean iPod touch. or3 24 3 Music and Video Tap Music to listen to songs, audiobooks, and podcasts, or tap Video to watch TV shows, movies, and other video. iPod touch syncs with iTunes on your computer to get the songs, movies, TV shows, and other content you’ve collected in your iTunes library. For information about using iTunes to get music and other media onto your computer, open iTunes and choose Help > iTunes Help. Syncing Content from Your iTunes Library If you’ve turned on syncing, iTunes automatically syncs content from your iTunes library to iPod touch each time you connect it to your computer. iTunes lets you sync all of your media, or specific songs, movies, videos, and podcasts. For example, you could set iTunes to sync selected music playlists, the most recent unwatched movie, and the three most recent episodes of your favorite TV show. If there are more songs in your iTunes library than can fit on iPod touch, iTunes asks if you want to create a special playlist and set it to sync with iPod touch. Then iTunes randomly fills the playlist. You can add or delete songs from the playlist and sync again. If you set iTunes to sync more songs, videos, and other content than can fit on iPod touch, you can have iTunes automatically delete random content from iPod touch to make room, or you can stop the sync and reconfigure your sync settings. When you sync podcasts or audiobooks on iPod touch with those on your computer, both iTunes and iPod touch remember where you stopped listening and start playing from that position. For more information about syncing iPod touch with your iTunes library, see “Getting Music, Videos, and Other Content onto iPod touch” on page 5.Chapter 3 Music and Video 25 Transferring Purchased Content from iPod touch to Another Authorized Computer Music, video, and podcasts sync from your iTunes library to iPod touch, but not from iPod touch to your iTunes library. However, content you purchased using the iTunes Wi-Fi Music Store on iPod touch is automatically copied to your iTunes library. You can also transfer content on iPod touch that was purchased using iTunes on one computer to an iTunes library on another authorized computer. Transfer content from iPod touch to another computer m Connect iPod touch to the other computer. iTunes asks if you want to transfer purchased content. You can also connect iPod touch and, in iTunes, choose File > Transfer Purchases. To play the content, the computer must be authorized to play content from your iTunes account. Supported Music and Video Formats Only songs and videos encoded in formats that iPod touch supports are transferred to iPod touch. For information about which formats iPod touch supports, see page 88. Converting Videos for iPod touch You can add videos other than those purchased from iTunes to iPod touch, such as videos you create in iMovie on a Macintosh or videos you download from the Internet. If you try to add a video from iTunes to iPod touch and a message says the video can’t play on iPod touch, you can convert the video. Convert a video to work with iPod touch m Select the video in your iTunes library and choose Advanced > “Convert Selection for iPod.” Then add the converted video to iPod touch. Playing Music The high resolution multi-touch display makes listening to songs on iPod touch as much a visual experience as a musical one. You can scroll through your playlists, or use Cover Flow to browse through your album art. WARNING: For important information about avoiding hearing loss, see the Important Product Information Guide at www.apple.com/support/manuals/ipod.26 Chapter 3 Music and Video Playing Songs, Audiobooks, and Podcasts Browse your collection m Tap Music, then tap Playlists, Artists, Songs, or Albums. Tap More to browse Audiobooks, Compilations, Composers, Genres, or Podcasts. Play a song m Tap the song. Controlling Song Playback When you play a song, the Now Playing screen appears: To Do this Adjust the volume Drag the volume slider. Pause a song Tap . Resume playback Tap . Restart a song or a chapter in an audiobook or podcast Tap . Skip to the next or previous song or chapter in an audiobook or podcast Tap twice to skip to the previous song. Tap to skip to the next song. Rewind or fast-forward Touch and hold or . Return to the browse lists Tap . Or swipe to the right over the album cover. Return to the Now Playing screen Tap Now Playing. See the tracks in your collection from the current album Tap . Tap any track to play it. Display a song’s lyrics Tap the album cover when playing a song. (Lyrics appear only if you’ve added them to the song using the song’s Info window in iTunes.) Next/Fast-forward Play/Pause Track List Now Playing screen Back Previous/Rewind VolumeChapter 3 Music and Video 27 Displaying playback controls at any time You can display playback controls at any time when you’re listening to music and using another application—or even when iPod touch is locked—by double-clicking the Home button. If iPod touch is active, the playback controls appear over the application you’re using. After using the controls, you can close them or tap Music to go to the Now Playing screen. If iPod touch is locked, the controls appear onscreen, then are dismissed automatically after you finish using them. Additional Controls m From the Now Playing screen tap the album cover. The repeat and shuffle controls and the scrubber bar appear. You can see time elapsed, time remaining, and the song number. The song’s lyrics appear also, if you’ve added them to the song using iTunes. To Do this Set iPod touch to repeat songs Tap . Tap again to set iPod touch to repeat only the current song. = iPod touch is set to repeat all songs in the current album or list. = iPod touch is set to repeat the current song over and over. = iPod touch is not set to repeat songs. Skip to any point in a song Drag the playhead along the scrubber bar. Set iPod touch to shuffle songs Tap . Tap again to set iPod touch to play songs in order. = iPod touch is set to shuffle songs. = iPod touch is set to play songs in order. Shuffle the tracks in any playlist, album, or other list of songs Tap Shuffle at the top of the list. For example, to shuffle all the songs on iPod touch, choose Songs > Shuffle. Whether or not iPod touch is set to shuffle, if you tap Shuffle at the top of a list of songs, iPod touch plays the songs from that list in random order. Scrubber bar Repeat Shuffle Playhead28 Chapter 3 Music and Video Browsing Album Covers in Cover Flow When you’re browsing music, you can rotate iPod touch sideways to see your iTunes content in Cover Flow and browse your music by album artwork. To Do this See Cover Flow Rotate iPod touch sideways. Browse album covers Drag or flick left or right. See the tracks on an album Tap a cover or . To Do this Play any track Tap the track. Drag up or down to scroll through the tracks. Return to the cover Tap the title bar. Or tap again. Play or pause the current song Tap or . Chapter 3 Music and Video 29 Viewing All Tracks on an Album See all the tracks on the album that contains the current song m From the Now Playing screen tap . Tap a track to play it. Tap the album cover thumbnail to return to the Now Playing screen. In track list view, you can assign ratings to songs. You can use ratings to create smart playlists in iTunes that dynamically update to show, for example, your highest rated songs. Rate a song m Drag your finger across the ratings bar to give the song zero to five stars. Making Playlists Directly on iPod touch Make an on-the-go playlist 1 Tap Playlists and tap On-The-Go. 2 Browse for songs using the buttons at the bottom of the screen. Tap any song or video to add it to the playlist. Tap Add All Songs at the top of any list of songs to add all the songs in the list. 3 When you finish, tap Done. When you make an on-the-go playlist and then sync iPod touch to your computer, the playlist is saved in your iTunes library, then deleted from iPod touch. The first is saved as “On-The-Go 1,” the second as “On-The-Go 2,” and so on. To get a playlist back on iPod touch, select iPod touch in the iTunes source list, click the Music tab, and set the playlist to sync. Edit an on-the-go playlist m Tap Playlists, tap On-The-Go, tap Edit, then do one of the following:  To move a song higher or lower in the list, drag next to the song.  To delete a song from the playlist, tap next to the song, then tap Delete. Deleting a song from the on-the-go playlist doesn’t delete it from iPod touch.  To clear the entire playlist, tap Clear Playlist.  To add more songs, tap . Track list view Ratings bar Back to Now Playing screen Album tracks30 Chapter 3 Music and Video Watching Videos With iPod touch, you can view video content such as movies, music videos, and video podcasts. Videos play in widescreen to take full advantage of the display. If a video contains chapters, you can skip to the next or previous chapter, or bring up a list and start playing at any chapter that you choose. If a video provides alternate language features, you can choose an audio language or display subtitles. Playing Videos on iPod touch Play a video m Tap Videos and tap the video. Display playback controls m Tap the screen to show the controls. Tap again to hide them. Say It Right by Nelly Furtado is available on iTunes in select countries. Restart/Rewind Video controls Playhead Scale Play/Pause Fast-forward Volume Scrubber bar To Do this Play or pause a video Tap or . Raise or lower the volume Drag the volume slider. Start a video over Drag the playhead on the scrubber bar all the way to the left, or tap if the video doesn’t contain chapters. Skip to the previous or next chapter (when available) Tap to skip to the previous chapter. Tap to skip to the next chapter. Start playing at a specific chapter Tap , then choose the chapter from the list. Rewind or fast-forward Touch and hold or . Skip to any point in a video Drag the playhead along the scrubber bar. Stop watching a video before it finishes playing Tap Done. Or press the Home button.Chapter 3 Music and Video 31 Watching Rented Movies You can rent movies from the iTunes Store and watch them on iPod touch. You use iTunes to rent the movies and transfer them to iPod touch. (Rented movies are available only in some regions. iTunes version 7.6 or later is required.) Rented movies are playable only for a limited time. The remaining time in which you must finish watching a rented movie appears near its title. Movies are automatically deleted when they expire. Check the iTunes Store for the expiration times before renting a movie. Transfer rented movies to iPod touch m Connect iPod touch to your computer. Then select iPod touch in the iTunes window (below Devices, on the left), click Movies and select the rented movies you want to transfer. Your computer must be connected to the internet. Note: Once a rented movie is transferred to iPod touch, you can’t transfer it back to your computer to watch it there. View a rented movie m Tap Videos and select a movie. Scale a video to fill the screen or fit to the screen Tap to make the video fill the screen. Tap to make it fit the screen. You can also double-tap the video to toggle between fitting and filling the screen. When you scale a video to fill the screen, the sides or top may be cropped from view. When you scale it to fit the screen, you may see black bars above and below or on the sides of the video. Select an alternate audio language (when available) Tap , then choose a language from the Audio list. Show or hide subtitles (when available) Tap , then choose a language, or Off, from the Subtitles list. Play the sound from a music video or video podcast without showing the video Browse for the music video or podcast through Music lists. To play the music and video for a music video or podcast, browse for it through the Videos list. To Do this32 Chapter 3 Music and Video Watching Videos on a TV Connected to iPod touch You can connect iPod touch to your TV and watch your videos on the larger screen. Use the Apple Component AV Cable, Apple Composite AV Cable, or other iPod touch compatible cable. You can also use these cables with the Apple Universal Dock, available separately, to connect iPod touch to your TV. (The Apple Universal Dock includes a remote, which allows you to control playback from a distance.) Apple cables and docks are available for purchase at www.apple.com/ipodstore. Video Settings Video settings let you set where to resume playing videos that you previously started, turn closed captioning on or off, turn widescreen on or off, and set the TV signal to NTSC or PAL. See page 80. Set Video settings m Choose Settings > Video. Deleting Videos from iPod touch You can delete videos directly from iPod touch to save space. Delete a video m In the Videos list, swipe left or right over the video, then tap Delete. When you delete a video (not including rented movies) from iPod touch, it isn’t deleted from your iTunes library and you can sync the video back to iPod touch later. If you don’t want to sync the video back to iPod touch, set iTunes to not sync the video (see page 6). If you delete a rented movie from iPod touch, it is deleted permanently and can’t be transferred back to your computer. Setting a Sleep Timer You can set iPod touch to stop playing music or videos after a period of time. m From the Home screen choose Clock > Timer, then flick to set the number of hours and minutes. Tap When Timer Ends and choose Sleep iPod, tap Set, then tap Start to start the timer. When the timer ends, iPod touch stops playing music or video, closes any other open application, and then locks itself. Chapter 3 Music and Video 33 Changing the Buttons on the Music Screen You can replace the Playlists, Artist, Songs, or Albums buttons at the bottom of the screen with ones you use more frequently. For example, if you listen to podcasts a lot and don’t browse by album, you can replace the Albums button with Podcasts. m Tap More and tap Edit, then drag a button to the bottom of the screen, over the button you want to replace. You can drag the buttons at the bottom of the screen left or right to rearrange them. When you finish, tap Done. Tap More at any time to access the buttons you replaced.4 34 4 Photos Tap Photos to view your photos, use a photo as wallpaper, and play slideshows. iPod touch lets you sync photos from your computer so you can share them with your family, friends, and associates on the high-resolution display. Syncing Photos from Your Computer If you’ve set up photo syncing, iTunes automatically copies or updates your photo library (or selected albums) from your computer to iPod touch whenever you connect iPod touch to your computer. iTunes can sync your photos from the following applications:  On a Mac: iPhoto 4.0.3 or later  On a PC: Adobe Photoshop Album 2.0 or later or Adobe Photoshop Elements 3.0 or later For information about syncing iPod touch with photos and other information on your computer, see “Getting Music, Videos, and Other Content onto iPod touch” on page 5.Chapter 4 Photos 35 Viewing Photos Photos synced from your computer can be viewed in Photos. View photos m Tap Photo Library to see all your photos, or tap an album to see just those photos. See a photo at full screen m Tap the thumbnail of a photo to see it at full screen. Tap the full screen photo to hide the controls. Tap the photo again to show the controls. See the next or previous photo m Flick left or right. Or tap the screen to show the controls, then tap or .36 Chapter 4 Photos Changing the Size or Orientation See a photo in landscape orientation m Rotate iPod touch sideways. The photo automatically reorients and, if it’s in landscape format, expands to fit the screen. Zoom in on part of a photo m Double-tap the part you want to zoom in on. Double-tap again to zoom out. Zoom in or out m Pinch to zoom in or out. Pan around a photo m Drag the photo.Chapter 4 Photos 37 Viewing Slideshows View photos in a slideshow m Choose an album and tap a photo, then tap . If you don’t see , tap the photo to show the controls. Stop a slideshow m Tap the screen. Set slideshow settings 1 From the Home screen choose Settings > Photos. 2 To set:  The length of time each slide is shown, tap Play Each Slide For and choose a time.  Transition effects when moving from photo to photo, tap Transition and choose a transition type.  Whether slideshows repeat, turn Repeat on or off.  Whether photos are shown in random order, turn Shuffle on or off. Play music during a slideshow m From the Home screen choose Music, and play a song. Then choose Photos from the Home screen and start a slideshow. Using a Photo as Wallpaper You see a wallpaper background picture as you unlock iPod touch. Set a photo as wallpaper 1 Choose any photo. 2 Drag to pan, or pinch to zoom in or out, until the photo looks the way you want. 3 Tap the photo to display the controls, then tap and tap Set Wallpaper. You can also choose from several wallpaper pictures included with iPod touch by choosing Settings > General > Wallpaper > Wallpaper from the Home screen. Emailing a Photo Email a photo m Choose any photo and tap , then tap Email Photo. iPod touch must be set up for email (see “Setting Up Email Accounts” on page 53).38 Chapter 4 Photos Sending a Photo to a Web Gallery If you have a .Mac account, you can send photos directly from iPod touch to a Web Gallery created with iPhoto ‘08. You can also send photos to someone else’s .Mac Web Gallery if that person has enabled email contributions. To send photos to a Web Gallery, you need to do the following:  Set up your .Mac mail account on iPod touch  Publish an iPhoto ‘08 album to a .Mac Web Gallery  Select “Allow photo uploading by email” in the Publish Settings pane of iPhoto ‘08 For more information about creating a Web Gallery in iPhoto ‘08, open iPhoto ‘08, choose Help, and search for Web Gallery. Send a photo to your web gallery Choose any photo and tap , then tap Send to Web Gallery. Assigning a Photo to a Contact You can assign a photo to a contact. Assign a photo to a contact 1 Choose any photo on iPod touch and tap . 2 Tap Assign to Contact and choose a contact. 3 Drag the photo to pan, or pinch the photo to zoom in or out, until it looks the way you want. 4 Tap Set Photo. You can also assign a photo to a contact in Contacts by tapping edit and then tapping the picture icon.5 39 5 iTunes Wi-Fi Music Store Tap iTunes to purchase songs and albums from the iTunes Wi-Fi Music Store. You can search for, browse, preview, purchase, and download songs and albums from the iTunes Wi-Fi Music Store directly to iPod touch. Your purchased content is automatically copied to your iTunes library the next time you sync iPod touch with your computer. To use the iTunes Wi-Fi Music Store, iPod touch must join a Wi-Fi network that is connected to the Internet. For information about joining a Wi-Fi network, see page 21. You’ll also need an iTunes Store account to purchase songs over Wi-Fi (available in some countries). If you don’t already have an iTunes Store account, open iTunes and choose Store > Account to set one up. Browsing and Searching You can browse featured selections, top-ten categories, or search the iTunes Wi-Fi Music Store music catalog for the songs and albums you’re looking for. Use the featured selections to see new releases and iTunes Wi-Fi Music Store recommendations. Top Tens lets you see the most popular songs and albums in each of several categories. If you’re looking for a specific song, album, or artist, use Search.40 Chapter 5 iTunes Wi-Fi Music Store Browse featured songs and albums m Tap Featured and select a category at the top of the screen. Browse top ten songs and albums m Tap Top Tens, then choose a category and tap Top Songs or Top Albums.Chapter 5 iTunes Wi-Fi Music Store 41 Search for songs and albums m Tap Search, tap the search field and enter one or more words, then tap Search. See the songs on an album m Tap the album. See the album a song is on m Double-tab the song. Browsing Starbucks Selections If you’re in a select Starbucks location (available in the U.S. only), the Starbucks icon appears at the bottom of the screen next to Featured. Tap the Starbucks icon to find out what song is playing in the café and browse featured Starbucks Collections. For a list of select Starbucks locations, go to: www.apple.com/itunes/starbucks42 Chapter 5 iTunes Wi-Fi Music Store Find out what song is playing m Tap Starbucks. The currently playing song appears at the top of the screen. Tap the song to see the album the song is on and the other songs on the album. View Recently Played and other Starbucks playlists m Tap Starbucks, then choose Recently Played or one of the Starbucks playlists. Purchasing Songs and Albums When you find a song or album you like in the the iTunes Wi-Fi Music Store, you can purchase and download it to iPod touch. You can preview a song before you purchase it to make sure it’s a song you want. In select Starbucks locations (available in the U.S. only), you can also preview and purchase the currently playing and other songs from featured Starbucks Collections. Preview a song m Tap the song. Purchase and download a song or album 1 Tap the price, then tap Buy Now. Note: To purchase songs on iPod touch, you must have been signed in to your iTunes Store account in iTunes the last time you synced iPod touch. Chapter 5 iTunes Wi-Fi Music Store 43 2 Enter your password and tap OK. Your purchase is charged to your iTunes Store account. For additional purchases made within the next fifteen minutes, you don’t have to enter your password again. An alert appears if you’ve previously purchased one or more songs from an album. Tap Buy if you want to purchase the entire album including the songs you’ve already purchased, or tap Cancel if you want to purchase the remaining songs individually. Note: Some albums include bonus content, which is downloaded to your iTunes library on your computer. Not all bonus content is downloaded directly to iPod touch. See the status of downloading songs and albums m Tap Downloads. To pause a download, tap . If you need to turn off iPod touch or leave the area of your Wi-Fi connection, don’t worry about interrupting the download. iPod touch starts the download again the next time iPod touch joins a Wi-Fi network with an Internet connection. Or if you open iTunes on your computer, iTunes completes the download to your iTunes library. Purchased songs are added to a Purchased playlist on iPod touch. If you delete the Purchased playlist, iTunes creates a new one when you buy an item from the iTunes Wi-Fi Music Store. Syncing Purchased Content iTunes automatically syncs songs and albums you’ve purchased on iPod touch to your iTunes library when you connect iPod touch to your computer. This lets you listen to the purchases on your computer and provides a backup if you delete purchases from iPod touch. The songs are synced to the “Purchased on ” playlist. iTunes creates the playlist if it doesn’t exist. iTunes also copies your purchases to the Purchased playlist that iTunes uses for purchases you make on your computer, if that playlist exists and is set to sync with iPod touch.44 Chapter 5 iTunes Wi-Fi Music Store Verifying purchases You can use iTunes to verify that all the music, videos, and other items you bought from the the iTunes Wi-Fi Music Store are in your iTunes library. You might want to do this if a download was interrupted. Verify your purchases 1 Make sure your computer is connected to the Internet. 2 In iTunes, choose Store > Check for Purchases. 3 Enter your iTunes Store account ID and password, then click Check. Purchases not yet on your computer will be downloaded. The Purchased playlist displays all your purchases. However, because you can add or remove items in this list, it might not be accurate. To see all your purchases, make sure you’re signed in to your account, choose Store > View My Account, and click Purchase History. Changing Your iTunes Store Account Information iPod touch gets your iTunes Store account information from iTunes, including whether you get iTunes Plus music (when available). You can view and change your iTunes Store account information using iTunes. View and change your iTunes Store account information m In iTunes, choose Store > View My Account. You must be signed in to your iTunes Store account. If “View My Account” doesn’t appear in the Store menu, choose Store > Sign in. Purchase music from another iTunes Store account m Sign in to that account when you connect to iTunes Wi-Fi Music Store.6 45 6 Applications Safari Surfing the Web Safari lets you see webpages just as they were designed to be seen in computer-based browsers. A simple double-tap lets you zoom in; rotate iPod touch sideways for a wider view. Search using Google or Yahoo!—both are built in. To use Safari, iPod touch must join a Wi-Fi network that is connected to the Internet. For information about joining a Wi-Fi network, see page 21. Opening and Navigating Webpages Open a webpage m Tap the address field at the top of the screen, type the web address—apple.com or www.google.com, for example—and tap Go. If you don’t see the address field, tap the status bar at the top of the screen. As you type, any web address in your bookmarks or history list that contains those letters appears below. Tap a web address to go to its webpage. Erase all the text in the address field m Tap the address field, then tap . Follow a link on a webpage m Tap the link. Text links are typically underlined in blue. Many images are also links. 46 Chapter 6 Applications If a link leads to a sound or movie file supported by iPod touch, Safari plays the sound or movie. For supported file types, see page 88. Zooming In to See a Page More Easily View a webpage in landscape orientation m Rotate iPod touch sideways. Safari automatically reorients and expands the page. To Do this See a link’s destination address Touch and hold the link. The address pops up next to your finger. You can touch and hold an image to see if it has a link. Stop a page from loading if you change your mind Tap . Reload a webpage Tap . Return to the previous or next webpage Tap or at the bottom of the screen. Return to any of the last several webpages you’ve visited Tap and tap History. To clear the history list, tap Clear. Send a webpage address over email Tap and tap Mail Link to this Page. You must have an email account set up on iPod touch (see page 53).Chapter 6 Applications 47 Resize any column to fit the screen m Double-tap the column. The column expands so you can read it more easily. Double-tap again to zoom out. Zoom in on part of a webpage m Double-tap the part of the page you want to zoom in on. Double-tap again to zoom out. Zoom in or out manually m Pinch to zoom in or out. Scroll around the page m Drag up, down, or sideways. When scrolling, you can touch and drag anywhere on the page without activating any links. If you tap a link, you follow the link, but if you drag a link, the page scrolls. Scroll within a frame on a webpage Use two fingers to scroll within a frame on a webpage. Use one finger to scroll the entire webpage. Jump to the top of a webpage Tap the status bar at the top of the iPod touch screen. Searching the Web By default, Safari searches using Google. You can set it to search using Yahoo!, instead. Search for anything on the web 1 Tap to go to the Google search field. 2 Type a word or phrase that describes what you’re looking for, then tap Google. 3 Tap a link in the list of search results to open a webpage. Set Safari to search using Yahoo! m From the Home screen choose Settings > Safari > Search Engine, then choose Yahoo!.48 Chapter 6 Applications Opening Multiple Pages at Once You can have more than one webpage open at a time. Some links automatically open a new page instead of replacing the current one. The number inside the pages icon at the bottom of the screen shows how many pages are open. If there’s no number, just one page is open. For example: = one page is open = three pages are open Open a new page m Tap and tap New Page. See all open pages and go to another page that’s open m Tap and flick left or right. When you get to the page you want, tap it. Close a page m Tap and tap . You can’t close a page if it’s the only one that’s open. Typing in Text Fields Some webpages have forms or text fields you can enter information in. Bring up the keyboard m Tap inside a text field. Move to other text fields on the page m Tap another text field. Or tap the Next or Previous button.Chapter 6 Applications 49 Submit the form m Once you finish filling out the text fields on the page, tap Go or Search. Most pages also have a link you can tap to submit the form. Dismiss the keyboard without submitting the form m Tap Done. Adding Safari Web Clips to the Home Screen You can add Web Clips for your favorite webpages to the Home screen for fast access. Web Clips appear as icons, which you can arrange however you want on the Home screen. See “Customizing the Home Screen Layout” on page 13. Add a Web Clip to the Home screen m Open the page and tap . Then tap “Add to Home Screen.” Web Clips remember the displayed portion—zoom level and location—of webpages. When you open a Web Clip, Safari automatically zooms and scrolls to that portion of the webpage again. The displayed portion is also used to create the icon for the Web Clip on the Home screen. Before you add a Web Clip, you can edit its name. If the name is too long (more than about 10 characters), it may appear abbreviated on the Home screen. Delete a Web Clip from the Home screen 1 Touch and hold any Home screen icon until the icons begin to wiggle. 2 Tap the “x” in the corner of the Web Clip you want to delete. 3 Tap Delete, then press the Home button to save your arrangement. Using Bookmarks You can bookmark webpages so that you can quickly return to them at any time without having to type the address. Bookmark a webpage m Open the page and tap . Then tap Add Bookmark. Before you save a bookmark you can edit its title or choose where to save it. By default, the bookmark is saved in the top-level Bookmarks folder. Tap Bookmarks to choose another folder. Open a bookmarked webpage m Tap , then choose a bookmark or tap a folder to see the bookmarks inside.50 Chapter 6 Applications Edit a bookmark or bookmark folder m Tap , choose the folder that has the bookmark or folder you want to edit, then tap Edit. Then do one of the following:  To make a new folder, tap New Folder.  To delete a bookmark or folder, tap next to the bookmark or folder, then tap Delete.  To reposition a bookmark or folder, drag next to the item you want to move.  To edit the name or address of a bookmark or folder, or to put it in a different folder, tap the bookmark or folder. When you finish, tap Done. Syncing Bookmarks If you use Safari on a Mac, or Safari or Microsoft Internet Explorer on a PC, you can sync bookmarks on iPod touch with bookmarks on your computer. Sync bookmarks between iPod touch and your computer m Connect iPod touch to your computer. If bookmarks are set to be synced (see page 9), the sync begins. Safari Settings From the Home screen choose Settings > Safari to adjust security and other settings. See page 83. Calendar Adding Calendar Events to iPod touch If you’ve set iTunes to sync calendars, you can enter appointments and events on your computer and sync them with iPod touch. You can also enter appointments and events directly on iPod touch. Entering Calendar Events on Your Computer You can enter appointments and events in iCal and Microsoft Entourage on a Mac, or in Microsoft Outlook 2003 or 2007 on a PC. Syncing Calendars Sync calendars between iPod touch and your computer Connect iPod touch to your computer. If iPod touch is set to sync calendars automatically (see page 6), the update begins.Chapter 6 Applications 51 Adding and Editing Calendar Events Directly on iPod touch Add an event m Tap and enter event information. Then tap Done. You can enter any of the following:  Title  Location  Starting and ending times (or turn on All-day if it’s an all-day event)  Repeat times—none, or every day, week, two weeks, month, or year  Alert time—from five minutes to two days before the event If you set an alert time, iPod touch gives you the option to set a second alert time, in case you miss the first one.  Notes Set iPod touch to make a sound when you get a calendar alert m In Settings, choose General > Sound Effects and select whether you want sound effects to play over the internal speaker, through the headphones, or both. Select Off to turn sound effects off. If Sound Effects is off, iPod touch displays a message instead of making a sound when you get a calendar alert. Edit an event m Tap the event and tap Edit. Delete an event Tap the event, tap Edit, then scroll down and tap Delete Event. Viewing Your Calendar View your calendar m Tap Calendar. Switch views m Tap List, Day, or Month.  List view: All your appointments and events appear in an easy-to-scan list. Scroll up or down to see previous or upcoming days.  Day view: Scroll up or down to see hours earlier or later in the day. Tap or to see the previous or next day.52 Chapter 6 Applications  Month view: Days with events show a dot below the date. Tap a day to see its events in a list below the calendar. Tap or to see the previous or next month. See today’s events m Tap Today. See the details of an event m Tap the event. Set iPod touch to adjust event times for a selected time zone m From the Home screen tap Settings > General > Date & Time, then turn Time Zone Support on. Then tap Time Zone and search for a major city in the time zone you want. When Time Zone Support is on, Calendar displays event dates and times in the time zone set for your calendars. When Time Zone Support is off, Calendar displays events in the time zone of your current location. Days with dots have scheduled events Month view Switch views Events for selected day Go to todayChapter 6 Applications 53 Mail Mail is a rich HTML email client that retrieves your email in the background while you do other things on iPod touch. iPod touch works with the most popular email systems—including Yahoo! Mail, Google email, AOL, and .Mac Mail—as well as most industry-standard POP3 and IMAP email systems. Mail lets you send and receive photos and graphics, which are displayed in your message along with the text. You can also get PDFs and other attachments and view them on iPod touch. Setting Up Email Accounts You must have an email address—which looks like “yourname@example.com”—to use iPod touch for email. If you have Internet access, you most likely got an email address from your Internet service provider. If you chose automatic syncing during setup, your existing email accounts should be already set up and ready to go. Otherwise, you can set iTunes to sync your email accounts, or configure email accounts directly on iPod touch. Syncing Email Accounts to iPod touch You use iTunes to sync your email accounts to iPod touch. iTunes supports Mail and Microsoft Entourage on a Mac, and Microsoft Outlook 2003 or 2007 and Outlook Express on a PC. See “Getting Music, Videos, and Other Content onto iPod touch” on page 5. Note: Syncing an email account to iPod touch copies the email account setup, not the messages themselves. Whether the messages in your inbox appear on both iPod touch and your computer depends on the type of email account you have and how it’s configured. If You Don’t Have an Email Account Email accounts are available from most Internet service providers. If you use a Mac, you can get an email address, along with other services, at www.mac.com. Fees may apply. Free accounts are also available online:  www.mail.yahoo.com  www.google.com/mail  www.aol.com54 Chapter 6 Applications Setting Up an Email Account on iPod touch You can set up and make changes to an email account directly on iPod touch. Your email service provider can provide the account settings you need to enter. Changes you make on iPod touch to an email account synced from your computer are not copied to your computer. To use the online Mail Setup Assistant, go to: www.apple.com/support/ipodtouch/mailhelper Enter account settings directly on iPod touch 1 If this is the first account you’re setting up on iPod touch, tap Mail. Otherwise, from the Home screen choose Settings > Mail > Accounts > Add Account. 2 Choose your email account type: Y! Mail (for Yahoo!), Google email, .Mac, AOL, or Other. 3 Enter your account information: If you’re setting up a Yahoo!, Google email, .Mac, or AOL account, enter your name, email address, and password. After that, you’re done. Otherwise, click Other, select a server type—IMAP, POP, or Exchange—and enter your account information:  Your email address  The email server type (IMAP, POP, or Exchange)  The Internet host name for your incoming mail server (which may look like “mail.example.com”)  The Internet host name for your outgoing mail server (which may look like “smtp.example.com”)  Your user name and password for incoming and outgoing servers (you may not need to enter a user name and password for an outgoing server) Note: Exchange email accounts must be configured for IMAP in order to work with iPod touch. Contact your IT organization for more information. Sending Email You can send an email message to anyone who has an email address. You can send the message to one person or to a group of people. Compose and send a message 1 Tap . 2 Type one or more names or email addresses in the To or Cc (carbon copy) fields, or tap and choose a contact to add the contact’s email address. As you type an email address, comparable email addresses from your contacts list appear below. Tap one to add it.Chapter 6 Applications 55 3 Type a subject, then type a message. 4 Tap Send. Send a photo in a message m From the Home screen choose Photos, then choose a photo. Then tap and tap Email Photo. If you have more than one email account on iPod touch, the photo is sent using the default account (see page 83). Save a message as a draft so you can work on it later m Start composing the message and tap Cancel. Then tap Save. You can find the message in the Drafts mailbox, add to it or change it, and then send it. Reply to a message m Open a message and tap . Tap Reply to reply to just the person who sent the message. Tap Reply All to reply to the sender and the other recipients. Then add a message of your own if you like, and tap Send. When you reply to a message, files or images attached to the initial message aren’t sent back. Forward a message m Open a message and tap , then tap Forward. Add one or more email addresses and a message of your own if you like, then tap Send. When you forward a message, you can include the files or images attached to the original message. Send a message to a recipient of a message you received m Open the message and tap the recipient’s name or email address, then tap Email. Checking and Reading Email The Mail button shows the total number of unread messages in all of your inboxes. You may have other unread messages in other mailboxes. Number of unread emails56 Chapter 6 Applications On each account screen, you can see the number of unread messages next to each mailbox. Tap a mailbox to see its messages. Unread messages have a blue dot next to them. Read a message m Tap a mailbox, then tap a message. Within a message, tap or to see the next or previous message. Delete a message m Open the message and tap . You can also delete a message directly from the mailbox message list by swiping left or right over the message title and then tapping Delete. Or you can tap Edit and tap next to a message. Number of unread messages Tap to see all your email accounts Unread messages To show the Delete button, swipe left or right over the message.Chapter 6 Applications 57 Check for new messages m Choose a mailbox, or tap at any time. Open an attached file You can view or read some types of files and images attached to messages you receive. For example, if someone sends you a PDF, Microsoft Word, or Microsoft Excel document, you canread it on iPod touch. m Tap the attachment. It downloads to iPod touch and then opens. You can view attachments in both portrait and landscape orientation. If the format of an attached file isn’t supported by iPod touch, you can see the name of the file but you can’t open it. iPod touch supports the following email attachment file formats:  .doc, .docx, .htm, .html, .pdf, .txt, .xls, .xlsx See all the recipients of a message m Open the message and tap Details. Tap a name or email address to see the recipient’s contact information. Then tap an email address to email the person. Tap Hide to hide the recipients. Add an email recipient to your contacts list m Tap the message and, if necessary, tap Details to see the recipients. Then tap a name or email address and tap Create New Contact or “Add to Existing Contact.” Mark a message as unread m Open the message and tap “Mark as Unread.” A blue dot appears next to the message in the mailbox list until you open it again. Move a message to another mailbox m Open the message and tap , then choose a mailbox. Tap attachment to download58 Chapter 6 Applications Zoom in to a part of a message m Double-tap the part you want to zoom in on. Double-tap again to zoom out. Resize any column of text to fit the screen m Double-tap the text. Resize a message manually m Pinch to zoom in or out. Follow a link m Tap the link. Text links are typically underlined in blue. Many images also have links. A link can take you to a webpage, open a map, or open a new preaddressed email message. Web and map links open Safari or Maps on iPod touch. To return to your email, press the Home button and tap Mail. Mail Settings From the Home screen choose Settings > Mail to set up and customize your email accounts for iPod touch. See page 81. Contacts With Contacts, it’s easy to have all your contact information with you. Syncing Contact Information from Your Computer If you’ve set iTunes to sync contacts, iTunes automatically keeps your contacts up-todate—whether you make changes on your computer or on iPod touch. You can sync contacts with applications such as:  On a Mac: Mac OS X Address Book, Microsoft Entourage, and Yahoo! Address Book  On a PC: Yahoo! Address Book, Windows Address Book (Outlook Express), or Microsoft Outlook For information about syncing iPod touch with your contacts, see “Getting Music, Videos, and Other Content onto iPod touch” on page 5. Viewing a Contact m Tap Contacts, then tap a contact. To view a specific group, tap the Group button.Chapter 6 Applications 59 Setting the Sort and Display Order Use Contacts settings to set whether your contacts are sorted by first or last name, and to set the order in which the names are displayed. m Tap Settings > Contacts, then tap Sort Order or Display Order and select “First, Last” or “Last, First.” Adding and Editing Contacts Directly on iPod touch You can enter new contacts on iPod touch, edit existing contacts, and delete contacts. Add a contact to iPod touch m Choose Contacts and tap , then enter the contact information. Edit a contact’s phone number, address, and other information m Tap Contacts and choose a contact, then tap Edit.  To add an item—such as a web address or mobile phone number, tap next to the item.  To delete an item, tap next to it.  To delete the contact from your contacts list, scroll down and tap Delete Contact. Enter a pause in a number m Tap , then tap Pause. Pauses are sometimes required by phone systems—before an extension or password, for example. Each pause lasts 2 seconds. You may need to enter more than one. Assign a photo to a contact or change a contact’s photo 1 Tap Contacts and choose a contact. 2 Tap Edit and tap Add Photo, or tap the existing photo. 3 Choose a photo. 60 Chapter 6 Applications 4 Move and scale the photo the way you want it. Drag the photo up, down, or sideways. Pinch or double-tap to zoom in or out. 5 Tap Set Photo. Delete a contact 1 Tap Contacts and choose a contact. 2 Tap Edit. 3 Scroll to the bottom of the contact information and tap Delete. YouTube Finding and Viewing Videos YouTube features short videos submitted by people from around the world (not available in all languages, may not be available in all locations). To use YouTube, iPod touch must join a Wi-Fi network that is connected to the Internet. For information about joining a Wi-Fi network, see page 21. Browse videos m Tap Featured, Most Viewed, or Bookmarks. Or tap More to browse by Most Recent, Top Rated, or History.  Featured: Videos reviewed and featured by YouTube staff.  Most Viewed: Videos most seen by YouTube viewers. Tap All for all-time most viewed videos, or Today or This Week for most viewed videos of the day or week.  Bookmarks: Videos you’ve bookmarked.  Most Recent: Videos most recently submitted to YouTube.  Top Rated: Videos most highly rated by YouTube viewers. To rate videos, go to www.youtube.com.  History: Videos you’ve viewed most recently. Search for a video 1 Tap Search, then tap the YouTube search field. 2 Type a word or phrase that describes what you’re looking for, then tap Search. YouTube shows results based on video titles, descriptions, tags, and user names. Chapter 6 Applications 61 Play a video m Tap the video. The video begins to download to iPod touch and a progress bar shows progress. When enough of the video has downloaded, it begins to play. You can also tap to start the video. Controlling Video Playback When a video starts playing, the controls disappear so they don’t obscure the video. m Tap the screen to show or hide the controls. To Do this Play or pause a video Tap or . Raise or lower the volume Drag the volume slider. Start a video over Tap . Skip to the next or previous video Tap twice to skip to the previous video. Tap to skip to the next video. Rewind or fast-forward Touch and hold or . Skip to any point in a video Drag the playhead along the scrubber bar. Stop watching a video before it finishes playing Tap Done. Or press the Home button. Toggle between scaling a video to fill the screen or fit the screen. Double-tap the video. You can also tap to make the video fill the screen, or tap to make it fit the screen. Bookmark a video Tap next to a video and tap Bookmark. Or start playing a video and tap . Tap Bookmarks to see your bookmarked videos. See details about a video and browse related videos Play the whole video, tap Done while a video is playing, or tap next to any video in a list. iPod touch shows the video’s rating, description, date added, and other information. You also see a list of related videos that you can tap to view. Next/Fast-forward Play/Pause Scale Download progress Playback controls Volume Previous/rewind Bookmark Playhead Scrubber bar62 Chapter 6 Applications Changing the Buttons at the Bottom of the Screen You can replace the Featured, Most Viewed, Bookmarks, and Search buttons at the bottom of the screen with ones you use more frequently. For example, if you often watch top rated videos but don’t watch many featured videos, you could replace the Featured button with Top Rated. m Tap More and tap Edit, then drag a button to the bottom of the screen, over the button you want to replace. You can drag the buttons at the bottom of the screen left or right to rearrange them. When you finish, tap Done. When you’re browsing for videos, tap More to access the buttons that aren’t visible. Add Your Own Videos to YouTube For information about adding your own videos to YouTube, go to www.youtube.com and tap Help.Chapter 6 Applications 63 Stocks Viewing Stock Quotes When you tap Stocks from the Home screen, the stock reader shows updated quotes for all your stocks. Quotes are updated every time you open Stocks while connected to the Internet. Quotes may be delayed by up to 20 minutes. Add a stock, index, or fund to the stock reader 1 Tap , then tap . 2 Enter a symbol, company name, index, or fund name, then tap Search. 3 Choose an item in the search list. Delete a stock m Tap and tap next to a stock, then tap Delete. Reorder stocks m Tap . Then drag next to a stock to a new place in the list. Switch between showing percentage change and change in monetary value m Tap the number showing the change. Tap it again to switch back. You can also tap and tap % or Numbers. Show a stock’s progress over a longer or shorter time period m Tap a stock symbol, then tap 1d, 1w, 1m, 3m, 6m, 1y, or 2y. The chart adjusts to show progress over one day, one week, one, three, or six months, or one or two years. See information about a stock at Yahoo.com m Tap . You can see news, information, websites related to the stock, and more.64 Chapter 6 Applications Maps Maps provides street maps, satellite photos, and hybrid views of locations in many of the world’s countries. You can get detailed driving directions and, in some areas, traffic information. Also in some areas, you can find your current approximate location, and use that location to get driving directions to or from another place.1 Finding and Viewing Locations Find a location and see a map m Tap the search field to bring up the keyboard, then type an address, intersection, general area, name of a landmark, bookmark name, name of someone in your contacts list, or zip code. Then tap Search. A pin marks the location on the map. Tap the pin to see the name or description of the location. Find your current approximate location on a map m Tap . A circle appears to show your current approximate location. Your approximate location is determined using information from some local Wi-Fi networks (if you have Wi-Fi turned on). The more accurate the available information, the smaller the circle on the map. This feature is not available in all areas. 1 Maps, directions, and location information depend on data collected and services provided by third parties. These data services are subject to change and may not be available in all geographic areas, resulting in maps, directions, or location information that may be unavailable, inaccurate, or incomplete. For more information, see www.apple.com/ipodtouch. In order to provide your location, data is collected in a form that does not personally identify you. If you do not want such data collected, don’t use the feature. Not using this feature will not impact the functionality of your iPod touch. WARNING: For important information about driving and navigating safely, see the Important Product Information Guide at www.apple.com/support/manuals/ipod. Tap to get information about the location, get directions, or add the location to your bookmarks or contacts listChapter 6 Applications 65 Use the dropped pin m Tap , then tap Drop Pin. A pin drops down on the map, which you can then drag to any location you choose. To quickly move the pin to the area currently displayed, tap , then tap Replace Pin. Zoom in to a part of a map m Pinch the map with two fingers. Or double-tap the part you want to zoom in on. Double-tap again to zoom in even closer. Zoom out m Pinch the map. Or tap the map with two fingers. Tap with two fingers again to zoom out further. Pan or scroll to another part of the map m Drag up, down, left, or right.66 Chapter 6 Applications See a satellite or hybrid view m Tap , then tap Satellite or Hybrid to see just a satellite view or a combined street map and satellite view. Tap Map to return to map view. See the location of someone’s address in your contacts list m Tap in the search field, then tap Contacts and choose a contact. To locate an address in this way, the contact must include at least one address. If the contact has more than one address, you must choose the one you want to locate. You can also find the location of an address by tapping the address directly in Contacts. Bookmark a location m Find a location, tap the pin that points to it, tap next to the name or description, then tap “Add to Bookmarks.” See a bookmarked location or recently viewed location m Tap in the search field, then tap Bookmarks or Recents. Add a location to your contacts list m Find a location, tap the pin that points to it, tap next to the name or description, then tap Create New Contact or “Add to Existing Contact.” Getting Directions Get directions 1 Tap Directions. 2 Enter starting and ending locations in the Start and End fields. By default, iPod touch starts with your current approximate location (when available). Tap in either field and choose a location in Bookmarks (including your current approximate location and the dropped pin, when available), Recents, or Contacts. For example, if a friend’s address is in your contacts list, you can tap Contacts and tap your friend’s name instead of having to type the address. To reverse the directions, tap .Chapter 6 Applications 67 3 Tap Route, then do one of the following:  To view directions one step at a time, tap Start, then tap to see the next leg of the trip. Tap to go back.  To view all the directions in a list, tap , then tap List. Tap any item in the list to see a map showing that leg of the trip. The approximate driving time appears at the top of the screen. If traffic data is available, the driving time is adjusted accordingly. You can also get directions by finding a location on the map, tapping the pin that points to it, tapping next to the name, then tapping Directions To Here or Directions From Here. Show or hide traffic conditions When available, you can show highway traffic conditions on the map. m Tap , then tap Show Traffic or Hide Traffic. Highways are color-coded according to the flow of traffic: If you tap Show Traffic and don’t see color-coded highways, you may need to zoom out to a level where you can see major roads, or traffic conditions may not be available for that area. Switch start and end points, for reverse directions m Tap . If you don’t see , tap List, then tap Edit. See recently viewed directions m Tap in the search field, then tap Recents. Traffic Gray = No data currently available Red = less than 25 miles per hour Yellow = 25–50 miles per hour Green = more than 50 miles per hour68 Chapter 6 Applications Finding and Contacting Businesses Find businesses in an area 1 Find a location—for example, a city and state or country, or a street address—or scroll to a location on a map. 2 Type the kind of business in the text field and tap Search. Pins appear for matching locations. For example, if you locate your city and then type “movies” and tap Search, pins mark movie theatres in your city. Tap the pin that marks a business to see its name or description. Find businesses without finding the location first m Type things like:  restaurants san francisco ca  apple inc new york Contact a business or get directions m Tap the pin that marks a business, then tap next to the name. From there, you can do the following:  Depending on what information is stored for that business, you can tap an email address to email, or web address to visit a website.  For directions, tap Directions To Here or Directions From Here.  To add the business to your contacts list, scroll down and tap Create New Contact or “Add to Existing Contact.” See a list of the businesses found in the search From the Map screen, tap List. Tap a business to see its location on the map. Or tap next to a business to see its information. Get directions Visit website Call Tap to show contact infoChapter 6 Applications 69 Weather Viewing Weather Summaries Tap Weather from the Home screen to see the current temperature and a six-day forecast for a city of your choice. You can store multiple cities, for quick access. If the weather board is light blue, it’s daytime in that city—between 6:00 a.m. and 6:00 p.m. If the board is dark purple, it’s nighttime—between 6:00 p.m. and 6:00 a.m. Switch to another city m Flick left or right. The number of dots below the weather board shows how many cities are stored. Reorder cities m Tap . Then drag next to a city to a new place in the list. Add a city 1 Tap , then tap . 2 Enter a city name or zip code, then tap Search. 3 Choose a city in the search list. Delete a city m Tap and tap next to a city, then tap Delete. Six-day forecast Current temperature Current conditions Today’s high and low Add and delete cities Number of cities stored Weather screen70 Chapter 6 Applications Set whether iPod touch shows the temperature in Fahrenheit or Celsius m Tap , then tap ºF or ºC. See information about a city at Yahoo.com m Tap . You can see a more detailed weather report, news and websites related to the city, and more. Clock Adding and Viewing Clocks for Locations Around the World You can add multiple clocks to show the time in major cities and time zones around the world. View clocks m Tap World Clock. If the clock face is white, it’s daytime in that city. If it’s black, it’s nighttime. If you have more than four clocks, scroll to see them all. Add a clock m Tap World Clock, then tap and type the name of a city. Cities matching what you’ve typed appear below. Tap a city to add a clock for that city. If you don’t see the city you’re looking for, try a major city in the same time zone. Delete a clock m Tap World Clock and tap Edit. Then tap next to a clock and tap Delete. Rearrange clocks m Tap World Clock and tap Edit. Then drag next to a clock to a new place in the list.Chapter 6 Applications 71 Setting Alarm Clocks You can set multiple alarms. Set each alarm to repeat on days you specify, or to sound only once. Set an alarm m Tap Alarm and tap , then adjust any of the following settings:  To set the alarm to repeat on certain days, tap Repeat and choose the days.  To choose the sound that’s played when the alarm goes off, tap Sound.  To set whether the alarm gives you the option to snooze, turn Snooze on or off. If Snooze is on and you tap Snooze when the alarm sounds, the alarm stops and then sounds again in ten minutes.  To give the alarm a description, tap Label. iPod touch displays the label when the alarm sounds. If at least one alarm is set and turned on, appears in the status bar at the top of the screen. Turn an alarm on or off m Tap Alarm and turn any alarm on or off. If an alarm is turned off, it won’t sound again unless you turn it back on. If an alarm is set to sound only once, it turns off automatically after it sounds. You can turn that alarm on again to reenable it. Change settings for an alarm m Tap Alarm and tap Edit, then tap next to the alarm you want to change. Delete an alarm m Tap Alarm and tap Edit, then tap next to the alarm and tap Delete. Using the Stopwatch Use the stopwatch to measure time m Tap Stopwatch. Tap Start to start the stopwatch. To record lap times, tap Lap after each lap. Tap Stop to pause the stopwatch, then tap Start to resume. Tap Reset to reset the stopwatch to zero. If you start the stopwatch and go to another iPod touch application, the stopwatch continues running in the background.72 Chapter 6 Applications Setting the Timer Set the timer m Tap Timer, then flick to set the number of hours and minutes. Tap When Timer Ends to choose the sound iPod touch makes when the timer ends. Tap Start to start the timer. Set a sleep timer m Set the timer, then tap When Timer Ends and choose Sleep iPod. When you set a sleep timer, iPod touch stops playing music or videos when the timer ends. If you start the timer and go to another iPod touch application, the timer continues running in the background. Calculator Using the Calculator m Add, subtract, multiply, and divide, as with a standard calculator. When you tap the add, subtract, multiply, or divide button, a white ring appears around the button to indicate the operation to be carried out. Using the Memory Functions m C: Tap to clear the displayed number. m M+: Tap to add the displayed number to the number in memory. If no number is in memory, tap to store the displayed number in memory. m M–: Tap to subtract the displayed number from the number in memory. m MR/MC: Tap once to replace the displayed number with the number in memory. Tap twice to clear the memory. If the MR/MC button has a white ring around it, there is a number stored in memory. If zero (“0”) is displayed, tap once to see the number stored in memory.Chapter 6 Applications 73 Notes Writing, Reading, and Emailing Notes Notes are listed by date added, with the most recent note at the top. You can see the first few words of each note in the list. Add a note m Tap , then type your note and tap Done. Read or edit a note m Tap the note. Tap anywhere on the note to bring up the keyboard and edit the note. Tap or to see the next or previous note. Delete a note m Tap the note, then tap . Email a note m Tap the note, then tap . To email a note, iPod touch must be set up for email (see “Setting Up Email Accounts” on page 53).7 74 7 Settings Tap Settings to adjust iPod touch settings. Settings allows you to customize iPod touch applications, set the date and time, configure Wi-Fi connections, and enter other preferences for iPod touch. Wi-Fi Wi-Fi settings determine when and how iPod touch joins a Wi-Fi network. Turn Wi-Fi on or off m Choose Wi-Fi and turn Wi-Fi on or off. Join a Wi-Fi network m Choose Wi-Fi, wait a moment as iPod touch detects networks in range, then select a network. If necessary, enter the password and tap Join. (Networks that require a password appear with a lock icon.) Once you’ve joined a Wi-Fi network manually, iPod touch automatically joins it whenever the network is in range. If more than one previously used network is in range, iPod touch joins the one last used. When iPod touch is joined to a Wi-Fi network, the Wi-Fi icon in the status bar at the top of the screen shows signal strength. The more bars you see, the stronger the signal. Set iPod touch to ask if you want to join a new network This option tells iPod touch to look for another network when you aren’t in range of a Wi-Fi network you’ve previously joined. iPod touch displays a list of all available Wi-Fi networks that you can choose from. (Networks that require a password appear with a lock icon.) m Choose Wi-Fi and turn “Ask to Join Networks” on or off. If you turn “Ask to Join Networks” off, you can still join new networks manually.Chapter 7 Settings 75 Forget a network, so iPod touch doesn’t join it automatically m Choose Wi-Fi and tap next to a network you’ve joined before. Then tap “Forget this Network.” Join a closed Wi-Fi network (an available Wi-Fi network that isn’t shown in the list of scanned networks) m Choose Wi-Fi > Other and enter the network name. If the network requires a password, tap Security, select the type of security the network uses, and then tap Other Network and enter the password. You must already know the network name, password, and security type to connect to a closed network. Some Wi-Fi networks may require you to enter or adjust additional settings, such as a client ID or static IP address. Ask the network administrator which settings to use. Adjust settings for joining a Wi-Fi network m Choose Wi-Fi, then tap next to the network. Brightness Screen brightness affects battery life. Dim the screen to extend the time before you need to recharge iPod touch. Or use Auto-Brightness, which is designed to conserve battery life. Adjust the screen brightness m Choose Brightness and drag the slider. Set whether iPod touch adjusts screen brightness automatically m Choose Brightness and turn Auto-Brightness on or off. If Auto-Brightness is on, iPod touch adjusts the screen brightness for current light conditions using the built-in ambient light sensor. General The General settings include date and time, security, and other settings that affect more than one application. This is also where you can find information about your iPod touch and reset iPod touch to its original state. About Choose General > About to get information about iPod touch, including:  number of songs  number of videos  number of photos  total storage capacity76 Chapter 7 Settings  storage available  software version  serial number  model number  Wi-Fi address  legal information Wallpaper You see a wallpaper background picture when you unlock iPod touch. You can select one of the images that came with iPod touch, or use a photo you’ve synced to iPod touch from your computer. Set wallpaper m Choose General > Wallpaper and choose a picture. Date and Time These settings apply to the time shown in the status bar at the top of the screen, world clocks, and your calendar. Set whether iPod touch shows 24-hour time or 12-hour time m Choose General > Date & Time and turn 24-Hour Time on or off. Set the time zone m Choose General > Date & Time > Time Zone and enter your location. Set the date and time 1 Choose General > Date & Time > Set Date & Time 2 Tap a button to select the date or time, then use the spinners to change the setting. Calendar Settings Turn on calendar time zone support m Choose General > Date & Time and turn Time Zone Support on. When Time Zone Support is on, Calendar displays event dates and times in the time zone set for your calendars. When Time Zone Support is off, Calendar displays events in the time zone of your current location. Set calendar time zone m Choose General > Date & Time > Time Zone and enter the time zone of your calendar. International Use the International settings to set the language for iPod touch, turn keyboards for different languages on and off, and set the date, time, and telephone number formats for your region.Chapter 7 Settings 77 Set the language for iPod touch m Choose General > International > Language, choose the language you want to use, and tap Done. Turn international keyboards on or off You can change the language for your keyboard on iPod touch, or make two or more keyboards available. m Choose General > International > Keyboards, and turn on the keyboards you want. If more than one keyboard is turned on, tap to switch keyboards when you’re typing. When you tap the symbol, the name of the newly active keyboard appears briefly. Set date, time, and telephone number formats m Choose General > International > Region Format, and choose your region. Auto-Lock Locking iPod touch turns off the display to save your battery and to prevent unintended operation of iPod touch. Set the amount of time before iPod touch locks m Choose General > Auto-Lock and choose a time. Passcode Lock By default, iPod touch doesn’t require you to enter a passcode to unlock it. Set a passcode m Choose General > Passcode Lock and enter a 4-digit passcode. iPod touch then requires you to enter the passcode to unlock it. Turn passcode lock off m Choose General > Passcode Lock and tap Turn Passcode Off, then enter your passcode. Change the passcode m Choose General > Passcode Lock and tap Change Passcode, enter the current passcode, then enter and reenter your new passcode. If you forget your passcode, you must restore the iPod touch software. See page 89. Set how long before your passcode is required m Choose General > Passcode Lock > Require Passcode, then select how long iPod touch can be locked before you need to enter a passcode to unlock it.78 Chapter 7 Settings Sound Effects iPod touch can play sound effects when you:  have an appointment  lock or unlock iPod touch  type on the keyboard Turn sound effects on or off m Choose General > Sound Effects and select whether you want sound effects to play over the internal speaker, through the headphones, or both. Select Off to turn sound effects off. Keyboard Turn auto-capitalization on or off By default, iPod touch automatically capitalizes the next word after you type sentenceending punctuation or a return character. m Choose General > Keyboard and turn Auto-Capitalization on or off. Set whether caps lock is enabled If caps lock is enabled and you double-tap the Shift key on the keyboard, all letters you type are uppercase. The Shift key turns blue when caps lock is on. m Choose General > Keyboard and turn Enable Caps Lock on or off. Turn “.” shortcut on or off The “.” shortcut lets you double-tap the space bar to enter a period followed by a space when you’re typing. It is on by default. m Choose General > Keyboard and turn “.” Shortcut on or off. Turn international keyboards on or off You can change the language for your keyboard on iPod touch, or make two or more keyboards available. m Choose General > Keyboards > International Keyboards and turn on the keyboards you want. If more than one keyboard is turned on, tap to switch keyboards when you’re typing. When you tap the symbol, the name of the newly active keyboard appears briefly. Resetting iPod touch Settings Reset all settings m Choose General > Reset and tap Reset All Settings. All your preferences and settings are reset. Data (such as your contacts and calendars) and media (such as your songs and videos) are not deleted.Chapter 7 Settings 79 Erase all content and settings m Choose General > Reset and tap “Erase All Content and Settings.” All your data and media are deleted. You must sync iPod touch with your computer to restore contacts, songs, videos, and other data and media. Reset the keyboard dictionary m Choose General > Reset and tap Reset Keyboard Dictionary. You add words to the keyboard dictionary by rejecting words iPod touch suggests as you type. Tap a word to reject the correction and add the word to the keyboard dictionary. Resetting the keyboard dictionary erases all words you’ve added. Reset network settings m Choose General > Reset and tap Reset Network Settings. When you reset network settings, your list of previously used networks is removed. Wi-Fi is turned off and then back on (disconnecting you from any network you’re on), and the “Ask to Join Networks” setting is turned on. Music The Music settings apply to songs, podcasts, and audiobooks. Set iTunes to play songs at the same sound level iTunes can automatically adjust the volume of songs, so they play at the same relative volume level. m In iTunes, choose iTunes > Preferences if you’re using a Mac, or Edit > Preferences if you’re using a PC, then click Playback and select Sound Check. You can set iPod touch to use the iTunes volume settings. Set iPod touch to use the iTunes volume settings (Sound Check) m Choose Music and turn Sound Check on. Set audiobook play speed You can set audiobooks to play faster than normal so you can hear them more quickly, or slower so you can hear them more clearly. m Choose Music > Audiobook Speed, then choose Slower, Normal, or Faster. Use the equalizer to change the sound on iPod touch to suit a particular sound or style m Choose Music > EQ and choose a setting. Set a volume limit for music and videos m Choose Music > Volume Limit and drag the slider to adjust the maximum volume. Tap Lock Volume Limit to assign a code to prevent the setting from being changed.80 Chapter 7 Settings Setting a volume limit only limits the volume of music (including podcasts and audiobooks) and videos (including rented movies), and only when headphones, earphones, or speakers are connected to the headphones port on iPod touch. Video Video settings apply to apply to video content (including rented movies). You can set where to resume playing videos that you previously started, turn closed captioning on or off, and set up iPod touch to play videos on your TV. Set where to resume playing m Choose Video > Start Playing, then select whether you want videos that you previously started watching to resume playing from the beginning or where you left off. Turn closed captioning on or off m Choose Video and turn Closed Captioning on or off. TV Out Settings Use these settings to set up how iPod touch plays videos on your TV. For more information about using iPod touch to play videos on your TV, see “Watching Videos on a TV Connected to iPod touch” on page 32. Turn widescreen on or off m Choose Video and turn Widescreen on or off. Set TV signal to NTSC or PAL m Choose Video > TV Signal and select NTSC or PAL. NTSC and PAL are TV broadcast standards. NTSC displays 480i and PAL displays 576i. Your TV might use either of these, depending on where it was sold. If you’re not sure which to use, check the documentation that came with your TV. Photos Photos settings let you specify how slideshows display your photos. Set the length of time each slide is shown m Choose Photos > Play Each Slide For and select the length of time. Set transition effect m Choose Photos > Transition and select the transition effect. WARNING: For important information about avoiding hearing loss, see the Important Product Information Guide at www.apple.com/support/manuals/ipod.Chapter 7 Settings 81 Set whether to repeat slideshows m Choose Photos and turn Repeat on or off. Set photos to appear randomly or in order m Choose Settings > Photos and turn Shuffle on or off. Mail Use Mail settings to customize your email account for iPod touch. Changes you make to accounts settings are not synced to your computer, allowing you to configure email to work with iPod touch without affecting email account settings on your computer. Account Settings The specific accounts settings that appear on iPod touch depend on the type of account you have—POP or IMAP. Note: Microsoft Outlook 2003 or 2007 email accounts must be configured for IMAP in order to work with iPod touch. Stop using an account m Choose Mail, choose an account, then turn Account off. If an account is off, iPod touch doesn’t display the account and doesn’t send or check email from that account, until you turn it back on. Adjust advanced settings m Choose Mail > Accounts, choose an account, then do one of the following:  To set whether drafts, sent messages, and deleted messages are stored on iPod touch or remotely on your email server (IMAP accounts only), tap Advanced and choose Drafts Mailbox, Sent Mailbox, or Deleted Mailbox. If you store messages on iPod touch, you can see them even when iPod touch isn’t connected to the Internet.  To set when deleted messages are removed permanently from iPod touch, tap Advanced and tap Remove, then choose a time: Never, or after one day, one week, or one month.  To adjust email server settings, tap Host Name, User Name, or Password under Incoming Mail Server or Outgoing Mail Server. Ask your network administrator or Internet service provider for the correct settings.  To adjust SSL and password settings, tap Advanced. Ask your network administrator or Internet service provider for the correct settings. Delete an email account from iPod touch m Choose Mail, tap an account, then scroll down and tap Delete Account. Deleting an email account from iPod touch doesn’t delete it from your computer.82 Chapter 7 Settings Settings for Email Messages iPod touch checks for and retrieves new email in your accounts whenever your open Mail. You can also set Mail to regularly check for email and download your messages even when you don’t have Mail open. Set whether iPod touch checks for new messages automatically m Choose Mail > Auto-Check, then tap Manual, “Every 15 minutes,” “Every 30 minutes,” or “Every hour.” If you have a Yahoo! email account, email is instantly transferred to iPod touch as it arrives at the Yahoo! server. Set the number of messages shown on iPod touch m Choose Mail > Show, then choose a setting. You can choose to see the most recent 25, 50, 75,100, or 200 messages. To download additional messages when you’re in Mail, scroll to the bottom of your inbox and tap “Download . . . more.” Set how many lines of each message are previewed in the message list m Choose Mail > Preview, then choose a setting. You can choose to see anywhere from zero to five lines of each message. That way, you can scan a list of messages in a mailbox and get an idea of what each message is about. Set a minimum font size for messages m Choose Mail > Minimum Font Size, then choose Small, Medium, Large, Extra Large, or Giant. Setting whether iPod touch shows To and Cc labels in message lists m Choose Mail, then turn Show To/Cc Label on or off. If Show To/Cc Label is on, or next to each message in a list indicates whether the message was sent directly to you or you were Cc’ed. Setting iPod touch to confirm that you want to delete a message m Choose Mail and turn Ask Before Deleting on or off. If Ask Before Deleting is on, to delete a message you must tap , then confirm by tapping Delete. To CcChapter 7 Settings 83 Settings for Sending Email Set whether iPod touch sends you a copy of every message you send m Choose Mail, then turn Always Bcc Myself on or off. Add a signature to your messages You can set iPod touch to add a signature—your favorite quote, or your name, title, and phone number, for example—that appears in every message you send. m Choose Mail > Signature, then type a signature. Set the default email account When you initiate sending a message from another iPod touch application, such as sending a photo from Photos or tapping a business’ email address in Maps, the message is sent from your default email account. m Choose Mail > Default Account, then choose an account. Safari General Settings You can use Google or Yahoo! to perform Internet searches. Select a search engine m Choose Safari > Search Engine and select the search engine you want to use. Security Settings By default, Safari is set to show some of the features of the web, like some movies, animation, and web applications. You may wish to turn off some of these features to help protect iPod touch from possible security risks on the Internet. Change security settings m Choose Safari, then do one of the following:  To enable or disable JavaScript, turn JavaScript on or off. JavaScript lets web programmers control elements of the page—for example, a page that uses JavaScript might display the current date and time or cause a linked page to appear in a new pop-up page.  To enable or disable plug-ins, turn Plug-ins on or off. Plug-ins allow Safari to play some types of audio and video files and to display Microsoft Word files and Microsoft Excel documents.  To block or allow pop-ups, turn Block Pop-ups on or off. Blocking pop-ups stops only pop-ups that appear when you close a page or open a page by typing its address. It doesn’t block pop-ups that open when you click a link.84 Chapter 7 Settings  To set whether Safari accepts cookies, tap Accept Cookies and choose Never, “From visited,” or Always. A cookie is a piece of information that a website puts on iPod touch so the website can remember you when you visit again. That way, webpages can be customized for you based on information you may have provided. Some pages won’t work correctly unless iPod touch is set to accept cookies.  To clear the history of webpages you’ve visited, tap Clear History.  To clear all cookies from Safari, tap Clear Cookies.  To clear the browser cache, tap Clear Cache. The browser cache stores the content of pages so the pages open faster the next time you visit them. If a page you open isn’t showing new content, clearing the cache may help. Developer Settings The Debug Console can help you resolve webpage errors. When turned on, the console appears automatically when a webpage error occurs. Turn the debug console on or off m Choose Safari > Developer, and turn Debug Console on or off. Contacts Use Contacts settings to determine the sort and display order of your contacts. Set the sort order m Choose Settings > Contacts > Sort Order, and select “First, Last” or “Last, First.” Set the display order m Choose Settings > Contacts > Display Order, and select “First, Last” or “Last, First.” Restoring or Transferring Your iPod touch Settings When you connect iPod touch to your computer, settings on iPod touch are automatically backed up to your computer. You can restore this information if you need to—if you get a new iPod touch, for example, and want to transfer your previous settings to it. You may also want to reset the information on iPod touch if you’re having trouble connecting to a Wi-Fi network. Automatically backed-up information includes notes, contact favorites, sound settings, and other preferences.Chapter 7 Settings 85 Restore or transfer settings Do one of the following: m Connect a new iPod touch to the same computer you used with your other iPod touch, open iTunes, and follow the onscreen instructions. m Reset the information on iPod touch. In Settings, choose General > Reset, then choose “Reset All Settings,” “Erase All Content and Settings,” or “Reset Network Settings.” Then connect iPod touch to your computer, open iTunes, and follow the onscreen instructions. When you reset network settings, your list of previously used networks is removed. Wi-Fi is turned off and then back on, disconnecting you from any network you’re on. The Wi-Fi and “Ask to Join Networks” settings are left turned on. Delete a set of backed-up settings m Open iTunes and choose iTunes > Preferences (on a Mac) or Edit > Preferences (on a PC). Then click Syncing, select an iPod touch, and click “Remove Backup.” iPod touch doesn’t need to be connected to your computer.A 86 A Tips and Troubleshooting Most problems with iPod touch can be solved quickly by following the advice in this chapter. General Suggestions If the screen is blank or shows a low-battery image iPod touch is low on power and needs to charge for up to ten minutes before you can use it. For information about charging iPod touch, see “Charging the Battery” on page 22. If iPod touch doesn’t appear in iTunes or you can’t sync iPod touch  The iPod touch battery might need to be recharged. For information about charging iPod touch, see “Charging the Battery” on page 22.  If that doesn’t work, disconnect other USB devices from your computer and connect iPod touch to a different USB 2.0 port on your computer (not on your keyboard).  If that doesn’t work, turn off iPod touch and turn it on again. Press and hold the Sleep/Wake button on top of iPod touch for a few seconds until a red slider appears, then drag the slider. Then press and hold the Sleep/Wake button until the Apple logo appears.  If that doesn’t work, restart your computer and reconnect iPod touch to your computer. orAppendix A Tips and Troubleshooting 87  If that doesn’t work, download and install (or reinstall) the latest version of iTunes from www.apple.com/itunes. If iPod touch won’t turn on, or if the display freezes or doesn’t respond  iPod touch may need charging. See “Charging the Battery” on page 22.  Press and hold the Home button for at least six seconds, until the application you were using quits.  If that doesn’t work, turn off iPod touch and turn it on again. Press and hold the Sleep/Wake button on top of iPod touch for a few seconds until a red slider appears, and then drag the slider. Then press and hold the Sleep/Wake button until the Apple logo appears.  If that doesn’t work, reset iPod touch. Press and hold both the Sleep/Wake button and the Home button for at least ten seconds, until the Apple logo appears. If iPod touch continues to freeze or not respond after you reset it  Reset iPod touch settings. From the Home screen choose Settings > General > Reset > Reset All Settings. All your preferences are reset, but your data and media are left untouched.  If that doesn’t work, erase all content on iPod touch. From the Home screen choose Settings > General > Reset > “Erase All Content and Settings.” All your preferences are reset, and all your data and media are removed from iPod touch.  If that doesn’t work, restore the iPod touch software. See “Updating and Restoring iPod touch Software” on page 89. If iPod touch isn’t playing sound  Unplug and reconnect the headphones. Make sure the connector is pushed in all the way.  Make sure the volume isn’t turned down all the way.  Music on iPod touch might be paused. From the Home screen tap Music, tap Now Playing, then tap .  Check to see if a volume limit is set. From the Home screen choose Settings > Music > Volume Limit. For more information, see page 79.  Make sure you are using iTunes 7.6 or later (go to www.apple.com/itunes). Songs purchased from the iTunes Store using earlier versions of iTunes won’t play on iPod touch until you upgrade iTunes.  If you are using the optional dock’s line out port, make sure your stereo or external speakers are turned on and working properly. If iPod touch shows a message saying “This accessory is not supported by iPod” The accessory you attached will not work with iPod touch.88 Appendix A Tips and Troubleshooting If you can’t play a song you just purchased Your purchase may still be downloading. Close and reopen Music, then try playing the song again. If you can’t add or play a song, video, or other item The media may have been encoded in a format that iPod touch doesn’t support. The following audio file formats are supported by iPod touch. These include formats for audiobooks and podcasting:  AAC (M4A, M4B, M4P, up to 320 Kbps)  Apple Lossless (a high-quality compressed format)  MP3 (up to 320 Kbps)  MP3 Variable Bit Rate (VBR)  WAV  AA (audible.com spoken word, formats 2, 3, and 4)  AAX (audible.com spoken word, AudibleEnhanced format)  AIFF The following video file formats are supported by iPod touch:  H.264 (Baseline Profile Level 3.0)  MPEG-4 (Simple Profile) A song encoded using Apple Lossless format has full CD-quality sound, but takes up only about half as much space as a song encoded using AIFF or WAV format. The same song encoded in AAC or MP3 format takes up even less space. When you import music from a CD using iTunes, it is converted to AAC format by default. Using iTunes for Windows, you can convert nonprotected WMA files to AAC or MP3 format. This can be useful if you have a library of music encoded in WMA format. iPod touch does not support WMA, MPEG Layer 1, MPEG Layer 2 audio files, or audible.com format 1. If you have a song or video in your iTunes library that isn’t supported by iPod touch, you may be able to convert it to a format iPod touch supports. See iTunes Help for more information. If you can’t remember your passcode You must restore the iPod touch software. See “Updating and Restoring iPod touch Software” on page 89. If you entered contacts on iPod touch that you don’t want to sync to your computer Replace contacts on iPod touch with information from your computer. 1 Open iTunes. Appendix A Tips and Troubleshooting 89 2 As you connect iPod touch to your computer, press and hold Command-Option (if you’re using a Mac) or Shift-Control (if you’re using a PC) until you see iPod touch in the iTunes source list on the left. This prevents iPod touch from syncing automatically. 3 Select iPod touch in the iTunes source list and click the Info tab. 4 Under “Replace information on this iPod,” select Contacts. You can select more than one. 5 Click Apply. The contacts on iPod touch are replaced with the contacts on your computer. The next time you sync, iPod touch syncs normally, adding data you’ve entered on iPod touch to your computer, and vice versa. If you can’t sync with Yahoo! Address Book iTunes may not be able to connect to Yahoo!. Make sure your computer is connected to the Internet and that you’ve entered the correct Yahoo! ID and password in iTunes. Connect iPod touch to your computer, click the Info tab in iTunes, select “Sync Yahoo! Address Book contacts,” then enter your current Yahoo! ID and password. If contacts you deleted on iPod touch or your computer are not removed from Yahoo! Address Book after syncing Yahoo! Address Book does not allow contacts containing a Messenger ID to be deleted through syncing. To delete a contact containing a Messenger ID, log in to your online Yahoo! account and delete the contact using Yahoo! Address Book. If you can’t access the iTunes Wi-Fi Music Store To use the iTunes Wi-Fi Music Store, iPod touch must join a Wi-Fi network that is connected to the Internet. For information about joining a Wi-Fi network, see page 21. The iTunes Wi-Fi Music Store is not available in all countries. If you can’t purchase music from the iTunes Wi-Fi Music Store To purchase songs from the iTunes Wi-Fi Music Store (only available in some countries), you must have an iTunes Store account, and you must have been signed in to that account when you last synced iPod touch with iTunes. If you get a message that no account information is found when you try to purchase music, open iTunes, sign in to your iTunes Store account, and then connect and sync iPod touch. Updating and Restoring iPod touch Software You can use iTunes to update or restore iPod touch software. You should always update iPod touch to use the latest software. You can also restore the software, which puts iPod touch back to its original state.  If you update, the iPod touch software is updated but your settings and songs are not affected. 90 Appendix A Tips and Troubleshooting  If you restore, all data is erased from iPod touch, including songs, videos, contacts, photos, calendar information, and any other data. All iPod touch settings are restored to their original state. Update or restore iPod touch 1 Make sure you have an Internet connection and have installed the latest version of iTunes from www.apple.com/itunes. 2 Connect iPod touch to your computer. 3 In iTunes, select iPod touch in the source list and click the Summary tab. 4 Click “Check for Update.” iTunes tells you if there’s a newer version of the iPod touch software available. 5 Click Update to install the latest version of the software. Or click Restore to restore iPod touch to its original settings and erase all data and media on iPod touch. Follow the onscreen instructions to complete the restore process. Using iPod touch Accessibility Features The following features may make it easier for you to use iPod touch if you have a disability. Closed captioning When available, you can turn on closed captioning for videos. See “Turn closed captioning on or off” on page 80. Minimum font size for Mail messages Set a minimum font size for Mail message text to Large, Extra Large, or Giant to increase readability. See “Set a minimum font size for messages” on page 82. Zooming Double-tap or pinch webpages, photos, and maps to zoom in. See page 18. Universal Access in Mac OS X Take advantage of the Universal Access features in Mac OS X when you use iTunes to sync information and content from your iTunes library to iPod touch. In the Finder, choose Help > Mac Help, then search for “universal access.” For more information about iPod touch and Mac OS X accessibility features, go to: www.apple.com/accessibilityB 91 B Learning More, Service, and Support There’s more information about using iPod touch, in onscreen help and on the web. The following table describes where to get more iPod-related software and service information. To learn about Do this Using iPod touch safely Go to www.apple.com/support/manuals/ipod for the latest Important Product Information Guide, including any updates to the safety and regulatory information. iPod touch support, tips, forums, and Apple software downloads Go to www.apple.com/support/ipodtouch. The latest information about iPod touch Go to www.apple.com/ipodtouch. Using iTunes Open iTunes and choose Help > iTunes Help. For an online iTunes tutorial (available in some areas only), go to www.apple.com/support/itunes. Using iPhoto in Mac OS X Open iPhoto and choose Help > iPhoto Help. Using Address Book in Mac OS X Open Address Book and choose Help > Address Book Help. Using iCal on Mac OS X Open iCal and choose Help > iCal Help. Microsoft Outlook, Windows Address Book, Adobe Photoshop Album, and Adobe Photoshop Elements See the documentation that came with those applications. Finding your iPod touch serial number Look at the back of your iPod touch or choose Settings > General > About from the Home screen. Obtaining warranty service First follow the advice in this guide and online resources. Then go to www.apple.com/support or see the Important Product Information Guide that comes with iPod touch.K Apple Inc. © 2008 Apple Inc. All rights reserved. Apple, the Apple logo, AirPort, Cover Flow, iCal, iPhoto, iPod, iTunes, Mac, Macintosh, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, Safari, and Shuffle are trademarks of Apple Inc. .Mac is a service mark of Apple Inc., registered in the U.S. and other countries. iTunes Store is a service mark of Apple Inc. Adobe and Photoshop are trademarks or registered trademarks of Adobe Systems Incorporated in the U.S. and/or other countries. Other company and product names mentioned herein may be trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. All understandings, agreements, or warranties, if any, take place directly between the vendors and the prospective users. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. The product described in this manual incorporates copyright protection technology that is protected by method claims of certain U.S. patents and other intellectual property rights owned by Macrovision Corporation and other rights owners. Use of this copyright protection technology must be authorized by Macrovision Corporation and is intended for home and other limited viewing uses only unless otherwise authorized by Macrovision Corporation. Reverse engineering or disassembly is prohibited. Apparatus Claims of U.S. Patent Nos. 4,631,603, 4,577,216, 4,819,098 and 4,907,093 licensed for limited viewing uses only. 019-1215/2008-03 93 Index Index 12-hour time 76 24-hour time 76 A accessibility features 90 accounts default email 83 email 81 Address Book 8, 58, 91 See also contacts address field, erasing text 45 Adobe Photoshop Album 8, 34, 91 Adobe Photoshop Element 91 Adobe Photoshop Elements 8, 34 alarms deleting 71 setting 71 status icon 11 turning on or off 71 album covers 28 album tracks 29 alerts calendar 51 alerts, turning on or off 78 alternate audio language 31 ambient light sensor 75 AOL free email account 53 attachments email 57 audio, alternate language 31 audiobooks play speed 79 syncing 5 See also music audio file formats, supported 88 Auto-Brightness 75 auto-capitalization, turning on or off 78 auto-lock, setting time for 77 AV cables 32 B battery charging 22 low on power 23, 86 replacing 23 status icon 11 bookmarking map locations 66 webpages 49 YouTube videos 61 bookmarks, syncing 9, 50 brightness, adjusting 75 browser cache, clearing 84 browsing album covers 28 YouTube videos 60 browsing iTunes Wi-Fi Music Store 39 businesses, finding 68 C cable, Dock Connector to USB 11 cache, clearing browser 84 Calculator 72 Calendar about 50 settings 52 views 51 See also events calendars, syncing 8, 50 capitalization, automatic 78 caps lock, enabling 78 Cc 82, 83 charging battery 22 cleaning iPod touch 11, 23 Clock 70 closed captioning, turning on or off 80 cloth, polishing 11 Component AV cable 32 Composite AV cable 32 computer requirements 4 connecting to Internet 21 contacts adding and editing 59 adding email recipient 5794 Index adding from Maps 66 assigning photo to 38 entering 58 seeing location of 66 settings 84 syncing 8 Yahoo! Address Book 8 controls, using 16 converting unprotected WMA files 88 cookies 84 Cover Flow 28 current approximate location 64, 66 cursor. See insertion point D date and time, setting 76 date format 77 Debug Console 84 deleting alarms 71 all contents and settings 79 calendar events 51 clocks 70 contacts 60 email account 81 email messages 56 notes 73 songs from a playlist 29 videos 32 Yahoo! Address Book contacts 8 developer settings 84 directions, getting 66 disconnecting iPod touch from computer 9 display freezes 87 displaying playback controls 27 Dock Connector to USB cable 11 downloading songs from iTunes Wi-Fi Music Store 43 drafts, email 55 dropped pin 65 E editing text 20 effects sounds, turning on or off 78 email accounts free 53 setting up 54 syncing 8 Entourage. See Microsoft Entourage equalizer 79 erasing all content and settings 79 events, calendar 50 Exchange email accounts 54 F file formats, supported 57, 88 forecast. See weather formats date, time, and telephone number 77 music and video 25 forwarding messages 55 G general settings 75 getting help 91 getting started 4 Google free email account 53 Google search engine 47, 83 H headphones 11 help, getting 91 Home screen 12, 16 adding Web Clips 49 customizing 13 hybrid view 66 I iCal 8, 91 icons status 11 IMAP email accounts 54 information about iPod touch 75 insertion point, positioning 20 international keyboards 77, 78 Internet, connecting to 21 iPhoto 8, 34, 91 iTunes getting help 91 iPod touch doesn’t appear in 86 iTunes Store account 44 iTunes Wi-Fi Music Store 39 browsing 39 K keyboard dictionary, resetting 79 keyboards international 77 typing on 19 L landscape orientation viewing photos 36 viewing webpages 46 legal information 76 light sensor 75 links in email 58Index 95 links on webpages 45 location. See Maps locking iPod touch 11, 15 lyrics, displaying 26 M .Mac account 54 Mac OS X Address Book 58 Mac system requirements 4 Mail 53 account setup 81 adding recipient to contacts 57 attachments 57 Cc 82, 83 checking for new messages 57, 82 default email account 83 deleting email account 81 deleting messages 56 forwarding messages 55 links 58 marking messages as unread 57 organizing email 57 password settings 81 reading messages 56 replying to messages 55 resizing text column 58 saving drafts 55 seeing recipients 57 sending messages 54, 83 sending photos 55 sending webpage addresses 46 settings 81 signatures 83 storing email on iPod touch or server 81 syncing email account settings 8, 54 Yahoo! email account 9, 82 zooming in a message 58 Maps adding location to a contact 66 bookmarking location 66 current approximate location 64, 66 dropped pin 65 finding businesses 68 finding location 64 getting directions 66 hybrid view 66 satellite view 66 seeing location of a contact 66 traffic conditions 67 zooming 65 mic button 26 Microsoft Entourage 8, 58 Microsoft Excel 83 Microsoft Internet Explorer 50 Microsoft Outlook 8, 58, 89, 91 Microsoft Word 83 model number 76 movies rented 8 movies, rented 31 music lyrics 26 managing manually 7 playing 25 previewing 42 purchasing 42 syncing 5, 7, 24 transferring purchased content 25 music settings 79 N navigating. See panning, scrolling networks 74 network settings, resetting 79 Notes 73 NTSC 80 O on-the-go playlists 29 orientation, changing 36 Outlook. See Microsoft Outlook Outlook Express. See Windows Address Book P PAL 80 panning maps 65 panning photos 36 passcode 77, 88 PC system requirements 4 photo albums 37 Photos assigning photos to contacts 38 changing size or orientation of photos 36 emailing photos 37 playing music during slideshow 37 sending photos in email 55 settings 37, 80 syncing 34 using photos as wallpaper 37 viewing slideshows 37 zooming photos 36 photos, syncing 8 playback controls, displaying 27 playing music and video 25 playlists, on-the-go 29 play speed, audiobooks 79 plug-ins 83 podcasts syncing 7, 2496 Index transferring purchased content 25 See also music POP email accounts 54 pop-ups 83 power, low 23, 86 power adapter 11, 22 previewing music 42 problems. See troubleshooting purchased music, syncing 43 purchasing music 39, 42 R reading email 56 rechargeable batteries 23 rented movies 8, 31 repeating songs 27 replacing battery 23 replying to messages 55 requirements for using iPod touch 4 resetting network settings 79 resizing webpage columns 47 restoring iPod touch software 89 S Safari clearing cache 84 cookies 84 Debug Console 84 developer settings 84 erasing text in address field 45 Home screen Web Clips 49 navigating 46 opening webpages 45, 48 plug-ins 83 pop-ups 83 reloading webpages 46 resizing columns to fit screen 47 searching the web 47 security 83 sending webpage addresses in email 46 settings 81 stopping webpages from loading 46 typing in text fields 48 zooming webpages 46 satellite view 66 screen adjusting brightness 75 using 16 scrolling about 16 maps 65 webpages 47 search engine 83 searching iTunes Wi-Fi Music Store 39 the web 47 YouTube videos 60 security setting passcode for iPod touch 77 web 83 sending email 54, 83 photos from Photos 37 serial number, finding 76, 91 settings alarms 71 alerts 51 auto-lock 77 brightness 75 Calendar 51 calendar 52 contacts 84 date and time 52, 76 deleting 85 developer 84 email account 8, 54, 81 email server 81 general 75 international 76 keyboard 78 language 76 Mail 54, 81, 83 music 79 passcode lock 77 Photos 37, 80 resetting 78 restoring 84 Safari 47, 81 screen brightness 75 security 83 slideshow 37 sound 51 sound effects 78 sync 6 temperature 70 time zone 76 transferring 84 TV out 80 video 80 wallpaper 37, 76 Wi-Fi 74 shuffling songs 27 signatures, email 83 sleep. See locking iPod touch sleep timer 32 slideshows 37 slideshow settings 80 software getting help 91 updating and restoring 89 software version 76Index 97 songs. See music sound adjusting volume 26 no sound 87 setting limit 79 Sound Check 79 sound effects settings 78 sounds calendar alert 51 turning on or off 78 SSL 81 stand 11 Starbucks, browsing and purchasing music 41 status icons 11 stock information, Yahoo! 63 Stocks, adding and deleting quotes 63 stopwatch, using 71 storage capacity 75 subtitles 31 support information 91 surfing the web 45 syncing “Sync in progress” message 9 calendars 50 email account settings 54 photos 34 preventing 9, 88 setting up 6 webpage bookmarks 50 Yahoo! Address Book 89 syncing purchased songs 43 system requirements 4 T telephone number format 77 temperature. See Weather Text, typing in webpages 48 time, setting 76 time format 77 timer setting 72 sleep 72 time zone support 52, 76 touchscreen, using 16 traffic conditions, checking 67 transferring purchased content 25, 43 transition effects, setting 80 troubleshooting can’t remember passcode 88 display freezes 87 iPod touch doesn’t appear in iTunes 86 iPod touch doesn’t respond 87 iPod touch doesn’t turn on 87 no sound 87 preventing syncing 88 problems playing songs or other content 88 software update and restore 89 turning iPod touch on or off 15 TV out settings 80 TV signal settings 80 typing about 19 in webpage text fields 48 U unlocking iPod touch 15 unread messages, marking 57 unsupported audio file formats 88 updating iPod touch software 89 USB cable 11 power adapter 11, 22 V videos alternate audio language 31 deleting 32 playing 25 subtitles 31 syncing 7, 24 transferring purchased content 25 watching on a TV 32 See also Music, YouTube video settings 80 volume adjusting 26 setting limit 79 W waking iPod touch 15 wallpaper choosing 76 settings 37 using photo as 37 warranty service 91 watching videos on a TV 32 Weather adding cities 69 deleting cities 69 temperature settings 70 viewing 69 weather information, Yahoo! 70 web. See Safari Web Clips, adding to Home screen 49 Wi-Fi forgetting a network 75 joining networks 21, 74 settings 74 status icon 11 turning on or off 7498 Index Wi-Fi address 76 Windows Address Book 8, 58, 91 WMA files, converting 88 World Clock 70 Y Y! Mail account 54 Yahoo! Address Book 8, 89 email accounts 9, 82 free email account 53 search engine 83 searching using 47 stock information 63 syncing email accounts 9 weather information 70 Y! Mail accounts 54 Yahoo! Address Book 58 YouTube bookmarking videos 61 browsing videos 60 playing videos 61 searching for videos 60 Z zooming email messages 58 maps 65 photos 36 webpages 46 Apple Wireless Mighty Mouse2 English 1 Setting Up Your Wireless Mighty Mouse Congratulations on selecting the wireless Mighty Mouse as your input device. Using the Wireless Mighty Mouse Follow the steps on the following pages to install batteries in your mouse, set up your Mac, and use Setup Assistant to set up your mouse with your Mac. Important: Don’t turn on your mouse until just before you are ready to start up your Mac in step 3. Step 1: Installing the Batteries Follow the instructions below to install batteries in your wireless Mighty Mouse. You can install either one or both of the nonrechargeable AA lithium batteries that came with your mouse (see “About Your Batteries” on page 7 for more information). To install batteries in your mouse: 1 Turn the mouse over and remove the bottom cover. 2 Slide the batteries into the battery compartment as shown in the illustration.English 3 3 Replace the bottom cover and leave the mouse turned off. Step 2: Setting Up Your Mac Follow the instructions in the user’s guide that came with your Mac to set it up. Because you have a wireless mouse, skip the instructions for connecting a USB mouse. Wait to start up your Mac until instructed to do so in step 3. Slide the switch up to turn the mouse off. Push the latch down to remove the bottom cover. Insert one or both AA batteries with the positive (+) end up.4 English Step 3: Pairing Your Mouse Before you can use your wireless Mighty Mouse, you have to pair it with your Mac. Pairing allows your mouse and Mac to communicate wirelessly with each other. You only have to pair them once. The first time you start up your Mac, Setup Assistant guides you in setting up your wireless Mighty Mouse and pairing it with your Mac. To pair your mouse and your Mac: 1 Slide the switch down to turn the mouse on. The laser used by the Mighty Mouse is not visible, but a small green indicator light on the bottom of the mouse blinks when the mouse is on and the batteries are charged. 2 Turn on your Mac. 3 When your Mac starts up, follow the onscreen instructions in Setup Assistant. Slide the switch down to turn the mouse on. The indicator light shows that the mouse is on.English 5 Using Your Mighty Mouse The Mighty Mouse has laser tracking technology, so you can use it on most surfaces. The Mighty Mouse comes with left and right buttons, a scroll ball (which can be clicked) and a button on either side. To use your Mighty Mouse:  Click the left or right button.  Press the side buttons.  Click or roll the scroll ball. Either the left or right button can function as the primary button. Use the primary button to click, double-click, and drag items. Either button can also function as the secondary button. Use the secondary button to display an item’s shortcut menu. You can assign a function to the side buttons, which work together as a single button, and to the scroll ball, which also functions as a button. Scroll ball (button) Left button Side button Side button Right button6 English Customizing Your Mighty Mouse Use the Mouse pane of Keyboard & Mouse preferences to change the way your Mighty Mouse works. To customize your mouse: 1 Choose Apple () > System Preferences. 2 Click Keyboard & Mouse. 3 Click Mouse. Use the pop-up menu to assign an action to each button. You can set any of the buttons to activate Dashboard, Exposé, Spotlight, switch applications, or open applications. You can enable or disable scrolling and screen zoom, and adjust the speed for tracking, scrolling, and double-clicking. You can also activate screen zoom by simultaneously pressing a key on the keyboard and scrolling. More Information For more information about using your wireless Mighty Mouse, open Mac Help and search for “Mighty Mouse.” Renaming Your Mouse Your Mac automatically gives your wireless mouse a unique name the first time it’s paired. You can rename your mouse using Keyboard & Mouse preferences. Choose Apple () > System Preferences and click Keyboard & Mouse. Click the Bluetooth® tab and enter a name in the Name field.English 7 Cleaning Your Mouse and Scroll Ball Follow these guidelines to clean the outside of your mouse and the scroll ball:  Remove the batteries.  Use a lint-free cloth that’s been lightly moistened with water to clean the mouse exterior and the scroll ball.  Don’t get moisture in any openings. Don’t use aerosol sprays, solvents, or abrasives. If your mouse stops scrolling or if scrolling becomes rough, clean the mouse scroll ball. Rotate the ball while cleaning for complete coverage. If scrolling feels rough, hold the mouse upside down and roll the ball vigorously while cleaning it to help remove any particles that may have collected. About Your Batteries Your Mighty Mouse comes with two nonrechargeable AA lithium batteries. Lithium batteries provide longer battery life, but you can also use alkaline or rechargeable AA batteries. Your mouse works with either one or two batteries installed. To reduce the weight of your mouse, install one battery; to extend the time between battery replacements, install two. WARNING: When you replace the batteries, replace them all at the same time. Also, don’t mix old batteries with new batteries or mix battery types (for example, don’t mix alkaline and lithium batteries). Don’t open or puncture the batteries, install them backwards, or expose them to fire, high temperatures, or water. Don’t charge the nonrechargeable AA lithium batteries that came with your mouse. Keep batteries out of the reach of children.8 English Battery Disposal Dispose of batteries according to your local environmental laws and guidelines. Battery Indicator You can use Keyboard & Mouse preferences to check the battery level. Choose Apple () > System Preferences. Click Keyboard & Mouse and click Bluetooth. Note: To conserve battery power, turn your mouse off when you are not using it. If you are not planning to use your mouse for an extended period, remove the batteries. Ergonomics For information about ergonomics, health, and safety, visit the Apple ergonomics website at www.apple.com/about/ergonomics. Support For support and troubleshooting information, user discussion boards, and the latest Apple software downloads, go to www.apple.com/support.910111213141516 Français 2 Configuration de votre souris Mighty Mouse sans fil Félicitations pour l’acquisition de la souris Mighty Mouse sans fil comme périphérique d’entrée. Utilisation de la souris Mighty Mouse sans fil Pour installer les piles dans la souris, configurer votre Mac et utiliser l’Assistant réglages pour configurer la souris avec votre Mac, veuillez suivre les instructions des pages suivantes. Important : n’allumez votre souris que lorsque vous êtes sur le point d’allumer votre Mac comme décrit à l’étape 3. Étape 1 : Installation des piles Pour installer les piles dans votre souris Mighty Mouse sans fil, veuillez suivre les instructions ci-dessous. Vous pouvez installer une ou deux des piles au lithium AA non rechargeables fournies avec votre souris (consultez la rubrique « À propos des piles » à la page 22 pour en savoir plus). Pour installer les piles dans la souris : 1 Retournez la souris et retirez le couvercle. 2 Placez les piles dans le compartiment comme illustré.Français 17 3 Remettez le couvercle de la souris. Étape 2 : Configuration de votre Mac Configurez votre Mac en suivant les instructions du Guide de l’utilisateur qui l’accompagne. Étant donné que vous possédez une souris sans fil, les instructions concernant la connexion d’une souris USB ne vous concernent pas. Ne démarrez votre Mac que lorsque cela vous est indiqué à l’étape 3. Faites glisser l’interrupteur vers le haut pour éteindre la souris. Poussez ce verrou vers le bas pour retirer le couvercle inférieur. Insérez une ou deux piles AA. La borne positive (+) doit être placée vers le haut.18 Français Étape 3 : Jumelage de votre souris Avant d’utiliser votre souris Mighty Mouse sans fil, vous devez la jumeler avec votre Mac. Grâce au jumelage, la souris peut communiquer sans fil avec votre Mac. Le jumelage ne s’effectue qu’une seule fois. La première fois que vous démarrez votre Mac, l’Assistant réglages vous guide tout au long de la configuration de votre souris Mighty Mouse sans fil afin de la jumeler à votre Mac. Pour jumeler votre souris à votre Mac : 1 Faites glisser l’interrupteur vers le bas pour allumer la souris. Le laser utilisé par la souris Mighty Mouse n’est pas visible, mais une petite lampe témoin verte placée en bas de la souris clignote lorsque celle-ci est en marche et que les piles sont suffisamment chargées. Faites glisser l’interrupteur vers le bas pour allumer la souris. Le voyant lumineux indique que la souris est allumée.Français 19 2 Allumez votre Mac. 3 Suivez ensuite les instructions à l’écran de l’Assistant réglages. Utilisation de votre Mighty Mouse La souris Mighty Mouse intègre la technologie de déplacement par laser, ce qui permet de l’utiliser sur la plupart des surfaces. La Mighty Mouse possède deux boutons (un gauche et un droit), une boule de défilement cliquable et un bouton sur chaque côté. Pour utiliser votre Mighty Mouse, vous pouvez :  cliquer sur le bouton gauche ou droit,  appuyer sur un des boutons latéraux,  faire défiler ou cliquer sur la boule de défilement. 20 Français Le bouton de gauche ou celui de droite peut agir en tant que bouton principal selon votre choix. Utilisez le bouton principal pour cliquer ou double-cliquer sur des éléments, ou encore pour les faire glisser. Ces boutons peuvent également servir de bouton secondaire. Celui-ci permet d’afficher le menu contextuel d’un élément. Vous pouvez affecter une fonction spécifique aux boutons latéraux, qui fonctionnent conjointement comme un seul bouton, et à la boule de défilement, faisant également office de bouton. Personnalisation de votre Mighty Mouse Utilisez la sous-fenêtre Souris des préférences Clavier et souris pour modifier le mode de fonctionnement de votre Mighty Mouse. Pour personnaliser votre souris : 1 Sélectionnez le menu Pomme () > Préférences Système. 2 Cliquez sur Clavier et souris. 3 Cliquez ensuite sur Souris. Boule de défilement (bouton) Bouton gauche Bouton latéral Bouton latéral Bouton droitFrançais 21 Utilisez les menus locaux pour affecter une action à chaque bouton. Vous pouvez ainsi régler n’importe quel bouton pour activer le Dashboard, Exposé, Spotlight, pour passer d’une application à l’autre ou en ouvrir directement. Vous pouvez activer ou désactiver le défilement ou le zoom de l’écran, mais aussi affiner la vitesse du déplacement du pointeur, du défilement et du double-clic. Enfin, vous avez la possibilité d’activer le zoom de l’écran en appuyant sur une touche du clavier tout en activant le défilement. Informations complémentaires Pour en savoir plus sur l’utilisation de votre Mighty Mouse sans fil, ouvrez l’Aide Mac et lancez une recherche du terme “Mighty Mouse”. Changement du nom de votre souris La première fois que la souris sans fil est jumelée, votre Mac lui attribue automatiquement un nom unique. Vous pouvez changer ce nom dans les préférences Clavier et souris. Sélectionnez le menu Pomme () > Préférences Système, puis cliquez sur Clavier et souris. Cliquez sur l’onglet Bluetooth® et saisissez un nouveau nom dans le champ Nom. Entretien de votre souris et de la boule de défilement Suivez les instructions suivantes pour assurer le nettoyage et l’entretien extérieur de votre souris et de la boule de défilement :  Retirez les piles.  Servez-vous d’un chiffon légèrement humide et ne peluchant pas pour nettoyer l’extérieur de la souris et la boule de défilement.22 Français  Faites en sorte que l’humidité ne s’infiltre pas par une des ouvertures. N’utilisez pas d’aérosol, de solvant ou tout autre produit abrasif. Si votre souris ne défile plus ou si cela devient difficile, nettoyez la boule de défilement. Faites pivoter la boule tout en passant le chiffon afin de la nettoyer de toutes parts. Si la boule semble résister, retournez la souris et faites tourner la boule vigoureusement tout en procédant au nettoyage pour contribuer à faire tomber les particules qui s’y seraient accumulées. À propos des piles Votre Mighty Mouse est fournie avec deux piles au lithium AA non rechargeables. Les piles au lithium sont caractérisées par une durée de vie plus longue, mais vous pouvez également utiliser des piles AA alcalines ou rechargeables. Votre souris fonctionne aussi bien avec une qu’avec deux piles. Ne placez qu’une seule pile si vous voulez réduire le poids de votre souris mais placez-en deux si vous voulez éviter de changer les piles fréquemment. AVERTISSEMENT : lorsque vous changez les piles, remplacez-les toutes en même temps. Ne mélangez pas de vieilles piles avec des nouvelles, ni différents types de piles (par exemple, ne mettez pas de piles alcalines avec des piles au lithium). N’ouvrez pas les piles, ne les percez pas, ne les installez pas à l’envers et ne les exposez pas au feu, à des températures élevées ou à l’eau. Ne tentez pas de recharger les piles au lithium AA non rechargeables fournies avec votre souris. Conservez-les hors de portée des enfants.Français 23 Mise au rebut des piles Mettez les piles au rebut en respectant la réglementation et les directives locales en matière d’environnement. Témoin de charge Vous pouvez utiliser les préférences Clavier & Souris pour connaître le niveau de charge des piles. Sélectionnez le menu Pomme () > Préférences Système. Cliquez sur Clavier et souris, puis sur Bluetooth. Remarque : pour économiser les piles, éteignez votre souris dès que vous avez fini de l’utiliser. Si vous ne comptez pas vous en servir pendant une période prolongée, retirez les piles. Ergonomie Pour obtenir des informations sur l’ergonomie, la santé et la sécurité, rendez-vous sur le site Web d’Apple concernant l’ergonomie : www.apple.com/fr/about/ergonomics Assistance Pour accéder à toute information supplémentaire sur l’assistance et le dépannage, à des forums de discussion et aux derniers téléchargements de logiciels Apple rendez-vous sur à l’adresse www.apple.com/fr/support.24 Español 3 Configuración del ratón inalámbrico Mighty Mouse Enhorabuena por haber elegido el ratón inalámbrico Mighty Mouse como dispositivo de entrada. Utilización del ratón inalámbrico Mighty Mouse Siga los pasos que se describen en las páginas siguientes para instalar las pilas en el ratón, configurar su Mac y utilizar el Asistente de Configuración para configurar el ratón con su ordenador. Importante: No encienda el ratón hasta que vaya a arrancar el ordenador en el paso 3. Paso 1: Colocación de las pilas Siga las instrucciones que figuran a continuación para insertar las pilas en el ratón inalámbrico Mighty Mouse. Puede optar por instalar las dos pilas de litio AA no recargables incluidas con el ratón o solamente una (para más información al respecto, consulte el apartado “Acerca de las pilas” en la página 30). Para colocar las pilas en el ratón: 1 Dé la vuelta al ratón y extraiga la tapa posterior. 2 Introduzca las pilas en el compartimento tal como se muestra en la ilustración.Español 25 3 Coloque de nuevo la tapa de la parte posterior y no encienda el ratón. Paso 2: Configuración del Mac Para configurar su ordenador, siga las instrucciones que figuran en el manual que se suministraba con su Mac. Puesto que tiene un ratón inalámbrico, no es necesario que lea las instrucciones correspondientes a la conexión de un ratón USB. No arranque el Mac hasta que no se le solicite hacerlo en el paso 3. Desplace el interruptor hacia arriba para apagar el ratón. Presione este cierre hacia abajo para abrir la tapa posterior del ratón. Introduzca una o dos pilas AA con los polos positivos (+) hacia arriba.26 Español Paso 3: Enlace del ratón con el ordenador Antes de poder utilizar el ratón inalámbrico Mighty Mouse, debe enlazarlo con su Mac. El proceso de enlace permite que el ratón se comunique de forma inalámbrica con el ordenador. Esta operación sólo deberá llevarse a cabo una vez. La primera vez que arranca el ordenador, el Asistente de Configuración le guía a través de los pasos necesarios para configurar el ratón inalámbrico Mighty Mouse y enlazarlo con su Mac. Para enlazar el ratón con el Mac: 1 Deslice el conmutador hacia abajo para encender el ratón. El láser que utiliza el Mighty Mouse es invisible, pero en la base del ratón hay un pequeño indicador luminoso de color verde que parpadea cuando el ratón está encendido y las pilas están cargadas. Desplace el interruptor hacia abajo para encender el ratón. El indicador luminoso indica que el ratón está encendido.Español 27 2 Encienda el ordenador. 3 Cuando el sistema haya arrancado, siga las instrucciones del Asistente de Configuración que van apareciendo en pantalla. Uso del Mighty Mouse Gracias a la tecnología láser del Mighty Mouse, es posible utilizarlo en la mayoría de las superficies. El Mighty Mouse incorpora un botón izquierdo, uno derecho, una bola de desplazamiento (que sirve para hacer clic) y dos botones laterales, uno en cada cara. Para usar el Mighty Mouse:  Haga clic en el botón izquierdo o derecho.  Pulse los botones laterales.  Haga clic o haga rodar la bola de desplazamiento. 28 Español Tanto el botón derecho como el izquierdo pueden funcionar como botón principal. Utilice el botón principal para hacer un clic simple o doble y para arrastrar ítems. Ambos botones pueden hacer las veces también de botón secundario. Utilice el botón secundario para visualizar el menú de función rápida de un ítem. Puede asignar una función a los botones laterales, que funcionan juntos como un único botón, y también a la bola de desplazamiento, que también funciona como un botón. Bola de desplazamiento (botón) Botón izquierdo Botón lateral Botón lateral Botón derechoEspañol 29 Cómo personalizar su Mighty Mouse Utilice el panel Ratón del panel de preferencias Teclado y Ratón para cambiar el modo de funcionamiento del Mighty Mouse. Para personalizar el ratón: 1 Seleccione Apple () > Preferencias del Sistema. 2 Haga clic en Teclado y Ratón. 3 Haga clic en Ratón. Utilice el menú local para asignar una acción a cada botón. Puede configurar cualquiera de los botones para activar el Dashboard, Exposé y Spotlight, alternar entre aplicaciones abiertas o abrir aplicaciones. Puede activar o desactivar el desplazamiento y el zoom de pantalla, así como ajustar la velocidad del cursor, del desplazamiento y del doble clic. Además, puede activar la ampliación o reducción de la pantalla pulsando simultáneamente una tecla del teclado y desplazando el ratón. Más información Para obtener más información acerca de cómo usar su Mighty Mouse inalámbrico, abra la Ayuda Mac y efectúe una búsqueda por “Mighty Mouse.” Cómo cambiar el nombre del ratón El Mac asigna automáticamente un nombre único al ratón inalámbrico la primera vez que se establece el enlace con el ratón. No obstante, si lo desea, puede modificar este nombre en el panel de preferencias Teclado y Ratón. Para ello, seleccione Apple () > Preferencias del Sistema y haga clic en Teclado y Ratón. Haga clic en la pestaña Bluetooth® e introduzca un nuevo nombre en el campo Nombre.30 Español Limpieza del ratón y la bola de desplazamiento Siga estas instrucciones para limpiar el exterior y la bola de desplazamiento del ratón:  Extraiga las pilas.  Utilice un paño suave que no desprenda pelusa y ligeramente humedecido en agua para limpiar la superficie exterior del ratón y la bola de desplazamiento.  Procure que no entre agua o humedad por las aberturas. No utilice aerosoles, disolventes ni limpiadores abrasivos. Si la bola de desplazamiento no funciona correctamente o nota que el desplazamiento no se realiza con suavidad, limpie la bola de desplazamiento del ratón. Para ello, límpiela haciéndola girar en todas las direcciones. Si la bola no gira suavemente, sostenga el ratón boca abajo y hágala girar enérgicamente mientras la limpia para eliminar cualquier partícula que pueda estar adherida. Acerca de las pilas Con el Mighty Mouse se incluyen dos pilas AA de litio no recargables. Las pilas de litio duran más, pero también puede usar pilas alcalinas o pilas AA recargables. El ratón funciona indistintamente con una pila o con dos instaladas. Para reducir el peso del ratón, instale solo una pila; si lo que le interesa es alargar el tiempo transcurrido entre la instalación de unas pilas y su sustitución, instale dos. ADVERTENCIA: Cuando sea necesario cambiar las pilas, sustituya siempre todas y no mezcle pilas nuevas con viejas ni tipos de pilas distintos (por ejemplo, no mezcle pilas alcalinas con pilas de litio). No intente abrir ni perforar las pilas, no las coloque al revés y evite que entren en contacto con el fuego, con altas temperaturas o con el agua. No intente recargar las dos pilas de litio AA no recargables que venían con el ratón. Mantenga las pilas fuera del alcance de los niños.Español 31 Eliminación de las pilas Tire las pilas siguiendo la normativa ambiental aplicable en su municipio. Indicador de carga de las pilas Puede comprobar el nivel de carga de las pilas a través del panel de preferencias Teclado y Ratón. Seleccione Apple () > Preferencias del Sistema. Haga clic en Teclado y Ratón y, a continuación, en Bluetooth. Nota: Para prolongar la duración de las pilas, apague el ratón cuando no lo utilice. Si tiene pensado no utilizarlo durante un tiempo prolongado, es aconsejable extraer las pilas. Ergonomía Para obtener más información sobre ergonomía, salud y seguridad, visite la página web de Apple sobre ergonomía: www.apple.com/es/about/ergonomics. Soporte Para obtener información acerca de soporte y resolución de problemas, sobre foros de discusión de usuarios y las últimas novedades en descargas de software de Apple, visite la página web www.apple.com/es/support32 Regulatory Compliance Information Compliance Statement This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or television reception is suspected. L‘utilisation de ce dispositif est autorisée seulement aux conditions suivantes : (1) il ne doit pas produire de brouillage et (2) l’utilisateur du dispositif doit étre prêt à accepter tout brouillage radioélectrique reçu, même si ce brouillage est susceptible de compromettre le fonctionnement du dispositif. Radio and Television Interference The equipment described in this manual generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or television reception, try to correct the interference by using one or more of the following measures:  Turn the television or radio antenna until the interference stops.  Move the computer to one side or the other of the television or radio.  Move the computer farther away from the television or radio.  Plug the computer into an outlet that is on a different circuit from the television or radio. (That is, make certain the computer and the television or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio or television technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc., could void the FCC compliance and negate your authority to operate the product. This product was tested for FCC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to 33 reduce the possibility of causing interference to radios, television sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple-authorized dealer. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only): Apple Inc., Product Compliance 1 Infinite Loop M/S 26-A Cupertino, CA 95014-2084 Industry Canada Statements Complies with the Canadian ICES-003 Class B specifications. Cet appareil numérique de la classe B est conforme à la norme NMB-003 du Canada. This device complies with RSS 210 of Industry Canada. This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la Class B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. European Compliance Statement This product complies with the requirements of European Directives 72/23/EEC, 89/336/EEC, and 1999/5/EC. Bluetooth Europe–EU Declaration of Conformity This wireless device complies with the specifications EN 300 328, EN 301-489, EN 50371, and EN 60950 following the provisions of the R&TTE Directive. Mighty Mouse Class 1 Laser Information The Mighty Mouse is a Class 1 laser product in accordance with IEC 60825-1 A1 A2 and 21 CFR 1040.10 and 1040.11 except for deviations pursuant to Laser Notice No. 50, dated July 26, 2001. Caution: Modification of this device may result in hazardous radiation exposure. For your safety, have this equipment serviced only by an Apple Authorized Service Provider. A Class 1 laser is safe under reasonably foreseeable conditions per the requirements in IEC 60825-1 AND 21 CFR 1040. However, it is recommended that you do not direct the laser beam at anyone’s eyes. Korea MIC Statement34 Korea Statements Singapore Wireless Certification Taiwan Wireless Statement Taiwan Class B Statement VCCI Class B Statement Apple and the Environment Apple Inc. recognizes its responsibility to minimize the environmental impacts of its operations and products. More information is available on the web at: www.apple.com/environment35 Disposal and Recycling Information When this product reaches its end of life, please dispose of it according to your local environmental laws and guidelines. For information about Apple’s recycling programs, visit: www.apple.com/environment/recycling Battery Disposal Information Dispose of batteries according to your local environmental laws and guidelines. Deutschland: Das Gerät enthält Batterien. Diese gehören nicht in den Hausmüll. Sie können verbrauchte Batterien beim Handel oder bei den Kommunen unentgeltlich abgeben. Um Kurzschlüsse zu vermeiden, kleben Sie die Pole der Batterien vorsorglich mit einem Klebestreifen ab. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd. Taiwan: European Union—Disposal Information The symbol above means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. © 2007 Apple Inc. All rights reserved. Apple, the Apple logo, Exposé, Mac, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. Spotlight is a trademark of Apple Inc. Mighty Mouse © Viacom International Inc. All rights reserved. The Mighty Mouse trademark is used under license. The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by Apple is under license.www.apple.com Printed in XXXX *1Z034-4321-A* Advanced Memory Management Programming GuideContents About Memory Management 4 At a Glance 4 Good Practices Prevent Memory-Related Problems 5 Use Analysis Tools to Debug Memory Problems 6 Memory Management Policy 7 Basic Memory Management Rules 7 A Simple Example 8 Use autorelease to Send a Deferred release 8 You Don’t Own Objects Returned by Reference 9 Implement dealloc to Relinquish Ownership of Objects 10 Core Foundation Uses Similar but Different Rules 11 Practical Memory Management 12 Use Accessor Methods to Make Memory Management Easier 12 Use Accessor Methods to Set Property Values 13 Don’t Use Accessor Methods in Initializer Methods and dealloc 14 Use Weak References to Avoid Retain Cycles 15 Avoid Causing Deallocation of Objects You’re Using 16 Don’t Use dealloc to Manage Scarce Resources 17 Collections Own the Objects They Contain 18 Ownership Policy Is Implemented Using Retain Counts 19 Using Autorelease Pool Blocks 20 About Autorelease Pool Blocks 20 Use Local Autorelease Pool Blocks to Reduce Peak Memory Footprint 21 Autorelease Pool Blocks and Threads 23 Document Revision History 24 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 2Figures Practical Memory Management 12 Figure 1 An illustration of cyclical references 15 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 3Application memory management is the process of allocating memory during your program’s runtime, using it, and freeing it when you are done with it. A well-written program uses as little memory as possible. In Objective-C, it can also be seen as a way of distributing ownership of limited memory resources among many pieces of data and code. When you have finished working through this guide, you will have the knowledge you need to manage your application’s memory by explicitly managing the life cycle of objects and freeing them when they are no longer needed. Although memory management istypically considered at the level of an individual object, your goal is actually to manage object graphs. You want to make sure that you have no more objects in memory than you actually need. alloc/init Retain count = 1 Destroyed Destroyed Class A retain 2 Class B 2 release 2 Class A release 1 Class B copy 1 release 0 0 Class C Class C At a Glance Objective-C provides two methods of application memory management. 1. In the method described in this guide, referred to as“manual retain-release” or MRR, you explicitly manage memory by keeping track of objects you own. This is implemented using a model, known as reference counting, that the Foundation class NSObject provides in conjunction with the runtime environment. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 4 About Memory Management2. In Automatic Reference Counting, or ARC, the system uses the same reference counting system as MRR, but it insertsthe appropriate memory management method callsfor you at compile-time. You are strongly encouraged to use ARC for new projects. If you use ARC, there is typically no need to understand the underlying implementation described in this document, although it may in some situations be helpful. For more about ARC, see Transitioning to ARC Release Notes. If you plan on writing code for iOS, you must use explicit memory management (the subject of this guide). Further, if you plan on writing library routines, plug-ins, orshared code—code that might be loaded into either a garbage-collection or non-garbage-collection process—you want to write your code using the memory-management techniques described throughout this guide. (Make sure that you then test your code in Xcode, with garbage collection disabled and enabled.) Good Practices Prevent Memory-Related Problems There are two main kinds or problem that result from incorrect memory management: ● Freeing or overwriting data that is still in use This causes memory corruption, and typically resultsin your application crashing, or worse, corrupted user data. ● Not freeing data that is no longer in use causes memory leaks A memory leak is where allocated memory is not freed, even though it is never used again. Leaks cause your application to use ever-increasing amounts of memory, which in turn may result in poor system performance or (in iOS) your application being terminated. Thinking about memory management from the perspective of reference counting, however, is frequently counterproductive, because you tend to consider memory management in terms of the implementation details rather than in terms of your actual goals. Instead, you should think of memory management from the perspective of object ownership and object graphs. Cocoa uses a straightforward naming convention to indicate when you own an object returned by a method. See “Memory Management Policy” (page 7). Although the basic policy is straightforward, there are some practical steps you can take to make managing memory easier, and to help to ensure your program remains reliable and robust while at the same time minimizing its resource requirements. See “Practical Memory Management” (page 12). About Memory Management At a Glance 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 5Autorelease pool blocks provide a mechanism whereby you can send an object a “deferred” release message. Thisis useful in situations where you want to relinquish ownership of an object, but want to avoid the possibility of it being deallocated immediately (such as when you return an object from a method). There are occasions when you might use your own autorelease pool blocks. See “Using Autorelease Pool Blocks” (page 20). Use Analysis Tools to Debug Memory Problems To identify problems with your code at compile time, you can use the Clang Static Analyzer that is built into Xcode. If memory management problems do nevertheless arise, there are other tools and techniques you can use to identify and diagnose the issues. ● Many of the tools and techniques are described in Technical Note TN2239, iOS Debugging Magic , in particular the use of NSZombie to help find over-released object. ● You can use Instruments to track reference counting events and look for memory leaks. See “Collecting Data on Your App”. About Memory Management At a Glance 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 6The basic model used for memory management in a reference-counted environment is provided by a combination of methods defined in the NSObject protocol and a standard method naming convention. The NSObject class also defines a method, dealloc, that is invoked automatically when an object is deallocated. This article describes all the basic rules you need to know to manage memory correctly in a Cocoa program, and provides some examples of correct usage. Basic Memory Management Rules The memory management model is based on object ownership. Any object may have one or more owners. Aslong as an object has at least one owner, it continuesto exist. If an object has no owners, the runtime system destroys it automatically. To make sure it is clear when you own an object and when you do not, Cocoa sets the following policy: ● You own any object you create You create an object using a method whose name begins with “alloc”, “new”, “copy”, or “mutableCopy” (for example, alloc, newObject, or mutableCopy). ● You can take ownership of an object using retain A received object is normally guaranteed to remain valid within the method it was received in, and that method may also safely return the object to its invoker. You use retain in two situations: (1) In the implementation of an accessor method or an init method, to take ownership of an object you want to store as a property value; and (2) To prevent an object from being invalidated as a side-effect of some other operation (as explained in “Avoid Causing Deallocation of Objects You’re Using” (page 16)). ● When you no longer need it, you must relinquish ownership of an object you own You relinquish ownership of an object by sending it a release message or an autorelease message. In Cocoa terminology, relinquishing ownership of an object is therefore typically referred to as “releasing” an object. ● You must not relinquish ownership of an object you do not own This is just corollary of the previous policy rules, stated explicitly. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 7 Memory Management PolicyA Simple Example To illustrate the policy, consider the following code fragment: { Person *aPerson = [[Person alloc] init]; // ... NSString *name = aPerson.fullName; // ... [aPerson release]; } The Person object is created using the alloc method, so it is subsequently sent a release message when it is no longer needed. The person’s name is not retrieved using any of the owning methods, so it is not sent a release message. Notice, though, that the example uses release rather than autorelease. Use autorelease to Send a Deferred release You use autorelease when you need to send a deferred release message—typically when returning an object from a method. For example, you could implement the fullName method like this: - (NSString *)fullName { NSString *string = [[[NSString alloc] initWithFormat:@"%@ %@", self.firstName, self.lastName] autorelease]; return string; } You own the string returned by alloc. To abide by the memory management rules, you must relinquish ownership of the string before you lose the reference to it. If you use release, however, the string will be deallocated before it is returned (and the method would return an invalid object). Using autorelease, you signify that you want to relinquish ownership, but you allow the caller of the method to use the returned string before it is deallocated. You could also implement the fullName method like this: - (NSString *)fullName { NSString *string = [NSString stringWithFormat:@"%@ %@", Memory Management Policy Basic Memory Management Rules 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 8self.firstName, self.lastName]; return string; } Following the basic rules, you don’t own the string returned by stringWithFormat:,so you can safely return the string from the method. By way of contrast, the following implementation is wrong : - (NSString *)fullName { NSString *string = [[NSString alloc] initWithFormat:@"%@ %@", self.firstName, self.lastName]; return string; } According to the naming convention, there is nothing to denote that the caller of the fullName method owns the returned string. The caller therefore has no reason to release the returned string, and it will thus be leaked. You Don’t Own Objects Returned by Reference Some methods in Cocoa specify that an object is returned by reference (that is, they take an argument of type ClassName ** or id *). A common pattern is to use an NSError object that contains information about an error if one occurs, as illustrated by initWithContentsOfURL:options:error: (NSData) and initWithContentsOfFile:encoding:error: (NSString). In these cases, the same rules apply as have already been described. When you invoke any of these methods, you do not create the NSError object, so you do not own it. There is therefore no need to release it, as illustrated in this example: NSString *fileName = <#Get a file name#>; NSError *error; NSString *string = [[NSString alloc] initWithContentsOfFile:fileName encoding:NSUTF8StringEncoding error:&error]; if (string == nil) { // Deal with error... } // ... [string release]; Memory Management Policy Basic Memory Management Rules 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 9Implement dealloc to Relinquish Ownership of Objects The NSObject class defines a method, dealloc, that is invoked automatically when an object has no owners and its memory is reclaimed—in Cocoa terminology it is “freed” or “deallocated.”. The role of the dealloc method is to free the object's own memory, and to dispose of any resources it holds, including ownership of any object instance variables. The following example illustrates how you might implement a dealloc method for a Person class: @interface Person : NSObject @property (retain) NSString *firstName; @property (retain) NSString *lastName; @property (assign, readonly) NSString *fullName; @end @implementation Person // ... - (void)dealloc [_firstName release]; [_lastName release]; [super dealloc]; } @end Memory Management Policy Implement dealloc to Relinquish Ownership of Objects 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 10Important: Never invoke another object’s dealloc method directly. You must invoke the superclass’s implementation at the end of your implementation. You should not tie management of system resources to object lifetimes; see “Don’t Use dealloc to Manage Scarce Resources” (page 17). When an application terminates, objects may not be sent a dealloc message. Because the process’s memory is automatically cleared on exit, it is more efficient simply to allow the operating system to clean up resources than to invoke all the memory management methods. Core Foundation Uses Similar but Different Rules There are similar memory management rules for Core Foundation objects (see Memory Management Programming Guide for Core Foundation ). The naming conventions for Cocoa and Core Foundation, however, are different. In particular, Core Foundation’s Create Rule (see “The Create Rule” in Memory Management Programming Guide for Core Foundation ) does not apply to methods that return Objective-C objects. For example, in the following code fragment, you are not responsible for relinquishing ownership of myInstance: MyClass *myInstance = [MyClass createInstance]; Memory Management Policy Core Foundation Uses Similar but Different Rules 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 11Although the fundamental concepts described in “Memory Management Policy” (page 7) are straightforward, there are some practical steps you can take to make managing memory easier, and to help to ensure your program remains reliable and robust while at the same time minimizing its resource requirements. Use Accessor Methods to Make Memory Management Easier If your class has a property that is an object, you must make sure that any object that is set as the value is not deallocated while you’re using it. You must therefore claim ownership of the object when it is set. You must also make sure you then relinquish ownership of any currently-held value. Sometimes it might seem tedious or pedantic, but if you use accessor methods consistently, the chances of having problems with memory management decrease considerably. If you are using retain and release on instance variables throughout your code, you are almost certainly doing the wrong thing. Consider a Counter object whose count you want to set. @interface Counter : NSObject @property (nonatomic, retain) NSNumber *count; @end; The property declares two accessor methods. Typically, you should ask the compiler to synthesize the methods; however, it’s instructive to see how they might be implemented. In the “get” accessor, you just return the synthesized instance variable, so there is no need for retain or release: - (NSNumber *)count { return _count; } 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 12 Practical Memory ManagementIn the “set” method, if everyone else is playing by the same rules you have to assume the new count may be disposed of at any time so you have to take ownership of the object—by sending it a retain message—to ensure it won’t be. You must also relinquish ownership of the old count object here by sending it a release message. (Sending a message to nil is allowed in Objective-C, so the implementation will still work if _count hasn’t yet been set.) You must send this after [newCount retain] in case the two are the same object—you don’t want to inadvertently cause it to be deallocated. - (void)setCount:(NSNumber *)newCount { [newCount retain]; [_count release]; // Make the new assignment. _count = newCount; } Use Accessor Methods to Set Property Values Suppose you want to implement a method to reset the counter. You have a couple of choices. The first implementation creates the NSNumber instance with alloc, so you balance that with a release. - (void)reset { NSNumber *zero = [[NSNumber alloc] initWithInteger:0]; [self setCount:zero]; [zero release]; } The second uses a convenience constructor to create a new NSNumber object. There is therefore no need for retain or release messages - (void)reset { NSNumber *zero = [NSNumber numberWithInteger:0]; [self setCount:zero]; } Note that both use the set accessor method. The following will almost certainly work correctly for simple cases, but as tempting as it may be to eschew accessor methods, doing so will almost certainly lead to a mistake atsome stage (for example, when you forget to retain or release, or if the memory management semantics for the instance variable change). Practical Memory Management Use Accessor Methods to Make Memory Management Easier 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 13- (void)reset { NSNumber *zero = [[NSNumber alloc] initWithInteger:0]; [_count release]; _count = zero; } Note also that if you are using key-value observing, then changing the variable in this way is not KVO compliant. Don’t Use Accessor Methods in Initializer Methods and dealloc The only places you shouldn’t use accessor methods to set an instance variable are in initializer methods and dealloc. To initialize a counter object with a number object representing zero, you might implement an init method as follows: - init { self = [super init]; if (self) { _count = [[NSNumber alloc] initWithInteger:0]; } return self; } To allow a counter to be initialized with a count other than zero, you might implement an initWithCount: method as follows: - initWithCount:(NSNumber *)startingCount { self = [super init]; if (self) { _count = [startingCount copy]; } return self; } Since the Counter class has an object instance variable, you must also implement a dealloc method. Itshould relinquish ownership of any instance variables by sending them a release message, and ultimately it should invoke super’s implementation: Practical Memory Management Use Accessor Methods to Make Memory Management Easier 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 14- (void)dealloc { [_count release]; [super dealloc]; } Use Weak References to Avoid Retain Cycles Retaining an object creates a strong reference to that object. An object cannot be deallocated until all of its strong references are released. A problem, known as a retain cycle, can therefore arise if two objects may have cyclical references—that is, they have a strong reference to each other (either directly, or through a chain of other objects each with a strong reference to the next leading back to the first). The object relationships shown in Figure 1 (page 15) illustrate a potential retain cycle. The Document object has a Page object for each page in the document. Each Page object has a property that keeps track of which document it is in. If the Document object has a strong reference to the Page object and the Page object has a strong reference to the Document object, neither object can ever be deallocated. The Document’s reference count cannot become zero until the Page object is released, and the Page object won’t be released until the Document object is deallocated. Figure 1 An illustration of cyclical references text parent parent paragraph Paragraph Page page Document retain don’t retain don’t retain retain Practical Memory Management Use Weak References to Avoid Retain Cycles 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 15The solution to the problem of retain cycles is to use weak references. A weak reference is a non-owning relationship where the source object does not retain the object to which it has a reference. To keep the object graph intact, however, there must be strong references somewhere (if there were only weak references, then the pages and paragraphs might not have any owners and so would be deallocated). Cocoa establishes a convention, therefore, that a “parent” object should maintain strong references to its “children,” and that the children should have weak references to their parents. So, in Figure 1 (page 15) the document object has a strong reference to (retains) its page objects, but the page object has a weak reference to (does not retain) the document object. Examples of weak references in Cocoa include, but are not restricted to, table data sources, outline view items, notification observers, and miscellaneous targets and delegates. You need to be careful about sending messages to objects for which you hold only a weak reference. If you send a message to an object after it has been deallocated, your application will crash. You must have well-defined conditions for when the object is valid. In most cases, the weak-referenced object is aware of the other object’s weak reference to it, asisthe case for circular references, and isresponsible for notifying the other object when it deallocates. For example, when you register an object with a notification center, the notification centerstores a weak reference to the object and sends messages to it when the appropriate notifications are posted. When the object is deallocated, you need to unregister it with the notification center to prevent the notification center from sending any further messages to the object, which no longer exists. Likewise, when a delegate object is deallocated, you need to remove the delegate link by sending a setDelegate: message with a nil argument to the other object. These messages are normally sent from the object’s dealloc method. Avoid Causing Deallocation of Objects You’re Using Cocoa’s ownership policy specifies that received objects should typically remain valid throughout the scope of the calling method. It should also be possible to return a received object from the current scope without fear of it being released. It should not matter to your application that the getter method of an object returns a cached instance variable or a computed value. What matters is that the object remains valid for the time you need it. There are occasional exceptions to this rule, primarily falling into one of two categories. 1. When an object is removed from one of the fundamental collection classes. heisenObject = [array objectAtIndex:n]; [array removeObjectAtIndex:n]; // heisenObject could now be invalid. Practical Memory Management Avoid Causing Deallocation of Objects You’re Using 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 16When an object is removed from one of the fundamental collection classes, it is sent a release (rather than autorelease) message. If the collection was the only owner of the removed object, the removed object (heisenObject in the example ) is then immediately deallocated. 2. When a “parent object” is deallocated. id parent = <#create a parent object#>; // ... heisenObject = [parent child] ; [parent release]; // Or, for example: self.parent = nil; // heisenObject could now be invalid. In some situations you retrieve an object from another object, and then directly or indirectly release the parent object. If releasing the parent causes it to be deallocated, and the parent was the only owner of the child, then the child (heisenObject in the example) will be deallocated at the same time (assuming that it is sent a release rather than an autorelease message in the parent’s dealloc method). To protect against these situations, you retain heisenObject upon receiving it and you release it when you have finished with it. For example: heisenObject = [[array objectAtIndex:n] retain]; [array removeObjectAtIndex:n]; // Use heisenObject... [heisenObject release]; Don’t Use dealloc to Manage Scarce Resources You should typically not manage scarce resources such as file descriptors, network connections, and buffers or caches in a dealloc method. In particular, you should not design classes so that dealloc will be invoked when you think it will be invoked. Invocation of dealloc might be delayed or sidestepped, either because of a bug or because of application tear-down. Instead, if you have a class whose instances manage scarce resources, you should design your application such that you know when you no longer need the resources and can then tell the instance to “clean up” at that point. You would typically then release the instance, and dealloc would follow, but you will not suffer additional problems if it does not. Problems may arise if you try to piggy-back resource management on top of dealloc. For example: Practical Memory Management Don’t Use dealloc to Manage Scarce Resources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 171. Order dependencies on object graph tear-down. The object graph tear-down mechanism is inherently non-ordered. Although you might typically expect—and get—a particular order, you are introducing fragility. If an object is unexpectedly autoreleased rather than released for example, the tear-down order may change, which may lead to unexpected results. 2. Non-reclamation of scarce resources. Memory leaks are bugsthatshould be fixed, but they are generally not immediately fatal. Ifscarce resources are not released when you expect them to be released, however, you may run into more serious problems. If your application runs out of file descriptors, for example, the user may not be able to save data. 3. Cleanup logic being executed on the wrong thread. If an object is autoreleased at an unexpected time, it will be deallocated on whatever thread’s autorelease pool block it happens to be in. This can easily be fatal for resources that should only be touched from one thread. Collections Own the Objects They Contain When you add an object to a collection (such as an array, dictionary, or set), the collection takes ownership of it. The collection will relinquish ownership when the object isremoved from the collection or when the collection is itself released. Thus, for example, if you want to create an array of numbers you might do either of the following: NSMutableArray *array = <#Get a mutable array#>; NSUInteger i; // ... for (i = 0; i < 10; i++) { NSNumber *convenienceNumber = [NSNumber numberWithInteger:i]; [array addObject:convenienceNumber]; } In this case, you didn’t invoke alloc, so there’s no need to call release. There is no need to retain the new numbers (convenienceNumber), since the array will do so. NSMutableArray *array = <#Get a mutable array#>; NSUInteger i; // ... for (i = 0; i < 10; i++) { Practical Memory Management Collections Own the Objects They Contain 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 18NSNumber *allocedNumber = [[NSNumber alloc] initWithInteger:i]; [array addObject:allocedNumber]; [allocedNumber release]; } In this case, you do need to send allocedNumber a release message within the scope of the for loop to balance the alloc. Since the array retained the number when it was added by addObject:, it will not be deallocated while it’s in the array. To understand this, put yourself in the position of the person who implemented the collection class. You want to make sure that no objects you’re given to look after disappear out from under you, so you send them a retain message as they’re passed in. If they’re removed, you have to send a balancing release message, and any remaining objects should be sent a release message during your own dealloc method. Ownership Policy Is Implemented Using Retain Counts The ownership policy is implemented through reference counting—typically called “retain count” after the retain method. Each object has a retain count. ● When you create an object, it has a retain count of 1. ● When you send an object a retain message, its retain count is incremented by 1. ● When you send an object a release message, its retain count is decremented by 1. When you send an object a autorelease message, its retain count is decremented by 1 at the end of the current autorelease pool block. ● If an object’s retain count is reduced to zero, it is deallocated. Important: There should be no reason to explicitly ask an object what itsretain count is(see retainCount). The result is often misleading, as you may be unaware of what framework objects have retained an object in which you are interested. In debugging memory management issues, you should be concerned only with ensuring that your code adheres to the ownership rules. Practical Memory Management Ownership Policy Is Implemented Using Retain Counts 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 19Autorelease pool blocks provide a mechanism whereby you can relinquish ownership of an object, but avoid the possibility of it being deallocated immediately (such as when you return an object from a method). Typically, you don’t need to create your own autorelease pool blocks, but there are some situations in which either you must or it is beneficial to do so. About Autorelease Pool Blocks An autorelease pool block is marked using @autoreleasepool, as illustrated in the following example: @autoreleasepool { // Code that creates autoreleased objects. } At the end of the autorelease pool block, objects that received an autorelease message within the block are sent a release message—an object receives a release message for each time it wassent an autorelease message within the block. Like any other code block, autorelease pool blocks can be “nested:” @autoreleasepool { // . . . @autoreleasepool { // . . . } . . . } (You wouldn’t normally see code exactly as above; typically code within an autorelease pool block in one source file would invoke code in another source file that is contained within another autorelease pool block.) For a given autorelease message, the corresponding release message issent at the end of the autorelease pool block in which the autorelease message was sent. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 20 Using Autorelease Pool BlocksCocoa always expects code to be executed within an autorelease pool block, otherwise autoreleased objects do not get released and your application leaks memory. (If you send an autorelease message outside of an autorelease pool block, Cocoa logs a suitable error message.) The AppKit and UIKit frameworks process each event-loop iteration (such as a mouse down event or a tap) within an autorelease pool block. Therefore you typically do not have to create an autorelease pool block yourself, or even see the code that is used to create one. There are, however, three occasions when you might use your own autorelease pool blocks: ● If you are writing a program that is not based on a UI framework, such as a command-line tool. ● If you write a loop that creates many temporary objects. You may use an autorelease pool block inside the loop to dispose of those objects before the next iteration. Using an autorelease pool block in the loop helps to reduce the maximum memory footprint of the application. ● If you spawn a secondary thread. You must create your own autorelease pool block as soon as the thread begins executing; otherwise, your application will leak objects. (See “Autorelease Pool Blocks and Threads” (page 23) for details.) Use Local Autorelease Pool Blocksto Reduce Peak Memory Footprint Many programs create temporary objects that are autoreleased. These objects add to the program’s memory footprint until the end of the block. In many situations, allowing temporary objects to accumulate until the end of the current event-loop iteration does not result in excessive overhead; in some situations, however, you may create a large number of temporary objects that add substantially to memory footprint and that you want to dispose of more quickly. In these latter cases, you can create your own autorelease pool block. At the end of the block, the temporary objects are released, which typically results in their deallocation thereby reducing the program’s memory footprint. The following example shows how you might use a local autorelease pool block in a for loop. NSArray *urls = <# An array of file URLs #>; for (NSURL *url in urls) { @autoreleasepool { NSError *error; NSString *fileContents = [NSString stringWithContentsOfURL:url encoding:NSUTF8StringEncoding error:&error]; /* Process the string, creating and autoreleasing more objects. */ } Using Autorelease Pool Blocks Use Local Autorelease Pool Blocks to Reduce Peak Memory Footprint 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 21} The for loop processes one file at a time. Any object (such as fileContents)sent an autorelease message inside the autorelease pool block is released at the end of the block. After an autorelease pool block, you should regard any object that was autoreleased within the block as “disposed of.” Do not send a message to that object or return it to the invoker of your method. If you must use a temporary object beyond an autorelease pool block, you can do so by sending a retain message to the object within the block and then send it autorelease after the block, as illustrated in this example: – (id)findMatchingObject:(id)anObject { id match; while (match == nil) { @autoreleasepool { /* Do a search that creates a lot of temporary objects. */ match = [self expensiveSearchForObject:anObject]; if (match != nil) { [match retain]; /* Keep match around. */ } } } return [match autorelease]; /* Let match go and return it. */ } Sending retain to match within the autorelease pool block the and sending autorelease to it after the autorelease pool block extends the lifetime of match and allows it to receive messages outside the loop and be returned to the invoker of findMatchingObject:. Using Autorelease Pool Blocks Use Local Autorelease Pool Blocks to Reduce Peak Memory Footprint 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 22Autorelease Pool Blocks and Threads Each thread in a Cocoa application maintains its own stack of autorelease pool blocks. If you are writing a Foundation-only program or if you detach a thread, you need to create your own autorelease pool block. If your application or thread is long-lived and potentially generates a lot of autoreleased objects, you should use autorelease pool blocks (like AppKit and UIKit do on the main thread); otherwise, autoreleased objects accumulate and your memory footprint grows. If your detached thread does not make Cocoa calls, you do not need to use an autorelease pool block. Note: If you create secondary threads using the POSIX thread APIsinstead of NSThread, you cannot use Cocoa unless Cocoa is in multithreading mode. Cocoa enters multithreading mode only after detaching its first NSThread object. To use Cocoa on secondary POSIX threads, your application must first detach at least one NSThread object, which can immediately exit. You can test whether Cocoa is in multithreading mode with the NSThread class method isMultiThreaded. Using Autorelease Pool Blocks Autorelease Pool Blocks and Threads 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 23This table describes the changes to Advanced Memory Management Programming Guide . Date Notes 2012-07-17 Updated to describe autorelease in terms of @autoreleasepool blocks. Updated to reflect new status as a consequence of the introduction of ARC. 2011-09-28 2011-03-24 Major revision for clarity and conciseness. 2010-12-21 Clarified the naming rule for mutable copy. Minor rewording tomemorymanagementfundamental rule,to emphasize simplicity. Minor additions to Practical Memory Management. 2010-06-24 Updated the description of handling memory warningsfor iOS 3.0; partially rewrote "Object Ownership and Disposal." 2010-02-24 Augmented section on accessor methods in Practical Memory Management. 2009-10-21 2009-08-18 Added links to related concepts. 2009-07-23 Updated guidance for declaring outlets on OS X. 2009-05-06 Corrected typographical errors. 2009-03-04 Corrected typographical errors. 2009-02-04 Updated "Nib Objects" article. Added section on use of autorelease pools in a garbage collected environment. 2008-11-19 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 24 Document Revision HistoryDate Notes 2008-10-15 Corrected missing image. 2008-02-08 Corrected a broken link to the "Carbon-Cocoa Integration Guide." 2007-12-11 Corrected typographical errors. 2007-10-31 Updated for OS X v10.5. Corrected minor typographical errors. 2007-06-06 Corrected minor typographical errors. 2007-05-03 Corrected typographical errors. 2007-01-08 Added article on memory management of nib files. 2006-06-28 Added a note about dealloc and application termination. Reorganized articles in this document to improve flow; updated "Object Ownership and Disposal." 2006-05-23 Clarified discussion of object ownership and dealloc. Moved discussion of accessor methods to a separate article. 2006-03-08 2006-01-10 Corrected typographical errors. Updated title from"Memory Management." 2004-08-31 Changed Related Topics links and updated topic introduction. Expanded description of what gets released when an autorelease pool is released to include both explicitly and implicitly autoreleased objects in “Using Autorelease Pool Blocks” (page 20). 2003-06-06 Revision history was added to existing topic. It will be used to record changes to the content of the topic. 2002-11-12 Document Revision History 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 25Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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. 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, Carbon, Cocoa, Instruments, Mac, Objective-C, OS X, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. 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.ASARESULT, THISDOCUMENT 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. iOS App Programming GuideContents About iOS App Programming 8 At a Glance 8 Translate Your Initial Idea into an Implementation Plan 8 UIKit Provides the Core of Your App 8 Apps Must Behave Differently in the Foreground and Background 9 iCloud Affects the Design of Your Data Model and UI Layers 9 Apps Require Some Specific Resources 9 Apps Should Restore Their Previous UI State at Launch Time 9 Many App Behaviors Can Be Customized 10 Apps Must Be Tuned for Performance 10 The iOS Environment Affects Many App Behaviors 10 How to Use This Document 10 Prerequisites 11 See Also 11 App Design Basics 12 Doing Your Initial Design 12 Learning the Fundamental iOS Design Patterns and Techniques 13 Translating Your Initial Design into an Action Plan 13 Starting the App Creation Process 14 Core App Objects 17 The Core Objects of Your App 17 The Data Model 20 Defining a Custom Data Model 21 Defining a Structured Data Model Using Core Data 24 Defining a Document-Based Data Model 24 Integrating iCloud Support Into Your App 26 The User Interface 26 Building an Interface Using UIKit Views 27 Building an Interface Using Views and OpenGL ES 29 The App Bundle 30 App States and Multitasking 33 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Managing App State Changes 34 The App Launch Cycle 36 Responding to Interruptions 42 Moving to the Background 44 Returning to the Foreground 48 App Termination 51 The Main Run Loop 52 Background Execution and Multitasking 54 Determining Whether Multitasking Is Available 54 Executing a Finite-Length Task in the Background 55 Scheduling the Delivery of Local Notifications 56 Implementing Long-Running Background Tasks 58 Being a Responsible Background App 63 Opting out of Background Execution 65 Concurrency and Secondary Threads 66 State Preservation and Restoration 67 The Preservation and Restoration Process 67 Flow of the Preservation Process 74 Flow of the Restoration Process 75 What Happens When You Exclude Groups of View Controllers? 78 Checklist for Implementing State Preservation and Restoration 81 Enabling State Preservation and Restoration in Your App 82 Preserving the State of Your View Controllers 82 Marking Your View Controllers for Preservation 83 Restoring Your View Controllers at Launch Time 83 Encoding and Decoding Your View Controller’s State 85 Preserving the State of Your Views 86 UIKit VIews with Preservable State 87 Preserving the State of a Custom View 88 Implementing Preservation-Friendly Data Sources 89 Preserving Your App’s High-Level State 89 Mixing UIKit’s State Preservation with Your Own Custom Mechanisms 90 Tips for Saving and Restoring State Information 91 App-Related Resources 93 App Store Required Resources 93 The Information Property List File 93 Declaring the Required Device Capabilities 94 Declaring Your App’s Supported Document Types 97 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsApp Icons 98 App Launch (Default) Images 100 Providing Launch Images for Different Orientations 101 Providing Device-Specific Launch Images 103 Providing Launch Images for Custom URL Schemes 103 The Settings Bundle 104 Localized Resource Files 105 Loading Resources Into Your App 106 Advanced App Tricks 108 Creating a Universal App 108 Updating Your Info.plist Settings 108 Implementing Your View Controllers and Views 109 Updating Your Resource Files 110 Using Runtime Checks to Create Conditional Code Paths 110 Supporting Multiple Versions of iOS 111 Launching in Landscape Mode 112 Installing App-Specific Data Files at First Launch 113 Protecting Data Using On-Disk Encryption 113 Tips for Developing a VoIP App 115 Configuring Sockets for VoIP Usage 116 Installing a Keep-Alive Handler 117 Configuring Your App’s Audio Session 117 Using the Reachability Interfaces to Improve the User Experience 118 Communicating with Other Apps 118 Implementing Custom URL Schemes 119 Registering Custom URL Schemes 119 Handling URL Requests 120 Showing and Hiding the Keyboard 125 Turning Off Screen Locking 126 Performance Tuning 127 Make App Backups More Efficient 127 App Backup Best Practices 127 Files Saved During App Updates 128 Use Memory Efficiently 129 Observe Low-Memory Warnings 129 Reduce Your App’s Memory Footprint 130 Allocate Memory Wisely 131 Move Work off the Main Thread 131 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFloating-Point Math Considerations 132 Reduce Power Consumption 132 Tune Your Code 134 Improve File Access Times 134 Tune Your Networking Code 135 Tips for Efficient Networking 135 Using Wi-Fi 136 The Airplane Mode Alert 136 The iOS Environment 137 Specialized System Behaviors 137 The Virtual Memory System 137 The Automatic Sleep Timer 137 Multitasking Support 138 Security 138 The App Sandbox 138 Keychain Data 140 Document Revision History 141 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5 ContentsFigures, Tables, and Listings Core App Objects 17 Figure 2-1 Key objects in an iOS app 18 Figure 2-2 Using documents to manage the content of files 25 Figure 2-3 Building your interface using view objects 28 Figure 2-4 Building your interface using OpenGL ES 29 Table 2-1 The role of objects in an iOS app 18 Table 2-2 Data classes in the Foundation framework 21 Table 2-3 A typical app bundle 30 Listing 2-1 Definition of a custom data object 23 App States and Multitasking 33 Figure 3-1 State changes in an iOS app 35 Figure 3-2 Launching an app into the foreground 37 Figure 3-3 Launching an app into the background 38 Figure 3-4 Handling alert-based interruptions 42 Figure 3-5 Moving from the foreground to the background 45 Figure 3-6 Transitioning from the background to the foreground 48 Figure 3-7 Processing events in the main run loop 52 Table 3-1 App states 34 Table 3-2 Notifications delivered to waking apps 49 Table 3-3 Common types of events for iOS apps 53 Listing 3-1 The main function of an iOS app 39 Listing 3-2 Checking for background support in earlier versions of iOS 54 Listing 3-3 Starting a background task at quit time 55 Listing 3-4 Scheduling an alarm notification 57 State Preservation and Restoration 67 Figure 4-1 A sample view controller hierarchy 69 Figure 4-2 Adding restoration identifies to view controllers 72 Figure 4-3 High-level flow interface preservation 74 Figure 4-4 High-level flow for restoring your user interface 76 Figure 4-5 Excluding view controllers from the automatic preservation process 79 Figure 4-6 Loading the default set of view controllers 80 Figure 4-7 UIKit handles the root view controller 90 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6Listing 4-1 Creating a new view controller during restoration 84 Listing 4-2 Encoding and decoding a view controller’s state. 86 Listing 4-3 Preserving the selection of a custom text view 88 App-Related Resources 93 Figure 5-1 Custom preferences displayed by the Settings app 104 Table 5-1 Dictionary keys for the UIRequiredDeviceCapabilities key 95 Table 5-2 Sizes for images in the CFBundleIcons key 98 Table 5-3 Typical launch image dimensions 100 Table 5-4 Launch image orientation modifiers 101 Advanced App Tricks 108 Figure 6-1 Defining a custom URL scheme in the Info.plist file 120 Figure 6-2 Launching an app to open a URL 122 Figure 6-3 Waking a background app to open a URL 123 Table 6-1 Configuring stream interfaces for VoIP usage 116 Table 6-2 Keys and values of the CFBundleURLTypes property 120 Listing 6-1 Handling a URL request based on a custom scheme 124 Performance Tuning 127 Table 7-1 Tips for reducing your app’s memory footprint 130 Table 7-2 Tips for allocating memory 131 The iOS Environment 137 Figure A-1 Sandbox directories in iOS 139 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7 Figures, Tables, and ListingsThis document is the starting point for creating iOS apps. It describes the fundamental architecture of iOS apps, including how the code you write fits together with the code provided by iOS. This document also offers practical guidance to help you make better choices during your design and planning phase and guides you to the other documents in the iOS developer library that contain more detailed information about how to address a specific task. The contents of this document apply to all iOS apps running on all types of iOS devices, including iPad, iPhone, and iPod touch. Note: Development of iOS apps requires an Intel-based Macintosh computer with the iOS SDK installed. For information about how to get the iOS SDK, go to the iOS Dev Center. At a Glance The starting point for any new app isidentifying the design choices you need to make and understanding how those choices map to an appropriate implementation. Translate Your Initial Idea into an Implementation Plan Every great iOS app starts with a great idea, but translating that idea into actions requires some planning. Every iOS app relies heavily on design patterns, and those design patterns influence much of the code you need to write. So before you write any code, take the time to explore the possible techniques and technologies available for writing that code. Doing so can save you a lot of time and frustration. Relevant Chapter: “App Design Basics” (page 12) UIKit Provides the Core of Your App The core infrastructure of an iOS app is built from objectsin the UIKit framework. The objectsin thisframework provide all of the support for handling events, displaying content on the screen, and interacting with the rest of the system. Understanding the role these objects play, and how you modify them to customize the default app behavior, is therefore very important for writing apps quickly and correctly. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8 About iOS App ProgrammingRelevant Chapter: “Core App Objects” (page 17) Apps Must Behave Differently in the Foreground and Background An iOS device runs multiple apps simultaneously but only one app—the foreground app—has the user’s attention at any given time. The current foreground app is the only app allowed to present a user interface and respond to touch events. Other apps remain in the background, usually asleep but sometimes running additional code. Transitioning between the foreground and background states involves changing several aspects of your app’s behavior. Relevant Chapter: “App States and Multitasking” (page 33) iCloud Affects the Design of Your Data Model and UI Layers iCloud allows you to share the user’s data among multiple instances of your app running on different iOS and Mac OS X devices. Incorporating support for iCloud into your app involves changing many aspects of how you manage your files. Because files in iCloud are accessible by more than just your app, all file operations must be synchronized to prevent data corruption. And depending on your app and how it presents its data, iCloud can also require changes to portions of your user interface. Relevant Chapter: “Integrating iCloud Support Into Your App” (page 26) Apps Require Some Specific Resources There are some resources that must be present in all iOS apps. Most apps include images, sounds, and other types of resources for presenting the app’s content but the App Store also requires some specific resources be present. The reason is that iOS uses several specific resources when presenting your app to the user and when coordinating interactions with other parts of the system. So these resources are there to improve the overall user experience. Relevant Chapter: “App-Related Resources” (page 93) Apps Should Restore Their Previous UI State at Launch Time At launch time, your app should restore its user interface to the state it was in when it was last used. During normal use, the system controls when apps are terminated. Normally when this happens, the app displays its default user interface when it is relaunched. With state restoration, UIKit helps your app restore your app’s interface to its previous state, which promotes a consistent user experience. About iOS App Programming At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9Relevant Chapter: “State Preservation and Restoration” (page 67) Many App Behaviors Can Be Customized The core architecture of all apps may be the same, but there are still ways for you to tweak the high-level design of your app. Some of these tweaks are how you add specific high-level features, such as data protection and URL handling. Others affect the design of specific types of apps, such as VoIP apps. Relevant Chapter: “Advanced App Tricks” (page 108) Apps Must Be Tuned for Performance Great apps are always tuned for the best possible performance. For iOS apps, performance means more than just writing fast code. It often means writing better code so that your user interface remains responsive to user input, your app does not degrade battery life significantly, and your app does not impact othersystem resources. Before you can tune your code, though, learn about the types of changes that are likely to provide the most benefit. Relevant Chapter: “Performance Tuning” (page 127) The iOS Environment Affects Many App Behaviors There are aspects of iOS itself that impact how you design and write applications. Because iOS is built for mobile devices, it takes a more active role in providing security for apps. Other system behaviors also affect everything from how memory is managed to how the system responds to hardware input. All of these system behaviors affect the way you design your apps. Relevant Appendix: “The iOS Environment” (page 137) How to Use This Document This document providesimportant information about the core objects of your app and how they work together. This document does not address the creation of any specific type of iOS app. Instead, it provides a tour of the architecture that is common to all iOS apps and highlights key places where you can modify that architecture to meet your needs. Whenever possible, the document also offers tips and guidance about ways to implement features related to the core app architecture. About iOS App Programming How to Use This Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10Prerequisites This document is the entry-point guide for designing an iOS app. This guide also covers many of the practical aspects involved with implementing your app. However, this book assumes that you have already installed the iOS SDK and configured your development environment. You must perform those steps before you can start writing and building iOS apps. If you are new to iOS app development, read Start Developing iOS Apps Today . This document offers a step-by-step introduction to the development process to help you get up to speed quickly. It also includes a hands-on tutorial that walks you through the app-creation process from start to finish, showing you how to create a simple app and get it running quickly. See Also For additional information related to app design, see the following documents: ● For guidance about how to design an iOS app, read iOS Human Interface Guidelines. This book provides you with tips and guidance about how to create a great experience for users of your app. It also conveys the basic design philosophy surrounding iOS apps. ● If you are not sure what is possible in an iOS app, read iOS Technology Overview. This book provides a summary of iOS technologies and the situations where you might want to use them. This book is not required reading but is a good reference during the brainstorming phase of your project. About iOS App Programming Prerequisites 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11If you are a new to developing iOS apps, you might be wondering where the app development process starts. After devising your initial idea for an app, you need to turn that idea into an action plan for implementing your app. From a design perspective, you need to make some high-level decisions about the best course of action for implementing your ideas. You also need to set up your initial Xcode project in a way that makes it easy to proceed with development. If you are new to developing iOS apps altogether, spend some time familiarizing yourself with the basic concepts. There are tutorials to help you jump right in if you want to start writing code, but iOS is a system built from basic design patterns. Taking a little bit of time to learn those patterns will help you tremendously later. Doing Your Initial Design There are many ways to design an app, and many of the best approaches do not involve writing any code. A great app starts with a great idea that you then expand into a more full-featured product description. Early in the design phase, it helps to understand just what you want your app to do. Write down the set of high-level features that would be required to implement your idea. Prioritize those features based on what you think your users will need. Do a little research into iOS itself so that you understand its capabilities and how you might be able to use them to achieve your goals. And sketch out some rough interface designs on paper to visualize how your app might look. The goal of your initial design is to answer some very important questions about your app. The set of features and the rough design of your interface help you think about what will be required later when you start writing code. At some point, you need to translate the information displayed by your app into a set of data objects. Similarly, the look of your app has an overwhelming influence on the choices you must make when implementing your user interface code. Doing your initial design on paper (as opposed to on the computer) gives you the freedom to come up with answers that are not limited by what is easy to do. Of course, the most important thing you can do before starting your initial design is read iOS Human Interface Guidelines. That book describes several strategies for doing your initial design. It also offers tips and guidance about how to create apps that work well in iOS. You might also read iOS Technology Overview to understand how the capabilities of iOS and how you might use those capabilities to achieve your design goals. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12 App Design BasicsLearning the Fundamental iOS Design Patterns and Techniques No matter what type of app you are creating, there are a few fundamental design patterns and techniques that you must know before you start writing code. In iOS, the system frameworks provide critical infrastructure for your app and in most cases are the only way to access the underlying hardware. In turn, the frameworks use many specific design patterns and assume that you are familiar with them. Understanding these design patterns is therefore an important first step to understanding how the system can help you develop your app. The most important design patterns you must know are: ● Model-View-Controller—This design pattern governs the overall structure of your app. ● Delegation—This design pattern facilitates the transfer information and data from one object to another. ● Target-action—This design pattern translates user interactions with buttons and controls into code that your app can execute. ● Block objects—You use blocks to implement callbacks and asynchronous code. ● Sandboxing—All iOS apps are placed in sandboxes to protect the system and other apps. The structure of the sandbox affects the placement of your app’s files and has implications for data backups and some app-related features. Accurate and efficient memory management is important for iOS apps. Because iOS apps typically have less usable memory than a comparable desktop computer, apps need to be aggressive about deleting unneeded objects and be lazy about creating objects in the first place. Apps use the compiler’s Automatic Reference Counting (ARC) feature to manage memory efficiently. Although using ARC is not required, it is highly recommended. The alternative is to manage memory yourself by explicitly retaining and releasing objects. There are other design patterns that you might see used occasionally or use yourself in your own code. For a complete overview of the design patterns and techniques you will use to create iOS apps, see Start Developing iOS Apps Today . Translating Your Initial Design into an Action Plan iOS assumes that all apps are built using the Model-View-Controller design pattern. Therefore, the first step you can take toward achieving this goal is to choose an approach for the data and view portions of your app. ● Choose a basic approach for your data model: ● Existing data model code—If you already have data model code written in a C-based language, you can integrate that code directly into your iOS apps. Because iOS apps are written in Objective-C, they work just fine with code written in other C-based languages. Of course, there is also benefit to writing an Objective-C wrapper for any non Objective-C code. App Design Basics Learning the Fundamental iOS Design Patterns and Techniques 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13● Customobjects datamodel—A custom object typically combinessome simple data (strings, numbers, dates, URLs, and so on) with the businesslogic needed to manage that data and ensure its consistency. Custom objects can store a combination of scalar values and pointers to other objects. For example, the Foundation framework defines classes for many simple data types and for storing collections of other objects. These classes make it much easier to define your own custom objects. ● Structured data model—If your data is highly structured—that is, it lends itself to storage in a database—use Core Data (or SQLite) to store the data. Core Data provides a simple object-oriented model for managing yourstructured data. It also provides built-in support forsome advanced features like undo and iCloud. (SQLite files cannot be used in conjunction with iCloud.) ● Decide whether you need support for documents: The job of a document isto manage your app’sin-memory data model objects and coordinate the storage of that data in a corresponding file (or set of files) on disk. Documents normally connote files that the user created but apps can use documents to manage non user facing files too. One big advantage of using documents is that the UIDocument class makes interacting with iCloud and the local file system much simpler. For appsthat use Core Data to store their content, the UIManagedDocument class providessimilar support. ● Choosing an approach for your user interface: ● Building block approach—The easiest way to create your user interface isto assemble it using existing view objects. Views represent visual elements such as tables, buttons, text fields, and so on. You use many views as-is but you can also customize the appearance and behavior ofstandard views as needed to meet your needs. You can also implement new visual elements using custom views and mix those views freely with the standard views in your interface. The advantages of views are that they provide a consistent user experience and they allow you to define complex interfaces quickly and with relatively little code. ● OpenGL ES-based approach—If your app requiresfrequentscreen updates orsophisticated rendering, you probably need to draw that content directly using OpenGL ES. The main use of OpenGL ES is for games and appsthat rely heavily on sophisticated graphics, and therefore need the best performance possible. Starting the App Creation Process After you formulate your action plan, it is time to start coding. If you are new to writing iOS apps, it is good to take some time to explore the initial Xcode templates that are provided for development. These templates greatly simplify the work you have to do and make it possible to have an app up and running in minutes. These templates also allow you to customize your initial project to support your specific needs more precisely. To that end, when creating your Xcode project, you should already have answers to the following questions in mind: App Design Basics Starting the App Creation Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14● What is the basic interface-style of your app? Different types of app require different sets of initial views and view controllers. Knowing how you plan to organize your user interface lets you select an initial project template that is most suited to your needs. You can always change your user interface later, but choosing the most appropriate template first makes starting your project much easier. ● Do you want to create a Universal app or one targeted specifically for iPad or iPhone? Creating a universal app requires specifying different sets of views and view controllers for iPad and iPhone and dynamically selecting the appropriate set at runtime. Universal apps are preferred because they support more iOS devices but do require you to factor your code better for each platform. For information about how a universal app affects the code you write, see “Creating a Universal App” (page 108). ● Do you want your app to use storyboards? Storyboards simplify the design process by showing both the views and view controllers of your user interface and the transitions between them. Storyboards are supported in iOS 5 and later and are enabled by default for new projects. If your app must run on earlier versions of iOS, though, you cannot use storyboards and should continue to use nib files. ● Do you want to use Core Data for your data model? Some types of apps lend themselves naturally to a structured data model, which makes them ideal candidates for using Core Data. For more information about Core Data and the advantages it offers, see Core Data Programming Guide . From these questions, you can use Xcode to create your initial project files and start coding. 1. If you have not yet installed Xcode, do so and configure your iOS development team. For detailed information about setting up your development teams and and preparing your Xcode environment, see Developing for the App Store . 2. Create your initial Xcode project. 3. Before writing any code, build and run your new Xcode project. Target your app for iOS Simulator so that you can see it run. Every new Xcode project starts you with a fully functional (albeit featureless) app. The app itself should run and display the default views found in the main storyboard or nib file, which are probably not very interesting. The reason that the app runs at all, though, is because of the infrastructure provided to you by UIKit. This infrastructure initializes the app, loads the initial interface file, and checks the app in with the system so that it can start handling events. For more information about this infrastructure and the capabilities it provides, see “The Core Objects of Your App” (page 17) and “The App Launch Cycle” (page 36). 4. Start writing your app’s primary code. For new apps, you probably want to start creating the classes associated with your app’s data model first. These classes usually have no dependencies on other parts of your app and should be something you can work on initially. For information about ways to build your data model, see “The Data Model” (page 20). App Design Basics Starting the App Creation Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15You might also want to start playing around with designs for your user interface by adding views to your main storyboard or nib file. From these views, you can also start identifying the places in your code where you need to respond to interface-related changes. For an overview of user interfaces and where they fit into your app’s code, see “The User Interface” (page 26). If your app supports iCloud, you should incorporate support for iCloud into your classes at an early stage. For information about adding iCloud support to your app, see “Integrating iCloud Support Into Your App” (page 26). 5. Add support for app state changes. In iOS, the state of an app determines what it is allowed to do and when. App states are managed by high-level objects in your app but can affect many other objects as well. Therefore, you need to consider how the current app state affects your data model and view code and update that code appropriately. For information about app states and how apps run in the foreground and background, see “App States and Multitasking” (page 33) 6. Create the resources needed to support your app. Apps submitted to the App Store are expected to have specific resources such as icons and launch images to make the overall user experience better. Well-factored apps also make heavy use of resource files to keep their code separate from the data that code manipulates. This factoring makes it much easier to localize your app, tweak its appearance, and perform other tasks without rewriting any code. For information about the types of resourcesfound in a typical iOS app and how they are used,see “The App Bundle” (page 30) and “App-Related Resources” (page 93). 7. As needed, implement any app-specific behaviors that are relevant for your app. There are many ways to modify the way your app launches or interacts with the system. For information about the most common types of app customizations, see “Advanced App Tricks” (page 108). 8. Add the advanced features that make your app unique. iOS includes many other frameworksfor managing multimedia, advanced rendering, game content, maps, contacts, location tracking, and many other advanced features. For an overview of the frameworks and features you can incorporate into your apps, see iOS Technology Overview. 9. Do some basic performance tuning for your app. All iOS appsshould be tuned for the best possible performance. Tuned appsrun faster but also use system resources,such as memory and battery life, more efficiently. For information about areasto focus on during the tuning process, see “Performance Tuning” (page 127). 10. Iterate. App development is an iterative process. As you add new features, you might need to revisit some or all of the preceding steps to make adjustments to your existing code. App Design Basics Starting the App Creation Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16UIKit provides the infrastructure for all apps but it is your custom objects that define the specific behavior of your app. Your app consists of a handful of specific UIKit objects that manage the event loop and the primary interactions with iOS. Through a combination of subclassing, delegation, and other techniques, you modify the default behaviors defined by UIKit to implement your app. In addition to customizing the UIKit objects, you are also responsible for providing or defining other key sets of objects. The largest set of objects is your app’s data objects, the definition of which is entirely your responsibility. You must also provide a set of user interface objects, but fortunately UIKit provides numerous classes to make defining your interface easy. In addition to code, you must also provide the resources and data files you need to deliver a shippable app. The Core Objects of Your App From the time your app is launched by the user, to the time it exits, the UIKit framework manages much of the app’s core behavior. At the heart of the app is the UIApplication object, which receives events from the system and dispatches them to your custom code for handling. Other UIKit classes play a part in managing your app’s behavior too, and all of these classes have similar ways of calling your custom code to handle the details. To understand how UIKit objects work with your custom code, it helps to understand a little about the objects make up an iOS app. Figure 2-1 shows the objects that are most commonly found in an iOS app, and Table 2-1 describes the roles of each object. As you can see from the diagram, iOS apps are organized around the model-view-controller design pattern. This pattern separates the data objects in the model from the views used 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17 Core App Objectsto present that data. This separation promotes code reuse by making it possible to swap out your views as needed and is especially useful when creating universal apps—that is, apps that can run on both iPad and iPhone. Figure 2-1 Key objects in an iOS app Table 2-1 The role of objects in an iOS app Object Description You use the UIApplication object essentially asis—that is, withoutsubclassing. This controller object managesthe app event loop and coordinates other high-level app behaviors. Your own custom app-level logic resides in your app delegate object, which works in tandem with this object. UIApplication object Core App Objects The Core Objects of Your App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18Object Description The app delegate is a custom object created at app launch time, usually by the UIApplicationMain function. The primary job of this object is to handle state transitions within the app. For example, this object is responsible for launch-time initialization and handling transitionsto and from the background. For information about how you use the app delegate to manage state transitions, see “Managing App State Changes” (page 34). In iOS 5 and later, you can use the app delegate to handle other app-related events. The Xcode project templates declare the app delegate as a subclass of UIResponder. If the UIApplication object does not handle an event, it dispatches the event to your app delegate for processing. For more information about the types of events you can handle, see UIResponder Class Reference . App delegate object Data model objects store your app’s content and are specific to your app. For example, a banking app might store a database containing financial transactions, whereas a painting app might store an image object or even the sequence of drawing commands that led to the creation of that image. (In the latter case, an image object isstill a data object because it isjust a container for the image data.) Apps can also use document objects (custom subclasses of UIDocument) to manage some or all of their data model objects. Document objects are not required but offer a convenient way to group data that belongs in a single file or file package. For more information about documents,see “Defining a Document-Based Data Model” (page 24). Documents and data model objects View controller objects manage the presentation of your app’s content on screen. A view controller manages a single view and its collection of subviews. When presented, the view controller makes its views visible by installing them in the app’s window. The UIViewController class is the base class for all view controller objects. It provides default functionality for loading views, presenting them, rotating them in response to device rotations, and several otherstandard system behaviors. UIKit and other frameworks define additional view controller classes to implement standard system interfaces such as the image picker, tab bar interface, and navigation interface. For detailed information about how to use view controllers, see View Controller Programming Guide for iOS . View controller objects Core App Objects The Core Objects of Your App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19Object Description A UIWindow object coordinatesthe presentation of one or more views on a screen. Most apps have only one window, which presents content on the main screen, but apps may have an additional window for content displayed on an external display. To change the content of your app, you use a view controller to change the views displayed in the corresponding window. You never replace the window itself. In addition to hosting views, windows work with the UIApplication object to deliver events to your views and view controllers. UIWindow object Views and controls provide the visual representation of your app’s content. A view is an object that draws content in a designated rectangular area and responds to events within that area. Controls are a specialized type of view responsible for implementing familiar interface objects such as buttons, text fields, and toggle switches. The UIKit framework provides standard views for presenting many different types of content. You can also define your own custom views by subclassing UIView (or its descendants) directly. In addition to incorporating views and controls, apps can also incorporate Core Animation layersinto their view and control hierarchies. Layer objects are actually data objects that represent visual content. Views use layer objects intensively behind the scenes to render their content. You can also add custom layer objects to your interface to implement complex animations and other types of sophisticated visual effects. View, control, and layer objects What distinguishes one iOS app from another is the data it manages (and the corresponding business logic) and how it presents that data to the user. Most interactions with UIKit objects do not define your app but help you to refine its behavior. For example, the methods of your app delegate let you know when the app is changing states so that your custom code can respond appropriately. For information about the specific behaviors of a given class, see the corresponding class reference. For more information about how events flow in your app and information about your app’s responsibilities at various points during that flow, see “App States and Multitasking” (page 33). The Data Model Your app’s data model comprises your data structures and the business logic needed to keep that data in a consistent state. You never want to design your data model in total isolation from your app’s user interface; however, the implementation of your data model objects should be separate and not rely on the presence of Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20specific views or view controllers. Keeping your data separate from your user interface makes it easier to implement a universal app—one that can run on both iPad and iPhone—and also makes it easier to reuse portions of your code later. If you have not yet defined your data model, the iOS frameworks provide help for doing so. The following sections highlight some of the technologies you can use when defining specific types of data models. Defining a Custom Data Model When defining a custom data model, create custom objects to represent any high-level constructs but take advantage of the system-supplied objects for simpler data types. The Foundation framework provides many objects (most of which are listed in Table 2-2) for managing strings, numbers, and other types of simple data in an object-oriented way. Using these objects is preferable to defining new objects both because it saves time and because many other system routines expect you to use the built-in objects anyway. Table 2-2 Data classes in the Foundation framework Data Classes Description Strings in iOS are Unicode based. The string classes provide support for creating and manipulating strings in a variety of ways. The attributed string classes support stylized text and are used only in conjunction with Core Text. NSString (NSMutableString) NSAttributedString (NSMutableAttributedString) Strings and text When you want to store numerical values in a collection, use number objects. The NSNumber class can represent integer, floating-point values, Booleans, and char types. The NSIndexPath class stores a sequence of numbers and is often used to specify multi-layer selections in hierarchical lists. NSNumber NSDecimalNumber NSIndexPath Numbers For times when you need to store raw streams of bytes, use data objects. Data objects are also commonly used to store objectsin an archived form. The NSValue class is typically extended (using categories) and used to archive common data types such as points and rectangles. NSData (NSMutableData) NSValue Raw bytes Use date objects to store timestamps, calendar dates, and other time-related information. NSDate NSDateComponents Dates and times Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21Data Classes Description In addition to their traditional use for referring to network resources, URLs in iOS are the preferred way to store paths to files. The NSURL class even provides support for getting and setting file-related attributes. URLs NSURL Use collections to group related objects together in a single place. The Foundation framework provides several different types of collection classes NSArray (NSMutableArray) NSDictionary (NSMutableDictionary) NSIndexSet (NSMutableIndexSet) NSOrderedSet (NSMutableOrderedSet) NSSet (NSMutableSet) Collections In addition to data-related objects, there are some other data types that are commonly used by the iOS frameworks to manage familiar types of data. You are encouraged to use these data types in your own custom objects to represent similar types of data. ● NSInteger/NSUInteger—Abstractions for scalar signed and unsigned integers that define the integer size based on the architecture. ● NSRange—A structure used to define a contiguous portion of a series. For example, you can use ranges to define the selected characters in a string. ● NSTimeInterval—The number of seconds (whole and partial) in a given time interval. ● CGPoint—An x and y coordinate value that defines a location. ● CGSize—Coordinate values that define a set of horizontal and vertical extents. ● CGRect—Coordinate values that define a rectangular region. Of course, when defining custom objects, you can always incorporate scalar values directly into your class implementations. In fact, a custom data object can include a mixture of scalar and object types for its member variables. Listing 2-1 shows a sample class definition for a collection of pictures. The class in this instance contains an array of images and a list of the indexes into that array representing the selected items. The class also contains a string for the collection’s title and a scalar Boolean variable indicating whether the collection is currently editable. Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22Listing 2-1 Definition of a custom data object @interface PictureCollection : NSObject { NSMutableOrderedSet* pictures; NSMutableIndexSet* selection; NSString* title; BOOL editable; } @property (nonatomic, strong) NSString * title; @property (nonatomic, readonly) NSOrderedSet* pictures; // Method definitions... @end Note: When defining data objects, it is strongly recommended that you declare properties for any member variables that you to expose to clients of the object. Synthesizing these properties in your implementation file automatically creates appropriate accessor methods with the attributes you require. This ensures that object relationships are maintained appropriately and that references to objects are removed at appropriate times. Consider how undo operations on your custom objects might be handled. Supporting undo means being able to reverse changes made to your objects cleanly. If your objects incorporate complex business logic, you need to factor that logic in a way that can be undone easily. Here are some tips for implementing undo support in your custom objects: ● Define the methods you need to make sure that changes to your object are symmetrical. For example, if you define a method to add an item, make sure you have a method for removing an item in a similar way. ● Factor out your business logic from the code you use to change the values of member variables. ● For multistep actions, use the current NSUndoManager object to group the steps together. For more information about how to implement undo support in your app, see Undo Architecture . For more information about the classes of the Foundation framework, see Foundation Framework Reference . Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23Defining a Structured Data Model Using Core Data Core Data is a schema-driven object graph management and persistence framework. Fundamentally, Core Data helps you to save model objects (in the sense of the model-view-controller design pattern) to a file and get them back again. This is similar to archiving (see Archives and Serializations Programming Guide ), but Core Data offers much more than that. ● Core Data provides an infrastructure for managing all the changes to your model objects. This gives you automatic support for undo and redo, and for maintaining reciprocal relationships between objects. ● It allows you to keep just a subset of your model objects in memory at any given time, which is very important for iOS apps. ● It uses a schema to describe the model objects. You define the principal features of your model classes—including the relationships between them—in a GUI-based editor. This provides a wealth of basic functionality “for free,” including setting of default values and attribute value validation. ● It allows you to maintain disjoint sets of edits of your objects. This is useful if you want to, for example, allow the user to make editsin one view that may be discarded without affecting data displayed in another view. ● It has an infrastructure for data store versioning and migration. This lets you easily upgrade an old version of the user’s file to the current version. ● It allows you to store your data in iCloud and access it from multiple devices. For information about how to use Core Data, see Core Data Programming Guide . Defining a Document-Based Data Model A document-based data model is a convenient way to manage the files your app writes to disk. In this type of data model, you use a document object to represent the contents of a single file (or file package) on disk. That document object is responsible for reading and writing the contents of the file and working with your app’s view controllers to present the document’s contents on screen. The traditional use for document objects is to manage files containing user data. For example, an app that creates and managestext files would use a separate document object to manage each text file. However, you can use document objects for private app data that is also backed by a file. Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Figure 2-2 illustrates the typical relationships between documents, files, and the objects in your app’s data model. With few exceptions, each document is self-contained and does not interact directly with other documents. The document manages a single file (or file package) and creates the in-memory representation of any data found in that file. Because the contents of each file are unique, the data structures associated with each document are also unique. Figure 2-2 Using documents to manage the content of files You use the UIDocument class to implement document objects in your iOS app. This class provides the basic infrastructure needed to handle the file management aspects of the document. Other benefits of UIDocument include: ● It provides support for autosaving the document contents at appropriate times. ● It handlesthe required file coordination for documentsstored in iCloud. It also provides hooksfor resolving version conflicts. ● It provides support for undoing actions. You mustsubclass UIDocument in order to implement the specific behavior required by your app’s documents. For detailed information about how to implement a document-based app using UIDocument, see Document-Based App Programming Guide for iOS . Core App Objects The Data Model 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25Integrating iCloud Support Into Your App No matter how you store your app’s data, iCloud is a convenient way to make that data available to all of the user’s devices. Supporting iCloud in your app just means changing where you store your files. Instead ofstoring them in your app’s sandbox directory, you store them in a designated portion of the user’s iCloud storage. In both cases, your app just works with files and directories. However, with iCloud, you have to do a little extra work because the data is now shared and accessible to multiple processes. Fortunately, when you use iOS frameworks to manage your data, much of the hard work needed to support iCloud is done for you. ● Document based apps get iCloud support through the UIDocument class. This class handles almost all of the complex interactions required to manage iCloud-based files. ● Core Data apps also get iCloud support through the Core Data framework. This framework automatically updates the data stores on all of the user’s devices to account for new and changed data objects, leaving each device with a complete and up-to-date set of data. ● If you implement a custom data model and manage files yourself, you can use file presenters and file coordinators to ensure that the changes you make are done safely and in concert with the changes made on the user’s other devices. ● For apps that want to share preferences or small quantities of infrequently changing data, you can use the NSUbiquitousKeyValueStore object to do so. This objectsupportsthe sharing ofsimple data types such as strings, numbers, and dates in limited quantities. For more information about incorporating iCloud support into your apps, see iCloud Design Guide . The User Interface Every iOS app has at least one window and one view for presenting its content. The window provides the area in which to display the content and is an instance of the UIWindow class. Views are responsible for managing the drawing of your content (and handling touch events) and are instances of the UIView class. For interfaces that you build using view objects, your app’s window naturally contains multiple view objects. For interfaces built using OpenGL ES, you typically have a single view and use that view to render your content. View controllers also play a very important role in your app’s user interface. A view controller is an instance of the UIViewController class and is responsible for managing a single set of views and the interactions between those views and other parts of your app. Because iOS apps have a limited amount of space in which to display content, view controllers also provide the infrastructure needed to swap out the views from one view controller and replace them with the views of another view controller. Thus, view controllers are you how implement transitions from one type of content to another. Core App Objects The User Interface 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26You should always think of a view controller object as a self-contained unit. It handles the creation and destruction of its own views, handles their presentation on the screen, and coordinates interactions between the views and other objects in your app. Building an Interface Using UIKit Views Apps that use UIKit views for drawing are easy to create because you can assemble a basic interface quickly. The UIKit framework provides many different types of views to help present and organize data. Controls—a special type of view—provide a built-in mechanism for executing custom code whenever the user performs appropriate actions. For example, clicking on a button causesthe button’s associated action method to be called. The advantage of interfaces based on UIKit views is that you can assemble them graphically using Interface Builder—the visual interface editor built in to Xcode. Interface Builder provides a library of the standard views, controls, and other objects that you need to build your interface. After dragging these objects from the library, you drop them onto the work surface and arrange them in any way you want. You then use inspectors to configure those objects before saving them in a storyboard or nib file. The process of assembling your interface graphically is much faster than writing the equivalent code and allows you to see the results immediately, without the need to build and run your app. Core App Objects The User Interface 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27Note: You can also incorporate custom views into your UIKit view hierarchies. A custom view is a subclass of UIView in which you handle all of the drawing and event-handling tasks yourself. For more information about creating custom views and incorporating them into your view hierarchies, see View Programming Guide for iOS . Figure 2-3 shows the basic structure of an app whose interface is constructed solely using view objects. In this instance, the main view spansthe visible area of the window (minusthe scroll bar) and provides a simple white background. The main view also contains three subviews: an image view, a text view, and a button. Those subviews are what the app uses to present content to the user and respond to interactions. All of the views in the hierarchy are managed by a single view controller object. Figure 2-3 Building your interface using view objects In a typical view-based app, you coordinate the onscreen views using your view controller objects. An app always has one view controller that is responsible for presenting all of the content on the screen. That view controller has a content view, which itself may contain other views. Some view controllers can also act as containers for content provided by other view controllers. For example, a split view controller displays the content from two view controllers side by side. Because view controllers play a vital role in view management, understand how they work and the benefits they provide by reading View Controller Programming Guide for iOS . For more information about views and the role they play in apps, see View Programming Guide for iOS . Core App Objects The User Interface 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Building an Interface Using Views and OpenGL ES Games and other appsthat need high frame rates orsophisticated drawing capabilities can add viewsspecifically designed for OpenGL ES drawing to their view hierarchies. The simplest type of OpenGL ES app is one that has a window object and a single view for OpenGL ES drawing and a view controller to manage the presentation and rotation of that content. More sophisticated applications can use a mixture of both OpenGL ES views and UIKit views to implement their interfaces. Figure 2-4 shows the configuration of an app that uses a single OpenGL ES view to draw its interface. Unlike a UIKit view, the OpenGL ES view is backed by a different type of layer object (a CAEAGLLayer object) instead of the standard layer used for view-based apps. The CAEAGLLayer object provides the drawing surface that OpenGL ES can render into. To manage the drawing environment, the app also creates an EAGLContext object and stores that object with the view to make it easy to retrieve. Figure 2-4 Building your interface using OpenGL ES For information on how to configure OpenGL ES for use in your app, see OpenGL ES Programming Guide for iOS . Core App Objects The User Interface 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29The App Bundle When you build your iOS app, Xcode packages it as a bundle. A bundle is a directory in the file system that groups related resources together in one place. An iOS app bundle contains the app executable file and supporting resource files such as app icons, image files, and localized content. Table 2-3 lists the contents of a typical iOS app bundle, which for demonstration purposes is called MyApp. This example is for illustrative purposes only. Some of the files listed in this table may not appear in your own app bundles. Table 2-3 A typical app bundle File Example Description The executable file contains your app’s compiled code. The name of your app’s executable file is the same as your app name minusthe .app extension. This file is required. App MyApp executable The Info.plist file contains configuration data for the app. The system usesthis data to determine how to interact with the app. This file is required and must be called Info.plist. For more information, see Figure 6-1 (page 120). The information Info.plist property list file Your app icon is used to represent your app on the device’s Home screen. Other icons are used by the system in appropriate places. Icons with @2x in their filename are intended for devices with Retina displays. An app icon is required. For information about specifying icon image files, see “App Icons” (page 98). Icon.png Icon@2x.png Icon-Small.png Icon-Small@2x.png App icons The system uses this file as a temporary background while your app is launching. It is removed as soon as your app is ready to display its user interface. At least one launch image is required. For information about specifying launch images, see “App Launch (Default) Images” (page 100). Default.png Default-Portrait.png Default-Landscape.png Launch images Core App Objects The App Bundle 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30File Example Description Storyboards contain the views and view controllers that the app presents on screen. Views in a storyboard are organized according to the view controller that presents them. Storyboards also identify the transitions (called segues) that take the user from one set of views to another. The name of the main storyboard file is set by Xcode when you create your project. You can change the name by assigning a different value to the NSMainStoryboardFile key in the Info.plist file.) Apps that use nib files instead of storyboards can replace the NSMainStoryboardFile key with the NSMainNibFile key and use that key to specify their main nib file. The use of storyboards (or nib files) is optional but recommended. Storyboard MainBoard.storyboard files (or nib files) If you are distributing your app ad hoc, include a 512 x 512 pixel version of your app icon. This icon is normally provided by the App Store from the materials you submit to iTunes Connect. However, because apps distributed ad hoc do not go through the App Store, your icon must be present in your app bundle instead. iTunes uses this icon to represent your app. (The file you specify should be the same one you would have submitted to the App Store, if you were distributing your app that way.) The filename of thisicon must be iTunesArtwork and must not include a filename extension. This file is required for ad hoc distribution but is optional otherwise. Ad hoc iTunesArtwork distribution icon Core App Objects The App Bundle 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31File Example Description If you want to expose custom app preferences through the Settings app, you must include a settings bundle. This bundle contains the property list data and other resource files that define your app preferences. The Settings app uses the information in this bundle to assemble the interface elements required by your app. This bundle is optional. For more information about preferences and specifying a settings bundle, see Preferences and Settings Programming Guide . Settings Settings.bundle bundle Nonlocalized resources include things like images, sound files, movies, and custom data filesthat your app uses. All of these files should be placed at the top level of your app bundle. sun.png mydata.plist Nonlocalized resource files Localized resources must be placed in language-specific project directories, the names for which consist of an ISO 639-1 language abbreviation plusthe .lproj suffix. (For example, the en.lproj, fr.lproj, and es.lproj directories contain resources localized for English, French, and Spanish.) An iOS app should be internationalized and have a language.lproj directory for each language it supports. In addition to providing localized versions of your app’s custom resources, you can also localize your app icon, launch images, and Settings icon by placing files with the same name in your language-specific project directories. For more information, see “Localized Resource Files” (page 105). en.lproj fr.lproj es.lproj Subdirectories for localized resources Formore information aboutthe structure of an iOS app bundle,see Bundle ProgrammingGuide . Forinformation about how to load resource files from your bundle, see “Loading Resources Into Your App” (page 106). Core App Objects The App Bundle 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32For iOS apps, it is crucial to know whether your app is running in the foreground or the background. Because system resources are more limited on iOS devices, an app must behave differently in the background than in the foreground. The operating system also limits what your app can do in the background in order to improve battery life and to improve the user’s experience with the foreground app. The operating system notifies your app whenever it moves between the foreground and background. These notifications are your chance to modify your app’s behavior. While your app isin the foreground, the system sendstouch eventsto it for processing. The UIKit infrastructure does most of the hard work of delivering eventsto your custom objects. All you have to do is override methods in the appropriate objectsto processthose events. For controls, UIKitsimplifiesthings even further by handling the touch events for you and calling your custom code only when something interesting happens, such as when the value of a text field changes. As you implement your app, follow these guidelines: ● (Required) Respond appropriately to the state transitions that occur. Not handling these transitions properly can lead to data loss and a bad user experience. For a summary of how to respond to state transitions, see “Managing App State Changes” (page 34). ● (Required) When moving to the background, make sure your app adjusts its behavior appropriately. For guidelines about what to do when your app movesto the background,see “Being a Responsible Background App” (page 63). ● (Recommended) Register for any notifications that report system changes your app needs. When an app is suspended, the system queues key notifications and delivers them when the app resumes execution. Apps should use these notifications to make a smooth transition back to execution. For more information, see “Processing Queued Notifications at Wakeup Time” (page 48). ● (Optional) If your app needsto do actual work while in the background, ask the system for the appropriate permissions to continue running. For more information about the types of background work you can do and how to request permission to do that work, see “Background Execution and Multitasking” (page 54). 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33 App States and MultitaskingManaging App State Changes At any given moment, your app is in one of the states listed in Table 3-1. The system moves your app from state to state in response to actions happening throughout the system. For example, when the user presses the Home button, a phone call comes in, or any of several other interruptions occurs, the currently running apps change state in response. Figure 3-1 (page 35) shows the paths that an app takes when moving from state to state. Table 3-1 App states State Description Not running The app has not been launched or was running but was terminated by the system. The app is running in the foreground but is currently not receiving events. (It may be executing other code though.) An app usually stays in this state only briefly as it transitions to a different state. Inactive The app is running in the foreground and is receiving events. This is the normal mode for foreground apps. Active The app is in the background and executing code. Most apps enter this state briefly on their way to being suspended. However, an app that requests extra execution time may remain in thisstate for a period of time. In addition, an app being launched directly into the background enters this state instead of the inactive state. For information about how to execute code while in the background, see “Background Execution and Multitasking” (page 54). Background App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34State Description The app is in the background but is not executing code. The system moves apps to this state automatically and does not notify them before doing so. While suspended, an app remains in memory but does not execute any code. When a low-memory condition occurs, the system may purge suspended apps without notice to make more space for the foreground app. Suspended Figure 3-1 State changes in an iOS app Note: Apps running in iOS 3.2 and earlier do not enter the background or suspended states. In addition, some devices do not support multitasking or background execution at all, even when running iOS 4 or later. Appsrunning on those devices also do not enter the background orsuspended states. Instead, apps are terminated upon leaving the foreground. Most state transitions are accompanied by a corresponding call to the methods of your app delegate object. These methods are your chance to respond to state changes in an appropriate way. These methods are listed below, along with a summary of how you might use them. ● application:willFinishLaunchingWithOptions:—This method is your app’s first chance to execute code at launch time. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35● application:didFinishLaunchingWithOptions:—This method allows you to perform any final initialization before your app is displayed to the user. ● applicationDidBecomeActive:—Lets your app know that it is about to become the foreground app. Use this method for any last minute preparation. ● applicationWillResignActive:—Lets you know that your app is transitioning away from being the foreground app. Use this method to put your app into a quiescent state. ● applicationDidEnterBackground:—Lets you know that your app is now running in the background and may be suspended at any time. ● applicationWillEnterForeground:—Lets you know that your app is moving out of the background and back into the foreground, but that it is not yet active. ● applicationWillTerminate:—Lets you know that your app is being terminated. This method is not called if your app is suspended. The App Launch Cycle When your app islaunched, it movesfrom the not running state to the active or background state, transitioning briefly through the inactive state. As part of the launch cycle, the system creates a process and main thread for your app and calls your app’s main function on that main thread. The default main function that comes with your Xcode project promptly hands control over to the UIKit framework, which does most of the work in initializing your app and preparing it to run. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36Figure 3-2 shows the sequence of events that occurs when an app is launched into the foreground, including the app delegate methods that are called. Figure 3-2 Launching an app into the foreground User taps app icon main() UIApplicationMain() Load main UI file First initialization Restore UI state Final initialization Launch Time application: willFinishLaunchingWithOptions: Various methods application: didFinishLaunchingWithOptions: Handle events Your Code Switch to a different app Running applicationDidBecomeActive: Event Loop Activate the app App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37If your app is launched into the background instead—usually to handle some type of background event—the launch cycle changes slightly to the one shown in Figure 3-3. The main difference is that instead of your app being made active, it entersthe background state to handle the event and then issuspended shortly afterward. When launching into the background, the system still loads your app’s user interface files but it does not display the app’s window. Figure 3-3 Launching an app into the background App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38To determine whether your app islaunching into the foreground or background, check the applicationState property ofthe shared UIApplication objectin your application:willFinishLaunchingWithOptions: or application:didFinishLaunchingWithOptions: delegate method. When the app is launched into the foreground, this property containsthe value UIApplicationStateInactive. When the app islaunched into the background, the property contains the value UIApplicationStateBackground instead. You can use this difference to adjust the launch-time behavior of your delegate methods accordingly. Note: When an app is launched so that it can open a URL, the sequence of startup events is slightly different from those shown in Figure 3-2 and Figure 3-3. For information about the startup sequences that occur when opening a URL, see “Handling URL Requests” (page 120). About the main Function Like any C-based app, the main entry point for an iOS app at launch time is the main function. In an iOS app, the main function is used only minimally. Its main job is to hand control to the UIKit framework. Therefore, any new project you create in Xcode comes with a default main function like the one shown in Listing 3-1. With few exceptions, you should never change the implementation of this function. Listing 3-1 The main function of an iOS app #import int main(int argc, char *argv[]) { @autoreleasepool { return UIApplicationMain(argc, argv, nil, NSStringFromClass([MyAppDelegate class])); } } Note: An autorelease pool is used in memory management. It is a Cocoa mechanism used to defer the release of objects created during a functional block of code. For more information about autorelease pools, see Advanced Memory Management Programming Guide . The UIApplicationMain function takes four parameters and uses them to initialize the app. You should never have to change the default values passed into thisfunction. Still, it is valuable to understand their purpose and how they start the app. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39● The argc and argv parameters contain any launch-time arguments passed to the app from the system. These arguments are parsed by the UIKit infrastructure and can otherwise be ignored. ● The third parameter identifies the name of the principal app class. This is the class responsible for running the app. It is recommend that you specify nil for this parameter, which causes UIKit to use the UIApplication class. ● The fourth parameter identifies the class of your custom app delegate. Your app delegate is responsible for managing the high-level interactions between the system and your code. The Xcode template projects set this parameter to an appropriate value automatically. Another thing the UIApplicationMain function does is load the app’s main user interface file. The main interface file contains the initial view-related objects you plan to display in your app’s user interface. For apps that use “Using Storyboards”, this function loads the initial view controller from your storyboard and installs it in the window provided by your app delegate. For appsthat use nib files, the function loadsthe nib file contents into memory but does not install them in your app’s window; you must install them in the application:willFinishLaunchingWithOptions: method of your app delegate. An app can have either a main storyboard file or a main nib file but it cannot have both. Storyboards are the preferred way to specify your app’s user interface but are not supported on all versions of iOS. The name of your app’s main storyboard file goes in the UIMainStoryboardFile key of your app’s Info.plist file. (For nib-based apps, the name of your main nib file goes in the NSMainNibFile key instead.) Normally, Xcode sets the value of the appropriate key when you create your project, but you can change it later if needed. For more information about the Info.plist file and how you use it to configure your app,see “The Information Property List File” (page 93). What to Do at Launch Time When your app is launched (either into the foreground or background), use your app delegate’s application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: methods to do the following: ● Check the contents of the launch options dictionary for information about why the app was launched, and respond appropriately. ● Initialize the app’s critical data structures. ● Prepare your app’s window and views for display. Apps that use OpenGL ES should not use this method to prepare their drawing environment. Instead, they should defer any OpenGL ES drawing calls to the applicationDidBecomeActive: method. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40If your app does not automatically load a main storyboard or nib file at launch time, you can use the application:willFinishLaunchingWithOptions: method to prepare your app’s window for display. For apps that support both portrait and landscape orientations, always set up the root view controller of your main window in a portrait orientation. If the device is in a different orientation at launch time, the system tells the root view controller to rotate your views to the correct orientation before displaying the window. Your application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: methods should always be as lightweight as possible to reduce your app’s launch time. Apps are expected to launch and initialize themselves and start handling events in less than 5 seconds. If an app does not finish its launch cycle in a timely manner, the system kills it for being unresponsive. Thus, any tasks that might slow down your launch (such as accessing the network) should be executed asynchronously on a secondary thread. When launching into the foreground, the system also calls the applicationDidBecomeActive: method to finish the transition to the foreground. Because this method is called both at launch time and when transitioning from the background, use it to perform any tasks that are common to the two transitions. When launching into the background, there should not be much for your app to do except get ready to handle whatever event arrived. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41Responding to Interruptions When an alert-based interruption occurs, such as an incoming phone call, the app moves temporarily to the inactive state so that the system can prompt the user about how to proceed. The app remains in this state until the user dismiss the alert. At this point, the app either returns to the active state or moves to the background state. Figure 3-4 shows the flow of events through your app when an alert-based interruption occurs. Figure 3-4 Handling alert-based interruptions In iOS 5, notificationsthat display a banner do not deactivate your app in the way that alert-based notifications do. Instead, the banner is laid along the top edge of your app window and your app continues receive touch events as before. However, if the user pulls down the banner to reveal the notification center, your app moves to the inactive state just as if an alert-based interruption had occurred. Your app remains in the inactive state until the user dismisses the notification center or launches another app. At this point, your app moves to the appropriate active or background state. The user can use the Settings app to configure which notifications display a banner and which display an alert. Pressing the Sleep/Wake button is another type of interruption that causes your app to be deactivated temporarily. When the user presses this button, the system disables touch events, moves the app to the background butsetsthe value of the app’s applicationState property to UIApplicationStateInactive App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42(as opposed to UIApplicationStateBackground), and finally locksthe screen. A locked screen has additional consequences for apps that use data protection to encrypt files. Those consequences are described in “What to Do When an Interruption Occurs” (page 43). What to Do When an Interruption Occurs Alert-based interruptions result in a temporary loss of control by your app. Your app continues to run in the foreground, but it does not receive touch events from the system. (It does continue to receive notifications and other types of events, such as accelerometer events, though.) In response to this change, your app should do the following in its applicationWillResignActive: method: ● Stop timers and other periodic tasks. ● Stop any running metadata queries. ● Do not initiate any new tasks. ● Pause movie playback (except when playing back over AirPlay). ● Enter into a pause state if your app is a game. ● Throttle back OpenGL ES frame rates. ● Suspend any dispatch queues or operation queues executing non-critical code. (You can continue processing network requests and other time-sensitive background tasks while inactive.) When your app is moved back to the active state, its applicationDidBecomeActive: method should reverse any of the steps taken in the applicationWillResignActive: method. Thus, upon reactivation, your app should restart timers, resume dispatch queues, and throttle up OpenGL ES frame rates again. However, games should not resume automatically; they should remain paused until the user chooses to resume them. When the user pressesthe Sleep/Wake button, apps with files protected by the NSFileProtectionComplete protection option must close any referencesto those files. For devices configured with an appropriate password, pressing the Sleep/Wake button locks the screen and forces the system to throw away the decryption keys for files with complete protection enabled. While the screen is locked, any attempts to access the corresponding files will fail. So if you have such files, you should close any references to them in your applicationWillResignActive: method and open new references in your applicationDidBecomeActive: method. Adjusting Your User Interface During a Phone Call When the user takes a call and then returns to your app while on the call, the height of the status bar grows to reflect the fact that the user is on a call. Similarly, when the user ends the call, the status bar height shrinks back to its regular size. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43The best way to handle status bar height changes is to use view controllers to manage your views. When installed in your interface, view controllers automatically adjust the height of their managed views when the status bar frame size changes. If your app does not use view controllers for some reason, you must respond to status bar frame changes manually by registering for the UIApplicationDidChangeStatusBarFrameNotification notification. Your handler for this notification should get the status bar height and use it to adjust the height of your app’s views appropriately. Moving to the Background When the user presses the Home button, presses the Sleep/Wake button, or the system launches another app, the foreground app transitions to the inactive state and then to the background state. These transitions result in callsto the app delegate’s applicationWillResignActive: and applicationDidEnterBackground: methods, as shown in Figure 3-5. After returning from the applicationDidEnterBackground: method, App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44most apps move to the suspended state shortly afterward. Apps that request specific background tasks (such as playing music) or that request a little extra execution time from the system may continue to run for a while longer. Figure 3-5 Moving from the foreground to the background App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45Note: Apps are moved to the background only on devices that support multitasking and only if those devices are running iOS 4.0 or later. In all other cases, the app is terminated (and thus purged from memory) instead of moved to the background. What to Do When Moving to the Background Apps can use their applicationDidEnterBackground: method to prepare for moving to the background state. When moving to the background, all apps should do the following: ● Prepare to have their picture taken. When the applicationDidEnterBackground: method returns, the system takes a picture of your app’s user interface and usesthe resulting image for transition animations. If any views in your interface contain sensitive information, you should hide or modify those views before the applicationDidEnterBackground: method returns. ● Save user data and app state information. All unsaved changes should be written to disk when entering the background. This step is necessary because your app might be quietly killed while in the background for any number of reasons. You can perform this operation from a background thread as needed. ● Free up as much memory as possible. For more information about what to do and why this is important, see “Memory Usage for Background Apps” (page 47). Your app delegate’s applicationDidEnterBackground: method has approximately 5 seconds to finish any tasks and return. In practice, this method should return as quickly as possible. If the method does not return before time runs out, your app is killed and purged from memory. If you still need more time to perform tasks, call the beginBackgroundTaskWithExpirationHandler: method to request background execution time and then start any long-running tasks in a secondary thread. Regardless of whether you start any background tasks, the applicationDidEnterBackground: method must still exit within 5 seconds. Note: The UIApplicationDidEnterBackgroundNotification notification is also sent to let interested parts of your app know that it is entering the background. Objects in your app can use the default notification center to register for this notification. Depending on the features of your app, there are other things your app should do when moving to the background. For example, any active Bonjour services should be suspended and the app should stop calling OpenGL ES functions. For a list of things your app should do when moving to the background, see “Being a Responsible Background App” (page 63). App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46Memory Usage for Background Apps Every app should free up as much memory as is practical upon entering the background. The system tries to keep as many apps in memory at the same time as it can, but when memory runs low it terminates suspended apps to reclaim that memory. Apps that consume large amounts of memory while in the background are the first apps to be terminated. Practically speaking, your app should remove strong referencesto objects assoon asthey are no longer needed. Removing strong references gives the compiler the ability to release the objects right away so that the corresponding memory can be reclaimed. However, if you want to cache some objectsto improve performance, you can wait until the app transitions to the background before removing references to them. Some examples of objects that you should remove strong references to as soon as possible include: ● Image objects ● Large media or data files that you can load again from disk ● Any other objects that your app does not need and can recreate easily later To help reduce your app’s memory footprint, the system automatically purges some data allocated on behalf of your app when your app moves to the background. ● The system purges the backing store for all Core Animation layers. This effort does not remove your app’s layer objectsfrom memory, nor doesit change the current layer properties. Itsimply preventsthe contents of those layersfrom appearing onscreen, which given that the app isin the background should not happen anyway. ● It removes any system references to cached images. (If your app does not have a strong reference to the images, they are subsequently removed from memory.) ● It removes strong references to some other system-managed data caches. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47Returning to the Foreground Returning to the foreground is your app’s chance to restart the tasks that it stopped when it moved to the background. The steps that occur when moving to the foreground are shown in Figure 3-6. The applicationWillEnterForeground: method should undo anything that was done in your applicationDidEnterBackground: method, and the applicationDidBecomeActive: method should continue to perform the same activation tasks that it would at launch time. Figure 3-6 Transitioning from the background to the foreground Note: The UIApplicationWillEnterForegroundNotification notification is also available for tracking when your app reenters the foreground. Objects in your app can use the default notification center to register for this notification. Processing Queued Notifications at Wakeup Time An app in the suspended state must be ready to handle any queued notifications when it returnsto a foreground or background execution state. A suspended app does not execute any code and therefore cannot process notifications related to orientation changes, time changes, preferences changes, and many others that would affect the app’s appearance orstate. To make sure these changes are not lost, the system queues many relevant notifications and delivers them to the app as soon as it starts executing code again (either in the foreground App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48or background). To prevent your app from becoming overloaded with notifications when it resumes, the system coalesces events and delivers a single notification (of each relevant type) that reflects the net change since your app was suspended. Table 3-2 lists the notifications that can be coalesced and delivered to your app. Most of these notifications are delivered directly to the registered observers. Some, like those related to device orientation changes, are typically intercepted by a system framework and delivered to your app in another way. Table 3-2 Notifications delivered to waking apps Event Notifications EAAccessoryDidConnectNotification EAAccessoryDidDisconnectNotification An accessory is connected or disconnected. UIDeviceOrientationDidChangeNotification In addition to this notification, view controllers update their interface orientations automatically. The device orientation changes. UIApplicationSignificantTimeChangeNotification There is a significant time change. UIDeviceBatteryLevelDidChangeNotification UIDeviceBatteryStateDidChangeNotification The battery level or battery state changes. The proximity state changes. UIDeviceProximityStateDidChangeNotification UIApplicationProtectedDataWillBecomeUnavailable UIApplicationProtectedDataDidBecomeAvailable The status of protected files changes. UIScreenDidConnectNotification UIScreenDidDisconnectNotification An external display is connected or disconnected. The screen mode of a display changes. UIScreenModeDidChangeNotification Preferences that your app exposes NSUserDefaultsDidChangeNotification through the Settings app changed. The current language or locale settings NSCurrentLocaleDidChangeNotification changed. The status of the user’s iCloud account NSUbiquityIdentityDidChangeNotification changed. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49Queued notifications are delivered on your app’s main run loop and are typically delivered before any touch events or other user input. Most apps should be able to handle these events quickly enough that they would not cause any noticeable lag when resumed. However, if your app appears sluggish when it returns from the background state, use Instruments to determine whether your notification handler code is causing the delay. An app returning to the foreground also receives view-update notifications for any views that were marked dirty since the last update. An app running in the background can still call the setNeedsDisplay or setNeedsDisplayInRect: methods to request an update for its views. However, because the views are not visible, the system coalesces the requests and updates the views only after the app returns to the foreground. Handling iCloud Changes If the status of iCloud changes for any reason, the system delivers a NSUbiquityIdentityDidChangeNotification notification to your app. The state of iCloud changes when the user logs into or out of an iCloud account or enables or disables the syncing of documents and data. This notification is your app’s cue to update caches and any iCloud-related user interface elementsto accommodate the change. For example, when the user logs out of iCloud, you should remove references to all iCloud–based files or data. If your app has already prompted the user about whether to store files in iCloud, do not prompt again when the status of iCloud changes. After prompting the user the first time, store the user’s choice in your app’s local preferences. You might then want to expose that preference using a Settings bundle or as an option in your app. But do not repeat the prompt again unless that preference is not currently in the user defaults database. Handling Locale Changes Gracefully If a user changes the current language while your app is suspended, you can use the NSCurrentLocaleDidChangeNotification notification to force updates to any views containing locale-sensitive information, such as dates, times, and numbers when your app returns to the foreground. Of course, the best way to avoid language-related issues is to write your code in ways that make it easy to update views. For example: ● Use the autoupdatingCurrentLocale class method when retrieving NSLocale objects. This method returns a locale object that updates itself automatically in response to changes, so you never need to recreate it. However, when the locale changes, you still need to refresh views that contain content derived from the current locale. ● Re-create any cached date and number formatter objects whenever the current locale information changes. For more information about internationalizing your code to handle locale changes, see Internationalization Programming Topics. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50Responding to Changes in Your App’s Settings If your app has settings that are managed by the Settings app, it should observe the NSUserDefaultsDidChangeNotification notification. Because the user can modify settings while your app is suspended or in the background, you can use this notification to respond to any important changes in those settings. In some cases, responding to this notification can help close a potential security hole. For example, an email program should respond to changes in the user’s account information. Failure to monitor these changes could cause privacy or security issues. Specifically, the current user might be able to send email using the old account information, even if the account no longer belongs to that person. Upon receiving the NSUserDefaultsDidChangeNotification notification, your app should reload any relevant settings and, if necessary, reset its user interface appropriately. In cases where passwords or other security-related information has changed, you should also hide any previously displayed information and force the user to enter the new password. App Termination Although apps are generally moved to the background and suspended, if any of the following conditions are true, your app is terminated and purged from memory instead: ● The app is linked against a version of iOS earlier than 4.0. ● The app is deployed on a device running a version of iOS earlier than 4.0. ● The current device does notsupportmultitasking;see “DeterminingWhether Multitasking Is Available” (page 54). ● The app includes the UIApplicationExitsOnSuspend key in its Info.plist file; see “Opting out of Background Execution” (page 65). If your app is running (either in the foreground or background) at termination time, the system calls your app delegate’s applicationWillTerminate: method so that you can perform any required cleanup. You can use this method to save user data or app state information that you would use to restore your app to its current state on a subsequent launch. Your method has approximately 5 seconds to perform any tasks and return. If it does not return in time, the app is killed and removed from memory. Important: The applicationWillTerminate: method is not called if your app is currently suspended. Even if you develop your app using iOS SDK 4 and later, you must still be prepared for your app to be killed without any notification. The user can kill apps explicitly using the multitasking UI. In addition, if memory becomes constrained, the system might remove apps from memory to make more room. Suspended apps are not notified of termination but if your app is currently running in the background state (and not suspended), the system calls the applicationWillTerminate: method of your app delegate. Your app cannot request additional background execution time from this method. App States and Multitasking Managing App State Changes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51The Main Run Loop The main run loop of your app is responsible for processing all user-related events. The UIApplication objectsets up the main run loop at launch time and usesit to process events and handle updatesto view-based interfaces. As the name suggests, the main run loop executes on the app’s main thread. This behavior ensures that user-related events are processed serially in the order in which they were received. Figure 3-7 shows the architecture of the main run loop and how user events result in actions taken by your app. As the user interacts with a device, events related to those interactions are generated by the system and delivered to the app via a special port set up by UIKit. Events are queued internally by the app and dispatched one-by-one to the main run loop for execution. The UIApplication object is the first object to receive the event and make the decision about what needs to be done. A touch event is usually dispatched to the main window object, which in turn dispatches it to the view in which the touch occurred. Other events might take slightly different paths through various app objects. Figure 3-7 Processing events in the main run loop Many types of events can be delivered in an iOS app. The most common ones are listed in Table 3-3. Many of these event types are delivered using the main run loop of your app, but some are not. For example, accelerometer events are delivered directly to the accelerometer delegate object that you specify. For information about how to handle most types of events—including touch, remote control, motion, accelerometer, and gyroscopic events—see Event Handling Guide for iOS . App States and Multitasking The Main Run Loop 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52Table 3-3 Common types of events for iOS apps Event type Delivered to… Notes Views are responder objects. Any touch events not handled by the view are forwarded down the responder chain for processing. The view object in which the event occurred Touch Remote control events are for controlling media playback and are generated by headphones and other accessories. Remote First responder object control Motion events reflect specific motion-related events (such as shaking a device) and are handled separately from other accelerometer-based events. . Motion First responder object Events related to the accelerometer and gyroscope hardware are delivered to the object you designate. The object you designate Accelerometer Core Motion Redraw events do not involve an event object but are simply calls to the view to draw itself. The drawing architecture for iOS is described in Drawing and Printing Guide for iOS . The view that needs the update Redraw You register to receive location events using the Core Location framework. For more information about using Core Location, see Location Awareness Programming Guide . The object you designate Location Some events, such as touch and remote control events, are handled by your app’s responder objects. Responder objects are everywhere in your app. (The UIApplication object, your view objects, and your view controller objects are all examples of responder objects.) Most eventstarget a specific responder object but can be passed to other responder objects (via the responder chain) if needed to handle an event. For example, a view that does not handle an event can pass the event to its superview or to a view controller. Touch events occurring in controls (such as buttons) are handled differently than touch events occurring in many other types of views. There are typically only a limited number of interactions possible with a control, and so those interactions are repackaged into action messages and delivered to an appropriate target object. This target-action design pattern makes it easy to use controls to trigger the execution of custom code in your app. App States and Multitasking The Main Run Loop 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53Background Execution and Multitasking In iOS 4 and later, multitasking allows appsto continue running in the background even after the userswitches to another app while still preserving battery life as much as possible. Most apps are moved to the suspended state shortly after entering the background. Only apps that provide important services to the user are allowed to continue running for any amount of time. As much as possible, you are encouraged to avoid executing in the background and let your app be suspended. If you find you need to perform background tasks, here are some guidelines for when that is appropriate: ● You need to implement at least one of several specific user services. ● You need to perform a single finite-length task. ● You need to use notifications to alert the user to some relevant piece of information when your app is not running. The system keeps suspended apps in memory for as long as possible, removing them only when the amount of free memory gets low. Remaining in memory means that subsequent launches of your app are much faster. At the same time, being suspended means your app does not drain the device’s battery as fast. Determining Whether Multitasking Is Available Apps must be prepared to handle situations where multitasking (and therefore background execution) is not available. Even if your app is specifically built for iOS 4 and later, some devices running iOS 4 may not support multitasking. And multitasking is never available on devices running iOS 3 and earlier. If your app supports these earlier versions of iOS, it must be prepared to run without multitasking. If the presence or absence of multitasking changes the way your app behaves, check the multitaskingSupported property of the UIDevice class to determine whether multitasking is available before performing the relevant task. For apps built for iOS 4 and later, this property is always available. However, if your app supports earlier versions of the system, you must check to see whether the property itself is available before accessing it, as shown in Listing 3-2. Listing 3-2 Checking for background support in earlier versions of iOS UIDevice* device = [UIDevice currentDevice]; BOOL backgroundSupported = NO; if ([device respondsToSelector:@selector(isMultitaskingSupported)]) backgroundSupported = device.multitaskingSupported; App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54Executing a Finite-Length Task in the Background Apps that are transitioning to the background can request an extra amount of time to finish any important last-minute tasks. To request background execution time, call the beginBackgroundTaskWithExpirationHandler: method of the UIApplication class. If your app moves to the background while the task is in progress, or if your app was already in the background, this method delays the suspension of your app. This can be important if your app is performing some important task, such as writing user data to disk or downloading an important file from a network server. The way to use the beginBackgroundTaskWithExpirationHandler: method is to call it before starting the task you want to protect. Every call to this method must be balanced by a corresponding call to the endBackgroundTask: method to mark the end of the task. Because apps are given only a limited amount of time to finish background tasks, you must call this method before time expires; otherwise the system will terminate your app. To avoid termination, you can also provide an expiration handler when starting a task and call the endBackgroundTask: method from there. (You can use the value in the backgroundTimeRemaining property of the app object to see how much time is left.) Important: An app can have any number of tasks running at the same time. Each time you start a task, the beginBackgroundTaskWithExpirationHandler: method returns a unique identifier for the task. You must pass this same identifier to the endBackgroundTask: method when it comes time to end the task. Listing 3-3 shows how to start a long-running task when your app transitionsto the background. In this example, the request to start a background task includes an expiration handler just in case the task takes too long. The task itself is then submitted to a dispatch queue for asynchronous execution so that the applicationDidEnterBackground: method can return normally. The use of blocks simplifies the code needed to maintain references to any important variables, such as the background task identifier. The bgTask variable is a member variable of the class that stores a pointer to the current background task identifier and is initialized prior to its use in this method. Listing 3-3 Starting a background task at quit time - (void)applicationDidEnterBackground:(UIApplication *)application { bgTask = [application beginBackgroundTaskWithExpirationHandler:^{ // Clean up any unfinished task business by marking where you. // stopped or ending the task outright. [application endBackgroundTask:bgTask]; bgTask = UIBackgroundTaskInvalid; }]; App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55// Start the long-running task and return immediately. dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ // Do the work associated with the task, preferably in chunks. [application endBackgroundTask:bgTask]; bgTask = UIBackgroundTaskInvalid; }); } Note: Always provide an expiration handler when starting a task, but if you want to know how much time your app has left to run, get the value of the backgroundTimeRemaining property of UIApplication. In your own expiration handlers, you can include additional code needed to close out your task. However, any code you include must not take too long to execute because, by the time your expiration handler is called, your app is already very close to its time limit. For this reason, perform only minimal cleanup of your state information and end the task. Scheduling the Delivery of Local Notifications Notifications are a way for an app that is suspended, is in the background, or is not running to get the user’s attention. Apps can use local notificationsto display alerts, play sounds, badge the app’sicon, or a combination of the three. For example, an alarm clock app might use local notifications to play an alarm sound and display an alert to disable the alarm. When a notification is delivered to the user, the user must decide if the information warrants bringing the app back to the foreground. (If the app is already running in the foreground, local notifications are delivered quietly to the app and not to the user.) To schedule the delivery of a local notification, create an instance of the UILocalNotification class, configure the notification parameters, and schedule it using the methods of the UIApplication class. The local notification object contains information about the type of notification to deliver (sound, alert, or badge) and the time (when applicable) at which to deliver it. The methods of the UIApplication class provide options for delivering notifications immediately or at the scheduled time. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56Listing 3-4 shows an example that schedules a single alarm using a date and time that is set by the user. This example configures only one alarm at a time and cancels the previous alarm before scheduling a new one. (Your own apps can have no more than 128 local notifications active at any given time, any of which can be configured to repeat at a specified interval.) The alarm itself consists of an alert box and a sound file that is played if the app is not running or is in the background when the alarm fires. If the app is active and therefore running in the foreground, the app delegate’s application:didReceiveLocalNotification: method is called instead. Listing 3-4 Scheduling an alarm notification - (void)scheduleAlarmForDate:(NSDate*)theDate { UIApplication* app = [UIApplication sharedApplication]; NSArray* oldNotifications = [app scheduledLocalNotifications]; // Clear out the old notification before scheduling a new one. if ([oldNotifications count] > 0) [app cancelAllLocalNotifications]; // Create a new notification. UILocalNotification* alarm = [[UILocalNotification alloc] init]; if (alarm) { alarm.fireDate = theDate; alarm.timeZone = [NSTimeZone defaultTimeZone]; alarm.repeatInterval = 0; alarm.soundName = @"alarmsound.caf"; alarm.alertBody = @"Time to wake up!"; [app scheduleLocalNotification:alarm]; } } App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 57Sound files used with local notifications have the same requirements as those used for push notifications. Custom sound files must be located inside your app’s main bundle and support one of the following formats: Linear PCM, MA4, µ-Law, or a-Law. You can also specify the sound name default to play the default alert sound for the device. When the notification is sent and the sound is played, the system also triggers a vibration on devices that support it. You can cancel scheduled notifications or get a list of notifications using the methods of the UIApplication class. For more information about these methods,see UIApplication Class Reference . For additional information about configuring local notifications, see Local and Push Notification Programming Guide . Implementing Long-Running Background Tasks For tasks that require more execution time to implement, you must request specific permissions to run them in the background without their being suspended. In iOS, only specific app types are allowed to run in the background: ● Apps that play audible content to the user while in the background, such as a music player app ● Apps that keep users informed of their location at all times, such as a navigation app ● Apps that support Voice over Internet Protocol (VoIP) ● Newsstand apps that need to download and process new content ● Apps that receive regular updates from external accessories Apps that implement these services must declare the services they support and use system frameworks to implement the relevant aspects of those services. Declaring the services lets the system know which services you use, but in some cases it is the system frameworks that actually prevent your application from being suspended. Declaring Your App’s Supported Background Tasks Support for some types of background execution must be declared in advance by the app that uses them. An app declares support for a service using its Info.plist file. Add the UIBackgroundModes key to your Info.plist file and set its value to an array containing one or more of the following strings: ● audio—The app plays audible content to the user while in the background. (This content includes streaming audio or video content using AirPlay.) ● location—The app keeps users informed of their location, even while it is running in the background. ● voip—The app provides the ability for the user to make phone calls using an Internet connection. ● newsstand-content—The app is aNewsstand app that downloads and processesmagazine or newspaper content in the background. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 58● external-accessory—The app works with a hardware accessory that needs to deliver updates on a regular schedule through the External Accessory framework. ● bluetooth-central—The app works with a Bluetooth accessory that needs to deliver updates on a regular schedule through the Core Bluetooth framework. ● bluetooth-peripheral—The app supports Bluetooth communication in peripheral mode through the Core Bluetooth framework. Each of the preceding values lets the system know that your app should be woken up at appropriate times to respond to relevant events. For example, an app that begins playing music and then moves to the background still needs execution time to fill the audio output buffers. Including the audio key tells the system frameworks that they should continue playing and make the necessary callbacks to the app at appropriate intervals. If the app does not include this key, any audio being played by the app stops when the app movesto the background. Tracking the User’s Location There are several ways to track the user’s location in the background, most of which do not actually require your app to run continuously in the background: ● The significant-change location service (Recommended) ● Foreground-only location services ● Background location services The significant-change location service is highly recommended for apps that do not need high-precision location data. With this service, location updates are generated only when the user’s location changes significantly; thus, it is ideal for social apps or apps that provide the user with noncritical, location-relevant information. If the app is suspended when an update occurs, the system wakes it up in the background to handle the update. If the app starts this service and is then terminated, the system relaunches the app automatically when a new location becomes available. This service is available in iOS 4 and later, and it is available only on devices that contain a cellular radio. The foreground-only and background location services both use the standard location Core Location service to retrieve location data. The only difference is that the foreground-only location services stop delivering updates if the app is ever suspended, which is likely to happen if the app does not support other background services or tasks. Foreground-only location services are intended for apps that only need location data while they are in the foreground. An app that provides continuous location updates to the user (even when in the background) can enable background location services by including the UIBackgroundModes key (with the location value) in its Info.plist file. The inclusion of this value in the UIBackgroundModes key does not preclude the system App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 59from suspending the app, but it does tell the system that it should wake up the app whenever there is new location data to deliver. Thus, this key effectively letsthe app run in the background to processlocation updates whenever they occur. Important: You are encouraged to use the standard servicessparingly or use the significant location change service instead. Location servicesrequire the active use of an iOS device’s onboard radio hardware. Running this hardware continuously can consume a significant amount of power. If your app does not need to provide precise and continuous location information to the user, it is best to minimize the use of location services. For information about how to use each of the different location services in your app, see Location Awareness Programming Guide . Playing Background Audio An app that plays audio continuously (even while the app is running in the background) can register as a background audio app by including the UIBackgroundModes key (with the value audio) in its Info.plist file. Apps that include this key must play audible content to the user while in the background. Typical examples of background audio apps include: ● Music player apps ● Apps that support audio or video playback over AirPlay ● VoIP apps When the UIBackgroundModes key contains the audio value, the system’s media frameworks automatically prevent the corresponding app from being suspended when it moves to the background. As long as it is playing audio or video content, the app continues to run in the background. However, if the app stops playing the audio or video, the system suspends it. You can use any of the system audio frameworks to initiate the playback of background audio, and the process for using those frameworks is unchanged. (For video playback over AirPlay, you can use the Media Player or AV Foundation framework to present your video.) Because your app is not suspended while playing media files, callbacks operate normally while your app is in the background. In your callbacks, though, you should do only the work necessary to provide data for playback. For example, a streaming audio app would need to download the music stream data from its server and push the current audio samples out for playback. You should not perform any extraneous tasks that are unrelated to playback. Because more than one app may support audio, the system limits which apps can play audio at any given time. The foreground app always has permission to play audio. In addition, one or more background apps may also be allowed to play some audio content depending on the configuration of their audio session objects. You App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 60should always configure your app’s audio session object appropriately and work carefully with the system frameworks to handle interruptions and other types of audio-related notifications. For information on how to configure audio session objects for background execution, see Audio Session Programming Guide . Implementing a VoIP App A Voice over Internet Protocol (VoIP) app allows the user to make phone calls using an Internet connection instead of the device’s cellular service. Such an app needs to maintain a persistent network connection to its associated service so that it can receive incoming calls and other relevant data. Rather than keep VoIP apps awake all the time, the system allowsthem to be suspended and providesfacilitiesfor monitoring theirsockets for them. When incoming traffic is detected, the system wakes up the VoIP app and returns control of itssockets to it. To configure a VoIP app, you must do the following: 1. Add the UIBackgroundModes key to your app’s Info.plist file. Set the value of this key to an array that includes the voip value. 2. Configure one of the app’s sockets for VoIP usage. 3. Before moving to the background, call the setKeepAliveTimeout:handler: method to install a handler to be executed periodically. Your app can use this handler to maintain its service connection. 4. Configure your audio session to handle transitions to and from active use. Including the voip value in the UIBackgroundModes key lets the system know that it should allow the app to run in the background as needed to manage its network sockets. An app with this key is also relaunched in the background immediately after system boot to ensure that the VoIP services are always available. Most VoIP apps also need to be configured as background audio appsto deliver audio while in the background. Therefore, you should include both the audio and voip values to the UIBackgroundModes key. If you do not do this, your app cannot play audio while it is in the background. For more information about the UIBackgroundModes key, see Information Property List Key Reference . For specific information about the steps you must take to implement a VoIP app, see “Tips for Developing a VoIP App” (page 115). Downloading Newsstand Content in the Background A Newsstand app that downloads new magazine or newspaper issues can register to perform those downloads in the background. When your server sends a push notification to indicate that a new issue is available, the system checks to see whether your app has the UIBackgroundModes key with the newsstand-content value. If it does, the system launches your app, if it is not already running,so that it can initiate the downloading of the new issue. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 61When you use the Newsstand Kit framework to initiate a download, the system handles the download process for your app. The system continues to download the file even if your app is suspended or terminated. When the download operation is complete, the system transfers the file to your app sandbox and notifies your app. If the app is not running, this notification wakes it up and gives it a chance to process the newly downloaded file. If there are errors during the download process, your app is similarly woken up to handle them. For information about how to download content using the Newsstand Kit framework, see Newsstand Kit Framework Reference . Communicating with an External Accessory Apps that work with external accessories can ask to be woken up if the accessory delivers an update when the app is suspended. This support is important for some types of accessories that deliver data at regular intervals, such as heart-rate monitors. When an app includes the UIBackgroundModes key with the external-accessory value in its Info.plist file, the external accessory framework keeps open any active sessions for the corresponding accessories. (In iOS 4 and earlier, these sessions are closed automatically when the app is suspended.) In addition, new data arriving from the accessory causes the system to wake up the app to processthat data. The system also wakes up the app to process accessory connection and disconnection notifications. Any app that supports the background processing of accessory updates must follow a few basic guidelines: ● Apps must provide an interface that allows the user to start and stop the delivery of accessory update events. That interface should then open or close the accessory session as appropriate. ● Upon being woken up, the app has around 10 seconds to process the data. Ideally, it should process the data as fast as possible and allow itself to be suspended again. However, if more time is needed, the app can use the beginBackgroundTaskWithExpirationHandler: method to request additional time; it should do so only when absolutely necessary, though. Communicating with a Bluetooth Accessory Apps that work with Bluetooth peripherals can ask to be woken up if the peripheral delivers an update when the app issuspended. Thissupport isimportant for Bluetooth-le accessoriesthat deliver data at regular intervals, such as a Bluetooth heart rate belt. When an app includes the UIBackgroundModes key with the bluetooth-central value in its Info.plist file, the Core Bluetooth framework keeps open any active sessionsfor the corresponding peripheral. In addition, new data arriving from the peripheral causesthe system to wake up the app so that it can process the data. The system also wakes up the app to process accessory connection and disconnection notifications. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 62In iOS 6, an app can also operate in peripheral mode with Bluetooth accessories. If the app wants to respond to accessory-related changes using peripheral mode in the background, it must link against the Core Bluetooth framework and include the UIBackgroundModes key with the bluetooth-peripheral value in its Info.plist file. This key lets the Core Bluetooth framework wake the app up briefly in the background so that it can handle accessory-related requests. Apps woken up for these events should process them and return as quickly as possible so that the app can be suspended again. Any app that supports the background processing of Bluetooth data must be session-based and follow a few basic guidelines: ● Apps must provide an interface that allows the user to start and stop the delivery of Bluetooth events. That interface should then open or close the session as appropriate. ● Upon being woken up, the app has around 10 seconds to process the data. Ideally, it should process the data as fast as possible and allow itself to be suspended again. However, if more time is needed, the app can use the beginBackgroundTaskWithExpirationHandler: method to request additional time; it should do so only when absolutely necessary, though. Being a Responsible Background App The foreground app always has precedence over background apps when it comesto the use ofsystem resources and hardware. Apps running in the background need to be prepared for this discrepancy and adjust their behavior when running in the background. Specifically, apps moving to the background should follow these guidelines: ● Do not make any OpenGL ES calls from your code. You must not create an EAGLContext object or issue any OpenGL ES drawing commands of any kind while running in the background. Using these calls causes your app to be killed immediately. Apps must also ensure that any previously submitted commands have completed before moving to the background. For information about how to handle OpenGL ES when moving to and from the background,see “Implementing a Multitasking-awareOpenGL ES Application” in OpenGL ES Programming Guide for iOS . ● Cancel any Bonjour-related services before being suspended. When your app movesto the background, and before it is suspended, it should unregister from Bonjour and close listening sockets associated with any network services. A suspended app cannot respond to incoming service requests anyway. Closing out those services prevents them from appearing to be available when they actually are not. If you do not close out Bonjour services yourself, the system closes out those services automatically when your app is suspended. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 63● Be prepared to handle connection failures in your network-based sockets. The system may tear down socket connections while your app is suspended for any number of reasons. As long as your socket-based code is prepared for other types of network failures, such as a lost signal or network transition, this should not lead to any unusual problems. When your app resumes, if it encounters a failure upon using a socket, simply reestablish the connection. ● Save your app state before moving to the background. During low-memory conditions, background apps may be purged from memory to free up space. Suspended apps are purged first, and no notice is given to the app before it is purged. As a result, apps should take advantage of the state preservation mechanism in iOS 6 and later to save their interface state to disk. For information about how to support this feature, see “State Preservation and Restoration” (page 67). ● Remove strong references to unneeded objects whenmoving to the background. If your app maintains a large in-memory cache of objects(especially images), remove allstrong referencesto those caches when moving to the background. For more information, see “Memory Usage for Background Apps” (page 47). ● Stop using shared system resources before being suspended. Apps that interact with shared system resources such as the Address Book or calendar databases should stop using those resources before being suspended. Priority for such resources always goes to the foreground app. When your app is suspended, if it is found to be using a shared resource, the app is killed. ● Avoid updating your windows and views. While in the background, your app’s windows and views are not visible, so you should not try to update them. Although creating and manipulating window and view objects in the background does not cause your app to be killed, consider postponing this work until you return to the foreground. ● Respond to connect and disconnect notifications for external accessories. For apps that communicate with external accessories, the system automatically sends a disconnection notification when the app moves to the background. The app must register for this notification and use it to close out the current accessory session. When the app moves back to the foreground, a matching connection notification is sent, giving the app a chance to reconnect. For more information on handling accessory connection and disconnection notifications, see External Accessory Programming Topics. ● Clean up resources for active alerts when moving to the background. In order to preserve context when switching between apps, the system does not automatically dismiss action sheets (UIActionSheet) or alert views (UIAlertView) when your app moves to the background. It is up to you to provide the appropriate cleanup behavior prior to moving to the background. For example, you might want to cancel the action sheet or alert view programmatically orsave enough contextual information to restore the view later (in cases where your app is terminated). For apps linked against a version of iOS earlier than 4.0, action sheets and alerts are still dismissed at quit time so that your app’s cancellation handler has a chance to run. App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 64● Remove sensitive information from views before moving to the background. When an app transitions to the background, the system takes a snapshot of the app’s main window, which it then presents briefly when transitioning your app back to the foreground. Before returning from your applicationDidEnterBackground: method, you should hide or obscure passwords and othersensitive personal information that might be captured as part of the snapshot. ● Do minimal work while running in the background. The execution time given to background apps is more constrained than the amount of time given to the foreground app. If your app plays background audio or monitors location changes, you should focus on that task only and defer any nonessential tasks until later. Apps that spend too much time executing in the background can be throttled back by the system or killed. If you are implementing a background audio app, or any other type of app that is allowed to run in the background, your app responds to incoming messages in the usual way. In other words, the system may notify your app of low-memory warnings when they occur. And in situations where the system needs to terminate apps to free even more memory, the app calls its delegate’s applicationWillTerminate: method to perform any final tasks before exiting. Opting out of Background Execution If you do not want your app to run in the background at all, you can explicitly opt out of background by adding the UIApplicationExitsOnSuspend key (with the value YES) to your app’s Info.plist file. When an app opts out, it cycles between the not-running, inactive, and active states and never enters the background or suspended states. When the user pressesthe Home button to quit the app, the applicationWillTerminate: method of the app delegate is called and the app has approximately 5 seconds to clean up and exit before it is terminated and moved back to the not-running state. Opting out of background execution is strongly discouraged but may be the preferred option under certain conditions. Specifically, if coding for the background adds significant complexity to your app, terminating the app might be a simpler solution. Also, if your app consumes a large amount of memory and cannot easily release any of it, the system might kill your app quickly anyway to make room for other apps. Thus, opting to terminate, instead of switching to the background, might yield the same results and save you development time and effort. Note: Explicitly opting out of background execution is necessary only if your app is linked against iOS SDK 4 and later. Apps linked against earlier versions of the SDK do not support background execution as a rule and therefore do not need to opt out explicitly. For more information about the keys you can include in your app’s Info.plist file, see Information Property List Key Reference . App States and Multitasking Background Execution and Multitasking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 65Concurrency and Secondary Threads The system creates your app’s main thread but your app can create additional threads as needed to perform other tasks. The preferred way to create threadsisto let the system do it for you by using Grand Central Dispatch queues and operation queues. Both types of queue provide an asynchronous execution model for tasks that you define. When you submit a task to a queue, the system spins up a thread and executes your task on that thread. Letting the system manage the threads simplifies your code and allows the system to manage the threads in the most efficient way available. You should use queues whenever possible to move work off of your app’s main thread. Because the main thread is responsible for processing touch and drawing events, you should never perform lengthy tasks on it. For example, you should never wait for a network response on your app’s main thread. It is much better to make the request asynchronously using a queue and process the results when they arrive. Another good time to move tasks to secondary threads is launch time. Launched apps have a limited amount of time (around 5 seconds) to do their initialization and start processing events. If you have launch-time tasks that can be deferred or executed on a secondary thread, you should move them off the main thread right away and use the main thread only to present your user interface and start handling events. Formore information about using dispatch and operation queuesto execute tasks,see Concurrency Programming Guide . App States and Multitasking Concurrency and Secondary Threads 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 66Even if your app supports background execution, it cannot run forever. At some point, the system might need to terminate your app to free up memory for the current foreground app. However, the user should never have to care if an app is already running or wasterminated. From the user’s perspective, quitting an app should just seem like a temporary interruption. When the user returns to an app, that app should always return the user to the last point of use, so that the user can continue with whatever task was in progress. This behavior provides a better experience for the user and with the state restoration support built in to UIKit is relatively easy to achieve. The state preservation system in UIKit provides a simple but flexible infrastructure for preserving and restoring the state of your app’s view controllers and views. The job of the infrastructure is to drive the preservation and restoration processes at the appropriate times. To do that, UIKit needs help from your app. Only you understand the content of your app, and so only you can write the code needed to save and restore that content. And when you update your app’s UI, only you know how to map older preserved content to the newer objects in your interface. There are three places where you have to think about state preservation in your app: ● Your app delegate object, which manages the app’s top-level state ● Your app’s view controller objects, which manage the overall state for your app’s user interface ● Your app’s custom views, which might have some custom data that needs to be preserved UIKit allows you to choose which parts of your user interface you want to preserve. And if you already have custom code for handling state preservation, you can continue to use that code and migrate portions to the UIKit state preservation system as needed. The Preservation and Restoration Process State preservation and restoration is an opt-in feature and requires help from your app to work. Your app essentially provides UIKit with a list of objects and lets UIKit handle the tedious aspects of preserving and restoring those objects at appropriate times. Because UIKit handlesso much of the process, it helpsto understand what it does behind the scenes so that you know how your custom code fits into the overall scheme. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 67 State Preservation and RestorationWhen thinking about state preservation and restoration, it helps to separate the two processes first. State preservation occurs when your app moves to the background. At that time, UIKit queries your app’s views and view controllersto see which onesshould be preserved and which onesshould not. For each object thatshould be preserved, UIKit writes preservation-related data to an on-disk file. The next time your app launches from scratch, UIKit looks for that file and, if it is present, uses it to try and restore your app’s state. During the restoration process, UIKit uses the preserved data to reconstitute your interface. The creation of actual objects is handled by your code. Because your app might load objects from a storyboard file automatically, only your code knows which objects need to be created and which might already exist and can simply be returned. After those objects are created, UIKit uses the on-disk data to restore the objects to their previous state. During the preservation and restoration process, your app has a handful of responsibilities. ● During preservation, your app is responsible for: ● Telling UIKit that it supports state preservation. ● Telling UIKit which view controllers and views should be preserved. ● Encoding relevant data for any preserved objects. ● During restoration, your app is responsible for: ● Telling UIKit that it supports state restoration. ● Providing (or creating) the objects that are requested by UIKit. ● Decoding the state of your preserved objects and using it to return the object to its previous state. Of your app’s responsibilities, the most significant are telling UIKit which objects to preserve and providing those objects during subsequent launches. Those two behaviors are where you should spend most of your time when designing your app’s preservation and restoration code. They are also where you have the most control over the actual process. To understand why that is the case, it helps to look at an example. Figure 4-1 shows the view controller hierarchy of a tab bar interface after the user has interacted with several of the tabs. As you can see, some of the view controllers are loaded automatically as part of the app’s main storyboard file butsome of the view controllers were presented or pushed onto the view controllersin different State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 68tabs. Without state restoration, only the view controllers from the main storyboard file would be restored during subsequent launches. By adding support for state restoration to your app, you can preserve all of the view controllers. Figure 4-1 A sample view controller hierarchy Loaded at launch time from the main storyboard file Added by the app after launch UINavigation Controller MyViewController MyPresented Controller UINavigation Controller Root Nav 2 Nav 1 Root Nav 1 UITabBar Controller MainStoryboard.storyboard State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 69UIKit preserves only those objects that have a restoration identifier. A restoration identifier is a string that identifies the view or view controller to UIKit and your app. The value of this string is significant only to your code but the presence of thisstring tells UIKit that it needsto preserve the tagged object. During the preservation process, UIKit walks your app’s view controller hierarchy and preserves all objects that have a restoration State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 70identifier. If a view controller does not have a restoration identifier, that view controller and all of its views and child view controllers are not preserved. Figure 4-2 shows an updated version of the previous view hierarchy, now with restoration identifies applied to most (but not all) of the view controllers. State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 71Figure 4-2 Adding restoration identifies to view controllers * * * * * * * * * Loaded at launch time from the main storyboard file Added by the app after launch Has restoration identifier X Does not have restoration identifier (not restored) * UINavigation Controller MyViewController MyPresented Controller UINavigation Controller Root Nav 2 Nav 1 Root Nav 1 UITabBar Controller MainStoryboard.storyboard X State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 72Depending on your app, it might or might not make sense to preserve every view controller. If a view controller presents transitory information, you might not want to return to that same point on restore, opting instead to return the user to a more stable point in your interface. For each view controller you choose to preserve, you also need to decide on how you want to restore it later. UIKit offerstwo waysto recreate objects. You can let your app delegate recreate it or you can assign a restoration class to the view controller and let that class recreate it. A restoration class implements the UIViewControllerRestoration protocol and is responsible for finding or creating a designated object at restore time. Here are some tips for when to use each one: ● If the view controller is always loaded from your app’s main storyboard file at launch time, do not assign a restoration class. Instead, let your app delegate find the object or take advantage of UIKit’s support for implicitly finding restored objects. ● For view controllers that are not loaded from your main storyboard file at launch time, assign a restoration class. The simplest option is to make each view controller its own restoration class. During the preservation process, UIKit identifies the objects to save and writes each affected object’s state to disk. Each view controller object is given a chance to write out any data it wants to save. For example, a tab view controller saves the identity of the selected tab. UIKit also saves information such as the view controller’s restoration class to disk. And if any of the view controller’s views has a restoration identifier, UIKit asks them to save their state information too. The next time the app is launched, UIKit loads the app’s main storyboard or nib file as usual, calls the app delegate’s application:willFinishLaunchingWithOptions: method, and then tries to restore the app’s previous state. The first thing it does is ask your app to provide the set of view controller objects that match the ones that were preserved. If a given view controller had an assigned restoration class, that class is asked to provide the object; otherwise, the app delegate is asked to provide it. State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 73Flow of the Preservation Process Figure 4-3 shows the high-level events that happen during state preservation and shows how the objects of your app are affected. Before preservation even occurs, UIKit asks your app delegate if itshould occur by calling the application:shouldSaveApplicationState: method. If that method returns YES, UIKit begins gathering and encoding your app’s views and view controllers. When it is finished, it writes the encoded data to disk. Figure 4-3 High-level flow interface preservation UIKit Save UI Done No Yes App supports save? application: shouldSaveApplicationState: application: willEncodeRestorableState: App Delegate @property restorationIdentifier encodeRestorableStateWithCoder: View /View Controller Objects @property restorationClass View Controller Only Start app preservation Gather restorable objects Encode restorable objects Write state to disk The next time your app launches, the system automatically looks for a preserved state file, and if present, uses it to restore your interface. Because this state information is only relevant between the previous and current launch cycles of your app, the file istypically discarded after your app finisheslaunching. The file is also discarded any time there is an error restoring your app. For example, if your app crashes during the restoration process, the system automatically throws away the state information during the next launch cycle to avoid another crash. State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 74Flow of the Restoration Process Figure 4-4 shows the high-level events that happen during state restoration and shows how the objects of your app are affected. After the standard initialization and UI loading is complete, UIKit asks your app delegate if state restoration should occur at all by calling the application:shouldRestoreApplicationState: State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 75method. Thisis your app delegate’s opportunity to examine the preserved data and determine ifstate restoration is possible. If it is, UIKit uses the app delegate and restoration classes to obtain references to your app’s view controllers. Each object is then provided with the data it needs to restore itself to its previous state. Figure 4-4 High-level flow for restoring your user interface UIKit App launches Load initial UI First app initialization Run app No Yes App supports restore? application: willFinishLaunchingWithOptions: application: shouldRestoreApplicationState: application: viewControllerWithRestoration IdentifierPath:coder: App Delegate viewControllerWithRestoration IdentifierPath:coder: Restoration Classes decodeRestorableStateWithCoder: View /View Controller Object application: didDecodeRestorableState: application: didFinishLaunchingWithOptions: App Delegate Obtain view controllers Decode restorable objects Finish app restoration Finish app initialization State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 76Although UIKit helps restore the individual view controllers, it does not automatically restore the relationships between those view controllers. Instead, each view controller is responsible for encoding enough state information to return itself to its previous state. For example, a navigation controller encodes information about the order of the view controllers on its navigation stack. It then uses this information later to return those view controllers to their previous positions on the stack. Other view controllers that have embedded child view controllers are similarly responsible for encoding any information they need to restore their children later. Note: Not all view controllers need to encode their child view controllers. For example, tab bar controllers do not encode information about their child view controllers. Instead, it is assumed that your app followsthe usual pattern of creating the appropriate child view controllers prior to creating the tab bar controller itself. Because you are responsible for recreating your app’s view controllers, you have some flexibility to change your interface during the restoration process. For example, you could reorder the tabs in a tab bar controller and still use the preserved data to return each tab to its previousstate. Of course, if you make dramatic changes to your view controller hierarchy, such as during an app update, you might not be able to use the preserved data. State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 77What Happens When You Exclude Groups of View Controllers? When the restoration identifier of a view controller is nil, that view controller and any child view controllers it manages are not preserved automatically. For example, in Figure 4-6, because a navigation controller did not have a restoration identifier, it and all of its child view controllers and views are omitted from the preserved data. State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 78Figure 4-5 Excluding view controllers from the automatic preservation process * * * * * * X * * * Preserved automatically Not preserved automatically UINavigation Controller MyViewController MyPresented Controller UINavigation Controller UITabBar Controller MainStoryboard.storyboard Has restoration identifier X Does not have restoration identifier * State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 79Even if you decide not to preserve view controllers, that does not mean all of those view controllers disappear from the view hierarchy altogether. At launch time, your app might still create the view controllers as part of its default setup. For example, if any view controllers are loaded automatically from your app’s storyboard file, they would still appear, albeit in their default configuration, as shown in Figure 4-6. Figure 4-6 Loading the default set of view controllers Loaded with the main storyboard file Created during the restoration process UINavigation Controller MyViewController MyPresented Controller UINavigation Controller UITabBar Controller MainStoryboard.storyboard State Preservation and Restoration The Preservation and Restoration Process 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 80Something else to realize is that even if a view controller is not preserved automatically, you can still encode a reference to that view controller and preserve it manually. In Figure 4-5 (page 79), the three child view controllers of the first navigation controller have restoration identifiers, even though there parent navigation controller does not. If your app delegate (or any preserved object) encodes a reference to those view controllers, their state is preserved. Even though their order in the navigation controller is not saved, you could still use those referencesto recreate the view controllers and install them in the navigation controller during subsequent launch cycles. Checklist for Implementing State Preservation and Restoration Supporting state preservation and restoration requires modifying your app delegate and view controller objects to encode and decode the state information. If your app has any custom views that also have preservable state information, you need to modify those objects too. When adding state preservation and restoration to your code, use the following list to remind you of the code you need to write. ● (Required) Implement the application:shouldSaveApplicationState: and application:shouldRestoreApplicationState: methods in your app delegate; see “Enabling State Preservation and Restoration in Your App” (page 82). ● (Required) Assign restoration identifiers to each view controller you want to preserve. a non empty string to their restorationIdentifier property; see “Marking Your View Controllers for Preservation” (page 83). If you want to save the state of specific views too, assign non empty strings to their restorationIdentifier properties; see “Preserving the State of Your Views” (page 86). ● (Required) Assign restoration classes to the appropriate view controllers. (If you do not do this, your app delegate is asked to provide the corresponding view controller at restore time.) See “Restoring Your View Controllers at Launch Time” (page 83). ● (Recommended) Encode and decode the state of your views and view controllers using the encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: methods of those objects; see “Encoding and Decoding Your View Controller’s State” (page 85). ● Encode and decode any version information or additional state information for your app using the application:willEncodeRestorableStateWithCoder: and application:didDecodeRestorableStateWithCoder:methods of your app delegate;see “Preserving Your App’s High-Level State” (page 89). State Preservation and Restoration Checklist for Implementing State Preservation and Restoration 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 81● Objects that act as data sources for table views and collection views should implement the UIDataSourceModelAssociation protocol. Although not required, this protocol helps preserve the selected and visible items in those types of views. See “Implementing Preservation-Friendly Data Sources” (page 89). Enabling State Preservation and Restoration in Your App State preservation and restoration is not an automatic feature and apps must opt-in to use it. Apps indicate their support for the feature by implementing the following methods in their app delegate: application:shouldSaveApplicationState: application:shouldRestoreApplicationState: Normally, your implementations of these methods just return YES to indicate that state preservation and restoration can occur. However, apps that want to preserve and restore their state conditionally can return NO in situations where the operations should not occur. For example, after releasing an update to your app, you might want to return NO from your application:shouldRestoreApplicationState: method if your app is unable to usefully restore the state from a previous version. Preserving the State of Your View Controllers Preserving the state of your app’s view controllers should be your main goal. View controllers define the structure of your user interface. They manage the views needed to present that interface and they coordinate the getting and setting of the data that backs those views. To preserve the state of a single view controller, you must do the following: ● (Required) Assign a restoration identifier to the view controller; see “Marking Your View Controllers for Preservation” (page 83). ● (Required) Provide code to create or locate new view controller objects at launch time; see “Restoring Your View Controllers at Launch Time” (page 83). ● (Optional) Implement the encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: methodsto encode and restore any state information that cannot be recreated during a subsequent launch;see “Encoding and Decoding Your View Controller’s State” (page 85). State Preservation and Restoration Enabling State Preservation and Restoration in Your App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 82Marking Your View Controllers for Preservation UIKit preserves only those view controllers whose restorationIdentifier property contains a valid string object. For view controllers that you know you want to preserve, set the value of this property when you initialize the view controller object. If you load the view controller from a storyboard or nib file, you can set the restoration identifier there. Choosing an appropriate value for restoration identifiers is important. During the restoration process, your code uses the restoration identifier to determine which view controller to retrieve or create. If every view controller object is based on a different class, you can use the class name for the restoration identifier. However, if your view controller hierarchy contains multiple instances of the same class, you might need to choose different names based on each view usage. When it asks you to provide a view controller, UIKit provides you with the restoration path of the view controller object. A restoration path is the sequence of restoration identifiers starting at the root view controller and walking down the view controller hierarchy to the current object. For example, imagine you have a tab bar controller whose restoration identifier is TabBarControllerID, and the first tab contains a navigation controller whose identifier is NavControllerID and whose root view controller’s identifier is MyViewController. The full restoration path for the root view controller would be TabBarControllerID/NavControllerID/MyViewController. The restoration path for every object must be unique. If a view controller has two child view controllers, each child must have a different restoration identifier. However, two view controllers with different parent objects may use the same restoration identifier because the rest of the restoration path providesthe needed uniqueness. Some UIKit view controllers, such as navigation controllers, automatically disambiguate their child view controllers, allowing you to use the same restoration identifiers for each child. For more information about the behavior of a given view controller, see the corresponding class reference. At restore time, you use the provided restoration path to determine which view controller to return to UIKit. For more information on how you use restoration identifiers and restoration paths to restore view controllers, see “Restoring Your View Controllers at Launch Time” (page 83). Restoring Your View Controllers at Launch Time During the restoration process, UIKit asks your app to create (or locate) the view controller objectsthat comprise your preserved user interface. UIKit adheres to the following process when trying to locate view controllers: 1. If the view controller had a restoration class, UIKit asks that class to provide the view controller. UIKit calls the viewControllerWithRestorationIdentifierPath:coder: method of the associated restoration classto retrieve the view controller. If that method returns nil, it is assumed that the app does not want to recreate the view controller and UIKit stops looking for it. State Preservation and Restoration Preserving the State of Your View Controllers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 832. If the view controller did not have a restoration class, UIKit asks the app delegate to provide the view controller.UIKit callsthe application:viewControllerWithRestorationIdentifierPath:coder: method of your app delegate to look for view controllers without a restoration class. If that method returns nil, UIKit tries to find the view controller implicitly. 3. If a view controller with the correct restoration path already exists, UIKit uses that object. If your app creates view controllers at launch time (either programmatically or by loading them from a resource file) and assigns restoration identifiers to them, UIKit finds them implicitly through their restoration paths. 4. If the view controller was originally loaded from a storyboard file, UIKit uses the saved storyboard information to locate and create it. UIKit saves information about a view controller’s storyboard inside the restoration archive. At restore time, it uses that information to locate the same storyboard file and instantiate the corresponding view controller if the view controller was not found by any other means. It is worth noting that if you specify a restoration class for a view controller, UIKit does not try to find your view controller implicitly. If the viewControllerWithRestorationIdentifierPath:coder: method of your restoration class returns nil, UIKit stops trying to locate your view controller. This gives you control over whether you really want to create the view controller. If you do not specify a restoration class, UIKit does everything it can to find the view controller for you, creating it as necessary from your app’s storyboard files. If you choose to use a restoration class, the implementation of your viewControllerWithRestorationIdentifierPath:coder: method should create a new instance of the class, perform some minimal initialization, and return the resulting object. Listing 4-1 shows an example of how you might use this method to load a view controller from a storyboard. Because the view controller was originally loaded from a storyboard, this method uses the UIStateRestorationViewControllerStoryboardKey key to get the name of the original storyboard file from the archive. Note that this method does not try to configure the view controller’s data fields. That step occurs later when the view controller’s state is decoded. Listing 4-1 Creating a new view controller during restoration + (UIViewController*) viewControllerWithRestorationIdentifierPath:(NSArray *)identifierComponents coder:(NSCoder *)coder { MyViewController* vc; NSString* storyboardName = [coder decodeObjectForKey:UIStateRestorationViewControllerStoryboardKey]; UIStoryboard* sb = [UIStoryboard storyboardWithName:storyboardName bundle:nil]; if (storyboardName) { vc = (MyViewController*)[sb instantiateViewControllerWithIdentifier:@"MyViewController"]; State Preservation and Restoration Preserving the State of Your View Controllers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 84thePush.restorationIdentifier = [identifierComponents lastObject]; thePush.restorationClass = [MyViewController class]; } return vc; } Reassigning the restoration identifier and restoration class, as in the preceding example, is a good habit to adopt when creating new view controllers. The simplest way to restore the restoration identifier is to grab the last item in the identifierComponents array and assign it to your view controller. For objects that were already loaded from your app’s main storyboard file at launch time, do not create a new instance of each object. Instead, implement the application:viewControllerWithRestorationIdentifierPath:coder:method of your app delegate and use it to return the appropriate objects or let UIKit find those objects implicitly. Encoding and Decoding Your View Controller’s State For each objectslated for preservation, UIKit callsthe object’s encodeRestorableStateWithCoder: method to give it a chance to save its state. During the decode process, a matching call to the decodeRestorableStateWithCoder: method is made to decode that state and apply it to the object. The implementation of these methods is optional, but recommended, for your view controllers. You can use them to save and restore the following types of information: ● References to any data being displayed (not the data itself) ● For a container view controller, references to its child view controllers ● Information about the current selection ● For view controllers with a user-configurable view, information about the current configuration of that view. In your encode and decode methods, you can encode any values supported by the coder, including other objects. For all objects except views and view controllers, the object must adopt the NSCoding protocol and use the methods of that protocol to write its state. For views and view controllers, the coder does not use the methods of the NSCoding protocol to save the object’sstate. Instead, the codersavesthe restoration identifier of the object and adds it to the list of preservable objects, which results in that object’s encodeRestorableStateWithCoder: method being called. State Preservation and Restoration Preserving the State of Your View Controllers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 85The encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: methods of your view controllers should always call super at some point in their implementation. Calling super gives the parent class a chance to save and restore any additional information. Listing 4-2 shows a sample implementation of these methods that save a numerical value used to identify the specified view controller. Listing 4-2 Encoding and decoding a view controller’s state. - (void)encodeRestorableStateWithCoder:(NSCoder *)coder { [super encodeRestorableStateWithCoder:coder]; [coder encodeInt:self.number forKey:MyViewControllerNumber]; } - (void)decodeRestorableStateWithCoder:(NSCoder *)coder { [super decodeRestorableStateWithCoder:coder]; self.number = [coder decodeIntForKey:MyViewControllerNumber]; } Coder objects are notshared during the encode and decode process. Each object with preservable state receives its own coder that it can use to read or write data. The use of unique coders means that you do not have to worry about key namespace collisions among your own objects. However, you must still avoid using some special key names that UIKit provides. Specifically, each coder contains the UIApplicationStateRestorationBundleVersionKey and UIApplicationStateRestorationUserInterfaceIdiomKey keys, which provide information about the bundle version and current user interface idiom. Coders associated with view controllers may also contain the UIStateRestorationViewControllerStoryboardKey key, which identifies the storyboard from which that view controller originated. For more information about implementing your encode and decode methods for your view controllers, see UIViewController Class Reference . Preserving the State of Your Views If a view has state information worth preserving, you can save that state with the rest of your app’s view controllers. Because they are usually configured by their owning view controller, most views do not need to save state information. The only time you need to save a view’s state is when the view itself can be altered by State Preservation and Restoration Preserving the State of Your Views 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 86the user in a way that is independent of its data or the owning view controller. For example, scroll views save the current scroll position, which is information that is not interesting to the view controller but which does affect how the view presents itself. To designate that a view’s state should be saved, you do the following: ● Assign a valid string to the view’s restorationIdentifier property. ● Use the view from a view controller that also has a valid restoration identifier. ● For table views and collection views, assign a data source that adopts the UIDataSourceModelAssociation protocol. As with view controllers, assigning a restoration identifier to a view tells the system that the view object has state that your app wants to save. The restoration identifier can also be used to locate the view later. Like view controllers, views define methods for encoding and decoding their custom state. If you create a view with state worth saving, you can use these methods to read and write any relevant data. UIKit VIews with Preservable State In order to save the state of any view, including both custom and standard system views, you must assign a restoration identifier to the view. Views without a restoration identifier are not added to the list of preservable objects by UIKit. The following UIKit views have state information that can be preserved: ● UICollectionView ● UIImageView ● UIScrollView ● UITableView ● UITextField ● UITextView ● UIWebView Other frameworks may also have views with preservable state. For information about whether a view saves state information and what state it saves, see the reference for the corresponding class. State Preservation and Restoration Preserving the State of Your Views 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 87Preserving the State of a Custom View If you are implementing a custom view that has restorable state, implement the encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder:methods and use them to encode and decode that state. Use those methods to save only the data that cannot be easily reconfigured by other means. For example, use these methods to save data that is modified by user interactions with the view. Do not use these methods to save the data being presented by the view or any data that the owning view controller can configure easily. Listing 4-3 shows an example of how to preserve and restore the selection for a custom view that contains editable text. In the example, the range is accessible using the selectionRange and setSelectionRange: methods, which are custom methods the view uses to manage the selection. Encoding the data only requires writing it to the provided coder object. Restoring the data requires reading it and applying it to the view. Listing 4-3 Preserving the selection of a custom text view // Preserve the text selection - (void) encodeRestorableStateWithCoder:(NSCoder *)coder { [super encodeRestorableStateWithCoder:coder]; NSRange range = [self selectionRange]; [coder encodeInt:range.length forKey:kMyTextViewSelectionRangeLength]; [coder encodeInt:range.location forKey:kMyTextViewSelectionRangeLocation]; } // Restore the text selection. - (void) decodeRestorableStateWithCoder:(NSCoder *)coder { [super decodeRestorableStateWithCoder:coder]; if ([coder containsValueForKey:kMyTextViewSelectionRangeLength] && [coder containsValueForKey:kMyTextViewSelectionRangeLocation]) { NSRange range; range.length = [coder decodeIntForKey:kMyTextViewSelectionRangeLength]; range.location = [coder decodeIntForKey:kMyTextViewSelectionRangeLocation]; if (range.length > 0) [self setSelectionRange:range]; } } State Preservation and Restoration Preserving the State of Your Views 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 88Implementing Preservation-Friendly Data Sources Because the data displayed by a table or collection view can change, both classes save information about the currentselection and visible cells only if their data source implementsthe UIDataSourceModelAssociation protocol. This protocol provides a way for a table or collection view to identify the content it contains without relying on the index path of that content. Thus, regardless of where the data source places an item during the next launch cycle, the view still has all the information it needs to locate that item. In order to implement the UIDataSourceModelAssociation protocol successfully, your data source object must be able to identify items between subsequent launches of the app. This means that any identification scheme you devise must be invariant for a given piece of data. This is essential because the data source must be able to retrieve the same piece of data for the same identifier each time it is requested. Implementing the protocol itself is a matter of mapping from a data item to its unique ID and back again. Apps that use Core Data can implement the protocol by taking advantage of object identifiers. Each object in a Core Data store has a unique object identifier that can be converted into a URI and used to locate the object later. If your app does not use Core Data, you need to devise your own form of unique identifiers if you want to support state preservation for your views. Note: Remember that implementing the UIDataSourceModelAssociation protocol is only necessary to preserve attributes such as the current selection in a table or collection view. This protocol is not used to preserve the actual data managed by your data source. It is your app’s responsibility to ensure that its data is saved at appropriate times. Preserving Your App’s High-Level State In addition to the data preserved by your app’s view controllers and views, UIKit provides hooks for you to save any miscellaneous data needed by your app. Specifically, the UIApplicationDelegate protocol includes the following methods for you to override: ● application:willEncodeRestorableStateWithCoder: ● application:didDecodeRestorableStateWithCoder: If your app contains state that does not live in a view controller, but that needs to be preserved, you can use the precedingmethodsto save and restore it. The application:willEncodeRestorableStateWithCoder: method is called at the very beginning of the preservation process so that you can write out any high-level app state, such as the current version of your user interface. The application:didDecodeRestorableStateWithCoder: method is called at the end of the restoration state so that you can decode any data and perform any final cleanup that your app requires. State Preservation and Restoration Preserving Your App’s High-Level State 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 89Mixing UIKit’s State Preservation with YourOwn Custom Mechanisms If your app already implementsits own custom state preservation and restoration mechanism, you can continue to use that mechanism and migrate your code to use UIKit’ssupport over time. The design of UIKit’s preservation mechanism allows you to pick and choose which view controllers you want to preserve. Thus, you can designate that only portions of your interface should be restored by UIKit, leaving the rest to be handled by your app’s current process. Figure 4-7 shows a sample view hierarchy containing a tab bar controller and the view controllersin its assorted tabs. In this sample, because the tab bar controller has a restoration identifier associated with it, UIKit saves the state of the tab bar controller and all other child view controllers that also have a restoration identifier. Your app’s custom code would then need to preserve the state of the remaining view controllers. During restoration, a similar process occurs. UIKit restores all of the view controllersthat it preserved while your custom code restores the rest. Figure 4-7 UIKit handles the root view controller Tab Bar Controller Navigation Controller View Controller View Controller Presented View Controller View Controller Presented View Controller View Controller Presented View Controller View Controller Presented View Controller UIKit restoration Custom restoration If you prefer to have your own code manage the root view controller of your app, the save and restore process differs slightly. Because UIKit would not automatically save any view controllers, you need to encode them manually in the application:willEncodeRestorableStateWithCoder: method of your app delegate. State Preservation and Restoration Mixing UIKit’s State Preservation with Your Own Custom Mechanisms 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 90When you use the encodeObject:forKey: method of the coder to encode a view controller object, the coder uses the view controller’s encodeRestorableStateWithCoder: method to do the encoding. This process allows you to write arbitrary view controllers to the state preservation archive managed by UIKit. When you decode archived view controllers during the next launch cycle, you muststill be prepared to provide an instance of each view controller to UIKit. When you call the decodeObjectForKey: method to decode your view controller, UIKit calls the application:viewControllerWithRestorationIdentifierPath:coder:method of your app delegate to retrieve the view controller object first. Only after UIKit has the view controller object does it call the decodeRestorableStateWithCoder: method to return the view controller to its previous state. Your code can use the application:viewControllerWithRestorationIdentifierPath:coder: method to create the view controller and install it in your app’s view controller hierarchy. Tips for Saving and Restoring State Information As you add support for state preservation and restoration to your app, consider the following guidelines: ● Encode version information along with the rest of your app’s state. During the preservation process, it is recommended that you encode a version string or number that identifies the current revision of your app’s user interface. You can encode this state in the application:willEncodeRestorableStateWithCoder: method of your app delegate. When your app delegate’s application:shouldRestoreApplicationState: method is called, you can retrieve this information from the provided coder and use it to determine if state preservation is possible. ● Do not include objects from your data model in your app’s state. Apps should continue to save their data separately in iCloud or to local files on disk. Never use the state restoration mechanism to save that data. Preserved interface data may be deleted if problems occur during a restore operation. Therefore, any preservation-related data you write to disk should be considered purgeable. ● The state preservation system expects you to use view controllers in the ways they were designed to be used. The view controller hierarchy is created through a combination of view controller containment and by presenting one view controller from another. If your app displays the view of a view controller by another means—for example, by adding it to another view without creating a containment relationship between the corresponding view controllers—the preservation system will not be able to find your view controller to preserve it. ● Remember that you might not want to preserve all view controllers. In some cases, it might not make sense to preserve a view controller. For example, if the user left your app while it was displaying a view controller to change the user’s password, you might want to cancel the operation and restore the app to the previous screen. In such a case, you would not preserve the view controller that asks for the new password information. State Preservation and Restoration Tips for Saving and Restoring State Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 91● Avoid swapping view controller classes during the restoration process. The state preservation system encodes the class of the view controllers it preserves. During restoration, if your app returns an object whose class does not match (or is not a subclass of) the original object, the system does not ask the view controller to decode any state information. Thus, swapping out the old view controller for a completely different one does not restore the full state of the object. ● Be aware that the system automatically deletes an app’s preserved state when the user force quits the app. Deleting the preserved state information when the app is killed is a safety precaution. (The system also deletes preserved state if the app crashes at launch time as a similar safety precaution.) If you want to test your app’s ability to restore its state, you should not use the multitasking bar to kill the app during debugging. Instead, use Xcode to kill the app or kill the app programmatically by installing a temporary command or gesture to call exit on demand. State Preservation and Restoration Tips for Saving and Restoring State Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 92Aside from the images and media files your app presents on screen, there are some specific resources that iOS itself requires your app to provide. The system uses these resources to determine how to present your app on the user’s home screen and, in some cases, how to facilitate interactions with other parts of the system. App Store Required Resources There are several things that you are required to provide in your app bundle before submitting it to the App Store: ● Your app must have an Info.plist file. This file contains information that the system needs to interact with your app. Xcode creates a version of this file automatically but most apps need to modify this file in some way. For information on how to configure this file, see “The Information Property List File” (page 93). ● Your app’s Info.plist file must include the UIRequiredDeviceCapabilities key. The App Store uses this key to determine whether or not a user can run your app on a specific device. For information on how to configure this key, see “Declaring the Required Device Capabilities” (page 94). ● You must include one or more icons in your app bundle. The system uses these icons when presenting your app on the device’s home screen. For information about how to specify app icons, see “App Icons” (page 98). ● Your app must include at least one image to be displayed while your app islaunching. The system displays this image to provide the user with immediate feedback that your app is launching. For information about launch images, see “App Launch (Default) Images” (page 100). The Information Property List File The information property list (Info.plist) file contains critical information about your app’s configuration and must be included in your app bundle. Every new project you create in Xcode has a default Info.plist file configured with some basic information about your project. You can modify this file to specify additional configuration details for your app. Your app’s Info.plist file must include the following keys: 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 93 App-Related Resources● UIRequiredDeviceCapabilities—The App Store uses this key to determine the capabilities of your app and to prevent it from being installed on devices that do not support features your app requires. For more information about this key, see “Declaring the Required Device Capabilities” (page 94). ● CFBundleIcons—Thisisthe preferred key forspecifying your app’sicon files. Older projects might include the CFBundleIconFiles key instead. Both keys have essentially the same purpose but the CFBundleIcons key is preferred because it allows you to organize your icons more efficiently. (The CFBundleIcons key is also required for Newsstand apps.) ● UISupportedInterfaceOrientations—This key is included by Xcode automatically and is set to an appropriate set of default values. However, you should add or remove values based on the orientations that your app actually supports. You might also want to include the following keys in your app’s Info.plist file, depending on the behavior of your app: ● UIBackgroundModes—Include this key if your app supports executing in the background using one of the defined modes; see “Implementing Long-Running Background Tasks” (page 58). ● UIFileSharingEnabled—Include this key if you want to expose the contents of your sandbox’s Documents directory in iTunes. ● UIRequiresPersistentWiFi—Include this key if your app requires a Wi-Fi connection. ● UINewsstandApp—Include this key if your app presents content from the Newsstand app. The Info.plist file itself is a property list file that you can edit manually or using Xcode. Each new Xcode project contains a file called-Info.plist, where isthe name of your Xcode project. This file is the template that Xcode uses to generate the actual Info.plist file at build time. When you select this file, Xcode displays the property list editor that you can use to add or remove keys or change the value of a key. For information about how to configure the contents of this file, see Property List Editor Help . For details about the keys you can include in the Info.plist file, see Information Property List Key Reference . Declaring the Required Device Capabilities The UIRequiredDeviceCapabilities key lets you declare the hardware or specific capabilities that your app needs in order to run. All apps are required to have this key in their Info.plist file. The App Store uses the contents of this key to prevent users from downloading your app onto a device that cannot possibly run it. App-Related Resources The Information Property List File 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 94The value of the UIRequiredDeviceCapabilities key is either an array or a dictionary that contains additional keys identifying features your app requires (or specifically prohibits). If you specify the value of the key using an array, the presence of a key indicates that the feature is required; the absence of a key indicates that the feature is not required and that the app can run without it. If you specify a dictionary instead, each key in the dictionary must have a Boolean value that indicates whether the feature is required or prohibited. A value of true indicates the feature is required and a value of false indicates that the feature must not be present on the device. If a given capability is optional for your app, do not include the corresponding key in the dictionary. Table 5-1 liststhe keysthat you can include in the array or dictionary for the UIRequiredDeviceCapabilities key. You should include keys only for the featuresthat your app absolutely requires. If your app can run without a specific feature, do not include the corresponding key. Table 5-1 Dictionary keys for the UIRequiredDeviceCapabilities key Key Description Include this key if your app requires(orspecifically prohibits) the presence of accelerometers on the device. Apps use the Core Motion framework to receive accelerometer events. You do not need to include this key if your app detects only device orientation changes. accelerometer Include this key if your app is compiled only for the armv6 instruction set. (iOS 3.1 and later) armv6 Include this key if your app is compiled only for the armv7 instruction set. (iOS 3.1 and later) armv7 Include this key if your app requires (or specifically prohibits) autofocus capabilities in the device’s still camera. Although most developers should not need to include this key, you might include it if your app supports macro photography or requires sharper images in order to perform some sort of image processing. auto-focus-camera Include this key if your app requires(orspecifically prohibits) the presence of Bluetooth low-energy hardware on the device. (iOS 5 and later.) bluetooth-le Include this key if your app requires(orspecifically prohibits) the presence of a camera flash for taking pictures or shooting video. Apps use the UIImagePickerController interface to control the enabling of this feature. camera-flash Include this key if your app requires(orspecifically prohibits) the presence of a forward-facing camera. Apps use the UIImagePickerController interface to capture video from the device’s camera. front-facing-camera App-Related Resources The Information Property List File 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 95Key Description Include this key if your app requires(orspecifically prohibits) Game Center. (iOS 4.1 and later) gamekit Include this key if your app requires(orspecifically prohibits) the presence of GPS (or AGPS) hardware when tracking locations. (You should include this key only if you need the higher accuracy offered by GPS hardware.) If you include this key, you should also include the location-services key. You should require GPS only if your app needs location data more accurate than the cellular or Wi-fi radios might otherwise provide. gps Include this key if your app requires(orspecifically prohibits) the presence of a gyroscope on the device. Apps use the Core Motion framework to retrieve information from gyroscope hardware. gyroscope Include this key if your app requires (or specifically prohibits) the ability to retrieve the device’s current location using the Core Location framework. (This key refers to the general location services feature. If you specifically need GPS-level accuracy, you should also include the gps key.) location-services Include this key if your app requires(orspecifically prohibits) the presence of magnetometer hardware. Apps use this hardware to receive heading-related events through the Core Location framework. magnetometer Include this key if your app uses the built-in microphone or supports accessories that provide a microphone. microphone Include this key if your app requires(orspecifically prohibits) the presence of the OpenGL ES 1.1 interfaces. opengles-1 Include this key if your app requires(orspecifically prohibits) the presence of the OpenGL ES 2.0 interfaces. opengles-2 Include this key if your app requires(orspecifically prohibits) peer-to-peer connectivity over a Bluetooth network. (iOS 3.1 and later) peer-peer Include this key if your app requires(orspecifically prohibits) the presence of the Messages app. You might require this feature if your app opens URLs with the sms scheme. sms Include this key if your app requires(orspecifically prohibits) the presence of a camera on the device. Apps use the UIImagePickerController interface to capture images from the device’s still camera. still-camera App-Related Resources The Information Property List File 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 96Key Description Include this key if your app requires(orspecifically prohibits) the presence of the Phone app. You might require this feature if your app opens URLs with the tel scheme. telephony Include this key if your app requires(orspecifically prohibits) the presence of a camera with video capabilities on the device. Apps use the UIImagePickerController interface to capture video from the device’s camera. video-camera Include this key if your app requires (or specifically prohibits) access to the networking features of the device. wifi For detailed information on how to create and edit property lists, see Information Property List Key Reference . Declaring Your App’s Supported Document Types If your app is able to open existing or custom file types, your Info.plist file should include information about those types. Declaring file types is how you let the system know that your app is able to open files of the corresponding type. The system uses this information to direct file requests to your app at appropriate times. For example, if the Mail app receives an attachment, the system can direct that attachment to your app to open. When declaring your app’s supported file types, you typically do not configure keys in your Info.plist file directly. In the Info tab of your target settings, there is a Document Settings section that you can use to specify your app’s supported types. Each document type that you add to this section can represent one file type or several file types. For example, you can define a single document type that represents only PNG images or one that represents PNG,JPG, and GIF images. The decision to represent one file type or multiple file types depends on how your app presents the files. If it presents all of the files in the same way—that is, with the same icon and with the same basic code path—then you can use one document type for multiple file types. If the code paths or icons are different for each file type, you should declare different document types for each. For each document type, you must provide the following information at a minimum: ● A name. This is a localizable string that can be displayed to the user if needed. ● An icon. All files associated with a document type share the same icon. ● The file types. These are uniform type identifier (UTI) strings that identify the supported file types. For example, to specify the PNG file type, you would specify the public.png UTI. UTIs are the preferred way to specify file types because they are less fragile than filename extensions and other techniques used to identify files. App-Related Resources The Information Property List File 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 97Ultimately, Xcode converts your document type information into a set of keys and adds them to the CFBundleDocumentTypes key in your app’s Info.plist file. The CFBundleDocumentTypes key contains an array of dictionaries, where each dictionary represents one of your declared document types and includes the name, icon, file type, and other information you specified. For more information on the keys you use to declare your app’s document types, see Information Property List Key Reference . For information about how to open files passed to your app by the system, see “Handling URL Requests” (page 120). App Icons Every app must provide an icon to be displayed on a device’s Home screen and in the App Store. An app may actually specify several different icons for use in different situations. For example, an app can provide a small icon to use when displaying search results and can provide a high-resolution icon for devices with Retina displays. Regardless of how many different icons your app has, you specify them using the CFBundleIcons key in the Info.plist file. The value of that key is an array of strings, each of which contains the filename of one of your icons. The filenames can be anything you want, but all image files must be in the PNG format and must reside in the top level of your app bundle. (Avoid using interlaced PNGs.) When the system needs an icon, it choose the image file whose size most closely matches the intended usage. Table 5-2 lists the dimensions of the icons you can include with your app. For apps that run on devices with Retina displays, two versions of each icon should be provided, with the second one being a high-resolution version of the original. The names of the two icons should be the same except for the inclusion of the string @2x in the filename of the high-resolution image. You can find out more about specifying and loading high-resolution image resources in Drawing and Printing Guide for iOS . For a complete list of app-related icons and detailed information about the usage and preparation of your icons, see iOS Human Interface Guidelines. Table 5-2 Sizes for images in the CFBundleIcons key Icon Idiom Size Usage Thisisthe main icon for appsrunning on iPhone and iPod touch. 57 x 57 pixels 114 x 114 pixels (@2x) App icon (required) iPhone Thisisthe main icon for appsrunning on iPad. 72 x 72 pixels 144 x 144 pixels (@2x) App icon (required) iPad App-Related Resources App Icons 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 98Icon Idiom Size Usage iTunes uses this icon when presenting your app for distribution. These files must be included at the top level of your app bundle and the names of the files must be iTunesArtwork and iTunesArtwork@2x (no filename extension). 512 x 512 1024 x 1024 (@2x) App icon for the App iPhone/iPad Store (required) This is the icon displayed in conjunction with search results on iPhone and iPod touch. This icon is also used by the Settings app on all devices. 29 x 29 pixels 58 x 58 pixels (@2x) Small icon for iPhone Spotlight search results and Settings (recommended) This is the icon displayed in conjunction with search results on iPad. 50 x 50 pixels 100 x 100 pixels (@2x) Small icon for iPad Spotlight search results and Settings (recommended) When specifying icon files using the CFBundleIcons key, it is best to omit the filename extensions of your image files. If you include a filename extension, you must explicitly add the names of all image files (including any high-resolution variants). When you omit the filename extension, the system automatically detects high-resolution variants of your file, even if they are not included in the array. If your iPhone app is running in iOS 3.1.3 or earlier, the system does not look for icons using your Info.plist file. The CFBundleIcons key was introduced in iOS 5.0 and the CFBundleIconFiles key was introduced in iOS 3.2. Instead of using these keys, the system looks for icon files with specific filenames. Although the sizes of the icons are the same as those in Table 5-2 (page 98), if your app supports deployment on iOS 3.1.3 and earlier, you must use the following filenames when naming your icons: ● Icon.png. The name for the app icon on iPhone or iPod touch. ● Icon-72.png. The name for the app icon on iPad. ● Icon-Small.png. The name for the search results icon on iPhone and iPod touch. This file is also used for the Settings icon on all devices. ● Icon-Small-50.png. The name of the search results icon on iPad. App-Related Resources App Icons 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 99Important: The use of fixed filenames for your app icons is for compatibility with earlier versions of iOS only. Even if you use these fixed icon filenames, your app should continue to include the CFBundleIcons or CFBundleIconFiles key in your app’s Info.plist file. For more information about the CFBundleIcons key, see Information Property List Key Reference . For information about creating your app icons, see iOS Human Interface Guidelines. App Launch (Default) Images When the system launches an app, it temporarily displays a static launch image on the screen. Your app provides this image, with the image contents usually containing a prerendered version of your app’s default user interface. The purpose of thisimage isto give the user immediate feedback that the app launched. It also gives your app time to initialize itself and prepare its initial set of views for display. When your app is ready to run, the system removes the image and displays your app’s windows and views. Every app must provide at least one launch image. This image is typically in a file named Default.png that displays your app’s initial screen in a portrait orientation. However, you can also provide other launch images to be used under different launch conditions. All launch images must be PNG files and must reside in the top level of your app’s bundle directory. (Avoid using interlaced PNGs.) The name of each launch image indicates its purpose and how it is used. The format for launch image filenames is as follows: .png The portion of the filename is either the string Default or a custom string that you specify using the UILaunchImageFile key in your app’s Info.plist file. The portion is the optional string @2x and should be included only for imagesintended for use on Retina displays. Other optional modifiers may also be included in the name, and several standard modifiers are discussed in the sections that follow. Table 5-3 lists the dimensions for launch images in iOS apps. For all dimensions, the image width is listed first, followed by the image height. For precise information about which size launch image to use and how to prepare your launch images, see iOS Human Interface Guidelines. Table 5-3 Typical launch image dimensions Device Portrait Landscape 320 x 480 pixels Not supported 640 x 960 pixels (@2x) iPhone and iPod touch iPhone 5 and iPod touch (5th generation) 640 x 1136 pixels (@2x) Not supported App-Related Resources App Launch (Default) Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 100Device Portrait Landscape 1024 x 748 pixels 2048 x 1496 pixels (@2x) 768 x 1004 pixels 1536 x 2008 pixels (@2x) iPad To demonstrate the naming conventions, suppose your iOS app’s Info.plist file included the UILaunchImageFile key with the value MyLaunchImage. The standard resolution version of the launch image would be named MyLaunchImage.png and would be in a portrait orientation (320 x 480). The high-resolution version of the same launch image would be named MyLaunchImage@2x.png. If you did not specify a customlaunch image name, these files would need to be named Default.png and Default@2x.png, respectively. To specify default launch images for iPhone 5 and iPod touch (5th generation) devices, include the modifier string -568h immediately after the portion of the filename. Because these devices have Retina displays, the @2x modifier must always be included with launch imagesfor the devices. For example, the default launch image name for a device is Default-568h@2x.png. (If your app has the UILaunchImageFile key in its Info.plist file, replace the Default portion of the string with your custom string.) The -568h modifier should always be the first one in the list. You can also insert other modifiers after the -568h string as described below. For more information about the UILaunchImageFile key, see Information Property List Key Reference . Providing Launch Images for Different Orientations In iOS 3.2 and later, an iPad app can provide both landscape and portrait versions of its launch images. Each orientation-specific launch image must include a special modifier string in its filename. The format for orientation-specific launch image filenames is as follows: .png Table 5-4 lists the possible modifiers you can specify for the value in your image filenames. As with all launch images, each file must be in the PNG format. These modifiers are supported for launch images used in iPad apps only; they are notsupported for appsrunning on iPhone or iPod touch devices. Table 5-4 Launch image orientation modifiers Modifier Description Specifies an upside-down portrait version of the launch image. A file with this modifier takes precedence over a file with the -Portrait modifier for this specific orientation. -PortraitUpsideDown App-Related Resources App Launch (Default) Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 101Modifier Description Specifies a left-oriented landscape version of the launch image. A file with this modifier takes precedence over a file with the -Landscape modifier for this specific orientation. -LandscapeLeft Specifies a right-oriented landscape version of the launch image. A file with this modifier takes precedence over a file with the -Landscape modifier for this specific orientation. -LandscapeRight Specifies the generic portrait version of the launch image. This image is used for right-side up portrait orientations and takes precedence over the Default.png image file (or your custom-named replacement for that file). If a file with the -PortraitUpsideDown modifier is not specified, this file is also used for upside-down portrait orientations as well. -Portrait Specifies the generic landscape version of the launch image. If a file with the -LandscapeLeft or -LandscapeRight modifier is not specified, this image is used instead. This image takes precedence over the Default.png image file (or your custom-named replacement for that file). -Landscape If you provide a launch image file with no orientation modifier, that file is used when no other orientation-specific launch image is available. For apps running on systems earlier than iOS 3.2, you must name this file Default.png. (none) For example, if you specify the value MyLaunchImage in the UILaunchImageFile key, the custom landscape and portrait launch images for your iPad app would be named MyLaunchImage-Landscape.png and MyLaunchImage-Portrait.png. If you do not specify a custom launch image filename, you would use the names Default-Landscape.png and Default-Portrait.png. No matter which launch image is displayed by the system, your app always launches in a portrait orientation initially and then rotates as needed to the correct orientation. Therefore, your application:didFinishLaunchingWithOptions: method should always assume a portrait orientation when setting up your window and views. Shortly after the application:didFinishLaunchingWithOptions: method returns, the system sends any necessary orientation-change notifications to your app’s window, giving it and your app’s view controllers a chance to reorient views using the standard process. For more information about how your view controllers manage the rotation process, see “Creating Custom Content View Controllers” in View Controller Programming Guide for iOS . App-Related Resources App Launch (Default) Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 102Providing Device-Specific Launch Images Universal apps must provide launch images for both the iPhone and iPad idioms. Because iPhone apps require only one launch image (Default.png), whereas iPad apps typically require different images for portrait and landscape orientations, you can usually do without device-specific modifiers. However, if you create multiple launch images for each idiom, the names of device-specific image files are likely to collide. In that situation, you can append a device modifier to filenames to indicate that they are for a specific platform only. The following device modifiers are recognized for launch images in iOS 4.0 and later: ● ~ipad. The launch image should be loaded on iPad devices only. ● ~iphone. The launch image should be loaded on iPhone or iPod touch devices only. Because device modifiers are notsupported in iOS 3.2, the minimalset of launch images needed for a universal app (running in iOS 3.2 and later) would need to be named Default.png and Default~iphone.png. In that case, the Default.png file would contain the iPad launch image (for all orientations) and the Default~iphone.png file would contain the iPhone version of the image. (To support high-resolution displays, you would also need to include a Default@2x~iphone.png launch image.) Note: If you are using the UILaunchImageFile key in your Info.plist file to specify a custom base name for your launch image files, add device-specific versions as needed to differentiate the launch images on different devices. For example, specify a UILaunchImageFile~ipad key to specify a different base name for iPad launch images. Specifying different base nameslets a universal app avoid naming conflicts among its launch images. For more information on how to apply device modifiers to keys in the Info.plist file, see Information Property List Key Reference . Providing Launch Images for Custom URL Schemes If your app supports one or more custom URL schemes, it can also provide a custom launch image for each URL scheme. When the system launches your app to handle a URL, it displays the launch image associated with the scheme of the given URL. In this case, the format for your launch image filenames are as follows: -.png The modifier is a string representing the name of your URL scheme name. For example, if your app supports a URL scheme with the name myscheme, the system looks for an image with the name Default-myscheme.png (or Default-myscheme@2x.png for Retina displays) in the app’s bundle. If the app’s Info.plist file includesthe UILaunchImageFile key, the base name portion changesfrom Default to the custom string you provide in that key. App-Related Resources App Launch (Default) Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 103Note: You can combine a URL scheme modifier with orientation modifiers. If you do this, the format for the filename is -.png.For more information about the launch orientation modifiers,see “Providing Launch Imagesfor Different Orientations” (page 101). In addition to including the launch images at the top level of your bundle, you can also include localized versions of your launch images in your app’s language-specific project subdirectories. For more information on localizing resources in your app, see “Localized Resource Files” (page 105). The Settings Bundle Apps that want to display preferences in the Settings app must include a Settings bundle resource. A Settings bundle is a specially formatted bundle that sits at the top of your app’s bundle directory and contains the data needed to display your app’s preferences. Figure 5-1 shows an example of custom preferences displayed for an app. Figure 5-1 Custom preferences displayed by the Settings app App-Related Resources The Settings Bundle 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 104Note: Because changing preferences in the Settings app requires leaving your app, you should use a Settings bundle only for preferences that the user changes infrequently. Frequently changed settings should be included directly inside your app. Xcode provides support for creating a Settings bundle resource and adding it to your app. Inside the Settings bundle, you place one or more property list files and any images associated with your preferences. Each property-list file contains special keys and values that tell the Settings app how to display different pages of your preferences. Changesto your app’s preferences are stored in the user defaults database and are accessible to your app using an NSUserDefaults object. For detailed information about how to create a Settings bundle, see Preferences and Settings Programming Guide . Localized Resource Files Because iOS apps are distributed in many countries, localizing your app’s content can help you reach many more customers. Users are much more likely to use an app when it is localized for their native language. When you factor your user-facing content into resource files, localizing that content is a relatively simple process. Before you can localize your content, you must internationalize your app in order to facilitate the localization process. Internationalizing your app involves factoring out any user-facing content into localizable resource files and providing language-specific project (.lproj) directories for storing that content. It also means using appropriate technologies (such as date and number formatters) when working with language-specific and locale-specific content. For a fully internationalized app, the localization process creates new sets of language-specific resource files for you to add to your project. A typical iOS app requires localized versions of the following types of resource files: ● Storyboard files (or nib files)—Storyboards can contain text labels and other content that need to be localized. You might also want to adjust the position of interface items to accommodate changes in text length. (Similarly, nib files can contain text that needs to be localized or layout that needs to be updated.) ● Strings files—Strings files (so named because of their .strings filename extension) contain localized text that you plan to display in your app. ● Image files—You should avoid localizing images unless the images contain culture-specific content. And you should never store text directly in your image files. Instead, store text in a strings file and composite that text with your image-based content at runtime.. App-Related Resources Localized Resource Files 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 105● Video and audio files—You should avoid localizing multimedia files unless they contain language-specific or culture-specific content. For example, you would want to localize a video file that contained a voice-over track. For information about the internationalization and localization process, see Internationalization Programming Topics. For information about the proper way to use resource files in your app, see Resource Programming Guide . Loading Resources Into Your App Putting resources into your bundle is the first step but at runtime, you need to be able to load those resources into memory and use them. Resource management is broken down basically into two steps: 1. Locate the resource. 2. Load the resource. 3. Use the resource. To locate resources, you use an NSBundle object. A bundle object understands the structure of your app’s bundle and knows how to locate resources inside it. Bundle objects even use the current language settings to choose an appropriately localized version of the resource. The pathForResource:ofType: method is one of several NSBundle methods that you can use to retrieve the location of resource files. Once you have the location of a resource file, you have to decide the most appropriate way to load it into memory. Common resource types usually have a corresponding class that you use to load the resource: ● To load view controllers (and their corresponding views) from a storyboard, use the UIStoryboard class. ● To load an image, use the methods of the UIImage class. ● To load string resources, use the NSLocalizedString and related macros defined in Foundation framework. ● To load the contents of a property list, use the dictionaryWithContentsOfURL: method of NSDictionary, or use the NSPropertyListSerialization class. ● To load binary data files, use the methods of the NSData class. ● To load audio and video resources, use the classes of the Assets Library, Media Player, or AV Foundation frameworks. App-Related Resources Loading Resources Into Your App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 106The following example shows how to load an image stored in a resource file in the app’s bundle. The first line gets the location of the file in the app’s bundle (also known as the main bundle here). The second line creates a UIImage object using the data in the file at that location. NSString* imagePath = [[NSBundle mainBundle] pathForResource:@"sun" ofType:@"png"]; UIImage* sunImage = [[UIImage alloc] initWithContentsOfFile:imagePath]; For more information about resources and how to access them from your app, see Resource Programming Guide . App-Related Resources Loading Resources Into Your App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 107Many app-related tasks depend on the type of app you are trying to create. This chapter shows you how to implement some of the common behaviors found in iOS apps. Creating a Universal App A universal app is a single app that is optimized for iPhone, iPod touch, and iPad devices. Providing a single binary that adapts to the current device offers the best user experience but, of course, involves extra work on your part. Because of the differences in device screen sizes, most of your window, view, and view controller code for iPad is likely to be very different from the code for iPhone and iPod touch. In addition, there are things you must do to ensure your app runs correctly on each device type. Xcode provides built-in support for configuring universal apps. When you create a new project, you can select whether you want to create a device-specific project or a universal project. After you create your project, you can change the supported set of devices for your app target using the Summary pane. When changing from a single-device project to a universal project, you must fill in the information for the device type for which you are adding support. The following sections highlight the changes you must make to an existing app to ensure that it runssmoothly on any type of device. Updating Your Info.plist Settings Most of the existing keys in a universal app’s Info.plist file should remain the same. However, for any keys that require different values on iPhone versus iPad devices, you can add device modifiers to the key name. When reading the keys of your Info.plist file, the system interprets each key using the following format: key_root-~ In this format, the key_root portion represents the original name of the key. The and portions are both optional endings that you can use for keys that are specific to a platform or device. For apps that run only on iOS, you can omit the platform string. (The iphoneos platform string is used to distinguish apps written for iOS from those written for Mac OS X.) To apply a key to a specific device, use one of the following values: ● iphone—The key applies to iPhone devices. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 108 Advanced App Tricks● ipod—The key applies to iPod touch devices. ● ipad—The key applies to iPad devices. For example, to indicate that you want your app to launch in a portrait orientation on iPhone and iPod touch devices but in landscape-right on iPad, you would configure your Info.plist with the following keys: UIInterfaceOrientation UIInterfaceOrientationPortrait UIInterfaceOrientation~ipad UIInterfaceOrientationLandscapeRight Notice that in the preceding example, there is an iPad-specific key and a default key without any device modifiers. Continue to use the default key to specify the most common (or default) value and add a specific version with a device-specific modifier when you need to change that value. This guarantees that there is always a value available for the system to examine. For example, if you were to replace the default key with an iPhone-specific and iPad-specific version of the UIInterfaceOrientation key, the system would not know the preferred starting orientation for iPod devices. For more information about the keys you can include in your Info.plist file, see Information Property List Key Reference Implementing Your View Controllers and Views The largest amount of effort that goes into creating universal apps is designing your user interface. Because of the different screen sizes, apps often need completely separate versions of their interface for each device idiom. This means creating new view hierarchies but might also mean creating completely different view controller objects to manage those views. For views, the main modification is to redesign your view hierarchies to support the larger screen. Simply scaling existing views may work but often yields poor results. Your new interface should make use of the available space and take advantage of new interface elements where appropriate. Doing so is better because it results in an interface that feels more natural to the user, and does not just feel like an iPhone app on a larger screen. For view controllers, follow these guidelines: ● Consider defining separate view controller classes for iPhone and iPad devices. Using separate view controllers is often easier than trying to create one view controller that supports both platforms. If there is a significant amount of shared code, you could always put the shared code in a base class and then implement custom subclasses to address device-specific issues. Advanced App Tricks Creating a Universal App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 109● If you use a single view controller class for both platforms, your code must support both iPhone and iPad screen sizes. (For an app that uses nib files, this might mean choosing which nib file to load based on the current device idiom.) Similarly, your view controller code must be able to handle differences between the two platforms. For views, follow these guidelines: ● Consider using separate sets of views for iPhone and iPad devices. For custom views, this means defining different versions of your class for each device. ● If you choose to use the same custom view for both devices, make sure your drawRect: and layoutSubviews methods especially work properly on both devices. For information about the view controllers you can use in your apps, see View Controller Programming Guide for iOS . Updating Your Resource Files Because resource files are often used to implement portions of your app’s user interface, you need to make the following changes: ● In addition to the Default.png file displayed when your app launches on iPhone devices, you must add new launch images for iPad devices as described in “Providing Launch Images for Different Orientations” (page 101). ● If you use images, you may need to add larger (or higher-resolution) versions to support iPad devices. ● If you use storyboard or nib files, you need to provide a new set of files for iPad devices. ● You must size your app icons appropriately for iPad, as described in “App Icons” (page 98). When using different resource files for each platform, you can conditionally load those resources just as you would conditionally execute code. For more information about how to use runtime checks,see “Using Runtime Checks to Create Conditional Code Paths” (page 110). Using Runtime Checks to Create Conditional Code Paths If your code needs to follow a different path depending on the underlying device type, use the userInterfaceIdiom property of UIDevice to determine which path to take. This property provides an indication of the style of interface to create: iPad or iPhone. Because this property is available only in iOS 3.2 and later, apps that support earlier versions of iOS need to check for the availability of this property before accessing it. Of course, the simplest way to check this property is to use the UI_USER_INTERFACE_IDIOM macro, which performs the necessary runtime checks for you. Advanced App Tricks Creating a Universal App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 110if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) { // The device is an iPad running iOS 3.2 or later. } else { // The device is an iPhone or iPod touch. } Supporting Multiple Versions of iOS Any app that supports a range of iOS versions must use runtime checks to prevent the use of newer APIs on older versions of iOS that do not support them. For example, if you build your app using new features in iOS 6 but your app still supports iOS 5, runtime checks allow you to use recently introduced features when they are available and to follow alternate code paths when they are not. Failure to include such checks will cause your app to crash when it tries to use new symbols that are not available on the older operating system. There are several types of checks that you can make: ● To determine whether amethod is available on an existing class, use the instancesRespondToSelector: class method or the respondsToSelector: instance method. ● Apps that link against iOS SDK 4.2 and later can use the weak linking support introduced in that version of the SDK. This support lets you check for the existence of a given Class object to determine whether you can use that class. For example: if ([UIPrintInteractionController class]) { // Create an instance of the class and use it. } else { // The print interaction controller is not available. } To use this feature, you must build your app using LLVM and Clang and the app’s deployment target must be set to iOS 3.1 or later. ● Appsthat link against iOS SDK 4.1 and earlier must use the NSClassFromString function to see whether a class is defined. If the function returns a value other than nil, you may use the class. For example: Class splitVCClass = NSClassFromString(@"UISplitViewController"); Advanced App Tricks Supporting Multiple Versions of iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 111if (splitVCClass) { UISplitViewController* mySplitViewController = [[splitVCClass alloc] init]; // Configure the split view controller. } ● To determine whether a C-based function is available, perform a Boolean comparison of the function name to NULL. If the symbol is not NULL, you can use the function. For example: if (UIGraphicsBeginPDFPage != NULL) { UIGraphicsBeginPDFPage(); } For more information and examples of how to write code that supports multiple deployment targets, see SDK Compatibility Guide . Launching in Landscape Mode Apps that uses only landscape orientations for their interface must explicitly ask the system to launch the app in that orientation. Normally, apps launch in portrait mode and rotate their interface to match the device orientation as needed. For apps that support both portrait and landscape orientations, always configure your views for portrait mode and then let your view controllers handle any rotations. If, however, your app supports landscape but not portrait orientations, perform the following tasks to make it launch in landscape mode initially: ● Add the UIInterfaceOrientation key to your app’s Info.plist file and set the value of this key to either UIInterfaceOrientationLandscapeLeft or UIInterfaceOrientationLandscapeRight. ● Lay out your views in landscape mode and make sure that their layout or autosizing options are set correctly. ● Override your view controller’s shouldAutorotateToInterfaceOrientation: method and return YES for the left or right landscape orientations and NO for portrait orientations. Advanced App Tricks Launching in Landscape Mode 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 112Important: Apps should always use view controllers to manage their window-based content. The UIInterfaceOrientation key in the Info.plist file tells iOS that it should configure the orientation of the app status bar (if one is displayed) as well as the orientation of views managed by any view controllers at launch time. In iOS 2.1 and later, view controllers respect this key and set their view’s initial orientation to match. Using this key is equivalent to calling the setStatusBarOrientation:animated: method of UIApplication early in the execution of your applicationDidFinishLaunching: method. Note: To launch a view controller–based app in landscape mode in versions of iOS before 2.1, you need to apply a 90-degree rotation to the transform of the app’s root view in addition to all the preceding steps. Installing App-Specific Data Files at First Launch You can use your app’s first launch cycle to set up any data or configuration files required to run. App-specific data files should be created in the Library/Application Support// directory of your app sandbox, where is your app’s bundle identifier. You can furthersubdivide this directory to organize your data files as needed. You can also create files in other directories, such as to your app’s iCloud container directory or to the local Documents directory, depending on your needs. If your app’s bundle contains data filesthat you plan to modify, you must copy those files out of the app bundle and modify the copies. You must not modify any files inside your app bundle. Because iOS apps are code signed, modifying files inside your app bundle invalidates your app’s signature and prevents your app from launching in the future. Copying those files to the Application Support directory (or another writable directory in your sandbox) and modifying them there is the only way to use such files safely. For more information about the directories of the iOS app sandbox and the proper location for files, see File System Programming Guide . Protecting Data Using On-Disk Encryption In iOS 4 and later, apps can use the data protection feature to add a level of security to their on-disk data. Data protection uses the built-in encryption hardware present on specific devices (such as the iPhone 3GS and iPhone 4) to store files in an encrypted format on disk. While the user’s device is locked, protected files are inaccessible even to the app that created them. The user must explicitly unlock the device (by entering the appropriate passcode) at least once before your app can access one of its protected files. Data protection is available on most iOS devices and is subject to the following requirements: Advanced App Tricks Installing App-Specific Data Files at First Launch 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 113● The file system on the user’s device must support data protection. This is true for newer devices, but for some earlier devices, the user might have to reformat the device’s disk and restore any content from a backup. ● The user must have an active passcode lock set for the device. To protect a file, your app must add an attribute to the file indicating the desired level of protection. Add this attribute using either the NSData class or the NSFileManager class. When writing new files, you can use the writeToFile:options:error: method of NSData with the appropriate protection value as one of the write options. For existing files, you can use the setAttributes:ofItemAtPath:error: method of NSFileManager to set or change the value of the NSFileProtectionKey. When using these methods, your app can specify one of the following protection levels for the file: ● No protection—The file is not encrypted on disk. You can use this option to remove data protection from an accessible file. Specify the NSDataWritingFileProtectionNone option (NSData) or the NSFileProtectionNone attribute (NSFileManager). ● Complete—The file is encrypted and inaccessible while the device is locked. Specify the NSDataWritingFileProtectionComplete option (NSData) or the NSFileProtectionComplete attribute (NSFileManager). ● Complete unless already open—The file is encrypted. A closed file isinaccessible while the device islocked. After the user unlocks the device, your app can open the file and use it. If the user locks the device while the file is open, though, your app can continue to access it. Specify the NSDataWritingFileProtectionCompleteUnlessOpen option (NSData) or the NSFileProtectionCompleteUnlessOpen attribute (NSFileManager). ● Complete until first login—The file is encrypted and inaccessible until after the device has booted and the user has unlocked it once. Specify the NSDataWritingFileProtectionCompleteUntilFirstUserAuthentication option (NSData) or the NSFileProtectionCompleteUntilFirstUserAuthentication attribute (NSFileManager). If you protect a file, your app must be prepared to lose access to that file. When complete file protection is enabled, even your app loses the ability to read and write the file’s contents when the user locks the device. Your app has several options for tracking when access to protected files might change, though: ● The app delegate can implement the applicationProtectedDataWillBecomeUnavailable: and applicationProtectedDataDidBecomeAvailable: methods. ● Any object can register for the UIApplicationProtectedDataWillBecomeUnavailable and UIApplicationProtectedDataDidBecomeAvailable notifications. ● Any object can check the value of the protectedDataAvailable property of the shared UIApplication object to determine whether files are currently accessible. Advanced App Tricks Protecting Data Using On-Disk Encryption 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 114For new files, it is recommended that you enable data protection before writing any data to them. If you are using the writeToFile:options:error: method to write the contents of an NSData object to disk, this happens automatically. For existing files, adding data protection replaces an unprotected file with a new protected version. Tips for Developing a VoIP App A Voice over Internet Protocol (VoIP) app allows the user to make phone calls using an Internet connection instead of the device’s cellular service. Such an app needs to maintain a persistent network connection to its associated service so that it can receive incoming calls and other relevant data. Rather than keep VoIP apps awake all the time, the system allowsthem to be suspended and providesfacilitiesfor monitoring theirsockets for them. When incoming traffic is detected, the system wakes up the VoIP app and returns control of itssockets to it. There are several requirements for implementing a VoIP app: 1. Add the UIBackgroundModes key to your app’s Info.plist file. Set the value of this key to an array that includes the voip string. 2. Configure one of the app’s sockets for VoIP usage. 3. Before moving to the background, call the setKeepAliveTimeout:handler: method to install a handler to be executed periodically. Your app can use this handler to maintain its service connection. 4. Configure your audio session to handle transitions to and from active use. 5. To ensure a better user experience on iPhone, use the Core Telephony framework to adjust your behavior in relation to cell-based phone calls; see Core Telephony Framework Reference . 6. To ensure good performance for your VoIP app, use the System Configuration framework to detect network changes and allow your app to sleep as much as possible. Including the voip value in the UIBackgroundModes key lets the system know that it should allow the app to run in the background as needed to manage its network sockets. This key also permits your app to play background audio (although including the audio value for the UIBackgroundModes key is still encouraged). An app with this key is also relaunched in the background immediately after system boot to ensure that the VoIP services are always available. For more information about the UIBackgroundModes key, see Information Property List Key Reference . Advanced App Tricks Tips for Developing a VoIP App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 115Configuring Sockets for VoIP Usage In order for your app to maintain a persistent connection while it is in the background, you must tag your app’s main communication socket specifically for VoIP usage. Tagging this socket tells the system that it should take over management of the socket when your app is suspended. The handoff itself is totally transparent to your app. And when new data arrives on the socket, the system wakes up the app and returns control of the socket so that the app can process the incoming data. You need to tag only the socket you use for communicating with your VoIP service. This is the socket you use to receive incoming calls or other data relevant to maintaining your VoIP service connection. Upon receipt of incoming data, the handler for this socket needs to decide what to do. For an incoming call, you likely want to post a local notification to alert the user to the call. For other noncritical data, though, you might just process the data quietly and allow the system to put your app back into the suspended state. In iOS, most sockets are managed using streams or other high-level constructs. To configure a socket for VoIP usage, the only thing you have to do beyond the normal configuration is add a special key that tags the interface as being associated with a VoIP service. Table 6-1 lists the stream interfaces and the configuration for each. Table 6-1 Configuring stream interfaces for VoIP usage Interface Configuration For Cocoa streams, use the setProperty:forKey: method to add the NSStreamNetworkServiceType property to the stream. The value of this property should be set to NSStreamNetworkServiceTypeVoIP. NSInputStream and NSOutputStream When using the URL loading system, use the setNetworkServiceType: method of your NSMutableURLRequest object to set the network service type of the request. The service type should be set to NSURLNetworkServiceTypeVoIP. NSURLRequest For Core Foundation streams, use the CFReadStreamSetProperty or CFWriteStreamSetProperty function to add the kCFStreamNetworkServiceType property to the stream. The value for this property should be set to kCFStreamNetworkServiceTypeVoIP. CFReadStreamRef and CFWriteStreamRef Advanced App Tricks Tips for Developing a VoIP App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 116Note: When configuring your sockets, you need to configure only your main signaling channel with the appropriate service type key. You do not need to include this key when configuring your voice channels. Because VoIP apps need to stay running in order to receive incoming calls, the system automatically relaunches the app if it exits with a nonzero exit code. (This type of exit could happen when there is memory pressure and your app is terminated as a result.) However, terminating the app also releases all of its sockets, including the one used to maintain the VoIP service connection. Therefore, when the app is launched, it always needs to create its sockets from scratch. Formore information about configuring Cocoa streamobjects,see StreamProgrammingGuide . Forinformation about using URL requests,see URL Loading System Programming Guide . And for information about configuring streams using the CFNetwork interfaces, see CFNetwork Programming Guide . Installing a Keep-Alive Handler To prevent the loss of its connection, a VoIP app typically needs to wake up periodically and check in with its server. To facilitate this behavior, iOS lets you install a special handler using the setKeepAliveTimeout:handler: method of UIApplication. You typically install this handler in the applicationDidEnterBackground: method of your app delegate. Once installed, the system calls your handler at least once before the timeout interval expires, waking up your app as needed to do so. Your keep-alive handler executes in the background and should return as quickly as possible. Handlers are given a maximum of 10 seconds to perform any needed tasks and return. If a handler has not returned after 10 seconds, or has not requested extra execution time before that interval expires, the system suspends the app. When installing your handler, specify the largest timeout value that is practical for your app’s needs. The minimum allowable interval for running your handler is 600 seconds, and attempting to install a handler with a smaller timeout value will fail. Although the system promises to call your handler block before the timeout value expires, it does not guarantee the exact call time. To improve battery life, the system typically groups the execution of your handler with other periodic system tasks, thereby processing all tasks in one quick burst. As a result, your handler code must be prepared to run earlier than the actual timeout period you specified. Configuring Your App’s Audio Session As with any background audio app, the audio session for a VoIP app must be configured properly to ensure the app works smoothly with other audio-based apps. Because audio playback and recording for a VoIP app are not used all the time, it is especially important that you create and configure your app’s audio session Advanced App Tricks Tips for Developing a VoIP App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 117object only when it is needed. For example, you would create the audio session to notify the user of an incoming call or while the user was actually on a call. As soon as the call ends, you would then remove strong references to the audio session and give other audio apps the opportunity to play their audio. For information about how to configure and manage an audio session for a VoIP app, see Audio Session Programming Guide . Using the Reachability Interfaces to Improve the User Experience Because VoIP apps rely heavily on the network, they should use the reachability interfaces of the System Configuration framework to track network availability and adjust their behavior accordingly. The reachability interfaces allow an app to be notified whenever network conditions change. For example, a VoIP app could close its network connections when the network becomes unavailable and recreate them when it becomes available again. The app could also use those kinds of changes to keep the user apprised about the state of the VoIP connection. To use the reachability interfaces, you must register a callback function with the framework and use it to track changes. To register a callback function: 1. Create a SCNetworkReachabilityRef structure for your target remote host. 2. Assign a callback function to yourstructure (using the SCNetworkReachabilitySetCallback function) that processes changes in your target’s reachability status. 3. Add that target to an active run loop of your app (such as the main run loop) using the SCNetworkReachabilityScheduleWithRunLoop function. Adjusting your app’s behavior based on the availability of the network can also help improve the battery life of the underlying device. Letting the system track the network changes means that your app can let itself go to sleep more often. For more information about the reachability interfaces, see System Configuration Framework Reference . Communicating with Other Apps Apps that support custom URL schemes can use those schemes to receive messages. Some apps use URL schemes to initiate specific requests. For example, an app that wants to show an address in the Maps app can use a URL to launch that app and display the address. You can implement your own URL schemes to facilitate similar types of communications in your apps. Advanced App Tricks Communicating with Other Apps 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 118Apple provides built-in support for the http, mailto, tel, and sms URL schemes. It also supports http–based URLs targeted at the Maps, YouTube, and iPod apps. The handlers for these schemes are fixed and cannot be changed. If your URL type includes a scheme that is identical to one defined by Apple, the Apple-provided app is launched instead of your app. Note: If more than one third-party app registers to handle the same URL scheme, there is currently no process for determining which app will be given that scheme. To communicate with an app using a custom URL, create an NSURL object with some properly formatted content and pass that object to the openURL: method of the shared UIApplication object. The openURL: method launches the app that registered to receive URLs of that type and passes it the URL. At that point, control passes to the new app. The following code fragment illustrates how one app can request the services of another app (“todolist” in this example is a hypothetical custom scheme registered by an app): NSURL *myURL = [NSURL URLWithString:@"todolist://www.acme.com?Quarterly%20Report#200806231300"]; [[UIApplication sharedApplication] openURL:myURL]; If your app defines a custom URL scheme, it should implement a handler for that scheme as described in “Implementing Custom URL Schemes” (page 119). For more information about the system-supported URL schemes, including information about how to format the URLs, see Apple URL Scheme Reference . Implementing Custom URL Schemes If your app can receive specially formatted URLs, you should register the corresponding URL schemes with the system. A custom URL scheme is a mechanism through which third-party apps can communicate with each other. Apps often use custom URL schemesto vend servicesto other apps. For example, the Maps app supports URLs for displaying specific map locations. Registering Custom URL Schemes To register a URL type for your app, include the CFBundleURLTypes key in your app’s Info.plist file. The CFBundleURLTypes key contains an array of dictionaries, each of which defines a URL scheme the app supports. Table 6-2 describes the keys and values to include in each dictionary. Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 119Table 6-2 Keys and values of the CFBundleURLTypes property Key Value A string containing the abstract name of the URL scheme. To ensure uniqueness, it is recommended that you specify a reverse-DNS style of identifier, for example, com.acme.myscheme. The string you specify is also used as a key in your app’s InfoPlist.strings file. The value of the key is the human-readable scheme name. CFBundleURLName An array of strings containing the URL scheme names—for example, http, mailto, tel, and sms. CFBundleURLSchemes Figure 6-1 shows the Info.plist file of an app that supports a custom scheme for creating “to-do” items. The URL types entry corresponds to the CFBundleURLTypes key added to the Info.plist file. Similarly, the “URL identifier” and “URL Schemes” entries correspond to the CFBundleURLName and CFBundleURLSchemes keys. Figure 6-1 Defining a custom URL scheme in the Info.plist file Handling URL Requests An app that has its own custom URL scheme must be able to handle URLs passed to it. All URLs are passed to your app delegate, either at launch time or while your app isrunning or in the background. To handle incoming URLs, your delegate should implement the following methods: Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 120● Use the application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: methods to retrieve information about the URL and decide whether you want to open it. If either method returns NO, your app’s URL handling code is not called. ● In iOS 4.2 and later, use the application:openURL:sourceApplication:annotation: method to open the file. ● In iOS 4.1 and earlier, use the application:handleOpenURL: method to open the file. If your app is not running when a URL request arrives, it is launched and moved to the foreground so that it can open the URL. The implementation of your application:willFinishLaunchingWithOptions: or application:didFinishLaunchingWithOptions: method should retrieve the URL from its options dictionary and determine whether the app can open it. If it can, return YES and let your application:openURL:sourceApplication:annotation: (or application:handleOpenURL:) Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 121method handle the actual opening of the URL. (If you implement both methods, both must return YES before the URL can be opened.) Figure 6-2 shows the modified launch sequence for an app that is asked to open a URL. Figure 6-2 Launching an app to open a URL If your app is running but is in the background or suspended when a URL request arrives, it is moved to the foreground to open the URL. Shortly thereafter, the system calls the delegate’s application:openURL:sourceApplication:annotation: to check the URL and open it. If your delegate Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 122does not implement this method (or the current system version is iOS 4.1 or earlier), the system calls your delegate’s application:handleOpenURL: method instead. Figure 6-3 shows the modified process for moving an app to the foreground to open a URL. Figure 6-3 Waking a background app to open a URL Note: Apps that support custom URL schemes can specify different launch images to be displayed when launching the app to handle a URL. For more information about how to specify these launch images, see “Providing Launch Images for Custom URL Schemes” (page 103). All URLs are passed to your app in an NSURL object. It is up to you to define the format of the URL, but the NSURL class conforms to the RFC 1808 specification and therefore supports most URL formatting conventions. Specifically, the class includes methods that return the various parts of a URL as defined by RFC 1808, including the user, password, query, fragment, and parameter strings. The “protocol” for your custom scheme can use these URL parts for conveying various kinds of information. In the implementation of application:handleOpenURL: shown in Listing 6-1, the passed-in URL object conveys app-specific information in its query and fragment parts. The delegate extracts this information—in this case, the name of a to-do task and the date the task is due—and with it creates a model object of the app. Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 123This example assumesthat the user is using a Gregorian calendar. If your app supports non-Gregorian calendars, you need to design your URL scheme accordingly and be prepared to handle those other calendar types in your code. Listing 6-1 Handling a URL request based on a custom scheme - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { if ([[url scheme] isEqualToString:@"todolist"]) { ToDoItem *item = [[ToDoItem alloc] init]; NSString *taskName = [url query]; if (!taskName || ![self isValidTaskString:taskName]) { // must have a task name return NO; } taskName = [taskName stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding]; item.toDoTask = taskName; NSString *dateString = [url fragment]; if (!dateString || [dateString isEqualToString:@"today"]) { item.dateDue = [NSDate date]; } else { if (![self isValidDateString:dateString]) { return NO; } // format: yyyymmddhhmm (24-hour clock) NSString *curStr = [dateString substringWithRange:NSMakeRange(0, 4)]; NSInteger yeardigit = [curStr integerValue]; curStr = [dateString substringWithRange:NSMakeRange(4, 2)]; NSInteger monthdigit = [curStr integerValue]; curStr = [dateString substringWithRange:NSMakeRange(6, 2)]; NSInteger daydigit = [curStr integerValue]; curStr = [dateString substringWithRange:NSMakeRange(8, 2)]; NSInteger hourdigit = [curStr integerValue]; curStr = [dateString substringWithRange:NSMakeRange(10, 2)]; NSInteger minutedigit = [curStr integerValue]; Advanced App Tricks Implementing Custom URL Schemes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 124NSDateComponents *dateComps = [[NSDateComponents alloc] init]; [dateComps setYear:yeardigit]; [dateComps setMonth:monthdigit]; [dateComps setDay:daydigit]; [dateComps setHour:hourdigit]; [dateComps setMinute:minutedigit]; NSCalendar *calendar = [s[NSCalendar alloc] initWithCalendarIdentifier:NSGregorianCalendar]; NSDate *itemDate = [calendar dateFromComponents:dateComps]; if (!itemDate) { return NO; } item.dateDue = itemDate; } [(NSMutableArray *)self.list addObject:item]; return YES; } return NO; } Be sure to validate the input you get from URLs passed to your app; see “Validating Input and Interprocess Communication” in Secure Coding Guide to find out how to avoid problems related to URL handling. To learn about URL schemes defined by Apple, see Apple URL Scheme Reference . Showing and Hiding the Keyboard The appearance of the keyboard is tied to the responder status of views. If a view is able to become the first responder, the system shows the keyboard whenever that view actually becomes the first responder. When the user taps another view that does not support becoming the first responder, the system hides the keyboard if it is currently visible. In UIKit, only views that support text entry can become the first responder by default. Other views must override the canBecomeFirstResponder method and return YES if they want the keyboard to be shown. Advanced App Tricks Showing and Hiding the Keyboard 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 125When a view becomes the first responder, the keyboard is shown by default, but you can replace the keyboard for viewsthatsupport custom forms of input. Every responder object has an inputView property that contains the view to be displayed when the responder becomes the first responder. When this property is nil, the system displaysthe standard keyboard. When this property is not nil, the system displaysthe view you provide instead. Normally, user taps dictate which view becomes the first responder in your app, but you can force a view to become the first responder too. Calling the becomeFirstResponder method any responder object causes that object to try to become the first responder. If that responder object is able to become the first responder, the custom input view (or the standard keyboard) is shown automatically. For more information about using the keyboard, see Text, Web, and Editing Programming Guide for iOS . Turning Off Screen Locking If an iOS-based device does not receive touch events for a specified period of time, the system turns off the screen and disables the touch sensor. Locking the screen is an important way to save power. As a result, you should generally leave this feature enabled. However, for an app that does not rely on touch events, such as a game that uses the accelerometers for input, disable screen locking to prevent the screen from going dark while the app is running. However, even in this case, disable screen locking only while the user is actively engaged with the app. For example, if the user pauses a game, reenable screen locking to allow the screen to turn off. To disable screen locking, set the idleTimerDisabled property of the shared UIApplication object to YES. Be sure to reset this property to NO when your app does not need to prevent screen locking. Advanced App Tricks Turning Off Screen Locking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 126At each step in the development of your app, you should consider the implications of your design choices on the overall performance of your app. The operating environment for iOS apps is more constrained than that for Mac OS X apps. The following sections describe the factors you should consider throughout the development process. Make App Backups More Efficient Backups occur wirelessly via iCloud or when the user syncs the device with iTunes. During backups, files are transferred from the device to the user’s computer or iCloud account. The location of files in your app sandbox determines whether or not those files are backed up and restored. If your application creates many large files that change regularly and putsthem in a location that is backed up, backups could be slowed down as a result. As you write your file-management code, you need to be mindful of this fact. App Backup Best Practices You do not have to prepare your app in any way for backup and restore operations. Devices with an active iCloud account have their app data backed up to iCloud at appropriate times. And for devices that are plugged into a computer, iTunes performs an incremental backup of the app’s data files. However, iCloud and iTunes do not back up the contents of the following directories: ● /AppName.app ● /Library/Caches ● /tmp To prevent the syncing process from taking a long time, be selective about where you place files inside your app’s home directory. Apps that store large files can slow down the process of backing up to iTunes or iCloud. These apps can also consume a large amount of a user's available storage, which may encourage the user to delete the app or disable backup of that app's data to iCloud. With this in mind, you should store app data according to the following guidelines: ● Critical data should be stored in the /Documents directory. Critical data is any data that cannot be recreated by your app, such as user documents and other user-generated content. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 127 Performance Tuning● Support files include files your application downloads or generates and that your application can recreate as needed. The location for storing your application’s support files depends on the current iOS version. ● In iOS 5.1 and later,store supportfilesin the /Library/Application Support directory and add the NSURLIsExcludedFromBackupKey attribute to the corresponding NSURL object using the setResourceValue:forKey:error: method. (If you are using Core Foundation, add the kCFURLIsExcludedFromBackupKey key to your CFURLRef object using the CFURLSetResourcePropertyForKey function.) Applying this attribute preventsthe filesfrom being backed up to iTunes or iCloud. If you have a large number of support files, you may store them in a custom subdirectory and apply the extended attribute to just the directory. ● In iOS 5.0 and earlier, store support files in the /Library/Caches directory to prevent them from being backed up. If you are targeting iOS 5.0.1, see How do I prevent files from being backed up to iCloud and iTunes? for information about how to exclude files from backups. ● Cached data should be stored in the /Library/Caches directory. Examples of files you should put in the Caches directory include (but are not limited to) database cache files and downloadable content, such as that used by magazine, newspaper, and map apps. Your app should be able to gracefully handle situations where cached data is deleted by the system to free up disk space. ● Temporary data should be stored in the /tmp directory. Temporary data comprises any data that you do not need to persist for an extended period of time. Remember to delete those files when you are done with them so that they do not continue to consume space on the user's device. Although iTunes backs up the app bundle itself, it does not do this during every sync operation. Apps purchased directly from a device are backed up when that device is next synced with iTunes. Apps are not backed up during subsequent sync operations, though, unless the app bundle itself has changed (because the app was updated, for example). For additional guidance about how you should use the directories in your app, see File System Programming Guide . Files Saved During App Updates When a user downloads an app update, iTunes installs the update in a new app directory. It then moves the user’s data files from the old installation over to the new app directory before deleting the old installation. Files in the following directories are guaranteed to be preserved during the update process: ● /Documents ● /Library Although files in other user directories may also be moved over, you should not rely on them being present after an update. Performance Tuning Make App Backups More Efficient 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 128Use Memory Efficiently Because the iOS virtual memory model does not include disk swap space, apps are more limited in the amount of memory they have available for use. Using large amounts of memory can seriously degrade system performance and potentially cause the system to terminate your app. In addition, apps running under multitasking must share system memory with all other running apps. Therefore, make it a high priority to reduce the amount of memory used by your app. There is a direct correlation between the amount of free memory available and the relative performance of your app. Less free memory means that the system is more likely to have trouble fulfilling future memory requests. If that happens, the system can always remove suspended apps, code pages, or other nonvolatile resources from memory. However, removing those apps and resources from memory may be only a temporary fix, especially if they are needed again a short time later. Instead, minimize your memory use in the first place, and clean up the memory you do use in a timely manner. The following sections provide more guidance on how to use memory efficiently and how to respond when there is only a small amount of available memory. Observe Low-Memory Warnings When the system dispatches a low-memory warning to your app, respond immediately. iOS notifies all running apps whenever the amount of free memory dips below a safe threshold. (It does not notify suspended apps.) If your app receives this warning, it must free up as much memory as possible. The best way to do this is to remove strong references to caches, image objects, and other data objects that can be recreated later. UIKit provides several ways to receive low-memory warnings, including the following: ● Implement the applicationDidReceiveMemoryWarning: method of your app delegate. ● Override the didReceiveMemoryWarning method in your custom UIViewController subclass. ● Register to receive the UIApplicationDidReceiveMemoryWarningNotificationnotification. Upon receiving any of these warnings, your handler method should respond by immediately freeing up any unneeded memory. For example, the default behavior of the UIViewController class is to purge its view if that view is not currently visible; subclasses can supplement the default behavior by purging additional data structures. An app that maintains a cache of images might respond by releasing any images that are not currently onscreen. If your data model includes known purgeable resources, you can have a corresponding manager object register forthe UIApplicationDidReceiveMemoryWarningNotification notification and remove strong references to its purgeable resources directly. Handling this notification directly avoids the need to route all memory warning calls through the app delegate. Performance Tuning Use Memory Efficiently 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 129Note: You can test your app’s behavior under low-memory conditions using the Simulate Memory Warning command in iOS Simulator. Reduce Your App’s Memory Footprint Starting off with a low footprint gives you more room for expanding your app later. Table 7-1 lists some tips on how to reduce your app’s overall memory footprint. Table 7-1 Tips for reducing your app’s memory footprint Tip Actions to take Because memory is a critical resource in iOS, your app should have no memory leaks. You can use the Instruments app to track down leaks in your code, both in Simulator and on actual devices. For more information on using Instruments, see Instruments User Guide . Eliminate memory leaks. Files reside on disk but must be loaded into memory before they can be used. Property list files and images can be made smaller with some very simple actions. To reduce the space used by property list files, write those files out in a binary format using the NSPropertyListSerialization class. For images, compress all image files to make them as small as possible. (To compress PNG images—the preferred image format for iOS apps—use the pngcrush tool.) Make resource files as small as possible. If your app manipulates large amounts of structured data, store it in a Core Data persistent store or in a SQLite database instead of in a flat file. Both Core Data and SQLite provides efficient ways to manage large data sets without requiring the entire set to be in memory all at once. The Core Data framework was introduced in iOS 3.0. Use Core Data or SQLite for large data sets. You should never load a resource file until it is actually needed. Prefetching resource files may seem like a way to save time, but this practice actually slows down your app right away. In addition, if you end up not using the resource, loading it wastes memory for no good purpose. Load resources lazily. Adding the -mthumb compiler flag can reduce the size of your code by up to 35%. However, if your app contains floating-point–intensive code modules and you are building your app for ARMv6, you should disable the Thumb option. If you are building your code for ARMv7, you should leave Thumb enabled. Build your program using the Thumb option. Performance Tuning Use Memory Efficiently 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 130Allocate Memory Wisely Table 7-2 lists tips for improving memory usage in your app. Table 7-2 Tips for allocating memory Tip Actions to take With automatic reference counting (ARC), it is better to alloc/init objects and let the compiler release them for you at the appropriate time. This is true even for temporary objects that in the past you might have autoreleased to prevent them from living past the scope of the current method. Reduce your use of autoreleased objects. Avoid loading a large resource file when a smaller one will do. Instead of using a high-resolution image, use one that is appropriately sized for iOS-based devices. If you must use large resource files, find ways to load only the portion of the file that you need at any given time. For example, rather than load the entire file into memory, use the mmap and munmap functions to map portions of the file into and out of memory. For more information about mapping files into memory, see File-System Performance Guidelines. Impose size limits on resources. Unbounded problem sets might require an arbitrarily large amount of data to compute. If the set requires more memory than is available, your app may be unable to complete the calculations. Your appsshould avoid such sets whenever possible and work on problems with known memory limits. Avoid unbounded problem sets. For detailed information about ARC and memory management, see Transitioning to ARC Release Notes. Move Work off the Main Thread Be sure to limit the type of work you do on the main thread of your app. The main thread is where your app handlestouch events and other user input. To ensure that your app is alwaysresponsive to the user, you should never use the main thread to perform long-running or potentially unbounded tasks, such as tasks that access the network. Instead, you should always move those tasks onto background threads. The preferred way to do so is to use Grand Central Dispatch (GCD) or operation objects to perform tasks asynchronously. Moving tasks into the background leaves your main thread free to continue processing user input, which is especially important when your app is starting up or quitting. During these times, your app is expected to respond to events in a timely manner. If your app’s main thread is blocked at launch time, the system could kill the app before it even finishes launching. If the main thread is blocked at quitting time, the system could similarly kill the app before it has a chance to write out crucial user data. For more information about using GCD, operation objects, and threads, see Concurrency Programming Guide . Performance Tuning Move Work off the Main Thread 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 131Floating-Point Math Considerations The processors found in iOS-based devices are capable of performing floating-point calculations in hardware. If you have an existing program that performs calculations using a software-based fixed-point math library, you should consider modifying your code to use floating-point math instead. Hardware-based floating-point computations are typically much faster than their software-based fixed-point equivalents. Important: If you build your app for ARMv6 and your code uses floating-point math extensively, compile that code without the -mthumb compiler option. The Thumb option can reduce the size of code modules, but it can also degrade the performance of floating-point code. If you build your app for ARMv7, you should always enable the Thumb option. In iOS 4 and later, you can also use the functions of the Accelerate framework to perform complex mathematical calculations. Thisframework contains high-performance vector-accelerated librariesfor digitalsignal processing and linear algebra mathematics. You can apply these librariesto problemsinvolving audio and video processing, physics, statistics, cryptography, and complex algebraic equations. Reduce Power Consumption Power consumption on mobile devices is always an issue. The power management system in iOS conserves power by shutting down any hardware featuresthat are not currently being used. You can help improve battery life by optimizing your use of the following features: ● The CPU ● Wi-Fi, Bluetooth, and baseband (EDGE, 3G) radios ● The Core Location framework ● The accelerometers ● The disk The goal of your optimizations should be to do the most work you can in the most efficient way possible. You should always optimize your app’s algorithms using Instruments. But even the most optimized algorithm can still have a negative impact on a device’s battery life. You should therefore consider the following guidelines when writing your code: ● Avoid doing work that requires polling. Polling prevents the CPU from going to sleep. Instead of polling, use the NSRunLoop or NSTimer classes to schedule work as needed. Performance Tuning Floating-Point Math Considerations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 132● Leave the idleTimerDisabled property of the shared UIApplication object set to NO whenever possible. The idle timer turns off the device’s screen after a specified period of inactivity. If your app does not need the screen to stay on, let the system turn it off. If your app experiences side effects as a result of the screen being turned off, you should modify your code to eliminate the side effects rather than disable the idle timer unnecessarily. ● Coalesce work whenever possible to maximize idle time. It generally takes less power to perform a set of calculations all at once than it does to perform them in small chunks over an extended period of time. Doing small bits of work periodically requires waking up the CPU more often and getting it into a state where it can perform your tasks. ● Avoid accessing the disk too frequently. For example, if your app saves state information to the disk, do so only when that state information changes, and coalesce changes whenever possible to avoid writing small changes at frequent intervals. ● Do not draw to the screen faster than is needed. Drawing is an expensive operation when it comes to power. Do not rely on the hardware to throttle your frame rates. Draw only as many frames as your app actually needs. ● If you use the UIAccelerometer class to receive regular accelerometer events, disable the delivery of those events when you do not need them. Similarly, set the frequency of event delivery to the smallest value that is suitable for your needs. For more information, see Event Handling Guide for iOS . The more data you transmit to the network, the more power must be used to run the radios. In fact, accessing the network is the most power-intensive operation you can perform. You can minimize that time by following these guidelines: ● Connect to external network servers only when needed, and do not poll those servers. ● When you must connect to the network, transmit the smallest amount of data needed to do the job. Use compact data formats, and do not include excess content that simply is ignored. ● Transmit data in bursts rather than spreading out transmission packets over time. The system turns off the Wi-Fi and cell radios when it detects a lack of activity. When it transmits data over a longer period of time, your app uses much more power than when it transmitsthe same amount of data in a shorter amount of time. ● Connect to the network using the Wi-Fi radios whenever possible. Wi-Fi uses less power and is preferred over cellular radios. ● If you use the Core Location framework to gather location data, disable location updates as soon as you can and set the distance filter and accuracy levels to appropriate values. Core Location uses the available GPS, cell, and Wi-Fi networks to determine the user’s location. Although Core Location works hard to minimize the use of these radios, setting the accuracy and filter values gives Core Location the option to turn off hardware altogether in situations where it is not needed. For more information, see Location Awareness Programming Guide . Performance Tuning Reduce Power Consumption 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 133The Instruments app includes several instruments for gathering power-related information. You can use these instruments to gather general information about power consumption and to gather specific measurements for hardware such as the Wi-Fi and Bluetooth radios, GPS receiver, display, and CPU. For more information about using these instruments, see Instruments User Guide . Tune Your Code iOS comes with several apps for tuning the performance of your app. Most of these tools run on Mac OS X and are suitable for tuning some aspects of your code while it runs in iOS Simulator. For example, you can use Simulator to eliminate memory leaks and make sure your overall memory usage is as low as possible. You can also remove any computational hotspots in your code that might be caused by an inefficient algorithm or a previously unknown bottleneck. After you have tuned your code in Simulator, you should then use the Instruments app to further tune your code on a device. Running your code on an actual device is the only way to tune your code fully. Because Simulator runs in Mac OS X, it has the advantage of a faster CPU and more usable memory, so its performance is generally much better than the performance on an actual device. And using Instruments to trace your code on an actual device may point out additional performance bottlenecks that need tuning. For more information on using Instruments, see Instruments User Guide . Improve File Access Times Minimize the amount of data you write to the disk. File operations are relatively slow and involve writing to the flash drive, which has a limited lifespan. Some specific tips to help you minimize file-related operations include: ● Write only the portions of the file that changed, and aggregate changes when you can. Avoid writing out the entire file just to change a few bytes. ● When defining your file format, group frequently modified content together to minimize the overall number of blocks that need to be written to disk each time. ● If your data consists of structured content that is randomly accessed, store it in a Core Data persistent store or a SQLite database, especially if the amount of data you are manipulating could grow to more than a few megabytes. Avoid writing cache files to disk. The only exception to this rule is when your app quits and you need to write state information that can be used to put your app back into the same state when it is next launched. Performance Tuning Tune Your Code 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 134Tune Your Networking Code The networking stack in iOS includes several interfaces for communicating over the radio hardware of iOS devices. The main programming interface is the CFNetwork framework, which builds on top of BSD sockets and opaque types in the Core Foundation framework to communicate with network entities. You can also use the NSStream classes in the Foundation framework and the low-level BSD sockets found in the Core OS layer of the system. For information about how to use the CFNetwork framework for network communication, see CFNetwork Programming Guide and CFNetwork Framework Reference . For information about using the NSStream class, see Foundation Framework Reference . Tips for Efficient Networking Implementing code to receive or transmit data acrossthe network is one of the most power-intensive operations on a device. Minimizing the amount of time spent transmitting or receiving data helps improve battery life. To that end, you should consider the following tips when writing your network-related code: ● For protocols you control, define your data formats to be as compact as possible. ● Avoid using chatty protocols. ● Transmit data packets in bursts whenever you can. Cellular and Wi-Fi radios are designed to power down when there is no activity. Depending on the radio, though, doing so can take several seconds. If your app transmits small bursts of data every few seconds, the radios may stay powered up and continue to consume power, even when they are not actually doing anything. Rather than transmit small amounts of data more often, it is better to transmit a larger amount of data once or at relatively large intervals. When communicating over the network, packets can be lost at any time. Therefore, when writing your networking code, you should be sure to make it as robust as possible when it comes to failure handling. It is perfectly reasonable to implement handlers that respond to changes in network conditions, but do not be surprised if those handlers are not called consistently. For example, the Bonjour networking callbacks may not always be called immediately in response to the disappearance of a network service. The Bonjour system service immediately invokes browsing callbacks when it receives a notification that a service is going away, but network services can disappear without notification. This situation might occur if the device providing the network service unexpectedly loses network connectivity or the notification is lost in transit. Performance Tuning Tune Your Networking Code 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 135Using Wi-Fi If your app accesses the network using the Wi-Fi radios, you must notify the system of that fact by including the UIRequiresPersistentWiFi key in the app’s Info.plist file. The inclusion of this key lets the system know that it should display the network selection dialog if it detects any active Wi-Fi hot spots. It also lets the system know that it should not attempt to shut down the Wi-Fi hardware while your app is running. To prevent the Wi-Fi hardware from using too much power, iOS has a built-in timer that turns off the hardware completely after 30 minutesif no running app hasrequested its use through the UIRequiresPersistentWiFi key. If the user launches an app that includes the key, iOS effectively disables the timer for the duration of the app’s life cycle. As soon as that app quits or is suspended, however, the system reenables the timer. Note: Note that even when UIRequiresPersistentWiFi has a value of true, it has no effect when the device is idle (that is, screen-locked). The app is considered inactive, and although it may function on some levels, it has no Wi-Fi connection. For more information on the UIRequiresPersistentWiFi key and the keys of the Info.plist file, see Figure 6-1 (page 120). The Airplane Mode Alert If your app launches while the device is in airplane mode, the system may display an alert to notify the user of that fact. The system displays this alert only when all of the following conditions are met: ● Your app’s information property list (Info.plist) file contains the UIRequiresPersistentWiFi key and the value of that key is set to true. ● Your app launches while the device is currently in airplane mode. ● Wi-Fi on the device has not been manually reenabled after the switch to airplane mode. Performance Tuning Tune Your Networking Code 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 136The iOS environment affects several aspects of how you design your app. Understanding some key aspects should help you when writing your code. Specialized System Behaviors The iOS system is based on the same technologies used by Mac OS X, namely the Mach kernel and BSD interfaces. Thus, iOS apps run in a UNIX-based system and have full support for threads, sockets, and many of the other technologies typically available at that level. However, there are places where the behavior of iOS differs from that of Mac OS X. The Virtual Memory System To manage program memory, iOS uses essentially the same virtual memory system found in Mac OS X. In iOS, each program still hasits own virtual addressspace, but unlike Mac OS X, the amount of usable virtual memory is constrained by the amount of physical memory available. This is because iOS does not support paging to disk when memory getsfull. Instead, the virtual memory system simply releasesread-only memory pages,such as code pages, when it needs more space. Such pages can always be loaded back into memory later if they are needed again. If memory continues to be constrained, the system may send low-memory notifications to any running apps, asking them to free up additional memory. All apps should respond to this notification and do their part to help relieve the memory pressure. For information on how to handle such notificationsin your app,see “Observe Low-Memory Warnings” (page 129). The Automatic Sleep Timer One way iOS saves battery power is through the automatic sleep timer. When the system does not detect touch events for an extended period of time, it dims the screen initially and eventually turns it off altogether. If you are creating an app that does not use touch inputs, such as a game that relies on the accelerometers, you can disable the automatic sleep timer to prevent the screen from dimming. You should use this timer sparingly and reenable it as soon as possible to conserve power. Only apps that display visual content and do not rely on touch inputs should ever disable the timer. Audio apps or apps that do not need to present visual content should not disable the timer. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 137 The iOS EnvironmentThe process for disabling the timer is described in “Turning Off Screen Locking” (page 126). For additional tips on how to save power in your app, see “Reduce Power Consumption” (page 132). Multitasking Support In iOS 4 and later, multitasking allows apps to run in the background even when they are not visible on the screen. Most background appsreside in memory but do not actually execute any code. These apps are suspended by the system shortly after entering the background to preserve battery life. Apps can ask the system for background execution time in a number of ways, though. For an overview of multitasking and what you need to do to support it, see “Background Execution and Multitasking” (page 54). Security The security infrastructure in iOS isthere to protect your app’s data and the system as a whole. Security breaches can and will happen, so the first line of defense in iOS is to minimize the damage caused by such breaches by securing each app separately in its own sandbox. But iOS provides other technologies, such as encryption and certificate support, to help you protect your data at an even more fundamental level. For an introduction to security and how it impacts the design of your app, see Security Overview. The App Sandbox For security reasons, iOS places each app (including its preferences and data) in a sandbox at install time. A sandbox is a set of fine-grained controls that limit the app’s access to files, preferences, network resources, hardware, and so on. As part of the sandboxing process, the system installs each app in its own sandbox directory, which acts as the home for the app and its data. The iOS Environment Security 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 138To help apps organize their data, each sandbox directory containsseveral well-known subdirectoriesfor placing files. Figure A-1 shows the basic layout of a sandbox directory. For detailed information about the sandbox directory and what belongs in each of its subdirectories, see File System Programming Guide . Figure A-1 Sandbox directories in iOS The iOS Environment Security 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 139Important: The purpose of a sandbox is to limit the damage that a compromised app can cause to the system. Sandboxes do not prevent attacksfrom happening to a particular app and it isstill your responsibility to code defensively to prevent attacks. For example, if your app does not validate user input and there is an exploitable buffer overflow in your input-handling code, an attacker could still hijack your app or cause it to crash. The sandbox only prevents the hijacked app from affecting other apps and other parts of the system. Keychain Data A keychain is a secure, encrypted container for passwords and other secrets. The keychain is intended for storing small amounts of sensitive data that are specific to your app. It is not intended as a general-purpose mechanism for encrypting and storing data. Keychain data for an app isstored outside of the app’ssandbox. When the user backs up app data using iTunes, the keychain data is also backed up. Before iOS 4.0, keychain data could only be restored to the device from which the backup was made. In iOS 4.0 and later, a keychain item that is password protected can be restored to a different device only if its accessibility is not set to kSecAttrAccessibleAlwaysThisDeviceOnly or any other value that restricts it to the current device. Upgrading an app does not affect that app’s keychain data. For more on the iOS keychain, see “Keychain Services Concepts” in Keychain Services Programming Guide . The iOS Environment Security 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 140This table describes the changes to iOS App Programming Guide . Date Notes 2012-09-19 Contains information about new features in iOS 6. Added information about the NSURL and CFURL keys used to prevent a file from being backed up. 2012-03-07 Updated the section that describes the behavior of apps in the background. 2012-01-09 2011-10-12 Added information about features introduced in iOS 5.0. Reorganized book and added more design-level information. Added high-level information about iCloud and how it impactsthe design of applications. 2011-02-24 Added information about using AirPlay in the background. 2010-12-13 Made minor editorial changes. 2010-11-15 Incorporated additional iPad-related design guidelinesinto this document. Updated the information about how keychain data is preserved and restored. Fixed several typographical errors and updated the code sample on initiating background tasks. 2010-08-20 Updated the guidance related to specifying application icons and launch images. 2010-06-30 Changed the title from iPhone Application Programming Guide . 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 141 Document Revision HistoryDate Notes Reorganized the book so that it focuses on the design of the core parts of your application. 2010-06-14 Added information about how to support multitasking in iOS 4 and later. For more information, see “Core App Objects” (page 17). Updated the section describing how to determine what hardware is available. Added information about how to support devices with high-resolution screens. Incorporated iPad-related information. 2010-02-24 Made minor corrections. Updated the “Multimedia Support” chapter with improved descriptions of audio formats and codecs. 2010-01-20 Moved the iPhone specific Info.plist keys to Information Property List Key Reference . 2009-10-19 Updated the “Multimedia Support” chapter for iOS 3.1. 2009-06-17 Added information about using the compass interfaces. Moved information about OpenGL support to OpenGL ES Programming Guide for iOS . Updated the list of supported Info.plist keys. 2009-03-12 Updated for iOS 3.0 Added code examples to "Copy and Paste Operations" in the Event Handling chapter. Added a section on keychain data to the Files and Networking chapter. Added information about how to display map and email interfaces. Made various small corrections. Document Revision History 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 142Date Notes Fixed several typos and clarified the creation process for child pages in the Settings application. 2009-01-06 2008-11-12 Added guidance about floating-point math considerations Updated information related to what is backed up by iTunes. 2008-10-15 Reorganized the contents of the book. Moved the high-level iOS information to iOS Technology Overview. Moved information about the standard system URL schemesto Apple URL Scheme Reference . Moved information about the development tools and how to configure devices to Tools Workflow Guide for iOS . Created the Core Application chapter, which now introduces the application architecture and covers much of the guidance for creating iPhone applications. Added a Text and Web chapter to cover the use of text and web classes and the manipulation of the onscreen keyboard. Created a separate chapter for Files and Networking and moved existing information into it. Changed the title from iPhone OS Programming Guide . New document that describesiOS and the development processfor iPhone applications. 2008-07-08 Document Revision History 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 143Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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. 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, AirPlay, Bonjour, Cocoa, Instruments, iPad, iPhone, iPod, iPod touch, iTunes, Keychain, Mac, Mac OS, Macintosh, Numbers, Objective-C, OS X, Sand, Spotlight, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Retina is a trademark of Apple Inc. iCloud is a service mark of Apple Inc., registered in the U.S. and other countries. App Store is a service mark of Apple Inc. Intel and Intel Core are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. OpenGL is a registered trademark of Silicon Graphics, Inc. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. UNIX is a registered trademark of The Open Group. 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.ASARESULT, THISDOCUMENT 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. Concurrency Programming GuideContents Introduction 7 Organization of This Document 7 A Note About Terminology 8 See Also 8 Concurrency and Application Design 9 The Move Away from Threads 10 Dispatch Queues 10 Dispatch Sources 11 Operation Queues 12 Asynchronous Design Techniques 12 Define Your Application’s Expected Behavior 13 Factor Out Executable Units of Work 13 Identify the Queues You Need 14 Tips for Improving Efficiency 14 Performance Implications 15 Concurrency and Other Technologies 15 OpenCL and Concurrency 15 When to Use Threads 16 Operation Queues 17 About Operation Objects 17 Concurrent Versus Non-concurrent Operations 18 Creating an NSInvocationOperation Object 19 Creating an NSBlockOperation Object 20 Defining a Custom Operation Object 21 Performing the Main Task 21 Responding to Cancellation Events 22 Configuring Operations for Concurrent Execution 24 Maintaining KVO Compliance 27 Customizing the Execution Behavior of an Operation Object 28 Configuring Interoperation Dependencies 29 Changing an Operation’s Execution Priority 29 Changing the Underlying Thread Priority 30 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 2Setting Up a Completion Block 30 Tips for Implementing Operation Objects 31 Managing Memory in Operation Objects 31 Handling Errors and Exceptions 32 Determining an Appropriate Scope for Operation Objects 32 Executing Operations 33 Adding Operations to an Operation Queue 33 Executing Operations Manually 34 Canceling Operations 36 Waiting for Operations to Finish 36 Suspending and Resuming Queues 37 Dispatch Queues 38 About Dispatch Queues 38 Queue-Related Technologies 41 Implementing Tasks Using Blocks 41 Creating and Managing Dispatch Queues 43 Getting the Global Concurrent Dispatch Queues 43 Creating Serial Dispatch Queues 44 Getting Common Queues at Runtime 45 Memory Management for Dispatch Queues 45 Storing Custom Context Information with a Queue 46 Providing a Clean Up Function For a Queue 46 Adding Tasks to a Queue 47 Adding a Single Task to a Queue 48 Performing a Completion Block When a Task Is Done 49 Performing Loop Iterations Concurrently 50 Performing Tasks on the Main Thread 51 Using Objective-C Objects in Your Tasks 51 Suspending and Resuming Queues 52 Using Dispatch Semaphores to Regulate the Use of Finite Resources 52 Waiting on Groups of Queued Tasks 53 Dispatch Queues and Thread Safety 54 Dispatch Sources 56 About Dispatch Sources 56 Creating Dispatch Sources 57 Writing and Installing an Event Handler 58 Installing a Cancellation Handler 60 Changing the Target Queue 61 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsAssociating Custom Data with a Dispatch Source 61 Memory Management for Dispatch Sources 62 Dispatch Source Examples 62 Creating a Timer 62 Reading Data from a Descriptor 64 Writing Data to a Descriptor 66 Monitoring a File-System Object 68 Monitoring Signals 70 Monitoring a Process 71 Canceling a Dispatch Source 72 Suspending and Resuming Dispatch Sources 73 Migrating Away from Threads 74 Replacing Threads with Dispatch Queues 74 Eliminating Lock-Based Code 76 Implementing an Asynchronous Lock 76 Executing Critical Sections Synchronously 77 Improving on Loop Code 77 Replacing Thread Joins 79 Changing Producer-Consumer Implementations 80 Replacing Semaphore Code 81 Replacing Run-Loop Code 81 Compatibility with POSIX Threads 82 Glossary 84 Document Revision History 87 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsTables and Listings Operation Queues 17 Table 2-1 Operation classes of the Foundation framework 17 Table 2-2 Methods to override for concurrent operations 24 Listing 2-1 Creating an NSInvocationOperation object 19 Listing 2-2 Creating an NSBlockOperation object 20 Listing 2-3 Defining a simple operation object 22 Listing 2-4 Responding to a cancellation request 23 Listing 2-5 Defining a concurrent operation 25 Listing 2-6 The start method 26 Listing 2-7 Updating an operation at completion time 27 Listing 2-8 Executing an operation object manually 35 Dispatch Queues 38 Table 3-1 Types of dispatch queues 39 Table 3-2 Technologies that use dispatch queues 41 Listing 3-1 A simple block example 42 Listing 3-2 Creating a new serial queue 45 Listing 3-3 Installing a queue clean up function 46 Listing 3-4 Executing a completion callback after a task 49 Listing 3-5 Performing the iterations of a for loop concurrently 51 Listing 3-6 Waiting on asynchronous tasks 54 Dispatch Sources 56 Table 4-1 Getting data from a dispatch source 59 Listing 4-1 Creating a timer dispatch source 63 Listing 4-2 Reading data from a file 65 Listing 4-3 Writing data to a file 67 Listing 4-4 Watching for filename changes 68 Listing 4-5 Installing a block to monitor signals 70 Listing 4-6 Monitoring the death of a parent process 71 Migrating Away from Threads 74 Listing 5-1 Modifying protected resources asynchronously 77 Listing 5-2 Running critical sections synchronously 77 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 5Listing 5-3 Replacing a for loop without striding 78 Listing 5-4 Adding a stride to a dispatched for loop 78 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 6 Tables and ListingsConcurrency is the notion of multiple things happening at the same time. With the proliferation of multicore CPUs and the realization that the number of cores in each processor will only increase, software developers need new ways to take advantage of them. Although operating systems like OS X and iOS are capable of running multiple programs in parallel, most of those programs run in the background and perform tasks that require little continuous processor time. It is the current foreground application that both captures the user’s attention and keeps the computer busy. If an application has a lot of work to do but keeps only a fraction of the available cores occupied, those extra processing resources are wasted. In the past, introducing concurrency to an application required the creation of one or more additional threads. Unfortunately, writing threaded code is challenging. Threads are a low-level tool that must be managed manually. Given that the optimal number of threads for an application can change dynamically based on the currentsystem load and the underlying hardware, implementing a correct threading solution becomes extremely difficult, if not impossible to achieve. In addition, the synchronization mechanisms typically used with threads add complexity and risk to software designs without any guarantees of improved performance. Both OS X and iOS adopt a more asynchronous approach to the execution of concurrent tasksthan istraditionally found in thread-based systems and applications. Rather than creating threads directly, applications need only define specific tasks and then let the system perform them. By letting the system manage the threads, applications gain a level ofscalability not possible with raw threads. Application developers also gain a simpler and more efficient programming model. This document describes the technique and technologies you should be using to implement concurrency in your applications. The technologies described in this document are available in both OS X and iOS. Organization of This Document This document contains the following chapters: ● “Concurrency and Application Design” (page 9) introduces the basics of asynchronous application design and the technologies for performing your custom tasks asynchronously. ● “Operation Queues” (page 17)shows you how to encapsulate and perform tasks using Objective-C objects. ● “Dispatch Queues” (page 38) shows you how to execute tasks concurrently in C-based applications. ● “Dispatch Sources” (page 56) shows you how to handle system events asynchronously. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 7 Introduction● “Migrating Away from Threads” (page 74) provides tips and techniques for migrating your existing thread-based code over to use newer technologies. This document also includes a glossary that defines relevant terms. A Note About Terminology Before entering into a discussion about concurrency, it is necessary to define some relevant terminology to prevent confusion. Developers who are more familiar with UNIX systems or older OS X technologies may find the terms “task”, “process”, and “thread” used somewhat differently in this document. This document uses these terms in the following way: ● The term thread is used to refer to a separate path of execution for code. The underlying implementation for threads in OS X is based on the POSIX threads API. ● The term process is used to refer to a running executable, which can encompass multiple threads. ● The term task is used to refer to the abstract concept of work that needs to be performed. For complete definitions of these and other key terms used by this document, see “Glossary” (page 84). See Also This document focuses on the preferred technologies for implementing concurrency in your applications and does not cover the use of threads. If you need information about using threads and other thread-related technologies, see Threading Programming Guide . Introduction A Note About Terminology 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 8In the early days of computing, the maximum amount of work per unit of time that a computer could perform was determined by the clock speed of the CPU. But as technology advanced and processor designs became more compact, heat and other physical constraints started to limit the maximum clock speeds of processors. And so, chip manufacturerslooked for other waysto increase the total performance of their chips. The solution they settled on was increasing the number of processor cores on each chip. By increasing the number of cores, a single chip could execute more instructions per second without increasing the CPU speed or changing the chip size or thermal characteristics. The only problem was how to take advantage of the extra cores. In order to take advantage of multiple cores, a computer needs software that can do multiple things simultaneously. For a modern, multitasking operating system like OS X or iOS, there can be a hundred or more programs running at any given time, so scheduling each program on a different core should be possible. However, most of these programs are either system daemons or background applications that consume very little real processing time. Instead, what is really needed is a way for individual applications to make use of the extra cores more effectively. The traditional way for an application to use multiple cores is to create multiple threads. However, as the number of cores increases, there are problems with threaded solutions. The biggest problem is that threaded code does not scale very well to arbitrary numbers of cores. You cannot create as many threads as there are cores and expect a program to run well. What you would need to know is the number of cores that can be used efficiently, which is a challenging thing for an application to compute on its own. Even if you manage to get the numbers correct, there is still the challenge of programming for so many threads, of making them run efficiently, and of keeping them from interfering with one another. So, to summarize the problem, there needsto be a way for applicationsto take advantage of a variable number of computer cores. The amount of work performed by a single application also needs to be able to scale dynamically to accommodate changing system conditions. And the solution has to be simple enough so as to not increase the amount of work needed to take advantage of those cores. The good news is that Apple’s operating systems provide the solution to all of these problems, and this chapter takes a look at the technologies that comprise this solution and the design tweaks you can make to your code to take advantage of them. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 9 Concurrency and Application DesignThe Move Away from Threads Although threads have been around for many years and continue to have their uses, they do not solve the general problem of executing multiple tasks in a scalable way. With threads, the burden of creating a scalable solution rests squarely on the shoulders of you, the developer. You have to decide how many threads to create and adjust that number dynamically as system conditions change. Another problem is that your application assumes most of the costs associated with creating and maintaining any threads it uses. Instead of relying on threads, OS X and iOS take an asynchronous design approach to solving the concurrency problem. Asynchronous functions have been present in operating systems for many years and are often used to initiate tasks that might take a long time, such as reading data from the disk. When called, an asynchronous function does some work behind the scenes to start a task running but returns before that task might actually be complete. Typically, this work involves acquiring a background thread, starting the desired task on that thread, and then sending a notification to the caller (usually through a callback function) when the task is done. In the past, if an asynchronous function did not exist for what you want to do, you would have to write your own asynchronous function and create your own threads. But now, OS X and iOS provide technologies to allow you to perform any task asynchronously without having to manage the threads yourself. One of the technologies for starting tasks asynchronously is Grand Central Dispatch (GCD). This technology takes the thread management code you would normally write in your own applications and moves that code down to the system level. All you have to do is define the tasks you want to execute and add them to an appropriate dispatch queue. GCD takes care of creating the needed threads and of scheduling your tasks to run on those threads. Because the thread management is now part of the system, GCD provides a holistic approach to task management and execution, providing better efficiency than traditional threads. Operation queues are Objective-C objects that act very much like dispatch queues. You define the tasks you want to execute and then add them to an operation queue, which handles the scheduling and execution of those tasks. Like GCD, operation queues handle all of the thread management for you, ensuring that tasks are executed as quickly and as efficiently as possible on the system. The following sections provide more information about dispatch queues, operation queues, and some other related asynchronous technologies you can use in your applications. Dispatch Queues Dispatch queues are a C-based mechanism for executing custom tasks. A dispatch queue executestasks either serially or concurrently but alwaysin a first-in, first-out order. (In other words, a dispatch queue always dequeues and starts tasks in the same order in which they were added to the queue.) A serial dispatch queue runs only one task at a time, waiting until that task is complete before dequeuing and starting a new one. By contrast, a concurrent dispatch queue starts as many tasks as it can without waiting for already started tasks to finish. Dispatch queues have other benefits: Concurrency and Application Design The Move Away from Threads 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 10● They provide a straightforward and simple programming interface. ● They offer automatic and holistic thread pool management. ● They provide the speed of tuned assembly. ● They are much more memory efficient (because thread stacks do not linger in application memory). ● They do not trap to the kernel under load. ● The asynchronous dispatching of tasks to a dispatch queue cannot deadlock the queue. ● They scale gracefully under contention. ● Serial dispatch queues offer a more efficient alternative to locks and other synchronization primitives. The tasks you submit to a dispatch queue must be encapsulated inside either a function or a block object. Block objects are a C language feature introduced in OS X v10.6 and iOS 4.0 that are similar to function pointers conceptually, but have some additional benefits. Instead of defining blocks in their own lexical scope, you typically define blocks inside another function or method so that they can access other variables from that function or method. Blocks can also be moved out of their original scope and copied onto the heap, which is what happens when you submit them to a dispatch queue. All of these semantics make it possible to implement very dynamic tasks with relatively little code. Dispatch queues are part of the Grand Central Dispatch technology and are part of the C runtime. For more information about using dispatch queues in your applications, see “Dispatch Queues” (page 38). For more information about blocks and their benefits, see Blocks Programming Topics. Dispatch Sources Dispatch sources are a C-based mechanism for processing specific types of system events asynchronously. A dispatch source encapsulates information about a particular type of system event and submits a specific block object or function to a dispatch queue whenever that event occurs. You can use dispatch sources to monitor the following types of system events: ● Timers ● Signal handlers ● Descriptor-related events ● Process-related events ● Mach port events ● Custom events that you trigger Dispatch sources are part of the Grand Central Dispatch technology. For information about using dispatch sources to receive events in your application, see “Dispatch Sources” (page 56). Concurrency and Application Design The Move Away from Threads 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 11Operation Queues An operation queue is the Cocoa equivalent of a concurrent dispatch queue and is implemented by the NSOperationQueue class. Whereas dispatch queues always execute tasks in first-in, first-out order, operation queues take other factors into account when determining the execution order of tasks. Primary among these factors is whether a given task depends on the completion of other tasks. You configure dependencies when defining your tasks and can use them to create complex execution-order graphs for your tasks. The tasks you submit to an operation queue must be instances of the NSOperation class. An operation object is an Objective-C object that encapsulates the work you want to perform and any data needed to perform it. Because the NSOperation class is essentially an abstract base class, you typically define custom subclasses to perform your tasks. However, the Foundation framework does include some concrete subclasses that you can create and use as is to perform tasks. Operation objects generate key-value observing (KVO) notifications, which can be a useful way of monitoring the progress of your task. Although operation queues always execute operations concurrently, you can use dependencies to ensure they are executed serially when needed. For more information about how to use operation queues, and how to define custom operation objects, see “Operation Queues” (page 17). Asynchronous Design Techniques Before you even consider redesigning your code to support concurrency, you should ask yourself whether doing so is necessary. Concurrency can improve the responsiveness of your code by ensuring that your main thread is free to respond to user events. It can even improve the efficiency of your code by leveraging more cores to do more work in the same amount of time. However, it also adds overhead and increases the overall complexity of your code, making it harder to write and debug your code. Because it adds complexity, concurrency is not a feature that you can graft onto an application at the end of your product cycle. Doing it right requires careful consideration of the tasks your application performs and the data structures used to perform those tasks. Done incorrectly, you might find your code runsslower than before and is less responsive to the user. Therefore, it is worthwhile to take some time at the beginning of your design cycle to set some goals and to think about the approach you need to take. Every application has different requirements and a different set of tasks that it performs. It is impossible for a document to tell you exactly how to design your application and its associated tasks. However, the following sections try to provide some guidance to help you make good choices during the design process. Concurrency and Application Design Asynchronous Design Techniques 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 12Define Your Application’s Expected Behavior Before you even think about adding concurrency to your application, you should alwaysstart by defining what you deem to be the correct behavior of your application. Understanding your application’s expected behavior gives you a way to validate your design later. It should also give you some idea of the expected performance benefits you might receive by introducing concurrency. The first thing you should do is enumerate the tasks your application performs and the objects or data structures associated with each task. Initially, you might want to start with tasks that are performed when the user selects a menu item or clicks a button. These tasks offer discrete behavior and have a well defined start and end point. You should also enumerate other types of tasks your application may perform without user interaction, such as timer-based tasks. After you have your list of high-level tasks,start breaking each task down further into the set ofstepsthat must be taken to complete the task successfully. At thislevel, you should be primarily concerned with the modifications you need to make to any data structures and objects and how those modifications affect your application’s overallstate. You should also note any dependencies between objects and data structures as well. For example, if a task involves making the same change to an array of objects, it is worth noting whether the changes to one object affect any other objects. If the objects can be modified independently of each other, that might be a place where you could make those modifications concurrently. Factor Out Executable Units of Work From your understanding of your application’s tasks, you should already be able to identify places where your code might benefit from concurrency. If changing the order of one or more steps in a task changes the results, you probably need to continue performing those steps serially. If changing the order has no effect on the output, though, you should consider performing those steps concurrently. In both cases, you define the executable unit of work that represents the step or steps to be performed. This unit of work then becomes what you encapsulate using either a block or an operation object and dispatch to the appropriate queue. For each executable unit of work you identify, do not worry too much about the amount of work being performed, at least initially. Although there is always a cost to spinning up a thread, one of the advantages of dispatch queues and operation queues is that in many cases those costs are much smaller than they are for traditional threads. Thus, it is possible for you to execute smaller units of work more efficiently using queues than you could using threads. Of course, you should always measure your actual performance and adjust the size of your tasks as needed, but initially, no task should be considered too small. Concurrency and Application Design Asynchronous Design Techniques 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 13Identify the Queues You Need Now that your tasks are broken up into distinct units of work and encapsulated using block objects or operation objects, you need to define the queues you are going to use to execute that code. For a given task, examine the blocks or operation objects you created and the order in which they must be executed to perform the task correctly. If you implemented your tasks using blocks, you can add your blocks to either a serial or concurrent dispatch queue. If a specific order is required, you would always add your blocks to a serial dispatch queue. If a specific order is not required, you can add the blocks to a concurrent dispatch queue or add them to several different dispatch queues, depending on your needs. If you implemented your tasks using operation objects, the choice of queue is often less interesting than the configuration of your objects. To perform operation objectsserially, you must configure dependencies between the related objects. Dependencies prevent one operation from executing until the objects on which it depends have finished their work. Tips for Improving Efficiency In addition to simply factoring your code into smaller tasks and adding them to a queue, there are other ways to improve the overall efficiency of your code using queues: ● Consider computing values directly within your task if memory usage is a factor. If your application is already memory bound, computing values directly now may be faster than loading cached values from main memory. Computing values directly uses the registers and caches of the given processor core, which are much faster than main memory. Of course, you should only do this if testing indicates this is a performance win. ● Identify serial tasks early and do what you can to make them more concurrent. If a task must be executed serially because it relies on some shared resource, consider changing your architecture to remove that shared resource. You might consider making copies of the resource for each client that needs one or eliminate the resource altogether. ● Avoid using locks. The support provided by dispatch queues and operation queuesmakeslocks unnecessary in most situations. Instead of using locks to protect some shared resource, designate a serial queue (or use operation object dependencies) to execute tasks in the correct order. ● Rely on the system frameworks whenever possible. The best way to achieve concurrency is to take advantage of the built-in concurrency provided by the system frameworks. Many frameworks use threads and other technologies internally to implement concurrent behaviors. When defining your tasks, look to see if an existing framework defines a function or method that does exactly what you want and does so concurrently. Using that API may save you effort and is more likely to give you the maximum concurrency possible. Concurrency and Application Design Asynchronous Design Techniques 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 14Performance Implications Operation queues, dispatch queues, and dispatch sources are provided to make it easier for you to execute more code concurrently. However, these technologies do not guarantee improvements to the efficiency or responsiveness in your application. It is still your responsibility to use queues in a manner that is both effective for your needs and does not impose an undue burden on your application’s other resources. For example, although you could create 10,000 operation objects and submit them to an operation queue, doing so would cause your application to allocate a potentially nontrivial amount of memory, which could lead to paging and decreased performance. Before introducing any amount of concurrency to your code—whether using queues or threads—you should always gather a set of baseline metrics that reflect your application’s current performance. After introducing your changes, you should then gather additional metrics and compare them to your baseline to see if your application’s overall efficiency has improved. If the introduction of concurrency makes your application less efficient or responsive, you should use the available performance tools to check for the potential causes. For an introduction to performance and the available performance tools, and for links to more advanced performance-related topics, see Performance Overview. Concurrency and Other Technologies Factoring your code into modular tasks is the best way to try and improve the amount of concurrency in your application. However, this design approach may not satisfy the needs of every application in every case. Depending on your tasks, there might be other options that can offer additional improvements in your application’s overall concurrency. This section outlines some of the other technologies to consider using as part of your design. OpenCL and Concurrency In OS X, the Open Computing Language (OpenCL) is a standards-based technology for performing general-purpose computations on a computer’s graphics processor. OpenCL is a good technology to use if you have a well-defined set of computations that you want to apply to large data sets. For example, you might use OpenCL to perform filter computations on the pixels of an image or use it to perform complex math calculations on several values at once. In other words, OpenCL is geared more toward problem sets whose data can be operated on in parallel. Although OpenCL is good for performing massively data-parallel operations, it is not suitable for more general-purpose calculations. There is a nontrivial amount of effort required to prepare and transfer both the data and the required work kernel to a graphics card so that it can be operated on by a GPU. Similarly, there is a nontrivial amount of effort required to retrieve any results generated by OpenCL. As a result, any tasks that interact with the system are generally not recommended for use with OpenCL. For example, you would not Concurrency and Application Design Performance Implications 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 15use OpenCL to process data from files or network streams. Instead, the work you perform using OpenCL must be much more self-contained so that it can be transferred to the graphics processor and computed independently. For more information about OpenCL and how you use it, see OpenCL Programming Guide for Mac . When to Use Threads Although operation queues and dispatch queues are the preferred way to perform tasks concurrently, they are not a panacea. Depending on your application, there may still be times when you need to create custom threads. If you do create custom threads, you should strive to create as few threads as possible yourself and you should use those threads only for specific tasks that cannot be implemented any other way. Threads are still a good way to implement code that must run in real time. Dispatch queues make every attempt to run their tasks as fast as possible but they do not address real time constraints. If you need more predictable behavior from code running in the background, threads may still offer a better alternative. As with any threaded programming, you should always use threads judiciously and only when absolutely necessary. For more information about thread packages and how you use them, see Threading Programming Guide . Concurrency and Application Design Concurrency and Other Technologies 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 16Cocoa operations are an object-oriented way to encapsulate work that you want to perform asynchronously. Operations are designed to be used either in conjunction with an operation queue or by themselves. Because they are Objective-C based, operations are most commonly used in Cocoa-based applications in OS X and iOS. This chapter shows you how to define and use operations. About Operation Objects An operation object is an instance of the NSOperation class (in the Foundation framework) that you use to encapsulate work you want your application to perform. The NSOperation classitself is an abstract base class that must be subclassed in order to do any useful work. Despite being abstract, this class does provide a significant amount of infrastructure to minimize the amount of work you have to do in your own subclasses. In addition, the Foundation framework provides two concrete subclasses that you can use as-is with your existing code. Table 2-1 lists these classes, along with a summary of how you use each one. Table 2-1 Operation classes of the Foundation framework Class Description A class you use as-is to create an operation object based on an object and selector from your application. You can use this class in cases where you have an existing method that already performs the needed task. Because it does not require subclassing, you can also use this classto create operation objects in a more dynamic fashion. For information about how to use this class, see “Creating an NSInvocationOperation Object” (page 19). NSInvocationOperation A class you use as-isto execute one or more block objects concurrently. Because it can execute more than one block, a block operation object operates using a group semantic; only when all of the associated blocks have finished executing is the operation itself considered finished. For information about how to use this class,see “Creating an NSBlockOperation Object” (page 20). This class is available in OS X v10.6 and later. For more information about blocks, see Blocks Programming Topics. NSBlockOperation 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 17 Operation QueuesClass Description The base class for defining custom operation objects. Subclassing NSOperation gives you complete control over the implementation of your own operations, including the ability to alter the default way in which your operation executes and reports its status. For information about how to define custom operation objects, see “Defining a Custom Operation Object” (page 21). NSOperation All operation objects support the following key features: ● Support for the establishment of graph-based dependencies between operation objects. These dependencies prevent a given operation from running until all of the operations on which it depends have finished running. For information about how to configure dependencies, see “Configuring Interoperation Dependencies” (page 29). ● Support for an optional completion block, which is executed after the operation’s main task finishes. (OS X v10.6 and later only.) For information about how to set a completion block,see “Setting Up a Completion Block” (page 30). ● Support for monitoring changes to the execution state of your operations using KVO notifications. For information about how to observe KVO notifications, see Key-Value Observing Programming Guide . ● Support for prioritizing operations and thereby affecting their relative execution order. For more information, see “Changing an Operation’s Execution Priority” (page 29). ● Support for canceling semantics that allow you to halt an operation while it is executing. For information about how to cancel operations, see “Canceling Operations” (page 36). For information about how to support cancellation in your own operations, see “Responding to Cancellation Events” (page 22). Operations are designed to help you improve the level of concurrency in your application. Operations are also a good way to organize and encapsulate your application’s behavior into simple discrete chunks. Instead of running some bit of code on your application’s main thread, you can submit one or more operation objects to a queue and let the corresponding work be performed asynchronously on one or more separate threads. Concurrent Versus Non-concurrent Operations Although you typically execute operations by adding them to an operation queue, doing so is not required. It is also possible to execute an operation object manually by calling its start method, but doing so does not guarantee that the operation runs concurrently with the rest of your code. The isConcurrent method of the Operation Queues Concurrent Versus Non-concurrent Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 18NSOperation class tells you whether an operation runs synchronously or asynchronously with respect to the thread in which its start method was called. By default, this method returns NO, which means the operation runs synchronously in the calling thread. If you want to implement a concurrent operation—that is, one that runs asynchronously with respect to the calling thread—you must write additional code to start the operation asynchronously. For example, you might spawn a separate thread, call an asynchronous system function, or do anything else to ensure that the start method starts the task and returns immediately and, in all likelihood, before the task is finished. Most developers should never need to implement concurrent operation objects. If you always add your operations to an operation queue, you do not need to implement concurrent operations. When you submit a nonconcurrent operation to an operation queue, the queue itself creates a thread on which to run your operation. Thus, adding a nonconcurrent operation to an operation queue still results in the asynchronous execution of your operation object code. The ability to define concurrent operations is only necessary in cases where you need to execute the operation asynchronously without adding it to an operation queue. For information about how to create a concurrent operation, see “Configuring Operations for Concurrent Execution” (page 24) and NSOperation Class Reference . Creating an NSInvocationOperation Object The NSInvocationOperation class is a concrete subclass of NSOperation that, when run, invokes the selector you specify on the object you specify. Use this classto avoid defining large numbers of custom operation objects for each task in your application; especially if you are modifying an existing application and already have the objects and methods needed to perform the necessary tasks. You can also use it when the method you want to call can change depending on the circumstances. For example, you could use an invocation operation to perform a selector that is chosen dynamically based on user input. The process for creating an invocation operation is straightforward. You create and initialize a new instance of the class, passing the desired object and selector to execute to the initialization method. Listing 2-1 shows two methodsfrom a custom classthat demonstrate the creation process. The taskWithData: method creates a new invocation object and supplies it with the name of another method, which contains the task implementation. Listing 2-1 Creating an NSInvocationOperation object @implementation MyCustomClass - (NSOperation*)taskWithData:(id)data { NSInvocationOperation* theOp = [[NSInvocationOperation alloc] initWithTarget:self selector:@selector(myTaskMethod:) object:data]; Operation Queues Creating an NSInvocationOperation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 19return theOp; } // This is the method that does the actual work of the task. - (void)myTaskMethod:(id)data { // Perform the task. } @end Creating an NSBlockOperation Object The NSBlockOperation class is a concrete subclass of NSOperation that acts as a wrapper for one or more block objects. This class provides an object-oriented wrapper for applications that are already using operation queues and do not want to create dispatch queues as well. You can also use block operationsto take advantage of operation dependencies, KVO notifications, and other features that might not be available with dispatch queues. When you create a block operation, you typically add at least one block at initialization time; you can add more blocks as needed later. When it comes time to execute an NSBlockOperation object, the object submits all of its blocks to the default-priority, concurrent dispatch queue. The object then waits until all of the blocks finish executing. When the last block finishes executing, the operation object marks itself as finished. Thus, you can use a block operation to track a group of executing blocks, much like you would use a thread join to merge the results from multiple threads. The difference is that because the block operation itself runs on a separate thread, your application’s other threads can continue doing work while waiting for the block operation to complete. Listing 2-2 shows a simple example of how to create an NSBlockOperation object. The block itself has no parameters and no significant return result. Listing 2-2 Creating an NSBlockOperation object NSBlockOperation* theOp = [NSBlockOperation blockOperationWithBlock: ^{ NSLog(@"Beginning operation.\n"); // Do some work. }]; Operation Queues Creating an NSBlockOperation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 20After creating a block operation object, you can add more blocks to it using the addExecutionBlock: method. If you need to execute blocks serially, you must submit them directly to the desired dispatch queue. Defining a Custom Operation Object If the block operation and invocation operation objects do not quite meet the needs of your application, you can subclass NSOperation directly and add whatever behavior you need. The NSOperation class provides a generalsubclassing point for all operation objects. The class also provides a significant amount of infrastructure to handle most of the work needed for dependencies and KVO notifications. However, there may still be times when you need to supplement the existing infrastructure to ensure that your operations behave correctly. The amount of extra work you have to do depends on whether you are implementing a nonconcurrent or a concurrent operation. Defining a nonconcurrent operation is much simpler than defining a concurrent operation. For a nonconcurrent operation, all you have to do is perform your main task and respond appropriately to cancellation events; the existing class infrastructure does all of the other work for you. For a concurrent operation, you must replace some of the existing infrastructure with your custom code. The following sectionsshow you how to implement both types of object. Performing the Main Task At a minimum, every operation object should implement at least the following methods: ● A custom initialization method ● main You need a custom initialization method to put your operation object into a known state and a custom main method to perform your task. You can implement additional methods as needed, of course, such as the following: ● Custom methods that you plan to call from the implementation of your main method ● Accessor methods for setting data values and accessing the results of the operation ● Methods of the NSCoding protocol to allow you to archive and unarchive the operation object Listing 2-3 shows a starting template for a custom NSOperation subclass. (This listing does not show how to handle cancellation but does show the methods you would typically have. For information about handling cancellation, see “Responding to Cancellation Events” (page 22).) The initialization method for this class takes a single object as a data parameter and stores a reference to it inside the operation object. The main method would ostensibly work on that data object before returning the results back to your application. Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 21Listing 2-3 Defining a simple operation object @interface MyNonConcurrentOperation : NSOperation @property id (strong) myData; -(id)initWithData:(id)data; @end @implementation MyNonConcurrentOperation - (id)initWithData:(id)data { if (self = [super init]) myData = data; return self; } -(void)main { @try { // Do some work on myData and report the results. } @catch(...) { // Do not rethrow exceptions. } } @end For a detailed example of how to implement an NSOperation subclass, see NSOperationSample . Responding to Cancellation Events After an operation begins executing, it continues performing its task until it is finished or until your code explicitly cancelsthe operation. Cancellation can occur at any time, even before an operation begins executing. Although the NSOperation class provides a way for clientsto cancel an operation, recognizing the cancellation event is voluntary by necessity. If an operation were terminated outright, there might not be a way to reclaim resources that had been allocated. As a result, operation objects are expected to check for cancellation events and to exit gracefully when they occur in the middle of the operation. Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 22To support cancellation in an operation object, all you have to do is call the object’s isCancelled method periodically from your custom code and return immediately if it ever returns YES. Supporting cancellation is important regardless of the duration of your operation or whether you subclass NSOperation directly or use one of its concrete subclasses. The isCancelled method itself is very lightweight and can be called frequently without any significant performance penalty. When designing your operation objects, you should consider calling the isCancelled method at the following places in your code: ● Immediately before you perform any actual work ● At least once during each iteration of a loop, or more frequently if each iteration is relatively long ● At any points in your code where it would be relatively easy to abort the operation Listing 2-4 provides a very simple example of how to respond to cancellation events in the main method of an operation object. In this case, the isCancelled method is called each time through a while loop, allowing for a quick exit before work begins and again at regular intervals. Listing 2-4 Responding to a cancellation request - (void)main { @try { BOOL isDone = NO; while (![self isCancelled] && !isDone) { // Do some work and set isDone to YES when finished } } @catch(...) { // Do not rethrow exceptions. } } Although the preceding example contains no cleanup code, your own code should be sure to free up any resources that were allocated by your custom code. Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 23Configuring Operations for Concurrent Execution Operation objects execute in a synchronous manner by default—that is, they perform their task in the thread that calls their start method. Because operation queues provide threads for nonconcurrent operations, though, most operations still run asynchronously. However, if you plan to execute operations manually and still want them to run asynchronously, you must take the appropriate actions to ensure that they do. You do this by defining your operation object as a concurrent operation. Table 2-2 lists the methods you typically override to implement a concurrent operation. Table 2-2 Methods to override for concurrent operations Method Description (Required) All concurrent operations must override this method and replace the default behavior with their own custom implementation. To execute an operation manually, you call its start method. Therefore, your implementation of this method is the starting point for your operation and is where you set up the thread or other execution environment in which to execute your task. Your implementation must not call super at any time. start (Optional) This method is typically used to implement the task associated with the operation object. Although you could perform the task in the start method, implementing the task using this method can result in a cleaner separation of your setup and task code. main (Required) Concurrent operations are responsible for setting up their execution environment and reporting the status of that environment to outside clients. Therefore, a concurrent operation must maintain some state information to know when it is executing its task and when it has finished that task. It must then report that state using these methods. Your implementations of these methods must be safe to call from other threads simultaneously. You must also generate the appropriate KVO notifications for the expected key paths when changing the values reported by these methods. isExecuting isFinished (Required) To identify an operation as a concurrent operation, override this method and return YES. isConcurrent The rest of this section shows a sample implementation of the MyOperation class, which demonstrates the fundamental code needed to implement a concurrent operation. The MyOperation class simply executes its own main method on a separate thread that it creates. The actual work that the main method performs is irrelevant. The point of the sample is to demonstrate the infrastructure you need to provide when defining a concurrent operation. Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 24Listing 2-5 showsthe interface and part of the implementation of the MyOperation class. The implementations of the isConcurrent, isExecuting, and isFinished methods for the MyOperation class are relatively straightforward. The isConcurrent method should simply return YES to indicate that this is a concurrent operation. The isExecuting and isFinished methods simply return values stored in instance variables of the class itself. Listing 2-5 Defining a concurrent operation @interface MyOperation : NSOperation { BOOL executing; BOOL finished; } - (void)completeOperation; @end @implementation MyOperation - (id)init { self = [super init]; if (self) { executing = NO; finished = NO; } return self; } - (BOOL)isConcurrent { return YES; } - (BOOL)isExecuting { return executing; } - (BOOL)isFinished { return finished; } Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 25@end Listing 2-6 shows the start method of MyOperation. The implementation of this method is minimal so as to demonstrate the tasks you absolutely must perform. In this case, the method simply starts up a new thread and configures it to call the main method. The method also updates the executing member variable and generates KVO notifications for the isExecuting key path to reflect the change in that value. With its work done, this method then simply returns, leaving the newly detached thread to perform the actual task. Listing 2-6 The start method - (void)start { // Always check for cancellation before launching the task. if ([self isCancelled]) { // Must move the operation to the finished state if it is canceled. [self willChangeValueForKey:@"isFinished"]; finished = YES; [self didChangeValueForKey:@"isFinished"]; return; } // If the operation is not canceled, begin executing the task. [self willChangeValueForKey:@"isExecuting"]; [NSThread detachNewThreadSelector:@selector(main) toTarget:self withObject:nil]; executing = YES; [self didChangeValueForKey:@"isExecuting"]; } Listing 2-7 shows the remaining implementation for the MyOperation class. As was seen in Listing 2-6 (page 26), the main method is the entry point for a new thread. It performs the work associated with the operation object and calls the custom completeOperation method when that work is finally done. The completeOperation method then generates the needed KVO notifications for both the isExecuting and isFinished key paths to reflect the change in state of the operation. Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 26Listing 2-7 Updating an operation at completion time - (void)main { @try { // Do the main work of the operation here. [self completeOperation]; } @catch(...) { // Do not rethrow exceptions. } } - (void)completeOperation { [self willChangeValueForKey:@"isFinished"]; [self willChangeValueForKey:@"isExecuting"]; executing = NO; finished = YES; [self didChangeValueForKey:@"isExecuting"]; [self didChangeValueForKey:@"isFinished"]; } Even if an operation is canceled, you should always notify KVO observers that your operation is now finished with its work. When an operation object is dependent on the completion of other operation objects, it monitors the isFinished key path for those objects. Only when all objects report that they are finished does the dependent operation signal that it isready to run. Failing to generate a finish notification can therefore prevent the execution of other operations in your application. Maintaining KVO Compliance The NSOperation class is key-value observing (KVO) compliant for the following key paths: ● isCancelled ● isConcurrent ● isExecuting Operation Queues Defining a Custom Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 27● isFinished ● isReady ● dependencies ● queuePriority ● completionBlock If you override the start method or do any significant customization of an NSOperation object other than override main, you must ensure that your custom object remains KVO compliant for these key paths. When overriding the start method, the key paths you should be most concerned with are isExecuting and isFinished. These are the key paths most commonly affected by reimplementing that method. If you want to implement support for dependencies on something besides other operation objects, you can also override the isReady method and force it to return NO until your custom dependencies were satisfied. (If you implement custom dependencies, be sure to call super from your isReady method if you still support the default dependency managementsystem provided by the NSOperation class.) When the readinessstatus of your operation object changes, generate KVO notificationsfor the isReady key path to report those changes. Unless you override the addDependency: or removeDependency: methods, you should not need to worry about generating KVO notifications for the dependencies key path. Although you could generate KVO notifications for other key paths of NSOperation, it is unlikely you would ever need to do so. If you need to cancel an operation, you can simply call the existing cancel method to do so. Similarly, there should be little need for you to modify the queue priority information in an operation object. Finally, unless your operation is capable of changing its concurrency status dynamically, you do not need to provide KVO notifications for the isConcurrent key path. For more information on key-value observing and how to support it in your custom objects, see Key-Value Observing Programming Guide . Customizing the Execution Behavior of an Operation Object The configuration of operation objects occurs after you have created them but before you add them to a queue. The types of configurations described in this section can be applied to all operation objects, regardless of whether you subclassed NSOperation yourself or used an existing subclass. Operation Queues Customizing the Execution Behavior of an Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 28Configuring Interoperation Dependencies Dependencies are a way for you to serialize the execution of distinct operation objects. An operation that is dependent on other operations cannot begin executing until all of the operations on which it depends have finished executing. Thus, you can use dependencies to create simple one-to-one dependencies between two operation objects or to build complex object dependency graphs. To establish dependencies between two operation objects, you use the addDependency: method of NSOperation. This method creates a one-way dependency from the current operation object to the target operation you specify as a parameter. This dependency means that the current object cannot begin executing until the target object finishes executing. Dependencies are also not limited to operations in the same queue. Operation objects manage their own dependencies and so it is perfectly acceptable to create dependencies between operations and add them all to different queues. One thing that is not acceptable, however, is to create circular dependencies between operations. Doing so is a programmer error that will prevent the affected operations from ever running. When all of an operation’s dependencies have themselves finished executing, an operation object normally becomes ready to execute. (If you customize the behavior of the isReady method, the readiness of the operation is determined by the criteria you set.) If the operation object is in a queue, the queue may start executing that operation at any time. If you plan to execute the operation manually, it is up to you to call the operation’s start method. Important: You should always configure dependencies before running your operations or adding them to an operation queue. Dependencies added afterward may not prevent a given operation object from running. Dependencies rely on each operation object sending out appropriate KVO notifications whenever the status of the object changes. If you customize the behavior of your operation objects, you may need to generate appropriate KVO notifications from your custom code in order to avoid causing issues with dependencies. For more information on KVO notifications and operation objects, see “Maintaining KVO Compliance” (page 27). For additional information on configuring dependencies, see NSOperation Class Reference . Changing an Operation’s Execution Priority For operations added to a queue, execution order is determined first by the readiness of the queued operations and then by their relative priority. Readinessis determined by an operation’s dependencies on other operations, but the priority level is an attribute of the operation object itself. By default, all new operation objects have a “normal” priority, but you can increase or decrease that priority as needed by calling the object’s setQueuePriority: method. Operation Queues Customizing the Execution Behavior of an Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 29Priority levels apply only to operations in the same operation queue. If your application has multiple operation queues, each prioritizes its own operations independently of any other queues. Thus, it is still possible for low-priority operations to execute before high-priority operations in a different queue. Priority levels are not a substitute for dependencies. Priorities determine the order in which an operation queue starts executing only those operations that are currently ready. For example, if a queue contains both a high-priority and low-priority operation and both operations are ready, the queue executes the high-priority operation first. However, if the high-priority operation is not ready but the low-priority operation is, the queue executes the low-priority operation first. If you want to prevent one operation from starting until another operation has finished, you must use dependencies (as described in “Configuring Interoperation Dependencies” (page 29)) instead. Changing the Underlying Thread Priority In OS X v10.6 and later, it is possible to configure the execution priority of an operation’s underlying thread. Thread policies in the system are themselves managed by the kernel, but in general higher-priority threads are given more opportunities to run than lower-priority threads. In an operation object, you specify the thread priority as a floating-point value in the range 0.0 to 1.0, with 0.0 being the lowest priority and 1.0 being the highest priority. If you do not specify an explicit thread priority, the operation runs with the default thread priority of 0.5. To set an operation’s thread priority, you must call the setThreadPriority: method of your operation object before adding it to a queue (or executing it manually). When it comes time to execute the operation, the default start method uses the value you specified to modify the priority of the current thread. This new priority remains in effect for the duration of your operation’s main method only. All other code (including your operation’s completion block) is run with the default thread priority. If you create a concurrent operation, and therefore override the start method, you must configure the thread priority yourself. Setting Up a Completion Block In OS X v10.6 and later, an operation can execute a completion block when its main task finishes executing. You can use a completion block to perform any work that you do not consider part of the main task. For example, you might use this block to notify interested clients that the operation itself has completed. A concurrent operation object might use this block to generate its final KVO notifications. To set a completion block, use the setCompletionBlock: method of NSOperation. The block you pass to this method should have no arguments and no return value. Operation Queues Customizing the Execution Behavior of an Operation Object 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 30Tips for Implementing Operation Objects Although operation objects are fairly easy to implement, there are several things you should be aware of as you are writing your code. The following sections describe factors that you should take into account when writing the code for your operation objects. Managing Memory in Operation Objects The following sections describe key elements of good memory management in an operation object. For general information about memory management in Objective-C programs, see Advanced Memory Management Programming Guide . Avoid Per-Thread Storage Although most operations execute on a thread, in the case of nonconcurrent operations, that thread is usually provided by an operation queue. If an operation queue provides a thread for you, you should consider that thread to be owned by the queue and not to be touched by your operation. Specifically, you should never associate any data with a thread that you do not create yourself or manage. The threads managed by an operation queue come and go depending on the needs of the system and your application. Therefore, passing data between operations using per-thread storage is unreliable and likely to fail. In the case of operation objects, there should be no reason for you to use per-thread storage in any case. When you initialize an operation object, you should provide the object with everything it needsto do itsjob. Therefore, the operation object itself provides the contextual storage you need. All incoming and outgoing data should be stored there until it can be integrated back into your application or is no longer required. Keep References to Your Operation Object As Needed Just because operation objects run asynchronously, you should not assume that you can create them and forget about them. They are still just objects and it is up to you to manage any references to them that your code needs. This is especially important if you need to retrieve result data from an operation after it is finished. The reason you should always keep your own references to operations is that you may not get the chance to ask a queue for the object later. Queues make every effort to dispatch and execute operations as quickly as possible. In many cases, queues start executing operations almost immediately after they are added. By the time your own code goes back to the queue to get a reference to the operation, that operation could already be finished and removed from the queue. Operation Queues Tips for Implementing Operation Objects 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 31Handling Errors and Exceptions Because operations are essentially discrete entities inside your application, they are responsible for handling any errors or exceptions that arise. In OS X v10.6 and later, the default start method provided by the NSOperation class does not catch exceptions. (In OS X v10.5, the start method does catch and suppress exceptions.) Your own code should always catch and suppress exceptions directly. It should also check error codes and notify the appropriate parts of your application as needed. And if you replace the start method, you must similarly catch any exceptions in your custom implementation to prevent them from leaving the scope of the underlying thread. Among the types of error situations you should be prepared to handle are the following: ● Check and handle UNIX errno-style error codes. ● Check explicit error codes returned by methods and functions. ● Catch exceptions thrown by your own code or by other system frameworks. ● Catch exceptions thrown by the NSOperation class itself, which throws exceptions in the following situations: ● When the operation is not ready to execute but its start method is called ● When the operation is executing or finished (possibly because it was canceled) and its start method is called again ● When you try to add a completion block to an operation that is already executing or finished ● When you try to retrieve the result of an NSInvocationOperation object that was canceled If your custom code does encounter an exception or error, you should take whatever steps are needed to propagate that error to the rest of your application. The NSOperation class does not provide explicit methods for passing along error result codes or exceptionsto other parts of your application. Therefore, ifsuch information is important to your application, you must provide the necessary code. Determining an Appropriate Scope for Operation Objects Although it is possible to add an arbitrarily large number of operations to an operation queue, doing so is often impractical. Like any object, instances of the NSOperation class consume memory and have real costs associated with their execution. If each of your operation objects does only a small amount of work, and you create tens of thousands of them, you may find that you are spending more time dispatching operations than doing real work. And if your application is already memory-constrained, you might find that just having tens of thousands of operation objects in memory might degrade performance even further. Operation Queues Determining an Appropriate Scope for Operation Objects 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 32The key to using operations efficiently isto find an appropriate balance between the amount of work you need to do and to keep the computer busy. Try to make sure that your operations do a reasonable amount of work. For example, if your application creates 100 operation objectsto perform the same task on 100 different values, consider creating 10 operation objects to process 10 values each instead. You should also avoid adding large numbers of operationsto a queue all at once, or avoid continuously adding operation objects to a queue faster than they can be processed. Rather than flood a queue with operation objects, create those objects in batches. As one batch finishes executing, use a completion block to tell your application to create a new batch. When you have a lot of work to do, you want to keep the queues filled with enough operations so that the computer stays busy, but you do not want to create so many operations at once that your application runs out of memory. Of course, the number of operation objects you create, and the amount of work you perform in each, is variable and entirely dependent on your application. You should always use tools such as Instruments and Shark to help you find an appropriate balance between efficiency and speed. For an overview of Instruments, Shark, and the other performance tools you can use to gather metrics for your code, see Performance Overview. Executing Operations Ultimately, your application needs to execute operations in order to do the associated work. In this section, you learn several waysto execute operations as well as how you can manipulate the execution of your operations at runtime. Adding Operations to an Operation Queue By far, the easiest way to execute operations is to use an operation queue, which is an instance of the NSOperationQueue class. Your application is responsible for creating and maintaining any operation queues it intends to use. An application can have any number of queues, but there are practical limits to how many operations may be executing at a given point in time. Operation queues work with the system to restrict the number of concurrent operationsto a value that is appropriate for the available cores and system load. Therefore, creating additional queues does not mean that you can execute additional operations. To create a queue, you allocate it in your application as you would any other object: NSOperationQueue* aQueue = [[NSOperationQueue alloc] init]; To add operations to a queue, you use the addOperation: method. In OS X v10.6 and later, you can add groups of operations using the addOperations:waitUntilFinished: method, or you can add block objects directly to a queue (without a corresponding operation object) using the addOperationWithBlock: method. Each of these methods queues up an operation (or operations) and notifies the queue that it should begin Operation Queues Executing Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 33processing them. In most cases, operations are executed shortly after being added to a queue, but the operation queue may delay execution of queued operations for any of several reasons. Specifically, execution may be delayed if queued operations are dependent on other operations that have not yet completed. Execution may also be delayed if the operation queue itself is suspended or is already executing its maximum number of concurrent operations. The following examples show the basic syntax for adding operations to a queue. [aQueue addOperation:anOp]; // Add a single operation [aQueue addOperations:anArrayOfOps waitUntilFinished:NO]; // Add multiple operations [aQueue addOperationWithBlock:^{ /* Do something. */ }]; Important: Never modify an operation object after it has been added to a queue. While waiting in a queue, the operation could start executing at any time, so changing its dependencies or the data it contains could have adverse effects. If you want to know the status of an operation, you can use the methods of the NSOperation class to determine if the operation is running, waiting to run, or already finished. Although the NSOperationQueue class is designed for the concurrent execution of operations, it is possible to force a single queue to run only one operation at a time. The setMaxConcurrentOperationCount: method lets you configure the maximum number of concurrent operations for an operation queue object. Passing a value of 1 to this method causes the queue to execute only one operation at a time. Although only one operation at a time may execute, the order of execution isstill based on other factors,such asthe readiness of each operation and its assigned priority. Thus, a serialized operation queue does not offer quite the same behavior as a serial dispatch queue in Grand Central Dispatch does. If the execution order of your operation objectsisimportant to you, you should use dependenciesto establish that order before adding your operations to a queue. For information about configuring dependencies, see “Configuring Interoperation Dependencies” (page 29). For information about using operation queues, see NSOperationQueue Class Reference . For more information about serial dispatch queues, see “Creating Serial Dispatch Queues” (page 44). Executing Operations Manually Although operation queues are the most convenient way to run operation objects, it is also possible to execute operations without a queue. If you choose to execute operations manually, however, there are some precautions you should take in your code. In particular, the operation must be ready to run and you must always start it using its start method. Operation Queues Executing Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 34An operation is not considered able to run until its isReady method returns YES. The isReady method is integrated into the dependency management system of the NSOperation class to provide the status of the operation’s dependencies. Only when its dependencies are cleared is an operation free to begin executing. When executing an operation manually, you should always use the start method to begin execution. You use this method, instead of main or some other method, because the start method performs several safety checks before it actually runs your custom code. In particular, the default start method generates the KVO notificationsthat operationsrequire to processtheir dependencies correctly. This method also correctly avoids executing your operation if it has already been canceled and throws an exception if your operation is not actually ready to run. If your application defines concurrent operation objects, you should also consider calling the isConcurrent method of operations prior to launching them. In cases where this method returns NO, your local code can decide whether to execute the operation synchronously in the current thread or create a separate thread first. However, implementing this kind of checking is entirely up to you. Listing 2-8 shows a simple example of the kind of checks you should perform before executing operations manually. If the method returns NO, you could schedule a timer and call the method again later. You would then keep rescheduling the timer until the method returns YES, which could occur because the operation was canceled. Listing 2-8 Executing an operation object manually - (BOOL)performOperation:(NSOperation*)anOp { BOOL ranIt = NO; if ([anOp isReady] && ![anOp isCancelled]) { if (![anOp isConcurrent]) [anOp start]; else [NSThread detachNewThreadSelector:@selector(start) toTarget:anOp withObject:nil]; ranIt = YES; } else if ([anOp isCancelled]) { // If it was canceled before it was started, Operation Queues Executing Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 35// move the operation to the finished state. [self willChangeValueForKey:@"isFinished"]; [self willChangeValueForKey:@"isExecuting"]; executing = NO; finished = YES; [self didChangeValueForKey:@"isExecuting"]; [self didChangeValueForKey:@"isFinished"]; // Set ranIt to YES to prevent the operation from // being passed to this method again in the future. ranIt = YES; } return ranIt; } Canceling Operations Once added to an operation queue, an operation object is effectively owned by the queue and cannot be removed. The only way to dequeue an operation is to cancel it. You can cancel a single individual operation object by calling its cancel method or you can cancel all of the operation objects in a queue by calling the cancelAllOperations method of the queue object. You should cancel operations only when you are sure you no longer need them. Issuing a cancel command puts the operation object into the “canceled” state, which prevents it from ever being run. Because a canceled operation is still considered to be “finished”, objects that are dependent on it receive the appropriate KVO notifications to clear that dependency. Thus, it is more common to cancel all queued operations in response to some significant event, like the application quitting or the user specifically requesting the cancellation, rather than cancel operations selectively. Waiting for Operations to Finish For the best performance, you should design your operations to be as asynchronous as possible, leaving your application free to do additional work while the operation executes. If the code that creates an operation also processes the results of that operation, you can use the waitUntilFinished method of NSOperation to block that code until the operation finishes. In general, though, it is best to avoid calling this method if you can help it. Blocking the current thread may be a convenient solution, but it does introduce more serialization into your code and limits the overall amount of concurrency. Operation Queues Executing Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 36Important: You should never wait for an operation from your application’s main thread. You should only do so from a secondary thread or from another operation. Blocking your main thread prevents your application from responding to user events and could make your application appear unresponsive. In addition to waiting for a single operation to finish, you can also wait on all of the operations in a queue by calling the waitUntilAllOperationsAreFinished method of NSOperationQueue. When waiting for an entire queue to finish, be aware that your application’s other threads can still add operations to the queue, thus prolonging the wait. Suspending and Resuming Queues If you want to issue a temporary halt to the execution of operations, you can suspend the corresponding operation queue using the setSuspended: method. Suspending a queue does not cause already executing operations to pause in the middle of their tasks. It simply prevents new operations from being scheduled for execution. You might suspend a queue in response to a user request to pause any ongoing work, because the expectation is that the user might eventually want to resume that work. Operation Queues Executing Operations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 37Grand Central Dispatch (GCD) dispatch queues are a powerful tool for performing tasks. Dispatch queues let you execute arbitrary blocks of code either asynchronously or synchronously with respect to the caller. You can use dispatch queues to perform nearly all of the tasks that you used to perform on separate threads. The advantage of dispatch queues is that they are simpler to use and much more efficient at executing those tasks than the corresponding threaded code. This chapter provides an introduction to dispatch queues, along with information about how to use them to execute general tasks in your application. If you want to replace existing threaded code with dispatch queues, you can find some additional tips for how to do that in “Migrating Away from Threads” (page 74). About Dispatch Queues Dispatch queues are an easy way to perform tasks asynchronously and concurrently in your application. A task is simply some work that your application needs to perform. For example, you could define a task to perform some calculations, create or modify a data structure, process some data read from a file, or any number of things. You define tasks by placing the corresponding code inside either a function or a block object and adding it to a dispatch queue. A dispatch queue is an object-like structure that manages the tasks you submit to it. All dispatch queues are first-in, first-out data structures. Thus, the tasks you add to a queue are always started in the same order that they were added. GCD provides some dispatch queues for you automatically, but others you can create for specific purposes. Table 3-1 lists the types of dispatch queues available to your application and how you use them. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 38 Dispatch QueuesTable 3-1 Types of dispatch queues Type Description Serial queues (also known as private dispatch queues) execute one task at a time in the order in which they are added to the queue. The currently executing task runs on a distinct thread (which can vary from task to task) that is managed by the dispatch queue. Serial queues are often used to synchronize access to a specific resource. You can create as many serial queues as you need, and each queue operates concurrently with respect to all other queues. In other words, if you create four serial queues, each queue executes only one task at a time but up to four tasks could still execute concurrently, one from each queue. For information on how to create serial queues, see “Creating Serial Dispatch Queues” (page 44). Serial Concurrent queues (also known as a type of global dispatch queue) execute one or more tasks concurrently, but tasks are stillstarted in the order in which they were added to the queue. The currently executing tasks run on distinct threads that are managed by the dispatch queue. The exact number of tasks executing at any given point is variable and depends on system conditions. You cannot create concurrent dispatch queues yourself. Instead, there are three global concurrent queues for your application to use. For more information on how to get the global concurrent queues, see “Getting the Global Concurrent Dispatch Queues” (page 43). Concurrent The main dispatch queue is a globally available serial queue that executes tasks on the application’s main thread. This queue works with the application’s run loop (if one is present) to interleave the execution of queued tasks with the execution of other event sources attached to the run loop. Because it runs on your application’s main thread, the main queue is often used as a key synchronization point for an application. Although you do not need to create the main dispatch queue, you do need to make sure your application drains it appropriately. For more information on how this queue is managed, see “Performing Tasks on the Main Thread” (page 51). Main dispatch queue When it comes to adding concurrency to an application, dispatch queues provide several advantages over threads. The most direct advantage is the simplicity of the work-queue programming model. With threads, you have to write code both for the work you want to perform and for the creation and management of the threads themselves. Dispatch queues let you focus on the work you actually want to perform without having to worry about the thread creation and management. Instead, the system handles all of the thread creation and management for you. The advantage is that the system is able to manage threads much more efficiently than any single application ever could. The system can scale the number of threads dynamically based on the available resources and current system conditions. In addition, the system is usually able to start running your task more quickly than you could if you created the thread yourself. Dispatch Queues About Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 39Although you might think rewriting your code for dispatch queues would be difficult, it is often easier to write code for dispatch queues than it is to write code for threads. The key to writing your code is to design tasks that are self-contained and able to run asynchronously. (This is actually true for both threads and dispatch queues.) However, where dispatch queues have an advantage is in predictability. If you have two tasks that access the same shared resource but run on different threads, either thread could modify the resource first and you would need to use a lock to ensure that both tasks did not modify that resource at the same time. With dispatch queues, you could add both tasksto a serial dispatch queue to ensure that only one task modified the resource at any given time. This type of queue-based synchronization is more efficient than locks because locks alwaysrequire an expensive kernel trap in both the contested and uncontested cases, whereas a dispatch queue works primarily in your application’s process space and only calls down to the kernel when absolutely necessary. Although you would be right to point out that two tasks running in a serial queue do not run concurrently, you have to remember that if two threads take a lock at the same time, any concurrency offered by the threads is lost or significantly reduced. More importantly, the threaded model requires the creation of two threads, which take up both kernel and user-space memory. Dispatch queues do not pay the same memory penalty for their threads, and the threads they do use are kept busy and not blocked. Some other key points to remember about dispatch queues include the following: ● Dispatch queues execute their tasks concurrently with respect to other dispatch queues. The serialization of tasks is limited to the tasks in a single dispatch queue. ● The system determines the total number of tasks executing at any one time. Thus, an application with 100 tasks in 100 different queues may not execute all of those tasks concurrently (unless it has 100 or more effective cores). ● The system takes queue priority levelsinto account when choosing which new tasksto start. For information about how to set the priority of a serial queue, see “Providing a Clean Up Function For a Queue” (page 46). ● Tasks in a queue must be ready to execute at the time they are added to the queue. (If you have used Cocoa operation objects before, notice that this behavior differs from the model operations use.) ● Private dispatch queues are reference-counted objects. In addition to retaining the queue in your own code, be aware that dispatch sources can also be attached to a queue and also increment its retain count. Thus, you must make sure that all dispatch sources are canceled and all retain calls are balanced with an appropriate release call. For more information about retaining and releasing queues, see “Memory Management for Dispatch Queues” (page 45). For more information about dispatch sources, see “About Dispatch Sources” (page 56). For more information about interfaces you use to manipulate dispatch queues, see Grand Central Dispatch (GCD) Reference . Dispatch Queues About Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 40Queue-Related Technologies In addition to dispatch queues, Grand Central Dispatch provides several technologies that use queues to help manage your code. Table 3-2 lists these technologies and provides links to where you can find out more information about them. Table 3-2 Technologies that use dispatch queues Technology Description A dispatch group is a way to monitor a set of block objects for completion. (You can monitor the blocks synchronously or asynchronously depending on your needs.) Groups provide a useful synchronization mechanism for code that depends on the completion of other tasks. For more information about using groups, see “Waiting on Groups of Queued Tasks” (page 53). Dispatch groups A dispatch semaphore is similar to a traditional semaphore but is generally more efficient. Dispatch semaphores call down to the kernel only when the calling thread needs to be blocked because the semaphore is unavailable. If the semaphore is available, no kernel call is made. For an example of how to use dispatch semaphores, see “Using Dispatch Semaphores to Regulate the Use of Finite Resources” (page 52). Dispatch semaphores A dispatch source generates notifications in response to specific types of system events. You can use dispatch sourcesto monitor eventssuch as process notifications, signals, and descriptor events among others. When an event occurs, the dispatch source submits your task code asynchronously to the specified dispatch queue for processing. For more information about creating and using dispatch sources, see “Dispatch Sources” (page 56). Dispatch sources Implementing Tasks Using Blocks Block objects are a C-based language feature that you can use in your C, Objective-C, and C++ code. Blocks make it easy to define a self-contained unit of work. Although they might seem akin to function pointers, a block is actually represented by an underlying data structure that resembles an object and is created and managed for you by the compiler. The compiler packages up the code you provide (along with any related data) and encapsulates it in a form that can live in the heap and be passed around your application. One of the key advantages of blocks is their ability to use variables from outside their own lexical scope. When you define a block inside a function or method, the block acts as a traditional code block would in some ways. For example, a block can read the values of variables defined in the parent scope. Variables accessed by the block are copied to the block data structure on the heap so that the block can access them later. When blocks Dispatch Queues Queue-Related Technologies 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 41are added to a dispatch queue, these values must typically be left in a read-only format. However, blocks that are executed synchronously can also use variables that have the __block keyword prepended to return data back to the parent’s calling scope. You declare blocks inline with your code using a syntax that is similar to the syntax used for function pointers. The main difference between a block and a function pointer is that the block name is preceded with a caret (^) instead of an asterisk (*). Like a function pointer, you can pass arguments to a block and receive a return value from it. Listing 3-1 shows you how to declare and execute blockssynchronously in your code. The variable aBlock is declared to be a block that takes a single integer parameter and returns no value. An actual block matching that prototype is then assigned to aBlock and declared inline. The last line executes the block immediately, printing the specified integers to standard out. Listing 3-1 A simple block example int x = 123; int y = 456; // Block declaration and assignment void (^aBlock)(int) = ^(int z) { printf("%d %d %d\n", x, y, z); }; // Execute the block aBlock(789); // prints: 123 456 789 The following is a summary of some of the key guidelines you should consider when designing your blocks: ● For blocks that you plan to perform asynchronously using a dispatch queue, it is safe to capture scalar variables from the parent function or method and use them in the block. However, you should not try to capture large structures or other pointer-based variables that are allocated and deleted by the calling context. By the time your block is executed, the memory referenced by that pointer may be gone. Of course, it issafe to allocate memory (or an object) yourself and explicitly hand off ownership of that memory to the block. ● Dispatch queues copy blocks that are added to them, and they release blocks when they finish executing. In other words, you do not need to explicitly copy blocks before adding them to a queue. Dispatch Queues Implementing Tasks Using Blocks 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 42● Although queues are more efficient than raw threads at executing small tasks, there is still overhead to creating blocks and executing them on a queue. If a block doestoo little work, it may be cheaper to execute it inline than dispatch it to a queue. The way to tell if a block is doing too little work is to gather metrics for each path using the performance tools and compare them. ● Do not cache data relative to the underlying thread and expect that data to be accessible from a different block. If tasks in the same queue need to share data, use the context pointer of the dispatch queue to store the data instead. For more information on how to access the context data of a dispatch queue, see “Storing Custom Context Information with a Queue” (page 46). ● If your block creates more than a few Objective-C objects, you might want to enclose parts of your block’s code in an @autorelease block to handle the memory management for those objects. Although GCD dispatch queues have their own autorelease pools, they make no guarantees as to when those pools are drained. If your application is memory constrained, creating your own autorelease pool allows you to free up the memory for autoreleased objects at more regular intervals. For more information about blocks, including how to declare and use them, see Blocks Programming Topics. For information about how you add blocks to a dispatch queue, see “Adding Tasks to a Queue” (page 47). Creating and Managing Dispatch Queues Before you add your tasks to a queue, you have to decide what type of queue to use and how you intend to use it. Dispatch queues can execute tasks either serially or concurrently. In addition, if you have a specific use for the queue in mind, you can configure the queue attributes accordingly. The following sections show you how to create dispatch queues and configure them for use. Getting the Global Concurrent Dispatch Queues A concurrent dispatch queue is useful when you have multiple tasks that can run in parallel. A concurrent queue is still a queue in that it dequeues tasks in a first-in, first-out order; however, a concurrent queue may dequeue additional tasks before any previoustasksfinish. The actual number of tasks executed by a concurrent queue at any given moment is variable and can change dynamically as conditions in your application change. Many factors affect the number of tasks executed by the concurrent queues, including the number of available cores, the amount of work being done by other processes, and the number and priority of tasks in other serial dispatch queues. The system provides each application with three concurrent dispatch queues. These queues are global to the application and are differentiated only by their priority level. Because they are global, you do not create them explicitly. Instead, you ask for one of the queues using the dispatch_get_global_queue function, asshown in the following example: Dispatch Queues Creating and Managing Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 43dispatch_queue_t aQueue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); In addition to getting the default concurrent queue, you can also get queues with high- and low-priority levels by passing in the DISPATCH_QUEUE_PRIORITY_HIGH and DISPATCH_QUEUE_PRIORITY_LOW constants to the function instead. As you might expect, tasks in the high-priority concurrent queue execute before those in the default and low-priority queues. Similarly, tasks in the default queue execute before those in the low-priority queue. Note: The second argument to the dispatch_get_global_queue function is reserved for future expansion. For now, you should always pass 0 for this argument. Although dispatch queues are reference-counted objects, you do not need to retain and release the global concurrent queues. Because they are global to your application, retain and release calls for these queues are ignored. Therefore, you do not need to store references to these queues. You can just call the dispatch_get_global_queue function whenever you need a reference to one of them. Creating Serial Dispatch Queues Serial queues are useful when you want your tasks to execute in a specific order. A serial queue executes only one task at a time and always pulls tasks from the head of the queue. You might use a serial queue instead of a lock to protect a shared resource or mutable data structure. Unlike a lock, a serial queue ensures that tasks are executed in a predictable order. And as long as you submit your tasks to a serial queue asynchronously, the queue can never deadlock. Unlike concurrent queues, which are created for you, you must explicitly create and manage any serial queues you want to use. You can create any number of serial queues for your application but should avoid creating large numbers of serial queues solely as a means to execute as many tasks simultaneously as you can. If you want to execute large numbers of tasks concurrently, submit them to one of the global concurrent queues. When creating serial queues, try to identify a purpose for each queue, such as protecting a resource or synchronizing some key behavior of your application. Listing 3-2 shows the steps required to create a custom serial queue. The dispatch_queue_create function takes two parameters: the queue name and a set of queue attributes. The debugger and performance tools display the queue name to help you track how your tasks are being executed. The queue attributes are reserved for future use and should be NULL. Dispatch Queues Creating and Managing Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 44Listing 3-2 Creating a new serial queue dispatch_queue_t queue; queue = dispatch_queue_create("com.example.MyQueue", NULL); In addition to any custom queues you create, the system automatically creates a serial queue and binds it to your application’s main thread. For more information about getting the queue for the main thread,see “Getting Common Queues at Runtime” (page 45). Getting Common Queues at Runtime Grand Central Dispatch provides functions to let you access several common dispatch queues from your application: ● Use the dispatch_get_current_queue function for debugging purposes or to test the identity of the current queue. Calling this function from inside a block object returns the queue to which the block was submitted (and on which it is now presumably running). Calling this function from outside of a block returns the default concurrent queue for your application. ● Use the dispatch_get_main_queue function to get the serial dispatch queue associated with your application’s main thread. This queue is created automatically for Cocoa applications and for applications that either call the dispatch_main function or configure a run loop (using either the CFRunLoopRef type or an NSRunLoop object) on the main thread. ● Use the dispatch_get_global_queue function to get any of the shared concurrent queues. For more information, see “Getting the Global Concurrent Dispatch Queues” (page 43). Memory Management for Dispatch Queues Dispatch queues and other dispatch objects are reference-counted data types. When you create a serial dispatch queue, it has an initial reference count of 1. You can use the dispatch_retain and dispatch_release functions to increment and decrement that reference count as needed. When the reference count of a queue reaches zero, the system asynchronously deallocates the queue. It is important to retain and release dispatch objects, such as queues, to ensure that they remain in memory while they are being used. As with memory-managed Cocoa objects, the general rule is that if you plan to use a queue that was passed to your code, you should retain the queue before you use it and release it when you no longer need it. This basic pattern ensures that the queue remains in memory for as long as you are using it. Dispatch Queues Creating and Managing Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 45Note: You do not need to retain or release any of the global dispatch queues, including the concurrent dispatch queues or the main dispatch queue. Any attemptsto retain or release the queues are ignored. Even if you implement a garbage-collected application, you must still retain and release your dispatch queues and other dispatch objects. Grand Central Dispatch does notsupport the garbage collection model for reclaiming memory. Storing Custom Context Information with a Queue All dispatch objects (including dispatch queues) allow you to associate custom context data with the object. To set and get this data on a given object, you use the dispatch_set_context and dispatch_get_context functions. The system does not use your custom data in any way, and it is up to you to both allocate and deallocate the data at the appropriate times. For queues, you can use context data to store a pointer to an Objective-C object or other data structure that helps identify the queue or its intended usage to your code. You can use the queue’s finalizer function to deallocate (or disassociate) your context data from the queue before it is deallocated. An example of how to write a finalizer function that clears a queue’s context data is shown in Listing 3-3 (page 46). Providing a Clean Up Function For a Queue After you create a serial dispatch queue, you can attach a finalizer function to perform any custom clean up when the queue is deallocated. Dispatch queues are reference counted objects and you can use the dispatch_set_finalizer_f function to specify a function to be executed when the reference count of your queue reaches zero. You use this function to clean up the context data associated with a queue and the function is called only if the context pointer is not NULL. Listing 3-3 shows a custom finalizer function and a function that creates a queue and installs that finalizer. The queue uses the finalizer function to release the data stored in the queue’s context pointer. (The myInitializeDataContextFunction and myCleanUpDataContextFunction functionsreferenced from the code are custom functions that you would provide to initialize and clean up the contents of the data structure itself.) The context pointer passed to the finalizer function contains the data object associated with the queue. Listing 3-3 Installing a queue clean up function void myFinalizerFunction(void *context) { Dispatch Queues Creating and Managing Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 46MyDataContext* theData = (MyDataContext*)context; // Clean up the contents of the structure myCleanUpDataContextFunction(theData); // Now release the structure itself. free(theData); } dispatch_queue_t createMyQueue() { MyDataContext* data = (MyDataContext*) malloc(sizeof(MyDataContext)); myInitializeDataContextFunction(data); // Create the queue and set the context data. dispatch_queue_t serialQueue = dispatch_queue_create("com.example.CriticalTaskQueue", NULL); if (serialQueue) { dispatch_set_context(serialQueue, data); dispatch_set_finalizer_f(serialQueue, &myFinalizerFunction); } return serialQueue; } Adding Tasks to a Queue To execute a task, you must dispatch it to an appropriate dispatch queue. You can dispatch taskssynchronously or asynchronously, and you can dispatch them singly or in groups. Once in a queue, the queue becomes responsible for executing your tasks as soon as possible, given its constraints and the existing tasks already in the queue. This section shows you some of the techniques for dispatching tasks to a queue and describes the advantages of each. Dispatch Queues Adding Tasks to a Queue 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 47Adding a Single Task to a Queue There are two ways to add a task to a queue: asynchronously or synchronously. When possible, asynchronous execution using the dispatch_async and dispatch_async_f functions is preferred over the synchronous alternative. When you add a block object or function to a queue, there is no way to know when that code will execute. As a result, adding blocks or functions asynchronously lets you schedule the execution of the code and continue to do other work from the calling thread. This is especially important if you are scheduling the task from your application’s main thread—perhaps in response to some user event. Although you should add tasks asynchronously whenever possible, there may still be times when you need to add a task synchronously to prevent race conditions or other synchronization errors. In these instances, you can use the dispatch_sync and dispatch_sync_f functions to add the task to the queue. These functions block the current thread of execution until the specified task finishes executing. Important: You should never call the dispatch_sync or dispatch_sync_f function from a task that is executing in the same queue that you are planning to pass to the function. This is particularly important for serial queues, which are guaranteed to deadlock, but should also be avoided for concurrent queues. The following example shows how to use the block-based variants for dispatching tasks asynchronously and synchronously: dispatch_queue_t myCustomQueue; myCustomQueue = dispatch_queue_create("com.example.MyCustomQueue", NULL); dispatch_async(myCustomQueue, ^{ printf("Do some work here.\n"); }); printf("The first block may or may not have run.\n"); dispatch_sync(myCustomQueue, ^{ printf("Do some more work here.\n"); }); printf("Both blocks have completed.\n"); Dispatch Queues Adding Tasks to a Queue 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 48Performing a Completion Block When a Task Is Done By their nature, tasks dispatched to a queue run independently of the code that created them. However, when the task is done, your application might still want to be notified of that fact so that it can incorporate the results. With traditional asynchronous programming, you might do this using a callback mechanism, but with dispatch queues you can use a completion block. A completion block is just another piece of code that you dispatch to a queue at the end of your original task. The calling code typically provides the completion block as a parameter when it starts the task. All the task code has to do is submit the specified block or function to the specified queue when it finishes its work. Listing 3-4 shows an averaging function implemented using blocks. The last two parameters to the averaging function allow the caller to specify a queue and block to use when reporting the results. After the averaging function computes its value, it passes the results to the specified block and dispatches it to the queue. To prevent the queue from being released prematurely, it is critical to retain that queue initially and release it once the completion block has been dispatched. Listing 3-4 Executing a completion callback after a task void average_async(int *data, size_t len, dispatch_queue_t queue, void (^block)(int)) { // Retain the queue provided by the user to make // sure it does not disappear before the completion // block can be called. dispatch_retain(queue); // Do the work on the default concurrent queue and then // call the user-provided block with the results. dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ int avg = average(data, len); dispatch_async(queue, ^{ block(avg);}); // Release the user-provided queue when done dispatch_release(queue); }); } Dispatch Queues Adding Tasks to a Queue 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 49Performing Loop Iterations Concurrently One place where concurrent dispatch queues might improve performance is in places where you have a loop that performs a fixed number of iterations. For example, suppose you have a for loop that does some work through each loop iteration: for (i = 0; i < count; i++) { printf("%u\n",i); } If the work performed during each iteration is distinct from the work performed during all other iterations, and the order in which each successive loop finishes is unimportant, you can replace the loop with a call to the dispatch_apply or dispatch_apply_f function. These functionssubmit the specified block or function to a queue once for each loop iteration. When dispatched to a concurrent queue, it is therefore possible to perform multiple loop iterations at the same time. You can specify either a serial queue or a concurrent queue when calling dispatch_apply or dispatch_apply_f. Passing in a concurrent queue allows you to perform multiple loop iterations simultaneously and isthe most common way to use these functions. Although using a serial queue is permissible and does the right thing for your code, using such a queue has no real performance advantages over leaving the loop in place. Important: Like a regular for loop, the dispatch_apply and dispatch_apply_f functions do not return until all loop iterations are complete. You should therefore be careful when calling them from code that is already executing from the context of a queue. If the queue you pass as a parameter to the function is a serial queue and is the same one executing the current code, calling these functions will deadlock the queue. Because they effectively block the current thread, you should also be careful when calling these functions from your main thread, where they could prevent your event handling loop from responding to events in a timely manner. If your loop code requires a noticeable amount of processing time, you might want to call these functions from a different thread. Listing 3-5 shows how to replace the preceding for loop with the dispatch_apply syntax. The block you pass in to the dispatch_apply function must contain a single parameter that identifies the current loop iteration. When the block is executed, the value of this parameter is 0 for the first iteration, 1 for the second, and so on. The value of the parameter for the last iteration is count - 1, where count is the total number of iterations. Dispatch Queues Adding Tasks to a Queue 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 50Listing 3-5 Performing the iterations of a for loop concurrently dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_apply(count, queue, ^(size_t i) { printf("%u\n",i); }); You should make sure that your task code does a reasonable amount of work through each iteration. As with any block or function you dispatch to a queue, there is overhead to scheduling that code for execution. If each iteration of your loop performs only a small amount of work, the overhead ofscheduling the code may outweigh the performance benefits you might achieve from dispatching it to a queue. If you find this is true during your testing, you can use striding to increase the amount of work performed during each loop iteration. With striding, you group together multiple iterations of your original loop into a single block and reduce the iteration count proportionately. For example, if you perform 100 iterations initially but decide to use a stride of 4, you now perform 4 loop iterations from each block and your iteration count is 25. For an example of how to implement striding, see “Improving on Loop Code” (page 77). Performing Tasks on the Main Thread Grand Central Dispatch provides a special dispatch queue that you can use to execute tasks on your application’s main thread. This queue is provided automatically for all applications and is drained automatically by any application that sets up a run loop (managed by either a CFRunLoopRef type or NSRunLoop object) on its main thread. If you are not creating a Cocoa application and do not want to set up a run loop explicitly, you must call the dispatch_main function to drain the main dispatch queue explicitly. You can still add tasks to the queue, but if you do not call this function those tasks are never executed. You can get the dispatch queue for your application’s main thread by calling the dispatch_get_main_queue function. Tasks added to this queue are performed serially on the main thread itself. Therefore, you can use this queue as a synchronization point for work being done in other parts of your application. Using Objective-C Objects in Your Tasks GCD provides built-in support for Cocoa memory management techniques so you may freely use Objective-C objects in the blocks you submit to dispatch queues. Each dispatch queue maintains its own autorelease pool to ensure that autoreleased objects are released at some point; queues make no guarantee about when they actually release those objects. Dispatch Queues Adding Tasks to a Queue 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 51If your application is memory constrained and your block creates more than a few autoreleased objects, creating your own autorelease pool is the only way to ensure that your objects are released in a timely manner. If your block creates hundreds of objects, you might want to create more than one autorelease pool or drain your pool at regular intervals. For more information about autorelease pools and Objective-C memory management, see Advanced Memory Management Programming Guide . Suspending and Resuming Queues You can prevent a queue from executing block objects temporarily by suspending it. You suspend a dispatch queue using the dispatch_suspend function and resume it using the dispatch_resume function. Calling dispatch_suspend increments the queue’s suspension reference count, and calling dispatch_resume decrementsthe reference count. While the reference count is greater than zero, the queue remainssuspended. Therefore, you must balance allsuspend calls with a matching resume call in order to resume processing blocks. Important: Suspend and resume calls are asynchronous and take effect only between the execution of blocks. Suspending a queue does not cause an already executing block to stop. Using Dispatch Semaphoresto Regulate the Use of Finite Resources If the tasks you are submitting to dispatch queues access some finite resource, you may want to use a dispatch semaphore to regulate the number of tasks simultaneously accessing that resource. A dispatch semaphore works like a regular semaphore with one exception. When resources are available, it takes less time to acquire a dispatch semaphore than it does to acquire a traditional system semaphore. This is because Grand Central Dispatch does not call down into the kernel for this particular case. The only time it calls down into the kernel is when the resource is not available and the system needsto park your thread until the semaphore issignaled. The semantics for using a dispatch semaphore are as follows: 1. When you create the semaphore (using the dispatch_semaphore_create function), you can specify a positive integer indicating the number of resources available. 2. In each task, call dispatch_semaphore_wait to wait on the semaphore. 3. When the wait call returns, acquire the resource and do your work. 4. When you are done with the resource, release it and signal the semaphore by calling the dispatch_semaphore_signal function. Dispatch Queues Suspending and Resuming Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 52For an example of how these steps work, consider the use of file descriptors on the system. Each application is given a limited number of file descriptors to use. If you have a task that processes large numbers of files, you do not want to open so many files at one time that you run out of file descriptors. Instead, you can use a semaphore to limit the number of file descriptors in use at any one time by your file-processing code. The basic pieces of code you would incorporate into your tasks is as follows: // Create the semaphore, specifying the initial pool size dispatch_semaphore_t fd_sema = dispatch_semaphore_create(getdtablesize() / 2); // Wait for a free file descriptor dispatch_semaphore_wait(fd_sema, DISPATCH_TIME_FOREVER); fd = open("/etc/services", O_RDONLY); // Release the file descriptor when done close(fd); dispatch_semaphore_signal(fd_sema); When you create the semaphore, you specify the number of available resources. This value becomes the initial count variable for the semaphore. Each time you wait on the semaphore, the dispatch_semaphore_wait function decrements that count variable by 1. If the resulting value is negative, the function tells the kernel to block your thread. On the other end, the dispatch_semaphore_signal function increments the count variable by 1 to indicate that a resource has been freed up. If there are tasks blocked and waiting for a resource, one of them is subsequently unblocked and allowed to do its work. Waiting on Groups of Queued Tasks Dispatch groups are a way to block a thread until one or more tasks finish executing. You can use this behavior in places where you cannot make progress until all of the specified tasks are complete. For example, after dispatching several tasksto compute some data, you might use a group to wait on those tasks and then process the results when they are done. Another way to use dispatch groupsis as an alternative to thread joins. Instead of starting several child threads and then joining with each of them, you could add the corresponding tasks to a dispatch group and wait on the entire group. Listing 3-6 shows the basic process for setting up a group, dispatching tasks to it, and waiting on the results. Instead of dispatching tasks to a queue using the dispatch_async function, you use the dispatch_group_async function instead. This function associates the task with the group and queues it for execution. To wait on a group of tasks to finish, you then use the dispatch_group_wait function, passing in the appropriate group. Dispatch Queues Waiting on Groups of Queued Tasks 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 53Listing 3-6 Waiting on asynchronous tasks dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_group_t group = dispatch_group_create(); // Add a task to the group dispatch_group_async(group, queue, ^{ // Some asynchronous work }); // Do some other work while the tasks execute. // When you cannot make any more forward progress, // wait on the group to block the current thread. dispatch_group_wait(group, DISPATCH_TIME_FOREVER); // Release the group when it is no longer needed. dispatch_release(group); Dispatch Queues and Thread Safety It might seem odd to talk about thread safety in the context of dispatch queues, but thread safety is still a relevant topic. Any time you are implementing concurrency in your application, there are a few things you should know: ● Dispatch queues themselves are thread safe. In other words, you can submit tasks to a dispatch queue from any thread on the system without first taking a lock or synchronizing access to the queue. ● Do not call the dispatch_sync function from a task that is executing on the same queue that you pass to your function call. Doing so will deadlock the queue. If you need to dispatch to the current queue, do so asynchronously using the dispatch_async function. ● Avoid taking locks from the tasks you submit to a dispatch queue. Although it is safe to use locks from your tasks, when you acquire the lock, you risk blocking a serial queue entirely if that lock is unavailable. Similarly, for concurrent queues, waiting on a lock might prevent other tasks from executing instead. If you need to synchronize parts of your code, use a serial dispatch queue instead of a lock. Dispatch Queues Dispatch Queues and Thread Safety 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 54● Although you can obtain information about the underlying thread running a task, it is better to avoid doing so. For more information about the compatibility of dispatch queues with threads,see “Compatibility with POSIX Threads” (page 82). For additional tips on how to change your existing threaded code to use dispatch queues,see “Migrating Away from Threads” (page 74). Dispatch Queues Dispatch Queues and Thread Safety 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 55Whenever you interact with the underlying system, you must be prepared for that task to take a nontrivial amount of time. Calling down to the kernel or othersystem layersinvolves a change in context that isreasonably expensive compared to calls that occur within your own process. As a result, many system libraries provide asynchronous interfaces to allow your code to submit a request to the system and continue to do other work while that request is processed. Grand Central Dispatch builds on this general behavior by allowing you to submit your request and have the results reported back to your code using blocks and dispatch queues. About Dispatch Sources A dispatch source is a fundamental data type that coordinates the processing of specific low-level system events. Grand Central Dispatch supports the following types of dispatch sources: ● Timer dispatch sources generate periodic notifications. ● Signal dispatch sources notify you when a UNIX signal arrives. ● Descriptor sources notify you of various file- and socket-based operations, such as: ● When data is available for reading ● When it is possible to write data ● When files are deleted, moved, or renamed in the file system ● When file meta information changes ● Process dispatch sources notify you of process-related events, such as: ● When a process exits ● When a process issues a fork or exec type of call ● When a signal is delivered to the process ● Mach port dispatch sources notify you of Mach-related events. ● Custom dispatch sources are ones you define and trigger yourself. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 56 Dispatch SourcesDispatch sourcesreplace the asynchronous callback functionsthat are typically used to processsystem-related events. When you configure a dispatch source, you specify the events you want to monitor and the dispatch queue and code to use to process those events. You can specify your code using block objects or functions. When an event of interest arrives, the dispatch source submits your block or function to the specified dispatch queue for execution. Unlike tasks that you submit to a queue manually, dispatch sources provide a continuous source of events for your application. A dispatch source remains attached to its dispatch queue until you cancel it explicitly. While attached, it submits its associated task code to the dispatch queue whenever the corresponding event occurs. Some events, such as timer events, occur at regular intervals but most occur only sporadically as specific conditions arise. For this reason, dispatch sources retain their associated dispatch queue to prevent it from being released prematurely while events may still be pending. To prevent events from becoming backlogged in a dispatch queue, dispatch sources implement an event coalescing scheme. If a new event arrives before the event handler for a previous event has been dequeued and executed, the dispatch source coalesces the data from the new event data with data from the old event. Depending on the type of event, coalescing may replace the old event or update the information it holds. For example, a signal-based dispatch source provides information about only the most recent signal but also reports how many total signals have been delivered since the last invocation of the event handler. Creating Dispatch Sources Creating a dispatch source involves creating both the source of the events and the dispatch source itself. The source of the events is whatever native data structures are required to process the events. For example, for a descriptor-based dispatch source you would need to open the descriptor and for a process-based source you would need to obtain the process ID of the target program. When you have your event source, you can then create the corresponding dispatch source as follows: 1. Create the dispatch source using the dispatch_source_create function. 2. Configure the dispatch source: ● Assign an event handler to the dispatch source; see “Writing and Installing an Event Handler” (page 58). ● For timer sources, set the timer information using the dispatch_source_set_timer function; see “Creating a Timer” (page 62). 3. Optionally assign a cancellation handler to the dispatch source;see “Installing a Cancellation Handler” (page 60). 4. Call the dispatch_resume function to start processing events; see “Suspending and Resuming Dispatch Sources” (page 73). Dispatch Sources Creating Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 57Because dispatch sources require some additional configuration before they can be used, the dispatch_source_create function returns dispatch sources in a suspended state. While suspended, a dispatch source receives events but does not process them. This gives you time to install an event handler and perform any additional configuration needed to process the actual events. The following sections show you how to configure various aspects of a dispatch source. For detailed examples showing you how to configure specific types of dispatch sources, see “Dispatch Source Examples” (page 62). For additional information about the functions you use to create and configure dispatch sources, see Grand Central Dispatch (GCD) Reference . Writing and Installing an Event Handler To handle the events generated by a dispatch source, you must define an event handler to process those events. An event handler is a function or block object that you install on your dispatch source using the dispatch_source_set_event_handler or dispatch_source_set_event_handler_f function. When an event arrives, the dispatch source submits your event handler to the designated dispatch queue for processing. The body of your event handler is responsible for processing any events that arrive. If your event handler is already queued and waiting to process an event when a new event arrives, the dispatch source coalesces the two events. An event handler generally sees information only for the most recent event, but depending on the type of the dispatch source it may also be able to get information about other events that occurred and were coalesced. If one or more new events arrive after the event handler has begun executing, the dispatch source holds onto those events until the current event handler has finished executing. At that point, it submits the event handler to the queue again with the new events. Function-based event handlerstake a single context pointer, containing the dispatch source object, and return no value. Block-based event handlers take no parameters and have no return value. // Block-based event handler void (^dispatch_block_t)(void) // Function-based event handler void (*dispatch_function_t)(void *) Inside your event handler, you can get information about the given event from the dispatch source itself. Although function-based event handlers are passed a pointer to the dispatch source as a parameter, block-based event handlers must capture that pointer themselves. You can do thisfor your blocks by referencing the variable containing the dispatch source normally. For example, the following code snippet capturesthe source variable, which is declared outside the scope of the block. Dispatch Sources Creating Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 58dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_READ, myDescriptor, 0, myQueue); dispatch_source_set_event_handler(source, ^{ // Get some data from the source variable, which is captured // from the parent context. size_t estimated = dispatch_source_get_data(source); // Continue reading the descriptor... }); dispatch_resume(source); Capturing variablesinside of a block is commonly done to allow for greater flexibility and dynamism. Of course, captured variables are read-only within the block by default. Although the blocks feature provides support for modifying captured variables under specific circumstances, you should not attempt to do so in the event handlers associated with a dispatch source. Dispatch sources always execute their event handlers asynchronously, so the defining scope of any variables you captured is likely gone by the time your event handler executes. For more information about how to capture and use variables inside of blocks, see Blocks Programming Topics. Table 4-1 lists the functions you can call from your event handler code to obtain information about an event. Table 4-1 Getting data from a dispatch source Function Description Thisfunction returnsthe underlying system data type that the dispatch source manages. For a descriptor dispatch source, this function returns an int type containing the descriptor associated with the dispatch source. For a signal dispatch source, this function returns an int type containing the signal number for the most recent event. For a process dispatch source, this function returns a pid_t data structure for the process being monitored. For a Mach port dispatch source, this function returns a mach_port_t data structure. For other dispatch sources, the value returned by this function is undefined. dispatch_source_- get_handle Dispatch Sources Creating Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 59Function Description This function returns any pending data associated with the event. For a descriptor dispatch source that reads data from a file, this function returns the number of bytes available for reading. For a descriptor dispatch source that writes data to a file, this function returns a positive integer if space is available for writing. For a descriptor dispatch source that monitorsfile system activity, thisfunction returns a constant indicating the type of event that occurred. For a list of constants, see the dispatch_source_vnode_flags_t enumerated type. For a process dispatch source, this function returns a constant indicating the type of event that occurred. For a list of constants, see the dispatch_source_proc_flags_t enumerated type. For a Mach port dispatch source, this function returns a constant indicating the type of event that occurred. For a list of constants, see the dispatch_source_machport_flags_t enumerated type. For a custom dispatch source, thisfunction returnsthe new data value created from the existing data and the new data passed to the dispatch_source_merge_data function. dispatch_source_- get_data This function returns the event flags that were used to create the dispatch source. For a process dispatch source, this function returns a mask of the events that the dispatch source receives. For a list of constants, see the dispatch_source_proc_flags_t enumerated type. For a Mach port dispatch source with send rights, thisfunction returns a mask of the desired events. For a list of constants, see the dispatch_source_- mach_send_flags_t enumerated type. For a custom OR dispatch source, thisfunction returnsthe mask used to merge the data values. dispatch_source_- get_mask Forsome examples of how to write and install event handlersforspecific types of dispatch sources,see “Dispatch Source Examples” (page 62). Installing a Cancellation Handler Cancellation handlers are used to clean up a dispatch source before it is released. For most types of dispatch sources, cancellation handlers are optional and only necessary if you have some custom behaviors tied to the dispatch source that also need to be updated. For dispatch sourcesthat use a descriptor or Mach port, however, Dispatch Sources Creating Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 60you must provide a cancellation handler to close the descriptor or release the Mach port. Failure to do so can lead to subtle bugs in your code resulting from those structures being reused unintentionally by your code or other parts of the system. You can install a cancellation handler at any time but usually you would do so when creating the dispatch source. You install a cancellation handler using the dispatch_source_set_cancel_handler or dispatch_source_set_cancel_handler_f function, depending on whether you want to use a block object or a function in your implementation. The following example shows a simple cancellation handler that closes a descriptor that was opened for a dispatch source. The fd variable is a captured variable containing the descriptor. dispatch_source_set_cancel_handler(mySource, ^{ close(fd); // Close a file descriptor opened earlier. }); To see a complete code example for a dispatch source that uses a cancellation handler, see “Reading Data from a Descriptor” (page 64). Changing the Target Queue Although you specify the queue on which to run your event and cancellation handlers when you create a dispatch source, you can change that queue at any time using the dispatch_set_target_queue function. You might do this to change the priority at which the dispatch source’s events are processed. Changing a dispatch source’s queue is an asynchronous operation and the dispatch source does its best to make the change as quickly as possible. If an event handler is already queued and waiting to be processed, it executes on the previous queue. However, other events arriving around the time you make the change could be processed on either queue. Associating Custom Data with a Dispatch Source Like many other data types in Grand Central Dispatch, you can use the dispatch_set_context function to associate custom data with a dispatch source. You can use the context pointer to store any data your event handler needs to process events. If you do store any custom data in the context pointer, you should also install a cancellation handler (as described in “Installing a Cancellation Handler” (page 60)) to release that data when the dispatch source is no longer needed. If you implement your event handler using blocks, you can also capture local variables and use them within your block-based code. Although this might alleviate the need to store data in the context pointer of the dispatch source, you should always use this feature judiciously. Because dispatch sources may be long-lived in your application, you should be careful when capturing variables containing pointers. If the data pointed Dispatch Sources Creating Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 61to by a pointer could be deallocated at any time, you should either copy the data or retain it to prevent that from happening. In either case, you would then need to provide a cancellation handler to release the data later. Memory Management for Dispatch Sources Like other dispatch objects, dispatch sources are reference counted data types. A dispatch source has an initial reference count of 1 and can be retained and released using the dispatch_retain and dispatch_release functions. When the reference count of a queue reaches zero, the system automatically deallocatesthe dispatch source data structures. Because of the way they are used, the ownership of dispatch sources can be managed either internally or externally to the dispatch source itself. With external ownership, another object or piece of code takes ownership of the dispatch source and is responsible for releasing it when it is no longer needed. With internal ownership, the dispatch source ownsitself and isresponsible for releasing itself at the appropriate time. Although external ownership is very common, you might use internal ownership in cases where you want to create an autonomous dispatch source and let it manage some behavior of your code without any further interactions. For example, if a dispatch source is designed to respond to a single global event, you might have it handle that event and then exit immediately. Dispatch Source Examples The following sections show you how to create and configure some of the more commonly used dispatch sources. For more information about configuring specific types of dispatch sources,see Grand Central Dispatch (GCD) Reference . Creating a Timer Timer dispatch sources generate events at regular, time-based intervals. You can use timers to initiate specific tasksthat need to be performed regularly. For example, games and other graphics-intensive applications might use timers to initiate screen or animation updates. You could also set up a timer and use the resulting events to check for new information on a frequently updated server. All timer dispatch sources are interval timers—that is, once created, they deliver regular events at the interval you specify. When you create a timer dispatch source, one of the values you must specify is a leeway value to give the system some idea of the desired accuracy for timer events. Leeway values give the system some flexibility in how it manages power and wakes up cores. For example, the system might use the leeway value to advance or delay the fire time and align it better with other system events. You should therefore specify a leeway value whenever possible for your own timers. Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 62Note: Even if you specify a leeway value of 0, you should never expect a timer to fire at the exact nanosecond you requested. The system does its best to accommodate your needs but cannot guarantee exact firing times. When a computer goes to sleep, all timer dispatch sources are suspended. When the computer wakes up, those timer dispatch sources are automatically woken up as well. Depending on the configuration of the timer, pauses of this nature may affect when your timer fires next. If you set up your timer dispatch source using the dispatch_time function or the DISPATCH_TIME_NOW constant, the timer dispatch source uses the default system clock to determine when to fire. However, the default clock does not advance while the computer is asleep. By contrast, when you set up your timer dispatch source using the dispatch_walltime function, the timer dispatch source tracks its firing time to the wall clock time. This latter option is typically appropriate for timers whose firing interval is relatively large because it prevents there from being too much drift between event times. Listing 4-1 shows an example of a timer that fires once every 30 seconds and has a leeway value of 1 second. Because the timer interval is relatively large, the dispatch source is created using the dispatch_walltime function. The first firing of the timer occurs immediately and subsequent events arrive every 30 seconds. The MyPeriodicTask and MyStoreTimer symbolsrepresent custom functionsthat you would write to implement the timer behavior and to store the timer somewhere in your application’s data structures. Listing 4-1 Creating a timer dispatch source dispatch_source_t CreateDispatchTimer(uint64_t interval, uint64_t leeway, dispatch_queue_t queue, dispatch_block_t block) { dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, queue); if (timer) { dispatch_source_set_timer(timer, dispatch_walltime(NULL, 0), interval, leeway); dispatch_source_set_event_handler(timer, block); dispatch_resume(timer); } return timer; } Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 63void MyCreateTimer() { dispatch_source_t aTimer = CreateDispatchTimer(30ull * NSEC_PER_SEC, 1ull * NSEC_PER_SEC, dispatch_get_main_queue(), ^{ MyPeriodicTask(); }); // Store it somewhere for later use. if (aTimer) { MyStoreTimer(aTimer); } } Although creating a timer dispatch source isthe main way to receive time-based events, there are other options available as well. If you want to perform a block once after a specified time interval, you can use the dispatch_after or dispatch_after_f function. This function behaves much like the dispatch_async function except that it allows you to specify a time value at which to submit the block to a queue. The time value can be specified as a relative or absolute time value depending on your needs. Reading Data from a Descriptor To read data from a file or socket, you must open the file or socket and create a dispatch source of type DISPATCH_SOURCE_TYPE_READ. The event handler you specify should be capable of reading and processing the contents of the file descriptor. In the case of a file, this amounts to reading the file data (or a subset of that data) and creating the appropriate data structures for your application. For a network socket, this involves processing newly received network data. Whenever reading data, you should always configure your descriptor to use non-blocking operations. Although you can use the dispatch_source_get_data function to see how much data is available for reading, the number returned by that function could change between the time you make the call and the time you actually read the data. If the underlying file istruncated or a network error occurs, reading from a descriptor that blocks the current thread could stall your event handler in mid execution and prevent the dispatch queue from dispatching other tasks. For a serial queue, this could deadlock your queue, and even for a concurrent queue this reduces the number of new tasks that can be started. Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 64Listing 4-2 shows an example that configures a dispatch source to read data from a file. In this example, the event handler reads the entire contents of the specified file into a buffer and calls a custom function (that you would define in your own code) to processthe data. (The caller of thisfunction would use the returned dispatch source to cancel it once the read operation was completed.) To ensure that the dispatch queue does not block unnecessarily when there is no data to read, this example usesthe fcntl function to configure the file descriptor to perform nonblocking operations. The cancellation handler installed on the dispatch source ensures that the file descriptor is closed after the data is read. Listing 4-2 Reading data from a file dispatch_source_t ProcessContentsOfFile(const char* filename) { // Prepare the file for reading. int fd = open(filename, O_RDONLY); if (fd == -1) return NULL; fcntl(fd, F_SETFL, O_NONBLOCK); // Avoid blocking the read operation dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_source_t readSource = dispatch_source_create(DISPATCH_SOURCE_TYPE_READ, fd, 0, queue); if (!readSource) { close(fd); return NULL; } // Install the event handler dispatch_source_set_event_handler(readSource, ^{ size_t estimated = dispatch_source_get_data(readSource) + 1; // Read the data into a text buffer. char* buffer = (char*)malloc(estimated); if (buffer) { ssize_t actual = read(fd, buffer, (estimated)); Boolean done = MyProcessFileData(buffer, actual); // Process the data. Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 65// Release the buffer when done. free(buffer); // If there is no more data, cancel the source. if (done) dispatch_source_cancel(readSource); } }); // Install the cancellation handler dispatch_source_set_cancel_handler(readSource, ^{close(fd);}); // Start reading the file. dispatch_resume(readSource); return readSource; } In the preceding example, the custom MyProcessFileData function determines when enough file data has been read and the dispatch source can be canceled. By default, a dispatch source configured for reading from a descriptor schedules its event handler repeatedly while there is still data to read. If the socket connection closes or you reach the end of a file, the dispatch source automatically stops scheduling the event handler. If you know you do not need a dispatch source though, you can cancel it directly yourself. Writing Data to a Descriptor The process for writing data to a file or socket is very similar to the process for reading data. After configuring a descriptor for write operations, you create a dispatch source of type DISPATCH_SOURCE_TYPE_WRITE. Once that dispatch source is created, the system calls your event handler to give it a chance to start writing data to the file or socket. When you are finished writing data, use the dispatch_source_cancel function to cancel the dispatch source. Whenever writing data, you should always configure your file descriptor to use non-blocking operations. Although you can use the dispatch_source_get_data function to see how much space is available for writing, the value returned by that function is advisory only and could change between the time you make the call and the time you actually write the data. If an error occurs, writing data to a blocking file descriptor Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 66could stall your event handler in mid execution and prevent the dispatch queue from dispatching other tasks. For a serial queue, this could deadlock your queue, and even for a concurrent queue this reduces the number of new tasks that can be started. Listing 4-3 shows the basic approach for writing data to a file using a dispatch source. After creating the new file, this function passes the resulting file descriptor to its event handler. The data being put into the file is provided by the MyGetData function, which you would replace with whatever code you needed to generate the data for the file. After writing the data to the file, the event handler cancels the dispatch source to prevent it from being called again. The owner of the dispatch source would then be responsible for releasing it. Listing 4-3 Writing data to a file dispatch_source_t WriteDataToFile(const char* filename) { int fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, (S_IRUSR | S_IWUSR | S_ISUID | S_ISGID)); if (fd == -1) return NULL; fcntl(fd, F_SETFL); // Block during the write. dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_source_t writeSource = dispatch_source_create(DISPATCH_SOURCE_TYPE_WRITE, fd, 0, queue); if (!writeSource) { close(fd); return NULL; } dispatch_source_set_event_handler(writeSource, ^{ size_t bufferSize = MyGetDataSize(); void* buffer = malloc(bufferSize); size_t actual = MyGetData(buffer, bufferSize); write(fd, buffer, actual); Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 67free(buffer); // Cancel and release the dispatch source when done. dispatch_source_cancel(writeSource); }); dispatch_source_set_cancel_handler(writeSource, ^{close(fd);}); dispatch_resume(writeSource); return (writeSource); } Monitoring a File-System Object If you want to monitor a file system object for changes, you can set up a dispatch source of type DISPATCH_SOURCE_TYPE_VNODE. You can use this type of dispatch source to receive notifications when a file is deleted, written to, or renamed. You can also use it to be alerted when specific types of meta information for a file (such as its size and link count) change. Note: The file descriptor you specify for your dispatch source must remain open while the source itself is processing events. Listing 4-4 shows an example that monitors a file for name changes and performssome custom behavior when it does. (You would provide the actual behavior in place of the MyUpdateFileName function called in the example.) Because a descriptor is opened specifically for the dispatch source, the dispatch source includes a cancellation handler that closesthe descriptor. Because the file descriptor created by the example is associated with the underlying file-system object, thissame dispatch source can be used to detect any number of filename changes. Listing 4-4 Watching for filename changes dispatch_source_t MonitorNameChangesToFile(const char* filename) { int fd = open(filename, O_EVTONLY); if (fd == -1) return NULL; Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 68dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_VNODE, fd, DISPATCH_VNODE_RENAME, queue); if (source) { // Copy the filename for later use. int length = strlen(filename); char* newString = (char*)malloc(length + 1); newString = strcpy(newString, filename); dispatch_set_context(source, newString); // Install the event handler to process the name change dispatch_source_set_event_handler(source, ^{ const char* oldFilename = (char*)dispatch_get_context(source); MyUpdateFileName(oldFilename, fd); }); // Install a cancellation handler to free the descriptor // and the stored string. dispatch_source_set_cancel_handler(source, ^{ char* fileStr = (char*)dispatch_get_context(source); free(fileStr); close(fd); }); // Start processing events. dispatch_resume(source); } else close(fd); return source; } Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 69Monitoring Signals UNIX signals allow the manipulation of an application from outside of its domain. An application can receive many different types of signals ranging from unrecoverable errors (such as illegal instructions) to notifications about important information (such as when a child process exits). Traditionally, applications use the sigaction function to install a signal handler function, which processes signals synchronously as soon as they arrive. If you just want to be notified of a signal’s arrival and do not actually want to handle the signal, you can use a signal dispatch source to process the signals asynchronously. Signal dispatch sources are not a replacement for the synchronous signal handlers you install using the sigaction function. Synchronous signal handlers can actually catch a signal and prevent it from terminating your application. Signal dispatch sources allow you to monitor only the arrival of the signal. In addition, you cannot use signal dispatch sources to retrieve all types of signals. Specifically, you cannot use them to monitor the SIGILL, SIGBUS, and SIGSEGV signals. Because signal dispatch sources are executed asynchronously on a dispatch queue, they do not suffer from some of the same limitations as synchronous signal handlers. For example, there are no restrictions on the functions you can call from yoursignal dispatch source’s event handler. The tradeoff for thisincreased flexibility is the fact that there may be some increased latency between the time a signal arrives and the time your dispatch source’s event handler is called. Listing 4-5 shows how you configure a signal dispatch source to handle the SIGHUP signal. The event handler for the dispatch source calls the MyProcessSIGHUP function, which you would replace in your application with code to process the signal. Listing 4-5 Installing a block to monitor signals void InstallSignalHandler() { // Make sure the signal does not terminate the application. signal(SIGHUP, SIG_IGN); dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_SIGNAL, SIGHUP, 0, queue); if (source) { dispatch_source_set_event_handler(source, ^{ Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 70MyProcessSIGHUP(); }); // Start processing signals dispatch_resume(source); } } If you are developing code for a custom framework, an advantage of using signal dispatch sources is that your code can monitor signals independent of any applications linked to it. Signal dispatch sources do not interfere with other dispatch sources or any synchronous signal handlers the application might have installed. For more information about implementing synchronous signal handlers, and for a list of signal names, see signal man page. Monitoring a Process A process dispatch source lets you monitor the behavior of a specific process and respond appropriately. A parent process might use this type of dispatch source to monitor any child processes it creates. For example, the parent process could use it to watch for the death of a child process. Similarly, a child process could use it to monitor its parent process and exit if the parent process exits. Listing 4-6 shows the steps for installing a dispatch source to monitor for the termination of a parent process. When the parent process dies, the dispatch source sets some internal state information to let the child process know it should exit. (Your own application would need to implement the MySetAppExitFlag function to set an appropriate flag for termination.) Because the dispatch source runs autonomously, and therefore owns itself, it also cancels and releases itself in anticipation of the program shutting down. Listing 4-6 Monitoring the death of a parent process void MonitorParentProcess() { pid_t parentPID = getppid(); dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_PROC, parentPID, DISPATCH_PROC_EXIT, queue); Dispatch Sources Dispatch Source Examples 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 71if (source) { dispatch_source_set_event_handler(source, ^{ MySetAppExitFlag(); dispatch_source_cancel(source); dispatch_release(source); }); dispatch_resume(source); } } Canceling a Dispatch Source Dispatch sourcesremain active until you cancel them explicitly using the dispatch_source_cancel function. Canceling a dispatch source stops the delivery of new events and cannot be undone. Therefore, you typically cancel a dispatch source and then immediately release it, as shown here: void RemoveDispatchSource(dispatch_source_t mySource) { dispatch_source_cancel(mySource); dispatch_release(mySource); } Cancellation of a dispatch source is an asynchronous operation. Although no new events are processed after you call the dispatch_source_cancel function, events that are already being processed by the dispatch source continue to be processed. After it finishes processing any final events, the dispatch source executes its cancellation handler if one is present. The cancellation handler is your chance to deallocate memory or clean up any resources that were acquired on behalf of the dispatch source. If your dispatch source uses a descriptor or mach port, you must provide a cancellation handler to close the descriptor or destroy the port when cancellation occurs. Other types of dispatch sources do not require cancellation handlers, although you still should provide one if you associate any memory or data with the dispatch source. For example, you should provide one if you store data in the dispatch source’s context pointer. For more information about cancellation handlers,see “Installing a Cancellation Handler” (page 60). Dispatch Sources Canceling a Dispatch Source 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 72Suspending and Resuming Dispatch Sources You can suspend and resume the delivery of dispatch source eventstemporarily using the dispatch_suspend and dispatch_resume methods. These methods increment and decrement the suspend count for your dispatch object. As a result, you must balance each call to dispatch_suspend with a matching call to dispatch_resume before event delivery resumes. When you suspend a dispatch source, any events that occur while that dispatch source is suspended are accumulated until the queue is resumed. When the queue resumes, rather than deliver all of the events, the events are coalesced into a single event before delivery. For example, if you were monitoring a file for name changes, the delivered event would include only the last name change. Coalescing events in this way prevents them from building up in the queue and overwhelming your application when work resumes. Dispatch Sources Suspending and Resuming Dispatch Sources 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 73There are many ways to adapt existing threaded code to take advantage of Grand Central Dispatch and operation objects. Although moving away from threads may not be possible in all cases, performance (and the simplicity of your code) can improve dramatically in places where you do make the switch. Specifically, using dispatch queues and operation queues instead of threads has several advantages: ● It reduces the memory penalty your application pays for storing thread stacks in the application’s memory space. ● It eliminates the code needed to create and configure your threads. ● It eliminates the code needed to manage and schedule work on threads. ● It simplifies the code you have to write. This chapter providessome tips and guidelines on how to replace your existing thread-based code and instead use dispatch queues and operation queues to achieve the same types of behaviors. Replacing Threads with Dispatch Queues To understand how you might replace threads with dispatch queues, first considersome of the ways you might be using threads in your application today: ● Single task threads. Create a thread to perform a single task and release the thread when the task is done. ● Worker threads. Create one or more worker threads with specific tasks in mind for each. Dispatch tasks to each thread periodically. ● Thread pools. Create a pool of generic threads and set up run loops for each one. When you have a task to perform, grab a thread from the pool and dispatch the task to it. If there are no free threads, queue the task and wait for a thread to become available. Although these might seem like dramatically different techniques, they are really just variants on the same principle. In each case, a thread is being used to run some task that the application has to perform. The only difference between them is the code used to manage the threads and the queueing of tasks. With dispatch queues and operation queues, you can eliminate all of your thread and thread-communication code and instead focus on just the tasks you want to perform. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 74 Migrating Away from ThreadsIf you are using one of the above threading models, you should already have a pretty good idea of the type of tasks your application performs. Instead ofsubmitting a task to one of your custom threads, try encapsulating that task in an operation object or a block object and dispatching it to the appropriate queue. For tasks that are not particularly contentious—that is, tasksthat do not take locks—you should be able to make the following direct replacements: ● For a single task thread, encapsulate the task in a block or operation object and submit it to a concurrent queue. ● For worker threads, you need to decide whether to use a serial queue or a concurrent queue. If you use worker threads to synchronize the execution of specific sets of tasks, use a serial queue. If you do use worker threads to execute arbitrary tasks with no interdependencies, use a concurrent queue. ● For thread pools, encapsulate your tasks in a block or operation object and dispatch them to a concurrent queue for execution. Of course, simple replacements like this may not work in all cases. If the tasks you are executing contend for shared resources, the ideal solution is to try to remove or minimize that contention first. If there are ways that you can refactor or rearchitect your code to eliminate mutual dependencies on shared resources, that is certainly preferable. However, if doing so is not possible or might be less efficient, there are still ways to take advantage of queues. A big advantage of queues is that they offer a more predictable way to execute your code. This predictability means that there are still ways to synchronize the execution of your code without using locks or other heavyweight synchronization mechanisms. Instead of using locks, you can use queues to perform many of the same tasks: ● If you have tasksthat must execute in a specific order,submit them to a serial dispatch queue. If you prefer to use operation queues, use operation object dependencies to ensure that those objects execute in a specific order. ● If you are currently using locks to protect a shared resource, create a serial queue to execute any tasks that modify that resource. The serial queue then replaces your existing locks as the synchronization mechanism. For more information techniques for getting rid of locks, see “Eliminating Lock-Based Code” (page 76). ● If you use thread joins to wait for background tasks to complete, consider using dispatch groups instead. You can also use an NSBlockOperation object or operation object dependencies to achieve similar group-completion behaviors. Formore information on how to track groups of executing tasks,see “Replacing Thread Joins” (page 79). ● If you use a producer-consumer algorithm to manage a pool of finite resources, consider changing your implementation to the one shown in “Changing Producer-Consumer Implementations” (page 80). ● If you are using threads to read and write from descriptors, or monitor file operations, use the dispatch sources as described in “Dispatch Sources” (page 56). Migrating Away from Threads Replacing Threads with Dispatch Queues 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 75It isimportant to remember that queues are not a panacea for replacing threads. The asynchronous programming model offered by queues is appropriate in situations where latency is not an issue. Even though queues offer ways to configure the execution priority of tasks in the queue, higher execution priorities do not guarantee the execution of tasks at specific times. Therefore, threads are still a more appropriate choice in cases where you need minimal latency, such as in audio and video playback. Eliminating Lock-Based Code For threaded code, locks are one of the traditional ways to synchronize access to resources that are shared between threads. However, the use of locks comes at a cost. Even in the non-contested case, there is always a performance penalty associated with taking a lock. And in the contested case, there is the potential for one or more threads to block for an indeterminate amount of time while waiting for the lock to be released. Replacing your lock-based code with queues eliminates many of the penalties associated with locks and also simplifies your remaining code. Instead of using a lock to protect a shared resource, you can instead create a queue to serialize the tasks that access that resource. Queues do not impose the same penalties as locks. For example, queueing a task does not require trapping into the kernel to acquire a mutex. When queueing tasks, the main decision you have to make is whether to do so synchronously or asynchronously. Submitting a task asynchronously letsthe current thread continue to run while the task is performed. Submitting a task synchronously blocksthe current thread until the task is completed. Both options have appropriate uses, although it is certainly advantageous to submit tasks asynchronously whenever you can. The following sectionsshow you how to replace your existing lock-based code with the equivalent queue-based code. Implementing an Asynchronous Lock An asynchronous lock is a way for you to protect a shared resource without blocking any code that modifies that resource. You might use an asynchronous lock when you need to modify a data structure as a side effect of some other work your code is doing. Using traditional threads, the way you would normally implement this code would be to take a lock for the shared resource, make the necessary changes, release the lock, and continue with the main part of your task. However, using dispatch queues, the calling code can make the modifications asynchronously without waiting for those changes to be completed. Listing 5-1 shows an example of an asynchronouslock implementation. In this example, the protected resource defines its own serial dispatch queue. The calling code submits a block object to this queue that contains the modifications that need to be made to the resource. Because the queue itself executes blocks serially, changes to the resource are guaranteed to be made in the order in which they were received; however, because the task was executed asynchronously, the calling thread does not block. Migrating Away from Threads Eliminating Lock-Based Code 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 76Listing 5-1 Modifying protected resources asynchronously dispatch_async(obj->serial_queue, ^{ // Critical section }); Executing Critical Sections Synchronously If the current code cannot continue until a given task is complete, you can submit the task synchronously using the dispatch_sync function. This function adds the task to a dispatch queue and then blocks the current thread until the task finishes executing. The dispatch queue itself can be a serial or concurrent queue depending on your needs. Because thisfunction blocksthe current thread, though, you should use it only when necessary. Listing 5-2 shows the technique for wrapping a critical section of your code using dispatch_sync. Listing 5-2 Running critical sections synchronously dispatch_sync(my_queue, ^{ // Critical section }); If you are already using a serial queue to protect a shared resource, dispatching to that queue synchronously does not protect the shared resource any more than if you dispatched asynchronously. The only reason to dispatch synchronously is to prevent the current code from continuing until the critical section finishes. For example, if you wanted to get some value from the shared resource and use it right away, you would need to dispatch synchronously. If the current code does not need to wait for the critical section to complete, or if it can simply submit additional follow-up tasks to the same serial queue, submitting asynchronously is generally preferred. Improving on Loop Code If your code has loops, and the work being done each time through the loop is independent of the work being done in the other iterations, you might consider reimplementing that loop code using the dispatch_apply or dispatch_apply_f function. These functions submit each iteration of a loop separately to a dispatch queue for processing. When used in conjunction with a concurrent queue, thisfeature lets you perform multiple iterations of the loop concurrently. Migrating Away from Threads Improving on Loop Code 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 77The dispatch_apply and dispatch_apply_f functions are synchronous function calls that block the current thread of execution until all of the loop iterations are complete. When submitted to a concurrent queue, the execution order of the loop iterations is not guaranteed. The threads running each iteration could block and cause a given iteration to finish before or after the others around it. Therefore, the block object or function you use for each loop iteration must be reentrant. Listing 5-3 shows how to replace a for loop with its dispatch-based equivalent. The block or function you pass to dispatch_apply or dispatch_apply_f must take an integer value indicating the current loop iteration. In this example, the code simply prints the current loop number to the console. Listing 5-3 Replacing a for loop without striding queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_apply(count, queue, ^(size_t i) { printf("%u\n", i); }); Although the preceding example is a simplistic one, it demonstrates the basic techniques for replacing a loop using dispatch queues. And although this can be a good way to improve performance in loop-based code, you must still use this technique discerningly. Although dispatch queues have very low overhead, there are still costs to scheduling each loop iteration on a thread. Therefore, you should make sure your loop code does enough work to warrant the costs. Exactly how much work you need to do is something you have to measure using the performance tools. A simple way to increase the amount of work in each loop iteration is to use striding. With striding, you rewrite your block code to perform more than one iteration of the original loop. You then reduce the count value you specify to the dispatch_apply function by a proportional amount. Listing 5-4 shows how youmightimplement striding for the loop code shown in Listing 5-3 (page 78). In Listing 5-4, the block calls the printf statement the same number of times as the stride value, which in this case is 137. (The actual stride value is something you should configure based on the work being done by your code.) Because there is a remainder left over when dividing the total number of iterations by a stride value, any remaining iterations are performed inline. Listing 5-4 Adding a stride to a dispatched for loop int stride = 137; dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_apply(count / stride, queue, ^(size_t idx){ Migrating Away from Threads Improving on Loop Code 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 78size_t j = idx * stride; size_t j_stop = j + stride; do { printf("%u\n", (unsigned int)j++); }while (j < j_stop); }); size_t i; for (i = count - (count % stride); i < count; i++) printf("%u\n", (unsigned int)i); There are some definite performance advantages to using strides. In particular, strides offer benefits when the original number of loop iterations is high, relative to the stride. Dispatching fewer blocks concurrently means that more time is spent executing the code of those blocks than dispatching them. As with any performance metric though, you may have to play with the striding value to find the most efficient value for your code. Replacing Thread Joins Thread joins allow you to spawn one or more threads and then have the current thread wait until those threads are finished. To implement a thread join, a parent creates a child thread as a joinable thread. When the parent can no longer make progress without the results from a child thread, it joins with the child. This process blocks the parent thread until the child finishes its task and exits, at which point the parent can gather the results from the child and continue with its own work. If the parent needs to join with multiple child threads, it does so one at a time. Dispatch groups offer semantics that are similar to those of thread joins but that have some additional advantages. Like thread joins, dispatch groups are a way for a thread to block until one or more child tasks finishes executing. Unlike thread joins, a dispatch group waits on all of its child tasks simultaneously. And because dispatch groups use dispatch queues to perform the work, they are very efficient. To use a dispatch group to perform the same work performed by joinable threads, you would do the following: 1. Create a new dispatch group using the dispatch_group_create function. 2. Add tasks to the group using the dispatch_group_async or dispatch_group_async_f function. Each task you submit to the group represents work you would normally perform on a joinable thread. 3. When the current thread cannot make any more forward progress, call the dispatch_group_wait function to wait on the group. This function blocks the current thread until all of the tasks in the group finish executing. Migrating Away from Threads Replacing Thread Joins 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 79If you are using operation objects to implement your tasks, you can also implement thread joins using dependencies. Instead of having a parent thread wait for one or more tasks to complete, you would move the parent code to an operation object. You would then set up dependencies between the parent operation object and any number of child operation objects set up to do the work normally performed by the joinable threads. Having dependencies on other operation objects prevents the parent operation object from executing until all of the operations have finished. For an example of how to use dispatch groups, see “Waiting on Groups of Queued Tasks” (page 53). For information about setting up dependencies between operation objects, see “Configuring Interoperation Dependencies” (page 29). Changing Producer-Consumer Implementations A producer-consumer model lets you manage a finite number of dynamically produced resources. While the producer creates new resources (or work), one or more consumers wait for those resources (or work) to be ready and consume them when they are. The typical mechanisms for implementing a producer-consumer model are conditions or semaphores. Using conditions, the producer thread typically does the following: 1. Lock the mutex associated with the condition (using pthread_mutex_lock). 2. Produce the resource or work to be consumed. 3. Signal the condition variable that there is something to consume (using pthread_cond_signal) 4. Unlock the mutex (using pthread_mutex_unlock). In turn, the corresponding consumer thread does the following: 1. Lock the mutex associated with the condition (using pthread_mutex_lock). 2. Set up a while loop to do the following: a. Check to see whether there is really work to be done. b. If there is no work to do (or no resource available), call pthread_cond_wait to block the current thread until a corresponding signal occurs. 3. Get the work (or resource) provided by the producer. 4. Unlock the mutex (using pthread_mutex_unlock). 5. Process the work. With dispatch queues, you can simplify the producer and consumer implementations into a single call: Migrating Away from Threads Changing Producer-Consumer Implementations 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 80dispatch_async(queue, ^{ // Process a work item. }); When your producer has work to be done, all it hasto do is add that work to a queue and let the queue process the item. The only part of the preceding code that changes is the queue type. If the tasks generated by the producer need to be performed in a specific order, you use a serial queue. If the tasks generated by the producer can be performed concurrently, you add them to a concurrent queue and let the system execute as many of them as possible simultaneously. Replacing Semaphore Code If you are currently using semaphoresto restrict accessto a shared resource, you should consider using dispatch semaphores instead. Traditional semaphores always require calling down to the kernel to test the semaphore. In contrast, dispatch semaphores test the semaphore state quickly in user space and trap into the kernel only when the test fails and the calling thread needs to be blocked. This behavior results in dispatch semaphores being much faster than traditional semaphores in the uncontested case. In all other aspects, though, dispatch semaphores offer the same behavior as traditional semaphores. For an example of how to use dispatch semaphores, see “Using Dispatch Semaphores to Regulate the Use of Finite Resources” (page 52). Replacing Run-Loop Code If you are using run loops to manage the work being performed on one or more threads, you may find that queues are much simpler to implement and maintain going forward. Setting up a custom run loop involves setting up both the underlying thread and the run loop itself. The run-loop code consists of setting up one or more run loop sources and writing callbacks to handle events arriving on those sources. Instead of all that work, you can simply create a serial queue and dispatch tasks to it. Thus, you can replace all of your thread and run-loop creation code with one line of code: dispatch_queue_t myNewRunLoop = dispatch_queue_create("com.apple.MyQueue", NULL); Migrating Away from Threads Replacing Semaphore Code 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 81Because the queue automatically executes any tasks added to it, there is no extra code required to manage the queue. You do not have to create or configure a thread, and you do not have to create or attach any run-loop sources. In addition, you can perform new types of work on the queue by simply adding the tasks to it. To do the same thing with a run loop, you would need to modify your existing run loop source or create a new one to handle the new data. One common configuration for run loops is to process data arriving asynchronously on a network socket. Instead of configuring a run loop for this type of behavior, you can attach a dispatch source to the desired queue. Dispatch sources also offer more options for processing data than traditional run loop sources. In addition to processing timer and network port events, you can use dispatch sources to read and write to files, monitor file system objects, monitor processes, and monitor signals. You can even define custom dispatch sources and trigger them from other parts of your code asynchronously. For more information on setting up dispatch sources, see “Dispatch Sources” (page 56). Compatibility with POSIX Threads Because Grand Central Dispatch manages the relationship between the tasks you provide and the threads on which those tasks run, you should generally avoid calling POSIX thread routines from your task code. If you do need to call them for some reason, you should be very careful about which routines you call. This section provides you with an indication of which routines are safe to call and which are not safe to call from your queued tasks. This list is not complete but should give you an indication of what is safe to call and what is not. In general, your application must not delete or mutate objects or data structures that it did not create. Consequently, block objects that are executed using a dispatch queue must not call the following functions: pthread_detach pthread_cancel pthread_join pthread_kill pthread_exit Although it is alright to modify the state of a thread while your task is running, you must return the thread to its original state before your task returns. Therefore, it is safe to call the following functions as long as you return the thread to its original state: pthread_setcancelstate pthread_setcanceltype pthread_setschedparam Migrating Away from Threads Compatibility with POSIX Threads 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 82pthread_sigmask pthread_setspecific The underlying thread used to execute a given block can change from invocation to invocation. As a result, your application should not rely on the following functions returning predictable results between invocations of your block: pthread_self pthread_getschedparam pthread_get_stacksize_np pthread_get_stackaddr_np pthread_mach_thread_np pthread_from_mach_thread_np pthread_getspecific Important: Blocks must catch and suppress any language-level exceptions thrown within them. Other errors that occur during the execution of your block should similarly be handled by the block or used to notify other parts of your application. For more information about POSIX threads and the functions mentioned in this section, see the pthread man pages. Migrating Away from Threads Compatibility with POSIX Threads 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 83application A specific style of program that displays a graphical interface to the user. asynchronous design approach The principle of organizing an application around blocks of code that can be run concurrently with an application’s main thread or other threads of execution. Asynchronous tasks are started by one thread but actually run on a different thread, taking advantage of additional processor resourcesto finish their work more quickly. block object A C construct for encapsulating inline code and data so that it can be performed later. You use blocksto encapsulate tasks you want to perform, either inline in the current thread or on a separate thread using a dispatch queue. For more information, see Blocks Programming Topics. concurrent operation An operation object that does not perform its task in the thread from which its start method was called. A concurrent operation typically sets up its own thread or calls an interface that sets up a separate thread on which to perform the work. condition A construct used to synchronize access to a resource. A thread waiting on a condition is not allowed to proceed until another thread explicitly signals the condition. critical section A portion of code that must be executed by only one thread at a time. custom source A dispatch source used to process application-defined events. A custom source calls your custom event handler in response to events that your application generates. descriptor An abstract identifier used to access a file, socket, or other system resource. dispatch queue A Grand Central Dispatch (GCD) structure that you use to execute your application’s tasks. GCD defines dispatch queues for executing tasks either serially or concurrently. dispatch source A Grand Central Dispatch (GCD) data structure that you create to process system-related events. descriptor dispatch source A dispatch source used to processfile-related events. A file descriptorsource calls your custom event handler either when file data is available for reading or writing or in response to file system changes. dynamic shared library A binary executable that is loaded dynamically into an application’s process space rather than linked statically as part of the application binary. framework A type of bundle that packages a dynamic shared library with the resources and header files that support that library. For more information, see Framework Programming Guide . global dispatch queue A dispatch queue provided to your application automatically by Grand Central Dispatch (GCD). You do not have to create global queues yourself or retain or release them. Instead, you retrieve them using the system-provided functions. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 84 GlossaryGrand Central Dispatch (GCD) A technology for executing asynchronous tasks concurrently. GCD is available in OS X v10.6 and later and iOS 4.0 and later. input source A source of asynchronous events for a thread. Input sources can be port based or manually triggered and must be attached to the thread’s run loop. joinable thread A thread whose resources are not reclaimed immediately upon termination. Joinable threads must be explicitly detached or be joined by another thread before the resources can be reclaimed. Joinable threads provide a return value to the thread that joins with them. library A UNIX feature for monitoring low-level system events. For more information see the kqueue man page. Mach port dispatch source A dispatch source used to process events arriving on a Mach port. main thread A special type of thread created when its owning processis created. When the main thread of a program exits, the process ends. mutex A lock that provides mutually exclusive access to a shared resource. A mutex lock can be held by only one thread at a time. Attempting to acquire a mutex held by a different thread puts the current thread to sleep until the lock is finally acquired. Open Computing Language (OpenCL) A standards-based technology for performing general-purpose computations on a computer’s graphics processor. For more information, see OpenCL Programming Guide for Mac . operation object An instance of the NSOperation class. Operation objects wrap the code and data associated with a task into an executable unit. operation queue An instance of the NSOperationQueue class. Operation queues manage the execution of operation objects. private dispatch queue A dispatch queue that you create, retain, and release explicitly. process The runtime instance of an application or program. A process hasits own virtualmemory space and system resources(including port rights) that are independent of those assigned to other programs. A process always contains at least one thread (the main thread) and may contain any number of additional threads. process dispatch source A dispatch source used to handle process-related events. A process source calls your custom event handler in response to changes to the process you specify. program A combination of code and resourcesthat can be run to perform some task. Programs need not have a graphical user interface, although graphical applications are also considered programs. reentrant Code that can be started on a new thread safely while it is already running on another thread. run loop An event-processing loop, during which events are received and dispatched to appropriate handlers. run loop mode A collection of input sources, timer sources, and run loop observers associated with a particular name. When run in a specific “mode,” a run loop monitors only the sources and observers associated with that mode. run loop object An instance of the NSRunLoop class or CFRunLoopRef opaque type. These objects provide the interface for implementing an event-processing loop in a thread. Glossary 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 85run loop observer A recipient of notifications during different phases of a run loop’s execution. semaphore A protected variable that restricts access to a shared resource. Mutexes and conditions are both different types of semaphore. signal A UNIX mechanism for manipulating a process from outside its domain. The system uses signals to deliver important messages to an application, such as whether the application executed an illegal instruction. For more information see the signal man page. signal dispatch source A dispatch source used to process UNIX signals. A signal source calls your custom event handler whenever the processreceives a UNIX signal. task A quantity of work to be performed. Although some technologies (most notably Carbon Multiprocessing Services) use this term differently, the preferred usage is as an abstract concept indicating some quantity of work to be performed. thread A flow of execution in a process. Each thread has its own stack space but otherwise shares memory with other threads in the same process. timer dispatch source A dispatch source used to process periodic events. A timer source calls your custom event handler at regular, time-based intervals. Glossary 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 86This table describes the changes to Concurrency Programming Guide . Date Notes Removed obsolete information about autorelease pool usage with operations. 2012-07-17 Updated the code for manually executing operations to handle cancellation correctly. 2011-01-19 Added information about using Objective-C objects in conjunction with dispatch queues. 2010-04-13 Updated to reflect support for iOS. Corrected the start method for the nonconcurrent operation object example. 2009-08-07 New document that describes technologies for executing multiple code paths in a concurrent manner. 2009-05-22 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 87 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, 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. 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, Carbon, Cocoa, Instruments, Mac, Objective-C, and OS X are trademarks of Apple Inc., registered in the U.S. and other countries. OpenCL is a trademark of Apple Inc. UNIX is a registered trademark of The Open Group. 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.ASARESULT, THISDOCUMENT 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. MainStage 2 User ManualCopyright © 2009 Apple Inc. All rights reserved. Your rights to the software are governed by the accompanying software license agreement. The owner or authorized user of a valid copy of Logic Studio software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid for support services. The Apple logo is a trademark of Apple Inc., registered in the U.S. and other countries. Use of the “keyboard” Apple logo (Shift-Option-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. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Note: Because Apple frequently releases new versions and updates to its system software, applications, and Internet sites, images shown in this manual may be slightly different from what you see on your screen. Apple 1 Infinite Loop Cupertino, CA 95014–2084 408-996-1010 www.apple.com Apple, the Apple logo, FireWire, GarageBand, Logic, Logic Studio, Mac, MainStage, Ultrabeat, and WaveBurner are trademarks of Apple Inc., registered in the U.S. and other countries. Finder is a trademark of Apple Inc. Intel, Intel Core, and Xeon are trademarks of Intel Corp. in the U.S. and other countries. Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products.Preface 7 Welcome to MainStage 7 About MainStage 8 About the MainStage Documentation 8 Additional Resources Chapter 1 11 Introducing MainStage 11 What Is MainStage? 13 Using MainStage with Keyboard Controllers 13 Using MainStage with Electric Guitars 13 Using MainStage with Vocals, Drums, and Other Instruments 13 How to Use MainStage in Your Music Setup 16 Using MainStage in Live Performance Chapter 2 17 Setting Up Your System 17 Using MIDI Devices with MainStage 19 Using Audio Devices with MainStage 19 Using Effects Plug-ins with MainStage 19 Using MainStage with Time Machine Chapter 3 21 The MainStage Interface 22 The MainStage Window 23 Layout Mode 24 Edit Mode 25 Perform Mode 26 Full Screen Mode 26 Customizing the MainStage Window Chapter 4 29 Getting Started with MainStage 29 Before You Begin 30 Opening MainStage 30 Choosing a Concert Template 31 Selecting Patch Settings in the Patch Library 32 Adding a Patch 33 Naming a Patch 3 Contents33 Selecting and Playing Patches 34 Adding a Channel Strip 36 Changing a Channel Strip Setting 37 Learning a Controller Assignment 39 Mapping a Screen Control 39 Trying Out Full Screen and Perform Modes Chapter 5 41 Working in Edit Mode 41 Working with Patches in Edit Mode 48 Working with Channel Strips in Edit Mode 69 Mapping Screen Controls 77 Editing Screen Control Parameters in Edit Mode 81 Working with Sets in Edit Mode 83 Working at the Set Level 84 Sharing Patches and Sets Between Concerts 85 Recording the Audio Output of a Concert Chapter 6 87 Working with Concerts 88 Opening and Closing Concerts 89 Saving Concerts 89 How Saving Affects Parameter Values 90 Setting the Time Signature for a Concert 91 Using Tempo in a MainStage Concert 92 Defining the Source for Program Change Messages for a Concert 93 Setting the Pan Law for a Concert 93 Changing the Tuning for a Concert 93 Silencing MIDI Notes 94 Muting Audio Output 95 Working at the Concert Level 101 Controlling the Metronome Chapter 7 103 Working in Layout Mode 104 Modifying the Layout of a Concert 104 Working with Screen Controls 114 Assigning Hardware Controls to Screen Controls 116 Editing Screen Control Parameters 121 How MainStage Passes Through MIDI Messages 122 Exporting a Layout 122 Importing a Layout 123 Changing the Aspect Ratio of a Layout Chapter 8 125 Playing Back Audio in MainStage 125 Adding a Playback Plug-in 4 Contents130 Using the Playback Plug-in Chapter 9 133 Performing Live with MainStage 133 Before the Performance Starts 134 Using Full Screen Mode and Perform Mode 135 Selecting Patches in Performance 136 Using Screen Controls in Performance 137 Handling Tempo Changes in Performance 137 Tips for Performing with Keyboard Controllers 137 Tips for Performing with Guitars and Other Instruments 138 Using the Tuner 139 Using the Playback Plug-in in Performance 140 Recording Your Performances 141 After the Performance 141 Tips for Complex Hardware Setups Chapter 10 143 Key Commands 143 Using the Command Editor 143 MainStage Default Key Commands Appendix A 147 The Playback Plug-in 148 Getting to Know the Playback Interface 149 Using the Playback Waveform Display 150 Using the Playback Transport and Function Buttons 151 Using the Playback Information Display 152 Using the Playback Sync, Snap To, and Play From Parameters 153 Using the Playback Group Functions 154 Using the Playback Action Menu and File Field 155 Using the Playback Shortcut Menu Appendix B 157 The Loopback Plug-in 158 Getting to Know the Loopback Interface 159 Using the Loopback Waveform Display 159 Using the Loopback Transport and Function Controls 160 Using the Loopback Information Display 161 Using the Loopback Sync, Snap To, and Play From Parameters 162 Using the Loopback Group Functions 163 Using the Loopback Action Menu 164 Adding Loopback to a Channel Strip Appendix C 165 Setting MainStage Preferences 165 General Preferences 166 Audio Preferences 168 MIDI Preferences Contents 5168 Display Preferences Appendix D 169 Using MainStage Actions 169 Table of Actions 6 ContentsMainStage turns your computer into a powerful and customizable musical instrument and effects processor that you can use with your music gear (your instruments, microphones, controllers, and other equipment) in live performance. This preface covers the following: • About MainStage (p. 7) • About the MainStage Documentation (p. 8) • Additional Resources (p. 8) About MainStage For performing musicians, MainStage gives you the power and flexibility of Logic Pro in an application optimized for live performance. Whether you are a keyboard player, guitarist, vocalist, drummer, or play another instrument, you can use MainStage in your live performance setup. Some of the things you can do with MainStage include: • Create custom sounds using a wide variety of software instruments and effects included in Logic Studio. You can also use third-party plug-ins, ReWire applications, and external sound modules. • Organize your sounds for easy access when you perform. • Create a visual layout that matches your hardware devices, putting the controls you need at your fingertips. • Connect MIDI devices to your MainStage concert so you can control parameters of your sounds in real time. • Trigger backing tracks and other audio files while you play. • Loop your performances to create multitextured, dynamic sound environments. • Record your performances in real time. This is only a brief list of what you can do with MainStage. For a more detailed introduction, see Introducing MainStage. 7 Welcome to MainStage PrefaceAbout the MainStage Documentation Logic Studio includes several documents that will introduce you to MainStage, help you get started working, and provide detailed information about the features and controls of MainStage. • MainStage User Manual: This onscreen manual (the MainStage User Manual) describes the MainStage interface, commands, and menus, and gives step-by-step instructions for creating MainStage concerts and for accomplishing specific tasks. It also includes information on setting up your system. It is designed to provide the information you need to get up to speed quickly so you can make use of the intuitive interface and powerful features of MainStage. If you want to start by learning how to set up audio and MIDI hardware to use with MainStage, read Setting Up Your System. If you want to learn about the features and controls in the MainStage interface, read The MainStage Interface. If you want to jump right in and start using the application, skip ahead to Getting Started with MainStage, then read the chapters on Edit mode, working with concerts, and Layout mode. If you want to read about using MainStage in live performance, turn to Performing Live with MainStage. • Exploring MainStage: This booklet introduces the basics of MainStage in an easy, approachable way. It aims to get new users up and running with MainStage quickly so you can have confidence and continue learning at your own pace. Each chapter presents major features and guides you in trying things out. This document is a PDF version of the printed Exploring MainStage document included in the Logic Studio package. • Logic Studio Instruments: This onscreen manual provides comprehensive instructions for using the powerful collection of instruments included with Logic Pro and MainStage. • Logic Studio Effects: This onscreen manual provides comprehensive instructions for using the powerful collection of effects included with Logic Pro, MainStage, and WaveBurner. • Logic Studio Working with Apogee Hardware: This onscreen manual describes the use of Apogee hardware with Logic Pro. Additional Resources Along with the documentation that comes with Logic Studio, there are a variety of other resources you can use to find out more. Release Notes and New Features Documents Each application offers detailed documentation that covers new or changed features and functions. This documentation can be accessed in the following location: • Click the Release Notes and New Features links in the application Help menu. 8 Preface Welcome to MainStageMainStage Website For general information and updates, as well as the latest news on MainStage, go to: • http://www.apple.com/logicstudio/mainstage Apple Service and Support Websites For software updates and answers to the most frequently asked questions for all Apple products, go to the general Apple Support webpage. You’ll also have access to product specifications, reference documentation, and Apple and third-party product technical articles. • http://www.apple.com/support For software updates, documentation, discussion forums, and answers to the most frequently asked questions for MainStage, go to: • http://www.apple.com/support/mainstage For discussion forums for all Apple products from around the world, where you can search for an answer, post your question, or answer other users’ questions, go to: • http://discussions.apple.com Preface Welcome to MainStage 9This chapter gives you a conceptual overview of MainStage and describes how you can use it together with your instruments and other musical equipment when you perform live. This chapter covers the following: • What Is MainStage? (p. 11) • Using MainStage with Keyboard Controllers (p. 13) • Using MainStage with Electric Guitars (p. 13) • Using MainStage with Vocals, Drums, and Other Instruments (p. 13) • How to Use MainStage in Your Music Setup (p. 13) • Using MainStage in Live Performance (p. 16) What Is MainStage? MainStage is a music application designed for you to use in live performance. MainStage turns your computer into a powerful multi-instrument and effects processor that you can use on stage when you perform. Whether you play a keyboard, guitar, another instrument, or sing, you can use MainStage with your instruments, microphones, and MIDI hardware when you perform live. MainStage lets you use the professional-quality instruments and effects included in Logic Studio in your live performances. You access and modify the instruments and effects in MainStage using the familiar Logic channel strip interface. If you play a USB or MIDI keyboard controller, you can play and control a wide variety of software instruments, including pianos and other keyboards, synthesizers, strings, horns, percussion, and more. If you play electric guitar, you can perform using Logic Studio effects setups, including amp simulation, overdrive, reverb, compression, and more. You can create your own effects setups and switch between them easily. Vocalists and acoustic musicians can also use effects setups with sound input through a microphone. 11 Introducing MainStage 1MainStage provides a flexible interface for organizing and accessing your sounds in concerts. Concerts are MainStage documents that hold your sounds—a concert can store all the sounds you’ll use in an entire performance or a series of performances. In a MainStage concert, individual sounds are stored as patches, and each patch can contain one or more channel strips, each with its own instruments and effects. You can add channel strips, choose channel strip settings, add instruments and effects, and edit their parameters to customize your sounds. You can even mix channel strips of different types in a single patch. You can organize patches in a concert by ordering them in the Patch List and also by grouping them into sets. Sets are folders where you can store patches you want to keep together. Each concert also includes a visual interface, called a layout, with controls that you can use to modify your patches in live performance. Layouts contain screen controls, which are onscreen representations of keyboards, faders, knobs, buttons, pedals, drum pads, and other hardware controls and displays. You make connections between your MIDI devices and your MainStage concert by assigning hardware controls to the screen controls in the concert. After you make these controller assignments, you map the screen controls to channel strip and plug-in parameters, completing the connection so that you can easily access and manipulate the parameters you want for each patch in the concert. You can also map screen controls to actions, which provide the ability to select patches, control the Tuner or metronome, provide visual feedback, and perform other functions. Parameter mapping MainStage screen control Channel strip or plug-in parameter Hardware control Controller assignment MainStage lets you quickly and easily make controller assignments and parameter mappings to speed your workflow. You can customize your layout to match the controls on your MIDI hardware, to optimize the use of available screen space, or in other ways that suit your needs. 12 Chapter 1 Introducing MainStageUsing MainStage with Keyboard Controllers If you perform using a USB or MIDI keyboard controller, you can play and control MainStage patches with software instruments using your controller. You can assign faders, knobs, buttons, and other controls on the keyboard controller to screen controls in your concert, and then map those screen controls to parameters in your patches. You can choose exactly the parameters you want to have at your fingertips for each patch and access them from your controller as you perform. You can use MainStage with other MIDI controllers, including sustain pedals, expression pedals, foot switches, MIDI guitars, and wind controllers that send standard MIDI messages. You can also control external hardware synthesizers, ReWire applications, and other virtual instruments using external instrument channel strips. Using MainStage with Electric Guitars If you play an electric guitar, you can use MainStage as a powerful, customizable multi-effects processor. After you connect your instrument to your computer using an audio interface, you send your guitar’s audio signal to audio channel strips in your patches, where you can add effects including the Amp Designer and Pedalboard plug-ins designed specifically for use with electric guitar. You can also use EQ, compression, reverb, overdrive, and other Logic Studio effects in your guitar patches. You can control volume, effect blend, or expression with an expression pedal, and use a foot switch to select patches hands-free when you perform. Using MainStage with Vocals, Drums, and Other Instruments Vocalists and acoustic musicians can use MainStage by sending the audio output from a microphone connected to their computer to audio channel strips in their patches. You can use MainStage with Core Audio-compatible audio devices, such as audio interfaces and digital mixers, for input from instruments and microphones, and for audio output to speakers, monitors, a mixing board, or a public address (PA) system. In MainStage, you can access a wide range of effects in your patches. Drummers can also use MainStage by sending the audio output from microphones to audio channel strips in their patches or by using drum pads or a virtual drum kit to control the EXS24 mkII sampler, Ultrabeat, and percussion-oriented plug-ins. How to Use MainStage in Your Music Setup You can add MainStage to your music equipment setup by following these steps: Chapter 1 Introducing MainStage 13Stage 1: Creating a Concert from a Template You begin working in MainStage by creating a new concert from a template. MainStage includes concert templates for keyboard, guitar, and other instruments, making it easy to choose a template suited to your needs. MainStage recognizes many popular MIDI controllers and automatically assigns hardware controls on the controller to corresponding screen controls in the workspace, simplifying hardware setup. For information about choosing a template to create a concert, see Choosing a Concert Template. Stage 2: Adding and Editing Patches to Customize Your Sounds After you create a concert, you add patches for the sounds you want to play, and edit the patches by adding channel strips, instruments, and effects, and adjusting their parameters to “dial in” your custom sounds. You edit and organize patches in Edit mode. In Edit mode, your patches are “live” so you can hear the results of your edits instantly. You can select and play patches, choose channel strip settings, and edit channel strip and plug-in parameters. You can quickly define key ranges for channel strips to create keyboard layers and splits, scale expression and other parameters using transforms, and filter incoming MIDI messages. For information about editing patches, see Working with Patches in Edit Mode. Stage 3: Organizing Your Patches for Easy Access When you open a concert in Edit mode, the patches in the concert appear in the Patch List, where you can select them and start playing. You can edit patch parameters, add channel strips to existing patches or create new ones, and reorder patches to build your custom collection of sounds to use when you perform. You can also organize patches in sets for added flexibility. Sets are like folders that can store groups of patches you want to keep together, which can be useful in several ways. For example, you can store all your favorite lead synth patches in a set or store multiple patches you intend to use in a single song, and quickly select the patches you want while performing. You can also add channel strips at the set level, and have them available with every patch in the set. For information about organizing patches, see Working with Patches in Edit Mode. For information about creating and editing sets, see Working with Sets in Edit Mode. 14 Chapter 1 Introducing MainStageStage 4: Customizing the Visual Layout of Your Concert to Match Your Hardware Devices In Layout mode, you arrange screen controls in the workspace to create the visual layout corresponding to your hardware controls. MainStage features a variety of screen controls, including keyboards, knobs, faders, pitch bend and modulation wheels, foot pedals, drum pads, and more. Also included are screen controls to display parameter and system informaton, text and images, and a selector that you can use to view and select patches or markers while performing. You can quickly add screen controls to the workspace, and move, resize, and copy them to create your layout. Alignment guides and other tools make it easy to visually arrange screen controls, and you can customize display color, text labels, and other parameters in the Screen Control Inspector. You can also group controls and arrange the grouped control as a single unit. For information about working with screen controls in Layout mode, see Working with Screen Controls. Stage 5: Making Connections Between MainStage and Your Music Hardware In Layout mode, you connect physical controls on your MIDI hardware to the screen controls in your concert by assigning the physical controls to the corresponding screen controls in the workspace. You can move and resize screen controls in the workspace and customize the display of visual feedback for parameter values and other information. You only need to make hardware controller assignments once for an entire concert, greatly reducing the amount of work required to connect your hardware with your computer. For information about making hardware assignments, see Assigning Hardware Controls to Screen Controls. Stage 6: Mapping Screen Controls to the Parameters You Want to Control in Performance Edit mode is where you map screen controls to channel strip parameters. You can map whichever parameters you want to modify for each patch to screen controls so they can be easily manipulated from your hardware when you perform live. You can also map screen controls to MainStage actions, such as selecting the next patch you want to play. For information about mapping screen controls, see Mapping Screen Controls. You need not follow these steps in a strict order; however, in most cases you will find working easier if you create your layout before making hardware assignments and make hardware assignments before you map screen controls. If you plan to use one of the existing concert templates without modifying its layout significantly, you can concentrate on stages 1 to 3 and stage 6. Chapter 1 Introducing MainStage 15To make setup easier, MainStage divides these tasks into two groups, with separate modes for each group of tasks. You customize and organize your patches in Edit mode and customize your layout and make connections with your hardware in Layout mode. The advantage of this division is that it separates tasks you normally perform only once, such as setting up your layout (the Layout mode tasks), from those you are likely to repeat more often, such as editing your sounds (the Edit mode tasks). Using MainStage in Live Performance After you have created a concert with your custom patches following the steps described above, you’re ready to play. When you perform live, you can use your computer as the final sound module and effects box in your rig. You can select a patch and start playing it instantly. MainStage switches seamlessly between patches and can sustain notes from the previous patch while you start playing the newly selected one. You can view feedback about your patches, including names, parameter values, and audio output levels, in real time. You can also adjust concert-wide effects using auxiliary channels and control other concert-wide settings. MainStage provides two modes optimized for performing live:Perform mode and Full Screen mode. In Perform mode, the workspace fills the MainStage window but lets you retain access to the Finder and to other applications. In Full Screen mode, the workspace fills your entire screen, optimizing available screen space for your onscreen layout. You can use whichever mode you prefer. You can use MainStage with multiple MIDI controllers, microphones, musical instruments, and other music equipment. For time-based effects such as reverb and delay, you can set a pre-defined tempo, use MIDI input for tempo changes, or tap the tempo as you perform. For tips and other information about using MainStage when you perform live, see Performing Live with MainStage. 16 Chapter 1 Introducing MainStageYou can use MainStage with a wide variety of MIDI controllers and Core Audio-compliant audio devices. For basic information about designing and configuring your system, including information about computer requirements, connecting audio and MIDI devices, and configuring your audio hardware, see the “Setting Up Your System” chapter in the Logic Pro User Manual. Real-time generation and processing of digital audio requires intensive processing by your computer. If you plan to work on large or complex projects, using a computer with a faster processor and extra random-access memory (RAM) installed can facilitate your productivity. Additional RAM is useful particularly when using a large number of effects plug-ins and when playing sample-based software instruments. It is recommended that you do not run other processor- or RAM-intensive applications simultaneously with MainStage, particularly when performing live. This chapter covers the following: • Using MIDI Devices with MainStage (p. 17) • Using Audio Devices with MainStage (p. 19) • Using Effects Plug-ins with MainStage (p. 19) • Using MainStage with Time Machine (p. 19) Using MIDI Devices with MainStage MainStage works with many USB and MIDI keyboard controllers and with other MIDI devices such as foot pedals and switches. To work with MainStage, MIDI devices must send standard MIDI control messages. MainStage receives standard MIDI messages and can be used to control external MIDI devices using external MIDI instrument channel strips. For more information about using keyboard controllers and other MIDI devices, see the “Setting Up Your System” chapter in the Logic Pro User Manual. 17 Setting Up Your System 2Using MIDI Devices That Send Special MIDI Message Types Certain types of hardware controls such as knobs (rotary controls) and buttons are capable of sending several types of MIDI messages. When you assign these controls to MainStage screen controls using the Learn process, MainStage analyzes the incoming MIDI data to determine which type of message the hardware control is sending. In order for MainStage to learn these controls correctly, be sure to turn knobs through their full range of motion and to press buttons exactly three times during the Learn process. Some MIDI controllers can send nonstandard or proprietary MIDI messages. MainStage cannot process or respond to nonstandard MIDI messages, to “registered” or “non-registered” parameter messages, or to system exclusive (SysEx) messages. MainStage can process some system real-time messages and MIDI Machine Control (MMC) messages when you assign a hardware control that sends these messages to a screen control. Some devices feature buttons that send program change messages. You can use these buttons to send program change messages to MainStage, but you cannot assign them to control other parameters using MainStage screen controls. Choosing a Controller Preset Some keyboard controllers allow you to choose different presets or “scenes” that reconfigure the messages sent by the controls on the device. In most cases, you should choose a generic preset that sends standard MIDI messages rather than system exclusive messages or messages intended for a particular application. After you have assigned hardware controls to screen controls in MainStage, do not change the preset on the MIDI device, or your assignments might be lost. In some cases, you can change the message type the controller sends by choosing a different preset or by reprogramming the device. Some devices may include software that you can use to reprogram knobs, buttons, and other controls. For information about reprogramming a MIDI device, see the documentation that came with the device. Using MIDI Devices That Support Automatic Configuration MainStage can automatically configure the screen controls in a concert to support many popular MIDI controllers. If you are using a device that supports automatic configuration, MainStage alerts you to select the appropriate preset on your device when you open a new concert. After you select the preset on your MIDI device, the screen controls in the concert are assigned to the corresponding controls on your hardware device so you can use them in MainStage with no further configuration. 18 Chapter 2 Setting Up Your SystemUsing Audio Devices with MainStage MainStage works with Core Audio-compliant audio devices, including FireWire, USB, ExpressCard, and PCI audio interfaces. You can connect microphones, electronic musical instruments, and other musical equipment to your computer, or to an audio interface or other audio device, and use them with MainStage. For detailed information about using audio devices, see the “Setting Up Your System” chapter in the Logic Pro User Manual. MainStage can require a large amount of available RAM, particularly when playing sample-based software instruments. It is recommended that you test your system and the concerts you plan to use before you perform using MainStage to make sure there is enough available memory to select and play the patches you want to use without causing audio drop-outs or distortion. Unlike in Logic Pro, you can choose different audio input and output drivers in MainStage. For more information about choosing audio drivers, see Setting MainStage Preferences. Using Effects Plug-ins with MainStage You can use all of the Logic Studio effects plug-ins, except for surround plug-ins, in MainStage channel strips. For more information about the included effects plug-ins, refer to the Logic Studio Instruments and Logic Studio Effects manuals. You can also use Apple and third-party Audio Units effects in MainStage channel strips in the same way you use them in Logic Pro channel strips. Some Logic Studio effects, including Space Designer, require intensive realtime processing of the audio signal. Using Space Designer on individual patches can affect the performance of your concert, and in some cases result in audio dropouts or glitches, particularly if you set the audio buffer to a smaller size. For this reason, it is recommended that you use Space Designer sparingly in your concerts, and use a few Space Designer instances on auxiliary channel strips shared between multiple patches, rather than in individual patches. Some Audio Units plug-ins can introduce latency. Using effects that introduce latency, such as compressors and limiters, can produce undesirable or unpredictable results during live performance. Other Audio Units plug-ins, particularly instrument and amp modelling plug-ins, require high levels of realtime processing and can affect the performance of your concert. Using MainStage with Time Machine If you use Time Machine to back up the computer you are using to perform with MainStage, be aware that if Time Machine runs while you are performing in Perform or Full Screen mode the performance of your MainStage concert could be affected. To avoid any impact on performance, it is recommended that you disconnect your Time Machine backup drive when you perform with MainStage. Chapter 2 Setting Up Your System 19You do all your work in MainStage in a single window, the MainStage window. The MainStage window is organized to make it easy to work with your patches and the layout of your concert. When you open MainStage, the workspace fills the center of the window, with Inspectors and other editing areas on the sides and below. When you are ready to perform, you can use one of two performance-oriented modes to maximize your computer performance and also maximize your display space for easy viewing on stage. The first time you open MainStage, the Choose Template dialog appears so that you can choose a concert template to create a new concert. To learn how to open MainStage, see Opening MainStage. For information about choosing a template, see Choosing a Concert Template. This chapter covers the following: • The MainStage Window (p. 22) • Layout Mode (p. 23) • Edit Mode (p. 24) • Perform Mode (p. 25) • Full Screen Mode (p. 26) • Customizing the MainStage Window (p. 26) 21 The MainStage Interface 3The MainStage Window Some features of the MainStage interface are common to all modes, while others are exclusive to certain modes. Inspector Workspace with Toolbar Activity Monitor screen controls The main features of the MainStage window include: • Toolbar: Includes buttons for quick access to common commands and tools. You can customize the toolbar so that the commands you use most frequently are readily available. • Activity Monitor: Shows your computer’s processor and memory usage, and shows the input from your MIDI devices as you edit and perform. • Workspace: The “canvas” where you customize your onscreen layout, assign hardware controls to screen controls, and view your concerts while you perform. • Screen controls: The onscreen objects that correspond to the controls on your hardware devices. You can add and arrange screen controls in the workspace, assign hardware controls to screen controls, and then map them to parameters you want to control for each patch in your concert. There are three types of screen controls: panel controls, shelf controls, and grouped controls. • Channel strips: Channel strips are where you build and customize your sounds. MainStage channel strips are similar to channel strips in Logic Pro, with Insert, Sends, and I/O menus as well as level meters, faders, pan knobs, and other controls. 22 Chapter 3 The MainStage Interface• Inspectors: Inspectors appear below (in Edit mode) or along the left side of the MainStage window (in Layout mode) when you select different items onscreen. The Inspectors allow you to edit parameters and attributes for patches, sets, screen controls, channel strips, and the concert. Most Inspectors feature tabs that make it easy to quickly access the parameters you want to edit. To make working easier, MainStage features four different modes, each suited to a different task. You audition, edit, and organize your sounds and map screen controls in Edit mode. You customize the visual arrangement of controls onscreen and make controller assignments in Layout mode. You use either Perform mode or Full Screen mode when you perform live. Layout Mode Layout mode is where you customize your onscreen layout and make connections between your MIDI hardware and the screen controls in your concert. You drag screen controls into the workspace and arrange them onscreen to customize your layout, then create connections (called controller assignments) between your MIDI hardware and the screen controls. In the Screen Control Inspector, you can edit layout parameters to customize hardware assignments and modify the visual look of the screen controls in your concert. Screen Control Inspector Screen Controls Palette • Screen Control Inspector: View and edit parameters for screen controls in the workspace, including hardware input, appearance, and certain types of MIDI output parameters. Chapter 3 The MainStage Interface 23• Screen Controls Palette: Drag screen controls from the palette into the workspace to add them to your onscreen layout. The palette has four tabs so that you can quickly view all screen controls or only one type of screen control. Panel controls appear as two-dimensional objects in the workspace, while shelf controls appear on an adjustable three-dimensional shelf. • Layout buttons: Along the left side of the workspace is a series of buttons that you can use to quickly position selected screen controls in the workspace. You can align, distribute, and group selected screen controls. In Layout mode, unlike the other modes in MainStage, you can’t select or edit individual patches. To learn what you can do in Layout mode, see Working in Layout Mode. Edit Mode Edit mode is where you create, customize, and organize your sounds. You can add patches, add and edit channel strips, create keyboard layers and splits, and edit channel strip and plug-in parameters. Edit mode is also where you map screen controls to channel strip parameters and actions, and edit patch, set, and concert-level parameters. Patch List Inspector (changes depending on the selection) Channel Strips area • Patch List: Shows the patches and sets in the concert. You can add patches and sets to the Patch List, name them, and organize them. The Patch List includes an Action menu with commands to create patches and sets, reset program change numbers, skip items, and import and export patches and sets to use in other concerts. 24 Chapter 3 The MainStage Interface• Inspector (varies depending on the type of item selected): View and edit parameters for the currently selected patch, channel strip, screen control, set, or for the concert. The name of the Inspector changes to identify the type of item you are currently inspecting. • Channel Strips area: View and edit the channel strips in your patches or at the concert or set level. Channel strips appear in a vertical format similar to Logic Pro channel strips, with many of the same controls. You can also add channel strips and save channel strip settings. To learn what you can do in Edit mode, see Working in Edit Mode and Working with Concerts. The remaining two modes, Perform mode and Full Screen mode, are both optimized for performing live. You can use either one when you perform. Perform Mode In Perform mode, the workspace fills the entire MainStage window. The toolbar is visible so that you can switch modes using the Mode buttons, use the Panic or Master Mute buttons and the Tuner, and view CPU and memory levels and MIDI input in the Activity Monitor. The browsers and Inspectors are hidden to maximize the size of the workspace, making screen controls larger and easier to read in onstage situations. You can still access the Finder and switch to other applications in Perform mode but cannot open plug-in windows. Chapter 3 The MainStage Interface 25Full Screen Mode In Full Screen mode, the workspace fills your entire computer display so that your screen controls are as large as possible for maximum readability. Full Screen mode optimizes your display for live performance when you want to use MainStage exclusively while you play. Plug-in windows cannot be open in Full Screen mode. To learn about using Perform mode and Full Screen mode when you perform live, see Performing Live with MainStage. Customizing the MainStage Window You can customize the MainStage window to suit your way of working. In Edit mode, you can adjust the width of the Patch List, show or hide the Inspectors and the Channel Strips area, and customize the buttons on the toolbar. Resizing the Workspace You can adjust both the horizontal and vertical size of the workspace to give more room to the Patch List, the Inspector, and the Channel Strips area. To resize the workspace horizontally 1 Move the pointer to the space between the workspace and the Inspector. The pointer becomes a resize pointer. 2 Drag up or down to resize the workspace. To resize the workspace vertically 1 Move the pointer to the space between the workspace and the Channel Strips area. 26 Chapter 3 The MainStage InterfaceThe pointer becomes a resize pointer. 2 Drag left or right to resize the workspace. Hiding and Showing the Inspector You can hide the Inspector or show it if it is hidden. To hide or show the Inspector Do one of the following: µ Choose View > Inspectors (or press Command-5). µ In the toolbar, click the Inspectors button. Hiding and Showing the Channel Strips Area You can hide the Channel Strips area or show it if it is hidden. Hiding the Channel Strips area gives you more room for the workspace. To hide or show the Channel Strips area Do one of the following: µ Choose View > Channel Strips (or press Command-6). µ In the toolbar, click the Channel Strips button. Customizing the Toolbar The toolbar at the top of the MainStage window contains buttons for frequently used commands. You can customize the toolbar, adding buttons for the functions you use most often and can return to the default set later. The default set of toolbar buttons includes buttons for selecting the different window modes, hiding the Inspector and the Channel Strips area, activating Master Mute, and other common commands. You can customize the toolbar with additional buttons for other commands and adjust the position and spacing of items. You can also hide the toolbar to maximize available screen space. You customize the toolbar by dragging items from the Customize Toolbar dialog to the toolbar. To show the Customize dialog Do one of the following: µ Choose View > Customize Toolbar. µ Control-click the toolbar, then choose Customize Toolbar from the shortcut menu. The Customize Toolbar dialog appears, and spaces between buttons in the toolbar are outlined in gray. Chapter 3 The MainStage Interface 27To add a button to the toolbar µ Drag a button from the Customize dialog to the toolbar. If you drag a button between two existing buttons, the buttons move to make room for the new button. To move a button in the toolbar Do one of the following: µ If the Customize Toolbar dialog is visible, drag the button to move it. µ If the Customize Toolbar dialog is not visible, Command-drag the button to move it. You can also rearrange the toolbar using set-width spaces, flexible spaces, and separators. To add a space or a separator to the toolbar µ Drag a space, flexible space, or separator from the Customize Toolbar dialog to the toolbar. To return the toolbar to the default set of buttons µ Drag the default button set, located at the bottom of the Customize Toolbar dialog, to the toolbar. You can also change the toolbar so that it shows only icons or only text by Control-clicking the toolbar, then choosing Icon Only or Text Only from the shortcut menu. To show only icons in the toolbar Do one of the following: µ Control-click the toolbar, then choose Icon Only from the shortcut menu. µ In the Customize Toolbar dialog, choose Icon Only from the Show pop-up menu. To show only text in the toolbar Do one of the following: µ Control-click the toolbar, then choose Text Only from the shortcut menu. µ In the Customize Toolbar dialog, choose Text Only from the Show pop-up menu. To show both icons and text in the toolbar Do one of the following: µ Control-click the toolbar, then choose Icon & Text from the shortcut menu. µ In the Customize Toolbar dialog, choose Icon & Text from the Show pop-up menu. To close the Customize dialog µ When you are finishing customizing the toolbar, click Done. To hide the toolbar µ Choose View > Hide Toolbar. When the toolbar is hidden, the menu item becomes Show Toolbar. 28 Chapter 3 The MainStage InterfaceYou can quickly start working in MainStage by choosing a concert template and trying out the patch settings in the concert. This chapter provides a brief guided “walkthrough” you can follow the first time you open MainStage. If you wish to continue learning the major features of the application in a hands-on manner, consult the Exploring MainStage guide included in the Logic Studio package. This chapter covers the following: • Before You Begin (p. 29) • Opening MainStage (p. 30) • Choosing a Concert Template (p. 30) • Selecting Patch Settings in the Patch Library (p. 31) • Adding a Patch (p. 32) • Naming a Patch (p. 33) • Selecting and Playing Patches (p. 33) • Adding a Channel Strip (p. 34) • Changing a Channel Strip Setting (p. 36) • Learning a Controller Assignment (p. 37) • Mapping a Screen Control (p. 39) • Trying Out Full Screen and Perform Modes (p. 39) Before You Begin Before you start working in MainStage, you should connect the hardware equipment that you plan to use, such as your keyboard controller, audio interface, instruments, or microphones, to your computer. To use keyboard controllers and other MIDI devices with MainStage, the devices should be capable of sending standard MIDI messages. If you’re not sure whether this is the case for a particular device, consult the owner’s manual or the product website. For more information, see Setting Up Your System. 29 Getting Started with MainStage 4Opening MainStage You start by opening MainStage and creating a new concert from a template. To open MainStage µ Double-click the MainStage icon in your Applications folder or in the Dock. Choosing a Concert Template MainStage includes templates for different musical instruments, including Keyboards, Guitar Rigs, Drums, Vocals, and more. You can choose a concert template in the Choose Template dialog, which appears the first time you open MainStage and when you create a new concert or close a concert. To choose a concert template 1 Choose File > New Concert (or press Command-N). 2 In the Choose Template dialog, click the instrument category on the left you want to view templates for. A brief description below each template describes its features and intended use. 30 Chapter 4 Getting Started with MainStage3 Scroll through the available templates to find the one you want to use. 4 Click Choose, or double-click the template. A new concert created from the template opens in Edit mode. The workspace appears in the center of the MainStage window, showing the screen controls in the concert. To the left of the workspace is the Patch List, which shows the patches and sets in the concert. The channel strips for the selected patch appear in the Channel Strips area to the right of the workspace. The new concert may contain a single patch, or several patches. Below the workspace, the Patch Library is open, so you can easily audition different patch settings to find the one you want to use. In the Choose Template dialog, you can view templates in either a grid or a Cover Flow view. You can choose a different view using the view buttons, located in the lower-left part of the dialog. To choose a different view for the Choose Template dialog µ To view templates in a grid, click the Grid button. µ To view templates in Cover Flow, click the Cover Flow button. For more information about opening, editing, and saving concerts, see Working with Concerts. Selecting Patch Settings in the Patch Library When you open a concert or select a patch, the Patch Library opens in the Patch Inspector below the workspace. The Patch Library contains a variety of patches optimized for the instrument the concert is designed for. You can quickly audition patch settings in the Patch Library and choose a setting for the selected patch. To select a patch setting 1 Look through the settings in the Patch Library to find the one you want to use. 2 Click the patch setting. You can start playing the patch immediately using the selected patch setting. You can also search for patch settings by name. To search for patch settings by name 1 Choose Find in Library from the Action menu in the upper-right corner of the Patch Inspector. 2 Enter the name of the patch setting you want to find. 3 Click Find. The first patch setting with the text you entered appears selected in the Patch Library. Chapter 4 Getting Started with MainStage 314 To find subsequent patch settings with the same name, choose Find Again in Library from the Action menu. Note: If you have saved multiple patches to a .patch file using the Save as Set command (or the Export as Set command in MainStage 1.0) in the Action menu, the saved file appears as a patch in the Patch Library unless you have selected a different location for saving the file. Clicking the saved file in the Patch Library causes an alert to appear while the individual patches are opened from the .patch file. Adding a Patch You can add patches to the concert and organize them in the Patch List. The number of patches is limited only by the amount of available memory in your system. When you add a patch to a concert, the patch is selected so you can easily audition and select a patch setting from the Patch Library. To add a new patch 1 Click the Add Patch button (+), located in the upper-right corner of the Patch List. The new patch appears in the Patch List, and the Patch Library is open in the Patch Inspector. 2 Select the patch setting you want to use from the Patch Library. If you want to play the patch using your keyboard controller, select a Keyboard patch. If you want to play the patch using your electric guitar, select a Guitar Rig patch. For other instruments or vocals, you can choose a template from the appropriate category or modify a keyboard or guitar template to suit your needs. 3 If the patch uses an audio channel strip, make sure the channel strip is set to use the correct audio input, then gradually raise the volume fader on the channel strip until you hear sound on the channel. 32 Chapter 4 Getting Started with MainStageNaming a Patch When you add a patch, by default it takes the name of the channel strip added with it. You can give each patch a custom name to make it easier to identify and distinguish between them. To name a patch 1 Double-click the patch in the Patch List. A field appears around the patch name, which is selected. Double-click the patch name, then type a new name. 2 Type a new name in the patch name field. For more information about editing and organizing patches, see Working with Patches in Edit Mode. Selecting and Playing Patches The patches in the concert appear in the Patch List along the left side of the MainStage window. You can easily access the patches in your concert by selecting them in the Patch List. You can quickly select patches by clicking them in the Patch List. If you are using a MIDI controller, you can play patches that have a software instrument channel strip using your controller. If you are playing an electric guitar or another instrument or are using a microphone connected to an audio interface, you can play or sing using patches that have an audio channel strip. Before playing through an audio channel strip, first make sure that the channel strip is set to receive input on the channel (or stereo pair of channels) to which your instrument or microphone is connected. With the patch selected, try moving some controls on your MIDI controller and check to see if the screen controls in the workspace respond. Some screen controls, including the keyboard, modulation and pitch bend wheels, and sustain pedal screen controls, respond to appropriate MIDI messages without needing to be assigned or mapped. Chapter 4 Getting Started with MainStage 33You can continue selecting and playing patches in the concert to find sounds you want to perform with or to use as a starting point for creating your own custom patches. You can also add new patches and edit their channel strip settings to create your own unique sounds. For more information about organizing and selecting patches in the Patch List, see Working with Patches in Edit Mode. Adding a Channel Strip You can add channel strips to a patch to create layered sounds and keyboard splits. When you add a channel strip to a patch, you choose the type of channel strip, the output, and other settings. You can mix both types in a single patch. To add a channel strip to a patch 1 Make sure the patch is selected in the Patch List. 2 Click the Add Channel Strip button (+) in the upper-right corner of the Channel Strips area. The New Channel Strip dialog appears. You choose settings in the Channel Strip dialog in the same way as when you add a patch. 3 In the New Channel Strip dialog, select the type of channel strip you want to create. 4 Choose the audio output for the channel strip from the Output pop-up menu. 5 For audio channel strips, choose mono or stereo format from the Format pop-up menu and choose the audio input from the Input pop-up menu. For external instrument channel strips, also choose the MIDI input, MIDI output, and MIDI channel from their respective pop-up menus. Important: Audio channel strips can produce feedback, particularly if you are using a microphone for audio input. When you add an audio channel strip, the volume of the channel strip is set to silence, and Feedback Protection is turned on to alert you when feedback occurs on the channel strip. When you add an external instrument channel strip, the volume of the channel strip is set to silence, but Feedback Protection is turned off. 6 Optionally, you can add multiple channel strips to a patch by typing a number in the Number field. You can add up to the maximum number for a channel strip type. 7 Click Create. A new channel strip appears in the Channel Strips area, highlighted in white to indicate that it is selected. The Channel Strip Inspector appears below the workspace, showing different parameters for the new channel strip. 34 Chapter 4 Getting Started with MainStage8 For audio and external instrument channel strips, gradually raise the volume fader until you hear sound on the channel. Most channel strip controls function in MainStage in the same way that they do in Logic Pro. You can adjust channel strip output using the Volume fader, adjust pan position using the Pan knob, and mute or solo the channel strip using the Mute and Solo buttons. You can choose new channel strip settings, add and edit effects, add sends to busses, and change the output in the same way as in Logic Pro. For audio channel strips, you can switch between mono and stereo format using the Format button. For software instrument channel strips, you can choose a different instrument from the Input pop-up menu. You can also define the key range for a channel strip, create transform and velocity graphs, and filter various MIDI messages to a channel strip in the Channel Strip Inspector. For general information about working with channel strips, see the “Working with Instruments and Effects” chapter of the Logic Pro User Manual. For more information about using channel strips in MainStage, see Working with Channel Strips in Edit Mode. Chapter 4 Getting Started with MainStage 35Changing a Channel Strip Setting You can quickly change the instrument, effects, and other parameters for a channel strip by selecting a new setting from the Channel Strip Library. The browser shows available settings for the currently selected channel strip. To select a new channel strip setting 1 Make sure that the channel strip you want to change is selected. The selected channel strip is highlighted. 2 In the Channel Strip Inspector, click the Channel Strip Library tab. Available channel strip settings appear in the Channel Strip Library. Logic Studio content appears as a series of folders with different instrument and usage categories. If you have GarageBand or have one or more Jam Pack collections installed on your computer, those settings appear below the Logic Studio settings. 3 Click a category from the column on the left, then click subcategories from the columns on the right until you see the settings you want. Click a category in this column to see the available choices. Click the channel strip setting you want to use from the columns to the right. You can also search for channel strip settings by name and perform other functions using the Channel Strip Library. For more information about the Channel Strip Inspector, see Choosing Channel Strip Settings. 36 Chapter 4 Getting Started with MainStageLearning a Controller Assignment When you select a patch or a channel strip setting, some channel strip parameters respond to the controls on your MIDI device instantly. MainStage responds to notes played on a keyboard controller, volume, pan, and expression messages, modulation and pitch bend wheel messages, and sustain pedal messages without your having to configure any screen controls to receive these messages. For other controls such as faders, knobs, and buttons, you must assign these hardware controls to MainStage screen controls before you can use them in your concert. In MainStage, you assign hardware controls to screen controls in the Layout Inspector using the Learn process, similar to learning controller assignments for a control surface in Logic Pro. Learning controller assignments is a quick and easy method for assigning hardware controls to screen controls. Note: To be able to assign a hardware control to a screen control, the hardware control must send standard MIDI messages. For more information, see Using MIDI Devices with MainStage. To learn a controller assignment 1 In the toolbar, click the Layout button. MainStage switches to Layout mode. 2 In the workspace, select the screen control you want to learn. The selected control appears highlighted in blue. 3 Click the Learn button in the Screen Control Inspector (or press Command-L). Chapter 4 Getting Started with MainStage 37The Learn button glows red to indicate that the Learn process is active, and the selected screen control is highlighted in red. Click the Learn button to start learning hardware assignments. 4 On your MIDI device, move the control you want to assign. Move faders and knobs through their full range of motion, and press buttons exactly three times (not too quickly) to enable MainStage to correctly learn the MIDI message types sent by these controls. The values in the Hardware Assignment pop-up menus change to reflect the type of hardware control learned by the screen control. While the assignment is being learned, incoming MIDI messages appear in the Activity Monitor above the workspace. After the assignment is learned, the screen control responds when you move the corresponding hardware control. This shows that the screen control is receiving MIDI input and is correctly assigned. 5 While the Learn process is active, you can learn additional controller assignments by selecting another screen control and moving the hardware control you want to assign to it. You can learn as many assignments as you wish while the Learn button remains red. 6 When you are finished assigning controls, click the Learn button (or press Command-L) again to turn off the Learn process. For more information about making controller assignments, see Assigning Hardware Controls to Screen Controls. 38 Chapter 4 Getting Started with MainStageMapping a Screen Control After you have learned controller assignments for the screen controls you want to use, you can map the screen controls to the parameters in your patches you will want to control while you are performing. You will likely want to map screen controls to parameters in each patch in a concert, so that you can easily access and modify the parameters you want for each patch when you are performing live. You can also map parameters at the concert level to control master volume, view master levels, or modify concert-wide effects. There are two ways to map screen controls to parameters: by visually selecting parameters on channel strips or plug-in windows, or by choosing parameters in the Parameter Mapping browser. To learn how to map a screen control to a channel strip or plug-in parameter, see Mapping Screen Controls to Channel Strip and Plug-In Parameters. To learn how to map a screen control to an action, see Mapping Screen Controls to Actions. Trying Out Full Screen and Perform Modes Now you can try playing your patches as you would in a performance. MainStage provides two modes, Full Screen mode and Perform mode, that optimize the display of the workspace for live performance. In Perform mode, you see the workspace and the toolbar, so you can use the toolbar buttons and access other applications. In Full Screen mode, the workspace occupies the entire screen, presenting the screen controls as large as possible for easy viewing in concert environments. To switch to Full Screen mode Do one of the following: µ Choose View > Full Screen (or press Command-4). µ Click the Full Screen button. To switch to Perform mode Do one of the following: µ Choose View > Perform (or press Command-3). µ Click the Perform button. You can try both of these modes, playing the patches you added or modified, and using the controls on your MIDI controller to modify the parameters you have mapped to screen controls. Chapter 4 Getting Started with MainStage 39In Edit mode, you add and edit patches to create your custom sounds, choose patch settings in the Patch Library, organize and select patches in the Patch List, edit patch parameters in the Inspector, and map screen controls to parameters and actions. You can create custom patches in Edit mode and organize them in the Patch List so that you can easily access them when you perform. This chapter covers the following: • Working with Patches in Edit Mode (p. 41) • Working with Channel Strips in Edit Mode (p. 48) • Mapping Screen Controls (p. 69) • Editing Screen Control Parameters in Edit Mode (p. 77) • Working with Sets in Edit Mode (p. 81) • Working at the Set Level (p. 83) • Sharing Patches and Sets Between Concerts (p. 84) • Recording the Audio Output of a Concert (p. 85) Working with Patches in Edit Mode Patches are the individual sounds you play using your keyboard controller (for MIDI keyboardists) and the effects setups you use with your guitar, microphone, or other instrument (for guitarists, vocalists, and other instrumentalists). MainStage patches can contain multiple channel strips, each with a different instrument or effects setup. Some basic patch operations, including adding and naming patches, selecting and naming patches, and adding channel strips to patches, are described in Getting Started with MainStage. If MainStage is currently in Layout, Perform, or Full Screen mode, click the Edit button in the top-left corner of the MainStage window to begin working in Edit mode. 41 Working in Edit Mode 5Selecting Items in the Patch List All of the patches and sets in a concert appear in the Patch List, located to the left of the workspace. To select an item in the Patch List in Edit mode, you can click the item or use key commands. To select a patch in the Patch List 1 In the Patch List, located to the left of the workspace, click the patch. Click a patch in the Patch List to select it, and start playing. 2 With the patch selected, you can start playing instantly. You can also select patches in the Patch List using your computer keyboard. To select a patch using your computer keyboard µ Press the Down Arrow key to select the next (lower) patch in the Patch List. µ Press the Up Arrow key to select the previous (higher) patch in the Patch List. There are additional key commands you can use to select items in the Patch List. Default key command Selects Up Arrow Previous item (patch or set) in the Patch List Down Arrow Next item (patch or set) in the Patch List Command-Up Arrow Previous patch in the Patch List Command-Down Arrow Next patch in the Patch List Command-Left Arrow First patch of the previous set Command-Right Arrow First patch of the next set Note: When you use the Command-Arrow key commands listed above to select different patches, the selected screen control remains selected in the workspace. This makes it easy to see how a screen control is configured in different patches. In addition to using key commands, you can select a patch (or set) in the Patch List by typing the first few letters of its name. 42 Chapter 5 Working in Edit ModeTo select a patch or set by typing its name 1 Click the border of the Patch List to select it. 2 With the Patch List selected, start typing the name of the patch. Once you type enough letters to uniquely identify its name, the patch or set is selected. You can also select a patch by typing its name in Perform or Full Screen mode. For information, see Selecting Patches by Typing. You can also select a patch using your computer keyboard by typing its patch number. Patch numbers appear to the left of the patch names in the Patch List. To select a patch by typing its patch number 1 Click the border of the Patch List to select it. 2 With the Patch List selected, type the patch number using your computer keyboard. Skipping Items in the Patch List You can skip patches or sets in the Patch List. When a patch or set is skipped, you can still select the item by clicking it. However, when you use the arrow keys together with the Command key to select items in the Patch List, skipped items are passed over and the next non-skipped item is selected. Skipped items are also skipped when you use the patch selector in Full Screen or Perform mode. To skip a patch or set 1 Select the patch or set in the Patch List. 2 Choose Skip from the Action menu for the Patch List. The item appears as a thin line in the Patch List. To set a skipped patch or set to no longer be skipped 1 Select the item (patch or set) in the Patch List. 2 Choose Don’t Skip from the Action menu for the Patch List. The item returns to full size in the Patch List. Patches and sets are skipped only when you use the arrow keys together with the Command key. Items set to be skipped are still selected when you use the arrow keys alone or when you click them. Collapsing Sets in the Patch List You can collapse sets in the Patch List. When you collapse a set, you can select the set and use any channel strips or busses at the set level but cannot select or play patches in the set while in Edit mode. To collapse a set µ In the Patch List, click the disclosure triangle for the set. Chapter 5 Working in Edit Mode 43You can uncollapse the set by clicking its disclosure triangle again. Collapsing a set has no effect on whether you can select patches in the set in Full Screen or Perform mode. For information about creating and using sets, see Working with Sets in Edit Mode. Copying and Pasting Patches You can copy, paste, and duplicate patches in the Patch List using the standard Mac OS X menu and key commands or by Option-dragging. When you paste or duplicate a patch, it includes any mappings made to parameters in the original patch. Reordering Patches in the Patch List When you add a patch to a concert, the new patch appears below the currently selected patch in the Patch List. You can reorder patches in the Patch List. To reorder patches in the Patch List µ Drag patches up or down in the Patch List until they appear in the order you want. Moving Patches in the Patch List Repeatedly The MainStage command set includes a Move Again command that lets you easily move selected patches multiple times. You can use Move Again when you drag, paste, create, or delete patches in the Patch List. By default, the Move Again command is not assigned to a key command. To use it, you should first assign it to a key command in the Command Editor. For information about using the Command Editor, see Using the Command Editor. Creating a Patch from Several Patches You can create a patch by combining several existing patches. The new patch contains all of the channel strips of the selected patches. To create a patch from several existing patches 1 In the Patch List, select the patches you want to use to create the new patch. 2 Choose “Create Patch from Selected Patches” from the Action menu at the upper-right corner of the Patch List. The new “combined” patch appears in the Patch List, labeled “Untitled Patch.” Note: Creating a patch with more than three channel strips can affect performance, particularly if the channel strips are audio channel strips, or if they use a large number of plug-ins or processor-intensive plug-ins. Setting the Time Signature for a Patch You can set the time signature for a patch. Time signatures can be used with the Playback plug-in and also control the beats for the metronome. When you set the time signature for a patch, it overrides any concert- or set-level time signature. To set the time signature for a patch 1 In the Patch Inspector, select the Attributes tab. 44 Chapter 5 Working in Edit Mode2 In the Attributes tab, select the Has Time Signature checkbox. 3 Double-click the number in the field to the right, and enter the number of beats for one measure of the time signature. 4 Choose the beat value from the pop-up menu to the right. Changing the Tempo When You Select a Patch You can give a patch its own tempo setting so that when you select the patch, the tempo changes to the patch tempo setting. MainStage uses the new tempo until you select another patch or set with its own tempo setting, tap a new tempo, or until MainStage receives tempo information from incoming MIDI messages. For more information about using and changing tempo in MainStage, see Using Tempo in a MainStage Concert. To change the tempo using a patch 1 In the Attributes tab of the Patch Inspector, set the patch tempo using the Change Tempo To value slider. 2 Select the Change Tempo To checkbox to activate the patch tempo when the patch is selected. Select the checkbox and set the tempo using the slider. Setting Patch Program Change Numbers When you add a patch to a concert, the patch is given a MIDI program change number (the lowest available number between 0 and 127) until all available program change numbers are taken. You can select patches using program change numbers when performing by assigning buttons on a MIDI device to send program change messages. You can change the program change number in the Patch Inspector. To change the program change number for a patch 1 In the Patch List, select the patch. When you select a patch, the Patch Inspector appears below the workspace. 2 In the Attributes tab of the Patch Inspector, select the Program Change checkbox. 3 Using the value slider, set the program change number. Chapter 5 Working in Edit Mode 45The MIDI standard allows program change numbers with values from 0 to 127. If all available program change numbers in a concert are already in use, any new patches added to the concert will be given program change number zero (0), but the number is inactive (the checkbox is not selected). Bank changes are not supported. If you set a program change number so that it duplicates an existing program change number, the word “Duplicate” appears in red next to the Program Change value slider. If two or more patches have the same program change number, and the numbers are active, the patch that appears first (highest) in the Patch List or patch selector is selected when you send the program change message with the corresponding value. You can reset program change numbers for all active (non-skipped) patches in a concert. When you reset program change numbers, patches are assigned program change numbers based on their order in the Patch List, starting from the top. The program change numbers for skipped (inactive) patches are not reset. To reset program change numbers for active patches in a concert µ Choose Reset Program Change Numbers from the Action menu for the Patch List (or press Command-Shift-Option-R). You can assign buttons and other controls to send program change messages and use them to select patches in the concert. For information about assigning buttons, see Assigning Buttons. Deferring Patch Changes By default, when you switch patches, the new patch is ready to play immediately. You can “defer” a patch change so that the patch change occurs after the last note of the previous patch has been released or sustained. To defer a patch change µ In the Attributes tab of the Patch Inspector, select the Defer Patch Change checkbox. Note: Deferring patch change works in Perform mode and Full Screen mode but does not work when you are editing patches in Edit mode. Instantly Silencing the Previous Patch Sometimes you may want the sound of the previous patch to continue after you select a new patch, as when you want to sustain a chord pad while soloing over it. At other times, you may want to silence the sound of the previous patch instantly when you select a new patch. To instantly silence the previous patch when you select a patch µ In the Attributes tab of the Patch Inspector, select the Instantly Silence Previous Patch checkbox. 46 Chapter 5 Working in Edit ModeChanging the Patch Icon Each patch has an icon that appears in the Patch List next to the patch name. By default, the patch icon shows the type of channel strip created when the patch was added. You can choose a new icon for a patch and use icons to visually distinguish patches in the Patch List. To change the icon for a patch µ In the Attributes tab of the Patch Inspector, choose an icon from the Icon pop-up menu. Changing the Tuning for a Patch By default, patches use the same tuning method as the concert (or the set, if they are in a set with its own tuning method). You can change the tuning for a patch so that it uses a different tuning. When you change the tuning for a patch, it overrides any concert- or set-level tuning method. To change the tuning for a patch 1 In the Patch Inspector, select the Tuning tab. 2 Choose the tuning you want the patch to use from the Method pop-up menu. Deleting Patches You can delete a patch if you decide you no longer want it in the concert. To delete a patch 1 Select the patch in the Patch List. 2 Choose Edit > Delete (or press the Delete key). Chapter 5 Working in Edit Mode 47Working with Channel Strips in Edit Mode Channel strips are the building blocks of your patches. They contain the instruments and effects for the sounds you use in performance. MainStage channel strips use the channel strip interface familiar from Logic Pro. MainStage channel strips have the same structure and many of the same functions as Logic Pro channel strips. The main features of MainStage channel strips are shown below: Settings menu Pan knob Icon Name Mute and solo buttons Insert slots Send slots Volume fader and level meter In MainStage, you can use audio, software instrument, and auxiliary (aux) channel strips in your patches and sets, and also at the concert level. You can also use external instrument patches to “play” external hardware devices and ReWire applications. You can use channel strips in MainStage just as you can in Logic Pro. You can adjust the volume level using the Volume fader, adjust the pan position using the Pan knob, and mute or solo the channel strip using the Mute and Solo buttons. 48 Chapter 5 Working in Edit ModeA MainStage concert can have a maximum of 1023 software instrument channel strips, 512 audio channel strips, 256 external instrument channel strips, and 256 auxiliary (aux) channel strips. As in Logic Pro, you can add effects using the Insert slots, send the signal to an auxiliary channel (aux) using the Sends slots, and choose a different output from the Output slot. For audio channel strips, you can change the format between mono and stereo using the Format button. For software instrument channel strips, you can change the instrument using the Input slot. You can also choose, copy, and save channel strip settings, choose a different channel strip type, or reset the channel strip from the channel strip menu. Because MainStage is designed for live performance rather than recording and arranging, there are a few differences between MainStage channel strips and Logic Pro channel strips: • MainStage channel strips include an Expression dial so that you can easily see the current MIDI Expression being received by the channel strip. • MainStage channel strips do not have a Record Enable or Bounce button. • MainStage audio channel strips can use automatic Feedback Protection to alert you when feedback occurs on the channel. For information about using Feedback Protection, see Using Feedback Protection with Channel Strips. • MainStage audio channel strips do not have an input monitoring (i) button. You can use the Mute button to silence the channel strip. • In MainStage, you can use the Format button to select mono or stereo format. MainStage does not support surround input or surround processing. • MainStage channel strips do not have Group or Automation Mode pop-up menus. • MainStage channel strips include a Change All option in both Input and Output pop-up menus that you can use to change either the input or output for all channel strips in a patch, a set, or for the overall concert. • In MainStage, the selected channel strip is highlighted in white. • Only one channel strip in each patch–the first audio channel strip–sends audio to the Tuner. The channel strip that sends audio to the Tuner is indicated by a tuning fork icon at the top of the channel strip. • In MainStage, the name of the channel strip changes when you select a new channel strip setting, unless you have renamed it. • In MainStage, the channel strip number (at the bottom of the channel strip) reflects its order in the patch, not the concert. • Surround plug-ins are not available in MainStage. Chapter 5 Working in Edit Mode 49• You can choose the information displayed on the channel strip, including latency information, by Control-clicking the channel strip and choosing the information you want to display from the shortcut menu. • The Playback plug-in is available only in MainStage, not in Logic Pro. For more information about working with channel strips, see the “Working with Instruments and Effects” and “Mixing” chapters in the Logic Pro User Manual. For complete information about the instruments and effects available in Logic Studio, see the Logic Studio Instruments and Logic Studio Effects guides. To learn how to add a channel strip, see Adding a Channel Strip. To learn how to change a channel strip setting, see Changing a Channel Strip Setting. Selecting Channel Strips When you add a channel strip to a patch (or add a channel strip at the set or concert level), the channel strip is selected in the Channel Strips area, and available settings appear in the Channel Strip Settings browser. You can select a channel strip directly by clicking it in the Channel Strips area and also select an adjacent channel strip by using key commands: Key command Selection Left Arrow The channel strip to the left Right Arrow The channel strip to the right Showing Signal Flow Channel Strips In addition to the channel strips in a patch, you can view and edit signal flow channel strips in the Channel Strips area. Signal flow channel strips include the Output and Master channel strips for the concert, auxes that are receiving signal from a channel strip in the patch, and any set- or concert-level channel strips that are available when the patch is selected. You can also view signal flow channel strips at the set level. When you show signal flow channel strips, channel strips at the concert level, including Output and Aux channel strips, include a small concert icon near the top of the channel strip to make it easy to distinguish them from patch-level channel strips. Channel strips at the set level include a small folder icon so they can also be easily distinguished. You can edit signal flow channel strips in the Channel Strips area. For example, you can adjust the volume fader or pan slider of a signal flow channel strip, or add effects to an aux channel strip. To show signal flow channel strips µ Choose Show Signal Flow Channel Strips from the Action menu in the upper-right corner of the Channel Strips area. 50 Chapter 5 Working in Edit ModeCreating an Alias of a Channel Strip You can create an alias of a channel strip and use the alias in different patches or sets. Aliases allow you to share highly memory-intensive plug-ins, such as third-party multi-channel instruments and samplers, between different patches, rather than creating multiple instances of these plug-ins. In some cases, creating an alias can be more efficient (use fewer resources) than adding a concert- or set-level channel strip. To create an alias of a channel strip 1 In the Channel Strips area, select the channel strip. 2 Choose Edit > Copy, or press Command-C (default). 3 In the Patch List, select the patch in which you want to use the alias. 4 Choose Edit > Paste as Alias, or press Command-Option-V (default). The alias is pasted after the last channel strip in the patch (but before any signal flow channel strips, if they are visible). An alias icon appears near the top of the alias to distinguish it from the channel strips in the patch. You can use an alias in multiple patches or sets. When you change any setting on the original channel strip, those changes are reflected in the aliases of the channel strip. You may want to audition each patch that uses an alias after changing the settings of the original channel strip, to make sure it sounds the way you want. Note: You can’t import a patch or set containing an alias, because the aliased channel strip may not be available. You can create an alias of a multi-output instrument, such as the EXS24 mkII, to use in another patch or set in the concert. When you copy a multi-output instrument to create an alias, be sure to select all of the aux channel strips for the instrument so that the complete multi-output instrument is pasted as an alias. For information about using multi-output instruments in MainStage, see Using Multiple Instrument Outputs in MainStage. Editing Channel Strips in MainStage You can add instruments to software instrument channel strips and add effects to any channel strip in the Channel Strips area. Adding instruments and effects to a channel strip is the same in MainStage as it is in Logic Pro. Chapter 5 Working in Edit Mode 51You edit channel strip parameters in the Channel Strip Inspector, which appears below the workspace when the channel strip is selected in the Channel Strips area. You can set the key range and velocity offset, create a controller transform, and filter MIDI control messages to the channel strip. You can also rename the channel strip and change the channel strip color and icon. The Channel Strip Inspector has four tabs, which provide the following functions: • Channel Strip Library and Plug-In Library: With a channel strip selected, you can choose channel strip settings from the Channel Strip Library. With an Insert slot selected, you can choose settings for the plug-in from the Plug-In Library. • Attributes: You can rename the channel strip and choose a different channel strip color and icon. • MIDI Input: You can create controller transforms in the MIDI Input tab. For software instrument and external instrument channel strips, you can also choose the MIDI input device, filter MIDI input, transpose the instrument, and create velocity scaling graphs. • Layer Editor: For software instrument and external instrument channel strips, you can define the key range, set floating split points, and set the minimum and maximum velocity for the channel strip. Using the Channel Strip Library you can access any Logic Studio channel strip. However, some channel strips include plug-ins, particularly Space Designer, not suited for live performance because of their intensive CPU usage. Using these channel strips can affect the performance of your concert, resulting in audio dropouts and other issues. Logic Studio surround effect plug-ins cannot be used with MainStage. If you choose a channel strip setting containing one of these effects, the unused effects are shown disabled (gray, with a diagonal line running through the effect name). Choosing Channel Strip Settings You can quickly change the instrument, effects, and other parameters for a channel strip by choosing a new channel strip setting. You can choose a new channel strip setting in one of two ways: by using the Channel Strip Library or by using the Settings button at the top of the channel strip. To choose a channel strip setting from the Channel Strip Library 1 In the Channel Strips area, select the channel strip you want to change. The selected channel strip is highlighted with a blue outline. 2 In the Channel Strip Inspector, click the Channel Strip Library tab. Available settings for the channel strip appear in the Channel Strip Library. Logic Studio content appears in a series of folders with different instrument categories. If you have GarageBand installed, or have one or more Jam Packs installed on your computer, those settings appear below the Logic Studio settings. 52 Chapter 5 Working in Edit Mode3 Click a category from the column on the left, then click subcategories from the columns on the right until you see the settings you want. You can select a recent channel strip setting by clicking Recent in the column on the left, and then selecting a recent setting from the second column. As in Logic Pro, you can also choose a new channel strip setting from the Settings menu at the top of the channel strip. To choose a channel strip setting from the Settings menu µ Click the Settings button at the top of the channel strip, then choose a new setting from the menu that appears. When you choose new channel strip settings from the Settings menu, the selected channel strip setting does not appear selected in the Channel Strip Library. You can also search for channel strip settings by name. To search for channel strip settings in the Channel Strip Library 1 In the Channel Strip Inspector, select the Channel Strip Library tab. 2 Choose Find in Library from the Action menu in the upper-right corner of the Channel Strip Inspector. 3 In the dialog that appears, type the text you want to search for. The channel strip with the text in its name appears selected in the library. 4 If more than one channel strip includes the search text, choose “Find Next in Library” from the Action menu to cycle through the channel strips with names containing the text. 5 To change the channel strip setting, click the name of the new setting in the Channel Strip Inspector. The Channel Strip Library shows all channel strip settings available to Logic Studio applications, including settings that may not be useful in MainStage, such as mastering settings. If you choose a channel strip setting containing plug-ins not usable in MainStage, the plug-ins appear with a bold diagonal line in the Channel Strips area. Chapter 5 Working in Edit Mode 53Renaming a Channel Strip When you add a channel strip to a patch, the channel strip has a default name. You can rename channel strips to distinguish your custom settings from the default ones. To rename a channel strip µ In the Attributes tab of the Channel Strip Inspector, select the name in the Name field and type a new name. Type a new name in the field. Changing the Channel Strip Color Each channel strip has a color, which appears at the bottom of the channel strip and as a layer above the keyboard screen control in the workspace and the Layer Editor. You can change the color of a channel strip to make it easier to visually distinguish channel strips. To change the color of a Software Instrument channel strip µ In the Attributes tab of the Channel Strip Inspector, choose a color from the Color pop-up menu. Choose a color from the pop-up menu. 54 Chapter 5 Working in Edit ModeChanging the Channel Strip Icon When you add a channel strip, the channel strip has a default icon, which appears above the Settings menu. You can change the icon to help visually distinguish channel strips with different instrument types or uses. To change the icon for a channel strip µ In the Attributes tab of the Channel Strip Inspector, choose an icon from the Icon well. Choose an icon from the menu. Using Feedback Protection with Channel Strips You can use “Feedback Protection” on audio and external instrument channel strips in MainStage. When Feedback Protection is turned on for a channel strip, MainStage alerts you when it detects feedback on the channel. When the feedback alert appears, the channel is temporarily silenced. You can then choose to mute the channel while you find and eliminate the source of the feedback, allow feedback on the channel, or continue to use the channel and receive alerts when feedback occurs. Feedback protection is turned on by default for audio channels strips and turned off by default for external instrument channel strips. You can turn Feedback Protection on or off for a channel strip in the Channel Strip Inspector. To turn Feedback Protection on or off µ In the Attributes tab of the Channel Strip Inspector, select the Feedback Protection checkbox to turn Feedback Protection on. If it is on, deselect the checkbox to turn it off. Setting Keyboard Input for a Software Instrument Channel Strip In the Channel Strip Inspector, you can choose the keyboard controller from which the channel strip receives MIDI input. If you are using a multitimbral instrument, you can also choose the input for each MIDI channel. For example, you can use the EVB3 instrument as a multitimbral instrument, and send input to the upper and lower register and the foot pedal using three separate MIDI channels. Chapter 5 Working in Edit Mode 55To set the keyboard input for a software instrument channel strip 1 In the Channel Strip Inspector, click the MIDI Input tab. 2 Choose the MIDI input device from the Keyboard pop-up menu in the Input section. The names in the Keyboard pop-up menu correspond to keyboard screen controls in the workspace. To set multitimbral input for different MIDI channels 1 In the Channel Strip Inspector, click the MIDI Input tab. 2 Choose Multitimbral from the Keyboard pop-up menu in the Input section. 3 In the Multitimbral Settings dialog, choose the input device for each MIDI channel you want to receive MIDI input. Transposing Software Instrument Channel Strips You can transpose (change the pitch of) a software instrument channel strip. When you transpose a channel strip, every MIDI note received by the channel strip is transposed by the number of semitones set in the Transpose value slider. To transpose the MIDI input of a software instrument channel strip 1 Select the channel strip in the Channel Strips area. 2 In the MIDI Input tab of the Channel Strip Inspector, set the value using the Transpose value slider. You can click the value and drag up or down to set the value, click the up arrow or down arrow, or double-click the value and type a new value. Filtering MIDI Messages You can filter some MIDI messages for a channel strip in the Channel Strip Inspector. When you select one or more MIDI message types in the Filter section of the Channel Strip Inspector, the corresponding MIDI message types are filtered out of any incoming MIDI data and are not sent to the channel strip. You can filter the following types of MIDI messages: • Pitch Bend • Sustain (control message 64) • Modulation (control message 1) • Expression (control message 11) • Aftertouch To filter incoming MIDI messages 1 In the Channel Strip Inspector, click the MIDI Input tab. 2 In the Filter section of the MIDI Input tab, select the checkbox for the MIDI messages you want to filter. 56 Chapter 5 Working in Edit ModeIf you have created a controller transform, you can filter the input message type, and the controller transform will still send its output message type. It is also possible to filter the output message type, but in this case the output of the controller transform will be filtered. Setting a Channel Strip to Ignore Hermode Tuning If a patch (or the concert or set containing the patch) is set to use Hermode tuning, but the patch contains a channel strip (for example, one with a drum or percussion instrument) that you do not want to use Hermode tuning, you can set the individual channel strip to ignore Hermode tuning. To set a channel strip to ignore Hermode tuning µ In the MIDI Input tab of the Channel Strip Inspector, select the Ignore Hermode Tuning checkbox. For information about using Hermode tuning, see the Logic Pro User Manual. Working with Graphs Using graphs, you can graphically remap the values for some MIDI control messages so that input values from your controller produce different output values for the channel strip or plug-in parameter. Graphs make it easier to see and modify a range of values for a parameter, such as velocity or filter cutoff. You can use graphs for the following types of parameters: • Controller transforms • Velocity scaling (both input velocity and note input) • Parameters to which a screen control is mapped You open a graph window by clicking the button for that type of graph in the appropriate Inspector. The Transform and Velocity Scaling graphs for the selected channel strip are available in the MIDI Input tab of the Channel Strip Inspector. The Parameter graph for the selected screen control is available in the tab for the individual mapping as well as in the Mappings tab in the (Edit mode) Screen Control Inspector. The graph shows the range of input values on the horizontal (x) axis, moving from left to right, and shows the range of output values on the vertical (y) axis, moving from bottom to top. In the graph window, you have several ways of working. You can edit the graph curve directly, edit values numerically using the Precision Editor, or use the Curve buttons to set the graph to one of the predefined curves. Chapter 5 Working in Edit Mode 57Most of the ways you edit graphs are the same, regardless of the type of graph—although there are a few features specific to one or another type. For Parameter graphs, you can change the minimum and maximum range values for the graph using the Range Min and Range Max value sliders. For information about controller transforms, see Creating Controller Transforms. For information about velocity scaling, see Scaling Channel Strip Velocity. For information about parameter mapping graphs, see Using Parameter Mapping Graphs. To edit a graph 1 Select the channel strip or screen control you want the graph to apply to. 2 Select the MIDI Input tab (for transform and velocity scaling graphs) or the Mapping tab (for parameter mapping graphs). 3 Click the graph button for the type of graph you want to edit. The graph window opens. 4 Do one of the following: • Click one of the Curve buttons to set the graph to one of the preset curves. • Click the curve at the point where you want to add a node, then drag the node to the desired value. Drag horizontally to change the input value, or vertically to change the output value. As you drag, the current values of the node appear next to the pointer. • Double-click the curve at the point where you want to add a node, then edit the values for the node in the Precision Editor. • Option-click any part of the curve (except a node), then drag the dotted part of the curve to make the curve nonlinear. 5 Continue adding and adjusting points on the curve until you achieve the result you want. 6 When you are finished, click the close button at the upper-left corner of the graph window to close it. To invert the values of the graph Do one of the following: µ In the graph window, click the Invert button. µ In the tab for the mapping, select the Invert Parameter Range checkbox. To reset the graph to its default values µ Click the Revert to Default button at the top of the graph window. After you have edited a graph, the button for the graph in the Inspector shows the edited shape of the graph in a dark blue color to make it easier to identify which graphs you have edited and how. 58 Chapter 5 Working in Edit ModeTo close the graph window µ Press Escape (Esc). Creating Controller Transforms Using a transform graph, you can remap the values for some MIDI control messages so that input values from your controller produce different output values for the channel strip. A common use of the transform is for expression scaling, where input MIDI expression values are mapped to different output values on a graphic curve. In addition, you can transform input values for one message type to output values for another message type. For example, you can transform MIDI volume values from your controller to send expression values to the channel strip, or transform input breath values to send modulation values. The transform graph provides a very flexible way of remapping both the values and the output destination for these MIDI control messages. In MainStage, you can transform values for expression, modulation, MIDI volume, and breath control messages. You choose the input and output message types and graphically create transform curves in the MIDI Input tab of the Channel Strip Inspector. In a transform graph, the horizontal axis represents input values from your controller, and the vertical axis represents output values sent to the channel strip. To set the input and output message types for a controller transform 1 In the Channel Strips area, select the channel strip for which you want to create a controller transform. 2 In the Channel Strip Inspector, select the MIDI Input tab. 3 In the Controllers section, choose the input message type from the Input pop-up menu. 4 Choose the output message type from the Output pop-up menu. Click the Transform button to edit the graph. Choose the input and output message types from these menus. Chapter 5 Working in Edit Mode 59To open the Transform graph µ In the MIDI Input tab of the Channel Strip Inspector, click the Transform button. The Transform graph opens. If a patch contains more than one channel strip with a transform graph, the transform curves for the other channel strips in the patch appear in the controller Transform graph window behind the current curve. Each channel strip in the patch can have its own controller transform. For information about editing the graph, see Working with Graphs. Scaling Channel Strip Velocity You can scale the output velocity of a channel strip using the Velocity Scaling graphs. You can scale output velocity based on note input or input velocity. When you perform velocity scaling, each input velocity (regardless of the note being played) is scaled to the output velocity. When you perform note scaling, output velocity is scaled depending on the note in the key range. This is useful when you want to have a parameter change in different parts of the key range; for example, when a filter or attack parameter opens for higher note values to give a brighter, sharper sound. To open a velocity scaling graph 1 In the Channel Strips area, select the channel strip on which you want to perform velocity scaling. 2 In the Channel Strip Inspector, select the MIDI Input tab. 3 In the MIDI Input tab, do one of the following: • To open the velocity input graph, select the Velocity Input button. • To open the note input graph, select the Note Input button. The selected velocity scaling graph opens. For information about editing the graph, see Working with Graphs. Creating Keyboard Layers and Splits If you play a keyboard controller, you can easily create keyboard layers and splits in your MainStage patches. You create layers and splits by adding two or more channel strips to a patch and setting the Low Key and High Key for each channel strip to define its key range. The key range defines the range of notes on a keyboard controller that trigger sound from a software instrument or external instrument in the channel strip. You can define key ranges so that they overlap (for layered sounds) or are contiguous (for splits). 60 Chapter 5 Working in Edit ModeThe Layer Editor tab in the Channel Strip Inspector shows the key range for each channel strip in a patch and in the concert or set containing the patch (if either includes a channel strip with a key range). You can define the key range for a channel strip in one of several ways: you can drag the edges of the layer, use the Learn buttons to define the Low and High keys, or use the Low Key and High Key value sliders. To open the Layer Editor µ In the Channel Strip Inspector, click the Layer Editor tab. To define a key range using the layers 1 In the Layer Editor, move the pointer over the left edge of the layer you want to change/define. The pointer changes to a resize pointer. 2 Drag the left edge of the layer to the note you want to use as the low key (the lowest note in the key range). 3 Move the pointer over the right edge of the layer. 4 Drag the right edge of the layer to the note you want to use as the high key (the highest note in the key range). To define a key range using the Learn buttons 1 In the Channel Strips area, select the channel strip. 2 In the Channel Strip Inspector, click the Layer Editor tab. 3 Click the Learn button next to the Low Key value slider. Click Learn and play the corresponding note on your music keyboard. 4 On your keyboard controller, press the key you want to set as the lowest key in the key range. 5 Click the Learn button again to turn off Learn mode for the Low Key. 6 Click the Learn button next to the High Key value slider. Chapter 5 Working in Edit Mode 617 On your keyboard controller, press the key you want to set as the highest key in the key range. 8 Click the Learn button again to turn off Learn mode for the High Key. When you play the patch, you hear the channel strip when you play notes inside the key range. When you play notes outside the key range, no sound is generated from the channel strip. To define a key range using the value sliders 1 In the Channel Strips area, select the channel strip. 2 In the Channel Strip Inspector, click the Layer Editor tab. 3 Change the value in the Low Key value slider. You can click the value and drag vertically, click the up arrow or down arrow, or double-click the value and type a new value. Set the high key and low key using these value sliders. 4 Change the value in the High Key value slider. You can click the value and drag vertically, click the up arrow or down arrow, or double-click the value and type a new value. Setting Floating Split Points When a key range has a floating split point, the notes that define the boundaries of the key range ends change depending on the keys you play as you approach the boundary of the key range. You set floating split points in the Layer Editor tab of the Channel Strip Inspector. 62 Chapter 5 Working in Edit ModeFloating split points can be explained using an example. If you set the Low Key of a key range to C1, set a floating split point value of 3, then play notes immediately above C1 (for example, the notes F1-Eb1-D1), and continue playing downward past C1 (for example, the notes C1-Bb0-A0), the split point moves down to include those notes, up to the floating split point value (3 semitones). If, however, you start by playing notes immediately below the Low Key (for example, the notes G0-A0-B0) and continue playing upward past C1 (for example, the notes C1-D1-E1), the split point moves up to include those notes, up to the floating split point value. (In this example, C1 and D1 would be included, but not E1, which is four semitones above the Low Key.) To set floating split points for a layer/key range 1 In the Layer Editor tab, click the Low Key Floating value slider and drag vertically to change the value, or double-click the current value and type a new value (the value is the number of semitones used for the split). 2 Click the High Key Floating value slider and drag vertically to change the value, or double-click the current value and type a new value. You can also create a keyboard split by adding a channel strip at the set level and adjusting the key range of the channel strips in the patches in the set. The channel strip at the set level takes precedence over any channel strips in patches in the set for the notes in its key range. For information about adding a channel strip at the set level, see Working at the Set Level. Setting the Velocity Range By default, the velocity of a channel strip extends from 1 to 127. You can limit the velocity range so that the channel strip only responds when the notes you play on your controller fall between the Min and Max values of the velocity range. To set the velocity range for a channel strip 1 In the Channel Strips area, select the channel strip. 2 In the Channel Strip Inspector, click the Layer Editor tab. 3 In the Layer Editor, set the minimum velocity that triggers the channel strip using the Velocity Min value slider. (Click the value and drag vertically to change the value, or double-click the value and type a new value.) 4 Set the maximum velocity that triggers the channel strip using the Velocity Max value slider. Overriding Concert- and Set-Level Key Ranges If a software instrument channel strip exists at the concert level, the concert-level channel strip takes precedence over any patch-level software instrument channel strips within its key range. This means that when you play any notes in the key range of the concert-level channel strip on a keyboard controller, you hear only the concert-level channel strip, even when a patch is selected. Chapter 5 Working in Edit Mode 63Similarly, if a software instrument channel strip exists at the set level, the same condition applies for all patches in the set. That is, the set-level channel strip takes precedence over any patch-level channel strips within its key range. You can override concert- or set-level channel strips for a channel strip on an individual patch, so that the patch-level channel strip takes precedence over the concert-level or set-level channel strips. To override concert- or set-level key ranges 1 In the Patch List, select the patch with the channel strip that you want to override the concert- or set-level channel strip. 2 In the Channel Strips area, select the channel strip with the key range that you want to override the concert- or set-level key range. 3 In the Channel Strip Inspector, select the Layer Editor. 4 Select the “Override parent ranges” checkbox. The “Override parent ranges” checkbox is available only if there is a concert- or set-level channel strip. Using the EXS24 mkII Instrument Editor in MainStage For channel strips using the EXS24 mkII sampler instrument, you can edit sampler instrument zones and groups in the EXS Instrument Editor. The EXS24 mkII Instrument Editor works exactly the same in MainStage as it does in Logic Pro, with one exception: in MainStage, you cannot open the Sample Editor to edit individual audio samples. In an EXS24 mkII instrument, a zone is a location into which a single sample (an audio file) is loaded from a hard disk. You can edit zone parameters in Zone view mode. Zones can be assigned to groups, which provide parameters that allow you to simultaneously edit all zones in the group. You can define as many groups as desired. The Instrument Editor has two view modes: Zones view and Groups view. You can edit zones in Zones view and edit group parameters in Groups view. To open the EXS24 mkII Instrument Editor 1 In a channel strip using the EXS24 mkII, double-click the EXS24 slot in the I/O section. 64 Chapter 5 Working in Edit Mode2 In the upper-right area of the EXS24 mkII plug-in window, click the Edit button. Click the Edit button to open the Instrument Editor. The Instrument Editor opens. When you play notes on the keyboard of the EXS24 mkII Instrument Editor, the notes are played on the selected channel strip. You can switch between Zones view and Groups view, click individual zones to view their parameters, click notes on the keyboard to hear the samples assigned to them, create zones and groups, and edit zone and group parameters just as you can in Logic Pro. For in-depth information about using the EXS24 mkII Instrument Editor, refer to the Logic Studio Instruments Help. Using Multiple Instrument Outputs in MainStage MainStage supports the multiple output versions of the EXS24 mkII, Ultrabeat, and some Audio Units instruments. You can insert multi output instruments and use them to route different outputs to different physical outputs, apply different plug-ins or processing to different outputs, or for other uses. Chapter 5 Working in Edit Mode 65If an instrument supports multiple outputs, one or more multi output versions are available in the Instrument Plug-In menu for the instrument. The Plug-In menu shows specific information about output configurations, for example: EXS24: Multi Output (5xStereo, 6xMono). Note: Not all instruments support multiple outputs. If no multi output version is available in the Plug-In menu, the instrument does not support multiple outputs. To insert a multi output instrument 1 On the channel strip in which you want to use the multi output instrument, click the Instrument slot. 2 Choose the instrument from the Plug-In menu, and choose the multi output version from the submenu. The instrument name appears in the Instrument slot, and a small Add (+) button appears below the Solo button on the channel strip. The Output for the instrument is set to Output 1-2. 3 Double-click the Instrument slot to open the instrument (plug-in) window. You need to set up the output routing for individual sounds or samples in the instrument (plug-in window). You set up output routing for the EXS24 mkII in the Instrument Editor, and set up output routing for Ultrabeat in the Output menu of the Assignment section of the Ultrabeat window. 66 Chapter 5 Working in Edit Mode4 On the channel strip, click the Add button to add additional outputs. Each time you add an output, a new section of the channel strip is added, with the next available pair of outputs. Each output uses the same instrument, but each can have its own inserts, volume, pan, and expressions settings and its own effect sends, as well as its own outputs. For more information about using multiple instrument outputs, see the Logic Pro User Manual and the Logic Studio Instruments manual. Information about specific instruments (for example, Ultrabeat) can be found in the chapters covering those instruments. Using External MIDI Instruments in MainStage You can add an external MIDI instrument channel strip to a patch and use it to play an external instrument, such as a hardware synthesizer. You can also use an external instrument to “play” a ReWire application. When you use an external MIDI instrument channel strip, you choose the MIDI channel to send MIDI output from MainStage to the instrument, and choose the audio inputs to receive audio from the instrument. The audio output from the instrument is routed to the input of the channel strip, where you can process it using MainStage effects. To add an external instrument channel strip 1 Click the Add Channel Strip (+) button in the upper-right corner of the Channel Strips area. 2 In the New Channel Strip dialog, select External Instrument. You can also choose the MIDI input and output, the format, and the audio input and output for the channel strip. You can choose an audio channel or a ReWire application for the input, but cannot choose a bus. The MIDI input pop-up menu shows the Keyboard or MIDI Activity screen controls (which receive MIDI note input) currently in the workspace. Note: When using an external instrument to send MIDI to a ReWire slave application (such as Reason or Live), you should disable any MIDI input the slave application receives directly from the hardware controller. For information about disabling MIDI input from a hardware device, consult the documentation for the application. For ReWire applications, when you add an external channel strip, set the MIDI port to the ReWire slave. The Channel list also updates based on the port. Some ReWire slaves set up multiple ports. To use a ReWire application with MainStage, open the ReWire application after opening MainStage. Chapter 5 Working in Edit Mode 67When you play your keyboard controller with the patch containing the external MIDI instrument selected, MainStage sends note and other MIDI messages to the chosen MIDI Output and MIDI Channel, receives audio from the chosen Input, and sends the audio output to the chosen Output. You can also send a program change message to the external instrument when you select the patch to control which program the external instrument uses. To send a program change to an external instrument when you select a patch 1 In the Channel Strip Inspector, click the MIDI Out tab. 2 In the MIDI Out tab, select the Send Program Change checkbox. The Program Change value is set to –1 by default, so that no program change is sent when you select the Send Program Change checkbox, until you change the value. 3 Set the program change number you want to send using the Send Program Change value slider. 4 If you want to send a Bank Change message, select the Send Program Change checkbox, then set the most-significant byte (MSB) and least-significant byte (LSB) of the bank change number using the Bank MSB and Bank LSB value sliders. When you select the patch, the program change and bank change messages are sent to the external instrument. Also note that program and bank changes are sent when you edit the program change and bank change value sliders in the Channel Strip Inspector (so you can be sure that the values you enter send the correct program and bank change messages). For more information about using external MIDI instruments, see the Logic Pro User Manual. If you want the external instrument to respond to the program change, but do not want it to receive note or other MIDI information from your controller, click the MIDI Input tab and choose None from the Keyboard pop-up menu. You can also use a knob or fader mapped to the Program Change action to send program changes to an external instrument. To send program changes to an external instrument using a screen control 1 In the workspace, click the screen control you want to use to send program change messages. 2 In the Screen Control Inspector, click the Unmapped tab. 3 In the Mapping browser, select the external instrument, then select MIDI Controller folder from the submenu. 4 In the third column from the left, select Program Change. The screen control is mapped to the Program Change parameter. By moving the hardware control assigned to the screen control, you can send program changes to the external instrument. 68 Chapter 5 Working in Edit ModeNote: If the MIDI Out parameter of the external instrument channel strip is set to the external instrument when you map the screen control to the Program change parameter, a program change (Program 0) is sent when you create the mapping. If you are editing the program on the external instrument, your changes may be lost. To map the screen control without sending an immediate program change to the external instrument, choose None from the MIDI Out slot of the external instrument before you create the mapping, then choose the external instrument in the MIDI Out slot. No program change is sent until you move the knob or fader. Using the Activity Monitor As you work on your concert in Edit mode, the Activity Monitor in the toolbar shows the current CPU and memory information as well as received MIDI messages. The CPU section of the Activity Monitor glows red to indicate a CPU overload condition. The Memory section of the Activity Monitor glows yellow to indicate a low-memory condition. If an extreme low-memory condition occurs, an alert appears, warning you to save the concert before MainStage quits. Low-memory conditions can be caused by having too many memory-intensive channel strips or plug-ins in a concert or by using other memory-intensive applications (including ReWire applications) together with the concert. If a low-memory condition occurs, try reopening the concert and consolidating some memory-intensive plug-ins or channel strips. Deleting Channel Strips You can delete a channel strip if you decide you no longer want it in a patch. To delete a channel strip 1 Select the channel strip in the Channel Strips area. 2 Choose Edit > Delete (or press the Delete key). Mapping Screen Controls After you have created your patches and learned controller assignments for the screen controls you want to use, you can map MainStage screen controls to channel strip and plug-in parameters to modify the sound of your patches while you perform, or map them to MainStage actions to control other functions. You map screen controls to parameters in Edit mode. After you learn controller assignments (in Layout mode), the screen controls in the workspace do not respond to movements of physical controls on your MIDI hardware until you map them to channel strip parameters (in Edit mode). There are two ways to map screen controls to parameters: by visually selecting parameters on channel strips or plug-in windows or by choosing parameters in the Parameter Mapping browser. Chapter 5 Working in Edit Mode 69Mapping Screen Controls to Channel Strip and Plug-In Parameters After you have made your controller assignments, you can begin mapping screen controls to the parameters in your patches you will want to control while you are performing. You will likely want to map screen controls to parameters in each patch in a concert, so that you can easily access and modify the parameters you want for each patch when you are performing live. You can also map parameters at the concert level to control master volume, view master levels, or modify concert-wide effects. You can map screen controls to channel strip and plug-in parameters in one of two ways: by mapping screen controls visually to parameters on the channel strip or in a plug-in window or by using the Parameter Mapping browser. You map screen controls to parameters in Edit mode. The screen controls in the workspace do not respond to movements of physical controls on your MIDI hardware until you map them to channel strip parameters. To map a screen control to a channel strip or plug-in parameter 1 In the workspace, click the screen control you want to map. The screen control is highlighted in blue. The Screen Control Inspector appears below the workspace, showing the parameters for the selected screen control. The Screen Control Inspector includes General and Mapping tabs as well as a tab labeled Unmapped. 2 Press Command-L. The Screen Control Inspector opens to the Unmapped tab, showing the Parameter Mapping browser. The Map Parameter button lights red to indicate that mapping is active. 3 To map the screen control to a channel strip parameter, click the control for the parameter on the channel strip in the Channel Strips area. 70 Chapter 5 Working in Edit Mode4 To map the screen control to a plug-in parameter, double-click the plug-in in the Inserts section of the channel strip to open the plug-in window, then click the parameter in the plug-in window. Click the parameter in a channel strip or plug-in window. Click the screen control you want to map to a parameter. The screen control is mapped to the selected parameter, and the Unmapped tab takes the name of the parameter. You can continue mapping additional screen controls by clicking them in the workspace and then clicking the corresponding parameters in a channel strip or plug-in window. 5 When you are finished, press Command-L again (or click the Map Parameter button) to turn off mapping. To map a screen control using the Parameter Mapping browser 1 In the workspace, click the screen control you want to map. The screen control is highlighted in blue. The Screen Control Inspector appears below the workspace, showing the parameters for the selected screen control. The Screen Control Inspector includes General and Mapping tabs as well as a tab labeled Unmapped. Chapter 5 Working in Edit Mode 712 In the Screen Control Inspector, click the Unmapped tab. The Parameter Mapping browser appears, showing the channel strips and plug-ins available for mapping as well as the Actions folder. 3 In the column on the left of the Parameter Mapping browser, select the channel strip with the parameter to which you want to map the screen control. Parameters for the selected channel strip appear in the columns on the right. Additional folders for the instruments and effects in the channel strip may appear in these columns. Click a folder to see the parameters for that instrument or effect. 4 Select the parameter you want to map. Click the parameter to which you want to map the screen control. Click the channel strip or plug-in with the parameter you want to map. The screen control is mapped to the selected parameter, and the Unmapped tab takes the name of the parameter. You can continue mapping additional screen controls by clicking them in the workspace and then choosing parameters in the Parameter Mapping browser. Using the Parameter Mapping browser, you can map parameters that are not visible in plug-in windows. You can also map screen controls to MainStage actions and to AppleScript scripts. For more information about mapping screen controls, see Mapping Screen Controls. Note: If you change the channel strip setting for a channel strip to which you have mapped screen controls, you will lose any parameter mappings. You can also edit velocity sensitivity for a channel strip, create controller transforms, and filter various MIDI messages. For information about editing channel strips, see Editing Channel Strips in MainStage. 72 Chapter 5 Working in Edit ModeMapping Screen Controls to Actions In addition to mapping screen controls to channel strip and plug-in parameters, you can map them to MainStage actions. Actions let you select patches and sets; silence MIDI notes; control the Tuner and the metronome; tap a new tempo; display information about patches, MIDI messages, and other information; and perform other functions using screen controls. For a complete table of actions, including descriptions and usage notes, see Using MainStage Actions. The Actions folder, which appears in the Parameter Mapping browser along with available parameters, contains actions for selecting patches and sets, showing the Tuner, activating tap tempo, Master Mute, or Panic, and others. The Actions folder also contains an AppleScript subfolder with useful scripts. You can map button screen controls to actions for selecting different patches and use physical buttons on your MIDI device to select patches when you perform. You can also map buttons to actions for selecting different sets or selecting the concert. For information about assigning buttons, see Assigning Buttons. To map a screen control to an action 1 In the workspace, click the screen control you want to map. The Screen Control Inspector appears below the workspace, showing the settings for the selected screen control. If the screen control is currently mapped, a tab with the name of the mapping is visible in addition to the General and Mapping tabs. If the control is unmapped, the tab is labeled “Unmapped.” 2 Click the Unmapped (or name of mapping) tab. The Parameter Mapping browser appears below the workspace. The Actions folder is available in the Parameter Mapping browser. 3 In the column on the left of the Parameter Mapping browser, click the Actions folder. Chapter 5 Working in Edit Mode 73The available actions appear in the second column of the browser. Click the Actions folder to see available actions. Click the action you want to map from the submenu. 4 Select the action you want to map. Note: If you map a knob screen control to an action to select a patch (such as the −10 Patches, Previous Patch, Next Patch, or +10 Patches action), the screen control jumps to the value of the hardware control, regardless of the setting of the Respond to Hardware Move parameter in the Screen Control Inspector. Mapping a Screen Control to Multiple Parameters You can map a single screen control to multiple parameters and control how the screen control modifies each mapped parameter. Mapping a screen control to multiple parameters is also referred to as multimapping. You map a screen control to up to eight parameters by adding mappings in the Screen Control Inspector. To add a mapping 1 Map the screen control to a parameter or action, as described in Mapping Screen Controls to Channel Strip and Plug-In Parameters and Mapping Screen Controls to Actions. 2 With the screen control selected, click the Add Mapping (+) button at the upper-right corner of the Screen Control Inspector. A new Unmapped tab appears in the Inspector, showing the Parameter Mapping browser. 3 In the Parameter Mapping browser, choose the parameter to which you want to map the screen control. If you add a mapping while the Learn process is active (the Map Parameter button is red), you can immediately learn the new mapping. The Command Editor also includes key commands for selecting the previous and next tab to make mapping to multiple parameters easier. For information about using key commands, see Using the Command Editor. 74 Chapter 5 Working in Edit ModeIf you frequently map screen controls to multiple parameters, you can speed your workflow by assigning key commands to select the previous and next tab or to select a specific tab in the Screen Control Inspector. For information about assigning key commands, see Using the Command Editor. To view all mappings for a screen control µ In the Screen Control Inspector, select the Mappings tab. The mappings appear in a list view that shows the minimum and maximum range values and patch change behavior for each mapping and includes buttons to open the Parameter graph and Invert graph values for each mapping. If you create multiple mappings for a screen control, you can define the relationships between the first mapping and subsequent mappings. This can be especially useful when, for example, you are mapping the same control to filter cutoff and filter resonance, and you want to ensure that resonance does not exceed a certain maximum value as you increase the cutoff value. The default relationship affects all future mappings (for the same and other screen controls), but does not affect existing mappings. The default is set to Scale the first time you open MainStage. To define the default relationship between the first mapping and subsequent mappings 1 Select a screen control you want to map to multiple parameters. 2 Choose “Default Relation to First Mapping” from the Action menu, located in the upper-right corner of the Screen Control Inspector. 3 Do one of the following: • To set subsequent mappings to be offset by a fixed value from the first mapping, choose Offset. • To set subsequent mappings to scale by a constant ratio, starting from the same minimum value, choose Scale. • To set subsequent mappings to scale by a constant ratio to the point defined for the mapping, starting from both the same minimum value and maximum value, choose Pivot. Using Parameter Mapping Graphs Each parameter mapping has a Parameter graph. You can edit the graph to remap input values to different output values for the parameter. To open the Parameter graph for a mapping µ In the tab for the mapping or in the Mappings tab, double-click the Graph button for the mapping you want to edit. The Parameter graph window opens. The title of the graph window shows the parameter name. Chapter 5 Working in Edit Mode 75For information about editing graphs, see Working with Graphs. Mapping Screen Controls to All Channel Strips in a Patch When you map a screen control to a channel strip parameter such as volume or pan, you can map it to control the same parameter in all of the channel strips in the patch. This is particularly useful when you want to control the overall volume of a layered sound, even if the different layers are played across multiple keyboards. To map a screen control to all channel strips in a patch 1 Map the screen control following the instructions in the preceding sections. 2 In the column on the left of the Parameter Mapping browser, select the Send to All folder. 3 Select the destination from the second column. 4 Select the parameter to map the screen control to from the third column. You can map the screen control to actions for transposing software instrument channel strips, channel strip parameters, and MIDI control message types from the Destinations folder. When you map a screen control to all channel strips in a patch, the parameter to which the screen control is mapped changes to the same value for all channel strips in the patch when you move the screen control. Note: When you map a drum map using Send to All, the Send to All folder contains MIDI notes, not controllers. Undoing Parameter Mapping You can undo parameter mapping if you decide you don’t want to keep the mapping. When you undo parameter mapping, all mappings created in the current Learn mode (either by pressing Command-L or clicking the Map Parameter button) session are undone. To undo parameter mappings Do one of the following: µ Choose Edit > Undo (or press Command-Z). µ Press the Escape key. Removing Screen Control Mappings If you want a screen control to be free of any mappings, you can remove its existing mapping. This can be useful with controls that pass through MIDI messages (for example, for pitch bend and modulation wheels, or expression pedals) when you do not want them to send MIDI messages for their pass-through control type. You do not need to remove the mapping for a screen control when you remap it. To reset the mapping for a screen control 1 In the workspace, click the screen control you want to map. 2 In the column on the left of the Parameter Mapping browser, click None. 76 Chapter 5 Working in Edit ModeEditing Screen Control Parameters in Edit Mode In Layout mode, you edit basic screen control parameters that are constant throughout the entire concert. In Edit mode, you can edit screen control parameters for a specific patch or set. You can also override concert- and set-level mappings for an individual patch or set. Overriding Concert- and Set-Level Mappings By default, mappings you make at the concert level (to parameters and actions) take precedence over mappings to individual patches or sets in the concert. If you map a screen control to a parameter at the concert level (for example, to Master Volume), that screen control cannot be mapped to a parameter or action in a patch or set, unless you override the concert-level mapping. Similarly, mappings you make at the set level take precedence over mappings for any patches in the set. If you map a screen control to a parameter at the set level (for example, to an effect on a set-level channel strip), that screen control cannot be mapped to a parameter or action in a patch in the set, unless you override the set-level mapping. If you try to map a screen control that is mapped at the concert or set level, text appears in the Screen Control Inspector informing you that the screen control is mapped at another level, and the parameters in the Screen Control Inspector are dimmed. You can override the concert- and set-level mappings for an individual patch, and then map the screen control at the patch level. To override concert-level mappings µ In the Screen Control Inspector, select the Override Concert Mapping checkbox. Select the checkbox to override mappings at the concert level. The parameters in the Screen Control Inspector become active. To override set-level mappings and other parameters for a patch µ In the Screen Control Inspector, select the Override Set Mapping checkbox. Chapter 5 Working in Edit Mode 77The Parameter Mapping section becomes active so that you can map the parameter. Mapping tabs for concert-level mappings are available only at the concert level, and mapping tabs for set-level mappings are available only at the set level. When you override a concert- or set-level mapping, the mapping tabs become available at the level of the override. Replacing the Parameter Label You can replace the parameter label for a screen control (for an individual patch or set), to make the label easier to identify. To replace the parameter label for a screen control 1 Select the screen control in the workspace. 2 In the Screen Control Inspector, select the Attributes tab. 3 Select the Replace Parameter Label checkbox. 4 Enter the new label text in the field. Choosing a Custom Color for a Screen Control You can change the color of the active area of a screen control (for an individual patch or set). To choose a custom color for a screen control 1 Select the screen control in the workspace. 2 In the Screen Control Inspector, select the Attributes tab. 3 Select the Custom Color checkbox. 4 Choose a new color from the Custom Color pop-up menu. Choosing a Custom Image for a Panel Screen Control You can display a custom image for a panel control, and choose a different image for each patch or set. To choose a custom image for a panel screen control 1 In Edit Mode, Option-click the panel screen control in the workspace. Panel and Image controls appear in the Screen Control Inspector. 2 In the Screen Control Inspector, select the Custom Image checkbox. 3 Click Image, then click Select... An Open dialog appears. 4 Browse to the image you want to use, select the image, then click Choose Image. Choosing Custom Text Color for a Screen Control You can change the color of the text for a screen control (for an individual patch or set). 78 Chapter 5 Working in Edit ModeTo choose a custom text color for a screen control 1 Select the screen control in the workspace. 2 In the Screen Control Inspector, select the Attributes tab. 3 Select the Custom Label Color checkbox. 4 Choose a new color from the Custom Label Color menu. Setting a Screen Control to Show the Hardware Value By default, screen controls show the value of the parameter the control is mapped to. In some cases, for example, when the screen control is assigned to a foot pedal, or when the screen control is mapped to multiple parameters, it may be better to show the value of the hardware control assigned to the screen control. To set a screen control to show the hardware value 1 Select the screen control in the workspace. 2 In the Screen Control Inspector, select the Attributes tab. 3 Select the Show Input Value checkbox. Setting Parameter Change Behavior for Screen Controls You can set the behavior for saving parameter values for screen controls in individual patches. This is useful, for example, when the default for saving parameter values is set to Reset, but you want certain screen controls (for example, concert- and set-level screen controls) to keep their current value when switching patches. To set the behavior for saving parameter values in a patch 1 Select the patch. 2 Select the screen control for which you want to set the parameter change behavior. 3 In the Attributes tab of the Screen Control Inspector, choose the parameter change behavior for the screen control from the “When a patch is changed and screen value differs from saved patch” pop-up menu: • To have the screen control use the default behavior set in MainStage preferences, choose Preference. • To preserve changes to parameter values when you change patches, choose Keep. • To return values to the last saved value, choose Reset. When this value is chosen, you should save the concert after making any changes you wish to keep to the patch, before selecting another patch. • To have the screen control use the last received value from the physical control assigned to it, choose Match. When you choose an item from the pop-up menu, a brief description of its function appears below the menu. Chapter 5 Working in Edit Mode 79Important: If you set the behavior for saving parameter values in a patch to Reset, parameter values are also reset when you switch to Layout mode. Setting Hardware Matching Behavior for Screen Controls Some hardware synthesizers and music workstations let users control what happens when you move a physical control that is set to a different value than the parameter it modifies. The parameter value can instantly change to the position of the physical control (sometimes called jump), it can change by the same amount (called relative), or it can not change at all until the physical control matches its current value (called snap). You can set the behavior for screen controls in MainStage to any of these behaviors when you move the physical control assigned to the screen control. To set the behavior for screen controls when you move a hardware control 1 Select the patch. 2 Select the screen control for which you want to set the hardware matching behavior. 3 In the Attributes tab of the Screen Control Inspector, choose the parameter change behavior for the screen control from the “When hardware value differs from screen value” pop-up menu: • To have the screen control use the default behavior set in MainStage preferences, choose Preference. • To have the screen control instantly change to match the hardware value, choose Jump. • To have the screen control change when the hardware control matches its current value, choose Pickup. • To have the screen control move relative to the hardware control, choose Relative. Note: When you choose an item from the menu, a brief description of its function appears below the menu. Resetting and Comparing Changes to a Patch You can reset changes to all parameters in a patch that are mapped to screen controls to their last saved value, letting you hear the patch in its last saved (original) state, and toggle between the original and modified states of the patch. There are two ways to reset and compare changes to a patch: by using the Reset/Compare Patch button in the toolbar or by using the Reset/Compare Patch action mapped to a screen control at the concert level. To reset changes to mapped patch parameters using the Reset/Compare Patch button 1 With the patch selected, click the Reset/Compare Patch button. The patch is reset to its previously saved state. 2 To hear the patch in its modified state, click the Reset/Compare Patch button. 80 Chapter 5 Working in Edit ModeTo reset and compare changes using the Reset/Compare action 1 In Layout mode, add a button screen control to your layout. 2 Assign a button on your hardware controller to the new button screen control. 3 In Edit mode, click the concert icon in the Patch List. 4 Select the new button screen control in the workspace. 5 In the Parameter Mapping browser, select the Actions folder, and then select the Reset/ Compare Patch action in the second column. For more information about mapping a screen control at the concert level, see Controlling the Overall Volume of a Concert. Working with Sets in Edit Mode Sets are like folders that let you organize patches you want to keep together. Using sets, you can organize patches in any manner. For example, you can put all the patches you want to use in the first part of a performance together or keep all your lead synth patches together. Sets are flexible, so you can use them in whatever way suits your method of working. Here are some different ways you can use sets: • To group similar or related sounds into “banks” • To keep multiple patches you’ll use in a single song together • To share a set-level instrument or channel strip between a group of songs Creating Sets You can create a new, empty set or create a set from a group of selected patches. To create a new, empty set µ Choose New Set from the Action menu in the upper-right corner of the Patch List. A new set appears in the Patch List. To create a set from a group of patches 1 In the Patch List, select the patches you want to include in the new set. 2 Choose New Set From Selection from the Action menu at the upper-right corner of the Patch List. The new set appears in the Patch List containing the selected patches. You can add new patches to the set or drag existing patches into the set. Renaming Sets When you create a set, it is given a default name. You can rename a set in the same way you rename a patch in the Patch List. Chapter 5 Working in Edit Mode 81To rename a set 1 Double-click the set in the Patch List. A text field appears around the set name, which is selected. 2 Type a new name in the set name field. Setting the Time Signature for a Set You can set the time signature for a set. Time signatures can be used with the Playback plug-in and also affect the beats of the metronome. When you set the time signature for a set, it overrides the concert-level time signature (if one is set). To set the time signature for a set 1 In the Set Inspector, select the Has Time Signature checkbox. 2 Double-click the number in the field to the right, and enter the number of beats for one measure of the time signature. 3 Choose the beat value from the pop-up menu to the right. Changing the Tempo When You Select a Set You can give a set its own tempo setting so that when you select the set, the tempo changes to the set tempo setting. MainStage uses the new tempo until you select another patch or set with its own tempo setting, tap a new tempo, or until MainStage receives tempo information from incoming MIDI messages. For more information about using and changing tempo in MainStage, see Using Tempo in a MainStage Concert. To change the tempo using a set 1 In the Patch List, select the set. 2 In the Set Inspector, set the set tempo using the “Change Tempo to” value slider. 3 Select the “Change Tempo to” checkbox to activate the set tempo when the set is selected. Changing the Tuning for a Set By default, new sets (and most existing ones) use the same tuning method as the concert. You can change the tuning for a set so that it uses a different tuning. When you change the tuning method for a set, the patches in the set use the set-level tuning unless you change the tuning at the patch level. To change the tuning for a set 1 In the Set Inspector, select the Tuning tab. 2 Choose the tuning you want the set to use from the Method pop-up menu. 82 Chapter 5 Working in Edit ModeOverriding Concert-Level Key Ranges for a Set If a software instrument channel strip exists at the concert level, the concert-level channel strip takes precedence over any set-level software instrument channel strips within its key range. This means that when you play any notes in the key range of the concert-level channel strip on a keyboard controller, you hear only the concert-level channel strip, even when a patch is selected in a set with a set-level channel strip. You can override the concert-level channel strip for a channel strip at the set level so that the set-level channel strip takes precedence over the concert-level one. To override concert- or set-level key ranges 1 In the Patch List, select the set with the channel strip that you want to override the concert-level channel strip. 2 In the Channel Strips area, select the channel strip with the key range that you want to override the concert-level key range. 3 Select the “Override parent ranges” checkbox. Deleting Sets You can delete a set if you decide you no longer want it in the concert. To delete a set 1 Select the set in the Patch List. 2 Choose Edit > Delete (or press the Delete key). When you delete a set, the patches in the set are also deleted. To delete the set without deleting the patches, move the patches outside the set before you delete it. Working at the Set Level You can add channel strips at the set level and play the set-level channel strips together with every patch in the set. This can be useful, for example, if you want to use the same bass instrument in a single song or group of songs. You can place the patches for all of the songs in a set, add a channel strip at the set level, and then add a bass instrument to the set-level channel strip. You can set the key range of the bass instrument to play only notes in the lower octaves so that you can play it together with your patches. Important: If you add a channel strip at the set level, it takes precedence over all of the channel strips in all of the patches in the set. For example, if you add a software instrument channel strip at the set level, the software instrument for the set takes precedence over all of the software instruments in all of the patches in the set that fall within the same key range as the set-wide software instrument. To add a set-level channel strip 1 In the Patch List, select the set. Chapter 5 Working in Edit Mode 832 Click the Add Channel Strip (+) button at the top of the Channel Strips area. 3 In the New Channel Strip dialog, select the type of channel strip you want to create. 4 Choose the audio output for the channel strip from the Output pop-up menu. 5 For audio channel strips, choose mono or stereo format from the Format pop-up menu and choose the audio input from the Input pop-up menu. 6 Click Create. Sharing Patches and Sets Between Concerts You can export patches and sets from a concert and import them into another concert. When you import a set, all the patches in the set are imported. To export a patch Do one of the following: µ Drag the patch from the Patch List to the Finder. The patch appears as a .patch file in the Finder. µ Select the patch, choose “Save as Patch” from the Action menu in the Patch List, then click Save. The patch is exported to the ~/Library/Application Support/Logic/MainStage Patches folder. To export a set Do one of the following: µ Drag the set from the Patch List to the Finder. The set appears as a .patch file in the Finder. µ Select the set, choose “Save as Set” from the Action menu in the Patch List, then click Save. The set is exported to the MainStage Patches folder. Note: You can also export an entire concert as a set by selecting the concert and choosing Export Set from the Action menu. You can export multiple patches or sets. When you export multiple patches by dragging them to the Finder, each patch is exported as a .patch file. When you select multiple patches and export them using the Export Patch command, the patches are grouped into a single exported set. You can import patches or sets from the Finder to another open concert. 84 Chapter 5 Working in Edit ModeTo import a patch or set Do one of the following: µ In Edit mode, drag the patch or set from the Finder to the Patch List. µ Choose Load Patch/Set from the Action menu in the Patch List, select the patch or set you want to import, then click Import. Recording the Audio Output of a Concert You can record the audio output of a MainStage concert. When you record audio output, all audio on the output you choose is recorded (including the metronome, and so on). Before you record audio output, make sure the correct output, recording location, and file format are set in the Audio tab of MainStage preferences. For information about setting recording preferences, see Setting MainStage Preferences. To record audio in Edit mode µ Click the Record button in the toolbar. To turn off recording µ Click the Record button again. You can also map a screen control to the Record action to record audio in Perform and Full Screen modes, and assign a key command to the action to turn recording on or off using a hardware control. Chapter 5 Working in Edit Mode 85Concerts are the documents in which you create and organize the sounds you use in your performances, customize your onscreen layout, and make connections between your MIDI hardware and MainStage. A concert holds all the sounds you’ll use for an entire performance or a series of performances. In a concert, you add, edit, and organize patches, and select patches while you are performing. You can reorder patches in the Patch List and also organize them into sets. Concerts also contain layouts, where you visually arrange screen controls in the workspace and make connections between your hardware devices and MainStage. You can add and arrange screen controls and assign physical controls on your hardware MIDI devices to screen controls in Layout mode. For information about customizing your layout, see Working in Layout Mode. You can also control the volume for an entire concert, add concert-wide effects, and make other changes at the concert level. This chapter covers the following: • Opening and Closing Concerts (p. 88) • Saving Concerts (p. 89) • How Saving Affects Parameter Values (p. 89) • Setting the Time Signature for a Concert (p. 90) • Using Tempo in a MainStage Concert (p. 91) • Defining the Source for Program Change Messages for a Concert (p. 92) • Setting the Pan Law for a Concert (p. 93) • Changing the Tuning for a Concert (p. 93) • Silencing MIDI Notes (p. 93) • Muting Audio Output (p. 94) • Working at the Concert Level (p. 95) • Controlling the Metronome (p. 101) 87 Working with Concerts 6Opening and Closing Concerts You can create a new concert from a template, open an existing concert to continue working, and close and save concerts. You can add patches to a concert and organize them in the Patch List. The number of patches is limited only by the amount of available memory. You can add channel strips to an existing patch or to new ones you create and can organize patches into sets. For information about patches and sets, see Working in Edit Mode. The process of creating a new concert from a concert template is described in Choosing a Concert Template. You can open an existing concert to play the patches in the concert or continue editing them. To open an existing concert Do one of the following: µ Choose File > Open Concert, select the concert you want to open, then click Open. µ Choose File > New to open the Choose Template dialog, click “Open an Existing Concert,” then choose the concert from the Open dialog. µ In the Finder, double-click the concert. µ In the Finder, drag the concert over the MainStage icon in the Dock. You can also reopen a recently open concert by choosing File > Open Recent Concert and then choosing a concert from the submenu, or by opening the Choose Template dialog, clicking Recent Concert, then choosing the concert you want to open. By default, when you open a concert, it opens in Edit mode. You can change the default behavior in MainStage preferences. For more information, see Setting MainStage Preferences. The first time you open a concert, the first patch is selected, and the Patch Library is open so you can easily choose a patch setting. When you reopen a concert, the patch that was selected when you last saved the concert is selected. If any audio files or other assets are not found when you open a concert, a dialog appears showing which assets are missing, and asking if you want to search for the assets, locate them manually, or skip them. Note: When you open a concert created with an earlier version of MainStage, it opens as an untitled concert, and MainStage prompts you to save the concert as a MainStage 2 concert. To close a concert µ Choose File > Close Concert. If you have edited the concert since the last time you saved it, you are prompted to save your changes. 88 Chapter 6 Working with ConcertsSaving Concerts When you save a concert, all of the changes you made to the patches and sets in the concert, as well as the concert settings, are saved. To prevent losing your changes, be sure to save your work periodically. To save a concert 1 Choose File > Save Concert. 2 The first time you save a concert, the Save dialog appears. Enter a name for the concert, and browse to the location where you want to save it, then click Save. You can save a copy of a concert with a new name by choosing File > Save Concert As. You can save a concert together with the assets (audio files, instruments, Ultrabeat samples, and Space Designer impulse response files) the concert uses, similar to saving a Logic song as a project. To save a concert including its assets 1 Choose File > Save As. 2 In the Save As dialog, select the Include Assets checkbox. 3 Optionally, with the Include Assets checkbox selected, click the Advanced Options triangle, then select the types of assets you want to include with the concert. 4 Click Save. You can also save a concert as a template. When you save a concert as a template, the template is available in the My Templates section of the Choose Template dialog. To save a concert as a template 1 Choose File > Save as Template. 2 In the Save As dialog, enter a name for the template. 3 Click Save. By default, templates are saved in the MainStage Concerts folder. When you save a concert as a template, you can choose a different location to save the concert. If you save the concert in a different location, it will not be available in the Choose Template dialog. How Saving Affects Parameter Values While a concert is open, any “performance” changes you make to channel strip parameters (including volume, pan, and expression) or plug-in parameters are retained for as long as the concert is open. If you close the concert without saving, the parameter values revert to their previously saved state when you reopen the concert. If you save the concert before closing it, the changed values are saved. Chapter 6 Working with Concerts 89If you decide not to keep your latest changes, you can revert a concert to its previously saved state. To revert a concert to its last saved state µ Choose File > Revert to Saved. All the changes you’ve made since the last time you saved the concert are lost when you revert the concert to its last saved state. If you change parameter values in a patch, select another patch, and later select the first patch again, the parameter values will be as you left them when you selected the other patch. You can also choose the default behavior for saving changes to values of parameters to which screen controls are mapped. You can set the default to either have parameters keep their current value when changing patches (the default behavior in MainStage version 1.0), or to reset their values to the last saved value (similar to many hardware synthesizers). To set the default behavior for saving parameter values 1 Choose MainStage > Preferences. 2 In the Parameter Values section of the General preferences pane, choose the default behavior from the “On patch changes” pop-up menu. a To preserve changes to parameter values when you change patches, choose “Keep current value.” b To return parameters to their last-saved value when you change patches, choose “Revert to saved value.” You can also set the behavior for saving parameter values for screen controls in individual patches. For information, see Setting Parameter Change Behavior for Screen Controls. Setting the Time Signature for a Concert You can set the time signature for a concert. Time signatures can be used with the Playback plug-in and also affect the operation of the metronome. When you set the time signature for a patch or set, it overrides the concert-level time signature while the patch or set is selected. When you select a patch or set without a time signature, it uses the concert time signature. To set the time signature for a concert 1 In the Concert Inspector, select the Has Time Signature checkbox. 2 Double-click the number in the field to the