Apple iOS App Programming Guide Apple sur FNAC.COM - Pour voir la liste complète des manuels APPLE, cliquez ici

 

 

TELECHARGER LE PDF :

http://developer.apple.com/library/ios/documentation/iphone/conceptual/iphoneosprogrammingguide/iphoneappprogrammingguide.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

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 around the room until you’ve finished installing memory or an AirPort Card. .Be sure to align the notches on the module with the small notches inside the slot.31 4. To install an AirPort Card, detach the antenna from the guide rail, then remove the protective plastic cap. 5. Connect the antenna firmly to the AirPort Card and insert the card sideways into the slot. 6. Close the access door and use a coin to close the latch. . For instructions on using the AirPort software, look in the Help Center, available in the Help menu. . Never turn your computer on unless all of its internal and external parts are in place.The guidelines in this section can help you work more comfortably with your computer. For detailed information about ergonomics, see Apple’s Environmental Health and Safety Web site at www.apple.com/about/ergonomics Keyboard m When you use the computer keyboard, your shoulders should be relaxed. Your upper arm and forearm should form an approximate right angle, with your wrist and hand in roughly a straight line. m You may have to raise your chair so your forearms and hands are at the proper angle to the keyboard. If this makes it impossible to rest your feet flat on the floor, you can use a footrest with adjustable height and tilt to make up for any gap between the floor and your feet. Or you may lower the desktop to eliminate the need for a footrest. Another option is to use a desk with a keyboard tray that is lower than the regular work surface. m Use a light touch when typing and keep your hands and fingers relaxed. Avoid rolling your thumbs under your palms. Mouse m Position the mouse at the same height as your keyboard. Allow adequate space to use the mouse comfortably. Chair m An adjustable chair that provides firm, comfortable support is best. Adjust the height of the chair so your thighs are horizontal and your feet flat on the floor. m The back of the chair should support your lower back (lumbar region). Follow the manufacturer’s instructions for adjusting the backrest to fit your body properly. Computer m Arrange the computer so the top of the screen is slightly below your eye level when you’re sitting at the keyboard. The best distance from your eyes to the screen is up to you, although most people seem to prefer 18 to 28 inches (45 to 70 cm). m Position the computer to minimize glare and reflections on the screen from overhead lights and windows. 32 Work more comfortably.33 Important Don’t lift the computer using the flip-out foot. You could damage your computer. To move your computer, grab the handle on the top of the computer with one hand; with your other hand, hold the bottom of the computer. Avoiding fatigue m Change your seated position, stand up, or stretch whenever you start to feel tired. Frequent short breaks are helpful in reducing fatigue. m Use a light touch when typing or using a mouse and keep your hands and fingers relaxed. m Some computer users may develop discomfort in their hands, wrists, or arms after periods of intensive work without breaks. If you begin to develop chronic pain or discomfort in your hands, wrists, or arms, consult a qualified health specialist immediately. m Allow adequate workspace so that you can use your keyboard and mouse comfortably. Place papers or other items so you can view them easily while using your computer. A document stand may make reading papers more comfortable. m Eye muscles must work harder to focus on nearby objects. Occasionally focus your eyes on a distant object, and blink often while you work. m Clean your screen regularly. Keeping the screen clean helps reduce unwanted reflections. 45–70 cm (18–28 in.) Thighs tilted slightly Shoulders relaxed Screen positioned to avoid reflected glare Forearms and hands in a straight line Forearms level or tilted down slightly Lower back supported Feet flat on the floor Top of the screen at or slightly below eye level (You may need to adjust the height of your monitor by raising your work surface.) Clearance under work surface34 Safety Make sure that you m keep these instructions handy for reference by you and others who may use your computer m follow all instructions and warnings regarding your system When setting up and using your computer, remember the following: m Place your computer in a location with adequate ventilation. Never block the vents on the computer. m Your computer has a three-wire grounding plug that will only fit a grounded AC outlet. If you are unable to insert the plug into the outlet, contact a licensed electrician to replace the outlet with a properly grounded outlet. m Make sure you only connect the modem to an analog phone line, the type commonly used in residences. Do not connect a digital telephone line to the modem, because it could damage the modem. m Never turn on your computer unless all of its internal and external parts are in place. Operating the computer when it is open or missing parts can be dangerous and damage your computer. Important The only way to disconnect power completely is to unplug the power cord. Make sure at least one end of the power cord is within easy reach so that you can unplug the computer when you need to. For your own safety and that of your equipment, always disconnect the power plug (by pulling the plug, not the cord) if any of the following conditions exists: m you want to remove any parts (leave the cord disconnected as long as the computer is open) m the power cord or plug becomes frayed or otherwise damaged m you spill something into the case m your computer is exposed to rain or any other excess moisture m your computer has been dropped or the case has been otherwise damaged m you suspect that your computer needs service or repair m you want to clean the case (use only the recommended procedure discussed in Mac Help) Be sure that you always do the following: m Keep your computer away from sources of liquids, such as drinks, washbasins, bathtubs, shower stalls, and so on. m Protect your computer from dampness or wet weather, such as rain, snow, and so on. Warning Electrical equipment may be hazardous if misused. Operation of this product must always be supervised by an adult. Do not allow children access to the interior of this product and do not permit them to handle any cables. Safety, cleaning, and power management35 Cleaning your computer equipment To clean your computer equipment, use only the recommended procedures discussed in Mac Help. Power supply The power supply in your computer is a high-voltage component and not user-serviceable. If you suspect the power supply needs service, contact your Apple-authorized dealer or service provider. Power-saving and environmental features Your computer is equipped with energy-saving features that allow it to conserve energy when not in use. For instructions on adjusting the system and display sleep settings and additional energy-conservation information, see Mac Help. ENERGY STAR ® As an ENERGY STAR® partner, Apple has determined that this product meets the ENERGY STAR® guidelines for energy efficiency. The ENERGY STAR® program is a partnership with office product equipment manufacturers to promote energy efficiency. Reducing energy consumption of office products saves money and reduces pollution by eliminating wasted energy. Warning Do not attempt to access the high-voltage area or power supply. If you suspect the power supply needs service, contact your Apple-authorized dealer or service provider. Warning Do not clean the screen with a cleaner that contains alcohol or acetone. Never spray cleaner directly onto the screen. Liquid could drip inside the screen and cause an electrical shock.36 Communications, telephone, and modem regulation information For information on FCC regulations, radio and television interference, and telephone and modem information related to this product, see the files in the Communications Regulations folder, inside the Documents folder on your hard disk. Laser information Warning Making adjustments or performing procedures other than those specified in your equipment’s manual may result in hazardous radiation exposure. Do not attempt to disassemble the cabinet containing the laser. The laser beam used in this product is harmful to the eyes. The use of optical instruments, such as magnifying lenses, with this product increases the potential hazard to your eyes. For your safety, have this equipment serviced only by an Apple-authorized service provider. Service warning label High-risk activities warning This computer system is not intended for use in the operation of nuclear facilities, aircraft navigation or communications systems, or air traffic control machines, or for any other uses where the failure of the computer system could lead to death, personal injury, or severe environmental damage. Camera information The DV camera pictured on page 12 of this manual is not included with this product. The model shown may not be available in all areas. Mouse information This product complies with the requirements of European Directives 72/23/EEC and 89/336/EEC. Complies with the Canadian ICES-003 Class B specification. This mouse is a Class 1 LED product. (IEC 60825-1:1993+A1:1997+A2:2001) Caution Use of controls or adjustment or performance of procedures other than those specified herein may result in hazardous radiation exposure. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Where’s the fine print?www.apple.com © 2002 Apple Computer, Inc. All rights reserved. AirPort, Apple, the Apple logo, AppleWorks, FireWire, the FireWire logo, iMac, Mac, the Mac logo, Macintosh, QuickTime, and Sherlock are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Finder, iMovie, iPod, and iTunes are trademarks of Apple Computer, Inc. ENERGY STAR® is a U.S. registered trademark. Digital imagery copyright 1998 PhotoDisc, Inc. 034-2102-A Printed in U.S.A. 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• • • iBooknce you’ve set up your iBook and followed the onscreen guide to connect to the Internet, what’s next? In this booklet you’ll find more information to help you get the most out of your iBook: 2 Features 4 Basics 6 Internet and email 14 Music and desktop video 20 Productivity 22 Learning more and solving problems 28 Installing memory and an AirPort Card 32 Ergonomics and safety 1 O2 What can my iBook do? Your computer has these built-in features: Optional AirPort wireless Internet and networking Using the optional AirPort Card, you can connect to the Internet, use email, share files, play network games, and more—without any wires to hold you down. Volume and brightness controls Adjust sound volume and screen brightness directly using your keyboard. Programmable function keys Set the keyboard function keys to open your Web browser, email application, or other favorite application or document automatically. Optical disc drive Install and run software, or listen to music CDs. Play DVD videos if you have the DVD or combo DVD/CD-RW drive, or create your own CDs if you have the CD-RW or combo drive. Press the eject key ( ) on the keyboard to open the drive. Battery level indicator (underneath) When you press the button on the battery, one to four lights glow to show how much charge is left. Two built-in stereo speakers Listen to music, movies, games, and multimedia. Built-in microphone Record sound or control your computer with spoken commands.Modem Connect to the Internet, browse the World Wide Web, and send and receive electronic mail. 3 Sleep indicator light Pulsating light indicates that the computer is in sleep. ® Power button Turn your computer on, put it to sleep, or shut it down. Audio/video port Connect headphones or external speakers. Mirror your iBook display on a TV or video projector. Ethernet Share files with another computer or access a computer network. USB Connect printers, Zip and other disk drives, digital cameras, joysticks, and more. FireWire Connect a digital video camera and use it to create your own desktop movies. You can also connect FireWire hard disks, printers, and more. RGB port Connect an external monitor (using the included Apple RGB Display Adapter). Reset button Use during troubleshooting to restart your computer. Kensington security slot Attach a lock and cable to prevent theft.4 What are the basics? The Macintosh desktop is your starting place. Control Strip Use this for convenient access to often-used settings. Application menu Click here to switch between open applications. Remote Access Use this Control Strip button to connect to and disconnect from the Internet. Disc This appears when a CD or DVD is in the disc drive. Double-click the icon to see what’s on the disc. To eject a disc, press the eject key ( ) on the keyboard. Apple menu Use this to select often-used applications and tools. To see the menu, click the apple () in the menu bar. Trash Drag items here to delete them. Items remain here until you choose Empty Trash from the Special menu. . For a quick tutorial on mouse and desktop skills, choose Mac Tutorials from the Help menu.5 Window close box Click this to close a window. Hard disk All of your files and applications are kept here. Double-click the icon to open it. Folder Folders help organize your files and applications. Double-click a folder to open it. Document Documents are files that you create with an application (such as a letter you create with your word processor). Double-click the icon to open the file in the application used to create it. 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.How do I find something on the Internet? If you know the Internet address, you can go there directly. 6 1 Double-click “Browse the Internet” to open your Web browser. 2 Type the Internet address and press Return on your keyboard.7 2 Type what you want to find and 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. Or you can search the Internet with Sherlock 2. 1 Choose Search Internet from the File menu.8 How can I get started on the World Wide Web? These Apple Web sites will help you get the most out of your computer. www.apple.com/support Product support, software updates, and technical information . From these Web sites you can quickly link to other Apple Web sites around the world. www.apple.com/store Purchase the latest Apple hardware, software, and accessories. www.apple.com/guide For great hardware and software products for your Mac, check this Web site or look for the Mac symbol. Also get contact and support information for third-party software manufacturers.9 www.apple.com/hotnews The latest Apple news and events, software updates for your Mac, and QuickTime hot picks www.apple.com/macosx Get the latest info on the world’s most advanced OS–Mac OS X. www.apple.com/icards Send customized electronic postcards to your friends and family.KidSafe Make the Internet a safer place for your kids. KidSafe gives them access to more than 100,000 educator-approved Web sites and blocks the rest. 10 What can I do with iTools? iTools is a new class of Internet services created for Mac users. iDisk Your own 20 MB of free storage on Apple’s Internet server. Share photos, movies, and other files over the Internet. Purchase additional storage space. Email Get your own Mac.com email address. It’s easy and it works with your favorite email programs. HomePage Build a personal Web site in three easy steps. Create a photo album, publish an iMovie, post your resumé, and more. Now anyone can view your page on the Internet. iCards Send an elegant iCard, just right for any occasion. Choose a ready-made photo, or create a personalized iCards using photos on your iDisk.11 To get started using iTools: 2 Follow the simple instructions to sign up for a free account. . If you signed up with EarthLink and got a Mac.com email address when you first turned on your computer, you already have an iTools account. Go to www.apple.com/itools and enter your member name and password. 1 Go to www.apple.com/itools and click the Free Sign Up button. To learn more about iTools: m go to www.apple.com/itools and click Help on the iTools menu bar12 How do I use email? Follow these steps to create and send a message: 1 Double-click the Mail icon on the desktop to open your email application. . The first time you open the application, a setup assistant helps you connect to your email account. . To check for new messages, click the Send & Receive button. To view a message, click its subject.13 2 To create a new email message, click the New button. 3 Type the email address and a subject. Then type your message and click Send Now.Portable music Take your iBook and your entire music collection with you, or transfer a few of your favorites to an MP3 player. Playlists Make personalized playlists using songs from your Library. Arrange your music by mood, artist, genre, or however you like. What can I do with iTunes? Create a library of music, listen to Internet radio, or transfer songs to a portable MP3 player. Library Your collection of songs, imported from your own audio CDs or downloaded from the Internet. Easily browse or search for music. Radio Tuner Listen to one of 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 learn more about iTunes: m see iTunes Help, available in the Help menu m go to www.apple.com/itunes 1415 If your computer has a CD-RW drive, you can create your own music CDs. 1 Drag songs from the Library to a playlist. Then double-click the playlist. . You can fit up to 74 minutes of songs on a music CD. 2 Click Burn CD and insert a CD-R disc. Then click Burn CD again to start. . To find out which recordable CDs work best with your computer, go to www.apple.com/itunesHow can I watch movies and videos? Watch live video on the Internet using QuickTime TV. 2 Double-click the QuickTime Player icon on the desktop. 3 Pull the tab to open the Favorites drawer. Then click a channel. .With QuickTime, you can also watch movies you make with iMovie, listen to MP3 music files, and much more. To learn more about QuickTime: m see QuickTime Help, available in the Help menu m go to www.apple.com/quicktime 1 Connect to the Internet. 1617 If your computer has a DVD drive, you can watch DVD video. . To use the whole screen to watch the movie, choose Present Video on Screen from the Video menu. . Connect your iBook to a television using the optional Apple AV Cable to watch a DVD on TV (see Mac Help to learn more). . To learn more about the Apple DVD Player, see Apple DVD Player Help, available in the Help menu. 1 Insert a DVD video disc. Then choose Apple DVD Player from the Apple (K) menu. 2 Use the controller to play the movie or see the DVD’s special features.18 How can I make a movie? Use iMovie 2 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 open the iMovie application, then go through the tutorial, available in the Help menu m see iMovie Help, available in the Help menu m go to www.apple.com/imovie to find compatible DV cameras 1 Shoot video with a digital video camera. Then connect the DV camera using a FireWire cable. . Standard 6-pin-to-4-pin FireWire cable not included. 3 Export your finished movie back to tape in your DV camera or to a QuickTime file.19 With iMovie 2, you can add music, voice-overs, titles, transitions, and more. Editing buttons Click these to open panels for adjusting and selecting sounds, video effects, titles (text), and scene transitions. Click the Clips button to see the shelf. iMovie monitor Preview your movie or view video directly from a connected DV camera. Shelf To make clips part of your movie after you import them, move them from the shelf to the clip viewer. Viewers Click the clip viewer (eye tab) to edit and place clips. Click the timeline viewer (clock tab) to edit sound. Mode switch Use this to switch between importing from a DV camera and editing. Scrubber bar Use this to select sections of video. Playback controls Use these to play the movie in the iMovie monitor. Click the Play Full Screen button to use the entire screen.20 What can I do with 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 To get started using AppleWorks: 1 Open AppleWorks, in the Applications folder on your hard disk. 2 Click the type of document you want to create, or click the Templates tab to modify a ready-made document. . 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 open the AppleWorks Getting Started file (on your hard disk in the AppleWorks folder) m go to the AppleWorks Web site at www.apple.com/appleworks22 How can I keep my computer software up-to-date? Use the Software Update control panel to get the latest updates and drivers. 1 Connect to the Internet. 2 Choose Control Panels from the Apple menu. Then choose Software Update from the submenu. 3 Click the Update Now button.23 4 Select the software you want to update and then click Install. . Click the name of a software item to learn more about it. . You can schedule your computer to check automatically for software updates.24 Where do I go to learn more? Look in Mac Help for more information on using your computer. 2 Type a question and click Search. . If you don’t see Mac Help in the Help menu, choose Finder from the Application menu and try again. . You can browse through information about your computer by clicking one of the blue underlined items in the window. . If you want to see the Help for other applications on your computer, choose Help Center from the Help menu. 1 Choose Mac Help from the Help menu.25 . Underlined items are links. When you click a link, it goes to another Help topic, does something for you, or takes you to more information on the Internet. 3 Click an item in the list of Help topics. . If you didn’t find what you were looking for, try rewording your question.If the computer won’t respond: Try to cancel what the computer is doing. m Press the Command (x) and period (.) keys at the same time. m If that doesn’t work, hold down the Option and Command (x) keys and then press the Esc key. If the computer still doesn’t respond, restart it. m Press and hold the Power button for 5 to 10 seconds to shut down the computer. Then press the Power button to restart it. m If that doesn’t work, hold down the Control and Command (x) keys and then press the Power button. m If that doesn’t work, gently press the reset ( ) button by inserting the end of a paper clip into the small hole above the audio/video port, wait a few seconds, and then press the Power button. You need to reset the date and time (using the Date & Time control panel) after you reset your iBook. Then do this: If the problem occurs when you use a certain application: m If this is the only way that you can start up your computer, check with the application’s manufacturer to see if it is compatible with your computer. If the problem occurs frequently: m Choose Mac Help from the Help menu. Look at the section on how to prevent and solve problems. You may need to check for extension conflicts or reinstall your computer’s system software. If the computer “freezes” during startup or you see a flashing question mark: Turn off system extensions. m Start up your computer while holding down the Shift key. If that does not work, start up using the system software CD. m Insert your system software CD and start up while holding down the C key. (Make sure the Caps Lock key is not engaged.) Then do this: After the computer starts up, see the troubleshooting information in the onscreen help. m Choose Mac Help from the Help menu. Look at the section on how to prevent and solve problems. You may need to check for extension conflicts or reinstall your computer’s system software. If the background picture is different: m You started up your computer using the system software on your CD instead of your hard disk. If this is the only way that you can start up your computer, you probably need to reinstall the system software on your hard disk. Look for instructions in Mac Help or look for the system software installation program on your CD. 26 What if I have a problem?27 If the computer won’t turn on or start up: Make sure the power adapter is plugged into the computer and into a functioning power outlet. m Your battery may need to be recharged. Press the small button on the battery. One to four lights glow indicating the battery’s level of charge. If that does not work, reset the computer’s memory. m Start up the computer and immediately hold down the Command (x), Option, P, and R keys until you hear the startup sound twice. If that does not work or if you hear a strange sound during startup: m If you recently installed additional memory, make sure that it is correctly installed. Try removing the memory; if the computer starts up normally, the memory is not compatible with your computer. m If that doesn’t work, gently press the reset ( ) button by inserting the end of a paper clip into the small hole above the audio/video port, wait a few seconds, and then press the Power button. m See the service and support information that came with your iBook for information on contacting Apple for service. 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 keyboard’s Eject key ( ), or drag the disc’s icon to the Trash. If the disc still won’t eject, eject it manually: m Carefully insert the end of a straightened paper clip into the emergency eject hole on the drive tray. Other problems: If you have a problem with your Internet connection: m Make sure the telephone line is connected to the modem port (W) and the line is functioning properly. m Choose Mac Help from the Help menu. There you can find out how to locate and change your Internet settings. m If you’re not sure of the correct information for your Internet settings, contact your Internet service provider. If you have a problem connecting other devices: m Make sure that the device is properly connected. Try unplugging and plugging in the device again. m Check to see if the device has software that needs to be installed. m If that doesn’t work, contact the device manufacturer. m If you want to connect an older device, see Mac Help for information on connecting older devices to your computer. If you have a problem with an application: m For problems with software, contact the software manufacturer. m For information on the software that came with your iBook, including how to contact the manufacturer, see www.apple.com/support/bundledsw If you have a problem using your computer: m Look at the information in Mac Help for instructions and troubleshooting information. If you suspect there may be a problem with your computer hardware: m You can use the Apple Hardware Test CD to help you determine if there is a problem with one of your computer’s components, such as the memory or processor.28 How do I expand my iBook? 1 Shut down your computer. Then disconnect the power adapter and phone cord. Turn the computer over and remove the battery. 3 If necessary, remove the metal clip and pull the AirPort Card from the adapter. The adapter is not used with the iBook. . For instructions on using the AirPort software, look in the Help Center, available in the Help menu.29 4 Flip up the wire bracket and connect the end of the antenna to the AirPort Card. Touch a metal surface inside the computer. 5 Slide the AirPort Card (with the AirPort ID and barcode facing up) under the wire bracket and into the slot. 6 Press the wire bracket down to secure the card. Then replace the keyboard and battery. . You may need to reset the date and time (using the Date & Time control panel) after installing the AirPort Card.Add additional memory. 30 . Your iBook has one expansion slot that accepts a 1.25-inch (or shorter), PC-100 compliant, SO-DIMM memory module. For more information on installing memory, look in Mac Help, available in the Help menu. 1 Shut down your computer. Then disconnect the power adapter and phone cord. Turn the computer over and remove the battery. 2 Release the keyboard by sliding the two plastic tabs away from the display. 3 Lift up the keyboard, flip it over, and lay it on the palm rests and trackpad. Touch a metal surface inside the computer.31 4 If necessary, remove the AirPort Card. . To prevent scratching, place a soft cloth between the AirPort Card and the iBook case. 5 Remove the two screws that secure the RAM shield, then carefully lift it out. 6 Insert the RAM into the slot at an angle and press down to lock it in place. Replace the RAM shield, AirPort Card (if necessary), keyboard, and battery. . You may need to reset the date and time (using the Date & Time control panel) after you install memory.Keyboard and trackpad When you use the keyboard and trackpad, your shoulders should be relaxed. Your upper arm and forearm should form an angle that is slightly greater than a right angle, with your wrist and hand in roughly a straight line. Use a light touch when typing or using the trackpad and keep your hands and fingers relaxed. Avoid rolling your thumbs under your palms. Change hand positions often to avoid fatigue. Some computer users may develop discomfort in their hands, wrists, or arms after intensive work without breaks. If you begin to develop chronic pain or discomfort in your hands, wrists, or arms, consult a qualified health specialist. This Not this This Not this 32 How do I work comfortably?33 Chair An adjustable chair that provides firm, comfortable support is best. Adjust the height of the chair so your thighs are horizontal and your feet flat on the floor. The back of the chair should support your lower back (lumbar region). Follow the manufacturer’s instructions for adjusting the backrest to fit your body properly. You may have to raise your chair so your forearms and hands are at the proper angle to the keyboard. If this makes it impossible to rest your feet flat on the floor, you can use a footrest with adjustable height and tilt to make up for any gap between the floor and your feet. Or you can lower the desktop to eliminate the need for a footrest. Another option is to use a desk with a keyboard tray that’s lower than the regular work surface. External mouse If you use an external mouse, position the mouse at the same height as your keyboard and within a comfortable reach. Built-in display Adjust the angle of the display to minimize glare and reflections from overhead lights and windows. You can adjust the brightness of the screen when you take the computer from one work location to another, if the lighting in your work area changes. For more information For additional ergonomic information, see the Apple ergonomic Web site at www.apple.com/about/ergonomicsWhen setting up and using your computer, remember the following: m Read all the installation instructions carefully before you plug your computer into a wall socket. m Keep these instructions handy for reference by you and others. m Follow all instructions and warnings dealing with your system. m Use only the Apple Portable Power Adapter that came with your computer. Adapters for other electronic devices may look similar, but they may damage your computer. m If your power adapter came equipped with a three-wire grounding plug (a plug that has a third grounding pin), then this plug will fit only a grounded AC outlet. If you are unable to insert the plug into the outlet because the outlet is not grounded, contact a licensed electrician to replace the outlet with a properly grounded outlet. Do not defeat the purpose of the grounding plug! m Always leave space around your power adapter. Do not use this equipment in a location where airflow around the power adapter is confined, such as a bookcase. m Always disconnect the power adapter, phone line, and any other cables before opening the computer to perform procedures such as installing memory. m Never turn on your computer unless all of its internal and external parts are in place. Operating the computer with missing parts can be dangerous and damage your computer. m Do not connect a digital telephone line to the modem, because the wrong type of line could damage the modem. m When using your computer or when charging the battery, it is normal for the bottom of the case to get warm. The bottom of the computer case functions as a cooling surface that transfers heat from inside the computer to the cooler air outside. The bottom of the case is raised slightly to allow airflow that keeps the unit within normal operating temperatures. m Keep your computer away from sources of liquids, such as drinks, washbasins, bathtubs, shower stalls, and so on. m Protect your computer from dampness or wet weather, such as rain, snow, and so on. 34 Is there anything else I need to know? Follow these instructions for using your computer safely and wisely:For your own safety and that of your equipment, always disconnect the power plug (by pulling the plug, not the cord), disconnect the phone line, and remove the battery if any of the following conditions exists: m you want to remove any parts (leave the cord disconnected as long as the keyboard is open) m the power cord or plug becomes frayed or otherwise damaged m you spill something into the case m your computer is exposed to rain or any other excess moisture m your computer has been dropped or the case has been otherwise damaged m you suspect that your computer needs service or repair m you want to clean the case (use only the recommended procedure) Important The only way to disconnect power completely is to unplug the power plug, disconnect the phone cord, and remove the battery. Make sure at least one end of the power cord is within easy reach so that you can unplug the computer when you need to. Your iBook has a unique appearance and finish that may contain minor imperfections, some of which may increase over time. Exposing your iBook to extreme temperatures or humidity may cause this process to accelerate. Proper care and handling, as described in this manual, will help keep your iBook looking its best. To clean the case, do the following: 1 Disconnect the power plug and phone cord and remove the battery. (Pull the plug, not the cord.) 2 Wipe the surfaces lightly with a clean, soft cloth. Warning Do not use any substance containing isopropyl alcohol. It can damage the case. If necessary, use products made specifically for cleaning computers. Warning To avoid damage to your computer, Apple recommends that only an Apple-certified technician install additional RAM or an AirPort Card. Consult the service and support information that came with your computer for instructions on how to contact an Apple-authorized service provider or Apple for service. If you attempt to install additional RAM or an AirPort Card yourself, any damage you may cause to your equipment will not be covered by the limited warranty on your computer. See an Apple-authorized dealer or service provider for additional information about this or any other warranty question. Warning Electrical equipment may be hazardous if misused. Operation of this product, or similar products, must always be supervised by an adult. Do not allow children access to the interior of any electrical product and do not permit them to handle any cables. Never push objects of any kind into this product through the openings in the case. Doing so may result in fire or a dangerous electric shock. 3536 Communications, Telephone, and Modem Regulation Information For information on FCC regulations, radio and television interference, and telephone and modem information related to this product, see the files in the Communications Regulations folder, inside the Documents folder on your hard disk. Laser Information Warning Making adjustments or performing procedures other than those specified in your equipment’s manual may result in hazardous radiation exposure. Do not attempt to disassemble the cabinet containing the laser. The laser beam used in this product is harmful to the eyes. The use of optical instruments, such as magnifying lenses, with this product increases the potential hazard to your eyes. For your safety, have this equipment serviced only by an Apple-authorized service provider. Service Warning Label Apple Portable Power Adapter The Apple Portable Power Adapter that comes with your computer is a high voltage component and should not be opened for any reason, even when the computer is turned off. If your computer needs service, contact your Apple-authorized dealer or service provider. Battery Warning Risk of explosion if battery is replaced by an incorrect type. Dispose of used batteries according to your local environmental guidelines. Do not puncture or incinerate. High-Risk Activities Warning This computer system is not intended for use in the operation of nuclear facilities, aircraft navigation or communications systems, or air traffic control machines, or for any other uses where the failure of the computer system could lead to death, personal injury, or severe environmental damage. Camera Information The DV camera pictured on page 18 of this manual is not included with this product. The model shown may not be available in all areas. ENERGY STAR ® As an ENERGY STAR® partner, Apple Computer has determined that standard configurations of this product meet the ENERGY STAR® guidelines for energy efficiency. The United States Environmental Protection Agency’s ENERGY STAR® program is a partnership with office product equipment manufacturers to promote energy-efficiency. Reducing energy consumption of office products saves money and reduces pollution by eliminating wasted energy. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Where’s the fine print? Macintosh PowerBook User’s Manual Includes setup, expansion, and important health-related information for Macintosh PowerBook G3 Series computersK Apple Computer, Inc. © 1998 Apple Computer, Inc. All rights reserved. Under the copyright laws, this manual may not be copied, in whole or in part, without the written consent of Apple. The Apple logo is a trademark of Apple Computer, Inc., registered in the U.S. and other countries. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014-2084 408-996-1010 http://www.apple.com Apple, the Apple logo, AppleTalk, LaserWriter, LocalTalk, Mac, Macintosh, PlainTalk, PowerBook, and StyleWriter are trademarks of Apple Computer, Inc., registered 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. Simultaneously published in the United States and Canada.3 Contents Communications Regulation Information 7 Laser Information 11 High-Risk Activities Warning 11 1 Setting Up 13 Becoming Familiar With Your Macintosh PowerBook 13 Hardware at a Glance 13 Your Computer’s Components and Controls 14 Your Computer’s Ports and Connectors 16 Setting Up the Computer 18 Your PowerBook Battery 18 Plugging In the Computer 20 Opening the Display 21 Turning the Computer On 22 Problems Turning the Computer On? 23 Adjusting the Internal Display 24 Adjusting the Resolution of the Internal Display 24 Moving Items on the Screen 25 Tips for Using the Trackpad 25 Putting the Computer to Sleep 26 Problems Working With Computer Programs or the Mac OS 27 Turning the Computer Off 28 What’s Next 284 Contents 2 Using Your PowerBook and Connecting to a Network 29 Using the Expansion Bays 30 Using Expansion Bay Modules 30 Removing an Expansion Bay Module 31 Inserting an Expansion Bay Module 33 Using a Disc in the CD-ROM or DVD-ROM Drive 34 Ejecting a Disc 36 Power Sources 37 AC Power 37 Main Battery 37 Optional Second Battery 37 Recharging the Battery 38 Monitoring the Battery Charge 38 Using the Battery Level Indicator Lights 39 Responding to Low-Power Messages 39 What You Should Do 39 What You Should Know 39 Maximizing Work Time 40 Removing or Replacing the Battery 41 Using PC Cards 42 Inserting a PC Card 43 Ejecting a PC Card 44 If You Can’t Eject a Card 45 Using a Zoomed Video PC Card 45 Using a PC Card Modem 46 Using the Infrared File Transfer Capability 47 Connecting to a Local Area Network 48 Connecting to a LocalTalk Network 48 Connecting to a 10Base-T Ethernet Network 50 Configuring Your Network Connection 50Contents 5 Using Your PowerBook’s Optional Internal Modem 51 Setting Up Your Modem’s Connections 51 Connecting the Telephone Line to the Modem 51 What Modems Do 53 Software for Your Modem 53 Choosing the Port Setting 54 Modem Tips and Troubleshooting 55 3 Connecting Additional Equipment 57 Connecting a Printer 58 Connecting an External Modem 58 Connecting SCSI Devices 59 Using Your Macintosh PowerBook as a Hard Disk 60 Connecting Your Computer as a Hard Disk 60 Quitting SCSI Disk Mode 62 Using an External Monitor 63 Connecting an External Monitor 64 Trouble With the External Monitor? 66 Disconnecting an External Monitor 66 Using an External Video Display or Recording Device 67 Connecting Video Equipment to Your PowerBook 68 Trouble With the External Video Device? 70 Disconnecting an External Video Device 70 Connecting and Using Sound Input Devices 71 Connecting Sound Output Devices 72 Locking Your Computer 72 Connecting a Mouse, Keyboard, or Other ADB Device 73 Connecting Other Devices 73 4 Installing a RAM Expansion Card and Removing Your Hard Disk 75 Getting Ready 75 Removing the Keyboard and Internal Heat Sink 75 Installing a RAM Expansion Card 79 Removing Your PowerBook Hard Disk Drive 81 Replacing the Keyboard and Internal Heat Sink 836 Contents Appendix Health, Safety, and Maintenance Tips 85 Health-Related Information About Computer Use 85 Musculoskeletal Discomfort 85 Eye Fatigue 86 Arranging Your Work Area and Equipment 87 Chair 87 Keyboard and Trackpad 87 Mouse 88 Built-In Display 88 External Monitor 88 Avoiding Fatigue 88 What About Electromagnetic Emissions? 88 Important Care and Safety Instructions 89 Caution 90 Important 90 Caring for Batteries 91 Handling Floppy Disks 91 Handling CD and DVD Discs 92 Traveling With the Macintosh PowerBook 92 Airplanes and Airports 93 Handling Your Macintosh PowerBook 93 International Repair and Service 93 Storing the Macintosh PowerBook 93 Service and Support 94 Modem and Fax Safety 94Communications Regulation Information 7 Communications Regulation Information FCC Declaration of Conformity 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. 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: m Turn the television or radio antenna until the interference stops. m Move the computer to one side or the other of the television or radio. m Move the computer farther away from the television or radio. m 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/television technician for additional suggestions. Important Changes or modifications to this product not authorized by Apple Computer, Inc., could void the FCC Certification 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 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): Robert Steinfeld, Apple Computer, Inc., 1 Infinite Loop, Cupertino, CA 95014-2084, 408-974-2618. Industry Canada Statement 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.8 Communications Regulation Information VCCI Class 2 Statement Notify Your Telephone Company Some telephone companies require that you notify the local business office when you hook up a modem to their lines. Information You Need in the United States The optional internal modem complies with Part 68 of the FCC rules. On the back of this equipment is a label that contains, among other information, the FCC registration number and ringer equivalence number (REN). If requested, provide this information to your telephone company. m Ringer equivalence number (REN): 0.8–0.9 The REN is useful to determine the quantity of devices you may connect to your telephone lines and still have all those devices ring when your telephone number is called. In most, but not all areas, the sum of the RENs of all devices connected to one line should not exceed five (5.0). To be certain of the number of devices you may connect to your line, as determined by the REN, you should contact your local telephone company to determine the maximum REN for your calling area. m Telephone jack type: USOC, RJ-11 An FCC-compliant telephone cord and modular plug are provided with this equipment. This equipment is designed to be connected to the telephone network or premises wiring using a compatible modular jack that complies with Part 68 rules. See the installation instructions for details. Telephone Line Problems If your telephone doesn’t work, there may be a problem with your telephone line. Disconnect the modem to see if the problem goes away. If it doesn’t, report the problem either to your local telephone company or to your company’s telecommunications people. If disconnecting the modem eliminates the problem, the modem itself may need service. See the service and support information that came with your Apple product for instructions on how to contact Apple or an Appleauthorized service provider for assistance. If you do not disconnect your modem when it is adversely affecting the telephone line, the telephone company has the right to disconnect your service temporarily until you correct the problem. The telephone company will notify you as soon as possible. Also, you will be informed of your right to file a complaint with the FCC. The telephone company may make changes in its facilities, equipment, operations, or procedures that could affect the operation of your equipment. If this happens, the telephone company will provide advance notice in order for you to make the necessary modifications to maintain uninterrupted service. The optional internal modem will not work with party lines, cannot be connected to a coin-operated telephone, and may not work with a private branch exchange (PBX). Telephone Consumer Protection Act The Telephone Consumer Protection Act of 1991 makes it unlawful for any person to use a computer or other electronic device to send any message via a telephone fax machine unless such message clearly contains in a margin at the top or bottom of each transmitted page or on the first page of the transmission, the date and time it was sent and an identification of the business or other entity, or individual sending the message and the telephone number of the sending machine of such business, entity, or individual.Communications Regulation Information 9 Information You Need in Canada The Industry Canada (IC) label identifies certified equipment. This certification means that the equipment meets certain telecommunications network protective, operational, and safety requirements. The Department does not guarantee the equipment will operate to a user’s satisfaction. Before installing this equipment, make sure that you are permitted to connect to the facilities of the local telecommunications company. Be sure you use an acceptable method of connection to install the equipment. In some cases, you may extend the company’s internal wiring for single-line individual service by means of a certified telephone extension cord. Be aware, however, that compliance with these conditions may not prevent degradation of service in some situations. Repairs to certified equipment should be made by an authorized Canadian maintenance facility designated by the supplier. Any equipment malfunctions or repairs or alterations that you make to this equipment may cause the telecommunications company to request that you disconnect the equipment. In Canada, contact Apple at: 7495 Birchmount Road, Markham, Ontario, L3R 5G2, 800-263-3394 Users should ensure for their own protection that the electrical ground connections of the power utility, telephone lines, and internal metallic water pipe system, if present, are connected together. This precaution may be particularly important in rural areas. Informations Destinés aux Utilisateurs Canadiens L’étiquette d’Industrie Canada identifie un matériel homologué. Cette étiquette certifie que le matériel est conforme à certaines normes de protection, d’exploitation et de sécurité des réseaux de télécommunications. Le Ministère n’assure toutefois pas que le matériel fonctionnera à la satisfaction de l’utilisateur. Avant d’installer ce matériel, l’utilisateur doit s’assurer qu’il est permis de le raccorder au réseau de l’entreprise locale de télécommunication. Le matériel doit également être installé en suivant une méthode acceptée de raccordement. Dans certains cas, le cablage appartenant à l’entreprise utilisé pour un service individuel à ligne unique peut être prolongé au moyen d’un dispositif homologué de raccordement (cordon prolongateur téléphonique). L’abonné ne doit pas oublier qu’il est possible que la conformité aux conditions énoncées ci-dessus n’empechent pas la dégradation du service dans certaines situations. De fait, les entreprises de télécommunication ne permettent pas que l’on raccorde un matériel aux prises d’abonné, sauf dans les cas précis prévus par les tarifs particuliers de ces entreprises. Les réparations de matériel homologué doivent être effectuées par un centre d’entretien canadien autorisé désigné par le fournisseur. La compagnie de télécommuncations peut demander à l’utilisateur de débrancher un appareil suite à des réparations ou des modifications effectuées par l’utilisateur ou à cause de mauvais fonctionnement. Veuillez contacter le fournisseur suivant pour des informations supplémentaires : Apple Canada, Inc. 7495 Birchmount Road Markham, Ontario Canada L3R 5G2 Apple Canada Customer Assistance Line: 800-263-3394 Warning Users should not attempt to make such connections themselves, but should contact the appropriate electric inspection authority or electrician m Load number: 0.3 The load number (LN) assigned to each terminal device denotes the percentage of the total load to be connected to the telephone loop that is used by the device, to prevent overloading. The termination of a loop may consist of any combination of devices, subject only to the requirement that the sum of the load numbers of all devices does not exceed 100. m Telephone jack type: CA-1110 Communications Regulation Information Pour sa propre protection, I’utilisateur doit s’assurer que tous les fils de mise à la terre du secteur, des lignes téléphoniques et les canalisations d’eau métalliques, s’il y en a, soient raccordés ensemble. Cette précaution est particulièrement importante dans les régions rurales. Information You Need in the United Kingdom This terminal equipment is intended for direct connection to the analogue Public Switched Telecommunications Network and is approved for use within the United Kingdom with the following features: m Modem facility m Autocalling facility m Autoanswer facility m DTMF signaling m Operation in the absence of proceed indication or upon detection of proceed indication This product is in conformity with relevant regulatory standards following the provisions of European Council Directives 73/23/EEC (Low Voltage Directive) and 89/336/EEC amended by 92/31/EEC (EMC Directive). Information You Need in Germany Diese Modem-Karte ist als Endeinrichtung vorgesehen und muss an ein TAE mit F-Kodierung angeschlossen werden. Diese Endeinrichtung ist in Konformität gemäss Niederspannungsrichtlinie 73 / 23 / EWG sowie EMC-Richtlinien 89 / 336 / EWG und 92 / 31 / EWG. Information You Need in France Ce matériel est conforme aux normes applicables de sécurité éléctrique d’après la directive 73 / 23 / CEE et aux normes applicables de comptabilité éléctromagnétique d’après la directive 89 / 336 / CEE, modifié par la directive 92 / 31 / CEE. Avertissement L’utilisateur ne doit pas tenter de faire ces raccordements lui-même; il doit avoir recours à un service d’inspection des installations électriques ou à un électricien, selon le cas. m Numéro de charge : 0.3 L’indice de charge (IC) assigné à chaque dispositif terminal indique, pour éviter toute surcharge, le pourcentage de la charge totale qui sera raccordée à un circuit téléphonique bouclé utilisé par ce dispositif. La terminaison du circuit bouclé peut être constituée de n’importe quelle combinaison de dispositifs pourvu que la somme des indices de charge de l’ensemble des dispositifs ne dépasse pas 100. m Type de prise téléphonique : CA-11Laser Information 11 Laser Information Do not attempt to disassemble the cabinet containing the laser. The laser beam used in this product is harmful to the eyes. The use of optical instruments, such as magnifying lenses, with this product increases the potential hazard to your eyes. For your safety, have this equipment serviced only by an Apple-authorized service provider. Your computer is a Class 1 laser product. The Class 1 label, located in a user-accessible area, indicates that the drive meets minimum safety requirements. A service warning label is located in a service-accessible area. The labels on your product may differ slightly from the ones shown here. High-Risk Activities Warning This computer system is not intended for use in the operation of nuclear facilities, aircraft navigation or communications systems, or air traffic control machines, or for any other uses where the failure of the computer system could lead to death, personal injury or severe environmental damage. Warning Making adjustments or performing procedures other than those specified in your equipment’s manual may result in hazardous radiation exposure. Class 1 label Service warning label13 C H A P T E R 1 1 Setting Up Your Macintosh PowerBook has been designed so that you can set it up quickly and start using it right away. If you have never used a PowerBook or are new to Macintosh computers, read this chapter for an overview of PowerBook features and instructions on getting started. If you are an experienced user, you may already know enough to get started with your new PowerBook. Take a moment to look over the information in this manual to find out about the new features of your Macintosh PowerBook. Becoming Familiar With Your Macintosh PowerBook Your PowerBook is designed to keep you working productively in any location. The information in this manual covers setting up, using, and expanding your PowerBook hardware. With a PowerBook, you have m easily configurable and expandable hardware. m Mac OS system software along with software for connecting to the Internet. m interactive online information and instructions for using the computer. m a separate manual for troubleshooting, and system software reinstallation. Hardware at a Glance The illustrations on the next several pages show the built-in features of your computer, including the expansion bays, PC Card slots, and the ports for connecting a printer, network, and other external equipment.14 Chapter 1 Your Computer’s Components and Controls Left expansion bay release lever Speaker — Mute button Ï Volume control Trackpad Right expansion bay release lever Trackpad button ¤Brightness control Sleep indicator Expansion bay with a CD-ROM or DVD-ROM drive inserted ® Power button Display latch Microphone Security slot SpeakerSetting Up 15 Sleep indicator Blinking green light indicates when the PowerBook is in sleep. ® Power button Turns your PowerBook on and off. Microphone Record sounds directly to your PowerBook hard disk with this built-in microphone. ¤ Brightness control Increase or decrease the brightness of your PowerBook display. Ï Volume control Increase or decrease the volume of the sound coming from your built-in speakers and sound output port using this control. — Mute button Turn the sound off and on from the PowerBook external speakers and sound output port. Trackpad Move the pointer on the PowerBook display. The trackpad can also be set up so that you can double-click and select items directly instead of using the trackpad button. Right expansion bay with a CD-ROM or DVD-ROM drive module inserted Dual-function expansion bay that accepts either removable modules (3.5-inch or 5.25-inch size) or a PowerBook battery. Ç Security slot Protect your PowerBook by connecting a security cable.16 Chapter 1 Your Computer’s Ports and Connectors - √ ¯ V ´ G g Æ ™ External TV out port ™ External monitor port PC Card slots PC Card eject buttons Internal modem port (some models) Expansion bay with a PowerBook battery Left expansion bay release lever Infrared window - Sound output port ¯ Power adapter port Printer/ External modem port V Apple Desktop Bus (ADB) port √ Sound input port g SCSI port (HDI-30) Ethernet port (10Base-T) G Æ W ´Setting Up 17 Infrared window Allows you to use infrared (IR) communication to send files to another IR-equipped computer or connect to a wireless IrDA network. g SCSI port (HDI-30) Connect up to seven external SCSI devices (such as external hard drives or scanners). ´ Printer/External modem port Connect to printer, external modem, or LocalTalk network. ™ External monitor port Connect to any external monitor with a VGA-style connector or to any Macintosh monitor using the included adapter. Æ External TV out port Connect to any television, VCR, or other video device that supports S-Video, NTSC, or PAL formats. V ADB port Connect a mouse, external keyboard, or other ADB device. G Ethernet port (10Base-T) Connect to a high-speed 10Base-T Ethernet network. ¯ Power adapter port Connect the power adapter to your PowerBook. When connected, the power adapter provides power to your PowerBook and also charges the batteries inside the PowerBook. PC Card slots Expand the capabilities of your PowerBook using these two PC Card slots that support both PCMCIA and CardBus formats. W Internal modem port (some models) Connect a standard phone line directly to the optional internal modem. Left expansion bay with a PowerBook battery Dual-function expansion bay that accepts either 3.5-inch removable modules or a PowerBook battery. √ Sound input port Connect an external line level microphone or other sound input device. - Sound output port Connect external speakers, headphones, or other sound output device.18 Chapter 1 Setting Up the Computer Now that you know some essential details about your PowerBook, you’re ready to set it up and begin using it. Setting up your Macintosh PowerBook for the first time is a quick and simple process. However, there are a few items that you need to have and things to do before you begin using your PowerBook. Your PowerBook Battery The battery that came with your PowerBook computer may be already inserted in an expansion bay. If not, you should insert it now so that it can be charged. You can easily tell if the battery is already installed by looking at the left expansion bay. If you see an opening for a floppy disk, then the floppy disk drive module is installed and the battery is not installed. If you see a small button with four small lights to its right, the battery is installed. If Your PowerBook Did Not Come With the Battery Installed If your PowerBook did not come with the battery inserted in the expansion bay, you should insert it in place of the floppy disk drive module in order to charge it. To remove the floppy disk drive module and insert the battery, follow these steps: 1 Place your PowerBook on a hard flat surface. Important Before following the setup instructions in this chapter, you may want to read “Arranging Your Work Area and Equipment” on page 87 for tips on adjusting your work furniture and computer so that you’re comfortable when using the computer. PowerBook battery PowerBook battery inserted in the left expansion bay Floppy disk drive module inserted in the left expansion baySetting Up 19 2 Pull the left expansion bay release lever to partially eject the floppy disk drive module. 3 Slide the floppy disk drive module out of its compartment. 4 Gently slide the battery (with the battery name facing up) into the left expansion bay until the edge of the battery is flush with the left side of the PowerBook. Be sure the battery is completely inserted. If Your PowerBook Came With the Battery Installed New PowerBook computers that ship with a battery installed have a shipping label covering the battery to protect it from losing its charge completely. You need to remove the label before the battery will provide power for the computer. 1 With the display open, peel off the part of the shipping label on the computer’s case, taking care not to tear the label. 2 Pull the left expansion bay release lever to partially eject the battery. 3 Slide the battery out of its compartment. 4 Carefully remove the shipping label from the battery. Avoid touching the battery’s metal contacts as you peel off the label. 5 Replace the battery. Wall St. User’s Manual 034-0426-A20 Chapter 1 Plugging In the Computer Plugging in the power adapter recharges the computer’s battery. You should plug in the power adapter in case the battery has drained during shipping or storage. When you are ready to begin, follow these steps: 1 Plug one end of the power cord into the power adapter and the other end into an outlet or power strip. 2 Plug the power adapter plug into the power adapter port (marked with the icon ¯) on the back of the computer. Warning Use only the power adapter that came with your Macintosh PowerBook computer. Adapters for other electronic devices (including other Macintosh PowerBook models and other portable computers) may look similar, but they may damage your computer. If your power adapter came equipped with a three-wire grounding plug—a plug that has a third (grounding) pin. This plug will fit only a grounded AC outlet. If you are unable to insert the plug into the outlet because the outlet is not grounded, contact a licensed electrician to replace the outlet with a properly grounded outlet. Do not defeat the purpose of the grounding plug! Power adapter plug ¯ Power adapter port Power cord Power adapterSetting Up 21 Opening the Display 1 Gently pull the display latch to release it. 2 Position the display at a comfortable viewing angle. You can adjust the angle of the display at any time by tilting it toward or away from you.22 Chapter 1 Turning the Computer On To turn on the computer for the first time, press the Power button (®) above the keyboard. You should hear a tone when you turn on the computer. It takes the computer a few moments to start up. As the computer starts up, several messages appear on the screen, including an application to help you set up the Mac OS. Note: Certain system settings (such as sound volume, screen brightness, and AppleTalk connection) may not be saved the first time you set them if the battery has been completely discharged or has been out of the computer for three days or more. You will need to reset these system settings the second time you start up the computer. ® Power buttonSetting Up 23 Problems Turning the Computer On? Nothing happened when you pressed the Power button. m The battery may be drained. Make sure that you plugged in the power adapter, and that the power adapter is firmly connected to both the computer and a power source. If the power adapter is plugged into a power strip, make sure the power strip is plugged in and turned on. m If the computer doesn’t start up when you press the Power button, hold down the Shift, Function (fn), and Control (ctrl) keys and then press the Power button (®). The Sleep indicator light glows briefly while the computer goes through a reset process. After the power indicator light turns off, wait a few seconds and then press the Power button again to start up the computer. Once the battery has charged, you should be able to use the Power button normally. m If the computer still doesn’t turn on, see the troubleshooting manual that came with your computer. There is a slight delay after you press the power button before the computer starts up. m Every time you press the power button, the PowerBook performs a check of the computer’s memory, causing a slight delay in startup. The more memory you have installed in the PowerBook, the longer the delay. You see a picture of a disk with a blinking question mark on the screen. m This icon usually means that the computer can’t find system software on the hard disk or any disks attached to the computer. You may need to reinstall system software. See the troubleshooting manual that came with your computer.24 Chapter 1 Adjusting the Internal Display Before you begin working with your new PowerBook, you may need to adjust your display so that items on the screen are easy to see. Your PowerBook comes with a control (labeled with the ¤ icon) that adjusts screen brightness. m Use the brightness (¤) control to change the brightness of your display. If your display is too dark, press and hold the right side of the brightness control (labeled with the + icon) until items are easily visible on the screen. If your display is too bright, press and hold the left side of the brightness control (labeled with the – icon) until items are easily visible on the screen. Adjusting the Resolution of the Internal Display You can increase the size of images on your built-in display by switching from the standard resolution to a scaled resolution. To do so, click the Resolution icon in the Control Strip. When you switch to a scaled resolution, items on the screen appear larger, making them easier to see. Note: Scaled resolutions may not appear as sharp as the standard display resolution. ¤ Brightness control Resolution iconSetting Up 25 Moving Items on the Screen You use your PowerBook trackpad to move items and select items on the screen. To move the arrow pointer on the screen, slide your finger across the trackpad. To select, click, or double-click an item on the screen, press the trackpad button. The trackpad is sensitive to how fast you move your finger. To move the pointer a short distance across the screen, move your finger slowly across the trackpad. The faster you move your finger, the farther the pointer moves on the screen. You can find more information on setting up your PowerBook trackpad in the online help, available in the Help menu. Trackpad Trackpad button Tips for Using the Trackpad For best results when using the trackpad, keep in mind these tips: m Use your index finger (left or right hand). Use only one finger. m Use only your finger on the trackpad. Do not use a pen or any other object. m Keep your finger and the trackpad dry. If the trackpad becomes moist from humidity or condensation, gently wipe the trackpad with a clean cloth before you use it. m Never use any kind of cleaning solutions on your PowerBook trackpad.26 Chapter 1 Putting the Computer to Sleep Sleep is a power conservation feature of Macintosh PowerBook computers that lets you quickly wake the computer and bypass the startup process. You can extend the period of time your battery will power the computer by putting the PowerBook to sleep when you won’t be using it for several minutes or more. The length of time the computer can be left in sleep depends on how much charge is left in the battery. When the computer is in sleep, it has a darkened screen and appears to be off. A small green light flashes on the case when the computer is in sleep. To put the computer to sleep, follow these instructions: 1 Press the Power button (®). The following dialog box appears. 2 Click the Sleep button. You can also put your computer to sleep by doing one of the following: m closing the display m choosing Sleep from the Special menu m clicking the Energy Settings icon in the Control Strip and choosing Sleep Now from the menu that appears 3 To wake the computer, press the Power button (®) or any key on the keyboard (except for the fn key.) The screen reappears as it was before the computer went to sleep. Note: To decrease the time it takes for the computer to wake up from sleep, turn off AppleTalk. For more information, see the online help, available in the Help menu. Warning Once you put your computer to sleep, listen for the hard disk to stop spinning before you move your PowerBook. Moving your computer while the hard disk is spinning can damage your computer. Energy Settings iconSetting Up 27 Problems Working With Computer Programs or the Mac OS If software difficulties (such as a software error message on your screen) don’t allow you to use standard methods of quitting a program or restarting your computer, you can try using these special key combinations. The reset key combination immediately turns off the computer. Then the sleep indicator light glows briefly while the computer goes through the reset process. After the sleep indicator light turns off, wait a few seconds and then press the Power button again to start up the computer. For more information on solving problems, see the troubleshooting manual that came with your computer. To do this... ...press this key combination Force a program to quit x-Option-Esc Force the computer to restart x-Control–Power button Force the computer to reset Shift-Fn-Control–Power button Important Only force the computer to reset if the other two key combinations are unsuccessful at solving your problem. When you force a reset, your computer’s default (original) settings will be restored. You may need to reconfigure settings for power management, memory, trackpad, TCP/IP, and AppleTalk if you reset the computer.28 Chapter 1 Turning the Computer Off Always use one of the following methods to shut down the computer. If you don’t, you risk losing any work you haven’t saved. You also risk losing any open documents. To turn the computer off, follow these instructions: 1 If the computer is in sleep, press the Power button (®) or any key on the keyboard (except for the fn key) to wake it. 2 Press the Power button. The following dialog box appears: 3 Press the Return key on the keyboard (or click the Shut Down button in the dialog box). If any applications are still open, a message asks if you want to save your work before the computer shuts down. Note: You can also turn off the computer by choosing Shut Down from the Special menu. What’s Next For more information about working with your computer’s hardware, refer to the following chapters in this manual: To learn more about the basics of your computer’s hardware, including the expansion bays, batteries and power, and connecting to a network, go to Chapter 2, “Using Your PowerBook and Connecting to a Network.” To learn how to connect additional equipment to your PowerBook, such as printers or external monitors, go to Chapter 3, “Connecting Additional Equipment.” To learn how to install additional memory or remove your hard disk, go to Chapter 4, “Installing a RAM Expansion Card and Removing Your Hard Disk.”29 C H A P T E R 2 2 Using Your PowerBook and Connecting to a Network This chapter provides information and instructions on using the built-in features of your Macintosh PowerBook such as expansion bays, batteries, and PC Card slots. In addition, this chapter describes connecting your PowerBook to a computer network and using your internal modem (available on certain configurations only). The information in this chapter will help you get started using the features of your PowerBook. Many of these features, such as networking and infrared communication, require that you configure your system software or use specific applications. You can find more information in the online help, available in the Help menu. In this chapter you will find information on using the following items: m expansion bays and expansion bay modules m batteries and power management m PC Card slots that support PCMCIA and CardBus formats m infrared communication m connecting to a local area network m using your internal modem (available on certain PowerBook configurations) For information on connecting additional equipment such as printers and external monitors, see Chapter 3, “Connecting Additional Equipment.”30 Chapter 2 Using the Expansion Bays Your PowerBook comes with dual-function expansion bays that accept either expansion bay modules or PowerBook batteries. Expansion bay modules–such as a floppy disk drive, CDROM drive, or DVD-ROM drive–are removable, which allows you to easily switch or replace them with another module. Dual-function expansion bays give you maximum flexibility in setting up your PowerBook to meet your needs. For example, if you are working with your PowerBook at home or in the office and you have the power adapter plugged in, you can have a floppy disk drive module in one expansion bay and a CD-ROM or DVD-ROM drive module in the other expansion bay. If you are traveling on a long plane trip, you can have a battery in each expansion bay. Using Expansion Bay Modules Expansion bay modules and PowerBook batteries are inserted and removed in the same way. You can switch expansion bay modules while the PowerBook is turned on, in sleep, or shut down. You should change batteries only when the PowerBook is shut down or in sleep (unless there is a charged battery in the other expansion bay). For more information on PowerBook batteries, see “Power Sources” on page 37. If you purchase an expansion bay module from an independent supplier, be sure to follow the instructions that came with the device. Some modules may have special requirements. Important Only use expansion bay modules and batteries specifically designed for this PowerBook. Expansion bay modules and batteries from other PowerBook computers are not compatible. Left expansion bay Right expansion bay Important Don’t switch modules while the computer is starting up. Also take care not to remove a module if a floppy disk, CD-ROM disc, or other media is inserted (even if the computer is in sleep). If you remove a module (such as the CD-ROM drive) when a disc is inserted, you’ll see a message telling you to reinsert the module.Using Your PowerBook and Connecting to a Network 31 Removing an Expansion Bay Module Before removing an expansion bay module from your PowerBook, you need to make sure that it is not in use and that it does not contain a floppy disk, CD, or other media. To remove an expansion bay module from your Macintosh PowerBook, follow these steps: 1 Place your PowerBook on a hard flat surface. 2 Click the Expansion Bay icon in the Control Strip to determine whether the expansion bay module is ready to be removed. If the Control Strip indicates that the expansion bay module is not removable, quit any application programs or files that may be using it. Then do one of the following: m Drag the icon of the floppy disk, CD, or other media that is inserted in the module to the Trash. m Click the icon of the floppy disk, CD, or other media that is inserted in the module and choose Put Away from the File menu or choose Eject from the Special menu. m Click the Expansion Bay icon in the Control Strip and choose Make Right Module Removable from the menu that appears. Important If you are going to remove both expansion bay modules at the same time, adjust your PowerBook display so that it is at a 90-degree angle to the computer. If the display is adjusted too far back, your PowerBook may tip backward when both expansion bays are empty. 90 o Expansion Bay icon Important Do not remove an expansion bay module that is in use, or you may lose data. If you try to remove the module when it is in use, you’ll see a message telling you to reinsert it.32 Chapter 2 To be sure that the computer isn’t using the module, wait 5 seconds after quitting programs and ejecting a disk before you remove the module. 3 Pull the expansion bay release lever to eject the module. When the lever is completely extended, the module will be partially out of the expansion bay. 4 Gently slide the expansion bay module out of the computer. Important If you see a message telling you to reinsert the module, the module is still in use. Reinsert the module and repeat step 2.Using Your PowerBook and Connecting to a Network 33 Inserting an Expansion Bay Module The PowerBook battery and the optional floppy disk drive module can be placed in either expansion bay. The CD-ROM or DVD-ROM drive module (because of its larger size) can only be put in the right expansion bay. To insert an expansion bay module, follow these steps: 1 If the expansion bay that you want to use already has a module in place, remove it as described in the previous section. 2 Gently slide the module into the expansion bay until the edge of the module is flush with the side of the PowerBook and you hear the module click into place. Make sure that you insert the module with the label facing up. Note: The right expansion bay can accept the wide 5.25-inch CD-ROM or DVD-ROM drive module or the narrower floppy disk drive module or PowerBook battery. When a narrower device is in the expansion bay, a small flap covers the empty part of the bay. When the wider CD-ROM or DVD-ROM drive module is inserted, the flap folds into the bay. Insert the module with the label facing up.34 Chapter 2 Using a Disc in the CD-ROM or DVD-ROM Drive Inserting a Disc To load a disc in the drive, follow these steps: 1 Make sure that the CD-ROM or DVD-ROM drive module is inserted into the right expansion bay. 2 Start up the PowerBook, if it’s not already on. 3 Press the Open button on the outside of the module to open its tray. 4 Pull the tray all the way open. Open button Drive spindle Drive lens Important Do not touch the drive lens. Using Your PowerBook and Connecting to a Network 35 5 Place a disc in the tray, with the label facing up. Make sure the disc is lying flat in the tray and is seated firmly on the spindle. Note: CD-ROM and DVD-ROM drives have small locks on the drive spindle that securely hold the disc in place. When inserting a disc over these locks, you may need to apply additional pressure. Place the hole in the center of the disc directly over the drive spindle and press down until you feel the disc lock into place. 6 Push the tray in to close it. Keep the tray closed except when loading discs. This prevents dust from getting inside the mechanism. Be sure to keep discs free of dust and grease. Note: When the drive is in use, you may notice some vibration as the disc spins rapidly. Certain discs can cause the drive to vibrate because they have heavily inked artwork or a label that creates an imbalance as the drive spins. Some vibration is not unusual for a high-speed CD-ROM or DVD-ROM drive. To minimize vibration from unbalanced discs, do not put labels on your discs. In addition, place the computer on a flat, solid surface when using the drive. Insert the disc, label side up.36 Chapter 2 Ejecting a Disc Follow these instructions to open the tray and eject a disc from the drive: 1 Open the tray. There are several ways to open the tray of your drive. If a disc icon appears on your screen, do one of the following: m Select the disc icon on your screen and drag the icon to the Trash. m Click the disc icon and choose Put Away from the File menu or Eject from the Special menu. m Click the Expansion Bay icon in the Control Strip and choose Make Right Module Removable from the pop-up menu that appears. If no disc icon appears on your screen, do this: m Press the Open button on your drive. If you can’t eject a disc, try this method: m If the standard methods of ejecting a disc do not work (or the computer is shut down), you can eject the disc manually. Carefully insert the end of a pen or straightened paper clip into the small recessed button next to the eject button, and push firmly until the tray disengages. 2 Take the disc out of the tray. Store your discs in a safe place, away from heat, dust, and moisture. 3 Push the tray in to close it. To avoid possible damage to the tray or the drive, keep the tray closed when you are not using it. Expansion Bay iconUsing Your PowerBook and Connecting to a Network 37 Power Sources Your computer can draw its operating power either from a PowerBook battery in one of the expansion bays or from an external power source, using the external power adapter that came with your computer. AC Power You can run your computer from an electrical outlet by plugging in the external power adapter that came with your computer. A battery in an expansion bay will automatically be charged whenever the external power adapter is plugged in. Main Battery The main lithium ion (LiIon) battery provides power to your computer when it is not plugged into an electrical outlet. This battery should provide power for 2–3.5 hours of work time (you may get longer work time, depending on the Macintosh PowerBook model you have and the battery conservation features you use). You can find more information about the battery and power conservation software that came with your PowerBook in the online help, available in the Help menu. Note: The LiIon battery is charged whenever the external power adapter is connected. However, the adapter will charge the battery more quickly if the computer is shut down or in sleep. Optional Second Battery You can configure your computer with a battery in each expansion bay. This configuration is especially useful when you need to use your PowerBook under battery power for a long amount of time, such as on a long plane flight. You can purchase a second battery from an Apple-authorized dealer. Note: When fully charged batteries are installed in both expansion bays, the batteries are discharged one at a time. The battery in the left expansion bay is discharged first. When the charge in the left battery is depleted, the PowerBook switches to the battery in the right expansion bay. Important Be sure to use only the external power adapter that came with your computer or one made specifically for this PowerBook model.38 Chapter 2 Recharging the Battery To recharge the battery inside the computer, plug in the external power adapter. You may also use an external battery charger designed specifically for your Macintosh PowerBook model (available from other manufacturers). When the AC adapter is plugged in, the LiIon battery is recharged whether the computer is off, on, or in sleep. However, the battery will recharge more quickly if the computer is off or in sleep. Monitoring the Battery Charge There are four ways you can determine the charge level of your battery: m Look in the Battery Monitor portion of the Control Strip. m See low-power messages on your display. m Look at the battery level icon next to the clock in the menu bar. m Look at the battery indicator level lights on the battery. Power adapter plug ¯ Power adapter port Power cord Power adapter Warning Use only the external power adapter that came with your computer. Adapters for other electronic devices (including other portable computers) may look similar, but they may damage your computer. If your power adapter came equipped with a three-wire grounding plug—a plug that has a third (grounding) pin—this plug will fit only a grounded AC outlet. If you are unable to insert the plug into the outlet because the outlet is not grounded, contact a licensed electrician to replace the outlet with a properly grounded outlet. Do not defeat the purpose of the grounding plug!Using Your PowerBook and Connecting to a Network 39 Using the Battery Level Indicator Lights You can tell the charge left in your battery by looking at the battery level indicator lights on the battery itself. The charge can be checked with the battery inserted or outside the PowerBook. Push the battery level indicator button to activate the battery level indicator lights. The lights show how much charge is left in the battery. A lighted square indicates that the battery has power; an unlighted square indicates lack of charge. The indicator lights remain lit for a few seconds. Note: The battery level indicator lights stay on while the battery is being charged by the external power adapter. When the battery is fully charged, the lights turn off. Responding to Low-Power Messages When the battery runs low, the computer displays a series of low-power messages. The work time remaining after you see the first message varies depending on how you are using the computer. It’s a good idea to act promptly. What You Should Do When you see a low-power message, you should do one of the following: m Plug in the external power adapter. m Save your work and shut down the computer. m Put the computer to sleep, and quickly replace the depleted battery with a charged one. What You Should Know When the first low-power message appears, the screen dims automatically to save power. If you continue to work without plugging in the power adapter or changing the battery, the computer displays a second low-power message indicating that the computer is about to put itself to sleep. Within a few seconds, the computer goes to sleep automatically to protect the contents of RAM. All activities are interrupted. It’s a good idea to save your work when you see the first of the two low-power messages to make sure you don’t lose information. Fully charged 3/4 charged 1/2 charged 1/4 charged Battery level indicator button Battery level indicator lights40 Chapter 2 If you continue working until the computer goes to sleep automatically, you can wake it again as soon as you plug in the power adapter or replace the battery with a charged battery. Maximizing Work Time The amount of work time your PowerBook’s battery can provide before you need to recharge depends on the equipment you’re using with your computer and the steps you take to conserve power while you work. Battery-saving measures include the following (in order of effectiveness): m Make sure that power cycling is turned on. Your PowerBook reduces the processor power when it is not being used in order to save battery power. For instructions on setting up power cycling, see the online help, available in the Help menu. m Set your PowerBook to run in a reduced processor speed mode when performing tasks such as word processing that don’t require fast processing speed. Setting your PowerBook to run in a reduced processor mode will provide additional battery savings but may affect system performance. For instructions, see the online help, available in the Help menu. m Remove CD-ROM and DVD-ROM discs when they are not in use. m Set the hard disk to spin down after a short time interval. m Set your PowerBook display to turn off (instead of dim) when not in use. m Reduce screen brightness using the brightness control (¤) on the PowerBook case. m Set your PowerBook to sleep after inactivity of 5 minutes or less. m Take advantage of the sleep feature of your PowerBook whenever your work is interrupted. You just need to close the display to put the computer in sleep. You can find more information on the power conservation software and battery conservation tips in the online help, available in the Help menu. Note: If your PowerBook came with an internal modem, it does not support the Energy Saver feature “Wake up when the modem detects a ring.” Important Recharge a depleted battery as soon as possible. Leaving a depleted battery in the computer for a length of time (especially in a hot location, such as the trunk of a car) may damage the battery so that it can’t be recharged. If this happens, you need to replace the battery.Using Your PowerBook and Connecting to a Network 41 Removing or Replacing the Battery PowerBook batteries are removed in the same way that expansion bay modules are. To remove or replace the battery, follow these steps: 1 Place your PowerBook on a hard, flat surface. 2 Save your work and then shut down the computer, put it to sleep, or plug in the power adapter. 3 Pull the expansion bay release lever to eject the PowerBook battery. 4 Gently slide the battery out of the expansion bay. 5 Push the charged battery into the expansion bay to lock it into place. It’s a good idea to plug in the power adapter in case the battery is not fully charged. Important Batteries contain chemicals, some of which may be harmful to the environment. Please dispose of used batteries according to your local environmental guidelines. Lithium-ion (Li-ion)42 Chapter 2 Using PC Cards PC Cards (also known as PCMCIA or CardBus cards) are about the size of a thick credit card and have a 68-pin connector at one end. They come in many varieties, such as fax/modem cards, mass-storage cards, Ethernet connection cards, zoomed video cards, and wireless communication cards. You can use PC Cards to expand your Macintosh PowerBook’s capabilities. Your Macintosh PowerBook has two PC Card slots. You can insert a card into either slot, or (depending on the cards you’re using) you can use both slots simultaneously. There are three types of PC Cards. The different types refer to the thickness of the card. A Type I card is 3.3 millimeters (mm) thick, a Type II card is 5 mm thick, and a Type III card is 10.5 mm thick. You can place a Type I or Type II card in either slot. You can place a Type III card only in the lower slot. When a Type III card is installed, you cannot use the upper slot. You may find it useful to get in the habit of always using the lower slot first to make sure the card is properly inserted. A special type of PC Card supports “zoomed video,” which can display full-motion video in a window on the computer’s screen. Note: Zoomed video cards must be placed in the lower PC Card slot. This section describes how to insert and eject PC Cards and how to use PC Card modems. You can find more information on using PC Cards in the online help, available in the Help menu. Warning Make sure only to use cards that are compatible with your Macintosh PowerBook. If you use an incompatible card, you may damage the card or your PowerBook. If you are not sure whether a PC Card is compatible with your PowerBook, contact the PC Card’s manufacturer.Using Your PowerBook and Connecting to a Network 43 Inserting a PC Card To insert a card, do this: m Insert the card, label up, into the slot. Make sure the card is level. You’ll feel some resistance as you slide the card in. When the card is firmly seated, you will feel it click into place. An icon for the PC Card appears on the desktop. You are now ready to use the card. Consult the card’s documentation for details of its use. A Type I or Type II PC Card can be inserted in either the upper or lower slot. A Type III PC Card must be inserted in the lower slot.44 Chapter 2 Ejecting a PC Card You can eject a PC Card when your computer is on or off. You cannot eject a PC Card when the computer is in sleep. To eject a PC Card when the computer is on, follow these steps: 1 If the computer is in sleep, press the Power button (®) to wake it. 2 Make sure that nothing is blocking the card slot. 3 Click the PC Card’s icon to select it. 4 Drag the card’s icon to the Trash to eject it from the card slot. The card will partially eject from the card slot. 5 Pull the card out of the slot. If you want to use the card again immediately, pull it out about an inch more, wait 10 seconds, and then push it back in. You can also eject a PC Card by doing the following: m Click the card’s icon to select it. Then choose Put Away from the File menu or Eject from the Special menu. After the card is ejected, pull it out of the slot. (If a dimmed icon of the card remains on the desktop, drag it to the Trash.) m Press the eject button for the slot containing the PC Card you want to eject. If the card is not in use, it will usually be ejected. Warning Do not force a PC Card out of the slot. Doing so may damage your computer or PC Card. Important Try to use the eject buttons only when the computer is turned off. Many PC Cards won’t eject this way if the computer is on. Press to eject upper PC card Press to eject lower PC cardUsing Your PowerBook and Connecting to a Network 45 If You Can’t Eject a Card If you are unable to eject a card, follow these steps: 1 Shut down the PowerBook. 2 Straighten one end of a paper clip. 3 Insert the end of the straightened paper clip into the hole next to the slot that contains the card, and press gently but firmly until the card is ejected. 4 Pull the card out of the slot. Using a Zoomed Video PC Card The lower PC Card slot has circuitry for handling video signals, called “zoomed video.” You can purchase PC Cards to which you can provide a video signal from a video camera, VCR, or other such device. The zoomed video card can only be used in the lower slot. With a zoomed video card installed, the PowerBook can display video on the computer’s screen or on an external monitor while performing other tasks at the same time. If you purchase a zoomed video PC Card, be sure it has software that works with your PowerBook. If you can’t eject a card, insert the end of a straightened paper clip into the hole next to the slot. This hole is for the upper slot. 46 Chapter 2 Using a PC Card Modem If your PowerBook does not come with a built-in modem, you can purchase a PC Card modem. For information on using your built-in modem, see the section “Using Your PowerBook’s Optional Internal Modem” on page 51. If you are using a PC Card modem, make sure you do the following: 1 Install the communications software you want to use and any software that came with your modem. 2 Insert the PC Card modem. A PC Card modem icon appears on the desktop. 3 Plug your modem into a working phone line. 4 To set up and connect, follow the instructions that came with your modem and communications software. If you are having problems setting up your PC Card modem, try the following: m Make sure to choose your PC Card modem in your communications software. Some modem files come with your PowerBook. If your PC Card modem is not listed, check the software that came with your modem. If you find the file for your modem, drag it to the Modem Scripts folder inside the Extensions folder (which is in the System Folder). If you can’t find the file for your modem, try using the modem file for a different model from the same manufacturer. If this doesn’t help, you may be able to get the correct modem file from your PC Card modem’s manufacturer. m Make sure to choose the port for your PC Card modem. The port shows the modem name or type, rather than the name of the PC Card slot. Some programs use a virtual port, the Data Port, to allow fax and data applications to share the modem. See the instructions that came with your modem and communications software to determine the specific setup procedure. You must reselect the port if you remove the modem and later put it in the other slot.Using Your PowerBook and Connecting to a Network 47 Using the Infrared File Transfer Capability Your PowerBook comes with built-in infrared (IR) communication features that let you send and receive data without wires. With IR communications, you can exchange files with another PowerBook or with a desktop Macintosh using an external IR module. You can also use IR to make a wireless connection to a network by means of a specialized local area network (LAN) access device that is compatible with the Infrared Data Association (IrDA) Standard specifications. To transfer files, your computer and the other IR device must be within range of each other with their IR windows facing. The range depends on the devices and the method of communication. Note: For best results, place the IR windows directly facing each other. If the angle between the windows is greater than 10 degrees, an IR connection may not be possible. IR-equipped PowerBook computers must be within 3 feet of each other to exchange files using the IRTalk transfer protocol (at 230 kilobits per second). Your computer must be within 3 feet of a LAN access device or another IrDA PowerBook to make a connection (at a communications rate of up to 4 megabits per second). For information on setting up your software for IR communication, see the online help, available in the Help menu. IR window48 Chapter 2 Connecting to a Local Area Network Your computer has built-in hardware allowing you to connect to the following types of networks: m LocalTalk: To connect to a Local Talk network, you plug a LocalTalk cable to the printer/ external modem port (´) on the back of the PowerBook. m Ethernet: To connect to a high-speed Ethernet network, you plug an Ethernet cable into the Ethernet port (G) on the back of the PowerBook. Once your computer is connected to a network, see the online help, available in the Help menu, for information about printing to a network printer, accessing information on file servers, and sharing files on your computer with other users. Ask your network administrator for information about network services such as Internet access and electronic mail. Connecting to a LocalTalk Network To connect your Macintosh PowerBook to a LocalTalk network, you need LocalTalk cables and a LocalTalk adapter (available from your Apple-authorized dealer). If a network administrator is responsible for network maintenance and upkeep at your location, ask for help connecting your computer to the network. To connect your Macintosh to a LocalTalk network, do the following: 1 Open the cover on the computer’s back panel to access the printer/external modem port (labeled with the ´ icon). 2 Attach the LocalTalk adapter to the printer/external modem port. ´Printer/External modem port - √ ¯ V ´ G g Æ ™Using Your PowerBook and Connecting to a Network 49 3 Attach a network cable between the LocalTalk adapter connected to your computer and a LocalTalk adapter on your existing network. 4 If you are using a LocalTalk adapter with RJ-11 (telephone) connectors, connect a terminator to the unused RJ-11 connector on the LocalTalk adapter. A LocalTalk adapter with DIN-8 connectors doesn’t require an external terminator. (For more information on terminators, see the instructions that came with the Apple LocalTalk RJ-11 Connector Kit.) See “Configuring Your Network Connection” on page 50 for information on configuring your LocalTalk connection. - √ ¯ V ´ G g Æ ™50 Chapter 2 Connecting to a 10Base-T Ethernet Network The built-in Ethernet capabilities of your Macintosh PowerBook allow you to connect to a standard (10 Mbit) Ethernet network. If a network administrator is responsible for network maintenance and upkeep at your location, ask for help connecting your computer to the network. To connect your Macintosh PowerBook to an Ethernet network, use the Ethernet cable that came with your computer. (The connector on the cable looks like a standard telephone connector, but it is wider.) To connect your PowerBook to an Ethernet network: 1 Open the cover on the computer’s back panel to access your Ethernet connector (labeled with a G icon). 2 Locate a modular Ethernet cable and connect one end of the cable to the network. 3 Connect the free end of the Ethernet cable to the Ethernet port. 4 Set up your PowerBook software to use Ethernet communication. Configuring Your Network Connection After you physically connect your computer to a network, you need to configure the software for your network connection using AppleTalk and/or TCP/IP. You can find more information in the online help, available in the Help menu. G Ethernet port - √ ¯ V ´ G g Æ ™ - √ ¯ V ´ G g Æ ™Using Your PowerBook and Connecting to a Network 51 Using Your PowerBook’s Optional Internal Modem Some models of the Macintosh PowerBook come with an internal modem card installed in the communications slot inside your computer. To see if a modem is installed, open the modem panel on the left side of the computer. If you see a connector for a phone line, then the modem is installed. Setting Up Your Modem’s Connections To use the internal modem, you need the following: m the single-line telephone cord supplied with your PowerBook, which has a standard RJ-11 phone connector at each end m an analog telephone line (the type found in most homes) with a modular jack You can find more information on setting up your modem communication software to work with your PowerBook internal modem in the online help, available in the Help menu. Connecting the Telephone Line to the Modem Follow these steps to connect the telephone line to the modem. 1 Open the cover on the left side of the computer to expose the modem telephone line connector. 2 Locate the telephone cord that came with your PowerBook. Phone line connector Modem panel Important Use the telephone cord that came with your computer or an equivalent single-line telephone cord. Other types of telephone cords may not work correctly with the modem.52 Chapter 2 3 Plug one end of the telephone cord into the internal modem port on your PowerBook. 4 Plug the other end of the telephone cord into your telephone wall socket. Once the telephone line is connected, you are ready to begin using the modem. Warning The telephone line must be an analog line—the type used in residences. Do not connect a digital telephone line to the modem, because the wrong type of line could damage the modem. Important When you have established a modem connection with another computer or an online service, do not put the computer to sleep. Doing so will disconnect the modem.Using Your PowerBook and Connecting to a Network 53 What Modems Do A modem allows your computer to communicate over telephone lines by converting information from the digital format used by the computer to the analog format used by most telephone systems. It dials the telephone number, establishes a connection with another modem, and controls the flow of data so that communication takes place with optimal speed and accuracy. To exchange data over a telephone line, your modem and the remote modem must establish a connection and agree on how data will be transmitted in these ways: m Connection speed: Initially, your modem tries to connect at its fastest speed. If the remote modem cannot connect at this speed, your modem tries to use the next highest speed. The two modems continue this fallback process until they find the highest speed supported by both. There are several circumstances that may prevent your modem from communicating at its fastest speed. For example, the telephone number you use to connect to your ISP may not support the fastest speed of your modem. m Error control: Error control ensures data accuracy. Your modem and the remote modem must agree on an error control method. Your modem will try to use one of the methods it supports. If the remote modem doesn’t support any of these methods, error control isn’t used. Modems can still communicate reliably without error control. m Data compression: Compression increases the speed of data transmission by up to four times. Your modem will try to use one of the data compression methods it supports. If the remote modem doesn’t support any of these methods, data compression isn’t used. Modems can still communicate reliably without data compression. Your modem is set up to make the best possible connection with other modems automatically. You do not need to do anything. Software for Your Modem Your Macintosh PowerBook comes with modem software, including programs to connect to the Internet and to send and receive faxes. Some of this software is already installed for you. Other software, such as your fax software, needs to be installed from a separate CD that came with your computer. For instructions on using these programs, see their electronic manuals on your computer’s hard disk or on the CD that came with your computer. Important The actual speed of data transmission can vary with line conditions. Because Federal Communications Commission (FCC) rules restrict the power output of modems used by service providers, transmission speeds are limited to 53 Kbps (53,000 bits per second) in the United States. You can obtain speeds of 53 Kbps on downloads from an Internet service provider (ISP) that uses K56flex modems.54 Chapter 2 Choosing the Port Setting You must specify the modem port in each communications program before you can connect to another computer by modem. The following example shows how to specify the modem port in America Online (AOL) software. 1 Open AOL (on your hard disk). 2 If you are new to America Online, click Continue in the dialog box that appears. If you have an AOL account already, click Upgrade. 3 Follow the instructions on the screen to set up an AOL account or to upgrade your current AOL account. When you finish setting up your AOL account, the AOL Welcome window appears. 4 Click Setup in the Welcome window. The Location window opens. 5 In the Port pop-up menu, choose Internal Modem. 6 In the Type pop-up menu, choose PowerBook/GV Internal 56. 7 In the Speed pop-up menu, choose 57600 bps. Always choose the highest speed available. This is the speed at which the computer communicates with the modem. 8 Click Save. Now the AOL software is ready to use with your modem.Using Your PowerBook and Connecting to a Network 55 Modem Tips and Troubleshooting If you have problems using your modem, try the following suggestions: m Make sure the telephone cord is connected properly. Unplug the telephone cord and reconnect it to ensure a good connection. You may also want to try a different telephone cord. Note: Your PowerBook internal modem does not support the Energy Saver feature “Wake up when the modem detects a ring.” m Make sure the telephone line you are using is working. Connect a telephone to the line. You should hear a dial tone when you lift the receiver. Listen for noise on the line. If the telephone line quality is poor, your modem may have trouble maintaining a connection or sending and receiving faxes. If you have a problem with the line quality, try connecting again. If the problem persists, you may need to contact your telephone service provider. Important The PowerBook internal modem will not work with party lines, cannot be connected to a coin-operated telephone, and may not work with a private branch exchange (PBX).57 C H A P T E R 3 3 Connecting Additional Equipment The illustration below shows where equipment should be connected to your Macintosh PowerBook. In most cases, you should refer to the documentation that came with your equipment for instructions on connecting. The safest course is always to shut down your Macintosh PowerBook before you connect any cable other than the power adapter. However, you can connect external devices to the sound input port (√), sound output port (-), printer/external modem port (´), Apple Desktop Bus port (V), and Ethernet port (G) while the computer is on. Information is provided in this chapter for connecting the following devices: m printers and external modems m SCSI devices m external monitors and video display devices m sound input and output devices m mouse, keyboard, or other ADB devices m security equipment to protect your PowerBook External TV out port ™ External monitor port Internal modem Infrared port (some models) - Sound output port ¯ Power adapter port V Apple Desktop Bus (ADB) port √ Sound input port ´Printer/external modem port g SCSI port (HDI-30) Ethernet port (10Base-T) G Æ W - √ ¯ V ´ G g Æ ™58 Chapter 3 Connecting a Printer Your PowerBook has a printer/external modem port, which you use to connect a printer. The printer/external modem port can accept either a direct connection (to a printer such as a StyleWriter) or a LocalTalk network connection (to a printer such as a LaserWriter). See the documentation that came with your printer for specific information about the type of connection it requires. Your computer comes with most Apple printer software (called “printer drivers”) already installed. If you are using a printer from a manufacturer other than Apple, you may need to install a printer driver. You use the Chooser to tell the computer which port you used to connect your printer. You can find more information on selecting a printer in the online help, available in the Help menu. Connecting an External Modem Your PowerBook provides several different ways to connect to the rest of the world using a modem. If your PowerBook came with the optional built-in modem, see “Using Your PowerBook’s Optional Internal Modem” on page 51. If your PowerBook did not come with an internal modem, you can use a PC Card modem in your computer’s PC Card slot (see “Using a PC Card Modem” on page 46). You can also connect an external modem to the printer/external modem port on the back panel of the computer. To connect an external modem, follow these steps: 1 Connect the modem to a power source and to the phone line. 2 Make sure the modem is turned off. 3 With the computer shut down, connect the modem cable to the printer/external modem port (´). 4 Turn on the modem. 5 Start up the computer. The external modem is ready to use. ´Printer/External modem port - √ ¯ V ´ G g Æ ™Connecting Additional Equipment 59 Connecting SCSI Devices You can attach up to seven SCSI devices, including hard disk drives, CD-ROM drives, and scanners, to your computer by linking them together in a chain that starts at your computer’s SCSI port. To connect a SCSI device to your Macintosh PowerBook, you need an Apple HDI-30 SCSI System Cable or equivalent. This cable is light gray, is about 19 inches long, and has 29 pins (one “missing” pin) on the end that connects to the PowerBook. Refer to the manuals that came with your SCSI devices for instructions on installing any necessary software, setting SCSI ID numbers, and connecting SCSI cables and SCSI terminators. The illustrations on the next page briefly describe the proper positioning of SCSI terminators. A SCSI chain of devices must include a terminator on the first and last devices in the chain (but nowhere else in the chain). Some devices include internal terminators. Your Macintosh PowerBook is internally terminated. The names and the part numbers of the cables mentioned in this chapter are as follows: Where to add cable terminators when connecting a single SCSI device Type of Connection Name of Part Part Number From your computer to a SCSI device Apple HDI-30 SCSI System Cable M2538**/A From SCSI device to SCSI device Apple SCSI Peripheral Interface Cable M0207 For SCSI disk mode Apple HDI-30 SCSI Disk Adapter Cable M2539**/A Warning When connecting SCSI equipment, always turn off power to all devices in the chain, including your computer. If you don’t, you could lose information and damage your equipment. Terminator (If this SCSI device has an internal terminator, omit this external terminator.) HDI-30 SCSI system cable60 Chapter 3 Where to add cable terminators when connecting two or more SCSI devices Using Your Macintosh PowerBook as a Hard Disk The Apple HDI-30 SCSI Disk Adapter lets you connect your Macintosh PowerBook to another computer as a hard disk. The PowerBook internal drive appears on the desktop of the other computer as a hard disk icon, and you can transfer information between the computers by dragging files. This feature is called SCSI disk mode. The Apple HDI-30 SCSI Disk Adapter cable is dark gray, is about 10 inches long, and has 30 pins. Connecting Your Computer as a Hard Disk Before making any connections, you need to assign a unique SCSI ID number to the PowerBook. (The ID numbers allow the computer to communicate with several connected SCSI devices.) 1 Set up your system software to use your PowerBook in SCSI disk mode. For information and instructions, see the online help, available in the Help menu. If you are connecting the PowerBook to an existing SCSI chain, make sure to give it an ID number different from those of the other devices. (Many devices include an ID number indicator on the back panel.) 2 Shut down the PowerBook and plug in the power adapter. HDI-30 SCSI SCSI peripheral interface cables system cable Terminator (If this SCSI device has an internal terminator, omit this external terminator.) Important Your Macintosh PowerBook hard disk uses Mac OS Extended format (also known as HFS Plus). In order to use your PowerBook in SCSI disk mode, the computer you are connecting to must be using Mac OS 8.1 or later. If the computer is using an earlier version of system software, you will not be able to see the files on your PowerBook hard disk. Important Turn off password protection before using SCSI disk mode. For instructions, see the online help, available in the Help menu.Connecting Additional Equipment 61 3 Shut down the computer you are connecting to and turn off any other devices in the SCSI chain. 4 Connect the small end of the Apple HDI-30 SCSI Disk Adapter to the SCSI port on your PowerBook. 5 If you are connecting the Macintosh PowerBook directly to the other computer (rather than to an external device in the SCSI chain), attach a SCSI system cable to the other computer. 6 Connect the large end of the Apple HDI-30 SCSI Disk Adapter cable to a SCSI peripheral interface cable attached to the SCSI port on the last device in the SCSI chain, or to the SCSI system cable on the other computer. 7 Make sure that your PowerBook display is open. 8 Turn on the PowerBook by pressing the Power button (®). After a few seconds a SCSI icon appears on the screen, showing the ID number you assigned in step 1. 9 Turn on the other SCSI devices in the chain, if any. 10 Turn on the other computer. Warning Always shut down the PowerBook before connecting or disconnecting the SCSI disk adapter cable. Connecting the adapter cable while the computer is turned on can damage the computer. Warning Always keep your PowerBook display open while operating in SCSI disk mode because heat from the PowerBook is partially dissipated through the keyboard. Closing your display may cause the PowerBook to function improperly. Warning If you do not see the SCSI icon, and the computer starts up normally or displays an error message, press the Power button (®) to shut down (if you can) and then immediately disconnect your computer from the SCSI chain. (If you can’t choose Shut Down, try resetting your PowerBook by holding down the Shift, Function (fn), and Control (ctrl) keys and then pressing the Power button. If you cannot shut down your PowerBook, you should disconnect the cable anyway, or you may lose information.) Then go back and repeat steps 4 through 8, making sure to use the proper cables.62 Chapter 3 The PowerBook’s internal drive appears as a hard disk icon on the screen of the computer you connected it to. You can now transfer and use files as if the Macintosh PowerBook were an external disk drive. Quitting SCSI Disk Mode 1 Shut down the computer your PowerBook is connected to. 2 Press the Power button (®) on the PowerBook. 3 Turn off any other SCSI devices in the chain. 4 Disconnect the PowerBook from the adapter cable. 5 If necessary, disconnect the adapter cable from the other computer or its SCSI chain. You can leave the adapter cable attached if you wish. Your equipment is now ready for normal use. If you disconnected the adapter cable from the other computer or SCSI chain, make sure that the SCSI chain is properly terminated. Important Do not leave the adapter cable attached to the PowerBook. If you do, the computer will behave as though it is still in SCSI disk mode when you try to restart.Connecting Additional Equipment 63 Using an External Monitor You can connect an external monitor to your Macintosh PowerBook. The types of monitors you can use with this model and the way images are displayed on an external monitor differ somewhat from the features available with other PowerBook computers. To make the best choice of an external monitor, keep the following in mind: m Your PowerBook can support a variety of external monitors, including 17-inch and 20-inch multiple-scan displays. m Your PowerBook display must be open when you use an external monitor because heat from the PowerBook is partially dissipated through the keyboard. Closing the display will cause the PowerBook to go to sleep. Macintosh PowerBook G3 Series computers do not work with the display closed. m The computer’s back panel has a VGA-style connector. You can connect the cable for a VGA-style monitor directly to your PowerBook. m To connect an Apple-compatible monitor to your PowerBook, you must use the video adapter that came with the computer. m Images can appear on the internal display, the external monitor, or both, depending on your choice of resolution on the external monitor. m When an image appears on both screens, it is exactly the same (this feature is known as “simulscan” or “video mirroring”). You cannot move the pointer or menu bar from one screen to the other (as you can when a second display is connected to most Macintosh desktop computers). m When an external monitor offers the same resolution as the PowerBook’s internal display, the image appears on both screens the first time you turn on the computer. m If a multiple-resolution external monitor provides a list of its capabilities, the list appears in the Control Strip. Otherwise the system uses a resolution of 640 x 480 pixels as the default for that monitor. For more information on adjusting the resolution of an external monitor, see the online help, available in the Help menu. Important Video mirroring works only with the PowerBook display’s standard resolution. For example, when the 12.1" display is set to its standard resolution (800 x 600) or the 14.1" display is set to its standard resolution (1024 x 768), the display can mirror the external monitor. However, if you switch the resolution to 640 x 480, the built-in display will go dark because scaled resolutions cannot be used for video mirroring.64 Chapter 3 Connecting an External Monitor To connect an external monitor to your PowerBook, follow these steps. Also consult the documentation that came with the monitor. 1 Press the Power button (®) once to get the Shut Down dialog box. 2 Click Shut Down or Sleep. If you connect a monitor with your computer turned on, the computer will not recognize the monitor. 3 Place the monitor near the PowerBook. Arrange the monitor so the top of the screen is slightly below eye level while you work. Position the monitor to minimize glare and reflections on the screen from lights and windows. 4 Make sure that the PowerBook display is open. 5 Make sure the monitor’s power cord is attached to the monitor. Plug the other end into a grounded outlet or power strip. If your monitor’s power cord is designed to plug into the power receptacle on the back of a computer, you can obtain a cord with the correct plug from your Apple-authorized dealer. If you are using a power strip, make sure it is turned on. 6 If you are connecting an Apple-compatible monitor, attach the monitor adapter (shown on the next page) that came with your computer to one end of the external monitor’s cable. If you are connecting a VGA or SVGA monitor, skip this step. Important Keep the computer and the monitor at least 8 inches apart. Interference between the monitor and your computer’s floppy disk drive can cause errors on your floppy disks. 8 inches minimum Important Macintosh PowerBook G3 Series computers do not support operation with the display closed.Connecting Additional Equipment 65 7 Make sure the other end of the monitor’s cable is attached to the monitor. Then attach the end of the cable (with the monitor adapter, if you connected it) to the external monitor port (™) on the back of the PowerBook. If you are connecting a VGA or SVGA monitor, do not use the adapter. Connect the monitor cable directly to the external monitor port on the PowerBook. 8 Turn on the external monitor. 9 Press the Power button (®) to turn on or wake your computer. The external monitor is automatically activated. 10 Click the Resolution icon in the Control Strip and select a resolution from the menu that appears. If you select an external monitor resolution that matches the standard built-in resolution of your PowerBook display, the same image will appear on both the display and the external monitor (known as “simulscan” or “video mirroring”). If you choose a different resolution, the PowerBook display will go dark and images will appear only on the external monitor. For more information on the external monitor resolutions supported by your PowerBook, see the Technical Information booklet that came with your computer. ™ External monitor port Monitor adapter Monitor cable (to Macintosh-compatible monitor) - √ ¯ V ´ G g Æ ™ Resolution icon Important Video mirroring works only with the PowerBook display’s standard resolution. For example, when the 12.1" display is set to its standard resolution (800 x 600) or the 14.1" display is set to its standard resolution (1024 x 768), the display can mirror the external monitor. However, if you switch the resolution to 640 x 480, the built-in display will go dark because scaled resolutions cannot be used for video mirroring.66 Chapter 3 Trouble With the External Monitor? m Nothing happened when you tried to turn on or wake the PowerBook. Make sure that all your equipment is connected properly. Then try turning on or waking the computer again. Make sure that the battery is charged, or that the power adapter is plugged into both the computer and an electrical outlet. If you are using a power strip, make sure it is turned on. m The computer is on, but the external monitor is dark. Make sure that the monitor’s power cord is connected and that its power switch is on. Try adjusting the monitor’s brightness and contrast settings. If this doesn’t work, try restarting your computer. Note: The screen-dimming feature in the Energy Saver control panel turns the screen brightness down to a low level when you haven’t used the computer for a few minutes. ( You can think of dimming as display sleep.) Dimming also affects the external monitor. When you move your finger on the trackpad or press a key on the keyboard, the brightness is restored on both screens. For information and instructions on setting screen dimming, see the online help, available in the Help menu. m The PowerBook goes to sleep when you close the display. The PowerBook display must be open when using an external monitor. Disconnecting an External Monitor 1 Make sure your computer is shut down or in sleep. 2 Make sure your monitor is switched off. 3 Disconnect the monitor cable (for a VGA-style monitor) or monitor adapter (for an Apple monitor) from the external monitor port on the computer’s back panel. Connecting Additional Equipment 67 Using an External Video Display or Recording Device Your PowerBook has an S-video output port (labeled with the Æ icon) where you can connect an external video display or recording device such as a television, videocassette recorder ( VCR), or video projection system. Note: Due to the display limitations of most televisions, images displayed on the television screen will be of lower quality than images on the built-in display or an external monitor. For best results, always use an S-video connection when available. Using the S-video output port, you can display your PowerBook desktop on a television screen and record images from the desktop to a VCR. PowerBook computers equipped with an S-video output port can output the following display formats: m S-video: High-quality video format used by certain televisions, VCRs, and video projectors. You can connect a cable from an S-video device directly to the S-video output port (Æ) on the back panel of your PowerBook. S-video is recommended because it provides better quality. m Composite video: Video format used by most televisions and VCRs. To connect a composite video device, you need to use the composite to S-video adapter that came with your PowerBook. Æ S-video output port - √ ¯ V ´ G g Æ ™ Warning The S-video output port (labeled with the Æ icon) looks similar to the ADB port (labeled with the V icon) and the printer/modem port (labeled with the ´ icon). Only plug your S-video device into the S-video output port. Plugging a video device into the wrong port could damage your equipment. RCA plug S-video plug Composite to S-video adapter68 Chapter 3 Connecting Video Equipment to Your PowerBook You can record and deliver a sophisticated presentation by combining the video and sound capabilities of your PowerBook. The steps that follow explain how to set up equipment for displaying the computer desktop on a television and recording the computer’s output to videotape. Use the information in this section as a guideline when connecting other external video display and recording devices. Note: You cannot use the S-video output port and the external monitor port at the same time. To connect a television or VCR for output from the computer: 1 Shut down your PowerBook and turn off the television or VCR. 2 Attach one end of a video cable (not included with your PowerBook) to the video in port on the television or VCR. Follow the directions that came with the television or VCR. 3 If you’re using an RCA-type cable, plug in the other end of the video cable to the composite to S-video adapter. If you’re using a device that supports S-video, skip this step. 4 Plug the S-video cable or adapter to the S-video output port (Æ) on the back panel of your PowerBook. PowerBook connected to a television using an S-video cable S-video cable (not included with your computer) RCA-type cable (not included with your computer) Important If the connector doesn’t slide easily into the port, check the pin alignment and try again. Don’t use force, which could damage your equipment. TV S-video output port Æ S-video cable S-video In portConnecting Additional Equipment 69 PowerBook connected to a television using an RCA-type cable 5 If you want to output sound as well as video from your PowerBook, use a dual-RCA-plug–to–stereo-miniplug cable (not included with your computer) to connect the sound output port on the back of your PowerBook to audio input ports on your television or VCR. 6 Turn on the computer and the television or VCR. Your PowerBook starts up using the built-in display. The television is dark. 7 Click the Resolution icon in the Control Strip and select a NTSC or PAL compatible screen resolution from the menu that appears. For best results use 640 x 480, 60 Hz for NTSC systems and 640 x 480, 50 Hz for PAL systems. The PowerBook display becomes dark and images appear on the television. 8 To switch back to your PowerBook display, select the “built-in” resolution for your PowerBook from the Control Strip. TV RCA In port S-video output port Æ Composite to S-video adapter RCA-type cable Dual-RCA-plug–to–stereo-miniplug cable (not included with your computer) Resolution icon70 Chapter 3 Trouble With the External Video Device? m Nothing happens when you tried to turn on the PowerBook. Make sure your equipment is connected properly. Then try pressing the Power button (®) again. Make sure the battery is charged, or the power adapter is plugged into both the computer and an electrical outlet. If you are using a power strip, make sure it is turned on. m The computer is on, but the television is dark. Select an NTSC or PAL compatible resolution from the Resolution icon in the Control Strip. If the television is still dark, make sure that the television is on and set up to receive video from an outside source. See the manual that came with your television or other video device for more information. If this doesn’t work, try restarting your computer. Note: The screen-dimming feature in the Energy Saver control panel turns the screen brightness down to a low level when you haven’t used the computer for a few minutes. Dimming also affects the television. When you move your finger on the trackpad or press a key on the keyboard, the brightness is restored on both screens. For information on screen dimming, see the online help, available in the Help menu. Disconnecting an External Video Device 1 Make sure your computer is shut down or in sleep. 2 Make sure your television or other external video device is switched off. 3 Disconnect the S-video cable or S-video adapter from the S-video output port (Æ) on the computer’s back panel. Connecting Additional Equipment 71 Connecting and Using Sound Input Devices Your computer has a built-in microphone. In addition, you can connect a PlainTalk microphone to the external sound input port (√). ( You can also connect a standard linelevel input microphone, although it is not suitable for speech recognition.) You can find more information on using the microphone to record sounds in the online help, available in the Help menu. Note: When using an external microphone, set the volume to 50 percent and point the microphone away from the PowerBook speakers. Pointing the microphone towards the speakers with the volume set to maximum may result in feedback. Because your PowerBook can receive sounds from a variety of different sources, such as the internal microphone, expansion bay module, or zoomed video card, you need to select a sound input source. m Click the Sound Source icon in the Control Strip and choose an input source from the menu that appears. -Sound output port √Sound input port - √ ¯ V ´ G g Æ ™ Sound Source icon72 Chapter 3 Connecting Sound Output Devices The Macintosh PowerBook has a stereo sound output port (-) to which you can connect externally powered speakers, an amplifier, headphones, or other audio output device. The sound output port accepts a standard stereo miniplug, like that used to attach headphones to a portable tape or CD player. Your computer also has two stereo speakers, which play sound from the following sources: audio CD in the CD-ROM or DVD-ROM drive, external stereo device connected to the computer through the sound input port, zoomed video card, internal modem, or file on your hard disk. The computer automatically selects the sound output source. If an external device, such as a pair of headphones, is connected, sound is routed there. If no external output device is connected, sound plays through the computer’s speakers. Locking Your Computer You can purchase a security cable and lock to protect your Macintosh PowerBook. With a lock, you can secure your computer to a desk or table. See your Apple-authorized dealer or computer retailer for details on security devices. Note: You can protect the contents of your hard disk by turning on password protection. You can find more information on password security in the online help, available in the Help menu. Important A security locking cable does not prevent the removal of expansion bay modules or batteries or access to your RAM and hard disk. Sample locking device with security cable Ç Security slotConnecting Additional Equipment 73 Connecting a Mouse, Keyboard, or Other ADB Device You can connect a mouse, keyboard, graphics tablet, or other Apple Desktop Bus (ADB) device to the ADB port on the back panel of the PowerBook. Note: You may experience a slight delay if you connect a mouse or other ADB device while the computer is turned on. Connecting Other Devices For instructions on connecting a device not discussed in this chapter, refer to the documentation that came with the device. V Apple Desktop Bus (ADB) port - √ ¯ V ´ G g Æ ™75 C H A P T E R 4 4 Installing a RAM Expansion Card and Removing Your Hard Disk This chapter provides information about installing a RAM expansion card and removing your PowerBook hard disk for service or security reasons. Getting Ready Before you open your computer, you need to make sure that you have a Phillips or a Torx T-8 screwdriver (available from a hardware or electronics supply store). Removing the Keyboard and Internal Heat Sink The design of your Macintosh PowerBook allows you to easily access the internal components of the computer by removing the keyboard. The steps in this section explain how to remove the PowerBook keyboard and internal heat sink to access the RAM expansion slot and internal hard disk. 1 Place your PowerBook on a hard, flat surface. Warning To avoid damage to your computer, Apple recommends that only an Applecertified technician install additional RAM. Consult the service and support information that came with your Apple product for instructions on how to contact an Appleauthorized service provider or Apple for service. If you attempt to install additional RAM yourself, any damage you may cause to your equipment will not be covered by the limited warranty on your computer. See an Apple-authorized dealer or service provider for additional information about this or any other warranty question.76 Chapter 4 2 If your PowerBook is turned on, press the Power button (®). In the Shut Down dialog box, click Shut Down. 3 Unplug the power adapter and any other devices from the back of your PowerBook. Unplug any phone line from the internal modem. 4 Adjust your display so that it is at a 90-degree angle to the computer. If your display is tilted too far back, your PowerBook may tip backward when the expansion bay modules are removed in the next step. 5 Pull out both expansion bay release levers to eject the modules or batteries in both the expansion bays. 6 Remove the modules or batteries from both the expansion bays. Warning The internal components (including the internal heat sink) of your PowerBook may be hot. If you have been using your PowerBook, wait 10 minutes before continuing, to let the internal components cool down. 90 oInstalling a RAM Expansion Card and Removing Your Hard Disk 77 7 With your thumbs positioned slightly below the keyboard, place your fingers inside the expansion bays and locate the small plastic tabs that hold the keyboard in place. The plastic tabs have small ridges on them and are located on the underside of the top shell of the PowerBook approximately one inch inside each expansion bay. 8 Gently slide the plastic tabs toward you until you see the lower portion of the keyboard pop up. 9 Lift the lower portion of the PowerBook keyboard up slightly and pull it back enough to displace the five metal tabs that hold the front of the keyboard in place. Plastic tab Plastic tab Tabs78 Chapter 4 10 Flip the keyboard over and lay it on the palm rests and trackpad. 11 Remove the two screws that secure the internal heat sink (using a Phillips or Torx T-8 screwdriver) and then lift it up by pulling on the small metal tab. You now have access to the internal components of your PowerBook. Warning The PowerBook internal heat sink may be hot. If you have been using your PowerBook, wait 10 minutes before continuing to let the internal components cool down. Screws Heat sink Small metal tabInstalling a RAM Expansion Card and Removing Your Hard Disk 79 Installing a RAM Expansion Card To install a RAM expansion card in your PowerBook, follow these steps: 1 If you have not already done so, remove the PowerBook keyboard and internal heat sink as described in “Removing the Keyboard and Internal Heat Sink” on page 75. 2 Locate the empty RAM expansion slot. Note: If you ordered your PowerBook with additional memory, this slot may already have a RAM card installed. 3 Gently touch the metal surface on the right side of the inside of the computer to discharge any static electricity built up on your body. This prevents damage to your Macintosh PowerBook or RAM card. Don’t walk around while installing the card. If you do, touch the metal surface again to discharge any static electricity. Important Make sure that the RAM expansion card you are installing is made for your Macintosh PowerBook model. Components designed for other PowerBook models will not work with your computer. RAM expansion slot Metal portion80 Chapter 4 4 Position the RAM expansion card at a 30-degree angle. Line up the notch in the PowerBook RAM expansion card with the small tab in the RAM expansion slot. 5 Push the RAM expansion card into the plastic expansion slot. You may feel some resistance. If you are having trouble inserting the card, try pushing one side at a time. 6 Gently push the RAM expansion card down until the two snaps on either side of the card lock into place. Your RAM expansion card is now ready to use. 7 Skip ahead to “Replacing the Keyboard and Internal Heat Sink” on page 83. 30 o SnapInstalling a RAM Expansion Card and Removing Your Hard Disk 81 Removing Your PowerBook Hard Disk Drive Your PowerBook was designed so that you could easily remove your internal hard disk drive for service or security needs. 1 If you have not already done so, remove the PowerBook keyboard and internal heat sink as described in “Removing the Keyboard and Internal Heat Sink” on page 75. 2 Locate the hard disk drive. 3 Gently touch the metal surface on the left side of the inside of the computer to discharge any static electricity built up on your body. This prevents damage to the Macintosh PowerBook or internal hard disk drive. Don’t walk around while removing the hard disk drive. If you do, make sure you touch the metal surface again to discharge any static electricity. Hard disk drive Metal portion of processor cage82 Chapter 4 4 Loosen the screw that locks the hard disk in place. Note: The hard disk screw stays attached to the hard disk; you do not need to remove it completely. 5 Gently pull up on the small metal tab (located on the left side of the hard disk) to disengage the hard disk from the logic board. 6 Carefully lift the hard disk out of the PowerBook. Always store your internal hard disk in a safe place and avoid contact with the hard disk connectors. Hard disk screwInstalling a RAM Expansion Card and Removing Your Hard Disk 83 Replacing the Keyboard and Internal Heat Sink Follow the steps in this section to replace your PowerBook keyboard. 1 Insert the internal heat sink and replace the two screws to secure it in place. 2 Press down on the bottom portion of the heat sink to secure it into place. 3 Flip the keyboard back on top of the opening in your PowerBook. 4 Insert the five small tabs at the top of the keyboard into the opening in the PowerBook case. 5 Press down on the lower portion of the keyboard until it snaps into place. 6 Replace the expansion bay modules. Screws Tabs84 Chapter 4 You are now ready to start working with your PowerBook again. Warning Never turn on your PowerBook G3 Series computer unless all of its internal and external parts are in place. Operating the computer when it is open or missing parts can be dangerous, and can damage your computer.85 A P P E N D I X Health, Safety, and Maintenance Tips Health-Related Information About Computer Use Muscle soreness, eye fatigue, and other discomforts and injuries sometimes associated with using computers can occur from performing any number of activities. In fact, misuse of the same muscles during multiple activities can create a problem that might not otherwise exist. For example, if you engage in nonwork activities that involve repetitive stress on the wrist— such as bicycling—and also use your computer’s keyboard improperly, you may increase your likelihood of developing wrist problems. Some individuals are at greater risk of developing these problems because of their health, physiology, lifestyle, and general exposure to stress. Work organization and conditions, such as workstation setup and lighting, also play a part in your overall health and comfort. Preventing health problems is a multifaceted task that requires careful attention to the way you use your body every hour of every day. The most common health effects associated with using a computer are musculoskeletal discomfort and eye fatigue. We’ll discuss each area of concern in this appendix. Musculoskeletal Discomfort As with any activity that involves sitting for long periods of time, using a computer can make your muscles sore and stiff. To minimize these effects, set up your work environment carefully, using the guidelines that follow, and take frequent breaks to rest tired muscles. To make working with your computer more comfortable, allow enough space in your work area so that you can change position frequently and maintain a relaxed posture. Another type of musculoskeletal concern is repetitive stress injuries (RSIs), also known as cumulative trauma disorders (CTDs). These problems can occur when a certain muscle or tendon is repeatedly overused and forced into an unnatural position. The exact causes of RSIs are not totally understood, but in addition to awkward posture, such factors as the amount of repetition, the force used in the activity, the individual’s physiology, workplace stress level, and lifestyle may affect the likelihood of experiencing an RSI.86 Appendix RSIs did not suddenly arise when computers were invented; tennis elbow and writer’s cramp, for example, are two RSIs that have been with us for a long time. Although less common than other RSIs, one serious RSI discussed more often today is a wrist problem called carpal tunnel syndrome, which may be aggravated by improper use of computer keyboards. This nerve disorder results from excessive pressure on the median nerve as it passes through the wrist to the hand. This section offers advice on setting up your work area to enhance your comfort while you use your computer. Since the effects of repetitive movements associated with using a computer can be compounded by those of other work and leisure activities to produce or aggravate physical problems, proper use of your computer system must be considered as just one element of a healthy lifestyle. No one, of course, can guarantee that you won’t have problems even when you follow the most expert advice on using computer equipment. You should always check with a qualified health specialist if muscle, joint, or eye problems occur. Eye Fatigue Eye fatigue can occur whenever the eyes are focused on a nearby object for a long time. This problem occurs because the eye muscles must work harder to view an object that’s closer than about 20 feet (6 meters). Improper lighting can hasten the development of eye fatigue. Although eye fatigue is annoying, there’s no evidence that it leads to permanent damage. Whenever you’re engaged in an activity that involves close-up work—such as reading a magazine, doing craft work, or using a computer—be sure to have sufficient glare-free lighting and give your eyes frequent rest breaks by looking up and focusing on distant objects. Remember to have your eyes examined regularly. To prevent discomfort and eye fatigue: m Arrange your work space so that the furniture is properly adjusted for you and doesn’t contribute to an awkward working posture. m Take frequent short breaks to give your muscles and eyes a chance to rest.Health, Safety, and Maintenance Tips 87 Arranging Your Work Area and Equipment The suggestions in this section can help you work more comfortably with you computer. Chair m An adjustable chair that provides firm, comfortable support is best. Adjust the height of the chair so your thighs are horizontal and your feet flat on the floor. The back of the chair should support your lower back (lumbar region). Follow the manufacturer’s instructions for adjusting the backrest to fit your body properly. Keyboard and Trackpad m When you use the keyboard and trackpad, your shoulders should be relaxed. Your upper arm and forearm should form an approximate right angle, with your wrist and hand in roughly a straight line. m You may have to raise your chair so your forearms and hands are at the proper angle to the keyboard. If this makes it impossible to rest your feet flat on the floor, you can use a footrest with adjustable height and tilt to make up for any gap between the floor and your feet. Or you may lower the desktop to eliminate the need for a footrest. Another option is to use a desk with a keyboard tray that’s lower than the regular work surface. m Use a light touch when typing or using the trackpad and keep your hands and fingers relaxed. Avoid rolling your thumbs under your palms. Some computer users may develop discomfort in their hands, wrists, or arms after intensive work without breaks. If you begin to develop chronic pain or discomfort in your hands, wrists, or arms, consult a qualified health specialist. m Change hand positions often to avoid fatigue. This Not this This Not this88 Appendix Mouse If you use an external mouse, position the mouse at the same height as your keyboard. Allow adequate space to use the mouse comfortably. Built-In Display m Adjust the angle of the display to minimize glare and reflections from overhead lights and windows. m You may need to adjust the brightness and contrast of the screen when you take the computer from one work location to another, or if the lighting in your work area changes. External Monitor If you use an external monitor, this suggestion may be helpful. m If possible, arrange the monitor so the top of the screen is slightly below your eye level when you’re sitting at the keyboard. The best distance from your eyes to the screen is up to you, although most people seem to prefer 18 to 28 inches (45 to 70 cm). Avoiding Fatigue m Change your seated position, stand up, or stretch whenever you start to feel tired. Frequent short breaks are helpful in reducing fatigue. m Allow adequate work space so that you can work comfortably. Place papers or other items so you can view them easily while using your computer. A document stand may make reading papers more comfortable. m Eye muscles must work harder to focus on nearby objects. Occasionally focus your eyes on a distant object, and blink often while you work. m Clean your screen regularly. Keeping the screen clean helps reduce unwanted reflections. What About Electromagnetic Emissions? There has been recent public discussion of the possible health effects of prolonged exposure to extremely low frequency (ELF) and very low frequency (VLF) electromagnetic fields. Such fields are associated with electromagnetic sources such as television sets, electrical wiring, and some household appliances—as well as computer monitors. Apple has reviewed scientific reports and sought the counsel of government regulatory agencies and respected health organizations. Based on the prevailing evidence and opinions, Apple believes that the electric and magnetic fields produced by computer monitors do not pose a health risk. In response to those customers who wish to reduce their exposure to electromagnetic fields, Apple has lowered the emission levels of its products. Health, Safety, and Maintenance Tips 89 Important Care and Safety Instructions For your own safety and that of your equipment, always take the following precautions. Disconnect the power plug (by pulling the plug, not the cord) and remove the expansion bay battery if any of the following conditions exists: m you want to remove any parts (leave the cord disconnected as long as the keyboard is open) m the power cord or plug becomes frayed or otherwise damaged m you spill something into the case m your PowerBook G3 Series computer is exposed to rain or any other excess moisture m your PowerBook G3 Series computer has been dropped or the case has been otherwise damaged m you suspect that your PowerBook G3 Series computer needs service or repair m you want to clean the case (use only the recommended procedure described later) Important The only way to disconnect power completely is to unplug the power cord and remove the batteries. Make sure at least one end of the power cord is within easy reach so that you can unplug the PowerBook G3 Series computer when you need to. Be sure that you always do the following: m Keep your PowerBook G3 Series computer away from sources of liquids, such as washbasins, bathtubs, shower stalls, and so on. m Protect your PowerBook G3 Series computer from dampness or wet weather, such as rain, snow, and so on. m Read all the installation instructions carefully before you plug your PowerBook G3 Series computer into a wall socket. m Keep these instructions handy for reference by you and others. m Follow all instructions and warnings dealing with your system. To clean the case, do the following: 1 Disconnect the power plug. (Pull the plug, not the cord.) 2 Wipe the surfaces lightly with a clean, soft cloth dampened with water. Clean the screen with soft, lint-free paper. Warning Electrical equipment may be hazardous if misused. Operation of this product, or similar products, must always be supervised by an adult. Do not allow children access to the interior of any electrical product and do not permit them to handle any cables.90 Appendix Caution m If you have a problem with your computer and nothing in the computer manual solves the problem, take the computer to your Apple-authorized dealer or service provider. Attempting to repair the computer yourself may void the limited warranty. m Do not move the computer when you can hear its hard disk spinning. When you put the computer to sleep, wait until the screen is blank before moving the computer. m Never force a connector into a port. Make sure that the connector matches the port and that it’s right side up. If the connector and port do not join easily, they do not match. m Do not use the computer in wet or dusty environments. m Keep dirt and liquids away from the ports on the back panel, the keyboard, and the trackpad. If you spill any food or liquid onto the computer, shut it down immediately, unplug it, and remove the expansion bay modules before cleaning up the spill. Depending on what you spilled and how much got into the computer, you may have to bring the computer to an Apple-authorized service provider for cleaning. m Do not touch the screen with any sharp or pointed objects. m Use only the battery supplied with your computer, or an identical model. Batteries designed for other portable computers may look similar, but they may not work with your computer and may damage it. m Use only the power adapter supplied with your computer, or an identical model. Adapters designed for other electronic devices may not work with your equipment and may damage it. m When using your PowerBook or when charging the battery, it is normal for the bottom of the case to get warm. The bottom of the PowerBook case functions as a cooling surface that transfers heat from inside the computer to the cooler air outside. The bottom of the case is raised slightly to allow airflow that keeps the unit within normal operating temperatures. Important m Use the computer only in environments where the temperature range is between 50°F/10°C and 95°F/35°C. m Do not expose the computer to very low (less than –13°F/–25°C) or very high (more than 140°F/60°C) temperatures. m If the computer has been in a cold place for several hours, let it warm up to room temperature before you use it.Health, Safety, and Maintenance Tips 91 Caring for Batteries m Always handle batteries carefully. m Do not short-circuit the battery terminals (that is, do not touch both terminals with a metal object). Do not carry loose batteries in a pocket or purse where they may mix with coins, keys, or other metal objects. Doing so may cause an explosion or a fire. m Do not drop, puncture, disassemble, mutilate, or incinerate the battery. m Recharge batteries only as described in this manual and only in ventilated areas. m Do not leave batteries in hot locations (such as the trunk of a car) for more than a day or two. Intense heat can shorten battery life. m Do not leave a battery in storage for longer than 6 months without recharging it. Handling Floppy Disks 125° F (52° C) 50° F (10° C) Do not use a pencil or an eraser on a disk or disk label. Store disks at temperatures between 50° F and 125° F. Do not touch the exposed part of the disk behind the metal shutter. Keep disks away from magnets.92 Appendix Handling CD and DVD Discs Traveling With the Macintosh PowerBook Always bring the system software CD that came with your computer when you travel. If you experience system software problems while traveling, you may need it to correct any problems. Take the necessary plug adapters if you’re traveling overseas. (You may need to use them with the power cord.) You do not need a voltage transformer. The power adapter can handle 100 volts to 240 volts AC (50 Hz to 60 Hz). Check the following diagrams to determine which plug adapters you’ll need, or ask your travel agent. Do not put tape on discs. Do not scratch discs. Do not write on discs. Do not spill liquids on discs. Do not get dust on discs. Do not expose discs to direct sunlight. Outlet Type Locations United States, Canada, parts of Latin America, Japan, Korea, the Philippines, Taiwan Russia and the Commonwealth of Independent States (CIS), most of Europe, parts of Latin America, the Middle East, parts of Africa, Hong Kong, India, most of South Asia Mexico, United Kingdom, Ireland, Malaysia, Singapore, parts of Africa China, Australia, New ZealandHealth, Safety, and Maintenance Tips 93 Airplanes and Airports Some airlines have reported that use of portable electronic devices may have interfered with the aircraft’s flight navigation or communications systems. Many airlines restrict or manage the use of electronic equipment during flights. Please respect the regulations of the airlines. A properly tuned X-ray machine or metal detector should cause no damage to your Macintosh PowerBook. But the motors that drive the belts on some security machines have magnets that can damage your information. To avoid problems, place the Macintosh PowerBook close to the entrance of the machine and remove it as soon as possible. At most airports you can also have the computer hand-inspected by security personnel. Security officials may require you to turn the Macintosh PowerBook on. Make sure you have a charged battery on hand. To speed up the security process, have your PowerBook in sleep instead of shut down. Handling Your Macintosh PowerBook The safety instructions earlier in this appendix also apply when you are traveling. In addition, note these precautions: m Do not transport your Macintosh PowerBook while it is turned on. Put your computer to sleep or shut it down before you move it. m Do not check your computer as baggage. Carry it with you. International Repair and Service Apple’s limited warranty covers your Macintosh PowerBook for one year, regardless of where it is purchased. The Apple-authorized service providers in more than 80 countries can handle most repairs (unless the repair involves a component specific to another area of the world). Bring a copy of your proof of purchase with you. Storing the Macintosh PowerBook 1 Save your work on a hard disk or floppy disks. 2 Press the Power button and click Shut Down, or choose Shut Down from the Special menu. 3 Close the display. 4 Store the computer in a cool, dry place. Storage temperatures should remain between –25°C and 60°C (between –13°F and 140°F). Avoid leaving the computer where temperatures may be extreme or unpredictable—in the trunk of a car, for example.94 Appendix Service and Support If your computer is malfunctioning but does not appear to be physically damaged, shut it down (and leave the power adapter plugged in, if possible) until you can get help. If you know or suspect that your computer is physically damaged, disconnect the power adapter, remove the battery, and do not use the computer until it can be repaired. Modem and Fax Safety If you’re planning to install telephone wiring or telephone jacks, follow these precautions: m Never install telephone wiring during a lightning storm. m Never install telephone jacks in wet locations unless the jacks are specifically designed for wet locations. m Never touch uninsulated telephone wires or terminals unless the telephone line has been disconnected at the network interface. m Use caution when installing or modifying telephone lines. m Avoid using a telephone, other than a cordless type, during an electrical storm. There may be a remote risk of shock from lightning. m Never use a telephone to report a gas leak while in the vicinity of the leak. Important See the service and support information that came with your computer for information about customer assistance. Important Disconnect the telephone line from the PowerBook before removing the keyboard to access the internal components. Pages Guide de l’utilisateur F2644.book Page 1 Thursday, January 13, 2005 5:18 PMK Apple Computer, Inc. © 2005 Apple Computer, Inc. Tous droits réservés. Ce manuel est soumis aux lois sur le copyright et ne peut être copié, totalement ou partiellement, sans le consentement écrit d’Apple. Vos droits concernant le logiciel sont régis par le contrat de licence qui l’accompagne. Le logo Apple est une marque d’Apple Computer, Inc., déposée aux États-Unis et dans d’autres pays. L’utilisation du logo Apple via le clavier (Option + Maj + K) pour des motifs commerciaux sans l’autorisation écrite préalable d’Apple peut constituer une violation du droit des marques et une concurrence déloyale en violation des lois fédérales et nationales. Tous les efforts ont été déployés afin de garantir l’exactitude des informations de ce manuel. Apple n’est pas responsable des erreurs d’impression ou de rédaction. Apple 1 Infinite Loop Cupertino, CA 95014-2084 408-996-1010 www.apple.com Apple, le logo Apple logo, AppleWorks, iBook, iMovie, iTunes, Mac, Mac OS, PowerBook et QuickTime sont des marques d’Apple Computer, Inc. déposées aux États-Unis et dans d’autres pays. Finder, iPhoto, iWork, Product Name et Safari sont des marques d’Apple Computer, Inc. AppleCare est une marque de service d’Apple Computer, Inc., déposée aux États-Unis et dans d’autres pays. Adobe et Acrobat sont des marques ou des marques déposées d’Adobe Systems Incorporated, aux ÉtatsUnis et/ou dans d’autres pays. Les autres noms de sociétés et de produits mentionnés dans ce document sont des marques de leurs propriétaires respectifs. La mention de produits tiers est indiquée à titre informatif exclusivement et ne constitue ni une approbation, ni une recommandation. Apple n’assume aucune responsabilité quant aux performances ou à l’utilisation de ces produits. F2644.book Page 2 Thursday, January 13, 2005 5:18 PM3 Table des matières 7 Préface: Bienvenue dans Pages 8 Vue d’ensemble des fonctionnalités de Pages 12 Pour en savoir plus 15 Chapitre 1: Présentation de Pages 16 La fenêtre Pages 22 Le tiroir Styles 23 Outils Pages 26 Raccourcis 26 Le document Pages 29 Chapitre 2: Création d’un document à l’aide des modèles de Pages 30 Étape 1 : Sélectionnez un type de document 33 Étape 2 : Ajoutez du texte 36 Étape 3 : Ajoutez des graphismes et d’autres éléments 41 Étape 4 : Éditez le document 47 Étape 5 : Enregistrez et partagez le document 51 Chapitre 3: Mise en forme de texte et de paragraphes 51 Mise en forme de la taille et de l’apparence du texte 59 Définition de l’alignement et de l’espacement du texte 64 Définition de taquets de tabulation afin d’aligner le texte 69 Création de listes à puces ou numérotées et de structures 72 Création de renvois, de barres latérales et de texte en surbrillance 79 Chapitre 4: Utilisation de styles 81 Application de styles F2644.book Page 3 Thursday, January 13, 2005 5:18 PM4 Table des matières 83 Substitutions de style 84 Recherche et remplacement de styles 85 Modification et création de styles de paragraphe 90 Modification et création de styles de caractère 93 Modification et création de styles de liste 99 Chapitre 5: Mise en forme de la disposition et de la table des matières d’un document 101 Configuration de l’orientation et de la taille des pages 102 Définition des marges de page 102 Création de colonnes 106 Création d’un document avec des pages opposées gauche et droite 107 Ajout d’en-têtes et de pieds de page, de numéros de page et de notes de bas de page 110 Modification de la mise en forme de documents à l’aide de sauts de section 114 Génération d’une table des matières 117 Chapitre 6: Utilisation de graphismes et autres médias 117 Utilisation de graphismes 119 Ajout d’objets fixes et d’objets en ligne 123 Utilisation de fichiers PDF en tant que graphismes 124 Rognage (masquage) d’images fixes 126 Utilisation du Navigateur de média 127 Redimensionnement, déplacement et superposition de texte ou de graphismes 132 Habillage d’un objet avec du texte 135 Ajout de son et de séquences 137 Ajout de liens et de signets 141 Chapitre 7: Modification de propriétés d’objets 141 Utilisation de remplissages par des couleurs et des images 147 Changement du style de trait 149 Ajout d’ombres 150 Ajustement de l’opacité 151 Modification de l’orientation F2644.book Page 4 Thursday, January 13, 2005 5:18 PMTable des matières 5 153 Ajustement de la taille et de la position d’objets 155 Chapitre 8: Création de tableaux 156 Ajout d’un tableau 158 Sélection de cellules et de bordures d’un tableau 161 Mise en forme de tableaux 168 Ajout d’images ou de couleurs à l’arrière-plan 171 Chapitre 9: Création de graphiques 171 À propos des graphiques 174 Ajout d’un graphique 176 Modification de données dans un graphique 177 Mise en forme de graphiques 189 Chapitre 10: Impression et exportation d’un document vers d’autres formats 189 Impression de documents 195 Exportation vers d’autres formats de document 197 Chapitre 11: Conception de modèles de document 198 Étape 1 : Configuration de document 200 Étape 2 : Définition de styles 204 Étape 3 : Création de texte et de graphismes destinés aux espaces réservés 207 Étape 4 : Enregistrement d’un modèle personnalisé 209 Index F2644.book Page 5 Thursday, January 13, 2005 5:18 PMF2644.book Page 6 Thursday, January 13, 2005 5:18 PM7 Préface Bienvenue dans Pages Pages est une application de traitement de texte standard mais puissante ; elle permet de créer facilement des documents de haute qualité, qu’il s’agisse d’une lettre, d’une invitation, d’un bulletin mensuel ou d’une brochure en tryptique. Cette préface présente les fonctionnalités de Pages ainsi que différentes ressources pour apprendre à l’utiliser. Pages facilite la composition et la conception de divers documents sur votre ordinateur, d’un simple mémo à des rapports scolaires bien structurés, en passant par une brochure très stylisée et élégante. Avec les outils de Pages, vous pouvez facilement changer la disposition et l’aspect de n’importe quel document à mesure que vous travaillez. Présentez les données à l’aide des tableaux ou graphiques de Pages. Inté- grez une multitude de types de texte et de graphisme ; vous pouvez même inclure des séquences vidéo, des liens et des séquences audio si vous prévoyez de publier votre document en ligne. Utilisez les modèles fournis avec Pages afin de créer des documents professionnels et uniformes. Vous pouvez également créer vos modèles. Avec Pages, vos mots sont un plaisir à lire. Votre document Pages peut être exporté vers différents types de fichier, notamment HTML pour l’affichage en ligne, PDF et Microsoft Word. F2644.book Page 7 Thursday, January 13, 2005 5:18 PM8 Préface Bienvenue dans Pages Vue d’ensemble des fonctionnalités de Pages Simple d’utilisation Grâce aux modèles fournis avec Pages, il est facile de créer des documents professionnels. Les espaces réservés pour le texte et les images permettent de personnaliser les documents par simple glisser-déposer. Importez des documents à partir de Microsoft Word et AppleWorks. Vous pouvez également créer vos modèles et les partager avec vos collègues. Insérez des renvois, des tableaux et d’autres éléments mis en forme à la volée. Ajoutez des graphismes par simple glisser-déposer. Insérez plusieurs dispositions de colonne. Utilisez les boutons des barres d’outils pour mettre en forme les pages et le texte à mesure que vous tapez. F2644.book Page 8 Thursday, January 13, 2005 5:18 PMPréface Bienvenue dans Pages 9 Modèles de pages Chaque modèle dispose de blocs de composition Pages vous permettant d’élaborer un document à partir d’une sélection de dispositions de type professionnel. F2644.book Page 9 Thursday, January 13, 2005 5:18 PM10 Préface Bienvenue dans Pages Styles Tapez simplement le texte en utilisant un modèle, et les styles sont appliqués automatiquement aux paragraphes, caractères et listes numérotées ou à puces. Vous pouvez également sélectionner différents styles ou créer vos styles. Utilisez la fenêtre Inspecteur afin de mettre en forme la disposition des documents, du texte et des graphismes pendant votre travail. Utilisez le menu Styles afin d’appliquer une mise en forme de texte cohérente dans tous vos documents. Importez les photos d’iPhoto à l’aide du navigateur de média iLife. F2644.book Page 10 Thursday, January 13, 2005 5:18 PMPréface Bienvenue dans Pages 11 Traitement de texte puissant Pages permet les dispositions à plusieurs colonnes, qui passent d’une page à l’autre lorsque vous tapez, ainsi que les documents déjà mis en forme qui permettent la création de documents exceptionnels. Il est également simple de configurer une table des matières, des pieds de page, des en-têtes et des numéros de page afin de créer des rapports professionnels ou universitaires. Créez une table des matières qui se met à jour automatiquement. Appliquez un style à la table des matières. Créez des listes à puces ou numérotées. F2644.book Page 11 Thursday, January 13, 2005 5:18 PM12 Préface Bienvenue dans Pages Pour en savoir plus Pour tirer le meilleur parti de Pages, consultez les ressources suivantes : Guide de l’utilisateur Le présent guide décrit les fonctionnalités de Pages et explique comment l’utiliser. Pour lire ce guide au format PDF couleurs, choisissez Aide > Manuel de l’utilisateur Pages. Le chapitre 1 de ce guide décrit les outils disponibles dans Pages et le chapitre 2 illustre la procédure pas à pas à suivre pour créer un document. Pour plus d’informations sur chaque étape, reportez-vous aux chapitres 3 à 10. Si vous souhaitez découvrir comment créer vos modèles, lisez le chapitre 11. Aide en ligne Pour afficher l’aide, choisissez Aide > Aide Pages. Vous pouvez parcourir la table des matières afin de rechercher une rubrique spécifique, ou saisir une question dans le champ de recherche afin de trouver une réponse concernant la façon d’effectuer une tâche. Vous pouvez ajouter le bouton Aide à la barre d’outils Pages afin de rendre l’aide de Pages disponible d’un simple clic. Pour en savoir plus sur la personnalisation de la barre d’outils, reportez-vous à la section “La barre d’outils” à la page 23. Remarque : pour effectuer nombre des tâches décrites dans ce guide (et dans l’Aide Pages), vous utilisez des commandes de menu. Les instructions se présentent ainsi : m Choisissez Afficher > Zoom > Taille réelle. Le premier terme après Choisissez est le menu sur lequel vous cliquez ; le terme suivant est l’élément sélectionné dans le menu, comme illustré ci-après. F2644.book Page 12 Thursday, January 13, 2005 5:18 PMPréface Bienvenue dans Pages 13 Les balises d’aide sont également disponibles pour de nombreux éléments à l’écran. Pour afficher une balise d’aide, positionnez le pointeur sur un élément pendant quelques secondes. Visite guidée de Pages Pour obtenir une démonstration à l’écran de ce que vous pouvez faire avec Pages, visualisez la visite guidée. Pour visualiser la visite à l’écran : m Choisissez Aide > Visite iWork, puis suivez les instructions à l’écran. Modèles Pages Pages est fourni avec des modèles qui illustrent les différents styles et dispositions que vous pouvez créer. Tapez directement du texte en utilisant un modèle afin de créer vos documents. Vous pouvez également utiliser les propriétés et éléments de ces modèles afin d’améliorer votre document en copiant et en collant des puces, des styles de graphique et des images d’arrière-plan, ou en utilisant les mêmes dispositions et styles. Pour plus d’informations, reportez-vous à la section “Étape 1 : Sélectionnez un type de document” à la page 30. Fascicule de référence rapide de Pages Le fascicule de référence rapide répertorie les raccourcis clavier de Pages. Vous pouvez également accéder aux raccourcis clavier en choisissant Aide > Raccourcis clavier Pages ou en recherchant “raccourcis clavier” dans l’aide en ligne. Ressources Web Rendez-vous sur www.apple.com/pages afin d’obtenir les mises à jour logicielles et les informations les plus récentes. Vous pouvez également acheter les produits Pages sur le Web. Pour afficher une balise d’aide, positionnez le pointeur sur un élément. F2644.book Page 13 Thursday, January 13, 2005 5:18 PM14 Préface Bienvenue dans Pages Pour en savoir plus sur les produits Pages et obtenir des informations à jour : m Choisissez Aide > Pages sur le Web. Support technique Différentes options de support sont disponibles pour les utilisateurs de Pages. Pour plus d’informations, reportez-vous au guide AppleCare des services logiciels et de support fourni avec la documentation de Pages ou visitez le site www.apple.com/fr/support. F2644.book Page 14 Thursday, January 13, 2005 5:18 PM15 1 1 Présentation de Pages Ce chapitre présente les fenêtres et outils que vous utiliserez dans Pages. Lorsque vous créez un document Pages, vous devez commencer par sélectionner un modèle avec lequel démarrer. Choisissez celui qui correspond le mieux à vos besoins et objectifs. Si vous souhaitez commencer avec un document brut, sans mise en forme prédéfinie, utilisez le modèle Vide. Vous pouvez faire glisser ou positionner des objets sur une page, notamment des graphismes importés, des séquences et du son, ou encore des zones de texte, des graphiques, des tables et des formes que vous créez dans Pages. De nouvelles pages sont ajoutées automatiquement lorsque vous tapez des informations dans un document. Vous pouvez également ajouter des pages avec une mise en forme prédéfinie, avant ou après des pages existantes, en sélectionnant parmi celles qui sont proposées dans chaque modèle. Pour plus d’informations, reportez-vous à la section “Développement du modèle en ajoutant des pages” à la page 31. Dans les modèles Pages, les pages contiennent des espaces réservésde texte et d’image qui illustrent l’aspect du document final. Vous pouvez remplacer le texte des espaces réservés par votre texte. Vous pouvez également remplacer les images des espaces réservés en y faisant glisser une image. Pour plus d’informations sur l’utilisation d’espaces réservés de texte et d’images, reportez-vous aux sections “Étape 2 : Ajoutez du texte” à la page 33 et “Étape 5 : Enregistrez et partagez le document” à la page 47. F2644.book Page 15 Thursday, January 13, 2005 5:18 PM16 Chapitre 1 Présentation de Pages La fenêtre Pages Lorsque vous ouvrez pour la première fois l’application Pages, le sélectionneur de modèles présente différents types de document. Si vous ne souhaitez utiliser aucun des modèles, vous pouvez créer un document vide. Pour commencer avec un document vide, sélectionnez-le et commencez à saisir le texte. La fenêtre Pages affiche le document sur lequel vous travaillez. Vous pouvez faire glisser des fichiers image, des séquences et des fichiers son vers la fenêtre afin de les ajouter au document. Lorsque vous travaillez dans le document, vous pouvez faire un zoom avant ou arrière afin de mieux voir ce que vous faites. Personnalisez la barre d’outils afin d’inclure les outils que vous utilisez le plus souvent. Les espaces réservés du texte indiquent où vous devez saisir le texte. Les espaces réservés d’image indiquent la taille et la position des graphismes dans un modèle de document. Les zones de texte contiennent du texte “flottant” à l’extérieur, au-dessus ou en dessous de la zone de texte principale. La commande Prévisualiser permet de faire un zoom avant ou arrière afin d’agrandir ou de réduire le document à l’écran. F2644.book Page 16 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 17 Pour faire un zoom avant ou arrière sur le document, effectuez l’une des opérations suivantes :  Choisissez Afficher > Zoom > [niveau de zoom].  Cliquez sur la commande Prévisualiser dans le coin inférieur gauche de la fenêtre, puis choisissez un niveau d’agrandissement dans le menu local.  L’option Un vers le haut présente les pages dans un flux linéaire.  L’option Deux vers le haut présente deux pages côte à côte à l’écran.  L’option Ajuster la largeur adapte la largeur du document à celle de la fenêtre. Vous pouvez agrandir la fenêtre Pages afin qu’elle occupe tout l’écran, ou bien la rétrécir.  L’option Ajuster la page adapte la page du document à la taille de la fenêtre de l’écran. F2644.book Page 17 Thursday, January 13, 2005 5:18 PM18 Chapitre 1 Présentation de Pages Mode Disposition En mode disposition, vous pouvez afficher les contours des différentes zones de texte du document, notamment les en-têtes, les pieds de page, les zones de texte fixes, les largeurs de colonne et le corps du document, c’est-à-dire la zone de texte principale du document. Avec le mode disposition activé, les règles et guides d’alignement du document deviennent visibles. Pour passer en mode disposition : m Choisissez Afficher > Afficher la disposition. Lorsque vous tapez du texte dans le corps du document, le texte passe automatiquement à la page suivante. Les autres zones de texte, telles que les en-têtes, les pieds de page et les zones de texte, ne passent pas aux pages suivantes ; elles conservent leur taille et leur largeur. Dans l’exemple suivant, vous constatez que la disposition de la page comporte deux colonnes en haut, deux sauts de disposition, puis trois colonnes, une image en ligne et la zone de pied de page. Pied de page Deux colonnes de texte Une image en ligne Trois colonnes de texte Deux sauts de disposition F2644.book Page 18 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 19 Texte d’espace réservé Le texte d’espace réservé indique où le texte est positionné et comment il est mis en forme dans un modèle. Un nouveau modèle contient du texte d’espace réservé, des images d’espace réservé, des images d’arrière-plan ou d’autres éléments qui représentent les éléments du document terminé. Si vous cliquez sur le texte d’espace réservé, la totalité de la zone de texte est sélectionnée. Lorsque vous commencez la saisie, le texte d’espace réservé disparaît et il est remplacé par ce que vous tapez. Espaces réservés d’image De la même façon que le texte d’espace réservé, les espaces réservés d’image servent à indiquer la taille et la position des graphismes dans un modèle. Si vous cliquez une fois, les poignées de sélection apparaissent. Faites glisser votre image vers l’espace réservé afin de la remplacer. Objets modèle Certains objets apparaissent sur chaque page d’un document, à mesure que la longueur du document augmente. Ces objets sont appelés “objets modèle”. Si vous ne pouvez pas sélectionner un objet dans un modèle, il s’agit probablement d’un objet modèle. Pour en savoir plus, reportez-vous à la section “Ajout d’une image répétée pour l’arrière-plan” à la page 113. Caractères de mise en forme (invisibles) Lorsque vous travaillez dans un document Pages, vous pouvez afficher les marques indiquant les espaces, les sauts de paragraphe, les sauts de section ou d’autres types d’élément invisible, vous permettant ainsi de vérifier la mise en forme du document. Dans Pages, ces marques de mise en forme sont appelées caractères invisibles. F2644.book Page 19 Thursday, January 13, 2005 5:18 PM20 Chapitre 1 Présentation de Pages Pour afficher les caractères invisibles : m Choisissez Afficher > Afficher les caractères invisibles. Le tableau ci-dessous illustre ce que représente chaque caractère de mise en forme. Pour changer la couleur des caractères de mise en forme : m Choisissez Pages > Préférences, cliquez sur la case de couleur Caractères invisibles, puis sélectionnez une couleur. Caractères invisibles Espace Espace insécable (Option + Barre espace) Tab Saut de ligne (Maj + Retour) Saut de paragraphe (Retour) Saut de page Saut de colonne Saut de disposition Saut de section Point d’ancrage (pour les objets en ligne avec l’habillage du texte) F2644.book Page 20 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 21 Règles et guides d’alignement Chaque fois que vous déplacez une image, une forme ou une zone de texte sur la page, les guides d’alignement apparaissent automatiquement afin de vous aider à positionner l’objet précisément à l’endroit où vous le souhaitez. Vous pouvez également utiliser les règles du document ou créer des guides d’alignement statiques qui restent sur la page afin de marquer la position des différents objets lorsque vous réorganisez les éléments sur la page. Pour savoir comment personnaliser le comportement des guides d’alignement, reportez-vous à la section “Guides d’alignement” à la page 39. Vous pouvez également utiliser des règles pour positionner les objets précisément sur une page, et vous pouvez utiliser la règle horizontale pour définir les taquets de tabulation, les marges des pages et les largeurs des colonnes. Pour plus d’informations sur les taquets de tabulation, les marges des pages et les colonnes, reportez-vous aux sections “Définition de taquets de tabulation afin d’aligner le texte” à la page 64, “Définition des marges de page” à la page 102 et “Création de colonnes” à la page 102. Vous pouvez remplacer les unités de mesure qui apparaissent sur les règles par des pouces, des centimètres, des points ou des picas dans les Préférences Pages. Vous pouvez également activer les règles sans les autres éléments de disposition. Pour rendre les règles visibles sans les autres éléments de disposition : m Choisissez Afficher > Afficher les règles, ou appuyez sur Commande + R. Pour changer les valeurs des règles : m Choisissez Pages > Préférences, puis choisissez une unité de mesure dans le menu local Unités de la règle. F2644.book Page 21 Thursday, January 13, 2005 5:18 PM22 Chapitre 1 Présentation de Pages Le tiroir Styles Lorsque vous créez un documen, vous pouvez utiliser un certain style de texte pour chaque titre de chapitre, titre de section, liste à puces et paragraphe de corps du texte. Chaque modèle est fourni avec une bibliothèque de styles prédéfinis parmi lesquels vous pouvez choisir. Le tiroir Styles répertorie et fournit un aperçu de tous les styles de texte du modèle que vous utilisez, ce qui vous permet de les créer, de les personnaliser et de les gérer facilement. Pour ouvrir le tiroir Styles : m Choisissez Afficher > Afficher le tiroir Styles (ou cliquez sur Style dans la barre d’outils et choisissez Afficher le tiroir Styles). Les règles vous aident à définir les marges et les tabulations à l’endroit où vous en avez besoin. Les guides d’alignement vous aident à positionner avec précision les objets sur la page. Dans le cas présent, les guides d’alignement sont bleus. Les icônes bleues sur la règle du haut indiquent les retraits du texte et les tabulations. Faites-les glisser afin demodifier la position du texte. Les rectangles bleus sous les règles indiquent les marges des colonnes. Faites-les glisser afin de modifier la largeur des gouttières des colonnes. F2644.book Page 22 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 23 Outils Pages La barre d’outils La barre d’outils Pages permet d’accéder en un seul clic à nombre des actions que vous utilisez lors de la création de documents dans Pages. Lorsque vous travaillez dans Pages et que vous savez quelles commandes vous utilisez le plus souvent, vous pouvez ajouter, supprimer et réorganiser les boutons de la barre d’outils afin de les adapter à votre style de travail. Le jeu par défaut de boutons de barre d’outils est illustré ci-dessous. Sélectionnez un style de paragraphe afin de l’appliquer aux paragraphes sélectionnés. Sélectionnez un style de caractère afin de l’appliquer au texte sélectionné. Sélectionnez un style de liste afin de l’appliquer au texte du paragraphe sélectionné. Cliquez afin d’afficher et de masquer les styles de liste et de caractère dans le tiroir. Appuyez dessus et choisissez une option afin de créer un style. F2644.book Page 23 Thursday, January 13, 2005 5:18 PM24 Chapitre 1 Présentation de Pages Pour personnaliser la barre d’outils : 1 Choisissez Afficher > Personnaliser la barre d’outils. 2 Pour ajouter un élément à la barre d’outils, faites glisser son icône vers la barre d’outils en haut. 3 Pour supprimer un élément de la barre d’outils, faites-le glisser à l’extérieur de la barre d’outils. 4 Pour réorganiser les éléments dans la barre d’outils, faites-les glisser à un autre endroit sur la barre. 5 Pour réduire les icônes sur la barre d’outils, sélectionnez Petites icônes. 6 Pour n’afficher que les icônes ou le texte, choisissez une option dans le menu local Afficher. Si vous reconfigurez fréquemment la barre d’outils, vous pouvez y ajouter le bouton Personnaliser. Remarque : vous pouvez restaurer le jeu par défaut de boutons de barre d’outils en faisant glisser celui-ci vers la barre d’outils. Pour savoir à quoi sert un bouton de la zone de dialogue Personnaliser, faites-le glisser vers la barre d’outils, puis positionnez le pointeur dessus jusqu’à ce qu’une balise d’aide apparaisse. Ajoutez des zones de texte, des formes, des tableaux et des graphiques. Ouvrez la fenêtre Inspecteur, le navigateur de média, la fenêtre Couleurs et le panneau Police. Créez des dispositions de colonne à la volée. Appliquez les styles au texte et aux listes. Changez la façon dont le texte s’ajuste autour des objets. Ajoutez des pages avec une mise en forme prédéfinie à votre document. F2644.book Page 24 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 25 La fenêtre Inspecteur La fenêtre Inspecteur vous permet d’accéder facilement aux outils de mise en forme pendant que vous travaillez. Vous pouvez mettre en forme la plupart des éléments de votre document à l’aide des dix sous-fenêtres de la fenêtre Inspecteur, notamment la disposition du document, l’apparence du texte, la taille et la position des graphismes, et bien d’autres choses encore. Pour ouvrir une fenêtre Inspecteur : m Choisissez Afficher > Afficher l’Inspecteur (ou cliquez sur Inspecteur dans la barre d’outils). Cliquez sur l’un des boutons du haut afin d’afficher la sous-fenêtre Inspecteur. Par exemple, le fait de cliquer sur le quatrième bouton à partir de la gauche affiche l’Inspecteur de texte. Plusieurs fenêtres de l’Inspecteur peuvent être ouvertes simultanément. Pour ouvrir une autre fenêtre Inspecteur : m Choisissez Afficher > Nouvel Inspecteur (ou appuyez sur la touche Option tout en cliquant sur Inspecteur dans la barre d’outils). Le panneau Police Pages utilise le panneau Police de Mac OS X, vous permettant d’utiliser n’importe quelle police de l’ordinateur dans vos documents. Pour ouvrir le panneau Police : m Choisissez Format > Police > Fenêtre des polices (ou cliquez sur Polices dans la barre d’outils). Utilisez le panneau Police afin de sélectionner les polices, les tailles de police et d’autres fonctionnalités de mise en forme (ombrage, barré, etc.) Pour plus de détails sur l’utilisation du panneau Police et sur la modification de l’aspect du texte, consultez chapitre 3, “Mise en forme de texte et de paragraphes”. Les boutons en haut de la fenêtre Inspecteur ouvrent les dix inspecteurs : Document, Disposition, Habillage, Texte, Graphismes, Mesures, Tableaux, Graphiques, Liens et QuickTime. F2644.book Page 25 Thursday, January 13, 2005 5:18 PM26 Chapitre 1 Présentation de Pages La fenêtre Couleurs Utilisez la fenêtre Couleurs de Mac OS X pour choisir les couleurs du texte, des objets dessinés ou des ombres. Pour ouvrir la fenêtre Couleurs : m Choisissez Afficher > Afficher les couleurs (ou cliquez sur Couleurs dans la barre d’outils). Pour plus d’informations sur l’utilisation de la fenêtre Couleurs pour définir la couleur des lignes, du texte et des formes, reportez-vous au chapitre 7, “Modification de propriétés d’objets”. Raccourcis Vous pouvez utiliser le clavier pour exécuter nombre des commandes et tâches des menus de Pages. Une liste complète de raccourcis clavier est disponible dans l’aide en ligne. Pour afficher la liste des raccourcis clavier : m Dans Pages, choisissez Aide > Raccourcis clavier Pages. De nombreuses commandes sont également disponibles par l’intermédiaire de raccourcis clavier, auxquels vous pouvez accéder directement à partir de l’objet avec lequel vous travaillez. Pour ouvrir un menu contextuel : m Appuyez sur la touche Contrôle en cliquant sur un objet. Les menus contextuels sont particulièrement utiles pour travailler sur les tableaux et les graphiques. Le document Pages Si vous créez un long document ou que l’aspect visuel est un élément important, il peut être utile de réfléchir à l’aspect général du document avant de commencer à travailler. Voici quelques éléments à prendre en considération lors de la création d’un document. F2644.book Page 26 Thursday, January 13, 2005 5:18 PMChapitre 1 Présentation de Pages 27 Disposition et style des documents Pensez à l’aspect général du document, y compris sa disposition et l’utilisation de l’espace. La plupart de ces questions sont traitées dans chapitre 5, “Mise en forme de la disposition et de la table des matières d’un document”.  Quel type de document créez-vous et quel modèle correspond le mieux à la disposition dont vous avez besoin ?  Le document nécessite-t-il une orientation de type paysage ou portrait ? Prenez soin de définir cette option dans la boîte de dialogue Format d’impression avant de commencer. Reportez-vous à la section “Configuration de l’orientation et de la taille des pages” à la page 101.  Si vous concevez une disposition de page unique, les marges du document sontelles définies comme vous le souhaitez ? Reportez-vous à la section “Définition des marges de page” à la page 102.  Le document sera-t-il relié ? Si oui, tenez compte des numéros de page, des marges et des sauts de section sur les pages recto et verso du document. Reportez-vous à la section “Création d’un document avec des pages opposées gauche et droite” à la page 106.  Le document sera-t-il divisé en sections avec différentes dispositions, numérotations des pages, en-têtes et pieds de page ou éléments de conception ? Déterminez dans quels cas vous pouvez utiliser des sauts de disposition et des sauts de section. Reportez-vous à la section “Ajout d’en-têtes et de pieds de page, de numéros de page et de notes de bas de page” à la page 107.  La disposition du document nécessite-t-elle des colonnes ? Reportez-vous à la section “Création de colonnes” à la page 102.  Le document sera-t-il suffisamment long pour nécessiter une table des matières ? Si tel est le cas, prenez soin d’utiliser des styles d’en-tête cohérents dans l’ensemble du document. Reportez-vous à la section “Génération d’une table des matières” à la page 114. Apparence du texte Déterminez de façon globale la façon dont vous souhaitez utiliser le texte dans votre document(façon dont il sera utilisé pour mettre l’accent sur l’organisation du contenu et pour créer un design attrayant). La plupart de ces questions sont traitées dans chapitre 3, “Mise en forme de texte et de paragraphes”. F2644.book Page 27 Thursday, January 13, 2005 5:18 PM28 Chapitre 1 Présentation de Pages  Quelles polices utiliserez-vous dans le document ?  Existe-t-il des styles d’en-tête ou des polices que vous souhaitez utiliser de manière cohérente dans l’ensemble du document ? Consultez chapitre 4, “Utilisation de styles”.  Quelle forme ou image souhaitez-vous utiliser pour les puces ? Quels styles de nombre pour les structures ? Reportez-vous à la section “Création de listes à puces ou numérotées et de structures” à la page 69.  Allez-vous utiliser des légendes, des barres latérales ou d’autre texte mis en surbrillance dans votre document ? Reportez-vous à la section “Création de renvois, de barres latérales et de texte en surbrillance” à la page 72. Utilisation des graphismes et autres médias Déterminez la façon dont vous allez utiliser les éléments graphiques dans votre document, ainsi que la façon dont ils apparaîtront dans le flux du document, ainsi que les types de graphisme que vous pouvez utiliser. Pages fournit des outils que vous pouvez utiliser pour créer des tableaux et des graphiques afin d’organiser et d’afficher les informations. Pour en savoir plus sur la création de tableaux et de graphiques, consultez le chapitre 8, “Création de tableaux” et chapitre 9, “Création de graphiques”. Pour en savoir plus sur les autres utilisations des graphismes, consultez chapitre 6, “Utilisation de graphismes et autres médias”.  Comment les images seront-elles utilisées dans le document ?  Pouvez-vous utiliser des tableaux pour présenter clairement les informations ? Consultez chapitre 8, “Création de tableaux”.  Pouvez-vous utiliser des graphiques pour afficher les données de manière efficace ? Consultez chapitre 9, “Création de graphiques”.  Quel sera le format final du document (page imprimée, HTML, etc.) ? Reportez-vous à la section “Exportation vers d’autres formats de document” à la page 195.  Utiliserez-vous du son ou des séquences dans votre document ? Reportez-vous à la section “Ajout de son et de séquences” à la page 135. F2644.book Page 28 Thursday, January 13, 2005 5:18 PM29 2 2 Création d’un document à l’aide des modèles de Pages Ce chapitre fournit des informations de base sur l’utilisation de Pages. Il explique également comment utiliser les modèles de Pages pour créer facilement vos documents professionnels, avec une mise en page relativement complexe. Avant de commencer à créer un document Pages, déterminez son utilisation. Si votre document est destiné à l’impression, quelle sera la taille du papier ? Quelle sera l’orientation de la page (portrait ou paysage) ? Comment sera-t-il plié ? Cela permet également de déterminer si le document sera long et nécessitera une table des matières et une numérotation des pages. Le fait de connaître ces paramètres vous permettra de choisir le modèle approprié et de le configurer correctement avant de commencer. Importation d’un document Microsoft Word ou AppleWorks Si vous avez déjà créé un document dans Microsoft Word ou dans AppleWorks, vous pouvez l’importer dans Pages et continuer à travailler dessus. Faites simplement glisser l’icône du document Microsoft Word ou AppleWorks vers l’icône de l’application Pages. Vous pouvez également réexporter des documents Pages vers MS Word ou au format PDF, RTF (Rich Text Format) ou HTML. Pour plus d’informations sur l’importation et l’exportation de documents Microsoft Word, reportez-vous à la section “Exportation vers d’autres formats de document” à la page 195. F2644.book Page 29 Thursday, January 13, 2005 5:18 PM30 Chapitre 2 Création d’un document à l’aide des modèles de Pages Étape 1 : Sélectionnez un type de document Pour commencer un nouveau document Pages, double-cliquez sur l’icône Pages. Dans le sélectionneur de modèles, sélectionnez le modèle correspondant le mieux au type de document que vous souhaitez créer. Si vous souhaitez commencer dans un document ne contenant aucun espace réservé pour du texte ou des images, sélectionnez Vide. En utilisant un modèle avec des espaces réservés pour du texte ou des images, vous pouvez facilement créer un document professionnel, tel qu’un rapport scolaire, une lettre commerciale, un journal ou une brochure, sans avoir à concevoir la mise en page. Chaque modèle comprend des styles prédéfinis pour les titres, les en-têtes, les tableaux, les notes de bas de page, les puces et autres fonctionnalités de mise en forme. F2644.book Page 30 Thursday, January 13, 2005 5:18 PMChapitre 2 Création d’un document à l’aide des modèles de Pages 31 Si vous ne voyez pas le sélectionneur de modèles lorsque vous ouvrez Pages pour la première fois, vous pouvez l’afficher en définissant une préférence dans les Préfé- rences Pages. Vous pouvez également configurer Pages afin d’ouvrir automatiquement un document vide ou le modèle de votre choix chaque fois que vous le démarrez. Pour afficher le sélectionneur de modèles ou pour configurer le mod