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

 

 

TELECHARGER LE PDF :

http://manuals.info.apple.com/en/ipod_touch_features_guide.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 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 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. 90 Chapter 6 Working with ConcertsUsing Tempo in a MainStage Concert Each concert has a tempo, which you can change in different ways while you are performing. Some plug-ins available in MainStage, including delay and tremolo effects, synthesizer LFOs, and the metronome, can require a specific tempo. You can set the initial tempo for a concert, and change the tempo by selecting a patch or a set with its own tempo setting. You can also change the tempo in real time by tapping a new tempo or have MainStage receive tempo changes from incoming MIDI messages. When you open a MainStage concert, the tempo setting in the Concert Inspector is used until you change the tempo by selecting a patch or set with its own tempo setting or by tapping a tempo. When you change the tempo, MainStage uses the new tempo until you change it again or until you close the concert. You can set the tempo for a concert in the Concert Inspector, which appears in the lower-left corner of the MainStage window when the concert icon is selected in the Patch List. By default, the tempo for new concerts is set to 120 beats per minute (bpm). To set the tempo for a concert 1 In the Patch List, select the concert icon. 2 In the Concert Inspector, set the tempo using the Tempo slider or value slider. Set the tempo by dragging the Tempo slider or using the value slider. You can use patches and sets to change the tempo when you select the patch or set while performing. For information about patch tempo settings, see Changing the Tempo When You Select a Patch. For information about set-level tempo settings, see Changing the Tempo When You Select a Set. Tapping the Tempo MainStage includes a “tap tempo” feature that allows you to set the tempo in real time while you perform. You can tap the tempo using the Tap Tempo button in the toolbar (if it is visible) or using a key command. To tap the tempo using the Tap Tempo button µ Click the Tap Tempo button in the toolbar several times at the desired tempo. Chapter 6 Working with Concerts 91For information about adding buttons to the toolbar, see Customizing the Toolbar. You can also tap the tempo using your computer keyboard. To tap the tempo using a computer keyboard µ Press Control-T several times at the desired tempo. You can also tap the tempo using a screen control mapped to the Tap Tempo action. For information about mapping screen controls to actions, see Mapping Screen Controls to Actions. Getting the Tempo from MIDI Input You can also have MainStage receive tempo changes from incoming MIDI messages. When the “Get tempo from MIDI input” checkbox is selected, MainStage listens to incoming MIDI clock messages for tempo information. If it receives tempo information, the concert tempo changes to the new tempo value. To get the tempo from incoming MIDI clock messages 1 In the Concert Inspector, select the “Get tempo from MIDI input” checkbox. 2 Choose the MIDI clock source from the Device pop-up menu. When the “Get tempo from MIDI input” checkbox is selected, the Tempo slider is dimmed and cannot be edited. If MIDI messages MainStage receives do not include MIDI clock information, MainStage uses the concert tempo setting and changes the tempo when you select a patch or a set with its own tempo setting, or tap a new tempo. If MainStage stops receiving MIDI clock messages, it continues to use the last received value for the tempo until you select a patch or set with its own tempo setting or tap a new tempo. Defining the Source for Program Change Messages for a Concert By default, MainStage receives and responds to program change messages from all connected MIDI controllers. Some MIDI controllers, however, send program change messages while performing other operations. You can define the source for program change messages for a concert, so the concert responds to messages for only one MIDI device, port, or channel. To define the source for program change messages 1 In the Attributes tab of the Concert Inspector, choose the device or port from which the concert will receive program change messages from the Device pop-up menu. 2 If you want to limit messages to a single MIDI channel on the device, choose the MIDI channel from the Channel pop-up menu. 92 Chapter 6 Working with ConcertsSetting the Pan Law for a Concert Audio signals panned to the center position may sound louder than signals panned hard left or right. The Pan Law value determines the amount of volume reduction applied to audio that is panned to the center position. You can choose from the following settings: • 0 dB: With no change to the volume level, signals will seem louder when panned to the center position, in comparison with extreme left or right pan positions. • −3 dB: A full scale signal (0 dBfs) will have a level of −3 dB when panned to the center position. • −3 dB compensated: A full scale signal (0 dBfs) will have a level of 0 dB when panned to the center position (or +3 dB when panned to extreme left or right positions). To set the pan law for a concert µ In the Attributes tab of the Concert Inspector, choose the pan law value for the concert. Changing the Tuning for a Concert By default, concerts use equal tempered tuning. You can change the tuning for a concert so that it uses a different tuning. To change the tuning for a concert 1 In the Concert Inspector, select the Tuning tab. 2 Choose the tuning you want the concert to use from the Method pop-up menu. When you change the tuning of a concert, the tuning of the patches and sets in the concert changes if their Tuning Method is set to “Use parent tuning.” Patches and sets with a different tuning method are not affected. Silencing MIDI Notes MainStage also includes a Panic function, which works like the Panic function in Logic Pro. The Panic function immediately silences any hanging MIDI notes. To silence all MIDI notes Do one of the following: µ Press Control-P. µ Double-click the MIDI Monitor in the toolbar. µ If the Panic button is visible in the toolbar, click it. µ If you have mapped the Panic function to a screen control, press or move the corresponding controller. Chapter 6 Working with Concerts 93If the Panic button is not visible in the toolbar, you can customize the toolbar by adding a Panic button. For information about customizing the toolbar, see Customizing the Toolbar. Muting Audio Output Sometimes when you are playing or editing sounds, you may want to quickly mute (silence) all audio output for the concert. MainStage includes a Master Mute button that silences the output from every patch in the concert. To quickly mute all sound Do one of the following: µ Press Control-M. µ In the toolbar, click the Master Mute button. µ If you have mapped the Master Mute function to a screen control, press or move the corresponding controller. The Master Mute button changes to show that the output is muted (a red diagonal line covers the speaker icon). All output remains muted until you click the Master Mute button again. To unmute all sound Do one of the following: µ Press Control-M again. µ In the toolbar, click the Master Mute button again. µ If you have mapped the Master Mute function to a screen control, press or move the corresponding controller. Master Mute is also a mappable parameter in the Parameter Mapping browser. You can map Master Mute to a button or other controller in your concerts so that you can quickly mute all output when you are playing live in Perform or Full Screen mode. In addition, you can mute audio output for a single channel strip by clicking its Mute (M) button. 94 Chapter 6 Working with ConcertsWorking at the Concert Level You can control the overall volume for a concert and make other changes at the concert level. You can use busses at the concert level to control concert-wide effects or to control the output of multiple channel strips assigned to the bus. You can also add channel strips at the concert level and have the concert-level channel strips available with every patch in the concert. You can map screen controls to busses and to concert-level channel strips only at the concert level, not at the patch or set level. To make changes at the concert level µ In Edit mode, select the concert icon in the Patch List. Click the concert icon in the Patch List to work at the concert level. Controlling the Overall Volume of a Concert A MainStage concert contains Output and Master channel strips that you can use to control the overall volume of the concert. The Master channel strip always controls the output volume of the entire concert. If the concert has multiple Output channel strips, each Output channel strip controls the volume level for a particular (mono or stereo) physical output. You can use the Output and Master channel strips to control the overall volume in the same way you control the overall volume of a Logic Pro project. Chapter 6 Working with Concerts 95To see all of the channel strips, you may need to resize the Channel Strips area. At the concert level, the Channel Strips area shows the Output and Master channel strips, auxes, and other concert-level channel strips. To control the overall volume level of a concert µ Drag either the Output 1-2 volume fader or the Master volume fader. You can map a screen control to a channel strip parameter or an action at the concert level. For example, you can map the Output 1-2 Volume fader to a fader screen control and use the hardware control assigned to that screen control to adjust the overall volume of the concert. To map a screen control at the concert level 1 Make sure the concert icon is selected in the Patch List. 2 Click the screen control you want to map. The Parameter Mapping browser appears below the workspace. 3 In the Parameter Mapping browser, click the parameter to which you want to map the screen control. 96 Chapter 6 Working with ConcertsIn the example above, you would click the fader screen control, click Out 1-2 in the left column of the Parameter Mapping browser, and then click Volume in the second column of the browser. Screen controls can also display visual feedback about parameter values, including volume level. For example, you can also map the Output 1-2 Volume fader to a level meter screen control and have the level meter display the overall volume level while you are performing live. In this case, you would map the level meter to Level in the second column of the browser, rather than to Volume. When you map a screen control at the concert level, you cannot map the same screen control at the patch or set level unless you override the concert-level mapping. For information about overriding concert-level mappings, see Overriding Concert- and Set-Level Mappings. Adding Concert-Wide Effects You can add concert-wide effects such as reverb and delay using auxiliary (aux) channels. When you choose a bus from the Send slot on a channel strip, a corresponding aux appears at the concert level. You can insert effects on the aux and have those effects apply to every channel strip sending its signal to the aux. To send a channel strip signal to an aux 1 In the Patch List, select the patch you want to use with a concert-wide effect. The channel strips for the patch appear in the Channel Strips area. Chapter 6 Working with Concerts 972 On the channel strip, click one of the Send slots and choose a bus from the menu. Choose a bus from one of the Send slots. 3 Drag the Send knob next to the slot to set the amount of the signal sent to the aux. To add a concert-wide effect to an aux 1 In the Patch List, select the concert icon. The auxes in the concert appear in the Channel Strips area along with the concert-level channel strips. 2 On an aux, click one of the Insert slots and choose an effect from the menu. After you add an effect to an aux, you can edit the effect as you would any channel strip effect, by double-clicking it to open the plug-in window, and then adjusting parameters in the plug-in window. You can add multiple effects to an aux, and adjust the level and pan of the aux using the channel strip controls on the aux. 98 Chapter 6 Working with ConcertsYou can also add concert-wide effects to an aux at the patch level if Show Signal Flow Channel Strips is active. For information about showing signal flow channel strips in the Channel Strips area, see Showing Signal Flow Channel Strips. Using Auxes to Control Channel Strip Output You can also send the output of multiple channel strips to an aux (auxiliary channel) and then use the aux to control the volume level and pan position of the channel strips. Sending the output to an aux is also useful for adding EQ or compression to a group of patches. To send the output of a channel strip to an aux 1 In the Patch List, select the patch you want to control using an aux. 2 In the channel strip, click the Output slot and choose a bus from the menu. When you send channel strip output to an aux, the volume fader of the channel strip controls how much of the signal is sent to the aux. To control the output of channel strips using an aux 1 In the Patch List, click the concert. The concert is selected. The busses added to the concert appear in the Channel Strips area along with the concert-level channel strips. 2 Drag the Volume fader on the aux to adjust the volume level of the overall aux output. 3 Drag the Pan knob on the aux to adjust the pan position of the overall aux output. When you control the output of multiple channel strips using an aux, their relative volume levels and pan positions are preserved, but the overall volume level and pan position are modified by the aux Volume fader and Pan knob. Adding Channel Strips at the Concert Level You can add a channel strip at the concert level and use the concert-level channel strip for a software instrument or audio input you want to use in every patch in the concert. Important: When you add a channel strip at the concert level, it takes precedence over the channel strips in the patches and sets in the concert. For example, if you add a concert-level channel strip containing a software instrument, the software instrument takes precedence over all of the software instruments in all of the patches and sets in the concert, for the notes in its key range. This means that you will hear only the sound of the concert-level software instrument and will not be able to play any software instruments in a patch or set that fall in the same key range. To add a concert-level channel strip 1 In the Patch List, select the concert. 2 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. Chapter 6 Working with Concerts 994 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. 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 Click Create. 7 For software instrument channel strips, you can define the key range for the channel strip in the Channel Strip Inspector so that the concert-level channel strip does not overlap software instruments you plan to use in your patches and sets. For information about defining the key range of a channel strip, see Creating Keyboard Layers and Splits. When you add a channel strip at the concert level, you can map screen controls to the channel strip only at the concert level, not for individual patches or sets. Using the MainStage Clock Some plug-ins, including the Playback and Ultrabeat plug-ins included with Logic Studio, require a time source, and use beat and tempo information in order to play in time. Additionally, some third-party applications and plug-ins using their own sequencer or playback engine may behave differently than sequencer-based plug-ins included in Logic Studio. These plug-ins (which include Reason and other ReWire applications and Reaktor) require a play message from the host application to begin playback and require a stop message to end playback. They may also require a continue (also sometimes called “resume”) message to continue playback from their current time position. MainStage includes an internal beat clock or “time base” that you can use to control the playback of these plug-ins. The MainStage clock generates beat, time position, and tempo information so sequencer-oriented plug-ins can start, stop, and play in time. The MainStage clock operates similarly to the song position in Logic Pro. You can send play and stop messages in the following ways: • Using the Play/Stop button in the toolbar, if it is visible • Using the Metronome button in the toolbar, if it is visible (turning on the metronome also starts the MainStage clock, if it is not already running) • Using a screen control mapped to the Play/Stop, Play, or Stop action • Using a screen control mapped to the Continue action to resume playback of a third-party plug-in (but not a Playback plug-in) 100 Chapter 6 Working with ConcertsDifferent plug-ins can make use of the MainStage clock in different ways, depending on what information they require and what mode they are set to. Some plug-ins may only make use of the beat information, while others may only make use of tempo information. For example: • The Playback plug-in can start immediately (if Snap To is set to Off), at the beginning of the next bar (if Snap To is set to Bar), or at the next beat (if Snap To is set to Beat). It can also start when you start the MainStage clock (if “Start with Play Action” is selected in the Action menu). • UltraBeat starts when you start the MainStage clock if its sequencer is turned on, except in Pattern mode. • Reason and other ReWire applications start when you start the MainStage clock, and stop when you stop the MainStage clock. • For plug-ins with synchronizable LFOs, the LFO can oscillate at the tempo set by the MainStage clock. You can view the beat information of the MainStage clock using a Parameter Text screen control mapped to the Beat Count action. When the MainStage clock is running, the current bar and beat are displayed in the screen control. Important: When you start the MainStage clock, the audio engine is reset, causing a brief interruption in the audio output from MainStage. In some cases, you may want to start the MainStage clock at the beginning of a song or performance and use screen controls mapped to individual plug-in parameters to start and stop those plug-ins to avoid an interruption in the audio output while you are performing. Controlling the Metronome MainStage features a metronome that you can use to play in time with the concert tempo. The metronome always plays at the current tempo of the concert. You can start the metronome in one of several ways. To start the metronome Do one of the following: µ Click the Metronome button in the toolbar, if it is visible. Chapter 6 Working with Concerts 101µ Click a button mapped to the Metronome action. µ If you are using a Playback plug-in, click the Metronome button in the Playback window (or click a button mapped to the Metronome button). µ Click any of the listed buttons again to stop the metronome. Note: Starting the metronome also starts the MainStage clock if it is not already running. By default, the metronome sound is routed to the main outputs (Output 1-2). You can route the metronome to another output pair, which can be useful in performance when you want to hear the metronome sound through a separate audio output (for example, a headphone mix) and not through the main outputs. To change the audio output for the metronome sound 1 Choose MainStage > Preferences. 2 In the Metronome section of the General tab, choose a different audio output from the Output pop-up menu. You can also change the volume of the metronome relative to the overall audio output. To change the relative output of the metronome sound 1 Choose MainStage > Preferences. 2 In the Metronome section of the General tab, drag the volume slider left or right to adjust the relative volume of the metronome sound. 102 Chapter 6 Working with ConcertsYou visually arrange your onscreen layout and make connections between your music hardware and MainStage in Layout mode. You can’t change the position of physical faders, knobs, and other controls on your instruments and other music hardware, but you can arrange the screen controls in your MainStage concert in any order you like by editing the layout. You can modify an existing layout or create one from a template, and you can export a layout and import it into another concert. Each concert template included with MainStage includes a built-in layout, optimized for a type of musical instrument you use with MainStage. You modify the layout of a concert in Layout mode. You can add and arrange screen controls in the MainStage workspace to match your music hardware, optimize your display size, and make assignments between controls on your MIDI hardware and the screen controls in your concert. Below the workspace, the Screen Controls palette contains different types of screen controls you can add to your layout. The Screen Control Inspector appears to the left of the workspace, where you can learn controller assignments and edit layout parameters. This chapter covers the following: • Modifying the Layout of a Concert (p. 104) • Working with Screen Controls (p. 104) • Assigning Hardware Controls to Screen Controls (p. 114) • Editing Screen Control Parameters (p. 116) • How MainStage Passes Through MIDI Messages (p. 121) • Exporting a Layout (p. 122) • Importing a Layout (p. 122) • Changing the Aspect Ratio of a Layout (p. 123) 103 Working in Layout Mode 7Modifying the Layout of a Concert You can modify an existing layout by adding and arranging screen controls in the workspace, changing existing controller assignments or making new ones, and editing screen control parameters. The following sections describe how to add and arrange controls onscreen, make hardware assignments, change the appearance of screen controls, and edit layout parameters. You can also export a layout and import the layout into a different concert. For information about importing and exporting layouts, see Exporting a Layout. To work with the layout of a concert, you switch to Layout mode. To switch to Layout mode µ Click the Layout button at the upper-left corner of the MainStage window. Working with Screen Controls Screen controls are objects in a MainStage concert that correspond to the physical controls on your music hardware. Screen controls can also display patch numbers, parameters values, and other information and update the displayed information in real time. You can add screen controls to the workspace of your concert, where you can move and resize them, group them together, and edit their appearance in different ways. After you have arranged the screen controls for your concert, you make connections between your MIDI hardware and the concert by assigning physical controls on your hardware to the screen controls in the workspace. You only need to make hardware assignments for a concert once, as long as you are using the same music hardware. After you make controller assignments, you can map screen controls to channel strip parameters in your patches or to actions. You map parameters in Edit mode. For information about mapping parameters, see Mapping Screen Controls. Screen Control Types There are three types of screen controls you can use in a MainStage layout: panel controls, shelf controls, and grouped controls. In the Screen Controls palette, located below the workspace in Layout mode, each type has its own tab; in addition, there is a tab for all controls. You can add screen controls to the workspace by dragging them from the palette to the workspace. 104 Chapter 7 Working in Layout ModeAdditionally, if you create and add a grouped control to the Screen Controls palette, a tab for My Grouped Controls appears in the palette. You can add your custom grouped controls to the palette, so they will be available in every concert. Panel Controls Panel controls appear on a two-dimensional plane (or panel) in the workspace. You can move a panel control to any position in the workspace, except onto the shelf of a shelf control. Panel controls include: • MIDI Activity light (displays MIDI note activity, and can be used as a substitute “keyboard”) • Round and directional knobs • Vertical and horizontal faders • Button • Drum pad • Vertical and horizontal level meters (used to visually display volume level or another parameter) • VU meter (used to visually display volume level or another parameter) • Parameter text (used to dynamically display parameter names and values) • Organ drawbar • Progress indicator (used with the Playback plug-in) • Waveform (used with the Playback plug-in) • Selector (used to select patches while you are performing, or to select markers for use with the Playback plug-in) • Text (used to display song lyrics, performance notes, and other static information) • Background (used to group a series of controls) Chapter 7 Working in Layout Mode 105Shelf Controls When you add a shelf control, it appears on a three-dimensional shelf. You can move the shelf, adjust the angle of the shelf, and place multiple shelf controls on the same shelf. For example, if you have a keyboard screen control in your layout, you can add pitch bend wheel and modulation wheel screen controls to the same shelf as the keyboard screen control. Shelf controls include: • Keyboard • Modulation or pitch bend wheel • Sustain pedal • Foot pedal • Foot switch Grouped Controls Grouped controls consist of individual controls that are grouped together to make them easier to work with as a single unit. Grouped controls include: • Selector grouped with increment and decrement buttons • Keyboard grouped with mod wheel, pitch bend wheel, and sustain pedal • Sustain and expression pedals • Organ drawbars • Guitar amp controls • Guitar pedal controls • Arrays of knobs and faders with uniform size and spacing • Effects and tone control knobs • Arrays of level meters and VU meters • Arrays of parameter text displays • Master output fader grouped with stereo level meter • Arrays of drum pads • Transport controls for use with Playback plug-in • Channel strip controls My Grouped Controls The first time you add a custom grouped control to the Screen Controls palette, the My Grouped Controls tab appears in the palette. You can add custom grouped controls and name them so they will be accessible from every concert. For information about adding custom grouped controls to the Screen Controls palette, see Grouping Screen Controls. 106 Chapter 7 Working in Layout ModeAdding Screen Controls to a Layout In Layout mode you can quickly add screen controls to your layout and arrange them in the workspace. To add a screen control µ Drag the screen control from the Screen Controls palette to the workspace. As you drag the screen control to the workspace, a white outline appears, showing where it will be added. You can use the alignment guides to align the screen control with other items in the workspace. You can drag screen controls into the workspace in any order. If you plan to perform with a keyboard controller, you might want to first drag a keyboard screen control into the workspace, position it near the center, and then drag screen controls for the faders, knobs, wheels, buttons, and other physical controls on the keyboard controller. When you drag a screen control into the workspace, the control is selected, and the available hardware assignments and other parameters for the screen control appear in the Screen Control Inspector to the left of the workspace. Different types of screen controls have different parameters, which are described in Editing Screen Control Parameters. Adding Mod/Pitch Wheel Screen Controls When you add mod/pitch wheels to a layout, by default they are configured to receive the following MIDI message types: • The first mod/pitch wheel is configured to receive modulation messages. • The second mod/pitch wheel is configured to receive pitch bend messages. • The third mod/pitch wheel is configured to receive aftertouch messages. By default, modulation and pitch bend screen controls pass through the MIDI messages for their common use—that is, mod wheels pass through MIDI modulation messages, and pitch bend wheels pass through MIDI pitch bend messages. In most cases this is desirable so that you can use them for their standard functions without any additional setup. If you want to use these screen controls to control other parameters, choose “Do not pass thru” from the MIDI Thru pop-up menu in the Screen Control Inspector. Adding Foot Pedal Screen Controls When you add a foot pedal to a layout, by default the first foot pedal you add is configured to receive expression messages, and the second foot pedal you add is configured to receive volume messages. By default, expression pedal screen controls pass through the MIDI messages for their common functions (expression or volume). If you want to use an expression pedal screen control to control another parameter, choose “Don’t pass thru” from the MIDI thru pop-up menu in the Screen Control Inspector. Chapter 7 Working in Layout Mode 107Copying and Pasting Screen Controls You can copy and paste screen controls using the standard Mac OS X menu items and key commands. To paste a copy of a screen control Do one of the following: µ Press Command-C to copy the selected screen control, then press Command-V to paste a copy. µ Option-drag the screen control to a new location in the workspace. To add multiple instances of the same screen control in a row or column 1 Option-drag the screen control to create the first copy. 2 Choose Edit > Duplicate to create as many additional copies of the screen control as you want. The duplicated screen controls appear offset by the same amount as the first copy. Option-drag the selected screen control. Duplicate additional copies in a row. Note: You can’t copy a panel control and a shelf control at the same time. Moving Screen Controls You can move screen controls to a new position whenever you are in Layout mode. You can use the alignment guides to help align and position screen controls in an orderly arrangement. You can move multiple controls together by selecting them (either by Shift-clicking or “rubber-banding” them) and then dragging them to a new position. If the panels for the screen controls are merged, rubber-banding selects the entire panel. To move a screen control Do one of the following: µ Drag the screen control to a new position in the workspace. µ Select the screen control, then press the arrow keys to move it in the workspace. 108 Chapter 7 Working in Layout ModeTo move multiple screen controls Do one of the following: µ Shift-click the screen controls, then drag them to a new position. µ Hold down the Shift key as you drag around the controls, then drag them to a new position. You can constrain the movement of screen controls to either horizontal or vertical by pressing Shift while dragging them. If a screen control overlaps another screen control in the workspace when you switch from Layout mode to another mode, an alert appears, asking if you want the overlapped controls to be highlighted so you can adjust them before leaving Layout mode. Resizing Screen Controls You can resize screen controls to make them more easily visible or to fit them into a smaller area. When you select a screen control, blue resize guides appear over it that you can drag to resize the control. To resize a screen control 1 Select the screen control in the workspace. Blue resize guides appear over the screen control. 2 Drag the resize guides to resize the screen control. Drag the outer resize guides to resize the screen control. For screen controls with a text display area, such as a knob or fader, you can resize the text display area independently from the control or resize them together. To resize the text display area of a screen control 1 Select the screen control in the workspace. 2 Drag the inner resize guide to increase the area of the text display. Chapter 7 Working in Layout Mode 1093 Drag the outer resize guide to increase the overall size of the control. Drag the inner resize guide to resize the text area. Notice that when you resize the text display area, the rest of the screen control becomes smaller. You can first resize the overall control, and then resize the text display area using the inner resize guide. Aligning and Distributing Screen Controls MainStage includes controls for centering, aligning, and distributing screen controls in the workspace. To align screen controls 1 Select the screen controls in the workspace. 2 Do one of the following: • To align the top edges of the screen controls, click the Align Top button. • To vertically align the centers of the screen controls, click the Align Vertical Centers button. • To align the bottom edges of the screen controls, click the Align Bottom button. • To align the left edges of the screen controls, click the Align Left button. • To horizontally align the centers of the screen controls, click the Align Horizontal Centers button. • To align the right edges of the screen controls, click the Align Right button. To distribute screen controls evenly 1 Select the screen controls in the workspace. 2 Do one of the following: • To vertically distribute the screen controls, click the Distribute Vertically button. • To horizontally distribute the screen controls, click the Distribute Horizontally button. 110 Chapter 7 Working in Layout ModeYou can also align and distribute screen controls by Control-clicking the selected screen controls and choosing commands from the Align and Distribute submenus in the shortcut menu. The Distribute shortcut menu contains additional controls for distributing the space between screen controls. Adjusting the Shelf for a Shelf Control When you add a shelf control such as a keyboard to the workspace, it appears at a default angle, creating a three-dimensional appearance. You can adjust the angle of the shelf control so that it appears more or less three-dimensional. This can be useful, for example, if you want to see more of the keys on the keyboard or minimize the amount of space it occupies onscreen. To adjust the angle of the shelf for a shelf control 1 In the workspace, select the shelf control. White alignment guides for the control’s shelf appear. Alignment guides 2 Drag the lower alignment guide (the one aligned with the front of the shelf control). Drag the lower alignment guide down to make the angle steeper (as though you are looking down on the shelf control from above), or drag it up to make the angle less steep (as though you are looking at it from the front). Drag the front (lower) alignment guide to change the angle of the shelf. Chapter 7 Working in Layout Mode 111Moving the Shelf Vertically You can also move the shelf vertically to change its position in the workspace. When you move the shelf vertically, all screen controls on the shelf (for example, a modulation or pitch bend wheel and a keyboard) move with the shelf. To move a shelf vertically 1 Select one of the screen controls on the shelf. The alignment guides for the shelf appear. Drag the rear (upper) guide to move the shelf vertically. 2 Place the pointer over the upper alignment guide (the one aligned with the rear of the shelf control). The pointer becomes a move pointer (a horizontal bar with up and down arrows). 3 Drag the upper alignment guide to move the shelf to a new position. Grouping Screen Controls You can group screen controls together, creating a grouped control. You can move and resize the grouped control as a single unit. Grouping screen controls has no effect on how they work in performance, but makes it easier to quickly create a layout. You can group screen controls using the Group button, using the shortcut menu, or using a background screen control. To group screen controls using the Group button 1 Select the screen controls you want to group together. The Group button is highlighted, indicating that the selected controls can be grouped. 2 Click the Group button, located below the align and distribute buttons on the left edge of the workspace (or press Command-Shift-G). The screen controls are grouped into a single, grouped control. If there is no background around the screen controls, one is added to encompass them. Selecting any member of the group selects the entire group so you can move and resize them together. When you group screen controls, the edges of the background appear “dotted” to indicate that the controls are grouped. When grouped controls are selected, the Ungroup button is highlighted, indicating that the controls are grouped. 112 Chapter 7 Working in Layout ModeTo group screen controls using the shortcut menu 1 Select the screen controls you want to group together. 2 Control-click the selected controls, then choose Group from the shortcut menu. To group screen controls using a background screen control 1 Drag a background screen control to the workspace. 2 Size and position the background screen control. 3 Drag the screen controls you want to include in the grouped control so they are within the borders of the background screen control. If you want to move one of the grouped controls separately, you can ungroup the controls. To ungroup screen controls 1 Select the grouped control. 2 Click the Group button again (or press Command-Shift-Option-G). You can quickly add one or more screen controls to a group. To add a screen control to a group µ Drag the screen control into the group. You can also move and resize individual controls in a group without ungrouping them. To move or resize a screen control in a group 1 Select the individual screen control you want to move or resize. The handles of the screen control appear so you can move or resize it independently from the group. 2 Hold down the Command key as you move or resize the screen control. You can add a panel or an image to the background of a grouped control to recreate the look of a hardware panel and visually distinguish the grouped control in the workspace. To add a panel to a background 1 Select the background. The Screen Control Inspector appears to the left of the workspace. 2 In the Appearance section of the Screen Control Inspector, click the Panel well, and choose a panel from the menu. If an image has been previously selected for the background, select the Panel button before choosing a texture for the background. To add an image to a background 1 Select the background. The Screen Control Inspector appears to the left of the workspace. Chapter 7 Working in Layout Mode 1132 In the Appearance section of the Screen Control Inspector, select the Image button. 3 Do one of the following: • Drag an image to the Image well. • Click the Select button, then navigate to the location containing the image you want to use, and select the image. You can add custom grouped controls to the Screen Controls palette, and use them in the same concert or another concert. Grouped screen controls you add to the palette appear in the My Grouped Controls tab. To add a grouped control to the Screen Controls palette Do one of the following: µ Control-click the grouped control, then choose Add to Palette from the shortcut menu. µ Select the grouped control, then choose Add to Palette from the Action menu at the upper-right corner of the workspace. After you add the first grouped control to the Screen Controls palette, the My Grouped Controls tab appears. Select this tab (or the All tab) to see the custom grouped controls you have added to the Screen Controls palette. Deleting Screen Controls If you decide you no longer want a screen control in your layout, you can delete it from the workspace. To delete a screen control 1 Select the screen control you want to delete. 2 Choose Edit > Delete (or press the Delete key). When you delete a screen control, any assignments or mappings for the screen control are deleted as well. Assigning Hardware Controls to Screen Controls To use MainStage with a MIDI controller, you assign hardware controls on the controller (such as faders, knobs, buttons, drum pads, and pedals) to screen controls in the workspace. After you assign a hardware control to a screen control, the screen control receives the MIDI messages from the hardware control. You only need to make controller assignments once for a concert as long as you use it with the same hardware. You assign hardware controls to screen controls using the Learn process, which is similar to the process for learning controller assignments for a control surface in Logic Pro. The Learn process is described in Learning a Controller Assignment. 114 Chapter 7 Working in Layout ModeWhen you assign a hardware control using the Learn button, MainStage determines the type of MIDI message the control sends when you move it, and the range of values the control is capable of sending. When you map the screen control to a channel strip parameter or an action, MainStage converts (or “maps”) the range of values sent by the hardware control to the optimal range of values usable by the parameter. For example, many faders, knobs, and other MIDI controls send a range of numeric values between 0 and 127. You could map a hardware knob with this range of values to control the frequency parameter of an EQ effect, which has a range of usable values between 20 Hz and 20 kHz. When you map the screen control for the knob to the EQ frequency parameter, MainStage converts the values sent by the hardware knob to be distributed between the minimum (20 Hz) and maximum (20 kHz) values for the parameter. Assigning Knobs MIDI controllers can have different types of knobs or rotary controllers. Knobs can be either absolute controllers, which send a fixed value determined by the knob’s position or can be relative controllers, which increment or decrement the previous value regardless of their exact position. Knobs can either have a fixed range of movement, or be continuous (sometimes called endless rotary encoders). When you assign a knob screen control using the Learn button, MainStage attempts to determine which type of knob or rotary control on your hardware is sending the MIDI message and sets the value in the Type pop-up menu in the Screen Control Inspector to the correct value. For absolute controllers, the correct value is Absolute; for relative controllers, the correct value can be either Relative (2’s complement) or Relative (Sign magnitude), depending on the type of relative controller. In most cases, there is no need to change the default values unless you intend to use the knob for a specific, non-standard purpose. When you assign a knob screen control, be sure Absolute is chosen from the Type pop-up menu if the hardware controller is an absolute rotary controller, or one of the Relative values is chosen if the hardware controller is a continuous rotary encoder. Moving the knob through its full range of motion helps ensure that MainStage correctly determines the type of knob you are assigning. Assigning Buttons MIDI controllers can have different types of buttons. Some buttons send a single value each time you press them, while others alternate between two values when pressed. Other buttons can send separate values when they are pressed and released (this type of button is called a momentary or temporary button). Chapter 7 Working in Layout Mode 115When you assign a button screen control using the Learn button, MainStage attempts to determine which type of button on your hardware is sending the MIDI message, and sets the value in the Type pop-up menu in the Screen Control Inspector to the correct value for that button type. To enable MainStage to determine the correct value, press the button exactly three times when you are learning it. Pressing the button three times helps ensure that MainStage determines if the button is a single value, an alternating value (binary), or a momentary button. In most cases, there is no need to change the default values unless you intend to use the button for a specific, non-standard purpose. You can change the function of a momentary button to match the function of a single value or alternating value button in MainStage. To change the function of a momentary button 1 In Layout mode, be sure the button screen control is selected. 2 In the Screen Control Inspector, choose either Single Value or Alternating Value from the Type pop-up menu. Choose Single Value if you want the button to function as a single value button, or choose Alternating Value if you want the button to function as an alternating value button. You cannot change the function of a single value or alternating value button to match the function of a momentary button. Editing Screen Control Parameters When you select a screen control in Layout mode, the parameters for the screen control appear in the Screen Control Inspector where you can edit them. Most screen controls share the same common parameters, but some types have different parameters according to their function. The parameters for each type are described in the following section. For most Hardware Input parameters, there is no need to change the default values MainStage sets when you learn a controller assignment unless you intend to use the screen control for a specific, non-standard purpose. To edit screen control parameters 1 In Layout mode, select the screen control. (When you drag a screen control to the workspace, it is selected.) 2 In the Screen Control Inspector, edit the parameters for the selected screen control by choosing the menu item, typing text, clicking the button, or selecting the checkbox for the parameters you want to edit. 116 Chapter 7 Working in Layout ModeLifting and Stamping Screen Control Parameters You can “lift,” or copy, certain parameters from a screen control and “stamp” them onto other screen controls. This makes it easy to give multiple screen controls the same size, appearance, and text attributes to create a uniform look in your layout. Parameters affected by lift and stamp include the parameters in the Appearance and Text Labels headings in the Screen Control Inspector (except the control type), as well as the size of the screen control. To lift parameters from a screen control µ Control-click the screen control in the workspace, then choose Lift Attributes from the shortcut menu. To stamp parameters onto another screen control µ Control-click the screen control in the workspace, then choose Stamp Attributes from the shortcut menu. You can Shift-click to select multiple screen controls, then Control-click the selection. Common Screen Control Parameters You can edit the following common parameters for button, knob, fader, knob, pedal, footswitch, mod/pitch wheel, meter, VU meter, organ drawbar, progress indicator, and parameter text screen controls. Hardware Input • Device pop-up menu: Shows the name of the device containing the assigned control. The device name may correspond to the name of a keyboard controller, or to a port on the controller, if it has multiple ports. You can choose another device, All, or Unassigned. • Channel pop-up menu: Choose the MIDI channel on which MainStage receives input from the controller. If you plan to use more than one keyboard when you perform, be sure that screen controls such as faders and knobs are assigned to receive input from the correct controller using the Device and Channel pop-up menus. • Type pop-up menu: Choose the type of control messages to which the control responds. Control types include the following three categories: • Continuous Control: Includes knobs, rotary encoders, faders, and most pedals that send values in the range of 0-127. In most cases, these controls are set to Absolute. Some rotary encoders can be set to Relative after you program the hardware device to send relative controller messages. The different types of Relative control messages represent different encoding types used by different vendors (who may refer to them by proprietary names). • Button Control—Toggle Only: Includes buttons that send either one (Single) or two (Alternating) values. Chapter 7 Working in Layout Mode 117• Button Control—Toggle or Momentary: Includes drum pads and other buttons that send a value when the button is released as well as when it is pressed. • Number pop-up menu: Choose the MIDI control number that the control sends. For common MIDI controls, such as volume, the control name appears in the menu along with the number. • MIDI Thru pop-up menu: Choose whether the control automatically passes MIDI through or does not pass MIDI through. • Send Value to pop-up menu: Sends the current value of the screen control to supported devices to display using an LED ring around a rotary encoder or to move a motorized fader. Appearance • Color selector: Choose the color for the active part of the screen control, which visually displays its current value in performance. (This parameter is not available for text or meter screen controls.) • Control pop-up menu: Choose the type for the screen control. If you change the control to a different type, you may need to resize it in the workspace. Text Labels • Color selector: Choose the color for the text labels. • Display pop-up menu: Choose what information is displayed in the text display area for the control and how many lines are used to display it. • Add hardware label checkbox and field: Select the checkbox, then type a hardware label in the field to display it on the top line of the control’s text display. Keyboard Screen Control Parameters If you are using a keyboard controller or another MIDI device that sends MIDI note messages, your layout should include a keyboard (or MIDI activity) screen control. You can edit the following parameters for keyboard screen controls. Hardware Assignment • Device pop-up menu: Shows the name of the learned keyboard. The device name may correspond to the name of the keyboard controller, or to a port on the controller, if it has multiple ports. You can choose another device or choose All. • Channel pop-up menu: Shows the MIDI channel on which MainStage receives input from the keyboard. You can choose another channel or choose All. • Velocity Sensitivity slider: Sets the velocity sensitivity for the keyboard. Less means that higher velocities are required to trigger the maximum value, while More means that lower velocities trigger the maximum value. 118 Chapter 7 Working in Layout ModeSettings • Name field: Enter a name for the keyboard. The name appears in the Input pop-up menu in the Channel Strip Inspector, where you can select the device the channel strip responds to. • Number of Keys value slider: Enter the number of keys to display on the keyboard screen control. • Lowest Key value slider: Enter the note name for the lowest key. • Lowest Key Learn button: Click the Learn button, then press the lowest key to have MainStage learn it. The Number of Keys and Low Key affect only the visual appearance of the screen control. They do not affect what notes are received from your keyboard controller. Layer Display • Display keyboard layers checkbox: When active, a layer is displayed above the keyboard in the workspace for each software instrument channel strip in a patch. The layers show the name and color of the channel strip and respond when you play the keyboard. • Height value slider: Sets the height of the layer display that appears above the keyboard. MIDI Activity Screen Control Parameters MIDI activity screen controls can indicate when MIDI note messages are received and can also be used as smaller, “noteless” keyboard screen controls. You can edit the following parameters for MIDI activity screen controls. Hardware Input • Device pop-up menu: Shows the name of the device to show MIDI activity for. You can choose another device, All, or Unassigned. • Channel pop-up menu: Choose the MIDI channel on which MainStage receives input from the controller. • Velocity Sensitivity slider: Set the amount of sensitivity for incoming MIDI data. Settings • Name field: Type a name for the screen control. Appearance • Color selector: Choose the color for the MIDI activity light. Drum Pad Screen Control Parameters You can use drum pad screen controls with hardware drum pads. You can edit the following parameters for drum pad screen controls. Hardware Input • Device pop-up menu: Shows the name of the hardware device with the drum pad control. You can choose another device, All, or Unassigned. Chapter 7 Working in Layout Mode 119Note: If the Device parameter for a drum pad screen control is set to All, the MIDI note that triggers the drum pad (set in the Note value slider) is not sent to any keyboard screen controls in the patch, and so does not produce sound from any software instrument plug-ins “played” using those keyboard screen controls. • Channel pop-up menu: Choose the MIDI channel on which MainStage receives input from the controller. • Note value slider: Change the MIDI note for the drum pad to a different value than the learned value. Appearance • Color selector: Choose the color for the active part of the screen control, so that you can easily see when the drum pad is pressed. Text Labels • Color selector: Choose the color for the active part of the text label. • Justification buttons: Click to set the text justification (left, center, or right). • Display pop-up menu: Choose what information is displayed in the text display area and how many lines are used to display text. • Add hardware label checkbox and field: Select the checkbox, then enter hardware label text in the field to display it on the top line of the control’s text display. Waveform Screen Control Parameters You can use waveform screen controls to display the audio waveform of the audio file for a Playback plug-in. You can edit the Color and Hide Ruler parameters for waveform screen controls. • Color selector: Choose the color for the waveform display. • Hide Ruler checkbox: When selected, the ruler at the top of the waveform display is not visible. Selector Parameters You can use selector screen controls to display and select patches and sets, or to display and select markers in audio files used by a Playback plug-in. You can edit the following parameters for selector (patch or marker selector) screen controls. • View Patches and Sets button: When active, both patches and sets are shown in the selector. • Dual Column Display checkbox: When selected, sets are displayed in the left column and patches are displayed in the right column. • Patches or markers button: When active, only patches are shown in the selector. • Items to Display value slider: Set the number of items (lines) visible in the selector. • Color selector: Choose the color for selected items in the selector. 120 Chapter 7 Working in Layout Mode• Set Justification buttons: Click to set whether sets are left, center, or right justified in the selector. • Patch Justification buttons: Click to set whether patches are left, center, or right justified in the selector. Text Screen Control Parameters You can edit the following parameters for text screen controls after adding text to the text field. • Font button: Select text, then click to show the Font menu from which you can select the font, style, color, and size. • Alignment buttons: Select whether the selected text is left, right, or center aligned, or justified. • Text field: Enter the text you want to display onscreen. • Show frame around text checkbox: When selected, a darker frame appears around the text, showing the borders of the screen control. Background Screen Control Parameters You can use backgrounds for grouped controls. You can edit the following parameters for background screen controls. • Name field: Enter a name for the grouped control in the Name field. • Description field: Enter a description for the grouped control in the Description field. • Panel button and well: Click the Panel button, then choose a panel or texture for the background from the menu that appears. • Image button and well: Click the Image button, then drag an image into the well to use it for the background. • Select button: Click to open an Open File dialog to browse and select an image. • Stretch to Fit checkbox: When selected, the image stretches to fill the area of the background as completely as possible. How MainStage Passes Through MIDI Messages Some MIDI messages sent by your keyboard controller (or other MIDI device) are “passed through” to any channel strips in the MainStage concert that are mapped to the same controller (or device). Whether or not MIDI messages are passed through depends on the following conditions: • If there is no screen control in your layout assigned to receive the message type sent by the controller, the messages are passed through. Chapter 7 Working in Layout Mode 121• If a screen control for that MIDI message type exists, and the MIDI Thru parameter for the screen control is set to Automatic or to the input device, the messages are passed through. This is the default for screen controls set to receive volume, pan, expression, sustain, modulation, pitch bend, and aftertouch messages. • If a screen control for that MIDI message type exists, and the MIDI Thru parameter for the screen control is set to “Do not pass through,” the data is not passed through. This is the default for most other screen controls. The reason for these exceptions is so that when you add a screen control for a modulation wheel or a sustain pedal, for example, it “automatically” responds to the appropriate MIDI message type, without your having to configure it further. If you want to have the screen control respond to a different type of MIDI message, you can choose another MIDI message type from the Number pop-up menu in the Screen Control Inspector. Incoming MIDI messages that are passed through are passed to any channel strips mapped to the same device sending those messages (that is, to the keyboard controller you are using to “play” those channel strips). If there is no matching device, the MIDI messages are sent to all channel strips. You can also filter incoming MIDI messages for individual channel strips. For information on filtering MIDI messages, see Filtering MIDI Messages. Exporting a Layout You can export a layout so that you can save it independently from the concert and import it into other concerts. To export a layout 1 Choose File > Export Layout (or press Command-Shift-Control-S). 2 In the Save As dialog, type a name for the layout, and browse to a location where you want to save the layout (or use the default location). 3 Click Save. Importing a Layout You can import an exported layout into another concert, and then adjust it to work with the mappings in the concert. To import a layout into a concert 1 Choose File > Import Layout (or press Command-Control-O). 2 In the Open dialog, select the layout you want to import. 3 Click Open. The layout for the concert changes to the imported layout. 122 Chapter 7 Working in Layout ModeWhen you import a layout into a concert, MainStage analyzes the layout and attempts to convert the assignments and mappings in the layout to work with the concert. It uses the following rules to convert imported assignments and mappings: • Screen controls are assigned and mapped to screen controls of the same type if they exist in the imported layout. • Keyboard screen controls are assigned only to keyboard screen controls. • If the arrangement of screen controls in the concert is similar to their arrangement in the imported layout, screen controls are assigned and mapped to screen controls in the same positions in the workspace. • If the arrangement of screen controls in the concert is different, MainStage tries to assign and map screen controls starting from the top-left corner of the workspace to the bottom-right corner. Because of the wide variety of possible layouts, not all assignments and mappings may be converted as you intended, depending on the differences between the layouts. After you import a layout into a concert, be sure to try the screen controls in the concert to see if they work as expected. After importing the layout, you may need to manually reassign some controls and then manually remap screen controls in your patches for the concert to work with the new layout. If the imported layout has fewer screen controls than the old layout, or has different types of screen controls, you will likely have to add new screen controls after importing and then assign physical controls to the screen controls to maintain the same level of functionality. Changing the Aspect Ratio of a Layout You can change the aspect ratio of a concert layout. Changing the aspect ratio lets you use the concert with different monitor types: 16:10 (widescreen), 4:3 (standard), and 10:16 (portrait). To change the aspect ratio of a layout µ In the Action menu located in the upper-right corner of the workspace, choose Aspect Ratio, then choose the aspect ratio from the submenu. Chapter 7 Working in Layout Mode 123You can play back audio files in time with your live performance. Playing back audio files can have a variety of uses, including playing backing tracks to accompany your performance, playing song stems that you can mix live, and using a “backing band” while you practice your performance. You play back audio files using the Playback plug-in, which is available in the Instrument menu. Using the Playback plug-in, you can start and stop playback of an audio file, cycle (loop) playback, and fade out the audio. Using markers, you can shift playback to different parts of the audio file. You can have files play at their original speed or synchronize playback to the current tempo of the concert. You can also play back several audio files together using multiple instances of the Playback plug-in and control them using groups. The Playback plug-in is available only in MainStage. This chapter provides information on how you can use the Playback plug-in in a MainStage concert. For detailed information about the interface, parameters, and functions of the Playback plug-in and supported audio file formats, see The Playback Plug-in. This chapter covers the following: • Adding a Playback Plug-in (p. 125) • Using the Playback Plug-in (p. 130) Adding a Playback Plug-in The Playback plug-in is an Instrument plug-in and is available only for software instrument channel strips. To use the Playback plug-in, you add it to a software instrument channel strip, then select an audio file to play. You can add a Playback plug-in to a channel strip in a patch or at the set or concert level. 125 Playing Back Audio in MainStage 8Where you add an instance of the Playback plug-in depends on how you want to use it. If you want to play back an audio file while you play a single patch, you can add it to the patch. If you add a Playback plug-in at the set level, you can select different patches in the set and have the audio file continue playing. This can be useful, for example, if the set includes all the patches you’ll use in a song, and the Playback plug-in plays an audio file with a backing track for the song. If you add a Playback plug-in at the concert level, you can select different patches in the concert and have the audio file continue playing. The ability to use the plug-in at any level gives you a great deal of creative freedom in how you use it. Each instance of the plug-in can play one audio file. You can use audio files in a variety of file formats including AIFF, WAVE, and CAF. You can play audio files containing marker information, including files exported (bounced) from Logic Pro and Apple Loops, and shift playback to markers located at different time positions in the audio file. There are two ways to add a Playback plug-in: by dragging an audio file to the Channel Strips area or from the Instrument slot on a channel strip. To add a Playback plug-in by dragging an audio file 1 In the Patch List, select the patch to which you want to add a Playback plug-in. You can also select a set or the concert icon. 2 Drag an audio file from the Finder to the space between channel strips in the Channel Strips area. A black line appears between the channel strips, and the pointer becomes an Add File pointer as a new channel strip is created. The new channel strip contains a Playback plug-in with the audio file you dragged to the Channel Strips area. To add a Playback plug-in from the Instrument slot 1 Click the Add Channel Strip button to add a new channel strip to the patch, set, or concert. 2 In the new Channel Strip dialog, select Software Instrument as the type. Leave other settings at their default values, or change them to suit your setup. A new software instrument channel strip appears in the Channel Strips area. 3 In the I/O section of the channel strip, click the Instrument slot, choose Playback from the menu, then choose either Mono or Stereo from the submenu. 126 Chapter 8 Playing Back Audio in MainStageThe Playback plug-in is added to the channel strip, and the plug-in window appears over the MainStage window. You can add an audio file to a Playback plug-in in one of several ways: by dragging an audio file, by clicking in the File field, or by using the Action menu in the plug-in window. Adding an Audio File to the Playback Plug-in After you add an instance of the Playback plug-in, you select and add the audio file you want to play using the plug-in. To add an audio file to the Playback plug-in Do one of the following: µ Drag the audio file to the Instrument slot with the Playback plug-in. µ Drag the audio file to the “tape” area of the plug-in window. µ Click the File field in the plug-in window, select an audio file in the Open dialog, then click Open. µ Choose Open File from the Action menu at the upper right of the Playback plug-in window, select an audio file in the Open dialog, then click Open. Chapter 8 Playing Back Audio in MainStage 127The name of the audio file appears in the File field, and the waveform of the audio file appears in the Waveform display. You can preview an audio file in the Open dialog by selecting the file and clicking Play. To hear the file after adding it to the Playback plug-in, click the Play button in the plug-in window. Setting the Sync Mode for the Playback Plug-in When you add an audio file to the Playback plug-in, MainStage looks for tempo information in the file. For audio files containing tempo information (including Apple Loops and files exported from Logic Pro), the file is scanned for transients (short bursts of audio energy that usually occur on rhythmic beats). Transient information is stored in the audio file and used to play the file with the best audio quality, even when the file is played at a different tempo or pitch. For these audio files, you can use the Sync feature to set whether the audio file plays at its recorded tempo or uses the current tempo of the concert. When Sync is set to Off, the audio file plays at its recorded tempo, regardless of the current tempo of the concert. This can be desirable, for example, when the audio file contains non-pitched sounds or a sound effect. When Sync is set to On, the audio file plays at the current tempo (set by the patch, set, or concert, by tapping the tempo, or by listening to MIDI beat clock). This makes it easy to keep backing tracks, for example, in time with each other and with your performance. Setting Sync to On can affect audio quality. You set the Sync mode for an instance of the Playback plug-in from the Sync pop-up menu, located in the lower-left corner of the plug-in window. To set the Sync mode for a Playback plug-in µ To have the audio file play back at its original tempo, choose Off from the Sync pop-up menu. µ To have the audio file play back at the current tempo of the concert, choose On from the Sync pop-up menu. 128 Chapter 8 Playing Back Audio in MainStageNote: For audio files that do not contain tempo information, Sync is set to Off and the Sync pop-up menu is unavailable. Choosing the Flex Mode for the Playback Plug-in For audio files containing tempo information, you can choose between different flex modes for playing back audio. Each flex mode is optimized for playback of a certain type of audio file, and you can choose which flex mode an instance of the Playback plug-in uses to play back the audio file you added. The flex modes available are: • Slicing: Slices the audio material at transient markers and plays each slice at its original speed. Slicing is a good choice for general use, particularly for rhythmic material. • Rhythmic: Based on the time-stretching algorithm used for Apple Loops, Rhythmic is best suited for playing non-monophonic material, such as rhythmic guitars, rhythmic keyboard parts, and Apple Loops. • Speed: Time-stretches material by playing the source material faster or slower, including changing the pitch. Speed is recommended for percussive material. • Polyphonic: Based on a phase vocoder, Polyphonic time-stretches material, delivering high sonic quality with suitable polyphonic material. It is recommended for complex polyphonic material and is good for all kinds of chords—such as guitar, piano, and choir—and for complex mixes. Because each flex mode can produce different results depending on the audio material, it is recommended that you try out different flex modes for each instance of the Playback plug-in to determine which provides the best playback for your audio files. To choose the flex mode for a Playback plug-in µ Choose Flex Mode from the Action menu at the upper right of the plug-in window, then choose the flex mode from the submenu. Note: For audio files that do not contain tempo information, the Flex Mode menu item is unavailable. Adding Screen Controls for the Playback Plug-in You can use screen controls to control the parameters of the Playback plug-in, display parameter values and the name of the audio file, and display the audio waveform of the audio file. The Screen Controls palette includes a waveform screen control that you can use with the Playback plug-in to view the waveform of the audio file. If the audio file contains markers, you can also view the markers in the waveform screen control. To add a waveform screen control to the workspace 1 Click the Layout button (in the upper-left corner of the MainStage window) to switch to layout mode. 2 Drag a waveform screen control to the workspace, and position it as needed. Chapter 8 Playing Back Audio in MainStage 129Note: If there is no Playback plug-in in the patch, an alert appears when you try to add a waveform screen control. When you map the waveform screen control to the Playback plug-in, the waveform for the audio file loaded in the Playback plug-in appears in the waveform screen control. When you press the button you mapped to the Play/Stop parameter, the audio file starts playing, and you see the waveform move across the waveform screen control. You can add screen controls for other parameters, including Fade Out, Cycle, Tempo, and so on, and map them to the corresponding parameters in the Mapping browser or in the Playback plug-in window. You can also map a parameter text screen control to the File field and have it display the name of the audio file being played. Using the Playback Plug-in The design of the Playback plug-in allows you to use it in many different ways. You should plan how you intend to use the Playback plug-in when you are designing your concert to use it most effectively. You can try out different placements and settings to decide how you want to use the Playback plug-in in your concerts. You start playback by sending a Play command to the Playback plug-in using a screen control, such as a button, mapped to the Play/Stop parameter of the plug-in. To stop playback, you send a Stop command using the same parameter. Alternatively, you can set the plug-in to start when you select the patch or set, or when the Play action is triggered. You can control other parameters of the Playback plug-in while you perform, including the Fade Out and Cycle parameters. If the audio file contains marker information, you can use the Go To Previous Marker and Go To Next Marker parameters to shift playback to different parts of the audio file, or use the Go to Marker action to shift playback to a specific marker. Note: When mapping a screen control to the Go to Marker action (in the Markers submenu), set both the Button On and Button Off parameters in the Screen Control Inspector to the value of the marker, to ensure that the mapping works correctly. 130 Chapter 8 Playing Back Audio in MainStageA Playback plug-in in a patch plays only while the patch is selected. If you are using a Playback plug-in at the set level, you can select different patches in the set (for example, different lead synth or guitar solo patches) and have the audio file continue playing. If you are using a Playback plug-in at the concert level, you can select different patches in the concert and have the audio file continue playing. The Playback plug-in provides an additional form of control using groups. If you use multiple instances of the plug-in in your concert, you can use groups to control which instances play together and which are mutually exclusive. When Playback instances are in the same group, a change to the Play/Stop, Cycle, Fade Out, Return to Start, Go to Previous Marker, or Go To Next Marker parameters in one instance changes that parameter for every member of the group. You can use up to 26 groups, each identified by a different letter. Starting one group stops all other groups, while ungrouped instances of the plug-in continue playing. If you are using multiple instances of the Playback plug-in in a group, you can start and stop their playback together by starting or stopping any member of the group using a screen control mapped to the Play/Stop parameter. When playback instances are grouped, playback is “locked” so changes in position affect all members of the group. You can control other aspects of playback, such as having the group fade out or loop playback, using screen controls mapped to the corresponding controls in the plug-in window of any member of the group. Playback instances that are not members of a group are not affected. You assign an instance of the Playback plug-in to a group from the Group pop-up menu, located in the lower-right corner of the plug-in window. To assign a Playback plug-in to a group 1 If the Playback plug-in window is not open, double-click its name in the Input slot to open it. 2 Choose the letter of the group you want to assign the instance to from the Group pop-up menu. Chapter 8 Playing Back Audio in MainStage 131Now that you’ve created and organized your sounds and set up your layout, it’s time to play! MainStage features two modes, Full Screen mode and Perform mode, optimized for live performance. This chapter covers the following: • Before the Performance Starts (p. 133) • Using Full Screen Mode and Perform Mode (p. 134) • Selecting Patches in Performance (p. 135) • Using Screen Controls in Performance (p. 136) • Handling Tempo Changes in Performance (p. 137) • Tips for Performing with Keyboard Controllers (p. 137) • Tips for Performing with Guitars and Other Instruments (p. 137) • Using the Tuner (p. 138) • Using the Playback Plug-in in Performance (p. 139) • Recording Your Performances (p. 140) • After the Performance (p. 141) • Tips for Complex Hardware Setups (p. 141) Before the Performance Starts Here are a few things to check before you begin performing: • Make sure your MIDI controllers, instruments, microphones, and other music equipment is connected to your computer and is working. • Test the audio output from MainStage using the audio interface and speakers or monitors you plan to use in performance. • Select a patch with a software instrument channel strip and play your keyboard controller. Watch the Activity Monitor to make sure MainStage is receiving MIDI input from the controller, and make sure you can hear the audio output. 133 Performing Live with MainStage 9• Make sure any instruments or microphones you plan to play through audio channel strips are connected to the correct audio inputs on your audio interface. Select a patch with an audio channel strip and play or sing to make sure you can hear audio output. • For the best results, close any applications that you do not need while performing, particularly applications with high processor or RAM requirements. • If you use Time Machine to back up your computer, turn it off. • Disconnect the computer running MainStage from any network connections. Using Full Screen Mode and Perform Mode When you perform live, you can use either Full Screen mode or Perform mode, depending on which you prefer. Each mode offers some advantages for different performance situations. Working in Full Screen Mode In Full Screen mode, the MainStage workspace fills the entire screen, and screen controls appear at the maximum possible size for easy viewing. MainStage receives all keyboard input (so no other key commands, including Mac OS X key commands, are active). You can access the Master Mute and Panic functions and the Tuner using their key commands or if you have mapped screen controls to these functions. To switch to Full Screen mode Do one of the following: µ Choose View > Full Screen (or press Command-4). µ Click the Full Screen button in the toolbar. To leave Full Screen mode Do one of the following: µ Press the Escape (Esc) key. µ Click the circled “X” in the upper-left corner of the screen. µ Use the key command for one of the other modes (Command-1 through Command-3). Working in Perform Mode In Perform mode, the workspace fills the MainStage window, but the toolbar is still visible so that you can access the Master Mute, Panic, Tuner, and other toolbar buttons. You can resize the MainStage window and can also change the size of the workspace inside the window using the zoom slider. You can access the Finder and other open applications by clicking outside the MainStage window. 134 Chapter 9 Performing Live with MainStageTo switch to Perform mode Do one of the following: µ Choose View > Perform (or press Command-3). µ Click the Perform button in the toolbar. By default, when you open MainStage, it opens in Edit mode. You can change the default behavior in the General pane of MainStage preferences so that it opens in Perform or Full Screen mode. For more information, see Setting MainStage Preferences. Selecting Patches in Performance In Full Screen or Perform mode, you can view and select patches using the patch selector screen control in your layout. Patches and sets appear in the patch selector in the same order as in the Patch List in Edit mode. Skipped items do not appear in the patch selector and cannot be selected, but patches in collapsed sets do appear and can be selected. For information about skipping items, see Skipping Items in the Patch List. When you select a patch, you can start playing it instantly. If you are sustaining notes from the previous patch, they will continue to be sustained until you release the notes or the sustain pedal. If the previous patch contains effects (such as a reverb or delay effect) with a release “tail,” the effect tail continues sounding for the amount of time set in the Silence Previous Patch pop-up menu in MainStage preferences. For more information, see Setting MainStage Preferences. When performing, keep in mind the difference between patch parameters and parameters controlled at the concert level. When you select a patch, its parameters are set to the values at which you last saved the patch. If you have previously played the patch since you opened the concert, they are set to the values at which you left them when you played the patch. Parameters at the concert level, however, remain at their current value when you select new patches. For example, if you select a patch with a channel strip set to a volume 0 dB, but the Master volume fader at the concert level is set to −96 dB, you will hear silence, not full volume. Similarly, parameters controlled at the set level remain at their current value when you select a different patch in the set. Also keep in mind that when you select a patch, the screen controls for knobs, faders, and other controls in the workspace show the parameter values for the patch, which may be different than the positions of the physical controls on your controller. When you move the physical controls, the screen controls instantly update to show the current value. Selecting Patches Using Key Commands You can select patches in the patch selector using the following key commands: Chapter 9 Performing Live with MainStage 135Key command Selection Up Arrow The previous patch Down Arrow The next patch Left Arrow The first patch in the previous set Right Arrow The first patch in the next set Selecting Patches by Typing You can select a patch in the Patch List by typing the first few letters of its name. To select a patch by typing its name µ Type the letter “f”, then begin typing the name of the patch. Once you type enough letters to uniquely identify the patch name, the patch is selected. µ To cancel typing, press Enter. Selecting Patches Using Actions If you have mapped screen controls to actions for selecting patches, such as selecting the previous or next patch, you can select the patches using the physical controls assigned to those screen controls as you perform. You can also select sets or the concert using actions. Buttons are particularly useful for selecting patches, sets, or the concert using actions. When selecting patches using actions, skipped patches are also skipped. For example, if you use a screen control mapped to select +10 patches, any skipped patches would not be counted in the +10. For more information, see Using MainStage Actions. Selecting Patches Using Program Change Messages If your MIDI device has buttons or other controls that send program change messages, you can select patches in your concert by program change number. You can use program change messages to select patches but not sets. For information about how your MIDI device sends program change messages, consult the documentation that came with the device or the manufacturer’s website. For information about changing the program change number for a patch, see Setting Patch Program Change Numbers. Using Screen Controls in Performance In performance, you use the controls on your MIDI hardware devices that are assigned to screen controls to manipulate the parameters mapped to those screen controls. When you select a new patch, the parameters you mapped for that patch are instantly available for editing. 136 Chapter 9 Performing Live with MainStageWhen you move a physical control, the screen control updates based on the Respond to Hardware Move parameter in the Screen Control Inspector. If the parameter is set to Jump, the screen control instantly moves to the position of the hardware control. If the parameter is set to Pickup, the screen control starts moving when the hardware control reaches its current position. If the parameter is set to Relative, the screen control moves in sync with the hardware control, starting from its current position. Handling Tempo Changes in Performance When you open the concert you plan to use in your performance, MainStage uses the tempo for the concert you set in the Concert Inspector. If the “Get tempo from MIDI input” checkbox is selected, MainStage uses incoming MIDI beat clock to set the tempo. For information about setting and changing the tempo in a concert, see Using Tempo in a MainStage Concert. If you select a patch or set with its own tempo setting, the tempo changes to the new setting. You can also change the tempo in real time while you perform using the Tap Tempo feature, either by pressing Control-T repeatedly at the tempo you want to use, by clicking the Tap Tempo button in the toolbar repeatedly, or using a screen control mapping to the Tap Tempo action. Tips for Performing with Keyboard Controllers If you are using one of the Keyboards templates designed for use with a MIDI-compatible keyboard controller, you can play your keyboard and use MainStage as a sophisticated sound module and multi-effects processor. The patches in the template make extensive use of the software instrument plug-ins included in Logic Studio as well as a wide range of effects plug-ins. Tips for Performing with Guitars and Other Instruments If you are using one of the Guitar Rigs templates designed for use with electric guitar, you can play your electric guitar and use MainStage as a multi-effects processor. The patches in the template make extensive use of the Amp Designer amp simulation plug-in and the Pedalboard effects plug-ins as well as other effects commonly used with guitars. Guitar patches with Pedalboard-style screen controls can be assigned to a foot switch, allowing you to bypass different effects in the channel strip. Some patches also allow you to switch between channel strips with different effects using an expression pedal. When playing guitars and other low-impedance instruments, be sure they are connected to an audio input that matches the impedance of the instrument. Connecting a guitar to a standard line-level audio input may produce a lower volume level for the guitar’s output than intended. Chapter 9 Performing Live with MainStage 137You can also use MainStage with vocals, or any sound captured with a microphone, using an audio interface connected to your computer and choosing the audio input channel in audio channel strips in your patches. For guitar patches that use multiple channel strips, you can control the overall volume of the patch using a foot pedal. Using the following procedure, you can set the overall volume for the patch (that is, for all channel strips) so it starts playing at the set volume level but still control subsequent volume changes using the foot pedal. Using the Tuner MainStage includes a Tuner that you can use to tune guitars and other instruments you play through an audio channel strip. The Tuner shows pitch on a circular scale with the note name and octave displayed in the center of the scale. When you play a single note on your instrument, the pitch is shown in relation to the correct pitch for the note displayed. You can use the Tuner on an instrument connected to the first audio channel strip in a patch. Channel strips that can use the Tuner are indicated by a tuning fork icon near the top of the channel strip. To tune an instrument using the Tuner 1 Select the audio channel strip you want to use the Tuner with. 2 Click the Tuner icon in the toolbar (or press Command-T). The Tuner appears in the workspace. 138 Chapter 9 Performing Live with MainStage3 Play a single note on your instrument, and watch the Tuner display. As you play, the Tuner shows the note name of the closest note. If the note is not in tune, red vertical bars appear, showing whether the note is sharp or flat. The bars appear to the right of the note name if the note is sharp, and to the left if the note is flat. 4 Adjust the tuning peg for the string you are tuning. When the note is in tune, a blue vertical bar appears in the center, above the note name. Be sure to play only a single note at a time while tuning. The Tuner can’t tune to a chord or interval or if you play different notes rapidly. When using the Tuner with a patch containing multiple channel strips, only audio from the first audio channel strip is sent to the Tuner, even if other channel strips in the patch have the same input source. Before using the Tuner, make sure that the first audio channel strip is active and not muted. In the Channel Strips area, the channel strip that will send audio to the Tuner is indicated by a tuning fork icon at the top of the channel strip. If other channel strips in the patch have the same audio input source as the first channel strip, the sound from those channel strips is still audible (unlike the output from the Tuner). For example, if you are using a twin-amp patch from the Rock guitar concert template, the output for the second amp is audible while you tune the guitar, unless you mute its output (by setting the Expression pedal screen control to zero). Using the Playback Plug-in in Performance You can use the Playback plug-in to play backing tracks or other audio files while you are performing, and trigger playback either when you select a patch or set, or using a button or other screen control. You can control other Playback parameters to which you have mapped screen controls, including fading out the sound and looping playback. For files containing marker information, you can also use markers to switch playback to different sections of the audio file. You can start and stop playback of multiple Playback plug-in instances using the Group menu. Where you add an instance of the Playback plug-in depends on how you want to use it. If you want to play back an audio file while you play a single patch, you can add it to the patch. If you add a Playback plug-in at the set level, you can select different patches in the set and have the audio file continue playing. This can be useful, for example, if the set includes all the patches you’ll use in a song, and the Playback plug-in plays an audio file with a backing track for the song. If you add a Playback plug-in at the concert level, you can select different patches in the concert and have the audio file continue playing. The ability to use the plug-in at any level gives you a great deal of creative freedom in how you use it. Chapter 9 Performing Live with MainStage 139The Playback plug-in is designed so that it can be used in a variety of ways. Following are a few ideas for how to use the Playback plug-in in different situations. You can try them out or use them as a starting point for your own creative uses. Some Playback Plug-in Usage Ideas You can use the Playback plug-in in software instrument channel strips in a patch or at the set or concert level. • Add a Playback plug-in to a patch and use it to play a backing track while you play an instrument on another channel strip in the patch. • Add a Playback plug-in at the set level and use it to play a backing track that continues while you select and play different patches in the set. • Add a Playback plug-in at the concert level and use it to play a backing track or sound effect while you select and play different patches in the concert. • Add multiple instances of the Playback plug-in at the set or concert level, and use them to play and remix different backing tracks. Recording Your Performances You can record a performance to an audio file. Before you record a performance, you can choose the file format of the recorded audio file. If you choose AIFF as the file format for recording, the maximum file size for the recorded file is 2 gigabytes. If you choose WAVE as the file format, the maximum file size is 4 gigabytes. If you choose CAF as the file format, there is no practical limit to the file size. You can choose the file format in the Audio pane of MainStage preferences and also set the location of the recorded file and choose which audio outputs are recorded (if you are using multiple sets of outputs in your concert). For information about recording preferences, see Recording. You can record in Perform or Full Screen mode by mapping a screen control to the Record action. You can also assign a key command to the Record action and use it to record in Perform mode but not in Full Screen mode. To start recording to an audio file µ Move the screen control mapped to the Record action (or press Option-R). To stop recording µ Move the screen control mapped to the Record action (or press Option-R again). 140 Chapter 9 Performing Live with MainStageAfter the Performance Before closing your concert after your performance, remember that, for any screen controls for which the On Patch Change parameter is set to “Reset to saved value,” any changes to channel strip parameters or plug-in parameters you made while performing revert to their previously saved state if you close the concert without saving. If you save the concert before closing, the new values are saved in the concert. Tips for Complex Hardware Setups It is highly recommended that you test your concert thoroughly using the same setup you plan to use in live performance prior to performing, at the performance location or venue if possible. This is especially important for more complex hardware setups. Using Multiple Keyboard Controllers in Performance If you plan to use multiple keyboard controllers when you perform, you can choose whether screen controls respond to MIDI messages from all controllers or only a specific controller and whether channel strips receive input from all controllers or only a single controller. In Layout mode, screen controls can be set to respond to MIDI input on all MIDI ports and channels or to only a specific device or channel. To have a screen control respond to MIDI input from all controllers, choose All from both the Device and Channel pop-up menus in the Layout Inspector. To have a screen control respond to a specific controller or to the same channel as the keyboard screen control, choose that controller from the Device pop-up menu. In Edit mode, you set the device from which a channel strip receives MIDI input in the Key Range section of the Channel Strip Inspector. By default, channel strips receive input from the first controller in the layout. You can set a channel strip to receive input from another device in the Input pop-up menu. Using a Different Hardware Setup in Performance If you use MainStage with a complex hardware setup, for example, with multiple MIDI controllers or MIDI interfaces or with multiple audio inputs, you will achieve the best results when you use exactly the same hardware setup you used when you created your concert. If you plan to use MainStage with different controllers, interfaces, or other devices than the ones you used to create your concert, you need to relearn your hardware assignments using your performance hardware setup. To facilitate working in this situation, you can create two separate layouts, one for your studio setup and another for your performance setup, with corresponding screen controls in each layout. Before you perform, import the performance layout into your concert. The hardware assignments for your performance setup are imported with the layout, and your mappings are maintained. Chapter 9 Performing Live with MainStage 141This chapter provides tables listing the default key commands for MainStage and describes how to open the Command Editor to customize key commands. This chapter covers the following: • Using the Command Editor (p. 143) • MainStage Default Key Commands (p. 143) Using the Command Editor MainStage includes a Command Editor that lets you view and customize key commands. You can assign key commands to functions that do not have a default key command and change the key command for other functions. You can also create multiple command sets and switch between them. You can assign key commands to customize the current command set. You can also choose a different command set, and import, export, duplicate, and delete command sets in the Command Editor. To open the Command Editor µ Choose MainStage > Commands > Customize. The Command Editor opens, showing the key commands for the selected command set. For detailed information about working with the Command Editor, including information on customizing, exporting, and importing command sets, see “Working with Key Commands” in the “Basic Operations” chapter of the Logic Pro User Manual. MainStage Default Key Commands The following sections show all of the default key commands for MainStage, grouped by function. These can significantly accelerate your workflow, particularly when creating large or complex projects. 143 Key Commands 10Concerts and Layouts Includes key commands for creating, opening, and saving concerts and for exporting and importing layouts. Default key command Function Command-N New concert Command-O Open concert Command-W Close concert, or close the active plug-in window Command-S Save concert Command-Shift-S Save concert as Command-Control-O Import layout Command-Shift-Control-S Export layout Patches and Sets (Edit Mode) Includes key commands for adding, selecting, exporting, and importing patches and sets. Default key command Function Command-Option-N Add a new patch Command-Option-S Add a new set Command-I Import patches or sets Export patch, export set, or export as set (depending on what is selected) Command-E Command-Up Arrow Select the previous patch Command-Down Arrow Select the next patch Command-Left Arrow Select the first patch in the previous set Command-Right Arrow Select the first patch in the next set Command-Shift-Option-S Create a new set from selected patches Command-Shift-Option-R Reset program change numbers Editing Includes key commands for cutting, copying, pasting, and other common editing functions. Default key command Function Command-Z Undo the last command Command-Shift-Z Redo the last undone command Command-X Cut Command-C Copy Command-V Paste Command-D Duplicate 144 Chapter 10 Key CommandsDefault key command Function Command-A Select all Actions Includes key commands for some MainStage actions. Default key command Function Control-P Panic Control-T Tap Tempo Control-M Master Mute Control-R Toggle Recording Space bar Toggle Play/Stop Parameter Mapping (Edit Mode) Includes commands for learning mappings and locating mappings in the Parameter Mappings browser. Default key command Function Command-L Map the selected parameter (turn on mapping) Command-F Find in Parameter Mapping browser Command-G Find again Channel Strips (Edit Mode) Includes commands for adding channel strips. Default key command Function Command-Option-A Add audio channel strip Command-Option-I Add software instrument channel strip Command-Option-F Show/Hide signal flow channel strips Screen Controls (Layout Mode) Includes key commands for learning controller assignments and for grouping and ungrouping screen controls. Default key command Function Command-L Learn controller assignment (turn on the Learn process) Command-Option-G Group screen controls Command-Shift-Option-G Ungroup screen controls Select the next screen control, select the Add hardware label checkbox, and select the Add hardware label text field for entering text Command-Option-H Chapter 10 Key Commands 145Full Screen Mode Includes key commands for selecting patches and sets, sending MIDI panic, muting/unmuting audio, and exiting Full Screen mode. Default key command Function Up Arrow Select the previous patch Down Arrow Select the next patch Left Arrow Select the first patch of the previous set Right Arrow Select the first patch of the next set P Send MIDI panic M Mute/unmute all audio Esc Exit Full Screen mode Window and View Includes key commands for switching modes and for showing Inspectors and other areas of the interface. Default key command Function Command-1 Layout mode Command-2 Edit mode Command-3 Perform mode Command-4 Full Screen mode Command-5 Show/Hide Inspectors Command-6 Show/Hide the Channel Strips area Command-T Show/Hide the Tuner Command-M Minimize the MainStage window Command-Comma (,) Open MainStage preferences V Show/Hide the active plug-in window Help and Support Includes the key command to open the MainStage User Manual. Default key command Function Command-Question Mark (?) MainStage User Manual 146 Chapter 10 Key CommandsThe Playback plug-in is an audio file player that you can use to play backing tracks, song stems, and other audio files. The Playback plug-in supports uncompressed mono or stereo audio files in the AIFF, WAV, and CAF formats with a bit depth of 16 or 24 bits. You can bounce a single stem from a Logic project or a set of stems from individual tracks. You can use Playback to jump to song sections and repeat them. If you assign multiple instances to groups, each song section can include multiple stems, which expands the possibilities for live remixing of your material. These and other features make the Playback plug-in a flexible, powerful, creative tool, both in the studio and in live performance. This appendix covers the following: • Getting to Know the Playback Interface (p. 148) • Using the Playback Waveform Display (p. 149) • Using the Playback Transport and Function Buttons (p. 150) • Using the Playback Information Display (p. 151) • Using the Playback Sync, Snap To, and Play From Parameters (p. 152) • Using the Playback Group Functions (p. 153) • Using the Playback Action Menu and File Field (p. 154) • Using the Playback Shortcut Menu (p. 155) 147 The Playback Plug-in A AppendixGetting to Know the Playback Interface The Playback interface resembles a hardware tape player. This section will familiarize you with various areas of the Playback plug-in window. Waveform display Action menu Sync, Snap To, Play From, Information display and Group pop-up menus Transport buttons Function buttons • Waveform display: The waveform display shows the waveform of the currently loaded audio file, the current playback position, and the ruler. See Using the Playback Waveform Display. • Transport and function buttons: The transport and function buttons appear on either side of the information display in the silver bar below the waveform display. See Using the Playback Transport and Function Buttons. • Information display: The information display shows the current playback position and audio file length, meter, tempo, fade time, and pitch. See Using the Playback Information Display. • Sync, Snap To, Play From, and Group pop-up menus: The bar across the bottom of the Playback window contains controls you use to set playback behavior: the Sync, Snap To, Play From, and Group pop-up menus. See Using the Playback Sync, Snap To, and Play From Parameters. The Group pop-up menu sets group membership for each Playback instance. See Using the Playback Group Functions. • Action menu and File field: The Action menu (with the gear icon) contains options for adding an audio file, choosing the flex mode, and other functions. See Using the Playback Action Menu and File Field. The File field displays the name of the currently loaded audio file. • Shortcut menu: You can add, edit, and remove markers using the shortcut menu (not shown), which you can access by Control-clicking (or right-clicking) the waveform display. See Using the Playback Shortcut Menu. 148 Appendix A The Playback Plug-inUsing the Playback Waveform Display The waveform display shows the waveform of the currently loaded audio file. The vertical line in the center of the display indicates the current playback position as the waveform scrolls from right to left. Above the waveform, the time ruler displays time in either hours, minutes, and seconds (when Sync mode is off) or bars and beats (when Sync is on). If the audio file contains marker information, the marker names and positions appear below the time ruler. File field Action menu Playhead/playback position Time ruler Marker bar You can drag the waveform horizontally to move to a different position while Playback is stopped. Playback starts from the new position if the Play From parameter is set to Current Position. Note: The Snap To and Play From parameters can affect playback behavior. See Using the Playback Sync, Snap To, and Play From Parameters. Markers, if present, are indicated on the marker bar, below the ruler. You can load audio files that contain markers, or add markers to the loaded audio file using the Add Marker command in the shortcut menu. For information about adding, renaming, and deleting markers, see Using the Playback Shortcut Menu. To move to different markers with the marker bar Do one of the following: µ Click a marker in the marker bar to move it to the current playhead position (in the center of the waveform display). Playback begins from this position if you are in play mode. µ Click to the left of a marker to move the preceding marker to the centered current position indicator. Repeated clicks move earlier markers to the current position indicator. Playback begins from this position if you are in play mode. Appendix A The Playback Plug-in 149Using the Playback Transport and Function Buttons This section covers the buttons used for playback, fade, count-in, click, and marker navigation operations. Return to Start button Play/Stop button Metronome button Cycle button Fade Out button Count-in button Previous/Next Marker button • Return to Start button: Moves to the very beginning of the audio material, but does not start playback. If Playback is in play mode, however, playback will continue from the start of the audio file. • Play/Stop button: Starts or stops playback. The position playback starts from is affected by the Sync, Snap To, and Play From parameters. See Using the Playback Sync, Snap To, and Play From Parameters. • Cycle button: Cycles playback between the current marker and the next marker. Audio is automatically crossfaded at the marker points to minimize clicks. If the file contains no markers, playback of the entire file is cycled. • Fade Out button: Gradually lowers the volume level to silence over the number of seconds specified in the Fade Time parameter. The Fade Out button turns blue until the fade out has completed and playback stops. You can stop an active fade out by clicking the Fade Out button a second time. This gradually restores audio playback to the full volume level over the same amount of elapsed time as the fade out. • Count-in button: Enables a one-bar count-in, using the MainStage metronome click. The count-in always uses the concert tempo and meter, regardless of the Sync mode. • Metronome button: Turns the MainStage metronome on or off. The metronome always uses the concert tempo and meter, regardless of the Sync mode. • Go to Previous Marker button: In play mode, immediately moves to the previous marker (to the left of the current playhead position) if the audio material contains markers. Playback continues from this position. If the audio file contains no markers, moves backward 8 bars (if Sync is on) or 20 seconds (if Sync is off). Playback continues from the new position. 150 Appendix A The Playback Plug-inIf Playback is stopped, moves to the previous marker or to the beginning of the audio file if the current playhead position precedes the first marker. If the file contains no markers, moves 8 bars (if Sync is on) or 20 seconds (if Sync is off). Press Play to start playback from this position. • Go to Next Marker button: In play mode, immediately moves to the next marker (to the right of the current playhead position) if the audio file contains markers. Playback continues from this position. If the audio file contains no markers, moves forward 8 bars (if Sync is on) or 20 seconds (if Sync is off). Playback continues from the new position. If Playback is stopped, moves to the next marker or to the end of the audio file if the current playhead position is after the last marker. If the file contains no markers, playback rewinds by 8 bars (if Sync is on) or 20 seconds (if Sync is off). Press Play to start playback from the new position. Using the Playback Information Display The information display shows information about several key aspects of your audio material, and lets you edit some of the displayed values. • Position field: Shows the current position in hours, minutes, and seconds (when Sync is off), or in bars and beats (when Sync is on). • Length field: Displays the overall length of the loaded audio file in hours, minutes, and seconds (when Sync is off), or in bars and beats (when Sync is on). • Meter field: When Sync is on, lets you define the meter (time signature) of the audio file. The bar and beat values can be altered independently. Editing the Meter field changes the ruler display, and may alter the Length field display, but has no impact on audio playback. • Tempo field: Displays the MainStage concert tempo in beats per minute when Sync is on. Playback follows only a single, constant tempo. The Tempo field is disabled when Sync is off. Note: Because Playback instances use the concert tempo when Sync is on, you can use audio files recorded at different tempos, and have them all play back at the same tempo (the concert tempo). • Fade Time field: Sets the fade-out time in seconds. Drag vertically to adjust this value. Click the Fade button to start or stop a fade-out. Appendix A The Playback Plug-in 151• Pitch fields: Transpose audio playback when Sync is on. Drag vertically in either the semi or cent field to transpose the audio file in semitones or cents (1/100 of a semitone). The Pitch fields are disabled when Sync is off. Using the Playback Sync, Snap To, and Play From Parameters The Sync, Snap To, and Play From pop-up menus control various aspects of playback and synchronization of the audio file. • Sync pop-up menu: Controls whether playback is synchronized with the concert tempo. When Sync is off, the audio file plays at its recorded tempo. When Sync is on, the file plays at the current tempo of the concert. Note: Only audio files that contain tempo information will play back at the MainStage concert tempo when Sync is active. If the file contains no tempo information, the Sync parameter is disabled. • Snap To pop-up menu: Sets the value to which transport functions—including Play, Return to Start, Previous Marker, and Next Marker—snap. The active transport function is delayed until the next bar, beat, or marker is reached, depending on the current Snap To setting. The Snap To setting always reflects the concert tempo and time signature, regardless of the Sync setting. • Off: Transport functions occur immediately, without waiting. • Beat: Transport functions occur at the start of the next beat. • Bar: Transport functions occur at the start of the next bar. • Wait for Marker: Transport functions occur when the next marker is reached. • Play From pop-up menu: Determines the position from which playback starts. • Current Position: Playback starts from the current playhead position in the audio file. This can be especially useful when you are setting up Playback instances in Edit mode. • Start: Playback starts from the beginning of the audio file. • Current Marker: Playback starts from the start of the current marker (the marker to the left of the current position) in the audio file. • Relative Position: Playback is synced to the MainStage clock, so stopping and starting playback follows the MainStage clock position. Using Relative Position is similar to using a mute button. 152 Appendix A The Playback Plug-inUsing the Playback Group Functions If you have multiple instances of the Playback plug-in in a concert, you can use groups to control which instances play together and which instances operate independently. Any Playback instance can either be assigned to one of 26 Groups, named A-Z, or not be a member of any group. The linked operation of multiple instances can be used for creative playback purposes, such as alternative versions of a song verse or chorus. Only one group can be active at a time. For example, if two Playback instances are in Group A, and four Playback instances are in Group B, activation of a transport function in any Group A member will stop playback of all Group B members, and vice versa. Instances that are not in any group are not affected. All Playback instances that belong to a group will switch between states for the following transport functions when changed in any group member: • Return to Start • Play or Stop • Dragging in the waveform display • Cycle • Fade Out (time and action) • Go to Previous (or Next) Marker Important: Editing a parameter in one member of a group does not automatically update the parameter value in other group members. To change the parameter value in all group members, hold down Shift while you edit the parameter in any group member. This applies to the Meter, Fade Time, Pitch, Sync, Snap To, and Play From parameters. You need to set Sync to the same mode for all group members or you will hear playback drift between grouped instances. To assign a Playback instance to a group µ Open the Group pop-up menu at the lower right of the interface and choose a letter. Note: When a Playback instance is added to an existing group, some button states may be different from other group members. If you want all group members to behave identically when a transport button is used in any group member, make sure that the states of all buttons match those of other group members before you add a Playback instance to a group. To remove a Playback instance from all groups µ Choose the “–” item from the Group pop-up menu. Appendix A The Playback Plug-in 153Using the Playback Action Menu and File Field The Action menu is found to the top right of the waveform display and contains the following items: • Open File: Opens a dialog from which you can preview and choose a file to load into the Playback plug-in. • Remove File: Removes the file currently loaded in the Playback plug-in. • Flex Mode: For audio files containing tempo information, you can choose one of the following time-stretching modes: • Slicing is a good choice for general use, particularly for rhythmic material such as drum parts. It works by dividing the audio material at transient markers. Each slice is played back at its original speed. • Rhythmic is best suited for playing polyphonic rhythmic audio material such as rhythm guitar or keyboard parts. • Speed is recommended when the concert tempo is the same as (or close to) the recorded tempo of the audio file. It produces an effect like slowing down or speeding up a tape recorder, without the artifacts of time stretching. • Polyphonic is designed for complex polyphonic audio material and is a good choice for guitar, piano, and choir parts, or for complete mixes. • Start on Patch Change: Starts playback when you select the patch (or set) containing the Playback instance. • Start with Play Action: Starts playback of the Playback plug-in when the MainStage clock starts. “Start with Play Action” follows the current Play From setting—that is, it waits until the next event specified in the Play From setting. The File field, which is located to the left of the Action menu, shows the name of the currently loaded audio file. You can load an audio file in several ways. To load an audio file Do one of the following: µ Click the File field to show an Open dialog, from which you can choose the file you want to load. µ Choose Open File from the Action menu to show an Open dialog, from which you can choose the file you want to load. µ Drag an audio file to the File field. µ Drag an audio file into the waveform display. µ Drag an audio file to the Instrument slot containing the Playback plug-in. 154 Appendix A The Playback Plug-inµ Drag an audio file between two channel strips. This creates a new channel strip with the Playback plug-in inserted. The (dragged) audio file is automatically loaded into this new Playback instance. You can drag multiple files between channel strips to create a new channel strip for each file. Note: Using either of the first two methods, you can preview files in the dialog before adding one to the Playback instance. To preview the selected audio file in the dialog, click the Play button. Click the Stop button in the dialog to stop playback. Using the Playback Shortcut Menu The Playback window includes a shortcut menu that lets you add, name, and remove markers in the waveform display. You access the shortcut menu by Control-clicking the waveform display. The shortcut menu contains the following commands. • Add Marker: Adds a marker at the current position of the pointer, and opens a name field. Enter the name, then press Return or click outside the name field. • Remove Marker: Removes the marker to the left of the current position. • Rename Marker: Opens a name field for the marker nearest to the clicked position. Enter a new name, then press Return or click outside the name field. • Remove All Markers: Removes all markers. Appendix A The Playback Plug-in 155The Loopback plug-in lets you record virtual “tape loops,” play them back repeatedly, and overdub new recordings while previous ones continue playing. You can use the Loopback plug-in to create simple loops, recurring motifs, or complex, evolving textures. Using Loopback as an insert plug-in in an instrument channel strip, you can create looped performances with a single instrument, your voice, or other audio material. By inserting Loopback in an aux channel strip and using it as a send effect, you can create loops with multiple instruments, vocal performances, and other audio material routed from other channel strips. Relative levels can be controlled with the Send knobs of the source channel strips. Loopback lets you create “sound-on-sound” backing tracks or grooves in your MainStage performance. You can use multiple instances as a rhythm section, and switch between a reduced and a full version of your rhythm parts, for example. The Loopback plug-in is a flexible, powerful, creative tool both for the studio and for live performance. You can also export loop performances as standard audio files to use in other plug-ins, including the Playback plug-in. This appendix covers the following: • Getting to Know the Loopback Interface (p. 158) • Using the Loopback Waveform Display (p. 159) • Using the Loopback Transport and Function Controls (p. 159) • Using the Loopback Information Display (p. 160) • Using the Loopback Sync, Snap To, and Play From Parameters (p. 161) • Using the Loopback Group Functions (p. 162) • Using the Loopback Action Menu (p. 163) • Adding Loopback to a Channel Strip (p. 164) 157 The Loopback Plug-in B AppendixGetting to Know the Loopback Interface The Loopback interface resembles a hardware tape-loop device. This section will familiarize you with various areas of the Loopback interface. Waveform display Action menu Sync, Snap To, and Information display Play From pop-up menus Transport buttons Function buttons • Waveform display: The waveform display shows the waveform of the recorded audio material, the playhead position, and the ruler. See Using the Loopback Waveform Display. • Transport and Function controls: The transport and function buttons are located to the left and right of the information display in the silver bar that spans the plug-in window. See Using the Loopback Transport and Function Controls. • Information display: The information display provides details on the current playback position and recording length, meter, tempo, and fade time. See Using the Loopback Information Display. • Sync, Snap To, Play From, and Group pop-up menus: The black bar across the bottom contains the Sync, Snap To, and Play From pop-up menus. These are used to set playback and recording behavior. See Using the Loopback Sync, Snap To, and Play From Parameters. The Group pop-up menu sets group membership for each Playback instance. See Using the Loopback Group Functions. • Action menu: The Action menu is accessed by clicking the button with the gear icon at the top right of the interface. It provides import and export, monitoring, and other commands. See Using the Loopback Action Menu. 158 Appendix B The Loopback Plug-inUsing the Loopback Waveform Display The waveform display shows the waveform of the recorded audio material. The waveform display updates in real time as you record new material. The vertical line in the center of the display is the playhead, which shows the current playback or recording position as the waveform scrolls from right to left. The ruler appears above the waveform, showing bars and beats (musical time). Using the Loopback Transport and Function Controls This section covers the controls for recording, playback, fade, count-in, metronome, and undo operations. Record button Play/Stop button Reverse button Fade Out button Count-in button Metronome button Undo button • Record button: Starts or stops recording. Click the Record button once to start recording to the tape loop—a virtual tape loop, not an actual one. Click a second time to set the length and start overdubbing. During overdubbing, the first recorded take plays back while you record subsequent takes. Subsequent clicks toggle recording off or on, while the tape loop keeps playing. • Play/Stop button: Starts playback at the position set by the Play From and Snap To parameters. If Loopback is playing or recording, stops immediately (without waiting to reach the Snap To value). If loopback is recording and has not established length it sets the length and just continues to play back with no overdubbing. See Using the Loopback Sync, Snap To, and Play From Parameters. Appendix B The Loopback Plug-in 159• Reverse button: Reverses the contents of the tape loop, so the sound plays back in reverse. You can activate Reverse when Loopback is either playing or stopped. • Fade Out button: Gradually lowers the volume level of the tape loop over the time specified in the Fade Time field. The Fade Out button remains highlighted until the fade-out has finished and playback stops. The fade-out affects only previously recorded material. You can start recording during a fade-out, and the new material is recorded and plays at full level. When you record new material during a fade-out, Loopback does not stop when the fade-out has finished, but continues playing the newly recorded material. If the tape loop length has been set, pressing the Fade Out button (or activating a screen control mapped to it) while Loopback is playing clears the buffer, but does not reset the loop length. Pressing the Fade Out button while Loopback is stopped clears the buffer. If the loop length was undefined when Loopback started playing, it also resets the loop length. • Count-in button: Enables a one-bar count-in, using the concert time signature. • Metronome button: Turns the MainStage metronome on or off. • Undo button: When pressed during playback or when stopped, removes the most recently recorded take from the tape loop. Pressing Undo during the first beat of a new take removes the previously recorded take. Using the Loopback Information Display The information display shows information about several key aspects of the audio material in the tape loop, and lets you edit some of the displayed values. • Position field: Indicates the current playhead position. • Length field: Displays the length of the loop. If Sync is set to Off, Loopback analyzes the first take and determines the tempo and length, using the concert tempo as a starting point. After the length is set, it cannot be changed (until you clear the tape loop). If Sync is set to On, you can set the length (in the information display, or using a screen control) before you record the first take. If you do not set the length, Loopback analyzes the first take and sets the length using the concert tempo, rounding up to the next whole bar. 160 Appendix B The Loopback Plug-in• Position dial: Displays the current playback position in the context of the overall loop length. • Meter field: Displays the meter (time signature) of the audio material. The bar and beat values can be altered independently, which changes the ruler display and may alter the Length field display, but does not affect audio playback. Cannot be changed once the length is set without first clearing the tape loop. • Tempo field: Displays the tempo in beats per minute. The tempo is “locked” after the first recording and cannot be changed. • Fade Time field: Indicates the fade-out time in seconds. Drag vertically to adjust this value. See Using the Loopback Transport and Function Controls. Using the Loopback Sync, Snap To, and Play From Parameters The Sync, Snap To, and Play From pop-up menus in the bar at the bottom of the interface control various aspects of playback and synchronization of the audio material. • Sync pop-up menu: Enables or disables synchronization with the MainStage tempo and clock. • Snap To pop-up menu: Determines how Loopback starts, in play or record mode, when stopped. It also quantizes the tape loop length “on the fly” by stopping the first take. • Off: Loopback starts immediately, without waiting. • Beat: Loopback starts or stops at the start of the next beat. • Bar: Loopback starts or stops at the start of the next bar. • Loop: Loopback waits for the amount of time defined by the Length parameter. • Play From pop-up menu: Determines the playback start position within the audio material. • Loop Start: Playback starts from the beginning of the audio material. • Relative Position: When you stop and restart the Loopback instance, playback continues as if the plug-in had been playing continuously, without interruption. This is useful when several Loopback instances are playing together, or when you are using Loopback instances with Playback or Ultrabeat instances, allowing you to effectively “mute” and “unmute” instances while keeping them in sync with each other. Appendix B The Loopback Plug-in 161Using the Loopback Group Functions If you have multiple instances of the Loopback plug-in in a concert, you can use groups to control which instances record and play together and which instances operate independently. Any Loopback instance can either be assigned to one of 26 Groups, named A-Z, or not be a member of any group. The linked operation of multiple instances can be used for creative purposes, such as alternative versions of a song verse or chorus. Loopback and Playback instances share the same group functions. If you have instances of Playback that you have assigned to a group, they will respond to any group functions (except Record) as any Loopback instances assigned to the same group. Only one group can be active at a time. For example, if two Loopback instances are in Group A, and four Loopback instances are in Group B, activation of a transport function in any Group A member will stop all Group B members, and vice versa. Instances that are not in any group are not affected. Similarly, any Playback instance in Group A will also respond, while Playback instances in Group B (or any other group) will stop. All Loopback instances that belong to a group will switch between states for the following transport functions when changed in any group member: • Record • Play or Stop • Return to Start • Dragging in the waveform display • Fade Out (time and action) • Count In • Metronome • Undo • Reverse Important: Editing a parameter in one member of a group does not automatically update the parameter value in other group members. To change the parameter value in all group members, hold down Shift while you edit the parameter in any group member. You need to set Sync to the same mode for all group members or you will hear playback drift between grouped instances. To assign a Loopback instance to a group µ Open the Group pop-up menu at the lower right of the interface and choose a letter. 162 Appendix B The Loopback Plug-inNote: When a Loopback instance is added to an existing group, some button states may be different from other group members. If you want all group members to behave identically when a transport button is used in any group member, make sure that the states of all buttons match those of other group members before you add a Loopback instance to a group. To remove a Loopback instance from all groups µ Choose the “–” item from the Group pop-up menu. Using the Loopback Action Menu The Action menu is found to the top right of the waveform display and contains the following items: • Export Tape Loop: Shows an export dialog, where you can name and choose a location to save the tape loop to an AIFF audio file. • Import Tape Loop: Shows an import dialog, where you can select and import a previously exported tape loop or any short audio file. • Clear Tape Loop: Deletes the entire tape loop in the Loopback plug-in. • Monitor: You can choose one of the following monitoring modes for the Loopback plug-in: On (monitoring is always on); During Record (monitoring is on only during recording); or Off (monitoring is disabled). Note: Some mixer routing configurations may result in no audio being heard through Loopback. Use this menu command if you encounter this situation. • When Patch or Set is Selected: You can choose one of the following functions to be performed when the patch (or set) containing the Loopback plug-in is selected: Do Nothing (the default); Clear (empties the entire tape loop); Start Playing (starts the plug-in playing at its current settings); Start Recording (starts recording the first take at the current plug-in settings); or Clear and Start Recording (clears the existing tape loop and starts recording the first take at the current plug-in settings). • On MainStage Clock Start: You can choose one of the following functions to be performed when the MainStage clock starts: Do Nothing (the default); Clear (empties the entire tape loop); Start Playing (starts the plug-in playing at its current settings); Start Recording (starts recording the tape loop at the current plug-in settings); or Clear and Start Recording (clears the existing tape loop and starts recording a new tape loop at the current plug-in settings). • Set Concert Tempo After First Take: With this item selected, and Sync set to Off, clicking Record tarts recording the tape loop but does not start the MainStage clock (if it is stopped). When you click Record a second time (or click Play), recording stops and the tape loop continues playing. MainStage sets the Length and Tempo based on the duration of the recorded take, and starts the MainStage clock. Appendix B The Loopback Plug-in 163Adding Loopback to a Channel Strip The Loopback plug-in is an insert plug-in. You can use it in any type of channel strip. To add a Loopback instance to a channel strip 1 Click one of the Insert slots in the channel strip you want to use Loopback on. 2 Choose Delay from the shortcut menu that appears, choose Loopback from the submenu, then choose Stereo from the second submenu. 164 Appendix B The Loopback Plug-inYou can set a variety of preferences in the MainStage preferences window. The preferences window includes tabs for general, audio, MIDI, and display preferences, which are described below. This appendix covers the following: • General Preferences (p. 165) • Audio Preferences (p. 166) • MIDI Preferences (p. 168) • Display Preferences (p. 168) General Preferences These preferences let you set the tuning of software instruments, set the volume and output for the metronome, choose what happens when you open MainStage, reset alerts, and set whether screen controls highlight when their parameter values change. Tuning • Tuning slider: Sets the tuning for all software instruments in MainStage. Tuning is centered around A440 Hz, in the range of 100 cents. Metronome • Output pop-up menu: Choose the audio output (or output pair) that the metronome sound is routed to. • Volume slider: Drag the slider to set the relative volume for the metronome sound. Startup • Startup Action pop-up menu: Choose the startup action when you open MainStage. The choices are: • Do Nothing: Does nothing. You can access the Choose Template dialog by choosing File > New. • Create New Concert from Template: Opens the Choose Template dialog. 165 Setting MainStage Preferences C Appendix• Open Most Recent Concert: Opens the last open concert in the same mode it was in when you closed it. • Open Most Recent Concert in Perform Mode: Opens the last open concert in Perform mode. • Open Most Recent Concert in Full Screen Mode: Opens the last open concert in Full Screen mode. Alerts • Reset Warnings button: Click to reset the behavior of alerts for which you have selected the “Do not show again” checkbox, so that they appear in the future when appropriate conditions occur. Parameter Values • On Patch Change pop-up menu: Choose whether parameter values change or remain the same when you change patches. By default, the On Patch Change parameter for individual screen controls is set to Preference, in which case they follow the preference behavior. If this parameter is set to another value for a screen control, the control follows the value of its individual setting. The choices are: • To preserve changes to parameter values when you change patches, choose “Keep current value.” • To return values to the last saved value, choose “Reset to saved value.” • Respond to Hardware Move pop-up menu: Choose how screen controls respond when you move the hardware controls assigned to them. By default, the Respond to Hardware Move parameter for individual screen controls is set to Preference, in which case they follow the preference behavior. If this parameter is set to another value for a screen control, the control follows the value of its individual setting. The choices are: • To have screen controls instantly change to match the hardware value, choose “Jump.” • To have screen controls change when the hardware control matches its current value, choose “Pickup.” • To have screen controls move relative to the hardware control, choose “Relative.” Audio Preferences These preferences let you set the audio output and input drivers, set the size of the I/O buffer, set the audio sample rate, and choose which note is displayed as middle C. Audio • Audio Output pop-up menu: Choose the device you want to use to hear the audio output from MainStage. 166 Appendix C Setting MainStage Preferences• Audio Input pop-up menu: Choose the device you want to use as the source for audio input. • Setup buttons: Click the Audio Output Setup button to open the Audio/MIDI Setup window and configure audio output. Click the Audio Input Setup button to open the Audio/MIDI Setup window and configure audio input. • I/O Buffer Size pop-up menu: Choose the size of the buffer for audio input and output in samples. Smaller buffer sizes reduce the amount of latency, but also require more work from the CPU and may result in playback artifacts. You may want to try different settings to find the lowest setting that does not produce any artifacts. • I/O Safety Buffer checkbox: When selected, MainStage uses an additional buffer to process audio output streams, providing a safeguard against crackling noises that may occur when using very low I/O Buffer Size settings. If turning on this preference doesn’t improve things on your system, disable the checkbox and select a larger I/O buffer size setting. Note: Use of the I/O Safety Buffer preference increases the output latency and therefore the round trip (input plus output) latency. The latency for the current buffer size is displayed below the I/O Safety Buffer checkbox. • Sample Rate pop-up menu: Choose the sample rate for audio input. If you are using an audio interface or other audio device with MainStage, the Sample Rate value should be set to the sample rate of your audio device. • Apply Changes button: Click to apply changes to the input, output, sample rate, and buffer size settings. If you do not click the Apply Changes button, changes are applied when you close the Preferences window. • Silence Previous Patch: Choose the amount of time sustained notes and effects tails continue to sound before falling to silence when you select a new patch. • Hot-Plug Behavior pop-up menu: Choose what action MainStage takes when you hot-plug an audio device while MainStage is open. The choices are: • Alert me: Displays an alert when a device is hot-plugged. The alert includes buttons allowing you to use or ignore the device. • Automatically Use Device: Switches the audio drivers to allow immediate use of the hot-plugged device for audio input and output. • Do Nothing: Does not switch the audio drivers. • Display audio engine overload message: When selected, an alert appears when the audio engine overloads. Recording • Output pop-up menu: Choose the audio output to record. Appendix C Setting MainStage Preferences 167• Recordings Folder field and Set button: Click the Set button, then browse to choose the location where recordings are saved. The file path of the chosen location appears in the field. • File Format pop-up menu: Choose the file format for audio recordings. The choices are: • AIFF • CAF • WAVE MIDI Preferences These preferences let you view the current status of MIDI inputs, set the instrument voice limiting threshold, and choose which note appears as middle C. MIDI • MIDI Status field and Setup button: Displays the number of detected MIDI inputs. Instrument Voice Limiting • CPU Usage Threshold: Set the level (percentage of CPU usage) above which voice limiting is active. If you experience audio dropouts or glitches when performing with the current setting, try lowering the threshold until the dropouts or glitches no longer occur. MIDI • Display Middle C As pop-up menu: Choose whether middle C is displayed as C3 or C4. Display Preferences This preference let you choose the default size at which plug-in windows are displayed. • Default size pop-up menu: Choose whether plug-in windows are displayed at their standard size (100%) or at a larger size. 168 Appendix C Setting MainStage PreferencesIn 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. The Actions folder, which appears in the Parameter Mapping browser along with available parameters, contains actions for a variety of MainStage functions. The Actions folder also contains an AppleScript subfolder with useful scripts. The following table describes each action and the type of screen control to map it to. For information about mapping screen controls to actions, see Mapping Screen Controls to Actions. This appendix covers the following: • Table of Actions (p. 169) Table of Actions For each action in the Actions folder, the Description column describes the function of the action, and the Usage column tells which screen controls it is intended to be used with. Action Description Usage Selects the patch 10 patches Button screen control above the current patch in the Patch List. −10 Patches Selects the patch above the Button screen control current patch in the Patch List. Prev Patch Parameter Text screen control (to display); Knob screen control (to select) Displays the name of the current patch and can also be used to change patches. Current Patch Parameter Text screen control (to display); Knob screen control (to select) Displays the patch number of the selected patch and can also be used to change patches. Current Patch Number 169 Using MainStage Actions D AppendixAction Description Usage Parameter Text screen control (to display); Button screen control (to change) Displays the program change number of the selected patch and can be used to change to a specific program. Current Program Number Selects the patch below the Button screen control current patch in the Patch List. Next Patch Selects the patch 10 patches Button screen control below the current patch in the Patch List. +10 Patches Selects the set above the current Button screen control patch in the Patch List. Prev Set Displays the name of the current Parameter Text screen control set. Current Set Selects the set below the current Button screen control patch in the Patch List. Next Set Displays the name of the Parameter Text screen control concert. Concert Tuner Shows or hides the Tuner. Button screen control Adjusts the overall tuning for the Knob or fader screen control concert, from −100 cents to +100 cents. Master Tuning Mutes or unmutes all audio Button screen control (toggle). Master Mute Tap Tempo Use to tap a new tempo. Button screen control Turns the metronome on or off Button screen control and starts the “transport” (toggle). Metronome Displays incoming MIDI beat Parameter Text screen control clock messages. MIDI Beat Clock Displays the current bar and Button screen control beat count from the “transport” if it is running. Beat Count Displays incoming MIDI Button screen control messages, the same as the MIDI Activity display in the toolbar. MIDI Display Silences all MIDI notes and resets Button screen control the audio engine. Panic Displays the current CPU usage, Parameter Text screen control the same as the CPU Activity display in the toolbar. CPU Load Turns audio recording on or off Button screen control (toggle). Record 170 Appendix D Using MainStage ActionsAction Description Usage Starts or stops playback at the Button screen control current transport position. Play/Stop Starts playback at the beginning Button screen control of the song or file (bar 1, beat 1). Play Pauses playback at the current Button screen control transport position. Stop Resumes playback at the current Button screen control transport position. Continue Toggles the selected patch Button screen control between its edited and last saved state (toggle). Reset/Compare Patch Displays the current time in Parameter Text screen control hours, minutes, and seconds. Current Time In addition to the actions in the Actions folder, there are two actions in the Send to All > Destinations > Actions folder. Action Description Usage Transposes the software Button screen control instrument played by the keyboard up one octave. Transpose Octave Up Transposes the software Button screen control instrument played by the keyboard down one octave. Transpose Octave Down Appendix D Using MainStage Actions 171 User’s Guide• • Manuel de l’utilisateur• Benutzerhandbuch Manual del usuario• Manuale Utente• Guia do Usuário• Gebruikershandleiding• Handbok Brukerhåndbok• Brugerhåndbog• Käsikirja• • •1 2 Your iMac at a glance 4 Mac OS X basics 8 What you can do with your iMac 10 Listen to music on your computer or on the go 12 Create and edit your own movies 14 Search the Internet 16 Get more out of the Internet 18 Send and receive email 20 Organize, plan, and create 22 Keep your iMac’s software up-to-date 24 Learn more and solve problems 30 Install memory and an AirPort Card 32 Work more comfortably 34 Safety, cleaning, and power management Once you’ve set up your iMac and followed the onscreen guide to connect to the Internet, what’s next? Read on to find out how to get the most out of your iMac:2 Your iMac at a glance Your computer has these built-in features: Headphones port CD-ROM or CD-RW drive Install software, use applications, and listen to music CDs. If you have the CD-RW drive, you can create your own CDs. (For use only with standard size, circular discs.) USB port Connect a USB device, such as a joystick or graphics tablet. Apple Pro Mouse An optical mouse you can use on almost any surface. Media Eject key Eject a CD. Volume controls ® Power button Turn your computer on or put it to sleep. Two internal stereo speakers Microphone3 FireWire Transfer video from a DV camera. Connect external hard disk drives, printers, and scanners. Modem Connect to the Internet, browse the World Wide Web, and send email. Ethernet Share files with another computer and access a computer network, printer, or the Internet. USB Connect printers, Zip and other disk drives, digital cameras, joysticks, and more. VGA output Connect an external monitor or television for video mirroring. Reset button Use during troubleshooting to restart your computer. Sound input Record sounds using an analog microphone or other audio device. To learn more about your iMac’s features: m Choose Mac Help from the Help menu, then click Go under “Discover my iMac.” Access door Install additional memory and an AirPort Card for wireless networking. Sound output Connect headphones, external speakers, and analog audio devices.4 Mac OS X basics The Macintosh desktop is your starting place. Finder icon Click to open a Finder window so you can see the files and applications on your computer. Window buttons Click the red button to close the window, the yellow one to minimize it into the Dock, and the green one to resize it. Apple menu Use to change system settings, open recent items, and restart or shut down your computer. To see the menu, click the apple () in the menu bar. View buttons Click to see your files as icons, in lists, or in columns. Toolbar button Click to show or hide the toolbar. Toolbar icons Click to navigate quickly to different folders. Your home folder contains your personal documents. Trash Drag an item here to delete it. Items remain here until you choose Empty Trash from the Finder menu. To learn more about Mac OS X: m See the Welcome to Mac OS X document in the Documents folder on your hard disk. Modem status Use this menu to connect to and disconnect from the Internet using a dialup modem.5 Dock Click icons in the Dock to open applications, documents, folders, or minimized windows. Application menu Shows the name of the application you’re using. Use to set preferences or quit applications (other than the Finder). Document Documents are files that you create with an application (such as a letter you create with your word processor). Doubleclick the icon to open the file in the application used to create it. Folder Folders help organize your files and applications. Doubleclick a folder to see what’s inside. Disc This appears when a CD is in the disc drive. Double-click the icon to see what’s on the disc. To eject a disc, press and hold the Media Eject ( ) key on the keyboard. Application Applications are software programs (such as a game or word processor) that you use with your computer. Double-click an application’s icon to open the application.6 Change the Mac OS to suit your preferences. There are lots of ways to customize Mac OS X. To change the size of the Dock or move it to a different place, open System Preferences and click Dock. To change Finder settings, choose Preferences from the Finder menu. To change icon sizes or the background of a Finder window, choose Show View Options from the View menu. Choose System Preferences from the Apple menu to change most of your computer’s settings. To select a desktop background picture, open System Preferences and click Desktop.7 Click the icons in the Dock or toolbar to find and open files and applications. The triangle indicates the application is open. Drag this bar up or down to resize the Dock. .Drag applications, files, and folders into the Dock for one-click access. This side of the Dock shows application icons. To set up the toolbar the way you want it, choose Customize Toolbar from the Finder’s View menu, then drag items to the toolbar. Press a folder icon to see its contents and open items in it. This side of the Dock shows files, windows, and folders.8 Make your own CDs. Use iTunes to transfer music from your CD collection. If your iMac has a CD-RW drive, burn your own music CDs. Transfer music to an iPod or other MP3 player to listen on the go. Make a movie. Shoot video on a DV camcorder and import it into iMovie . Then rearrange, edit, polish, and add titles and soundtracks. Connect to the Internet to send email and browse the Web, or use iTools to post digital photos on the Web for everyone to see. Browse through the next few pages to find out more. What you can do with your iMac Not sure how to get the most out of your new iMac? Read on for a few ideas.9 Send digital photos to friends and family. Connect to the Internet wirelessly. Listen to music and burn your own CDs. Send email and surf the 'Net. Import and edit home movies. The iMac is your digital hub. Put up to 1,000 songs in your pocket.10 Listen to music on your computer or on the go. Use iTunes to create a library of music and make your own CDs. Library Your collection of songs, imported from your own audio CDs or downloaded from the Internet. Easily browse or search for music. Radio Tuner Choose from hundreds of Internet radio stations – jazz, rock, talk, and more. Audio CDs Play an audio CD on your computer. Import songs to your Library to play them without the CD. To learn more about iTunes: m See iTunes Help, available in the Help menu. m Go to www.apple.com/itunes Portable music If you have an Apple iPod, transfer up to 1,000 songs for listening on the go. Go to www.apple.com/ipod for more information. Playlists Make personalized playlists using songs from your Library. Arrange your music by mood, artist, genre, or however you like. Equalizer Adjust the sound to your tastes using the 10-band EQ with 22 presets.11 2 3 1 1. Click the icon in the Dock to open iTunes. 2. Drag songs from the Library to a playlist. Then click the playlist. 3. Click Burn CD and insert a CD-R disc. Then click Burn CD again to start. . You can fit up to 74 minutes of songs on a standard music CD. . To find out which recordable CDs work best with your computer, go to www.apple.com/itunes If your computer has a CD-RW drive, you can create your own music CDs.12 Create and edit your own movies. Use iMovie to edit video from a digital video camera. 2. In iMovie, bring in your video clips, then edit and polish them into movies. To learn more about iMovie: m See iMovie Help, available in the Help menu. m Go to www.apple.com/store to find compatible DV cameras or to purchase a 6-pin to 4-pin FireWire cable. 1. Shoot video with a digital video camera. Then connect the DV camera using a FireWire cable. 3. Export your finished movie back to tape in your DV camera or to a QuickTime file.13 With iMovie, you can add music, voiceovers, titles transitions, and more. Playback controls Use these to play the movie in the iMovie monitor. Click the Play Full Screen button to use the entire screen. iMovie monitor Preview your movie or view video from a connected DV camera. Viewers Click the clip viewer (eye tab) to edit and place clips. Click the timeline viewer (clock tab) to edit sound. Editing buttons Click to open panels for adjusting and selecting sounds, video effects, titles, and transitions. Shelf Clips appear here when you import them. Move clips to the viewer to make them part of Mode switch your movie. Switch between importing from a DV camera and editing.14 Search the Internet. If you know the Internet address, you can go there directly. 1 2 1. Click the icon in the Dock to open Internet Explorer. To learn more about Internet Explorer: m Open Internet Explorer and choose Internet Explorer Help from the Help menu. 2. Type the Internet address and press Return on your keyboard. . If you have a dialup connection, you can use the modem status (W) to connect to and disconnect from the Internet. 1 215 1 1. Click the icon in the Dock to open Sherlock. 2. Click the Internet icon and type a question in the search field. 3. Click the Search button ( ). Then double-click an item in the list of sites. . Click the other buttons to find people, read the news, shop, and more. . Click the hard disk icon to search the files on your computer. Or you can search the Internet with Sherlock. 2 316 Get more out of the Internet with iTools. iTools is a suite of Internet services integrated into Mac OS X. iDisk Your own storage space on Apple’s Internet server. Share photos, movies, and other files over the Internet. Access your files from another Macintosh or PC. HomePage Build a personal Web site in three easy steps. Create a photo album, publish an iMovie, post your résumé, and more. Anyone can view your site on the World Wide Web. iCards Send an elegant iCard, just right for any occasion. Choose a ready-made photo, or create a personalized iCard using a photo on your iDisk. Email Get your own Mac.com email address. It’s easy and works with your favorite email application. To learn more about iTools: m Go to www.apple.com/itools and click Help on the iTools menu bar. . If you signed up for iTools when you first turned on your computer, you already have an account. Go to www.apple.com/itools to get started. . To sign up for a new iTools account, open System Preferences and click Internet. Then click Sign Up.17 Store pictures, movies, documents, and other files remotely. 1 2 2. Drag files to a folder on your iDisk 1. to copy them. Choose iDisk from the Go menu. . To access your files from another computer, log into your iTools account at www.apple.com/itools . Anyone can access the files in your Public folder. . To find out how to use pictures and other files from your iDisk to create a personal Web site, go to www.apple.com/itools and click the HomePage icon. 18 Send and receive email. Follow these steps to create and send a message. 1 1. Click the Mail icon in the Dock to open the Mail application. . To check for new messages, click Get Mail. To view a message, click its subject. . If you entered email information or got a Mac.com account when you first turned on your computer, Mail is already set up. To set up a new email account, choose Preferences from the Mail menu, then click Accounts.19 To learn more about Mail: m Open Mail, then choose Mail Help from the Help menu. m Go to www.apple.com/macosx/applications/ mail.html 2 3 2. To create a new email message, click Compose. 3. Type the email address and a subject. Then type your message and click Send.20 Organize, plan, and create using AppleWorks. Use AppleWorks for writing, drawing, making presentations, and more. Layout capabilities Add photos, tables, charts, and sidebars. Link text frames, layer graphics, and wrap text. Word processing Write letters, create brochures, make greeting cards and party invitations. Presentation tool Create an onscreen slide presentation. Add movies, art, graphs, and charts. Database Keep records, save addresses, make inventories. Merge mailing information with the word processor to send form letters. Customizable templates Choose from a wide range of predesigned documents and modify them as needed. Spreadsheet Compute data easily using over 100 built-in functions, then use formatting options to make it stand out. Painting Create art from scratch or apply effects to existing pictures or scanned photos. Extensive clip art libraries Choose from over 25,000 high-quality clip art images.21 . Click the Web tab to download more templates from the Internet. To learn more about AppleWorks: m See AppleWorks Help, available in the Help menu. m Go to the AppleWorks Web site at www.apple.com/appleworks 1. Click the icon in the Dock to open AppleWorks. 2. Click the type of document you want to create, or click the Templates tab to modify a ready-made document. To get started using AppleWorks: 1 222 Keep your iMac’s software up-to-date. Use Software Update to get the latest updates and drivers. 1. Click the icon in the Dock to open System Preferences. 2. Click Software Update. 1 2 . To use Software Update, you must have an Internet connection.23 3. Then click Update Now. 4. Select the software you want to update and then click Install. 3 4 . Click the name of a software item to learn more about it. . You can schedule your computer to check automatically for software updates.24 Learn more about using your computer. Look in Mac Help for more information on using your computer. 1 1. Click the Finder icon in the Dock. 2. Then choose Mac Help from the Help menu. 3. Type a question and click Ask. 4. Click an item in the list of Help topics. . To browse the features of your computer, click Go under “At a glance.” . Click Quick Clicks topics for answers to frequently asked questions. . To look at Help for other applications, click the ? button. 2 3 425 These Apple Web sites will help you get the most out of your computer. Apple Service and Support www.apple.com/support Product support, software updates, and technical information. Apple Store www.apple.com/store Purchase the latest Apple and third-party hardware, software, and accessories. Macintosh Products Guide www.apple.com/guide For great hardware and software products for your Mac, check the Web site or look for the Mac symbol. Also get contact and support information for third-party software manufacturers. . From these Web sites you can quickly link to other Apple Web sites around the world.26 If you don’t find the answer to your problem on the following pages: Look in Mac Help. m In Mac Help (see page 24), you can find a great deal of troubleshooting advice, including information to help you solve problems with m Connecting to the Internet m Using software installation and restore discs m Changing your computer’s settings m Printing m And more m Click the Finder icon in the Dock, then choose Mac Help from the Help menu. Type a question in the search window (for example, type “How do I eject a disc?”) and click Ask. Switching between Mac OS X and Mac OS 9 Your iMac is set to use Mac OS X. Most applications made for Mac OS 9 will work in the Mac OS X Classic environment. Just open the application as you normally would. You can also start up your computer using Mac OS 9. To set your computer to use Mac OS 9: m Choose System Preferences from the Apple (K) menu in Mac OS X. m Click the Startup Disk icon to open the Startup Disk pane. m Select the Mac OS 9 folder as your startup disk. If the icons are dimmed, click the padlock icon and enter the password you chose when you first set up Mac OS X. m Click Restart. To set your computer to use Mac OS X again: m Choose Control Panels from the Apple (K) menu. m Open the Startup Disk control panel. m Click the triangle next to the hard disk that contains your operating system folders. m Select the Mac OS X System as your startup disk. m Click Restart. If the computer won’t respond: First, make sure the mouse and keyboard are connected. m Unplug and then plug in the connectors and make sure they are secure. Then try to cancel what the computer is doing. m Try to force problem applications to quit. Hold down the Option and Command (x) keys, then press the Esc key. Select the application and click Force Quit. Advice and troubleshooting27 If the computer still doesn’t respond, restart it. m Hold the Power (®) button on the computer for five seconds. When the computer turns off, press the Power button again to restart it. m If that doesn’t work, press the Reset ( ) button. m If that doesn’t work, unplug the power cord from the computer. Then plug the power cord back in and press the Power button on the computer to turn it on. Then do this: If the problem occurs frequently when you use a particular application: m Check with the application’s manufacturer to see if it is compatible with your computer. m For support and contact information about the software that came with your computer, go to www.apple.com/guide If the problem occurs frequently: m You may need to reinstall your system software. Choose Mac Help from the Help menu and type “install system software” for more information. If you see a flashing question mark during startup: If the computer doesn’t start up after a delay, hold down the Option key and restart your computer. m When your computer starts up, click the hard disk icon, then click the arrow. Then do this: After the computer starts up: m Open System Preferences and click Startup Disk. Select a local Mac OS X System folder. If the problem occurs frequently: m You may need to reinstall your system software. Choose Mac Help from the Help menu and type “install system software” for more information. If the computer won’t turn on or start up: First, make sure the power cord is connected. m Make sure both ends of the power cord are plugged in securely. Make sure the power cord is plugged into a powered electrical outlet. m If your computer is plugged into a power strip, make sure the power strip is turned on.28 If that doesn’t work, or if you hear strange sounds during startup: m If you recently installed additional memory, make sure that it is correctly installed and that it is compatible with your computer. m If that doesn’t work, press the Reset ( ) button, wait a few seconds, and then press the Power (®) button. m See the service and support information that came with your iMac for information on having your computer serviced. If you can’t log into your computer: Make sure you are typing your user name and password correctly. m Make sure you are using the same capitalization and punctuation that you used originally. Check to see if the Caps Lock key has been pressed. If that doesn’t work, reset your password. m Insert the Mac OS X software install CD that came with your computer. Restart your computer while holding down the C key. When the Installer appears, choose Reset Password from the Installer menu and follow the onscreen instructions. If your printer won’t respond or work correctly: Check all cables and connections. m Make sure the printer is plugged into the computer and an electrical outlet. Make sure the printer is turned on. Make sure your computer is set up to use your printer. m Install the software that came with your printer. See the documentation that came with the printer for instructions. m Open the Print Center application in the Utilities folder. Then select your printer. If you can’t eject a CD: Make sure the disc is not in use. m Quit all applications that are using files on the disc. m Then press the Media Eject ( ) key at the top-right corner of the keyboard. m If that doesn’t work, drag the disc’s icon to the Trash. m If that doesn’t work, restart the computer, then hold down the mouse button. To restart, choose Restart from the Apple (K) menu.29 If you have a problem with a third-party software program: Make sure the software is compatible with your version of system software. m See the documentation that came with the software. You can check the version of system software you have by choosing About This Mac from the Apple (K) menu. To resolve other problems with software, contact the software manufacturer. m For support and contact information about the software that came with your computer, go to www.apple.com/guide If you have a problem with your Internet connection: First, make sure the telephone line or Ethernet cable is properly connected to your computer. m Wait a while, then try connecting again. If that doesn’t work, make sure your Internet settings are configured correctly. m Open the Internet Connect application in the Applications folder to check your dialup or AirPort settings. Open System Preferences and click Network to check your Internet settings. m If you’re not sure of the correct information for your Internet settings, contact your Internet service provider. If the Apple Pro Mouse isn’t responding properly: First, make sure the mouse and keyboard are connected. m Unplug and then plug in the connectors and make sure they are secure. If that doesn’t work, try using the mouse on another surface, like a mouse pad or a notebook. m Non-reflective, opaque surfaces without repetitive patterns work best. If you run out of room and want to keep the mouse clicked while you lift it: m Click the mouse, then squeeze the sides with your thumb and fingers and lift the mouse. If the mouse clicks too easily or not easily enough: m Turn the ring on the bottom of the mouse to adjust the tension of the click. For the latest troubleshooting information, go to the Apple Support Web site at www.apple.com/support30 Install memory and an AirPort Card. For detailed instructions, refer to Mac Help (see page 24). Before installing: m shut down the computer m unplug all cables, except the power cord m place the computer face down on a soft cloth 1. Open the access door using a coin to turn the latch. 2. Touch the metal shield inside the recessed latch area. Then unplug the power cord. 3. To install memory, insert a memory module into one of the two lower slots. . Touch this metal before you touch any parts inside the computer. Don’t walk