https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Archiving/Archiving.pdf

Apple-InstrumentsUserGuide.pdf-manuel

Apple-Logic-Pro-9-TDM-Guide-manuel

Apple-macbook_air_users_guide.pdf-manuel

Apple-macbook_air-13-inch_mid-2012-qs_ta.pdf-manuel

Apple-AppStoreMarketingGuidelines-JP.pdf-Japon-manuel

Apple-macbook_pro_retina_qs_ta.pdf-manuel

Apple-ipad_user_guide_tu.pdf-manuel

Apple-ipad_user_guide_th.pdf-manuel

Apple-iphone_user_guide_gr.pdf-manuel

Apple-Nike_Plus_iPod_Sensor_UG_2A.pdf-manuel

Apple-ipad_manual_del_usuario.pdf-manuel

Apple-ipad_uzivatelska_prirucka.pdf-manuel

Apple-ipad_wifi_informations_importantes.pdf-manuel

Apple-Xsan_2_Admin_Guide_v2.3.pdf-manuel

Apple-macbook_pro-13-inch-late-2012-quick_start.pdf-manuel

Apple-CocoaDrawingGuide.pdf-manuel

Apple-Cryptographic-Services-Guide-manuel

Apple-Resource-Programming-Guide-manuel

AppleSafariVisualEffectsProgGuide.pdf-manuel

/Apple-WorkingWithUSB.pdf-manuel

Apple-macbook_pro-retina-mid-2012-important_product_info_f.pdf-manuel

Apple-iOS_Security_May12.pdf-manue

Apple-Mac-Pro-2008-Performance-and-Productivity-for-Creative-Pros

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-KernelProgramming.pdf-manuel

Apple-Core-Data-Model-Versioning-and-Data-Migration-Programming-Guide-manuel

Apple-RED_Workflows_with_Final_Cut_Pro_X.pdf-manuel

Apple-Transitioning-to-ARC-Release-Notes-manuel

Apple-iTunes-Connect-Sales-and-Trends-Guide-manuel

Apple-App-Sandbox-Design-Guide-manuel

Apple-String-Programming-Guide-manuel

Apple-Secure-Coding-Guide-manuel

Apple_AirPort_Networks_Early2009.pdf-manuel

Apple-TimeCapsule_SetupGuide_TA.pdf-manuel

Apple-time_capsule_4th_gen_setup.pdf-manuel

Apple-TimeCapsule_SetupGuide.pdf-manuel

Apple-TimeCapsule_SetupGuide_CH.pdf-Chinois-manuel

Apple-CodeSigningGuide.pdf-manuel

Apple-ViewControllerPGforiOS.pdf-manuel

Apple-KeyValueObserving.pdf-manuel

Apple-mac_mini-late-2012-quick_start.pdf-manuel

Apple-OS-X-Mountain-Lion-Core-Technologies-Overview-June-2012-manuel

Apple-OS-X-Server-Product-Overview-June-2012-manuel

Apple-Apple_Server_Diagnostics_UG_109.pdf-manuel

Apple-PackageMaker_UserGuide.pdf-manuel

Apple-Instrumentos_y_efectos_de_Logic_Studio.pdf-Manuel

Apple-ipod_nano_kayttoopas.pdf-Finlande-Manuel

Apple_ProRes_White_Paper_October_2012.pdf-Manuel

Apple-wp_osx_configuration_profiles.pdf-Manuel

Apple-UsingiTunesProducerFreeBooks.pdf-Manuel

Apple-ipad_manual_do_usuario.pdf-Portugais-Manuel

Apple-Instruments_et_effets_Logic_Studio.pdf-Manuel

Apple-ipod_touch_gebruikershandleiding.pdf-Neerlandais-Manuel

AppleiPod_shuffle_4thgen_Manual_del_usuario.pdf-Espagnol-Manuel

Apple-Premiers-contacts-avec-votre-PowerBook-G4-Manuel

Apple_Composite_AV_Cable.pdf-Manuel

Apple-iPod_shuffle_3rdGen_UG_DK.pdf-Danemark-Manuel

Apple-iPod_classic_160GB_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-VoiceOver_GettingStarted-Manuel

Apple-iPod_touch_2.2_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-Apple_TV_Opstillingsvejledning.pdf-Allemand-Manuel

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-iphone_prirucka_uzivatela.pdf-Manuel

Apple-Aan-de-slag-Neerlandais-Manuel

Apple-airmac_express-80211n-2nd-gen_setup_guide.pdf-Thailande-Manuel

Apple-ipod_nano_benutzerhandbuch.pdf-Allemand-Manuel

Apple-aperture3.4_101.pdf-Manuel

Apple-Pages09_Anvandarhandbok.pdf-Manuel

Apple-nike_plus_ipod_sensor_ug_la.pdf-Mexique-Manuel

Apple-ResEdit-Reference-For-ResEdit02.1-Manuel

Apple-ipad_guide_de_l_utilisateur.pdf-Manuel

Apple-Compressor-4-Benutzerhandbuch-Allemand-Manuel

Apple-AirPort_Networks_Early2009_DK.pdf-Danemark-Manuel

Apple-MacBook_Pro_Mid2007_2.4_2.2GHz_F.pdf-Manuel

Apple-MacBook_13inch_Mid2010_UG_F.pdf-Manuel

Apple-Xserve-RAID-Presentation-technologique-Janvier-2004-Manuel

Apple-MacBook_Pro_15inch_Mid2010_F.pdf-Manuel

Apple-AirPort_Express-opstillingsvejledning.pdf-Danemark-Manuel

Apple-DEiPod_photo_Benutzerhandbuch_DE0190269.pdf-Allemand-Manuel

Apple-Final-Cut-Pro-X-Logic-Effects-Reference-Manuel

Apple-iPod_touch_2.1_Brugerhandbog.pdf-Danemark-Manuel

Apple-Remote-Desktop-Administratorhandbuch-Version-3.1-Allemand-Manuel

Apple-Qmaster-4-User-Manual-Manuel

Apple-Server_Administration_v10.5.pdf-Manuel

Apple-ipod_classic_features_guide.pdf-Manuel

Apple-Lecteur-Optique-Manuel

Apple-Carte-AirPort-Manuel

Apple-iPhone_Finger_Tips_Guide.pdf-Anglais-Manuel

Apple-Couvercle-Manuel

Apple-battery.cube.pdf-Manuel

Apple-Boitier-de-l-ordinateur-Manuel

Apple-Pile-Interne-Manuel

Apple-atacable.pdf-Manuel

Apple-videocard.pdf-Manuel

Apple-Guide_de_configuration_de_l_Airport_Express_5.1.pdf-Manuel

Apple-iMac_Mid2010_UG_F.pdf-Manuel

Apple-MacBook_13inch_Mid2009_F.pdf-Manuel

Apple-MacBook_Mid2007_UserGuide.F.pdf-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Administration_de_QuickTime_Streaming_et_Broadcasting_10.5.pdf-Manuel

Apple-Opstillingsvejledning_til_TimeCapsule.pdf-Danemark-Manuel

Apple-iPod_nano_5th_gen_Benutzerhandbuch.pdf-Manuel

Apple-iOS_Business.pdf-Manuel

Apple-AirPort_Extreme_Installationshandbuch.pdf-Manuel

Apple-Final_Cut_Express_4_Installation_de_votre_logiciel.pdf-Manuel

Apple-MacBook_Pro_15inch_2.53GHz_Mid2009.pdf-Manuel

Apple-Network_Services.pdf-Manuel

Apple-Aperture_Performing_Adjustments_f.pdf-Manuel

Apple-Supplement_au_guide_Premiers_contacts.pdf-Manuel

Apple-Administration_des_images_systeme_et_de_la_mise_a_jour_de_logiciels_10.5.pdf-Manuel

Apple-Mac_OSX_Server_v10.6_Premiers_contacts.pdf-Francais-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Mise_a_niveau_et_migration_v10.5.pdf-Manue

Apple-MacBookPro_Late_2007_2.4_2.2GHz_F.pdf-Manuel

Apple-Mac_mini_Late2009_SL_Server_F.pdf-Manuel

Apple-Mac_OS_X_Server_10.5_Premiers_contacts.pdf-Manuel

Apple-iPod_touch_2.0_Guide_de_l_utilisateur_CA.pdf-Manuel

Apple-MacBook_Pro_17inch_Mid2010_F.pdf-Manuel

Apple-Comment_demarrer_Leopard.pdf-Manuel

Apple-iPod_2ndGen_USB_Power_Adapter-FR.pdf-Manuel

Apple-Feuille_de_operations_10.4.pdf-Manuel

Apple-Time_Capsule_Installationshandbuch.pdf-Allemand-Manuel

Apple-F034-2262AXerve-grappe.pdf-Manuel

Apple-Mac_Pro_Early2009_4707_UG_F

Apple-imacg5_17inch_Power_Supply

Apple-Logic_Studio_Installieren_Ihrer_Software_Retail

Apple-IntroductionXserve1.0.1

Apple-Aperture_Getting_Started_d.pdf-Allemand

Apple-getting_started_with_passbook

Apple-iPod_mini_2nd_Gen_UserGuide.pdf-Anglais

Apple-Deploiement-d-iPhone-et-d-iPad-Reseaux-prives-virtuels

Apple-F034-2262AXerve-grappe

Apple-Mac_OS_X_Server_Glossaire_10.5

Apple-FRLogic_Pro_7_Guide_TDM

Apple-iphone_bluetooth_headset_userguide

Apple-Administration_des_services_reseau_10.5

Apple-imacg5_17inch_harddrive

Apple-iPod_nano_4th_gen_Manuale_utente

Apple-iBook-G4-Getting-Started

Apple-XsanGettingStarted

Apple-Mac_mini_UG-Early2006

Apple-Guide_des_fonctionnalites_de_l_iPod_classic

Apple-Guide_de_configuration_d_Xsan_2

Apple-MacBook_Late2006_UsersGuide

Apple-sur-Fnac.com

Apple-Mac_mini_Mid2010_User_Guide_F.pdf-Francais

Apple-PowerBookG3UserManual.PDF.Anglais

Apple-Installation_de_votre_logiciel_Logic_Studio_Retail

Apple-Pages-Guide-de-l-utilisateur

Apple-MacBook_Pro_13inch_Mid2009.pdf.Anglais

Apple-MacBook_Pro_15inch_Mid2009

Apple-Installation_de_votre_logiciel_Logic_Studio_Upgrade

Apple-FRLogic_Pro_7_Guide_TDM

Apple-airportextreme_802.11n_userguide

Apple-iPod_shuffle_3rdGen_UG

Apple-iPod_classic_160GB_User_Guide

Apple-iPod_nano_5th_gen_UserGuide

Apple-ipod_touch_features_guide

Apple-Wireless_Mighty_Mouse_UG

Apple-Advanced-Memory-Management-Programming-Guide

Apple-iOS-App-Programming-Guide

Apple-Concurrency-Programming-Guide

Apple-MainStage-2-User-Manual-Anglais

Apple-iMacG3_2002MultilingualUserGuide

Apple-iBookG3_DualUSBUserGuideMultilingual.PDF.Anglais

Apple-imacG5_20inch_AirPort

Apple-Guide_de_l_utilisateur_de_Mac_Pro_Early_2008

Apple-Installation_de_votre_logiciel_Logic_Express_8

Apple-iMac_Guide_de_l_utilisateur_Mid2007

Apple-imacg5_20inch_OpticalDrive

Apple-FCP6_Formats_de_diffusion_et_formats_HD

Apple-prise_en_charge_des_surfaces_de_controle_logic_pro_8

Apple-Aperture_Quick_Reference_f

Apple-Shake_4_User_Manual

Apple-aluminumAppleKeyboard_wireless2007_UserGuide

Apple-ipod_shuffle_features_guide

Apple-Color-User-Manual

Apple-XsanGettingStarted

Apple-Migration_10.4_2e_Ed

Apple-MacBook_Air_SuperDrive

Apple-MacBook_Late2007-f

ApplePowerMacG5_(Early_2005)_UserGuide

Apple-iSightUserGuide

Apple-MacBook_Pro_Early_2008_Guide_de_l_utilisateur

Apple-Nouvelles-fonctionnalites-aperture-1.5

Apple-premiers_contacts_2e_ed_10.4.pdf-Mac-OS-X-Server

Apple-premiers_contacts_2e_ed_10.4

Apple-eMac_2005UserGuide

Apple-imacg5_20inch_Inverter

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

Archives and Serializations Programming GuideContents Introduction 5 Organization of This Document 5 Object Graphs 6 Archives 8 Serializations 8 Archives 9 Coders 9 Root Object 10 Conditional Objects 10 Keyed Archives 11 Naming Values 11 Return Values for Missing Keys 11 Type Coercions 12 Class Versioning 12 Root Objects 12 Delegates 12 Non-Keyed Coding Methods 12 Creating and Extracting Archives 13 Creating an Archive 13 Decoding an Archive 14 Encoding and Decoding Objects 16 Encoding an Object 16 Decoding an Object 17 Performance Considerations 18 Making Substitutions During Coding 18 Restricting Coder Support 19 Encoding and Decoding C Data Types 21 Pointers 21 Arrays of Simple Types 21 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 2Arrays of Objects 22 Structures and Bit Fields 22 More Complex Data Types 23 Forward and Backward Compatibility for Keyed Archives 24 Benefits of Keyed Archiving 24 General Tips on Maintaining Compatibility 25 Adding New Values to Keys 25 Adding New Keys 25 Removing or Retiring Keys 26 Changing Bit Sizes of Values 27 Subclassing NSCoder 29 Serializing Property Lists 31 Document Revision History 33 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 3Figures Object Graphs 6 Figure 1 Partial object graph of an application 7 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 4Archives and serializations are two ways in which you can create architecture-independent byte streams of hierarchical data. Byte streams can then be written to a file or transmitted to another process, perhaps over a network. When the byte stream is decoded, the hierarchy is regenerated. Archives provide a detailed record of a collection of interrelated objects and values. Serializationsrecord only the simple hierarchy of property-list values. You should read this document to learn how to create and extract archived representations of object graphs. Organization of This Document This programming topic contains the following articles: ● “Object Graphs” (page 6) introduces the concept of an object graph and discusses the two techniques for turning objects into byte streams: archives and serializations. ● “Archives” (page 9) describes the different types of archive and archiver classes. ● “Creating and Extracting Archives” (page 13) describes how to create and extract an archive. ● “Encoding and Decoding Objects” (page 16) describes how to implement the methods that allow an object to be encoded in and decoded from archives. ● “Encoding and Decoding C Data Types” (page 21) describes how to encode and decode C data types that do not have convenience methods defined in the archive classes. ● “Forward and Backward Compatibility for Keyed Archives” (page 24) provides some tips on how to make your classes more compatible with previous and future versions of your classes in keyed archives. ● “Subclassing NSCoder” (page 29) provides some tips on how to create your own coder classes. ● “Serializing Property Lists” (page 31) describes how to create and read serialized representations of a property list. 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 5 IntroductionObject-oriented applications contain complex webs of interrelated objects. Objects are linked to each other by one object either owning or containing another object or holding a reference to another object to which it sends messages. This web of objects is called an object graph. Even with very few objects, an application’s object graph becomes very entangled with circular references and multiple links to individual objects. Figure 1 (page 7) shows an incomplete object graph for a simple Cocoa application in OS X. (Many more connections exist than are shown in this figure.) Consider the window’s view hierarchy portion of the object graph. This hierarchy is described by each view containing a list of all of its 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 6 Object Graphsimmediate subviews. However, views also have links to each other to describe the responder chain and the keyboard focus loop. Views also link to other objects in the application for target-action messages, contextual menus, and much more. Figure 1 Partial object graph of an application There are situations where you may want to convert an object graph, usually just a section of the full object graph in the application, into a form that can be saved to a file or transmitted to another process or machine and then reconstructed. Nib files and property lists are two examples in OS X where object graphs are saved to a file. Nib files are archivesthat represent the complex relationships within a user interface,such as a window’s view hierarchy. Property lists are serializations that store the simple hierarchical relationship of basic value objects. More details on archives and serializations, and how you can use them, are described in the following sections. Object Graphs 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 7Archives An archive can store an arbitrarily complex object graph. The archive preserves the identity of every object in the graph and all the relationships it has with all the other objects in the graph. When unarchived, the rebuilt object graph should, with few exceptions, be an exact copy of the original object graph. Your application can use an archive as the storage medium of your data model. Instead of designing (and maintaining) a special file format for your data, you can leverage Cocoa’s archiving infrastructure and store the objects directly into an archive. To support archiving, an object must adopt the NSCoding protocol, which consists of two methods. One method encodes the object’s important instance variables into the archive and the other decodes and restores the instance variables from the archive. All of the Foundation value objects objects (NSString, NSArray, NSNumber, and so on) and most of the Application Kit and UIKit user interface objects adopt NSCoding and can be put into an archive. Each class’s reference document identifies whether they adopt NSCoding. Serializations Serializations store a simple hierarchy of value objects, such as dictionaries, arrays, strings, and binary data. The serialization only preservesthe values of the objects and their position in the hierarchy. Multiple references to the same value object might result in multiple objects when deserialized. The mutability of the objects is not maintained. Property lists are examples of serializations. Application attributes (the Info.plist file) and user preferences are stored as property lists. Object Graphs Archives 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 8Archives provide a means to convert objects and values into an architecture-independent stream of bytes that preserves the identity of and the relationships between the objects and values. Cocoa archives can hold Objective-C objects, scalars, arrays, structures, and strings. They do not hold types whose implementation varies across platforms, such as union, void *, function pointers, and long chains of pointers. Archives store object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream. Exceptions to this rule are described in “Making Substitutions During Coding” (page 18). Coders Objects are written to and read from archives with coder objects. Coder objects are instances of concrete subclasses of the abstract class NSCoder. NSCoder declares an extensive interface for taking the information stored in an object and putting it into another format suitable for writing to a file, transmitting between processes or across a network, or performing other types of data exchange. NSCoder also declaresthe interface for reversing the process, taking the information stored in a byte stream and converting it back into an object. Subclasses implement the appropriate portions of this interface to support a specific archiving format. Coder objectsread and write objects by sending one of two messages to the objectsto be encoded or decoded. A codersends encodeWithCoder: to objects when creating an archive and initWithCoder: when reading an archive. These messages are defined by the NSCoding protocol. Only objects whose class conforms to the NSCoding protocol can be written to an archive. (The reference for each Cocoa class indicates whether the class adopts the NSCoding protocol.) When an object receives one of these messages, the object sends messages back to the coder to tell the coder which objects or values, usually instance variables, to read or write next. When encoding objects, the coder records in the archive the class identity of the objects (or type of Objective-C values) and their position in the hierarchy. Object graphs, such as the one shown in Figure 1 (page 7), pose two problems for a coder: redundancy and constraint. To solve these problems, NSCoder introduces the concepts of root objects and conditional objects, which are described in the following sections. 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 9 ArchivesRoot Object An object graph is not necessarily a simple tree structure. Two objects can contain references to each other, for example, creating a cycle. If a coder follows every link and blindly encodes each object it encounters, this circular reference will generate an infinite loop in the coder. Also, a single object can be referenced by several other objects. The coder must be able to recognize and handle multiple and circular references so that it does not encode more than one copy of each object, but still regenerate all the references when decoding. To solve this problem, NSCoder introduces the concept of a root object. The root object is the starting point of an object graph. To encode an object graph, you invoke the NSCoder method encodeRootObject:, passing in the first object to encode. Every object encoded within the context of this invocation is tracked. If the coder is asked to encode an object more than once, the coder encodes a reference to the first encoding instead of encoding the object again. NSCoder does not implement support for root objects; NSCoder’s implementation of encodeRootObject: simply encodes the object by invoking encodeObject:. It is the responsibility of its concrete subclasses to keep track of multiple references to objects, thus preserving the structure of any object graphs. Conditional Objects Another problem presented by object graphs is that it is not always appropriate to archive the entire graph. For example, when you encode an NSView object, the view can have many links to other objects: subviews, superviews, formatters, targets, windows, menus, and so on. If a view encoded all of its references to these objects, the entire application would get pulled in. Some objects are more important than others, though. A view’s subviews always should be archived, but not necessarily its superview. In this case, the superview is considered an extraneous part of the graph; a view can exist without its superview, but not its subviews. A view, however, needsto keep a reference to itssuperview, if the superview is also being encoded in the archive. To solve this dilemma, NSCoder introduces the concept of a conditional object. A conditional object is an object that should be encoded only if it is being encoded unconditionally elsewhere in the object graph. A conditional object is encoded by invoking encodeConditionalObject:forKey:. If all requests to encode an object are made with these conditional methods, the object is not encoded and references to it decode to nil. If the object is encoded elsewhere, all the conditional references decode to the single encoded object. Typically, conditional objects are used to encode weak references to objects. NSCoder does not implement support for conditional objects; NSCoder’s implementation of encodeConditionalObject:forKey: simply encodes the object by invoking encodeObject:forKey:. It is the responsibility of its concrete subclasses to keep track of conditional objects and to not encode objects unless they are needed. Archives Coders 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 10Keyed Archives Keyed archives are created by NSKeyedArchiver objects and decoded by NSKeyedUnarchiver objects. Keyed archives differ from sequential archives in that every value encoded in a keyed archive is given a name, or key. When decoding the archive, the values can be requested by name, allowing the values to be requested in any order or not at all. Thisfreedom enables greater flexibility for making your classesforward and backward compatible. The following sections describe how to use keyed archives. Naming Values Values that an object encodes to a keyed archive can be individually named with an arbitrary string. Archives are hierarchical with each object defining a separate name space for its encoded values, similar to the object’s instance variables. Therefore, keys must be unique only within the scope of the current object being encoded. The keys used by object A to encode its instance variables do not conflict with the keys used by object B, even if A and B are instances of the same class. Within a single object, however, the keys used by a subclass can conflict with keys used in its superclasses. Public classes, such as those in a framework, which can be subclassed, should add a prefix to the name string to avoid collisions with keys that may be used now or in the future by the subclasses of the class. A reasonable prefix is the full name of the class. Cocoa classes use the prefix “NS” in their keys, the same as the API prefix, and carefully makes sure that there are no collisions in the class hierarchy. Another possibility is to use the same string as the bundle identifier for the framework. You should avoid using “$” as a prefix for your keys. The keyed archiver and unarchiver use keys prefixed with “$” for internal values. Although they test for and mangle user-defined keysthat have a “$” prefix, this overhead slows down archiving performance. Subclasses also need to be somewhat aware of the prefix used by superclasses to avoid accidental collisions on key names. Subclasses of Cocoa classes should avoid unintentionally starting their key names with “NS”. For example, don’t name a key “NSString search options”. Return Values for Missing Keys While decoding, if you request a keyed value that does not exist, the unarchiver returns a default value based on the return type of the decode method you invoked. The default values are the equivalent of zero for each data type: nil for objects, NO for booleans, 0.0 for reals, NSZeroSize for sizes, and so on. If you need to detect the absence of a keyed value, use the NSKeyedUnarchiver instance method containsValueForKey:, which returns NO if the supplied key is not present. For performance reasons, you should avoid explicitly testing for keys when the default values are sufficient. Archives Keyed Archives 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 11Type Coercions NSKeyedUnarchiver supportslimited type coercion. A value encoded as any type of integer, be it a standard int or an explicit 32-bit or 64-bit integer, can be decoded using any of the integer decode methods. Likewise, a value encoded as a float or double can be decoded as either a float or a double value. When decoding a double value as a float, though, the decoded value loses precision. If an encoded value is too large to fit within the coerced decoded type, the decoding method throws an NSRangeException. Further, when trying to coerce a value to an incompatible type, such as decoding an int as a float, the decoding method throws an NSInvalidUnarchiveOperationException. Class Versioning Versioning of encoded data is not handled through class versioning with keyed coding as it is in sequential archives. In fact, no automatic versioning is done for a class; this allows a class to at least get a look at the encoded values without the unarchiver deciding on its own that the versions fatally mismatch. A class is free to decide to encode some type of version information with its other values if it wishes, and this information can be of any type or quantity. Root Objects The encodeObject: and encodeObject:forKey: methods are able to track multiple references to objects in multiple object graphs. As many object graphs or values as desired may be encoded at the top level of a keyed archive. NSKeyedArchiver implements archiveRootObject:toFile: and archivedDataWithRootObject: to produce archives with a single object graph. These archives, however, have to be unarchived using the NSKeyedUnarchiver methods unarchiveObjectWithFile: and unarchiveObjectWithData:. Delegates NSKeyedArchiver and NSKeyedUnarchiver objects can have delegate objects. The delegates are notified as each object is encoded or decoded. You can use the delegatesto perform substitutions, replacing one object for another, if desired. Non-Keyed Coding Methods Keyed archivers do not have to provide names for every value encoded in the archive. The NSKeyedArchiver and NSKeyedUnarchiver classesimplement the non-keyed encoding and decoding methodsthat they inherit from NSCoder. Use of the non-keyed methods within keyed coding is discouraged. Archives Keyed Archives 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 12This chapter describes how to create and extract an archive. To understand how to make your custom objects support archival, see “Encoding and Decoding Objects” (page 16). Creating an Archive The easiest way to create an archive of an object graph is to invoke a single class method—either archiveRootObject:toFile: or archivedDataWithRootObject:—on the archiver class. These convenience methods create a temporary archiver object that encodes a single object graph; you need do no more. The following code fragment, for example, archives a custom object called aPerson directly to a file. Person *aPerson = <#Get a Person#>; NSString *archivePath = ; BOOL success = [NSKeyedArchiver archiveRootObject:aPerson toFile:archivePath]; However, if you want to customize the archiving process(for example, by substituting certain classesfor others), you must instead create an instance of the archiver yourself, configure it as desired, and send it an encode message explicitly. NSCoder itself defines no particular method for creating a coder; this typically varies with the subclass. NSKeyedArchiver defines initForWritingWithMutableData:. Once you have the configured coder object, to encode an object or data item, use any encode method for an NSKeyedArchiver coder. When finished encoding, you must invoke finishEncoding before accessing the archive data. The following sample code fragment archives a custom object called aPerson similar to the above code, but allows for customization. Person *aPerson = <#Get a Person#>; NSString *archivePath = ; NSMutableData *data = [NSMutableData data]; NSKeyedArchiver *archiver = [[NSKeyedArchiver alloc] initForWritingWithMutableData:data]; [archiver encodeObject:aPerson forKey:ASCPersonKey]; [archiver finishEncoding]; 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 13 Creating and Extracting ArchivesNSURL *archiveURL = ; BOOL result = [data writeToURL:archiveURL atomically:YES]; It is possible to create an archive that does not contain any objects. To archive other data types, invoke one of the type-specific methods, such as encodeInteger:forKey: or encodeDouble:forKey: directly for each data item to be archived, instead of using encodeRootObject:. Decoding an Archive The easiest way to decode an archive of an object is to invoke a single class method—either unarchiveObjectWithFile: or unarchiveObjectWithData:—on the unarchiver class. These convenience methods create a temporary unarchiver object that decodes and returns a single object graph; you need do no more. NSKeyedUnarchiver requires that the object graph in the archive was encoded with one of NSKeyedArchiver’s convenience class methods, such as archiveRootObject:toFile:. The following code fragment, for example, unarchives a custom object called aPerson directly from a file. NSString *archivePath = ; Person *aPerson = [NSKeyedUnarchiver unarchiveObjectWithFile:archivePath]; However, if you want to customize the unarchiving process (for example, by substituting certain classes for others), you typically create an instance of the unarchiver class yourself, configure it as desired, and send it a decodemessage explicitly. NSCoder itself defines no particular method for creating a coder; this typically varies with the subclass. NSKeyedUnarchiver defines initForReadingWithData:. Once you have the configured decoder object, to decode an object or data item, use the decodeObjectForKey:method.When finished decoding a keyed archive, you should invoke finishDecoding before releasing the unarchiver. The following sample code fragment unarchives a custom object called myMap similar to the above code sample, but allows for customization. NSURL *archiveURL = ; NSData *data = [NSData dataWithContentsOfURL:archiveURL]; NSKeyedUnarchiver *unarchiver = [[NSKeyedUnarchiver alloc] initForReadingWithData:data]; // Customize the unarchiver. Person *aPerson = [unarchiver decodeObjectForKey:ASCPersonKey]; Creating and Extracting Archives Decoding an Archive 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 14[unarchiver finishDecoding]; You can create an archive that does not contain any objects. To unarchive non-object data types, simply use the decode... method (such as decodeIntForKey: or decodeDoubleForKey:) corresponding to the original encode... method for each data item to be unarchived. To customize the unarchiving processfor an archive previously created using archiveRootObject:toFile:, use decodeObjectForKey: and the key “root” to identify the root object in the archive: id object = [unarchiver decodeObjectForKey:@"root"]; Creating and Extracting Archives Decoding an Archive 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 15To support encoding and decoding of instances, a class must adopt the NSCoding protocol and implement its methods. This protocol declares two methods that are sent to the objects being encoded or decoded. In keeping with object-oriented design principles, an object being encoded or decoded is responsible for encoding and decoding its state. A coder instructs the object to do so by invoking encodeWithCoder: or initWithCoder:. The encodeWithCoder: method instructsthe object to encode itsstate with the provided coder; an object can receive this method any number of times. The initWithCoder: message instructs the object to initialize itself from data in the provided coder; as such, it replaces any other initialization method and is sent only once per object. Encoding an Object When an object receives an encodeWithCoder: message, it should encode all of its vital state (often represented by its properties or instance variables), after forwarding the message to itssuperclassif itssuperclass also conforms to the NSCoding protocol. An object does not have to encode all of its state. Some values may not be important to reestablish and others may be derivable from related state upon decoding. Other state should be encoded only under certain conditions (for example, with encodeConditionalObject:, as described in “Conditional Objects” (page 10)). You use the coding methods, such as encodeObject:forKey:, to encode id’s, scalars, C arrays, structures, strings, and pointers to any of these types. See the NSKeyedArchiver class specification for a list of methods. For example, suppose you created a Person class that has properties for first name, last name, and height; you might implement encodeWithCoder: as follows - (void)encodeWithCoder:(NSCoder *)coder { [coder encodeObject:self.firstName forKey:ASCPersonFirstName]; [coder encodeObject:self.lastName forKey:ASCPersonLastName]; [coder encodeFloat:self.height forKey:ASCPersonHeight]; } 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 16 Encoding and Decoding ObjectsThis example assumes that the superclass of Person does not adopt the NSCoding protocol. If the superclass of your class does adopt NSCoding, you should invoke the superclass’s encodeWithCoder: method before invoking any of the other encoding methods: - (void)encodeWithCoder:(NSCoder *)coder { [super encodeWithCoder:coder]; // Implementation continues. The @encode() compiler directive generates an Objective-C type code from a type expression that can be used as the first argument of encodeValueOfObjCType:at:. See “Type Encodings” in The Objective-C Programming Language for more information. Decoding an Object In the implementation of an initWithCoder: method, the objectshould first invoke itssuperclass’s designated initializer to initialize inherited state, and then itshould decode and initialize itsstate. The keys can be decoded in any order. Person’s implementation of initWithCoder: might look like this: - (id)initWithCoder:(NSCoder *)coder { self = [super init]; if (self) { _firstName = [coder decodeObjectForKey:ASCPersonFirstName]; _lastName = [coder decodeObjectForKey:ASCPersonLastName]; _height = [coder decodeFloatForKey:ASCPersonHeight]; } return self; } If the superclass adoptsthe NSCoding protocol, you start by assigning of the return value of initWithCoder: to self: - (id)initWithCoder:(NSCoder *)coder { self = [super initWithCoder:coder]; if (self) { // Implementation continues. Encoding and Decoding Objects Decoding an Object 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 17This is done in the subclass because the superclass, in its implementation of initWithCoder:, may decide to return an object other than itself. Performance Considerations The less you encode for an object, the less you have to decode, and both writing and reading archives becomes faster. Stop writing out items which are no longer pertinent to the class (but which you may have had to continue writing under non-keyed coding). Encoding and decoding booleans is faster and cheaper than encoding and decoding individual 1-bit bit fields as integers. However, encoding many bit fields into a single integer value can be cheaper than encoding them individually, but that can also complicate compatibility efforts later (see “Structures and Bit Fields” (page 22)). Don’t read keys you don’t need. You aren’t required to read all the information from the archive for a particular object, as you were with non-keyed coding, and it is much cheaper not to. However, unread data still contributes to the size of an archive, so stop writing it out, too, if you don’t need to read it. It is faster to just decode a value for a key than to check if it exists and then decode it if it exists. Invoke containsValueForKey: only when you need to distinguish the default return value (due to non-existence) from a real value that happens to be the same as the default. It is typically more valuable for decoding to be fast than for encoding to be fast. If there is some trade-off you can make that improves decoding performance at the cost of lower encoding performance, the trade-off is usually reasonable to make. Avoid using “$” as a prefix for your keys. The keyed archiver and unarchiver use keys prefixed with “$” for internal values. Although they test for and mangle user-defined keysthat have a “$” prefix, this overhead makes archiving slower. Making Substitutions During Coding During encoding or decoding, a coder object invokes methods that allow the object being coded to substitute a replacement class or instance for itself. This allows archives to be shared among implementations with different class hierarchies or simply different versions of a class. Class clusters, for example, take advantage of this feature. This feature also allows classes that should maintain unique instances to enforce this policy on decoding. For example, there need only be a single NSFont instance for a given typeface and size. Substitution methods are declared by NSObject, and come in two flavors: generic and specialized. These are the generic methods: Encoding and Decoding Objects Performance Considerations 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 18Method Typical use Allows an object, before being encoded, to substitute a class other than its own. For example, the private subclasses of a class cluster substitute the name of their public superclass when being archived. classForCoder Allows an object, before being encoded, to substitute another instance in its place. replacementObjectForCoder: Allows an object, after being decoded, to substitute another object for itself. For example, an object that represents a font might, upon being decoded, return an existing object having the same font description as itself. In this way, redundant objects can be eliminated. awakeAfterUsingCoder: The specialized substitutionmethods are analogousto classForCoder and replacementObjectForCoder:, but they are designed for (and invoked by) a specific, concrete codersubclass. For example, classForArchiver and replacementObjectForPortCoder: are used by NSArchiver and NSPortCoder, respectively. By implementing these specialized methods, your class can base its coding behavior on the specific coder class being used. For more information on these methods, see their method descriptions in the NSObject class specification. In addition to the methods just discussed, NSKeyedArchiver and NSKeyedUnarchiver allow a delegate object to perform a final substitution before encoding and after decoding objects. The delegate for an NSKeyedArchiver object can implement archiver:willEncodeObject: and the delegate for an NSKeyedUnarchiver object can implement unarchiver:didDecodeObject: to perform the substitutions. Restricting Coder Support In some cases, a class may implement the NSCoding protocol, but not support one or more coder types. For example, the classes NSDistantObject, NSInvocation, NSPort, and theirsubclasses adopt NSCoding only for use by NSPortCoder within the distributed objects system; they cannot be encoded into an archive. In these cases, a class can test whether the coder is of a particular type and raise an exception if it isn’t supported. If the restriction is just to limit a class to sequential or keyed archives, you can send the message allowsKeyedCoding to the coder; otherwise, you can test the class identity of the coder as shown in the following sample. - (void)encodeWithCoder:(NSCoder *)coder { if ([coder isKindOfClass:[NSKeyedArchiver class]]) { // encode object } Encoding and Decoding Objects Restricting Coder Support 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 19else { [NSException raise:NSInvalidArchiveOperationException format:@"Only supports NSKeyedArchiver coders"]; } } In other situations, a class may inherit NSCoding from a superclass, but the subclass may not want to support coding. For example, NSWindow inherits NSCoding from NSResponder, but it does not support coding. In these cases, the class should override the initWithCoder: and encodeWithCoder: methods so that they raise exceptions if they are ever invoked. Encoding and Decoding Objects Restricting Coder Support 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 20NSKeyedArchiver and NSKeyedUnarchiver provide a number of methods for handling non-object data. Integers can be encoded with encodeInt:forKey:, encodeInt32:forKey:, or encodeInt64:forKey:. Likewise, real values can be encoded with encodeFloat:forKey: or encodeDouble:forKey:. Other methods encode booleans and byte arrays. The classes also provide several convenience methodsfor handling special data types used in Cocoa, such as NSPoint, NSSize, and NSRect. NSKeyedArchiver and NSKeyedUnarchiver do not provide methodsfor encoding and decoding aggregate types, such as structures, arrays, and bit fields. The following sections provide suggestions on how to handle unsupported data types. Pointers You can’t encode a pointer and get back something useful at decode time. You have to encode the information to which the pointer is pointing. This is true in non-keyed coding as well. Pointers to C strings (char *) are a special case because they can be treated as a byte array which can be encoded using encodeBytes:length:forKey:. You can also wrap C strings with a temporary NSString object and archive the string. Reverse the process when decoding. Be sure to keep in mind the character set encoding of the string when creating the NSString object, and chose an appropriate creation method. Arrays of Simple Types If you are encoding an array of bytes, you can just use the provided methods to do so. For other arithmetic types, create an NSData object with the array. Note that in this case, dealing with platform endianness issues is your responsibility. Platform endianness can be handled in two general ways. The first technique is to convert the elements of the array (or rather, a temporary copy of the array) into a canonical endianness, either big or little, one at a time with the functions discussed in “Swapping Bytes” in Universal Binary Programming Guidelines, Second Edition (see also “Byte Ordering” in Foundation Functions Reference ) and give that result to the NSData as the buffer. (Or, you can write the bytes directly with encodeBytes:length:forKey:.) At decode time, you have to reverse the process, converting from the big or little endian canonical form to the current host representation. The other technique is to use the array as-is 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 21 Encoding and Decoding C Data Typesand record in a separate keyed value (perhaps a boolean) which endianness the host was when the archive was created. During decoding, read the endian key and compare it to the endianness of the current host and swap the values only if different. Alternatively, you can archive each array element separately as their native type, perhaps by using key names inspired by the array syntax, like “theArray[0]”, “theArray[1]”, and so on. This is not a terribly efficient technique, but you can ignore endian issues. Arrays of Objects The simplest thing to do for a C array of objects is to temporarily wrap the array in an NSArray object with initWithObjects:count:, encode the array object, then get rid of the object. Because objects contain other information that has to be encoded, you can’t just embed the array of pointers in an NSData object; each object must be individually archived. During decoding, use getObjects: on the retrieved array to get the objects back out into an allocated C array (of the correct size). Structures and Bit Fields The best technique for archiving a structure or a collection of bit fields is to archive the fields independently and choose the appropriate type of encoding/decoding method for each. The key names can be composed from the structure field names if you wish, like “theStruct.order”, “theStruct.flags”, and so on. This creates a slight dependency on the names of the fields in the source code, which over time may get renamed, but the archiving keys cannot change if you want to maintain compatibility. You should not wrap a structure with an NSData object and archive that. If the structure contains object or pointer fields, the data object isn’t going to archive them correctly. You also create a dependence on how the compiler decidesto lay out the structure, which can change between versions of the compiler and may depend on other factors. A compiler is not constrained to organize a structure just as you’ve specified it in the source code—there may be arbitrary internal and invisible padding bytes between fieldsin the structure, for example, and the amount of these can change without notice and on different platforms. In addition, any fields that are multiple bytes in width aren’t going to get treated correctly with respect to endianness issues. You will cause yourself all sorts of compatibility trouble. Likewise, bit fields should never be encoded by reading the raw bits of several bit fields as an integer and encoding the integer. (Encoding an integer that you construct manually from several bit fields, using bit shifts and OR operations, however, avoids most of the pitfalls that follow.) Although there are some requirements on compilersspecified in the C standard, a compilerstill hassome freedom in how things are actually organized and which bits it chooses to store where, and what bits it may choose not to use (inter-field padding bits). The Encoding and Decoding C Data Types Arrays of Objects 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 22location of those bits could differ between compilers or change as a particular compiler evolves. On top of this, you also have to deal with endianness issues. The order of the bits within an integer could be different for the machine that encodes the archive and the machine that decodes it. Finally, by encoding the raw bits, you constrain future development of your class to use the same bit field sizes as the oldest archive you need to support. Otherwise, you have to be able to parse the old bitstream and initialize the new bitstream yourself, handling the compiler and platform issues appropriately. Asisthe case for an object’sinstance variablesin general, it is not necessary to archive every field of a structure or bit field. You only need to encode and decode the fields required to preserve a structure’s state. Fields that are calculated or otherwise derived by other means should not be archived. More Complex Data Types More complex data types, such as arrays of aggregates, can generally be handled using the techniques for simple data types and combining them with custom logic for your particular application. Encoding and Decoding C Data Types More Complex Data Types 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 23Keyed archiving gives you plenty of flexibility to make your classes forward and backward compatible. The following sections describe some general tips on how you can implement compatibility and then some guidelines for maintaining compatibility with specific types of changes. Benefits of Keyed Archiving The principal benefit of keyed coding is that it makes it easier to be backward and forward compatible. The ability to read keyed values from the archive in any order, ignore keys you don’t need, and add new keys without disrupting older versions of the class is the foundation for implementing backward and forward compatibility with keyed coding. For maximum compatibility, you need to be able to do the following: ● Read archives created by older versions of your class. ● Create archives that can be read by older versions of your class. ● Read archives created by future versions of your class. ● Create archives that can be read by future versions of your class. The first two items provide full backward compatibility: the old and current versions of the class can read each others archives. To achieve this capability, it is essential that you know what values were encoded by all the previous versions of your class that you need to support as well as how previous versions decode themselves. If you don’t have this information, you may be able to deduce some things from existing archives and the existing implementations of the NSCoding methods. The last two items provide full forward compatibility: the current and future versions of the class can read each others archives. To achieve this capability, you need to anticipate the types of changes you may make in the future and code your current NSCoding methods appropriately. 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 24 Forward and Backward Compatibility for Keyed ArchivesGeneral Tips on Maintaining Compatibility To easily identify the version of the class being decoded, you can add some version info to the archive. This can be any type of information you want, not just an integer (such asthe class version) asit was with non-keyed coding. You may just encode a “version” integer or string with some key or in some rare cases you may want a dictionary object full of goodies. Of course, adding some version information today presumes that you also have a plan for dealing with different versions in your initWithCoder: today. If not, changing the version info in the future will not do the present version of the class any good. Remember to keep your NSCoding implementations synchronized. Whenever you change how you write out an objects’ state in the class’s encodeWithCoder: method, you need to update your initWithCoder: method to understand the new keys. Because information in a keyed archive can be encoded and decoded in any order, the two NSCoding methods don’t need to process keys in the same sequence. Use whatever sequences is most convenient for each method. Adding New Values to Keys Some of the values a class encodes may have a particular set of possible values. For example, a button can be a checkbox, a radio button, a push button, and so on. In the future, your set of values may expand; you may create a button that has another type of behavior and need to have a new value for the button’s type. To prepare for this change in future archives, you can test whether the decoded value for the key is one of the allowed values. If it is not, you can assign a default value to it. Then, the future version of the class can just assign the new value to the old key and the current class will behave reasonably well. If you are making this change and a previous version did not make allowancesfor the change or the allowances are insufficient or unacceptable, you probably have to create a whole new key for the new state (see “Adding New Keys” (page 25)) and make the old key obsolete (see “Removing or Retiring Keys” (page 26)). Adding New Keys As a class evolves, you may need to add information to the class to describe its new features. For example, a button has a label and a style. Later you may allow the button to have a custom color. You need to create a new key in the archive to hold the color data. Because you do not need to decode every value in a keyed archive, new keyed values are harmless to old versions of the class, as long as it is OK for them not to be initialized with such state. You can safely add as many new keys as necessary without affecting older versions; old versions automatically ignore those values. Forward and Backward Compatibility for Keyed Archives General Tips on Maintaining Compatibility 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 25When decoding older archives, you must be prepared to handle the absence of the new key. If appropriate, you can still attempt to decode the new key and just accept the default value for the missing key (nil, 0, NSZeroPoint, and so on). The coder’s default value may not be valid for every key, however. In that case, you should detect the default value and substitute a more reasonable default value of your own. If the new key is a replacement for an older key, the appropriate substitution should come from the old key, which may require mapping the old value to one of the allowed values for the new key. If you must distinguish between the default value for a missing key and the same value for an existing key, use the NSCoder method containsValueForKey:. If the new key is replacing an older key, you need to properly handle the obsolete key (see “Removing or Retiring Keys” (page 26)). Removing or Retiring Keys As a class evolves, some information may become obsolete or replaced by a newer implementation. Because you do not need to decode every value in a keyed archive, when decoding older archives, you can just ignore keys you no longer need. The decoding will be slightly faster, too. When decoding future archives, you must be prepared to handle missing keys. If appropriate, you can simply accept the default decode value for the missing keys (nil, 0, NSZeroPoint, and so on). If the coder’s default value is not valid for a particular key, you should detect the default value and substitute a more reasonable default value of your own. If you must distinguish between the default value for a missing key and the same value for an existing key, use the NSCoder method containsValueForKey:. In this way, you give yourself the flexibility to stop encoding certain values later. In cases where you need to abandon an old key for a newer one, but an old class cannot handle a missing key appropriately, you need to keep writing some value for the old key as well as the newer key. The value should be something the old class can understand and should probably be as close a simulation of the new state as possible. For example, consider a class that originally came in “vanilla”, “chocolate”, and “butter pecan” flavors and now has additional “double chocolate” and “caramel” flavors. To encode a value for the old key, you can map “double chocolate” to the value for “chocolate” in the old class, but you may have to map “caramel” to “vanilla”. Of course, you write the entire new set of values with the new key and your initWithCoder: method should prefer to use the new key if available. In some cases it may also be useful to build in fallback handling. Fallback handling is useful when one of a set of possible keys for a value is encoded. The set of supported keys may evolve over time, with newer keys being preferred in future versions of your class. Fallback handling defines a fundamental key that must be readable Forward and Backward Compatibility for Keyed Archives Removing or Retiring Keys 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 26forever, but is used only when no other recognized keys are present. Future versions can then write a value using both a new key and the fallback key. Older versions of the class will not see the new key, but can still read the value with the fallback key. Consider as an example a class named Image that representsimages. (This example does not necessarily reflect the actual behavior of any image class, like NSImage.) Suppose the Image class is able to encode its instances as an URL, JPEG, or GIF, depending on whichever is most convenient for the particular instance. An encoded Image object, therefore, contains only one of the following keys: @"URL", @"JPEG", @"GIF". The initWithCoder: method checks for the keys in the order @"URL", @"JPEG", @"GIF", and initializes itself with the first representation that it finds. In the future it might be that none of these are easy or convenient to archive (for example, taking whatever data the Image instance does have and converting it to JPEG might be fairly expensive). An example of fallback handling in this case would be to allow for an additional key (or group of keys), like @"rawdata", that is understood and used by Image’s initWithCoder: method if none of the other keys for this value (the image data) are present. The value of the @"rawdata" key might be defined, for example, to be an NSData object containing 32-bit RGBA pixels. There might also be auxiliary keys like @"pixelshigh" and @"pixelswide" that initWithCoder: would look for to get a minimal set of information needed to produce an Image instance from the archived information. In the future, the encoding process for an Image might write out the convenient information, whatever that is at that time, and would also have to write out the @"rawdata" and other keys to allow old decoders to read the object. Changing Bit Sizes of Values In some situations, you may have code and archives that you use on 32- and 64-bit platforms (for example, you might have iOS and OS X versions of an application that share data via iCloud). In these cases, you need to take care to ensure that integer values are treated correctly. Encoding what is a 32-bit integer as a 64-bit integer isn’t necessarily the best solution. The extra high-order zero bits you’re giving to the value as you give it to the archiver are wasted. On the other hand, it isn’t harmful either, and is easy to implement. The generic encodeInt:forKey: and decodeIntForKey: methods read and write whatever the native int size is on the computer. On a 64-bit computer, int may be 64 bits wide (or it might not be; the C language is flexible in this regard). Therefore, it’s possible that values requiring more than 32 bits to represent may be written by an encodeInt:forKey: method. If such an archive is transported to a 32-bit computer, the decodeIntForKey: method may be unable to represent that integer in the int return value, and have to throw an NSRangeException. Forward and Backward Compatibility for Keyed Archives Changing Bit Sizes of Values 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 27Whether or not it is useful to attempt to handle this by always decoding such integers as 64-bit is debatable. If the integer is a “count” of something, for example, it may be physically impossible to have more than 2^32 of whatever it is on a 32-bit computer, so further attempting to unarchive the file is probably a waste of time, and an exception is reasonable. Alternatively, you might want to either catch the exception or perform your own bounds checking on a 64-bit decoded value and return nil from initWithCoder:. However, the caller of the decodeObjectForKey: method that is unpacking an instance of your class may not like the nil any more than the exception, and might end up raising an exception of its own that is less intelligible as to the cause of the problem than the range exception might have been. Forward and Backward Compatibility for Keyed Archives Changing Bit Sizes of Values 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 28NSCoder’s interface is quite general and extensive, declaring methods to encode and decode objects and values with and without keys. Concrete subclasses are not required to properly implement all of NSCoder’s methods and may explicitly restrict themselves to certain types of operations. For example, NSArchiver does not implement the decode... methods, and NSUnarchiver does not implement the encode... methods. In addition, neither class implements the keyed coding methods for encoding and decoding keyed archives. Invoking a decode method on NSArchiver or an encode method on NSUnarchiver raises an NSInvalidArgumentException. If you define a subclass of NSCoder that does not support keyed coding, at a minimum your subclass must override the following methods: encodeValueOfObjCType:at: decodeValueOfObjCType:at: encodeDataObject: decodeDataObject versionForClassName: If your subclass supports keyed coding, you must override the above methods as well as the allowsKeyedCoding method (to return YES) and all of the keyed coding methods defined by NSCoder. In both cases, if you are creating separate classes for encoding and decoding, you do not need to override the encode methods in the decoder class nor the decode methods in the encoder class. Note that encodeObject: and decodeObject are not among the basic methods. They are defined abstractly to invoke encodeValueOfObjCType:at: or decodeValueOfObjCType:at: with an Objective-C type code of “@”. Your implementations of the latter two methods must handle this case, invoking the object’s encodeWithCoder: or initWithCoder:method and sending the propersubstitutionmessages(as described in “Making Substitutions During Coding” (page 18)) to the object before encoding it and after decoding it. Your subclass may override other methods to provide specialized handling for certain situations. In particular, you can implement any of the following methods: encodeRootObject: encodeConditionalObject: encodeBycopyObject: 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 29 Subclassing NSCoderencodeByrefObject: See the individual method descriptions for more information on their required behavior. The default NSCoder implementations of these methods just invoke encodeObject:. If you override encodeConditionalObject: to support conditional objects(see “Conditional Objects” (page 10)), be aware that the first unconditional encoding may occur after any number of conditional encoding requests,so your coder will not know which conditional objectsto encode until all the other objects have been encoded. With objects, the object being coded is fully responsible for coding itself. However, a few classes hand this responsibility back to the coder object, either for performance reasons or because proper support depends on more information than the object itself has. The notable classes in Foundation that do this are NSData and NSPort. NSData’s low-level nature makes optimization important. For this reason, an NSData object always asksits coder to handle its contents directly using the encodeDataObject: and decodeDataObject methods when it receives the encodeWithCoder: and initWithCoder: messages. Similarly, an NSPort object asks its coder to handle it using the encodePortObject: and decodePortObject methods (which only NSPortCoder implements). This is because an NSPort represents information kept in the operating system itself, which requires special handling for transmission to another process. These special cases don’t affect users of coder objects,since the redirection is handled by the classesthemselves in their NSCoding protocol methods. An implementor of a concrete coder subclass, however, must implement the appropriate custom methods to encode and decode NSData and (if relevant) NSPort objects itself. Subclassing NSCoder 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 30Serialization converts Objective-C types to and from an architecture-independent byte stream. In contrast to archiving, basic serialization does not record the data type of the values nor the relationships between them; only the values themselves are recorded. It is your responsibility to deserialize the data in the proper order. Property list serialization does not preserve the full class identity of the objects, only its general kind—a dictionary, an array, and so on. As a result, if a property list is serialized and then deserialized, the objects in the resulting property list might not be of the same class asthe objectsin the original property list. In particular, when a property list isserialized, the mutability of the container objects(NSDictionary and NSArray objects) is not preserved. When deserializing, though, you can choose to have all container objects created mutable or immutable. Serialization also does not track the presence of objects referenced multiple times. Each reference to an object within the property list is serialized separately, resulting in multiple instances when deserialized. Because serialization does not preserve classinformation or mutability, nor handles multiple references, coding (as implemented by NSCoder and its subclasses) is the preferred way to make object graphs persistent. The NSPropertyListSerialization class provides the serialization methods that convert property list objects to and from either an XML or an optimized binary format. The NSPropertyListSerialization class object provides the interface to the serialization process; you don’t create instances of NSPropertyListSerialization. The following code sample shows how to serialize a simple property list into an XML format. NSDictionary *propertyList= @{ @"FirstNameKey" : @"Edmund", @"LastNameKey" : @"Blackadder" }; NSString *errorStr; NSData *dataRep = [NSPropertyListSerialization dataFromPropertyList:propertyList format:NSPropertyListXMLFormat_v1_0 errorDescription:&errorStr]; if (!dataRep) { // Handle error } 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 31 Serializing Property ListsThe following code sample converts the XML data from above back into an object graph. NSDictionary *propertyList = [NSPropertyListSerialization propertyListFromData:dataRep mutabilityOption:NSPropertyListImmutable format:NULL errorDescription:&errorStr]; if (!propertyList) { // Handle error } Serializing Property Lists 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 32This table describes the changes to Archives and Serializations Programming Guide . Date Notes 2012-07-17 Removed legacy information about non-keyed archiving. Added note for customizing unarchival of archives created using archiveRootObject:toFile:. 2010-09-01 2009-08-18 Added links to related concepts. 2009-02-04 Replaced instances of "/tmp" with NSTemporaryDirectory(). 2007-10-31 Added discussion of how to distinguish old archives from keyed archives. 2007-07-09 Removed pointers to deprecated reference. 2006-11-07 Corrected inaccurate description of code sample in "Encoding an Object." Clarified preference of keyed over non-keyed archiving. Changed title from "Archives and Serializations." 2006-02-07 Changed use of cString, which will eventually be deprecated, to UTF8String in sample code in “Serializing Property Lists” (page 31). 2003-04-02 2002-11-12 Revision history was added to existing topic. 2012-07-17 | © 2002, 2012 Apple Inc. All Rights Reserved. 33 Document Revision HistoryApple Inc. © 2002, 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, Cocoa, Mac, Objective-C, and OS X are trademarks of Apple Inc., registered in the U.S. and other countries. iCloud is a service mark of Apple Inc., registered in the U.S. and other countries. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. iTunes Extras and iTunes LP Test Guide v1.1  2012-7-6 Apple Inc.© 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist iTunes Content Developers to manage and deliver content for the iTunes Store. Every efort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 2QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states 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. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 3Table of Contents Revision History............................................................................................................5 Overview ..........................................................................................................................6 Functionality Testing on Mac and PC ..................................................................7 Testing for Apple TV...................................................................................................8 Creating XID for Testing ...........................................................................................9 Testing Checklist..........................................................................................................9 iTunes LP ...................................................................................................................................9 iTunes Extras.........................................................................................................................10 General Items........................................................................................................................11 iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 4Revision History July 06, 2012—Version 1.1. Major revision, checklist included. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 5Overview This document helps you to test your iTunes LP or iTunes Extras on a Mac, PC, or Apple TV. You can use the included testing checklist to ensure that your packages work correctly on all the platforms. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 6Functionality Testing on Mac and PC To test the functionality of iTunes LP or iTunes Extras content, you can use Safari on a Mac or PC. To open the iTunes LP or iTunes Extras content in Safari, drag the index.html file to the Safari icon. To navigate you iTunes LP or iTunes Extras, you can use the pointer or the keyboard arrows. If you are using the templates available on apple.com/itunes/lp-and-extras, you will hear a sound whenever you use the arrow keys or reach the end of a navigation pane. Note that core assets must be viewed in iTunes (for example, movies, albums, and tracks) and will not work in Safari. To view the core assets in iTunes, follow the step below: 1. Before launching iTunes, you must set it up for debugging and identifier editing (XIDs) by using the following commands in Terminal (OS X) or the command line (PC). Edit HTML: To allow right click “Inspect Element” in iTunes LP or iTunes Extras, use the following command: Mac defaults write com.apple.iTunes WebKitDeveloperExtras -bool true Windows iTunes.exe /setPrefInt WebKitDeveloperExtras 1 To undo, use the following command: Mac defaults write com.apple.iTunes WebKitDeveloperExtras -bool false Windows iTunes.exe /setPrefInt WebKitDeveloperExtras 0 Asset XID editing: To change the “Grouping” field in Get Info to “XID” use the following command: Mac defaults write com.apple.iTunes booklet-authoring-mode 1 Windows iTunes.exe /setPrefInt booklet-authoring-mode 1 To undo, use the following command: Mac defaults write com.apple.iTunes booklet-authoring-mode 0 iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 7Windows iTunes.exe /setPrefInt booklet-authoring-mode 0 2. If you do not have an existing XID for your content, you can create a test XID. The test XID must be added to the core asset. To add it,use the Get Info pane and add the XID to the Grouping field. You can remove the existing XID “TEST:uuid:F97CCBE5-EBD4-4A30-A13A-6B5052EE6A04” and replace it with your own. To verify chapter functionality of your core asset, use the test core movie Movie Chapter Test File available on apple.com/itunes/lp-andextras. 3. Use the XID from the core asset in the data.js file. 4. Create an iTunes LP (itlp) or iTunes Extras (ite) package by adding “.itlp” or “.ite” to the folder containing the index.html file. If you are using a Mac, this will convert the folder into a package file. If you want to edit the package content at a later point, right click on the package and choose Open Package Contents from the menu. Drag the package, including the core asset or test core movie, to the iTunes icon. 5. Make sure that the background audio is included in the “audio” folder and that video bonus content is included in the “videos” folder. To function properly, audio files must be in the MPEG-4 Audio (.m4a) format and videos in the MPEG-4 Video (.m4v) format. Testing for Apple TV To test the functionality of your iTunes LP or iTunes Extras on Apple TV: 1. To ensure that the iTunes LP and iTunes Extras content works on Apple TV, include the following section in the manifest.xml file: 2. Core assets for iTunes LP or iTunes Extras must have the same “Album Name” in the Get Info pane. Note that this is for testing only. 3. Core assets, iTunes LP, or iTunes Extras content must be synced to Apple TV via iTunes. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 8Creating XID for Testing If you are testing iTunes LP or iTunes Extras prior to submitting to iTunes, and have no XID for your content, you can generate a temporary XID. The temporary XID consists of a universally unique identifier (UUID) with a TEST prefix. In OS X, use the “uuidgen” command to generate a temporary XID. For example: $ uuidgen 94C2C4BC-E57B-4CA6-B7C9-AA9EE8A63298 Create your XID by adding “TEST:uuid:” to your UUID. For example: TEST:uuid:94C2C4BC-E57B-4CA6-B7C9-AA9EE8A63298 For more information on XIDs, see the Development Guide on apple.com/ itunes/lp-and-extras. Testing Checklist Once you have created iTunes LP or iTunes Extras content, you can test it on a Mac, PC, or Apple TV. Make sure you test all of the items listed below. iTunes LP Field Notes Home The correct background audio plays when iTunes LP loads. The audio must not loop, unless specifically set to loop. Animations function correctly and do not stutter. Play Album Play Album starts audio playback from track one and starts the visualizer, if available. The visualizer, if available, displays properly and cycles through each scene correctly. The Home button disappears after a few seconds without pointer movement. The Apple TV visualizer push is conditional. If no visualizer is used on Apple TV, it is disabled. Playlists are only created once per session. Track List All Play Song links play the correct audio track. Home button returns to main menu. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 9Field Notes Song and Lyrics Pages All Play buttons play the correct audio track. Scroll bars work correctly, for example sliders are flush with top and bottom of scrollable area when slider is at top or bottom. Song and Lyrics Pages Lyrics are visible and not cut of by other page elements. Song and Lyrics Pages Previous and Next song button go to the correct song page. Home button returns to main menu. Photos Scroll bars, left, and right buttons work correctly. Home button returns to main menu. If slideshow or zoomed view is used, the Home button disappears after a few seconds without pointer movement. Videos Play button plays the correct video. Video thumbnail images show the correct videos. iTunes displays the correct video title and artist name. Scroll bars work correctly. Home button returns to main menu. Discography iTunes links go to correct store pages. Scroll bars work correctly. Home button returns to main menu. Liner Notes and Credits All text is visible and is not cut of by other page elements. Liner Notes and Credits Scroll bars work correctly. Home button returns to main menu. iTunes Extras Field Notes Play Movie Play button starts movie playback from beginning or last position. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 10Field Notes Chapters Resume button plays feature movie from last position. Each chapter starts at the correct location of the feature movie. The chapter thumbnail image is the movie's current chapter. The correct number of chapters and unique chapter thumbnail images are displayed. The chapter slider, if used, works correctly. The left arrow must not appear in the first chapter. The right arrow must not appear in the last chapter. Home button returns to main menu. Features Resume button plays feature movie from last position. Video thumbnail images show the correct videos. iTunes displays the correct video title and artist name. Scroll bars work correctly. Home button returns to main menu. More Resume button plays feature movie from last position. iTunes Store links go to the correct store pages. Links go to the correct webpages. Home button returns to main menu. General Items Field Notes General All buttons appear correctly on Apple TV. Unused code is removed (for example, “playchapters” from photos pages). Ensure appData includes the VAM playback strings. iTunes Extras and iTunes LP Test v1.1 July 6, 2012 CONFIDENTIAL 11 Text System User Interface Layer Programming GuideContents Introduction to Text System User Interface Layer 4 Who Should Read This Document 4 Organization of This Document 4 See Also 5 The User-Interface Layer: NSTextView Class 6 Creating an NSTextView Object 8 Creating an NSTextView Object Programmatically 12 Putting an NSTextView Object in an NSScrollView 14 Setting Up the Scroll View 14 Setting Up the Text View 15 Assembling the Pieces 16 Setting Up a Horizontal Scroll Bar 16 Using Multiple NSTextViews 17 Plain and Rich Text Objects 18 Setting Text Attributes 20 Kerning 20 Ligatures 21 Setting Text Margins 22 Document Revision History 24 Index 25 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 2Figures, Tables, and Listings Creating an NSTextView Object 8 Figure 1 Cocoa-Text palette 8 Figure 2 Edit menu 9 Figure 3 Text menu 9 Figure 4 Font panel 10 Creating an NSTextView Object Programmatically 12 Listing 1 Creating an NSTextView object programmatically 12 Putting an NSTextView Object in an NSScrollView 14 Listing 1 Setting up the scroll view 14 Listing 2 Setting up the text view 15 Listing 3 Assembling the pieces 16 Listing 4 Setting up a horizontal scroll bar 16 Plain and Rich Text Objects 18 Table 1 RTF control words recognized by all text objects 18 Setting Text Margins 22 Figure 1 Text margins and insets 22 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 3Text System User Interface Layer describes the high-level user interface to the Cocoa text system through the NSTextView class. Who Should Read This Document You should read this document if your application needs to present a user interface to the full capabilities of the text system, that is, if your users need to edit substantial amounts of text. To understand this material you should have a general understanding of Cocoa programming conventions, and you should have read Cocoa Text Architecture Guide . Organization of This Document This document contains the following articles: ● "The User-Interface Layer: NSTextView Class" (page 6) describes the capabilities and features of the NSTextView class, through which most applications interact with the text system. ● "Creating an NSTextView Object" (page 8) explains how to instantiate an NSTextView object using Interface Builder. ● "Creating an NSTextView Programmatically" (page 12) explains how to create an NSTextView object in code and cause it to create its supporting web of text-handling objects. ● "Putting an NSTextView Object in an NSScrollView" (page 14) shows how to programmatically configure an NSTextView object with scroll bars. ● "Using Multiple NSTextViews" (page 17) describes the attributes held in common by multiple text views configured to share a single layout manager. ● "Plain and Rich Text Objects" (page 18) explains the difference between plain text and rich text and lists the RTF control words that any text object recognizes. ● "Setting Text Attributes" (page 20) discussestext attributes and the action methods you can use to control them programmatically. 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 4 Introduction to Text System User Interface Layer● "Setting Text Margins" (page 22) describes the values, maintained by various text system objects, that affect the apparent margins surrounding text on a printed page or display. See Also For more information, refer to the following documents: ● Cocoa Text Architecture Guide provides an overview of the Cocoa text system. It also explains how the text system supports entering and modifying text and attributesthrough user interaction with the user interface layer. ● Text System Storage Layer Overview describes the facilities that the Cocoa text system uses to store the text and geometric shape information used for text layout. Introduction to Text System User Interface Layer See Also 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 5The vast majority of applications interact with the text system through one class: NSTextView. An NSTextView object provides a rich set of text-handling features and can: ● Display text in various fonts, colors, and paragraph styles ● Display images ● Read text and images from (and write them to) disk or the pasteboard ● Let users control text attributes such as font, superscripting and subscripting, kerning, and the use of ligatures ● Cooperate with other views to enable scrolling and display of the ruler ● Cooperate with the Font panel (Fonts window) and Spelling panel ● Support various key bindings, such as those used in Emacs The interface that this class declares (and inherits from its superclass NSText) lets you programmatically: ● Control the size of the area in which text is displayed ● Control the editability and selectability of the text ● Select and act on portions of the text NSTextView objects are used throughout the Cocoa user interface to provide standard text input and editing features. An NSTextView object is a convenient package of the most generally useful text-handling features. If the features of the NSTextView class satisfy your application’s requirements and you need more programmatic control over the characters and attributes that make up the text, you’ll have to learn something about the object that stores this data, NSTextStorage. One of the design goals of NSTextView is to provide a comprehensive set of text-handling features so that you should rarely need to create a subclass. In its standard incarnation, NSTextView creates the requisite group of objects that support the text system—NSTextContainer, NSLayoutManager, and NSTextStorage objects. Here are the major features that NSTextView adds to those of NSText: 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 6 The User-Interface Layer: NSTextView Class● Rulers. NSTextView works with the NSRulerView classto let users control paragraph formatting, in addition to using commands in the Text menu provided by Interface Builder, which is available as a submenu of the Format menu as well as a menu in the menu bar. ● Inputmanagement and key binding. Certain key combinations are bound to specific NSTextView methods so that the user can, for example, move the insertion point without using the mouse. ● Marked text attributes. NSTextView defines a set of text attributes that support special display characteristics during input management. Marked text attributes affect only visual aspects of text—color, underline, and so on—they don’t include any attributes that would change the layout of text. ● File and graphic attachments. The extended textsystem provides programmatic accessto text attachments as instances of NSTextAttachment, through the NSTextView and NSTextStorage classes. ● Delegate messages and notifications. NSTextView adds several delegate messages and notifications to those used by NSText. The delegate and observers of an NSTextView can receive any of the messages or notifications declared by either class. The User-Interface Layer: NSTextView Class 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 7The easiest way to use the text system is through Interface Builder. Interface Builder’s Cocoa-Text palette, shown in Figure 1, supplies a specially configured NSScrollView object that contains an NSTextView object as its document view. This NSTextView is configured to work with the NSScrollView and other user-interface controls such as a ruler, the Font menu, the Edit menu, and so on. Figure 1 Cocoa-Text palette Using Interface Builder’s Info window (also called the inspector) you can specify, among other things, whether the contained NSTextView allows multiple fonts and embedded graphics. 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 8 Creating an NSTextView ObjectMuchmore of NSTextView’sfunctionality is accessible throughmenu commands. Interface Builder’s Cocoa-Menus palette offers the ready-made Edit menu that contains text-editing commands shown in Figure 2. Figure 2 Edit menu The Cocoa-Menus palette also has the Text menu, shown in Figure 3, which contains paragraph style controls and provides user access to the document’s ruler. Figure 3 Text menu Creating an NSTextView Object 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 9The Cocoa-Menus palette also has the system Font panel (or Fonts window) shown in Figure 4. Figure 4 Font panel By default, most of the commands in these menus operate on the first responder, that is, the view within the key window that the user has selected for input. (See the reference documentation for NSResponder, NSView, and NSWindow for more information on the first responder.) In practice, the first responder is the object that’s displaying the selection, a drawing object in the case of a graphical selection or an NSTextView in the case of a textual selection. By adding these menus to your application, you can offer the user access to many powerful text-editing features. NSTextViews cooperate with the Servicesfacility through the Servicesmenu, also available fromthe Cocoa-Menus palette. By simply adding the Services menu item to your application’s main menu, the NSTextViews in your application can access services provided by other applications. For example, if the user selects a word within an NSTextView and chooses the Mail > Send Selection service, the NSTextView passes its selected text to the Mail application which places the text in a new message. Interface Builder offers these direct ways of accessing the features of the text system. You can also configure your own menu items or other controls within Interface Builder to send messages to an NSTextView object. For example, you can make an NSTextView output its text for printing or faxing by sending it a print: or fax: message. One way to do thisisto drag a menu item from the Cocoa-Menus palette into your application’s File menu and hook it up to an NSTextView (either through the first responder or by direct connection). By specifying that the item send a print: message to its target, the NSTextView’s contents can be printed or faxed when the application is running. Creating an NSTextView Object 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 10Interface Builder also offers other objects—of the NSTextField and NSForm classes—that make use of NSTextView objects for their text-editing facilities. In fact, all NSTextField and NSForm objects within the same window share the same NSTextView object (known as the field editor), thus reducing the memory demands of an application. If your application requires standalone or grouped text fields that support editing (and all the other facilities provided by the NSTextView class), these are the classes to use. Using the Info window (inspector), you can set many text-related attributes of these controls. For example, you can specify whether the text in a text field is selectable, editable, scrollable, and so on. The Info window also lets you set the text alignment and background and foreground colors. Creating an NSTextView Object 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 11At times, you may need to assemble the text system programmatically. You can do this in either of two ways: by creating an NSTextView object and letting it create its network of supporting objects or by building the network of objects yourself. In most cases, you’ll find it sufficient to create an NSTextView object and let it create the underlying network of text-handling objects, as discussed in this article. If your application has complex text-layout requirements, you’ll have to create the network yourself;see “Creating Text System Objects” in Cocoa Text Architecture Guide for information. You create an NSTextView object programmatically in the usual way: by sending the alloc and init... messages. You can also create an NSTextView object using either of these methods: ● initWithFrame:textContainer: (the designated initializer) ● initWithFrame: The method that takes one argument, initWithFrame:, is the simplest way to obtain an NSTextView object—it creates all the other components of the text system for you. If you use the method that takes two arguments, initWithFrame:textContainer:, you must create the other components yourself. Listing 1 shows how you can create an NSTextView object, given an NSWindow object represented here by aWindow. Listing 1 Creating an NSTextView object programmatically /* determine the size for the NSTextView */ NSRect cFrame =[[aWindow contentView] frame]; /* create the NSTextView and add it to the window */ NSTextView *theTextView = [[NSTextView alloc] initWithFrame:cFrame]; [aWindow setContentView:theTextView]; [aWindow makeKeyAndOrderFront:nil]; [aWindow makeFirstResponder:theTextView]; 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 12 Creating an NSTextView Object ProgrammaticallyThis code determines the size for the text view’s frame rectangle by asking aWindow for the size of its content view. The NSTextView is then created and made the content view of aWindow using setContentView:. Finally, the makeKeyAndOrderFront: and makeFirstResponder: messages display the window and cause the text view to prepare to accept keyboard input. The initWithFrame: method not only initializes the receiving NSTextView object, it causes the object to create and interconnect the other components of the text system. This is a convenience that frees you from having to create and interconnect them yourself. Creating an NSTextView Object Programmatically 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 13A scrolling text view is commonly required in applications, and Interface Builder provides an NSTextView configured just for this purpose. However, at times you may need to create a scrolling text view programmatically. The process consists of three steps: setting up the NSScrollView, setting up the NSTextView, and assembling the pieces. This article describes these steps in terms of a typical text view configured with a vertical scroll bar only, then shows alternate statements used to configure a horizontal scroll bar. Setting Up the Scroll View Assuming an object has the variable theWindow that represents the window where the scrolling view is displayed, you can set up the NSScrollView using the code in Listing 1. Listing 1 Setting up the scroll view NSScrollView *scrollview = [[NSScrollView alloc] initWithFrame:[[theWindow contentView] frame]]; NSSize contentSize = [scrollview contentSize]; [scrollview setBorderType:NSNoBorder]; [scrollview setHasVerticalScroller:YES]; [scrollview setHasHorizontalScroller:NO]; [scrollview setAutoresizingMask:NSViewWidthSizable | NSViewHeightSizable]; Note that the code creates an NSScrollView that completely coversthe content area of the window it’s displayed in. It also specifies a vertical scroll bar but no horizontal scroll bar, since this scrolling text view wraps text within the horizontal extent of the NSTextView, but letstext flow beyond the vertical extent of the NSTextView. To use a horizontal scroll bar, you must configure the scroll view and text view slightly differently, as described in "Setting Up a Horizontal Scroll Bar" (page 16). 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 14 Putting an NSTextView Object in an NSScrollViewFinally, the code sets how the NSScrollView reacts when the window it’s displayed in changes size. Turning on the NSViewWidthSizable and NSViewHeightSizable bits of its resizing mask ensures that the NSScrollView grows and shrinks to match the window’s dimensions. Setting Up the Text View The nextstep isto create and configure an NSTextView to fit in the NSScrollView. Listing 2 showsthe statements that accomplish this step. Listing 2 Setting up the text view theTextView = [[NSTextView alloc] initWithFrame:NSMakeRect(0, 0, contentSize.width, contentSize.height)]; [theTextView setMinSize:NSMakeSize(0.0, contentSize.height)]; [theTextView setMaxSize:NSMakeSize(FLT_MAX, FLT_MAX)]; [theTextView setVerticallyResizable:YES]; [theTextView setHorizontallyResizable:NO]; [theTextView setAutoresizingMask:NSViewWidthSizable]; [[theTextView textContainer] setContainerSize:NSMakeSize(contentSize.width, FLT_MAX)]; [[theTextView textContainer] setWidthTracksTextView:YES]; Listing 2 specifies that the NSTextView’s width and height initially match those of the content area of the NSScrollView. The setMinSize: message tells the NSTextView that it can get arbitrarily small in width, but no smaller than its initial height. The setMaxSize: message allows the receiver to grow arbitrarily in either dimension. These limits are used by the NSLayoutManager when it resizes the NSTextView to fit the text laid out. The next three messages determine how the NSTextView’s dimensions change in response to additions or deletions of text and to changes in the scroll view’s size. The NSTextView is set to grow vertically as text is added but not horizontally. Its resizing mask is set to allow it to change width in response to changes in the width of its superview. Since, except for the minimum and maximum values, the NSTextView’s height is determined by the amount of text it has in it, its height should not change with that of its superview. The last two messages in this step are to the NSTextContainer, not the NSTextView. One message sets the text container’s initial width to that of the scroll view and its height to the maximum size of the text view. The last message tells the NSTextContainer to resize its width according to the width of the NSTextView. Recall that Putting an NSTextView Object in an NSScrollView Setting Up the Text View 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 15the text system lays out text according to the dimensions stored in NSTextContainer objects. An NSTextView provides a place for the text to be displayed, but its dimensions and those of its NSTextContainer can be quite different. The setWidthTracksTextView:YES message ensures that as the NSTextView is resized, the width dimension stored in its NSTextContainer is likewise resized, causing the text to be laid out within the new boundaries. Assembling the Pieces The last step is to assemble and display the pieces. Listing 3 shows the statements that accomplish this step. Listing 3 Assembling the pieces [scrollview setDocumentView:theTextView]; [theWindow setContentView:scrollview]; [theWindow makeKeyAndOrderFront:nil]; [theWindow makeFirstResponder:theTextView]; Setting Up a Horizontal Scroll Bar To set up both horizontal and vertical scroll bars, use the statements in Listing 4 in place of the corresponding statements in the previous listings. Listing 4 Setting up a horizontal scroll bar [[theTextView enclosingScrollView] setHasHorizontalScroller:YES]; [theTextView setHorizontallyResizable:YES]; [theTextView setAutoresizingMask:(NSViewWidthSizable | NSViewHeightSizable)]; [[theTextView textContainer] setContainerSize:NSMakeSize(FLT_MAX, FLT_MAX)]; [[theTextView textContainer] setWidthTracksTextView:NO]; This code fragment adds the horizontal scroll bar to the scroll view and makes the text view horizontally resizable so it can display text of any width. The code sets the text view’s resizing mask so that it changes in both width and height in response to corresponding changes in its superview. The next-to-last message sets both dimensions of the text container to an arbitrarily large value, which essentially means the text is laid out in one long line, and the last message ensures that the text container does not resize horizontally with the text view. Putting an NSTextView Object in an NSScrollView Assembling the Pieces 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 16A single NSLayoutManager can be assigned any number of NSTextContainers, in whose NSTextViews it lays out textsequentially. In such a configuration, many of the attributes accessed through the NSTextView interface are actually shared by all of these text views. Among these attributes are: ● The selection ● The delegate ● Selectability ● Editability ● Whether they act as a field editor ● Whether they display plain or rich text ● Whether they import graphics ● Whether they use the ruler ● Whether the ruler is visible ● Whether they use the Font panel (Fonts window) Setting any of these attributes causes all associated NSTextView objects to share the new value. With multiple NSTextViews, only one isthe first responder at any time. NSLayoutManager definesthese methods for determining and appropriately setting the first responder: ● layoutManagerOwnsFirstResponderInWindow: ● firstTextView ● textViewForBeginningOfSelection See their descriptions in the NSLayoutManager class specification for more information. 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 17 Using Multiple NSTextViewsText objects such as NSText and NSTextView can contain either plain text or rich text. Plain text objects allow only one set of text attributes for all of their text; rich text objects allow multiple fonts, sizes, indents, and other attributes for different sets of characters and paragraphs. You can control whether a text object is plain or rich using the setRichText: method. Rich text objects are also capable of allowing the user to drag images and files into them. This behavior is controlled by the setImportsGraphics: method. A rich NSText object can use RTF (Rich Text Format) as an interchange format. Not all RTF control words are supported, however. On input, an NSText object ignores any control word it doesn’t recognize; some of those it can read and interpret it doesn’t write out. Table 1 lists the RTF control words that any text object recognizes. Subclasses may recognize more. Table 1 RTF control words recognized by all text objects Control word Can be written out \ansi yes \b yes \cb yes \cf yes \colortbl yes \dnn yes \fin yes \fn yes \fonttbl yes \fsn yes \i yes \lin yes \margrn yes 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 18 Plain and Rich Text ObjectsControl word Can be written out \paperwn yes \mac no \margln yes \par yes \pard no \pca no \qc yes \ql yes \qr yes \sn no \tab yes \upn yes Plain and Rich Text Objects 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 19NSTextView allows you to change the attributes of its text programmatically through various methods, most inherited from the superclass, NSText. NSTextView adds its own methods for setting the attributes of text that the user types, for setting the baseline offset of text as an absolute value, and for adjusting kerning and use of ligatures. Most of the methods for changing attributes are defined as action methods and apply to the selected text or typing attributes for a rich text view, or to all of the text in a plain text view. An NSTextView maintains a set of typing attributes (font, size, color, and so on) that it applies to newly entered text, whether typed by the user or pasted as plain text. It automatically setsthe typing attributesto the attributes of the first character immediately preceding the insertion point, of the first character of a paragraph if the insertion point is at the beginning of a paragraph, or of the first character of a selection. The user can change the typing attributes by choosing menu commands and using utilities such as the Font panel (Fonts window). You can also set the typing attributes programmatically using setTypingAttributes:, though you should rarely find need to do so unless creating a subclass. NSText defines the action methods superscript:, subscript:, and unscript:, which raise and lower the baseline of text by predefined increments. NSTextView gives you much finer control over the baseline offset of text by defining the raiseBaseline: and lowerBaseline: action methods, which raise or lower text by one point each time they’re invoked. Kerning NSTextView provides convenient action methods for adjusting the spacing between characters. By default, an NSTextView object uses standard kerning (as provided by the data in a font’s AFM file). A turnOffKerning: message causes this kerning information to be ignored and the selected text to be displayed using nominal widths. The loosenKerning: and tightenKerning: methods adjust kerning values over the selected text and useStandardKerning: reestablishes the default kerning values. Kerning information is a character attribute that’s stored in the text view’s NSTextStorage object. If your application needs finer control over kerning than the methods of this class provide, you should operate on the NSTextStorage object directly through methods defined by its superclass, NSMutableAttributedString. See the reference documentation for NSAttributedString Additions for information on setting attributes. 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 20 Setting Text AttributesLigatures NSTextView’s support for ligatures provides the minimum required ligatures for a given font and script. The required ligatures for a specific font and script are determined by the mechanisms that generate glyphs for a specific language. Some scripts may well have no ligatures at all—English text, as an example, doesn’t require ligatures, although certain ligatures such as “fi” and “fl” are desirable and are used if they’re available. Other scripts,such as Arabic, demand that certain ligatures must be available even if a turnOffLigatures: message is sent to the NSTextView. Other scripts and fonts have standard ligatures that are used if they’re available. The useAllLigatures: method extends ligature support to include all possible ligatures available in each font for a given script. Ligature information is a character attribute that’s stored in the text view’s NSTextStorage object. If your application needs finer control over ligature use than the methods of this class provide, you should operate on the NSTextStorage object directly through methods defined by its superclass, NSMutableAttributedString. See the reference documentation for NSAttributedString Additions for information on setting attributes. Setting Text Attributes Ligatures 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 21Many text system objects cooperate in the display of text, and several of them maintain inset values that affect the apparent margins of text on a printed page or display. This article describesthose settings and their proper use. Figure 1 illustrates the various margins and insets you can place around text. Figure 1 Text margins and insets Line fragment padding Text container inset Text view inset in superview Print settings margins Text container Text view Superview of text view (if present) Printed page Paragraph head indent We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America. Paragraph tail indent Paragraph first line indent Line fragment padding Paragraph style objects maintain head indent values for the first and subsequent lines and a tail indent value. These values describe space between the beginning and end of text lines and the edge of the text container. For left-to-right text, as shown in Figure 1, the head indents appear on the left side of the paragraph and the tail indent on the right side. You can find the indent values using the NSParagraphStyle methods firstLineHeadIndent, headIndent, and tailIndent. You set the values using the corresponding NSMutableParagraphStylemethods setFirstLineHeadIndent:, setHeadIndent:, and setTailIndent:. By default, a text container covers its text view exactly. However, you can specify blank space between the edges of the text container and the edges of the text view with the NSTextView method setTextContainerInset:. This method specifies a width and height by which the text container’s top-left origin point is offset from the origin of the text view. The text container’s right and bottom edges are then 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 22 Setting Text Marginsinset by an equal amount. The container inset is respected even when the container is set to track the height and width of the text view. It’s possible to set the text container and text view sizes and resizing behavior so that the inset cannot be maintained exactly, but the text system maintains it whenever possible. The text container inset refers to the bounding rectangle of the text container’s region. However, you can define the region to be a nonrectangular shape, in which case some lines of text can have additional space between the ends of the lines and the bounding rectangle. See “Calculating Region, Bounding Rectangle, and Inset” for more information. Another parameter that you can set to leave space at the ends of lines of type is called line fragment padding. You can setthe padding value with theNSTextContainermethod setLineFragmentPadding:. This adjustment is meant to specify a small amount of blank space on each end of the line fragment rectangles in which the typesetter sets lines of text. Line fragment padding keeps text from directly abutting any graphics or other elements positioned next to the text container. Finally, the text view itself can optionally be inset in a superview, as in TextEdit’s multiple-page view, and views can be inset on a printed page using print settings. Setting Text Margins 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 23This table describes the changes to Text System User Interface Layer Programming Guide . Date Notes 2012-09-19 Fixed broken link. Corrected line fragment padding representation in Figure 1 of "Setting Text Margins." 2006-06-28 2004-07-27 Made editorial revisions to previously unedited articles. Added section to “Putting an NSTextView Object in an NSScrollView.” Added a new article titled “Setting Text Margins.” Rewrote introduction and added an index. 2004-02-06 2003-05-02 Moved four articles to new Text Editing programming topic. Corrected error in example code in the article “Putting an NSTextView Object in an NSScrollView.” 2003-01-16 2002-11-12 Revision history added to existing topic. 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 24 Document Revision HistoryA alloc method to create an NSTextView object 12 E Edit menu and NSTextView 8, 9 F field editor 11 first line indent 22 first responder 10, 13, 17 firstLineHeadIndent method 22 firstTextView method 17 H head indent 22 headIndent method 22 I init... methods to create an NSTextView object 12 initWithFrame: method 12, 13 initWithFrame:textContainer: method 12 Interface Builder to create a text view object 8 K kerning of text 20 L layoutManagerOwnsFirstResponderInWindow: method 17 ligatures in fonts 21 line fragment padding 22 loosenKerning: method 20 lowerBaseline: method 20 M makeFirstResponder: method 13 makeKeyAndOrderFront: method 13 margins of text 22 memory management and Cocoa text objects 13 menu commands of Cocoa text system 9 N NSForm class 11 NSLayoutManager class 15, 17 NSMutableAttributedString class 20 NSScrollView class 8, 14 NSText class 6 NSTextContainer class 17 NSTextField class 11 NSTextStorage class 20 NSTextView class configured as multiple text views 17 features of 6 in a scroll view 14 instantiating 8, 12 setting text attributes with 20 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 25 IndexP plain text and Cocoa text objects 18 print settings margins 22 R raiseBaseline: method 20 Rich Text Format (RTF) and NSText objects 18 RTF. See Rich Text Format S scroll bars and NSTextView 14, 16 scroll views, setting up 14 Services menu and NSTextView 10 setContentView: method 13 setFirstLineHeadIndent: method 22 setHeadIndent: method 22 setImportsGraphics: method 18 setLineFragmentPadding: method 23 setMaxSize: method 15 setMinSize: method 15 setRichText: method 18 setTailIndent: method 22 setTextContainerInset: method 22 setTypingAttributes: method 20 setWidthTracksTextView: method 16 subscript: method 20 superscript: method 20 T tail indent 22 tailIndent method 22 text attributes 18, 20–21 text container insets 22 Text menu and NSTextView 9 text views configuring 15 insets 22 text-handling features of NSTextView 6–7 textViewForBeginningOfSelection method 17 tightenKerning: method 20 turnOffKerning: method 20 turnOffLigatures: method 21 typing attributes 20 U unscript: method 20 useAllLigatures: method 21 useStandardKerning: method 20 Index 2012-09-19 | © 1997, 2012 Apple Inc. All Rights Reserved. 26Apple Inc. © 1997, 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, Cocoa, and Mac are trademarks of Apple Inc., registered in the U.S. and other countries. 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. Cocoa Text Architecture GuideContents About the Cocoa Text System 7 At a Glance 7 Most Applications Can Use the Cocoa Text System 8 Typographical Concepts Are Essential for Understanding the Text System 8 The Text System Comprises Views, Controllers, and Storage Classes 8 Attributes Characterize Text and Documents 8 Font Objects, the Font Panel, and the Font Manager Provide Typeface Handling 9 Text Objects Are Key to Text Editing 9 Prerequisites 9 See Also 9 Text Handling Technologies in OS X 11 Typographical Concepts 12 Characters and Glyphs 12 Typefaces and Fonts 13 Text Layout 14 Text System Organization 18 Functional Areas of the Cocoa Text System 19 Class Hierarchy of the Cocoa Text System 21 MVC and the Text System 23 Creating Text System Objects 23 Text View Creates the Objects 23 Your App Creates the Objects Explicitly 24 Common Configurations 26 Text Fields, Text Views, and the Field Editor 30 Text Fields 30 Text Views 31 The Field Editor 32 Text Attributes 33 Character Attributes 33 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Storing Character Attributes 34 Attribute Fixing 34 Temporary Attributes 35 Paragraph Attributes 35 Glyph Attributes 35 Document Attributes 36 Font Handling 37 The Font Panel 37 Creating a Font Panel 37 Using the Font Panel 38 Working with Font Objects 39 Querying Font Metrics 39 Querying Standard Font Variations 40 Characters, Glyphs, and the Layout Manager 41 Getting the View Coordinates of a Glyph 42 Working with the Font Manager 42 Creating a Font Manager 42 Handling Font Changes 43 Converting Fonts Manually 44 Setting Font Styles and Traits 45 Examining Fonts 46 Customizing the Font Conversion System 46 Text Editing 48 The Editing Environment 48 The Key-Input Message Sequence 49 Intercepting Key Events 51 Text View Delegation 52 Text View Delegate Messages and Notifications 53 Text Field Delegation 54 Synchronizing Editing 55 Batch-Editing Mode 55 Forcing the End of Editing 56 Setting Focus and Selection Programmatically 57 Subclassing NSTextView 58 Updating State 59 Custom Import Types 59 Altering Selection Behavior 60 Preparing to Change Text 60 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsText Change Notifications and Delegate Messages 60 Smart Insert and Delete 61 Creating a Custom Text View 61 Implementing Text Input Support 61 Managing Marked Text 62 Communicating with the Text Input Context 63 Working with the Field Editor 64 How the Field Editor Works 64 Using Delegation and Notification with the Field Editor 64 Using a Custom Field Editor 66 Field Editor–Related Methods 67 Document Revision History 71 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures, Tables, and Listings Typographical Concepts 12 Figure 2-1 Glyphs of the character A 12 Figure 2-2 Ligatures 13 Figure 2-3 Fonts in the Times font family 14 Figure 2-4 Glyph metrics 16 Figure 2-5 Kerning 16 Figure 2-6 Alignment of text relative to margins 17 Figure 2-7 Justified text 17 Text System Organization 18 Figure 3-1 Major functional areas of the Cocoa text system 19 Figure 3-2 Cocoa Text System Class Hierarchy 22 Figure 3-3 Text object configuration for a single flow of text 26 Figure 3-4 Text object configuration for paginated text 27 Figure 3-5 Text object configuration for a multicolumn document 27 Figure 3-6 Text object configuration for multiple views of the same text 28 Figure 3-7 Text object configuration with custom text containers 29 Text Fields, Text Views, and the Field Editor 30 Figure 4-1 A text field 30 Figure 4-2 A text view 31 Figure 4-3 The field editor 32 Text Attributes 33 Figure 5-1 The composition of an NSAttributedString object including its attributes dictionary 34 Font Handling 37 Figure 6-1 Font metrics 39 Table 6-1 Font metrics and related NSFont methods 39 Table 6-2 Standard font methods 40 Table 6-3 Font conversion methods 44 Table 6-4 Font menu item actions and tags 47 Text Editing 48 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5Figure 7-1 Key-event processing 49 Figure 7-2 Input context key binding and interpretation 50 Figure 7-3 Delegate of an NSTextView object 53 Table 7-1 NSWindow field editor–related methods 67 Table 7-2 NSTextFieldCell field editor–related method 68 Table 7-3 NSCell field editor–related methods 68 Table 7-4 NSControl field editor–related methods 69 Table 7-5 NSResponder field editor–related methods 69 Table 7-6 NSText field editor–related methods 70 Listing 7-1 Forcing layout 56 Listing 7-2 Forcing the end of editing 57 Listing 7-3 Forcing the field editor to enter a newline character 65 Listing 7-4 Substituting a custom field editor 67 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6 Figures, Tables, and ListingsThe Cocoa text system is the primary text-handling system in OS X, responsible for the processing and display of all visible text in Cocoa. It provides a complete set of high-quality typographical services through the text-related AppKit classes, which enable applications to create, edit, display, and store text with all the characteristics of fine typesetting, such as kerning, ligatures, line-breaking, and justification. Ruler views, font and color panels Glyph generator Text input Typesetter Text containers Text storage Text views Layout manager Display View Layer Controller Layer Storage Layer At a Glance The Cocoa text system provides text editing and layout for most applications. The object-oriented design of the system provides flexibility and ease of use. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7 About the Cocoa Text SystemMost Applications Can Use the Cocoa Text System If your application needs to display text, and especially if its users need to enter and edit text, then you should use the Cocoa text system. The Cocoa text system is one of two text-handling systems in OS X. The other is Core Text, which provides low-level, basic text layout and font-handling capabilities to higher-level engines such as the AppKit. Related Chapter: “Text Handling Technologies in OS X” Typographical Concepts Are Essential for Understanding the Text System The Cocoa text system encodes characters as Unicode values. It translates characters into glyphs, including ligatures and other contextual forms, and handles typefaces, styles, fonts, and families. The system does text layout, placing glyphs horizontally or vertically in either direction, using font metric information, and uses kerning when appropriate. It performs high-quality line breaking and hyphenation to create lines of text with proper alignment or justification. Related Chapter: “Typographical Concepts” (page 12) The Text System Comprises Views, Controllers, and Storage Classes The Cocoa textsystem is abstracted as a set of classesthat represent modular, layered functional areasreflecting the Model-View-Controller design paradigm. The top layer of the system is the user-interface layer of various views, the bottom layer stores the data models, and the middle layer consists of controllers that interpret keyboard input and arrange text for display. The four primary text system classes—NSTextView, NSLayoutManager, NSTextContainer, and NSTextStorage—can be configured in various ways to accomplish different text-handling goals. Related Chapters: “Text System Organization” (page 18), “Text Fields, Text Views, and the Field Editor” (page 30) Attributes Characterize Text and Documents The Cocoa text system handles five kinds of attributes: character attributes, such as font and size; temporary attributes used during processing or display, such as underlining of misspelled words; paragraph attributes, such as alignment and tab stops; glyph attributes that may control special handling of particular glyphs; and document attributes, such as margins and paper size. About the Cocoa Text System At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8Related Chapter: “Text Attributes” (page 33) Font Objects, the Font Panel, and the Font Manager Provide Typeface Handling The Font panel, also called the Fonts window, is a user interface object that displays a list of available font families and styles, letting the user preview them and change the font used to display text. Text views work with NSFontPanel and NSFontManager objects to implement the font-handling system. You can create font objects using the NSFont class and query them for font metrics and detailed glyph layout information. Related Chapter: “Font Handling” (page 37) Text Objects Are Key to Text Editing Usually, text editing is performed by direct user action with a text view, but it can also be accomplished by programmatic interaction with a text storage object. The text input system translates keyboard events into commands and text input. You can customize editing behavior using many methods of text system objects, through the powerful Cocoa mechanisms of notification and delegation, or, in extreme cases, by replacing the text view itself with a custom subclass. Related Chapter: “Text Editing” (page 48) Prerequisites To understand the information in this document, you should understand the material in Text System User Interface Layer Programming Guide . In addition, you should have a general knowledge of Cocoa programming paradigms and, to understand the code examples, familiarity with the Objective-C language. See Also The following documents describe other aspects of the Cocoa text system: Text SystemUserInterface Layer ProgrammingGuide describesthe high-level interface to the Cocoa textsystem, which is sufficient for most applications. Text System Storage Layer Overview discusses the lower-level facilities that the Cocoa text system uses to store text. About the Cocoa Text System Prerequisites 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9Text Layout Programming Guide describes how the Cocoa text system lays out text on a page, suitable for display and printing. The following sample code projects illustrate how to use many of the APIs of the Cocoa text system: CircleView is a small application with a demonstration subclass of NSView that draws text in a circle. NSFontAttributeExplorer demonstrates how to gather and display various metric information for installed fonts using NSFont. TextInputView demonstrates how to gather and display various metric information for installed fonts using NSFont. TextViewConfig demonstrates configuration of multiple layout managers and multiple text container–text view pairs on a single text storage object. TextLinks programmatically creates links to URLs and other objects and handles clicks in non-URL links. TextViewDelegate demonstrates using a text view's delegate to control selection and user input. About the Cocoa Text System See Also 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10The Macintosh operating system has provided sophisticated text handling and typesetting capabilities from its beginning. In fact, these featuressparked the desktop publishing revolution. Over the years, the text handling facilities of the platform have continued to evolve to become more advanced, more efficient, and easier to use. OS X provides modern text handling capabilities that are available to all applications through the classes of the Cocoa text system and the opaque types and functions of Core Text. The text-handling component of any application presents one of the greatest challengesto software designers. Even the most basic text-handling system must be relatively sophisticated, allowing for text input, layout, display, editing, copying and pasting, and many other features. But developers and users expect even more than these basic features, expecting even simple editors to support multiple fonts, various paragraph styles, embedded images, spell checking, and other features. The Cocoa text system provides all these basic and advanced text-handling features, and it also satisfies additional requirements from the ever-more-interconnected computing world: support for the character sets of all of the world’s living languages, powerful layout capabilities to handle various text directionality and nonrectangular text containers, and sophisticated typesetting capabilities such as control of kerning and ligatures. Cocoa’s object-oriented text system is designed to provide all these capabilities without requiring you to learn about or interact with more of the system than is necessary to meet the needs of your application. Underlying the Cocoa text system is Core Text, which provides low-level, basic text layout and font-handling capabilitiesto higher-level enginessuch as AppKit, WebKit, and others. Core Text providesthe implementation for many Cocoa text technologies. Application developers typically have no need to use Core Text directly. However, the Core Text API is accessible to developers who must use it directly,such asthose writing applications with their own layout engine and those porting ATSUI- or QuickDraw-based codebases to the modern world. To decide which OS X text technology is right for your application, apply the following guidelines: ● If possible, use Cocoa text. The NSTextView class is the most advanced full-featured, flexible text view in OS X. Forsmall amounts of text, use NSTextField. For more information about text views,see Text System User Interface Layer Programming Guide . ● To display web content in your application, use WebKit. For more information about WebKit, see WebKit Objective-C Programming Guide . ● If you have your own page layout engine, you can use Core Text to generate the glyphs and position them relative to each other. For more information about Core Text, see Core Text Programming Guide . 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11 Text Handling Technologies in OS XThis chapter defines some important typographical concepts relevant to the text system. If you are already familiar with typography, you can skip this chapter. Characters and Glyphs A character is the smallest unit of written language that carries meaning. Characters can correspond to a particularsound in the spoken form of the language, as do the letters of the Roman alphabet; they can represent entire words, such as Chinese ideographs; or they can represent independent concepts, such as mathematical symbols. In every case, however, a character is an abstract concept. Although characters must be represented in a display area by a recognizable shape, they are not identical to that shape. That is, a character can be drawn in various forms and remain the same character. For example, an “uppercase A” character can be drawn with a different size or a different stroke thickness, it can lean or be vertical, and it can have certain optional variations in form, such as serifs. Any one of these various concrete forms of a character is called a glyph. Figure 2-1 shows different glyphs that all represent the character “uppercase A.” Figure 2-1 Glyphs of the character A 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12 Typographical ConceptsCharacters and glyphs do not have a one-to-one correspondence. In some cases a character may be represented by multiple glyphs, such as an “é” which may be an “e” glyph combined with an acute accent glyph “´”. In other cases, a single glyph may represent multiple characters, as in the case of a ligature, or joined letter. Figure 2-2 shows individual characters and the single-glyph ligature often used when they are adjacent. Figure 2-2 Ligatures + = + = A ligature is an example of a contextual form in which the glyph used to represent a character changes depending on the characters next to it. Other contextual formsinclude alternate glyphsfor characters beginning or ending a word. Computers store characters as numbers mapped by encoding tables to their corresponding characters. The encoding scheme native to OS X is called Unicode. The Unicode standard provides a unique number for every character in every modern written language in the world, independent of the platform, program, and programming language being used. This universalstandard solves a longstanding problem of different computer systems using hundreds of conflicting encoding schemes. It also hasfeaturesthatsimplify handling bidirectional text and contextual forms. Glyphs are also represented by numeric codes called glyph codes. The glyphs used to depict characters are selected by the Cocoa layout manager during composition and layout processing. The layout manager determines which glyphs to use and where to place them in the display, or view. The layout manager caches the glyph codesin use and provides methodsto convert between characters and glyphs and between characters and view coordinates. (See “Text Layout” (page 14) for more information about the layout process.) Typefaces and Fonts A typeface is a set of visually related shapesforsome or all of the charactersin a written language. For example, Times is a typeface, designed by Stanley Morrison in 1931 for The Times newspaper of London. All of the letter forms in Times are related in appearance, having consistent proportions between stems (vertical strokes) and counters (rounded shapes in letter bodies) and other elements. When laid out in blocks of text, the shapes in a typeface work together to enhance readability. Typographical Concepts Typefaces and Fonts 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13A typestyle, orsimply style, is a distinguishing visual characteristic of a typeface. For example, roman typestyle is characterized by upright letters having serifs and stems thicker than horizontal lines. In italic typestyle, the letters slant to the right and are rounded, similar to cursive or handwritten letter shapes. A typeface usually has several associated typestyles. A font is a series of glyphs depicting the characters in a consistent size, typeface, and typestyle. A font is intended for use in a specific display environment. Fonts contain glyphs for all the contextual forms, such as ligatures, as well as the normal character forms. A font family is a group of fontsthatshare a typeface but differ in typestyle. So, for example, Timesisthe name of a font family (as well as the name of its typeface). Times Roman and Times Italic are the names of two individual fonts belonging to the Times family. Figure 2-3 shows several of the fonts in the Times font family. Figure 2-3 Fonts in the Times font family Styles, also called traits, that are available in Cocoa include variationssuch as bold, italic, condensed, expanded, narrow, small caps, poster fonts, and fixed pitch. Font descriptors in the Cocoa text system provide a font-matching capability,so that you can partially describe a font by creating a font descriptor with, for example, just a family name or weight, and you can then find all the fonts on the system that match the given trait. Text Layout Text layoutisthe process of arranging glyphs on a display device, in an area called a text view, which represents an area similar to a page in traditional typesetting. The order in which glyphs are laid out relative to each other is called text direction. In English and other languages derived from Latin, glyphs are placed side by side to form words that are separated by spaces. Words are laid out in lines beginning at the top left of the text view proceeding from left to right until the text reaches the right side of the view. Text then begins a new line at the left side of the view under the beginning of the previous line, and layout proceeds in the same manner to the bottom of the text view. Typographical Concepts Text Layout 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14In other languages, glyph layout can be quite different. For example, some languages lay out glyphs from right to left or vertically instead of horizontally. It is common, especially in technical writing, to mix languages with differing text direction, such as English and Hebrew, in the same line. Some writing systems even alternate layout direction in every other line (an arrangement called boustrophedonic writing). Some languages do not group glyphs into words separated by spaces. Moreover, some applications call for arbitrary arrangements of glyphs; for example, in a graphic design context, a layout may require glyphs to be arranged on a nonlinear path. To create lines from a string of glyphs, the layout engine must perform line breaking by finding a point at which to end one line and begin the next. In the Cocoa text system, you can specify line breaking at either word or glyph boundaries. In Roman text, a word broken between glyphs requires insertion of a hyphen glyph at the breakpoint. The Cocoa layout manager lays out glyphs along an invisible line called the baseline. In Roman text, the baseline is horizontal, and the bottom edge of most of the glyphs rest on it. Some glyphs extend below the baseline, including those for characters like “g” that have descenders, or “tails,” and large rounded characters like “O” that must extend slightly below the baseline to compensate for optical effects. Other writing systems place glyphs below or centered on the baseline. Every glyph includes an origin point that the layout manager uses to align it properly with the baseline. Glyph designers provide a set of measurements with a font, called metrics, which describe the spacing around each glyph in the font. The layout manager uses these metrics to determining glyph placement. In horizontal text, the glyph has a metric called the advance width, which measures the distance along the baseline to the origin point of the next glyph. Typically there is some space between the origin point and the left side of the glyph, which is called the left-side bearing. There may also be space between the right side of the glyph and the point described by the advance width, which is called the right-side bearing. The vertical dimension of the glyph is provided by two metrics called the ascent and the descent. The ascent is the distance from the Typographical Concepts Text Layout 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15origin (on the baseline) to the top of the tallest glyphs in the font. The descent, which is the distance below the baseline to the bottom of the font’s deepest descender. The rectangle enclosing the visible parts of the glyph is called the bounding rectangle or bounding box. Figure 2-4 illustrates these metrics. Figure 2-4 Glyph metrics Advance width = Origin Ascent Baseline Right-side bearing Descent Left-side bearing Bounding box By default, in horizontal text, typesetters place glyphs side-by-side using the advance width, resulting in a standard interglyph space. However, in some combinations, text is made more readable by kerning, which is shrinking or stretching the space between two glyphs. A very common example of kerning occurs between an uppercase W and uppercase A, as shown in Figure 2-5. Type designers include kerning information in the metricsfor a font. The Cocoa textsystem provides methodsto turn kerning off, use the defaultsettings provided with the font, or tighten or loosen the kerning throughout a selection of text. Figure 2-5 Kerning With kerning Without kerning Type systems usually measure font metrics in units called points, which in OS X measure exactly 72 per inch. Adding the distance of the ascent and the descent of a font provides the font’s point size. Space added during typesetting between lines of type is called leading, after the slugs of lead used for that purpose in traditional metal-type page layout. (Leading is sometimes also called linegap .) The total amount of ascent plus descent plus leading provides a font’s line height. Typographical Concepts Text Layout 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16Although the preceding typographic concepts of type design may be somewhat esoteric, most people who have created documents on a computer or typewriter are familiar with the elements of text layout on a page. For example, the margins are the areas of white space between the edges of the page and the text area where the layout engine places glyphs. Alignment describes the way text lines are placed relative to the margins. For example, horizontal text can be aligned right, left, or centered, as shown in Figure 2-6. Figure 2-6 Alignment of text relative to margins Left aligned Alignment or flushness, is the process of placing text in relation to one or both margins. You set the alignment in the style object for glyph and text shapes, not for layout shapes. Justification, is the process of typographically “stretching” or “shrinking” a line of text to fit within a given width. Your application can set the width of the space in which the line of text should appear; ATSUI then distributes the white space available on the line between words or even between glyphs, depending on the level of justification your application or the user choses. Centered Alignment or flushness, is the process of placing text in relation to one or both margins. You set the alignment in the style object for glyph and text shapes, not for layout shapes. Justification, is the process of typographically “stretching” or “shrinking” a line of text to fit within a given width. Your application can set the width of the space in which the line of text should appear; ATSUI then distributes the white space available on the line between words or even between glyphs, depending on the level of justification your application or the user choses. Right aligned Alignment or flushness, is the process of placing text in relation to one or both margins. You set the alignment in the style object for glyph and text shapes, not for layout shapes. Justification, is the process of typographically “stretching” or “shrinking” a line of text to fit within a given width. Your application can set the width of the space in which the line of text should appear; ATSUI then distributes the white space available on the line between words or even between glyphs, depending on the level of justification your application or the user choses. Lines of text can also be justified; for horizontal text the lines are aligned on both right and left margin by varying interword and interglyph spacing, as shown in Figure 2-7. The system performs alignment and justification, if requested, after the text stream has been broken into lines and hyphens added and other glyph substitutions made. Figure 2-7 Justified text Justified Glyph designers provide a set of measurements with a font, called metrics, which describe the spacing around each glyph placement. Layout engines use the metrics to determine glyph placement. In horizontal text, the glyph has a metric called the advanced width, which measures the distance along the baseline where the origin point if the next glyph is placed. Typically there is some space between the origin point and the left side of the glyph, which is called the left-side bearing. There may also be space between the right side of the glyph and the point described by the advanced width, called the right-side bearing. Vertical spacing of the glyph is provided by two metrics called the ascent, which is the distance from the origin (on the baseline) to a height slightly above the top of the tallest glyphs in the font, and the descent, which is below the baseline. The rectangle enclosing the visible Typographical Concepts Text Layout 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17The Cocoa textsystem is abstracted into a set of classesthat interact to provide all of the text-handling features of the system. The classesrepresentspecific functional areas with well-defined interfacesthat enable application programs to modify the behavior of the system or even to replace parts with custom subclasses. The Cocoa text system is designed so that you don’t need to learn about or interact with more of the system than is necessary to meet the needs of your application. For most developers, the general-purpose programmatic interface of the NSTextView class is all you need to learn. NSTextView provides the user interface to the text system. See NSTextView Class Reference for detailed information about NSTextView. If you need more flexible, programmatic access to the text, you’ll need to learn about the storage layer and the NSTextStorage class. And, of course, to access all the available features, you can interact with any of the classes that support the text system. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18 Text System OrganizationFunctional Areas of the Cocoa Text System Figure 3-1 shows the major functional areas of the text system with the user interface layer on top, the storage layer on the bottom, and, in the middle region, the components that lay out the text for display. These layers represent view, controller, and model concepts, respectively, as described in “MVC and the Text System” (page 23). Figure 3-1 Major functional areas of the Cocoa text system Ruler views, font and color panels Glyph generator Text input Typesetter Text containers Text storage Text views Layout manager Display View Layer Controller Layer Storage Layer The text classes exceed most other classes in the AppKit in the richness and complexity of their interface. One of their design goals is to provide a comprehensive set of text-handling features so that you rarely need to create a subclass. Among other things, a text object such as NSTextView can: ● Control whether the user can select or edit text. ● Control the font and layout characteristics of its text by working with the Font menu and Font panel (also called the Fonts window). ● Let the user control the format of paragraphs by manipulating a ruler. ● Control the color of its text and background. ● Wrap text on a word or character basis. ● Display graphic images within its text. ● Write text to or read text from files in the form of RTFD—Rich Text Format files that contain TIFF or EPS images, or attached files. Text System Organization Functional Areas of the Cocoa Text System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19● Let another object, the delegate, dynamically control its properties. ● Let the user copy and paste text within and between applications. ● Let the user copy and paste font and format information between NSTextView objects. ● Let the user check the spelling of words in its text. Graphical user-interface building tools (such as Interface Builder) may give you access to text objects in several different configurations,such asthose found in the NSTextField, NSForm, and NSScrollView objects. These classes configure a text object for their own specific purposes. Additionally, all NSTextField, NSForm, or NSButton objects within the same window—in short, all objects that access a text object through associated cells—share the same text object, called the field editor. Thus, it’s generally best to use one of these classes whenever it meets your needs, rather than create text objects yourself. But if one of these classes doesn’t provide enough flexibility for your purposes, you can create text objects programmatically. Text objects typically work closely with various other objects. Some of these—such as the delegate or an embedded graphic object—require some programming on your part. Others—such as the Font panel, spell checker, or ruler—take no effort other than deciding whether the service should be enabled or disabled. To control layout of text on the screen or printed page, you work with the objectsthat link the NSTextStorage repository to the NSTextView that displays its contents. These objects are of the NSLayoutManager and NSTextContainer classes. An NSTextContainer object defines a region where text can be laid out. Typically, a text container defines a rectangular area, but by creating a subclass of NSTextContainer you can create other shapes: circles, pentagons, or irregular shapes, for example. NSTextContainer isn’t a user-interface object, so it can’t display anything or receive events from the keyboard or mouse. It simply describes an area that can be filled with text, and it’s not tied to any particular coordinate system. Nor does an NSTextContainer object store text—that’s the job of an NSTextStorage object. A layout manager object, of the NSLayoutManager class, orchestratesthe operation of the other text handling objects. It intercedes in operations that convert the data in an NSTextStorage object to rendered text in an NSTextView object’s display. It also overseesthe layout of text within the areas defined by NSTextContainer objects. Text System Organization Functional Areas of the Cocoa Text System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20Class Hierarchy of the Cocoa Text System In addition to the four principal classes in the text system—NSTextStorage, NSLayoutManager, NSTextContainer, NSTextView—there are a number of auxiliary classes and protocols. Figure 3-2 provides a more complete picture of the text system. Names between angle brackets, such as , are protocols. Text System Organization Class Hierarchy of the Cocoa Text System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21Figure 3-2 Cocoa Text System Class Hierarchy NSAttributedString NSObject NSActionCell NSSecureTextFieldCell NSGlyphInfo NSMutableAttributedString NSTextStorage NSView NSFontDescriptor NSFont NSCell NSTextFieldCell NSTextTable NSTextTableBlock NSMutableParagraphStyle NSGlyphGenerator NSLayoutManager NSParagraphStyle NSResponder NSTextAttachmentCell NSSearchFieldCell NSTokenFieldCell NSFontManager NSATSTypesetter NSTextBlock NSSpellChecker NSRulerMarker NSTextContainer NSTextInputContext NSTextList NSTextTab NSTypesetter NSTextAttachment NSWindow NSPanel NSFontPanel NSControl NSRulerView NSSearchField NSSecureTextField NSTokenField NSTextField NSText NSTextView NSView Text System Organization Class Hierarchy of the Cocoa Text System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22MVC and the Text System The Cocoa text system’s architecture is both modular and layered to enhance its ease of use and flexibility. Its modular design reflects the Model-View-Controller paradigm (originating with Smalltalk-80) where the data, its visual representation, and the logic that links the two are represented by separate objects. In the case of the text system, NSTextStorage holds the model’s text data, NSTextContainer models the geometry of the layout area, NSTextView presents the view, and NSLayoutManager intercedes as the controller to make sure that the data and its representation onscreen stay in agreement. This factoring of responsibilities makes each component less dependent on the implementation of the others and makes it easier to replace individual components with improved versions without having to redesign the entire system. To illustrate the independence of the text-handling components, considersome of the operations that are possible using different subsets of the text system: ● Using only an NSTextStorage object, you can search text forspecific characters,strings, paragraph styles, and so on. ● Using only an NSTextStorage object, you can programmatically operate on the text without incurring the overhead of laying it out for display. ● Using all the components of the text system except for an NSTextView object, you can calculate layout information, determine where line breaks occur, figure the total number of pages, and so forth. The layering of the text system reduces the amount you have to learn to accomplish common text-handling tasks. In fact, many applications interact with the system solely through the API of the NSTextView class. Creating Text System Objects There are two standard ways to create an object web of the four principal classes of the text system to handle text editing, layout, and display: in one case, the text view creates and owns the other objects; in the other case, you create all the objects explicitly and the text storage owns them. Text View Creates the Objects You create and maintain a reference to an NSTextView object which automatically creates, interconnects, and owns the other text system objects. The majority of Cocoa apps use this technique and interact with the text system at a high level through NSTextView. You can create a text view and have it create the other text objects using Interface Builder, the graphical interface editor of Xcode, or you can do the same thing programmatically. Text System Organization MVC and the Text System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23To create the text view object in Interface Builder, drag a Text View from the Object library onto your app window. When your app launches and its nib file is loaded, it instantiates an NSTextView object and embeds it in a scroll view. Behind the scenes, the text view object automatically instantiates and manages NSTextContainer, NSLayoutManager, and NSTextStorage objects. To create the text view object programmatically and let it create and own the other objects, use the NSTextView initialization method initWithFrame:. The text view ownership technique is the easiest and cleanest way to set up the text system object web. However, it creates a single flow of text which does not support pagination or complex layouts, as described in “Common Configurations” (page 26). For other configurations you must create the objects explicitly. Your App Creates the Objects Explicitly You create all four text objects explicitly and connect them together, maintaining a reference only to the NSTextStorage object. The text storage object then owns and manages the other text objects in the web. To create the text system objects explicitly and connect them together, use the steps shown in this section. This code could reside in the implementation of the applicationDidFinishLaunching: notification method of the app delegate, for example. It assumesthat textStorage is an instance variable of the delegate object. It also assumes that window and windowView are properties of the app delegate representing outlets to the app’s main window and its content view. 1. Create an NSTextStorage object in the normal way using the alloc and init… messages. When you create the text system explicitly, you need to keep a reference only to this NSTextStorage object. The other objects of the system are owned by the text storage object, and they are released automatically by the system. textStorage = [[NSTextStorage alloc] initWithString:@"Here's to the ones who see things different."]; 2. Create an NSLayoutManager object and connect it to the text storage object. The layout manager needs a number of supporting objects—such as those that help it generate glyphs or position text within a text container—for its operation. It automatically createsthese objects(or connects to existing ones) upon initialization. NSLayoutManager *layoutManager; layoutManager = [[NSLayoutManager alloc] init]; Text System Organization Creating Text System Objects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24[textStorage addLayoutManager:layoutManager]; 3. Create an NSTextContainer object, initialize it with a size, and connect it to the layout manager. The size of the text container isthe size of the view in which it is displayed—in this case self.windowView is the content view of the app’s main window. Once you’ve created the text container, you add it to the list of containers that the layout manager owns. If your app has multiple text containers, you can create them and add them in this step, or you can create them lazily as needed. NSTextContainer *textContainer; textContainer = [[NSTextContainer alloc] initWithContainerSize:self.windowView.frame.size]; [layoutManager addTextContainer:textContainer]; 4. Create an NSTextView object, initialize it with a frame, and connect it to the text container. When you create the text system’s object web explicitly, you must use the initWithFrame:textContainer: method to initialize the text view. This initialization method does nothing more than initialize the receiver and set its text container (unlike initWithFrame:, which not only initializesthe receiver, but automatically creates and interconnectsits own web of textsystem objects). Each text view in the system is connected to its own text container. NSTextView *textView; textView = [[NSTextView alloc] initWithFrame:self.windowView.frame textContainer:textContainer]; Once the NSTextView object has been initialized, you make it the content view of the window, which is then displayed. The makeFirstResponder: message makesthe text view key,so that it accepts keystroke events. [self.window setContentView:textView]; [self.window makeKeyAndOrderFront:nil]; [self.window makeFirstResponder:textView]; For simplicity, this code puts the text view directly into the window’s content view. More commonly, text views are placed inside scroll views, as described in “Putting an NSTextView Object in an NSScrollView”. Text System Organization Creating Text System Objects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25Common Configurations The following diagrams give you an idea of how you can configure objects of the four primary text system classes—NSTextStorage, NSLayoutManager, NSTextContainer, and NSTextView—to accomplish different text-handling goals. To display a single flow of text, arrange the objects as shown in Figure 3-3. Figure 3-3 Text object configuration for a single flow of text With one NSTextView, all of the text flows within a single, typically rectangular, area. NSTextStorage NSLayoutManager NSTextContainer NSTextView The NSTextView object providesthe view that displaysthe glyphs, and the NSTextContainer object defines an area within that view where the glyphs are laid out. Typically in this configuration, the NSTextContainer object’s vertical dimension is declared to be some extremely large value so that the container can accommodate any amount of text, while the NSTextView object is set to size itself around the text using the setVerticallyResizable: method defined by NSText, and given a maximum height equal to the NSTextContainer object’s height. Then, with the text view embedded in an NSScrollView object, the user can scroll to see any portion of this text. If the text container’s area is inset from the text view’s bounds, a margin appears around the text. The NSLayoutManager object, and other objects not pictured here, work together to generate glyphs from the NSTextStorage object’s data and lay them out within the area defined by the NSTextContainer object. This configuration islimited by having only one NSTextContainer-NSTextView pair. In such an arrangement, the text flows uninterrupted within the area defined by the NSTextContainer. Page breaks, multicolumn layout, and more complex layouts can’t be accommodated by this arrangement. Text System Organization Common Configurations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26By using multiple NSTextContainer-NSTextView pairs, more complex layout arrangements are possible. For example, to support page breaks, an application can configure the text objects as shown in Figure 3-4. Figure 3-4 Text object configuration for paginated text As text is added, it fills the region defined by the first NSTextContainer. The text is displayed in the NSTextView that is paired with the NSTextContainer. When there's no more room, another NSTextContainer (and associated NSTextView) is added, and the text flows onto the second page. NSTextStorage NSLayoutManager NSTextContainer NSTextView NSTextContainer NSTextView Each NSTextContainer-NSTextView pair corresponds to a page of the document. The blue rectangle in Figure 3-4 represents a custom view object that your application provides as a background for the NSTextView objects. This custom view can be embedded in an NSScrollView object to enable the user to scroll through the document’s pages. A multicolumn document uses a similar configuration, as shown in Figure 3-5. Figure 3-5 Text object configuration for a multicolumn document With multiple text views and containers, text can flow in more complex layouts, such as in paginated documents having multiple columns. As a column fills with text, a new column is added. When the second column on the page is filled, a new page is added. NSTextStorage NSLayoutManager NSTextContainer NSTextView NSTextContainer NSTextView NSTextContainer NSTextView NSTextContainer NSTextView Text System Organization Common Configurations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27Instead of having one NSTextView-NSTextContainer pair correspond to a single page, there are now two pairs—one for each column on the page. Each NSTextContainer-NSTextView pair controls a portion of the document. As the text is displayed, glyphs are first laid out in the top-left view. When there is no more room in that view, the NSLayoutManager object informs its delegate that it has finished filling the container. The delegate can check whether there’s more text that needs to be laid out and add another NSTextContainer and NSTextView if necessary. The NSLayoutManager object proceeds to lay out text in the next container, notifies the delegate when finished, and so on. Again, a custom view (depicted as a blue rectangle) provides a canvas for these text columns. Not only can you have multiple NSTextContainer-NSTextView pairs, you can also have multiple NSLayoutManager objects accessing the same text storage. Figure 3-6 illustrates the simplest arrangement with multiple layout managers. Figure 3-6 Text object configuration for multiple views of the same text NSTextStorage NSTextView NSTextContainer NSTextView Multiple NSLayoutManagers allow you to have multiple presentations of the same text. The text within eachview can have separate layout and selections. Multiple NSLayoutManagers allow you to have multiple presentations of the same text. The text within each view can have separate layout and selections. NSLayoutManager NSLayoutManager NSTextContainer The effect of this arrangement is to give multiple views on the same text. If the user alters the text in the top view, the change is immediately reflected in the bottom view (assuming the location of the change is within the bottom view’s bounds). Text System Organization Common Configurations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Finally, complex page layout requirements, such as permitting text to wrap around embedded graphics, can be achieved by a configuration that uses a custom subclass of NSTextContainer. This subclass defines a region that adapts its shape to accommodate the graphic image and uses the object configuration shown in Figure 3-7. Figure 3-7 Text object configuration with custom text containers NSTextStorage NSLayoutManager NSTextContainer NSTextView NSTextContainer NSTextView The text container defines a region that wraps around the embedded graphic. A custom view is the super view for each of the NSTextViews. It both arranges the NSTextViews as pages and detects when the graphic has moved. When a graphic is moved or added, the text container must adapt its shape to accommodate the new placement. See Text Layout Programming Guide for information about how the text system lays out text. Text System Organization Common Configurations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29Text fields, text views, and the field editor are important objects in the Cocoa text system because they are central to the user’s interaction with the system. They provide text entry, manipulation, and display. If your application deals in any way with user-entered text, you should understand these objects. Text Fields A text field is a user interface control object instantiated from the NSTextField class. Figure 4-1 shows a text field. Text fields display small amounts of text, typically (although not necessarily) a single line. Text fields provide places for users to enter text responses, such as search parameters. Like all controls, a text field has a target and an action, and it performs validation on its value when edited. If the value isn’t valid, it sends a special error action message to its target. Figure 4-1 A text field A text field is implemented by two classes: NSTextFieldCell, the cell which does most of the work, and NSTextField, the control that contains that cell. Every method in NSTextFieldCell has a cover in NSTextField. (A cover is a method of the same name that callsthe original method.) An NSTextField object can have a delegate that responds to such delegate methods as textShouldEndEditing:. By default, text fields send their action message when editing ends—that is, when the user presses Return or moves focus to another control. You can control a text field’s shape and layout, the font and color of its text, background color, whether the text is editable or read-only, whether it is selectable or not (if read-only), and whether the text scrolls or wraps when the text exceeds the text field’s visible area. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30 Text Fields, Text Views, and the Field EditorTo create a secure text field for password entry, use NSSecureTextField, a subclass of NSTextField. Secure text fields display bullets in place of characters entered by the user, and they do not allow cutting or copying of their contents. You can get the text field’s value using the stringValue method, but users have no access to the value. See “Why Use a Custom Field Editor?” (page 66) for information about the implementation of secure text fields. The usual way to instantiate a text field is to drag an NSTextField or NSSecureTextField object from the Interface Builder objects library and place it in a window of your application’s user interface. You can link text fields together in their window’s key view loop by setting each field’s nextKeyView outlet in the Connections pane of the Inspector window, so that users can press Tab to move keyboard focus from one field to the next in the order you specify. Text Views Text views are user interface objects instantiated from the NSTextView class. Figure 4-2 shows a text view. Text viewstypically display multiple lines of text laid out in paragraphs with all the characteristics ofsophisticated typesetting. A text view is the main user interface to the Cocoa text-editing system. It handles user events to provide text entry and modification, and to display any font, including those of non-English languages, with arbitrary colors, styles, and other attributes. Figure 4-2 A text view The Cocoa text system supports text views with many other underlying objects providing text storage, layout, font and attribute manipulation, spell checking, undo and redo, copy and paste, drag and drop, saving of text to files, and other features. NSTextView is a subclass of NSText, which is a separate classfor historical reasons. You don’t instantiate NSText, although it declares many of the methods you use with NSTextView. When you put an NSTextView object in an NSWindow object, you have a full-featured text editor whose capabilities are provided “for free” by the Cocoa text system. Text Fields, Text Views, and the Field Editor Text Views 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31The Field Editor The field editor is a single NSTextView object that is shared among all the controls, including text fields, in a window. This text view object inserts itself into the view hierarchy to provide text entry and editing services for the currently active text field. When the user shifts focus to a text field, the field editor begins handling keystroke events and display for that field. Figure 4-3 illustrates the field editor in relation to the text field it is editing. Figure 4-3 The field editor NSTextView Field editor delegate Field editor becomes first responder while text field is being edited. NSTextField Because only one of the text fieldsin a window can be active at a time, the system needs only one NSTextView instance per window to be the field editor. However, you can substitute custom field editors, in which case there could be more than one field editor. Among its other duties, the field editor maintains the selection. Therefore, a text field that's not being edited typically does not have a selection at all. For more information about the field editor, see “Working with the Field Editor” (page 64). Text Fields, Text Views, and the Field Editor The Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32The Cocoa textsystem handlesfive kinds of text attributes: character attributes, temporary attributes, paragraph attributes, glyph attributes, and document attributes. Character attributes include traits such as font, color, and subscript, which can be associated with an individual character or a range of characters. Temporary attributes are character attributes that apply only to a particular layout and are not persistent. Paragraph attributes are traits such as indentation, tabs, and line spacing. Glyph attributes affect the way the layout manager renders glyphs and include traitssuch as overstriking the previous glyph. Document attributesinclude document-wide traits such as paper size, margins, and view zoom percentage. This chapter provides a brief introduction to the various types of text attributes with cross-references to more detailed documentation. Character Attributes The text system stores character attributes persistently in attributed strings along with the characters to which they apply. The text system’s predefined character attributes control the appearance of characters (font, foreground color, background color, and ligature handling) and their placement (superscript, baseline offset, and kerning). Two special character attributes pertain to links and attachments. A link attribute pointsto a URL (encapsulated in an NSURL object) or any other object of your choice. An attachment attribute is associated with a special attachment character and points to an NSFileWrapper object containing the attached file or in-memory data. The predefined character attribute NSCharacterShapeAttributeName enables you to set a value for the character shape feature used in font rendering by Apple Type Services. This feature is currently used to specify traditional shapes in Chinese and Japanese scripts, but font developers could use it for other scripts as well. The predefined character attribute NSGlyphInfoAttributeName points to an NSGlyphInfo object that provides a means to override the standard glyph generation process and substitute a specified glyph over the attribute’s range. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33 Text AttributesStoring Character Attributes An attributed string stores character attributes as key-value pairs in NSDictionary objects. The key is an attribute name, represented by an identifier (an NSString constant) such as NSFontAttributeName. Figure 5-1 shows an attributed string with an attribute dictionary applied to a range within the string. Figure 5-1 The composition of an NSAttributedString object including its attributes dictionary NSForegroundColorAttributeName NSFontAttributeName This is a character string. NSString NSRange NSDictionary NSFont NSColor Conceptually, each character in an attributed string has an associated dictionary of attributes. Typically, however, an attribute dictionary applies to a longer range of characters. The NSAttributedString class provides methods that take a character index and return the associated attribute dictionary and the range to which its attribute values apply. See “Accessing Attributes” for more information about using these methods. In addition to the predefined attributes, you can assign any attribute key-value pair you wish to a range of characters. You add the attributes to the appropriate character range in the NSTextStorage object using the NSMutableAttributedString method addAttribute:value:range:. You can also create an NSDictionary object containing the names and values of a set of custom attributes and add them to the character range in a single step using the addAttributes:range: method. To make use of your custom attributes, you need a custom subclass of NSLayoutManager that understands what to do with them. Your subclass should override the drawGlyphsForGlyphRange:atPoint: method first to call the superclass to draw the glyph range, then draw your own attributes on top, or else draw the glyphs entirely your own way. Attribute Fixing Editing attributed strings can cause inconsistencies that must be cleaned up by attribute fixing. The AppKit extensionsto NSMutableAttributedString define fix...methodsto fix inconsistencies among attachment, font, and paragraph attributes. These methods ensure that attachments don’t remain after their attachment characters are deleted, that font attributes apply only to characters available in that font, and that paragraph attributes are consistent throughout paragraphs. See Attributed String Programming Guide for more details about character attributes and attribute fixing. Text Attributes Character Attributes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34Temporary Attributes Temporary attributes are character attributes that are not stored with an attributed string. Rather, the layout manager assigns temporary attributes during the layout process and uses them only when drawing the text. For example, you can use temporary attributes to underline misspelled words or color key words in a programming language. Temporary attributes affect only the appearance of text, not the way in which it islaid out. You store temporary attributes in an NSDictionary object using the same keys as regular character attributes, or using custom attribute names(if you have an NSLayoutManager subclassthat can handle them). Then you add the attributes using an NSLayoutManagermethod such as addTemporaryAttributes:forCharacterRange:. By default, the only temporary attributes recognized are those affecting color and underlines. During layout, temporary attributes supersede regular character attributes. So, for example, if a character has a stored NSForegroundColorAttributeName value specifying blue and a temporary attribute of the same identifier specifying red, then the character is rendered in red. For more information on temporary attributes, see NSLayoutManager Class Reference . Paragraph Attributes Paragraph attributes affect the way the layout manager arranges lines of text into paragraphs on a page. The text system encapsulates paragraph attributes in objects of the NSParagraphStyle class. The value of one of the predefined character attributes, NSParagraphStyleAttributeName, pointsto an NSParagraphStyle object containing the paragraph attributes for that character range. Attribute fixing ensures that only one NSParagraphStyle object pertains to the characters throughout each paragraph. Paragraph attributes include traits such as alignment, tab stops, line-breaking mode, and line spacing (also known as leading). Users of text applications control paragraph attributes through ruler views, defined by the NSRulerView class. See Ruler and Paragraph Style Programming Topics for more details about paragraph attributes. Glyph Attributes Glyphs are the concrete representations of characters that the text system actually draws on a display. Glyph attributes are not complex data structureslike character attributes but are simply integer valuesthat the layout manager uses to denote special handling for particular glyphs during rendering. Text Attributes Temporary Attributes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35The text system uses glyph attributes rarely, and applications should have little reason to be concerned with them. Nonetheless, NSLayoutManager provides public methods that handle glyph attributes, so you can use subclasses to extend the mechanism to handle custom glyph attributes if necessary. The glyph generatorsets built-in glyph attributes asrequired on glyphs during typesetting. They are maintained in the layout manager’s glyph cache during that process, but they are not stored persistently. Two examples of glyph attributes are the elastic attribute for spaces, used to lay out fully justified text, and the attribute NSGlyphAttributeInscribe, which is used forsituationssuch as drawing an umlaut over a character when the font does not include a built-in character-with-umlaut. For more information about glyph attributes, see the description of the setIntAttribute:value:forGlyphAtIndex: method in NSLayoutManager Class Reference . Document Attributes Document attributes pertain to a document as a whole. Document attributes include traits such as paper size, margins, and view zoom percentage. Although the text system has no built-in mechanism to store document attributes, initialization methods such as initWithRTF:documentAttributes: can populate an NSDictionary object that you provide with document attributes derived from a stream of RTF or HTML data. Conversely, methods that write RTF data, such as RTFFromRange:documentAttributes:, write document attributes if you pass a reference to an NSDictionary object containing them with the message. See “RTF Files and Attributed Strings” and NSAttributedString Application Kit Additions Reference for more information. Text Attributes Document Attributes 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36This chapter explains how the Cocoa text system deals with fonts. It explains how to use the Font panel in your application, how to work directly with font objects, and how to work with the font manager. The Font Panel The Font panel, also called the Fonts window, is a user interface object that displays a list of available font families and styles, letting the user preview them and change the font used to display text. Text objects, such as NSTextView, work with NSFontPanel and NSFontManager objects to implement the AppKit’s font conversion system. By default, a text object keeps the Font panel updated with the first font in its selection, or with its typing attributes. It also changes the font in which it displays text in response to messages from the Font panel and Font menu. Such changes apply to the selected text or typing attributes for a rich text object or to all the text in a plain text object. NSFontManager is the hub for font conversion—that is, changing the traits of a font object, such as its size or typeface. The font manager receivesthe messagesfrom the Font panel and sends messages up the responder chain for action on the text objects. Normally, an application’s Font panel displays all the standard fonts available on the system. If this isn’t appropriate for your application—for example, if only fixed-pitch fonts should be used—you can assign a delegate to the NSFontPanel object to filter the available fonts. Before the NSFontPanel object adds a particular font family or face to its list, the NSFontPanel object asks its delegate to confirm the addition by sending the delegate a fontManager:willIncludeFont: message. If the delegate returns TRUE (or doesn’t implement this method), the font is added. If the delegate returns FALSE, the font isn’t added. This method must be invoked before the loading of the main nib file. Creating a Font Panel In general, you add the facilities of the Font panel to your application, along with the NSFontManager object and the Font menu, through which the user opens the Font panel, using Interface Builder. You do this by dragging a Font or Format menu (which contains a Font submenu) into one of your application’s menus. At runtime, the Font panel object is created and hooked into the font conversion system. You can also create (or access) the Font panel using the sharedFontPanel class method. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37 Font HandlingYou can add a custom view object to an NSFontPanel object using setAccessoryView:, allowing you to add custom controlsto the Font panel. You can also limit the fonts displayed (by default, all fonts are displayed) by assigning a delegate to the application’s font manager object. If you want the NSFontManager object to instantiate the Font panel from some class other than NSFontPanel, use the NSFontManager class method setFontPanelFactory:. See “Converting Fonts Manually” for more information on using the font conversion system. Using the Font Panel You can enable the interaction between a text object and the Font panel using the NSTextView (or NSText) method setUsesFontPanel: method. Doing so is recommended for a text view that serves as a field editor, for example. You can use the Font panel on objects other than standard text fields. The NSFontManager method setAction: sets the action (specified by a selector) that is sent up the first responder chain when a new font is selected. The default selector is changeFont:. Any object that receives this message from the responder chain should send a convertFont: message back to the NSFontManager to convert the font in a manner the user has specified. This example assumes there is only one font selected: – (void)changeFont:(id)sender { NSFont *oldFont = [self font]; NSFont *newFont = [sender convertFont:oldFont]; [self setFont:newFont]; return; } If multiple fonts are selected, changeFont: must send conversion messages for each selected font. This is useful for objects such as table views, which do not inherently respond to messages from the Font panel. Font Handling The Font Panel 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38Working with Font Objects You don’t create font objects using the alloc and init methods; instead, you use either fontWithName:matrix: or fontWithName:size: to look up an available font and alter its size or matrix to your needs. These methods check for an existing font object with the specified characteristics, returning it if there is one. Otherwise, they look up the font data requested and create the appropriate object. NSFont also defines a number of methodsforspecifying standard system fonts,such as systemFontOfSize:, userFontOfSize:, and messageFontOfSize:. To request the default size for these standard fonts, pass 0 or a negative number as the font size. The standard system font methods are listed in “Querying Standard Font Variations” (page 40). Querying Font Metrics NSFont defines a number of methods for accessing a font’s metrics information, when that information is available. Methods such as boundingRectForGlyph:, boundingRectForFont, xHeight, and so on, all correspond to standard font metrics information. Figure 6-1 shows how the font metrics apply to glyph dimensions, and Table 6-1 lists the method names that correlate with the metrics. See the various method descriptions for more specific information. Figure 6-1 Font metrics Advancement Ascent Line height Cap height X-height Descent Baseline Bounding Italic angle rectangle Line gap (leading) Origin Table 6-1 Font metrics and related NSFont methods Font metric Methods Advancement advancementForGlyph:, maximumAdvancement Font Handling Working with Font Objects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39Font metric Methods X-height xHeight Ascent ascender Bounding rectangle boundingRectForFont, boundingRectForGlyph: Cap height capHeight defaultLineHeightForFont, pointSize, labelFontSize, smallSystemFontSize, systemFontSize, systemFontSizeForControlSize: Line height Descent descender Italic angle italicAngle Querying Standard Font Variations Using the methods of NSFont listed in Table 6-2, you can query all of the standard font variations. To request the default font size for the standard fonts, you can either explicitly pass in default sizes (obtained from class methods such as systemFontSize and labelFontSize), or pass in 0 or a negative value. Table 6-2 Standard font methods Font Methods System font [NSFont systemFontOfSize:[NSFont systemFontSize]] Emphasized system font [NSFont boldSystemFontOfSize:[NSFont systemFontSize]] [NSFont systemFontOfSize:[NSFont smallSystemFontSize]] Small system font [NSFont boldSystemFontOfSize:[NSFont smallSystemFontSize]] Emphasized small system font [NSFont systemFontSizeForControlSize: NSMiniControlSize] Mini system font [NSFont boldSystemFontOfSize:[NSFont systemFontSizeForControlSize: NSMiniControlSize]] Emphasized mini system font Application font [NSFont userFontOfSize:-1.0] Font Handling Working with Font Objects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40Font Methods Application fixed-pitch font [NSFont userFixedPitchFontOfSize:-1.0] Label Font [NSFont labelFontOfSize:[NSFont labelFontSize]] Characters, Glyphs, and the Layout Manager Characters are conceptual entities that correspond to units of written language. Generally, a glyph is the concrete, rendered image of a character. (“Typographical Concepts” (page 12) presents a more detailed discussion of characters and glyphs.) In English, there’s often a one-to-one mapping between characters and glyphs, but that is not always the case. For example, the glyph “ö” can be the result of two characters, one representing the base character “o” and the other representing the umlaut diacritical mark “¨”. A user of a word processor can press an arrow key one time to move the insertion point from one side of the “ö” glyph to the other; however, the current position in the character stream must be incremented by two to account for the two characters that make up the single glyph. Thus, the text system must manage two related but different streams of data: the stream of characters (and their attributes) and the stream of glyphs that are derived from these characters. The NSTextStorage object stores the attributed characters, and the NSLayoutManager object stores the derived glyphs. Finding the correspondence between these two streams is the responsibility of the layout manager. For example, when a user selects a range of text, working with glyphs displayed on screen, the layout manager must determine which range of characters corresponds to the selection. When characters are deleted, some glyphs may have to be redrawn. For example, if the user deletes the characters “ee” from the word “feel”, then the “f” and “l” are now adjacent and can be represented by the “fl” ligature rather than the two glyphs “f” and “l”. The NSLayoutManager object directs a glyph generator object to generate new glyphs as needed. Once the glyphs are regenerated, the text must be laid out and displayed. Working with the NSTextContainer object and other objects of the text system, the layout manager determines where each glyph appears in the text view. Finally, the text view renders the text. Because an NSLayoutManager object is central to the operation of the text system, it also serves as the repository of information shared by various components of the system. For more information about NSLayoutManager, refer to NSLayoutManager Class Reference and to Text Layout Programming Guide . Font Handling Working with Font Objects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41Getting the View Coordinates of a Glyph Glyph locations are figured relative to the origin of the bounding rectangle of the line fragment in which they are laid out. To get the rectangle of the glyph’s line fragment in its container coordinates, use the NSLayoutManager method lineFragmentRectForGlyphAtIndex:effectiveRange:. Then add the origin of that rectangle to the location of the glyph returned by locationForGlyphAtIndex: to get the glyph location in container coordinates. The following code fragment from the CircleView sample code project illustrates this technique. usedRect = [layoutManager usedRectForTextContainer:textContainer]; NSRect lineFragmentRect = [layoutManager lineFragmentRectForGlyphAtIndex:glyphIndex effectiveRange:NULL]; NSPoint viewLocation, layoutLocation = [layoutManager locationForGlyphAtIndex:glyphIndex]; // Here layoutLocation is the location (in container coordinates) where the glyph was laid out. layoutLocation.x += lineFragmentRect.origin.x; layoutLocation.y += lineFragmentRect.origin.y; Working with the Font Manager Any object that recordsfontsthat the user can change should tell the font manager what the font of itsselection is whenever it becomes the first responder and whenever its selection changes while it’s the first responder. The object does so by sending the shared font manager a setSelectedFont:isMultiple: message. It should pass in the first font of the selection, along with a flag indicating whether there’s more than one font. The font manager uses this information to update the Font panel and Font menu to reflect the font in the selection. For example, suppose the font is Helvetica Oblique 12.0 point. In this case, the Font panel selects that font and displays its name; the Font menu adds a check mark before its Italic command; if there’s no Bold variant of Helvetica available, the Bold menu item is disabled; and so on. Creating a Font Manager You normally set up a font manager and the Font menu using Interface Builder. However, you can also do so programmatically by getting the shared font manager instance and having it create the standard Font menu at runtime, as in this example: NSFontManager *fontManager = [NSFontManager sharedFontManager]; Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42NSMenu *fontMenu = [fontManager fontMenu:YES]; You can then add the Font menu to your application’s menus. Once the Font menu isinstalled, your application automatically gains the functionality of both the Font menu and the Font panel. Handling Font Changes The user normally changes the font of the selection by manipulating the Font panel (also called the Fonts window) and the Font menu. These objects initiate the intended change by sending an action message to the font manager. There are four font-changing action methods: addFontTrait: removeFontTrait: modifyFont: modifyFontViaPanel: The first three cause the font manager to query the sender of the message in order to determine which trait to add or remove, or how to modify the font. The last causes the font manager to use the settings in the Font panel to modify the font. The font manager records this information and uses it in later requests to convert fonts. When the font manager receives an addFontTrait: or removeFontTrait: message, it queries the sender with a tag message, interpreting the return value as a trait mask for use with convertFont:toHaveTrait: or convertFont:toNotHaveTrait:, as described in “Converting Fonts Manually” (page 44). The Font menu commandsItalic and Bold, for example, have trait mask values of NSItalicFontMask and NSBoldFontMask, respectively. See the Constants section in NSFontManager Class Reference for a list of trait mask values. When the font manager receives a modifyFont: message, it queries the sender with a tag message and interprets the return value as a particular kind of conversion to perform, via the various conversion methods described in “Converting Fonts Manually” (page 44). For example, a button whose tag value is SizeUpFontAction causes the font manager’s convertFont: method to increase the size of the NSFont object passed as the parameter. See the NSFontManager method modifyFont: for a list of conversion tag values. For modifyFontViaPanel:, the font manager sends the application’s Font panel a panelConvertFont: message. The Font panel in turn uses the font manager to convert the font provided according to the user’s choices. For example, if the user selects only the font family in the Font panel (perhaps Helvetica), then for whatever fonts are provided to panelConvertFont:, only the family is changed: Courier Medium 10.0 point becomes Helvetica Medium 10.0 point, and Times Italic 12.0 point becomes Helvetica Oblique 12.0 point. Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43The font manager responds to a font-changing action method by sending a changeFont: action message up the responder chain. A text-bearing object that receivesthis message should have the font manager convert the fonts in its selection by invoking convertFont: for each font and using the NSFont object returned. The convertFont: method uses the information recorded by the font-changing action method, such as addFontTrait:, modifying the font provided appropriately. (There’s no way to explicitly set the font-changing action or trait; instead, you use the methods described in “Converting Fonts Manually” (page 44).) This simple example assumes there’s only one font in the selection: - (void)changeFont:(id)sender { NSFont *oldFont = [self selectionFont]; NSFont *newFont = [sender convertFont:oldFont]; [self setSelectionFont:newFont]; return; } Most text-bearing objects have to scan the selection for ranges with different fonts and invoke convertFont: for each one. Converting Fonts Manually NSFontManager defines a number of methods for explicitly converting particular traits and characteristics of a font. Table 6-3 lists these conversion methods. Table 6-3 Font conversion methods Methods Behavior Alters the basic design of the font provided. Requires a fully specified typeface name, such as “Times-Roman” or “Helvetica-BoldOblique”. convertFont:toFace: Alters the basic design of the font provided. Requires only a family name, such as “Times” or “Helvetica”. convertFont: toFamily: Uses a trait mask to add a single trait such as Italic, Bold, Condensed, or Extended. convertFont: toHaveTrait: Uses a trait mask to remove a single trait such as Italic, Bold, Condensed, or Extended. convertFont: toNotHaveTrait: Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44Methods Behavior Returns a font of the requested size, with all other characteristics the same as those of the original font. convertFont:toSize: Either increases or decreasesthe weight of the font provided, according to a Boolean flag. Font weights are typically indicated by a series of names, which can vary from font to font. Some go from Light to Medium to Bold, while others have Book, SemiBold, Bold, and Black. This method offers a uniform way of incrementing and decrementing any font’s weight. convertWeight: ofFont: Each method returns a transformed version of the font provided, or the original font if it can’t be converted. The default implementation of font conversion is very conservative, making a change only if no other trait or aspect is affected. For example, if you try to convert Helvetica Oblique 12.0 point by adding the Bold trait, and only Helvetica Bold is available, the font isn’t converted. You can create a subclass of NSFontManager and override the conversion methods to perform less conservative conversion, perhaps using Helvetica Bold in this case and losing the Oblique trait. In addition to the font-conversion methods, NSFontManager defines fontWithFamily:traits:weight:size: to construct a font with a given set of characteristics. If you don’t care to make a subclass of NSFontManager, you can use this method to perform approximate font conversions yourself. Setting Font Styles and Traits This section shows how to programmatically set font styles, such as bold or italic, and font attributes, such as underlining, in an attributed string. Underlining is an attribute that can be easily set on an attributed string, using the NSUnderlineStyleAttributeName constant, as explained in NSMutableAttributedString Class Reference . Use the following method: - (void)addAttribute:(NSString *)name value:(id)value range:(NSRange)aRange Pass NSUnderlineStyleAttributeName for the name parameter with a value of [NSNumber numberWithInt:1]. Unlike underlining, bold and italic are traits of the font, so you need to use a font manager instance to convert the font to have the desired trait, then add the font attribute to the mutable attributed string. For a mutable attributed string named attributedString, use the following technique: Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45NSFontManager *fontManager = [NSFontManager sharedFontManager]; unsigned idx = range.location; NSRange fontRange; NSFont *font; while (NSLocationInRange(idx, range)){ font = [attributedString attribute:NSFontAttributeName atIndex:idx longestEffectiveRange:&fontRange inRange:range]; fontRange = NSIntersectionRange(fontRange, range); [attributedString applyFontTraits:NSBoldFontMask range:fontRange]; idx = NSMaxRange(fontRange); } If your mutable attributed string is actually an NSTextStorage object, place this code between beginEditing and endEditing calls. Examining Fonts In addition to converting fonts, NSFontManager provides information on which fonts are available to the application and on the characteristics of any given font. The availableFonts method returns an array of the names of all fonts available. The availableFontNamesWithTraits: method filters the available fonts based on a font trait mask. There are three methods for examining individual fonts. The fontNamed:hasTraits: method returns true if the font matches the trait mask provided. The traitsOfFont: method returns a trait mask for a given font. The weightOfFont: method returns an approximate ranking of a font’s weight on a scale of 0–15, where 0 is the lightest possible weight, 5 is Normal or Book weight, 9 is the equivalent of Bold, and 15 is the heaviest possible (often called Black or Ultra Black). Customizing the Font Conversion System If you need to customize the font conversion systemby creating subclasses of NSFontManager or NSFontPanel, you must inform the NSFontManager class of this change with a setFontManagerFactory: or setFontPanelFactory: message, before either the shared font manager or shared Font panel is created. These methods record your class as the one to instantiate the first time the font manager or Font panel is requested. You may be able to avoid using subclasses if all you need is to add some custom controls to the Font panel. In this case, you can invoke the NSFontPanel method setAccessoryView: to add an NSView object below its font browser. Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46If you provide your own Font menu, you should register it with the font manager using the setFontMenu: method. The font manager is responsible for validating Font menu items and changing their titles and tags according to the selected font. For example, when the selected font is Italic, the font manager adds a check mark to the Italic Font menu item and changes its tag to UnitalicMask. Your Font menu’s items should use the appropriate action methods and tags, as shown in Table 6-4. Table 6-4 Font menu item actions and tags Font menu item Action Tag Italic addFontTrait: ItalicMask Bold addFontTrait: BoldMask Heavier modifyFont: HeavierFontAction Larger modifyFont: SizeUpFontAction See also the following documents: Attributed String Programming Guide describes NSAttributedString objects, which manage sets of attributes, such as font and kerning, that are associated with character strings or individual characters. Text Layout Programming Guide describes how the Cocoa textsystem convertsstrings of text characters, font information, and page specifications into lines of glyphs placed at specific locations on a page, suitable for display and printing. Font Handling Working with the Font Manager 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47This chapter describes ways in which you can control the behavior of the Cocoa text system as it performs text editing. Text editing isthe modification of text characters or attributes by interacting with text objects. Usually, editing is performed by direct user action with a text view, but it can also be accomplished by programmatic interaction with a text storage object. This document also discusses the text input system that translates keyboard events into commands and text input. The Cocoa text system implements a sophisticated editing mechanism that enables input and modification of complex text character and style information. It is important to understand this mechanism if your code needs to hook into it to modify that behavior. The text system provides a number of control points where you can customize the editing behavior: ● Text system classes provide methods to control many of the ways in which they perform editing. ● You can implement more control through the Cocoa mechanisms of notification and delegation. ● In extreme cases where the capabilities of the text system are not suitable, you can replace the text view with a custom subclass. The Editing Environment Text editing is performed by a text view object. Typically, a text view is an instance of NSTextView or a subclass. A text view provides the front end to the text system. It displays the text, handles the user events that edit the text, and coordinates changes to the stored text required by the editing process. NSTextView implements methods that perform editing, manage the selection, and handle formatting attributes affecting the layout and display of the text. NSTextView has a number of methods that control the editing behavior available to the user. For example, NSTextView allows you to grant or deny the user the ability to select or edit itstext, using the setSelectable: and setEditable: methods. NSTextView also implements the distinction between plain and rich text defined by NSText with its setRichText: and setImportsGraphics: methods. See Text System User InterfaceLayerProgrammingGuide ,NSTextViewClassReference ,andNSTextClassReference formoreinformation. An editable text view can operate in either of two distinct editing modes: as a normal text editor or as a field editor. A field editor is a single text view instance shared by many text fields belonging to a window in an application. This sharing results in a performance gain. When a text field becomes the first responder, the 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48 Text Editingwindow inserts the field editor in its place in the responder chain. A normal text editor accepts Tab and Return characters as input, whereas a field editor interprets Tab and Return as cues to end editing. The NSTextView method setFieldEditor: controls this behavior. See “Working with the Field Editor” (page 64) for more information about the field editor. The Key-Input Message Sequence When you want to modify the way in which Cocoa edits text, it’s helpful to understand the message sequence that definesthe editing mechanism,so you can select the most appropriate point at which to add your custom behavior. The message sequence invoked when a text view receives key events involves four methods declared by NSResponder. When the user presses a key, the operating system handles certain reserved key events and sends others to the NSApplication object, which handles Command-key events as key equivalents. The key events not handled are sent by the application object to the key window, which processes key events mapped to keyboard navigation actions (such as Tab moving focus on the next view) and sends other key events to the first responder. Figure 7-1 illustrates this sequence. Figure 7-1 Key-event processing sendEvent: keyDown: Key press sendEvent: Control-key events First responder Command-key events Reserved key events NSWindow NSApplication OS Text Editing The Key-Input Message Sequence 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49If the first responder is a text view, the key event enters the text system. The key window sends the text view a keyDown: message with the event as its argument. The keyDown: method passes the event to handleEvent:, which sends the character input to the input context for key binding and interpretation. In response, the input context sends either insertText:replacementRange:, setMarkedText:selectedRange:replacementRange:, or doCommandBySelector: to the text view. Figure 7-2 illustrates the sequence of text-input event processing. Figure 7-2 Input context key binding and interpretation setMarkedText:selectedRange: replacementRange: or doCommandBySelector: or insertText:replacementRange: handleEvent: keyDown: First responder Key binding and marked text processing NSTextView NSTextInputContext Key-bindings dictionary The text input system uses a dictionary property list, called a key-bindings dictionary, to interpret keyboard events before passing them to the Input Method Kit framework for mapping to characters. During the processing of a keyboard event, the event passes through the NSMenu object, then to the first responder via the keyDown: method. The default implementation of the method provided by the NSResponder class propagates the message up the responder chain until an overridden keyDown: implementation stops the propagation. Typically, an NSResponder subclass can choose to process certain keys and ignore others (for example, in a game) or to send the handleEvent: message to its input context. Text Editing The Key-Input Message Sequence 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50The input context checksthe event to see if it matches any of the keystrokesin the user’s key-bindings dictionary. A key-bindings dictionary maps a keystroke (including its modifier keys) to a method name. For example, the default key-bindings dictionary maps ^d (Control-D) to the method name deleteForward:. If the keyboard event is in the dictionary, then the input context calls the text view’s doCommandBySelector: method with the selector associated with the dictionary entry. If the input context cannot match the keyboard event to an entry in the key-bindings dictionary, it passes the event to the Input Method Kit for mapping to characters. The standard key-bindings dictionary is in the file /System/Library/Frameworks/AppKit.framework/Resources/StandardKeyBinding.dict. You can override the standard dictionary entirely by providing a dictionary file at the path ~/Library/KeyBindings/DefaultKeyBinding.dict. However, defining customkey bindings dynamically (that is, while the application is running) is not supported. For more information about text-input key event processing, see ““Text System Defaults and Key Bindings”” in Cocoa Event Handling Guide . When the text view has enough information to specify an actual change to itstext, itsends an editing message to its NSTextStorage object to effect the change. The methodsthat change character and attribute information in the text storage object are declared in the NSTextStorage superclass NSMutableAttributedString, and they depend on the two primitive methods replaceCharactersInRange:withString: and setAttributes:range:. The text storage object then informs its layout managers of the change to initiate glyph generation and layout when necessary, and it posts notifications and sends delegate messages before and after processing the edits. For more information about the interaction of text view, textstorage, and layout manager objects, see Text Layout Programming Guide . Intercepting Key Events This section explains how to catch key events received by a text view so that you can modify the result. It also explains the message sequence that occurs when a text view receives a key event. You need to intercept key events, for example, if you want users to be able to insert a line-break character in a text field. By default, text fields hold only one line of text. Pressing either Enter or Return causes the text field to end editing and send its action message to its target, so you would need to modify the behavior. You may also wish to intercept key events in a text view to do something different from simply entering characters in the text being displayed by the view, such as changing the contents of an in-memory buffer. Text Editing Intercepting Key Events 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51In both circumstances you need to deal with the text view object, which is obvious for the text view case but less so for a text field. Editing in a text field is performed by an NSTextView object, called the field editor, shared by all the text fields belonging to a window. When a text view receives a key event, it sends the character input to the input context for key binding and interpretation. In response, the input context sends either insertText:replacementRange: or doCommandBySelector: to the text view, depending on whether the key event representstext to be inserted or a command to perform. The input context can also send the setMarkedText:selectedRange:replacementRange: message to set the marked text in the text view’s associated textstorage object. The message sequence invoked when a text view receives key eventsis described in more detail in “The Key-Input Message Sequence” (page 49). With the standard key bindings, an Enter or Return character causes the text view to receive doCommandBySelector: with a selector of insertNewline:, which can have one of two results. If the text view is not a field editor, the text view’s insertText:replacementRange: method inserts a line-break character. If the text view is a field editor, as when the user is editing a text field, the text view ends editing instead. You can cause a text view to behave in either way by calling setFieldEditor:. Although you could alter the text view’s behavior by subclassing the text view and overriding insertText:replacementRange: and doCommandBySelector:, a better solution is to handle the event in the text view’s delegate. The delegate can take control over user changes to text by implementing the textView:shouldChangeTextInRange:replacementString: method. To handle keystrokes that don’t insert text, the delegate can implement the textView:doCommandBySelector: method. To distinguish between Enter and Return, for example, the delegate can test the selector passed with doCommandBySelector:. If it is @selector(insertNewline:), you can send currentEvent to the NSApp object to make sure the event is a key event and, if so, which key was pressed. Text View Delegation Delegation provides a powerful mechanism for modifying editing behavior because you can implement methods in the delegate that can then perform editing commands in place of the text view, a technique called delegation of implementation . NSTextView gives its delegate this opportunity to handle a command by sending it a textView:doCommandBySelector: message whenever it receives a doCommandBySelector: message from the input context. If the delegate implements this method and returns YES, the text view does nothing further; if the delegate returns NO, the text view must try to perform the command itself. Text Editing Text View Delegation 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52Before a text view makes any change to its text, it sends its delegate a textView:shouldChangeTextInRange:replacementString: message, which returns a Boolean value. (As with all delegate messages, it sends the message only if the delegate implements the method.) This mechanism providesthe delegate with an opportunity to control all editing of the character and attribute data in the text storage object associated with the text view. Text View Delegate Messages and Notifications An NSTextView object can have a delegate that it informs of certain actions or pending changes to the state of the text. The delegate can be any object you choose, and one delegate can control multiple NSTextView objects(or multiple series of connected NSTextView objects). Figure 7-3 illustratesthe activity of the delegate of an NSTextView object receiving the delegate message textView:shouldChangeTextInRange:replacementString:. Figure 7-3 Delegate of an NSTextView object YES or NO textView: shouldChangeTextInRange: replacementString: Delegate can return NO to deny any changes to text or do other processing first and then return YES to allow the change. NSTextView Delegate NSTextDelegate Protocol Reference andNSTextViewDelegate Protocol Reference describe the delegatemessages the delegate can receive. The delegating object sends a message only if the delegate implements the method. All NSTextView objects attached to the same NSLayoutManager share the same delegate. Setting the delegate of one such text view setsthe delegate for all the others. Delegate messages passthe id of the sender as an argument. Note: For multiple NSTextView objects attached to the same NSLayoutManager object, the argument id is that of the notifying text view, which is the first NSTextView object for the shared NSLayoutManager object. This NSTextView object is responsible for posting notifications at the appropriate times. The notifications posted by NSTextView are: Text Editing Text View Delegate Messages and Notifications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53NSTextDidBeginEditingNotification NSTextDidEndEditingNotification NSTextDidChangeNotification NSTextViewDidChangeSelectionNotification NSTextViewWillChangeNotifyingTextViewNotification It is particularly important for observers to register for the last of these notifications. If a new NSTextView object is added at the beginning of a series of connected NSTextView objects, it becomes the new notifying text view. It doesn’t have access to which objects are observing its group of text objects, so it posts an NSTextViewWillChangeNotifyingTextViewNotification, which allows allthose observersto unregister themselvesfrom the old notifying text view and reregister themselves with the new one. For more information, see the description for this notification in NSTextView Class Reference . Text Field Delegation Text fields(that is, instances of NSTextField, as opposed to instances of NSTextView) can also use delegation to control their editing behavior. One way in which thisis done isfor the text field itself to designate a delegate. Typically, you do this in Interface Builder by Control-dragging from the text field object to the delegate object, but you can also do it at run time by sending the text field a setDelegate: message, for example, in an awakeFromNib method. The delegate must respond to the messages defined by the NSTextFieldDelegate protocol (which adoptsthe NSControlTextEditingDelegate protocol). In addition to the methods defined by the NSControlTextEditingDelegate protocol, a text field delegate can respond to the delegate methods of NSControl. As an example of how a text field’s delegate can control its editing behavior, you can disable text completion in a text field by having its delegate implement the delegate method control:textView:completions:forPartialWordRange:indexOfSelectedItem: simply to return nil. Another way in which you can customize editing behavior in a text field by delegation involves the field editor, an NSTextView object that handles the actual editing, in turn, for all the text fields in a window. The field editor automatically designates any text field it is editing asits delegate,so you can encapsulate special editing behavior for a text field with the text field itself by implementing the delegate methods defined by NSTextDelegate and NSTextViewDelegate protocols. For information about controlling the editing behavior of text fieldsthrough delegate messages and notificationssent by the field editor,see “Using Delegation and Notification with the Field Editor” (page 64). Text Editing Text Field Delegation 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54Synchronizing Editing The editing process involves careful synchronization of the complex interaction of various objects. The text system coordinates event processing, data modification, responder chain management, glyph generation, and layout to maintain consistency in the text data model. The system provides a rich set of notifications to delegates and observers to enable your code to interact with this logic, as described in “Text View Delegate Messages and Notifications” (page 53). Batch-Editing Mode If your code needsto modify the text backing store directly, you should use batch-editing mode; that is, bracket the changes between the NSMutableAttributedString methods beginEditing and endEditing. Although this bracketing is not strictly necessary, it’s good practice, and it’s important for efficiency if you’re making multiple changes in succession. NSTextView uses the beginEditing and endEditing methods to synchronize its editing activity, and you can use the methods directly to control the timing of notifications to delegates, observers, and associated layout managers. When the NSTextStorage object is in batch-editing mode, it refrains from informing its layout managers of any editing changes until it receives the endEditing message. The “beginning of editing” means that a series of modifications to the text backing store (NSTextStorage for text views and cell values for cells) is about to occur. Bracketing editing between beginEditing and endEditing locks down the text storage to ensure that text modifications are atomic transactions. The “end of editing” means that the backing store is in a consistent state after modification. In cells (such as NSTextFieldCell objects, which control text editing in text fields), the end of editing coincides with the field editor resigning first responder status, which triggers synchronization of the contents of the field editor and its parent cell. In addition, the text view sends NSTextDidEndEditingNotification when it completes modifying its backing store, regardless of its first responder status. For example, it sends out this notification when the Replace All button is clicked in the Find window, even if the text view is not the first responder. Important: Calling any of the layout manager’s layout-causing methods between beginEditing and endEditingmessagesraises anexception.NSLayoutManager Class Reference andtheNSLayoutManager.h header file indicate which methods cause layout. Listing 7-1 illustrates a situation in which the NSText method scrollRangeToVisible: forces layout to occur and raises an exception. Text Editing Synchronizing Editing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55Listing 7-1 Forcing layout [[myTextView textStorage] beginEditing]; [[myTextView textStorage] replaceCharactersInRange:NSMakeRange(0,0) withString:@"Hello to you!"]; [myTextView scrollRangeToVisible:NSMakeRange(0,13)]; //BOOM [[myTextView textStorage] endEditing]; Scrolling a character range into visibility requires layout to be complete through that range so the text view can know where the range is located. But in Listing 7-1, the text storage is in batch-editing mode. It is in an inconsistent state, so the layout manager has no way to do layout at this time. Moving the scrollRangeToVisible: call after endEditing would solve the problem. There are additional actions that you should take if you implement new user actions in a text view, such as a menu action or key binding method that changes the text. For example, you can modify the selected range of characters using the NSTextView method setSelectedRange:, depending on the type of change performed by the command, using the results of the NSTextView methods rangeForUserTextChange, rangeForUserCharacterAttributeChange, or rangeForUserParagraphAttributeChange. For example, rangeForUserParagraphAttributeChange returnsthe entire paragraph containing the original selection—that is the range affected if your action modifies paragraph attributes. Also, you should call textView:shouldChangeTextInRange:replacementString: before you make the change and didChangeText afterwards. These actions ensure that the correct text gets changed and the system sends the correct notifications and delegate messagesto the text view’s delegate. See “Subclassing NSTextView” (page 58) for more information. Forcing the End of Editing There may be situations in which you need to force the text system to end editing programmatically so you can take some action dependent on notifications being sent. In such a case, you don’t need to modify the editing mechanism but simply stimulate its normal behavior. To force the end of editing in a text view, which subsequently sends a textDidEndEditing: message to its delegate, you can observe the window’s NSWindowDidResignKeyNotification notification. Then, in the observer method, send makeFirstResponder: to the window to finish any editing in progress while the window was active. Otherwise, the control that is currently being edited remains the first responder of the window and does not end editing. Listing 7-2 presents an implementation of the textDidEndEditing: delegate method that ends editing in an NSTableView subclass. By default, when the user is editing a cell in a table view and presses Tab or Return, the field editor ends editing in the current cell and begins editing the next cell. In this case, you want to end Text Editing Synchronizing Editing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56editing altogether if the user presses Return. This method distinguishes which key the user pressed; for Tab it does the normal behavior, and for Return it forces the end of editing completely by making the window first responder. Listing 7-2 Forcing the end of editing - (void)textDidEndEditing:(NSNotification *)notification { if([[[notification userInfo] valueForKey:@"NSTextMovement"] intValue] == NSReturnTextMovement) { NSMutableDictionary *newUserInfo; newUserInfo = [[NSMutableDictionary alloc] initWithDictionary:[notification userInfo]]; [newUserInfo setObject:[NSNumber numberWithInt:NSIllegalTextMovement] forKey:@"NSTextMovement"]; notification = [NSNotification notificationWithName:[notification name] object:[notification object] userInfo:newUserInfo]; [super textDidEndEditing:notification]; [[self window] makeFirstResponder:self]; } else { [super textDidEndEditing:notification]; } } Setting Focus and Selection Programmatically Usually the user clicks a view object in a window to set the focus, or first responder status, so that subsequent keyboard events go to that object initially. Likewise, the user usually creates a selection by dragging the mouse in a view. However, you can set both the focus and the selection programmatically. For example, if you have a window that contains a text view, and you want that text view to become the first responder with the insertion point located at the beginning of any text currently in the text view, you need a reference to the window and the text view. If those references are theWindow and theTextView, respectively, you can use the following code to set the focus and the insertion point, which is simply a zero-length selection range: [theWindow makeFirstResponder: theTextView]; [theTextView setSelectedRange: NSMakeRange(0,0)]; Text Editing Synchronizing Editing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 57When an object conforming to the NSTextInputClient protocol becomes the first responder in the key window, its NSTextInputContext object becomes active and bound to the active text input sources, such as character palette, keyboards, and input methods. Whether the selection was set programmatically or by the user, you can get the range of characters currently selected using the selectedRange method. NSTextView indicates its selection by applying a special set of attributes to it. The selectedTextAttributes method returns these attributes, and setSelectedTextAttributes: sets them. While changing the selection in response to user input, an NSTextView object invokes its own setSelectedRange:affinity:stillSelecting: method. The first parameter is the range to select. The second, called the selection affinity, determines which glyph the insertion point displays near when the two glyphs defining the selected range are not adjacent. It’s typically used where the selected lines wrap to place the insertion point at the end of one line or the beginning of the following line. You can get the selection affinity currently in effect using the selectionAffinity method. The last parameter indicates whether the selection is still in the process of changing; the delegate and any observers aren’t notified of the change in the selection until the method is invoked with NO for this argument. Another factor affecting selection behavior is the selection granularity: whether characters, words, or whole paragraphs are being selected. This is usually determined by the number of initial mouse clicks; for example, a double click initiates word-level selection. NSTextView decides how much to change the selection during input tracking using its selectionRangeForProposedRange:granularity: method. An additional aspect of selection, related to input management, is the range of marked text. As the input context interprets keyboard input, it can mark incomplete input in a special way. The text view displays this marked text differently from the selection, using temporary attributes that affect only display, not layout or storage. For example, NSTextView uses marked text to display a combination key, such as Option-E, which places an acute accent character above the character entered next. When the user types Option-E, the text view displays an acute accent in a yellow highlight box, indicating that it is marked text, rather than final input. When the user typesthe next character, the text view displaysit as a single accented character, and the marked text highlight disappears. The markedRange method returns the range of any marked text, and markedTextAttributes returns the attributes used to highlight the marked text. You can change these attributes using setMarkedTextAttributes:. Subclassing NSTextView Using NSTextView directly is the easiest way to interact with the text system, and its delegate mechanism provides an extremely flexible way to modify its behavior. In cases where delegation does not provide required behavior, you can subclass NSTextView. Text Editing Subclassing NSTextView 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 58Note: To modify editing behavior, your first resort should be to notification or delegation, rather than subclassing. It may be tempting to start by subclassing NSTextView and overriding keyDown:, but that’s usually not appropriate, unless you really need to deal with raw key events before input management or key binding. In most cases it’s more appropriate to work with one of the text view delegate methods or with text view notifications, as described in “Text View Delegate Messages and Notifications” (page 53). The text system requires NSTextView subclasses to abide by certain rules of behavior, and NSTextView provides many methods to help subclasses do so. Some of these methods are meant to be overridden to add information and behavior into the basic infrastructure. Some are meant to be invoked as part of that infrastructure when the subclass defines its own behavior. Updating State NSTextView automatically updates the Fonts window and ruler as its selection changes. If you add any new font or paragraph attributesto yoursubclass of NSTextView, you’ll need to override the methodsthat perform this updating to account for the added information. The updateFontPanel method makesthe Fonts window display the font of the first character in the selection. You could override this method to update the display of an accessory view in the Fonts window. Similarly, updateRuler causes the ruler to display the paragraph attributes for the first paragraph in the selection. You can also override this method to customize display of items in the ruler. Be sure to invoke the super implementation in your override to have the basic updating performed as well. Custom Import Types NSTextView supports pasteboard operations and the dragging of files and colorsinto itstext. If you customize the ability of your subclass to handle pasteboard operations for new data types, you should override the readablePasteboardTypes and writablePasteboardTypes methods to reflect those types. Similarly, to support new types of data for dragging operations, you should override the acceptableDragTypes method. Your implementation of these methods should invoke the superclass implementation, add the new data types to the array returned from super, and return the modified array. To read and write custom pasteboard types, you must override the readSelectionFromPasteboard:type: and writeSelectionToPasteboard:type: methods. In your implementation of these methods, you should read the new data types your subclass supports and let the superclass handle any other types. For dragging operations, if your subclass’s ability to accept your custom dragging types varies over time, you can override updateDragTypeRegistration to register or unregister the custom types according to the text view’s current status. By default this method enables dragging of all acceptable types if the receiver is editable and a rich text view. Text Editing Subclassing NSTextView 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 59Altering Selection Behavior Your subclass of NSTextView can customize the way selections are made for the various granularities (such as character, word, and paragraph) described in“Setting Focus and Selection Programmatically” (page 57). While tracking user changes to the selection, an NSTextView object repeatedly invokes selectionRangeForProposedRange:granularity: to determine what range to actually select. When finished tracking changes, it sends the delegate a textView:willChangeSelectionFromCharacterRange:toCharacterRange: message. By overriding the NSTextView method or implementing the delegate method, you can alter the way the selection is extended or reduced. For example, in a code editor you can provide a delegate that extends a double click on a brace or parenthesis character to its matching delimiter. These mechanisms aren’t meant for changing language word definitions (such as what’s selected by a double click). That detail of selection is handled at a lower (and currently private) level of the text system. Preparing to Change Text If you create a subclass of NSTextView to add new capabilities that will change the text in response to user actions, you may need to modify the range selected by the user before actually applying the change. For example, if the user is making a change to the ruler, the change must apply to whole paragraphs, so the selection may have to be extended to paragraph boundaries. Three methods calculate the range to which certain kinds of change should apply. The rangeForUserTextChange method returns the range to which any change to characters themselves—insertions and deletions—should apply. The rangeForUserCharacterAttributeChange method returns the range to which a character attribute change, such as a new font or color, should apply. Finally, rangeForUserParagraphAttributeChange returns the range for a paragraph-level change, such as a new or moved tab stop or indent. These methods all return a range whose location is NSNotFound if a change isn’t possible; you should check the returned range and abandon the change in this case. Text Change Notifications and Delegate Messages In actually making changesto the text, you must ensure that the changes are properly performed and recorded by different parts of the text system. You do this by bracketing each batch of potential changes with shouldChangeTextInRange:replacementString: and didChangeText messages. These methods ensure that the appropriate delegate messages are sent and notifications posted. The first method asks the delegate for permission to begin editing with a textShouldBeginEditing: message. If the delegate returns NO, shouldChangeTextInRange:replacementString: in turn returns NO, in which case your subclass should disallow the change. If the delegate returns YES, the text view posts an NSTextDidBeginEditingNotification, and shouldChangeTextInRange:replacementString: in Text Editing Subclassing NSTextView 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 60turn returns YES. In this case you can make your changesto the text, and follow up by invoking didChangeText. This method concludes the changes by posting an NSTextDidChangeNotification, which results in the delegate receiving a textDidChange: message. The textShouldBeginEditing: and textDidBeginEditing: messages are sent only once during an editing session. More precisely, they’re sent upon the first user input since the NSTextView became the first responder. Thereafter, these messages—and the NSTextDidBeginEditingNotification—are skipped in the sequence. The textView:shouldChangeTextInRange:replacementString: method, however, must be invoked for each individual change. Smart Insert and Delete NSTextView defines several methods to aid in “smart” insertion and deletion of text, so that spacing and punctuation are preserved after a change. Smart insertion and deletion typically applies when the user has selected whole words or othersignificant units of text. A smart deletion of a word before a comma, for example, also deletesthe space that would otherwise be left before the comma (though not placing it on the pasteboard in a Cut operation). A smart insertion of a word between another word and a comma adds a space between the two words to protect that boundary. NSTextView automatically uses smart insertion and deletion by default; you can turn this behavior off using setSmartInsertDeleteEnabled:. Doing so causes only the selected text to be deleted, and inserted text to be added, with no addition of white space. If your subclass of NSTextView defines any methods that insert or delete text, you can make them smart by taking advantage of two NSTextView methods. The smartDeleteRangeForProposedRange: method expands a proposed deletion range to include any white space that should also be deleted. If you need to save the deleted text, however, it’s typically best to save only the text from the original range. For smart insertion, smartInsertForString:replacingRange:beforeString:afterString: returns by reference two stringsthat you can insert before and after a given string to preserve spacing and punctuation. See the method descriptions for more information. Creating a Custom Text View A strategy even more complicated than subclassing NSTextView is to create your own custom text view object. If you need more sophisticated text handling than NSTextView provides, for example in a word processing application, it is possible to create a text view by subclassing NSView, implementing the NSTextInputClient protocol, and interacting directly with the input management system. Implementing Text Input Support Custom Cocoa views can provide varying levels ofsupport for the text inputsystem. There are essentially three levels of support to choose from: Text Editing Creating a Custom Text View 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 611. Override the keyDown: method. 2. Override keyDown: and use handleEvent: to support key bindings. 3. Also implement the full NSTextInputClient protocol. In the first level of support, the keyDown: method recognizes a limited set of events and ignores others. This level of support is typical of games. (When overriding keyDown:, you must also override acceptsFirstResponder to make your custom view respond to key events, as described in ““Event Handling Basics”” in Cocoa Event Handling Guide .) In the second level of support, you can override keyDown: and use the handleEvent: method to receive key-binding support without implementing the NSTextInputClient protocol. Because the NSView method inputContext does not instantiate NSTextInputContext automatically if the view does not conform to NSTextInputClient, the custom view must instantiate it manually. You then implement the standard key-binding methodsthat your view wantsto support,such as moveForward: or deleteForward:. (The full list of key-binding methods can be found in NSResponder.h.) If you are writing your own text view from scratch, you should use the third level of support and implement the NSTextInputClient protocol in addition to overriding keyDown: and using handleEvent:. NSTextView and its subclasses are the only classes provided in Cocoa that implement NSTextInputClient, and if your application needs more complex behavior than NSTextView can provide, as a word processor might, you may need to implement a text view from the ground up. To do this, you must subclass NSView and implement the NSTextInputClient protocol. (A class implementing this protocol—by inheriting from NSTextView or by implementing the protocol directly—is called a text view.) If you are implementing the NSTextInputClient protocol, your view needs to manage marked text and communicate with the text input context to support the text input system. These tasks are described in the next two sections. Managing Marked Text One of the primary thingsthat a text view must do to cooperate with an input context isto maintain a (possibly empty) range of marked text within its text storage. The text view should highlight text in this range in a distinctive way, and itshould allow selection within the marked text. A text view must also maintain an insertion point, which is usually at the end of the marked text, but the user can place it within the marked text. The text view also maintains a (possibly empty) selection range within its text storage, and if there is any marked text, the selection must be entirely within the marked text. Text Editing Creating a Custom Text View 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 62A common example of marked text appears when a user enters a character with multiple keystrokes, such as “é”, in an NSTextView object. To enter this character, the user needs to type Option-E followed by the E key. After pressing Option-E, the accent mark appears in a highlighted box, indicating that the text is marked (not final). After the final E is pressed, the “é” character appears and the highlight disappears. Communicating with the Text Input Context A text view and a text input context must cooperate so that the input context can implement its user interface. The NSTextInputContext class represents the interface to the text input system, that is, a state or context unique to its client object such as the key binding state, input method communication session, and so on. Most of the NSTextInputClient protocol methods are called by an input context to manipulate text within the text view for the input context’s user-interface purposes. Each NSTextInputClient-compliant object(typically an NSView subclass) hasits own NSTextInputContext instance. The default implementation of the NSView method inputContext manages an NSTextInputContext instance automatically if the view subclass conforms to the NSTextInputClient protocol. A text view must inform the current input manager when a mouse or keyboard event happens by sending the handleEvent: message to the current input context. When its marked text range is no longer needed, the text view sends a discardMarkedText message to the current input context. In addition, a text view must tell the input context when position information for a character range changes, such as when the text view scrolls, by sending the invalidateCharacterCoordinates message to the input context. The input context can then update information previously queried via methods like firstRectForCharacterRange:actualRange: when, for example, it wants to show a selection pop-up menu for marked text (as with a Japanese input method). There is an optional method, drawsVerticallyForCharacterAtIndex:, that can inform the text input system whether the protocol-conforming client renders the character at the given index vertically. The input context generally uses all of the methodsin the NSTextInputClient protocol. You can also register to receive a notification from the input context when the keyboard layout changes. For more information, refer to NSText Class Reference , NSTextView Class Reference , NSView Class Reference , NSTextInputContext Class Reference , and NSTextInputClient Protocol Reference . Text Editing Creating a Custom Text View 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 63Working with the Field Editor This section explains how the Cocoa text system uses the field editor and how you can modify that behavior. In most cases, you don’t need to be concerned about the field editor because Cocoa handles its operation automatically, behind the scenes. However, it’s good to know of its existence, and it’s possible that in some circumstances you could want to change its behavior. How the Field Editor Works The text system automatically instantiates the field editor from the NSTextView class when the user begins editing text of an NSControl object such as a text field. While it is editing, the system inserts the field editor into the responder chain as first responder, so it receives keystroke events in place of the text field or other control object. When the focus shifts to another text field, the field editor attaches itself to that field instead. The field editor designates the current text field as its delegate, which enables the text field to control changes to its contents. This mechanism can be confusing if you’re not familiar with the workings of the field editor, because the NSWindow method firstResponder returns the field editor, which is not visible, rather than the onscreen object that currently has keyboard focus. Among its other duties, the field editor maintains the selection for the text fields it edits. Therefore, a text field that's not being edited does not have a selection (unless you cache it). A field editor is defined by its treatment of certain characters during text input, which is different from an ordinary text view. An ordinary text view inserts a newline when the user presses Return or Enter, it inserts a tab character when the user presses Tab, and it ignores a Shift-Tab. In contrast, a field editor interprets these characters as cues to end editing and resign first responder status, shifting focus to the next object in the key-view loop (or in the case of Shift-Tab, the previous key view). The end of editing triggers synchronization of the contents of the field editor and the NSTextFieldCell object that controls editing in the text field. At that point Cocoa detaches the field editor from the text field and reveals the text field at the top of the view hierarchy. Using Delegation and Notification with the Field Editor One of the ways you can control the editing behavior of text fieldsis by interacting with the field editor through delegation and notification. Because the field editor automatically designates any text field it is editing as its delegate, you can often encapsulate special editing behavior for a text field with the text field itself. Changing Default Behavior It’s straightforward to change the default behavior of the field editor by implementing delegate methods. For example, the delegate can change the behavior that occurs when the user presses Return while editing a text view. By default, that action ends editing and selects the next control in the key view loop. If, for example, you Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 64want pressing Return to end editing but not select the next control, you can implement the textDidEndEditing: delegate method in the text field. The field editor automatically calls this method if the delegate implements it, and passes NSTextDidEndEditingNotification. The implementation can examine this notification to discover the event that ended editing and respond appropriately. Getting Newlines into an NSTextField Object Users can easily put newline characters into a text field by pressing Option-Return or Option-Enter. However, there may be situations in which you want to allow users to enter newlines without taking any special action, and you can do so by implementing a delegate method. The easiest approach isto call setFieldEditor:NO on the window'sfield editor. But, of course, this approach changes the behavior of the field editor for all controls. Another approach is to use the NSControl delegate message control:textShouldBeginEditing:, which issent to a text view’s delegate when the user enters a character into the text field. Because it passes references to both the text view and the field editor, you could test to see if the text view is one into which you want to enter newlines, then simply send setFieldEditor:NO to the field editor. However, this method is not called until after the user has entered one character into the text field, and if that character is a newline, it is rejected. A better method is to implement another NSControl delegate method, control:textView:doCommandBySelector:, which enables the text field’s delegate to check whether the user is attempting to insert a newline character and, ifso, force to field editor to insert it. The implementation could appear as shown in Listing 7-3. Listing 7-3 Forcing the field editor to enter a newline character - (BOOL)control:(NSControl *)control textView:(NSTextView *)fieldEditor doCommandBySelector:(SEL)commandSelector { BOOL retval = NO; if (commandSelector == @selector(insertNewline:)) { retval = YES; [fieldEditor insertNewlineIgnoringFieldEditor:nil]; } return retval; } Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 65This method returns YES to indicate that it handles this particular command and NO for other commands that it doesn’t handle. This approach has the advantage that it doesn’t change the setup of the field editor but handles just the special case of interest. Because the delegate message includes a reference to the control being edited, you could add a check to restrict the behavior to a particular class, such as NSTextField, or an individual subclass. Using a Custom Field Editor To customize behavior in ways that go beyond what the delegate can do, you need to define a subclass of NSTextView that incorporates yourspecialized behavior and substitute it for the window’s default field editor. Why Use a Custom Field Editor? It’s not necessary to use a custom field editor if you simply need to validate, interpret, format, or even edit the contents of text fields as the user types. You can attach an NSFormatter, such as NSNumberFormatter, NSDateFormatter, or a custom formatter, for that purpose. See Data Formatting Guide for more information about using formatters. Delegation and notification also provide many opportunities for you to intervene, as described in “Using Delegation and Notification with the Field Editor” (page 64). A secure text field is an example of truly specialized handling of data that goes beyond what can be reasonably handled by formatters or delegates. A secure text field must accept text data entered by the user and validate the entries, which are easily done with a regular text field and a formatter. But it must display some bogus characters to keep the real data secret while it preserves the real data for an authentication process or other purpose. Moreover, a secure text field must keep its data safe from unauthorized access by disabling features, such as copy and cut, and possibly encrypting the data. To implement these specialized requirements, it is easiest to deploy a custom field editor. In fact, Cocoa implements a custom field editor in the NSSecureTextField class. Any situation requiring unusual processing of data entered into a text field, or other individualized behavior not available through the standard Cocoa mechanisms, is a good candidate for a custom field editor. How to Substitute a Custom Field Editor You can substitute your custom field editor in place of the window’s default version by implementing the NSWindow delegate method windowWillReturnFieldEditor:toObject:. You implement this method in the window’s delegate, which could be, for example, the window controller object. The window sends this message to its delegate with itself and the object requesting the field editor as parameters. So, you can test the object and make substitution of your custom field editor dependent on the result. The window continues to use its default field editor for other controls. Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 66For example, the implementation shown in Listing 7-4 tests whether or not the requesting object isinstantiated from a custom text field class named CustomTextField, and, if it is, returns a custom field editor. Listing 7-4 Substituting a custom field editor - (id)windowWillReturnFieldEditor:(NSWindow *)sender toObject:(id)anObject { if ([anObject isKindOfClass:[CustomTextField class]]) { if (!myCustomFieldEditor) { myCustomFieldEditor = [[CustomFieldEditor alloc] init]; [myCustomFieldEditor setFieldEditor:YES]; } return myCustomFieldEditor; } return nil; } If the requesting object is not a custom text field orsubclass, the delegate method returns nil and the window uses its default field editor. This arrangement has the advantage that it does not instantiate the custom field editor unless it is needed. In OS X v10.6 and later, another way of providing a custom field editor is to override the NSCell method fieldEditorForView:. This method, rather than the window delegate method, is more suitable for custom cell subclasses. You can find more information about subclassing NSTextView in “Subclassing NSTextView” (page 58). Field Editor–Related Methods This section lists the AppKit methods most directly related to the field editor. You can peruse these tables to understand where Cocoa provides opportunities for you to interact with the field editor. Refer to Application Kit Framework Reference for details. The NSWindow methods related to the field editor are listed in Table 7-1. Table 7-1 NSWindow field editor–related methods Method Description fieldEditor: forObject: Returns the receiver’s field editor, creating it if needed. Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 67Method Description Forces the field editor to give up its first responder status and prepares it for its next assignment. endEditingFor: Delegate method invoked when the field editor of sender is requested by an object. If the delegate’s implementation of this method returns an object other than nil, NSWindow substitutes it for the field editor. windowWillReturnFieldEditor: toObject: The NSTextFieldCell method related to the field editor is listed in Table 7-2. Table 7-2 NSTextFieldCell field editor–related method Method Description You never invoke this method directly; by overriding it, however, you can customize the field editor. setUpFieldEditorAttributes: The NSCell methods related to the field editor are listed in Table 7-3. Table 7-3 NSCell field editor–related methods Method Description The primary way to substitute a custom field editor in OS X v10.6 and later. fieldEditorForView: Uses the field editor passed with the message to select text in a range. selectWithFrame: inView:editor: delegate:start: length: Begins editing of the receiver’s text using the field editor passed with the message. editWithFrame: inView:editor: delegate:event: Ends any editing of text, using the field editor passed with the message, begun with either of the other two NSCell field editor–related methods. endEditing: The NSControl methods related to the field editor are listed in Table 7-4. The NSControl delegate methods listed in Table 7-4 are control-specific versions of the delegate methods and notifications defined by NSText. The field editor, derived from NSText, initiates sending the delegate messages and notifications through its editing actions. Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 68Table 7-4 NSControl field editor–related methods Method Description Terminates and discards any editing of text displayed by the receiver and removes the field editor’s delegate. abortEditing If the receiver is being edited, this method returns the field editor; otherwise, it returns nil. currentEditor Sets the object value of the text in a cell of the receiving control to the current contents of the cell’s field editor. validateEditing Sent directly to the delegate when the user triesto enter a character in a cell of the control passed with the message. control: textShouldBeginEditing: Sent directly to the delegate when the insertion point tries to leave a cell of the control that has been edited. control: textShouldEndEditing: Sent by the default notification center to the delegate (and all observers of the notification) when a control begins editing text, passing NSControlTextDidBeginEditingNotification. controlTextDidBeginEditing: Sent by the default notification center to the delegate and observers when the text in the receiving control changes, passing NSControlTextDidChangeNotification. controlTextDidChange: Sent by the default notification center to the delegate and observers when a control ends editing text, passing NSControlTextDidEndEditingNotification. controlTextDidEndEditing: The NSResponder methods related to the field editor are listed in Table 7-5. Table 7-5 NSResponder field editor–related methods Method Description insertBacktab: Implemented by subclasses to handle a “backward tab.” Implemented by subclasses to insert a line-break character at the insertion point or selection. insertNewlineIgnoringFieldEditor: Implemented by subclasses to insert a tab character at the insertion point or selection. insertTabIgnoringFieldEditor: The NSText and NSTextDelegate methods related to the field editor are listed in Table 7-6. Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 69Table 7-6 NSText field editor–related methods Method Description Returns YES if the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder; NO if it accepts them as text input. isFieldEditor Controls whether the receiver interprets Tab, Shift-Tab, and Return (Enter) as cues to end editing and possibly to change the first responder. setFieldEditor: Informs the delegate that the user has begun changing text, passing NSTextDidBeginEditingNotification. textDidBeginEditing: Informs the delegate that the text object has changed its characters or formatting attributes, passing NSTextDidChangeNotification. textDidChange: Informsthe delegate that the text object hasfinished editing (that it has resigned first responder status), passing NSTextDidEndEditingNotification. textDidEndEditing: Invoked from a text object’s implementation of becomeFirstResponder, this method requests permission to begin editing. textShouldBeginEditing: Invoked from a text object’s implementation of resignFirstResponder, this method requests permission to end editing. textShouldEndEditing: Text Editing Working with the Field Editor 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 70This table describes the changes to Cocoa Text Architecture Guide . Date Notes 2012-09-19 Added section on creating text objects programmatically. Fixed typo. 2012-07-23 Added section titled "Text Field Delegation" to "Text Editing" chapter. Removed out-of-date text editortutorial and section describing deprecated glyph-handling methods of NSFont. Removed references to manual reference counting. Fixed typos. 2012-04-27 Updated textsystem class hierarchy diagram and configuration diagrams. Additional legacy documents providing content to this document are Font Handling and Font Panel. 2010-05-04 New document that explains how the objects of the Cocoa text system interact. This document contains content previously published in the following documents, which remain in the legacy area of the ADC library: Text System Overview, Text Attributes, Text Editing Programming Guide for Cocoa, and Text Input and Output. 2010-03-23 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 71 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, Cocoa, Mac, Macintosh, Objective-C, OS X, QuickDraw, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Helvetica and Times are registered trademarks of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Smalltalk-80 is a trademark of ParcPlace Systems. 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. Key-Value Observing Programming GuideContents Introduction to Key-Value Observing Programming Guide 4 At a Glance 4 Registering for Key-Value Observing 7 Registering as an Observer 7 Receiving Notification of a Change 8 Removing an Object as an Observer 10 KVO Compliance 11 Automatic Change Notification 11 Manual Change Notification 12 Registering Dependent Keys 15 To-one Relationships 15 To-many Relationships 16 Key-Value Observing Implementation Details 19 Document Revision History 20 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 2Listings Registering for Key-Value Observing 7 Listing 1 Registering the inspector as an observer of the openingBalance property 7 Listing 2 Implementation of observeValueForKeyPath:ofObject:change:context: 9 Listing 3 Removing the inspector as an observer of openingBalance 10 KVO Compliance 11 Listing 1 Examples of method calls that cause KVO change notifications to be emitted 11 Listing 2 Example implementation of automaticallyNotifiesObserversForKey: 12 Listing 3 Example accessor method implementing manual notification 13 Listing 4 Testing the value for change before providing notification 13 Listing 5 Nesting change notifications for multiple keys 13 Listing 6 Implementation of manual observer notification in a to-many relationship 14 Registering Dependent Keys 15 Listing 1 Example implementation of keyPathsForValuesAffectingValueForKey: 15 Listing 2 Example implementation of the keyPathsForValuesAffecting naming convention 16 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 3Key-value observing is a mechanism that allows objects to be notified of changes to specified properties of other objects. Important: In order to understand key-value observing, you must first understand key-value coding. At a Glance Key-value observing provides a mechanism that allows objects to be notified of changes to specific properties of other objects. It is particularly useful for communication between model and controller layers in an application. (In OS X, the controller layer binding technology relies heavily on key-value observing.) A controller object typically observes properties of model objects, and a view object observes properties of model objects through a controller. In addition, however, a model object may observe other model objects (usually to determine when a dependent value changes) or even itself (again to determine when a dependent value changes). You can observe properties including simple attributes, to-one relationships, and to-many relationships. Observers of to-many relationships are informed of the type of change made—as well as which objects are involved in the change. There are three steps to setting up an observer of a property. Understanding these three steps provides a clear illustration of how KVO works. 1. First, see whether you have a scenario where key-value observing could be beneficial, for example, an object that needs to be notified when any changes are made to a specific property in another object. BankObject @property int accountBalance PersonObject For example, a PersonObject will want to be aware of any changes made to their accountBalance in the BankObject. 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 4 Introduction to Key-Value Observing Programming Guide2. The PersonObject must register as an observer of the BankObject’s accountBalance property by sending an addObserver:forKeyPath:options:context: message. BankObject PersonObject Connection established [bankInstance addObserver:personInstance forKeyPath:@"accountBalance" options:NSKeyValueObservingOptionNew context:NULL]; Note: The addObserver:forKeyPath:options:context:method establishes a connection between the instances of the objects that you specify. A connection is not established between the two classes, but rather between the two specified instances of the objects. 3. In order to respond to change notifications, the observer must implement the observeValueForKeyPath:ofObject:change:context: method. This method implementation defines how the observer responds to change notifications. It is in this method that you can customize your response to a change in one of the observed properties. BankObject PersonObject Connection established -(void) observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context { //custom implementation //be sure to call the superclass’ implementation //if the superclass implements it } “Registering for Key-Value Observing” (page 7) describes how to register and receive observation notifications. Introduction to Key-Value Observing Programming Guide At a Glance 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 54. The observeValueForKeyPath:ofObject:change:context: method is automatically invoked when the value of an observed property is changed in a KVO-compliant manner, or if a key upon which it depends is changed. BankObject PersonObject Automatically notifies person Person can react accordingly in customized method [bankInstance setAccountBalance:50]; “Registering Dependent Keys” (page 15) explains how to specify that the value of a key is dependent on the value of another key. KVO’s primary benefit is that you don’t have to implement your own scheme to send notifications every time a property changes. Its well-defined infrastructure has framework-level support that makes it easy to adopt—typically you do not have to add any code to your project. In addition, the infrastructure is already full-featured, which makes it easy to support multiple observers for a single property, as well as dependent values. “KVO Compliance” (page 11) describes the difference between automatic and manual key-value observing, and how to implement both. Unlike notifications that use NSNotificationCenter, there is no central object that provides change notification for all observers. Instead, notifications are sent directly to the observing objects when changes are made. NSObject provides this base implementation of key-value observing, and you should rarely need to override these methods. “Key-Value Observing Implementation Details ” (page 19) describes how key-value observing is implemented. Introduction to Key-Value Observing Programming Guide At a Glance 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 6In order to receive key-value observing notifications for a property, three things are required: ● The observed class must be key-value observing compliant for the property that you wish to observe. ● You must register the observing object with the observed object, using the method addObserver:forKeyPath:options:context:. ● The observing class must implement observeValueForKeyPath:ofObject:change:context:. Important: Not all classes are KVO-compliant for all properties. You can ensure your own classes are KVO-compliant by following the steps described in “KVO Compliance” (page 11). Typically properties in Apple-supplied frameworks are only KVO-compliant if they are documented as such. Registering as an Observer In order to be notified of changes to a property, an observing object must first register with the object to be observed by sending it an addObserver:forKeyPath:options:context: message, passing the observer object and the key path of the property to be observed. The options parameter specifies the information that is provided to the observer when a change notification is sent. Using the option NSKeyValueObservingOptionOld specifies that the original object value is provided to the observer as an entry in the change dictionary. Specifying the NSKeyValueObservingOptionNew option provides the new value as an entry in the change dictionary. To receive both values, you would bitwise OR the option constants. The example in Listing 1 demonstrates registering an inspector object for the property openingBalance. Listing 1 Registering the inspector as an observer of the openingBalance property - (void)registerAsObserver { /* Register 'inspector' to receive change notifications for the "openingBalance" property of the 'account' object and specify that both the old and new values of "openingBalance" should be provided in the observe… method. 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 7 Registering for Key-Value Observing*/ [account addObserver:inspector forKeyPath:@"openingBalance" options:(NSKeyValueObservingOptionNew | NSKeyValueObservingOptionOld) context:NULL]; } When you register an object as an observer, you can also provide a context pointer. The context pointer is provided to the observer when observeValueForKeyPath:ofObject:change:context: is invoked. The context pointer can be a C pointer or an object reference. The context pointer can be used as a unique identifier to determine the change that is being observed, or to provide some other data to the observer. Note: The key-value observing addObserver:forKeyPath:options:context: method does not maintain strong references to the observing object, the observed objects, or the context. You should ensure that you maintain strong references to the observing, and observed, objects, and the context as necessary. Receiving Notification of a Change When the value of an observed property of an object changes, the observer receives an observeValueForKeyPath:ofObject:change:context: message. All observers must implement this method. The observer is provided the object and key path that triggered the observer notification, a dictionary containing details about the change, and the context pointer that was provided when the observer was registered. The change dictionary entry NSKeyValueChangeKindKey provides information about the type of change that occurred. If the value of the observed object has changed, the NSKeyValueChangeKindKey entry returns NSKeyValueChangeSetting. Depending on the options specified when the observer was registered, the NSKeyValueChangeOldKey and NSKeyValueChangeNewKey entries in the change dictionary contain the values of the property before, and after, the change. If the property is an object, the value is provided directly. If the property is a scalar or a C structure, the value is wrapped in an NSValue object (as with key-value coding). Registering for Key-Value Observing Receiving Notification of a Change 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 8If the observed property is a to-many relationship, the NSKeyValueChangeKindKey entry also indicates whether objects in the relationship were inserted, removed, or replaced by returning NSKeyValueChangeInsertion, NSKeyValueChangeRemoval, or NSKeyValueChangeReplacement, respectively. The change dictionary entry for NSKeyValueChangeIndexesKey is an NSIndexSet object specifying the indexes in the relationship that changed. If NSKeyValueObservingOptionNew or NSKeyValueObservingOptionOld are specified as options when the observer is registered, the NSKeyValueChangeOldKey and NSKeyValueChangeNewKey entries in the change dictionary are arrays containing the values of the related objects before, and after, the change. The example in Listing 2 shows the observeValueForKeyPath:ofObject:change:context: implementation for an inspector that reflects the old and new values of the property openingBalance, as registered in Listing 1 (page 7). Listing 2 Implementation of observeValueForKeyPath:ofObject:change:context: - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context { if ([keyPath isEqual:@"openingBalance"]) { [openingBalanceInspectorField setObjectValue: [change objectForKey:NSKeyValueChangeNewKey]]; } /* Be sure to call the superclass's implementation *if it implements it*. NSObject does not implement the method. */ [super observeValueForKeyPath:keyPath ofObject:object change:change context:context]; } Registering for Key-Value Observing Receiving Notification of a Change 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 9Removing an Object as an Observer You remove a key-value observer by sending the observed object a removeObserver:forKeyPath: message, specifying the observing object and the key path. The example in Listing 3 removesthe inspector as an observer of openingBalance. Listing 3 Removing the inspector as an observer of openingBalance - (void)unregisterForChangeNotification { [observedObject removeObserver:inspector forKeyPath:@"openingBalance"]; } If the context is an object, you must keep a strong reference to it until removing the observer. After receiving a removeObserver:forKeyPath: message, the observing object will no longer receive any observeValueForKeyPath:ofObject:change:context: messagesfor the specified key path and object. Registering for Key-Value Observing Removing an Object as an Observer 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 10In order to be considered KVO-compliant for a specific property, a class must ensure the following: ● The class must be key-value coding compliant for the property, as specified in “Ensuring KVC Compliance”. KVO supports the same data types as KVC. ● The class emits KVO change notifications for the property. ● Dependent keys are registered appropriately (see “Registering Dependent Keys” (page 15)). There are two techniques for ensuring the change notifications are emitted. Automatic support is provided by NSObject and is by default available for all properties of a class that are key-value coding compliant. Typically, if you follow standard Cocoa coding and naming conventions, you can use automatic change notifications—you don’t have to write any additional code. Manual change notification provides additional control over when notifications are emitted, and requires additional coding. You can control automatic notifications for properties of your subclass by implementing the class method automaticallyNotifiesObserversForKey:. Automatic Change Notification NSObject provides a basic implementation of automatic key-value change notification. Automatic key-value change notification informs observers of changes made using key-value compliant accessors, as well as the key-value coding methods. Automatic notification is also supported by the collection proxy objects returned by, for example, mutableArrayValueForKey:. The examples shown in Listing 1 result in any observers of the property name to be notified of the change. Listing 1 Examples of method calls that cause KVO change notifications to be emitted // Call the accessor method. [account setName:@"Savings"]; // Use setValue:forKey:. [account setValue:@"Savings" forKey:@"name"]; 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 11 KVO Compliance// Use a key path, where 'account' is a kvc-compliant property of 'document'. [document setValue:@"Savings" forKeyPath:@"account.name"]; // Use mutableArrayValueForKey: to retrieve a relationship proxy object. Transaction *newTransaction = <#Create a new transaction for the account#>; NSMutableArray *transactions = [account mutableArrayValueForKey:@"transactions"]; [transactions addObject:newTransaction]; Manual Change Notification Manual change notification provides more granular control over how and when notifications are sent to observers. This can be useful to help minimize triggering notifications that are unnecessary, or to group a number of changes into a single notification. A class that implements manual notification must override the NSObject implementation of automaticallyNotifiesObserversForKey:. It is possible to use both automatic and manual observer notifications in the same class. For properties that perform manual notification, the subclass implementation of automaticallyNotifiesObserversForKey: should return NO. A subclassimplementation should invoke super for any unrecognized keys. The example in Listing 2 enables manual notification for the openingBalance property allowing the superclass to determine the notification for all other keys. Listing 2 Example implementation of automaticallyNotifiesObserversForKey: + (BOOL)automaticallyNotifiesObserversForKey:(NSString *)theKey { BOOL automatic = NO; if ([theKey isEqualToString:@"openingBalance"]) { automatic = NO; } else { automatic = [super automaticallyNotifiesObserversForKey:theKey]; } return automatic; } KVO Compliance Manual Change Notification 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 12To implement manual observer notification, you invoke willChangeValueForKey: before changing the value, and didChangeValueForKey: after changing the value. The example in Listing 3 implements manual notifications for the openingBalance property. Listing 3 Example accessor method implementing manual notification - (void)setOpeningBalance:(double)theBalance { [self willChangeValueForKey:@"openingBalance"]; _openingBalance = theBalance; [self didChangeValueForKey:@"openingBalance"]; } You can minimize sending unnecessary notifications by first checking if the value has changed. The example in Listing 4 tests the value of openingBalance and only provides the notification if it has changed. Listing 4 Testing the value for change before providing notification - (void)setOpeningBalance:(double)theBalance { if (theBalance != _openingBalance) { [self willChangeValueForKey:@"openingBalance"]; _openingBalance = theBalance; [self didChangeValueForKey:@"openingBalance"]; } } If a single operation causes multiple keysto change you must nest the change notifications asshown in Listing 5. Listing 5 Nesting change notifications for multiple keys - (void)setOpeningBalance:(double)theBalance { [self willChangeValueForKey:@"openingBalance"]; [self willChangeValueForKey:@"itemChanged"]; _openingBalance = theBalance; _itemChanged = _itemChanged+1; [self didChangeValueForKey:@"itemChanged"]; [self didChangeValueForKey:@"openingBalance"]; } KVO Compliance Manual Change Notification 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 13In the case of an ordered to-many relationship, you must specify not only the key that changed, but also the type of change and the indexes of the objects involved. The type of change is an NSKeyValueChange that specifies NSKeyValueChangeInsertion, NSKeyValueChangeRemoval, or NSKeyValueChangeReplacement. The indexes of the affected objects are passed as an NSIndexSet object. The code fragment in Listing 6 demonstrates how to wrap a deletion of objects in the to-many relationship transactions. Listing 6 Implementation of manual observer notification in a to-many relationship - (void)removeTransactionsAtIndexes:(NSIndexSet *)indexes { [self willChange:NSKeyValueChangeRemoval valuesAtIndexes:indexes forKey:@"transactions"]; // Remove the transaction objects at the specified indexes. [self didChange:NSKeyValueChangeRemoval valuesAtIndexes:indexes forKey:@"transactions"]; } KVO Compliance Manual Change Notification 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 14There are many situations in which the value of one property depends on that of one or more other attributes in another object. If the value of one attribute changes, then the value of the derived property should also be flagged for change. How you ensure that key-value observing notifications are posted for these dependent properties depends on the cardinality of the relationship. To-one Relationships To trigger notifications automatically for a to-on relationship you should either override keyPathsForValuesAffectingValueForKey: or implement a suitable method that follows the pattern it defines for registering dependent keys. For example, the full name of a person is dependent on both the first and last names. A method that returns the full name could be written as follows: - (NSString *)fullName { return [NSString stringWithFormat:@"%@ %@",firstName, lastName]; } An application observing the fullName property must be notified when either the firstName or lastName properties change, as they affect the value of the property. One solution is to override keyPathsForValuesAffectingValueForKey: specifying that the fullName property of a person is dependent on the lastName and firstName properties. Listing 1 (page 15) shows an example implementation of such a dependency: Listing 1 Example implementation of keyPathsForValuesAffectingValueForKey: + (NSSet *)keyPathsForValuesAffectingValueForKey:(NSString *)key { NSSet *keyPaths = [super keyPathsForValuesAffectingValueForKey:key]; if ([key isEqualToString:@"fullName"]) { 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 15 Registering Dependent KeysNSArray *affectingKeys = @[@"lastName", @"firstName"]; keyPaths = [keyPaths setByAddingObjectsFromArray:affectingKeys]; } return keyPaths; } Your override should typically invoke super and return a set that includes any members in the set that result from doing that (so as not to interfere with overrides of this method in superclasses). You can also achieve the same result by implementing a class method that follows the naming convention keyPathsForValuesAffecting, where is the name of the attribute (first letter capitalized) that is dependent on the values. Using this pattern the code in Listing 1 (page 15) could be rewritten as a class method named keyPathsForValuesAffectingFullName as shown in Listing 2 (page 16). Listing 2 Example implementation of the keyPathsForValuesAffecting naming convention + (NSSet *)keyPathsForValuesAffectingFullName { return [NSSet setWithObjects:@"lastName", @"firstName", nil]; } You can't override the keyPathsForValuesAffectingValueForKey: method when you add a computed property to an existing class using a category, because you're not supposed to override methods in categories. In that case, implement a matching keyPathsForValuesAffecting class method to take advantage of this mechanism. Note: You cannot set up dependencies on to-many relationships by implementing keyPathsForValuesAffectingValueForKey:. Instead, you must observe the appropriate attribute of each of the objects in the to-many collection and respond to changes in their values by updating the dependent key yourself. The following section shows a strategy for dealing with this situation. To-many Relationships The keyPathsForValuesAffectingValueForKey: method does not support key-paths that include a to-many relationship. For example, suppose you have a Department object with a to-many relationship (employees) to a Employee, and Employee has a salary attribute. You might want the Department object have Registering Dependent Keys To-many Relationships 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 16a totalSalary attribute that is dependent upon the salaries of all the Employees in the relationship. You can not do this with, for example, keyPathsForValuesAffectingTotalSalary and returning employees.salary as a key. There are two possible solutions in both situations: 1. You can use key-value observing to register the parent (in this example, Department) as an observer of the relevant attribute of all the children (Employeesin this example). You must add and remove the parent as an observer as child objects are added to and removed from the relationship (see “Registering for Key-Value Observing” (page 7)). In the observeValueForKeyPath:ofObject:change:context: method you update the dependent value in response to changes, as illustrated in the following code fragment: - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context { if (context == totalSalaryContext) { [self updateTotalSalary]; } else // deal with other observations and/or invoke super... } - (void)updateTotalSalary { [self setTotalSalary:[self valueForKeyPath:@"employees.@sum.salary"]]; } - (void)setTotalSalary:(NSNumber *)newTotalSalary { if (totalSalary != newTotalSalary) { [self willChangeValueForKey:@"totalSalary"]; _totalSalary = newTotalSalary; [self didChangeValueForKey:@"totalSalary"]; } } - (NSNumber *)totalSalary { return _totalSalary; Registering Dependent Keys To-many Relationships 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 17} 2. If you're using Core Data, you can register the parent with the application's notification center as an observer of its managed object context. The parentshould respond to relevant change notifications posted by the children in a manner similar to that for key-value observing. Registering Dependent Keys To-many Relationships 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 18Automatic key-value observing is implemented using a technique called isa-swizzling. The isa pointer, as the name suggests, points to the object's class which maintains a dispatch table. This dispatch table essentially contains pointers to the methods the class implements, among other data. When an observer is registered for an attribute of an object the isa pointer of the observed object is modified, pointing to an intermediate class rather than at the true class. As a result the value of the isa pointer does not necessarily reflect the actual class of the instance. You should never rely on the isa pointer to determine class membership. Instead, you should use the class method to determine the class of an object instance. 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 19 Key-Value Observing Implementation DetailsThis table describes the changes to Key-Value Observing Programming Guide . Date Notes 2012-07-17 Updated to use new Objective-C features. ARCification 2011-03-08 Clarified terminology in "Registering Dependent Keys." 2009-08-14 Added links to some key Cocoa definitions. 2009-05-09 Corrected minor typo. 2009-05-06 Clarified Core Data requirement in Registering Dependent Keys. 2009-03-04 Updated Registering Dependent Keys chapter. 2006-06-28 Updated code examples. Clarified that you should not release objects before calling willChangeValueForKey: methods. Noted that Java is not supported. 2005-07-07 2004-08-31 Corrected minor typos. Clarified the need to nest manual key-value change notifications. 2004-03-20 Modified source example in “Registering Dependent Keys” (page 15). Corrected source example in “Registering for Key-Value Observing” (page 7). Added article “Key-Value Observing Implementation Details ” (page 19). 2004-02-22 2003-10-15 Initial publication of Key-Value Observing. 2012-07-17 | © 2003, 2012 Apple Inc. All Rights Reserved. 20 Document Revision HistoryApple Inc. © 2003, 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, Cocoa, Mac, and Objective-C are trademarks of Apple Inc., registered in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. 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. Location Awareness Programming GuideContents Making Your App Location-Aware 7 At a Glance 8 Location Services Provide a Geographical Context for Apps 8 Heading Information Indicates the User’s Current Orientation 8 Maps Support Navigation and the Display of Geographically Relevant Content 8 Routing Apps Provide Directions to the User 9 How to Use This Document 9 See Also 9 Getting the User’s Location 10 Requiring the Presence of Location Services in Order to Run 10 Getting the User’s Current Location 11 Determining Whether Location Services Are Available 11 Starting the Standard Location Service 12 Starting the Significant-Change Location Service 13 Receiving Location Data from a Service 14 Monitoring Shape-Based Regions 15 Determining the Availability of Region Monitoring 15 Defining a Region to Be Monitored 16 Handling Boundary-Crossing Events for a Region 17 Testing Your App’s Region Monitoring Support 18 Getting Location Events in the Background 18 Tips for Conserving Battery Power 18 Getting Direction-Related Events 20 Adding a Requirement for Direction-Related Events 20 Getting Heading-Related Events 21 Getting Course Information While the User Is Moving 23 Geocoding Location Data 24 About Geocoder Objects 24 Converting Coordinates Into Place Name Information 25 Getting Placemark Information using CLGeocoder 25 Getting Placemark Information from the Reverse Geocoder 26 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Converting Place Names Into Coordinates 29 Displaying Maps 30 Understanding Map Geometry 30 Map Coordinate Systems 31 Converting Between Coordinate Systems 32 Adding a Map View to Your User Interface 33 Configuring the Properties of a Map 34 Setting the Visible Portion of the Map 34 Zooming and Panning the Map Content 34 Displaying the User’s Current Location on the Map 35 Responding to User Interactions with a Map 36 Annotating Maps 37 Adding Annotations to a Map 38 Checklist for Adding an Annotation to the Map 39 Defining a Custom Annotation Object 40 Using the Standard Annotation Views 41 Defining a Custom Annotation View 42 Creating Annotation Views from Your Delegate Object 44 Managing the Map’s Annotation Objects 46 Marking Your Annotation View as Draggable 46 Displaying Overlays on a Map 47 Checklist for Adding an Overlay to the Map 49 Using the Standard Overlay Objects and Views 50 Defining a Custom Overlay Object 51 Defining a Custom Overlay View 52 Creating Overlay Views from Your Delegate Object 55 Managing the Map’s Overlay Objects 56 Using Overlays as Annotations 56 Providing Directions 58 Asking the Maps App to Display Directions 58 Registering as a Routing App 58 Configuring Your App to Accept Direction Requests 59 Declaring the Supported Geographic Coverage for Directions 60 Handling Direction Requests 62 Legacy Map Techniques 64 Creating Draggable Annotations in Earlier Versions of iOS 64 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsDocument Revision History 69 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures, Tables, and Listings Getting the User’s Location 10 Listing 1-1 Starting the standard location service 12 Listing 1-2 Starting the significant-change location service 13 Listing 1-3 Processing an incoming location event 14 Listing 1-4 Creating and registering a region based on a Map Kit overlay 16 Getting Direction-Related Events 20 Listing 2-1 Initiating the delivery of heading events 21 Listing 2-2 Processing heading events 22 Geocoding Location Data 24 Listing 3-1 Geocoding a location using CLGeocoder 25 Listing 3-2 Geocoding a location using MKReverseGeocoder 27 Displaying Maps 30 Figure 4-1 Mapping spherical data to a flat surface 31 Table 4-1 Map coordinate system conversion routines 32 Annotating Maps 37 Figure 5-1 Displaying an annotation in a map 38 Figure 5-2 Displaying an overlay on a map 48 Figure 5-3 Using a custom overlay view to draw 55 Listing 5-1 Creating a simple annotation object 40 Listing 5-2 Implementing the MyCustomAnnotation class 41 Listing 5-3 Creating a standard annotation view 42 Listing 5-4 Declaring a custom annotation view 42 Listing 5-5 Initializing a custom annotation view 43 Listing 5-6 Creating annotation views 44 Listing 5-7 Creating a polygon overlay object 50 Listing 5-8 Creating a polygon view for rendering a shape 51 Listing 5-9 Drawing a gradient in a custom overlay view 53 Providing Directions 58 Table 6-1 Keys and values for the directions request document type 59 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5Listing 6-1 A sample GeoJSON file 61 Listing 6-2 Handling a directions request URL 63 Legacy Map Techniques 64 Listing A-1 The BullseyeAnnotationView class 64 Listing A-2 Tracking the view’s location 66 Listing A-3 Handling the final touch events 67 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6 Figures, Tables, and ListingsUsing location-based information in your apps is a way to keep the user connected to the surrounding world. Whether you use thisinformation for practical purposes(such as navigation) or for entertainment, location-based information can improve the overall user experience. Location-based information in iOS comprises two pieces: location services and maps. Location services are provided by the Core Location framework, which provides Objective-C interfaces for obtaining information about the user’s location and heading. Maps are provided by the Map Kit framework, which supports both the display and annotation of maps similar to those found in the Maps app. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7 Making Your App Location-AwareAt a Glance Map and location services provide a way for you to enhance user interactions. By incorporating geographic data into your apps, you can orient the user to the surrounding environment or help the user stay connected to other people nearby. Location Services Provide a Geographical Context for Apps Location services is all about mobility and the fact that your app is running on a device that can go anywhere. Knowing the user’s geographic location can help you improve the quality of the information you offer, and in some cases it might even be at the heart of your app. Apps that offer navigation features use location services to monitor the user’s position and generate updates. And many other types of apps use location as a way of connecting nearby users socially. Relevant Chapters: “Getting the User’s Location” (page 10), “Geocoding Location Data” (page 24) Heading Information Indicates the User’s Current Orientation Heading services complement the basic location services by providing more precise information about which way a device is pointed. The most obvious use for this technology is for implementing a compass but this technology is also used to support augmented reality, games, and navigational apps. And even on devices that do not have a magnetometer—the hardware used to get precise heading information—information about the user’s course and speed are still available for apps that need it. Relevant Chapters: “Getting Direction-Related Events” (page 20) Maps Support Navigation and the Display of Geographically Relevant Content Maps are a way to visualize geographical data in a way that is easy to understand. The Map Kit framework provides standard views that you can incorporate into your app and use to display information tied to specific geographic points. In addition, this framework provides the means to layer custom information on top of the map and have it scroll along with the rest of the map content. Making Your App Location-Aware At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8Relevant Chapters: “Displaying Maps” (page 30), “Annotating Maps” (page 37) Routing Apps Provide Directions to the User A routing app is an app that is able to receive coordinates from the Maps app and use those coordinates to provide point-to-point directions to the user. Apps that provide navigation capabilities can declare themselves as a routing app with minimal additional effort. In addition to driving and walking directions, routing apps can support many other modes of transport, including taxi, airplane, and many public transportation options. Relevant Chapters: “Providing Directions” (page 58) How to Use This Document You do not have to read this entire document to use each of the technologies. The services provided by the Core Location and Map Kit frameworks are separate and can be used independent of other services. Therefore, the beginning of each chapter introduces the terminology and information you need to understand the corresponding technology followed by examples and task-related steps on how to use it. The only exception is the “Annotating Maps” (page 37) chapter, which builds on the information presented in the “Displaying Maps” (page 30) chapter. See Also For information about the classes of the Core Location framework, see Core Location Framework Reference . For information about the classes of the Map Kit framework, see Map Kit Framework Reference . Making Your App Location-Aware How to Use This Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9Apps use location data for a wide variety of purposes, ranging from social networking to turn-by-turn navigation services. They get location data by using the classes of the Core Location framework. This framework provides several services that you can use to get and monitor the device’s current location: ● The significant-change location service provides a low-power way to get the current location and be notified of changes to that location. (iOS 4.0 and later). ● The standard location service offers a more configurable way to get the current location. ● Region monitoring lets you monitor boundary crossings for a defined area. (iOS 4.0 and later). To use the features of the Core Location framework, you must link your app to CoreLocation.framework in your Xcode project. To access the classes and headers of the framework, include an #import statement at the top of any relevant source files. For general information about the classes of the Core Location framework, see Core Location Framework Reference . Requiring the Presence of Location Services in Order to Run If your app relies on location services to function properly, you should include the UIRequiredDeviceCapabilities key in the app’s Info.plist file. You use this key to specify the location services that must be present in order for your app to run. The App Store uses the information in this key from preventing users from downloading apps to devices that do not contain the listed features. The value for the UIRequiredDeviceCapabilities is an array of strings indicating the features that your app requires. There are two strings relevant to location services: ● Include the location-services string if you require location services in general. ● Include the gps string if your app requires the accuracy offered only by GPS hardware. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10 Getting the User’s LocationImportant: If your app uses location services but is able to operate successfully without them, do not include the corresponding strings in the UIRequiredDeviceCapabilities key. For more information about the UIRequiredDeviceCapabilities key, see Information Property List Key Reference . Getting the User’s Current Location The Core Location framework lets you locate the current position of the device and use that information in your app. The framework uses information obtained from the built-in cellular, Wi-Fi, or GPS hardware to triangulate a location fix for the device. It reports that location to your code and, depending on how you configure the service, also provides periodic updates as it receives new or improved data. There are two different services you can use to get the user’s current location: ● The standard location service is a configurable, general-purpose solution and is supported in all versions of iOS. ● The significant-change location service offers a low-power location service for devices with cellular radios. This service is available only in iOS 4.0 and later and can also wake up an app that is suspended or not running. Gathering location data is a power-intensive operation. It involves powering up the onboard radios and querying the available cell towers, Wi-Fi hotspots, or GPS satellites, which can take severalseconds. Leaving the standard location service running for extended periods can drain the device’s battery. (The significant-change location service drastically reduces battery drain by monitoring only cell tower changes, but the service works only on devices with cellular radios.) For most apps, it is usually sufficient to establish an initial position fix and then acquire updates only periodically after that. If you are sure you need regular position updates, you should use the significant-change location service where you can; otherwise, you should configure the parameters of the standard location service in a way that minimizes its impact on battery life. Determining Whether Location Services Are Available Every iOS-based device is capable of supporting location services in some form but there are still situations where location services may not be available: ● The user can disable location services in the Settings app. ● The user can deny location services for a specific app. ● The device might be in Airplane mode and unable to power up the necessary hardware. Getting the User’s Location Getting the User’s Current Location 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11For these reasons, it is recommended that you always call the locationServicesEnabled class method of CLLocationManager before attempting to start either the standard or significant-change location services. (In iOS 3.x and earlier, check the value of the locationServicesEnabled property instead.) If this class method returns YES, you can start location services as planned. If it returns NO and you attempt to start location services anyway, the system promptsthe user to confirm whether location servicesshould be reenabled. Given that location services are very likely to be disabled on purpose, the user might not welcome this prompt. Starting the Standard Location Service The standard location service is the most common way to get the user’s current location because it is available on all devices and in all versions of iOS. Before using this service, you configure it by specifying the desired accuracy of the location data and the distance that must be traveled before reporting a new location. When you start the service, it uses the specified parameters to determine which radios to enable and then proceeds to report location events to your app. To use the standard location service, create an instance of the CLLocationManager class and configure its desiredAccuracy and distanceFilter properties. To begin receiving location notifications, assign a delegate to the object and call the startUpdatingLocation method. As location data becomes available, the location manager notifies its assigned delegate object. If a location update has already been delivered, you can also get the most recent location data directly from the CLLocationManager object without waiting for a new event to be delivered. Listing 1-1 shows a sample method that configures a location manager for use. This method is part of a class that caches its location manager object in a member variable for later use. (The class also conforms to the CLLocationManagerDelegate protocol and so acts as the delegate for the location manager.) Because the app does not need precise location data, it configures the location service to report the general area of the user and notify it only when the user moves a significant distance, which in this case is half a kilometer. Listing 1-1 Starting the standard location service - (void)startStandardUpdates { // Create the location manager if this object does not // already have one. if (nil == locationManager) locationManager = [[CLLocationManager alloc] init]; locationManager.delegate = self; locationManager.desiredAccuracy = kCLLocationAccuracyKilometer; Getting the User’s Location Getting the User’s Current Location 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12// Set a movement threshold for new events. locationManager.distanceFilter = 500; [locationManager startUpdatingLocation]; } The code for receiving location updates from this service is shown in “Receiving Location Data from a Service” (page 14). Starting the Significant-Change Location Service In iOS 4.0 and later, you can use the significant-change location service to receive location events. This service offers a significant powersavings and provides accuracy that is good enough for most apps. It usesthe device’s cellular radio to determine the user’s location and report changes in that location, allowing the system to manage power usage much more aggressively than it could otherwise. This service is also capable of waking up an app that is currently suspended or not running in order to deliver new location data. To use the significant-change location service, create an instance of the CLLocationManager class, assign a delegate to it, and call the startMonitoringSignificantLocationChanges method as shown in Listing 1-2. Aslocation data becomes available, the location manager notifiesits assigned delegate object. If a location update has already been delivered, you can also get the most recent location data directly from the CLLocationManager object without waiting for a new event to be delivered. Listing 1-2 Starting the significant-change location service - (void)startSignificantChangeUpdates { // Create the location manager if this object does not // already have one. if (nil == locationManager) locationManager = [[CLLocationManager alloc] init]; locationManager.delegate = self; [locationManager startMonitoringSignificantLocationChanges]; } Getting the User’s Location Getting the User’s Current Location 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13As with the standard location service, location data is delivered to the delegate object as described in “Receiving Location Data from a Service” (page 14). If you leave thisservice running and your app issubsequently suspended or terminated, the service automatically wakes up your app when new location data arrives. At wake-up time, your app is put into the background and given a small amount of time to process the location data. Because your app is in the background, it should do minimal work and avoid any tasks (such as querying the network) that might prevent it from returning before the allocated time expires. If it does not, your app may be terminated. Receiving Location Data from a Service Whether you use the standard location service or the significant-change location service to get location events, the way you receive those events is the same. In iOS 6 and later, the location manager reports events to the locationManager:didUpdateLocations: method of its delegate when they become available. (In earlier versions of the system, it reports eventsto the locationManager:didUpdateToLocation:fromLocation: method.) If there is an error retrieving an event, the location manager calls the locationManager:didFailWithError: method of its delegate instead. Listing 1-3 shows the delegate method for receiving location events. Because the location manager object sometimes returns cached events, it is recommended that you check the timestamp of any location events you receive. (It can take several seconds to obtain a rough location fix, so the old data simply serves as a way to reflect the last known location.) In this example, the method throws away any events that are more than fifteen seconds old under the assumption that fairly recent events are likely to be good enough. If you were implementing a navigation app, you might want to lower the threshold. Listing 1-3 Processing an incoming location event // Delegate method from the CLLocationManagerDelegate protocol. - (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations { // If it's a relatively recent event, turn off updates to save power CLLocation* location = [locations lastObject]; NSDate* eventDate = location.timestamp; NSTimeInterval howRecent = [eventDate timeIntervalSinceNow]; if (abs(howRecent) < 15.0) { // If the event is recent, do something with it. NSLog(@"latitude %+.6f, longitude %+.6f\n", location.coordinate.latitude, location.coordinate.longitude); Getting the User’s Location Getting the User’s Current Location 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14} } In addition to a location object’s timestamp, you can also use the accuracy reported by that object as a means of determining whether you want to accept an event. As it receives more accurate data, the location service may return additional events, with the accuracy values reflecting the improvements accordingly. Throwing away less accurate events means your app wastes less time on events that cannot be used effectively anyway. Monitoring Shape-Based Regions Apps can use region monitoring to be notified when the user crosses geographic boundaries. You can use this capability to generate alerts when the user gets close to a specific location. For example, upon approaching a specific dry cleaners, an app could notify the user to pick up any clothes that had been dropped off and are now ready. In iOS, regions associated with your app are tracked at all times, including when your app is not running. If a region boundary is crossed while an app is not running, that app is relaunched into the background to handle the event. Similarly, if the app is suspended when the event occurs, it is woken up and given a short amount of time to handle the event. Determining the Availability of Region Monitoring Before attempting to monitor any regions, your app should check to see if region monitoring is supported on the current device. There are several reasons why region monitoring might not be available: ● The device may not have the hardware needed to support region monitoring. ● The user may have disabled location services in the Settings app. ● The device might be in Airplane mode and unable to power up the necessary hardware. For these reasons, it is recommended that you always call the regionMonitoringAvailable and regionMonitoringEnabled class methods of CLLocationManager before attempting to monitor regions. The regionMonitoringAvailable method lets you know whether the underlying hardware supportsregion monitoring. If it returns NO, there is no chance that your app will ever be able to use region monitoring on the device. If region monitoring is available, the regionMonitoringEnabled method reports whether the feature is currently enabled. If region monitoring is available but not enabled when you attempt to monitor a region, the system promptsthe user to confirm whether region monitoring should be reenabled. Given that the feature is likely to be disabled on purpose, the user might not welcome this prompt. Getting the User’s Location Monitoring Shape-Based Regions 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15Defining a Region to Be Monitored To begin monitoring a region, you must define the region and register it with the system. Regions are defined using the CLRegion class, which currently supports the creation of circular regions. Each region you create must include both the data that definesthe desired geographic area and a unique identifierstring. (The identifier string is required and is the only guaranteed way for your app to identify regions later.) To register a region, you call the startMonitoringForRegion:desiredAccuracy: method of your CLLocationManager object. Listing 1-4 shows a sample method that creates a new region based on a circular Map Kit overlay. The overlay’s center point and radius form the boundary for the region, although if the radius is too large to be monitored, it is reduced automatically. After registering the region, the region object itself can be released. Core Location stores the data associated with a region but does not typically store the region object itself. Listing 1-4 Creating and registering a region based on a Map Kit overlay - (BOOL)registerRegionWithCircularOverlay:(MyCircle*)overlay andIdentifier:(NSString*)identifier { // Do not create regions if support is unavailable or disabled. if ( ![CLLocationManager regionMonitoringAvailable] || ![CLLocationManager regionMonitoringEnabled] ) return NO; // If the radius is too large, registration fails automatically, // so clamp the radius to the max value. CLLocationDegrees radius = overlay.radius; if (radius > self.locManager.maximumRegionMonitoringDistance) radius = self.locManager.maximumRegionMonitoringDistance; // Create the region and start monitoring it. CLRegion* region = [[CLRegion alloc] initCircularRegionWithCenter:overlay.coordinate radius:radius identifier:identifier]; [self.locManager startMonitoringForRegion:region desiredAccuracy:kCLLocationAccuracyHundredMeters]; [region release]; Getting the User’s Location Monitoring Shape-Based Regions 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16return YES; } Monitoring of a region begins immediately after registration. However, do not expect to receive an event right away. Only boundary crossings can generate an event. Thus, if at registration time the user’s location is already inside the region, the location manager does not generate an event. Instead, you must wait for the user to cross the region boundary before an event is generated and sent to the delegate. You should always be judicious when specifying the set of regions to monitor. Regions are a shared system resource and the total number of regions available systemwide is limited. For this reason, Core Location limits the number of regions that may be simultaneously monitored by a single app. To work around these limits, you should consider registering only those regions in the user’s immediate vicinity. As the user’s location changes, you can remove regions that are now farther way and add regions coming up on the user’s path. If you attempt to register a region and space is unavailable, the location manager calls the locationManager:monitoringDidFailForRegion:withError: method of its delegate with the kCLErrorRegionMonitoringFailure error code. Handling Boundary-Crossing Events for a Region Every time the user’s current location crosses a boundary region, the system generates an appropriate region event for your app. If your app is already running, these events go directly to the delegates of any current location manager objects. If your app is not running, the system launches it in the background so that it can respond. Apps can implement the following methods to handle boundary crossings: ● locationManager:didEnterRegion: ● locationManager:didExitRegion: The system does not report boundary crossings until the boundary plus a designated cushion distance is exceeded. You specify the desired cushion distance for a region when you register it using the startMonitoringForRegion:desiredAccuracy: method. This cushion value prevents the system from generating numerous entered and exited events in quick succession while the user is traveling close the edge of the boundary. When a region boundary is crossed, the most likely response is to alert the user of the proximity to the target item. If your app is running in the background, you can use local notifications to alert the user; otherwise, you can simply post an alert. Getting the User’s Location Monitoring Shape-Based Regions 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17Testing Your App’s Region Monitoring Support When testing your region monitoring code in iOS Simulator or on a device, realize that region events may not happen immediately after a region boundary is crossed. To prevent spurious notifications, iOS does not deliver region notifications until certain threshold conditions are met. Specifically, the user’s location must cross the region boundary and move away from that boundary by a minimum distance and remain at that minimum distance for at least 20 seconds before the notifications are reported. The specific threshold distances are determined by the hardware and the location technologiesthat are currently available. For example, if Wi-Fi is disabled, region monitoring is significantly less accurate. However, for testing purposes, you can assume that the minimum distance is approximately 200 meters. Getting Location Events in the Background If your app needs location updates delivered whether the app is in the foreground or background, there are multiple options for doing so. The preferred option is to use the significant location change service to wake your app at appropriate times to handle new events. However, if your app needs to use the standard location service, you can declare your app as needing background location services. An app should request background location services only if the absence of those services would impair its ability to operate. In addition, any app that requests background location services should use those services to provide a tangible benefit to the user. For example, a turn-by-turn navigation app would be a likely candidate for background location services because of its need to track the user’s position and report when it is time to make the next turn. The process for configuring a background location app is described in “App States and Multitasking” in iOS App Programming Guide . Tips for Conserving Battery Power Receiving and transmitting data using the radios of an iOS-based device require more power than any other operation on the device. Because Core Location relies on these radios to determine the user’s location, you should use location services judiciously in your apps. Most apps do not need location services to be running all the time, and so turning off those services is the simplest way to save power. ● Turn off location services when you are not using them. This may seem obvious but it is worth repeating. With the exception of navigation apps that offer turn-by-turn directions, most apps do not need location services to be on all the time. Turn location services on just long enough to get a location fix and then turn them off. Unless the user is in a moving vehicle, the current location should not change frequently enough to be an issue. And you can always start location services again later if needed. Getting the User’s Location Getting Location Events in the Background 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18● Use the significant-change location service instead ofthe standard location service whenever possible. The significant-change location service providessignificant powersavings while still allowing you to leave location services running. This is highly recommended for apps that need to track changes in the user’s location but do not need the higher precision offered by the standard location services. ● Use lower-resolution values forthe desired accuracy unless doing so would impair your app. Requesting a higher accuracy than you need causes Core Location to power up additional hardware and waste power for precision you are not using. Unless your app really needs to know the user’s position within a few meters, do not put the values kCLLocationAccuracyBest or kCLLocationAccuracyNearestTenMeters in the desiredAccuracy property. And remember that specifying a value of kCLLocationAccuracyThreeKilometers does not prevent the location service from returning better data. Most of the time, Core Location can return location data with an accuracy within a hundred meters or so using Wi-FI and cellular signals. ● Turn off location events if the accuracy does not improve over a period of time. If your app is not receiving events with the desired level of accuracy, you should look at the accuracy of events you do receive and see if it is improving or staying about the same over time. If accuracy is not improving, it could be because the desired accuracy is simply not available at the moment. Turning off location services and trying again later prevents your app from wasting power. Getting the User’s Location Tips for Conserving Battery Power 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19Core Location supports two different ways to get direction-related information: ● Devices with a magnetometer can report the direction in which a device is pointing, also known as its heading. ● Devices with GPS hardware can report the direction in which a device is moving, also known as its course. Remember that heading and course information do not represent the same information. The heading of a device reflects the actual orientation of the device relative to true north or magnetic north. The course of the device represents the direction of travel and does not take into account the device orientation. Depending on your app, you might prefer one over the other or use a combination of the two. For example, a navigation app might toggle between course and heading information depending on the user’s current speed. At walking speeds, heading information would be more useful for orienting the user to the current environment, whereas in a car, course information provides the general direction of the car’s movement. Adding a Requirement for Direction-Related Events If your app requires some form of direction-related information in order to function properly, you should include the UIRequiredDeviceCapabilities key in the app’s Info.plist file. This key contains an array of strings indicating the features that your app requires of the underlying iOS-based device. The App Store usesthisinformation to prevent usersfrom installing apps on a device without the minimum required hardware. For direction-related events, there are two relevant strings you can associate with this key: ● magnetometer—Include this string if your app requires the presence of heading information. ● gps—Include this string if your app requires the presence of course-related information. Important: If your app uses heading or course events but is able to operate successfully without them, do not include the corresponding string value with the UIRequiredDeviceCapabilities key. In both cases, you should also include the location-services string in the array. For more information about the UIRequiredDeviceCapabilities key, see Information Property List Key Reference . 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20 Getting Direction-Related EventsGetting Heading-Related Events Heading events are available to apps running on a device that contains a magnetometer. A magnetometer measures nearby magnetic fields emanating from the Earth and usesthem to determine the precise orientation of the device. Although a magnetometer can be affected by local magnetic fields, such as those emanating from fixed magnetsfound in audio speakers, motors, and many other types of electronic devices, Core Location is smart enough to filter out fields that move with the device. Heading values can be reported relative either to magnetic north or true north on the map. Magnetic north represents the point on the Earth’s surface from which the planet’s magnetic field emanates. This location is not the same asthe North Pole, which representstrue north. Depending on the location of the device, magnetic north may be good enough for many purposes, but the closer to the poles you get, the less useful this value becomes. The steps for receiving heading events are as follows: 1. Create a CLLocationManager object. 2. Determine whether heading events are available by calling the headingAvailable class method. (In iOS 3.x and earlier, check the value of the headingAvailable property instead.) 3. Assign a delegate to the location manager object. 4. If you want true north values, start location services. 5. Call the startUpdatingHeading method to begin the delivery of heading events. Listing 2-1 shows a custom method that configures a location manager and starts the delivery of heading events. In this case, the object is a view controller that displays the current heading to the user. Because the view controller displaysthe true north heading value, itstartslocation updatesin addition to heading updates. This code runs in iOS 4.0 and later Listing 2-1 Initiating the delivery of heading events - (void)startHeadingEvents { if (!self.locManager) { CLLocationManager* theManager = [[[CLLocationManager alloc] init] autorelease]; // Retain the object in a property. self.locManager = theManager; locManager.delegate = self; } Getting Direction-Related Events Getting Heading-Related Events 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21// Start location services to get the true heading. locManager.distanceFilter = 1000; locManager.desiredAccuracy = kCLLocationAccuracyKilometer; [locManager startUpdatingLocation]; // Start heading updates. if ([CLLocationManager headingAvailable]) { locManager.headingFilter = 5; [locManager startUpdatingHeading]; } } The object you assign to the delegate property must conform to the CLLocationManagerDelegate protocol. When a new heading event arrives, the location manager object calls the locationManager:didUpdateHeading: method to deliver that event to your app. Upon receiving a new event, you should check the headingAccuracy property to ensure that the data you just received is valid, as shown in Listing 2-2. In addition, if you are using the true heading value, you should also check to see if it contains a valid value before using it. Listing 2-2 Processing heading events - (void)locationManager:(CLLocationManager *)manager didUpdateHeading:(CLHeading *)newHeading { if (newHeading.headingAccuracy < 0) return; // Use the true heading if it is valid. CLLocationDirection theHeading = ((newHeading.trueHeading > 0) ? newHeading.trueHeading : newHeading.magneticHeading); self.currentHeading = theHeading; [self updateHeadingDisplays]; } Getting Direction-Related Events Getting Heading-Related Events 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22Getting Course Information While the User Is Moving Devices that include GPS hardware can generate information indicating the device’s current course and speed. Course information is used to indicate the direction in which the device is moving and does not necessarily reflect the orientation of the device itself. As a result, it is primarily intended for apps that provide navigation information while the user is moving. The actual course and speed information is returned to your app in the same CLLocation objects you use to get the user’s position. When you start location updates, Core Location automatically provides course and speed information when it is available. The framework uses the incoming location events to compute the current direction of motion. For more information on how to start location updates, see “Getting the User’s Location” (page 10) Getting Direction-Related Events Getting Course Information While the User Is Moving 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23Location data is usually returned as a pair of numerical values representing the latitude and longitude of the corresponding point on the globe. These coordinates offer a precise and easy way to specify location data in your code but they are not very intuitive for users. Instead of global coordinates, users are more likely to understand a location that is specified using information they are more familiar with such as street, city, state, and country information. For situations where you want to display a user friendly version of a location, you can use a geocoder object to obtain that information. About Geocoder Objects A geocoder object uses a network service to convert between latitude and longitude values and a user-friendly placemark, which is a collection of data such as the street, city, state, and country information. Reverse geocoding is the process of converting a latitude and longitude into a placemark. Forward geocoding is the process of converting place name information into a latitude and longitude value. Reverse geocoding is supported in all versions of iOS but forward geocoding is supported only in iOS 5.0 and later. Because geocodersrely on a network service, a live network connection must be present in order for a geocoding request to succeed. If a device is in Airplane mode or the network is currently not configured, the geocoder cannot connect to the service it needs and must therefore return an appropriate error. Here are some rules of thumb for creating geocoding requests: ● Send at most one geocoding request for any one user action. ● If the user performs multiple actions that involve geocoding the same location, reuse the results from the initial geocoding request instead of starting individual requests for each action. ● When you want to update the location automatically (such as when the user is moving), reissue the geocoding request only when the user's location has moved a significant distance and after a reasonable amount of time has passed. For example, in a typical situation, you should not send more than one geocoding request per minute. ● Do notstart a geocoding request at a time when the user will notsee the resultsimmediately. For example, do not start a request if your app is in the background or was interrupted and is currently in the inactive state. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24 Geocoding Location DataConverting Coordinates Into Place Name Information Note: In iOS 5.0, MKReverseGeocoder and MKReverseGeocoderDelegate are deprecated so use CLGeocoder for all new app development. In iOS, you can use either the CLGeocoder or MKReverseGeocoder class to handle reverse-geocoding requests. The CLGeocoder is the preferred class to use and is available in iOS 5.0 and later. However, if your app must run on earlier versions of iOS, you can use the MKReverseGeocoder class. Getting Placemark Information using CLGeocoder To initiate a reverse-geocoding request using the CLGeocoder class, create an instance of the class and call the reverseGeocodeLocation:completionHandler: method. The geocoder object initiates the reverse geocoding request asynchronously and delivers the results to the block object you provide. The block object is executed whether the request succeeds or fails. In the event of a failure, an error object is passed to the block indicating the reason for the failure. Note: The same CLGeocoder object can be used to initiate any number of geocoding requests but only one request at a time may be active for a given geocoder. “Converting Coordinates Into Place Name Information” shows an example of how to reverse geocode a point on the map. The only code specific to the geocoding request are the first few lines, which allocate the geocoder object as needed and call the reverseGeocodeLocation:completionHandler: method to start the reverse-geocoding operation. (The geocoder variable represents a member variable used to store the geocoder object.) The rest of the code isspecific to the sample app itself. In this case, the sample app storesthe placemark with a custom annotation object (defined by the MapLocation class) and adds a button to the callout of the corresponding annotation view. Listing 3-1 Geocoding a location using CLGeocoder @implementation MyGeocoderViewController (CustomGeocodingAdditions) - (void)geocodeLocation:(CLLocation*)location forAnnotation:(MapLocation*)annotation { if (!geocoder) geocoder = [[CLGeocoder alloc] init]; [theGeocoder reverseGeocodeLocation:location completionHandler: Geocoding Location Data Converting Coordinates Into Place Name Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25^(NSArray* placemarks, NSError* error){ if ([placemarks count] > 0) { annotation.placemark = [placemarks objectAtIndex:0]; // Add a More Info button to the annotation's view. MKPinAnnotationView* view = (MKPinAnnotationView*)[map viewForAnnotation:annotation]; if (view && (view.rightCalloutAccessoryView == nil)) { view.canShowCallout = YES; view.rightCalloutAccessoryView = [UIButton buttonWithType:UIButtonTypeDetailDisclosure]; } } }]; } @end The advantage of using a block object in a sample like this is that information (such as the annotation object) can be easily captured and used as part of the completion handler. Without blocks, the process of wrangling data variables becomes much more complicated. Getting Placemark Information from the Reverse Geocoder For apps running on iOS 4.1 and earlier, you must perform reverse-geocoding requests using the MKReverseGeocoder class of the Map Kit framework. This class uses a delegate-based approach for geocoding a single location. This means that you can use a single instance of the MKReverseGeocoder class only once. In addition, the Google terms of service require that the MKReverseGeocoder class be used in conjunction with a Google map. To initiate a reverse geocoding request, create an instance of the MKReverseGeocoder class, assign an appropriate object to the delegate property, and call the start method. If the query completessuccessfully, your delegate’s reverseGeocoder:didFindPlacemark: method is called and passed an MKPlacemark object with the results. If there is a problem reverse geocoding the location, the reverseGeocoder:didFailWithError: method is called instead. Geocoding Location Data Converting Coordinates Into Place Name Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26Listing 3-2 shows the code required to use a reverse geocoder. Upon successful completion of the geocoding operation, the code adds a button to the annotation view’s callout so that it can display the placemark information. Because the annotation is not automatically available to the delegate, the custom annotationForCoordinate: method is included to find the appropriate annotation object from the map view. Listing 3-2 Geocoding a location using MKReverseGeocoder @implementation MyGeocoderViewController (CustomGeocodingAdditions) - (void)geocodeLocation:(CLLocation*)location forAnnotation:(MapLocation*)annotation { MKReverseGeocoder* theGeocoder = [[MKReverseGeocoder alloc] initWithCoordinate:location.coordinate]; theGeocoder.delegate = self; [theGeocoder start]; } // Delegate methods - (void)reverseGeocoder:(MKReverseGeocoder*)geocoder didFindPlacemark:(MKPlacemark*)place { MapLocation* theAnnotation = [map annotationForCoordinate:place.coordinate]; if (!theAnnotation) return; // Associate the placemark with the annotation. theAnnotation.placemark = place; // Add a More Info button to the annotation's view. MKPinAnnotationView* view = (MKPinAnnotationView*)[map viewForAnnotation:annotation]; if (view && (view.rightCalloutAccessoryView == nil)) { view.canShowCallout = YES; view.rightCalloutAccessoryView = [UIButton buttonWithType:UIButtonTypeDetailDisclosure]; } Geocoding Location Data Converting Coordinates Into Place Name Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27} - (void)reverseGeocoder:(MKReverseGeocoder*)geocoder didFailWithError:(NSError*)error { NSLog(@"Could not retrieve the specified place information.\n"); } @end @implementation MKMapView (GeocoderAdditions) - (MapLocation*)annotationForCoordinate:(CLLocationCoordinate2D)coord { // Iterate through the map view's list of coordinates // and return the first one whose coordinate matches // the specified value exactly. id theObj = nil; for (id obj in [self annotations]) { if (([obj isKindOfClass:[MapLocation class]])) { MapLocation* anObj = (MapLocation*)obj; if ((anObj.coordinate.latitude == coord.latitude) && (anObj.coordinate.longitude == coord.longitude)) { theObj = anObj; break; } } } return theObj; } Geocoding Location Data Converting Coordinates Into Place Name Information 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28@end Converting Place Names Into Coordinates In iOS 5.0 and later, you use the CLGeocoder class to initiate forward-geocoding requests using either a dictionary of Address Book information or a simple string. There is no designated format for string-based requests; delimiter characters are welcome, but not required, and the geocoder server treats the string as case-insensitive. Therefore, any of the following strings would yield results: ● "Apple Inc” ● "1 Infinite Loop” ● "1 Infinite Loop, Cupertino, CA USA” The more information you can provide to the forward geocoder, the better the results returned to you. The geocoder object parses the information you give it and, if it finds a match, returns some number of placemark objects. The number of returned placemark objects depends greatly on the specificity of the information provided. Thus, providing street, city, province, and country information is much more likely to return a single address than just street and city information. The completion handler block you pass to the geocoder should therefore be prepared to handle multiple placemarks, as shown in the following example: [geocoder geocodeAddressString:@"1 Infinite Loop" completionHandler:^(NSArray* placemarks, NSError* error){ for (CLPlacemark* aPlacemark in placemarks) { // Process the placemark. } }]; Geocoding Location Data Converting Place Names Into Coordinates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29Introduced in iOS 3.0, the Map Kit framework lets you embed a fully functional map interface into your app. The map support provided by this framework includes many of the features normally found in the Maps app. You can display standard street-level map information, satellite imagery, or a combination of the two. You can zoom and pan the map programmatically, and the framework provides automatic support for the touch events that let users zoom and pan the map. You can also annotate the map with custom information. To use the features of the Map Kit framework, you must linking your app to MapKit.framework in your Xcode project. To access the classes and headers of the framework, include an #import statement at the top of any relevant source files. For general information about the classes of the Map Kit framework, see Map Kit Framework Reference . Important: The Map Kit framework uses Google services to provide map data. Use of the framework and its associated interfaces binds you to the Google Maps/Google Earth API terms of service. You can find these terms of service at http://code.google.com/apis/maps/iphone/terms.html. Understanding Map Geometry A map view contains a flattened representation of a spherical object, namely the Earth. In order to use maps effectively, you need to understand a little bit about how to specify pointsin a map view, and how those points translate to points on the Earth’s surface. Understanding map coordinate systems is especially important if you plan to place custom content, such as overlays, on top of the map. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30 Displaying MapsMap Coordinate Systems In order to understand the coordinate systems used by Map Kit, it helpsto understand how the three-dimensional surface of the Earth is mapped to a two-dimensional map. Figure 4-1 shows how the surface of the Earth can be mapped to a two-dimensional surface. Figure 4-1 Mapping spherical data to a flat surface Map Kit uses a Mercator map projection, which is a specific type of cylindrical map projection like the one shown in Figure 4-1 (page 31). In a cylindrical map projection, the coordinates of a sphere are mapped onto the surface of a cylinder, which is then unwrapped to generate a flat map. In such a projection, the longitude lines that normally converge at the poles become parallel instead, causing land masses to be distorted as you move away from the equator. The advantage of a Mercator projection is that the map content is scaled in a way that benefits general navigation. Specifically, on a Mercator map projection, a straight line drawn between any two points on the map yields a course heading that can be used in actual navigation on the surface of the Earth. The projection used by Map Kit uses the Prime Meridian as its central meridian. How you specify data points on a map depends on how you intend to use them. Map Kit supports three basic coordinate systems for specifying map data points: Displaying Maps Understanding Map Geometry 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31● A map coordinate is a latitude and longitude on the spherical representation of the Earth. Map coordinates are the primary way of specifying locations on the globe. You specify individual map coordinate values using the CLLocationCoordinate2D structure. You can specify areas using the MKCoordinateSpan and MKCoordinateRegion structures. ● A map point is an x and y value on the Mercator map projection. Map points are used for many map-related calculationsinstead of map coordinates because they simplify the mathematicsinvolved in the calculations. In your app, you use map points primarily when specifying the shape and position of custom map overlays. You specify individual map points using the MKMapPoint structure. You can specify areas using the MKMapSize and MKMapRect structures. ● A point is a graphical unit associated with the coordinate system of a UIView object. Map points and map coordinates must be mapped to points before drawing custom content in a view. You specify individual points using the CGPoint structure. You can specify areas using the CGSize and CGRect structures. In most situations, the coordinate system you should use is predetermined by the Map Kit interfaces you are using. When it comes to storing actual data in files or inside your app, map coordinates are precise, portable, and the best option forstoring location data. Core Location also uses map coordinates when specifying location values. Converting Between Coordinate Systems Although you normally specify points on the map using latitude and longitude values, there may be times when you need to convert to and from other coordinate systems. For example, you typically use map points when specifying the shape of overlays. Table 4-1 lists the conversion routines you use to convert from one coordinate system to another. Most of these conversionsrequire a view object because they involve converting to or from points. Table 4-1 Map coordinate system conversion routines Convert from Convert to Conversion routines convertCoordinate: toPointToView: (MKMapView) convertRegion: toRectToView: (MKMapView) Map coordinates Points Map coordinates Map points MKMapPointForCoordinate MKCoordinateForMapPoint MKCoordinateRegionForMapRect Map points Map coordinates pointForMapPoint: (MKOverlayView) rectForMapRect: (MKOverlayView) Map points Points Displaying Maps Understanding Map Geometry 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32Convert from Convert to Conversion routines convertPoint: toCoordinateFromView: (MKMapView) convertRect: toRegionFromView: (MKMapView) Points Map coordinates mapPointForPoint: (MKOverlayView) mapRectForRect: (MKOverlayView) Points Map points Adding a Map View to Your User Interface The MKMapView class is a self-contained interface for presenting map data in your app. This class provides support for displaying map data, for managing user interactions, and for hosting custom content provided by your app. You should never subclass MKMapView but should only embed it as-is into your app’s view hierarchy. You should also assign a delegate object to the map. The map view reports all relevant interactions to its delegate so that it has a chance to respond appropriately. You can add a map view to your app programmatically or using Interface Builder: ● To add a map using Interface Builder, drag a Map view object to the appropriate view or window. ● To add a map programmatically, create an instance of the MKMapView class, initialize it using the initWithFrame: method, and then add it as a subview to your view hierarchy. Because it is a view, you can manipulate a map view in the same ways you manipulate other views. You can change its size and position in your view hierarchy, you can configure its autoresizing behaviors, and you can add subviews to it. Unlike a view, you never handle touch events directly in a map view. The map view itself is an opaque container for a complex view hierarchy that handles the display of map-related data and all interactions with that data. Any subviews you add to the map view retain the position specified by their frame property and do not scroll with the map contents. If you want content to remain fixed relative to a specific map coordinate (and thus scroll with the map itself), you must use annotations or overlays as described in “Annotating Maps” (page 37). New maps are configured to accept user interactions and display map data only. You can configure the map to display satellite imagery or a mixture of satellite and map data by changing the Type attribute of the map in Interface Builder or changing the value in the mapType property. If you want to limit user interactions, you can change the values in the zoomEnabled and scrollEnabled properties as well. If you want to respond to user interactions, you should do so using a delegate as described in “Responding to User Interactions with a Map” (page 36). Displaying Maps Adding a Map View to Your User Interface 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33Configuring the Properties of a Map The MKMapView class has a handful of properties that you can configure programmatically. These properties control important information such as which part of the map is currently visible and what user interactions are allowed. Setting the Visible Portion of the Map The region property of the MKMapView class controls the currently visible portion of the map. When it is first created, a map’s visible region is typically set to the entire world. In other words, the region encompasses the area that shows as much of the map as possible. You can change this region at any time by assigning a new value to the region property. This property contains an MKCoordinateRegion structure, which has the following definition: typedef struct { CLLocationCoordinate2D center; MKCoordinateSpan span; } MKCoordinateRegion; The interesting part of an MKCoordinateRegion structure is the span. The span is analogous to the width and height values of a rectangle but is specified using map coordinates and thus is measured in degrees, minutes, and seconds. One degree of latitude is equivalent to approximately 111 kilometers but longitudinal distances vary with the latitude. At the equator, one degree of longitude is equivalent to approximately 111 kilometers but at the poles this value is zero. If you prefer to specify the span using meters, you can use the MKCoordinateRegionMakeWithDistance to create a region data structure using meter values instead of degrees. The value you assign to the region property (or set using the setRegion:animated: method) is usually not the same value that is eventually stored by that property. Setting the span of a region nominally defines the rectangle you want to view but also implicitly sets the zoom level for the map view itself. The map view cannot display arbitrary zoom levels and must adjust any regions you specify to match the zoom levels it supports. It chooses the zoom level that allows your entire region to be visible while still filling as much of the screen as possible. It then adjust the region property accordingly. To find out the resulting region without actually changing the value in the region property, you can use the regionThatFits: method of the map view. Zooming and Panning the Map Content Zooming and panning allow you to change the visible portion of the map at any time: Displaying Maps Configuring the Properties of a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34● To pan the map (but keep the same zoom level), change the value in the centerCoordinate property of the map view or call the setCenterCoordinate:animated: method. ● To change the zoom level (and optionally pan the map), change the value in the region property of the map view or call the setRegion:animated: method. If you only want to pan the map, you should only do so by modifying the centerCoordinate property. Attempting to pan the map by changing the region property usually causes a change in the zoom level as well, because changing any part of the region causes the map view to evaluate the zoom level needed to display that region appropriately. Changesto the current latitude almost always cause the zoom level to change and other changes might cause a different zoom level to be chosen as well. Using the centerCoordinate property (or the setCenterCoordinate:animated: method) lets the map view know that it should leave the zoom level unchanged and update the span as needed. For example, to pan the map to the left by half the current map width, you could use the following code to find the coordinate at the left edge of the map and use that as the new center point, as shown here: CLLocationCoordinate2D mapCenter = myMapView.centerCoordinate; mapCenter = [myMapView convertPoint: CGPointMake(1, (myMapView.frame.size.height/2.0)) toCoordinateFromView:myMapView]; [myMapView setCenterCoordinate:mapCenter animated:YES]; To zoom the map, modify the span of the visible map region. To zoom in, assign a smaller value to the span. To zoom out, assign a larger value. In other words if the current span is one degree, specifying a span of two degrees zooms out by a factor of two: MKCoordinateRegion theRegion = myMapView.region; // Zoom out theRegion.span.longitudeDelta *= 2.0; theRegion.span.latitudeDelta *= 2.0; [myMapView setRegion:theRegion animated:YES]; Displaying the User’s Current Location on the Map Map Kit includes built-in support for displaying the user’s current location on the map. To show this location, set the showsUserLocation property of your map view object to YES. Doing so causes the map view to use Core Location to find the user’s location and add an annotation of type MKUserLocation to the map. Displaying Maps Configuring the Properties of a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35The addition of the MKUserLocation annotation object to the map is reported by the delegate in the same way that custom annotations are. If you want to associate a custom annotation view with the user’s location, you should return that view from your delegate object’s mapView:viewForAnnotation: method. If you want to use the default annotation view, you should return nil from that method instead. Responding to User Interactions with a Map The MKMapView class reports significant map-related events to its associated delegate object. The delegate object is an object that conforms to the MKMapViewDelegate protocol. You provide this object in situations where you want to respond to the following types of events: ● Changes to the visible region of the map ● The loading of map tiles from the network ● Changes in the user’s location ● Changes associated with annotations and overlays. For information about handling changes associated with annotations and overlays,see “Annotating Maps” (page 37). Displaying Maps Responding to User Interactions with a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36The MKMapView class implements an opaque view hierarchy for displaying a scrollable map. Although the map itself is scrollable, any subviews you add to a map view remain fixed in place and do not scroll. If you want to affix content to the map itself, and thus have that content scroll along with the rest of the map, you must use annotations and overlays. Annotations are used to display content that can be defined by a single coordinate point. By contrast, overlays are used to display content that is defined by any number of points and may constitute one or more contiguous or noncontiguousshapes. For example, you use annotationsto represent information such asthe user’s current location, a specific address, or a single point of interest. You use overlays to present more complex information such as traffic information, the boundaries of parks, lakes, cities, states, countries, or other bounded areas. Map Kit separates the data associated with an annotation or overlay from its visual presentation on the map. This separation allows the map to manage visible annotations and overlays much more efficiently and means that you can add hundreds of annotations and overlays to a map and still expect reasonable performance. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37 Annotating MapsAdding Annotations to a Map Annotations offer a way to highlightspecific coordinates on the map and provide additional information about them. You can use annotationsto call outspecific addresses, points of interest, and other types of destinations. When displayed on a map, annotations typically have some sort of image to identify their location and may also have a callout bubble providing information and links to more content. Figure 5-1 shows an annotation that uses a custom image to highlight a particular location. Figure 5-1 Displaying an annotation in a map In order to display an annotation on a map, your app must provide two distinct objects: ● An object that conforms to the MKAnnotation protocol and manages the data for the annotation. (This object is the annotation object.) ● A view (derived from the MKAnnotationView class) used to draw the visual representation of the annotation on the map surface. (This is the annotation view.) Annotation objects are typically small data objects that store the map coordinate data and any other relevant information about the annotation, such as a title string. Because annotations are defined using a protocol, you can turn any class in your app into an annotation object. In practice, it is good to keep annotation objects lightweight, especially if you intend to add large numbers of them to the map. The map view keeps a reference to the annotation objects you add to it and uses the data in those objects to determine when to display the corresponding view. Map Kit provides some standard annotation views and you can also define custom annotation views if you want. However, you do not add annotation views directly to the map surface. Instead, you provide an annotation view when asked for it and let the map view incorporate that view into its opaque view hierarchy. You provide the annotation view using your map view delegate object. Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38The annotations you create are typically anchored to a single map coordinate that does not change. However, you can change the coordinate for an annotation programmatically as needed and can implement support to allow the user to drag annotations around the map. In iOS 4.0 and later, support for dragging annotations is even incorporated into the Map Kit classes; implementing thissupport in prior versions of the operating system requires some additional custom code on your part. Checklist for Adding an Annotation to the Map The steps for implementing and using annotations in your map-based app are shown below. These steps assume that your app incorporates an MKMapView object somewhere in its interface. 1. Define an appropriate annotation object using one of the following options: ● Use the MKPointAnnotation class to implement a simple annotation. This type of annotation contains properties for specifying the title and subtitle strings to display in the annotation’s onscreen callout bubble. ● Define a custom object that conforms to the MKAnnotation protocol, as described in “Defining a Custom Annotation Object” (page 40). This type of annotation can store any type of data you want. 2. Define an annotation view to present the data on screen. How you define your annotation view depends on your needs and may be one of the following: ● If the annotation can be represented by a static image, create an instance of the MKAnnotationView class and assign the image to its image property; see “Using the Standard Annotation Views” (page 41). ● If you want to use a standard pin annotation, create an instance of the MKPinAnnotationView class; see “Using the Standard Annotation Views” (page 41). ● If a static image is insufficient for representing your annotation, subclass MKAnnotationView and implement the custom drawing code needed to present it. For information about how to implement custom annotation views, see “Defining a Custom Annotation View” (page 42). 3. Implement the mapView:viewForAnnotation: method in your map view delegate. Your implementation of this method should dequeue an existing annotation view if one exists or create a new one. If your app supports multiple types of annotations, you must include logic in this method to create a view of the appropriate type for the provided annotation object. For more information about implementing this method, see “Creating Annotation Views from Your Delegate Object” (page 44). 4. Add your annotation object to the map view using the addAnnotation: or addAnnotations: method. When you add an annotation to a map view, the map view displays the corresponding annotation view whenever the coordinate for the annotation is in the visible map rectangle. If you want to hide annotations selectively, you must manually remove them from the map view yourself. You can add and remove annotations at any time. Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39All annotations are drawn at the same scale every time, regardless of the map’s current zoom level. If your map contains many annotations, this could result in your annotation views overlapping each other as the user zooms out. To counter this behavior, you can add and remove annotations based on the map’s current zoom level. For example, a weather app might display information only for major cities when the map is zoomed out to show the entire state. Asthe user zoomsin, the app could then add new annotations containing weather information for smaller cities and regions. Implementing the logic necessary to add and remove annotations is your responsibility. For more information about how to manage the annotations of a map view effectively, see “Managing the Map’s Annotation Objects” (page 46). Defining a Custom Annotation Object The most important part of an annotation is the annotation object, which is an object that conforms to the MKAnnotation protocol. If all you want to do is associate a title with a map coordinate, you can use the MKPointAnnotation classfor your annotation object. However, if you need to represent additional information with the annotation, you need to define a custom annotation object. A custom annotation object consists of a map coordinate and whatever other data you want to associate with the annotation. Listing 5-1 shows the minimal code needed to declare a custom annotation class. The coordinate property declaration isfrom the MKAnnotation protocol and must be included in all annotation classes. Because this is a simple annotation, it also includes an initializer method, which is used to set the value of the coordinate property, since it is read-only. Your own declaration would likely also include methods and properties defining the additional annotation data. Listing 5-1 Creating a simple annotation object @interface MyCustomAnnotation : NSObject { CLLocationCoordinate2D coordinate; } @property (nonatomic, readonly) CLLocationCoordinate2D coordinate; - (id)initWithLocation:(CLLocationCoordinate2D)coord; // Other methods and properties. @end Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40The implementation for your custom class must provide an implementation for the coordinate property and a way to set its value. Because coordinate is a declared property, you can synthesize the code needed to implement it easily enough using the @synthesize keyword. All that remains is to implement the code for the custom initWithLocation: method, which is shown in Listing 5-2. Listing 5-2 Implementing the MyCustomAnnotation class @implementation MyCustomAnnotation @synthesize coordinate; - (id)initWithLocation:(CLLocationCoordinate2D)coord { self = [super init]; if (self) { coordinate = coord; } return self; } @end Important: When you implement the coordinate property in your class, it is recommended that you synthesize its creation. If you choose to implement the methodsfor this property yourself, or if you manually modify the variable underlying that property in other parts of your class after the annotation has been added to the map, be sure to send out notifications when you do. Map Kit uses KVO notifications to detect changes to the coordinate, title, and subtitle properties of your annotations and make any needed changes to the map display. If you do not send out KVO notifications, the position of your annotations may not be updated properly on the map. For more information about how to implement KVO-compliant accessor methods, see Key-Value Observing Programming Guide . For an example of an annotation object that is based on a Core Data object, see the sample code project WeatherMap . Using the Standard Annotation Views Using one of the standard annotation views is the easiest way to present annotations on your map. The MKAnnotationView class is a concrete view that defines the basic behavior for all annotation views. The MKPinAnnotationView class is a subclass of MKAnnotationView that displays one of the standard system pin images at the associated annotation’s coordinate point. Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41The MKAnnotationView class is perfect for situations where you have a static image that you want to display for an annotation. After creating an instance of this class, assign your custom image to the image property of the object. When the annotation is displayed, the image is displayed centered over the target map coordinate. If you do not want the image to be centered on the map coordinate, you can use the centerOffset property to move the center point horizontally and vertically in any direction. Listing 5-3 shows an example of how to create an annotation view with a custom image and offset. Listing 5-3 Creating a standard annotation view MKAnnotationView* aView = [[[MKAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:@"MyCustomAnnotation"] autorelease]; aView.image = [UIImage imageNamed:@"myimage.png"]; aView.centerOffset = CGPointMake(10, -20); You create the standard annotation views in your delegate’s mapView:viewForAnnotation: method. For more information about how to implement this method, see “Creating Annotation Views from Your Delegate Object” (page 44). Defining a Custom Annotation View If a static image is insufficient for representing your annotation, you can subclass MKAnnotationView and draw content dynamically in one of two ways. You can continue to use the image property of MKAnnotationView but change the image at regular intervals, or you can also override the view’s drawRect: method and draw your content dynamically every time. As with any custom drawing you do in a view, you should always consider performance before choosing an approach. Custom drawing gives you the most flexibility but if most of your content is fixed, using images may still be faster. If you choose to define a custom annotation view, you subclass like any other view. The only difference is that instead of subclassing UIView, you subclass MKAnnotationView as shown in Listing 5-4. Listing 5-4 Declaring a custom annotation view #import #import @interface MyCustomAnnotationView : MKAnnotationView { // Custom data members Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42} // Custom properties and methods. @end When drawing content using the drawRect: method, you must always remember to specify a nonzero frame size for your annotation view shortly after initialization. The default initialization method for annotation views does not take a frame rectangle as a parameter. Instead, it uses the image you specify in the image property to set that frame size later. If you do not set an image, though, you must set the frame property of the view explicitly in order for your rendered content to be visible, as shown in Listing 5-5. Because the view draws in only part of its frame, it also sets its opaque property to NO so that the remaining map content shows through. If you do not do this, the drawing system fills your view with the current background color before calling your drawRect: method. Listing 5-5 Initializing a custom annotation view - (id)initWithAnnotation:(id )annotation reuseIdentifier:(NSString *)reuseIdentifier { self = [super initWithAnnotation:annotation reuseIdentifier:reuseIdentifier]; if (self) { // Set the frame size to the appropriate values. CGRect myFrame = self.frame; myFrame.size.width = 40; myFrame.size.height = 40; self.frame = myFrame; // The opaque property is YES by default. Setting it to // NO allows map content to show through any unrendered // parts of your view. self.opaque = NO; } return self; } Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43In all other respects, drawing custom content in an annotation view is the same as it is in any view. The system calls your view’s drawRect: method as needed to redraw portions of the view that need it and you can force a redraw operation by calling the setNeedsDisplay or setNeedsDisplayInRect: method of your view at any time. If you want to animate the contents of your view, you need to set up a timer to fire at periodic intervals and update your view. For information on how to set up timers, see Timer Programming Topics. For information about how views draw content in iOS, see View Programming Guide for iOS . Creating Annotation Views from Your Delegate Object When it needs an annotation view, the map view calls the mapView:viewForAnnotation: method of its delegate object. If you do not implement this method, or if you implement it and always return nil, the map view uses a default annotation view, which is typically a pin annotation view. If you want to return annotation views other than the default ones, you need to override the method and create your views there. Before trying to create a new view in your mapView:viewForAnnotation: method, you should always check to see if a similar annotation view already exists. Like table views, the map view has the option of caching unused annotation views that it is not using. When it does this, it makes the unused views available from the dequeueReusableAnnotationViewWithIdentifier: method. If this method returns a value other than nil, you should update the view’s attributes and return it. If the method returns nil, just create a new instance of the appropriate annotation view class. In both cases, it is your responsibility to take the annotation passed to this method and assign it to your annotation view. You should also use this method to update the view before returning it. Listing 5-6 shows a sample implementation of the mapView:viewForAnnotation: method. This method provides pin annotation views for custom annotation objects. If an existing pin annotation view already exists, this method associates the annotation object with that view. If no view is in the reuse queue, this method creates a new one, setting up the basic properties of the view and configuring an accessory view for the annotation’s callout. If the map is currently showing the user’s location, this method returns nil for any MKUserLocation objects so that the map uses the default annotation view. Listing 5-6 Creating annotation views - (MKAnnotationView *)mapView:(MKMapView *)mapView viewForAnnotation:(id )annotation { // If it's the user location, just return nil. if ([annotation isKindOfClass:[MKUserLocation class]]) return nil; Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44// Handle any custom annotations. if ([annotation isKindOfClass:[MyCustomAnnotation class]]) { // Try to dequeue an existing pin view first. MKPinAnnotationView* pinView = (MKPinAnnotationView*)[mapView dequeueReusableAnnotationViewWithIdentifier:@"CustomPinAnnotationView"]; if (!pinView) { // If an existing pin view was not available, create one. pinView = [[[MKPinAnnotationView alloc] initWithAnnotation:annotation reuseIdentifier:@"CustomPinAnnotation"] autorelease]; pinView.pinColor = MKPinAnnotationColorRed; pinView.animatesDrop = YES; pinView.canShowCallout = YES; // Add a detail disclosure button to the callout. UIButton* rightButton = [UIButton buttonWithType: UIButtonTypeDetailDisclosure]; [rightButton addTarget:self action:@selector(myShowDetailsMethod:) forControlEvents:UIControlEventTouchUpInside]; pinView.rightCalloutAccessoryView = rightButton; } else pinView.annotation = annotation; return pinView; } return nil; } Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45Managing the Map’s Annotation Objects If your app works with more than a few annotations, you might need to think about how you manage those objects. The map view does not make any distinction between active and inactive annotations; it considers all annotation objectsit knows about to be active. As a result, it alwaystriesto display a corresponding annotation view when the given coordinate point is on the screen. If the coordinatesfor two annotations are close together, this could lead to overlap between the corresponding annotation views. And if your map includes hundreds of annotations, zooming out far enough could lead to a visually unappealing mass of annotation views. Even worse, the views may be so close together that the user cannot access some of them. The only way to eliminate annotation overcrowding is to remove some of the annotation objects from the map view. This typically involves implementing the mapView:regionWillChangeAnimated: and mapView:regionDidChangeAnimated: methods to detect changes in the map zoom level. During a zoom change, you can add or remove annotations as needed based on their proximity to one another. You might also consider other criteria (such as the user’s current location) to eliminate some annotations. In iOS 4.0 and later, Map Kit includes numerous functions to make determining the proximity of map points easier. If you convert the map coordinate of your annotation to the map point coordinate space, you can use the MKMetersBetweenMapPoints method to get absolute distances between two points. You can also use each coordinate as the center of a map rectangle and use the MKMapRectIntersectsRect function to find any intersections. For a complete list of functions, see Map Kit Functions Reference . Marking Your Annotation View as Draggable In iOS 4.0 and later, annotation views provide built-in dragging support. This support makes it very easy to drag annotations around the map and to ensure that the annotation data is updated accordingly. To implement minimal support for dragging, you must do the following: ● In your annotation objects, implement the setCoordinate: method to allow the map view to update the annotation’s coordinate point. ● When creating your annotation view, set its draggable property to YES. When the user touches and holds a draggable annotation view, the map view begins a drag operation for it. As the drag operation progresses, the map view calls the mapView:annotationView:didChangeDragState:fromOldState: method of its delegate to notify it of changes to the drag state of your view. You can use this method to affect or respond to the drag operation. If you want to animate your view during a drag operation, you can do that by implementing a custom dragState method in your annotation view. As the map view processes drag-related touch events, it updates the dragState property of the affected annotation view. Implementing a custom dragState method gives Annotating Maps Adding Annotations to a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46you a chance to intercept these changes and perform additional actions, such as animate the appearance of your view. For example, the MKPinAnnotationView class raises the pin off the map when a drag operation starts and drops the pin back down on the map when it ends. If you need to support draggable annotations in earlier versions of iOS, you must implement the support for it yourself. For information and sample code showing how to do it, see “Legacy Map Techniques” (page 64). Displaying Overlays on a Map Overlays offer a way to layer content over an arbitrary region of the map. Whereas annotations are always defined by a single map coordinate, overlays are typically defined by multiple coordinates. You can use these coordinates to create contiguous or noncontiguous sets of lines, rectangles, circles, and other shapes, which Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47can then be filled or stroked with color. For example, you might use overlays to layer traffic information on top of roadways, highlight the boundaries of a park, or show city, state, and national borders. Figure 5-2 shows a filled and stroked overlay covering the state of Colorado. Figure 5-2 Displaying an overlay on a map In order to display an overlay on a map, your app must provide two distinct objects: ● An object that conforms to the MKOverlay protocol and manages the data points for the overlay. (This object is the overlay object.) ● A view (derived from the MKOverlayView class) used to draw the visual representation of the overlay on the map surface. (This is the overlay view.) Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48Overlay objects are typically small data objects that store the points that define the overlay and any other relevant information, such as a title string. Because overlays are defined using a protocol, you can turn any class in your app into an overlay object. In addition, Map Kit defines several concrete overlay objects for specifying different types of standard shapes. The map view keeps a reference to the overlay objects you add to it and uses the data in those objects to determine when to display a corresponding view. Map Kit provides standard overlay views that are capable of drawing any shapes represented by the concrete overlay objects. Like annotations, you do not add overlay views directly to the map surface. Instead, you provide an overlay view when asked for it and let the map view incorporate that view into its opaque view hierarchy. You provide the annotation view using your map view delegate object. Once defined, the position of an overlay on the map typically never changes. Although it is possible to create draggable overlays, doing so israre and you would need to implement the code to track the dragging operation and update the overlay coordinate points yourself. Checklist for Adding an Overlay to the Map Here are the steps for implementing and using overlays in your map-based app. These steps assume that your app incorporates an MKMapView object somewhere in its interface. 1. Define an appropriate overlay data object using one of the following options: ● Use the MKCircle, MKPolygon, or MKPolyline class as-is. ● Subclass MKShape or MKMultiPoint to create overlays that provide app-specific behaviors or use custom shapes. ● Use an existing class from your app and make it conform to the MKOverlay protocol. 2. Define an overlay view to present on the screen using one of the following options: ● For standard shapes, use the MKCircleView, MKPolygonView, or MKPolylineView to represent the annotation. You can customize many of the drawing attributes of the final shape using these classes. ● For custom shapes descended from MKShape, define an appropriate subclass of MKOverlayPathView to render the shape. ● For all other custom shapes and overlays, subclass MKOverlayView and implement your custom drawing code. 3. Implement the mapView:viewForOverlay: method in your map view delegate. 4. Add your overlay data object to the map view using the addOverlay: method or one of many others. Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49Unlike annotations, rendered overlays are automatically scaled to match the current zoom level of the map. Scaling the overlay is necessary because overlays generally highlight boundaries, roads, and other content that also scales during zooming. In addition, you can rearrange their Z-ordering of overlays in a map to ensure that specific overlays are always displayed on top of others. Using the Standard Overlay Objects and Views If all you want to do is highlight a specified map region, the standard overlay classes are the easiest way to do it. The standard overlay classes include MKCircle, MKPolygon, and MKPolyline. These classes define the basic shape of the overlay and are used in conjunction with the MKCircleView, MKPolygonView, or MKPolylineView classes, which handle the rendering of that shape on the map surface. Listing 5-7 shows an example of how you would create the rectangular polygon shown in Figure 5-2 (page 48). This polygon consists of four map coordinates that correspond to the four corners of the state of Colorado. After creating the polygon, all you have to do is add it to the map using the addOverlay: method. Listing 5-7 Creating a polygon overlay object // Define an overlay that covers Colorado. CLLocationCoordinate2D points[4]; points[0] = CLLocationCoordinate2DMake(41.000512, -109.050116); points[1] = CLLocationCoordinate2DMake(41.002371, -102.052066); points[2] = CLLocationCoordinate2DMake(36.993076, -102.041981); points[3] = CLLocationCoordinate2DMake(36.99892, -109.045267); MKPolygon* poly = [MKPolygon polygonWithCoordinates:points count:4]; poly.title = @"Colorado"; [map addOverlay:poly]; In order for an overlay can be shown on the map, the mapView:viewForOverlay: method of your map view delegate needs to provide an appropriate overlay view. For the standard overlay shapes, you can do this by creating a view that matches the type of shape you want to display. Listing 5-8 shows an implementation of this method that creates the polygon view used to cover the state of Colorado. In this example, the method sets the colors to use for rendering the shape and the border width. Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50Listing 5-8 Creating a polygon view for rendering a shape - (MKOverlayView *)mapView:(MKMapView *)mapView viewForOverlay:(id )overlay { if ([overlay isKindOfClass:[MKPolygon class]]) { MKPolygonView* aView = [[[MKPolygonView alloc] initWithPolygon:(MKPolygon*)overlay] autorelease]; aView.fillColor = [[UIColor cyanColor] colorWithAlphaComponent:0.2]; aView.strokeColor = [[UIColor blueColor] colorWithAlphaComponent:0.7]; aView.lineWidth = 3; return aView; } return nil; } It is important to remember that the standard overlay views are there to simply fill and stroke the shape represented by the overlay. If you want to display additional information, you need to create a custom overlay view to do the necessary drawing. You should avoid adding subviews to an existing overlay in an attempt to render any extra content. Any subviews you add to an overlay are scaled along with the overlay itself and made to fit the zoom level of the map. Unless your subviews contain content that also scales well, the results would probably not look very good. Defining a Custom Overlay Object The job of an overlay object is to manage the coordinate data and any additional information associated with the overlay. Map Kit provides a couple of options for defining custom overlays. You can subclass MKShape or MKMultiPoint to define new types of shape-based overlays or you can adopt the MKOverlay protocol into one of your app’s existing classes. The choice between the two techniques depends mostly on whether you already have a class with the data you want. If you do, you should incorporate the protocol into your existing class; otherwise, subclass MKShape or MKMultiPoint to create a custom shape subclass. Whether you subclass or adopt the MKOverlay protocol, the work you have to do in any custom overlay object is the same. The main job of an overlay object is to vend two key pieces of information: ● A coordinate defining the center point of the overlay Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51● A bounding rectangle that completely encompasses the overlay’s content Of the two pieces of information, the bounding rectangle isthe one that is most important to the overlay itself. The map view uses the bounding rectangle specified by an overlay object as its cue for when to add the corresponding overlay view to the map. (If you add the overlay to the map as an annotation as well, the coordinate value similarly determines when the corresponding annotation view should be added to the map.) The bounding rectangle itself must be specified using map points, not map coordinates. You can convert between the two coordinate systems using the Map Kit functions. Most of the real work involved with displaying an overlay isincurred by the corresponding overlay view object. The overlay object simply defines where on the map the overlay should be placed, whereas the overlay view defines the final appearance of the overlay, including what information (if any) is displayed for the overlay. The creation of custom overlay views is described further in “Defining a Custom Overlay View” (page 52). Defining a Custom Overlay View If you want to do more than draw the boundaries or fill the content of your overlay shape, you need to create a custom overlay view. Custom overlays give you the opportunity to draw any content you want. For example, if you are drawing a traffic overlay, you could use a custom overlay view to color-code each roadway based on its conditions. You can also use custom drawing code to animate your overlay’s appearance. To create a custom overlay view, you mustsubclass MKOverlayView. (If you simply want to modify the drawing behavior of an existing shape-based overlay, you can subclass MKOverlayPathView instead.) In your custom implementation, you should implement the following methods: ● drawMapRect:zoomScale:inContext: to draw your custom content ● canDrawMapRect:zoomScale: if your drawing code depends on content that might not always be available The canDrawMapRect:zoomScale: method is for situations where your content may not always be ready to draw. For example, a traffic overlay would need to download the needed traffic data from the network before it could draw. If you return NO from this method, the map view refrains from drawing your view until you signal that you are ready. You can do this by marking your view as dirty using either the setNeedsDisplayInMapRect: or setNeedsDisplayInMapRect:zoomScale: method. When your view is ready to draw, the map view calls the drawMapRect:zoomScale:inContext: method to do the actual drawing. Unlike drawing in a normal view, drawing in an overlay view involves some special considerations, including the following: Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52● Your drawing code should never use the view’s bounds or frame as reference points for drawing. Instead, it should use the map points associated with the overlay object to define shapes. Immediately before drawing, it should then convert those map points to points (CGPoint and so on) using the conversion routines found in the MKOverlayView class. Also, you typically do not apply the zoom scale value passed to this method directly to your content. Instead, you provide it only when a Map Kit function or method specifically requires it. As long as you specify content using map points and convert to points, your content should be scaled to the correct size automatically. ● If you use UIKit classes and functions to draw, you must explicitly set up and clean up the drawing environment. Before issuing any calls, call the UIGraphicsPushContext function to make the context passed to your method the current context. When you are done drawing, call UIGraphicsPopContext to remove that context. ● Remember that the map view may tile large overlays and render each tile on a separate thread. Your drawing code should therefore not attempt to modify variables or other data unless it can do so in a thread-safe manner. Listing 5-9 shows the drawing code used to fill the bounding rectangle of an overlay using a gradient. When drawing gradients, it is especially important to contain the drawing operation by applying a clipping rectangle to the desired drawing area. The view’s frame is actually larger than the overlay’s bounding rectangle, so without a clipping rectangle, the gradient would render outside the expected area. Because the bounding rectangle of the overlay definesthe actualshape in this case, this method simply clipsto the bounding rectangle. For more complex overlays, you would want to clip to the path representing your overlay. The results of this drawing code are shown in Figure 5-3 (page 55). Listing 5-9 Drawing a gradient in a custom overlay view - (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale inContext:(CGContextRef)context { // Get the overlay bounding rectangle. MKMapRect theMapRect = [self.overlay boundingMapRect]; CGRect theRect = [self rectForMapRect:theMapRect]; // Clip the context to the bounding rectangle. CGContextAddRect(context, theRect); CGContextClip(context); // Set up the gradient color and location information. Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53CGColorSpaceRef myColorSpace = CGColorSpaceCreateDeviceRGB(); CGFloat locations[4] = {0.0, 0.33, 0.66, 1.0}; CGFloat components[16] = {0.0, 0.0, 1.0, 0.5, 1.0, 1.0, 1.0, 0.8, 1.0, 1.0, 1.0, 0.8, 0.0, 0.0, 1.0, 0.5}; // Create the gradient. CGGradientRef myGradient = CGGradientCreateWithColorComponents(myColorSpace, components, locations, 4); CGPoint start, end; start = CGPointMake(CGRectGetMidX(theRect), CGRectGetMinY(theRect)); end = CGPointMake(CGRectGetMidX(theRect), CGRectGetMaxY(theRect)); // Draw. CGContextDrawLinearGradient(context, myGradient, start, end, 0); // Clean up. CGColorSpaceRelease(myColorSpace); CGGradientRelease(myGradient); } Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54Figure 5-3 shows the results of drawing custom content over the overlay for the state of Colorado. In this case, the overlay view fills its content with a custom gradient. Figure 5-3 Using a custom overlay view to draw Creating Overlay Views from Your Delegate Object When it needs an overlay view, the map view calls the mapView:viewForOverlay: method of its delegate object. If you do not implement this method, or if you implement it and always return nil, the map view does not display anything for the specified overlay. Therefore, you must implement this method and return a valid overlay view for any overlays you want displayed on the map. For the most part, every overlay is different. Although you should always create your overlay views in your mapView:viewForOverlay: method, you may need to be a little more creative in how you configure those views. If all of your views share the same drawing attributes, you can implement this method in a way similar Annotating Maps Displaying Overlays on a Map 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55to the one shown in Listing 5-8 (page 51). However, if each overlay uses different colors or drawing attributes, you should find a way to initialize that information using the annotation object, rather than having a large decision tree in this method. Because overlays are typically different from one another, the map view does not recycle those views when they are removed from the map. Instead of dequeueing an existing overlay view, you must create a new overlay view every time. Managing the Map’s Overlay Objects If your app works with more than one overlay, you might need to think about how to manage those objects. Like annotations, the overlays associated with a map are always displayed when any portion of the overlay intersects the visible portion of the map. Unlike annotations, overlays scale proportionally with the map and therefore do not automatically overlap one another. This means, you are less likely to have to remove overlays and add them later to prevent overcrowding. In cases where the bounding rectangles of two overlays do overlap, you can either remove one of the overlays or arrange their Z-order to control which one appears on top. The overlays property of the MKMapView class stores the registered overlays in an ordered array. The order of the objects in this array matches the Z-order of the objects at render time, with the first object in the array representing the bottom of the Z-order. To place an overlay on top of all other overlays, you add it to the end of this array. You can also insert objects at different pointsin the array and exchange the position of two objects in the array using the map view’s methods. If you decide to implement some type of overlap-detection algorithm for overlays, one place to do so is in the mapView:didAddOverlayViews: method of your map view delegate. When this method is called, you can use the MKMapRectIntersectsRect function to see if the added overlay intersects the bounds of any other overlays. If there is an overlap, use whatever custom logic is needed to choose which one should be placed on top in the rendering tree and exchange positions as needed. (Because the map view is an interface item, any modifications to the overlays array should be synchronized and performed on the app’s main thread. The actual comparisons may occur on a different thread, though.) Using Overlays as Annotations The MKOverlay protocol conforms to the MKAnnotation protocol. As a result, all overlay objects are also annotation objects and can be treated as one or both in your code. If you opt to treat an overlay object as both, you are responsible for managing that object in two places. If you want to display both an overlay view Annotating Maps Using Overlays as Annotations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56and annotation view for it, you must implement both the mapView:viewForOverlay: and mapView:viewForAnnotation: methodsin your app delegate. It also meansthat you must add and remove the object from both the overlays and annotations arrays of your map. Annotating Maps Using Overlays as Annotations 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 57In iOS 6 and later, Map Kit offerssupport for providing map-based directionsto the user. Apps can be a provider of directions or they can use the Maps app itself to provide directions. Appsthat consume direction information do so by sending an appropriate request to the Maps app, which then handles the task of displaying that information to the user. However, if you are implementing a navigation app of your own, you can register your app as a routing app—that is, a provider of directions. When the Maps app receives direction requests from the user (or other apps), it can then forward those requests to your app for display. Asking the Maps App to Display Directions Map Kit provides a way for you to display specific map locations or turn-by-turn directions using the Maps app. This support allows apps to use the Maps app in situations where you might not want to display the map data yourself. For example, if your app does not have its own turn-by-turn navigation services, you can ask Maps to provide the information for you. To generate a direction request, use the openMapsWithItems:launchOptions: or openInMapsWithLaunchOptions: method of MKMapItem. These methods let you send map items to the Maps app so that it can display them. If you include the MKLaunchOptionsDirectionsModeKey key with the launch options you pass to these methods, Maps attempts to display directions from the start and end points you specify. For information about how to use these methods, see MKMapItem Class Reference . Registering as a Routing App Apps that are able to display point-to-point directions can register as a routing app and make those directions available to the Maps app and to all other apps on a user’s device by extension. Registering as a routing app improves the user experience by giving other apps a means to access routing information from your app, thus avoiding the need for every app to provide its own routing directions. It is also a great way to get your app in front of the user. Maps always displays appropriate suggestions from the App Store as options for displaying directions. To register your app as a directions provider, you must do the following: 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 58 Providing Directions● Configure your app’s Info.plist with the keys needed to indicate the type of directions your app offers and the handlers you use to process incoming directions requests. ● Declare the map regions that your app supports using a geographic coverage file (specified using a GeoJSON file). ● Process direction request URLs when they are sent to your app. Configuring Your App to Accept Direction Requests To enable directions support for your app, you must configure the following support for your app target in Xcode: ● Enable directions support for your app. ● Configure a special document type to handle requests for directions. You enable directions support in the Maps section of your target’s Summary tab. In addition to enabling directions, you also specify the types of directions (pedestrian, car, subway, and so on) your app is able to provide. Enabling directions support adds the MKDirectionsApplicationSupportedModes key to your app’s Info.plist file and sets the value of the key to the transportation modes you select. These keys act as a signal to the system (and to iTunes Connect) that your app provides directions and has an associated GeoJSON file. (For more information about specifying the GeoJSON file, see “Declaring the Supported Geographic Coverage for Directions” (page 60).) In addition to declaring the types of directions your app supports, you need to declare support for a special document type. The Maps app uses this document type to send URLs with direction requests to your app. To add the document type, use the Xcode document type editor, located in the Info tab of your target. After adding a new document type, use the information in Table 6-1 to set the values for the type. You should use the values in this table exactly as they appear here. Table 6-1 Keys and values for the directions request document type Xcode field Value Description The value in this field can be anything you want, but you are encouraged to use the suggested value. Name MKDirectionsRequest The value of this key is a custom UTI type used to identify direction requests. The value of this key must be exactly as shown here. Types com.apple.maps.directionsrequest Providing Directions Registering as a Routing App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 59The changes you make in the document types editor cause Xcode to add a corresponding entry to the CFBundleDocumentTypes key in your app’s Info.plist file. For more information about your app’s Info.plist file and the keys you put into it, see Information Property List Key Reference . Declaring the Supported Geographic Coverage for Directions Apps must declare the geographic regions for which they are capable of providing directions. Declaring the supported regions prevents the system from sending requests that your app is unable to handle. For example, if your app provides subway route information only for New York, you would not want it to receive requests to provide directions in London. To declare your app’s supported regions, you must create a GeoJSON file, which is a type of JavaScript Object Notation (JSON) file. This is your app’s geographic coverage file and it contains a set of map coordinates that define the boundaries of one or more geographic regions. The format of thisfile is part of a public specification, the details of which you can obtain at http://geojson.org/geojson-spec.html. Your geographic coverage file is used by the Maps app and the App Store, but not by your app. Uploading it to iTunes Connect makes it possible for Maps to look up apps on the App Store that are capable of providing directions in the target region. It can then provide the user with that information in case the user wants to download one of those apps. Because you upload it to iTunes Connect, you can also update the file at any time without submitting a new version of your app. Specifying the Geographic Coverage File Contents The geographic coverage file for an iOS app must contain a single MultiPolygon shape that defines the boundaries of the supported geographic regions. A single multi polygon may contain any number of child polygons, each of which defines the boundaries around a single geographic region. Each polygon contains four or more coordinate valuesthat define the boundaries of the polygon. Per the GeoJSON specification, every polygon must represent a closed region—that is, the first and last coordinate values must always be identical. Therefore, you must specify at least four points to define a triangular region, which is the simplest possible shape. Of course, you can use include more points to define more complex polygons. Listing 6-1 shows an example of a geographic coverage file that specifies two separate regions: one around San Francisco and one around Chicago. Note that the set of coordinates for each region are surrounded by whatseem to be an extra set of brackets. In each case, the first open bracket marksthe beginning of the overall polygon shape, the second open bracket defines the beginning of the exterior bounding polygon, and the third open bracket marks the beginning of the first coordinate. After closing the exterior bounding polygon, you could add additional sets of points that define holes in the polygonal region. Providing Directions Registering as a Routing App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 60Listing 6-1 A sample GeoJSON file { "type": "MultiPolygon", "coordinates": [ [[[-122.7, 37.3], [-121.9, 37.3], [-121.9, 37.9], [-122.7, 37.9], [-122.7, 37.3]]], [[[-87.9, 41.5], [-87.3, 41.5], [-87.3, 42.1], [-87.9, 42.1], [-87.9, 41.5]]] ] } Use the following guidelines to help you when defining the regions for your app: ● Keep your regions simple and do not try to trace precise routes around a given geographic area. Although you can technically use hundreds of coordinates to define a region, doing so is inefficient and usually unnecessary. The system has to determine whether a given point is inside one of your polygons. Using a shape that contains hundreds of points is far less efficient than specifying a rectangular polygon around the region. ● Only specify regions for which you can provide useful directions to the user. ● Use only MultiPolygon shape in your app’s coverage file. Although the GeoJSON specification supports other types of shapes, only MultiPolygon shapes are supported for routing apps. ● Do not include comments in your coverage file. ● All coordinates must be specified as a longitude followed by a latitude value. ● The polygonsin your coverage files must not include holes. Although holes are supported by the GeoJSON specification, they are not supported in Apple’s maps implementation. Uploading Your GeoJSON File to iTunes Connect When you upload your app to iTunes Connect, the server checks your app’s Info.plist file for the presence of the MKDirectionsApplicationSupportedModes key. If that key is present, the iTunes Connect page for your app includes a space for uploading your geographic coverage file. You must upload the file before your app can be approved. See “Uploading Icons, Screenshots, and Routing Files for Your App” in iTunes Connect Developer Guide for more information. Debugging Your App’s Geographic Coverage File During development, you use the scheme options of your Xcode project to specify the geographic coverage file to use during testing. When you run your app in the simulator, Xcode transfers this file to the simulator or device so that the Maps app knows about the regions your app supports. The content of this file should be identical to the file you plan to upload to iTunes Connect. Providing Directions Registering as a Routing App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 61To specify the geographic coverage file for testing, do the following: 1. Open the scheme editor for your project. 2. Select the Run (Debug) scheme for your project. 3. In the Options tab, select your coverage file from the Routing App Coverage File popup menu. After installing your app on the device or simulator, exit your app and launch the Maps app to specify the start and end points for directions. Your app should appear if its geographic coverage file is valid and contains the two specified points. If it does not, check the pointsfor your geographical regionsto make sure they are correct. Note: If you are running in the simulator and the Maps does not display your app as one of the possible options, check the Console app for any possible error messages. Mapsreports any problems it encounters when reading your app’s GeoJSON to the console output rather than to Xcode. Handling Direction Requests The system sends direction requests to your app using URLs. When the user asks the Maps app for directions and chooses your app, Maps creates a URL with the start and end points and asks your app to open it. You handle the opening of this URL in your app’s application:openURL:sourceApplication:annotation: method, just like you would for other URLs. But the steps you take to processthe URL are a little more prescribed. When your app receives a URL to open, it should perform the following steps in its application:openURL:sourceApplication:annotation: method: 1. Call the isDirectionsRequestURL: class method of MKDirectionsRequest to check whether the URL is a directions request URL. If it is a directions request, proceed with the remaining steps. 2. Create an MKDirectionsRequest object using the provided URL. 3. Obtain the start and end points of the route from the MKDirectionsRequest object. The start and end points are specified as MKMapItem objects, which contain the geographic coordinate of the location and possibly additional information. If the MKMapItem object represents the user’s current location, you need to use Core Location to retrieve the actual coordinate location data yourself. 4. Compute and display the route using your custom routing technology. Because the preceding steps are the same for every app, you can include code in your application:openURL:sourceApplication:annotation: method similar to that shown in Listing 6-2. The most important addition you must make is to compute the route information and display it in your app. If your app handles other URL types, you would also include code for processing those URLs separately. Providing Directions Registering as a Routing App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 62Listing 6-2 Handling a directions request URL - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { if ([MKDirectionsRequest isDirectionsRequestURL:url]) { MKDirectionsRequest* directionsInfo = [[MKDirectionsRequest alloc] initWithContentsOfURL:url]; // TO DO: Plot and display the route using the // source and destination properties of directionsInfo. return YES; } else { // Handle other URL types... } return NO; } For additional information about using the MKDirectionsRequest class, see MKDirectionsRequest Class Reference . Providing Directions Registering as a Routing App 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 63Creating Draggable Annotations in Earlier Versions of iOS If you want to support draggable annotationsin iOS 3.x, you must implement the code for tracking drag-related touches yourself. Although they live in a special layer above the map content, annotation views are full-fledged views capable of receiving touch events. You can use these events to detect hits within the view and initiate a drag operation. Note: Because maps are displayed in a scrolling interface, there is typically a short delay between the time the user touches your custom view and the time corresponding events are delivered. This delay gives the underlying scroll view a chance to determine whether the touch event is part of a scrolling gesture. The following sequence of code listings shows you how to implement a user-movable annotation view in iOS 3.x. In this example, the annotation view displays a bulls-eye image directly over the annotation’s coordinate point and includes a custom accessory view for displaying details about the target. Listing A-1 shows the definition of the BullseyeAnnotationView class. The class includes some additional member variables that it uses during tracking to move the view correctly. It also stores a pointer to the map view itself, the value for which is set by the code in the mapView:viewForAnnotation: method when it creates or reinitializes the annotation view. The map view object is needed when event tracking is finished to adjust the map coordinate of the annotation object. Listing A-1 The BullseyeAnnotationView class @interface BullseyeAnnotationView : MKAnnotationView { BOOL isMoving; CGPoint startLocation; CGPoint originalCenter; MKMapView* map; } 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 64 Legacy Map Techniques@property (assign,nonatomic) MKMapView* map; - (id)initWithAnnotation:(id )annotation; @end @implementation BullseyeAnnotationView @synthesize map; - (id)initWithAnnotation:(id )annotation { self = [super initWithAnnotation:annotation reuseIdentifier:@"BullseyeAnnotation"]; if (self) { UIImage* theImage = [UIImage imageNamed:@"bullseye32.png"]; if (!theImage) return nil; self.image = theImage; self.canShowCallout = YES; self.multipleTouchEnabled = NO; map = nil; UIButton* rightButton = [UIButton buttonWithType: UIButtonTypeDetailDisclosure]; [rightButton addTarget:self action:@selector(myShowAnnotationAddress:) forControlEvents:UIControlEventTouchUpInside]; self.rightCalloutAccessoryView = rightButton; } return self; } @end Legacy Map Techniques Creating Draggable Annotations in Earlier Versions of iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 65When a touch event first arrives in a bulls-eye view, the touchesBegan:withEvent: method of that class records information about the initial touch event, as shown in Listing A-2. It uses this information later in its touchesMoved:withEvent: method to adjust the position of the view. All location information is stored in the coordinate space of the superview. Listing A-2 Tracking the view’s location @implementation BullseyeAnnotationView (TouchBeginMethods) - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { // The view is configured for single touches only. UITouch* aTouch = [touches anyObject]; startLocation = [aTouch locationInView:[self superview]]; originalCenter = self.center; [super touchesBegan:touches withEvent:event]; } - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { UITouch* aTouch = [touches anyObject]; CGPoint newLocation = [aTouch locationInView:[self superview]]; CGPoint newCenter; // If the user's finger moved more than 5 pixels, begin the drag. if ( (abs(newLocation.x - startLocation.x) > 5.0) || (abs(newLocation.y - startLocation.y) > 5.0) ) isMoving = YES; // If dragging has begun, adjust the position of the view. if (isMoving) { newCenter.x = originalCenter.x + (newLocation.x - startLocation.x); newCenter.y = originalCenter.y + (newLocation.y - startLocation.y); self.center = newCenter; } Legacy Map Techniques Creating Draggable Annotations in Earlier Versions of iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 66else // Let the parent class handle it. [super touchesMoved:touches withEvent:event]; } @end When the userstops dragging an annotation view, you need to adjust the coordinate of the original annotation to ensure the view remains in the new position. Listing A-3 shows the touchesEnded:withEvent: method forthe BullseyeAnnotationView class. Thismethod usesthemapmember variable to convertthe pixel-based point into a map coordinate value. Because the coordinate property of an annotation is normally read-only, the annotation object in this case implements a custom changeCoordinate method to update the value it stores locally and reports using the coordinate property. If the touch event was canceled for some reason, the touchesCancelled:withEvent: method returns the annotation view to its original position. Listing A-3 Handling the final touch events @implementation BullseyeAnnotationView (TouchEndMethods) - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { if (isMoving) { // Update the map coordinate to reflect the new position. CGPoint newCenter = self.center; BullseyeAnnotation* theAnnotation = self.annotation; CLLocationCoordinate2D newCoordinate = [map convertPoint:newCenter toCoordinateFromView:self.superview]; [theAnnotation changeCoordinate:newCoordinate]; // Clean up the state information. startLocation = CGPointZero; originalCenter = CGPointZero; isMoving = NO; } else [super touchesEnded:touches withEvent:event]; } Legacy Map Techniques Creating Draggable Annotations in Earlier Versions of iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 67- (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { if (isMoving) { // Move the view back to its starting point. self.center = originalCenter; // Clean up the state information. startLocation = CGPointZero; originalCenter = CGPointZero; isMoving = NO; } else [super touchesCancelled:touches withEvent:event]; } @end Legacy Map Techniques Creating Draggable Annotations in Earlier Versions of iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 68This table describes the changes to Location Awareness Programming Guide . Date Notes 2012-09-19 Added information about how to support custom routing directions. 2011-10-12 Added information about the new Core Location geocoders. 2010-05-20 Added information about region monitoring. Added information about creating overlays. Expanded the existing information about maps and annotations. Updated the location-related sections to cover new technologies for obtaining the user’s location. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 69 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, Chicago, iTunes, New York, Objective-C, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. App Store is a service mark of Apple Inc. Java is a registered trademark of Oracle and/or its affiliates. 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. Shark User Guide (Legacy)Contents Introduction 12 Overview 12 Philosophy 12 Organization of This Document 13 Getting Started with Shark 16 Main Window 16 Mini Configuration Editors 18 Perform Sampling 18 Session Windows and Files 19 Session Files 20 Session Information Sheet 21 Session Report 22 Advanced Settings Drawer 22 Shark Preferences 23 Time Profiling 28 Statistical Sampling 28 Taking a Time Profile 30 Profile Browser 31 Heavy View 35 Tree View 35 Profile Display Preferences 37 Chart View 39 Advanced Chart View Settings 42 Code Browser 45 Assembly Browser 48 Advanced Code Browser Settings 50 ISA Reference Window 54 Tips and Tricks 56 Example: Optimizing MPEG-2 using Time Profiles 58 Base 58 Vectorization 60 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 2System Tracing 63 Tracing Methodology 63 Basic Usage 64 Interpreting Sessions 66 Summary View In-depth 67 Trace View In-depth 73 Timeline View In-depth 77 Sign Posts 90 Tips and Tricks 93 Other Profiling and Tracing Techniques 97 Time Profile (All Thread States) 97 Malloc Trace 101 Using a Malloc Trace 102 Advanced Display Options 105 Static Analysis 107 Using Shark with Java Programs 108 Java Tracing Techniques 109 Linking Shark with the Java Virtual Machine 110 Event Counting and Profiling Overview 111 Timed Counters: The Performance Counter Spreadsheet 111 Event-Driven Counters: Correlating Events with Your Code 119 Advanced Profiling Control 122 Process Attach 122 Process Launch 122 Batch Mode 125 Windowed Time Facility (WTF) 125 WTF with System Trace 127 Unresponsive Application Measurements 128 Command Line Shark 129 Basic Methodology 130 Common Options 131 Target Selection 132 Reports 133 Custom Configurations 133 More Information 134 Interprocess Remote Control 134 Programmatic Control 134 Command Line Remote Control 137 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsNetwork/iPhone Profiling 138 Using Shared Profiling Mode 141 Mac OS X Firewall Considerations 143 Advanced Session Management and Data Mining 145 Automatic Symbolication Troubleshooting 145 Symbol Lookup 145 Debugging Information 146 Manual Session Symbolication 146 Managing Sessions 150 Comparing Sessions 150 Merging Sessions 151 Data Mining 151 Callstack Data Mining 152 Perf Count Data Mining 157 Example: Using Data Mining with a Time Profile 158 A Performance Problem... 158 Taking Samples 160 High Level Analysis 162 Analysis Via Source Navigation 163 Introduction To Focusing 168 Dig Deeper by Charging Costs 173 Example: Graphical Analysis using Chart View with a Malloc Trace 176 Taking Samples 176 Graphical Analysis of a Malloc Trace 179 Custom Configurations 183 The Config Editor 184 Simple Timed Samples and Counters Config Editor 186 Malloc Data Source PlugIn Editor 189 Static Analysis Data Source PlugIn Editor 190 Java Trace Data Source PlugIn Editor 191 Sampler Data Source PlugIn Editor 192 System Trace Data Source PlugIn Editor 193 All Thread States Data Source PlugIn Editor 194 Analysis and Viewer PlugIn Summary 195 Counter Spreadsheet Analysis PlugIn Editor 196 Using the Editor 196 Spreadsheet Configuration Example 199 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsHardware Counter Configuration 202 Configuring the Sampling Technique: The Sampling Tab 202 Common Elements in Performance Counter Configuration Tabs 206 Counter Control 206 Privilege Level Filtering 207 Process Marking 207 MacOS X OS-Level Counters Configuration 208 Intel CPU Performance Counter Configuration 209 PowerPC G3/G4/G4+ CPU Performance Counter Configuration 211 PowerPC G5 (970) Performance Counter Configuration 213 PowerPC North Bridge Counter Configuration 221 U1.5/U2 North Bridges 222 U3 North Bridge 223 U4 (Kodiak) North Bridge 226 ARM11 CPU Performance Counter Configuration 229 Command Reference 230 Menu Reference 230 Shark 230 File 230 Edit 231 Format 233 Config 233 Sampling 234 Data Mining 235 Window 235 Help 236 Alphabetical Reference 236 Miscellaneous Topics 242 Code Analysis with the G5 (PPC970) Model 242 Supervisor Space Sampling Guidelines 243 Intel Core Performance Counter Event List 246 Intel Core 2 Performance Counter Event List 252 PPC 750 (G3) Performance Counter Event List 263 PPC 7400 (G4) Performance Counter Event List 265 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 5 ContentsPPC 7450 (G4+) Performance Counter Event List 271 PPC 970 (G5) Performance Counter Event List 282 UniNorth-2 (U1.5/2) Performance Counter Event List 315 UniNorth-3 (U3) Performance Counter Event List 318 Kodiak (U4) Performance Counter Event List 322 ARM11 Performance Counter Event List 326 Document Revision History 328 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 6 ContentsFigures, Tables, and Listings Getting Started with Shark 16 Figure 1-1 Main Window 16 Figure 1-2 Process Target 17 Figure 1-3 Mini Configuration Editor 18 Figure 1-4 Session Inspector Panel 21 Figure 1-5 Sample Window with Advanced Settings Drawer visible at right 23 Figure 1-6 Shark Preferences — Appearance 24 Figure 1-7 Shark Preferences — Sampling 25 Figure 1-8 Shark Preferences — Sessions 26 Figure 1-9 Shark Preferences — Search Paths 27 Time Profiling 28 Figure 2-1 Execution Before Sampling 29 Figure 2-2 Sampling Results 29 Figure 2-3 Time Profile mini-configuration editor 31 Figure 2-4 The Profile Browser 32 Figure 2-5 Tuning Advice 33 Figure 2-6 Callstack Table 34 Figure 2-7 Heavy Profile View Detail 35 Figure 2-8 Tree Profile View 36 Figure 2-9 Profile Analysis Preferences 37 Figure 2-10 Chart View 40 Figure 2-11 Advanced Settings for the Chart View 44 Figure 2-12 Code Browser 45 Figure 2-13 Hot Spot Scrollbar 47 Figure 2-14 Assembly Browser 50 Figure 2-15 Advanced Settings for the Code Browser 53 Figure 2-16 x86 Asm Browser Advanced Settings 54 Figure 2-17 ARM Asm Browser Advanced Settings 54 Figure 2-18 ISA Reference Window 55 Figure 2-19 Original Time Profile, with Tuning Advice 59 Figure 2-20 Code Browser with Vectorization Hint 61 Figure 2-21 Time Profile after Vectorizing IDCT 61 Table 2-1 MPEG-2 Performance Improvement 61 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 7System Tracing 63 Figure 3-1 Time Profile vs. System Trace Comparison 64 Figure 3-2 System Trace Mini Config Editor 65 Figure 3-3 Summary View 67 Figure 3-4 Summary View: Scheduler 68 Figure 3-5 Summary View: System Calls 69 Figure 3-6 Summary View: VM Faults 71 Figure 3-7 Summary View Advanced Settings Drawer 72 Figure 3-8 Trace View: Scheduler 74 Figure 3-9 Trace View: System Calls 75 Figure 3-10 Trace View: VM Faults 77 Figure 3-11 Timeline View 78 Figure 3-12 Timeline View: Thread Run Intervals 79 Figure 3-13 Thread Run Interval Inspector 79 Figure 3-14 Timeline View: System Calls 81 Figure 3-15 System Call Inspector 82 Figure 3-16 Timeline View: VM Faults 83 Figure 3-17 VM Fault Inspector 84 Figure 3-18 Interrupt Inspector 85 Figure 3-19 Sign Post Inspector 86 Figure 3-20 Timeline View Advanced Settings Drawer 89 Listing 3-1 ~/Library/Application Support/Shark/KDebugCodes/myFirstSignPosts 90 Listing 3-2 signPostExample.c 92 Listing 3-3 testKernelSignPost.c 92 Other Profiling and Tracing Techniques 97 Figure 4-1 Time Profile (All Thread States) mini configuration editor 98 Figure 4-2 Time Profile (All Thread States) session, heavy view 99 Figure 4-3 Time Profile (All Thread States) session, tree view 100 Figure 4-4 Malloc Trace mini configuration editor 102 Figure 4-5 Malloc Trace session, profile browser 103 Figure 4-6 Malloc Trace session, chart view 104 Figure 4-7 Enabling Malloc Trace Advanced Options 105 Figure 4-8 Additional Malloc Trace Charts 106 Figure 4-9 Static Analysis mini configuration editor 108 Figure 4-10 How Shark-for-Java differs from regular Shark configurations 109 Figure 4-11 Performance Counter Spreadsheet 114 Figure 4-12 Counters Menu 115 Figure 4-13 Performance Counter Spreadsheet: Advanced Settings 116 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 8 Figures, Tables, and ListingsFigure 4-14 Chart View with additional timed counter graphs 121 Advanced Profiling Control 122 Figure 5-1 Process Attach 122 Figure 5-2 Launch Process Panel 123 Figure 5-3 Batch Mode 125 Figure 5-4 Normal Profiling Workflow 126 Figure 5-5 Windowed Time Facility Workflow 126 Figure 5-6 The Windowed Time Facility Timeline 128 Figure 5-7 Unresponsive Application Triggering 129 Figure 5-8 Samples Taken for Towers of Hanoi N=10..20 137 Figure 5-9 Network/iPhone Manager 139 Figure 5-10 Command Line Shark in Network Profiling Mode 142 Figure 5-11 Sharing Firewall Warning Dialog 143 Figure 5-12 Firewall Sharing Preferences, while adding a new port range for Shark 144 Listing 5-1 Towers of Hanoi Source Code 135 Listing 5-2 Instrumented Towers of Hanoi 135 Advanced Session Management and Data Mining 145 Figure 6-1 Session Inspector: Symbols 147 Figure 6-2 Symbolication Dialog 148 Figure 6-3 Before Symbolication 149 Figure 6-4 After Symbolication 150 Figure 6-5 Example Callstacks 153 Figure 6-6 Heavy View 153 Figure 6-7 Tree View 154 Figure 6-8 Data Mining Advanced Settings 155 Figure 6-9 Contextual Data Mining Menu 157 Figure 6-10 Perf Count Data Mining Palette 158 Figure 6-11 Example Shapes 159 Figure 6-12 Example Shapes, Replicated 160 Figure 6-13 Sampling a Specific Process 161 Figure 6-14 Default Profile View 161 Figure 6-15 Navigation Via the Call-Stack Pane 163 Figure 6-16 Navigation Via the Call-Stack Pane with Tree View 163 Figure 6-17 Source View: SKTGraphicView selectAll 164 Figure 6-18 Source View: NSObject 165 Figure 6-19 Source View: SKTGraphicView selectGraphic 166 Figure 6-20 Source View: SKTGraphicView invalidateGraphic 167 Figure 6-21 Tree view before focusing 168 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 9 Figures, Tables, and ListingsFigure 6-22 Data Mining Contextual Menu 168 Figure 6-23 After Focus Symbol -[SKTGraphicView drawRect:] 169 Figure 6-24 After focus and expansion 170 Figure 6-25 Source View: SKTGraphic drawInView:isSelected: 171 Figure 6-26 Source View: SKGraphic drawHandlesInView: 172 Figure 6-27 Source View: SKGraphic drawHandleAtPoint:inView: 173 Figure 6-28 Heavy View of Focused Sketch 174 Figure 6-29 Expanded Heavy View of Focused Sketch 174 Figure 6-30 After Charge Library libRIP.A.dylib 175 Figure 6-31 After Flatten Library 175 Figure 6-32 Malloc Trace Main Window 177 Figure 6-33 Result of Malloc Sampling 178 Figure 6-34 Chart View 179 Figure 6-35 Place to Select 180 Figure 6-36 Graph View with Call-Stack Pane 182 Custom Configurations 183 Figure 7-1 Main Configuration Menu 183 Figure 7-2 Config Editor 186 Figure 7-3 Simple Timed Samples and Counters Data Source - Sampling Tab 187 Figure 7-4 Simple Timed Samples and Counters Data Source - Counter Settings 188 Figure 7-5 Malloc Data Source - Sampling Settings 189 Figure 7-6 Static Analysis Data Source - Settings 190 Figure 7-7 Java Trace Data Source - Sampling Settings 191 Figure 7-8 Sampler Data Source - Settings 192 Figure 7-9 System Trace Data Source - Settings 193 Figure 7-10 All Thread States Data Source - Settings 194 Figure 7-11 Counter Spreadsheet Analysis 196 Figure 7-12 Choosing a counter-based starting configuration 199 Figure 7-13 Enabling two performance counters 200 Figure 7-14 Performance Spreadsheet: Shortcut Equation 201 Hardware Counter Configuration 202 Figure 8-1 Timed Samples & Counters Data Source - Advanced Sampling Tab 203 Figure 8-2 A typical set of performance counter controls 206 Figure 8-3 Process Marker 208 Figure 8-4 MacOS X Performance Counters Configuration 209 Figure 8-5 Intel Core 2 Configuration Tab 211 Figure 8-6 PowerPC G4+ Configuration Tab (G3 and G4 are similar) 213 Figure 8-7 PowerPC 970 Processor Performance Counters Configuration 215 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 10 Figures, Tables, and ListingsFigure 8-8 PowerPC 970 IMC (IFU) Configuration Tab 217 Figure 8-9 PowerPC 970 IMC (IDU) Configuration Tab 221 Figure 8-10 U1.5/U2 Configuration Tab 223 Figure 8-11 U3 Memory Configuration Tab 225 Figure 8-12 U3 API Configuration Tab 226 Figure 8-13 U4 (Kodiak) Memory Configuration Tab 227 Figure 8-14 U4 (Kodiak) API Configuration Tab 228 Figure 8-15 ARM11 Counter Configuration Tab 229 Miscellaneous Topics 242 Figure B-1 PPC970 Resource Modeling 243 Figure B-2 Timer Sampling in the Kernel 244 Figure B-3 CPU PMI Sampling in the Kernel 245 Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 11 Figures, Tables, and ListingsImportant: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid. Overview Shark is a tool for performance understanding and optimization. Why is it called “Shark?” Performance tuning requires a hunter’s mentality, and no animal is as pure in this quest as a shark. A shark is also an expert in his field — one who uses all potential resources to achieve his goals. The name “Shark” embodies the spirit and emotion you should have when tuning your code. To help you analyze the performance of your code, Shark allows you to profile the entire system (kernel and drivers as well as applications). At the simplest level, Shark profiles the system while your code is running to see where time is being spent. It can also produce profiles of hardware and software performance events such as cache misses, virtual memory activity, memory allocations, function calls, or instruction dependency stalls. This information is an invaluable first step in your performance tuning effort so you can see which parts of your code or the system are the bottlenecks. In addition to showing you where time is being spent, Shark can give you advice on how to improve your code. Shark is capable of identifying many common performance pitfalls and visually presents the costs of these problems to you. Philosophy The first and most important step when optimizing your code is to determine what to optimize. In a program of moderate complexity, there can be thousands of different code paths. Optimizing all of them is normally impractical due to deadlines and limited programmer resources. There are also more subtle tradeoffs between optimized code and portability and maintenance that limit candidates for optimization. Here are a few general guidelines for finding a good candidate for optimization: 1. It should be time-critical. This is generally any operation that is perceptibly slow; the user has to wait for the computer to finish doing something before continuing. Optimizing functionality that is already faster than the user can perceive is usually unnecessary. Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 12 Introduction2. It must be relevant. Optimizing functionality that is rarely used is usually counter-productive. 3. It shows up as a hot spot in a time profile. If there is no obvious hot spot in your code or you are spending a lot of time in system libraries, performance is more likely to improve through high-level improvements (architectural changes). Low-level optimizationstypically focus on a single segment of code and make it a better match to the hardware and software systemsit is being run on. Examples of low-level optimizationsinclude using vector or cache hint instructions. High-level optimizations include algorithmic or other architectural changes to your program. Examples of high-level optimizations include data structure choice (for example, switching from a linked list to a hash-table) or replacing calls to computationally expensive functions with a cache or lookup table. Remember, it is critical to profile before investing your time and effort in optimization. Sadly, many programmers invest prodigious amounts of effort optimizing what their intuition tellsthem isthe performance-criticalsection of code only to realize no performance improvement. Profiling quickly reveals that bottlenecks often lie far from where programmers might assume they are. Using Shark, you can focus your optimization efforts on both algorithmic changes and tuning performance-critical code. Often, even small changesto a critical piece of code can yield large overall performance improvements. By default, Shark creates a profile of execution behavior by periodically interrupting each processor in the system and sampling the currently running process, thread, and instruction address as well as the function callstack. Along with this contextual information, Shark can record the values of hardware and software performance counters. Each counter is capable of counting a wide variety of performance events. In the case of processor and memory controller counters, these include detailed, low-level information that is otherwise impossible to know without a simulator. The overhead for sampling with Shark is extremely low because all sample collection takes place in the kernel and is based on hardware interrupts. A typical sample incurs an overhead on the order of 20µs. This overhead can be significantly larger if callstack recording is enabled and a virtual memory fault is incurred while saving the callstack. Time profiles generated by Shark are statistical in nature; they give a representative view of what wasrunning on the system during a sampling session . Samples can include all of the processes running on the system from both user and supervisor code, or samples can be limited to a specific process or execution state. Shark’s sampling period can be an arbitrary time interval (timer sampling). Shark also has the ability to use a performance event as the sampling trigger (event sampling). Using event sampling, it is possible to associate performance events such as cache misses or instruction stalls with the code that caused them. Additionally, Shark can generate exact profiles for specific function calls or memory allocations. Organization of This Document This manual is organized into four major sections, each consisting of two or three chapters, plus several appendices. Here is a brief “roadmap” to help you orient yourself: Introduction Organization of This Document Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 13● Getting Started with Shark— This introduction and “Getting Started with Shark” (page 16) are designed to give you an overall introduction to Shark. After covering some basic philosophy here, “Getting Started with Shark” (page 16) describes basic ways to use Shark to sample your applications, features of the Session windows that open after you sample your applications, and the use of Shark’s global preferences. ● Profiling Configurations— Three chapters discuss Shark’s default Configurations — its methods of collecting samples from your system or applications — and presentation of the sampled results in Session windows. These chapters are probably the most important ones. “Time Profiling” (page 28) discusses Time Profiling , the most frequently used configuration, which gives a statistical profile of processor utilization. System Tracing , discussed in “System Tracing” (page 63), provides an exact trace of user-kernel transitions, and is useful both to debug interactions between your program and the underlying system and to provide a “microscope” to examine multithreaded programming issues in detail. After the complete chapters devoted to these two configurations, the remainder are covered in “Other Profiling and Tracing Techniques” (page 97). Time Profile (All Thread States) is a variant of Time Profile that also samples blocked threads, and as a result is a good way to get an overview of locking behavior in multithreaded applications. Malloc Trace allows you to examine memory allocation and deallocation activity in detail. Shark can apply Static Analysis to your application in order to quickly examine rarely-traversed code paths. Equivalents for Time Profile , Malloc Trace , and an exact Call Trace , all customized for use with Java applications, are also available. Finally, the chapter gives an overview of Shark’s extensive performance counter recording and analysis capabilities. ● Advanced Techniques—Shark’s basic techniquesforsampling and analysis are sufficient for most purposes, but with complex applications you may need more sophisticated techniques. “Advanced Profiling Control” (page 122) covers waysto start and stop Shark’ssampling very precisely, allowing you to carefully control what issampled, in advance. You can also learn how to control Shark remotely from other machines or even to control Shark running on iOS devices attached to your machine in this chapter. “Advanced Session Management and Data Mining” (page 145) looks at Shark’s symbol management and data mining techniques, which are ways to very precisely select subsets of your samples for examination after they are taken. ● Custom Configurations— Shark is not just limited to its default configurations. If you want to save your own custom settings for a configuration or create a new one from scratch, then you will want to check out chapters “Custom Configurations” (page 183) and “Hardware Counter Configuration” (page 202). The first describes how you may make adjustments to the existing configurations, while the latter covers the many options relating to the use of hardware performance counters. Because there are so many different possible combinations of performance counters, only a limited number of the possibilities are covered by the default configurations. Hence, thisislikely to be the main area where the use of custom configurations will be necessary for typical Shark users. ● Appendices— The first appendix, “Command Reference” (page 230), provides a brief reference to Shark’s menu commands. The second, “Miscellaneous Topics” (page 242), describes several minor, miscellaneous options that do not really fit in anywhere else or are of interest only to a small minority of Shark users. The Introduction Organization of This Document Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 14remainder of the appendices (“Intel Core Performance Counter Event List” (page 246), “Intel Core 2 Performance Counter Event List” (page 252), “PPC 750 (G3) Performance Counter Event List” (page 263), “PPC 7400 (G4) Performance Counter Event List” (page 265), “PPC 7450 (G4+) Performance Counter Event List” (page 271),“PPC 970 (G5) Performance Counter Event List” (page 282),“UniNorth-2 (U1.5/2) Performance Counter Event List” (page 315), “UniNorth-3 (U3) Performance Counter Event List” (page 318), and “Kodiak (U4) Performance Counter Event List” (page 322)) provide a reference for the performance counters that you can measure with Shark. Introduction Organization of This Document Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 15Starting to use Shark is a relatively simple process. You only need to choose one or two items from menus and press a big “Start” button in order to start sampling your applications. This chapter describes these basic steps and a few other general Shark features, such as its preferences. Main Window Figure 1-1 Main Window After launching Shark, you will be presented with Shark’s main window, as illustrated in Figure 1-1. The default sampling configuration istimer-based sampling (Time Profile ) of everything running on the system. By default, the Time Profile configuration uses a 1 ms timer as the trigger for sampling and will record for 30 seconds (30,000 samples per processor). Opening the Sampling Configuration menu (#1) allows you to select from various built-in profiling configurations. Here is a list: ● Time Profile— This configuration, the default, performs timer-based sampling, interrupting your system after a regular interval and taking a sample of what is executing. It is a great starting point, as it allows you to very quickly see what code in your application is actually executing most frequently. Knowing this isthe firststep to successfully optimizing CPU-bound applications. See “Time Profiling” (page 28) for more information. ● System Trace—This configuration records an exact trace of callsinto the Mac OS X kernel by your program, and which threads are running. It is useful for examining your program’s interactions with Mac OS X and for visualizing how your threads are interacting in multithreaded programs. System Trace is discussed in depth in “System Tracing” (page 63). ● Time Profile (All Thread States)— This variation on time profiling also records the state of all blocked, inactive threads. As a result, it’s a great way to see how much and why your threads are blocked. This is quite helpful in the development of multithreaded programs that do a lot of synchronization. This configuration is described in “Time Profile (All Thread States)” (page 97). Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 16 Getting Started with Shark● Malloc Trace— If your program allocates and deallocates a lot of memory, performance can suffer and the odds of accidental memory leaks increase. Shark can help you find and analyze these allocations. “Malloc Trace” (page 101) talks about this more. ● Static Analysis— Shark can provide some basic optimization hints without actually running code. See “Static Analysis” (page 107) for more information. ● Java Profiling— Because Java programs run within the Java Virtual Machine (JVM), normally sampling them with Shark produces little useful information. However, Shark also includes several configurations that simulate the normal Time Profile , Malloc Trace , and even an exact trace of method calls, but while collecting information about what the JVM is executing instead of the native machine. A full description of these options and how to attach Shark to your Java programs is given in “Using Shark with Java Programs” (page 108). ● Hardware Measurements— The L2 cache miss and Processor Bandwidth (x86 systems) or Memory Bandwidth (PowerPC systems) configurations measure memory system activity using counters built into the hardware. They are a great way to see how your program is being slowed because of poor cache memory use. See “Event Counting and Profiling Overview” (page 111) for an overview of Shark’s counter measurement capabilities. These built-in configurations are adequate for sampling most applications. After you have used Shark for awhile, however, you may decide that you would like to sample something in your application that is not covered by the built-in collection of options. In particular, you may want to perform hardware measurements using countersthat are not used by the default hardware measurement configurations. The processfor building your own configurations is described in “Custom Configurations” (page 183). This process is complex enough that you should probably familiarize yourself with Shark before attempting the creation of configurations. By default, Shark samples your entire system, as indicated by the “Everything” item selected for you in the Target pop-up menu (#2). Popping open this menu allows you to select a specific process or file (Figure 1-2). You may also choose different targets using the keyboard: Command-1 for everything, Command-2 for an executing process, and Command-3 for a file. For a Time Profile , it is unnecessary to select a specific target, but others like Malloc Trace and Static Analysis require you to target a specific process or file. If you select the “Process” target, you can also choose to launch a new process. See “Process Attach” (page 122) and “Process Launch” (page 122) for full instructions on the process attaching and launching target selection techniques. Figure 1-2 Process Target Getting Started with Shark Main Window Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 17Mini Configuration Editors Each configuration typically has a few parameters that are frequently modified. Shark allows you to edit these easily using themini configuration editors associated with each configuration. You can enablemini configuration editors by selecting the Config ShowMini Config Editor menu item(Command-Shift-C). Mostmini configuration editors are similar to the one depicted in “Shark Preferences,” but all have small configuration-specific variations. The selection of controls available in each min configuration editor are described in the chapters associated with each type of configuration. Figure 1-3 Mini Configuration Editor Perform Sampling After you choose what you would like to sample (or trace, with some configurations) and how, then actually using Shark to sample your program is extremely simple. There are two main ways to start sampling: 1. Click the Start button (#3 in “Main Window”). 2. Press the current “Hot Key” (Option-Esc , by default). Shark will emit a brief tone and the Shark icon in the dock will turn bright red to let you know that Shark is now actively sampling. At this point, you should exercise your program appropriately to trigger the execution of code that you want to measure. Sometimes this may require no active input on your part, but if you are measuring something like user interface performance then you may need to manually perform several steps while Shark samples. Getting Started with Shark Perform Sampling Retired Document | 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 18 Drawing and Printing Guide for iOSContents About Drawing and Printing in iOS 7 At a Glance 7 Custom UI Views Allow Greater Drawing Flexibility 8 Apps Can Draw Into Offscreen Bitmaps or PDFs 10 Apps Have a Range of Options for Printing Content 10 It’s Easy to Update Your App for High-Resolution Screens 11 See Also 11 iOS Drawing Concepts 12 The UIKit Graphics System 12 The View Drawing Cycle 13 Coordinate Systems and Drawing in iOS 13 Points Versus Pixels 16 Obtaining Graphics Contexts 18 Color and Color Spaces 20 Drawing with Quartz and UIKit 20 Configuring the Graphics Context 21 Creating and Drawing Paths 23 Creating Patterns, Gradients, and Shadings 24 Customizing the Coordinate Space 24 Applying Core Animation Effects 27 About Layers 27 About Animations 28 Accounting for Scale Factors in Core Animation Layers 28 Drawing Shapes Using Bézier Paths 30 Bézier Path Basics 30 Adding Lines and Polygons to Your Path 31 Adding Arcs to Your Path 32 Adding Curves to Your Path 34 Creating Oval and Rectangular Paths 35 Modifying the Path Using Core Graphics Functions 35 Rendering the Contents of a Bézier Path Object 36 Doing Hit-Detection on a Path 38 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Drawing and Creating Images 40 Drawing Images 40 Creating New Images Using Bitmap Graphics Contexts 41 Generating PDF Content 45 Creating and Configuring the PDF Context 45 Drawing PDF Pages 48 Creating Links Within Your PDF Content 50 Printing 52 Printing in iOS is Designed to be Simple and Intuitive 52 The Printing User Interface 52 How Printing Works in iOS 56 The UIKit Printing API 57 Printing Support Overview 58 Printing Workflow 59 Printing Printer-Ready Content 61 Using Print Formatters and Page Renderers 63 Setting the Layout Properties for the Print Job 63 Using a Print Formatter 65 Using a Page Renderer 69 Testing the Printing of App Content 73 Common Printing Tasks 73 Testing for Printing Availability 73 Specifying Print-Job Information 74 Specifying Paper Size, Orientation, and Duplexing Options 75 Integrating Printing Into Your User Interface 76 Responding to Print-Job Completion and Errors 79 Improving Drawing Performance 80 Supporting High-Resolution Screens In Views 82 Checklist for Supporting High-Resolution Screens 82 Drawing Improvements That You Get for Free 82 Updating Your Image Resource Files 83 Loading Images into Your App 83 Using an Image View to Display Multiple Images 84 Updating Your App’s Icons and Launch Images 85 Drawing High-Resolution Content Using OpenGL ES or GLKit 85 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsLoading Images 88 System Support for Images 89 UIKit Image Classes and Functions 89 Other Image-Related Frameworks 90 Supported Image Formats 90 Maintaining Image Quality 91 Document Revision History 92 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures, Tables, and Listings About Drawing and Printing in iOS 7 Figure I-1 You can combine custom views with standard views, and even draw things offscreen. 7 iOS Drawing Concepts 12 Figure 1-1 The relationship between drawing coordinates, view coordinates, and hardware coordinates 14 Figure 1-2 Default coordinate systems in iOS 15 Figure 1-3 A one-point line centered at a whole-numbered point value 17 Figure 1-4 Appearance of one-point-wide lines on standard and retina displays 18 Figure 1-5 Arc rendering in Core Graphics versus UIKit 26 Table 1-1 Core graphics functions for modifying graphics state 21 Drawing Shapes Using Bézier Paths 30 Figure 2-1 Shape drawn with methods of the UIBezierPath class 32 Figure 2-2 An arc in the default coordinate system 33 Figure 2-3 Curve segments in a path 34 Listing 2-1 Creating a pentagon shape 31 Listing 2-2 Creating a new arc path 33 Listing 2-3 Assigning a new CGPathRef to a UIBezierPath object 35 Listing 2-4 Mixing Core Graphics and UIBezierPath calls 36 Listing 2-5 Drawing a path in a view 37 Listing 2-6 Testing points against a path object 38 Drawing and Creating Images 40 Listing 3-1 Drawing a scaled-down image to a bitmap context and obtaining the resulting image 42 Listing 3-2 Drawing to a bitmap context using Core Graphics functions 43 Generating PDF Content 45 Figure 4-1 Creating a link destination and jump point 51 Listing 4-1 Creating a new PDF file 46 Listing 4-2 Drawing page-based content 48 Printing 52 Figure 5-1 System item action button—used for printing 53 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5Figure 5-2 Printer-options popover view (iPad) 53 Figure 5-3 Printer-options sheet (iPhone) 54 Figure 5-4 Print Center 55 Figure 5-5 Print Center: detail of print job 56 Figure 5-6 Printing architecture 57 Figure 5-7 Relationships of UIKit printing objects 57 Figure 5-8 The layout of a multi-page print job 65 Table 5-1 Deciding how to print app content 58 Listing 5-1 Printing a single PDF document with capability for page-range selection 62 Listing 5-2 Printing an HTML document (without header information) 66 Listing 5-3 Printing the contents of a web view 68 Listing 5-4 Drawing the header and footer of a page 71 Listing 5-5 Enabling or disabling a print button based on availability of printing 74 Listing 5-6 Setting properties of a UIPrintInfo object and assigning it to the printInfo property 74 Listing 5-7 Setting the printing orientation to match image dimension 75 Listing 5-8 Implementing the printInteractionController:choosePaper: method 76 Listing 5-9 Presenting printing options based upon current device type 77 Listing 5-10 Implementing a completion-handler block 79 Improving Drawing Performance 80 Table A-1 Tips for improving drawing performance 80 Supporting High-Resolution Screens In Views 82 Listing B-1 Initializing a render buffer’s storage and retrieving its actual dimensions 85 Loading Images 88 Table C-1 Usage scenarios for images 88 Table C-2 Supported image formats 90 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6 Figures, Tables, and ListingsThis document covers three related subjects: ● Drawing custom UI views. Custom UI views allow you to draw content that cannot easily be drawn with standard UI elements. For example, a drawing program might use a custom view for the user’s drawing, or an arcade game might use a custom view into which it draws sprites. ● Drawing into offscreen bitmap and PDF content. Whether you plan to display the images later, export them to a file, or print the images to an AirPrint-enabled printer, offscreen drawing lets you do so without interrupting the user’s workflow. ● Adding AirPrint support to your app. The iOS printing system lets you draw your content differently to fit on the page. Figure I-1 You can combine custom views with standard views, and even draw things offscreen. At a Glance The iOS native graphics system combines three major technologies: UIKit, Core Graphics, and Core Animation. UIKit provides views and some high-level drawing functionality within those views, Core Graphics provides additional (lower-level) drawing support within UIKit views, and Core Animation provides the ability to apply transformations and animation to UIKit views. Core Animation is also responsible for view compositing. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7 About Drawing and Printing in iOSCustom UI Views Allow Greater Drawing Flexibility This document describes how to draw into custom UI views using native drawing technologies. These technologies, which include the Core Graphics and UIKit frameworks, support 2D drawing. Before you consider using a custom UI view, you should make certain that you really need to do so. Native drawing is suitable for handling more complex 2D layout needs. However, because custom views are processor-intensive, you should limit the amount of drawing you do using native drawing technologies. As an alternative to custom drawing, an iOS app can draw things onscreen in several other ways. ● Using standard (built-in) views. Standard viewslet you draw common user-interface primitives, including lists, collections, alerts, images, progress bars, tables, and so on without the need to explicitly draw anything yourself. Using built-in views not only ensures a consistent user experience between iOS apps, but also saves you programming effort. If built-in views meet your needs, you should read ViewProgramming Guide for iOS . ● Using Core Animation layers. Core Animation lets you create complex, layered 2D views with animation and transformations. Core Animation is a good choice for animating standard views, or for combining views in complex ways to present the illusion of depth, and can be combined with custom-drawn views as described in this document. To learn more about Core Animation, read Core Animation Overview. ● Using OpenGL ES in a GLKit view or a custom view. The OpenGL ES framework provides a set of open-standard graphics libraries geared primarily toward game development or apps that require high frame rates, such as virtual prototyping apps and mechanical and architectural design apps. It conforms to the OpenGL ES 2.0 and OpenGL ES v1.1 specifications. To learn more about OpenGL drawing, read OpenGL ES Programming Guide for iOS . ● Using web content. The UIWebView class lets you display web-based user interfaces in an iOS app. To learn more about displaying web content in a web view, read Using UIWebView to display select document types and UIWebView Class Reference . Depending on the type of app you are creating, it may be possible to use little or no custom drawing code. Although immersive apps typically make extensive use of custom drawing code, utility and productivity apps can often use standard views and controls to display their content. The use of custom drawing code should be limited to situations where the content you display needsto change dynamically. For example, a drawing app typically needsto use custom drawing code to track the user’s drawing commands, and an arcade-style game may need to update the screen constantly to reflect the changing game environment. In those situations, you should choose an appropriate drawing technology and create a custom view class to handle events and update the display appropriately. About Drawing and Printing in iOS At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8On the other hand, if the bulk of your app’s interface is fixed, you can render the interface in advance to one or more image files and display those images at runtime using the UIImageView class. You can layer image views with other content as needed to build your interface. You can also use the UILabel class to display configurable text and include buttons or other controls to provide interactivity. For example, an electronic version of a board game can often be created with little or no custom drawing code. Because custom views are generally more processor-intensive (with less help from the GPU), if you can do what you need to do using standard views, you should always do so. Also, you should make your custom views as small as possible, containing only content that you cannot draw in any other way, use use standard views for everything else. If you need to combine standard UI elements with custom drawing, consider using a Core Animation layer to superimpose a custom view with a standard view so that you draw as little as possible. A Few Key Concepts Underpin Drawing With the Native Technologies When you draw content with UIKit and Core Graphics, you should be familiar with a few concepts in addition to the view drawing cycle. ● For the drawRect: method, UIKit creates a graphics context for rendering to the display. This graphics context contains the information the drawing system needs to perform drawing commands, including attributes such as fill and stroke color, the font, the clipping area, and line width. You can also create and draw into custom graphics context for bitmap images and PDF content. ● UIKit has a default coordinate system where the origin of drawing is at the top-left of a view; positive values extend downward and to the right of that origin. You can change the size, orientation, and position of the default coordinate system relative to the underlying view or window by modifying the current transformation matrix, which maps a view’s coordinate space to the device screen. ● In iOS, the logical coordinate space, which measures distances in points, is not equal to the device coordinate space, which measures in pixels. For greater precision, points are expressed in floating-point values. Relevant Chapter: “iOS Drawing Concepts” (page 12) UIKit, Core Graphics, and Core Animation Give Your App Many Tools For Drawing The UIKit and Core Graphics have many complementary graphics capabilitiesthat encompass graphics contexts, Bézier paths, images, bitmaps, transparency layers, colors, fonts, PDF content, and drawing rectangles and clipping areas. In addition, Core Graphics has functions related to line attributes, color spaces, pattern colors, gradients, shadings, and image masks. The Core Animation framework enables you to create fluid animations by manipulating and displaying content created with other technologies. About Drawing and Printing in iOS At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9Relevant Chapters: “iOS Drawing Concepts” (page 12), “Drawing Shapes Using Bézier Paths” (page 30), “Drawing and Creating Images” (page 40), “Generating PDF Content” (page 45) Apps Can Draw Into Offscreen Bitmaps or PDFs It is often useful for an app to draw content offscreen: ● Offscreen bitmap contexts are often used when scaling down photographs for upload, rendering content into an image file for storage purposes, or using Core Graphics to generate complex images for display. ● Offscreen PDF contexts are often used when drawing user-generated content for printing purposes. After you create an offscreen context, you can draw into it just as you would draw within the drawRect: method of a custom view. Relevant Chapters: “Drawing and Creating Images” (page 40), “Generating PDF Content” (page 45) Apps Have a Range of Options for Printing Content As of iOS 4.2, apps can print content wirelessly to supported printers using AirPrint. When assembling a print job, they have three ways to give UIKit the content to print: ● They can give the framework one or more objects that are directly printable; such objects require minimal app involvement. These are instances of the NSData, NSURL, UIImage, or ALAsset classes containing or referencing image data or PDF content. ● They can assign a print formatter to the print job. A print formatter is an object that can lay out content of a certain type (such as plain text or HTML) over multiple pages. ● They can assign a page renderer to the print job. A page renderer is usually an instance of a custom subclass of UIPrintPageRenderer that draws the content to be printed in part or in full. A page renderer can use one or more print formatters to help it draw and format its printable content. About Drawing and Printing in iOS At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10Relevant Chapter: “Printing” (page 52) It’s Easy to Update Your App for High-Resolution Screens Some iOS devices feature high-resolution screens, so your app must be prepared to run on these devices and on devices with lower-resolution screens. iOS handles much of the work required to handle the different resolutions, but your app must do the rest. Your tasksinclude providing specially named high-resolution images and modifying your layer- and image-related code to take the current scale factor into account. Relevant Appendix: “Supporting High-Resolution Screens In Views” (page 82) See Also For complete examples of printing, see the PrintPhoto , Recipes and Printing , and PrintWebView sample code projects. About Drawing and Printing in iOS See Also 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11High-quality graphics are an important part of your app’s user interface. Providing high-quality graphics not only makes your app look good, but it also makes your app look like a natural extension to the rest of the system. iOS provides two primary paths for creating high-quality graphics in your system: OpenGL or native rendering using Quartz, Core Animation, and UIKit. This document describes native rendering. (To learn about OpenGL drawing, see OpenGL ES Programming Guide for iOS .) Quartz isthe main drawing interface, providing support for path-based drawing, anti-aliased rendering, gradient fill patterns, images, colors, coordinate-space transformations, and PDF document creation, display, and parsing. UIKit provides Objective-C wrappers for line art, Quartz images, and color manipulations. Core Animation provides the underlying support for animating changes in many UIKit view properties and can also be used to implement custom animations. This chapter provides an overview of the drawing process for iOS apps, along with specific drawing techniques for each of the supported drawing technologies. You will also find tips and guidance on how to optimize your drawing code for the iOS platform. Important: Not all UIKit classes are thread safe. Be sure to check the documentation before performing drawing-related operations on threads other than your app’s main thread. The UIKit Graphics System In iOS, all drawing to the screen—regardless of whether it involves OpenGL, Quartz, UIKit, or Core Animation—occurs within the confines of an instance of the UIView class or a subclass thereof. Views define the portion of the screen in which drawing occurs. If you use system-provided views, this drawing is handled for you automatically. If you define custom views, however, you must provide the drawing code yourself. If you use Quartz, Core Animation, and UIKit to draw, you use the drawing concepts described in the following sections. In addition to drawing directly to the screen, UIKit also allows you to draw into offscreen bitmap and PDF graphics contexts. When you draw in an offscreen context, you are not drawing in a view, which means that concepts such as the view drawing cycle do not apply (unless you then obtain that image and draw it in an image view or similar). 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12 iOS Drawing ConceptsThe View Drawing Cycle The basic drawing model forsubclasses of the UIView classinvolves updating content on demand. The UIView class makes the update process easier and more efficient; however, by gathering the update requests you make and delivering them to your drawing code at the most appropriate time. When a view is first shown or when a portion of the view needs to be redrawn, iOS asks the view to draw its content by calling the view’s drawRect: method. There are several actions that can trigger a view update: ● Moving or removing another view that was partially obscuring your view ● Making a previously hidden view visible again by setting its hidden property to NO ● Scrolling a view off of the screen and then back onto the screen ● Explicitly calling the setNeedsDisplay or setNeedsDisplayInRect: method of your view System views are redrawn automatically. For custom views, you must override the drawRect: method and perform all your drawing inside it. Inside your drawRect: method, use the native drawing technologies to draw shapes, text, images, gradients, or any other visual content you want. The first time your view becomes visible, iOS passes a rectangle to the view’s drawRect: method that contains your view’s entire visible area. During subsequent calls, the rectangle includes only the portion of the view that actually needsto be redrawn. For maximum performance, you should redraw only affected content. After calling your drawRect: method, the view marks itself as updated and waits for new actions to arrive and trigger another update cycle. If your view displays static content, then all you need to do is respond to changes in your view’s visibility caused by scrolling and the presence of other views. If you want to change the contents of the view, however, you must tell your view to redraw its contents. To do this, call the setNeedsDisplay or setNeedsDisplayInRect: method to trigger an update. For example, if you were updating content several times a second, you might want to set up a timer to update your view. You might also update your view in response to user interactions or the creation of new content in your view. Important: Do not call your view’s drawRect: method yourself. That method should be called only by code built into iOS during a screen repaint. At other times, no graphics context exists, so drawing is not possible. (Graphics contexts are explained in the next section.) Coordinate Systems and Drawing in iOS When an app draws something in iOS, it has to locate the drawn content in a two-dimensional space defined by a coordinate system. This notion mightseem straightforward at first glance, but it isn’t. Appsin iOS sometimes have to deal with different coordinate systems when drawing. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13In iOS, all drawing occurs in a graphics context. Conceptually, a graphics context is an object that describes where and how drawing should occur, including basic drawing attributes such as the colors to use when drawing, the clipping area, line width and style information, font information, compositing options, and so on. In addition, as shown in Figure 1-1 (page 14), each graphics context has a coordinate system. More precisely, each graphics context has three coordinate systems: ● The drawing (user) coordinate system. This coordinate system is used when you issue drawing commands. ● The view coordinate system (base space). This coordinate system is a fixed coordinate system relative to the view. ● The (physical) device coordinate system. This coordinate system represents pixels on the physical screen. Figure 1-1 The relationship between drawing coordinates, view coordinates, and hardware coordinates The drawing frameworks of iOS create graphics contexts for drawing to specific destinations—the screen, bitmaps, PDF content, and so on—and these graphics contexts establish the initial drawing coordinate system for that destination. This initial drawing coordinate system is known as the default coordinate system, and is a 1:1 mapping onto the view’s underlying coordinate system. Each view also has a current transformation matrix (CTM), a mathematical matrix that maps the points in the current drawing coordinate system to the (fixed) view coordinate system. The app can modify this matrix (as described later) to change the behavior of future drawing operations. Each of the drawing frameworks of iOS establishes a default coordinate system based on the current graphics context. In iOS, there are two main types of coordinate systems: iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14● An upper-left-origin coordinate system (ULO), in which the origin of drawing operationsis at the upper-left corner of the drawing area, with positive values extending downward and to the right. The default coordinate system used by the UIKit and Core Animation frameworks is ULO-based. ● A lower-left-origin coordinate system (LLO), in which the origin of drawing operations is at the lower-left corner of the drawing area, with positive values extending upward and to the right. The default coordinate system used by Core Graphics framework is LLO-based. These coordinate systems are shown in Figure 1-2. Figure 1-2 Default coordinate systems in iOS UIKit Core Graphics (0.0, 0.0) (0.0, 0.0) Note: The default coordinate system in OS X is LLO-based. Although the drawing functions and methods of the Core Graphics and AppKit frameworks are perfectly suited to this default coordinate system, AppKit provides programmatic support for flipping the drawing coordinate system to have an upper-left origin. Before calling your view’s drawRect: method, UIKit establishes the default coordinate system for drawing to the screen by making a graphics context available for drawing operations. Within a view’s drawRect: method, an app can set graphics-state parameters (such as fill color) and draw to the current graphics context without needing to refer to the graphics context explicitly. This implicit graphics context establishes a ULO default coordinate system. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15Points Versus Pixels In iOS there is a distinction between the coordinates you specify in your drawing code and the pixels of the underlying device. When using native drawing technologies such as Quartz, UIKit, and Core Animation, the drawing coordinate space and the view’s coordinate space are both logical coordinate spaces, with distances measured in points. These logical coordinate systems are decoupled from the device coordinate space used by the system frameworks to manage the pixels onscreen. The system automatically maps points in the view’s coordinate space to pixels in the device coordinate space, but this mapping is not always one-to-one. This behavior leads to an important fact that you should always remember: One point does not necessarily correspond to one physical pixel. The purpose of using points (and the logical coordinate system) is to provide a consistent size of output that is device independent. For most purposes, the actualsize of a point isirrelevant. The goal of pointsisto provide a relatively consistentscale that you can use in your code to specify the size and position of views and rendered content. How points are actually mapped to pixels is a detail that is handled by the system frameworks. For example, on a device with a high-resolution screen, a line that is one point wide may actually result in a line that is two physical pixels wide. The result is that if you draw the same content on two similar devices, with only one of them having a high-resolution screen, the content appears to be about the same size on both devices. In iOS, the UIScreen, UIView, UIImage, and CALayer classes provide properties to obtain (and, in some cases, set) a scale factor that describes the relationship between points and pixels for that particular object. For example, every UIKit view has a contentScaleFactor property. On a standard-resolution screen, the scale factor is typically 1.0. On a high-resolution screen, the scale factor is typically 2.0. In the future, other scale factors may also be possible. (In iOS prior to version 4, you should assume a scale factor of 1.0.) Native drawing technologies, such as Core Graphics, take the current scale factor into account for you. For example, if one of your views implements a drawRect: method, UIKit automatically sets the scale factor for that view to the screen’sscale factor. In addition, UIKit automatically modifiesthe current transformation matrix of any graphics contexts used during drawing to take into account the view’s scale factor. Thus, any content you draw in your drawRect: method is scaled appropriately for the underlying device’s screen. Because of this automatic mapping, when writing drawing code, pixels usually don’t matter. However, there are times when you might need to change your app’s drawing behavior depending on how points are mapped to pixels—to download higher-resolution images on devices with high-resolution screens or to avoid scaling artifacts when drawing on a low-resolution screen, for example. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16In iOS, when you draw things onscreen, the graphics subsystem uses a technique called antialiasing to approximate a higher-resolution image on a lower-resolution screen. The best way to explain this technique is by example. When you draw a black vertical line on a solid white background, if that line falls exactly on a pixel, it appears as a series of black pixels in a field of white. If it appears exactly between two pixels, however, it appears as two grey pixels side-by-side, as shown in Figure 1-3. Figure 1-3 A one-point line centered at a whole-numbered point value Positions defined by whole-numbered points fall at the midpoint between pixels. For example, if you draw a one-pixel-wide vertical line from (1.0, 1.0) to (10.0, 10.0), you get a fuzzy grey line. If you draw a two-pixel-wide line, you get a solid black line because it fully covers two pixels (one on either side of the specified point). As a rule, lines that are an odd number of physical pixels wide appear softer than lines with widths measured in even numbers of physical pixels unless you adjust their position to make them cover pixels fully. Where the scale factor comes into play is when determining how many pixels are covered by a one-point-wide line. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17On a low-resolution display (with a scale factor of 1.0), a one-point-wide line is one pixel wide. To avoid antialiasing when you draw a one-point-wide horizontal or vertical line, if the line is an odd number of pixels in width, you must offset the position by 0.5 points to either side of a whole-numbered position. If the line is an even number of points in width, to avoid a fuzzy line, you must not do so. Figure 1-4 Appearance of one-point-wide lines on standard and retina displays On a high-resolution display (with a scale factor of 2.0), a line that is one point wide is not antialiased at all because it occupies two full pixels (from -0.5 to +0.5). To draw a line that covers only a single physical pixel, you would need to make it 0.5 points in thickness and offset its position by 0.25 points. A comparison between the two types of screens is shown in Figure 1-4. Of course, changing drawing characteristics based on scale factor may have unexpected consequences. A 1-pixel-wide line might look nice on some devices but on a high-resolution device might be so thin that it is difficult to see clearly. It is up to you to determine whether to make such a change. Obtaining Graphics Contexts Most of the time, graphics contexts are configured for you. Each view object automatically creates a graphics contextso that your code can start drawing immediately assoon as your custom drawRect: method is called. As part of this configuration, the underlying UIView class creates a graphics context (a CGContextRef opaque type) for the current drawing environment. If you want to draw somewhere other than your view (for example, to capture a series of drawing operations in a PDF or bitmap file), or if you need to call Core Graphics functions that require a context object, you must take additional steps to obtain a graphics context object. The sections below explain how. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18For more information about graphics contexts, modifying the graphics state information, and using graphics contextsto create customcontent,seeQuartz 2DProgrammingGuide . For a list of functions used in conjunction with graphics contexts, see CGContext Reference , CGBitmapContext Reference , and CGPDFContext Reference . Drawing to the Screen If you use Core Graphics functions to draw to a view, either in the drawRect: method or elsewhere, you’ll need a graphics context for drawing. (The first parameter of many of these functions must be a CGContextRef object.) You can call the function UIGraphicsGetCurrentContext to get an explicit version of the same graphics context that’s made implicit in drawRect:. Because it’s the same graphics context, the drawing functions should also make reference to a ULO default coordinate system. If you want to use Core Graphics functions to draw in a UIKit view, you should use the ULO coordinate system of UIKit for drawing operations. Alternatively, you can apply a flip transform to the CTM and then draw an object in the UIKit view using Core Graphics native LLO coordinate system. “Flipping the Default Coordinate System” (page 25) discusses flip transforms in detail. The UIGraphicsGetCurrentContext function always returns the graphics context currently in effect. For example, if you create a PDF context and then call UIGraphicsGetCurrentContext, you’d receive that PDF context. You must use the graphics context returned by UIGraphicsGetCurrentContext if you use Core Graphics functions to draw to a view. Note: The UIPrintPageRenderer class declares several methods for drawing printable content. In a manner similar to drawRect:, UIKit installs an implicit graphics context for implementations of these methods. This graphics context establishes a ULO default coordinate system. Drawing to Bitmap Contexts and PDF Contexts UIKit provides functions for rendering images in a bitmap graphics context and for generating PDF content by drawing in a PDF graphics context. Both of these approachesrequire that you first call a function that creates a graphics context—a bitmap context or a PDF context, respectively. The returned object serves as the current (and implicit) graphics context for subsequent drawing and state-setting calls. When you finish drawing in the context, you call another function to close the context. Both the bitmap context and the PDF context provided by UIKit establish a ULO default coordinate system. Core Graphics has corresponding functions for rendering in a bitmap graphics context and for drawing in a PDF graphics context. The context that an app directly creates through Core Graphics, however, establishes a LLO default coordinate system. iOS Drawing Concepts The UIKit Graphics System 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19Note: In iOS, it is recommended that you use the UIKit functions for drawing to bitmap contexts and PDF contexts. However, if you do use the Core Graphics alternatives and intend to display the rendered results, you will have to adjust your code to compensate for the difference in default coordinate systems. See “Flipping the Default Coordinate System” (page 25) for more information. For details, see “Drawing and Creating Images” (page 40) (for drawing to bitmap contexts) and “Generating PDF Content” (page 45) (for drawing to PDF contexts). Color and Color Spaces iOS supports the full range of color spaces available in Quartz; however, most apps should need only the RGB color space. Because iOS is designed to run on embedded hardware and display graphics onscreen, the RGB color space is the most appropriate one to use. The UIColor object provides convenience methods for specifying color values using RGB, HSB, and grayscale values. When creating colors in this way, you never need to specify the color space. It is determined for you automatically by the UIColor object. You can also use the CGContextSetRGBStrokeColor and CGContextSetRGBFillColor functions in the Core Graphics framework to create and set colors. Although the Core Graphics framework includes support for creating colors using other color spaces, and for creating custom color spaces, using those colors in your drawing code is not recommended. Your drawing code should always use RGB colors. Drawing with Quartz and UIKit Quartz is the general name for the native drawing technology in iOS. The Core Graphics framework is at the heart of Quartz, and is the primary interface you use for drawing content. This framework provides data types and functions for manipulating the following: ● Graphics contexts ● Paths ● Images and bitmaps ● Transparency layers ● Colors, pattern colors, and color spaces ● Gradients and shadings ● Fonts ● PDF content iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20UIKit builds on the basic features of Quartz by providing a focused set of classesfor graphics-related operations. The UIKit graphics classes are not intended as a comprehensive set of drawing tools—Core Graphics already providesthat. Instead, they provide drawing support for other UIKit classes. UIKitsupport includesthe following classes and functions: ● UIImage, which implements an immutable class for displaying images ● UIColor, which provides basic support for device colors ● UIFont, which provides font information for classes that need it ● UIScreen, which provides basic information about the screen ● UIBezierPath, which enables your app to draw lines, arcs, ovals, and other shapes. ● Functions for generating a JPEG or PNG representation of a UIImage object ● Functions for drawing to a bitmap graphics context ● Functions for generating PDF data by drawing to a PDF graphics context ● Functions for drawing rectangles and clipping the drawing area ● Functions for changing and getting the current graphics context For information about the classes and methods that comprise UIKit, see UIKit Framework Reference . For more information about the opaque types and functions that comprise the Core Graphics framework, see Core Graphics Framework Reference . Configuring the Graphics Context Before calling your drawRect: method, the view object creates a graphics context and sets it as the current context. This context exists only for the lifetime of the drawRect: call. You can retrieve a pointer to this graphics context by calling the UIGraphicsGetCurrentContext function. This function returns a reference to a CGContextRef type, which you pass to Core Graphics functions to modify the current graphics state. Table 1-1 lists the main functions you use to set different aspects of the graphics state. For a complete list of functions, see CGContext Reference . This table also lists UIKit alternatives where they exist. Table 1-1 Core graphics functions for modifying graphics state Graphics state Core Graphics functions UIKit alternatives CGContextRotateCTM None CGContextScaleCTM CGContextTranslateCTM CGContextConcatCTM Current transformation matrix (CTM) iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21Graphics state Core Graphics functions UIKit alternatives Clipping area CGContextClipToRect UIRectClip function CGContextSetLineWidth None CGContextSetLineJoin CGContextSetLineCap CGContextSetLineDash CGContextSetMiterLimit Line: Width, join, cap, dash, miter limit Accuracy of curve estimation CGContextSetFlatness None Anti-aliasing setting CGContextSetAllowsAntialiasing None CGContextSetRGBFillColor UIColor class CGContextSetRGBStrokeColor Color: Fill and stroke settings Alpha global value CGContextSetAlpha None (transparency) Rendering intent CGContextSetRenderingIntent None CGContextSetFillColorSpace UIColor class CGContextSetStrokeColorSpace Color space: Fill and stroke settings CGContextSetFont UIFont class CGContextSetFontSize CGContextSetCharacterSpacing Text: Font, font size, character spacing, text drawing mode The UIImage class and various drawing functions let you specify which blend mode to use. Blend mode CGContextSetBlendMode The graphics context contains a stack of saved graphics states. When Quartz creates a graphics context, the stack is empty. Using the CGContextSaveGState function pushes a copy of the current graphics state onto the stack. Thereafter, modifications you make to the graphics state affect subsequent drawing operations but do not affect the copy stored on the stack. When you are done making modifications, you can return to the previous graphics state by popping the saved state off the top of the stack using the iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22CGContextRestoreGState function. Pushing and popping graphics states in this manner is a fast way to return to a previous state and eliminates the need to undo each state change individually. It is also the only way to restore some aspects of the state, such as the clipping path, back to their original settings. For general information about graphics contexts and using them to configure the drawing environment, see “Graphics Contexts” in Quartz 2D Programming Guide . Creating and Drawing Paths A path is a vector-based shapes created from a sequence of lines and Bézier curves. UIKit includes the UIRectFrame and UIRectFill functions(among others) for drawing simple pathssuch asrectanglesin your views. Core Graphics also includes convenience functions for creating simple paths such as rectangles and ellipses. For more complex paths, you must create the path yourself using the UIBezierPath class of UIKit, or using the functions that operate on the CGPathRef opaque type in the Core Graphics framework. Although you can construct a path without a graphics context using either API, the pointsin the path still must refer to the current coordinate system (which either has a ULO or LLO orientation), and you still need a graphics context to actually render the path. When drawing a path, you must have a current context set. This context can be a custom view’s context (in drawRect:), a bitmap context, or a PDF context. The coordinate system determines how the path is rendered. UIBezierPath assumes a ULO coordinate system. Thus, if your view is flipped (to use LLO coordinates), the resulting shape may render differently than intended. For best results, you should alwaysspecify pointsrelative to the origin of the current coordinate system of the graphics context used for rendering. Note: Arcs are an aspect of paths that require additional work even if this “rule” is followed. If you create a path using Core Graphic functions that locate points in a ULO coordinate system, and then render the path in a UIKit view, the direction an arc “points” is different. See “Side Effects of Drawing with Different Coordinate Systems” (page 25) for more on this subject. For creating paths in iOS, it is recommended that you use UIBezierPath instead of CGPath functions unless you need some of the capabilities that only Core Graphics provides, such as adding ellipses to paths. For more on creating and rendering paths in UIKit, see “Drawing Shapes Using Bézier Paths” (page 30). For information on using UIBezierPath to draw paths, see “Drawing Shapes Using Bézier Paths” (page 30). For information on how to draw paths using Core Graphics, including information about how you specify the pointsfor complex path elements,see “Paths”inQuartz 2DProgramming Guide . Forinformation on the functions you use to create paths, see CGContext Reference and CGPath Reference . iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23Creating Patterns, Gradients, and Shadings The Core Graphics framework includes additional functions for creating patterns, gradients, and shadings. You use these typesto create non monochrome colors and use them to fill the paths you create. Patterns are created from repeating images or content. Gradients and shadings provide different ways to create smooth transitions from color to color. The details for creating and using patterns, gradients, and shadings are all covered in Quartz 2D Programming Guide . Customizing the Coordinate Space By default, UIKit creates a straightforward current transformation matrix that maps points onto pixels. Although you can do all of your drawing without modifying that matrix, sometimes it can be convenient to do so. When your view’s drawRect: method is first called, the CTM is configured so that the origin of the coordinate system matches the your view’s origin, its positive X axis extends to the right, and its positive Y axis extends down. However, you can change the CTM by adding scaling, rotation, and translation factors to it and thereby change the size, orientation, and position of the default coordinate system relative to the underlying view or window. Using Coordinate Transforms to Improve Drawing Performance Modifying the CTM is a standard technique for drawing content in a view because it allows you to reuse paths, which potentially reduces the amount of computation required while drawing. For example, if you want to draw a square starting at the point (20, 20), you could create a path that moves to (20, 20) and then draws the needed set of lines to complete the square. However, if you later decide to move that square to the point (10, 10), you would have to recreate the path with the new starting point. Because creating paths is a relatively expensive operation, it is preferable to create a square whose origin is at (0, 0) and to modify the CTM so that the square is drawn at the desired origin. In the Core Graphics framework, there are two ways to modify the CTM. You can modify the CTM directly using the CTM manipulation functions defined in CGContext Reference . You can also create a CGAffineTransform structure, apply any transformations you want, and then concatenate that transform onto the CTM. Using an affine transform lets you group transformations and then apply them to the CTM all at once. You can also evaluate and invert affine transforms and use them to modify point, size, and rectangle values in your code. For more information on using affine transforms, see Quartz 2D Programming Guide and CGAffineTransform Reference . iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Flipping the Default Coordinate System Flipping in UIKit drawing modifiesthe backing CALayer to align a drawing environment having a LLOcoordinate system with the default coordinate system of UIKit. If you only use UIKit methods and function for drawing, you shouldn’t need to flip the CTM. However, if you mix Core Graphics or Image I/O function calls with UIKit calls, flipping the CTM might be necessary. Specifically, if you draw an image or PDF document by calling Core Graphics functions directly, the object is rendered upside-down in the view’s context. You must flip the CTM to display the image and pages correctly. To flip a object drawn to a Core Graphics context so that it appears correctly when displayed in a UIKit view, you must modify the CTM in two steps. You translate the origin to the upper-left corner of the drawing area, and then you apply a scale translation, modifying the y-coordinate by -1. The code for doing this looks similar to the following: CGContextSaveGState(graphicsContext); CGContextTranslateCTM(graphicsContext, 0.0, imageHeight); CGContextScaleCTM(graphicsContext, 1.0, -1.0); CGContextDrawImage(graphicsContext, image, CGRectMake(0, 0, imageWidth, imageHeight)); CGContextRestoreGState(graphicsContext); If you create a UIImage object initialized with a Core Graphics image object, UIKit performs the flip transform for you. Every UIImage object is backed by a CGImageRef opaque type. You can access the Core Graphics object through the CGImage property and do some work with the image. (Core Graphics has image-related facilities not available in UIKit.) When you are finished, you can recreate the UIImage object from the modified CGImageRef object. Note: You can use the Core Graphics function CGContextDrawImage to draw an image to any rendering destination. This function has two parameters, the first for a graphics context and the second for a rectangle that defines both the size of the image and its location in a drawing surface such as a view. When drawing an image with CGContextDrawImage, if you don’t adjust the current coordinate system to a LLO orientation, the image appears inverted in a UIKit view. Additionally, the origin of the rectangle passed into this function is relative to the origin of the coordinate system that is current when the function is called. Side Effects of Drawing with Different Coordinate Systems Some rendering oddities are brought to light when you draw an object with with reference to the default coordinate system of one drawing technology and then render it in a graphics context of the other. You may want to adjust your code to account for these side effects. iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25Arcs and Rotations If you draw an path with functionssuch as CGContextAddArc and CGPathAddArc and assume a LLOcoordinate system, then you need to flip the CTM to render the arc correctly in a UIKit view. However, if you use the same function to create an arc with points located in a ULO coordinate system and then render the path in a UIKit view, you’ll notice that the arc is an altered version of its original. The terminating endpoint of the arc now pointsin the opposite direction of what that endpoint would do were the arc created using the UIBezierPath class. For example, a downward-pointing arrow now points upward (as shown in Figure 1-5), and the direction in which the arc “bends” is also different. You must change the direction of Core Graphics-drawn arcsto account for the ULO-based coordinate system; this direction is controlled by the startAngle and endAngle parameters of those functions. Figure 1-5 Arc rendering in Core Graphics versus UIKit Arc specified in Core Graphics Arc rendered in UIKit y y x (0,0) (0,0) x You can observe the same kind of mirroring effect if you rotate an object (for example, by calling CGContextRotateCTM). If you rotate an object using Core Graphics calls that make reference to a ULO coordinate system, the direction of the object when rendered in UIKit is reversed. You must account for the different directions of rotation in your code; with CGContextRotateCTM, you do this by inverting the sign of the angle parameter (so, for example, a negative value becomes a positive value). Shadows The direction a shadow falls from its object is specified by an offset value, and the meaning of that offset is a convention of a drawing framework. In UIKit, positive x and y offsets make a shadow go down and to the right of an object. In Core Graphics, positive x and y offsets make a shadow go up and to the right of an object. Flipping the CTM to align an object with the default coordinate system of UIKit does not affect the object’s shadow, and so a shadow does not correctly track its object. To get it to track correctly, you must modify the offset values appropriately for the current coordinate system. iOS Drawing Concepts Drawing with Quartz and UIKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26Note: Prior to iOS 3.2, Core Graphics and UIKit shared the same convention for shadow direction: positive offset values make the shadow go down and to the right of an object. Applying Core Animation Effects Core Animation is an Objective-C framework that provides infrastructure for creating fluid, real-time animations quickly and easily. Core Animation is not a drawing technology itself, in the sense that it does not provide primitive routines for creating shapes, images, or other types of content. Instead, it is a technology for manipulating and displaying content that you created using other technologies. Most apps can benefit from using Core Animation in some form in iOS. Animations provide feedback to the user about what is happening. For example, when the user navigates through the Settings app, screens slide in and out of view based on whether the user is navigating further down the preferences hierarchy or back up to the root node. This kind of feedback is important and provides contextual information for the user. It also enhances the visual style of an app. In most cases, you may be able to reap the benefits of Core Animation with very little effort. For example, several properties of the UIView class (including the view’s frame, center, color, and opacity—among others) can be configured to trigger animations when their values change. You have to do some work to let UIKit know that you want these animations performed, but the animations themselves are created and run automatically for you. For information about how to trigger the built-in view animations, see “Animating Views” in UIView Class Reference . When you go beyond the basic animations, you must interact more directly with Core Animation classes and methods. The following sections provide information about Core Animation and show you how to work with its classes and methods to create typical animations in iOS. For additional information about Core Animation and how to use it, see Core Animation Programming Guide . About Layers The key technology in Core Animation is the layer object. Layers are lightweight objects that are similar in nature to views, but that are actually model objects that encapsulate geometry, timing, and visual properties for the content you want to display. The content itself is provided in one of three ways: ● You can assign a CGImageRef to the contents property of the layer object. ● You can assign a delegate to the layer and let the delegate handle the drawing. ● You can subclass CALayer and override one of the display methods. iOS Drawing Concepts Applying Core Animation Effects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27When you manipulate a layer object’s properties, what you are actually manipulating is the model-level data that determines how the associated content should be displayed. The actual rendering of that content is handled separately from your code and is heavily optimized to ensure it is fast. All you must do is set the layer content, configure the animation properties, and then let Core Animation take over. For more information about layers and how they are used, see Core Animation Programming Guide . About Animations When it comes to animating layers, Core Animation uses separate animation objects to control the timing and behavior of the animation. The CAAnimation class and its subclasses provide different types of animation behaviors that you can use in your code. You can create simple animations that migrate a property from one value to another, or you can create complex keyframe animations that track the animation through the set of values and timing functions you provide. Core Animation also lets you group multiple animations together into a single unit, called a transaction. The CATransaction object manages the group of animations as a unit. You can also use the methods of this class to set the duration of the animation. For examples of how to create custom animations, see Animation Types and Timing Programming Guide . Accounting for Scale Factors in Core Animation Layers Apps that use Core Animation layers directly to provide content may need to adjust their drawing code to account for scale factors. Normally, when you draw in your view’s drawRect: method, or in the drawLayer:inContext: method of the layer’s delegate, the system automatically adjusts the graphics context to account for scale factors. However, knowing or changing that scale factor might still be necessary when your view does one of the following: ● Creates additional Core Animation layers with different scale factors and composites them into its own content ● Sets the contents property of a Core Animation layer directly Core Animation’s compositing engine looks at the contentsScale property of each layer to determine whether the contents of that layer need to be scaled during compositing. If your app creates layers without an associated view, each new layer object’s scale factor is initially set to 1.0. If you do not change that scale factor, and if you subsequently draw the layer on a high-resolution screen, the layer’s contents are scaled automatically to compensate for the difference in scale factors. If you do not want the contents to be scaled, you can change the layer’s scale factor to 2.0 by setting a new value for the contentsScale property, but if you do so without providing high-resolution content, your existing content may appear smaller than you were expecting. To fix that problem, you need to provide higher-resolution content for your layer. iOS Drawing Concepts Applying Core Animation Effects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Important: The contentsGravity property of the layer plays a role in determining whether standard-resolution layer content is scaled on a high-resolution screen. This property is set to the value kCAGravityResize by default, which causes the layer content to be scaled to fit the layer’s bounds. Changing the gravity to a nonresizing option eliminates the automatic scaling that would otherwise occur. In such a situation, you may need to adjust your content or the scale factor accordingly. Adjusting the content of your layer to accommodate different scale factors is most appropriate when you set the contents property of a layer directly. Quartz images have no notion of scale factors and therefore work directly with pixels. Therefore, before creating the CGImageRef object you plan to use for the layer’s contents, check the scale factor and adjust the size of your image accordingly. Specifically, load an appropriately sized image from your app bundle or use the UIGraphicsBeginImageContextWithOptions function to create an image whose scale factor matches the scale factor of your layer. If you do not create a high-resolution bitmap, the existing bitmap may be scaled as discussed previously. For information on how to specify and load high-resolution images, see “Loading Images into Your App” (page 83). For information about how to create high-resolution images, see “Drawing to Bitmap Contexts and PDF Contexts” (page 19). iOS Drawing Concepts Applying Core Animation Effects 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29In iOS 3.2 and later, you can use the UIBezierPath class to create vector-based paths. The UIBezierPath class is an Objective-C wrapper for the path-related features in the Core Graphics framework. You can use this classto define simple shapes,such as ovals and rectangles, as well as complex shapesthat incorporate multiple straight and curved line segments. You can use path objects to draw shapes in your app’s user interface. You can draw the path’s outline, fill the space it encloses, or both. You can also use paths to define a clipping region for the current graphics context, which you can then use to modify subsequent drawing operations in that context. Bézier Path Basics A UIBezierPath object is a wrapper for a CGPathRef data type. Paths are vector-based shapes that are built using line and curve segments. You can use line segments to create rectangles and polygons, and you can use curve segments to create arcs, circles, and complex curved shapes. Each segment consists of one or more points(in the current coordinate system) and a drawing command that defines how those points are interpreted. Each set of connected line and curve segments form what is referred to as a subpath. The end of one line or curve segment in a subpath defines the beginning of the next. A single UIBezierPath object may contain one or more subpaths that define the overall path, separated by moveToPoint: commands that effectively raise the drawing pen and move it to a new location. The processes for building and using a path object are separate. Building the path is the first process and involves the following steps: 1. Create the path object. 2. Set any relevant drawing attributes of your UIBezierPath object, such as the lineWidth or lineJoinStyle properties for stroked paths or the usesEvenOddFillRule property for filled paths. These drawing attributes apply to the entire path. 3. Set the starting point of the initial segment using the moveToPoint: method. 4. Add line and curve segments to define a subpath. 5. Optionally, close the subpath by calling closePath, which draws a straight line segment from the end of the last segment to the beginning of the first. 6. Optionally, repeat the steps 3, 4, and 5 to define additional subpaths. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30 Drawing Shapes Using Bézier PathsWhen building your path, you should arrange the points of your path relative to the origin point (0, 0). Doing so makes it easier to move the path around later. During drawing, the points of your path are applied as-is to the coordinate system of the current graphics context. If your path is oriented relative to the origin, all you have to do to reposition it is apply an affine transform with a translation factor to the current graphics context. The advantage of modifying the graphics context (as opposed to the path object itself) is that you can easily undo the transformation by saving and restoring the graphics state. To draw your path object, you use the stroke and fill methods. These methods render the line and curve segments of your path in the current graphics context. The rendering process involves rasterizing the line and curve segments using the attributes of the path object. The rasterization process does not modify the path object itself. As a result, you can render the same path object multiple timesin the current context or in another context. Adding Lines and Polygons to Your Path Lines and polygons are simple shapes that you build point-by-point using the moveToPoint: and addLineToPoint: methods. The moveToPoint: method sets the starting point of the shape you want to create. From that point, you create the lines of the shape using the addLineToPoint: method. You create the linesin succession, with each line being formed between the previous point and the new point you specify. Listing 2-1 shows the code needed to create a pentagon shape using individual line segments. (Figure 2-1 showsthe result of drawing thisshape with appropriate stroke and fill colorsettings, as described in “Rendering the Contents of a Bézier Path Object” (page 36).) This code sets the initial point of the shape and then adds four connected line segments. The fifth segment is added by the call to the closePath method, which connects the last point (0, 40) with the first point (100, 0). Listing 2-1 Creating a pentagon shape UIBezierPath *aPath = [UIBezierPath bezierPath]; // Set the starting point of the shape. [aPath moveToPoint:CGPointMake(100.0, 0.0)]; // Draw the lines. [aPath addLineToPoint:CGPointMake(200.0, 40.0)]; [aPath addLineToPoint:CGPointMake(160, 140)]; [aPath addLineToPoint:CGPointMake(40.0, 140)]; [aPath addLineToPoint:CGPointMake(0.0, 40.0)]; Drawing Shapes Using Bézier Paths Adding Lines and Polygons to Your Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31[aPath closePath]; Figure 2-1 Shape drawn with methods of the UIBezierPath class Using the closePath method not only ends the subpath describing the shape, it also draws a line segment between the first and last points. This is a convenient way to finish a polygon without having to draw the final line. Adding Arcs to Your Path The UIBezierPath class providessupport for initializing a new path object with an arc segment. The parameters of the bezierPathWithArcCenter:radius:startAngle:endAngle:clockwise: method define the circle that containsthe desired arc and the start and end points of the arc itself. Figure 2-2 showsthe components that go into creating an arc, including the circle that defines the arc and the angle measurements used to Drawing Shapes Using Bézier Paths Adding Arcs to Your Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32specify it. In this case, the arc is created in the clockwise direction. (Drawing the arc in the counterclockwise direction would paint the dashed portion of the circle instead.) The code for creating this arc isshown in Listing 2-2 (page 33). Figure 2-2 An arc in the default coordinate system 100 200 100 200 (0, 0) 3π 4 (135°) rad 75 pts 0 rad (0°) (150, 150) Listing 2-2 Creating a new arc path // pi is approximately equal to 3.14159265359. #define DEGREES_TO_RADIANS(degrees) ((pi * degrees)/ 180) - (UIBezierPath *)createArcPath { UIBezierPath *aPath = [UIBezierPath bezierPathWithArcCenter:CGPointMake(150, 150) radius:75 startAngle:0 endAngle:DEGREES_TO_RADIANS(135) clockwise:YES]; return aPath; } Drawing Shapes Using Bézier Paths Adding Arcs to Your Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33If you want to incorporate an arc segment into the middle of a path, you must modify the path object’s CGPathRef data type directly. For more information about modifying the path using Core Graphics functions, see “Modifying the Path Using Core Graphics Functions” (page 35). Adding Curves to Your Path The UIBezierPath class provides support for adding cubic and quadratic Bézier curves to a path. Curve segments start at the current point and end at the point you specify. The shape of the curve is defined using tangent lines between the start and end points and one or more control points. Figure 2-3 shows approximations of both types of curve and the relationship between the control points and the shape of the curve. The exact curvature of each segment involves a complex mathematical relationship between all of the points and is well documented online and at Wikipedia. Figure 2-3 Curve segments in a path Start point Control point 2 Endpoint Control point 1 A Current point B Control point C Endpoint Bézier curve Quad curve To add curves to a path, you use the following methods: ● Cubic curve:addCurveToPoint:controlPoint1:controlPoint2: ● Quadratic curve:addQuadCurveToPoint:controlPoint: Because curves rely on the current point of the path, you must set the current point before calling either of the preceding methods. Upon completion of the curve, the current point is updated to the new end point you specified. Drawing Shapes Using Bézier Paths Adding Curves to Your Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34Creating Oval and Rectangular Paths Ovals and rectangles are common types of pathsthat are built using a combination of curve and line segments. The UIBezierPath class includes the bezierPathWithRect: and bezierPathWithOvalInRect: convenience methods for creating paths with oval or rectangular shapes. Both of these methods create a new path object and initialize it with the specified shape. You can use the returned path object right away or add more shapes to it as needed. If you want to add a rectangle to an existing path object, you must do so using the moveToPoint:, addLineToPoint:, and closePath methods as you would for any other polygon. Using the closePath method for the final side of the rectangle is a convenient way to add the final line of the path and also mark the end of the rectangle subpath. If you want to add an oval to an existing path, the simplest way to do so is to use Core Graphics. Although you can use the addQuadCurveToPoint:controlPoint: to approximate an oval surface, the CGPathAddEllipseInRect function is much simpler to use and more accurate. For more information, see “Modifying the Path Using Core Graphics Functions” (page 35). Modifying the Path Using Core Graphics Functions The UIBezierPath class is really just a wrapper for a CGPathRef data type and the drawing attributes associated with that path. Although you normally add line and curve segments using the methods of the UIBezierPath class, the class also exposes a CGPath property that you can use to modify the underlying path data type directly. You can use this property when you would prefer to build your path using the functions of the Core Graphics framework. There are two ways to modify the path associated with a UIBezierPath object. You can modify the path entirely using Core Graphicsfunctions, or you can use a mixture of Core Graphicsfunctions and UIBezierPath methods. Modifying the path entirely using Core Graphics calls is easier in some ways. You create a mutable CGPathRef data type and call whatever functions you need to modify its path information. When you are done you assign your path object to the corresponding UIBezierPath object, as shown in Listing 2-3. Listing 2-3 Assigning a new CGPathRef to a UIBezierPath object // Create the path data. CGMutablePathRef cgPath = CGPathCreateMutable(); CGPathAddEllipseInRect(cgPath, NULL, CGRectMake(0, 0, 300, 300)); CGPathAddEllipseInRect(cgPath, NULL, CGRectMake(50, 50, 200, 200)); // Now create the UIBezierPath object. Drawing Shapes Using Bézier Paths Creating Oval and Rectangular Paths 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35UIBezierPath *aPath = [UIBezierPath bezierPath]; aPath.CGPath = cgPath; aPath.usesEvenOddFillRule = YES; // After assigning it to the UIBezierPath object, you can release // your CGPathRef data type safely. CGPathRelease(cgPath); If you choose to use a mixture of Core Graphics functions and UIBezierPath methods, you must carefully move the path information back and forth between the two. Because a UIBezierPath object owns its underlying CGPathRef data type, you cannot simply retrieve that type and modify it directly. Instead, you must make a mutable copy, modify the copy, and then assign the copy back to the CGPath property as shown in Listing 2-4. Listing 2-4 Mixing Core Graphics and UIBezierPath calls UIBezierPath *aPath = [UIBezierPath bezierPathWithOvalInRect:CGRectMake(0, 0, 300, 300)]; // Get the CGPathRef and create a mutable version. CGPathRef cgPath = aPath.CGPath; CGMutablePathRef mutablePath = CGPathCreateMutableCopy(cgPath); // Modify the path and assign it back to the UIBezierPath object. CGPathAddEllipseInRect(mutablePath, NULL, CGRectMake(50, 50, 200, 200)); aPath.CGPath = mutablePath; // Release both the mutable copy of the path. CGPathRelease(mutablePath); Rendering the Contents of a Bézier Path Object After creating a UIBezierPath object, you can render it in the current graphics context using its stroke and fill methods. Before you call these methods, though, there are usually a few other tasksto perform to ensure your path is drawn correctly: Drawing Shapes Using Bézier Paths Rendering the Contents of a Bézier Path Object 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36● Set the desired stroke and fill colors using the methods of the UIColor class. ● Position the shape where you want it in the target view. If you created your path relative to the point (0, 0), you can apply an appropriate affine transform to the current drawing context. For example, to draw your shape starting at the point (10, 10), you would call the CGContextTranslateCTM function and specify 10 for both the horizontal and vertical translation values. Adjusting the graphics context (as opposed to the points in the path object) is preferred because you can undo the change more easily by saving and restoring the previous graphics state. ● Update the drawing attributes of the path object. The drawing attributes of your UIBezierPath instance override the values associated with the graphics context when rendering the path. Listing 2-5 shows a sample implementation of a drawRect: method that draws an oval in a custom view. The upper-left corner of the oval’s bounding rectangle is located at the point (50, 50) in the view’s coordinate system. Because fill operations paint right up to the path boundary, this method fills the path before stroking it. This prevents the fill color from obscuring half of the stroked line. Listing 2-5 Drawing a path in a view - (void)drawRect:(CGRect)rect { // Create an oval shape to draw. UIBezierPath *aPath = [UIBezierPath bezierPathWithOvalInRect: CGRectMake(0, 0, 200, 100)]; // Set the render colors. [[UIColor blackColor] setStroke]; [[UIColor redColor] setFill]; CGContextRef aRef = UIGraphicsGetCurrentContext(); // If you have content to draw after the shape, // save the current state before changing the transform. //CGContextSaveGState(aRef); // Adjust the view's origin temporarily. The oval is // now drawn relative to the new origin point. CGContextTranslateCTM(aRef, 50, 50); Drawing Shapes Using Bézier Paths Rendering the Contents of a Bézier Path Object 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37// Adjust the drawing options as needed. aPath.lineWidth = 5; // Fill the path before stroking it so that the fill // color does not obscure the stroked line. [aPath fill]; [aPath stroke]; // Restore the graphics state before drawing any other content. //CGContextRestoreGState(aRef); } Doing Hit-Detection on a Path To determine whether a touch event occurred on the filled portion of a path, you can use the containsPoint: method of UIBezierPath. This method teststhe specified point against all closed subpathsin the path object and returns YES if it lies on or inside any of those subpaths. Important: The containsPoint: method and the Core Graphics hit-testing functions operate only on closed paths. These methods always return NO for hits on open subpaths. If you want to do hit detection on an open subpath, you must create a copy of your path object and close the open subpaths before testing points. If you want to do hit-testing on the stroked portion of the path (instead of the fill area), you must use Core Graphics. The CGContextPathContainsPoint function lets you test points on either the fill orstroke portion of the path currently assigned to the graphics context. Listing 2-6 shows a method that tests to see whether the specified point intersects the specified path. The inFill parameter lets the caller specify whether the point should be tested against the filled or stroked portion of the path. The path passed in by the caller must contain one or more closed subpaths for the hit detection to succeed. Listing 2-6 Testing points against a path object - (BOOL)containsPoint:(CGPoint)point onPath:(UIBezierPath *)path inFillArea:(BOOL)inFill { CGContextRef context = UIGraphicsGetCurrentContext(); Drawing Shapes Using Bézier Paths Doing Hit-Detection on a Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38CGPathRef cgPath = path.CGPath; BOOL isHit = NO; // Determine the drawing mode to use. Default to // detecting hits on the stroked portion of the path. CGPathDrawingMode mode = kCGPathStroke; if (inFill) { // Look for hits in the fill area of the path instead. if (path.usesEvenOddFillRule) mode = kCGPathEOFill; else mode = kCGPathFill; } // Save the graphics state so that the path can be // removed later. CGContextSaveGState(context); CGContextAddPath(context, cgPath); // Do the hit detection. isHit = CGContextPathContainsPoint(context, point, mode); CGContextRestoreGState(context); return isHit; } Drawing Shapes Using Bézier Paths Doing Hit-Detection on a Path 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39Most of the time, it is fairly straightforward to display images using standard views. However, there are two situations in which you may need to do additional work: ● If you want to display images as part of a custom view, you must draw the images yourself in your view’s drawRect: method. “Drawing Images” (page 40) explains how. ● If you want to render images offscreen (to draw later, or to save into a file), you must create a bitmap image context. To learn more, read “Creating New Images Using Bitmap Graphics Contexts” (page 41). Drawing Images For maximum performance, if your image drawing needs can be met using the UIImageView class, you should use this image object to initialize a UIImageView object. However, if you need to draw an image explicitly, you can store the image and use it later in your view’s drawRect: method. The following example shows how to load an image from your app’s bundle. NSString *imagePath = [[NSBundle mainBundle] pathForResource:@"myImage" ofType:@"png"]; UIImage *myImageObj = [[UIImage alloc] initWithContentsOfFile:imagePath]; // Store the image into a property of type UIImage * // for use later in the class's drawRect: method. self.anImage = myImageObj; To draw the resulting image explicitly in your view’s drawRect: method, you can use any of the drawing methods available in UIImage. These methods let you specify where in your view you want to draw the image and therefore do not require you to create and apply a separate transform prior to drawing. The following snippet draws the image loaded above at the point (10, 10) in the view. - (void)drawRect:(CGRect)rect { 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40 Drawing and Creating Images... // Draw the image. [self.anImage drawAtPoint:CGPointMake(10, 10)]; } Important: If you use the CGContextDrawImage function to draw bitmap images directly, the image data is inverted along the y axis by default. This is because Quartz images assume a coordinate system with a lower-left corner origin and positive coordinate axes extending up and to the right from that point. Although you can apply a transform before drawing, the simpler (and recommended) way to draw Quartz images is to wrap them in a UIImage object, which compensates for this difference in coordinate spaces automatically. For more information on creating and drawing images using Core Graphics, see Quartz 2D Programming Guide . Creating New Images Using Bitmap Graphics Contexts Most of the time, when drawing, your goal is to show something onscreen. However, it is sometimes useful to draw something to an offscreen buffer. For example, you might want to create a thumbnail of an existing image, draw into a buffer so that you can save it to a file, and so on. To support those needs, you can create a bitmap image context, use UIKit framework or Core Graphics functions to draw to it, and then obtain an image object from the context. In UIKit, the procedure is as follows: 1. Call UIGraphicsBeginImageContextWithOptions to create a bitmap context and push it onto the graphics stack. For the first parameter (size), pass a CGSize value to specify the dimensions of the bitmap context (in points). For the second parameter (opaque), if your image contains transparency (an alpha channel), pass NO. Otherwise, pass YES to maximize performance. For the final parameter (scale), pass 0.0 for a bitmap that is scaled appropriately for the main screen of the device, or pass the scale factor of your choice. For example, the following code snippet creates a bitmap that is 200 x 200 pixels. (The number of pixels is determined by multiplying the size of the image by the scale factor.) UIGraphicsBeginImageContextWithOptions(CGSizeMake(100.0,100.0), NO, 2.0); Drawing and Creating Images Creating New Images Using Bitmap Graphics Contexts 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41Note: You should generally avoid calling the similarly named UIGraphicsBeginImageContext function (except as a fallback for backwards compatibility), because it always creates images with a scale factor of 1.0. If the underlying device has a high-resolution screen, an image created with UIGraphicsBeginImageContext might not appear as smooth when rendered. 2. Use UIKit or Core Graphics routines to draw the content of the image into the newly created graphics context. 3. Call the UIGraphicsGetImageFromCurrentImageContext function to generate and return a UIImage object based on what you drew. If desired, you can continue drawing and call this method again to generate additional images. 4. Call UIGraphicsEndImageContext to pop the context from the graphics stack. The method in Listing 3-1 gets an image downloaded over the Internet and draws it into an image-based context, scaled down to the size of an app icon. It then obtains a UIImage object created from the bitmap data and assigns it to an instance variable. Note that the size of the bitmap (the first parameter of UIGraphicsBeginImageContextWithOptions) and the size of the drawn content (the size of imageRect) should match. If the content is larger than the bitmap, a portion of the content will be clipped and not appear in the resulting image. Listing 3-1 Drawing a scaled-down image to a bitmap context and obtaining the resulting image - (void)connectionDidFinishLoading:(NSURLConnection *)connection { UIImage *image = [[UIImage alloc] initWithData:self.activeDownload]; if (image != nil && image.size.width != kAppIconHeight && image.size.height != kAppIconHeight) { CGRect imageRect = CGRectMake(0.0, 0.0, kAppIconHeight, kAppIconHeight); UIGraphicsBeginImageContextWithOptions(itemSize, NO, [UIScreen mainScreen].scale); [image drawInRect:imageRect]; self.appRecord.appIcon = UIGraphicsGetImageFromCurrentImageContext(); // UIImage returned. UIGraphicsEndImageContext(); } else { self.appRecord.appIcon = image; } self.activeDownload = nil; [image release]; Drawing and Creating Images Creating New Images Using Bitmap Graphics Contexts 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42self.imageConnection = nil; [delegate appImageDidLoad:self.indexPathInTableView]; } You can also call Core Graphics functions to draw the contents of the generated bitmap image; the code fragment in Listing 3-2, which draws a scaled-down image of a PDF page, gives an example of this. Note that the code flips the graphics context prior to calling CGContextDrawPDFPage to align the drawn image with default coordinate system of UIKit. Listing 3-2 Drawing to a bitmap context using Core Graphics functions // Other code precedes... CGRect pageRect = CGPDFPageGetBoxRect(page, kCGPDFMediaBox); pdfScale = self.frame.size.width/pageRect.size.width; pageRect.size = CGSizeMake(pageRect.size.width * pdfScale, pageRect.size.height * pdfScale); UIGraphicsBeginImageContextWithOptions(pageRect.size, YES, pdfScale); CGContextRef context = UIGraphicsGetCurrentContext(); // First fill the background with white. CGContextSetRGBFillColor(context, 1.0,1.0,1.0,1.0); CGContextFillRect(context,pageRect); CGContextSaveGState(context); // Flip the context so that the PDF page is rendered right side up CGContextTranslateCTM(context, 0.0, pageRect.size.height); CGContextScaleCTM(context, 1.0, -1.0); // Scale the context so that the PDF page is rendered at the // correct size for the zoom level. CGContextScaleCTM(context, pdfScale,pdfScale); CGContextDrawPDFPage(context, page); CGContextRestoreGState(context); UIImage *backgroundImage = UIGraphicsGetImageFromCurrentImageContext(); UIGraphicsEndImageContext(); Drawing and Creating Images Creating New Images Using Bitmap Graphics Contexts 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43backgroundImageView = [[UIImageView alloc] initWithImage:backgroundImage]; // Other code follows... If you prefer using Core Graphics entirely for drawing in a bitmap graphics context, you can use the CGBitmapContextCreate function to create the context and draw your image contents into it. When you finish drawing, call the CGBitmapContextCreateImage function to obtain a CGImageRef object from the bitmap context. You can draw the Core Graphics image directly or use this it to initialize a UIImage object. When finished, call the CGContextRelease function on the graphics context. Drawing and Creating Images Creating New Images Using Bitmap Graphics Contexts 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44The UIKit framework provides a set of functions for generating PDF content using native drawing code. These functions let you create a graphics context that targets a PDF file or PDF data object. You can then create one or more PDF pages and draw into those pages using the same UIKit and Core Graphics drawing routines you use when drawing to the screen. When you are done, what you are left with is a PDF version of what you drew. The overall drawing process is similar to the process for creating any other image (described in “Drawing and Creating Images” (page 40)). It consists of the following steps: 1. Create a PDF context and push it onto the graphics stack (as described in “Creating and Configuring the PDF Context” (page 45)). 2. Create a page (as described in “Drawing PDF Pages” (page 48)). 3. Use UIKit or Core Graphics routines to draw the content of the page. 4. Add links if needed (as described in “Creating Links Within Your PDF Content” (page 50)). 5. Repeat steps 2, 3, and 4 as needed. 6. End the PDF context (as described in “Creating and Configuring the PDF Context” (page 45)) to pop the context from the graphicsstack and, depending on how the context was created, either write the resulting data to the specified PDF file or store it into the specified NSMutableData object. The following sections describe the PDF creation processin more detail using a simple example. For information about the functions you use to create PDF content, see UIKit Function Reference . Creating and Configuring the PDF Context You create a PDF graphics context using either the UIGraphicsBeginPDFContextToData or UIGraphicsBeginPDFContextToFile function. These functions create the graphics context and associate it with a destination for the PDF data. For the UIGraphicsBeginPDFContextToData function, the destination is an NSMutableData object that you provide. And for the UIGraphicsBeginPDFContextToFile function, the destination is a file in your app’s home directory. PDF documents organize their content using a page-based structure. This structure imposes two restrictions on any drawing you do: ● There must be an open page before you issue any drawing commands. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45 Generating PDF Content● You must specify the size of each page. The functions you use to create a PDF graphics context allow you to specify a default page size but they do not automatically open a page. After creating your context, you must explicitly open a new page using either the UIGraphicsBeginPDFPage or UIGraphicsBeginPDFPageWithInfo function. And each time you want to create a new page, you must call one of these functions again to mark the start of the new page. The UIGraphicsBeginPDFPage function creates a page using the default size, while the UIGraphicsBeginPDFPageWithInfo function lets you customize the page size and other page attributes. When you are done drawing, you close the PDF graphics context by calling the UIGraphicsEndPDFContext. This function closes the last page and writes the PDF content to the file or data object you specified at creation time. This function also removes the PDF context from the graphics context stack. Listing 4-1 shows the processing loop used by an app to create a PDF file from the text in a text view. Aside from three function calls to configure and manage the PDF context, most of the code is related to drawing the desired content. The textView member variable points to the UITextView object containing the desired text. The app uses the Core Text framework (and more specifically a CTFramesetterRef data type) to handle the text layout and management on successive pages. The implementations for the custom renderPageWithTextRange:andFramesetter: and drawPageNumber: methods are shown in Listing 4-2 (page 48). Listing 4-1 Creating a new PDF file - (IBAction)savePDFFile:(id)sender { // Prepare the text using a Core Text Framesetter. CFAttributedStringRef currentText = CFAttributedStringCreate(NULL, (CFStringRef)textView.text, NULL); if (currentText) { CTFramesetterRef framesetter = CTFramesetterCreateWithAttributedString(currentText); if (framesetter) { NSString *pdfFileName = [self getPDFFileName]; // Create the PDF context using the default page size of 612 x 792. UIGraphicsBeginPDFContextToFile(pdfFileName, CGRectZero, nil); CFRange currentRange = CFRangeMake(0, 0); NSInteger currentPage = 0; Generating PDF Content Creating and Configuring the PDF Context 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46BOOL done = NO; do { // Mark the beginning of a new page. UIGraphicsBeginPDFPageWithInfo(CGRectMake(0, 0, 612, 792), nil); // Draw a page number at the bottom of each page. currentPage++; [self drawPageNumber:currentPage]; // Render the current page and update the current range to // point to the beginning of the next page. currentRange = [self renderPageWithTextRange:currentRange andFramesetter:framesetter]; // If we're at the end of the text, exit the loop. if (currentRange.location == CFAttributedStringGetLength((CFAttributedStringRef)currentText)) done = YES; } while (!done); // Close the PDF context and write the contents out. UIGraphicsEndPDFContext(); // Release the framewetter. CFRelease(framesetter); } else { NSLog(@"Could not create the framesetter needed to lay out the atrributed string."); } // Release the attributed string. CFRelease(currentText); } else { NSLog(@"Could not create the attributed string for the framesetter"); } Generating PDF Content Creating and Configuring the PDF Context 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47} Drawing PDF Pages All PDF drawing must be done in the context of a page. Every PDF document has at least one page and many may have multiple pages. You specify the start of a new page by calling the UIGraphicsBeginPDFPage or UIGraphicsBeginPDFPageWithInfo function. These functions close the previous page (if one was open), create a new page, and prepare it for drawing. The UIGraphicsBeginPDFPage creates the new page using the default size while the UIGraphicsBeginPDFPageWithInfo function lets you customize the page size or customize other aspects of the PDF page. After you create a page, all of your subsequent drawing commands are captured by the PDF graphics context and translated into PDF commands. You can draw anything you want in the page, including text, vectorshapes, and images just as you would in your app’s custom views. The drawing commands you issue are captured by the PDF context and translated into PDF data. Placement of content on the the page is completely up to you but must take place within the bounding rectangle of the page. Listing 4-2 shows two custom methods used to draw content inside a PDF page. The renderPageWithTextRange:andFramesetter: method uses Core Text to create a text frame that fits the page and then lay out some text inside that frame. After laying out the text, it returns an updated range that reflectsthe end of the current page and the beginning of the next page. The drawPageNumber: method uses the NSString drawing capabilities to draw a page number string at the bottom of each PDF page. Note: This code snippet makes use of the Core Text framework. Be sure to add it to your project. Listing 4-2 Drawing page-based content // Use Core Text to draw the text in a frame on the page. - (CFRange)renderPage:(NSInteger)pageNum withTextRange:(CFRange)currentRange andFramesetter:(CTFramesetterRef)framesetter { // Get the graphics context. CGContextRef currentContext = UIGraphicsGetCurrentContext(); // Put the text matrix into a known state. This ensures // that no old scaling factors are left in place. CGContextSetTextMatrix(currentContext, CGAffineTransformIdentity); Generating PDF Content Drawing PDF Pages 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48// Create a path object to enclose the text. Use 72 point // margins all around the text. CGRect frameRect = CGRectMake(72, 72, 468, 648); CGMutablePathRef framePath = CGPathCreateMutable(); CGPathAddRect(framePath, NULL, frameRect); // Get the frame that will do the rendering. // The currentRange variable specifies only the starting point. The framesetter // lays out as much text as will fit into the frame. CTFrameRef frameRef = CTFramesetterCreateFrame(framesetter, currentRange, framePath, NULL); CGPathRelease(framePath); // Core Text draws from the bottom-left corner up, so flip // the current transform prior to drawing. CGContextTranslateCTM(currentContext, 0, 792); CGContextScaleCTM(currentContext, 1.0, -1.0); // Draw the frame. CTFrameDraw(frameRef, currentContext); // Update the current range based on what was drawn. currentRange = CTFrameGetVisibleStringRange(frameRef); currentRange.location += currentRange.length; currentRange.length = 0; CFRelease(frameRef); return currentRange; } - (void)drawPageNumber:(NSInteger)pageNum { NSString *pageString = [NSString stringWithFormat:@"Page %d", pageNum]; UIFont *theFont = [UIFont systemFontOfSize:12]; Generating PDF Content Drawing PDF Pages 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49CGSize maxSize = CGSizeMake(612, 72); CGSize pageStringSize = [pageString sizeWithFont:theFont constrainedToSize:maxSize lineBreakMode:UILineBreakModeClip]; CGRect stringRect = CGRectMake(((612.0 - pageStringSize.width) / 2.0), 720.0 + ((72.0 - pageStringSize.height) / 2.0), pageStringSize.width, pageStringSize.height); [pageString drawInRect:stringRect withFont:theFont]; } Creating Links Within Your PDF Content Besides drawing content, you can also include links that take the user to another page in the same PDF file or to an external URL. To create a single link, you must add a source rectangle and a link destination to your PDF pages. One of the attributes of the link destination is a string that serves as the unique identifier for that link. To create a link to a specific destination, you specify the unique identifier for that destination when creating the source rectangle. To add a new link destination to your PDF content, you use the UIGraphicsAddPDFContextDestinationAtPoint function. This function associates a named destination with a specific point on the current page. When you want to link to that destination point, you use UIGraphicsSetPDFContextDestinationForRect function to specify the source rectangle for the link. Generating PDF Content Creating Links Within Your PDF Content 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50Figure 4-1 shows the relationship between these two function calls when applied to the pages of your PDF documents. Tapping on the rectangle surrounding the “see Chapter 1” text takesthe user to the corresponding destination point, which is located at the top of Chapter 1. Figure 4-1 Creating a link destination and jump point Chapter 1 UIGraphicsAddPDFContextDestinationAtPoint Name: “Chapter_1” Point: (72, 72) see Chapter 1 UIGraphicsSetPDFContextDestinationForRect Name: “Chapter_1” Rect: (72, 528, 400, 44) In addition to creating links within a document, you can also use the UIGraphicsSetPDFContextURLForRect function to create links to content located outside of the document. When using this function to create links, you specify the target URL and the source rectangle on the current page. Generating PDF Content Creating Links Within Your PDF Content 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51In iOS 4.2 and later, apps can add support for printing content to local AirPrint-capable printers. Although not all apps need printing support, it is often a useful feature if your app is used for creating content (such as a word processor or a drawing program), making purchases(printing order confirmations), and other tasks where the user might reasonably want a permanent record. This chapter explains how to add printing support to your app. At a high level, your app creates a print job, providing either an array of ready-to-print images and PDF documents, a single image or PDF document, an instance of any of the built-in print formatter classes, or a custom page renderer. Terminology Note: The notion of a print job comes up many times in this chapter. A print job is a unit of work that includes not just the content to be printed but information used in the printing of it, such as the identity of the printer, the name of the print job, and the quality and orientation of printing. Printing in iOS is Designed to be Simple and Intuitive To print, users tap a button that is usually in a navigation bar or toolbar that is associated with the view or selected item the user wants to print. The app then presents a view of printing options. The user selects a printer and various options and then requests printing. The app is asked to generate printing output from its content or provide printable data or file URLs. The requested print job is spooled and control returns to the app. If the destination printer is currently not busy, printing beginsimmediately. If the printer is already printing or if there are jobs before it in the queue, the print job remains in the iOS print queue until it moves to the top of queue and is printed. The Printing User Interface The first thing a user sees related to printing is a print button. The print button is often a bar-button item on a navigation bar or a toolbar. The print button should logically apply to the content the app is presenting; if the user taps the button, the app should print that content. Although the print button can be any custom 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52 Printingbutton, it is recommended that you use the system item-action button shown in Figure 5-1. This is a UIBarButtonItem object, specified with the UIBarButtonSystemItemAction constant, that you create either in Interface Builder or by calling initWithBarButtonSystemItem:target:action:. Figure 5-1 System item action button—used for printing When a user taps the print button, a controller object of the app receives the action message. The controller responds by preparing for printing and displaying the printer-options view. The options always include the destination printer (selected from a list of discoverable printers), the number of copies, and sometimes the range of pages to print. If the selected printer is capable of duplex printing, users can choose single-sided or double-sided output. If users decide not to print, they tap outside the options view (on iPad) or tap the Cancel button (on iPhone and iPod touch) to dismiss the printer-options view. The kind of user interface shown depends on the device. On iPad, the UIKit framework displays a popover view containing the options, as shown in Figure 5-2. An app can animate this view to appear from the print button or from an arbitrary area of the app’s user interface. Figure 5-2 Printer-options popover view (iPad) Printing Printing in iOS is Designed to be Simple and Intuitive 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53On iPhone and iPod touch devices, UIKit displays a sheet of printing options that an app can animate to slide up from the bottom of the screen, as shown in Figure 5-3. Figure 5-3 Printer-options sheet (iPhone) Printing Printing in iOS is Designed to be Simple and Intuitive 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54Once a print job has been submitted and is either printing or waiting in the print queue, users can check on itsstatus by double-tapping the Home button to accessthe Print Center in the multitasking UI. The Print Center (shown in Figure 5-4) is a background system app that shows the order of jobs in the print queue, including those that are currently printing. It is only available while a print job is in progress. Figure 5-4 Print Center Printing Printing in iOS is Designed to be Simple and Intuitive 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55Users can tap a print job in the Print Center to get detailed information about it (Figure 5-5) and cancel jobs that are printing or waiting in the queue. Figure 5-5 Print Center: detail of print job How Printing Works in iOS An app uses the UIKit printing API to assemble the elements of a print job, including the content to print and information related to the print job. It then presents the printer-options view described in “The Printing User Interface” (page 52). The user makes his or her choices and then taps Print. In some cases, the UIKit framework then asks the app to draw the content to be printed; UIKit records what the app draws as PDF data. UIKit then hands off the printing data to the printing subsystem. The printing system does a few things. As UIKit passes the print data to the printing subsystem, it writes this data to storage (that is, it spools the data). It also captures information about the print job. The printing system manages the combined print data and metadata for each print job in a first-in-first-out print queue. Multiple apps on a device can submit multiple print jobs to the printing subsystem, and all of these are placed in the print queue. Each device has one queue for all print jobs regardless of originating app or destination printer. Printing Printing in iOS is Designed to be Simple and Intuitive 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56When a print job risesto the top of the queue, the system printing daemon (printd) considersthe destination printer's requirements and, if necessary, converts the print data to a form that is usable by the printer. The printing system reports error conditions such as "Out of Paper" to the user as alerts. It also reports the progress of print jobs programmatically to the Print Center, which displays information such as “page 2 of 5” for a print job. This overall architecture is shown in Figure 5-6. Figure 5-6 Printing architecture Application UIKit Print job Print job Print job Print job Printing subsystem Print Queue printd Printer The UIKit Printing API The UIKit printing API includes eight classes and one formal protocol. Objects of these classes and the delegate implementing the protocol have runtime relationships as depicted in Figure 5-7. Figure 5-7 Relationships of UIKit printing objects UIPrintFormatter subclass UIPrintPageRenderer subclass UIPrintInteractionController printInfo delegate printPaper printingItems printingItem printPageRenderer printFormatter UIPrintPaper paperSize printableRect numberOfPages headerHeight footerHeight paperRect printableRect printFormatters UIPrintFormatter UIPrintFormatter subclass subclass Inherited: contentInsets maximumContentWidth maximumContentHeight startPage pageCount , , , UIPrintInfo printerID jobName orientation duplex outputType Printing The UIKit Printing API 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 57Printing Support Overview At a high level, there are two waysto add printing to your app. If you are using a UIActivityViewController, and if you do not need the ability to control whether the user can choose a page range or override the paper selection process, you can add a printing activity. Otherwise, to add printing to your app, you must work with the UIPrintInteractionController class. A shared instance of the UIPrintInteractionController class provides your app with the ability to specify what should happen when the user tells your app to print. It contains information about the print job (UIPrintInfo) and the size of the paper and the area for the printed content (UIPrintPaper). It can also have a reference to a delegate object that adoptsthe UIPrintInteractionControllerDelegate protocol for further configuring behavior. More importantly, the print interaction controller lets your app provide the content to be printed. The UIPrintInteractionController class provides three distinct ways to print content: ● Static images or PDFs. For simple content, you can use the print interaction controller’s printingItem or printingItems properties to provide an image (in various formats), a PDF file, or an array of images and PDF files. ● Print formatters. If you need to print text and HTML content with automatic reflow, you can assign an instance of any of the built-in print formatter classesto the print interaction controller’s printFormatter property. ● Page renderers. Page renderers let you provide your own drawing routines for custom content, and give you complete control over the page layout, including headers and footers. To use a page renderer, you must first write a page renderer subclass, then assign an instance of it to the print interaction controller’s printPageRenderer property. Important: These four properties are mutually exclusive; that is, if you assign a value to one of the properties, UIKit makes sure that all the other properties are nil. With such a range of options available to you, what is the best option for your app? Table 5-1 clarifies the factors involved in making this decision. Table 5-1 Deciding how to print app content If... Then... Your app has access to directly printable Use the printingItem or printingItems properties. content (images or PDF documents). Printing The UIKit Printing API 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 58If... Then... You want to print a single image or PDF Use the printingItem property. document and want the user to be able to select a page range. Assign a UISimpleTextPrintFormatter or UIMarkupTextPrintFormatter object to the printFormatter property. The print-formatter object must be initialized with the plain or HTML text. You want to print a plain text or HTML document (and do not want additional content such as headers and footers). Get a UIViewPrintFormatter object from the view and assign it to the printFormatter property. You want to print the content of a UIKit view (and do not want additional content such as headers and footers). Assign an instance of a custom subclass of UIPrintPageRenderer to printPageRenderer. This subclass should implement the methods required for drawing headers and footers. You want the printed pages to have repeating headers and footers, possibly with incremented page numbers. Assign an instance of UIPrintPageRenderer (or a custom subclassthereof) to printPageRenderer. You can add one or more print formatters to render specific pages of content. If you are using a custom subclass of UIPrintPageRenderer, you also have the option of providing custom drawing code to render some or all of the pages yourself. You have mixed content or sources that you want to print—for example, HTML and custom drawing. Assign an instance of a custom subclass of UIPrintPageRenderer to printPageRenderer and draw everything that gets printed. You want to have the greatest amount of control over what gets drawn for printing. Printing Workflow The general workflow for printing an image, document, or other printable content of an app is as follows: 1. Obtain the shared instance of UIPrintInteractionController. 2. (Optional, but strongly recommended) Create a UIPrintInfo object, set attributes such as output type, job name, and print orientation; then assign the object to the printInfo property of the UIPrintInteractionController instance. (Setting the output type and job name are strongly recommended.) If you don’t assign a print-info object, UIKit assumes default attributes for the print job (for example, the job name is the app name). Printing The UIKit Printing API 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 593. (Optional) Assign a custom controller object to the delegate property. This object must adopt the UIPrintInteractionControllerDelegate protocol. The delegate can do a range of tasks. It can respond appropriately when printing options are presented and dismissed, and when the print job starts and ends. It can return a parent view controller for the print interaction controller. Also, by default, UIKit chooses a default paper size and printable area based on the output type, which indicates the kind of content your app is printing. If your app needs more control over paper size, you can override this standard behavior. See “Specifying Paper Size, Orientation, and Duplexing Options” (page 75) for more details. 4. Assign one of the following to a property of the UIPrintInteractionController instance: ● A single NSData, NSURL, UIImage, or ALAsset object containing or referencing PDF data or image data to the printingItem property. ● An array of directly printable images or PDF documents to the printingItems property. Array elements must be NSData, NSURL, UIImage, or ALAsset objects containing, referencing, or representing PDF data or images in supported formats. ● A UIPrintFormatter object to the printFormatter property. Print formatters perform custom layout of printable content. ● A UIPrintPageRenderer object to the printPageRenderer property. Only one of these properties can be non-nil for any print job. See “Printing Support Overview” (page 58) for descriptions of these properties. 5. If you assigned a page renderer in the previousstep, that object istypically an instance of a custom subclass of UIPrintPageRenderer. This object draws pages of content for printing when requested by the UIKit framework. It can also draw content in headers and footers of printed pages. A custom page renderer must override one or more of the “draw” methods and, if it is drawing at least part of the content (excluding headers and footers), it must compute and return the number of pages for the print job. (Note that you can use an instance of UIPrintPageRenderer “as-is” to connect a series of print formatters.) 6. (Optional) If you are using a page renderer, you can create one or more UIPrintFormatter objects using concrete subclasses of this class; then add the print formatters for specific pages (or page ranges) to the UIPrintPageRenderer instance either by calling the addPrintFormatter:startingAtPageAtIndex: method of UIPrintPageRenderer or by creating an array of one or more print formatters (each with its own starting page) and assigning that array to the printFormatters property of UIPrintPageRenderer. 7. If the current user-interface idiom is iPad, present the printing interface to the user by calling presentFromBarButtonItem:animated:completionHandler: or presentFromRect:inView:animated:completionHandler:; if the idiom is iPhone or iPod touch, call presentAnimated:completionHandler:. Alternatively, you can embed the printing UI into your existing UI by implementing a printInteractionControllerParentViewController: delegate method. If your app uses an activity sheet (in iOS 6.0 and later), you can also add a printing activity item. Printing The UIKit Printing API 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 60From here, the process varies depending on whether you are printing using static content, a print formatter, or a page renderer. Printing Printer-Ready Content The iOS printing system accepts certain objects and prints their contents directly, with minimal involvement by the app. These objects are instances of the NSData, NSURL, UIImage, and ALAsset classes, and they must contain or reference image data or PDF data. Image data involves all of these object types; PDF data is either referenced by NSURL objects or encapsulated by NSData objects. There are additional requirements for these printer-ready objects: ● An image must be in a format supported by the Image I/O framework. See “Supported Image Formats” in UIImage Class Reference for a list of these formats. ● NSURL objects must use as a scheme file:, assets-library:, or anything that can return an NSData with a registered protocol (for example, QuickLook’s x-apple-ql-id: scheme). ● ALAsset objects must be of type ALAssetTypePhoto. You assign printer-ready objects either to the printingItem or printingItems property of the shared UIPrintInteractionController instance. You assign a single printer-ready object to printingItem and an array of printer-ready objects to the printingItems property. Note: By providing printer-ready content, you are putting the layout of that content in the hands of the printing system. Thus, settings such as printing orientation have no effect. If your app needs to control layout, you must do the drawing yourself. Also, if your app uses printingItems for its printable content (as opposed to printingItem), users cannot specify page ranges in the printer-options view, even if there are multiple pages and the showsPageRange property is set to YES. Before assigning objects to the these properties, you should validate the objects by using one of the class methods of UIPrintInteractionController. If, for example, you have the UTI of an image and you want to verify that the image is printer-ready, you can test it first with the printableUTIs class method, which returns the set of UTIs that are valid for the printing system: if ([[UIPrintInteractionController printableUTIs] containsObject:mysteryImageUTI]) printInteractionController.printingItem = mysteryImage; Printing Printing Printer-Ready Content 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 61Similarly, you can apply the canPrintURL: and canPrintData: class methods of UIPrintInteractionController to NSURL and NSData objects prior to assigning those objects to the printingItem or printingItems properties. These methods determine if the printing system can directly print those objects. Their use is strongly recommended, especially for PDF. Listing 5-1 shows code that prints a PDF document encapsulated in an NSData object. Before assigning it to printingItem, it teststhe object’s validity. It also tellsthe print interaction controller to include the page-range controls in the printing options presented to the user. Listing 5-1 Printing a single PDF document with capability for page-range selection - (IBAction)printContent:(id)sender { UIPrintInteractionController *pic = [UIPrintInteractionController sharedPrintController]; if (pic && [UIPrintInteractionController canPrintData: self.myPDFData] ) { pic.delegate = self; UIPrintInfo *printInfo = [UIPrintInfo printInfo]; printInfo.outputType = UIPrintInfoOutputGeneral; printInfo.jobName = [self.path lastPathComponent]; printInfo.duplex = UIPrintInfoDuplexLongEdge; pic.printInfo = printInfo; pic.showsPageRange = YES: pic.printingItem = self.myPDFData; void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) = ^(UIPrintInteractionController *pic, BOOL completed, NSError *error) { self.content = nil; if (!completed && error) NSLog(@"FAILED! due to error in domain %@ with error code %u", error.domain, error.code); }; if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) { [pic presentFromBarButtonItem:self.printButton animated:YES completionHandler:completionHandler]; } else { Printing Printing Printer-Ready Content 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 62[pic presentAnimated:YES completionHandler:completionHandler]; } } The procedure for submitting several printer-ready objects at once is identical—except (of course), you must assign an array of these objects to the printingItems property: pic.printingItems = [NSArray arrayWithObjects:imageViewOne.image, imageViewTwo.image, imageViewThree.image, nil]; Using Print Formatters and Page Renderers Print formatters and page renderers are objectsthat lay out printable content over multiple pages. They specify the beginning page of content and compute the final page of content based on the starting page, the content area, and the content they lay out. They can also specify the margins relative to the printable area of the page. The difference can be summarized as follows: ● Print formatters lay out a single piece of content (a block of text or HTML, a view, and so on). ● Page renderers let you add headers and footers, perform custom drawing, and so on. Page renderers can, if desired, use print formatters to do most of their work. If you create a custom subclass of UIPrintPageRenderer, you can draw each page of printable content partially or entirely. A page renderer can have one or more print formatters associated with specific pages or page ranges of the printable content. Setting the Layout Properties for the Print Job To define the areas on pages for printable content, the UIPrintFormatter class declares four key properties for its concrete subclasses. These properties, along with the footerHeight and headerHeight properties of UIPrintPageRenderer and the paperSize and printableRect properties of UIPrintPaper, define the layout of a multi-page print job. Figure 5-8 (page 65) depicts this layout. Property Description Distances in points inset from the top, left, and right boundaries of the printable rectangle. These valuesset the margins of the printed content, although they can be overridden by the maximumContentHeight and maximumContentWidth values. The top inset applies only to the first page of a given formatter. contentInsets Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 63Property Description Specifies the maximum height of the content area, which factors in any header or footer height. UIKit compares this value against the height of the content area minus the top content-inset and uses the lesser of the two values. maximumContentHeight Specifies the maximum width of the content area. UIKit compares this value against the width of the content area created by the left content-inset and right content-inset and uses the lesser of the two values. maximumContentWidth The page on which this formatter should start drawing content for printing. This value is zero-based—the first page of output has a value of 0—but a formatter used by a pager renderer may begin drawing on a later page. For example, to tell a formatter to start printing on the third page, a page renderer would specify 2 for startPage. startPage Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 64Note: If you are using the printFormatter property of UIPrintInteractionController, there is no UIPrintPageRenderer object, which means you cannot specify headers or footers on the printed pages. Figure 5-8 The layout of a multi-page print job Paper rect Printable rect Right content inset Maximum content width Start page Page 1 Page 3 Header height Top content inset Footer height Left content inset Page 2 Maximum content height UIPrintFormatter uses all the properties depicted in the diagram in Figure 5-8 to compute the number of pages needed for the print job; it stores this value in the read-only pageCount property. Using a Print Formatter UIKit allows you to assign a single print formatter for a print job. This can be a useful capability if you have plain-text or HTML documents, because UIKit has concrete print-formatter classes for these types of textual content. The framework also implements a concrete print-formatter subclass that enables you to print the content of certain UIKit views in a printer-friendly way. The UIPrintFormatter class is the abstract base class for the system-provided print formatters. Currently, iOS provides the following built-in print formatters: ● UIViewPrintFormatter—automatically lays out the content of a view over multiple pages. To obtain a print formatter for a view, call the view’s viewPrintFormatter method. Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 65Not all built-in UIKit classes support printing. Currently, only the view classes UIWebView, UITextView, and MKMapView know how to draw their contents for printing. View formatters should not be used for printing your own custom views. To print the contents of a custom view, use a UIPrintPageRenderer instead. ● UISimpleTextPrintFormatter—automatically draws and lays out plain-text documents. Thisformatter allows you to set global properties for the text, such a font, color, alignment, and line-break mode. ● UIMarkupTextPrintFormatter—automatically draws and lays out HTML documents. Note: The UIPrintFormatter class is not intended to be subclassed by third-party developers. If you need to do custom layout, you should write a page renderer instead. Although the following discussion pertains to the use of a single formatter (and no page renderer), much of the information about print formatters applies to print formatters used in conjunction with page renderers, which is described in “Using One or More Formatters with a Page Renderer” (page 72). Printing Text or HTML Documents Many apps include textual content that users might want to print. If the content is plain text or HTML text, and you have access to the backing string for the displayed textual content, you can use an instance of UISimpleTextPrintFormatter or UIMarkupTextPrintFormatter to lay out and draw the text for printing. Simply create the instance, initializing it with the backing string, and specify the layout properties. Then assign it to the printFormatter instance variable of the shared UIPrintInteractionController instance. Listing 5-2 illustrates how you might use a UIMarkupTextPrintFormatter object to print an HTML document. It adds an additional inch of margin inside the (printer-defined) printable area. You can determine the printable area by examining the printPaper property of the UIPrintInteractionController object. For a more complete example of how to create margins of a specific width, see the PrintWebView sample code project. Listing 5-2 Printing an HTML document (without header information) - (IBAction)printContent:(id)sender { UIPrintInteractionController *pic = [UIPrintInteractionController sharedPrintController]; pic.delegate = self; UIPrintInfo *printInfo = [UIPrintInfo printInfo]; printInfo.outputType = UIPrintInfoOutputGeneral; Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 66printInfo.jobName = self.documentName; pic.printInfo = printInfo; UIMarkupTextPrintFormatter *htmlFormatter = [[UIMarkupTextPrintFormatter alloc] initWithMarkupText:self.htmlString]; htmlFormatter.startPage = 0; htmlFormatter.contentInsets = UIEdgeInsetsMake(72.0, 72.0, 72.0, 72.0); // 1 inch margins pic.printFormatter = htmlFormatter; pic.showsPageRange = YES; void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) = ^(UIPrintInteractionController *printController, BOOL completed, NSError *error) { if (!completed && error) { NSLog(@"Printing could not complete because of error: %@", error); } }; if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) { [pic presentFromBarButtonItem:sender animated:YES completionHandler:completionHandler]; } else { [pic presentAnimated:YES completionHandler:completionHandler]; } } Remember that if you use a single print formatter for a print job (that is, a UIPrintFormatter object assigned to the printFormatter property of the UIPrintInteractionController instance), you cannot draw header and footer content on each printed page. To do this you must use a UIPrintPageRenderer object plus any needed print formatters. For more information, see “Using One or More Formatters with a Page Renderer” (page 72). The procedure for using a UISimpleTextPrintFormatter object to lay out and print a plain text document is almost identical. However, the class of this object includes properties that enable you to set the font, color, and alignment of the printed text. Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 67Using a View Print Formatter You can use an instance of the UIViewPrintFormatter class to lay out and print the contents of some system views. The UIKit framework creates these view print formatters for the view. Often the same code used to draw the view for display is used to draw the view for printing. Currently, the system views whose contents you can print using a view print formatter are instances of UIWebView, UITextView, and MKMapView (MapKit framework). To get the view print formatter for a UIView object, call viewPrintFormatter on the view. Set the starting page and any layout properties and then assign the object to the printFormatter property of the UIPrintInteractionController shared instance. Alternatively, you can add the view print formatter to a UIPrintPageRenderer object if you are using that object to draw portions of the printed output. Listing 5-3 shows code that uses a view print formatter from a UIWebView object to print the contents of that view. Listing 5-3 Printing the contents of a web view - (void)printWebPage:(id)sender { UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController]; void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) = ^(UIPrintInteractionController *printController, BOOL completed, NSError *error) { if(!completed && error){ NSLog(@"FAILED! due to error in domain %@ with error code %u", error.domain, error.code); } }; UIPrintInfo *printInfo = [UIPrintInfo printInfo]; printInfo.outputType = UIPrintInfoOutputGeneral; printInfo.jobName = [urlField text]; printInfo.duplex = UIPrintInfoDuplexLongEdge; controller.printInfo = printInfo; controller.showsPageRange = YES; UIViewPrintFormatter *viewFormatter = [self.myWebView viewPrintFormatter]; viewFormatter.startPage = 0; controller.printFormatter = viewFormatter; Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 68if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) { [controller presentFromBarButtonItem:printButton animated:YES completionHandler:completionHandler]; }else [controller presentAnimated:YES completionHandler:completionHandler]; } For a complete example based on UIViewPrintFormatter, see the PrintWebView sample code project. Using a Page Renderer A page renderer is an instance of a custom subclass of UIPrintPageRenderer that draws the full or partial content of a print job. To use one, you must create the subclass, add it to your project, and instantiate it when you prepare a UIPrintInteractionController instance for a print job. Then assign the page renderer to the printPageRenderer property of the UIPrintInteractionController instance. A page renderer can have one or more print formatters associated with it; if it does, it mixes its drawing with the drawing of the print formatters. A page renderer can draw and lay out printable content on its own or it can use print formatters to handle some or all of the rendering of specific ranges of pages. Thus, for relatively straightforward formatting needs, you can use an instance of UIPrintPageRenderer “as-is” to connect multiple print formatters. However, most page renderers are typically instances of custom subclasses of UIPrintPageRenderer. Note: If you want to print header and footer information, such as a repeating document title and an incrementing page count, you must use a custom subclass of UIPrintPageRenderer. The UIPrintPageRenderer base class includes properties for the page count and for heights of headers and footers of pages. It also declares several methods that you can override to draw specific portions of a page: the header, the footer, the content itself, or to integrate page renderer and print formatter drawing. Setting Page Renderer Attributes If your page renderer is going to draw in the header or footer of each printed page, you should specify a height for the header and footer. To do this, assign float values (representing points) to the headerHeight and footerHeight properties inherited by your subclass. If these properties have height values of 0 (the default), the drawHeaderForPageAtIndex:inRect: and drawFooterForPageAtIndex:inRect: methods are not called. Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 69If your page renderer is going to draw in the content area of the page—that is, the area between any header or footer areas—then your subclass should override the numberOfPages method to compute and return the number of pages the page renderer will draw. If print formatters associated with the page renderer are going to draw all of the content between the header and footer, then the print formatters will compute the number of pages for you. This situation occurs your page renderer just draws in the header and footer areas and you let the print formatter draw all the other content. With a page renderer with no associated print formatter, the layout of each page of printable content is entirely up to you. When computing layout metrics, you can take into account the headerHeight, footerHeight, paperRect, and printableRect properties of UIPrintPageRenderer (the lasttwo properties are read-only). If the page renderer uses print formatters, the layout metrics also include the contentInsets, maximumContentHeight, and maximumContentWidth properties of UIPrintFormatter. See “Setting the Layout Properties for the Print Job” (page 63) for an illustration and explanation. Implementing the Drawing Methods When an app uses a page renderer to draw printable content, UIKit calls the following methods for each page of requested content. Note that there is no guarantee that UIKit calls these methods in page-sequence order. Moreover, if users request a subset of pages for printing (that is, they specify a page range), UIKit does not invoke the methods for pages not in the subset. Note: Remember that if you are drawing images or PDF documents as printable content using non-UIKit API (for example, Quartz API), then you must "flip” the UIKit’s coordinate system—putting the origin in the lower-left corner with positive values going upwards—to match the coordinate system used by Core Graphics. See “Coordinate Systems and Drawing in iOS” (page 13) for more information. The drawPageAtIndex:inRect: method calls each of the other draw methods, in the order listed below. Your app can override this method if you want to have complete control over what is drawn for printing. Override... To... Draw content in the header. This method is not called if headerHeight is 0. drawHeaderForPageAtIndex: inRect: Draw the content of the print job (that is, the area between the header and the footer). drawContentForPageAtIndex: inRect: Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 70Override... To... Intermix custom drawing with the drawing performed by print formatters. This method is called for each print formatter associated with a given page. See “Using One or More Formatters with a Page Renderer” (page 72) for more information. drawPrintFormatter: forPageAtIndex: Draw content in the footer. This method is not called if footerHeight is 0. drawFooterForPageAtIndex: inRect: All of these drawing methods are set up for drawing to the current graphics context (as returned by UIGraphicsGetCurrentContext). The rectangle passed into each method—defining header area, footer area, content area, and entire page—has values relative to the origin of the page, which is in the upper-left corner. Listing 5-4 shows example implementations of the drawHeaderForPageAtIndex:inRect: and drawFooterForPageAtIndex:inRect: methods. They use CGRectGetMaxX and CGRectGetMaxY to compute placement of text in the footerRect and headerRect rectangles in the coordinate system of the printable rectangle. Listing 5-4 Drawing the header and footer of a page - (void)drawHeaderForPageAtIndex:(NSInteger)pageIndex inRect:(CGRect)headerRect { UIFont *font = [UIFont fontWithName:@"Helvetica" size:12.0]; CGSize titleSize = [self.jobTitle sizeWithFont:font]; //center title in header CGFloat drawX = CGRectGetMaxX(headerRect)/2 - titleSize.width/2; CGFloat drawY = CGRectGetMaxY(headerRect) - titleSize.height; CGPoint drawPoint = CGPointMake(drawX, drawY); [self.jobTitle drawAtPoint:drawPoint withFont: font]; } - (void)drawFooterForPageAtIndex:(NSInteger)pageIndex inRect:(CGRect)footerRect { UIFont *font = [UIFont fontWithName:@"Helvetica" size:12.0]; NSString *pageNumber = [NSString stringWithFormat:@"%d.", pageIndex+1]; // page number at right edge of footer rect CGSize pageNumSize = [pageNumber sizeWithFont:font]; Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 71CGFloat drawX = CGRectGetMaxX(footerRect) - pageNumSize.width - 1.0; CGFloat drawY = CGRectGetMaxY(footerRect) - pageNumSize.height; CGPoint drawPoint = CGPointMake(drawX, drawY); [pageNumber drawAtPoint:drawPoint withFont: font]; } Using One or More Formatters with a Page Renderer A page renderer can draw printable content in conjunction with one or more print formatters. For example, an app can use a UISimpleTextPrintFormatter object to draw pages of textual content for printing, but use a page renderer to draw a document title in each page header. Or an app can use two print formatters, one to draw header (or summary) information at the beginning of the first page and another print formatter to draw the remaining content; then it might use a page renderer to draw a line separating the two parts. As you may recall, you can use a single print formatter for a print job by assigning it the printFormatter property of the UIPrintInteractionController shared instance. But if you use a page renderer and print formatters, you must associate each print formatter with the page renderer. You do this one of two ways: ● Include each print formatter in the array assigned to the printFormatters property. ● Add each print formatter by calling the addPrintFormatter:startingAtPageAtIndex: method. Before you associate a print formatter with a page renderer, be sure to set its layout properties, including the starting page (startPage) of the print job. Once you have set these properties, UIPrintFormatter computes the number of pages for the print formatter. Note that if you specify a starting page by calling addPrintFormatter:startingAtPageAtIndex:; that value overwrites any value assigned to startPage. For a discussion of print formatters and layout metrics,see “Setting the Layout Propertiesfor the PrintJob” (page 63). A page renderer can override drawPrintFormatter:forPageAtIndex: to integrate its drawing with the drawing performed by the print formatters assigned to a given page. It can draw in an area of the page where the print formatter doesn’t draw and then call the drawInRect:forPageAtIndex: method on the passed-in print formatter to have it draw its portion of the page. Or the page renderer can achieve an “overlay” effect by having the print formatter draw first and then drawing something over the content drawn by the print formatter. For complete examples based on UIPrintPageRenderer, see the PrintPhoto , Recipes and Printing , and PrintWebView sample code projects. Printing Using Print Formatters and Page Renderers 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 72Testing the Printing of App Content The iOS 4.2 SDK (and later) provides a Printer Simulator app that you can use to test your app’s printing capabilities. The app simulates printers of various general types (inkjet, black-and-white laser, color laser, and so on). It displays printed pages in the OS X Preview app. You can set a preference to show the printable area of each page. Printer Simulator also logs information from the printing system about each print job. You can run the Printer Simulator in one of thee ways: ● Choose Open Printer Simulator from the File menu in the iOS Simulator. ● Choose the Printer Simulator in Xcode using the Xcode > Open Developer Tool menu. ● You can find Printer Simulator in the following file-system location: /Platforms/iPhoneOS.platform/Developer/Applications/PrinterSimulator.app When testing your app’s printing code, you should also implement the completion handler passed into the present... methods and log any errors returned from the printing system. These errors are typically programming errors, which you should catch before your app is deployed. See “Responding to Print-Job Completion and Errors” (page 79) for details. Common Printing Tasks All the coding tasks described below are things that an app does (or can do) in response to a request for printing. Although most of the tasks can occur in any order, you should first check that the device is capable of printing and you should conclude with presenting the printing options. See “Printing Printer-Ready Content” (page 61), “Using Print Formatters and Page Renderers” (page 63), and “Using a Page Renderer” (page 69) for complete examples. An important set of tasks not covered here is adding a print button to an appropriate place in the app’s user interface, declaring an action method, making a target-action connection, and implementing the action method. (See “The Printing User Interface” (page 52) for a recommendation on which print button to use.) The following tasks (except for “Specifying Paper Size, Orientation, and Duplexing Options” (page 75)) are part of the implementation of the action method. Testing for Printing Availability Some iOS devices do not support printing. You should immediately determine this fact once your view loads. If printing is not available for the device, you should either not programmatically add any printing user-interface element (button, bar button item, and so on), or you should remove any printing element loaded from a nib Printing Testing the Printing of App Content 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 73file. To determine if printing is available, call the isPrintingAvailable class method of UIPrintInteractionController. Listing 5-5 illustrates how you might do this; it assumes an outlet to a print button (myPrintButton) loaded from a nib file. Listing 5-5 Enabling or disabling a print button based on availability of printing - (void)viewDidLoad { if (![UIPrintInteractionController isPrintingAvailable]) [myPrintButton removeFromSuperView]; // other tasks... } Note: Although you could disable a printing element such as an “action” bar button item, removal is recommended. The value returned by isPrintingAvailable never changes for a given device because it reflects whether that device supports printing, not whether printing is currently available. Specifying Print-Job Information An instance of the UIPrintInfo class encapsulates information about a print job, specifically: ● The output type (indicating the type of content) ● The print-job name ● The printing orientation ● The duplex mode ● The identifier of the selected printer You do not need to assign values to all UIPrintInfo properties; users choose some of these values and UIKit assumes default valuesfor others. (Indeed, you don’t even have to explicitly create an instance of UIPrintInfo.) However, in most cases you’ll want to specify some aspects of a print job, such as output type. Get an instance of UIPrintInfo by calling the printInfo class method. Assign values to the object’s properties you want to configure. Then assign the UIPrintInfo object to the printInfo property of the shared UIPrintInteractionController instance. Listing 5-6 gives an example of this procedure. Listing 5-6 Setting properties of a UIPrintInfo object and assigning it to the printInfo property UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController]; Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 74UIPrintInfo *printInfo = [UIPrintInfo printInfo]; printInfo.outputType = UIPrintInfoOutputGeneral; printInfo.jobName = [self.path lastPathComponent]; printInfo.duplex = UIPrintInfoDuplexLongEdge; controller.printInfo = printInfo; One of the UIPrintInfo properties is the printing orientation: portrait or landscape. You might want the printing orientation to suit the dimensions of the object being printed. In other words, if the object is large, and its width is greater than its height, landscape would be a suitable printing orientation for it. Listing 5-7 illustrates this with an image. Listing 5-7 Setting the printing orientation to match image dimension UIPrintInteractionController *controller = [UIPrintInteractionController sharedPrintController]; // other code here... UIPrintInfo *printInfo = [UIPrintInfo printInfo]; UIImage *image = ((UIImageView *)self.view).image; printInfo.outputType = UIPrintInfoOutputPhoto; printInfo.jobName = @"Image from PrintPhoto"; printInfo.duplex = UIPrintInfoDuplexNone; // only if drawing... if (!controller.printingItem && image.size.width > image.size.height) printInfo.orientation = UIPrintInfoOrientationLandscape; Specifying Paper Size, Orientation, and Duplexing Options By default, UIKit presents a set of default paper sizes for printable content based on the destination printer and the output type of the print job, as specified by the outputType property of the UIPrintInfo object. For example, if the output type is UIPrintInfoOutputPhoto, the default paper size is 4 x 6 inches, A6, or some other standard size, depending on locale; if the output type is UIPrintInfoOutputGeneral or UIPrintInfoOutputGrayscale, the default paper size is US Letter (8 1/2 x 11 inches), A4, or some other standard size, depending on locale. For most apps, these default paper sizes are acceptable. However, some apps might need a special paper size. A page-based app might need to show the user how content will actually appear on paper of a given size, an app that produces brochures or greeting cards might have its own preferred size, and so on. Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 75In this case, the delegate of the print interaction controller can implement the UIPrintInteractionControllerDelegate protocol method printInteractionController:choosePaper: to return a UIPrintPaper objectrepresenting the optimal combination of available paper size and printable rectangle for a given content size. The delegate has two approaches it can take. It can examine the passed-in array of UIPrintPaper objects and identify the one that is most suitable. Or it can let the system pick the most suitable object by calling the UIPrintPaper class method bestPaperForPageSize:withPapersFromArray:. Listing 5-8 shows an implementation of the method for an app that supports multiple document types, each with its own page size. Listing 5-8 Implementing the printInteractionController:choosePaper: method - (UIPrintPaper *)printInteractionController:(UIPrintInteractionController *)pic choosePaper:(NSArray *)paperList { // custom method & properties... CGSize pageSize = [self pageSizeForDocumentType:self.document.type]; return [UIPrintPaper bestPaperForPageSize:pageSize withPapersFromArray:paperList]; } Typically, apps that use custom page renderers factor the paper size into their calculations of the number of pages for a print job (numberOfPages). If your app needs to present the user with a choice of page size (for a word processing app, for example), you must implement that UI yourself, and you must then use that paper size in your printInteractionController:choosePaper: implementation. For example: // Create a custom CGSize for 8.5" x 11" paper. CGSize custompapersize = CGSizeMake(8.5 * 72.0, 11.0 * 72.0); The UIPrintInfo class also lets you provide additional settings, such as the printing orientation, selected printer, and the duplexing mode (if the printersupports duplex printing). Users can change the selected printer and duplex settings from the values you provide Integrating Printing Into Your User Interface There are two ways to integrate printing into your user interface: Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 76● Using a print interaction controller. ● From the activity sheet (in iOS 6.0 and later). The way you integrate printing depends on which of these techniques you choose. Presenting Printing Options Using a Print Interaction Controller UIPrintInteractionController declares three methods for presenting the printing options to users, each with its own animation: ● presentFromBarButtonItem:animated:completionHandler: animates a popover view from a button in the navigation bar or toolbar (usually the print button). ● presentFromRect:inView:animated:completionHandler: animates a popover view from an arbitrary rectangle in the app’s view. ● presentAnimated:completionHandler: animates a sheet that slides up from the bottom of the screen. The first two of these methods are intended to be invoked on iPad devices; the third method is intended to be invoked on iPhone and iPod touch devices. You can conditionally code for each device type (or, user-interface idiom) by calling the UI_USER_INTERFACE_IDIOM and comparing the result to UIUserInterfaceIdiomPad or UIUserInterfaceIdiomPhone. Listing 5-9 gives an example of this. Listing 5-9 Presenting printing options based upon current device type if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad) { [controller presentFromBarButtonItem:self.printButton animated:YES completionHandler:completionHandler]; } else { [controller presentAnimated:YES completionHandler:completionHandler]; } If your app calls one of the iPad-specific methods on an iPhone (and requests animation), the default behavior is to display the printing options in a sheet that slides up from the bottom of the screen. If your app calls the iPhone-specific method on iPad, the default behavior is to animate the popover view from the current window frame. If you call one of the present… methods when the printing options are already displayed, UIPrintInteractionController hidesthe printing-options view orsheet. You must call the method again to display the options. Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 77If you assign a printer ID or a duplex mode as print-info values, these appear as defaultsin the printing options. (The printer must be capable of double-sided printing for the duplex control to appear.) If you want to let your users select ranges of pages for printing, you should set the showsPageRange property of the UIPrintInteractionController object to YES (NO is the default value). Be aware, however, that no page-range control appears in the printing options if you supply printable content via the printingItems property or if the total number of pages is 1, even if showsPageRange is YES. If you want the printing UI to appear within a particular view, you can do this by implementing the printInteractionControllerParentViewController: method in your UIPrintInteractionControllerDelegate class. This method should return the view controller that should be used as the parent for the print interaction controller. If the provided parent view controller is a UINavigationController instance, the printing UI is pushed into view in that controller. For any other UIViewController instance, the print navigation is shown as a modal dialog within the specified view. Printing From the Activity Sheet If your app uses an activity sheet (in iOS 6.0 and later), you can allow printing from the activity sheet. Printing from the activity sheet is simpler than using a print interaction controller. There are two caveats, however: ● The app cannot control whether a user can choose a page range. ● The app cannot use delegate methods to override behavior, such as manually overriding the paper size selection process. To use this technique, your app must create an activity items array containing: ● A UIPrintInfo object. ● Either a page renderer formatter object, a page renderer or a printable item. ● Any additional activity items appropriate for your app. You then call initWithActivityItems:applicationActivities:, passing that array asthe first parameter and nil as the second parameter (or an array of custom activities, if your app provides any). Finally, you present the activity view using the standard view controller present* methods. If the user chooses to printfromthat activity view, iOS creates a printjob for you. Formore information,read UIActivityViewController Class Reference and UIActivity Class Reference . Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 78Responding to Print-Job Completion and Errors The final parameter of the presentation methods declared by UIPrintInteractionController and described in “Presenting Printing Options Using a Print Interaction Controller ” (page 77) is a completion handler. The completion handler is a block of type UIPrintInteractionCompletionHandler that isinvoked when a print job completes successfully or when it is terminated because of an error. You can provide a block implementation that cleans up state that you have set up for the print job. The completion handler can also log error messages. The example in Listing 5-10 clears an internal property upon completion or error; if there is an error, it logs information about it. Listing 5-10 Implementing a completion-handler block void (^completionHandler)(UIPrintInteractionController *, BOOL, NSError *) = ^(UIPrintInteractionController *pic, BOOL completed, NSError *error) { self.content = nil; if (!completed && error) NSLog(@"FAILED! due to error in domain %@ with error code %u", error.domain, error.code); }; UIKit automatically releases all objects assigned to the UIPrintInteractionController instance at the end of a print job (except for the delegate), so you do not have to do this yourself in a completion handler. A printing error isrepresented by an NSError object having a domain of UIPrintErrorDomain and an error code declared in UIPrintError.h. In almost all cases, these codes indicate programming errors, so usually there is no need to inform the user about them. However, some errors can result from an attempt to print a file (located by a file-scheme NSURL object) that results in an error. Printing Common Printing Tasks 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 79Drawing is a relatively expensive operation on any platform, and optimizing your drawing code should always be an important step in your development process. Table A-1 lists several tips for ensuring that your drawing code is as optimal as possible. In addition to these tips, you should always use the available performance tools to test your code and remove hotspots and redundancies. Table A-1 Tips for improving drawing performance Tip Action During each update cycle, you should update only the portions of your view that actually changed. If you are using the drawRect: method of UIView to do your drawing, use the update rectangle passed to that method to limit the scope of your drawing. For OpenGL drawing, you must track updates yourself. Draw minimally If you are calling setNeedsDisplay:, always spend the time to calculate the actual area that you need to redraw. Don’t just pass a rectangle containing the entire view. Also, don’t call setNeedsDisplay: unless you actually need to redraw content. If the content hasn’t actually changed, don’t redraw it. Call setNeedsDisplay: judiciously Compositing a view whose contents are opaque requires much less effort than compositing one that is partially transparent. To make a view opaque, the contents of the view must not contain any transparency and the opaque property of the view must be set to YES. Mark opaque views as such Creating new views during scrolling should be avoided at all costs. Taking the time to create new views reduces the amount of time available for updating the screen, which leads to uneven scrolling behavior. Reuse table cells and views during scrolling By modifying the current transformation matrix, you can use a single path to draw content on different parts of the screen. For details, see “Using Coordinate Transforms to Improve Drawing Performance” (page 24). Reuse paths by modifying the current transformation matrix By default, UIKit clears a view’s current context buffer prior to calling its drawRect: method to update that same area. If you are responding to scrolling eventsin your view, clearing thisregion repeatedly during scrolling updates can be expensive. To disable the behavior, you can change the value in the clearsContextBeforeDrawing property to NO. Avoid clearing the previous content during scrolling 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 80 Improving Drawing PerformanceTip Action Changing the graphics state requires work by the underlying graphics subsystems. If you need to draw content that usessimilarstate information, try to draw that content together to reduce the number of state changes needed. Minimize graphics state changes while drawing The Core Animation instrument can help you spot drawing performance problems in your app. In particular: ● Flash Updated Regions makes it easy to see what parts of your view are actually being updated. ● Color Misaligned Images helps you see imagesthat are aligned poorly, which results in both fuzzy images and poor performance. For more information,see “Measuring Graphics Performance in Your iOS Device” in Instruments User Guide . Use Instruments to debug your performance Improving Drawing Performance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 81Apps built against iOS SDK 4.0 and later need to be prepared to run on devices with differentscreen resolutions. Fortunately, iOS makes supporting multiple screen resolutions easy. Most of the work of handling the different types of screens is done for you by the system frameworks. However, your app still needs to do some work to update raster-based images, and depending on your app you may want to do additional work to take advantage of the extra pixels available to you. See “Points Versus Pixels” (page 16) for important background information related to this topic. Checklist for Supporting High-Resolution Screens To update your apps for devices with high-resolution screens, you need to do the following: ● Provide a high-resolution image for each image resource in your app bundle, as described in “Updating Your Image Resource Files” (page 83). ● Provide high-resolution app and document icons, as described in “Updating Your App’s Icons and Launch Images” (page 85). ● For vector-based shapes and content, continue using your custom Core Graphics and UIKit drawing code as before. If you want to add extra detail to your drawn content, see “Points Versus Pixels” (page 16) for information on how to do so. ● If you use OpenGL ES for drawing, decide whether you want to opt in to high-resolution drawing and set the scale factor of your layer accordingly, as described in “Drawing High-Resolution Content Using OpenGL ES or GLKit” (page 85). ● For custom images that you create, modify your image-creation code to take the current scale factor into account, as described in “Drawing to Bitmap Contexts and PDF Contexts” (page 19). ● If your app uses Core Animation, adjust your code as needed to compensate for scale factors, as described in “Accounting for Scale Factors in Core Animation Layers” (page 28). Drawing Improvements That You Get for Free The drawing technologies in iOS provide a lot of support to help you make your rendered content look good regardless of the resolution of the underlying screen: 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 82 Supporting High-Resolution Screens In Views● Standard UIKit views (text views, buttons, table views, and so on) automatically render correctly at any resolution. ● Vector-based content (UIBezierPath, CGPathRef, PDF) automatically takes advantage of any additional pixels to render sharper lines for shapes. ● Text is automatically rendered at higher resolutions. ● UIKit supports the automatic loading of high-resolution variants (@2x) of your images. If your app uses only native drawing technologies for its rendering, the only thing you need to do to support higher-resolution screens is provide high-resolution versions of your images. Updating Your Image Resource Files Apps running in iOS 4 should now include two separate files for each image resource. One file provides a standard-resolution version of a given image, and the second provides a high-resolution version of the same image. The naming conventions for each pair of image files is as follows: ● Standard: . ● High resolution: @2x. The and portions of each name specify the usual name and extension for the file. The portion is optional and contains either the string ~ipad or ~iphone. You include one of these modifiers when you want to specify different versions of an image for iPad and iPhone. The inclusion of the @2x modifier for the high-resolution image is new and letsthe system know that the image is the high-resolution variant of the standard image. Important: The order of the modifiers is critical. If you incorrectly put the @2x after the device modifier, iOS will not find the image. When creating high-resolution versions of your images, place the new versions in the same location in your app bundle as the original. Loading Images into Your App The UIImage class handles all of the work needed to load high-resolution imagesinto your app. When creating new image objects, you use the same name to request both the standard and the high-resolution versions of your image. For example, if you have two image files, named Button.png and Button@2x.png, you would use the following code to request your button image: Supporting High-Resolution Screens In Views Updating Your Image Resource Files 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 83UIImage *anImage = [UIImage imageNamed:@"Button"]; Note: In iOS 4 and later, you may omit the filename extension when specifying image names. On devices with high-resolution screens, the imageNamed:, imageWithContentsOfFile:, and initWithContentsOfFile: methods automatically looksfor a version of the requested image with the @2x modifier in its name. If it finds one, it loads that image instead. If you do not provide a high-resolution version of a given image, the image object still loads a standard-resolution image (if one exists) and scales it during drawing. When it loads an image, a UIImage object automatically sets the size and scale properties to appropriate values based on the suffix of the image file. For standard resolution images, it sets the scale property to 1.0 and sets the size of the image to the image’s pixel dimensions. For images with the @2x suffix in the filename, it sets the scale property to 2.0 and halves the width and height values to compensate for the scale factor. These halved values correlate correctly to the point-based dimensions you need to use in the logical coordinate space to render the image. Note: If you use Core Graphics to create an image, remember that Quartz images do not have an explicit scale factor, so their scale factor is assumed to be 1.0. If you want to create a UIImage object from a CGImageRef data type, use the initWithCGImage:scale:orientation: to do so. That method allows you to associate a specific scale factor with your Quartz image data. A UIImage object automatically takes its scale factor into account during drawing. Thus, any code you have for rendering images should work the same as long as you provide the correct image resources in your app bundle. Using an Image View to Display Multiple Images If your app uses the UIImageView class to present multiple images for a highlight or animation, all of the images you assign to that view must use the same scale factor. You can use an image view to display a single image or to animate several images, and you can also provide a highlight image. Therefore, if you provide high-resolution versions for one of these images, then all must have high-resolution versions as well. Supporting High-Resolution Screens In Views Updating Your Image Resource Files 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 84Updating Your App’s Icons and Launch Images In addition to updating your app’s custom image resources, you should also provide new high-resolution icons for your app’s icon and launch images. The process for updating these image resources is the same as for all other image resources. Create a new version of the image, add the @2x modifier string to the corresponding image filename, and treat the image as you do the original. For example, for app icons, add the high-resolution image filename to the CFBundleIconFiles key of your app’s Info.plist file. For information about specifying the icons and launch images for your app, see “App-Related Resources” in iOS App Programming Guide . Drawing High-Resolution Content Using OpenGL ES or GLKit If your app uses OpenGL ES or GLKit for rendering, your existing drawing code should continue to work without any changes. When drawn on a high-resolution screen, though, your content is scaled accordingly and will appear more blocky. The reason for the blocky appearance is that the default behavior of the CAEAGLLayer class, which you use to back your OpenGL ES renderbuffers (directly or indirectly), is the same as other Core Animation layer objects. In other words, its scale factor is set to 1.0 initially, which causes the Core Animation compositor to scale the contents of the layer on high-resolution screens. To avoid this blocky appearance, you need to increase the size of your OpenGL ES renderbuffers to match the size of the screen. (With more pixels, you can then increase the amount of detail you provide for your content.) Because adding more pixels to your renderbuffers has performance implications, though, you must explicitly opt in to support high-resolution screens. To enable high-resolution drawing, you must change the scale factor of the view you use to present your OpenGL ES or GLKit content. Changing the contentScaleFactor property of your view from 1.0 to 2.0 triggers a matching change to the scale factor of the underlying CAEAGLLayer object. The renderbufferStorage:fromDrawable: method, which you use to bind the layer object to your renderbuffers, calculatesthe size of the render buffer by multiplying the layer’s bounds by itsscale factor. Thus, doubling the scale factor doubles the width and height of the resulting render buffer, giving you more pixels for your content. After that, it is up to you to provide the content for those additional pixels. Listing B-1 shows the proper way to bind your layer object to your renderbuffers and retrieve the resulting size information. If you used the OpenGL ES app template to create your code, then this step is already done for you, and the only thing you need to do is set the scale factor of your view appropriately. If you did not use the OpenGL ES app template, you should use code similar to this to retrieve the render buffer size. You should never assume that the render buffer size is fixed for a given type of device. Listing B-1 Initializing a render buffer’s storage and retrieving its actual dimensions GLuint colorRenderbuffer; Supporting High-Resolution Screens In Views Drawing High-Resolution Content Using OpenGL ES or GLKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 85glGenRenderbuffersOES(1, &colorRenderbuffer); glBindRenderbufferOES(GL_RENDERBUFFER_OES, colorRenderbuffer); [myContext renderbufferStorage:GL_RENDERBUFFER_OES fromDrawable:myEAGLLayer]; // Get the renderbuffer size. GLint width; GLint height; glGetRenderbufferParameterivOES(GL_RENDERBUFFER_OES, GL_RENDERBUFFER_WIDTH_OES, &width); glGetRenderbufferParameterivOES(GL_RENDERBUFFER_OES, GL_RENDERBUFFER_HEIGHT_OES, &height); Important: A view that is backed by a CAEAGLLayer object should not implement a custom drawRect: method. Implementing a drawRect: method causes the system to change the default scale factor of the view so that it matches the scale factor of the screen. If your drawing code is not expecting this behavior, your app content will not be rendered correctly. If you do opt in to high-resolution drawing, you also need to adjust the model and texture assets of your app accordingly. For example, when running on iPad or on a high-resolution device, you might want to choose larger models and more detailed textures to take advantage of the increased number of pixels. Conversely, on a standard-resolution iPhone, you can continue to use smaller models and textures. An important factor when determining whether to support high-resolution content is performance. The quadrupling of pixels that occurs when you change the scale factor of your layer from 1.0 to 2.0 puts additional pressure on the fragment processor. If your app performs many per-fragment calculations, the increase in pixels may reduce your app’s frame rate. If you find your app runs significantly slower at the higher scale factor, consider one of the following options: ● Optimize your fragment shader’s performance using the performance-tuning guidelines found in OpenGL ES Programming Guide for iOS . ● Choose a simpler algorithm to implement in your fragment shader. By doing so, you are reducing the quality of each individual pixel to render the overall image at a higher resolution. ● Use a fractional scale factor between 1.0 and 2.0. A scale factor of 1.5 provides better quality than a scale factor of 1.0 but needs to fill fewer pixels than an image scaled to 2.0. ● OpenGL ES in iOS 4 and later offers multisampling as an option. Even though your app can use a smaller scale factor (even 1.0), implement multisampling anyway. An added advantage is that this technique also provides higher quality on devices that do not support high-resolution displays. Supporting High-Resolution Screens In Views Drawing High-Resolution Content Using OpenGL ES or GLKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 86The best solution depends on the needs of your OpenGL ES app; you should test more than one of these options and choose the approach that provides the best balance between performance and image quality. Supporting High-Resolution Screens In Views Drawing High-Resolution Content Using OpenGL ES or GLKit 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 87For both functional and aesthetic reasons, images are a pervasive element of app user interfaces. They can be a key differentiating factor for apps. Many images used by apps, including launch images and app icons, are stored asfilesin the app’s main bundle. You can have launch images and icons that are specific to device type (iPad versus iPhone and iPod touch) and that are optimized for high-resolution displays. You can find full descriptions of these bundled image files in “Advanced App Tricks” and “App-Related Resources” in iOS App Programming Guide . “Updating Your Image Resource Files” (page 83) discusses adjustments that make your image files compatible with high-resolution screens. In addition, iOS provides support for loading and displaying images using both the UIKit and Core Graphics frameworks. How you determine which classes and functionsto use to draw images depends on how you intend to use them. Whenever possible, though, it is recommended that you use the classes of UIKit for representing images in your code. Table C-1 lists some of the usage scenarios and the recommended options for handling them. Table C-1 Usage scenarios for images Scenario Recommended usage Use the UIImageView class to display the image. This option assumes that your view’s only content is an image. You can still layer other views on top of the image view to draw additional controls or content. Display an image as the content of a view Display an image as an Load and draw the image using the UIImage class. adornment for part of a view You can do this using the UIKit functions or Core Graphicsfunctions described in “Creating New Images Using Bitmap Graphics Contexts” (page 41). Save some bitmap data into an image object Create a UIImage object from the original image data. Call the UIImageJPEGRepresentationorUIImagePNGRepresentation function to get an NSData object, and use that object’s methods to save the data to a file. Save an image as a JPEG or PNG file 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 88 Loading ImagesSystem Support for Images The UIKit framework as well as the lower-level system frameworks of iOS give you a wide range of possibilities for creating, accessing, drawing, writing, and manipulating images. UIKit Image Classes and Functions The UIKit framework has three classes and one protocol that are related to images in some way: UIImage Objects of this class represent images in the UIKit framework. You can create them from several different sources, including files and Quartz image objects. Methods of the class enable you to draw images to the current graphics context using different blend modes and opacity values. The UIImage class automatically handles any required transformations for you, such as applying the proper scale factor (taking into consideration high-resolution displays) and, when given Quartz images, modifying the coordinate system of the image so that it matches the default coordinate system of UIKit (where the y origin is at the upper left). UIImageView Objects of this class are views that display either a single image or animate a series of images. If an image is to be the sole content of a view, use the UIImageView class instead of drawing the image. UIImagePickerController and UIImagePickerControllerDelegate This class and protocol give your app a way to obtain images (photos) and movies supplied by the user. The class presents and manages user interfaces for choosing and taking photos and movies. When users pick a photo, it deliversthe selected UIImage object to the delegate, which must implement the protocol methods. In addition to these classes, UIKit declares functions that you can call to perform a variety of tasks with images: ● Drawing into an image-backed graphics context. The UIGraphicsBeginImageContext function creates an offscreen bitmap graphics context. You can draw in this graphics context and then extract a UIImage object from it. (See “Drawing Images” (page 40) for additional information.) ● Getting or caching image data. Each UIImage object has a backing Core Graphics image object (CGImageRef) that you can access directly. You can then pass the Core Graphics object to the Image I/O framework to save the data. You can also convert the image data in a UIImage object to either a PNG or JPEG format by calling the UIImagePNGRepresentation or UIImageJPEGRepresentation functions. You can then access the bytes in the data object and you can write the image data to a file. ● Writing an image to the Photo Album on a device. Call the UIImageWriteToSavedPhotosAlbum function, passing in a UIImage object, to put that image in the Photo Album on a device. “Drawing Images” (page 40) identifies scenarios when you would use these UIKit classes and functions. Loading Images System Support for Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 89Other Image-Related Frameworks You can use several system frameworks other than UIKit to create, access, modify, and write images. If you find that you cannot accomplish a certain image-related task using a UIKit method or function, a function of one of these lower-level frameworks might be able do what you want. Some of these functions might require a Core Graphicsimage object (CGImageRef). You can accessthe CGImageRef object backing a UIImage object through the CGImage property. Note: If a UIKit method or function exists to accomplish a given image-related task, you should use it instead of any corresponding lower-level function. The Core Graphics framework of Quartz is the most important of the lower-level system frameworks. Several of its functions correspond to UIKit functions and methods; for example, some Core Graphics functions allow you to create and draw to bitmap graphics contexts, while others let you create images from various sources. However, Core Graphics offers more optionsfor handling images. With Core Graphics you can create and apply image masks, create images from portions of existing images, apply color spaces, and access a number of additional image attributes, including bytes per row, bits per pixel, and rendering intent. The Image I/O framework is closely related to Core Graphics. It allows an app to read and write most image file formats, including the standard web formats, high dynamic range images, and raw camera data. It features fast image encoding and decoding, image metadata, and image caching. Assets Library is a framework that allows an app to access assets managed by the Photos app. You can get an asset either by representation (for example, PNG or JPEG) or URL. From the representation or URL you can obtain a Core Graphics image object or the raw image data. The framework also lets you write images to the Saved Photos Album. Supported Image Formats Table C-2 lists the image formats supported directly by iOS. Of these formats, the PNG format is the one most recommended for use in your apps. Generally, the image formats that UIKit supports are the same formats supported by the Image I/O framework. Table C-2 Supported image formats Format Filename extensions Portable Network Graphic (PNG) .png Tagged Image File Format (TIFF) .tiff or .tif Joint Photographic Experts Group (JPEG) .jpeg or .jpg Loading Images System Support for Images 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 90Format Filename extensions Graphic Interchange Format (GIF) .gif Windows Bitmap Format (DIB) .bmp or .BMPf Windows Icon Format .ico Windows Cursor .cur XWindow bitmap .xbm Maintaining Image Quality Providing high-quality images for your user interface should be a priority in your design. Images provide a reasonably efficient way to display complicated graphics and should be used wherever they are appropriate. When creating images for your app, keep the following guidelines in mind: ● Use the PNG format for images. The PNG format provides lossless image content, meaning that saving image data to a PNG format and then reading it back results in the exact same pixel values. PNG also has an optimized storage format designed for faster reading of the image data. It isthe preferred image format for iOS. ● Create images so that they do not need resizing. If you plan to use an image at a particular size, be sure to create the corresponding image resource at that size. Do not create a larger image and scale it down to fit, because scaling requires additional CPU cycles and requires interpolation. If you need to present an image at variable sizes, include multiple versions of the image at different sizes and scale down from an image that is relatively close to the target size. ● Remove alpha channels from opaque PNG files. If every pixel of a PNG image is opaque, removing the alpha channel avoids the need to blend the layers containing that image. This simplifies compositing of the image considerably and improves drawing performance. Loading Images Maintaining Image Quality 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 91This table describes the changes to Drawing and Printing Guide for iOS . Date Notes Revised wording throughout, fixed a number of technical errors, and updated the printing chapter for iOS 6. 2012-09-19 2011-09-26 Made several minor changes. 2011-03-09 Made some minor changes. 2010-12-07 Added "Drawing to a Bitmap Graphics Context" to the Images chapter. First version of the document describing the concepts, APIs, and techniques for drawing and printing in iOS. 2010-11-15 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 92 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, Instruments, iPad, iPhone, iPod, iPod touch, Objective-C, OS X, Pages, Quartz, Spaces, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. AirPrint is a trademark of Apple Inc. Helvetica is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. OpenGL is a registered trademark of Silicon Graphics, Inc. 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. QuickTime 7.3 User’s Guide Includes instructions for using QuickTime Pro For Mac OS X version 10.3.9 or later, and WindowsK Apple Inc. © 2007 Apple 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. Your rights to the software are governed by the accompanying software license agreement. The Apple logo is a trademark of Apple 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 1 Infinite Loop Cupertino, CA 95014-2084 408-996-1010 www.apple.com Apple, the Apple logo, AppleScript, Final Cut Pro, FireWire, iMovie, iPod, iTunes, Mac, Mac OS, Macintosh, QuickDraw, and QuickTime are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, iPhone, and Tiger are trademarks of Apple Inc. Apple Store is a service mark of Apple Inc., registered in the U.S. and other countries. .Mac is a service mark of Apple Inc. Intel, Intel Core, and Xeon are trademarks of Intel Corp. in the U.S. and other countries. PowerPC™ is a trademark of International Business Machines Corporation, used under license therefrom. 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. Manufactured under license from Dolby Laboratories. “Dolby,” “Pro Logic,” and the double-D symbol are trademarks of Dolby Laboratories. Confidential UnPublished Works, © 1992–1997 Dolby Laboratories, Inc. All rights reserved. Simultaneously published in the United States and Canada. 019-1032/2007-09-01 3 3 Contents Preface 6 Welcome to QuickTime 6 What Is QuickTime? 6 What Is QuickTime Pro? 7 What’s New in QuickTime 7? 7 New in QuickTime Player 8 New in QuickTime Pro 9 System Requirements 9 Types of Files QuickTime Supports 10 Checking for New Versions of QuickTime 10 Using Onscreen Help 10 Where to Go for Additional Information Chapter 1 11 Using QuickTime Player 11 Opening and Playing Files 11 Opening and Playing Movies in QuickTime Player 12 Opening and Playing Files in a Web Browser 15 Viewing QuickTime Virtual Reality (QTVR) Movies 16 Viewing Still Images 16 Playing MIDI Files 17 Opening Recently Used Files 17 Finding Movies Quickly Using QuickTime Favorites 17 Playing Copy-Protected Movies 18 Viewing Information About a File 18 Controlling Playback 18 Adjusting Audio and Video Settings 18 Changing Playback Preferences 19 Viewing Movies at Full Screen 20 Changing Movie Size for Playback 20 Looping a Movie 20 Simultaneously Playing Multiple Movies 21 Using Frame Number and Time Codes 21 Navigating a Movie by Frame Number or Time Code 22 Finding Text in a Text Track4 Contents 22 Preventing Users from Changing QuickTime Settings 22 Viewing Movies that have Flash Content Chapter 2 23 Getting Started with QuickTime Pro 23 Getting QuickTime Pro 23 Using Advanced Playback Options 23 Playing a Movie on a Second Display 24 Presenting a Movie as a Slideshow 24 Changing the Color Around a Movie 25 Loading Movies into RAM for Better Playback 25 Creating Movies and Other Media 25 Recording Video and Audio 26 About Saving Movies 27 Saving Movies from the Internet 27 Creating a Slideshow or Animation from Still Images 28 Creating a Still Image from a Movie 28 Converting Files into QuickTime Movies 29 Sharing Movies by Email or the Web 29 Sharing Movies for Podcast Producer Chapter 3 30 Editing and Authoring with QuickTime Pro 30 Simple Editing 30 Selecting and Playing Part of a Movie 31 Cutting, Copying, or Deleting a Section of a Movie 31 Combining Two QuickTime Movies into One 32 Working with Tracks 32 Turning Tracks On or Off 32 Extracting, Adding, and Moving Tracks 33 Working with Audio Tracks 34 Presenting Multiple Movies in the Same Window 35 Pasting Graphics and Text into a Movie 35 Working with Text Tracks 37 Specifying Languages for Individual Tracks 38 Changing Movie Properties 38 Adding Annotations to a Movie 38 Resizing, Flipping, or Rotating a Movie 39 Changing a Movie’s Shape with a Video Mask 39 Changing a Track’s Transparency 39 Creating a Chapter List for a Movie 41 Setting a Movie’s Poster Frame 41 Saving a Movie with Specific Playback Settings 41 Changing the Movie Controller TypeContents 5 Chapter 4 42 Exporting Files with QuickTime Pro 42 About Video and Audio Compression 43 Exporting Files Using Presets 43 Customizing Export Settings 43 Customizing Video Export Settings 45 Adding Special Effects and Filters to a QuickTime Movie 45 Changing Image (Frame) Size 46 Customizing Sound Export Settings 46 Preparing Movies for Internet Delivery 47 Preparing a Movie for Fast Start 47 Preparing a Movie for Real-Time Streaming 48 Creating Reference Movies to Optimize Web Playback 48 Creating Movies Optimized for iPhone and Web Delivery 49 Exporting MPEG-4 Files 49 MPEG-4 Video Export Options 50 MPEG-4 Audio Export Options 51 MPEG-4 Streaming Export Options 51 Exporting 3G Files 52 3G File Format Export Options 52 3G Video Export Options 53 3G Audio Export Options 54 3G Text Options 54 3G Streaming Options 54 3G Advanced Options Appendix 55 Shortcuts and Tips 55 QuickTime Player Keyboard Shortcuts 56 QuickTime Pro Keyboard Shortcuts 57 Automating QuickTime Player with AppleScript 58 Automating QuickTime Player on Windows Glossary 59 Index 62Preface 6 Welcome to QuickTime Want to play movies from your hard disk or the Internet? QuickTime Player makes it easy. What Is QuickTime? QuickTime Player is a free multimedia player. You can use it to view many kinds of files, including video, audio, still images, graphics, and virtual reality (VR) movies. QuickTime supports the most popular formats on the Internet for news, sports, education, movie trailers, and other entertainment. QuickTime is also a multimedia architecture that other applications can leverage. Some of the most popular software—such as iTunes, iMovie, and Final Cut Pro from Apple, as well as many third-party programs—uses the QuickTime architecture for important multimedia functions. These applications require QuickTime to be installed in order to function properly. What Is QuickTime Pro? You can easily add a host of useful features to your QuickTime software by purchasing QuickTime Pro. With QuickTime Pro, you can:  Save files from the Internet  Edit audio and video  Record audio (Mac OS X and Windows) and video (Mac OS X only)  Add special effects  Create slideshows  Convert and save video, audio, and images to more than a hundred standard formats For information about how to start using QuickTime Pro, see “Getting QuickTime Pro” on page 23.Preface Welcome to QuickTime 7 What’s New in QuickTime 7? Both the free QuickTime Player and QuickTime Pro provide a host of new features. New in QuickTime Player  H.264 video support. This state-of-the-art, standards-based codec delivers exceptional-quality video at the lowest data rate possible, across data rates ranging from 3G to HD and beyond.  Live resize. Playback continues smoothly as you change the size of the QuickTime Player window. (Some hardware requirements may apply.)  Zero-configuration streaming. You no longer need to set your Internet connection speed in QuickTime Preferences. QuickTime automatically determines the best connection speed for your computer. If a connection is lost during streaming, QuickTime automatically reconnects to the server.  Surround sound. QuickTime Player can now play up to 24 channels of audio. With QuickTime 7, your Mac, and surround speakers, you can enjoy the full effect of your surround sound movie or game.  New and improved playback controls. Use the new A/V Controls window to adjust settings for the best viewing experience. Easily change settings including jog shuttle, playback speed, bass, treble, and balance.  All-new content guide. The all-new QuickTime Content Guide provides the latest in entertainment on the Internet.  Full-screen playback. Get the most out of your display by using every pixel possible. Thee new modes allow you fit the content to any size screen.  Floating controls. Full-screen mode now provides floating DVD-like controls for easy access to functions like pause, play, fast-forward, rewind, and full-screen options. Move your mouse and the full-screen controller appears on the screen for several seconds.  Additional keyboard shortcuts. QuickTime Player now supports the same transport control keyboard shortcuts as Final Cut Pro. While viewing a movie, press J, K, or L to rewind, pause, or resume playback at variable speeds.  Closed Captioning. An option in QuickTime Player Preferences allows you to display standard CEA-608 closed captions, when they’re available in your movies.  Timecode Display. QuickTime Player now allows you to switch between displaying movie time, timecode, and frame count. You can also jump to a specific timecode or frame number using the keyboard.  Spotlight-friendly media. With Mac OS X v10.4 or later, you can use Spotlight to easily find your QuickTime content. Spotlight can search for movie attributes such as artist, copyright, codec, and so on.  Screen reader compatibility. Using VoiceOver, included with Mac OS X v10.4 or later, visually impaired users can enjoy QuickTime Player features.8 Preface Welcome to QuickTime  Easy access to QuickTime Pro. When you use the free QuickTime Player, features available only in QuickTime Pro display “Pro” by their name. If you choose one of these items, you’ll see a definition of the feature and learn how to purchase QuickTime Pro. (To purchase QuickTime Pro, you must be connected to the Internet using the computer on which you want to install the software.) New in QuickTime Pro QuickTime 7 Pro users enjoy not only all the great features in QuickTime Player, but also the following new QuickTime Pro capabilities:  Create H.264 video. Use this codec for all your video encoding needs. Create content ranging in size from HD (high definition) to 3G (for mobile devices), and everything in between.  Create surround audio. Create a rich multimedia experience for your customers by adding multi-channel audio to your movie. If some of your customers don’t have surround speakers, don’t worry; QuickTime automatically mixes the audio to work with the speaker setup of each user.  Improved movie authoring. Editing tasks are much easier with new hot keys for in and out points. In addition, the Movie Properties interface has been completely redesigned to facilitate simple and efficient movie authoring.  New AAC constant-quality mode. Create AAC audio files optimized for constant quality rather than a constant bit rate for a consistently high-quality listening experience.  3G streaming. Create 3G files for RTSP streaming that are fully interoperable with other 3G streaming handsets and delivery architectures.  Conform to Aperture. View a movie’s aperture mode, and choose to have the movie conform to new aperture settings, including pixel shape.  Deinterlace source video. When exporting with the “Movie to QuickTime Movie” option, you can now deinterlace the video by setting an option in Export Size settings.  Export to Apple TV, iPod, and iPhone. New presets allow you to easily export your movies in formats optimized for use with Apple TV, iPod, and iPhone.  Export for Web. Automatically creates versions of a movie that are optimized for both web and iPhone delivery, a reference movie that automatically selects the appropriate version for playback, and an HTML snippet file that you can use to embed the movie on a web page.  Concurrent exports. Export multiple files simultaneously—and continue with your next playback or editing task. New for Mac OS X In addition to the capabilities above, QuickTime Pro for Mac OS X provides these capabilities:  Video recording. With a digital video camera connected to your Mac, you can quickly create video postcards to share with family and friends.Preface Welcome to QuickTime 9  Movie sharing. Easily create a movie file for sending via email or posting to a website.  Automator integration. With Mac OS X v10.4 Tiger or later, employ the easy-to-use interface of Automator for streamlining your QuickTime workflow. QuickTime 7 Pro users have exclusive access to a set of QuickTime-based Automator actions for easily automating such tasks as starting and stopping captures, hinting movies, enabling tracks, and more. With Automator and QuickTime 7 Pro, you can also create your own personal set of QuickTime-based Automator actions.  Podcast sharing. With Mac OS X v10.5 Leopard, you can easily send a movie file to Podcast Producer, on a computer with Mac OS X Server v10.5 Leopard, for automatic creation and delivery of podcasts. System Requirements For Mac OS computers:  A 400 MHz or faster G3 PowerPC–based or Intel-based Macintosh computer  At least 128 MB of RAM  Mac OS X version 10.3.9 or later For Windows computers:  A Pentium processor–based PC or compatible computer  At least 128 MB of RAM  Windows XP Service Pack 2 or Windows Vista Types of Files QuickTime Supports You can open (import) dozens of types of media with QuickTime. Some of the formats you can open in QuickTime include the following:  Video formats: MOV, MPEG-1, MPEG-2, 1 MPEG-4, 3GPP, 3GPP2, JPEG, DV, Motion JPEG, AVI, MQV, H.264  Audio formats: AIFF/AIFC, Audio CD, CAF, MOV, MP3, MPEG-4, AU, WAV, iTunes audio  Still-image formats: BMP, GIF, JPEG/JFIF, JPEG 2000, PDF, MacPaint, PICT, PNG, Photoshop (including layers), SGI, Targa, FlashPix (including layers), TIFF (including layers)  Animation formats: Animated GIF, FLC, Flash, PICS  Other formats: KAR (Karaoke), MIDI, QuickDraw GX, QuickTime Image File, QuickTime VR, Text 1. MPEG-2 playback is available via the QuickTime MPEG-2 Playback Component, sold separately at the Apple Store online. Because some file formats can contain many different kinds of audio and video, QuickTime may not be able to play all audio and video formats within a particular file format.10 Preface Welcome to QuickTime For a complete list of supported formats, see the Products area of the QuickTime website. To determine if QuickTime Player can open a file, choose File > Open File and select the file you want to open. You will be able to select only files that can be imported. Checking for New Versions of QuickTime From time to time, Apple releases new versions of QuickTime. If you’re connected to the Internet while using QuickTime Player, you’ll be notified when there’s a newer version of QuickTime available. It’s a good idea to have the latest version of the software installed on your computer. To check for a new version of QuickTime (if you are using Mac OS X), choose QuickTime Player > Update Existing Software. In Windows, choose Edit > Preferences > QuickTime Preferences, and then choose Update Check. Using Onscreen Help While QuickTime is open, you can see instructions for performing tasks by choosing Help > QuickTime Player Help. Where to Go for Additional Information Consult the resources listed below for more information about QuickTime:  Latest QuickTime content listings. QuickTime Player includes an up-to-the-minute guide to the best in QuickTime content. You can view the latest news, entertainment, educational features, and more. You can also listen to audio programs. To view the content guide, open QuickTime Player and choose Window > Show Content Guide. You can also visit www.apple.com/quicktime.  QuickTime News. For the latest news about QuickTime content and products, sign up for the QuickTime newsletter at applenews.lists.apple.com/subscribe.  Tutorials and tips. For step-by-step tutorials and a collection of instructional books and CDs, visit www.apple.com/quicktime/resources.  Discussion lists. Sign up with one of the many QuickTime-specific discussion lists to post messages, exchange ideas and information, and keep current with the latest QuickTime developments at www.apple.com/quicktime/resources.  Developer support. If you’re interested in developing products using QuickTime, go to developer.apple.com/quicktime.  Technical support. To view all the support resources available, visit www.apple.com/support.1 11 1 Using QuickTime Player This chapter explains the basics of using QuickTime Player. Opening and Playing Files You can open and play QuickTime movies in QuickTime Player or in your web browser. Opening and Playing Movies in QuickTime Player You can use QuickTime Player to play media stored on your computer’s hard disk, a CD, a DVD, or the Internet. To open a movie on your hard disk, a CD, or a DVD, do one of the following:  In the Finder (or Windows Explorer), double-click the file or drag it to the QuickTime Player application icon.  Choose File > Open and select the file.  Drag the file to the QuickTime Player icon in the Dock (Mac OS X only). To open a movie on the Internet, open QuickTime Player, choose File > Open URL, and enter the URL (the Internet address) for the movie file. When audio is detected, you’ll see activity in the equalizer. Playhead Volume Play/Pause Go to Fast-forward; go to end beginning; rewind Drag to resize the window.12 Chapter 1 Using QuickTime Player QuickTime Player has onscreen controls similar to those found on CD players and DVD players. Use the controls to play, pause, rewind, fast-forward, jump to the beginning or end, and adjust the volume of a QuickTime movie. You can also use the controls to move forward or backward in a movie. To go to a specific point in the movie, drag the playhead (the small black triangle) in the timeline. To step through frame-by-frame, first click the small black triangle and then press the Right or Left Arrow keys on your keyboard. Some movies have chapter lists you can use to jump to a specific point in a movie. If a movie has a chapter list, a pop-up menu appears between the timeline and the equalizer. You can drag the handle in the lower-right corner of the window to resize the viewing space. Opening and Playing Files in a Web Browser With the QuickTime plug-in (part of the free QuickTime software), you can play most multimedia you encounter on the Internet within your web browser. On some websites, movies play automatically. On other sites, you need to click an image of the movie or a play button. When a movie plays on a webpage, you typically see controls you can use to play, pause, fast-forward, rewind, and adjust the volume of the movie. To play a movie in a web browser, go to the website and follow the site’s instructions to watch the movie. Choose a chapter from the pop-up menu to jump to that chapter. Volume Play/Pause Rewind; fast-forward QuickTime Pro menu The playheadChapter 1 Using QuickTime Player 13 With QuickTime Pro, you also have the option of saving the movie to your hard disk (if the author of the movie allows it). To save a movie from the web, click the downwardpointing arrow on the right and choose “Save as QuickTime Movie” or “Save as Source” from the QuickTime Pro menu. If the movie is a Real-Time Streaming Protocol (RTSP) movie, it is saved as a small “reference movie” that points to the actual movie on the Internet. The QuickTime website has a number of QuickTime movies (including the latest movie trailers) that you can view in your web browser. Go to www.apple.com/quicktime. Adjusting Playback Preferences for Internet Movies When you watch movies on the Internet, they start playing automatically. You can, however, download entire movies to your hard disk before they start playing so that you can watch the movies at your convenience. To download movies before they start playing (in Mac OS X): 1 Choose QuickTime Player > QuickTime Preferences and click Browser. 2 Deselect “Play movies automatically.” To download movies before they start playing (in Windows): 1 Choose Edit > Preferences > QuickTime Preferences. 2 Choose Browser. 3 Deselect “Play movies automatically.” So that you don’t have to download movies and images each time you view them on a website, QuickTime can save these files in a storage area called a cache. If you view a movie or image more than once, having the item cached improves performance. To have QuickTime cache movies and images you view on the Internet, select “Save movies in disk cache.” You might not want to select this option if you don't have sufficient free space on your hard disk to allocate a cache, or if, for security reasons, you don't want movie data stored in a cache file. You can specify how big to make the cache by changing the Movie Cache Size setting. How big you make the cache depends on how much free space your hard disk has. A larger cache can hold more files (or larger files), but it takes up more space on your hard disk. After the QuickTime cache fills all the space reserved for it, older items are automatically deleted from the cache when new items are added. To clear the cache, click Empty Download Cache (in Windows, choose Download Cache in QuickTime Settings and then click Empty Cache Now). You might want to clear the cache for security or privacy reasons, or to recover free space on your hard disk.14 Chapter 1 Using QuickTime Player QuickTime automatically detects your Internet connection speed so that you get the highest-quality QuickTime content that your Internet connection can support. If movies you’re watching on the Internet don’t play properly, however, it may help to change the connection speed setting. To change the connection speed setting in Mac OS X, open QuickTime Preferences and click Streaming. In Windows, open QuickTime Preferences and choose Connection Speed. QuickTime tries to play versions of the movie authored to match the connection speed you choose. If you choose a speed slower than your actual connection speed, the resulting movie may be smaller in size and lower in quality than your connection can actually support. If you choose a speed faster than your actual connection, QuickTime playback may stutter or appear jerky because it is sending more data than your connection can support. If you’re unsure of your connection speed, check with your Internet service provider (ISP). If you change your connection speed setting and later want to make QuickTime automatically detect your speed again, choose Automatic from the Streaming Speed pop-up menu (in Mac OS X). To set the Internet connection speed in Windows, choose Edit > Preferences > QuickTime Preferences, and then follow the directions above. Instant-On QuickTime includes Instant-On, a technology that dramatically reduces buffer (wait) time when you view streamed video. Instant-On provides an instantaneous viewing experience; you can navigate quickly through video as if it were on your hard disk. To experience Instant-On, you must have a broadband connection. The responsiveness of Instant-On is affected by available bandwidth and the size, or data rate, of the content. It can also be affected by the codec used to compress the streaming video. Instant-On is on by default. If you experience problems with streamed video, you can change the wait time (drag the Play slider) or turn off Instant-On (open QuickTime Preferences and click Streaming). Viewing Streamed Files Behind a Firewall QuickTime streaming chooses the best protocol (a method of communicating via the Internet) for your needs. Typically, QuickTime streaming uses Real-Time Streaming Protocol (RTSP) to ensure the best performance. If your network connection is protected by a firewall, you may want to use the HTTP protocol instead.Chapter 1 Using QuickTime Player 15 To use HTTP streaming (in Mac OS X): 1 In QuickTime Player, choose QuickTime Player > QuickTime Preferences (or open System Preferences and click QuickTime). 2 Click Advanced. 3 Choose Custom from the Transport Setup pop-up menu. 4 Choose HTTP from the Transport Protocol pop-up menu. To use HTTP streaming (in Windows): 1 In QuickTime Player, choose Edit > Preferences > QuickTime Preferences. 2 Choose Advanced. 3 Choose Custom from the Transport Setup pop-up menu. 4 Choose HTTP from the Transport Protocol pop-up menu. If QuickTime can configure itself for your firewall, you can now watch streaming QuickTime movies. If you still experience problems, contact your network administrator or see the information on the Apple QuickTime website (www.apple.com/quicktime). Setting QuickTime to Handle More or Fewer File Types (MIME Settings) When files are downloaded over the Internet, each file is assigned a MIME type to indicate what kind of file it is. Your browser keeps track of which plug-in should be used to display each kind of file. QuickTime can display a wide variety of file types. To make QuickTime handle more or fewer file types, you can edit the MIME type settings. If you edit the list, you can return to the default list by following the instructions below and clicking Use Defaults. To edit MIME settings in Mac OS X, open QuickTime Preferences and click Advanced. In Windows, choose Edit > Preferences > QuickTime Preferences, choose Browser, and click MIME Settings. Viewing QuickTime Virtual Reality (QTVR) Movies QTVR movies display three-dimensional places (panoramas) and objects with which the user can interact. With a QTVR panorama, it’s as if you’re standing in the scene and you can look around you up to 360 degrees in any direction. In a QTVR movie of an object, you can rotate the object in any direction. To pan through a QTVR movie, drag the cursor through the scene. To zoom in or out, click the + or – button. (If the buttons are not showing, zoom in by pressing Shift; zoom out by pressing Control.)16 Chapter 1 Using QuickTime Player Some QTVR movies have hot spots that take you from one scene (or node) to another. As you move the mouse over a hot spot, the cursor changes to an arrow. To see all the places where you can jump from one node in a scene to another, click the Show Hot Spot button (an arrow with a question mark in it). A translucent blue outline of any hot spots within the currently visible VR scene appears. (If there are no hot spots, clicking this button has no effect.) Click a hot spot to jump to a new scene. To step backward scene by scene, click the Back button. (The Back button appears only on QTVR movie windows, not in all QuickTime movie windows.) Viewing Still Images You can view still images in QuickTime Player. Choose File > Open File and select the file, or drag the file to the QuickTime Player icon in the Dock (Mac OS X only). Mac OS X: You can use Preview to convert a still image to other formats (Preview is in the Applications folder on your hard disk). You can also convert many kinds of files using QuickTime Pro. For more information, see “Converting Files into QuickTime Movies” on page 28. Windows: If you have QuickTime Pro, you can use PictureViewer to import and export various types of still image file formats and to rotate images. PictureViewer is in the QuickTime folder on your hard disk. Playing MIDI Files QuickTime Player can import MIDI (Karaoke MIDI, Standard MIDI, and General MIDI) formats. To open a MIDI file, choose File > Open File and select the file. QuickTime uses its built-in synthesizer to play MIDI files. You can also set QuickTime to use an external synthesizer instead of the built-in one. To specify a different synthesizer (in Mac OS X): 1 Open System Preferences, click QuickTime, and then click Advanced. 2 Choose the synthesizer you want from the Default Synthesizer pop-up menu. To specify a different synthesizer (in Windows): 1 Choose Edit > Preferences > QuickTime Preferences. 2 Click Audio. 3 Select the synthesizer you want from the Default Music Synthesizer pop-up menu.Chapter 1 Using QuickTime Player 17 Opening Recently Used Files You can easily open recently used files. To open recently used files: m Choose File > Open Recent > [option] To change the number of items that appear in the Open Recent submenu (in Mac OS X), choose QuickTime Player > Preferences, click General, and choose an option from the Number of Recent Items pop-up menu. In Windows, choose Edit > Preferences > Player Preferences. Finding Movies Quickly Using QuickTime Favorites You can easily find and open movies by putting pointers to them in your QuickTime Favorites window. To view your list of favorites, choose Window > Favorites > Show Favorites. To add a movie to the Favorites list: 1 Open the movie in QuickTime Player. 2 Choose Window > Favorites > Add Movie As Favorite. You can also drag a file to the Favorites list window. To rearrange movies in the list, drag them. To delete an item from the list, drag the item to the Trash or select the item and press the Delete key. (In Windows, drag the item to the Recycle Bin or select the item and press the Backspace key.) Deleting an item from the Favorites list does not delete the file from your hard disk (or wherever the file is saved). Playing Copy-Protected Movies QuickTime movies can be encrypted so that only authorized viewers can watch them. Such movies are known as “secured media files.” To use such a file, you must enter a “media key,” which is usually available from the media file provider. To enter a media key (in Mac OS X): 1 Open System Preferences, click QuickTime, and click Advanced. 2 Click Media Keys. 3 Click the Add button and then enter the key provided by the author or vendor. To enter a media key (in Windows): 1 Choose Edit > Preferences > QuickTime Preferences. 2 Click Advanced. 3 Click Media Keys. 4 Click Add and then enter the key provided by the author or vendor.18 Chapter 1 Using QuickTime Player Viewing Information About a File QuickTime Player can display information about a QuickTime file, such as its compression format, size, and frame rate while playing. To view information about a file: 1 Open the file. 2 Choose Window > Show Movie Info. With QuickTime Pro, you can see additional information about a movie by choosing Window > Show Movie Properties. For more information about movie properties, see “Changing Movie Properties” on page 38. Controlling Playback You can change playback options such as balance, playback speed, the size at which a movie plays, and whether the QuickTime Player window shows. You can also optimize movies for playback on certain computers. Adjusting Audio and Video Settings For any QuickTime movie with an audio track, you can adjust the right/left balance, as well as the volume, bass, and treble levels. For any movie, you can also set playback options such as speed and playback rate (the jog shuttle). To set audio and video controls: 1 Choose Window > Show A/V Controls. 2 Drag a slider to adjust the setting. Other playback options (for playing several movies at once or for playing a movie while using another application, for example) are available in QuickTime Player Preferences. To open QuickTime Player Preferences (in Mac OS X), choose QuickTime Player > Preferences. In Windows, choose Edit > Preferences > Player Preferences. For more information, see “Changing Playback Preferences.” Changing Playback Preferences You can change playback preferences by choosing QuickTime Player > Preferences. The available options include:  Open movies in new players: Select to open movies in a new player window; deselect to replace the movie in the current player window with the new movie.  Automatically play movies when opened: Select to make all movies start playing when they’re opened; deselect to have the movie start when you click the Play button.  Use high-quality video settings when available: When this option is selected, video looks sharper and smoother, but more processor capacity is used.Chapter 1 Using QuickTime Player 19  Play sound in frontmost player only: Select to play the audio for only one QuickTime Player window (the active window); deselect to play the sound of all playing movies simultaneously.  Play sound when application is in background: Select to play audio even if QuickTime is not the frontmost application; deselect to mute the audio when QuickTime is not the active application.  Show equalizer: Select or deselect to show or hide the equalizer (which shows the presence of audio) in the QuickTime Player window.  Show Content Guide automatically: Select to see the latest content listings when QuickTime Player first opens (unless you open a specific movie file).  Pause movie before switching users: Select to automatically pause a movie when you use fast user switching to let another person use your computer.  Hide selection indicators for empty selection: Select to have the selection indicators in the timeline removed when no frames are selected.  Show closed captioning when available: Select to see the closed caption information, if captions have been provided by the movie’s creators. With QuickTime Pro, more options are available. For information about them, see “Getting QuickTime Pro” on page 23. Viewing Movies at Full Screen You can set the screen so that only the movie is visible, not the QuickTime Player window, desktop, or other windows. This presentation setting is called “full-screen mode.” (You can also set a movie to play at half size, double size, or other sizes.) To play a movie at full screen, do one of the following:  Choose View > Full Screen.  Choose View > Present Movie, choose Full Screen, and click Play. To quit full-screen mode, press Esc. To adjust the way the picture is sized to fit your screen, such as stretched to fit or in letterbox format, move the pointer to the top of the screen to display the QuickTime Player menu options, and then choose a setting from the View menu. The following additional options are available in full-screen mode:  Fit to Screen: The content is scaled to fill your screen as fully as possible without cropping the movie or changing the aspect ratio.  Zoom: The content is scaled and cropped to completely fill your screen in at least one dimension. This can eliminate black areas on the top (letterboxing) or side (pillarboxing) but may hide or distort the content.  Panoramic: The content is scaled to fit your screen and the outer horizontal edges compressed to avoid cropping the image. You can also cycle through all of the available full-screen options by clicking the button in the movie controls that appear when you move the pointer. 20 Chapter 1 Using QuickTime Player You can also set options for all movies playing at full screen. For example, you can hide the movie controls or change the amount of time they’re displayed before being hidden. To set these options in Mac OS X, choose QuickTime Player > Preferences and click Full Screen. To set these options in Windows, choose Edit > Preferences > Player Preferences, and then click Full Screen. Note: As long as “Display full-screen controls” is selected in QuickTime Player Preferences, you can make hidden controls appear by moving the pointer. Changing Movie Size for Playback QuickTime Player includes several options for changing movie playback size. To change a movie’s playback size, choose View > [a size], or drag the resize control in the lower-right corner of the window. To stretch the movie in any direction, hold down the Shift key when you drag (holding down the Shift key while dragging doesn’t preserve the aspect ratio). To return the movie to its default size and aspect ratio, press Command-1 (in Windows, press Alt-1). You can also view movies at full screen, with additional sizing options available during full-screen playback. For more information, see “Viewing Movies at Full Screen” on page 19. Looping a Movie You can play a movie repeatedly. When the movie finishes, it automatically starts playing again. To loop a movie: m Choose View > Loop. With QuickTime Pro, you can also play the movie forward and then backward repeatedly by choosing View > Loop Back and Forth. Simultaneously Playing Multiple Movies You can have more than one QuickTime Player window open at a time. To open more than one QuickTime Player window, do one of the following:  Double-click another movie file.  Choose View > Play All Movies. By default, when you have more than one QuickTime Player window open, the audio plays only on the active (frontmost) QuickTime Player window. For information about changing this setting, see “Changing Playback Preferences” on page 18.Chapter 1 Using QuickTime Player 21 Using Frame Number and Time Codes When you’re viewing a movie in QuickTime Player, you can display the current movie time or frame number, or the SMPTE time code if the movie has a time code track. (Some applications, such as Final Cut Pro, automatically add a time code during capture.) Displaying Frame Numbers, Movie Time, or Time Code The area next to the timeline in QuickTime Player displays the time information for the current movie. 1 Click the time display area. 2 Choose an option from the pop-up menu that appears:  Standard: Displays movie time in HH:MM:SS format.  Time Code: Displays the movie’s time code in HH:MM:SS:Frame format. Either the time code or drop-frame time code will be displayed, depending on the frames per second of the movie. A colon in the frame segment of the time notation indicates that a non-drop time code is being displayed. A semicolon indicates a drop-frame time code. If the movie has a time code track, it will be used. Otherwise, the time code will be calculated from 00:00:00:00 at the start of the movie.  Frame Number: Displays the frame number, incrementing from 0 at the start of the movie. An “f“ in the time display area indicates that the frame count is being displayed. Navigating a Movie by Frame Number or Time Code You can jump to a point in a movie by entering a specific frame number or time code.  Double-click the time display, and then press the arrow keys or type a new time or frame number.  To select the entire time display, double-click the area, or click the area and then press Command-A (in Mac OS X) or Control-A (in Windows). To enter a time, separate each unit with a period. For example, 5.02.10 will go to five minutes, two seconds, and 10 frames. To go to five minutes, zero seconds, and 10 frames you can enter 5..10.22 Chapter 1 Using QuickTime Player Finding Text in a Text Track Some movies contain text such as titles, credits, subtitles, or section headings. You can search for text in a movie so that, for example, you can find specific frames in the movie. To search for text in a QuickTime movie: 1 Choose Edit > Find > Find. If this command is unavailable, the movie does not have a text track. 2 In the Find dialog, type the text you are looking for and click Next. Preventing Users from Changing QuickTime Settings If you’re using a computer in a public setting (at a kiosk, for example), you can prevent users from changing QuickTime settings and saving movies from the Internet. To set up QuickTime for use on a public computer (in Mac OS X): 1 Open System Preferences, click QuickTime, and click Advanced. 2 Select “Enable kiosk mode.” To set up QuickTime for use on a public computer (in Windows): 1 Choose Edit > Preferences > QuickTime Preferences. 2 Choose Browser Plug-in. 3 Select “Enable kiosk mode.” Viewing Movies that have Flash Content Some QuickTime movies contain a Flash track . To enable these movies to play properly, you must turn on support for Flash within QuickTime. To enable Flash playback in QuickTime movies (in Mac OS X): 1 Open System Preferences, click QuickTime, and click Advanced. 2 Select “Enable Flash.” To enable Flash playback in QuickTime movies (in Windows): 1 Choose Edit > Preferences > QuickTime Preferences. 2 Choose Advanced. 3 Select “Enable Flash.”2 23 2 Getting Started with QuickTime Pro Learn how to use the advanced playback options in QuickTime Pro, create movie postcards, and share them via email or the web. Getting QuickTime Pro To get QuickTime Pro, choose a QuickTime Pro menu item and click Buy Now, or choose QuickTime Player > Buy QuickTime Pro. You must be connected to the Internet using the computer on which you want QuickTime Pro installed. You may need to restart QuickTime Player to make the new options available. Using Advanced Playback Options With QuickTime Pro, you have additional options for playing movies, such as playing a movie on a second display, and more. Playing a Movie on a Second Display With QuickTime Pro and a two-display setup with dual display support, you can play a movie on one display while working in another application on the other display. This arrangement is useful for presentations. Mac OS X: Make sure Mirror Displays is not selected. (Open System Preferences, click Displays, and click Arrangement. If you don’t see an Arrangement button, your computer does not support this feature.) Windows: Whether you can play a movie on a second display depends on your computer and monitor. Open the Display control panel, click Settings, and make sure that the second display is enabled. If it is not enabled, click it and make sure “Extend my Windows desktop onto this monitor” is selected.24 Chapter 2 Getting Started with QuickTime Pro To play a movie on a second display: 1 Open a movie in QuickTime Player. 2 Choose View > Present Movie. The two displays are shown side by side; one contains the menu bar. The letter “Q” appears on the display on which the movie will play. To play the movie on the other display, click it. 3 Choose an option from the pop-up menu. To play the movie without displaying the QuickTime Player controls, choose Full Screen. 4 Select Movie or Slideshow mode. In slideshow mode, you can advance frames by clicking the mouse or pressing the Right Arrow or Left Arrow key. 5 Click Play. You can open other applications while the movie is playing. To make another application active, press Command-Tab (in Windows, Alt-Tab). You can now use the mouse and keyboard in other applications while the movie continues to play. To stop the movie before it ends, press Command-Tab (in Windows, Alt-Tab) to make QuickTime Player active, and then click the mouse. All QuickTime movie playback keyboard shortcuts are available in full-screen mode. Presenting a Movie as a Slideshow In a slideshow, the viewer clicks to advance to the next frame. With QuickTime Pro, you can set a movie to play as a slideshow. To play a movie as a slideshow: 1 Choose View > Present Movie. 2 Click Slideshow, then click Play. 3 To advance the slideshow, click the mouse or press the Left or Right Arrow keys. Changing the Color Around a Movie By default, the onscreen area around the edge of a movie playing in full-screen mode is black, but you can change it to another color. To change a movie’s border color: 1 Choose View > Present Movie. 2 Click the color well to the right of the pop-up menu, then choose a color from the Colors window. If you have more than one display, you can have this color appear on all displays (not just the one playing the movie), by selecting “Display background color on all screens.”Chapter 2 Getting Started with QuickTime Pro 25 Loading Movies into RAM for Better Playback QuickTime has two memory (RAM) options you can use to improve playback performance. Preload puts the entire movie into memory before it is played; Cache keeps movie data in memory after it has played. This option is useful for small files you want to loop. With QuickTime Pro, you can adjust memory options for a QuickTime movie track. To adjust memory options for a track: 1 Choose Window > Show Movie Properties. 2 Select the track you want to adjust and click Other Settings. 3 To put the track into memory, select “Preload this track.” 4 To keep track data in memory, select Cache. Use these options only with tracks that contain very small amounts of data; too much data in memory may cause poor performance, system errors, or unpredictable results. Creating Movies and Other Media With QuickTime Pro, you can create movies in various ways. Recording Video and Audio With a video camera and a Macintosh computer you can use QuickTime Pro to record a movie. QuickTime Pro can capture video from most FireWire-equipped sources, including the Apple iSight, DV cameras, and some webcams. With a Macintosh or Windows computer, you can also record audio using a built-in or external microphone. To record audio or video with QuickTime Pro: 1 Connect the camera or microphone to the computer (unless you are using a built-in microphone). 2 In QuickTime Pro, choose File > New Movie Recording (or File > New Audio Recording). A preview window appears, which you can use to adjust settings such as camera position, lighting, and audio level before you start recording. 3 To start recording, click the Record button at the bottom of the window. 4 To stop recording, click the button again. The movie you just recorded appears in a QuickTime movie window. By default, the movie is saved on the desktop, but you can choose a different default location in the Recording pane of QuickTime Player Preferences. To see where the movie has been saved, Command-click the icon at the top of the window.26 Chapter 2 Getting Started with QuickTime Pro Setting Recording Options When you first use QuickTime Pro to record video or audio, settings are automatically chosen for you. If you want, you can change settings such as which recording device and format to use, and where recorded movies are stored. To change recording options: 1 Choose QuickTime Player > Preferences. 2 Click Recording (or Audio Recording in Windows). 3 Choose the desired options for your video source, microphone, and quality, and then choose a default location to store recorded files. About Saving Movies With QuickTime Pro, you can create and edit movies, and then save them. When you choose File > Save As, you can save the movie as one of the following:  A self-contained movie includes all the data (video, audio, and so on) you used to create the movie within a single file.  A reference movie contains pointers to other movies (or parts of movies) stored elsewhere, such as in different folders on your hard disk or even on a web server. Pointers to other movies are created when, for example, you copy and paste part of a movie from one movie into another. If you are concerned about free space on your hard disk and can be sure your source movies won’t change location, you can save your movie as a reference movie; the media you copy and paste is stored as a space-saving pointer to that media, rather than being stored entirely inside your new movie file. When you play a reference movie, QuickTime follows the pointers to access and play the other movies (or parts of movies). To determine whether a movie contains pointers to other data, choose Window > Show Movie Properties, select the movie at the top of the window, and click Resources. If the file containing the movie does not appear in the list, then the movie has pointers and is not self-contained. In Mac OS X, you can Command-click the icon to see the name and location of the file that contains the movie. The term “reference movie” is also used for the files you can create to intelligently deliver different-sized streams to different users depending on their connection speeds. For more information, see “Creating Reference Movies to Optimize Web Playback” on page 48.Chapter 2 Getting Started with QuickTime Pro 27 Saving Movies from the Internet With QuickTime Pro, you can save (download) a movie viewed in your web browser to your hard disk. (The movie must be authored to allow for saving.) If it’s a streaming movie, QuickTime Pro saves a small “reference movie” that points to the stream. To save an Internet movie on your hard disk: 1 When the movie finishes loading (when the entire progress bar is filled with gray), click the down arrow in the playback controls. 2 Choose “Save as QuickTime Movie.” If this command is not available, the movie is authored so that it cannot be saved. Creating a Slideshow or Animation from Still Images With QuickTime Pro, you can combine a series of still images to create a movie that plays like a slideshow. This process is an easy way to share the pictures from your digital camera or mobile phone. Note: Slideshows look best when all the images are the same size. To create a slideshow from still images: 1 Put all the graphic files you want to include in a folder. 2 Name each file with the same name followed by an increasing number; for example, “picture1,” “picture2.” Most digital cameras number files automatically. The numbers must be increasing but don’t have to be precisely sequential (for example, you could name the files “picture1,” “picture5,” “picture10,” and so on). 3 In QuickTime Player, choose File > Open Image Sequence, and then select the first file. 4 Choose a frame rate (the number of frames displayed per second) from the Frame Rate pop-up menu. Slideshows usually work best when slides are shown at 2 to 3 seconds per frame. QuickTime Pro creates the movie, which shows each picture in sequence. 5 Choose File > Save to name and save the movie.28 Chapter 2 Getting Started with QuickTime Pro You can add music to your slideshow by adding an audio track to your movie before saving it. Open an audio file, select the portion you want to add to the slideshow, and choose Edit > Copy. Select the slideshow (or a portion of it) and choose Edit > Select All, then choose Edit > “Add to Selection and Scale.” The audio is sped up or slowed down to fit the length of the paste destination (the pitch remains the same). For best results, make the slideshow length match that of the audio as closely as possible. You can also lengthen a soundtrack by adding multiple audio files to the movie, each beginning at a different point. Alternatively, you can keep the original audio speed and alter the image speed by opening a new player window, copying and pasting the audio into the new window, and then copying the slideshow and pasting it into the new window by choosing Edit > “Add to Selection and Scale.” If you’re using Mac OS X: You can also use the recording feature in QuickTime Pro to narrate your slideshow. See “Recording Video and Audio” on page 25. Creating a Still Image from a Movie With QuickTime Pro, you can export a single frame from a movie as an image file. To save a still image from a movie: 1 Move the playhead to the frame you want to export. 2 Choose File > Export. 3 Choose “Movie to Picture” from the Export pop-up menu. 4 Click Options and choose a format from the “Compression type” pop-up menu. To export every frame from the movie as a series of images, choose “Movie to Image Sequence.” Exporting every frame can generate a very large number of files; you may want to export to a folder rather than to the desktop. Converting Files into QuickTime Movies If you have QuickTime Pro, you can use QuickTime Player to convert many types of video, audio, graphics, and animation files (including Flash files) into QuickTime movies. To convert a file into a QuickTime movie, open it in QuickTime Player and then choose File > Save.Chapter 2 Getting Started with QuickTime Pro 29 Sharing Movies by Email or the Web With QuickTime Pro and Mac OS X it’s easy to create movies that are just right for sharing with others by email or on your .Mac HomePage. Simply select how you want to share your movie, and QuickTime Pro automatically creates a file suitable for that delivery method. (To use the Share feature to put your movie on the web, you need a .Mac account.) To share a movie: 1 Choose File > Share. 2 Click Email or HomePage. 3 Choose a name and size for the movie. 4 If you are going to publish your movie on the web, you can type a name for the movie (the name you type will appear on the webpage). 5 Click Share. While the movie is being exported, you can click the “x” to cancel the export if necessary. If you click Email, a new message window opens in Mail, with your movie attached. If you click HomePage, your browser opens to the specified webpage, with the movie embedded. Send the URL to friends so that they can view the movie. Sharing Movies for Podcast Producer With QuickTime Pro and Mac OS X, you can create a movie for use with Podcast Producer, an application included with Mac OS X Server v10.5 Leopard. Note: This option is available only if you have the Podcast Capture application installed on your computer. To share a movie to Podcast Producer: 1 Choose File > Share. 2 Click Podcast Producer. 3 Enter your user name, password, and server name, then click Login. 4 Choose a Podcast Producer workflow from the pop-up menu. See the Podcast Producer Administration Guide, or your network administrator, for information about these settings. 5 Click Share.3 30 3 Editing and Authoring with QuickTime Pro Learn how to use QuickTime Pro to edit movies, manipulate movie tracks, and much more. Simple Editing With QuickTime Pro, you can perform movie-editing tasks. Selecting and Playing Part of a Movie To perform editing functions such as Copy and Delete, in most cases you need to first select the desired portion of a movie. (If you don’t select anything, the edit commands work on the current frame.) To select a portion of a movie, move the In and Out selection markers. The darkened area between the two markers indicates the selected portion. To fine-tune the selection, select a marker and move it with the arrow keys. You can also move the playhead and press I (for In) or O (for Out) to set the start or end point of the selection, even while the movie is playing. To play the selection, choose View > Play Selection Only (so that the checkmark appears), then click Play. To play the whole movie, choose View > Play Selection again (to remove the checkmark). With QuickTime Pro, you can save the movie (choose File > Save) so that the next time it is opened, only the part you selected plays. Tip: To move the In or Out marker to a different position, drag the playhead to the desired position (or use the arrow keys), then press I or O. In and Out markers, showing the selected portion of the movie The playheadChapter 3 Editing and Authoring with QuickTime Pro 31 Note: By default, the selection markers hide when nothing is selected, making it easy to determine whether or not a frame is selected. To turn off this option so that the selection markers appear even when nothing is selected, change the “Hide selection indicators for empty selection” option in QuickTime Player preferences. Cutting, Copying, or Deleting a Section of a Movie Selecting and moving, copying, or deleting (trimming) part of a movie is easy in QuickTime Pro. To cut, copy, or delete part of a movie: 1 Move the playhead until the desired frame appears, or select the part of the movie you want to modify (use the In and Out selection markers and the arrow keys). 2 Choose Edit > Copy, Cut, or Delete. If you choose Copy or Cut, you can paste the selection elsewhere. 3 Position the playhead where you want to paste the selection and choose Edit > Paste. QuickTime Pro inserts the selection you pasted at the position of the playhead. You can also delete all parts of a movie that are not selected by choosing Edit > “Trim to Selection.” Note: After you delete parts of a movie, the file size stays the same until you choose File > Save As and select “Save as a self-contained movie.” Combining Two QuickTime Movies into One With QuickTime Pro, you can easily add one movie to another to make one longer movie. To combine two movies: 1 In QuickTime Player, choose Edit > Select All to select the entire contents of the first movie. 2 Choose Edit > Copy, then open the second movie. 3 Move the playhead to the point at which you want to insert the movie (usually the very beginning or end of the original movie), and choose Edit > Paste. 4 Choose File > Save As to name and save the new movie.32 Chapter 3 Editing and Authoring with QuickTime Pro Working with Tracks A QuickTime movie is made up of one or more “tracks.” Each track stores a particular kind of data. For example, a QuickTime movie could have a video track, music tracks, and sound effects tracks. With QuickTime Pro, you can edit tracks individually. You can move tracks from one movie to another, turn a track on or off, delete tracks, or modify the information contained in a track. Turning Tracks On or Off With QuickTime Pro, you can choose one or more tracks to enable or disable. For example, you might want to turn off tracks to simplify editing, or to hide a track in a final movie. When you export a movie, only enabled tracks are exported. To turn movie tracks on or off: 1 In QuickTime Player, choose Window > Show Movie Properties. The movie’s tracks appear in the list at the top of the Properties window. 2 Use the Enable checkboxes to turn tracks on (selected) or off (deselected). To delete a track, drag it to the Trash, or select it and click Delete,.You can also choose Edit > Cut, or press the Delete key. Note: For audio tracks, other options are available by clicking Audio Settings. To play only the audio in the selected track, select Solo. To play the movie without audio, select Mute. Extracting, Adding, and Moving Tracks With QuickTime Pro, you can create a new movie from one or more tracks of an existing movie, while leaving the original movie file intact. For example, you could create a movie that uses only the audio from an existing movie. To do so, you extract the desired tracks. You can also add the extracted track to an existing movie. Audio narration Video 1 Video 2 Text title Text credits Audio sound effectsChapter 3 Editing and Authoring with QuickTime Pro 33 To extract a track (and add it to another movie): 1 Choose Window > Show Movie Properties. 2 Select the desired track or tracks and click Extract. You can select more than one track by holding down the Shift key when you click. QuickTime creates a new movie containing the extracted tracks. 3 To add the extracted track to another movie, select the movie (or the portion of it you want your pasted media to fit into) and choose Edit > “Add to Movie.” When you add a track to a movie, the track’s duration is unaltered. For example, if you add a 10-second sound track to a 1-minute movie, the sound track plays for 10 seconds, starting at the position in the movie where you added the track. To “scale” a track so that it stretches or compresses to a particular length, drag the In and Out markers of the target movie to select the duration you want the new track to cover and then choose Edit > “Add to Selection and Scale” in step 3. Scaling audio may change the speed of the audio (although the pitch remains the same when you play the movie in QuickTime Player). You could add video to sound instead, and speed up or slow down the video to match the audio. You might have better results if you compare the timelines of the two tracks and cut from one or the other until they have the same duration. Working with Audio Tracks QuickTime audio includes music tracks, which contain MIDI or other data, and sound tracks, which contain digitized audio. Adding an Audio Track to a QuickTime Movie You can easily add audio and other tracks to a QuickTime movie. To add an audio track to a movie: 1 In QuickTime Player, choose File > Open File and select the audio file you want to import. 2 In the QuickTime Player window that opens, choose Edit > Select All to select the entire audio file, then choose Edit > Copy. 3 Open the movie to which you want to add the audio. 4 To add the audio to the whole movie, choose Edit > Add. To add the audio to a part of the movie, select a part and choose Edit > “Add to Selection and Scale”. “Add to Selection and Scale” slows down or speeds up the audio track to fit the length of the selected part of the movie; the pitch remains the same (when you play the movie in QuickTime Player). You could add video to sound instead, and speed up or slow down the video to match the audio. You might have better results if you compare the timelines of the two tracks and cut from one or the other until they have the same duration.34 Chapter 3 Editing and Authoring with QuickTime Pro Note: If your audio and video are created by the same device, such as a DV camera, and are created at the same time, the audio and video will be synchronized. Changing Sound Track Volume Levels and Other Audio Settings With QuickTime Pro, you can change the volume and balance of audio and music tracks. For example, if a movie has more than one audio track, you can adjust the volume of the tracks relative to one another. You can also change the bass and treble levels. To change settings for an audio track: 1 In QuickTime Player, choose Window > Show Movie Properties. 2 In the Properties window, select the audio track and click Audio Settings. 3 Drag the sliders to adjust the settings. 4 Use the pop-up menu to the right of each audio channel to specify where the channel’s sound should be directed. To direct a channel's sound to the subwoofer, choose LFE Screen. To specify a particular output for the audio device, choose one of the Discrete options. To silence a channel, choose Unused. 5 To turn off the audio (without having to delete the track), select Mute. To play only the selected audio track, select Solo. 6 To save the balance and channel settings with your movie, choose File > Save or Save As. Presenting Multiple Movies in the Same Window With QuickTime Pro, you can place multiple video tracks in the same window to play movies side by side or to create a picture-in-picture effect. To present multiple movies in the same window: 1 In QuickTime Player, choose Edit > Select All to select the entire contents of the first movie. 2 Choose Edit > Copy, then open the second movie. 3 Move the playhead to the point at which you want the first movie to begin playing (usually the beginning or end of the original movie), and choose Edit > “Add to Movie.” 4 Choose Window > Show Movie Properties, select the new video track, and click Visual Settings. 5 Use the Current Size and Layer controls to set the new video to a desired size and layer (layers with lower numbers are farther forward, or more “on top”). For example, for a picture-within-a-picture effect, with the added movie inside the original movie, make the new movie smaller and assign it a lower layer number.Chapter 3 Editing and Authoring with QuickTime Pro 35 Pasting Graphics and Text into a Movie With QuickTime Pro, you can paste graphics and text into a QuickTime movie. If a pasted graphic is larger than the movie’s dimensions, QuickTime Pro resizes the movie to fit the dimensions of the graphic. For best results, size graphics (using a graphics program) to match the movie size before you insert them. You can export a single frame from the movie to use as a guide for text placement. (See “Creating a Still Image from a Movie” on page 28.) To find a movie’s dimensions, choose Window > Show Movie Properties, select the video track, and click Visual Settings. To add graphics or text: 1 Copy the text or graphic to the Clipboard. 2 In QuickTime Player, move the playhead to the point at which you want the copied item to appear. 3 Choose Edit > Paste. This procedure inserts the graphic into the movie at the Paste location, in its own frame. To paste the graphic onto the frame at the Paste location, choose Edit >”Add to Movie.” To make a graphic show up in more than one frame, select the portion of the movie you want to add it to and choose Edit > “Add to Selection and Scale.” You can use this technique to add a company logo throughout a movie. (Also see “Changing a Track’s Transparency” on page 39.) Working with Text Tracks You can add text to a QuickTime movie to create titles, credits, and subtitles. With QuickTime Pro, text tracks are searchable, so you can use keywords to find precise frames in the movie. The following topics provide details about adding text tracks. Adding a Text Track to a QuickTime Movie With QuickTime Pro, you can import a text file into a QuickTime movie. To add a text track: 1 Create a text file containing the text you want in the movie, and save the file as text only (.txt). Separate each paragraph with a return character. Each paragraph appears in a separate frame of the movie. By default, each text frame is displayed for 2 seconds. 2 In QuickTime Player, choose File > Open File and select the text file. 3 Click Open.36 Chapter 3 Editing and Authoring with QuickTime Pro Overlaying a Movie with Text With QuickTime Pro, you can use QuickTime Player to overlay (superimpose) text on a specific part of an existing movie. To overlay text: 1 In QuickTime Player, choose File > Open File and then select the text file. 2 Choose Edit > Select All and then choose Edit > Copy. (In Windows, click Options, select the Keyed Text checkbox, and copy the track). 3 Select the part of the movie on which you want to overlay the text. 4 Choose Edit > “Add to Selection and Scale.” 5 Save as a self-contained movie. The text appears throughout the part of the movie you selected. For information about adjusting how long each line of text displays, see “Setting the Frame Duration of a Text Track” on page 36. Specifying Font Styles for Text Tracks With QuickTime Pro you can change the font attributes of a text track already in a movie. To do so, you export the track, make changes, then reimport the track. To change font styles for the text track: 1 In QuickTime Player, choose File > Export. 2 Choose “Text to Text” from the Export pop-up menu. 3 Click Options and select “Show Text, Descriptors, and Time.” 4 Use a text editor to alter the values after the {QTtext} tag. 5 Import the text track back into your movie. In Windows, click Convert. To import the text with the default settings, click Save. To select different settings (such as font attributes), click Options. You can also insert tags throughout the text to change values while the movie plays. Setting the Frame Duration of a Text Track With QuickTime Pro, you can set the duration of each frame in an existing text track to a value other than 2 seconds. To do so, you export the track, make changes, then reimport the track. To change the current text frame information: 1 In QuickTime Player, choose File > Export and choose “Text to Text” from the Export pop-up menu. 2 Click Options and select “Show Text, Descriptors, and Time.” 3 Edit the information in the text file and then import the track back into the movie. Chapter 3 Editing and Authoring with QuickTime Pro 37 The duration for each line of text in the text file appears on a separate line before the line of text. The time you type is the length of time after the movie has started at which this line of text will appear. Timestamps are specified as hours:minutes:seconds:fractions of a second (the default Text to Text export setting is 1/600th of a second). For example, if you enter the time 00:02:11:00, the text on the following line appears at 2 minutes and 11 seconds into the movie. For information about the other text track descriptors, see the developer section of the QuickTime website at www.apple.com/quicktime. Specifying Languages for Individual Tracks With QuickTime Pro, you can create a movie with support for multiple languages by specifying a language for an individual track. For example, you can create a movie that contains a separate audio track for each language. QuickTime automatically plays the correct track, based on the language setting of the user’s computer. To specify languages: 1 Create or assemble the alternate tracks. Record voiceovers in each desired language or create text tracks to use as subtitles. Save each alternate track as a self-contained movie, and put all the alternates together in a single folder. 2 Put a copy of your original movie, self-contained and minus any tracks that are now stored as alternates, in the folder with the alternates. 3 Open the movie and choose Window > Show Movie Properties. 4 In the Properties window, select a sound or text track and click Other Settings. 5 Choose the language of this track from the Language pop-up menu. 6 Choose a track to use when a different language is selected from the Alternate pop-up menu. 7 Save as a self-contained movie (choose Edit > Save As and make sure “Make movie selfcontained” is selected). 8 Repeat these steps for additional language tracks; each time, choose the previously selected language from the Alternate pop-up menu.38 Chapter 3 Editing and Authoring with QuickTime Pro Changing Movie Properties The following sections describe how to resize or rotate a movie, set a movie’s poster frame, and more. Adding Annotations to a Movie With QuickTime Pro, you can add annotations to document information about the movie, such as its author, director, and copyright information. You can annotate the entire movie and any of its individual tracks. To annotate a movie: 1 In QuickTime Player, choose Window > Show Movie Properties. 2 Select an item from the list and click Annotations. 3 Choose an annotation to add from the Add Annotation pop-up menu. 4 Enter the annotation in the Value column of the list. Users who don’t have QuickTime Pro see only three of the annotations the movie contains. (Which three appear depends on which annotations the movie contains.) Resizing, Flipping, or Rotating a Movie With QuickTime Pro, you can change the size and orientation of a video track of a movie. To resize or rotate a QuickTime movie: 1 In QuickTime Player, choose Window > Show Movie Properties. 2 In the Properties window, select a video track and click Visual Settings. 3 To resize the movie, type new numbers in the Current Size fields. To keep the same height-to-width proportions, select Preserve Aspect Ratio. 4 To rotate the movie, click one of the rotate buttons. To restore the movie to its original appearance, click Reset. Flip horizontal or vertical Rotate right or leftChapter 3 Editing and Authoring with QuickTime Pro 39 Changing a Movie’s Shape with a Video Mask With QuickTime Pro, you can change the shape of a movie from rectangular to other shapes using a video mask. In combination with a media skin; you can “skin” a movie so that it plays in a non-rectangular region (for example, a movie could play from within a ship porthole), and then use a mask to restrict the movie’s shape to the desired playback region. Use a graphics program to create the mask and save it as a QuickTime-compatible file (for example, BMP, GIF, JPEG, or PICT). The mask should be a black shape on a white background. The movie appears through the black shape. To add a video mask: 1 In QuickTime Player, choose Window > Show Movie Properties. 2 Select the video track you want to assign the mask to, then click Visual Settings. 3 Drag the mask file to the Mask well in the Properties window, or click Choose to select the file. Changing a Track’s Transparency With QuickTime Pro, you can create a track that is partly transparent. This technique is useful, for example, for overlaying a movie with a logo. To change a track’s transparency: 1 Add the track to the movie. (See “Extracting, Adding, and Moving Tracks” on page 32.) 2 Choose Window > Show Movie Properties. 3 Select the track and click Visual Settings. 4 Choose Blend from the Transparency pop-up menu and drag the Transparency Level slider. Creating a Chapter List for a Movie With QuickTime Pro, you can create a pop-up chapter list to navigate to specific points in a movie. First you create a list of topics (or entry points), and then you import the list into the movie as a text track. When you play the movie in QuickTime Player, the current chapter displays in the movie controller. (See “Opening and Playing Movies in QuickTime Player” on page 11.) To create a chapter list: 1 In a text editor or word processor, type your list of chapters and save the document as plain text. Make each item very short (preferably one word but no more than two or three words) and separate each item with a return character. 2 In QuickTime Player, choose File > Open File, select the text file, and click Open. 40 Chapter 3 Editing and Authoring with QuickTime Pro 3 Choose File > Export. In the Export pop-up menu, choose “Text to Text.” In the Use pop-up menu, choose “Text with Descriptors.” 4 Click Options. In the Text Export Settings dialog, select “Show Text, Descriptors, and Time”; select “Show time relative to start of Movie”; and set fractions of seconds to 1/30 (the default is 1/1000). 5 Click OK, then click Save to create a text file with descriptors. 6 Open the exported list in your text editor or word processor, and open the target movie in QuickTime Player. 7 Choose Window > Show Movie Info. 8 In QuickTime Player, drag the playhead on the timeline to find the first point in the movie where you want to begin a new chapter. Use the Right and Left Arrow keys to step forward or backward a frame at a time as needed. Note the current time in the Properties window. 9 In the text file, find the first chapter title and change the timestamp just before that chapter title to the time you noted in the Properties window. The timestamp might now read, for example, [00:01:30.15], meaning that selecting the first chapter title will jump the viewer 1 minute, 30 seconds, and 15 frames into the movie. 10 Repeat steps 9 through 11 until you’ve identified all the places in the movie that correspond to the chapter divisions and you’ve entered the proper timestamps in the text file. 11 Change the last timestamp (the one after the last chapter title in the text file) to match the duration of the movie. 12 Save the text file and import it into QuickTime Player. QuickTime creates a new movie with just a text track. 13 Choose Edit > Select All, choose Edit > Copy, and close the movie. 14 Click in the main movie, choose Edit > Select All, and then choose Edit > “Add to Movie.” QuickTime adds the text track to the movie. 15 Choose Window > Show Movie Properties. 16 In the Properties window, select the video or audio track you want to associate with the chapter track, and click Other Settings. 17 Choose the main video or audio track from the Chapters pop-up menu. If you have a movie with alternate subtitle or sound tracks, you can create multiple chapter lists in different languages and set the appropriate subtitle or sound track as the owner of each chapter list. The chapter list will change to match the selected language. Chapter 3 Editing and Authoring with QuickTime Pro 41 18 Select the text track, then select “Preload this track” (to make the chapter track load first). 19 Deselect the new text track so that it doesn’t display on top of the video. The new track will still function as a chapter track. 20 Save the movie as a self-contained movie. You can now choose a chapter title from the pop-up menu to the right of the timeline. Setting a Movie’s Poster Frame A poster frame is a still image of a movie that represents the movie in places like the QuickTime Player Favorites window and the Finder. The default poster frame is the first frame in the movie. With QuickTime Pro, you can change the poster frame. To change a movie’s poster frame: 1 In QuickTime Player, drag the playhead (or use the arrow keys to move the playhead) to the desired frame. 2 Choose View > Set Poster Frame. To view a movie’s poster frame, choose View > “Go to Poster Frame.” Saving a Movie with Specific Playback Settings With QuickTime Pro, you can specify how a movie should open and play, what happens when the movie finishes, and the method QuickTime uses to resize the video. To specify playback options: 1 Choose Window > Show Movie Properties. 2 Select the movie name, and then click Presentation. 3 Select the desired options. 4 Save the movie. Changing the Movie Controller Type With QuickTime Pro, you can specify the kind of playback controls available on the QuickTime Player window. For a QTVR movie, for example, you can save the movie with one of the QTVR movie controllers. To specify a movie controller type: 1 Choose Window > Show Movie Properties. 2 Select Movie and click Presentation. 3 Choose an option from the Movie Controller Type pop-up menu. 4 Save the movie.4 42 4 Exporting Files with QuickTime Pro If you want more control over how QuickTime creates a file, use the Export feature of QuickTime Pro. With QuickTime Pro, you can export a movie to a number of different file formats, such as QuickTime movie (MOV), MPEG-4, 3GPP, 3GPP2, AVI, and DV. In addition, you can export an audio track to several different audio formats, export the individual frames of a movie as separate image files, or export a text track to a text file. To see the list of file formats available for a movie open in QuickTime Player, choose File > Export and browse the list of file format choices in the Export pop-up menu. About Video and Audio Compression Because uncompressed video and audio require a lot of disk space to store and a lot of bandwidth (the rate at which data can be transferred) to deliver, you’ll want to compress (encode) your movie before sending it to another computer or on the web. Movies are usually compressed (encoded) as part of the export process.Chapter 4 Exporting Files with QuickTime Pro 43 Exporting Files Using Presets QuickTime Pro offers a myriad of settings and options for compressing video and audio during export. To help simplify the process of compressing and exporting, QuickTime Pro also offers export presets. Different presets are available for each file format. To export a movie using presets: 1 In QuickTime Player, open the movie you wish to export. 2 Choose File > Export. 3 Choose a file format from the Export pop-up menu. 4 Choose the preset that best meets your needs from the Use pop-up menu. For example, to export a movie for use with a video-capable iPod, choose “Movie to iPod.” To export a movie that is optimized for Apple TV, choose “Movie to Apple TV.” You can also create movies for iPhone by choosing one of the “Movie to iPhone” options. 5 Choose a filename and location, and click Save. Note: To use the same settings you used during the last export, choose Most Recent Settings from the Use pop-up menu. Customizing Export Settings For the greatest possible control when compressing and exporting media files, use the export options available in QuickTime Pro. For video compression and export, QuickTime Pro offers customizable settings in three categories: video settings, filters (also known as special effects), and image size. QuickTime Pro also offers many options for customizing compression settings for sound. The following topics provide information about which options to choose when exporting and compressing movies. Customizing Video Export Settings To customize video settings for export: 1 Choose File > Export. 2 Choose a file format from the Export pop-up menu. For the options discussed below, choose “Movie to QuickTime Movie.” 3 Click Options.44 Chapter 4 Exporting Files with QuickTime Pro 4 In the Video area of the Movie Settings dialog, click Settings, and then choose your settings.  Compression type: Choose the video compressor (codec) you want to use to compress your video. For the highest quality at the lowest data rate (or the smallest file), H.264 is recommended.  Data rate (bit rate): In general, the higher the data rate, the better the quality, but the bigger the file. In most cases, you’ll want to set a data rate based on the way your movie will be viewed. For example, for streaming to Internet dialup connections, limit the data rate to around 45 kilobits per second to leave room for network traffic. If the file will be downloaded for playback, the data rate can be higher (a 56K modem user, however, has longer to wait before playback begins). The data rate of a movie is also affected by other compression options you set, such as the frame rate. To let the compressor choose an appropriate data rate, select Automatic.  Optimized for: Choose your intended delivery method from the “Optimized for” pop-up menu. This setting informs the codec how much the data rate can vary above and below the data rate you choose. This option is available only for compressors that can apply limits, such as H.264.  Key frame options: Many compressors use “frame differencing” to compress moving images. Frame differencing is the process of determining what information has changed from a starting frame (called a key frame) to subsequent frames. The key frame contains all of the information for an image. Subsequent frames contain only the information that has changed. Depending on the compressor you use, you can specify how often you want key frames to occur. If you don’t have enough key frames, the quality of your movie might be lower because most frames are generated from others. However, more key frames result in a larger movie with a higher data rate. With some compressors, an additional key frame is inserted automatically if too much of the image has changed from one frame to the next. A good rule of thumb for general use is to have one key frame every 5 seconds (multiply the frames per second by 5). If you are creating a file for RTSP streaming and have concerns about the reliability of the delivery network (as with the public Internet), you may want to increase key frame frequency to one key frame every 1 or 2 seconds. To let the compressor choose the key frame interval, select Automatic.  Frame rate: Frame rate is the number of individual images shown every second. Standard (NTSC) video has a frame rate of 29.97 frames per second (fps), and the standard for film is 24 fps. The European standard (PAL) is 25 fps. QuickTime movies are sometimes created with a slower frame rate to reduce bandwidth and CPU requirements.Chapter 4 Exporting Files with QuickTime Pro 45 Movies with higher frame rates show motion better but have larger file sizes. If you choose a frame rate that’s lower than the movie’s current frame rate, frames will be deleted. If you choose a number that’s higher than the movie’s current frame rate, existing frames will be duplicated (not recommended, since it increases file size without improving quality). When choosing a frame rate, use a simple fraction of your current frame rate, such as 1/2, 1/3, and so on. For example, if your current frame rate is 30 (29.97), use 15 or 10.  Other options: Some compressors or codecs offer options specific to the codec. After you select a compressor (codec), any special options appear. Adding Special Effects and Filters to a QuickTime Movie With QuickTime Pro, you can add special effects such as blur, emboss, and film noise to a movie before you export it. You add special effects by using filters. To set a filter for a movie: 1 In QuickTime Player, choose File > Export. 2 Choose “Movie to QuickTime Movie” from the Export pop-up menu. 3 Click Options, click Filter, and select the filter and settings you want to use. The selected filter is applied to the entire movie. Changing Image (Frame) Size With QuickTime Pro, you can change the size of a movie’s video frame. For example, if your movie will be viewed on a small screen (such as a mobile device), you can change the movie’s dimensions to match the target device. You can experiment with making the frame size smaller for a given data rate to get better encoding results. To change the size of a movie’s video frame: 1 Choose File > Export. 2 Choose a file format from the Export pop-up menu. 3 Click Options. 4 In the Video area of the Movie Settings dialog, click Size and then choose an option:  Use current size: This option (the default) keeps the exported movie’s image size the same as your original source movie.  Use custom size: When you choose this option, you can specify (in pixels) a height and width for the exported movie’s image size. For best results, choose dimensions smaller than your source movie, and keep the height-to-width ratio the same as the source (so that objects don’t appear distorted).46 Chapter 4 Exporting Files with QuickTime Pro Customizing Sound Export Settings To customize sound settings for export: 1 Choose File > Export. 2 Choose “Movie to QuickTime Movie” from the Export pop-up menu. 3 Click Options. 4 In the Sound area of the Movie Settings dialog, click Settings and then choose your options:  Format: Choose the compressor (codec) you want to use for compressing sound. For general use and Internet delivery of music, MPEG-4 Audio (AAC) is recommended.  Channels: Choose between mono (1 channel) or stereo (2 channels).  Rate: Digitized sound is made up of sound samples. The more samples per second, the higher the sound quality. To maintain quality, music requires a higher sampling rate than spoken voice because music uses a wider range of frequencies. Audio CDs use a sampling rate of 44.1 kHz.  Render Settings: Choose the quality of the signal processing that will be used; higher quality settings take longer to process.  Other options: To see any additional options specific to your chosen codec, click the Options button. if it’s available. Preparing Movies for Internet Delivery With QuickTime Pro, you can create movies so that they can be delivered over the Internet. You can deliver a movie over the Internet in two ways:  With HTTP download, the movie is downloaded to the client’s hard disk. Fast Start is a QuickTime feature that enables users to watch or listen to media as it is being downloaded (long before the whole movie has been downloaded) from a standard web server to their hard disks. Fast Start works well for short-form movies where file size is limited. It ensures high-quality playback regardless of users’ Internet connection speeds, although those with slower connections will wait longer before media starts to play.  Real-time streaming provided by QuickTime Streaming Server (QTSS) delivers media in real time over the Internet, from modem rates to broadband. No file is ever downloaded to a viewer’s hard disk. Media is played, but not stored, by the client software as it is delivered. You would choose real-time streaming rather than Fast Start for webcasts of live events in real time, delivery of long-form video, 24/7 Internet radio and TV channels, and other cases in which you don’t files stored on a user’s hard disk. QTSS uses the RTSP protocol.Chapter 4 Exporting Files with QuickTime Pro 47 Preparing a Movie for Fast Start With QuickTime Pro, you can set up a movie to start playing from a web server before the movie has completely downloaded to the user’s hard disk. This is called a “Fast Start” movie. Set the Fast Start setting just before you distribute your movie; making other changes and resaving may undo the Fast Start setting. If the movie is in the format you want, you can set it up for Fast Start by choosing File > Save As and then selecting “Save as a self-contained movie.” If the movie is not in the format you want, you need to encode it first by following the steps below. To convert a movie and set it up for Fast Start: 1 In QuickTime Player, choose File > Export. 2 Choose “Movie to QuickTime Movie” from the Export pop-up menu. 3 Click Options and select video and sound compression options appropriate for web delivery. For more information, see “Customizing Video Export Settings” on page 43, “Customizing Sound Export Settings” on page 46, and the tutorials at www.apple.com/quicktime/resources. 4 Make sure the “Prepare for Internet Streaming” checkbox is selected and Fast Start appears in the pop-up menu. Preparing a Movie for Real-Time Streaming With QuickTime Pro, you can set up a movie to be streamed over the Internet. To do so, you should compress the movie so that its data rate is appropriate for the bandwidth at which your users will connect. Hinted streaming format is for use with QuickTime Streaming Server or Darwin Streaming Server. When you choose hinted streaming, “hint tracks” (information needed to stream the movie) are added to the movie. If the movie is already in the desired format, you can prepare a movie for streaming by choosing File > Export and then choosing “Movie to Hinted Movie.” If you want to change the movie’s format, follow the steps below. To set up a movie for Internet streaming: 1 In QuickTime Player, choose File > Export. 2 Choose “Movie to QuickTime Movie” from the Export pop-up menu. 3 Choose a streaming option from the Use pop-up menu. 4 Click Options and select the “Prepare for Internet Streaming” checkbox. 5 Choose Hinted Streaming from the pop-up menu.48 Chapter 4 Exporting Files with QuickTime Pro If you want to stream a QuickTime movie using QuickTime Streaming Server, you should use a web-optimized video or audio compressor to compress the movie file. All QuickTime compressors are compatible with QuickTime Streaming Server, but the compressors listed here are optimized to give the best results for delivery over the Internet. For a complete list of compressors that QuickTime supports, see the Products area of the QuickTime website (www.apple.com/quicktime/products).  Video compressors: H.264, MPEG-4, Sorenson Video (any version), H.263, H.261  Audio compressors: AAC, QUALCOMM PureVoice, AMR, QDesign For more information about preparing a movie for streaming, go to www.apple.com/quicktime/resources. Creating Reference Movies to Optimize Web Playback You can use reference movies to provide the appropriate movie for different users’ connection speeds. For example, you can have a smaller movie streamed to users connected over a standard modem, and a larger version of the movie streamed to users connected over a broadband connection. Apple provides a free tool, MakeRefMovie X, that greatly simplifies the process of creating reference movies. You can download this software at: developer.apple.com/quicktime/quicktimeintro/tools For more information about reference movies see “Creating Movies Optimized for iPhone and Web Delivery” on page 48 Creating Movies Optimized for iPhone and Web Delivery With QuickTime Pro you can easily create versions of your movie that are optimized for iPhone and desktop viewing. This saves you several steps in creating movies for online distribution and ensures that your audience automatically receives the best viewing experience for the device they’re using. To export for iPhone and web delivery: 1 Choose File > Export for Web. 2 In the dialog that appears, specify a filename and select a location for the exported movies and HTML snippet file. 3 Select the versions you want to create.  iPhone: Creates a movie that is optimized for delivery to iPhone over a Wi-Fi connection.  iPhone (cellular): Creates a move that is optimized for delivery to iPhone over a cellular (EDGE) connection.  Desktop: Creates a movie optimized for delivery to computers over broadband connections.Chapter 4 Exporting Files with QuickTime Pro 49 4 Choose a poster frame option for the movie. The poster frame determines the still image viewers will see when they load the web page with the embedded reference movie. If you want to set a new poster frame before exporting the versions, click Cancel. Then navigate to the frame you want to use and choose View > Set Poster Frame. 5 Click Export to create the files necessary for the options you selected. The exporting process creates several files, including files for each version of the movie you select, a reference movie that will automatically deliver the correct version to the viewer, and an HTML file that contains a snippet of code you can use to embed the movie in a web page. All of these files must be copied to your web server, in the same location relative to each other and with the same file names, in order for the reference movie and HTML snippet to function correctly. Exporting MPEG-4 Files MPEG-4 is the latest worldwide industry standard for delivering professional-quality audio and video over a wide range of bandwidths, from mobile multimedia to high definition. When you want to create a file that will work with another MPEG-4 device, use QuickTime Pro to create MPEG-4 content by exporting a movie. To export a file to the MPEG-4 format: 1 Open the movie you want to export in QuickTime Player, then choose File > Export. 2 Choose “Movie to MPEG-4” from the Export pop-up menu. Note: To create an MPEG-4 movie that is optimized for use with Apple TV, iPhone, or iPod, select “Movie to Apple TV” , “Movie to iPhone”, or “Movie to iPod” from the Export pop-up menu. All of the MPEG-4 options will be set to the appropriate values for you. To adjust settings such as file format, compression, and distribution restrictions, click Options. The options you choose depend on the network over which you’ll deliver the file and the viewers’ connection. The following sections describe the options in detail. MPEG-4 Video Export Options When you export a movie to MPEG-4 format (by choosing File > Export and then choosing “Movie to MPEG-4”), you access the following options by clicking Options and then clicking Video.  File Format: To ensure operability with devices made by ISMA members, choose “MP4 (ISMA).” For more information, go to www.isma.tv.50 Chapter 4 Exporting Files with QuickTime Pro  Video Format: Choose the video compressor (codec) you want to use to compress your video. For the highest quality at the lowest data rate (or the smallest file), H.264 is recommended. If you need the file to play on a device that supports MPEG-4 video, choose MPEG-4 Basic or MPEG-4 Improved, depending on the target device. If your source movie’s video track is already compressed, you can choose “Pass through” so that the video doesn’t get compressed again.  Data Rate: The more kilobits per second (kbps), the better the movie quality. For best playback, however, don’t choose a data rate higher than the available bandwidth.  Optimized for: If you choose H.264 from the Video Format pop-up menu, choose your intended delivery method from the “Optimized for” pop-up menu. This setting tells the codec how much the data rate can vary above and below the data rate you choose.  Image Size: Current maintains the source material size. To choose a size not listed in the pop-up menu, choose Custom.  Preserve Aspect Ratio Using: If you are changing the image size, use this option to specify an option in case the movie needs to be scaled to the new dimensions. Letterbox will scale the source proportionally to fit into the clean aperture, adding black bars to the top and bottom or sides as necessary. Crop centers, scales, and trims to the clean aperture. Fit Within Dimensions adjusts to the destination size by fitting to the longest side, scaling if necessary.  Frame Rate: In most cases, your video will look better if you choose a number that is exactly divisible by the FPS (frames per second) of your source. For example, if your source is captured at 30 FPS, choose a frame rate of 10 or 15. Don’t choose a rate larger than that of your source material.  Key Frame: The more often you specify a key frame (the lower the number), the better the video quality, but the bigger the file. If you choose MP4 from the File Format pop-up menu and H.264 from the Video Format pop-up menu, and then click Video Options, you get the following additional options:  Restrict Profile(s) to: If you need the file to play on a device that conforms to one or more of the standard’s profiles, check those profiles here.  Encoding Mode: Choose whether you want the best quality or faster encoding. MPEG-4 Audio Export Options When you export a movie to MPEG-4 format (by choosing File > Export and then choosing “Movie to MPEG-4”), you access the following options by clicking Options and then clicking Audio.  Audio Format: Choose your audio compressor (codec) here. If your source movie has only one audio track and it is already compressed, you can choose “Pass through” so that the audio doesn’t get compressed again.Chapter 4 Exporting Files with QuickTime Pro 51  Data Rate: As with video, the more kilobits per second, the better the audio quality.  Channels: Choose between mono (1 channel) or stereo (2 channels).  Output Sample Rate: Available only with AAC audio. It’s best to match the sample rate to that of the target device.  Encoding Quality: Available only with AAC audio. The Good setting is optimized for the highest-speed encoding, for higher-quality, choose Best for 16-bit audio, or Better if your audio source is 24-bit. MPEG-4 Streaming Export Options When you export a movie to MPEG-4 format (by choosing File > Export and then choosing “Movie to MPEG-4”), you access the following options by clicking Options and then clicking Streaming. If you’re going to deliver the exported file using RTSP streaming, select “Enable streaming.” Streamed data must be sent in smaller-size packets. Some networks have limitations on packet size and packet duration. If your network provider gives you information about size limitations, you can change the packet size and the maximum packet duration to comply with your delivery network. Otherwise, use the default values. Exporting 3G Files QuickTime Player can import and play back files for use on 3G networks—high-speed mobile networks that enable multimedia to be sent between mobile devices. QuickTime supports standards for nearly any kind of 3G mobile network. To import a 3G file, choose File > Open File and then select the file. You can also open a 3G file in QuickTime by dragging it to the QuickTime icon in the Dock or doubleclicking the file (Mac OS X only). With QuickTime Pro, you can export video, audio, and text to one of the many 3G formats that QuickTime supports. To export a file to the 3G format: 1 Open the movie you want to export in QuickTime Player, then choose File > Export. 2 Choose “Movie to 3G” from the Export pop-up menu. To adjust settings such as file format, compression, and distribution restrictions, click Options. The options you choose depend on the mobile network over which you’ll deliver the file and the capabilities of the viewer’s phone. The following sections describe the options in detail.52 Chapter 4 Exporting Files with QuickTime Pro 3G File Format Export Options After you choose File > Export and click Options, the first two items in the File Format pop-up menu are the standard formats.  3GPP is for GSM networks. With this format, you can use:  MPEG-4, H.263, or H.264 video  AAC or AMR audio  3G timed text  3GPP2 is for CDMA 2000 networks. With this format, you can use:  MPEG-4, H.263, or H.264 video  AAC, AMR, or QCELP audio  3G timed text  Movie fragments (enables playback to start sooner for longer movies, since only the fragment, not the whole movie, must fit on the handset) The remaining formats are provided for specific networks. With these formats, you can restrict distribution so that a file can’t be shared from the recipient’s phone (set this option in the Advanced pane). These formats may limit the acceptable file size or data rate; check with the service provider for more information.  3GPP (Mobile MP4) is for NTT DoCoMo’s i-motion 3G service. With this format, you can use the 3GPP options described above.  3GPP2 (EZmovie) is for KDDI’s 3G network service. This format provides the same options as 3GPP2 (described above), except for AMR audio support.  AMC (EZmovie) is for KDDI subscribers with AMC-capable phones. With this format, you can use:  MPEG-4 video  QCELP audio  KDDI’s text format 3G Video Export Options  Video Format: If your source movie has only one video track and it is already compressed, you can choose “Pass through” (so that the video doesn’t get compressed again).  Data Rate: The more kilobits per second (kbps), the better the movie quality. For best playback, however, don’t choose a data rate higher than the available bandwidth.  Optimized for: If you choose H.264 from the Video Format pop-up menu, choose your intended delivery method from the “Optimized for” pop-up menu. This setting tells the codec how much the data rate can vary above and below the data rate you choose.Chapter 4 Exporting Files with QuickTime Pro 53  Image Size: If you’re sending the file to a mobile phone, choose one of the standards. Current maintains the source material size; the resulting file may not play on a mobile phone. To choose a size not listed in the pop-up menu, choose Custom.  Preserve Aspect Ratio Using: If you are changing the image size, use this option to specify an option in case the movie needs to be scaled to the new dimensions. Letterbox will scale the source proportionally to fit into the clean aperture, adding black bars to the top and bottom or sides as necessary. Crop centers, scales, and trims to the clean aperture. Fit Within Dimensions adjusts to the destination size by fitting to the longest side, scaling if necessary.  Frame Rate: In most cases, your video will look better if you choose a number that is exactly divisible by the FPS (frames per second) of your source. For example, if your source is captured at 30 FPS, choose a frame rate of 10 or 15. Don’t choose a rate larger than that of your source material.  Key Frame: The more often you specify a key frame (the lower the number), the better the video quality, but the bigger the file. These additional options are available when you click Video Options:  Re-sync markers: Adds re-sync markers inside the video frames to help with packet loss recovery when streaming.  Encoding Mode: With H.264 video, you can speed up the compression process (for preview purposes, for example) by choosing “Faster encode (Single-pass).” With the default option, “Best quality (Multi-pass),” the codec determines how many passes are needed to compress the data for the best quality. 3G Audio Export Options When you export a movie to 3G format (by choosing File > Export and then choosing “Movie to 3G”), you access the following options by clicking Options and then clicking Audio.  Audio Format: If your source movie has only one audio track and it is already compressed, you can choose “Pass through” (so that the audio doesn’t get compressed again).  Data Rate: As with video, the more kilobits per second, the better the audio quality.  Channels: Choose between mono (1 channel) or stereo (2 channels).  Frames per sample: Available only with AMR audio, this option enables exported audio data to be packed more efficiently.  Silence detection: Available only with AMR audio, this option detects audio portions with low signal levels and adjusts the data rate of the output accordingly.  Output Sample Rate: Available only with AAC audio. It’s best to match the sample rate to that of the target device.  Encoding Quality: Available only with AAC audio. By choosing Best, you can get higher-quality audio but it takes longer to encode.54 Chapter 4 Exporting Files with QuickTime Pro 3G Text Options When you export a movie to 3G format (by choosing File > Export and then choosing “Movie to 3G”), you access the following options by clicking Options and then clicking Text. These options are available if your movie has a text track (credits, titles, subtitles, and so on). Some mobile devices can’t play text in a movie. To allow the movie to play only if the text can be displayed on the receiving device, select “Require text capability on handset.” Deselect this checkbox to allow the audio and video to play even if the text can’t be displayed on the device. 3G Streaming Options When you export a movie to 3G format (by choosing File > Export and then choosing “Movie to 3G”), you access the following options by clicking Options and then clicking Streaming. To create a file for RTSP streaming to QuickTime Player, select “Enable streaming.” This option creates a hint track (instructions necessary for streaming a file). “Optimize for server” helps the server to process the file faster, but increases the file size. 3G Advanced Options When you export a movie to 3G format (by choosing File > Export and then choosing “Movie to 3G”), you access the following options by clicking Options and then clicking Advanced. If your file is in Mobile MP4 or EZmovie format, you can restrict distribution so that once the file is on a handset it can’t be sent or copied anywhere else. You can specify how many times the file can play back on the handset once downloaded, or make the file expire after a certain number of days or on a certain date. “Fragment movie” enables the file to download via HTTP in small pieces so that playback can start faster and so that larger files can be played on the handset (only the fragment, not the entire movie, must fit on the handset at one time). 55 Appendix Shortcuts and Tips Learn keyboard shortcuts and other tips for using QuickTime efficiently. QuickTime Player Keyboard Shortcuts QuickTime Player and QuickTime Pro provide keyboard shortcuts for most playback options. When available, each of these shortcuts appears to the right of its associated menu item. A few keyboard shortcuts have no menu equivalents. For this control Press Play/pause Space bar Play or pause all movies Command-Return Play movie backward Shift–double-click, Command–Left Arrow Stop playback and go back one frame Left Arrow Stop playback and go forward one frame Right Arrow Go to beginning of selection or movie Option–Left Arrow Go to end of selection or movie Option–Right Arrow Turn volume up Up Arrow Turn volume down Down Arrow Turn volume up to maximum level Option–Up Arrow Turn volume down to minimum level Option–Down Arrow56 Appendix Shortcuts and Tips QuickTime Pro Keyboard Shortcuts For this control Press (Mac OS X) Press (Windows) Play/pause Space bar Space bar Play or pause all movies Command-Return Control-Enter Play movie backward Shift–double-click Command–Left Arrow Shift–double-click Stop playback and go back one frame Left Arrow Left Arrow Stop playback and go forward one frame Right Arrow Right Arrow Go to beginning of selection or movie Option–Left Arrow Control–Left Arrow Go to end of selection or movie Option–Right Arrow Control–Right Arrow Turn volume up Up Arrow Up Arrow Turn volume down Down Arrow Down Arrow Turn volume up to maximum level Option–Up Arrow Control–Up Arrow Turn volume down to minimum level Option–Down Arrow Control–Down Arrow To do this... Press Enter full-screen mode Command-F Exit full-screen mode Command-period or Esc Play movie at half size Command-0 Play movie at normal size Command-1 Play movie at double size Command-2 Play movie at full size Command-3 Move In marker to playhead location I Move Out marker to playhead location O Extend selection to the left Option–Shift–Left Arrow Extend selection to the right Option–Shift–Right Arrow Extend selection to point clicked in LCD Shift-clickAppendix Shortcuts and Tips 57 Automating QuickTime Player with AppleScript In Mac OS X, you can use AppleScript to automate QuickTime Player functions. For example, you can open a movie and tell it to play for a specific duration; automate the conversion of movies from one format to another; adjust track playback properties such as start time, volume, and layer; or adjust movie properties such as copyright and author. To determine all of the AppleScript commands you can use to control QuickTime Player, install AppleScript and look at the QuickTime Player AppleScript dictionary. 1 Open Script Editor. 2 Choose File > Open Dictionary. 3 Select QuickTime Player. Sample QuickTime Player scripts can be found on the AppleScript website (www.apple.com/applescript/quicktime). To do this Press (Mac OS X) Press (Windows) Enter full-screen mode Command-F Control-F Exit full-screen mode Command-period or Esc Control-period or Esc Play movie at half size Command-0 Control-0 Play movie at normal size Command-1 Control-1 Play movie at double size Command-2 Control-2 Play movie at full size Command-3 Control-3 Move In marker to playhead location I I Move Out marker to playhead location O O Extend selection to the left Option–Shift–Left Arrow Extend selection to the right Option–Shift– Right Arrow Extend selection to point clicked in LCD Shift-click58 Appendix Shortcuts and Tips Automating QuickTime Player on Windows In Windows, you can use JavaScript, Visual Basic, or other Active Scripting languages to automate QuickTime Player functions. As with AppleScript on Mac OS X, you can control movie playback, convert movies from one format to another, adjust movie and track properties, and more. There are three QuickTime Player objects available for use:  QuickTimePlayerApp The application object. This object has a Players property which returns a collection of the QuickTime Player windows. The Quit method exits the program.  QuickTimePlayers Use this object to enumerate player windows; the Remove and Add methods permit the removal and creation of new QuickTime Player windows.  QuickTimePlayer This object has properties and methods to open movies, control the window’s position and appearance, and to interact with its menus. The QTControl property returns the ActiveX control hosting the window’s movie. To examine the QuickTime Player or QuickTime Control interfaces in detail, look at the Apple QuickTime Player Library 1.0 or Apple QuickTime Control 2.0 interfaces in a COM object browser. 59 Glossary Glossary AIFF (Audio Interchange File Format) An audio file format used widely on the web. aspect ratio The relationship between the height and width of an image. audio channel Audio tracks can contain one or more channels of audio data. Each channel represents the sound directed to a particular speaker. For instance, stereo tracks contain two audio channels. audio channel label Each audio channel may be labeled to specify where its sound should be directed. In a stereo track, the channels are typically labeled Left and Right. In a 5.1 surround sound track, there are labels for Left, Right, Center, Left Surround, Right Surround, and LFE Screen (the subwoofer). bandwidth The capacity of a network connection, measured in bits or bytes per second (bps or Bps), for carrying data. BMP A bitmapped graphics format used for still images in the Windows environment. bitmapped Represented by pixels. chapter list A list of “locations” in a movie. A user can choose an item from the chapter list to go to that point in the movie. codec From “compressor/decompressor.” A codec is technology for compressing and decompressing data. Codecs can be implemented in software, hardware, or a combination of the two. Codecs can by “lossy” or “lossless,” depending on whether data is lost during compression. compression The process of reducing the data size of a file. Darwin Streaming Server A technology for delivering media over the Internet in real time. Based on the same code as Apple’s QuickTime Streaming Server (QTSS), Darwin Streaming Server is an open-source streaming server.60 Glossary Fast Start A method of delivering a movie so that it can start playing before it is fully downloaded. frame A single image in a movie. frame rate The number of frames displayed per second. GIF (Graphics Interchange Format) A file format for images. hint track In a streamed movie, a hint track specifies for the server how the movie’s content is to be transmitted. hot spot A place in a virtual reality movie where the user can interact with the movie using the mouse. Instant-On A technology that dramatically improves access to streaming content for broadband users. JPEG (Joint Photographic Experts Group) A standard for compressing still images. layer In QuickTime movies, how an image is displayed depends on its layer; images with lower layer numbers are displayed on top. MIDI (Musical Instrument Digital Interface) A software and hardware standard set by the music industry that enables electronic instruments to communicate with one another and with computers. MP3 (MPEG-1 layer 3) A format for compressing music. MPEG-4 An ISO standard based on the QuickTime file format that defines multimedia file and compression formats. node In QuickTime VR, a point from which an object or panorama can be viewed. NTSC (National Television System Committee) The organization that defines North American broadcast standards. The term NTSC video also refers to the video standard defined by the committee, which is 29.97 fps, 525 lines per frame, and interlaced. PAL (Phase Alternation by Line) A video format used by many European countries and other countries outside North America. The PAL standard is 25 fps, 625 lines per frame, and interlaced. PICT A Mac OS picture file format that does not apply compression to an image and therefore maintains the same quality level from copy to copy. pixel The onscreen dots that form text and graphics. A contraction of the words picture and element. plug-in Software that helps a web browser interpret certain types of media files.Glossary 61 PNG (Portable Network Graphics) A file format for images. poster In QuickTime, a still image, usually a single frame from a movie, used to represent the movie to users. protocol A set of standards for sending and receiving information on a network. QTSS (QuickTime Streaming Server) A technology used to deliver media over the Internet in real time. QuickTime Player An application that opens and plays QuickTime movies, as well as many other kinds of files. QuickTime Pro A version of QuickTime Player with advanced features, primarily the addition of editing capabilities. QuickTime VR A QuickTime media type with which users can interact with threedimensional places and objects. reference movie A file that contains the location of one or more media files. A reference file linked from a webpage, for example, can direct a QuickTime Player to the version encoded for a particular connection speed. RGB Red, green, blue; a way of representing colors onscreen. RTSP (Real-Time Streaming Protocol) A protocol for controlling a stream of real-time multimedia content. Sources of data can include both live feeds and stored digital video. sprite An image that is defined once and is then animated by commands that change its position or appearance. streaming Delivery of video or audio data over a network in real time, in packets instead of in a single file download. TIFF (Tagged Image File Format) A format for graphics, commonly used to transfer bitmapped images between applications. track A single data type in a QuickTime movie. A movie may contain one or more tracks. tween track A track that modifies the display of other tracks. virtual reality (VR) The effect achieved by QuickTime VR, where users can manipulate objects or environments. wav A Windows format for sound files.Index 62 Index 3G files exporting 51–53 A A/V Controls 18 animations 27 annotations 38 AppleScript 57 audio adding an audio track 33 audio controls 18, 34 B balance changing for an audio track 34 balance controls 18 bass level 18, 34 bit rate. See data rate browser playing movies in a 12 C Cache checkbox 25 chapter lists 12, 39 color changing a movie’s border 24 compressing audio and video 42–53 connection speed 14 content guide 19 converting files to QuickTime 28 copy-protected movies 17 cropping movies 31 D data rate 14, 44, 47, 50, 52 dimensions of a movie changing 20, 45 determining 35 disk cache 13 displays using more than one 23 E editing QuickTime movies 30–39 email sharing movies via 29 Empty Download Cache checkbox 13 “Enable kiosk mode” checkbox 22 Encoding Mode 53 equalizer 11, 19 exporting movies 42–53 F Fast Start 47 Favorites 17 file formats 9 filters (special effects) 45 firewalls 14 frame rate 18, 27, 44, 50, 53 full-screen mode 19 H help getting additional 10 onscreen 10 hinting 47 HomePage 29 HTTP 14 I importing files 9 Instant-On streaming 14 Internet connection speed 14 preparing movies for delivery over the 46–48 saving movies from the 27 sharing movies via the 29 J jog shuttle 18 K keyboard shortcuts 55 key frame options 44 L languages 37 Layer control 34Index 63 locked media files 17 looping 20 M media keys 17 memory options 25 MIDI 16 MIME Settings 15 Mirror Displays 23 monitors. See displays movie controller 41 Movie Download Cache Size slider 13 MPEG-4 files exporting 49–51 Multi-pass mode 53 Mute checkbox 32, 34 N new features in QuickTime 7 7 O Open Image Sequence command 27 opening files 9, 11 opening files automatically 18 opening more than one movie at a time 20 Open Recent command 17 P pass through 53 pasting items into a movie 35 playback options 13, 18, 41 playhead 11 playing movies 11 playing sound 19 “Play movies automatically” checkbox 13 poster frames 41 Preferences 18 “Preload this track” checkbox 25, 41 Preview application 16 protocols 14 Q QuickTime Player Preferences 18 QuickTime plug-in 12 QuickTime Pro defined 6 getting 23 QuickTime Streaming 47 QuickTime VR movies 15 QuickTime website 13 R recording audio and video 25 reference movies 13, 26, 27, 48 repeating a movie 20 resizing a movie 38 rotating a movie 38 RTSP 14 S “Save movies in disk cache” checkbox 13 saving a movie 27 secured media files 17 selecting part of a movie 30 self-contained movies 26 sharing movies 29 Show Movie Info command 18 Single-pass mode 53 size changing movie 20, 45 slideshow creating from still images 27 slideshows 24, 27 Solo checkbox 32, 34 special effects 45 still images converting to slideshow 27 exporting frames from a QuickTime movie 28 viewing and modifying 16 streaming 47 subtitles 22 system requirements 9 T technical support 10 text adding a text track 35 finding 22 overlaying a movie with text 36 specifying font styles 36 titles 22 tracks 32–37 adding an audio track 33 adding a text track 35 disabling 32 transparency 39 treble level 18, 34 Trim to Selection 31 V versions getting new versions of QuickTime 10 video frame changing the size of 45 video masks 39 virtual reality movies 15 volume 11, 34 adjusting during playback 12 changing sound track volume 34 W web. See Internet Event Handling Guide for iOSContents About Events in iOS 6 At a Glance 6 An Application Receives Multitouch Events When Users Touch its Views 6 An Application Receives Motion Events When Users Move the Device 7 Remote-Control Events Are Sent When Users Manipulate Multimedia Controls 7 How to Use this Book 7 See Also 8 Event Types and Delivery 9 UIKit Event Objects and Types 9 Event Delivery 11 Responder Objects and the Responder Chain 11 Motion Event Types 14 Multitouch Events 16 Events and Touches 17 Approaches for Handling Touch Events 18 Regulating Touch Event Delivery 19 Handling Multitouch Events 20 The Event-Handling Methods 20 Basics of Touch-Event Handling 21 Handling Tap Gestures 24 Handling Swipe and Drag Gestures 27 Handling a Complex Multitouch Sequence 29 Hit-Testing 33 Forwarding Touch Events 35 Handling Events in Subclasses of UIKit Views and Controls 37 Best Practices for Handling Multitouch Events 37 Gesture Recognizers 39 Gesture Recognizers Simplify Event Handling 39 Recognized Gestures 39 Gestures Recognizers Are Attached to a View 40 Gestures Trigger Action Messages 41 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 2Discrete Gestures and Continuous Gestures 41 Implementing Gesture Recognition 42 Preparing a Gesture Recognizer 43 Responding to Gestures 44 Interacting with Other Gesture Recognizers 46 Requiring a Gesture Recognizer to Fail 46 Preventing Gesture Recognizers from Analyzing Touches 47 Permitting Simultaneous Gesture Recognition 48 Regulating the Delivery of Touches to Views 48 Default Touch-Event Delivery 48 Affecting the Delivery of Touches to Views 49 Creating Custom Gesture Recognizers 50 State Transitions 50 Implementing a Custom Gesture Recognizer 52 Motion Events 56 Shaking-Motion Events 56 Getting the Current Device Orientation 58 Setting Required Hardware Capabilities for Accelerometer and Gyroscope Events 59 Accessing Accelerometer Events Using UIAccelerometer 59 Choosing an Appropriate Update Interval 61 Isolating the Gravity Component from Acceleration Data 61 Isolating Instantaneous Motion from Acceleration Data 62 Core Motion 63 Handling Accelerometer Events Using Core Motion 65 Handling Rotation-Rate Data 68 Handling Processed Device-Motion Data 72 Remote Control of Multimedia 76 Preparing Your Application for Remote-Control Events 76 Handling Remote-Control Events 77 Document Revision History 79 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 3 ContentsFigures, Tables, and Listings Event Types and Delivery 9 Figure 1-1 The responder chain in iOS 13 Listing 1-1 Event-type and event-subtype constants 9 Multitouch Events 16 Figure 2-1 A multitouch sequence and touch phases 17 Figure 2-2 Relationship of a UIEvent object and its UITouch objects 18 Figure 2-3 All touches for a given touch event 22 Figure 2-4 All touches belonging to a specific window 22 Figure 2-5 All touches belonging to a specific view 23 Listing 2-1 Detecting a double-tap gesture 24 Listing 2-2 Handling a single-tap gesture and a double-tap gesture 25 Listing 2-3 Tracking a swipe gesture in a view 27 Listing 2-4 Dragging a view using a single touch 28 Listing 2-5 Storing the beginning locations of multiple touches 30 Listing 2-6 Retrieving the initial locations of touch objects 30 Listing 2-7 Handling a complex multitouch sequence 31 Listing 2-8 Determining when the last touch in a multitouch sequence has ended 33 Listing 2-9 Calling hitTest: on a view’s CALayer object 34 Listing 2-10 Overriding hitTest:withEvent: 34 Listing 2-11 Forwarding touch events to “helper” responder objects 35 Gesture Recognizers 39 Figure 3-1 Path of touch objects when gesture recognizer is attached to a view 41 Figure 3-2 Discrete versus continuous gestures 42 Figure 3-3 Possible state transitions for gesture recognizers 51 Table 3-1 Gestures recognized by the gesture-recognizer classes of the UIKit framework 40 Listing 3-1 Creating and initializing discrete and continuous gesture recognizers 43 Listing 3-2 Handling pinch, pan, and double-tap gestures 44 Listing 3-3 Implementation of a “checkmark” gesture recognizer. 53 Listing 3-4 Resetting a gesture recognizer 55 Motion Events 56 Figure 4-1 Core Motion classes 64 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 4Figure 4-2 Right-hand rule 71 Table 4-1 Common update intervals for acceleration events 61 Listing 4-1 Becoming first responder 56 Listing 4-2 Handling a motion event 57 Listing 4-3 Configuring the accelerometer 60 Listing 4-4 Receiving an accelerometer event 60 Listing 4-5 Isolating the effects of gravity from accelerometer data 62 Listing 4-6 Getting the instantaneous portion of movement from accelerometer data 62 Listing 4-7 Configuring the motion manager and starting updates 66 Listing 4-8 Sampling and filtering accelerometer data 67 Listing 4-9 Creating the CMMotionManager object and setting up for gyroscope updates 70 Listing 4-10 Starting and stopping gyroscope updates 71 Listing 4-11 Starting and stopping device-motion updates 73 Listing 4-12 Getting the change in attitude prior to rendering 74 Remote Control of Multimedia 76 Listing 5-1 Preparing to receive remote-control events 76 Listing 5-2 Ending the receipt of remote-control events 77 Listing 5-3 Handling remote-control events 77 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 5 Figures, Tables, and ListingsEvents are objects sent to an application to inform it of user actions. In iOS, events can take many forms: multitouch events, motion events—for example, from device accelerometers—and events for controlling multimedia. (This last type of event is known as a remote-control event because it originates from a headset or other external accessory.) Multitouch events Remote-control events Accelerometer events anApp The UIKit and Core Motion frameworks are responsible for event propagation and delivery in iOS. At a Glance An Application Receives Multitouch Events When Users Touch its Views The Multi-Touch interface of iPhones, iPads, and iPod touches generates low-level events when users touch views of an application. The application sends these events (as UIEvent objects) to the view on which the touches occurred. That view typically analyzes the touches represented by each event object and responds in an appropriate manner. 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 6 About Events in iOSApplications are frequently interested in interpreting the touches a user makes as a common gesture, such as a tap or swipe gesture. These applications can make use of UIKit classes called gesture recognizers, each of which is designed to recognize a specific gesture. Relevant Chapters:: “Event Types and Delivery” (page 9), “Multitouch Events” (page 16), “Gesture Recognizers” (page 39) An Application Receives Motion Events When Users Move the Device Motion events come in different forms, and you can handle them using different frameworks. When users shake the device, the UIKit delivers a UIEvent object to an application; these shaking-motion events are gestures often used to trigger undo and redo actions. If you want your application to receive high-rate, continuous accelerometer and gyroscope data, use the Core Motion framework. (Only certain devices have a gyroscope.) You may also use the UIAccelerometer class to receive and handle accelerometer data. Relevant Chapters:: “Event Types and Delivery” (page 9), “Motion Events” (page 56) Remote-Control Events Are Sent When Users Manipulate Multimedia Controls By conforming to an Apple-provide specification, headsets and other external accessories can send (via the UIKit framework) remote-control events to an application capable of playing audio or video. The view hosting the multimedia can receive the events and thereby control the audio video according to the user’s command (for example, pausing or fast-forwarding). Relevant Chapters:: “Event Types and Delivery” (page 9), “Remote Control of Multimedia” (page 76) How to Use this Book Regardless of the type of event you’re interested in, you should first read “Event Types and Delivery” (page 9). This chapter provides essential background information. About Events in iOS How to Use this Book 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 7See Also Some iPhones and other devices have GPS and compass hardware that also generate low-level data delivered to an application for processing. Location Awareness Programming Guide discusses how to receive and handle this data. Many sample code projects in the iOS Reference Library have code that illustrates the handling of multitouch events and the use of gesture recognizers. Among these are the following projects: Touches, CopyPasteTile , and SimpleGestureRecognizers. About Events in iOS See Also 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 8An iPhone, iPad, or iPod touch device has multiple items of hardware that generate streams of input data an application can access. The Multi-Touch technology enables the direct manipulation of views, including the virtual keyboard. Three accelerometers measure acceleration along the three spatial axes. A gyroscope (only on some device models) measures the rate of rotation around the three axes. The Global Positioning System (GPS) and compass provide measurements of location and orientation. Each of these hardware systems, as they detect touches, device movements, and location changes, produce raw data that is passed to system frameworks. The frameworks package the data and deliver them as events to an application for processing. The following sections identify these frameworks and describe how events are packaged and delivered to applications for handling. Note: This document describes touch events, motion events, and remote control events only. For information on handling GPS and magnetometer (compass) data, see Location Awareness Programming Guide . UIKit Event Objects and Types An event is an object that represents a user action detected by hardware on the device and conveyed to iOS—for example, a finger touching the screen or hand shaking the device. Many events are instances of the UIEvent class of the UIKit framework. A UIEvent object may encapsulate state related to the user event,such asthe associated touches. It also recordsthe moment the event was generated. As a user action takes place—for example, as fingers touch the screen and move across its surface—the operating system continually sends event objects to an application for handling. UIKit currently recognizes three types of events: touch events, “shaking” motion events, and remote-control events. The UIEvent class declares the enum constants shown in Listing 1-1. Listing 1-1 Event-type and event-subtype constants typedef enum { UIEventTypeTouches, UIEventTypeMotion, 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 9 Event Types and DeliveryUIEventTypeRemoteControl, } UIEventType; typedef enum { UIEventSubtypeNone = 0, UIEventSubtypeMotionShake = 1, UIEventSubtypeRemoteControlPlay = 100, UIEventSubtypeRemoteControlPause = 101, UIEventSubtypeRemoteControlStop = 102, UIEventSubtypeRemoteControlTogglePlayPause = 103, UIEventSubtypeRemoteControlNextTrack = 104, UIEventSubtypeRemoteControlPreviousTrack = 105, UIEventSubtypeRemoteControlBeginSeekingBackward = 106, UIEventSubtypeRemoteControlEndSeekingBackward = 107, UIEventSubtypeRemoteControlBeginSeekingForward = 108, UIEventSubtypeRemoteControlEndSeekingForward = 109, } UIEventSubtype; Each event has one of these event type and subtype constants associated with it, which you can accessthrough the type and subtype properties of UIEvent. The event type includes touch events, motion events, and remote control events. In iOS 3.0, there is a shake-motion subtype (UIEventSubtypeMotionShake) and many remote-control subtypes; touch events always have a subtype of UIEventSubtypeNone. A remote-control event originates as commands from the system transport controls or an external accessory conforming to an Apple-provided specification, such as a headset. They are intended to allow users to control multimedia content using those controls and external accessories. Remote-control events are new with iOS 4.0 and are described in detail in “Remote Control of Multimedia” (page 76). You should never retain a UIEvent object in your code. If you need to preserve the current state of an event object for later evaluation, you should copy and store those bits of state in an appropriate manner (using an instance variable or a dictionary object, for example). A device running iOS can send other types of events, broadly considered, to an application for handling. These events are not UIEvent objects, but still encapsulate a measurement of some hardware-generated values. “Motion Event Types” (page 14) discusses these other events. Event Types and Delivery UIKit Event Objects and Types 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 10Event Delivery The delivery of an event to an object for handling occurs along a specific path. As described in “Preparing Your Application for Remote-Control Events” (page 76), when users touch the screen of a device, iOS recognizes the set of touches and packages them in a UIEvent object that it places in the active application’s event queue. If the system interprets the shaking of the device as a motion event, an event object representing that event is also placed in the application’s event queue. The singleton UIApplication object managing the application takes an event from the top of the queue and dispatches it for handling. Typically, it sends the event to the application’s key window—the window currently the focusfor user events—and the window object representing that window sends the event to an initial object for handling. That object is different for touch events and motion events. ● Touch events. The window object uses hit-testing and the responder chain to find the view to receive the touch event. In hit-testing, a window calls hitTest:withEvent: on the top-most view of the view hierarchy; this method proceeds by recursively calling pointInside:withEvent: on each view in the view hierarchy that returns YES, proceeding down the hierarchy until it finds the subview within whose bounds the touch took place. That view becomes the hit-test view. If the hit-test view cannot handle the event, the event travels up the responder chain as described in “Responder Objects and the Responder Chain” (page 11) until the system finds a view that can handle it. A touch object (described in “Events and Touches” (page 17)) is associated with its hit-test view for its lifetime, even if the touch represented by the object subsequently moves outside the view. “Hit-Testing” (page 33) discusses some of the programmatic implications of hit-testing. ● Motion and remote-control events. The window object sends each shaking-motion or remote-control event to the first responder for handling. (The first responder is described in “Responder Objects and the Responder Chain.” Although the hit-test view and the first responder are often the same view object, they do not have to be the same. The UIApplication object and each UIWindow object dispatches eventsin the sendEvent: method. (These classes declare a method with the same signature). Because these methods are funnel pointsfor events coming into an application, you can subclass UIApplication or UIWindow and override the sendEvent: method to monitor events (which is something few applications would need to do). If you override these methods, be sure to call the superclass implementation (that is, [super sendEvent:theEvent]); never tamper with the distribution of events. Responder Objects and the Responder Chain The preceding discussion mentions the concept of responders. What is a responder object and how does it fit into the architecture for event delivery? Event Types and Delivery Event Delivery 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 11A responder object is an object that can respond to events and handle them. UIResponder is the base class for all responder objects, also known as, simply, responders. It defines the programmatic interface not only for event handling but for common responder behavior. UIApplication, UIView, and all UIKit classes that descend from UIView (including UIWindow) inherit directly or indirectly from UIResponder, and thus their instances are responder objects. The first responder is the responder object in an application (usually a UIView object) that is designated to be the first recipient of events other than touch events. A UIWindow object sends the first responder these events in messages, giving it the first shot at handling them. To receive these messages, the responder object must implement canBecomeFirstResponder to return YES; it must also receive a becomeFirstResponder message (which it can invoke on itself). The first responder isthe first view in a window to receive the following type of events and messages: ● Motion events—via calls to the UIResponder motion-handling methods described in “Shaking-Motion Events” (page 56) ● Remote-control events—via calls to the UIResponder method remoteControlReceivedWithEvent: ● Action messages—sent when the user manipulates a control (such as a button or slider) and no target is specified for the action message ● Editing-menu messages—sent when userstap the commands of the editing menu (described in “Displaying and Managing the Edit Menu”) The first responder also plays a role in text editing. A text view or text field that is the focus of editing is made the first responder, which causes the virtual keyboard to appear. Note: Applications must explicitly set a first responder to handle motion events, action messages, and editing-menu messages; UIKit automatically sets the text field or text view a user taps to be the first responder. If the first responder or the hit-test view doesn’t handle an event, UIKit may pass the event (via message) to the next responder in the responder chain to see if it can handle it. The responder chain is a linked series of responder objects along which an event, action message, or editing-menu message is passed. It allows responder objects to transfer responsibility for handling an event to other, higher-level objects. An event proceeds up the responder chain as the application looks for an object Event Types and Delivery Event Delivery 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 12capable of handling the event. Because the hit-test view is also a responder object, an application may also take advantage of the responder chain when handing touch events. The responder chain consists of a series of next responders (each returned by the nextResponder method) in the sequence depicted in Figure 1-1. Figure 1-1 The responder chain in iOS superview window View View View UIApplication View controller Window superview When the system delivers a touch event, it first sends it to a specific view. For touch events, that view is the one returned by hitTest:withEvent:; for “shaking”-motion events, remote-control events, action messages, and editing-menu messages, that view is the first responder. If the initial view doesn’t handle the event, it travels up the responder chain along a particular path: 1. The hit-test view or first responder passes the event or message to its view controller if it has one; if the view doesn’t have a view controller, it passes the event or message to its superview. 2. If a view or its view controller cannot handle the event or message, it passes it to the superview of the view. 3. Each subsequentsuperview in the hierarchy followsthe pattern described in the first two stepsif it cannot handle the event or message. 4. The topmost view in the view hierarchy, if it doesn’t handle the event or message, passes it to the window object for handling. 5. The UIWindow object, if it doesn’t handle the event or message, passesit to the singleton application object. If the application object cannot handle the event or message, it discards it. If you implement a custom view to handle “shaking”-motion events, remote-control events, action messages, or editing-menu messages, you should not forward the event or message to nextResponder directly to send it up the responder chain. Instead invoke the superclass implementation of the current event-handling method—let UIKit handle the traversal of the responder chain. Event Types and Delivery Event Delivery 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 13Motion Event Types Motion events come from two hardware sources on a device: the three accelerometers and the gyroscope, which is available only some devices. An accelerometer measures changes in velocity over time along a given linear path. The combination of accelerometers lets you detect movement of the device in any direction. You can use this data to track both sudden movements in the device and the device’s current orientation relative to gravity. A gyroscope measures the rate of rotation around each of the three axes. (Although there are three accelerometers, one for each axis, the remainder of this document refers to them as a single entity.) The Core Motion framework is primarily responsible for accessing raw accelerometer and gyroscope data and feeding that data to an application for handling. In addition, Core Motion processes combined accelerometer and gyroscope data using special algorithms and presents that refined motion data to applications. Motion eventsfrom Core Motion are represented by three data objects, each encapsulating one or more measurements: ● A CMAccelerometerData object encapsulates a structure that captures the acceleration along each of the spatial axes. ● A CMGyroData object encapsulates a structure that captures the rate of rotation around each of the three spatial axes. ● A CMDeviceMotion object encapsulates several different measurements, including attitude and more useful measurements of rotation rate and acceleration. Core Motion is apart from UIKit architectures and conventions. There is no connection with the UIEvent model and there is no notion of first responder or responder chain. It delivers motion events directly to applications that request them. The CMMotionManager class is the central access point for Core Motion. You create an instance of the class, specify an update interval (either explicitly or implicitly), request that updates start, and handle the motion events as they are delivered. “Core Motion” (page 63) describes this procedure in full detail. An alternative to Core Motion, at least for accessing accelerometer data, is the UIAccelerometer class of the UIKit framework. When you use this class, accelerometer events are delivered as UIAcceleration objects. Although UIAccelerometer is part of UIKit, it is also separate from the UIEvent and responder-chain architectures. See “Accessing Accelerometer Events Using UIAccelerometer” (page 59) for information on using the UIKit facilities. Event Types and Delivery Motion Event Types 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 14Notes: The UIAccelerometer and UIAcceleration classes will be deprecated in a future release, so if your application handles accelerometer events, it should transition to the Core Motion API. In iOS 3.0 and later, if you are trying to detect specific types of motion as gestures—specifically shaking motions—you should consider handling motion events (UIEventTypeMotion) instead of using the accelerometer interfaces. If you want to receive and handle high-rate, continuous motion data, you should instead use the Core Motion accelerometer API. Motion events are described in “Shaking-Motion Events” (page 56). Event Types and Delivery Motion Event Types 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 15Note: This chapter contains information that used to be in iOS App Programming Guide . The information in this chapter has not been updated specifically for iOS 4.0. Touch events in iOS are based on a Multi-Touch model. Instead of using a mouse and a keyboard, users touch the screen of the device to manipulate objects, enter data, and otherwise convey their intentions. iOS recognizes one or more fingers touching the screen as part of a multitouch sequence . This sequence begins when the first finger touches down on the screen and ends when the last finger is lifted from the screen. iOS tracks fingers touching the screen throughout a multitouch sequence and records the characteristics of each of them, including the location of the finger on the screen and the time the touch occurred. Applications often recognize certain combinations of touches as gestures and respond to them in ways that are intuitive to users, such as zooming in on content in response to a pinching gesture and scrolling through content in response to a flicking gesture. Notes: A finger on the screen affords a much different level of precision than a mouse pointer. When a user touches the screen, the area of contact is actually elliptical and tends to be offset below the point where the user thinks he or she touched. This “contact patch” also varies in size and shape based on which finger is touching the screen, the size of the finger, the pressure of the finger on the screen, the orientation of the finger, and other factors. The underlying Multi-Touch system analyzes all of this information for you and computes a single touch point. iOS 4.0 still reports touches on iPhone 4 (and on future high-resolution devices) in a 320x480 coordinate space to maintain source compatibility, but the resolution is twice as high in each dimension for applications built for iOS 4.0 and later releases. In concrete terms, that means that touchesfor applications built for iOS 4 running on iPhone 4 can land on half-point boundaries where on older devices they land only on full point boundaries. If you have any round-to-integer code in your touch-handling path you may lose this precision. Many classes in UIKit handle multitouch events in ways that are distinctive to objects of the class. This is especially true of subclasses of UIControl, such as UIButton and UISlider. Objects of these subclasses—known as control objects—are receptive to certain types of gestures, such as a tap or a drag in a certain direction; when properly configured, they send an action message to a target object when that gesture occurs. Other UIKit classes handle gestures in other contexts; for example, UIScrollView provides scrolling behavior for table views, text views, and other views with large content areas. 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 16 Multitouch EventsSome applications may not need to handle events directly; instead, they can rely on the classes of UIKit for that behavior. However, if you create a custom subclass of UIView—a common pattern in iOS development—and if you want that view to respond to certain touch events, you need to implement the code required to handle those events. Moreover, if you want a UIKit object to respond to events differently, you have to create a subclass of that framework class and override the appropriate event-handling methods. Events and Touches In iOS, a touch is the presence or movement of a finger on the screen that is part of a unique multitouch sequence. For example, a pinch-close gesture has two touches: two fingers on the screen moving toward each other from opposite directions. There are simple single-finger gestures, such as a tap, or a double-tap, a drag, or a flick (where the user quickly swipes a finger across the screen). An application might recognize even more complicated gestures; for example, an application might have a custom control in the shape of a dial that users “turn” with multiple fingers to fine-tune some variable. A UIEvent object of type UIEventTypeTouches represents a touch event. The system continually sends these touch-event objects (or simply, touch events) to an application as fingers touch the screen and move acrossitssurface. The event provides a snapshot of all touches during a multitouch sequence, most importantly the touchesthat are new or have changed for a particular view. As depicted in Figure 2-1, a multitouch sequence begins when a finger first touches the screen. Other fingers may subsequently touch the screen, and all fingers may move across the screen. The sequence ends when the last of these fingers is lifted from the screen. An application receives event objects during each phase of any touch. Figure 2-1 A multitouch sequence and touch phases UITouchPhaseBegan UITouchPhaseEnded Touch 1 down UITouchPhaseBegan Touch 2 down UITouchPhaseMoved Touch 1 and 2 moved Touch 1 and 2 up Touches, which are represented by UITouch objects, have both temporal and spatial aspects. The temporal aspect, called a phase, indicates when a touch has just begun, whether it is moving or stationary, and when it ends—that is, when the finger is lifted from the screen. Multitouch Events Events and Touches 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 17The spatial aspect of touches concerns their association with the object in which they occur as well as their location in it. When a finger touches the screen, the touch is associated with the underlying window and view and maintains that association throughout the life of the event. If multiple touches arrive at once, they are treated together only if they are associated with the same view. Likewise, if two touches arrive in quick succession, they are treated as a multiple tap only if they are associated with the same view. A touch object stores the current location and previous location (if any) of the touch in its view or window. An event object contains all touch objects for the current multitouch sequence and can provide touch objects specific to a view or window (see Figure 2-2). A touch object is persistent for a given finger during a sequence, and UIKit mutates it as it tracks the finger throughout it. The touch attributes that change are the phase of the touch, its location in a view, its previous location, and its timestamp. Event-handling code may evaluate these attributes to determine how to respond to a touch event. Figure 2-2 Relationship of a UIEvent object and its UITouch objects UIEvent UITouch phase = UITouchPhaseBegan locationInView = (35,50) view = ViewA phase = UITouchPhaseMoved locationInView = (35,20) view = ViewA UITouch phase = UITouchPhaseEnded locationInView = (120,87) view = ViewB UITouch Because the system can cancel a multitouch sequence at any time, an event-handling application must be prepared to respond appropriately. Cancellations can occur as a result of overriding system events, such as an incoming phone call. Approaches for Handling Touch Events Most applications that are interested in users’ touches on their custom views are interested in detecting and handling well-established gestures. These gestures include tapping (one or multiple times), pinching (to zoom a view in or out), swiping , panning or dragging a view, and using two fingers to rotate a view. You could implement the touch-event handling code to recognize and handle these gestures, but that code would be complex, possibly buggy, and take some time to write. Alternatively, you could simplify the interpretation and handling of common gestures by using one of the gesture recognizer classes introduced in iOS 3.2. To use a gesture recognizer, you instantiate it, attach it to the view receiving touches, configure it, and assign it an action selector and a target object. When the gesture recognizer recognizes its gesture, it sends an action message to the target, allowing the target to respond to the gesture. Multitouch Events Approaches for Handling Touch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 18You can implement a custom gesture recognizer by subclassing UIGestureRecognizer. A custom gesture recognizer requires you to analyze the stream of events in a multitouch sequence to recognize your distinct gesture; to do this, you should be familiar with the information in this chapter. For information about gesture recognizers, see “Gesture Recognizers” (page 39). Regulating Touch Event Delivery UIKit gives applications programmatic means to simplify event handling or to turn off the stream of UIEvent objects completely. The following list summarizes these approaches: ● Turning off delivery of touch events. By default, a view receives touch events, but you can set its userInteractionEnabled property to NO to turn off delivery of touch events. A view also does not receive these events if it’s hidden or if it’s transparent. ● Turning off delivery of touch events for a period. An application can call the UIApplication method beginIgnoringInteractionEvents and later call the endIgnoringInteractionEvents method. The first method stops the application from receiving touch events entirely; the second method is called to resume the receipt of such events. You sometimes want to turn off event delivery while your code is performing animations. ● Turning on delivery of multiple touches. By default, a view ignores all but the first touch during a multitouch sequence. If you want the view to handle multiple touches you must enable this capability for the view. You do this programmatically by setting the multipleTouchEnabled property of your view to YES, or in Interface Builder by setting the related attribute in the inspector for the related view. ● Restricting event delivery to a single view. By default, a view’s exclusiveTouch property is set to NO, which means that this view does not block other views in a window from receiving touches. If you set the property to YES, you mark the view so that, if it is tracking touches, it is the only view in the window that is tracking touches. Other views in the window cannot receive those touches. However, a view that is marked “exclusive touch” does not receive touches that are associated with other views in the same window. If a finger contacts an exclusive-touch view, then that touch is delivered only if that view is the only view tracking a finger in that window. If a finger touches a non-exclusive view, then that touch is delivered only if there is not another finger tracking in an exclusive-touch view. ● Restricting event delivery to subviews. A custom UIView class can override hitTest:withEvent: to restrict the delivery of multitouch events to its subviews. See “Hit-Testing” (page 33) for a discussion of this technique. Multitouch Events Regulating Touch Event Delivery 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 19Handling Multitouch Events To handle multitouch events, you must first create a subclass of a responder class. This subclass could be any one of the following: ● A custom view (subclass of UIView) ● A subclass of UIViewController or one of its UIKit subclasses ● A subclass of a UIKit view or control class, such as UIImageView or UISlider ● A subclass of UIApplication or UIWindow (although this would be rare) A view controller typically receives, via the responder chain, touch events initially sent to its view if that view does not override the touch-handling methods. For instances of your subclass to receive multitouch events, your subclass must implement one or more of the UIResponder methods for touch-event handling, described below. In addition, the view must be visible (neither transparent or hidden) and must have its userInteractionEnabled property set to YES, which is the default. The following sections describe the touch-event handling methods, describe approachesfor handling common gestures, show an example of a responder object that handles a complex sequence of multitouch events, discuss event forwarding, and suggest some techniques for event handling. The Event-Handling Methods During a multitouch sequence, the application dispatches a series of event messages to the target responder. To receive and handle these messages, the class of a responder object must implement at least one of the following methods declared by UIResponder, and, in some cases, all of these methods: - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event The application sends these messages when there are new or changed touches for a given touch phase: ● Itsendsthe touchesBegan:withEvent: message when one or more fingerstouch down on the screen. ● It sends the touchesMoved:withEvent: message when one or more fingers move. ● It sends the touchesEnded:withEvent: message when one or more fingers lift up from the screen. Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 20● It sends the touchesCancelled:withEvent: message when the touch sequence is cancelled by a system event, such as an incoming phone call. Each of these methodsis associated with a touch phase; for example, touchesBegan:withEvent: is associated with UITouchPhaseBegan. You can get the phase of any UITouch object by evaluating its phase property. Each message that invokes an event-handling method passes in two parameters. The first is a set of UITouch objectsthat represent new or changed touchesfor the given phase. The second parameter is a UIEvent object representing this particular event. From the event object you can get all touch objectsfor the event or a subset of those touch objects filtered for specific views or windows. Some of these touch objects represent touches that have not changed since the previous event message or that have changed but are in different phases. Basics of Touch-Event Handling You frequently handle an event for a given phase by getting one or more of the UITouch objects in the passed-in set, evaluating their properties or getting their locations, and proceeding accordingly. The objects in the set represent those touchesthat are new or have changed for the phase represented by the implemented event-handling method. If any of the touch objects will do, you can send the NSSet object an anyObject message; this is the case when the view receives only the first touch in a multitouch sequence (that is, the multipleTouchEnabled property is set to NO). An important UITouch method is locationInView:, which, if passed a parameter of self, yieldsthe location of the touch in the coordinate system of the receiving view. A parallel method tells you the previous location of the touch (previousLocationInView:). Properties of the UITouch instance tell you how many taps have been made (tapCount), when the touch was created or last mutated (timestamp), and what phase it is in (phase). Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 21If for some reason you are interested in touches in the current multitouch sequence that have not changed since the last phase or that are in a phase other than the ones in the passed-in set, you can request them from the passed-in UIEvent object. The diagram in Figure 2-3 depicts a UIEvent object that contains four touch objects. To get all these touch objects, you would invoke the allTouches on the event object. Figure 2-3 All touches for a given touch event Window B Window A UIEvent UITouch UITouch UITouch UITouch View C View A View B If on the other hand you are interested in only those touches associated with a specific window (Window A in Figure 2-4), you would send the UIEvent object a touchesForWindow: message. Figure 2-4 All touches belonging to a specific window Window B Window A UIEvent UITouch UITouch UITouch UITouch View C View A View B Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 22If you want to get the touches associated with a specific view, you would call touchesForView: on the event object, passing in the view object (View A in Figure 2-5). Figure 2-5 All touches belonging to a specific view Window B Window A UIEvent UITouch UITouch UITouch UITouch View C View A View B If a responder creates persistent objects while handling events during a multitouch sequence, it should implement touchesCancelled:withEvent: to dispose ofthose objects when the system cancelsthe sequence. Cancellation often occurs when an external event—for example, an incoming phone call—disruptsthe current application’s event processing. Note that a responder object should also dispose of those same objects when it receivesthe last touchesEnded:withEvent: message for a multitouch sequence. (See “Forwarding Touch Events” (page 35) to find out how to determine the last UITouchPhaseEnded touch object in a multitouch sequence.) Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 23Important: If your custom responder class is a subclass of UIView or UIViewController, you should implement all of the methods described in “The Event-Handling Methods” (page 20). If your class is a subclass of any other UIKit responder class, you do not need to override all of the event-handling methods; however, in those methods that you do override, be sure to call the superclass implementation of the method (for example, super touchesBegan:touches withEvent:theEvent];). The reason for this guideline issimple: All viewsthat processtouches, including your own, expect (orshould expect) to receive a full touch-eventstream. If you prevent a UIKit responder object from receiving touchesfor a certain phase of an event, the resulting behavior may be undefined and probably undesirable. Handling Tap Gestures A very common gesture in iOS applications is the tap: the user taps an object on the screen with his or her finger. A responder object can handle a single tap in one way, a double-tap in another, and possibly a triple-tap in yet another way. To determine the number of times the user tapped a responder object, you get the value of the tapCount property of a UITouch object. The best places to find this value are the methods touchesBegan:withEvent: and touchesEnded:withEvent:. In many cases, the latter method is preferred because it corresponds to the touch phase in which the user lifts a finger from a tap. By looking for the tap count in the touch-up phase (UITouchPhaseEnded), you ensure that the finger is really tapping and not, for instance, touching down and then dragging. Listing 2-1 shows how to determine whether a double-tap occurred in one of your views. Listing 2-1 Detecting a double-tap gesture - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { } - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { for (UITouch *touch in touches) { if (touch.tapCount >= 2) { [self.superview bringSubviewToFront:self]; } } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 24} - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { } A complication arises when a responder object wants to handle a single-tap and a double-tap gesture in different ways. For example, a single tap might select the object and a double tap might display a view for editing the item that was double-tapped. How is the responder object to know that a single tap is not the first part of a double tap? Listing 2-2 (page 25) illustrates an implementation of the event-handling methods that increases the size of the receiving view upon a double-tap gesture and decreases it upon a single-tap gesture. The following is a commentary on this code: 1. In touchesEnded:withEvent:, when the tap count is one, the responder object sends itself a performSelector:withObject:afterDelay: message. The selector identifies another method implemented by the responder to handle the single-tap gesture; the second parameter is an NSValue or NSDictionary object that holdssome state of the UITouch object; the delay issome reasonable interval between a single- and a double-tap gesture. Note: Because a touch object is mutated as it proceeds through a multitouch sequence, you cannot retain a touch and assume that itsstate remainsthe same. (And you cannot copy a touch object because UITouch does not adopt the NSCopying protocol.) Thusif you want to preserve the state of a touch object, you should store those bits ofstate in a NSValue object, a dictionary, or a similar object. (The code in Listing 2-2 stores the location of the touch in a dictionary but does not use it; this code is included for purposes of illustration.) 2. In touchesBegan:withEvent:, if the tap count is two, the responder object cancels the pending delayed-perform invocation by calling the cancelPreviousPerformRequestsWithTarget: method of NSObject, passing itself as the argument. If the tap count is not two, the method identified by the selector in the previous step for single-tap gestures is invoked after the delay. 3. In touchesEnded:withEvent:, if the tap count is two, the responder performs the actions necessary for handling double-tap gestures. Listing 2-2 Handling a single-tap gesture and a double-tap gesture - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *aTouch = [touches anyObject]; if (aTouch.tapCount == 2) { Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 25[NSObject cancelPreviousPerformRequestsWithTarget:self]; } } - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *theTouch = [touches anyObject]; if (theTouch.tapCount == 1) { NSDictionary *touchLoc = [NSDictionary dictionaryWithObject: [NSValue valueWithCGPoint:[theTouch locationInView:self]] forKey:@"location"]; [self performSelector:@selector(handleSingleTap:) withObject:touchLoc afterDelay:0.3]; } else if (theTouch.tapCount == 2) { // Double-tap: increase image size by 10%" CGRect myFrame = self.frame; myFrame.size.width += self.frame.size.width * 0.1; myFrame.size.height += self.frame.size.height * 0.1; myFrame.origin.x -= (self.frame.origin.x * 0.1) / 2.0; myFrame.origin.y -= (self.frame.origin.y * 0.1) / 2.0; [UIView beginAnimations:nil context:NULL]; [self setFrame:myFrame]; [UIView commitAnimations]; } } - (void)handleSingleTap:(NSDictionary *)touches { // Single-tap: decrease image size by 10%" CGRect myFrame = self.frame; myFrame.size.width -= self.frame.size.width * 0.1; myFrame.size.height -= self.frame.size.height * 0.1; myFrame.origin.x += (self.frame.origin.x * 0.1) / 2.0; myFrame.origin.y += (self.frame.origin.y * 0.1) / 2.0; Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 26[UIView beginAnimations:nil context:NULL]; [self setFrame:myFrame]; [UIView commitAnimations]; } - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { /* no state to clean up, so null implementation */ } Handling Swipe and Drag Gestures Horizontal and vertical swipes are a simple type of gesture that you can track easily from your own code and use to perform actions. To detect a swipe gesture, you have to track the movement of the user’s finger along the desired axis of motion, but it is up to you to determine what constitutes a swipe. In other words, you need to determine whether the user’s finger moved far enough, if it moved in a straight enough line, and if it went fast enough. You do that by storing the initial touch location and comparing it to the location reported by subsequent touch-moved events. Listing 2-3 shows some basic tracking methods you could use to detect horizontal swipes in a view. In this example, the view stores the initial location of the touch in a startTouchPosition instance variable. As the user’sfinger moves, the code comparesthe current touch location to the starting location to determine whether it is a swipe. If the touch moves too far vertically, it is not considered to be a swipe and is processed differently. If it continues along its horizontal trajectory, however, the code continues processing the event as if it were a swipe. The processing routines could then trigger an action once the swipe had progressed far enough horizontally to be considered a complete gesture. To detect swipe gestures in the vertical direction, you would use similar code but would swap the x and y components. Listing 2-3 Tracking a swipe gesture in a view #define HORIZ_SWIPE_DRAG_MIN 12 #define VERT_SWIPE_DRAG_MAX 4 - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *touch = [touches anyObject]; // startTouchPosition is an instance variable startTouchPosition = [touch locationInView:self]; } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 27- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *touch = [touches anyObject]; CGPoint currentTouchPosition = [touch locationInView:self]; // To be a swipe, direction of touch must be horizontal and long enough. if (fabsf(startTouchPosition.x - currentTouchPosition.x) >= HORIZ_SWIPE_DRAG_MIN && fabsf(startTouchPosition.y - currentTouchPosition.y) <= VERT_SWIPE_DRAG_MAX) { // It appears to be a swipe. if (startTouchPosition.x < currentTouchPosition.x) [self myProcessRightSwipe:touches withEvent:event]; else [self myProcessLeftSwipe:touches withEvent:event]; } } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { startTouchPosition = CGPointZero; } - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { startTouchPosition = CGPointZero; } Listing 2-4 shows an even simpler implementation of tracking a single touch, but this time for the purposes of dragging the receiving view around the screen. In this instance, the responder class fully implements only the touchesMoved:withEvent: method, and in this method computes a delta value between the touch's current location in the view and its previouslocation in the view. It then usesthis delta value to reset the origin of the view’s frame. Listing 2-4 Dragging a view using a single touch - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 28- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *aTouch = [touches anyObject]; CGPoint loc = [aTouch locationInView:self]; CGPoint prevloc = [aTouch previousLocationInView:self]; CGRect myFrame = self.frame; float deltaX = loc.x - prevloc.x; float deltaY = loc.y - prevloc.y; myFrame.origin.x += deltaX; myFrame.origin.y += deltaY; [self setFrame:myFrame]; } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { } - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { } Handling a Complex Multitouch Sequence Taps, drags, and swipes are simple gestures, typically involving only a single touch. Handling a touch event consisting of two or more touches is a more complicated affair. You may have to track all touches through all phases, recording the touch attributes that have changed and altering internal state appropriately. There are a couple of things you should do when tracking and handling multiple touches: ● Set the multipleTouchEnabled property of the view to YES. ● Use a Core Foundation dictionary object (CFDictionaryRef) to track the mutations of touches through their phases during the event. When handling an event with multiple touches, you often store initial bits of each touch’s state for later comparison with the mutated UITouch instance. As an example, say you want to compare the final location of each touch with its original location. In the touchesBegan:withEvent: method, you can obtain the original location of each touch from the locationInView: method and store those in a CFDictionaryRef object using the addresses of the UITouch objects as keys. Then, in the touchesEnded:withEvent: method you can use the address of each passed-in UITouch object to obtain the object’s original location and compare Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 29that with its current location. (You should use a CFDictionaryRef type rather than an NSDictionary object; the latter copies its keys, but the UITouch class does not adopt the NSCopying protocol, which is required for object copying.) Listing 2-5 illustrates how you might store beginning locations of UITouch objects in a Core Foundation dictionary. Listing 2-5 Storing the beginning locations of multiple touches - (void)cacheBeginPointForTouches:(NSSet *)touches { if ([touches count] > 0) { for (UITouch *touch in touches) { CGPoint *point = (CGPoint *)CFDictionaryGetValue(touchBeginPoints, touch); if (point == NULL) { point = (CGPoint *)malloc(sizeof(CGPoint)); CFDictionarySetValue(touchBeginPoints, touch, point); } *point = [touch locationInView:view.superview]; } } } Listing 2-6 illustrates how to retrieve those initial locations stored in the dictionary. It also gets the current locations of the same touches. It uses these values in computing an affine transformation (not shown). Listing 2-6 Retrieving the initial locations of touch objects - (CGAffineTransform)incrementalTransformWithTouches:(NSSet *)touches { NSArray *sortedTouches = [[touches allObjects] sortedArrayUsingSelector:@selector(compareAddress:)]; // other code here ... UITouch *touch1 = [sortedTouches objectAtIndex:0]; UITouch *touch2 = [sortedTouches objectAtIndex:1]; Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 30CGPoint beginPoint1 = *(CGPoint *)CFDictionaryGetValue(touchBeginPoints, touch1); CGPoint currentPoint1 = [touch1 locationInView:view.superview]; CGPoint beginPoint2 = *(CGPoint *)CFDictionaryGetValue(touchBeginPoints, touch2); CGPoint currentPoint2 = [touch2 locationInView:view.superview]; // compute the affine transform... } Although the code example in Listing 2-7 doesn’t use a dictionary to track touch mutations, it also handles multiple touches during an event. It shows a custom UIView object responding to touches by animating the movement of a “Welcome” placard around the screen as a finger moves it and changing the language of the welcome when the user makes a double-tap gesture. (The code in this example comes from the MoveMe sample code project, which you can examine to get a better understanding of the event-handling context.) Listing 2-7 Handling a complex multitouch sequence - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *touch = [[event allTouches] anyObject]; // Only move the placard view if the touch was in the placard view if ([touch view] != placardView) { // On double tap outside placard view, update placard's display string if ([touch tapCount] == 2) { [placardView setupNextDisplayString]; } return; } // "Pulse" the placard view by scaling up then down // Use UIView's built-in animation [UIView beginAnimations:nil context:NULL]; [UIView setAnimationDuration:0.5]; CGAffineTransform transform = CGAffineTransformMakeScale(1.2, 1.2); placardView.transform = transform; [UIView commitAnimations]; [UIView beginAnimations:nil context:NULL]; Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 31[UIView setAnimationDuration:0.5]; transform = CGAffineTransformMakeScale(1.1, 1.1); placardView.transform = transform; [UIView commitAnimations]; // Move the placardView to under the touch [UIView beginAnimations:nil context:NULL]; [UIView setAnimationDuration:0.25]; placardView.center = [self convertPoint:[touch locationInView:self] fromView:placardView]; [UIView commitAnimations]; } - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *touch = [[event allTouches] anyObject]; // If the touch was in the placardView, move the placardView to its location if ([touch view] == placardView) { CGPoint location = [touch locationInView:self]; location = [self convertPoint:location fromView:placardView]; placardView.center = location; return; } } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { UITouch *touch = [[event allTouches] anyObject]; // If the touch was in the placardView, bounce it back to the center if ([touch view] == placardView) { // Disable user interaction so subsequent touches don't interfere with animation self.userInteractionEnabled = NO; [self animatePlacardViewToCenter]; return; } } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 32Note: Custom views that redraw themselves in response to events they handle generally should only set drawing state in the event-handling methods and perform all of the drawing in the drawRect: method. To learn more about drawing view content, see View Programming Guide for iOS . To find out when the last finger in a multitouch sequence islifted from a view, compare the number of UITouch objects in the passed-in set with the number of touches for the view maintained by the passed-in UIEvent object. If they are the same, then the multitouch sequence has concluded. Listing 2-8 illustrates how to do this in code. Listing 2-8 Determining when the last touch in a multitouch sequence has ended - (void)touchesEnded:(NSSet*)touches withEvent:(UIEvent*)event { if ([touches count] == [[event touchesForView:self] count]) { // last finger has lifted.... } } Remember that the passed-in set contains all touch objects associated with the receiving view that are new or changed for the given phase whereas the touch objects returned from touchesForView: includes all objects associated with the specified view. Hit-Testing Your custom responder can use hit-testing to find the subview or sublayer of itself that is "under” a touch, and then handle the event appropriately. It does this by either calling the hitTest:withEvent: method of UIView or the hitTest: method of CALayer; or it can override one of these methods. Responderssometimes perform hit-testing prior to event forwarding (see “Forwarding Touch Events” (page 35)). Note: The hitTest:withEvent: and hitTest: methods have some slightly different behaviors. If the point passed into hitTest:withEvent: or hitTest: is outside the bounds of the view, it is ignored. This means that subviews that are outside their superview do not receive touch events. If you have a custom view with subviews, you need to determine whether you want to handle touches at the subview level or the superview level. If the subviews do not handle touches by implementing touchesBegan:withEvent:, touchesEnded:withEvent:, or touchesMoved:withEvent:, then these messages propagate up the responder chain to the superview. However, because multiple taps and multiple Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 33touches are associated with the subviews where they first occurred, the superview won’t receive these touches. To ensure reception of all kinds of touches, the superview should override hitTest:withEvent: to return itself rather than any of its subviews. The example in Listing 2-9 detects when an “Info” image in a layer of the custom view is tapped. Listing 2-9 Calling hitTest: on a view’s CALayer object - (void)touchesEnded:(NSSet*)touches withEvent:(UIEvent*)event { CGPoint location = [[touches anyObject] locationInView:self]; CALayer *hitLayer = [[self layer] hitTest:[self convertPoint:location fromView:nil]]; if (hitLayer == infoImage) { [self displayInfo]; } } In Listing 2-10, a responder subclass (in this case, a subclass of UIWindow) overrides hitTest:withEvent:. It first gets the hit-test view returned by the superclass. Then, if that view is itself, it substitutes the view that is furthest down the view hierarchy. Listing 2-10 Overriding hitTest:withEvent: - (UIView*)hitTest:(CGPoint)point withEvent:(UIEvent *)event { UIView *hitView = [super hitTest:point withEvent:event]; if (hitView == self) return [[self subviews] lastObject]; else return hitView; } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 34Forwarding Touch Events Event forwarding is a technique used by some applications. You forward touch events by invoking the event-handling methods of another responder object. Although this can be an effective technique, you should use it with caution. The classes of the UIKit framework are not designed to receive touches that are not bound to them; in programmatic terms, this means that the view property of the UITouch object must hold a reference to the framework object in order for the touch to be handled. If you want to conditionally forward touches to other responders in your application, all of these responders should be instances of your own subclasses of UIView. For example, let’s say an application has three custom views: A, B, and C. When the user touches view A, the application’s window determines that it is the hit-test view and sends the initial touch event to it. Depending on certain conditions, view A forwards the event to either view B or view C. In this case, views A, B, and C must be aware that this forwarding is going on, and views B and C must be able to deal with touches that are not bound to them. Event forwarding often requires analysis of touch objectsto determine where they should be forwarded. There are several approaches you can take for this analysis: ● With an “overlay” view (such as a common superview), use hit-testing to intercept events for analysis prior to forwarding them to subviews (see “Hit-Testing” (page 33)). ● Override sendEvent: in a custom subclass of UIWindow, analyze touches, and forward them to the appropriate responders. In your implementation you should alwaysinvoke the superclassimplementation of sendEvent:. ● Design your application so that touch analysis isn’t necessary Listing 2-11 illustrates the second technique, that of overriding sendEvent: in a subclass of UIWindow. In this example, the object to which touch events are forwarded is a custom “helper” responder that performs affine transformations on the view that is associated with. Listing 2-11 Forwarding touch events to “helper” responder objects - (void)sendEvent:(UIEvent *)event { for (TransformGesture *gesture in transformGestures) { // collect all the touches we care about from the event NSSet *touches = [gesture observedTouchesForEvent:event]; NSMutableSet *began = nil; NSMutableSet *moved = nil; NSMutableSet *ended = nil; Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 35NSMutableSet *cancelled = nil; // sort the touches by phase so we can handle them similarly to normal event dispatch for(UITouch *touch in touches) { switch ([touch phase]) { case UITouchPhaseBegan: if (!began) began = [NSMutableSet set]; [began addObject:touch]; break; case UITouchPhaseMoved: if (!moved) moved = [NSMutableSet set]; [moved addObject:touch]; break; case UITouchPhaseEnded: if (!ended) ended = [NSMutableSet set]; [ended addObject:touch]; break; case UITouchPhaseCancelled: if (!cancelled) cancelled = [NSMutableSet set]; [cancelled addObject:touch]; break; default: break; } } // call our methods to handle the touches if (began) [gesture touchesBegan:began withEvent:event]; if (moved) [gesture touchesMoved:moved withEvent:event]; if (ended) [gesture touchesEnded:ended withEvent:event]; if (cancelled) [gesture touchesCancelled:cancelled withEvent:event]; } [super sendEvent:event]; } Multitouch Events Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 36Notice that in this example that the overriding subclass does something important to the integrity of the touch-event stream: It invokes the superclass implementation of sendEvent:. Handling Events in Subclasses of UIKit Views and Controls If you subclass a view or control class of the UIKit framework (for example, UIImageView or UISwitch) for the purpose of altering or extending event-handling behavior, you should keep the following points in mind: ● Unlike in a custom view, it is not necessary to override each event-handling method. ● Always invoke the superclass implementation of each event-handling method that you do override. ● Do not forward events to UIKit framework objects. Best Practices for Handling Multitouch Events When handling events, both touch events and motion events, there are a few recommended techniques and patterns you should follow. ● Always implement the event-cancellation methods. In your implementation, you should restore the state of the view to what it was before the current multitouch sequence, freeing any transient resourcesset up for handling the event. If you don’t implement the cancellation method your view could be left in an inconsistent state. In some cases, another view might receive the cancellation message. ● If you handle events in a subclass of UIView, UIViewController, or (in rare cases) UIResponder, ● You should implement all of the event-handling methods (even if it is a null implementation). ● Do not call the superclass implementation of the methods. ● If you handle events in a subclass of any other UIKit responder class, ● You do not have to implement all of the event-handling methods. ● But in the methods you do implement, be sure to call the superclass implementation. For example, [super touchesBegan:theTouches withEvent:theEvent]; ● Do not forward events to other responder objects of the UIKit framework. The responders that you forward events to should be instances of your own subclasses of UIView, and all of these objects must be aware that event-forwarding is taking place and that, in the case of touch events, they may receive touches that are not bound to them. ● Custom views that redraw themselves in response to events should only set drawing state in the event-handling methods and perform all of the drawing in the drawRect: method. Multitouch Events Best Practices for Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 37● Do not explicitly send events up the responder (via nextResponder); instead, invoke the superclass implementation and let the UIKit handle responder-chain traversal. Multitouch Events Best Practices for Handling Multitouch Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 38Note: This chapter containsinformation that used to be in iPad ProgrammingGuide . The information in this chapter has not been updated specifically for iOS 4.0. Applicationsfor iOS are driven largely through events generated when userstouch buttons, toolbars, table-view rows and other objects in an application’s user interface. The classes of the UIKit framework provide default event-handling behavior for most of these objects. However, some applications, primarily those with custom views, have to do their own event handling. They have to analyze the stream of touch objects in a multitouch sequence and determine the intention of the user. Most event-handling views seek to detect common gestures that users make on their surface—things such as triple-tap, touch-and-hold (also called long press), pinching, and rotating gestures, The code for examining a raw stream of multitouch events and detecting one or more gestures is often complex. Prior to iOS 3.2, you cannot reuse the code except by copying it to another project and modifying it appropriately. To help applications detect gestures, iOS 3.2 introduces gesture recognizers, objects that inherit directly from the UIGestureRecognizer class. The following sections tell you about how these objects work, how to use them, and how to create custom gesture recognizers that you can reuse among your applications. Gesture Recognizers Simplify Event Handling UIGestureRecognizer is the abstract base class for concrete gesture-recognizer subclasses (or, simply, gesture recognizers). The UIGestureRecognizer class defines a programmatic interface and implements the behavioral underpinnings for gesture recognition. The UIKit framework provides six gesture recognizers for the most common gestures. For other gestures, you can design and implement your own gesture recognizer (see “Creating Custom Gesture Recognizers” (page 50) for details). Recognized Gestures The UIKit framework supports the recognition of the gestures listed in Table 3-1. Each of the listed classes is a direct subclass of UIGestureRecognizer. 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 39 Gesture RecognizersTable 3-1 Gestures recognized by the gesture-recognizer classes of the UIKit framework Gesture UIKit class Tapping (any number of taps) UITapGestureRecognizer Pinching in and out (for zooming a view) UIPinchGestureRecognizer Panning or dragging UIPanGestureRecognizer Swiping (in any direction) UISwipeGestureRecognizer Rotating (fingers moving in opposite directions) UIRotationGestureRecognizer Long press (also known as “touch and hold”) UILongPressGestureRecognizer Before you decide to use a gesture recognizer, consider how you are going to use it. Respond to gestures only in ways that users expect. For example, a pinching gesture should scale a view, zooming it in and out; it should not be interpreted as, say, a selection request, for which a tap is more appropriate. For guidelines about the proper use of gestures, see iOS Human Interface Guidelines. Gestures Recognizers Are Attached to a View To detect its gestures, a gesture recognizer must be attached to the view that a user is touching. This view is known as the hit-tested view. Recall that events in iOS are represented by UIEvent objects, and each event object encapsulates the UITouch objects of the current multitouch sequence. A set of those UITouch objects is specific to a given phase of a multitouch sequence. Delivery of events initially follows the usual path: from operating system to the application object to the window object representing the window in which the touches Gesture Recognizers Gesture Recognizers Simplify Event Handling 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 40are occurring. But before sending an event to the hit-tested view, the window object sends it to the gesture recognizer attached to that view or to any of that view’s subviews. Figure 3-1 illustrates this general path, with the numbers indicating the order in which touches are received. Figure 3-1 Path of touch objects when gesture recognizer is attached to a view UIApplication View Gesture Recognizer Touch UIWindow 1 Touch 2 Touch 3 Thus gesture recognizers act as observers of touch objects sent to their attached view or view hierarchy. However, they are not part of that view hierarchy and do not participate in the responder chain. Gesture recognizers may delay the delivery of touch objects to the view while they are recognizing gestures, and by default they cancel delivery of remaining touch objects to the view once they recognize their gesture. For more on the possible scenarios of event delivery from a gesture recognizer to its view, see “Regulating the Delivery of Touches to Views” (page 48). For some gestures, the locationInView: and the locationOfTouch:inView: methods of UIGestureRecognizer enable clients to find the location of gestures or specific touches in the attached view or its subviews. See “Responding to Gestures” (page 44) for more information. Gestures Trigger Action Messages When a gesture recognizer recognizes its gesture, it sends one or more action messages to one or more targets. When you create a gesture recognizer, you initialize it with an action and a target. You may add more target-action pairs to it thereafter. The target-action pairs are not additive; in other words, an action is only sent to the target it was originally linked with, and not to other targets (unless they’re specified in another target-action pair). Discrete Gestures and Continuous Gestures When a gesture recognizer recognizes a gesture, it sends either a single action message to its target or multiple action messages until the gesture ends. This behavior is determined by whether the gesture is discrete or continuous. A discrete gesture, such as a double-tap, happens just once; when a gesture recognizer recognizes Gesture Recognizers Gesture Recognizers Simplify Event Handling 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 41a discrete gesture, it sends its target a single action message. A continuous gesture, such as pinching, takes place over a period and ends when the user lifts the final finger in the multitouch sequence. The gesture recognizer sends action messages to its target at short intervals until the multitouch sequence ends. Figure 3-2 Discrete versus continuous gestures UITapGestureRecognizer Tapping gesture Pinching gesture Touch events Target UIPinchGestureRecognizer Target Action messages Action messages Touch events The reference documents for the gesture-recognizer classes note whether the instances of the class detect discrete or continuous gestures. Implementing Gesture Recognition To implement gesture recognition, you create a gesture-recognizer instance to which you assign a target, action, and, in some cases, gesture-specific attributes. You attach this object to a view and then implement the action method in your target object that handles the gesture. Gesture Recognizers Implementing Gesture Recognition 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 42Preparing a Gesture Recognizer To create a gesture recognizer, you must allocate and initialize an instance of a concrete UIGestureRecognizer subclass. When you initialize it, specify a target object and an action selector, as in the following code: UITapGestureRecognizer *doubleFingerDTap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleDoubleDoubleTap:)]; The action methods for handling gestures—and the selector for identifying them—are expected to conform to one of two signatures: - (void)handleGesture - (void)handleGesture:(UIGestureRecognizer *)sender where handleGesture and sender can be any name you choose. Methods having the second signature allow the target to query the gesture recognizer for addition information. For example, the target of a UIPinchGestureRecognizer object can ask that object for the current scale factor related to the pinching gesture. After you create a gesture recognizer, you must attach it to the view receiving touches—that is, the hit-test view—using the UIView method addGestureRecognizer:. You can find out what gesture recognizers a view currently has attached through the gestureRecognizers property, and you can detach a gesture recognizer from a view by calling removeGestureRecognizer:. The sample method in Listing 3-1 creates and initializes three gesture recognizers: a single-finger double-tap, a panning gesture, and a rotation gesture. It then attaches each gesture-recognizer object to the same view. For the singleFingerDTap object, the code specifies that two taps are required for the gesture to be recognized. Each method adds the created gesture recognizer to a view and then releases it (because the view now retains it). Listing 3-1 Creating and initializing discrete and continuous gesture recognizers - (void)createGestureRecognizers { UITapGestureRecognizer *singleFingerDTap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleDoubleTap:)]; singleFingerDTap.numberOfTapsRequired = 2; [self.theView addGestureRecognizer:singleFingerDTap]; [singleFingerDTap release]; UIPanGestureRecognizer *panGesture = [[UIPanGestureRecognizer alloc] Gesture Recognizers Implementing Gesture Recognition 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 43initWithTarget:self action:@selector(handlePanGesture:)]; [self.theView addGestureRecognizer:panGesture]; [panGesture release]; UIPinchGestureRecognizer *pinchGesture = [[UIPinchGestureRecognizer alloc] initWithTarget:self action:@selector(handlePinchGesture:)]; [self.theView addGestureRecognizer:pinchGesture]; [pinchGesture release]; } You may also add additional targets and actions to a gesture recognizer using the addTarget:action: method of UIGestureRecognizer. Remember that action messages for each target and action pair are restricted to that pair; if you have multiple targets and actions, they are not additive. Responding to Gestures To handle a gesture, the target for the gesture recognizer must implement a method corresponding to the action selector specified when you initialized the gesture recognizer. For discrete gestures, such as a tapping gesture, the gesture recognizer invokesthe method once per recognition; for continuous gestures, the gesture recognizer invokes the method at repeated intervals until the gesture ends (that is, the last finger is lifted from the gesture recognizer’s view). In gesture-handling methods, the target object often gets additional information about the gesture from the gesture recognizer; it does this by obtaining the value of a property defined by the gesture recognizer, such as scale (for scale factor) or velocity. It can also query the gesture recognizer (in appropriate cases) for the location of the gesture. Listing 3-2 shows handlers for two continuous gestures: a pinching gesture (handlePinchGesture:) and a panning gesture (handlePanGesture:). It also gives an example of a handler for a discrete gesture; in this example, when the user double-taps the view with a single finger, the handler (handleSingleDoubleTap:) centers the view at the location of the double-tap. Listing 3-2 Handling pinch, pan, and double-tap gestures - (IBAction)handlePinchGesture:(UIGestureRecognizer *)sender { CGFloat factor = [(UIPinchGestureRecognizer *)sender scale]; self.view.transform = CGAffineTransformMakeScale(factor, factor); } Gesture Recognizers Implementing Gesture Recognition 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 44- (IBAction)handlePanGesture:(UIPanGestureRecognizer *)sender { CGPoint translate = [sender translationInView:self.view]; CGRect newFrame = currentImageFrame; newFrame.origin.x += translate.x; newFrame.origin.y += translate.y; sender.view.frame = newFrame; if (sender.state == UIGestureRecognizerStateEnded) currentImageFrame = newFrame; } - (IBAction)handleSingleDoubleTap:(UIGestureRecognizer *)sender { CGPoint tapPoint = [sender locationInView:sender.view.superview]; [UIView beginAnimations:nil context:NULL]; sender.view.center = tapPoint; [UIView commitAnimations]; } These action methods handle the gestures in distinctive ways: ● In the handlePinchGesture: method, the target communicates with its gesture recognizer (sender) to get the scale factor (scale). The method uses the scale value in a Core Graphics function that scales the view and assigns the computed value to the view’s affine transform property. ● The handlePanGesture: method applies the translationInView: values obtained from its gesture recognizer to a cached frame value for the attached view. When the gesture concludes, it caches the newest frame value. ● In the handleSingleDoubleTap: method, the target gets the location of the double-tap gesture from its gesture recognizer by calling the locationInView: method. It then uses this point, converted to superview coordinates, to animate the center of the view to the location of the double-tap. The scale factor obtained in the handlePinchGesture: method, as with the rotation angle and the translation value related to other recognizers of continuous gestures, is to be applied to the state of the view when the gesture is first recognized. It is not a delta value to be concatenated over each handler invocation for a given gesture. Gesture Recognizers Implementing Gesture Recognition 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 45A hit-test with an attached gesture recognizer does not have to be passive when there are incoming touch events. Instead, it can determine which gesture recognizers, if any, are involved with a particular UITouch object by querying the gestureRecognizers property. Similarly, it can find out which touches a given gesture recognizer is analyzing for a given event by calling the UIEvent method touchesForGestureRecognizer:. Interacting with Other Gesture Recognizers More than one gesture recognizer may be attached to a view. In the default behavior, touch events in a multitouch sequence go from one gesture recognizer to another in a nondeterministic order until the events are finally delivered to the view (if at all). Often this default behavior is what you want. But sometimes you might want one or more of the following behaviors: ● Have one gesture recognizer fail before another can start analyzing touch events. ● Prevent other gesture recognizers from analyzing a specific multitouch sequence or a touch object in that sequence. ● Permit two gesture recognizers to operate simultaneously. The UIGestureRecognizer class provides client methods, delegate methods, and methods overridden by subclasses to enable you to effect these behaviors. Requiring a Gesture Recognizer to Fail You might want a relationship between two gesture recognizers so that one can operate only if the other one fails. For example, recognizer A doesn’t begin analyzing a multitouch sequence until recognizer B fails and, conversely, if recognizer B does recognize its gesture, recognizer A never looks at the multitouch sequence. An example where you might specify this relationship is when you have a gesture recognizer for a single tap and another gesture recognizer for a double tap; the single-tap recognizer requires the double-tap recognizer to fail before it begins operating on a multitouch sequence. The method you call to specify this relationship is requireGestureRecognizerToFail:. After sending the message, the receiving gesture recognizer must stay in the UIGestureRecognizerStatePossible state until the specified gesture recognizer transitions to UIGestureRecognizerStateFailed. If the specified gesture recognizer transitions to UIGestureRecognizerStateRecognized or UIGestureRecognizerStateBegan instead, then the receiving recognizer can proceed, but no actionmessage is sent if it recognizes its gesture. Gesture Recognizers Interacting with Other Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 46Note: In the case of the single-tap versus double-tap gestures, if a single-tap gesture recognizer doesn’t require the double-tap recognizer to fail, you should expect to receive yoursingle-tap actions before your double-tap actions, even in the case of a double tap. This is expected and desirable behavior because the best user experience generally involvesstackable actions. If you want double-tap and single-tap gesture recognizersto have mutually exclusive actions, you can require the double-tap recognizer to fail. You won't get any single-tap actions on a double tap, but any single-tap actions you do receive will necessarily lag behind the user's touch input. In other words, there is no way to know if the user double tapped until after the double-tap delay,so the single-tap gesture recognizer cannot send its action until that delay has passed. For a discussion of gesture-recognition states and possible transition between these states, see “State Transitions” (page 50). Preventing Gesture Recognizers from Analyzing Touches You can prevent gesture recognizers from looking at specific touches or from even recognizing a gesture. You can specify these “prevention” relationships using either delegation methods or overriding methods declared by the UIGestureRecognizer class. The UIGestureRecognizerDelegate protocol declares two optional methods that prevent specific gesture recognizers from recognizing gestures on a case-by-case basis: ● gestureRecognizerShouldBegin: — This method is called when a gesture recognizer attempts to transition out of UIGestureRecognizerStatePossible. Return NO to make it transition to UIGestureRecognizerStateFailed instead. (The default value is YES.) ● gestureRecognizer:shouldReceiveTouch: —This method is called before the window object calls touchesBegan:withEvent: on the gesture recognizer when there are one or more new touches. Return NO to prevent the gesture recognizer from seeing the objects representing these touches. (The default value is YES.) In addition,there are two UIGestureRecognizermethods(declared in UIGestureRecognizerSubclass.h) that effect the same behavior as these delegation methods. A subclass can override these methods to define class-wide prevention rules: - (BOOL)canPreventGestureRecognizer:(UIGestureRecognizer *)preventedGestureRecognizer; - (BOOL)canBePreventedByGestureRecognizer:(UIGestureRecognizer *)preventingGestureRecognizer; Gesture Recognizers Interacting with Other Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 47Permitting Simultaneous Gesture Recognition By default, no two gesture recognizers can attempt to recognize their gestures simultaneously. But you can change this behavior by implementing gestureRecognizer:shouldRecognizeSimultaneouslyWithGestureRecognizer:, an optional method of the UIGestureRecognizerDelegate protocol. This method is called when the recognition of the receiving gesture recognizer would block the operation of the specified gesture recognizer, or vice versa. Return YES to allow both gesture recognizers to recognize their gestures simultaneously. Note: Returning YES is guaranteed to allow simultaneous recognition, but returning NO is not guaranteed to prevent simultaneous recognition because the other gesture's delegate may return YES. Regulating the Delivery of Touches to Views Generally, a window delivers UITouch objects (packaged in UIEvent objects) to a gesture recognizer before it delivers them to the attached hit-test view. But there are some subtle detours and dead-ends in this general delivery path that depend on whether a gesture is recognized. You can alter this delivery path to suit the requirements of your application. Default Touch-Event Delivery By default a window in a multitouch sequence delays the delivery of touch objects in Ended phases to the hit-test view and, if the gesture is recognized, both prevents the delivery of current touch objects to the view and cancels touch objects previously received by the view. The exact behavior depends on the phase of touch objects and on whether a gesture recognizer recognizes its gesture or fails to recognize it in a multitouch sequence. To clarify this behavior, consider a hypothetical gesture recognizer for a discrete gesture involving two touches (that is, two fingers). Touch objects enter a system and are passed from the UIApplication object to the UIWindow object for the hit-test view. The following sequence occurs when the gesture is recognized: 1. The window sendstwo touch objectsin the Began phase (UITouchPhaseBegan) to the gesture recognizer, which doesn’t recognize the gesture. The window sends these same touches to the view attached to the gesture recognizer. 2. The window sendstwo touch objectsin the Moved phase (UITouchPhaseMoved) to the gesture recognizer, and the recognizer still doesn’t detect its gesture. The window then sends these touches to the attached view. Gesture Recognizers Regulating the Delivery of Touches to Views 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 483. The window sends one touch object in the Ended phase (UITouchPhaseEnded) to the gesture recognizer. This touch object doesn’t yield enough information for the gesture, but the window withholds the object from the attached view. 4. The window sends the other touch object in the Ended phase. The gesture recognizer now recognizes its gesture and so it sets its state to UIGestureRecognizerStateRecognized. Just before the first (or only) action message issent, the view receives a touchesCancelled:withEvent: message to invalidate the touch objects previously sent (in the Began and Moved phases). The touches in the Ended phase are canceled. Now assume that the gesture recognizer in the last step instead decides that this multitouch sequence it’s been analyzing is not its gesture. It sets its state to UIGestureRecognizerStateFailed. The window then sends the two touch objects in the Ended phase to the attached view in a touchesEnded:withEvent: message. A gesture recognizer for a continuous gesture goes through a similar sequence, except that it is more likely to recognize its gesture before touch objectsreach the Ended phase. Upon recognizing its gesture, itsetsitsstate to UIGestureRecognizerStateBegan. The window sends all subsequent touch objects in the multitouch sequence to the gesture recognizer but not to the attached view. Note: For a discussion of gesture-recognition states and possible transition between these states, see “State Transitions” (page 50). Affecting the Delivery of Touches to Views You can change the values of three UIGestureRecognizer properties to alter the default delivery path of touch objects to views in certain ways. These properties and their default values are: cancelsTouchesInView (default of YES) delaysTouchesBegan (default of NO) delaysTouchesEnded (default of YES) If you change the default values of these properties, you get the following differences in behavior: ● cancelsTouchesInView set to NO — Causes touchesCancelled:withEvent: to not be sent to the view for any touches belonging to the recognized gesture. As a result, any touch objects in Began or Moved phases previously received by the attached view are not invalidated. ● delaysTouchesBegan set to YES — Ensures that when a gesture recognizer recognizes a gesture, no touch objects that were part of that gesture are delivered to the attached view. This setting provides a behavior similar to that offered by the delaysContentTouches property on UIScrollView; in this Gesture Recognizers Regulating the Delivery of Touches to Views 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 49case, when scrolling begins soon after the touch begins, subviews of the scroll-view object never receive the touch, so there is no flash of visual feedback. You should be careful about this setting because it can easily make your interface feel unresponsive. ● delaysTouchesEnded set to NO — Prevents a gesture recognizer that's recognized its gesture after a touch has ended from canceling that touch on the view. For example, say a view has a UITapGestureRecognizer object attached with its numberOfTapsRequired set to 2, and the user double-taps the view. If this property is set to NO, the view gets the following sequence of messages: touchesBegan:withEvent:, touchesEnded:withEvent:, touchesBegan:withEvent:, and touchesCancelled:withEvent:. With the property set to YES, the view gets touchesBegan:withEvent:, touchesBegan:withEvent:, touchesCancelled:withEvent:, and touchesCancelled:withEvent:. The purpose of this property is to ensure that a view won't complete an action as a result of a touch that the gesture will want to cancel later. Creating Custom Gesture Recognizers If you are going to create a custom gesture recognizer, you need to have a clear understanding of how gesture recognizers work. The following section gives you the architectural background of gesture recognition, and the subsequent section goes into details of actually creating a gesture recognizer. State Transitions Gesture recognizers operate in a predefined state machine. They transition from one state to another depending on whether certain conditions apply. The following enum constants from UIGestureRecognizer.h define the states for gesture recognizers: typedef enum { UIGestureRecognizerStatePossible, UIGestureRecognizerStateBegan, UIGestureRecognizerStateChanged, UIGestureRecognizerStateEnded, UIGestureRecognizerStateCancelled, UIGestureRecognizerStateFailed, UIGestureRecognizerStateRecognized = UIGestureRecognizerStateEnded } UIGestureRecognizerState; Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 50The sequence of states that a gesture recognizer may transition through varies, depending on whether a discrete or continuous gesture is being recognized. All gesture recognizers start in the Possible state (UIGestureRecognizerStatePossible). They then analyze the multitouch sequence targeted at their attached hit-test view, and they either recognize their gesture or fail to recognize it. If a gesture recognizer does not recognize its gesture, it transitions to the Failed state(UIGestureRecognizerStateFailed); this is true of all gesture recognizers, regardless of whether the gesture is discrete or continuous. When a gesture is recognized, however, the state transitions differ for discrete and continuous gestures. A recognizer for a discrete gesture transitions from Possible to Recognized (UIGestureRecognizerStateRecognized). A recognizer for a continuous gesture, on the other hand, transitionsfrom Possible to Began (UIGestureRecognizerStateBegan) when it first recognizesthe gesture. Then it transitionsfrom Began to Changed (UIGestureRecognizerStateChanged), and subsequently from Changed to Changed every time there is a change in the gesture. Finally, when the last finger in the multitouch sequence is lifted from the hit-test view, the gesture recognizer transitions to the Ended state (UIGestureRecognizerStateEnded), which is an aliasfor the UIGestureRecognizerStateRecognized state. A recognizer for a continuous gesture can also transition from the Changed state to a Cancelled state (UIGestureRecognizerStateCancelled) if it determines that the recognized gesture no longer fits the expected pattern for its gesture. Figure 3-3 illustrates these transitions. Figure 3-3 Possible state transitions for gesture recognizers Possible Began Changed Cancelled Gesture cancelled — continuous gestures Possible Began Changed Ended Recognizes gestures — continuous gestures Possible Recognized Recognizes gesture — discrete gestures Possible Failed Fails to recognize gesture — all gesture recognizers Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 51Note: The Began, Changed, Ended, and Cancelled states are not necessarily associated with UITouch objects in corresponding touch phases. They strictly denote the phase of the gesture itself, not the touch objects that are being recognized. When a gesture is recognized, every subsequent state transition causes an action message to be sent to the target. When a gesture recognizer reaches the Recognized or Ended state, it is asked to reset its internal state in preparation for a new attempt at recognizing the gesture. The UIGestureRecognizer class then sets the gesture recognizer’s state back to Possible. Implementing a Custom Gesture Recognizer To implement a custom gesture recognizer, first create a subclass of UIGestureRecognizer in Xcode. Then, add the following import directive in your subclass’s header file: #import Next copy the following method declarations from UIGestureRecognizerSubclass.h to your header file; these are the methods you override in your subclass: - (void)reset; - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event; - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event; You must be sure to call the superclass implementation (super) in all of the methods you override. Examine the declaration of the state property in UIGestureRecognizerSubclass.h. Notice that it is now given a readwrite option instead of readonly (in UIGestureRecognizer.h). Your subclass can now change its state by assigning UIGestureRecognizerState constants to the property. The UIGestureRecognizer class sends action messages for you and controls the delivery of touch objects to the hit-test view. You do not need to implement these tasks yourself. Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 52Implementing the Multitouch Event-Handling Methods The heart of the implementation for a gesture recognizer are the four methods touchesBegan:withEvent:, touchesMoved:withEvent:, touchesEnded:withEvent:, and touchesCancelled:withEvent:. You implement these methods much as you would implement them for a custom view. Note: See “Handling Multi-Touch Events” in iOS App Programming Guide in “Document Revision History” for information about handling events delivered during a multitouch sequence. The main difference in the implementation of these methods for a gesture recognizer is that you transition between states at the appropriate moment. To do this, you must set the value of the state property to the appropriate UIGestureRecognizerState constant. When a gesture recognizer recognizes a discrete gesture, it sets the state property to UIGestureRecognizerStateRecognized. If the gesture is continuous, it sets the state property first to UIGestureRecognizerStateBegan; then, for each change in position of the gesture, it sets (or resets) the property to UIGestureRecognizerStateChanged. When the gesture ends, it sets state to UIGestureRecognizerStateEnded. If at any point a gesture recognizer realizes that this multitouch sequence is not its gesture, it sets its state to UIGestureRecognizerStateFailed. Listing 3-3 is an implementation of a gesture recognizer for a discrete single-touch “checkmark” gesture (actually any V-shaped gesture). It records the midpoint of the gesture—the point at which the upstroke begins—so that clients can obtain this value. Listing 3-3 Implementation of a “checkmark” gesture recognizer. - (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event { [super touchesBegan:touches withEvent:event]; if ([touches count] != 1) { self.state = UIGestureRecognizerStateFailed; return; } } - (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event { [super touchesMoved:touches withEvent:event]; if (self.state == UIGestureRecognizerStateFailed) return; CGPoint nowPoint = [[touches anyObject] locationInView:self.view]; CGPoint prevPoint = [[touches anyObject] previousLocationInView:self.view]; if (!strokeUp) { Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 53// on downstroke, both x and y increase in positive direction if (nowPoint.x >= prevPoint.x && nowPoint.y >= prevPoint.y) { self.midPoint = nowPoint; // upstroke has increasing x value but decreasing y value } else if (nowPoint.x >= prevPoint.x && nowPoint.y <= prevPoint.y) { strokeUp = YES; } else { self.state = UIGestureRecognizerStateFailed; } } } - (void)touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event { [super touchesEnded:touches withEvent:event]; if ((self.state == UIGestureRecognizerStatePossible) && strokeUp) { self.state = UIGestureRecognizerStateRecognized; } } - (void)touchesCancelled:(NSSet *)touches withEvent:(UIEvent *)event { [super touchesCancelled:touches withEvent:event]; self.midPoint = CGPointZero; strokeUp = NO; self.state = UIGestureRecognizerStateFailed; } If a gesture recognizer detects a touch (as represented by a UITouch object) that it determines is not part of its gesture, it can pass it on directly to its view. To do this, it calls ignoreTouch:forEvent: on itself, passing in the touch object. Ignored touches are not withheld from the attached view even if the value of the cancelsTouchesInView property is YES. Resetting State When your gesture recognizer transitions to either the UIGestureRecognizerStateRecognized state or theUIGestureRecognizerStateEnded state, the UIGestureRecognizer class calls the reset method of the gesture recognizer just before it winds back the gesture recognizer’s state to Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 54UIGestureRecognizerStatePossible. A gesture recognizer class should implement this method to reset any internal state so that it is ready for a new attempt at recognizing the gesture. After a gesture recognizer returns from this method, it receives no further updates for touches that have already begun but haven’t ended. Listing 3-4 Resetting a gesture recognizer - (void)reset { [super reset]; self.midPoint = CGPointZero; strokeUp = NO; } Gesture Recognizers Creating Custom Gesture Recognizers 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 55An iPhone, iPad, or iPod touch device generates motion events when users move the device in a certain way, such as shaking it or tilting it. All motion events have their origin in the device accelerometer or gyroscope. If you want to detect motions as gestures—specifically shaking motions—you should handle motion events as described in “Shaking-Motion Events” (page 56). If you want to receive and handle high-rate, continuous motion data, you should instead follow the approaches described in “Core Motion” (page 63) or “Accessing Accelerometer Events Using UIAccelerometer” (page 59). Notes: This chapter contains information that used to be in iOS App Programming Guide . The information in this chapter has not been updated specifically for iOS 4.0. Shaking-Motion Events When usersshake a device, the system evaluatesthe accelerometer data and, if that data meets certain criteria, interprets it as a shaking gesture. The system creates a UIEvent object representing this gesture and sends the event object to the currently active application for processing. Note: Motion events as a type of UIEvent were introduced in iOS 3.0. Currently, only shaking motions are interpreted as gestures and become motion events. Motion events are much simpler than touch events. The system tells an application when a motion starts and when it stops, and not when each individual motion occurs. And, whereas a touch event includes a set of touches and their related state, a motion event carries with it no state other than the event type, eventsubtype, and timestamp. The system interprets motion gesturesin a way that does not conflict with orientation changes. To receive motion events, the responder object that is to handle them must be the first responder. Listing 4-1 shows how a responder can make itself the first responder. Listing 4-1 Becoming first responder - (BOOL)canBecomeFirstResponder { return YES; 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 56 Motion Events} - (void)viewDidAppear:(BOOL)animated { [self becomeFirstResponder]; } To handle motion events, a class inheriting from UIResponder must implement either the motionBegan:withEvent: method or motionEnded:withEvent: method, or possibly both of these methods (see “Best Practices for Handling Multitouch Events” (page 37)). For example, if an application wants to give horizontal shakes and vertical shakes different meanings, it can cache the current acceleration axis values in motionBegan:withEvent:, compare those cached values to the same axis values in motionEnded:withEvent:, and act on the results accordingly. A responder should also implement the motionCancelled:withEvent: method to respond to events that the system sends to cancel a motion event; these events sometimes reflect the system’s determination that the motion is not a valid gesture after all. Listing 4-2 shows code that handles a shaking-motion event by resetting views that have have been altered (by translation, rotation, and scaling) to their original positions, orientations, and sizes. Listing 4-2 Handling a motion event - (void)motionBegan:(UIEventSubtype)motion withEvent:(UIEvent *)event { } - (void)motionEnded:(UIEventSubtype)motion withEvent:(UIEvent *)event { [UIView beginAnimations:nil context:nil]; [UIView setAnimationDuration:0.5]; self.view.transform = CGAffineTransformIdentity; for (UIView *subview in self.view.subviews) { subview.transform = CGAffineTransformIdentity; } [UIView commitAnimations]; for (TransformGesture *gesture in [window allTransformGestures]) { Motion Events Shaking-Motion Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 57[gesture resetTransform]; } } - (void)motionCancelled:(UIEventSubtype)motion withEvent:(UIEvent *)event { } An application and its key window deliver a motion event to a window’s first responder for handling. If the first responder doesn’t handle it, the event progresses up the responder chain in the same way touch events do until it is either handled or ignored. (See “Event Delivery” (page 11) for details.) However, there is one important difference between touch events and shaking-motion events. When the user starts shaking the device, the system sends a motion event to the first responder in a motionBegan:withEvent: message; if the first responder doesn’t handle the event, it travels up the responder chain. If the shaking lasts less than a second or so, the system sends a motionEnded:withEvent: message to the first responder. But if the shaking lasts longer or if the system determines the motion is not a shake, the first responder receives a motionCancelled:withEvent: message. If a shaking-motion event travels up the responder chain to the window without being handled and the applicationSupportsShakeToEdit property of UIApplication is set to YES, iOS displays a sheet with Undo and Redo commands. By default, this property is set to YES. Getting the Current Device Orientation If you need to know only the general orientation of the device, and not the exact vector of orientation, you should use the methods of the UIDevice class to retrieve that information. Using the UIDevice interface is simple and does not require that you calculate the orientation vector yourself. Before getting the current orientation, you must tell the UIDevice classto begin generating device orientation notifications by calling the beginGeneratingDeviceOrientationNotifications method. Doing so turns on the accelerometer hardware (which may otherwise be off to conserve power). Shortly after enabling orientation notifications, you can get the current orientation from the orientation property of the shared UIDevice object. You can also register to receive UIDeviceOrientationDidChangeNotification notifications, which are posted whenever the general orientation changes. The device orientation is reported using the UIDeviceOrientation constants, which Motion Events Getting the Current Device Orientation 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 58indicate whether the device is in landscape or portrait mode or whether the device is face up or face down. These constants indicate the physical orientation of the device and need not correspond to the orientation of your application’s user interface. When you no longer need to know the orientation of the device, you should always disable orientation notifications by calling the endGeneratingDeviceOrientationNotifications method of UIDevice. Doing so gives the system the opportunity to disable the accelerometer hardware if it is not in use elsewhere. Setting Required Hardware Capabilities for Accelerometer and Gyroscope Events If your application requires device-related featuresin order to run—such asthe ability to receive accelerometer data—you must add a list of required capabilitiesto your application. At runtime, iOS launches your application only if those capabilities are present on the device. Furthermore, the App Store uses the information in this key to generate a list of requirements for user devices and prevent users from downloading applications that they cannot run. You declare your application’s required capabilities by adding the UIRequiredDeviceCapabilities key to your application’s Info.plist file. This key, supported in iOS 3.0 and later, has a value that is either an array or a dictionary. If you use an array, the presence of a given key indicates the corresponding feature is required. If you use a dictionary, you must specify a Boolean value for each key indicating whether the feature is required. In both cases, having no key for a feature indicates that the feature is not required. The following UIRequiredDeviceCapabilities keys are for motion events, based on hardware source: ● accelerometer (for accelerometer events) You do not need to include this key if your application detects only device orientation changes or if your application handles shaking-motion events delivered via UIEvent objects. ● gyroscope (for gyroscope events) Accessing Accelerometer Events Using UIAccelerometer Every application has a single UIAccelerometer object that can be used to receive acceleration data. You get the instance of this class using the sharedAccelerometer class method of UIAccelerometer. Using this object, you set the desired reporting interval and a custom delegate to receive acceleration events. You can set the reporting interval to be as small as 10 milliseconds (ms), which corresponds to a 100 Hz update Motion Events Setting Required Hardware Capabilities for Accelerometer and Gyroscope Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 59rate, although most applications can operate sufficiently with a larger interval. As soon as you assign your delegate object, the accelerometerstartssending it data. Thereafter, your delegate receives data at the requested update interval. Listing 4-3 shows the basic steps for configuring an accelerometer. In this example, the update frequency is 50 Hz, which corresponds to an update interval of 20 ms. The myDelegateObject is a custom object that you define; it must support the UIAccelerometerDelegate protocol, which defines the method used to receive acceleration data. Listing 4-3 Configuring the accelerometer #define kAccelerometerFrequency 50.0 //Hz -(void)configureAccelerometer { UIAccelerometer* theAccelerometer = [UIAccelerometer sharedAccelerometer]; theAccelerometer.updateInterval = 1 / kAccelerometerFrequency; theAccelerometer.delegate = self; // Delegate events begin immediately. } At regular intervals, the shared accelerometer object delivers event data to your delegate’s accelerometer:didAccelerate: method, shown in Listing 4-4. You can use this method to process the accelerometer data however you want. In general it is recommended that you use some sort of filter to isolate the component of the data in which you are interested. Listing 4-4 Receiving an accelerometer event - (void)accelerometer:(UIAccelerometer *)accelerometer didAccelerate:(UIAcceleration *)acceleration { UIAccelerationValue x, y, z; x = acceleration.x; y = acceleration.y; z = acceleration.z; // Do something with the values. } Motion Events Accessing Accelerometer Events Using UIAccelerometer 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 60To stop the delivery of acceleration events, set the delegate of the shared UIAccelerometer object to nil. Setting the delegate object to nil lets the system know that it can turn off the accelerometer hardware as needed and thus save battery life. The acceleration data you receive in your delegate method represents the instantaneous values reported by the accelerometer hardware. Even when a device is completely at rest, the values reported by this hardware can fluctuate slightly. When using these values, you should be sure to account for these fluctuations by averaging out the values over time or by calibrating the data you receive. For example, the Bubble Levelsample application provides controls for calibrating the current angle against a known surface. Subsequent readings are then reported relative to the calibrated angle. If your own code requires a similar level of accuracy, you should also include a calibration option in your user interface. Choosing an Appropriate Update Interval When configuring the update interval for acceleration events, it is best to choose an interval that minimizes the number of delivered events and still meetsthe needs of your application. Few applications need acceleration events delivered 100 times a second. Using a lower frequency prevents your application from running as often and can therefore improve battery life. Table 4-1 lists some typical update frequencies and explains what you can do with the acceleration data generated at that frequency. Table 4-1 Common update intervals for acceleration events Event frequency (Hz) Usage Suitable for use in determining the vector representing the current orientation of the device. 10–20 Suitable for games and other applications that use the accelerometers for real-time user input. 30–60 Suitable for applications that need to detect high-frequency motion. For example, you might use this interval to detect the user hitting the device or shaking it very quickly. 70–100 Isolating the Gravity Component from Acceleration Data If you are using the accelerometer data to detect the current orientation of a device, you need to be able to filter out the portion of the acceleration data caused by gravity from the portion of the data that is caused by motion of the device. To do this, you can use a low-pass filter to reduce the influence of sudden changes on the accelerometer data. The resulting filtered values then reflect the more constant effects of gravity. Motion Events Accessing Accelerometer Events Using UIAccelerometer 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 61Listing 4-5 shows a simplified version of a low-pass filter. This example uses a low-value filtering factor to generate a value that uses 10 percent of the unfiltered acceleration data and 90 percent of the previously filtered value. The previous values are stored in the accelX, accelY, and accelZ member variables of the class. Because acceleration data comes in regularly, these values settle out quickly and respond slowly to sudden but short-lived changes in motion. Listing 4-5 Isolating the effects of gravity from accelerometer data #define kFilteringFactor 0.1 - (void)accelerometer:(UIAccelerometer *)accelerometer didAccelerate:(UIAcceleration *)acceleration { // Use a basic low-pass filter to keep only the gravity component of each axis. accelX = (acceleration.x * kFilteringFactor) + (accelX * (1.0 - kFilteringFactor)); accelY = (acceleration.y * kFilteringFactor) + (accelY * (1.0 - kFilteringFactor)); accelZ = (acceleration.z * kFilteringFactor) + (accelZ * (1.0 - kFilteringFactor)); // Use the acceleration data. } Isolating Instantaneous Motion from Acceleration Data If you are using accelerometer data to detect just the instant motion of a device, you need to be able to isolate sudden changes in movement from the constant effect of gravity. You can do that with a high-pass filter. Listing 4-6 shows a simplified high-pass filter computation. The acceleration values from the previous event are stored in the accelX, accelY, and accelZ member variables of the class. This example computes the low-pass filter value and then subtracts it from the current value to obtain just the instantaneous component of motion. Listing 4-6 Getting the instantaneous portion of movement from accelerometer data #define kFilteringFactor 0.1 - (void)accelerometer:(UIAccelerometer *)accelerometer didAccelerate:(UIAcceleration *)acceleration { Motion Events Accessing Accelerometer Events Using UIAccelerometer 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 62// Subtract the low-pass value from the current value to get a simplified high-pass filter accelX = acceleration.x - ( (acceleration.x * kFilteringFactor) + (accelX * (1.0 - kFilteringFactor)) ); accelY = acceleration.y - ( (acceleration.y * kFilteringFactor) + (accelY * (1.0 - kFilteringFactor)) ); accelZ = acceleration.z - ( (acceleration.z * kFilteringFactor) + (accelZ * (1.0 - kFilteringFactor)) ); // Use the acceleration data. } Core Motion Core Motion is a system framework that obtains motion data from sensors on a device and presents that data to applicationsfor processing. The handling of the sensor data and the application of related algorithms occurs on Core Motion’s own thread. The items of hardware that detect and originate these motion events are the accelerometer and the gyroscope. (The gyroscope is currently available only on iPhone 4.) Core Motion publishes an Objective-C programmatic interface that enables applications to receive device-motion data of various types, which they can then process in appropriate ways. As illustrated by Figure 4-1 (page 64), Core Motion defines a manager class, CMMotionManager, and three classes whose instances encapsulate measurements of motion data of various types: ● A CMAccelerometerData object encapsulates a data structure that records a measurement of device acceleration along the three spatial axes. This data derives from the accelerometer. For more on CMAccelerometerData, see “Handling Accelerometer Events Using Core Motion” (page 65). ● A CMGyroData object encapsulates a data structure that records a biased estimate of a device’s rate of rotation along the three spatial axes. This “raw” data derives from the gyroscope. (“Biased” in this context refers to an offset from the true rotation rate. Thus, if the device is not rotating, this estimate from the gyroscope will still give a non-zero value.) For more on CMGyroData, see “Handling Rotation-Rate Data” (page 68). ● A CMDeviceMotion object encapsulates processed device-motion data that derives from both the accelerometer and the gyroscope. Core Motion’s sensor fusion algorithms process both accelerometer and gyroscope data and provide an application with highly accurate measurements of device attitude, the (unbiased) rotation rate of a device, the direction of gravity on a device, and the acceleration that the Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 63user is giving to a device. A CMAttitude object, which is contained in an CMDeviceMotion instance, contains properties giving different measurements of attitude, including the Euler angles indicated by roll, pitch, and yaw. Attitude refers to the orientation of a device in three dimensions relative to a reference frame that is external to the device. For more on attitude and CMDeviceMotion,see “Handling Processed Device-Motion Data” (page 72). Figure 4-1 Core Motion classes Core Motion Framework CMMotionManager CMAccelerometerData CMDeviceMotion CMGyroData CMAttitude All of the data-encapsulating classes of Core Motion are subclasses of CMLogItem, which defines a timestamp so that motion data can be tagged with the event time and logged to a file. An application can also compare the timestamp of motion events with earlier motion events to determine the true update interval between events. For each of the data-motion types described above, the CMMotionManager class offers two approaches for obtaining motion data, a push approach and a pull approach: ● Push. An application requests an update interval and implements a block (of a specific type) for handling the motion data; it then starts updatesfor that type of motion data, passing into Core Motion an operation queue as well as the block. Core Motion delivers each update to the block, which executes as a task in the operation queue. ● Pull. An application starts updates of a type of motion data and periodically samples the most recent measurement of motion data. The pull approach is the recommended approach for most applications, especially games; it is generally more efficient and requires less code. The push approach is appropriate for data-collection applications and similar applications that cannot miss a sample measurement. Both approaches have benign thread-safety effects; with the push approach, your block executes on the operation-queue’sthread whereas, with the pull approach, Core Motion never interrupts your threads. Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 64Important: An application should create only a single instance of the CMMotionManager class. Multiple instances of this class can affect the rate at which an application receives data from the accelerometer and gyroscope. Be aware that there is no simulator support for application features related to Core Motion. You have to test and debug applications on a device. Handling Accelerometer Events Using Core Motion Core Motion provides an alternative programmatic interface to UIAccelerometer for accessing accelerometer events. Each of these events is an instance of CMAccelerometerData that encapsulates a measurement of accelerometer activity in a structure of type CMAcceleration. – Z + Z + Y – Y – X + X To start receiving and handling accelerometer data, create an instance of the CMMotionManager class and call one of the following two methods on it: ● startAccelerometerUpdates After this method is called, Core Motion continuously updates the accelerometerData property of CMMotionManager with the latest measurement of accelerometer activity. The application periodically samples this property, usually in a render loop typical of games. If you adopt this polling approach, you should set the update-interval property (accelerometerUpdateInterval) to the maximum interval at which Core Motion performs updates. (Core Motion might perform updates at a faster rate, however.) Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 65The code examples in this section illustrate this first approach. ● startAccelerometerUpdatesToQueue:withHandler: Before calling this method, the application assigns an update interval to the accelerometerUpdateInterval property. It also creates an instance of NSOperationQueue and implements a block of the CMAccelerometerHandler type that handles the accelerometer updates. Then it calls startAccelerometerUpdatesToQueue:withHandler: on the motion-manager object, passing in the operation queue and the block. At the specified update interval, Core Motion passes the latest sample of accelerometer activity to the block, which executes as a task in the queue. You should stop updates of motion data as soon as your application is finished processing the data. Doing so allows Core Motion to turn off motion sensors, thereby saving battery power. For Core Motion accelerometer events, you configure the update interval exactly as you do when using UIAccelerometer. You must identify an interval suitable for your application and then assign that value (expressed asseconds) to the accelerometerUpdateInterval property. If you prefer to think of the update interval in terms of cycles per second (Hertz), divide 1 by the desired Hertz value to get the update-interval value. Listing 4-3 (page 60) gives an example. (“Choosing an Appropriate Update Interval” (page 61) offers guidance for choosing a suitable update interval.) The following code examples are based on the OpenGL ES project template in Xcode. An OpenGL ES application periodically samples device-motion updates using the render loop itsets up for drawing its view. The application first declares an instance variable—a three-member C array—to hold the acceleration values: double filteredAcceleration[3]; Asshown in Listing 4-7, the application creates an instance of CMMotionManager in the same template method used for configuring and scheduling the timing mechanism of the render loop (startAnimation). The application then assigns an appropriate accelerometer-update interval to the motion manager, allocates memory for the C array, and starts accelerometer updates. Note that the application stops accelerometer updates in the same template method (stopAnimation) used for invalidating the timing mechanism of the render loop. Listing 4-7 Configuring the motion manager and starting updates - (void)startAnimation { if (!animating) { // code that configures and schedules CADisplayLink or timer here ... } Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 66motionManager = [[CMMotionManager alloc] init]; // motionManager is an instance variable motionManager.accelerometerUpdateInterval = 0.01; // 100Hz memset(filteredAcceleration, 0, sizeof(filteredAcceleration)); [motionManager startAccelerometerUpdates]; } - (void)stopAnimation { if (animating) { // code that invalidates CADisplayLink or timer here... } [motionManager stopAccelerometerUpdates]; } In the OpenGL ES application template, the drawView method is invoked at each cycle of the render loop. Listing 4-8 shows how the application, in this same method, gets the latest accelerometer data and runs it through a low-pass filter. It then updates the drawing model with the filtered acceleration values and renders its view. Listing 4-8 Sampling and filtering accelerometer data - (void)drawView { // alpha is the filter value (instance variable) CMAccelerometerData *newestAccel = motionManager.accelerometerData; filteredAcceleration[0] = filteredAcceleration[0] * (1.0-alpha) + newestAccel.acceleration.x * alpha; filteredAcceleration[1] = filteredAcceleration[1] * (1.0-alpha) + newestAccel.acceleration.y * alpha; filteredAcceleration[2] = filteredAcceleration[2] * (1.0-alpha) + newestAccel.acceleration.z * alpha; [self updateModelsWithAcceleration:filteredAcceleration]; [renderer render]; } Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 67Note: You can apply a low-pass or high-pass filter to acceleration values and thereby isolate the gravity and user-acceleration components: ● To apply a low-pass filter, thereby isolating the gravity component, see “Isolating the Gravity Component from Acceleration Data” (page 61). ● To apply a high-pass filter, thereby isolating the user-acceleration component, see “Isolating Instantaneous Motion from Acceleration Data” (page 62) (which refers to the user-acceleration component as “instantaneous motion.”) Your application can also receive the gravity-caused and user-caused components of acceleration directly from Core Motion by receiving and handling device-motion updatesinstead of accelerometer updates. See “Handling Processed Device-Motion Data” (page 72) for information. Handling Rotation-Rate Data A gyroscope measures the rate at which a device rotates around each of the three spatial axes. (Compare this with the accelerometer, which measures the acceleration of the device along each of the three spatial axes.) For each requested gyroscope update, Core Motion takes a biased estimate of the rate of rotation and returns this information to an application in the form of a CMGyroData object. The object has a rotationRate property through which you can access a CMRotationRate structure that capturesthe rotation rate (in radians per second) for each of the three axes. Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 68Note: The measurement of rotation rate encapsulated by a CMGyroData object is biased. You can obtain a much more accurate (unbiased) measurement by accessing the rotationRate property of CMDeviceMotion. – Z + Z + Y – Y – X + X To start receiving and handling rotation-rate data, create an instance of the CMMotionManager class and call one of the following two methods on it: ● startGyroUpdates Afterthismethod is called, Core Motion continuously updatesthe gyroData property of CMMotionManager with the latest measurement of gyroscope activity. The application periodically samples this property, usually in a render loop that is typical of games. If you adopt this polling approach, you should set the update-interval property (gyroUpdateInterval) to the maximum interval at which Core Motion performs updates. (Core Motion might perform updates at a faster rate, however.) ● startGyroUpdatesToQueue:withHandler: Before calling this method, the application assigns an update interval to the gyroUpdateInterval property. It also creates an instance of NSOperationQueue and implements a block of the CMGyroHandler type that handles the gyroscope updates. Then it calls startGyroUpdatesToQueue:withHandler: on the motion-manager object, passing in the operation queue and the block. At the specified update interval, Core Motion passes the latest sample of gyroscope activity to the block, which executes as a task in the queue. Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 69The code examples in this section illustrate this approach. You should stop updates of motion data as soon as your application is finished processing the data. Doing so allows Core Motion to turn off motion sensors, thereby saving battery power. When configuring the update interval for rotation-rate (gyroscope) events, identify an intervalsuitable for your application and then assign that value (expressed as seconds) to the gyroUpdateInterval property. If you prefer to think of the update interval in terms of cycles per second (Hertz), divide 1 by the desired Hertz value to get the update-interval value. Listing 4-3 (page 60) in “Choosing an Appropriate Update Interval” (page 61) gives an example in the context of accelerometer updates. The following code segments illustrate how to start gyroscope updates by calling the startGyroUpdatesToQueue:withHandler: method. In Listing 4-9, a view controller in its viewDidLoad instantiates a CMMotionManager object and assigns an update interval for gyroscope data. If the device has a gyroscope, the view controller creates an NSOperationQueue object and defines a block handler for gyroscope updates. Listing 4-9 Creating the CMMotionManager object and setting up for gyroscope updates - (void)viewDidLoad { [super viewDidLoad]; motionManager = [[CMMotionManager alloc] init]; motionManager.gyroUpdateInterval = 1.0/60.0; if (motionManager.gyroAvailable) { opQ = [[NSOperationQueue currentQueue] retain]; gyroHandler = ^ (CMGyroData *gyroData, NSError *error) { CMRotationRate rotate = gyroData.rotationRate; // handle rotation-rate data here...... }; } else { NSLog(@"No gyroscope on device."); toggleButton.enabled = NO; [motionManager release]; } } Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 70When analyzing rotation-rate data—that is, the fields of the CMRotationMatrix structure—follow the “right-hand rule” to determine the direction of rotation (see Figure 4-2 (page 71)). For example, if you wrap your right hand around the X axis such that the tip of the thumb points toward positive X, a positive rotation is one toward the tips of the other 4 fingers. A negative rotation goes away from the tips of those fingers. Figure 4-2 Right-hand rule When the user taps a button, an action message is sent to the view controller. The view controller implements the action method to toggle between starting updates and stopping updates. Listing 4-10 shows how it does this. Listing 4-10 Starting and stopping gyroscope updates - (IBAction)toggleGyroUpdates:(id)sender { if ([[(UIButton *)sender currentTitle] isEqualToString:@"Start"]) { [motionManager startGyroUpdatesToQueue:opQ withHandler:gyroHandler]; } else { [motionManager stopGyroUpdates]; } } Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 71Handling Processed Device-Motion Data If a device has an accelerometer and a gyroscope, Core Motion offers a device-motion service that reads raw motion data from both sensors. The service uses sensor fusion algorithms to refine the raw data and generate information on a device’s attitude, its unbiased rotation rate, the direction of gravity on a device, and the acceleration that the user imparts to a device. An instance of the CMDeviceMotion class encapsulates this data. You can access attitude data through the attitude property of a CMDeviceMotion object. An instance of the CMAttitude class encapsulates a measurement of attitude. This class defines three mathematical representations of attitude: ● a quaternion ● a rotation matrix ● the three Euler angles (roll, pitch, and yaw) Because the device-motion service returns gravity and user acceleration as separate items of data, there is no need to filter the acceleration data. To start receiving and handling device-motion updates, create an instance of the CMMotionManager class and call one of the following two methods on it: ● startDeviceMotionUpdates After this method is called, Core Motion continuously updates the deviceMotion property of CMMotionManager with the latest refined measurements of accelerometer and gyroscope activity (as encapsulated in a CMDeviceMotion object). The application periodically samples this property, usually in a render loop that is typical of games. If you adopt this polling approach, you should set the update-interval property (deviceMotionUpdateInterval) to the maximum interval at which Core Motion performs updates. (Core Motion might perform updates at a faster rate, however.) The code examples in this section illustrate this approach. ● startDeviceMotionUpdatesToQueue:withHandler: Before calling this method, the application assigns an update interval to the deviceMotionUpdateInterval property. It also creates an instance of NSOperationQueue and implements a block of the CMDeviceMotionHandler type that handlesthe accelerometer updates. Then it calls startDeviceMotionUpdatesToQueue:withHandler: on themotion-manager object, passing in the operation queue and the block. At the specified update interval, Core Motion passes the latest sample of combined accelerometer and gyroscope activity (asrepresented by a CMDeviceMotion object) to the block, which executes as a task in the queue. Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 72You should stop updates of motion data as soon as your application is finished processing the data. Doing so allows Core Motion to turn off motion sensors, thereby saving battery power. When configuring the update interval for device-motion events, identify an intervalsuitable for your application and then assign that value (expressed as seconds) to the deviceMotionUpdateInterval property. If you prefer to think of the update interval in terms of cycles per second (Hertz), divide 1 by the desired Hertz value to get the update-interval value. Listing 4-3 (page 60) in “Choosing an Appropriate Update Interval” (page 61) gives an example of this in the context of accelerometer updates. An Example of Handling Device-Motion Data The following code examples are based on the OpenGL ES project template in Xcode. An OpenGL ES application periodically samples device-motion updates using the render loop it sets up for drawing the view. In Listing 4-11, the application creates an instance of CMMotionManager in initWithCoder: and assigns this object to an instance variable. It also specifies a minimum update interval for device-motion data. The application then starts device-motion updates when the OpenGL view schedules the render loop; it stops device-motion updates when the view invalidates that loop. Listing 4-11 Starting and stopping device-motion updates - (id)initWithCoder:(NSCoder*)coder { if ((self = [super initWithCoder:coder])) { motionManager = [[CMMotionManager alloc] init]; motionManager.deviceMotionUpdateInterval = 0.02; // 50 Hz // other initialization code here... } } - (void)startAnimation { if (!animating) { // code that configures and schedules CADisplayLink or timer here ... } if ([motionManager.isDeviceMotionAvailable]) [motionManager startDeviceMotionUpdates]; } - (void)stopAnimation { if (animating) { Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 73// code that invalidates CADisplayLink or timer here... } if ([motionManager.isDeviceMotionActive]) [motionManager stopDeviceMotionUpdates]; } Note that if device-motion services are not available—most likely because the device lacks a gyroscope—you might want to implement an alternative approach that responds to device motion by handling accelerometer data. Device Attitude and the Reference Frame A particularly useful bit of information yielded by a CMDeviceMotion object is device attitude. From a practical standpoint, an even more useful bit of information is the change in device attitude. The attitude, or spatial orientation of a device is always measured in relation to a reference frame. Core Motion establishesthe reference frame when your application starts device-motion updates. An instance of CMAttitude gives the rotation from thisinitial reference frame to the device's current reference frame. Core Motion'sreference frame is always chosen so that the z-axis is always vertical, and the x-axis and y-axis are always orthogonal to gravity. When expressed in Core Motion's reference frame, gravity is always the vector [0, 0, -1]; this is called the gravity reference. If you multiply the rotation matrix obtained from a CMAttitude object by the gravity reference, you get gravity in the device's frame. Or, mathematically: 0 0 -1 deviceMotion.gravity = R You can change the reference frame used by a CMAttitude instance. To do that, cache the attitude object that containsthat reference frame and passthat asthe argument to multiplyByInverseOfAttitude:. The attitude argument receiving the message is changed to represent the change in attitude from that reference frame. To see how this might be useful, consider a baseball game where the user rotatesthe device to swing. Normally, at the beginning of a pitch, the bat would be atsome resting orientation. After that, the bat would be rendered at an orientation determined by how the device's attitude had changed from where it was at the start of a pitch. Listing 4-12 illustrates how you might do this. Listing 4-12 Getting the change in attitude prior to rendering -(void) startPitch { Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 74// referenceAttitude is an instance variable referenceAttitude = [motionManager.deviceMotion.attitude retain]; } - (void)drawView { CMAttitude *currentAttitude = motionManager.deviceMotion.attitude; [currentAttitude multiplyByInverseOfAttitude: referenceAttitude]; // render bat using currentAttitude ..... [self updateModelsWithAttitude:currentAttitude]; [renderer render]; } After multiplyByInverseOfAttitude: returns, currentAttitude in this example representsthe change in attitude (that is, the rotation) from referenceAttitude to the most recently sampled CMAttitude instance. Motion Events Core Motion 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 75Remote-control events let users control application multimedia through the system transport controls or through an external accessory. If your application plays audio or video content as a feature, you might want to write the code that enables it to respond to remote-control events. These events originate either from the transport controls or as commands issued by external accessories (such as a headset) that conform to an Apple-provided specification. iOS converts these commands into UIEvent objects that it delivers to an application. The application sends them to the first responder and, if the first responder doesn’t handle them, they go up the responder chain. The following sections describe how to prepare your application for receiving remote-control events and how to handle them. The code examples are taken from the Audio Mixer (MixerHost) sample code project. Preparing Your Application for Remote-Control Events To receive remote-control events, the view or view controller managing the presentation of multimedia content must be the first responder. It (or some other object in the application) must also tell the application object that it is ready to receive remote-control events. To make itself capable of becoming first responder, the view or view controllershould override the UIResponder method canBecomeFirstResponder to return YES. It should also send itself the becomeFirstResponder at an appropriate time, such as (for view controllers) in an override of the viewDidAppear: method. Listing 5-1 shows this call and also shows something else: The view controller calls the beginReceivingRemoteControlEvents method of UIApplication to “turn on” the delivery of remote-control events. Listing 5-1 Preparing to receive remote-control events - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [[UIApplication sharedApplication] beginReceivingRemoteControlEvents]; [self becomeFirstResponder]; } 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 76 Remote Control of MultimediaWhen the view or view controller is no longer managing audio or video, it should turn off the delivery of remote-control events and resign first-responderstatus by implementing the viewWillDisappear:asshown in Listing 5-2. Listing 5-2 Ending the receipt of remote-control events - (void)viewWillDisappear:(BOOL)animated { [[UIApplication sharedApplication] endReceivingRemoteControlEvents]; [self resignFirstResponder]; [super viewWillDisappear:animated]; } Handling Remote-Control Events To handle remote-control events, the first responder must implement the remoteControlReceivedWithEvent: method declared by UIResponder. The method implementation should evaluate the subtype of each UIEvent object passed in and send the appropriate message to the object presenting the audio or video content. The example in Listing 5-3 sends play, pause, and stop messages to an audio object. Listing 5-3 Handling remote-control events - (void) remoteControlReceivedWithEvent: (UIEvent *) receivedEvent { if (receivedEvent.type == UIEventTypeRemoteControl) { switch (receivedEvent.subtype) { case UIEventSubtypeRemoteControlTogglePlayPause: [self playOrStop: nil]; break; case UIEventSubtypeRemoteControlPreviousTrack: [self previousTrack: nil]; break; case UIEventSubtypeRemoteControlNextTrack: Remote Control of Multimedia Handling Remote-Control Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 77[self nextTrack: nil]; break; default: break; } } } Other remote-control UIEvent subtypes are possible. See UIEvent Class Reference for details. You can test your application’s receipt and handling of remote-control events by using the Now Playing Controls. These controls are available on recent models of device (for iPhone, iPhone 3GS and later) that are running iOS 4.0 or later. To access these controls, double-press the Home button, then flick left or right along the bottom of the screen until you find the audio playback controls. These controlssend remote-control events to the application that is currently or was most recently playing audio; the icon to the right of the playback controls represents the application. For testing purposes, you can programmatically make your application begin audio playback and then test the remote-control events sent to your application by tapping the Now Playing Controls. Note that a deployed application should not programmatically begin playback; that should always be done by the user. Remote Control of Multimedia Handling Remote-Control Events 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 78This table describes the changes to Event Handling Guide for iOS . Date Notes 2011-03-10 Made some minor corrections. 2010-09-29 Made some minor corrections and clarifications. 2010-08-12 Corrected code snippet in "Remote Control of Multimedia" Corrected code examples and related text in "Remote Control of Multimedia" chapter. Made other minor corrections. 2010-08-03 Changed the title from "Event Handling Guide for iPhone OS" and changed "iPhone OS" to "iOS" throughout. Updated the section on the Core Motion framework. 2010-07-09 First version of a document that describes how applications can handle multitouch, motion, and other events. 2010-05-18 2011-03-10 | © 2011 Apple Inc. All Rights Reserved. 79 Document Revision HistoryApple Inc. © 2011 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, iPad, iPhone, iPod, iPod touch, Objective-C, Shake, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Multi-Touch is a trademark of Apple Inc. App Store is a service mark of Apple Inc. OpenGL is a registered trademark of Silicon Graphics, Inc. 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. iPod nano Features Guide2 2 Contents Chapter 1 4 iPod nano Basics 5 iPod nano at a Glance 5 Using iPod nano Controls 8 Disabling iPod nano Controls 9 Using iPod nano Menus 10 Connecting and Disconnecting iPod nano 14 About the iPod nano Battery Chapter 2 17 Music Features 17 About iTunes 18 Importing Music into Your iTunes Library 22 Organizing Your Music 22 Adding Music and Podcasts to iPod nano 26 Playing Music 31 Watching and Listening to Podcasts 32 Listening to Audiobooks 32 Listening to FM Radio Chapter 3 33 Video Features 33 Purchasing or Renting Videos and Downloading Video Podcasts 34 Converting Your Own Videos to Work with iPod nano 35 Adding Videos to iPod nano 37 Viewing and Listening to Videos Chapter 4 40 Photo Features 40 Importing Photos 43 Viewing Photos Chapter 5 46 Extra Features and Accessories 46 Using iPod nano as an External Disk 47 Using Extra Settings 51 Syncing Contacts, Calendars, and To-Do Lists 53 Storing and Reading NotesContents 3 54 Recording Voice Memos 54 Learning About iPod nano Accessories Chapter 6 56 Tips and Troubleshooting 56 General Suggestions 61 Updating and Restoring iPod Software Chapter 7 62 Safety and Cleaning 62 Important Safety Information 64 Important Handling Information Chapter 8 65 Learning More, Service, and Support Index 681 4 1 iPod nano Basics Congratulations on purchasing iPod nano. Read this chapter to learn about the features of iPod nano, how to use its controls, and more. To use iPod nano, you put music, videos, photos, and other files on your computer and then add them to iPod nano. iPod nano is a music player and much more. Use iPod nano to:  Sync songs, videos, and digital photos for listening and viewing on the go  Listen to podcasts, downloadable audio and video shows delivered over the Internet  View video on iPod nano, or on a TV using an optional cable  View photos as a slideshow with music on iPod nano, or on a TV using an optional cable  Listen to audiobooks purchased from the iTunes Store or audible.com  Store or back up files and other data, using iPod nano as an external disk  Sync contact, calendar, and to-do list information from your computer  Play games, store text notes, set an alarm, and moreChapter 1 iPod nano Basics 5 iPod nano at a Glance Get to know the controls on iPod nano: Using iPod nano Controls The controls on iPod nano are easy to find and use. Press any button to turn on iPod nano. The main menu appears. Use the Click Wheel and Center button to navigate through onscreen menus, play songs, change settings, and view information. Move your thumb lightly around the Click Wheel to select a menu item. To choose the item, press the Center button. To go back to the previous menu, press Menu on the Click Wheel. Dock connector Menu Previous/Rewind Play/Pause Hold switch Headphones port Click Wheel Next/Fast-forward Center button6 Chapter 1 iPod nano Basics Here’s what else you can do with iPod nano controls. To Do this Turn on iPod nano Press any button. Turn off iPod nano Press and hold Play/Pause (’). Turn on the backlight Press any button or use the Click Wheel. Disable the iPod nano controls (so nothing happens if you press them accidentally) Slide the Hold switch to HOLD (an orange bar appears). Reset iPod nano (if it isn’t responding) Slide the Hold switch to HOLD and back again. Press the Menu and Center buttons at the same time for about 6 seconds, until the Apple logo appears. Choose a menu item Scroll to the item and press the Center button. Go back to the previous menu Press Menu. Go directly to the main menu Press and hold Menu. Browse for a song From the main menu, choose Music. Browse for a video From the main menu, choose Videos. Play a song or video Select the song or video and press the Center or Play/Pause (’) button. iPod nano has to be ejected from your computer to play songs and videos. Pause a song or video Press Play/Pause (’) or unplug your headphones. Change the volume From the Now Playing screen, use the Click Wheel. Play all the songs in a playlist or album Select the playlist or album and press Play/Pause (’). Play all songs in random order From the main menu, choose Shuffle Songs. You can also shuffle songs from the Now Playing screen. Skip to any point in a song or video From the Now Playing screen, press the Center button to show the scrubber bar (a diamond icon on the bar shows the current location), and then scroll to any point in the song or video. Skip to the next song or chapter in an audiobook or podcast Press Next/Fast-forward (‘). Start a song or video over Press Previous/Rewind (]). Play the previous song or chapter in an audiobook or podcast Press Previous/Rewind (]) twice. Fast-forward or rewind a song Press and hold Next/Fast-forward (‘) or Previous/Rewind (]). Add a song to the On-The-Go playlist Select a song in a playlist, and then press and hold the Center button until the song title flashes. Find the iPod nano serial number From the main menu, choose Settings > About and press the Center button until you get to the serial number, or look on the back of iPod nano.Chapter 1 iPod nano Basics 7 Browsing Music Using Cover Flow You can browse your music collection using Cover Flow, a visual way to flip through your library. To use Cover Flow: 1 From the Music menu, choose Cover Flow. 2 Use the Click Wheel to move through your album art or press the Next/Fast-forward and Previous/Rewind buttons. 3 Select an album and press the Center button. 4 Use the Click Wheel to select a song and press the Center button to play it. Scrolling Quickly Through Long Lists If you have more than 100 songs, videos, or other items, you can scroll quickly through a long list by moving your thumb quickly on the Click Wheel. Note: Not all languages are supported. To scroll quickly: 1 Move your thumb quickly on the Click Wheel, to display a letter of the alphabet on the screen. 2 Use the Click Wheel to navigate the alphabet until you find the first letter of the item you’re looking for. This takes you to the first item in the list beginning with that letter. Items beginning with a symbol or number appear before the letter “A.” 3 Lift your thumb momentarily to return to normal scrolling. 4 Use the Click Wheel to finish navigating to the item you want. Searching Music You can search iPod nano for songs, playlists, album titles, artist names, audio podcasts, and audiobooks. The search feature doesn’t search videos, notes, calendar items, contacts, or lyrics. Note: Not all languages are supported. To search iPod nano: 1 From the Music menu, choose Search. 2 Enter a search string by using the Click Wheel to navigate the alphabet and pressing the Center button to enter each character. iPod nano starts searching as soon as you enter the first character, displaying the results on the search screen. For example, if you enter “b,” then iPod nano displays all music items containing the letter “b.” If you enter “ab,” iPod nano displays all items containing that sequence of letters. To enter a space, press the Next/Fast-forward button.8 Chapter 1 iPod nano Basics To delete the previous character, press the Previous/Rewind button. 3 Press Menu to display the results list, which you can now navigate. Items appear in the results list with icons identifying their type: song, video, artist, album, audiobook, or podcast. To return to Search (if Search is highlighted in the menu), press the Center button. Turning off the Click Wheel Sound When you scroll through menu items, you can hear a clicking sound through the iPod nano internal speaker. If you like, you can turn the Click Wheel sound off. To turn off the Click Wheel sound: m Choose Settings and set Clicker to Off. To turn the Click Wheel sound on again, set Clicker to On. Disabling iPod nano Controls If you don’t want to turn iPod nano on or activate controls accidentally, you can make them inactive using the Hold switch. m Slide the Hold switch to HOLD (so you can see the orange bar).Chapter 1 iPod nano Basics 9 Using iPod nano Menus When you turn on iPod nano, you see the main menu. Choose menu items to perform functions or go to other menus. Icons along the top of the screen show iPod nano status. Adding or Removing Items from the Main Menu You might want to add often-used items to the iPod nano main menu. For example, you can add a Songs item to the main menu, so you don’t have to choose Music before you choose Songs. To add or remove items from the main menu: 1 Choose Settings > Main Menu. 2 Choose each item you want to appear in the main menu. A checkmark indicates which items have been added. Setting the Backlight Timer You can set the backlight to turn on and illuminate the screen for a certain amount of time when you press a button or use the Click Wheel. The default is 10 seconds. m Choose Settings > Backlight Timer, and then choose the time you want. Choose “Always On” to prevent the backlight from turning off. Display item Function Menu title Displays the title of the current menu. Lock icon The Lock icon appears when the Hold switch (on the bottom of iPod nano) is set to HOLD. This indicates that the iPod nano controls are disabled. Play status The Play (“) icon appears when a song, video, or other item is playing. The Pause (1) icon appears when the item is paused. Battery status The Battery icon shows the approximate remaining battery charge. Menu items Use the Click Wheel to scroll through menu items. Press the Center button to choose an item. An arrow next to a menu item indicates that choosing it leads to another menu or screen. Menu title Menu items Battery status Play status Lock icon10 Chapter 1 iPod nano Basics Setting the Screen Brightness You can adjust the brightness of the iPod nano screen by moving a slider. m Choose Settings > Brightness, and then use the Click Wheel to move the slider. Moving it to the left dims the screen; moving it to the right increases the screen brightness. You can also set the brightness during a slideshow or video. Press the Center button to bring up or dismiss the brightness slider. Setting the Language iPod nano can be set to use different languages. m Choose Settings > Language, and then choose a language from the list. Getting Information About iPod nano You can get details about your iPod nano, such as how much space is available, how many songs, videos, photos, and other items you have, and the serial number, model, and software version. To get information about iPod nano: m Choose Settings > About, and press the Center button to cycle through the screens of information. Resetting All Settings You can reset all the items on the Settings menu to their default setting. m Choose Settings > Reset Settings, and then choose Reset. Connecting and Disconnecting iPod nano You connect iPod nano to your computer to add music, videos, photos, and files, and to charge the battery. Disconnect iPod nano when you’re done. Connecting iPod nano To connect iPod nano to your computer: m Plug the included iPod Dock Connector to USB 2.0 cable into a high-powered USB 2.0 port on your computer, and then connect the other end to iPod nano. If you have an iPod Dock, you can connect the cable to a USB 2.0 port on your computer, connect the other end to the Dock, and then put iPod nano in the Dock.Chapter 1 iPod nano Basics 11 Note: The USB port on most keyboards doesn’t provide enough power. You must connect iPod nano to a USB 2.0 port on your computer, unless your keyboard has a high-powered USB 2.0 port. By default, iTunes syncs songs on iPod nano automatically when you connect it to your computer. When iTunes is finished, you can disconnect iPod nano. Note: You can sync songs while your battery is charging. If you connect iPod nano to a different computer and it’s set to sync music automatically, iTunes prompts you before syncing any music. If you click Yes, the songs and other audio files already on iPod nano will be erased and replaced with songs and other audio files on the computer iPod nano is connected to. For more information about adding music to iPod nano and using iPod nano with more than one computer, see Chapter 2, “Music Features,” on page 17.12 Chapter 1 iPod nano Basics Disconnecting iPod nano It’s important not to disconnect iPod nano from your computer while music is being synced. You can easily see if it’s OK to disconnect iPod nano by looking at the iPod nano screen. Important: Don’t disconnect iPod nano if you see the “Connected” or “Sync in Progress” messages. You could damage files on iPod nano. If you see one of these messages, you must eject iPod nano before disconnecting it. If you set iPod nano to manage songs manually (see “Managing iPod nano Manually” on page 24) or enable iPod nano for disk use (see “Using iPod nano as an External Disk” on page 46), you must always eject iPod nano before disconnecting it. If you see the main menu or a large battery icon, you can disconnect iPod nano. Important: If you see one of these messages, you must eject iPod nano before disconnecting it.Chapter 1 iPod nano Basics 13 To eject iPod nano: m Click the Eject (C) button next to iPod nano in the list of devices in the iTunes source list. If you’re using a Mac, you can also eject iPod nano by dragging the iPod nano icon on the desktop to the Trash. If you’re using a Windows PC, you can also eject iPod nano in My Computer or by clicking the Safely Remove Hardware icon in the Windows system tray and selecting iPod nano. To disconnect iPod nano: 1 Unplug the headphones if they’re attached. 2 Disconnect the cable from iPod nano. If iPod nano is in the Dock, simply remove it. If your Dock connector is larger than the one shown, squeeze both sides of the connector while removing. You can safely disconnect iPod nano while either of these messages is displayed.14 Chapter 1 iPod nano Basics About the iPod nano Battery iPod nano has an internal, non-user-replaceable battery. For best results, the first time you use iPod nano, let it charge for about three hours or until the battery icon in the status area of the display shows that the battery is fully charged. If iPod nano isn’t used for a while, the battery might need to be charged. The iPod nano battery is 80-percent charged in about 1.5 hours and fully charged in about three hours. If you charge iPod nano while adding files, playing music, viewing videos, or viewing a slideshow, it might take longer. Charging the iPod nano Battery You can charge the iPod nano battery in two ways:  Connect iPod nano to your computer.  Use the Apple USB Power Adapter, available separately. To charge the battery using your computer: m Connect iPod nano to a USB 2.0 port on your computer. The computer must be turned on and not in sleep mode (some Mac models can charge iPod nano while in sleep mode). If the battery icon on the iPod nano screen shows the Charging screen, the battery is charging. If it shows the Charged screen, the battery is fully charged. If you don’t see the charging screen, iPod nano might not be connected to a high-power USB port. Try another USB port on your computer. Chapter 1 iPod nano Basics 15 Important: If a “Charging, Please Wait” or “Connect to Power” message appears on the iPod nano screen, the battery needs to be charged before iPod nano can communicate with your computer. See “If iPod nano displays a “Connect to Power” message” on page 58. If you want to charge iPod nano when you’re away from your computer, you can purchase the Apple USB Power Adapter. To charge the battery using the Apple USB Power Adapter: 1 Connect the AC plug adapter to the power adapter (they might already be connected). 2 Connect the iPod Dock Connector to USB 2.0 cable to the power adapter, and plug the other end of the cable into iPod nano. 3 Plug the power adapter into a working electrical outlet. WARNING: Make sure the power adapter is fully assembled before plugging it into an electrical outlet. AC plug adapter (The plug on your Power Adapter may look different.) USB Power Adapter iPod Dock Connector to USB 2.0 Cable16 Chapter 1 iPod nano Basics Understanding Battery States When iPod nano isn’t connected to a power source, a battery icon in the top-right corner of the iPod nano screen shows approximately how much charge is left. If iPod nano is connected to a power source, the battery icon changes to show that the battery is charging or fully charged. You can disconnect and use iPod nano before it’s fully charged. Note: Rechargeable batteries have a limited number of charge cycles and might eventually need to be replaced. Battery life and number of charge cycles vary by use and settings. For more information, go to www.apple.com/batteries. Battery less than 20% charged Battery about halfway charged Battery fully charged Battery charging (lightning bolt) Battery fully charged (plug)2 17 2 Music Features With iPod nano, you can take your music and audio collection with you wherever you go. Read this chapter to learn about adding music and listening to iPod nano. You use iPod nano by importing songs, audiobooks, movies, TV shows, music videos, and podcasts into your computer and then adding them to iPod nano. Read on to learn more about the steps in this process, including:  Getting music from your CD collection, hard disk, or the iTunes Store (part of iTunes and available in some countries only) into the iTunes application on your computer  Organizing your music and other audio into playlists, if you want  Adding playlists, songs, audiobooks, videos, and podcasts to iPod nano  Listening to music or other audio on the go About iTunes iTunes is the software application you use with iPod nano. iTunes can sync music, audiobooks, podcasts, and more with iPod nano. When you connect iPod nano to your computer, iTunes opens automatically. This guide explains how to use iTunes to download songs and other audio and video to your computer, create personal compilations of your favorite songs (called playlists), add them to iPod nano, and adjust iPod nano settings. iTunes also has many other features. You can make your own CDs that play in standard CD players (if your computer has a CD-recordable drive); listen to streaming Internet radio; watch videos and TV shows; rate songs according to preference; and much more. For information about using these iTunes features, open iTunes and choose Help > iTunes Help.18 Chapter 2 Music Features Importing Music into Your iTunes Library To listen to music on iPod nano, you first need to get that music into iTunes on your computer. There are three ways of getting music and other audio into iTunes:  Purchase music, audiobooks, and videos, or download podcasts online from the iTunes Store.  Import music and other audio from audio CDs.  Add music and other audio that’s already on your computer to your iTunes library. Purchasing Songs and Downloading Podcasts Using the iTunes Store If you have an Internet connection, you can easily purchase and download songs, albums, audiobooks, and videos online using the iTunes Store. You can also subscribe to and download podcasts. To purchase music online using the iTunes Store, you set up an Apple account in iTunes, find the songs you want, and then buy them. If you already have an Apple account, or if you have an America Online (AOL) account (available in some countries only), you can use that account to sign in to the iTunes Store and buy songs. Note: You don’t need an iTunes Store account to download or subscribe to podcasts. To sign in to the iTunes Store: m Open iTunes and then:  If you already have an iTunes account, choose Store > Sign In.  If you don’t already have an iTunes account, choose Store > Create Account and follow the onscreen instructions to set up an Apple account or enter your existing Apple account or AOL account information.Chapter 2 Music Features 19 To find songs, audiobooks, videos, and podcasts: You can browse or search the iTunes Store to find the album, song, or artist you’re looking for. Open iTunes and select iTunes Store in the source list.  To browse the iTunes Store, choose a category (for example, Music) on the left side of the main page in the iTunes Store. You can choose a genre, look at new releases, click one of the featured songs, look at Top Songs and more, or click Browse under Quick Links in the main iTunes Store window.  To browse for podcasts, click the Podcasts link on the left side of the main page in the iTunes Store.  To browse for videos, click the Movies, TV Shows, or Music Videos link on the left side of the main page in the iTunes Store.  To search the iTunes Store, type the name of an album, song, artist, or composer in the search field.  To narrow your search, type something in the search field, press Return or Enter on your keyboard, and then click links in the Search Bar at the top of the results page. For example, to narrow your search to songs and albums, click the Music link.  To search for a combination of items, click Power Search in the Search Results window.  To return to the main page of the iTunes Store, click the Home button in the status line at the top of the window. To buy a song, album, movie, TV show, music video, or audiobook: 1 Select iTunes Store in the source list, and then find the item you want to buy. You can double-click a song or other item to listen to a portion of it and make sure it’s what you want. You can view movie trailers or TV show previews. (If your network connection is slower than 128 kbps, choose iTunes > Preferences, and in the Store pane, select the “Load complete preview before playing” checkbox.) 2 Click Buy Song, Buy Album, Buy Movie, Buy Episode, Buy Video, or Buy Book. Some items have other options, such as TV shows that let you buy a season pass for all episodes. The song or other item is downloaded to your computer and charged to the credit card listed on your Apple or AOL account. To download or subscribe to a podcast: 1 Select iTunes Store in the source list. 2 Click the Podcasts link on the left side of the main page in the iTunes Store. 3 Browse for the podcast you want to download.  To download a single podcast episode, click the Get Episode button next to the episode.20 Chapter 2 Music Features  To subscribe to a podcast, click the Subscribe button next to the podcast graphic. iTunes downloads the most recent episode. As new episodes become available, they are automatically downloaded to iTunes when you connect to the Internet. For more information, see “Adding Podcasts to iPod nano” on page 25 and “Watching and Listening to Podcasts” on page 31. Adding Songs Already on Your Computer to Your iTunes Library If you have songs on your computer encoded in file formats that iTunes supports, you can easily add the songs to iTunes. To add songs on your computer to your iTunes library: m Drag the folder or disk containing the audio files to Library in the iTunes source list (or choose File > Add to Library and select the folder or disk). If iTunes supports the song file format, the songs are automatically added to your iTunes library. You can also drag individual song files to iTunes. Note: Using iTunes for Windows, you can convert nonprotected WMA files to AAC or MP3 format. This can be useful if you have a library of music encoded in WMA format. For more information, open iTunes and choose Help > iTunes Help. Importing Music From Your Audio CDs Into iTunes Follow these instructions to get music from your CDs into iTunes. To import music from an audio CD into iTunes: 1 Insert a CD into your computer and open iTunes. If you have an Internet connection, iTunes gets the names of the songs on the CD from the Internet (if available) and lists them in the window. If you don’t have an Internet connection, you can import your CDs and, later, when you’re connected to the Internet, choose Advanced > Get CD Track Names. iTunes will bring in the track names for the imported CDs. If the CD track names aren’t available online, you can enter the names of the songs manually. For more information, see “Entering Song Names and Other Details” on page 21. With song information entered, you can browse for songs in iTunes or on iPod by title, artist, album, and more. 2 Click to remove the checkmark next to any song you don’t want to import. 3 Click the Import button. The display area at the top of the iTunes window shows how much time it will take to import each song. Note: By default, iTunes plays songs as they are imported. If you’re importing a lot of songs, you might want to stop the songs from playing to improve performance.Chapter 2 Music Features 21 4 To eject the CD, click the Eject (C) button. You cannot eject a CD until the import is done. 5 Repeat these steps for any other CDs with songs you want to import. Entering Song Names and Other Details To enter CD song names and other information manually: 1 Select the first song on the CD and choose File > Get Info. 2 Click Info. 3 Enter the song information. 4 Click Next to enter information for the next song. 5 Click OK when you finish. Adding Lyrics You can enter song lyrics in plain text format into iTunes so that you can view the song lyrics on iPod nano while the song is playing. To enter lyrics into iTunes: 1 Select a song and choose File > Get Info. 2 Click Lyrics. 3 Enter song lyrics in the text box. 4 Click Next to enter lyrics for the next song. 5 Click OK when you finish. For more information, see “Viewing Lyrics on iPod nano” on page 30. Adding Album Artwork Music you purchase from the iTunes Store includes album artwork, which your iPod nano can display. You can add album artwork for music you’ve imported from CDs, if you have the album art on your computer. To add album artwork to iTunes: 1 Select a song and choose File > Get Info. 2 Click Artwork. 3 Click Add, navigate to the artwork file, and click Choose. 4 Use the slider to adjust the size of the artwork. 5 Click Next to add artwork for the next song or album. 6 Click OK when you finish. For more information, see “Viewing Album Artwork on iPod nano” on page 31.22 Chapter 2 Music Features Organizing Your Music Using iTunes, you can organize songs and other items into lists, called playlists, in any way you want. For example, you can make playlists with songs to listen to while exercising, or playlists with songs for a particular mood. You can also make Smart Playlists that update automatically based on rules you define. When you add songs to iTunes that match the rules, they automatically get added to the Smart Playlist. You can make as many playlists as you like using any of the songs in your iTunes library. Adding a song to a playlist or later removing it doesn’t remove it from your library. To make a playlist in iTunes: 1 Click the Add (+) button or choose File > New Playlist. 2 Type a name for the playlist. 3 Click Music in the Library list, and then drag a song or other item to the playlist. To select multiple songs, hold down the Shift key or the Command (x) key on a Mac, or the Shift key or the Control key on a Windows PC, as you click each song. To make a Smart Playlist: m Choose File > New Smart Playlist and define the rules for your playlist. Note: To make playlists on iPod nano when iPod nano isn’t connected to your computer, see “Making On-The-Go Playlists on iPod nano” on page 27. Adding Music and Podcasts to iPod nano After your music is imported and organized in iTunes, you can easily add it to iPod nano. To set how music is added from your computer to iPod nano, you connect iPod nano to your computer, and then use iTunes preferences to choose iPod nano settings.Chapter 2 Music Features 23 You can set iTunes to add music to iPod nano in three ways:  Sync all songs and playlists: When you connect iPod nano, it’s automatically updated to match the songs and other items in your iTunes library. Any other songs on iPod nano are deleted.  Sync selected playlists: When you connect iPod nano, it’s automatically updated to match the songs in playlists you select in iTunes.  Manually add music to iPod nano: When you connect iPod nano, you can drag songs and playlists individually to iPod nano, and delete songs and playlists individually from iPod nano. Using this option, you can add songs from more than one computer without erasing songs from iPod nano. When you manage music yourself, you must always eject iPod nano from iTunes before you can disconnect it. Syncing Music Automatically By default, iPod nano is set to sync all songs and playlists when you connect it to your computer. This is the simplest way to add music to iPod nano. You just connect iPod nano to your computer, let it add songs, audiobooks, videos, and other items automatically, and then disconnect it and go. If you added any songs to iTunes since the last time you connected iPod nano, they are synced with iPod nano. If you deleted songs from iTunes, they are removed from iPod nano. To sync music with iPod nano: m Simply connect iPod nano to your computer. If iPod nano is set to sync automatically, the update begins. Important: The first time you connect iPod nano to a computer, a message asks if you want to sync songs automatically. If you accept, all songs, audiobooks, and videos are erased from iPod nano and replaced with the songs and other items from that computer. If you don’t accept, you can still add songs to iPod nano manually without erasing any of the songs already on iPod nano. While music is being synced from your computer onto iPod nano, the iTunes status window shows progress, and you see a sync icon next to the iPod nano icon in the source list. When the update is done, a message in iTunes says “iPod update is complete.” Syncing Music From Selected Playlists onto iPod nano Setting iTunes to sync selected playlists to iPod nano is useful if the music in your iTunes library doesn’t all fit on iPod nano. Only the music in the playlists you select is synced to iPod nano. To set iTunes to sync music from selected playlists onto iPod nano: 1 In iTunes, select iPod nano in the source list and click the Music tab. 2 Select “Sync music” and then choose “Selected playlists.”24 Chapter 2 Music Features 3 Select the playlists you want. 4 To include music videos and display album artwork, select those options. 5 Click Apply. Note: If “Sync only checked songs and videos” is selected in the Summary pane, iTunes syncs only items that are checked. Managing iPod nano Manually Setting iTunes to let you manage iPod nano manually gives you the most flexibility for managing music and video on iPod nano. You can add and remove individual songs (including music videos) and videos (movies and TV shows). Also, you can add music and videos from multiple computers to iPod nano without erasing items already on iPod nano. Note: Setting iPod nano to manually manage music and video turns off the automatic sync options in the Music, Movies, and TV Shows panes. You cannot manually manage one and automatically sync another at the same time. To set iTunes to let you manage music and video on iPod nano manually: 1 In iTunes, select iPod nano in the source list and click the Summary tab. 2 In the Options section, select “Manually manage music and video.” 3 Click Apply. Note: When you manage songs and video yourself, you must always eject iPod nano from iTunes before you disconnect it. To add a song, video, or other item to iPod nano: 1 Click Music or another Library item in the iTunes source list. 2 Drag a song or other item to the iPod nano icon in the source list. To remove a song, video, or other item from iPod nano: 1 In iTunes, select iPod nano in the source list. 2 Select a song or other item on iPod nano and press the Delete or Backspace key on your keyboard. If you manually remove a song or other item from iPod nano, it isn’t deleted from your iTunes library. To make a new playlist on iPod nano: 1 In iTunes, select iPod nano in the source list, and then click the Add (+) button or choose File > New Playlist. 2 Type a name for the playlist. 3 Click an item, such as Music, in the Library list, and then drag songs or other items to the playlist.Chapter 2 Music Features 25 To add songs to or remove songs from a playlist on iPod nano: m Drag a song to a playlist on iPod nano to add the song. Select a song in a playlist and press the Delete key on your keyboard to delete the song. If you set iTunes to manage music manually, you can reset it later to sync automatically. To reset iTunes to sync all music automatically on iPod nano: 1 In iTunes, select iPod nano in the source list and click the Music tab. 2 Select “Sync music” and then choose “All songs and playlists.” 3 Click Apply. The update begins automatically. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your Music and other libraries. Adding Podcasts to iPod nano The settings for adding podcasts to iPod nano are unrelated to the settings for adding songs. Podcast update settings don’t affect song update settings, and vice versa. You can set iTunes to automatically sync all or selected podcasts, or you can add podcasts to iPod nano manually. To set iTunes to update the podcasts on iPod nano automatically: 1 In iTunes, select iPod nano in the source list and click the Podcasts tab. 2 In the Podcasts pane, select “Sync … episodes” and choose the number of episodes you want in the pop-up menu. 3 Click “All podcasts” or “Selected podcasts.” If you click “Selected podcasts,” also select the podcasts in the list that you want to sync. 4 Click Apply. When you set iTunes to sync iPod nano podcasts automatically, iPod nano is updated each time you connect it to your computer. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your Podcasts and other libraries. To manually manage podcasts: 1 In iTunes, select iPod nano in the source list and click the Summary tab. 2 Select “Manually manage music and videos” and click Apply. 3 Select the Podcasts library in the source list and drag the podcasts you want to iPod nano.26 Chapter 2 Music Features Playing Music After you add music and other audio to iPod nano, you can listen to it. Use the Click Wheel and Center button to browse for a song, audiobook, video, or podcast. To browse for and play a song: m Choose Music, browse for a song, and press the Play/Pause button. Note: When you browse for music videos in the Music menu, you only hear the music. When you browse for them in the Videos menu, you also see the video. When a song is playing, the Now Playing screen appears. The following table describes the elements on the Now Playing screen of iPod nano. When you see the Now Playing screen, you can use the Click Wheel to change the volume. You can press the Center button multiple times from the Now Playing screen to get to other information and options, such as the scrubber bar, rating bullets, shuffle settings, lyrics, podcast information, and more. The scrubber bar displays a diamond to show where you are in the track, along with elapsed and remaining times. Press the Menu button to return to the previous screen. Now Playing screen item Function Shuffle (¡) icon Appears if iPod nano is set to shuffle songs or albums. Repeat (⁄) icon Appears if iPod nano is set to repeat all songs. The Repeat Once (!) icon appears if iPod nano is set to repeat one song. Album art Shows the album art, if it’s available. Song information Displays the song title, artist, and album title. Rating Displays stars if you rate the song. Song number Shows the number of the song that’s playing within the current sequence of songs. Song time progress bar Shows the elapsed and remaining times for the song that’s playing. Shuffle icon Repeat icon Song time Song information, rating, and sequence number Album artChapter 2 Music Features 27 Setting iPod nano to Shuffle Songs You can set iPod nano to play songs, albums, or your entire library in random order. To set iPod nano to shuffle and play all your songs: m Choose Shuffle Songs from the iPod nano main menu. iPod nano begins playing songs from your entire music library in random order, skipping audiobooks and podcasts. To set iPod nano to always shuffle songs or albums: 1 Choose Settings from the iPod nano main menu. 2 Set Shuffle to either Songs or Albums. When you set iPod nano to shuffle songs by choosing Settings > Shuffle, iPod nano shuffles songs within the list (for example, album or playlist) you choose to play. When you set iPod nano to shuffle albums, it plays all the songs on an album in order, and then randomly selects another album in the list and plays through it in order. To set shuffle options from the Now Playing screen: m Press the Center button until you see the shuffle icon. Choose Songs, Albums, or Off. Setting iPod nano to Repeat Songs You can set iPod nano to repeat a song over and over, or repeat songs within the list you choose to play. To set iPod nano to repeat songs: m Choose Settings from the iPod nano main menu.  To repeat all songs in the list, set Repeat to All.  To repeat one song over and over, set Repeat to One. Customizing the Music Menu You can add items to or remove them from the Music menu, just as you do with the main menu. For example, you can add a Compilations item to the Music menu, so you can easily choose compilations that are put together from various sources. To add or remove items from the Music menu: 1 Choose Settings > Music Menu. 2 Choose each item you want to appear in the main menu. A checkmark indicates which items have been added. To revert to the original Music menu settings, choose Reset Menu. Making On-The-Go Playlists on iPod nano You can make playlists on iPod nano, called On-The-Go Playlists, when iPod nano isn’t connected to your computer.28 Chapter 2 Music Features To make an On-The-Go playlist: 1 Select a song, and then press and hold the Center button until the song title flashes. 2 Choose other songs you want to add. 3 Choose Music > Playlists > On-The-Go to view and play your list of songs. You can also add a list of songs. For example, to add an album, highlight the album title and press and hold the Center button until the album title flashes. To play songs in the On-The-Go playlist: m Choose Music > Playlists > On-The-Go and choose a song. To remove a song from the On-The-Go playlist: m Select a song in the playlist, and hold down the Center button until the song title flashes. To clear the entire On-The-Go playlist: m Choose Music > Playlists > On-The-Go > Clear Playlist and then click Clear. To save the On-The-Go playlists on iPod nano: m Choose Music > Playlists > On-The-Go > Save Playlist. The first playlist is saved as “New Playlist 1” in the Playlists menu. The On-The-Go playlist is cleared. You can save as many playlists as you like. After you save a playlist, you can no longer remove songs from it. To copy the On-The-Go playlists to your computer: m If iPod nano is set to update songs automatically (see “Syncing Music Automatically” on page 23), and you make an On-The-Go playlist, the playlist is automatically copied to iTunes when you connect iPod nano. You see the new On-The-Go playlist in the list of playlists in iTunes. You can rename, edit, or delete the new playlist, just as you would any playlist in iTunes. Rating Songs You can assign a rating to a song (from 1 to 5 stars) to indicate how much you like it. You can use song ratings to help you create Smart Playlists automatically in iTunes. To rate a song: 1 Start playing the song. 2 From the Now Playing screen, press the Center button until the five Rating bullets appear. 3 Use the Click Wheel to choose a rating (represented by stars). Note: You cannot assign ratings to video podcasts.Chapter 2 Music Features 29 Setting the Maximum Volume Limit You can choose to set a limit for the maximum volume on iPod nano and assign a combination to prevent the setting from being changed. To set the maximum volume limit for iPod nano: 1 Choose Settings > Volume Limit. The volume control shows the current volume. 2 Use the Click Wheel to select the maximum volume limit. You can press Play to hear the currently selected song play while you select the maximum volume limit. 3 Press Play/Pause to set the maximum volume limit. A triangle on the volume bar indicates the maximum volume limit. 4 Press the Menu button to accept the maximum volume limit without requiring a combination to change it. Or, on the Enter Combination screen, set a combination to require that the combination be entered to change the maximum volume limit. 5 To enter a combination:  Use the Click Wheel to select a number for the first position. Press the Center button to confirm your choice and move to the next position.  Use the same method to set the remaining numbers of the combination. You can use the Next/Fast-forward button to move to the next position and the Previous/Rewind button to move to the previous position. Press the Center button in the final position to confirm the entire combination. Note: The volume of songs and other audio may vary depending on how the audio was recorded or encoded. See “Setting Songs to Play at the Same Volume Level” on page 30 for information about how to set a relative volume level in iTunes and on iPod nano. Volume level may also vary if you use different earphones or headphones. With the exception of the iPod Radio Remote, accessories that connect through the iPod Dock Connector don’t support volume limits. If you set a combination, you must enter it before you can change or remove the maximum volume limit. To change the maximum volume limit: 1 Choose Settings > Volume Limit. 2 If you set a combination, enter it by using the Click Wheel to select the numbers and pressing the Center button to confirm them. 3 Use the Click Wheel to change the maximum volume limit. 4 Press the Play/Pause button to accept the change.30 Chapter 2 Music Features To remove the maximum volume limit: 1 If you’re currently listening to iPod nano, press Pause. 2 Choose Settings > Volume Limit. 3 If you set a combination, enter it by using the Click Wheel to select the numbers and pressing the Center button to confirm them. 4 Use the Click Wheel to move the volume limit to the maximum level on the volume bar. This removes any restriction on volume. 5 Press the Play/Pause button to accept the change. Note: If you forget the combination, you can restore iPod nano. See “Updating and Restoring iPod Software” on page 61 for more information. Setting Songs to Play at the Same Volume Level iTunes can automatically adjust the volume of songs, so they play at the same relative volume level. You can set iPod nano to use the iTunes volume settings. To set iTunes to play songs at the same sound level: 1 In iTunes, choose iTunes > Preferences if you’re using a Mac, or choose Edit > Preferences if you’re using a Windows PC. 2 Click Playback and select Sound Check, and then click OK. To set iPod nano to use the iTunes volume settings: m Choose Settings and set Sound Check to On. If you haven’t activated Sound Check in iTunes, setting it on iPod nano has no effect. Using the Equalizer You can use equalizer presets to change the sound on iPod nano to suit a particular music genre or style. For example, to make rock music sound better, set the equalizer to Rock. To use the equalizer to change the sound on iPod nano: m Choose Settings > EQ and choose an equalizer preset. If you assigned an equalizer preset to a song in iTunes and the iPod nano equalizer is set to Off, the song plays using the iTunes setting. See iTunes Help for more information. Viewing Lyrics on iPod nano If you enter lyrics for a song in iTunes (see “Adding Lyrics” on page 21) and then add the song to iPod nano, you can view the lyrics on iPod nano. To view lyrics on iPod nano while a song is playing: m On the Now Playing screen, press the Center button until you see the lyrics. The screen displays the lyrics, which you can scroll through as the song plays.Chapter 2 Music Features 31 Viewing Album Artwork on iPod nano By default, iTunes is set to allow you to view album artwork on iPod nano. If the artwork is available, you’ll see it on iPod nano in the album list and when you play music from the album. To set iTunes to display album artwork on iPod nano: 1 In iTunes, select iPod nano in the source list and click the Music tab. 2 Choose “Display album artwork on your iPod.” To see album artwork on iPod nano: m Play a song that has album artwork. For more information about album artwork, open iTunes and choose Help > iTunes Help. Watching and Listening to Podcasts Podcasts are downloadable audio or video shows you get at the iTunes Store. You can listen to audio podcasts and watch video podcasts. Podcasts are organized by shows, episodes within shows, and chapters within episodes. If you stop watching or listening to a podcast and go back to it later, the podcast begins playing from where you left off. To watch or listen to a podcast: 1 From the main menu, choose Podcasts, and then choose a show. Shows appear in reverse chronological order so that you can watch or listen to the most recent one first. You see a blue dot next to shows and episodes you haven’t watched or listened to yet. 2 Choose an episode to play it. The Now Playing screen displays the show, episode, and date information, along with elapsed and remaining time. Press the Center button to see more information about the podcast. If the podcast includes artwork, you also see a picture. Podcast artwork can change during an episode, so you might see several pictures during the podcast. If the podcast you’re watching or listening to has chapters, you can press the Next/Fast-forward or Previous/Rewind button to skip to the next chapter or the beginning of the current chapter in the podcast. For more information about podcasts, open iTunes and choose Help > iTunes Help. Then search for “podcasts.”32 Chapter 2 Music Features Listening to Audiobooks You can purchase and download audiobooks from the iTunes Store or from audible.com and listen to them on iPod nano. You can use iTunes to add audiobooks to iPod nano the same way you add songs. If you stop listening to an audiobook on iPod nano and go back to it later, the audiobook begins playing from where you left off. iPod nano skips audiobooks when set to shuffle. If the audiobook you’re listening to has chapters, you can press the Next/Fast-forward or Previous/Rewind button to skip to the next chapter or the beginning of the current chapter in the audiobook. You can play audiobooks at speeds faster or slower than normal. To set audiobook play speed: m Choose Settings > Audiobooks and choose a speed. Setting the play speed only affects audiobooks purchased from the iTunes Store or audible.com. Listening to FM Radio You can listen to radio using the optional iPod Radio Remote accessory for iPod nano. iPod Radio Remote attaches to iPod nano using the Dock connector cable. When you’re using iPod Radio Remote, you see a Radio menu item on the iPod nano main menu. For more information, see the iPod Radio Remote documentation.3 33 3 Video Features You can purchase movies, TV shows, and music videos, rent movies, and download video podcasts at the iTunes Store, and then add them to your iPod nano. You can watch videos on iPod nano or on a TV connected to iPod nano. Read this chapter to learn about downloading and viewing videos. Purchasing or Renting Videos and Downloading Video Podcasts To purchase videos—movies, TV shows, and music videos—or rent movies online from the iTunes Store (part of iTunes and available in some countries only), you set up an Apple account in iTunes, find the videos you want, and then buy or rent them. If you already have an Apple account, or if you have an America Online (AOL) account (available in some countries only), you can use that account to sign in to the iTunes Store and buy videos or rent movies. To sign in to the iTunes Store: m Open iTunes and then:  If you already have an iTunes account, choose Store > Sign In.  If you don’t already have an iTunes account, choose Store > Create Account and follow the onscreen instructions to set up an Apple account or enter your existing Apple account or AOL account information.34 Chapter 3 Video Features To browse videos in the iTunes Store: 1 In iTunes, select iTunes Store in the source list. 2 Click an item (Movies, TV Shows, or Music Videos) in the iTunes Store list on the left. You can also find some music videos as part of an album or other offer. Videos in iTunes and in the iTunes Store have a display ( ) icon next to them. To buy or rent a video: 1 Select iTunes Store in the source list, and then find the item you want to buy or rent. 2 Click Buy Video, Buy Episode, Buy Season, Buy Movie, or Rent Movie. Purchased videos appear when you select Movies (under Library) or Purchased (under Store) in the source list. Rented videos appear when you select Rented Movies (under Library). To download a video podcast: Video podcasts appear alongside other podcasts in the iTunes Store. You can subscribe to them and download them just as you would other podcasts. You don’t need an iTunes Store account to download podcasts. See “Purchasing Songs and Downloading Podcasts Using the iTunes Store” on page 18 for instructions. Converting Your Own Videos to Work with iPod nano You can view other video files on iPod nano, such as videos you create in iMovie on a Mac or videos you download from the Internet. Import the video into iTunes, convert it for use with iPod nano, if necessary, and then add it to iPod nano. iTunes supports all the video formats that QuickTime supports. For more information, choose Help > QuickTime Player Help from the QuickTime Player menu bar. To import a video into iTunes: m Drag the video file to your iTunes library. Some videos may be ready for use with iPod nano after you import them to iTunes. If you try to add a video to iPod nano (see “Syncing Videos Automatically” on page 35 for instructions), and a message says the video can’t play on iPod nano, then you must convert the video for use with iPod nano. To convert a video for use with iPod nano: 1 Select the video in your iTunes library. 2 Choose Advanced > “Convert Selection to iPod.” Depending on the length and content of a video, converting it for use with iPod nano can take several minutes to several hours. Note: When you convert a video for use with iPod nano, the original video remains in your iTunes library. Chapter 3 Video Features 35 For more information about converting video for iPod nano, go to www.info.apple.com/kbnum/n302758. Adding Videos to iPod nano You add movies and TV shows to iPod nano much the same way you add songs. You can set iTunes to sync all movies and TV shows to iPod nano automatically when you connect iPod nano, or you can set iTunes to sync only selected playlists. Alternatively, you can manage movies and TV shows manually. Using this option, you can add videos from more than one computer without erasing videos already on iPod nano. Note: Music videos are managed with songs, under the Music tab in iTunes. See “Adding Music and Podcasts to iPod nano” on page 22. Important: If you rent a movie from the iTunes Store and add it to iPod nano, you will only be able to view it on iPod nano. Once you add a rented movie to iPod nano, it can’t be transferred again. Syncing Videos Automatically By default, iPod nano is set to sync all videos when you connect it to your computer. This is the simplest way to add videos to iPod nano. You just connect iPod nano to your computer, let it add videos and other items automatically, and then disconnect it and go. If you added any videos to iTunes since the last time you connected iPod nano, they are added to iPod nano. If you deleted videos from iTunes, they are removed from iPod nano. You can set iPod nano to sync videos automatically when you connect it to your computer. To sync videos to iPod nano: m Simply connect iPod nano to your computer. If iPod nano is set to sync automatically, the syncing begins.36 Chapter 3 Video Features Important: The first time you connect iPod nano to a different computer and have the automatic sync option set, a message asks if you want to sync songs and videos automatically. If you accept, all songs, videos, and other items are deleted from iPod nano and replaced with the songs, videos, and other items in the iTunes library on that computer. If you don’t accept, you can still add videos to iPod nano manually without deleting any of the videos already on iPod nano. iTunes includes a feature to sync purchased items from iPod nano to another computer. For more information, see iTunes Help. While videos are being synced from your computer to iPod nano, the iTunes status window shows progress and the iPod nano icon in the source list flashes red. When the update is done, a message in iTunes says “iPod update is complete.” Syncing Selected Videos to iPod nano Setting iTunes to sync selected videos to iPod nano is useful if you have more videos in your iTunes library than will fit on iPod nano. Only the videos you specify are synced with iPod nano. You can sync selected videos or selected playlists that contain videos. To set iTunes to sync unwatched or selected movies to iPod nano: 1 In iTunes, select iPod nano in the source list and click the Movies tab. 2 Select “Sync movies.” 3 Select the movies or playlists you want. Unwatched movies: Select “… unwatched movies” and choose the number you want from the pop-up menu. Selected movies or playlists: Click “Selected …,” choose “movies” or “playlists” from the pop-up menu, and then select the movies or playlists you want. 4 Click Apply. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your Movies and other libraries. To set iTunes to sync most recent episodes or selected TV shows to iPod nano: 1 In iTunes, select iPod nano in the source list and click the TV Shows tab. 2 Select “Sync … episodes” and choose the number of episodes you want from the popup menu. 3 Click “Selected …” and choose “TV shows” or “playlists” from the pop-up menu. 4 Select the movies or playlists you want to sync. 5 Click Apply. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your TV Shows and other libraries.Chapter 3 Video Features 37 Managing Videos Manually Setting iTunes to let you manage iPod nano manually gives you the most flexibility for managing videos on iPod nano. You can add and remove movies, TV shows, and other items individually. You can also add videos from multiple computers to iPod nano without removing videos already on iPod nano. See “Managing iPod nano Manually” on page 24. Adding Video Podcasts to iPod nano You add video podcasts to iPod nano the same way you add other podcasts (see page 25). If a podcast has a video component, the video plays when you choose it from Podcasts. If you set iTunes to manage movies and TV shows manually, you can reset iTunes later to sync them automatically. If you set iTunes to sync automatically after you’ve been manually managing iPod nano, you lose any items on iPod nano that aren’t part of your iTunes library. To reset iTunes to sync all movies automatically on iPod nano: 1 In iTunes, select iPod nano in the source list and click the Movies tab. 2 Select “Sync movies” and then select “All movies.” 3 Click Apply. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your Movies and other libraries. To reset iTunes to sync all TV shows automatically on iPod nano: 1 In iTunes, select iPod nano in the source list and click the TV Shows tab. 2 Select “Sync … episodes” and choose “all” from the pop-up menu. 3 Select “All TV shows.” 4 Click Apply. Note: If “Only sync checked items” is selected in the Summary pane, iTunes syncs only items that are checked in your TV Shows and other libraries. Viewing and Listening to Videos You can view and listen to videos on iPod nano. If you have an AV cable from Apple (available separately at www.apple.com/ipodstore), you can watch videos from iPod nano on TV.38 Chapter 3 Video Features Viewing and Listening to Videos on iPod nano Videos you add to iPod nano appear in the Videos menus. Music videos also appear in Music menus. To view a video on iPod nano: m Choose Videos and browse for a video. When you play the video, you see and hear it. To listen to a music video’s sound or a video podcast’s sound without playing the video: m Choose Music and browse for a music video or a video podcast. When you play the video, you hear it but don’t see the video. Watching Videos on a TV Connected to iPod nano If you have an AV cable from Apple, you can watch videos on a TV connected to your iPod nano. First you set iPod nano to display videos on a TV, then connect iPod nano to your TV, and then play a video. Note: Use the Apple Component AV Cable, the Apple Composite AV Cable, or the Apple AV Connection Kit. Other similar RCA-type cables might not work. You can purchase the cables at www.apple.com/ipodstore. To set iPod nano to display videos on a TV: m Choose Videos > Settings, and then set TV Out to Ask or On. If you set TV Out to Ask, iPod nano gives you the option of displaying videos on TV or on iPod nano every time you play a video. You can also set video to display full screen or widescreen, and set video to display on PAL or NTSC devices. To set TV settings: m Choose Videos > Settings, and then follow the instructions below. To set Do this Video to display on PAL or NTSC TVs Set TV Signal to PAL or NTSC. PAL and NTSC refer to TV broadcast standards. Your TV might use either of these, depending on the region where it was purchased. If you aren’t sure which your TV uses, check the documentation that came with your TV. The format of your external TV Set TV Screen to Widescreen for 16:9 format or Standard for 4:3 format. Video to fit to your screen Set “Fit to Screen” to On. If you set “Fit to Screen” to Off, widescreen videos display in letterbox format on iPod nano or a standard (4:3) TV screen. Captions to display Set Captions to On.Chapter 3 Video Features 39 To use the Apple Component AV Cable to connect iPod nano to your TV: 1 Plug the red, green, and blue video connectors into the component video input (Y, Pb, and Pr) ports on your TV. You can also use the Apple Composite AV cable. If you do, plug in the yellow video connector into the video input port on your TV. Your TV must have RCA video and audio ports. 2 Plug the white and red audio connectors into the left and right analog audio input ports, respectively, on your TV. 3 Plug the iPod Dock Connector into your iPod nano or Universal Dock. 4 Plug the USB connector into your USB Power Adapter or your computer to keep your iPod nano charged. 5 Turn on iPod nano and your TV or receiver to start playing. Make sure you set TV Out on your iPod nano to On. Note: The ports on your TV or receiver may differ from the ports in the illustration. To view a video on your TV: 1 Connect iPod nano to your TV (see above). 2 Turn on your TV and set it to display from the input ports connected to iPod nano. See the documentation that came with your TV for more information. 3 On iPod nano, choose Videos and browse for a video. USB Power Adapter iPod Left audio (white) Dock Connector USB connector Television Video in (Y, Pb, Pr) Right audio (red)4 40 4 Photo Features You can import digital photos to your computer and add them to iPod nano. You can view your photos on iPod nano or as a slideshow on your TV. Read this chapter to learn about importing and viewing photos. Importing Photos You can import digital photos from a digital camera to your computer, and then add them to iPod nano for viewing. You can connect iPod nano to a TV and view photos as a slideshow with music. Importing Photos from a Camera to Your Computer You can import photos from a digital camera or a photo card reader. To import photos to a Mac using iPhoto: 1 Connect the camera or photo card reader to your computer. Open iPhoto (located in the Applications folder) if it doesn’t open automatically. 2 Click Import. Images from the camera are imported into iPhoto. You can import other digital images into iPhoto, such as images you download from the web. For more information about importing and working with photos and other images, open iPhoto and choose Help > iPhoto Help.Chapter 4 Photo Features 41 iPhoto is available for purchase as part of the iLife suite of applications at www.apple.com/ilife. iPhoto might already be installed on your Mac, in the Applications folder. If you don’t have iPhoto, you can import photos using Image Capture. To import photos to a Mac using Image Capture: 1 Connect the camera or photo card reader to your computer. 2 Open Image Capture (located in the Applications folder) if it doesn’t open automatically. 3 To choose specific items to import, click Download Some. Or to download all items, click Download All. To import photos to a Windows PC: m Follow the instructions that came with your digital camera or photo application. Adding Photos From Your Computer to iPod nano You can add photos to iPod nano from a folder on your hard disk. If you have a Mac and iPhoto 4.0.3 or later, you can sync iPhoto albums automatically. If you have a Windows PC and Adobe Photoshop Album 2.0 or later, or Adobe Photoshop Elements 3.0 or later, you can sync photo collections automatically. Adding photos to iPod nano the first time might take some time, depending on how many photos are in your photo library. To sync photos from a Mac or Windows PC to iPod nano using a photo application: 1 In iTunes, select iPod nano in the source list and click the Photos tab. 2 Select “Sync photos from: …”  On a Mac, choose iPhoto from the pop-up menu.  On a Windows PC, choose Photoshop Album or Photoshop Elements from the pop-up menu. Note: Some versions of Photoshop Album and Photoshop Elements don’t support collections. You can still use them to add all your photos.42 Chapter 4 Photo Features 3 If you want to add all your photos, select “All photos and albums.” If you want to keep your photos organized by event, select “… events” and choose an option from the popup menu. If you want to add photos from only certain albums, select “Selected albums” and select the albums you want. 4 Click Apply. Each time you connect iPod nano to your computer, photos are synced automatically. To add photos from a folder on your hard disk to iPod nano: 1 Drag the images you want into a folder on your computer. If you want images to appear in separate photo albums on iPod nano, create folders inside the main image folder, and drag images into the new folders. 2 In iTunes, select iPod nano in the source list and click the Photos tab. 3 Select “Sync photos from: …” 4 Choose “Choose Folder” from the pop-up menu and select your image folder. 5 Click Apply. When you add photos to iPod nano, iTunes optimizes the photos for viewing. Full-resolution image files aren’t transferred by default. Adding full-resolution image files is useful, for example if you want to move them from one computer to another, but isn’t necessary for viewing the images at full quality on iPod nano. To add full-resolution image files to iPod nano: 1 In iTunes, select iPod nano in the source list and click the Photos tab. 2 Select “Include full-resolution photos.” 3 Click Apply. iTunes copies the full-resolution versions of the photos to the Photos folder on iPod nano. To delete photos from iPod nano: 1 In iTunes, select iPod nano in the source list and click the Photos tab. 2 Select “Sync photos from: …”  On a Mac, choose iPhoto from the pop-up menu.  On a Windows PC, choose Photoshop Album or Photoshop Elements from the pop-up menu. 3 Choose “Selected albums” and deselect the albums you no longer want on iPod nano. 4 Click Apply.Chapter 4 Photo Features 43 Adding Photos from iPod nano to a Computer If you add full-resolution photos from your computer to iPod nano using the previous steps, they’re stored in a Photos folder on iPod nano. You can connect iPod nano to a computer and put these photos onto the computer. iPod nano must be enabled for disk use (see “Using iPod nano as an External Disk” on page 46). To add photos from iPod nano to a computer: 1 Connect iPod nano to the computer. 2 Drag image files from the Photos folder or DCIM folder on iPod nano to the desktop or to a photo editing application on the computer. Note: You can also use a photo editing application, such as iPhoto, to add photos stored in the Photos folder. See the documentation that came with the application for more information. To delete photos from the Photos folder on iPod nano: 1 Connect iPod nano to the computer. 2 Navigate to the Photos folder on iPod nano and delete the photos you no longer want. Viewing Photos You can view photos on iPod nano manually or as a slideshow. If you have an optional AV cable from Apple (for example, Apple Component AV Cable), you can connect iPod nano to a TV and view photos as a slideshow with music. Viewing Photos on iPod nano To view photos on iPod nano: 1 On iPod nano, choose Photos > All Photos. Or choose Photos and a photo album to see only the photos in the album. Thumbnail views of the photos might take a moment to appear. 2 Select the photo you want and press the Center button to view a full-screen version.44 Chapter 4 Photo Features From any photo-viewing screen, use the Click Wheel to scroll through photos. Press the Next/Fast-forward or Previous/Rewind button to skip to the next or previous screen of photos. Press and hold the Next/Fast-forward or Previous/Rewind button to skip to the last or first photo in the library or album. Viewing Slideshows You can view a slideshow, with music and transitions if you choose, on iPod nano. If you have an optional AV cable from Apple, you can view the slideshow on a TV. To set slideshow settings: m Choose Photos > Settings, and then follow these instructions: To set Do this Slideshows to display on iPod nano Set TV Out to Ask or Off. Slideshows to display on TV Set TV Out to Ask or On. If you set TV Out to Ask, iPod nano gives you the option of showing slideshows on TV or on iPod nano every time you start a slideshow. How long each slide is shown Choose Time Per Slide and pick a time. The music that plays during slideshows Choose Music and choose a playlist. If you’re using iPhoto, you can choose From iPhoto to copy the iPhoto music setting. Only the songs that you’ve added to iPod nano play. Slides to repeat Set Repeat to On. Slides to display in random order Set Shuffle Photos to On. Slides to display with transitions Choose Transitions and choose a transition type. Slides to show on PAL or NTSC TVs Set TV Signal to PAL or NTSC. PAL and NTSC refer to TV broadcast standards. Your TV might use either of these, depending on the region where it was purchased. If you aren’t sure which your TV uses, check the documentation that came with your TV.Chapter 4 Photo Features 45 To view a slideshow on iPod nano: m Select any photo, album, or roll, and press the Play/Pause button. Or select any full-screen photo and press the Center button. To pause, press the Play/Pause button. To skip to the next or previous photo, press the Next/Fast-forward or Previous/Rewind button. To connect iPod nano to a TV: 1 Connect the optional Apple Component or Composite AV cable to iPod nano. Note: Use the Apple Component AV Cable, Apple Composite AV Cable, or Apple AV Connection Kit. Other similar RCA-type cables won’t work. You can purchase the cables at www.apple.com/ipodstore. 2 Connect the video and audio connectors to the ports on your TV (for an illustration, see page 39). Your TV must have RCA video and audio ports. To view a slideshow on a TV: 1 Connect iPod nano to a TV (see above). 2 Turn on your TV and set it to display from the input ports connected to iPod nano. See the documentation that came with your TV for more information. 3 On iPod nano, select any photo or album and press the Play/Pause button. Or select any full-screen photo and press the Center button. To pause, press the Play/Pause button. To skip to the next or previous photo, press the Next/Fast-forward or Previous/ Rewind button. If you selected a playlist in Photos > Settings > Music, the playlist plays automatically when you start the slideshow. The photos display on your TV and advance automatically according to settings in the Slideshow > Settings menu.5 46 5 Extra Features and Accessories iPod nano can do a lot more than play songs. And you can do a lot more with it than listen to music. Read this chapter to find out more about the extra features of iPod nano, including how to use it as an external disk, alarm, or sleep timer; show the time of day in other parts of the world; display notes; and sync contacts, calendars, and to-do lists. Learn about how to use iPod nano as a stopwatch and to lock the screen, and about the accessories available for iPod nano. Using iPod nano as an External Disk You can use iPod nano as an external disk to store data files. Note: To add music and other audio or video files to iPod nano, you must use iTunes. For example, you won’t see songs you add using iTunes in the Mac Finder or in Windows Explorer. Likewise, if you copy music files to iPod nano in the Mac Finder or Windows Explorer, you won’t be able to play them on iPod nano. To enable iPod nano as an external disk: 1 In iTunes, select iPod nano in the source list and click the Summary tab. 2 In the Options section, select “Enable disk use.” 3 Click Apply. When you use iPod nano as an external disk, the iPod nano disk icon appears on the desktop on Mac, or as the next available drive letter in Windows Explorer on a Windows PC. Note: Clicking Summary and selecting “Manually manage music and videos” in the Options section also enables iPod nano to be used as an external disk. Drag files to and from iPod nano to copy them. If you use iPod nano primarily as a disk, you might want to keep iTunes from opening automatically when you connect iPod nano to your computer.Chapter 5 Extra Features and Accessories 47 To prevent iTunes from opening automatically when you connect iPod nano to your computer: 1 In iTunes, select iPod nano in the source list and click the Summary tab. 2 In the Options section, deselect “Open iTunes when this iPod is connected.” 3 Click Apply. Using Extra Settings You can set the date and time, clocks in different time zones, and alarm and sleep features on iPod nano. You can use iPod nano as a stopwatch or to play games, and you can lock the iPod nano screen. Setting and Viewing the Date and Time The date and time are set automatically from your computer’s clock when you connect iPod nano, but you can change the settings. To set date and time options: 1 Choose Settings > Date & Time. 2 Choose one or more of the following options: Adding Clocks for Other Time Zones To add clocks for other time zones: 1 Choose Extras > Clocks. 2 On the Clocks screen, click the Center button and choose Add. 3 Choose a region and then choose a city. The clocks you add appear in a list. The last clock you added appears last. To Do this Set the date Choose Date. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Set the time Choose Time. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Specify the time zone Choose Time Zone and use the Click Wheel to select a city in another time zone. Specify the status of Daylight Savings Time (DST) Choose DST and press the Center button to turn DST on or off. Display the time in 24-hour format Choose 24 Hour Clock and press the Center button to turn the 24-hour format on or off. Display the time in the title bar Choose Time in Title and press the Center button to turn the option on or off. 48 Chapter 5 Extra Features and Accessories To delete a clock: 1 Choose Extras > Clocks. 1 Choose the clock. 2 Choose Delete. Setting the Alarm You can set an alarm for any clock on iPod nano. To use iPod nano as an alarm clock: 1 Choose Extras > Alarms. 2 Choose Create Alarm and set one or more of the following options: To delete an alarm: 1 Choose Extras > Alarms. 2 Choose the alarm and then choose Delete. Setting the Sleep Timer You can set iPod nano to turn off automatically after playing or other content for a specific period of time. To set the sleep timer: 1 Choose Extras > Alarms. 2 Choose Sleep Timer and choose how long you want iPod nano to play. Using the Stopwatch You can use the stopwatch as you exercise to track your overall time and, if you’re running on a track, your lap times. You can play music while you use the stopwatch. To Do this Turn the alarm on Choose Alarm and choose On. Set the time Choose Time. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Set the date Choose Date. Use the Click Wheel to change the selected value. Press the Center button to move to the next value. Choose a sound Choose Tones or a playlist. If you choose Tones, select Beep to hear the alarm through the internal speaker. If you choose a playlist, you’ll need to connect iPod nano to speakers or headphones to hear the alarm. Set a repeat option Choose Repeat and choose an option (for example, “weekdays”). Name the alarm Choose Label and choose an option (for example, “Wake up”).Chapter 5 Extra Features and Accessories 49 To use the stopwatch: 1 Choose Extras > Stopwatch. 2 Press the Play/Pause button to start the timer. 3 Press the Center button to record lap times. Up to three lap times show beneath the overall time. 4 Press the Play/Pause button to stop the overall timer, or choose Resume to start the timer again. 5 Choose New Timer to start a new stopwatch session. Note: After you start the stopwatch, iPod nano stays on as long as you display the Timer screen and the timer continues to run. If you start the stopwatch and then go to another menu, and iPod nano isn’t playing music or a video, the stopwatch timer stops and iPod nano turns off automatically after a few minutes. To review or delete a logged stopwatch session: 1 Choose Extras > Stopwatch. The current log and a list of saved sessions appear. 2 Choose a log to view session information. iPod nano stores stopwatch sessions with dates, times, and lap statistics. You see the date and time the session started; the total time of the session; the shortest, longest, and average lap times; and the last several lap times. 3 Press the Center button and choose Delete Log to delete the chosen log, or Clear Logs to delete all current logs. Playing Games iPod nano comes with three games: iQuiz, Klondike, and Vortex. To play a game: m Choose Extras > Games and choose a game. You can purchase additional games from the iTunes Store (in some countries) to play on iPod nano. After purchasing games in iTunes, you can add them to iPod nano by syncing them automatically or by managing them manually. To buy a game: 1 In iTunes, select iTunes Store in the source list. 2 Choose iPod Games from the iTunes Store list. 3 Select the game you want and click Buy Game.50 Chapter 5 Extra Features and Accessories To sync games automatically to iPod nano: 1 In iTunes, select iPod nano in the source list and click the Games tab. 2 Select “Sync games.” 3 Click “All games” or “Selected games.” If you click “Selected games,” also select the games you want to sync. 4 Click Apply. Locking the iPod nano Screen You can set a combination to prevent iPod nano from being used by someone without your permission. When you lock an iPod nano that isn’t connected to a computer, you must enter a combination to unlock and use it. Note: This is different from the Hold button in that the Hold button prevents iPod nano buttons from being pressed accidentally. The combination prevents another person from using iPod nano. To set a combination for iPod nano: 1 Choose Extras > Screen Lock. 2 On the New Combination screen, enter a combination:  Use the Click Wheel to select a number for the first position. Press the Center button to confirm your choice and move to the next position.  Use the same method to set the remaining numbers of the combination. You can use the Next/Fast-forward button to move to the next position and the Previous/Rewind button to move to the previous position. Press the Center button in the final position. 3 On the Confirm Combination screen, enter the combination to confirm it, or press Menu to exit without locking the screen. When you finish, you return to the Screen Lock screen, where you can lock the screen or reset the combination. Press the Menu button to exit without locking the screen. To lock the iPod nano screen: m Choose Extras > Screen Lock > Lock. If you just finished setting your combination, Lock will already be selected on the screen. Just press the Center button to lock iPod. When the screen is locked, you see a picture of a lock. Note: You might want to add the Screen Lock menu item to the main menu so that you can quickly lock the iPod nano screen. See “Adding or Removing Items from the Main Menu” on page 9.Chapter 5 Extra Features and Accessories 51 When you see the lock on the screen, you can unlock the iPod nano screen in two ways:  Press the Center button to enter the combination on iPod nano. Use the Click Wheel to select the numbers and press the Center button to confirm them. If you enter the wrong combination, the lock remains. Try again.  Connect iPod nano to the primary computer you use it with, and iPod nano automatically unlocks. Note: If you try these methods and you still can’t unlock iPod nano, you can restore iPod nano. See “Updating and Restoring iPod Software” on page 61. To change a combination you’ve already set: 1 Choose Extras > Screen Lock > Reset. 2 On the Enter Combination screen, enter the current combination. 3 On the New Combination screen, enter and confirm a new combination. Note: If you can’t remember the current combination, the only way to clear it and enter a new one is to restore the iPod nano software. See “Updating and Restoring iPod Software” on page 61. Syncing Contacts, Calendars, and To-Do Lists iPod nano can store contacts, calendar events, and to-do lists for viewing on the go. If you’re using Mac OS X v10.4 or later, you can use iTunes to sync the contact and calendar information on iPod nano with Address Book and iCal. If you’re using any version of Mac OS X earlier than 10.4, you can use iSync to sync your information. Syncing information using iSync requires iSync 1.1 or later, and iCal 1.0.1 or later. If you’re using Windows 2000 or Windows XP, and you use Windows Address Book or Microsoft Outlook 2003 or later to store your contact information, you can use iTunes to sync the address book information on iPod nano. If you use Microsoft Outlook 2003 or later to keep a calendar, you can also sync calendar information. To sync contacts or calendar information using Mac OS X v10.4 or later: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the source list and click the Contacts tab. 3 Do one of the following:  To sync contacts, in the Contacts section, select “Sync Address Book contacts,” and select an option:  To sync all contacts automatically, select “All contacts.”  To sync selected groups of contacts automatically, select “Selected groups” and select the groups you want to sync.52 Chapter 5 Extra Features and Accessories  To copy contacts’ photos to iPod nano, when available, select “Include contacts’ photos.” When you click Apply, iTunes updates iPod nano with the Address Book contact information you specified.  To sync calendars, in the Calendars section, select “Sync iCal calendars,” and choose an option:  To sync all calendars automatically, choose “All calendars.”  To sync selected calendars automatically, choose “Selected calendars” and select the calendars you want to sync. When you click Apply, iTunes updates iPod nano with the calendar information you specified. To sync contacts and calendars with a Mac and iSync using a version of Mac OS X earlier than v10.4: 1 Connect iPod nano to your computer. 2 Open iSync and choose Devices > Add Device. You need to do this step only the first time you use iSync with iPod nano. 3 Select iPod nano and click Sync Now. iSync puts information from iCal and Mac Address Book onto iPod nano. The next time you want to sync iPod nano, you can simply open iSync and click Sync Now. You can also choose to have iPod nano sync automatically when you connect it. Note: iSync syncs information from your computer with iPod nano. You can’t use iSync to sync information from iPod nano to your computer. To sync contacts or calendars using Windows Address Book or Microsoft Outlook for Windows: 1 Connect iPod nano to your computer. 2 In iTunes, select iPod nano in the source list and click the Contacts tab. 3 Do one of the following:  To sync contacts, in the Contacts section, select “Sync contacts from” and choose Windows Address Book or Microsoft Outlook from the pop-up menu. Then select which contact information you want to sync.  To sync calendars from Microsoft Outlook, in the Calendars section, select “Sync calendars from Microsoft Outlook.” 4 Click Apply. You can also add contact and calendar information to iPod nano manually. iPod nano must be enabled as an external disk (see “Using iPod nano as an External Disk” on page 46).Chapter 5 Extra Features and Accessories 53 To add contact information manually: 1 Connect iPod nano and open your favorite email or contacts application. You can add contacts using Palm Desktop, Microsoft Outlook, Microsoft Entourage, and Eudora, among others. 2 Drag contacts from the application’s address book to the Contacts folder on iPod nano. In some cases, you might need to export contacts and then drag the exported file or files to the Contacts folder. See the documentation for your email or contacts application. To add appointments and other calendar events manually: 1 Export calendar events from any calendar application that uses the standard iCal format (filenames end in .ics) or vCal format (filenames end in .vcs). 2 Drag the files to the Calendars folder on iPod nano. Note: To add to-do lists to iPod nano manually, save them in a calendar file with a .ics or .vcs extension. To view contacts on iPod nano: m Choose Extras > Contacts. To sort contacts by first or last name: m Choose Settings > Sort By, and press the Center button to choose First or Last. To view calendar events: m Choose Extras > Calendars. To view to-do lists: m Choose Extras > Calendars > To Do’s. Storing and Reading Notes You can store and read text notes on iPod nano if it’s enabled as an external disk (see page 46). 1 Save a document in any word-processing application as a text (.txt) file. 2 Place the file in the Notes folder on iPod nano. To view notes: m Choose Extras > Notes.54 Chapter 5 Extra Features and Accessories Recording Voice Memos You can record voice memos using an optional iPod nano-compatible microphone (available for purchase at www.apple.com/ipodstore). You can store voice memos on iPod nano and sync them with your computer. You can set iPod nano to record at lowquality mono (22.05 kHz) to save space, or high-quality stereo (44.1 kHz) for better sound. Note: Voice memos cannot be longer than two hours. If you record for more than two hours, iPod nano automatically starts a new voice memo to continue your recording. To record a voice memo: 1 Connect a microphone to the Dock connector port on iPod nano. 2 Set Quality to Low or High. 3 To begin recording, choose Record. 4 Hold the microphone a few inches from your mouth and speak. To pause recording, choose Pause. 5 When you finish, choose Stop and Save. Your saved recording is listed by date and time. To play a recording: m Choose Extras > Voice Memos and select the recording. Note: You won’t see a Voice Memos menu item if you’ve never connected a microphone to iPod nano. To sync voice memos with your computer: Voice memos are saved in a Recordings folder on iPod in the WAV file format. If you enable iPod nano for disk use, you can drag voice memos from the folder to copy them. If iPod nano is set to sync songs automatically (see “Syncing Music Automatically” on page 23) and you record voice memos, the voice memos are automatically synced to a playlist in iTunes (and removed from iPod nano) when you connect iPod nano. You see the new Voice Memos playlist in the source list. Learning About iPod nano Accessories iPod nano comes with some accessories, and many other accessories are available at www.apple.com/ipodstore. To purchase iPod nano accessories, go to www.apple.com/ipodstore. Chapter 5 Extra Features and Accessories 55 Available accessories include:  iPod Radio Remote  Nike + iPod Sport Kit  Apple Universal Dock  Apple Component AV Cable  Apple Composite AV Cable  Apple AV Connection Kit  Apple USB Power Adapter  iPod In-Ear Headphones  World Travel Adapter Kit  iPod Socks  iPod Earphones  Third-party accessories—such as speakers, headsets, cases, car stereo adapters, power adapters, and more To use the earphones: m Plug the earphones into the Headphones port. Then place the earbuds in your ears as shown. WARNING: Permanent hearing loss may occur if earbuds or headphones are used at high volume. You can adapt over time to a higher volume of sound that may sound normal but can be damaging to your hearing. If you experience ringing in your ears or muffled speech, stop listening and have your hearing checked. The louder the volume, the less time is required before your hearing could be affected. Hearing experts suggest that to protect your hearing:  Limit the amount of time you use earbuds or headphones at high volume.  Avoid turning up the volume to block out noisy surroundings.  Turn the volume down if you can’t hear people speaking near you. For information about setting a maximum volume limit on iPod, see “Setting the Maximum Volume Limit” on page 29. The earphones cord is adjustable.6 56 6 Tips and Troubleshooting Most problems with iPod nano can be solved quickly by following the advice in this chapter. General Suggestions Most problems with iPod nano can be solved by resetting it. First, make sure iPod nano is charged. To reset iPod nano: 1 Toggle the Hold switch on and off (slide it to HOLD and then back again). 2 Press and hold the Menu and Center buttons for at least 6 seconds, until the Apple logo appears. If iPod nano won’t turn on or respond  Make sure the Hold switch isn’t set to HOLD.  The iPod nano battery might need to be recharged. Connect iPod nano to your computer or to an Apple USB Power Adapter and let the battery recharge. Look for the lightning bolt icon on the iPod nano screen to verify that iPod nano is receiving a charge. The 5 Rs: Reset, Retry, Restart, Reinstall, Restore Remember these five basic suggestions if you have a problem with iPod nano. Try these steps one at a time until your issue is resolved. If one of the following doesn’t help, read on for solutions to specific problems.  Reset iPod nano. See “General Suggestions,” below.  Retry with a different USB port if you cannot see iPod nano in iTunes.  Restart your computer, and make sure you have the latest software updates installed.  Reinstall iTunes software from the latest version on the web.  Restore iPod nano. See “Updating and Restoring iPod Software” on page 61.Chapter 6 Tips and Troubleshooting 57 To charge the battery, connect iPod nano to a USB 2.0 on your computer. Connecting iPod nano to a USB port on your keyboard won’t charge the battery, unless your keyboard has a high-powered USB 2.0 port.  Try the 5 Rs, one by one, until iPod nano responds. If you want to disconnect iPod nano, but you see the message “Connected” or “Sync in Progress”  If iPod nano is syncing music, wait for it to complete.  Select iPod nano in the iTunes source list and click the Eject (C) button.  If iPod nano disappears from the list of devices in the iTunes source list, but you still see the “Connected” or “Sync in Progress” message on the iPod nano screen, disconnect iPod nano.  If iPod nano doesn’t disappear from the list of devices in the iTunes source list, drag the iPod nano icon from the desktop to the Trash (if you’re using a Mac) or, if you’re using a Windows PC, eject the device in My Computer or click the Safely Remove Hardware icon in the system tray and select iPod nano. If you still see the “Connected” or “Sync in Progress” message, restart your computer and eject iPod nano again. If iPod nano isn’t playing music  Make sure the Hold switch isn’t set to HOLD.  Make sure the headphone connector is pushed in all the way.  Make sure the volume is adjusted properly. A maximum volume limit might have been set. You can change or remove it by using Settings > Volume Limit. See “Setting the Maximum Volume Limit” on page 29.  iPod nano might be paused. Try pressing the Play/Pause button.  Make sure you’re using iTunes 7.4 or later (go to www.apple.com/ipod/start). Songs purchased from the iTunes Store using earlier versions of iTunes won’t play on iPod nano until you upgrade iTunes.  If you’re using the iPod Universal Dock, make sure the iPod nano is seated firmly in the Dock and make sure all cables are connected properly. If you connect iPod nano to your computer and nothing happens  Make sure you have installed the latest iTunes software from www.apple.com/ipod/start.  Try connecting to a different USB port on your computer. Note: A USB 2.0 port is recommended to connect iPod nano. USB 1.1 is significantly slower than USB 2.0. If you have a Windows PC that doesn’t have a USB 2.0 port, in some cases you can purchase and install a USB 2.0 card. For more information, go to www.apple.com/ipod.  iPod nano might need to be reset (see page 56). 58 Chapter 6 Tips and Troubleshooting  If you’re connecting iPod nano to a portable or laptop computer using the iPod Dock Connector to USB 2.0 Cable, connect the computer to a power outlet before connecting iPod nano.  Make sure you have the required computer and software. See “If you want to doublecheck the system requirements” on page 60.  Check the cable connections. Unplug the cable at both ends and make sure no foreign objects are in the USB ports. Then plug the cable back in securely. Make sure the connectors on the cables are oriented correctly. They can be inserted only one way.  Try restarting your computer.  If none of the previous suggestions solves your problems, you might need to restore iPod nano software. See “Updating and Restoring iPod Software” on page 61. If iPod nano displays a “Connect to Power” message This message may appear if iPod nano is exceptionally low on power and the battery needs to be charged before iPod nano can communicate with your computer. To charge the battery, connect iPod nano to a USB 2.0 port on your computer. Leave iPod nano connected to your computer until the message disappears and iPod nano appears in iTunes or the Finder. Depending on how depleted the battery is, you may need to charge iPod nano for up to 30 minutes before it will start up. To charge iPod nano more quickly, use the optional Apple USB Power Adapter. Note: Connecting iPod nano to a USB port on your keyboard won’t charge the battery, unless your keyboard has a high-powered USB 2.0 port. If iPod nano displays a “Use iTunes to restore” message  Make sure you have the latest version of iTunes on your computer (download it from www.apple.com/ipod/start).  Connect iPod nano to your computer. When iTunes opens, follow the onscreen prompts to restore iPod nano.  If restoring iPod nano doesn’t solve the problem, iPod nano may need to be repaired. You can arrange for service at the iPod Service & Support website: www.apple.com/support/ipod If songs or data sync more slowly over USB 2.0  If you sync a large number of songs or amount of data using USB 2.0 and the iPod nano battery is low, iPod nano syncs the information at a reduced speed in order to conserve battery power.  If you want to sync at higher speeds, you can stop syncing and keep the iPod nano connected so that it can recharge, or connect it to the optional iPod USB 2.0 Power Adapter. Let iPod nano charge for about an hour, and then resume syncing your music or data.Chapter 6 Tips and Troubleshooting 59 If you can’t add a song or other item to iPod nano The song may have been encoded in a format that iPod nano doesn’t support. The following audio file formats are supported by iPod nano. These include formats for audiobooks and podcasting:  AAC (M4A, M4B, M4P, up to 320 Kbps)  Apple Lossless (a high-quality compressed format)  MP3 (up to 320 Kbps)  MP3 Variable Bit Rate (VBR)  WAV  AA (audible.com spoken word, formats 2, 3, and 4)  AIFF A song encoded using Apple Lossless format has full CD-quality sound, but takes up only about half as much space as a song encoded using AIFF or WAV format. The same song encoded in AAC or MP3 format takes up even less space. When you import music from a CD using iTunes, it’s converted to AAC format by default. Using iTunes for Windows, you can convert nonprotected WMA files to AAC or MP3 format. This can be useful if you have a library of music encoded in WMA format. iPod nano doesn’t support WMA, MPEG Layer 1, MPEG Layer 2 audio files, or audible.com format 1. If you have a song in iTunes that isn’t supported by iPod nano, you can convert it to a format iPod nano supports. For more information, see iTunes Help. If you accidentally set iPod nano to use a language you don’t understand You can reset the language. 1 Press and hold Menu until the main menu appears. 2 Choose the sixth menu item (Settings). 3 Choose the last menu item (Reset Settings). 4 Choose the left item (Reset) and select a language. Other iPod nano settings, such as song repeat, are also reset. Note: If you added or removed items from the iPod nano main menu (see “Adding or Removing Items from the Main Menu” on page 9) the Settings menu item may be in a different place. If you can’t find the Reset Settings menu item, you can restore iPod nano to its original state and choose a language you understand. See “Updating and Restoring iPod Software” on page 61. If you can’t see videos or photos on your TV  You must use RCA-type cables made specifically for iPod nano, such as the Apple Component or Apple Composite AV cables, to connect iPod nano to your TV. Other similar RCA-type cables won’t work.60 Chapter 6 Tips and Troubleshooting  Make sure your TV is set to display images from the correct input source (see the documentation that came with your TV for more information).  Make sure all cables are connected correctly (see “Watching Videos on a TV Connected to iPod nano” on page 38).  Make sure the yellow end of the Apple Composite AV Cable is connected to the video port on your TV.  If you’re trying to watch a video, go to Videos > Settings and set TV Out to On, and then try again. If you’re trying to view a slideshow, go to Photos > Slideshow Settings and set TV Out to On, and then try again.  If that doesn’t work, go to Videos > Settings (for video) or Photos > Settings (for a slideshow) and set TV Signal to PAL or NTSC, depending on which type of TV you have. Try both settings. If you want to double-check the system requirements To use iPod nano, you must have:  One of the following computer configurations:  A Mac with a USB 2.0 port  A Windows PC with a USB 2.0 or a USB 2.0 card installed  One of the following operating systems:  Mac OS X v10.4.9 or later  Windows Vista  Windows XP Home or Professional with Service Pack 2 or later  iTunes 7.6 or later (iTunes can be downloaded from www.apple.com/ipod/start) If your Windows PC doesn’t have a USB 2.0 port, you can purchase and install a USB 2.0 card. For more information on cables and compatible USB cards, go to www.apple.com/ipod. On the Mac, iPhoto 4.0.3 or later is recommended for adding photos and albums to iPod nano. This software is optional. iPhoto might already be installed on your Mac. Check the Applications folder. If you have iPhoto 4 you can update it by choosing Apple () > Software Update. On a Windows PC, iPod nano can sync photo collections automatically from Adobe Photoshop Album 2.0 or later, and Adobe Photoshop Elements 3.0 or later, available at www.adobe.com. This software is optional. On both Mac and Windows PC, iPod nano can sync digital photos from folders on your computer’s hard disk.Chapter 6 Tips and Troubleshooting 61 If you want to use iPod nano with a Mac and a Windows PC If you’re using iPod nano with a Mac and you want to use it with a Windows PC, you must restore the iPod software for use with the PC (see “Updating and Restoring iPod Software” on page 61). Restoring the iPod software erases all data from iPod nano, including all songs. You cannot switch from using iPod nano with a Mac to using it with a Windows PC without erasing all data on iPod nano. If you lock the iPod nano screen and can’t unlock it Normally, if you can connect iPod nano to the computer it’s authorized to work with, iPod nano automatically unlocks. If the computer authorized to work with iPod nano is unavailable, you can connect iPod nano to another computer and use iTunes to restore iPod software. See the next section for more information. If you want to change the screen lock combination and you can’t remember the current combination, you must restore the iPod software and then set a new combination. Updating and Restoring iPod Software You can use iTunes to update or restore iPod software. It’s recommended that you update iPod nano to use the latest software. You can also restore the software, which puts iPod nano back to its original state.  If you choose to update, the software is updated, but your settings and songs aren’t affected.  If you choose to restore, all data is erased from iPod nano, including songs, videos, files, contacts, photos, calendar information, and any other data. All iPod nano settings are restored to their original state. To update or restore iPod nano: 1 Make sure you have an Internet connection and have installed the latest version of iTunes from www.apple.com/ipod/start. 2 Connect iPod nano to your computer. 3 In iTunes, select iPod nano in the source list and click the Summary tab. The Version section tells you whether iPod nano is up to date or needs a newer version of the software. 4 Click Update to install the latest version of the software. 5 If necessary, click Restore to restore iPod nano to its original settings (this erases all data from iPod nano). Follow the onscreen instructions to complete the restore process.7 62 7 Safety and Cleaning Read the following important safety and handling information for Apple iPods. Keep the iPod Safety Guide and the features guide for your iPod handy for future reference. Important Safety Information Handling iPod Do not bend, drop, crush, puncture, incinerate, or open iPod. Avoiding water and wet locations Do not use iPod in rain, or near washbasins or other wet locations. Take care not to spill any food or liquid into iPod. In case iPod gets wet, unplug all cables, turn iPod off, and slide the Hold switch (if available) to HOLD before cleaning, and allow it to dry thoroughly before turning it on again. Repairing iPod Never attempt to repair iPod yourself. iPod does not contain any userserviceable parts. For service information, choose iPod Help from the Help menu in iTunes or go to www.apple.com/support/ipod. The rechargeable battery in iPod should be replaced only by an Apple Authorized Service Provider. For more information about batteries, go to www.apple.com/batteries. ± Read all safety information below and operating instructions before using iPod to avoid injury. WARNING: Failure to follow these safety instructions could result in fire, electric shock, or other injury or damage.Chapter 7 Safety and Cleaning 63 Using the Apple USB Power Adapter (available separately) If you use the Apple USB Power Adapter (sold separately at www.apple.com/ipodstore) to charge iPod, make sure that the power adapter is fully assembled before you plug it into a power outlet. Then insert the Apple USB Power Adapter firmly into the power outlet. Do not connect or disconnect the Apple USB Power Adapter with wet hands. Do not use any power adapter other than an Apple iPod power adapter to charge your iPod. The iPod USB Power Adapter may become warm during normal use. Always allow adequate ventilation around the iPod USB Power Adapter and use care when handling. Unplug the iPod USB Power Adapter if any of the following conditions exist:  The power cord or plug has become frayed or damaged.  The adapter is exposed to rain, liquids, or excessive moisture.  The adapter case has become damaged.  You suspect the adapter needs service or repair.  You want to clean the adapter. Avoiding hearing damage Permanent hearing loss may occur if earbuds or headphones are used at high volume. Set the volume to a safe level. You can adapt over time to a higher volume of sound that may sound normal but can be damaging to your hearing. If you experience ringing in your ears or muffled speech, stop listening and have your hearing checked. The louder the volume, the less time is required before your hearing could be affected. Hearing experts suggest that to protect your hearing:  Limit the amount of time you use earbuds or headphones at high volume.  Avoid turning up the volume to block out noisy surroundings.  Turn the volume down if you can’t hear people speaking near you. For information about how to set a maximum volume limit on iPod, see “Setting the Maximum Volume Limit” on page 29. Using headphones safely Use of headphones while operating a vehicle is not recommended and is illegal in some areas. Be careful and attentive while driving. Stop using iPod if you find it disruptive or distracting while operating any type of vehicle or performing any other activity that requires your full attention. Avoiding seizures, blackouts, and eye strain If you have experienced seizures or blackouts, or if you have a family history of such occurrences, please consult a physician before playing video games on iPod (if available). Discontinue use and consult a physician if you experience: convulsion, eye or muscle twitching, loss of awareness, involuntary movements, or disorientation. When watching videos or playing games on iPod (if available), avoid prolonged use and take breaks to prevent eye strain.64 Chapter 7 Safety and Cleaning Important Handling Information Carrying iPod iPod contains sensitive components, including, in some cases, a hard drive. Do not bend, drop, or crush iPod. If you are concerned about scratching iPod, you can use one of the many cases sold separately. Using connectors and ports Never force a connector into a port. Check for obstructions on the port. If the connector and port don’t join with reasonable ease, they probably don’t match. Make sure that the connector matches the port and that you have positioned the connector correctly in relation to the port. Keeping iPod within acceptable temperatures Operate iPod in a place where the temperature is always between 0º and 35º C (32º to 95º F). iPod play time might temporarily shorten in low-temperature conditions. Store iPod in a place where the temperature is always between -20º and 45º C (-4º to 113º F). Don’t leave iPod in your car, because temperatures in parked cars can exceed this range. When you’re using iPod or charging the battery, it is normal for iPod to get warm. The exterior of iPod functions as a cooling surface that transfers heat from inside the unit to the cooler air outside. Keeping the outside of iPod clean To clean iPod, unplug all cables, turn iPod off, and slide the Hold switch (if available) to HOLD. Then use a soft, slightly damp, lint-free cloth. Avoid getting moisture in openings. Don’t use window cleaners, household cleaners, aerosol sprays, solvents, alcohol, ammonia, or abrasives to clean iPod. Disposing of iPod properly For information about the proper disposal of iPod, including other important regulatory compliance information, see “Regulatory Compliance Information” on page 66. NOTICE: Failure to follow these handling instructions could result in damage to iPod or other property.8 65 8 Learning More, Service, and Support You can find more information about using iPod nano in onscreen help and on the web. The following table describes where to get more iPod-related software and service information. To learn about Do this Service and support, discussions, tutorials, and Apple software downloads Go to: www.apple.com/support/ipodnano Using iTunes Open iTunes and choose Help > iTunes Help. For an online iTunes tutorial (available in some areas only), go to: www.apple.com/support/itunes Using iPhoto (on Mac OS X) Open iPhoto and choose Help > iPhoto Help. Using iSync (on Mac OS X) Open iSync and choose Help > iSync Help. Using iCal (on Mac OS X) Open iCal and choose Help > iCal Help. The latest information on iPod nano Go to: www.apple.com/ipodnano Registering iPod nano To register iPod nano, install iTunes on your computer and connect iPod nano. Finding the iPod nano serial number Look at the back of iPod nano or choose Settings > About and press the Center button. In iTunes (with iPod nano connected to your computer), select iPod nano in the source list and click the Settings tab. Obtaining warranty service First follow the advice in this booklet, the onscreen help, and online resources. Then go to: www.apple.com/support/ipodnano/ service66 Regulatory Compliance Information FCC Compliance Statement This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or TV reception is suspected. Radio and TV Interference This computer equipment generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and TV reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or TV reception, try to correct the interference by using one or more of the following measures:  Turn the TV or radio antenna until the interference stops.  Move the computer to one side or the other of the TV or radio.  Move the computer farther away from the TV or radio.  Plug the computer in to an outlet that is on a different circuit from the TV or radio. (That is, make certain the computer and the TV or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/TV technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product. This product was tested for EMC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, TV sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple Authorized Reseller. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only): Apple Inc. Product Compliance, 1 Infinite Loop M/S 26-A, Cupertino, CA 95014-2084, 408-974-2000. Industry Canada Statement This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la classe B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. VCCI Class B Statement Korea Class B Statement (૶ ૺૺဧ ઠધබ 67 Russia European Community Disposal and Recycling Information Your iPod must be disposed of properly according to local laws and regulations. Because this product contains a battery, the product must be disposed of separately from household waste. When your iPod reaches its end of life, contact Apple or your local authorities to learn about recycling options. For information about Apple’s recycling program, go to: www.apple.com/environment/recycling Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd. China: Taiwan: European Union—Disposal Information: This symbol means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Apple and the Environment At Apple, we recognize our responsibility to minimize the environmental impacts of our operations and products. For more information, go to: www.apple.com/environment © 2008 Apple Inc. All rights reserved. Apple, the Apple logo, FireWire, iCal, iLife, iPhoto, iPod, iPod Socks, iTunes, Mac, Macintosh, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, the FireWire logo, and Shuffle are trademarks of Apple Inc. iTunes Store is a service mark of Apple Inc. NIKE is a trademark of NIKE, Inc. and its affiliates and is used under license. Other company and product names mentioned herein may be trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. All understandings, agreements, or warranties, if any, take place directly between the vendors and the prospective users. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. The product described in this manual incorporates copyright protection technology that is protected by method claims of certain U.S. patents and other intellectual property rights owned by Macrovision Corporation and other rights owners. Use of this copyright protection technology must be authorized by Macrovision Corporation and is intended for home and other limited viewing uses only unless otherwise authorized by Macrovision Corporation. Reverse engineering or disassembly is prohibited. Apparatus Claims of U.S. Patent Nos. 4,631,603, 4,577,216, 4,819,098 and 4,907,093 licensed for limited viewing uses only. 019-1149/01-2008Index 68 Index A accessories for iPod 54 adding album artwork 21 adding menu items 9, 27 adding music disconnecting iPod 12 from more than one computer 23, 35 manually 24 methods 22 On-The-Go playlists 28 tutorial 65 adding photos about 40 all or selected photos 41, 42 automatically 41 from computer to iPod 41 from iPod to computer 43 full-resolution image 42 address book, syncing 51 Adobe Photoshop Album 60 Adobe Photoshop Elements 60 alarms deleting 48 setting 48 album artwork adding 21 viewing 31 albums, purchasing 19 audiobooks purchasing 19 setting play speed 32 AV cables 38, 39, 45 B backlight setting timer 9 turning on 6, 9 battery charge states when disconnected 16 charging 14 rechargeable 16 replacing 16 very low 15, 58 viewing charge status 14 brightness setting 10 browsing iTunes Store 19 podcasts 19 quickly 7 songs 6, 26 videos 6, 19 with Cover Flow 7 buttons Center 5 disabling with Hold switch 6 Eject 13 buying. See purchasing C calendar events, syncing 51 Center button, using 5, 26 Charging, Please Wait message 15, 58 charging the battery about 14 using the iPod USB Power Adapter 15 using your computer 14 when battery very low 15, 58 cleaning iPod 64 Click Wheel browsing songs 26 turning off the Click Wheel sound 8 using 5 clocks adding for other time zones 47 settings 47 close captions 38 compilations 27 component AV cable 38, 39, 45 composite AV cable 38, 39, 45 computer adding photos to iPod 41 charging the battery 14 connecting iPod 10 getting photos from iPod 43 importing photos from camera 40Index 69 problems connecting iPod 57 requirements 60 connecting iPod about 10 charging the battery 14 to a TV 39, 45 Connect to Power message 15 contacts sorting 53 syncing 51 controls disabling with Hold switch 8 using 5 converting unprotected WMA files 59 converting videos for use with iPod 34 Cover Flow 7 customizing the Music menu 27 D data files, storing on iPod 46 date and time setting 47 viewing 47 determining battery charge 16 diamond icon on scrubber bar 6 digital photos. See photos disconnecting iPod about 10 during music update 12 ejecting first 12 instructions 13 troubleshooting 57 disk, using iPod as 46 displaying time in title bar 47 downloading podcasts 19 video podcasts 34 See also adding; syncing E Eject button 13 ejecting before disconnecting 12 external disk, using iPod as 46 F fast-forwarding a song or video 6 features of iPod 4 file formats, supported 59 finding your iPod serial number 6 fit video to screen 38 full-resolution images 42 G games 49 getting help 65 getting information about your iPod 10 getting started with iPod 60 H handling information 62 hearing loss warning 55 help, getting 65 Hold switch 6, 8 I iCal, getting help 65 Image Capture, importing photos to a Mac 41 images. See photos importing contacts, calendars, and to-do lists. See syncing importing photos from camera to computer 40 See also adding photos importing videos 34 iPhoto getting help 40, 65 importing photos from camera 40 recommended version 60 iPod Dock 10 iPod Dock Connector 10 iPod Updater application 61 iPod USB power adapter 14 iSync, getting help 65 iTunes ejecting iPod 13 getting help 65 setting not to open automatically 46 Sound Check 30 Store 19 iTunes Library, adding songs 20 iTunes Store browsing 19 browsing videos 34 searching 19 signing in 18, 33 L language resetting 59 specifying 10 letterbox 38 library, adding songs 20 lightning bolt on battery icon 14 locating your iPod serial number 6 locking iPod screen 50 lyrics adding 21 viewing on iPod 3070 Index M Mac OS X operating system 60 main menu adding or removing items 9 opening 5 settings 9, 27 main menu, returning to 6 managing iPod manually 24 manually adding 24 maximum volume limit, setting 29 memos, recording 54 menu items adding or removing 9, 27 choosing 6 returning to main menu 6 returning to previous menu 6 modifying playlists 24 movies syncing 37 syncing selected 36 See also videos music iPod not playing 57 purchasing 19 rating 28 setting for slideshows 44 tutorial 65 See also adding music; songs Music menu, customizing 27 music videos syncing 24 See also videos N navigating quickly 7 notes, storing and reading 53 Now Playing screen moving to any point in a song or video 6 scrubber bar 6 shuffling songs or albums 27 NTSC TV 38, 44 O On-The-Go playlists copying to computer 28 making 27 rating songs 28 saving 28 operating system requirements 60 overview of iPod features 4 P PAL TV 38, 44 pausing a song 6 a video 6 phone numbers, syncing 51 photo collections, adding automatically 41 photo library 41 photos adding and viewing 40 deleting 42, 43 full-resolution 42 importing to Windows PC 41 importing using Image Capture 41 syncing 41, 42 viewing on iPod 43 playing games 49 songs 6 videos 6 playlists adding songs 6, 24 making on iPod 27 modifying 24 On-The-Go 27 setting for slideshows 45 plug on battery icon 14 podcasting 31 podcasts browsing 19 downloading 19 downloading video podcasts 34 listening 31 subscribing 19 updating 25 ports RCA video and audio 39, 45 USB 60 power adapter safety 63 Power Search in iTunes Store 19 previous menu, returning to 6 problems. See troubleshooting purchasing songs, albums, audiobooks 19 purchasing videos 34 Q quick navigation 7 R radio accessory 32 random play 6 rating songs 28 RCA video and audio ports 39, 45 rechargeable batteries 16 recording voice memos 54 registering iPod 65 relative volume, playing songs at 30 removing menu items 9, 27 repairing iPod 62Index 71 replacing battery 16 replaying a song or video 6 requirements computer 60 operating system 60 reset all settings 10 resetting iPod 6, 56 resetting the language 59 restore message 58 restoring iPod software 61 rewinding a song or video 6 S Safely Remove Hardware icon 13 safety considerations setting up iPod 62 safety information 62 saving On-The-Go playlists 28 screen lock 50 scrolling quickly 7 scrubber bar 6 searching iPod 7 iTunes Store 19 Select button. See Center button serial number 6, 10 serial number, locating 65 service and support 65 sets of songs. See playlists setting combination for iPod 50 settings about your iPod 10 alarm 48 audiobook play speed 32 backlight timer 9 brightness 10 Click Wheel sound 8 date and time 47 language 10 main menu 9, 27 PAL or NTSC TV 38, 44 playing songs at relative volume 30 repeating songs 27 reset all 10 shuffle songs 27 sleep timer 48 slideshow 44 TV 38 volume limit 29 shuffling songs on iPod 6, 27 sleep mode and charging the battery 14 sleep timer, setting 48 slideshows background music 44 random order 44 setting playlist 45 settings 44 viewing on iPod 45 software getting help 65 iPhoto 60 iPod Updater 61 support versions 60 updating 61 songs adding to On-The-Go playlists 6 browsing 6 browsing and playing 26 entering names 21 fast-forwarding 6 pausing 6 playing 6 playing at relative volume 30 purchasing 19 rating 28 repeating 27 replaying 6 rewinding 6 shuffling 6, 27 skipping ahead 6 viewing lyrics 21 See also music sorting contacts 53 Sound Check 30 standard TV 38 stopwatch 48, 49 storing data files on iPod 46 notes on iPod 53 subscribing to podcasts 19 supported operating systems 60 suppressing iTunes from opening 46 syncing address book 51 movies 37 music 22 music videos 24 photos 41, 42 selected movies 36 selected videos 36 to-do lists 51 TV shows 37 videos 35 See also adding T third-party accessories 55 time, displaying in title bar 47 timer, setting for backlight 9 time zones, clocks for 4772 Index title bar, displaying time 47 to-do lists, syncing 51 transitions for slides 44 troubleshooting connecting iPod to computer 57 cross-platform use 61 disconnecting iPod 57 iPod not playing music 57 iPod won’t respond 56 resetting iPod 56 restore message 58 safety considerations 62 setting incorrect language 59 slow syncing of music or data 58 software update and restore 61 TV slideshows 59 unlocking iPod screen 61 turning iPod on and off 6 tutorial 65 TV connecting to iPod 39, 45 PAL or NTSC 38, 44 settings 38 viewing slideshows 39, 45 TV shows syncing 37 See also videos U unlocking iPod screen 51, 61 unresponsive iPod 56 unsupported audio file formats 59 updating and restoring software 61 USB 2.0 port recommendation 60 slow syncing of music or data 58 USB port on keyboard 11, 57 Use iTunes to restore message in display 58 V video captions 38 video podcasts downloading 33, 34 viewing on a TV 38 videos adding to iPod 35 browsing 6 browsing in iTunes Store 19, 34 converting 34 fast-forwarding 6 importing into iTunes 34 pausing 6 playing 6 purchasing 33, 34 replaying 6 rewinding 6 skipping ahead 6 syncing 35 viewing on a TV 38 viewing on iPod 38 viewing album artwork 31 viewing lyrics 30 viewing music videos 38 viewing photos 43 viewing slideshows on a TV 39, 45 on iPod 45 settings 44 troubleshooting 59 voice memos recording 54 syncing with your computer 54 volume changing 6 setting maximum limit 29 W warranty service 65 widescreen TV 38 Windows importing photos 41 supported operating systems 60 troubleshooting 61 WMA files, converting 59 iTunes Video and Audio Asset Guide 5.0  Contents Overview 4 Introduction 4 Changes Made in this Release 4 What’s New in the iTunes Video and Audio Asset Guide 5.0? 4 Music Audio Content Profiles 6 Music Audio Source Profile 6 Pre-Cut Ringtone Source Profile 6 Music Album Cover Art Profile 7 Music Digital Booklet Profile 7 Content Considerations 8 Music Video Content Profiles 9 Music Video SD Source Profile 9 NTSC 9 PAL 10 Music Video HD Source Profile 10 Music Video Audio Source Profile 11 Music Video Audio/Video Container 11 Music Video Screen Capture Image Profile 12 Television Content Profiles 13 HD TV Source Profile 13 SD TV Source Profile 14 NTSC 14 PAL 14 TV Audio Source Profile 15 MPEG-2 Program Stream Container 15 QuickTime Container 16 TV Audio/Video Container 16 MPEG-2 Program Stream Container 16 QuickTime Container 16 TV Closed Captioning Profile 17 TV Cover Art Profile 18 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 2TV Content Considerations 19 Film Content Profiles 20 Film HD Source Profile 20 Film SD Source Profile 20 NTSC 20 PAL 21 Film Audio Source Profile 21 Film Audio/Video and Alt-Audio Container 22 Film Closed Captioning Profile 23 Film iTunes Timed Text Profile 23 Film Dub Card Video Profile 24 Dub Card Video Profile 24 Film Chapter Image Profile 25 Film Poster Art Profile 25 Film Content Considerations 26 XML 27 Revision History 28 Previous Spec Revisions 28 Audio Channel Assignments 30 How to Apply Audio Channel Assignments 30 Table 1: Audio Channel Assignment Labels 36 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsThis document provides detailed delivery information for all accepted media and files for the iTunes Store, including music, music video, television, and movies. If further details are required, contact your iTunes Technical Representative. Introduction Quality is important to us at iTunes. We expect to receive the highest-quality assets available. Our product must meet or exceed the quality of the physical product already out in the marketplace. For example, if 5.1 surround sound or closed captions exist on the physical version of the product, those must be provided. If the physical product gives the chapters actual names (as opposed to Chapter 1, Chapter 2, and so on), then our product should have those same chapter titles. If the album is in stereo, stereo audio must be provided. Changes Made in this Release Date/Version Changes Made Album cover art and poster art requirements have changed. Removed TIFF from the list of recommended image formats and removed DPI requirements. Added delivery requirements for dub card video. 96Khz audio is now supported. May 30, 2012 - Version 5.0 For a complete history of changes, see “Previous Spec Revisions” (page 28). What’s New in the iTunes Video and Audio Asset Guide 5.0? Music: Album Cover Art Album cover art must be at least 1400 x 1400 pixels (2400 x 2400 pixels recommended for best results) with a 1:1 aspect ratio. The file must be a high-quality JPEG with .jpg extension or PNG with .png extension. Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 4 Overviewdummy tet to make page break Music: Audio Source Profile The iTunes Store accepts audio with a sampling rate of 96Khz and 24-bit resolution for album tracks and ringtones. TV: Cover Art TV cover art must be at least 1400 x 1400 pixels (2400 x 2400 pixels recommended for best results) with a 1:1 aspect ratio. The file must be a high-quality JPEG with .jpg extension or PNG with .png extension. Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Film: Poster Art Poster art must be at least 1400 x 2100 pixels with a 2:3 aspect ratio. The file must be a high-quality JPEG with .jpg extension or PNG with .png extension. Don't increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Film: Dub Card Video Added delivery requirements for dub card video files. See “Film Dub Card Video Profile” (page 24). Overview Changes Made in this Release 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 5Music Audio Source Profile The iTunes Store accepts audio with a sampling rate of 44.1Khz and 16-bit or 24-bit resolution and 96Khz with 24-bit resolution. Note that the audio source must be stereo unless it does not exist. Uncompressed audio formats supported are: Format Container Type Qualified CODEC Pulse-Code Modulation (PCM) WAV (.wav) QuickTime http://www.apple.com/quicktime iTunes http://www.apple.com/itunes Apple Lossless (ALAC) M4A (.m4a) CAF (.caf) iTunes Producer Free Lossless Audio Codec (FLAC) FLAC (.flac) FLAC http://flac.sourceforge.net All other audio formats will be rejected. Important All audio must be generated using a CODEC qualified and approved by Apple. Pre-Cut Ringtone Source Profile The iTunes Store accepts pre-cut ringtones with a sampling rate of 44.1 kHz and 16-bit or 24-bit resolution and 96Khz with 24-bit resolution. Note that the audio source must be stereo unless it does not exist. The audio file must be lossless and be one of these formats: WAV, FLAC, ALAC. The minimum length is 5 seconds and the maximum length is 30 seconds. See the table above for the uncompressed audio formats that are supported. All other audio formats will be rejected. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 6 Music Audio Content ProfilesImportant All audio must be generated using a CODEC qualified and approved by Apple. Music Album Cover Art Profile ● JPEG with .jpg extension (quality unconstrained) or PNG with .png extension ● Color space: RGB (screen standard) ● Minimum size of 1400 x 1400 pixels. 2400 x 2400 pixels recommended for best results. ● Images must be square ● File formats: JPEG or PNG (100% quality) ● 1:1 aspect ratio Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Important CMYK (print standard) images will not be accepted. Music Digital Booklet Profile ● PDF format with .pdf extension ● Four-page minimum ● No more than 10 MB in size ● All fonts embedded ● 11 in x 8.264 in (28 cm x 21 cm) ● RGB color ● Horizontal presentation ● All images full-bleed as shown in sample pages Important These booklets are expressly designed for the iTunes Store format, and cannot be reproductions of the liner notes with borders to increase their size. Music Audio Content Profiles Music Album Cover Art Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 7Content Considerations ● When saving as PDF, make sure the document opens full screen with no negative space surrounding the document. ● If the digital booklet is many pages, consider using fewer images or optimizing images to achieve lower overall file size. ● Printer’s marks are not allowed. ● You cannot sell or advertise other products or services. No other promotional sites are allowed. ● No links to anything outside of the booklet, except to the artist and/or label website(s). ● No time-sensitive information (for example, a promotion or dates for an upcoming tour or concert). Music Audio Content Profiles Music Digital Booklet Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 8Note Chaptering is not supported for music videos. Music Video SD Source Profile NTSC ● MPEG-2 Program Stream Main Profile ● 4:2:0 chroma sampling ● ITU-R BT.601 color space ● 15 Mbps minimum ● Long GOP ● 640 fixed horizontal dimension ● Variable size vertical dimension depending on aspect ratio of source, maximum size of 480 ● Square pixel aspect ratio (1:1) ● Native frame rate of original source: ● 29.97 interlaced frames per second video source can be delivered either interlaced or de-interlaced properly tagged as progressive ● 24 frames per second must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Field dominance must be properly tagged (top field first, bottom field first, or progressive) ● Telecine materials will not be accepted ● For mixed frame rate material please contact your iTunes Technical Representative ● Interlaced content must be tagged non-progressive and field ordering must be defined in the stream. ● Crop inactive pixels and maintain fields. All edges must have active pixels for greater than 90% of the duration of the video. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 9 Music Video Content ProfilesPAL ● MPEG-2 Program Stream Main Profile ● 4:2:0 chroma sampling ● ITU-R BT.601 color space ● 15 Mbps minimum ● Long GOP ● 640 fixed horizontal dimension ● Variable size vertical dimension depending on aspect ratio of source, maximum size of 480 ● Square pixel aspect ratio (1:1) ● Native frame rate of original source: ● 25 interlaced frames per second sourced from video must be delivered de-interlaced and properly tagged as progressive ● 24 and 25 frames per second sourced from film must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Field dominance must be properly tagged (top field first, bottom field first, or progressive) ● Telecine or interlaced materials will not be accepted ● For mixed frame rate material please contact your iTunes Technical Representative ● Crop inactive pixels. All edges must have active pixels for greater than 90% of the duration of the video. Important All video must begin and end with at least one black frame. Music Video HD Source Profile ● Apple ProRes 422 (HQ) ● VBR expected at ~220 Mbps ● 1920 x 1080 square pixel aspect ratio material ● Native frame rate of original source: ● 29.97 interlaced frames per second for video sourced ● 24 or 25 progressive frames per second for film sourced ● 23.976 progressive frames for inverse telecine sourced from film Music Video Content Profiles Music Video HD Source Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 10● Telecine materials will not be accepted ● HD source may be delivered matted: letterbox, pillarbox, or windowbox. ● The HD source may be delivered in its full-frame state with metadata included to specify the crop rectangle. See “Music Video Single” in the iTunes Package Music Specification for details. ● If the HD source file is not delivered matted or if there are no inactive pixels, we recommend setting all crop dimension attributes to '0' (zero). Important All video must begin and end with at least one black frame. Music Video Audio Source Profile If 5.1 Surround is available for a music video audio source, the audio should be delivered in 5.1 Surround in addition to providing a stereo version; otherwise the audio may be delivered in Stereo only. Surround ● LPCM in either Big Endian or Little Endian, 16-bit or 24-bit, at least 48kHz ● Expected channels: L, R, C, LFE, Ls, Rs Stereo ● MPEG-1 layer II stereo ● 384 kpbs ● 48Khz ● Included in the same file as the delivered video Music Video Audio/Video Container ● Deliver all content in an MPEG-2 Program Stream file container ● The .mpg file extension is expected for all MPEG-2 content ● Audio must be delivered muxed with the video stream Music Video Content Profiles Music Video Audio Source Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 11Note Closed-captioning is currently not supported for music videos. Music Video Screen Capture Image Profile ● Screen capture from delivered video ● JPEG with .jpg extension (quality unconstrained) or PNG with .png extension ● RGB (screen standard) ● Minimum dimensions: Must be 640 x 100 pixels. ● Variable size vertical dimension. Must be same aspect ratio as video source, with a maximum size of 480. ● Only the active pixel area may be included. Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Images must be taken directly from the video. Important CMYK (print standard) images will not be accepted. Music Video Content Profiles Music Video Screen Capture Image Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 12HD TV Source Profile ● Apple ProRes 422 (HQ) ● ITU-R BT.709 color space, file tagged correctly as 709 ● VBR expected at 88-220 Mbps ● 1920 x 1080 or 1280 x 720 square pixel aspect ratio material* ● 23.976, 24, 25, 29.97 frame rates are supported ● Native frame rate of original source: ● 29.97 interlaced frames per second video source can be delivered either interlaced or de-interlaced properly tagged as progressive ● 24 and 25 frames per second must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Field dominance must be properly tagged (top field first, bottom field first, or progressive) ● Fields and frames may not be duplicated or eliminated to create a broadcast frame rate (for example, telecine, NTSC to PAL conversion) ● For mixed frame rate material please contact your iTunes Technical Representative ● Interlaced content must be correctly tagged as interlaced and field ordering must be defined in the QuickTime container. ● Crop dimensions should be supplied in the metadata for content with inactive pixels due to letterbox, pillarbox, or windowbox. Please refer to the iTunes Package TV Specification for further information. ● Content upscaled from SD will be rejected. * If your mezzanine library is not stored in HD D5 or HDCam-SR, contact your iTunes Technical Representative. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 13 Television Content ProfilesSD TV Source Profile NTSC ● MPEG-2 Program Stream Main Profile ● 4:2:0 chroma sampling ● ITU-R BT.601 color space ● 15 Mbps minimum ● Long GOP ● 640 fixed horizontal dimension ● Variable size vertical dimension depending on aspect ratio of source, maximum size of 480 ● Square pixel aspect ratio (1:1) ● Native frame rate of original source: ● 29.97 interlaced frames per second video source can be delivered either interlaced or de-interlaced properly tagged as progressive ● 24 frames per second must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Field dominance must be properly tagged (top field first, bottom field first, or progressive) ● Fields and frames may not be duplicated or eliminated to create a broadcast frame rate (for example, telecine, NTSC to PAL conversion) ● For mixed frame rate material please contact your iTunes Technical Representative ● Interlaced content must be tagged non-progressive and field ordering must be defined in the stream. ● Crop inactive pixels and maintain fields. All edges must have active pixels for greater than 90% of the duration of the video. ● Content may NOT be delivered letterbox, pillarbox, or windowbox. PAL ● MPEG-2 Program Stream Main Profile ● 4:2:0 chroma sampling ● ITU-R BT.601 color space ● 15 Mbps minimum Television Content Profiles SD TV Source Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 14● Long GOP ● 640 fixed horizontal dimension ● Variable size vertical dimension depending on aspect ratio of source, maximum size of 480 ● Square pixel aspect ratio (1:1) ● Native frame rate of original source: ● 25 interlaced frames per second sourced from video must be delivered de-interlaced and properly tagged as progressive ● 24 and 25 frames per second sourced from film must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Field dominance must be properly tagged (top field first, bottom field first, or progressive) ● Interlaced materials will not be accepted ● Fields and frames may not be duplicated or eliminated to create a broadcast frame rate (for example, telecine, NTSC to PAL conversion) ● For mixed frame rate material please contact your iTunes Technical Representative ● Crop inactive pixels. All edges must have active pixels for greater than 90% of the duration of the video. ● Content may NOT be delivered letterbox, pillarbox, or windowbox. Important All video must begin and end with at least one black frame. TV Audio Source Profile MPEG-2 Program Stream Container Stereo ● MPEG-1 layer II ● 384 kpbs ● 48Khz ● Included in the same file as the delivered video Television Content Profiles TV Audio Source Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 15QuickTime Container Surround ● LPCM in either Big Endian or Little Endian, 16-bit or 24-bit, at least 48kHz ● Expected channels: L, R, C, LFE, Ls, Rs Stereo ● LPCM in either Big Endian or Little Endian, 16-bit or 24-bit, at least 48kHz ● Expected Dolby Pro Logic channels: Lt, Rt or expected stereo channels: L, R TV Audio/Video Container MPEG-2 Program Stream Container ● Deliver all content in an MPEG-2 Program Stream file container. ● The .mpg file extension is expected for all MPEG-2 content. ● Audio must be delivered muxed with the video stream. QuickTime Container ● Deliver all content in a QuickTime .mov file container. ● The QuickTime .mov file extension is expected for all audio and video content. Television Content Profiles TV Audio/Video Container 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 16● Each audio channel must have an assignment. The channel assignments must match one of the options below. Note that "Lt" and "Rt" are only used for Dolby matrix audio mixdown. If audio doesn't conform, contact your iTunes Technical Representative. Option 1 5.1 Surround Tracks Stereo Tracks L R C Lfe Ls Rs Lt Rt Track 1 -- six channels Track 2 L R C Lfe Ls Rs Lt Rt Track 3 One track containing all Surround channels; Matrix Stereo with Lt in one track and Rt channel in another track L R C Lfe Ls Rs Lt Rt Option 2 Track 1 Track 2 Track 3 Track 4 Track 5 Track 6 Track 7 Track 8 One track for each channel Option 3 Track 1 -- six channels Track 2 -- two channels L R C Lfe Ls Rs Lt Rt One track containing all Surround channels; Matrix Stereo with Lt and Rt channels in one track L R C Lfe Ls Rs Option 4 Track 1 Track 2 Track 3 Track 4 Track 5 Track 6 One track for each Surround channel; Matrix Stereo with Lt and Rt channels in one track Track 7 -- two channels Lt Rt Option 5 No Surround. Stereo with L in one track and R in another track L R Track 1 Track 2 Option 6 No Surround. Stereo with both L and R channels in one track Track 1 -- two channels L R Important Refer to “Table 1: Audio Channel Assignment Labels” (page 36) for label descriptions and “How to Apply Audio Channel Assignments” (page 30) for instructions on applying audio channel assignments. TV Closed Captioning Profile Note Closed captioning can only be sent with ProRes files. ● English text in EIA 608 format. ● Delivered in the same package with the video it references. ● In a Scenarist SCC formatted file, using .scc file extension. Television Content Profiles TV Closed Captioning Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 17● SCC files must be 29.97 regardless of frame rate of the movie file. Note: Captioning workflows utilizing 23.976 FPS timecodes can be accepted but the timecodes will be regarded as 29.97 FPS. ● SCC files should preserve the timecode mode (drop or non-drop) used in your captioning process, not necessarily the mode represented in the QuickTime movie source. ● SCC files must be validated for proper sync against the associated video file using QuickTime 7 Pro. ● Captionsshould display and synchronize to within one second of the initial, audible dialog to be represented in text. The timecodes of the captions are relative to the start of the program, and not the QuickTime movie'stimecode track. Currently, the iTunes Store does not support EIA 708 (ATSC closed captioning) or Teletext. MacCaption is a tool you can use to create .scc files: http://www.cpcweb.com/products/. (Note that this product is not endorsed by Apple. Apple cannot and does not provide support for third-party products.) Note If closed caption data is available for any broadcast or web delivery system, it must be suppled to iTunes. TV Cover Art Profile ● JPEG with .jpg extension (quality unconstrained) or PNG with .png extension ● RGB (screen standard) ● 1400 x 1400 pixels minimum size (2400 x 2400 recommended for best results) ● 1:1 aspect ratio Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Important CMYK (print standard) images will not be accepted. Television Content Profiles TV Cover Art Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 18TV Content Considerations ● No bugs or logos should be visible during the body of the video. ● No tune-ins should be visible during the body of the video. Tune-ins are only acceptable at the end of the video. ● No ratings or advisories should be displayed at any time during the video. ● Network cards at the beginning and end of the video are accepted as long as they are visible less than five (5) seconds. ● Commercials or other promotional material, including URLs, are NOT accepted. For more details, please contact your iTunes Technical Representative. ● Commercial black may be a maximum of 5 seconds. ● Previews must contain content suitable for a general audience. ● Previews must not have opening or ending credits and should not start on a black frame. ● A minimum of 1 black frame at the beginning and end of each video is required. Television Content Profiles TV Content Considerations 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 19Film HD Source Profile ● Apple ProRes 422 (HQ) ● ITU-R BT.709 color space, file tagged correctly as 709 ● VBR expected at ~220 Mbps ● 1920 x 1080 square pixel aspect ratio material ● Native frame rate of original source: ● 29.97 interlaced frames per second for video sourced ● 24 or 25 progressive frames per second for film sourced ● 23.976 progressive frames for inverse telecine sourced from film ● Telecine materials will not be accepted ● Content may be delivered matted: letterbox, pillarbox, or windowbox. Important All videos must begin and end with at least one black frame. Film SD Source Profile NTSC ● Apple ProRes 422 (HQ) ● VBR expected at 40-60 Mbps ● 720 x 480 or 720 x 486 encoded pixels; for display at either 853 x 480 for 16:9 content or 640 x 480 for 4:3 content ● All encoded content must include pixel aspect ratio (pasp) that defines content as either 4:3 or 16:9. ● Native frame rate of original source: ● 29.97 frames per second video source can be delivered interlaced ● 24 frames per second must be delivered progressive 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 20 Film Content Profiles● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Telecine materials will not be accepted ● Content may be delivered matted: letterbox, pillarbox, or windowbox. PAL ● Apple ProRes 422 (HQ) ● VBR expected at 40-60 Mbps ● 720 x 576 encoded pixels; for display at either 1024 x 576 for 16:9 content or 768 x 576 for 4:3 content ● All encoded content must include pixel aspect ratio (pasp) that defines content as either 4:3 or 16:9. ● Native frame rate of original source: ● 24 and 25 frames per second sourced from film must be delivered progressive ● 23.976 frames per second for inverse telecine must be delivered progressive; must not be delivered interlaced or delivery will fail ● Telecine materials will not be accepted ● Content may be delivered matted: letterbox, pillarbox, or windowbox. 25 fps interlaced PAL films are NOT supported. Important All videos must begin and end with at least one black frame. Film Audio Source Profile For every film that 5.1 Surround audio is available in any competing format or market, it must be provided to iTunes in addition to the stereo tracks. Surround ● LPCM in either Big Endian or Little Endian, 16-bit or 24-bit, at least 48kHz ● Expected channels: L, R, C, LFE, Ls, Rs Stereo ● LPCM in either Big Endian or Little Endian, 16-bit or 24-bit, at least 48kHz ● Expected Dolby Pro Logic channels: Lt, Rt or expected stereo channels: L, R Film Content Profiles Film Audio Source Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 21Film Audio/Video and Alt-Audio Container ● Deliver all content in a QuickTime .mov file container. ● The QuickTime .mov file extension is expected for all audio and video content. ● Each audio channel must have an assignment. The channel assignments must match one of the options below: Option 1 5.1 Surround Tracks Stereo Tracks L R C Lfe Ls Rs Lt Rt Track 1 -- six channels Track 2 L R C Lfe Ls Rs Lt Rt Track 3 One track containing all Surround channels; Matrix Stereo with Lt in one track and Rt channel in another track L R C Lfe Ls Rs Lt Rt Option 2 Track 1 Track 2 Track 3 Track 4 Track 5 Track 6 Track 7 Track 8 One track for each channel Option 3 Track 1 -- six channels Track 2 -- two channels L R C Lfe Ls Rs Lt Rt One track containing all Surround channels; Matrix Stereo with Lt and Rt channels in one track L R C Lfe Ls Rs Option 4 Track 1 Track 2 Track 3 Track 4 Track 5 Track 6 One track for each Surround channel; Matrix Stereo with Lt and Rt channels in one track Track 7 -- two channels Lt Rt Option 5 No Surround. Stereo with L in one track and R in another track L R Track 1 Track 2 Option 6 No Surround. Stereo with both L and R channels in one track Track 1 -- two channels L R Important Refer to “Table 1: Audio Channel Assignment Labels” (page 36) for label descriptions and “How to Apply Audio Channel Assignments” (page 30) for instructions on applying audio channel assignments. Note For more information on alternate audio, see the “Assets and Data Files” section in the iTunes Package Film Specification . Film Content Profiles Film Audio/Video and Alt-Audio Container 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 22Film Closed Captioning Profile ● English text in EIA 608 format. ● Delivered in the same package with the video it references. ● In a Scenarist SCC formatted file, using .scc file extension. ● SCC files must be 29.97 regardless of frame rate of the movie file. Note: Captioning workflows utilizing 23.976 FPS timecodes can be accepted but the timecodes will be regarded as 29.97 FPS. ● SCC files should preserve the timecode mode (drop or non-drop) used in your captioning process, not necessarily the mode represented in the QuickTime movie source. ● SCC files must be validated for proper sync against the associated video file using QuickTime 7 Pro. ● Captionsshould display and synchronize to within one second of the initial, audible dialog to be represented in text. The timecodes of the captions are relative to the start of the program, and not the QuickTime movie'stimecode track. Currently, the iTunes Store does not support EIA 708 (ATSC closed captioning) or Teletext. MacCaption is a tool you can use to create .scc files: http://www.cpcweb.com/products/. (Note that this product is not endorsed by Apple. Apple cannot and does not provide support for third-party products.) Note The closed caption file must be provided unless it does not exist. Film iTunes Timed Text Profile Below is a summary of delivery requirements for iTunes Timed Text. Refer to Chapter 5 in the iTunes Package Film Specification for complete details. ● Delivered in an iTunes Timed Text (iTT) formatted file, using .itt file extension. ● Delivered in the same package with the video it references as an asset in the block. ● Only one div element is allowed in an iTT document. ● timeBase must be set to smpte. ● dropMode must be set to "dropNTSC" or "nonDrop"; iTunes Timed Text does not support dropPAL. ● Only sansSerif may be specified as the typeface in fontFamily. Film Content Profiles Film Closed Captioning Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 23The iTT file format is a subset of the Timed Text Markup Language, Version 1.0 W3C Candidate Recommendation 23 February 2010 (TTML) (http://www.w3.org/TR/2010/CR-ttaf1-dfxp-20100223/) from the World Wide Web Consortium (W3C) (http://w3.org/). All iTT documents are TTML documents that use the restricted subset of TTML. Film Dub Card Video Profile The full feature-length video asset is comprised of a set of data files, which play specific roles for their asset. The following table describes the optional data file for dub card video. Asset Data File Description Type A video-only sequence containing one or more still credits specific to the locale-matched audio. iTunes products will include dub credit video sequencesfor the associated audio dubs following the main program. Locale: Required Role: video.end.dub_credits An optional data file containing the credits associated with an audio track. Full Dub Card Video Profile ● Apple ProRes 422 (HQ) ● Movie correctly tagged with color parameter: ITU BT.709 ● Video dimensions, pixel aspect ratio, and frame rate must match full program video ● Minimum of 4 seconds per dub card ● Crop dimensions from full program video will be applied to all dub card video — effective crop must match full program video ● Crop attributes must not be supplied for dub card video ● Sound tracks should not be supplied for dub card video — sound tracks will be ignored ● Dub card video will be deinterlaced if necessary so the field order does not need to match — progressive is preferred ● Dissolves and scrolling credits are not supported ● First and last frames do not need to be black frames Film Content Profiles Film Dub Card Video Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 24Film Chapter Image Profile ● JPEG with .jpg extension (quality unconstrained) ● RGB (screen standard) ● Must be same aspect ratio as video source ● 640 minimum horizontal dimension (larger for HD sourced) ● Variable size vertical dimension (based on aspect ratio of video source) ● Only active pixel area may be included ● Chapter images must be cropped (no letterbox, pillarbox, or windowbox) ● Chapter images must contain picture content ● Chapter image files must be unique with different checksums Important CMYK (print standard) images will not be accepted. Film Poster Art Profile ● JPEG with .jpg extension (quality unconstrained) or PNG with .png extension ● RGB (screen standard) ● 1400 x 2100 pixels minimum size ● 2:3 aspect ratio ● Poster art (one-sheet) from film. Must contain key art and title. DVD cover, release date, website, or promotional tagging may not be included. ● Poster art must not display film ratings. Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Important CMYK (print standard) images will not be accepted. Film Content Profiles Film Chapter Image Profile 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 25Film Content Considerations ● The full movie asset should not contain FBI, MPAA, or release date tagging. ● The trailer asset should not contain FBI, MPAA, or release date tagging. ● A minimum of 1 black frame at the beginning and end of each video is required. ● Trailer should be same aspect ratio as the full asset. ● Promotional bumpers, including URLs, are NOT accepted. For more details, please contact your iTunes Technical Representative. ● Trailers must contain content suitable for a general audience. ● Poster art should not contain DVD tagging, release date tagging, or website tagging. Film Content Profiles Film Content Considerations 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 26● All XML must be encoded in UTF-8. ● No byte order markers (BOM) can be used. ● There should be no null data or empty tags in the XML. If not used, elements should be removed. ● The XML must be formatted to use line breaks and indentations. For further information, please refer to the appropriate media type metadata specification, or consult with your iTunes Technical Representative. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 27 XMLPrevious Spec Revisions The following table lists the previously-released specifications and the revisions: Date/Version Summary Added crop dimensions for TV. Clarified content considerations for TV. Clarified closed captioning for TV. Added delivery requirements for iTT files. September 22, 2011 - Version 4.8 Clarified delivery requirements for 5.1 audio and closed captioning. Added the profile for closed captioning for TV. Film poster art requirements have changed. July 13, 2011 - Version 4.7 Revision 2 Clarified HD cropping for TV. Added color space requirement for HD film source. Clarified closed captioning text for film. April 15, 2011 - Version 4.7 Removed assetspecificationsfor books(a new iBookstore asset guide has been created). Renamed this asset guide to: iTunes Video and Audio Asset Guide . February 9, 2011 - Version 4.6 Clarified surround sound for HD music video audio source profile. Clarified delivery of HD source for music videos. Added a chapter for book source profiles. Put back 25 fps in the HD TV source profile that was incorrectly removed. Added two new best practice items to the TV Content Considerations section. November 5, 2010 - Version 4.5 Added source profile for HD music video and cropping information. Clarified album cover art. Added surround sound to HD music video audio source profile. August 5, 2010 - Version 4.4 Clarified that ALAC in a CAF container is allowed. Added source profile for pre-cut ringtones. Clarified that film ratings should not appear on poster art. February 3, 2010 - Version 4.3 December 18, 2009 - Version Clarified quality standards. Clarified closed captioning. 4.2 November 10, 2009 - Version Clarified audio requirements for music and film. 4.1 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 28 Revision HistoryDate/Version Summary Added best practices content for Film. Clarified requirements for SCC files. September 11, 2009 - Version 4.0 Clarified image and audio requirements. Clarified frame rate requirements for TV. July 1, 2009 - Version 3.3.2 Added support for PNG format images for cover art, poster art, and video screen captures. PNG images are not currently supported for chapter thumbnail images. May 12, 2009 - Version 3.3.1 Added updated PAL support for film. Added closed-captioning to Film Content Profile. Added 24-bit support for audio. Added best practices content for TV. Clarified how to send stereo sound for Film and TV. March 17, 2009 - Version 3.3 Added audio source specification to Music Audio Content Profile, added HD format to Television Content Profile and Appendix I, which provides audio channel assignments instructions. October 1, 2008 - Version 3.2 Complete reformatting of the Guide. Separation of content type profiles. Addition of Movie HD and SD specification. Addition of image specifications for TV and Film. May 8, 2008 - Version 3.1.1 April 2, 2007 - Version 2.3 Introduction of Asset Specification Guide. Revision History Previous Spec Revisions 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 29How to Apply Audio Channel Assignments Step 1: Open the Movie Properties window from the Window > Show Movie Properties menu. Important You must use the Pro version of QuickTime. 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 30 Audio Channel AssignmentsStandard Movie Properties window: Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 31Step 2: Go to the View > Columns menu and choose Channels. You may add additional columns like ID, Data Rate, and so on. Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 32Notice the Channels column in the following screenshot indicates the audio tracks are Mono. Step 3: Select the sound track to make the audio channel assignment and click the Audio Settings tab. Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 33Step 4: To make the Channel Assignment, choose the appropriate setting from the pop-up menu. Repeat this process for each audio track. In this example all the tracks have been properly assigned for the channel assignments of Option 2 asindicated in the Audio/Video Containersection for“Television Content Profiles” (page 13) and “Film Content Profiles” (page 20). Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 34Notice the Channels column in the following screenshot no longer indicates the audio tracks are Mono. Noticethisindicatestheassignment. Thisshouldnotindicatemono. Step 5: Save the file. Step 6: Open the Movie Inspector from the Window > Show Movie Inspector menu to verify assignments were applied correctly. Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 35Table 1: Audio Channel Assignment Labels Label Description L Left R Right C Center LFE LFE Screen Ls Left Surround Rs Right Surround Lt* Left Total Rt* Right Total * Lt and Rt are supported in the latest version of QuickTime. Audio Channel Assignments How to Apply Audio Channel Assignments 2012-05-22 | © 2012 Apple Inc. All Rights Reserved. 36Apple 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. The Apple logo is a trademark of Apple Inc. 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 .Mac is a registered service mark of Apple Inc. iBookstore is a service mark of Apple Inc. iTunes Store is a registered service mark of Apple Inc. Apple, the Apple logo, iBook, iBooks, iTunes, Logic, Mac, and QuickTime are trademarks of Apple Inc., registered in the United States and other countries. DEC is a trademark of Digital Equipment Corporation. Dolby and Pro Logic are trademarks of Dolby Laboratories. 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. Apple Remote Desktop Administrator’s Guide Version 3K Apple Computer, Inc. © 2006 Apple Computer, Inc. All rights reserved. The owner or authorized user of a valid copy of Apple Remote Desktop 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 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. Apple, the Apple logo, AirPort, AppleScript, AppleTalk, AppleWorks, FireWire, iBook, iMac, iSight, Keychain, Mac, Macintosh, Mac OS, PowerBook, QuickTime, and Xserve are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Apple Remote Desktop, Bonjour, eMac, Finder, iCal, and Safari are trademarks of Apple Computer, Inc. Adobe and Acrobat are trademarks of Adobe Systems Incorporated. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. 019-0629/02-28-06 3 3 Contents Preface 9 About This Book 10 Using This Guide 10 Remote Desktop Help 10 Notation Conventions 11 Where to Find More Information About Apple Remote Desktop Chapter 1 13 Using Apple Remote Desktop 13 Administering Computers 15 Deploying Software 18 Taking Inventory 21 Housekeeping 22 Supporting Users 23 Providing Help Desk Support 25 Interacting with Students 26 Finding More Information Chapter 2 28 Getting to Know Remote Desktop 28 Remote Desktop Human Interface Guide 29 Remote Desktop Main Window 31 Task Dialogs 32 Control and Observe Window 33 Multiple-Client Observe Window 34 Report Window 35 Changing Report Layout 36 Configuring Remote Desktop 36 Customizing the Remote Desktop Toolbar 36 Setting Preferences for the Remote Desktop Administrator Application 37 Interface Tips and Shortcuts Chapter 3 39 Installing Apple Remote Desktop 39 System Requirements for Apple Remote Desktop 40 Network Requirements 40 Installing the Remote Desktop Administrator Software 41 Setting Up an Apple Remote Desktop Client Computer for the First Time4 Contents 41 Upgrading the Remote Desktop Administrator Software 42 Upgrading the Client Software 42 Method #1—Remote Upgrade Installation 43 Method #2—Manual Installation 43 Upgrading Apple Remote Desktop Clients Using SSH 44 Creating a Custom Client Installer 46 Considerations for Managed Clients 46 Removing or Disabling Apple Remote Desktop 46 Uninstalling the Administrator Software 47 Disabling the Client Software 48 Uninstalling the Client Software from Client Computers Chapter 4 49 Organizing Client Computers Into Computer Lists 49 Finding and Adding Clients to Apple Remote Desktop Computer Lists 50 Finding Clients by Searching the Local Network 50 Finding Clients by Searching a Network Range 51 Finding Clients by Network Address 52 Finding Clients by File Import 52 Making a New Scanner 53 Making and Managing Lists 53 About Apple Remote Desktop Computer Lists 54 Creating an Apple Remote Desktop Computer List 54 Deleting Apple Remote Desktop Lists 54 Creating a Smart Computer List 55 Editing a Smart Computer List 55 Creating a List of Computers of from Existing Computer Lists 56 Importing and Exporting Computer Lists 56 Transferring Computer Lists from Apple Remote Desktop 3 to a New Administrator Computer 57 Transferring Remote Desktop 2 Computer Lists to a New Remote Desktop 3 Administrator Computer 57 Transferring Old v1.2 Computer Lists to a New Administrator Computer Chapter 5 59 Understanding and Controlling Access Privileges 59 Apple Remote Desktop Administrator Access 61 Setting Apple Remote Desktop Administrator Access Authorization and Privileges Using Local Accounts 62 Apple Remote Desktop Administrator Access Using Directory Services 62 Creating Administrator Access Groups 65 Enabling Directory Services Group Authorization 65 Apple Remote Desktop Guest Access 66 Apple Remote Desktop Nonadministrator Access 67 Virtual Network Computing AccessContents 5 68 Command-Line SSH Access 68 Managing Client Administration Settings and Privileges 69 Getting an Administration Settings Report 69 Changing Client Administrator Privileges Chapter 6 71 Setting Up the Network and Maintaining Security 71 Setting Up the Network 72 Using Apple Remote Desktop with Computers in an AirPort Wireless Network 73 Getting the Best Performance 73 Maintaining Security 75 Remote Desktop Authentication and Data Transport Encryption 75 Encrypting Observe and Control Network Data 76 Encrypting Network Data During Copy Items and Install Packages Tasks Chapter 7 77 Interacting with Users 78 Controlling 78 Controlling Apple Remote Desktop Clients 79 Control Window Options 80 Switching the Control Window Between Full Size And Fit-To-Window 80 Switching Between Control and Observe Modes 80 Sharing Control with a User 81 Hiding a User’s Screen While Controlling 81 Capturing the Control Window to a File 81 Switching Control Session Between Full Screen and In a Window 82 Sharing Clipboards for Copy and Paste 82 Controlling VNC Servers 83 Setting up a Non–Mac OS X VNC Server 84 VNC Control Options 85 Configuring an Apple Remote Desktop Client to be Controlled by a VNC Viewer 85 Observing 87 Changing Observe Settings While Observing 88 Changing Screen Titles While Observing 88 Viewing a User’s Account Picture While Observing 88 Viewing a Computer’s System Status While at the Observe Window 90 Shortcuts in the Multiple Screen Observe Window 90 Observing a Single Computer 91 Observing Multiple Computers 91 Observing a Computer in Dashboard 92 Sending Messages 92 Sending One-Way Messages 92 Interactive Chat 93 Viewing Attention Requests 93 Sharing Screens6 Contents 93 Sharing a Screen with Client Computers 94 Monitoring a Screen Sharing Tasks 94 Interacting with Your Apple Remote Desktop Administrator 94 Requesting Administrator Attention 95 Canceling an Attention Request 95 Changing Your Observed Client Icon Chapter 8 96 Administering Client Computers 96 Keeping Track of Task Progress and History 97 Enabling a Task Notification Script 98 Getting Active Task Status 98 Using the Task Feedback Display 98 Stopping a Currently Running Task 99 Getting Completed Task History 99 Saving a Task for Later Use 100 Creating and Using Task Templates 101 Editing a Saved Task 101 Installing Software Using Apple Remote Desktop 101 Installing by Package and Metapackage 103 Installing Software on Offline Computers 104 Installing by Using the Copy Items Command 104 Using Installers from Other Companies 105 Upgrading Software 106 Copying Files 107 Copy Options 108 Copying from Administrator to Clients 109 Copying Using Drag and Drop 110 Restoring Items from a Master Copy 111 Creating Reports 111 Collecting Report Data 112 Using a Task Server for Report Data Collection 113 Report Database Recommendations and Bandwidth Usage 114 Auditing Client Usage Information 116 Finding Files, Folders, and Applications 118 Comparing Software 119 Auditing Hardware 124 Testing Network Responsiveness 125 Exporting Report Information 126 Using Report Windows to Work with Computers 127 Maintaining Systems 127 Deleting Items 128 Emptying the Trash 128 Setting the Startup DiskContents 7 129 Renaming Computers 129 Synchronizing Computer Time 130 Setting Computer Audio Volume 131 Repairing File Permissions 131 Adding Items to the Dock 132 Changing Energy Saver Preferences 133 Changing Sharing Preferences for Remote Login 133 Setting Printer Preferences 135 Managing Computers 135 Opening Files and Folders 136 Opening Applications 137 Quitting Applications Without Logging Out the User 137 Putting a Computer to Sleep 138 Waking Up a Computer 138 Locking a Computer Screen 139 Displaying a Custom Picture on a Locked Screen 139 Unlocking a Computer Screen 140 Disabling a Computer Screen 140 Logging In a User at the Login Window 141 Logging Out the Current User 141 Restarting a Computer 142 Shutting Down a Computer 143 UNIX Shell Commands 143 Send UNIX Command Templates 145 Executing a Single UNIX Command 145 Executing Scripts Using Send UNIX Command 147 Built-in Command-Line Tools 152 Automating Functions 152 Setting the Client’s Data Reporting Policy 153 Creating a Template Data Reporting Policy 154 Designating the Task Server and Setting the Report Data Collection Location 155 Scheduled Tasks 156 Using AppleScript with Remote Desktop 159 Using Automator with Remote Desktop Appendix A 161 Icon and Port Reference 161 Client Status Icons 161 Apple Remote Desktop Status Icons 162 List Menu Icons 162 Task Status Icons 163 System Status Icons (Basic) 163 System Status Icons (Detailed) 164 TCP and UDP Port Reference8 Contents Appendix B 165 Report Field Definitions Reference 165 System Overview Report 167 Storage Report 169 USB Devices Report 169 FireWire Devices Report 169 Memory Report 169 PCI Cards Report 170 Network Interfaces Report 172 Network Test Report 172 Administration Settings Report 173 Application Usage Report 173 User History Report Appendix C 174 AppleScript Remote Desktop Suite 174 Classes and Commands for the Remote Desktop Application. Appendix D 180 PostgreSQL Schema Sample Index 182 9 Preface About This Book What Is Apple Remote Desktop? Apple Remote Desktop is easy-to-use, powerful, open standards-based, desktop management software for all your networked Macs. IT professionals can remotely control and configure systems, install software, offer interactive online help to end users, and assemble detailed software and hardware reports for an entire Mac network. You can use Apple Remote Desktop to:  Manage client computers and maintain, update, and distribute software  Collect more than 200 system-information attributes for any Mac on your network  Store the results in an SQL database and view the information using any of several hardware or software reports  Control and manage multiple computer systems simultaneously, making shutdown, restart, and sending UNIX commands fast and easy  Provide help and remote assistance to users when they encounter problems  Interact with users by sending text messages, observing and controlling users’ screens, and sharing their screens with other client users You can use Apple Remote Desktop to manage your client systems. IT administrators use Remote Desktop in education and business to simplify and empower the management of their organizations computer assets. For system administrators, Apple Remote Desktop can be used to administer large numbers of servers, like a virtual Keyboard-Video-Mouse (KVM) sharing unit. In computer administration environments, it’s the ideal solution for managing remote systems, reducing administration costs, and increasing productivity. Apple Remote Desktop can also be used by educators to facilitate instruction in computer labs or one-on-one learning initiatives. Used in a classroom, Apple Remote Desktop enhances the learning experience and allows teachers to monitor and control students’ computers.10 Preface About This Book Using This Guide The Apple Remote Desktop Administrator’s Guide contains chapters to help you use Remote Desktop. It contains overviews and explanations about Apple Remote Desktop’s features and commands. It also explains how to install and configure Apple Remote Desktop on clients, how to administer client computers, and how to use Remote Desktop to interact with computer users. This guide is provided on the Apple Remote Desktop installation disc and on the Apple Remote Desktop support website as a fully searchable, bookmarked PDF file. You can use Apple’s Preview application or Adobe (Acrobat) Reader to browse the contents of this guide as well as search for specific terms, features, or tasks. Remote Desktop Help Remote Desktop Help is available using Help Viewer. To open Remote Desktop Help, choose Help > Remote Desktop Help. The help files contain the same information found in this guide, and are useful when trying to accomplish a task when this guide is unavailable. Additionally, the Remote Desktop Help contains new information, corrections, and latebreaking information about Apple Remote Desktop. The most up-to-date information is available through Remote Desktop Help before it’s available on the web as an updated PDF file. Notation Conventions This guide and Remote Desktop Help contain step-by-step procedures to help you use Remote Desktop’s commands effectively. In many tasks shown in this manual and in Remote Desktop Help, you need to choose menu commands, which look like this: Choose Edit > Clear. The first term after Choose is the name of a menu in the Remote Desktop menu bar. The next term (or terms) are the items you choose from that menu.Preface About This Book 11 Terminal Command Conventions Commands or command parameters that you might type, along with other text that normally appears in a Terminal window, are shown in this font. For example: You can use the doit command to get things done. When a command is shown on a line by itself as you might type it in a Terminal window, it follows a dollar sign that represents the shell prompt. For example: $ doit To use this command, type “doit” without the dollar sign at the command prompt in a Terminal window, then press the Return key. Where to Find More Information About Apple Remote Desktop For additional information related to Apple Remote Desktop, try these resources. You’ll find more information in the Apple Remote Desktop Read Me file and on the Apple Remote Desktop website: www.apple.com/remotedesktop/ You can find the most recent edition of the Apple Remote Desktop Administrator’s Guide at:  the Apple Server Division Documentation page www.apple.com/server/documentation/  the Remote Desktop section of Apple.com, and www.apple.com/remotedesktop/  the Help Menu in the Remote Desktop application Notation Indicates monospaced font A command or other Terminal text $ A shell prompt [text_in_brackets] An optional parameter (one|other) Alternative parameters (type one or the other) underlined A parameter you must replace with a value [...] A parameter that may be repeated A displayed value that depends on your configuration or settings12 Preface About This Book The Apple Remote Desktop Support website provides a database of technical articles about product issues, use, and implementation: www.apple.com/support/remotedesktop/ To provide feedback about Apple Remote Desktop, visit the feedback page: www.apple.com/feedback/remotedesktop.html For details about how to join the Apple Remote Desktop Mailing list, visit: lists.apple.com/mailman/listinfo/remote-desktop/ To share information and learn from others in online discussions, visit the Apple Remote Desktop Discussions Forum: discussions.info.apple.com/appleremotedesktop/ For more information about PostgreSQL go to: www.postgresql.org For more information about using Apple products for IT professionals go to: apple.com/itpro/1 13 1 Using Apple Remote Desktop Apple Remote Desktop helps you keep Macintosh computers and the software running on them up to date and trouble free. And it lets you interact directly with Macintosh users to provide instructional and troubleshooting support. This chapter describes the main aspects of Apple Remote Desktop’s administration and user interaction capabilities and tells you where to find complete instructions for using them. Administering Computers Apple Remote Desktop lets you perform a wide range of client hardware and software administrative activities remotely, from an administrator computer (a computer on which administrator software resides):  Keep users’ software up to date by using Apple Remote Desktop to deploy software and related files to client computers.  Create reports that inventory the characteristics of client computer software and hardware.  Use Apple Remote Desktop’s remote administration capabilities to perform housekeeping tasks for client computers.14 Chapter 1 Using Apple Remote Desktop You can administer client computers individually, but most Apple Remote Desktop features can be used to manage multiple computers at the same time. For example, you may want to install or update the same applications on all the computers in a particular department. Or you may want to share your computer screen to demonstrate a task to a group of users, such as students in a training room. To manage multiple computers with a single action, you define Apple Remote Desktop computer lists. A computer list is a group of computers that you want to administer similarly. Computer lists let you group and organize computers for administration. Setting up computer lists is easy; you simply scan the network or import the identity of computers from files. A particular computer can belong to more than one list, giving you a lot of flexibility for multicomputer management. A computer can be categorized by its type (laptop, desktop), its physical location (building 3, 4th floor), its use (marketing, engineering, computing), and so forth. Once you’ve set up computer lists, you can perform most of the computer administration activities described next for groups of client computers. Marketing department Engineering departmentChapter 1 Using Apple Remote Desktop 15 Deploying Software Apple Remote Desktop lets you distribute software and related files to client computers from your Apple Remote Desktop administrator computer or from a computer running Mac OS X Server. Distributing Installer Packages You can distribute and automatically install packages in .pkg and .mpkg formats. Apple Remote Desktop lets you install software and software updates on one or more client computers without user interaction or interruption, or even if no user is logged in. After installation, Apple Remote Desktop erases the installer files. If the computers need to be restarted, as they do following an operating system update, you can restart them from Apple Remote Desktop. Xserve cluster node Marketing department Engineering department Deploy configuration files Deploy drag-and-drop application folders Deploy install packages (.pkg or .mpkg) Network install images NetBoot images Deploy UNIX shell scripts Set startup partition Administrator computer Mac OS X Server16 Chapter 1 Using Apple Remote Desktop For example, you can use Apple Software Update to download an iCal update or an operating system update to a test computer. If the update works as expected and introduces no compatibility issues, copy the installer package to the administrator computer to distribute to computers that need upgrading. Note that this approach conserves Internet bandwidth, because only one copy of the package needs to be downloaded. You can also use Apple Remote Desktop to deploy new versions of computational software to Xserve computers in a cluster node. You can use the PackageMaker tool (included on the Apple Remote Desktop installation CD and with Apple’s developer tools) to create your own installer packages, such as when you want to:  Distribute school project materials or business forms and templates  Automate the installation of multiple installer packages  Deploy custom applications Before performing remote installations, you can send an Apple Remote Desktop text message to notify users, perhaps letting them know that you’ll be using Apple Remote Desktop to lock their screens at a particular time before you start the installation. Using Network Install Images You can also distribute and install software, including the Mac OS X operating system, by using Network Install images. On Mac OS X Server, use the Network Image Utility to create a Network Install image. You can create the image by cloning a system that’s already installed and set up, or by using an installation disc or an image downloaded using Apple Software Update. If you choose to auto-install, you won’t have to interact with each computer. On the Apple Remote Desktop administrator computer, set the startup disk of remote client systems to point to the Network Install image, and then remotely reboot the clients to initiate installation. Before initiating installations that require computers to be restarted afterwards, send an Apple Remote Desktop text message to client users to notify them of a pending installation. For example, tell users you’ll log them off at 5:00 p.m. to install an operating system update. Using NetBoot Images Another kind of system image you can create using Mac OS X Server is a NetBoot image. Like a Network Install image, a client computer uses NetBoot images to start up. Unlike a Network Install image, the boot software is not installed on the client system. Instead, it resides on a remote server. It is recommended you use a NetBoot image that has Apple Remote Desktop installed and configured. Otherwise, administering the computer using Apple Remote Desktop after starting up from NetBoot is impossible.Chapter 1 Using Apple Remote Desktop 17 Client computers that boot from a NetBoot image get a fresh system environment every time they start up. For this reason, using NetBoot images is useful when a particular computer is shared by several users who require different work environments or refreshed work environments, or when you want to start a new experiment or use a different computing environment in a cluster node. You can use Apple Remote Desktop to set the startup disks of client systems to point to the NetBoot image, and then restart the systems remotely using Apple Remote Desktop. Users can also choose a NetBoot image for startup by using the Startup Disk pane of System Preferences. With just a few clicks you can reconfigure all the computers in a lab or cluster without having to manually restart and configure each computer individually. Distributing Preference Files Managed computers often require a standard set of preferences for each instance of an application. Use Apple Remote Desktop to distribute preference files when you need to replace or update a application preferences. For example, you can copy a standardized preference file to the currently logged in user’s Library/Preferences folder. Using UNIX Shell Scripts You can use Apple Remote Desktop to distribute and run UNIX shell scripts on client computers. For example, a script can mount an AFP server volume, from which it downloads a disk image to client computers. The script might also download an installer package and then perform a command-line installation. On an Xserve in a cluster node, you could also run a script that mounts an Xserve RAID disk designed for high throughput and then downloads large data sets for processing. You can also use Apple Remote Desktop to distribute AppleScript files that automate PDF workflows, or job instructions for computational clusters. Distributing Drag-and-Drop Applications You can distribute and install self-contained (drag-and-drop) applications by copying them to one or more client computers. Use this approach, for example, to distribute application updates. Verifying Installations To check whether an installation has been completed successfully, use Apple Remote Desktop’s remote control capabilities. For example, you can start an application remotely, or search for particular files. You can also use the File Search report to verify that all files for an application are installed correctly.18 Chapter 1 Using Apple Remote Desktop Taking Inventory Apple Remote Desktop lets you capture data describing the attributes of client computers, then generate reports based on the data. You specify how often you want to capture data, the data you want to capture, and the computers you want to profile. You can collect data just before generating a report if you need up-to-the-minute information. Or you can schedule data to be collected by Apple Remote Desktop at regular intervals and stored in its built-in SQL (Structured Query Language) database for use on an as-needed basis. You can also specify where you want the database to reside—on the local administrator computer, or on a server where the Apple Remote Desktop administrator software is installed and always running, so data can be captured on an ongoing basis. Using the collected data, Apple Remote Desktop generates reports tailored to your specifications. Xserve cluster node Marketing department Engineering department Administrator computer Mac OS X Server ARD SQL database ARD SQL database SQL toolsChapter 1 Using Apple Remote Desktop 19 File Search Report Use the File Search report to search client systems for specific files and folders and to audit installed applications. This report can help you find out how many copies of a particular application are in use so you don’t violate license agreements. Spotlight File Search Use the Spotlight Search report to search Tiger client systems for specific files and folders. The information in the report is updated as files matching your search change on the client systems. Software Version Report Use the Software Version report to make sure that all users have the latest application versions appropriate for their systems. Software Difference Report Use the Software Difference report to detect application versions that are out of date, nonstandard, or unacceptable for some other reason. Or, you can learn whether a user has installed an application that shouldn’t be installed. System Overview Report The System Overview report makes visible a wide variety of client computer characteristics. Using this report, you can review information about a client’s AirPort setup, computer and display characteristics, devices, network settings, system preferences, printer lists, and key software attributes. There are numerous uses for this report, such as identifying problems or verifying system configurations before installing new software, or determining how many devices of a particular type (such as scanners) are in a particular lab. Hardware Reports Several reports provide details about particular hardware used by client computers— storage, FireWire devices, USB devices, network interfaces, memory, and PCI cards. Use these reports to determine, for example, which computers need more memory, which computer has the fastest processor speed, and how much free space is left on a particular disk. Administration Settings Report Use the Administration Settings report to determine which Apple Remote Desktop administrator privileges are enabled or disabled for you in the Sharing pane of System Preferences on individual client computers. User History Report Use the User History report to show you who has logged in to a client, how they logged in, and for how long.20 Chapter 1 Using Apple Remote Desktop Application Usage Report Use the Application Usage report to find out which applications have been running on your client computers and who ran those applications. Network Test Report A Network Test report helps you measure and troubleshoot the communication between your administrator computer and your client computers. The Network Interfaces report might also help troubleshooting network hardware issues. Use this report to help identify reasons for network communication problems that could affect Apple Remote Desktop. For example, if you’re unable to copy items to particular client computers from the administrator computer, you may find you have a bad connection to the computers. Using this information can help you isolate the problem to a particular cable or hub. Generating Your Own Reports Because the Apple Remote Desktop database is in standard SQL format, you can also use your favorite SQL scripts to query, sort, and analyze the collected data. In addition, you can export data from the database into a file so you can import it for viewing in a different program, such as a spreadsheet application.Chapter 1 Using Apple Remote Desktop 21 Housekeeping Apple Remote Desktop provides several ways to remotely control client computers for housekeeping activities, which you can conduct using one or more Apple Remote Desktop windows. Managing Power State Use Apple Remote Desktop to control the power state of client computers. For example, you may need to have all computers turned off during maintenance of a power generation unit or during a holiday shutdown. You can send an Apple Remote Desktop text message reminding users to shut down their computers at a particular time. Any computers still running when you need to start maintenance can be detected and shut down remotely with Apple Remote Desktop. Xserve cluster node Marketing department Engineering department Administrator computer Execute UNIX shell script Restart/ shutdown/sleep Remote screen control Empty Trash Set startup partition Send text notification Mac OS X Server NetBoot images22 Chapter 1 Using Apple Remote Desktop Locking Computer Screens You can lock the screens of client computers for specified durations when you don’t want the computers to be used. For example, you may need to perform network maintenance and want to make sure computers don’t use the network for a few hours. You can display custom pictures or text messages on locked computer screens to let users know when the computers are available again. Reclaiming Disk Space Periodically empty the Trash on client computers to conserve disk space. Automating Periodic Maintenance Use AppleScript and UNIX shell scripts to automate periodic maintenance, such as checking permissions or deleting log files. Controlling Screens Use Apple Remote Desktop’s remote screen control to perform activities on the desktop of Xserve computers, or use graphical applications on them. Apple Remote Desktop replaces the need for KVM (keyboard-video-mouse) switches for accessing Xserve computers without a monitor attached. You can also remotely control a user’s computer to help determine reasons for slow performance or other problems. Changing Startup Disks Change the startup disk of a client computer to perform diagnostic or troubleshooting activities. For example, start up a computer using a server-based NetBoot image that’s been set up for troubleshooting. When you’re finished, reset the startup disk to the original boot volume. Managing Shared Computers On computers that are shared among users, check for files that need to be deleted, close applications, log users off, or perform other activities needed to prepare computers for the next users. Supporting Users Apple Remote Desktop lets you interact with users from your administrator computer in these ways:  Provide help: respond to users who need help by using Apple Remote Desktop to receive user requests and to remotely diagnose and fix problems.  Interact: conduct instructional interactions with students in a school or corporate training environment—from controlling or observing student screens to sharing your screen with all your students in order to perform a demonstration.Chapter 1 Using Apple Remote Desktop 23 Providing Help Desk Support When a user is having trouble, Apple Remote Desktop provides several ways to interact with the user and his or her computer to diagnose and fix the problem. Requesting Help A user can discreetly notify you of a problem by sending a request for help using an Apple Remote Desktop text message. Users initiate requests using the commands in the menu that appears when they click the Apple Remote Desktop icon in the menu bar. A notification on the administrator computer alerts you to the message, and you can use several techniques to obtain more information and troubleshoot the problem. Chatting with the User Conduct two-way Apple Remote Desktop text communication with the user to obtain more information. Screen Monitoring Use Apple Remote Desktop to observe the user’s screen if you need more details to understand the problem. Marketing department Engineering department Copy items Administrator computer Control, observe, and share screens Use text chat24 Chapter 1 Using Apple Remote Desktop Screen Controlling Use Apple Remote Desktop to control the user’s screen in order to diagnose and fix the problem. You may have unlimited control, or a user can grant you temporary guest access so you can control the computer only during troubleshooting. There are two levels of control available. You can take complete control of the user’s computer, or you can share control of the keyboard and mouse with the user. Screen Sharing If the problem is caused by incorrect actions by the user, share your screen with the user as you demonstrate the correct way to perform the action. Using Reports Use hardware and software reports as diagnostic tools to determine whether the client computer setup is part of the problem. For example, if a user can’t save his or her work, the storage report can help you determine whether it’s a disk space issue. Deploying New Software or Files If software or configuration settings are part of the problem, use Apple Remote Desktop to copy new configuration files, installer packages, or other items to client computers.Chapter 1 Using Apple Remote Desktop 25 Interacting with Students Apple Remote Desktop helps instructors teach more efficiently by letting them interact with student computers individually or as a group. Using Text Messages Send Apple Remote Desktop text messages to communicate with students. For example, notify them that a classroom activity will start soon or that they have ten minutes to finish an examination. Monitoring Student Computers View student computer screens on your computer, so you can monitor student activities or assess how well they’re able to perform a particular task. You can also monitor the applications running on any student’s computer. Sharing Screens Display your screen or a student’s screen on other student computers for training and demonstration purposes. Controlling Screens Show students how to perform tasks by controlling their screens from your computer, opening applications and using files as required. Classroom Administrator computer Observe and share one or multiple screens One-to-one help desk support Broadcast text messages Lock screens Distribute items electronically Open applications or files Control screen Log out students26 Chapter 1 Using Apple Remote Desktop Locking Screens Lock student screens to prevent students from using their computer when you want them to focus on other activities. Terminating Computer Use Remotely log students out or shut down their computers at the end of a class or school day. Distributing and Collecting Files Distribute handouts electronically, at a time that won’t disrupt class activities or when they’re needed for the next class activity, and collect homework files. Automating Website Access Open a webpage on all student computers. Drag a URL from Safari to your desktop, then copy it to student computers and open it in Safari. You can also copy files and open them in the appropriate applications on student computers. Providing One-to-One Assistance Provide help when a student needs it, conducting private and discreet computer-tocomputer interactions. Finding More Information You’ll find detailed instructions for performing the tasks highlighted in this chapter— and more—throughout this manual. To learn more about See information for Starting on page Remote Dekstop interface Window and icon functions page 28 Computer lists Creating computer lists page 49 Apple Remote Desktop administration Administrator privileges Administrator computers page 59 Controlling screens Controlling page 78 Observing screens Observing page 85 Deploying software Installing software Upgrading software page 101 Distributing files Copying files page 106 Taking inventory Data collection options Auditing software Auditing hardware Network responsiveness Customizing reports Exporting report data page 111 Client use reporting User login accounting Application usage page 114Chapter 1 Using Apple Remote Desktop 27 Additional information can be obtained at several Apple websites:  For information about NetBoot and Network Install, download the system imaging administration guide at: www.apple.com/server/documentation  You can find PackageMaker’s documentation at Apple’s Developer Connection: http://developer.apple.com/documentation/DeveloperTools/Conceptual/ SoftwareDistribution/index.html? Housekeeping tasks Deleting items Emptying the Trash Setting startup volumes Renaming computers Sleeping and waking Locking screens Logging users out Restart and shutdown page 127 Automating tasks Configuring data gathering Scheduling tasks Using UNIX shell scripts page 152 To learn more about See information for Starting on page2 28 2 Getting to Know Remote Desktop Remote Desktop is the administrator application for Apple Remote Desktop. Its attractive interface is powerful, yet simple to use. Remote Desktop’s interface is customizable, allowing you to get the information you want quickly, the way you want it. This chapter contains screenshots and short descriptions of Remote Desktop’s interface, as well as detailed instructions for customizing the appearance and preferences of the application. You will learn about:  “Remote Desktop Human Interface Guide” on page 28  “Configuring Remote Desktop” on page 36  “Interface Tips and Shortcuts” on page 37 Remote Desktop Human Interface Guide The following sections give basic information about the human interface of Remote Desktop, Apple Remote Desktop’s administrator application.  “Remote Desktop Main Window” on page 29  “Task Dialogs” on page 31  “Control and Observe Window” on page 32  “Multiple-Client Observe Window” on page 33  “Report Window” on page 34  “Changing Report Layout” on page 35Chapter 2 Getting to Know Remote Desktop 29 Remote Desktop Main Window The main window of Remote Desktop has a customizable toolbar, groups of lists, tasks, and scanners on the left, and the main window area to the right. “List Menu Icons” on page 162 contains icons seen in the list menu of the main window. A All Computers list: The All Computers list is a list of all client computers that you plan to administer. It includes all the clients you have authenticated to, as well as the client computers that you plan to authenticate to. Computers need to be in the All Computers list before you can command or administer them. If you have a 10-client license, the All Computers list can contain only 10 computers. B Apple Remote Desktop computer lists: A list of computers you create to group computers in ways that are convenient for you. Any list is a subset of the client computers in the All Computers list. If you add a computer directly to a computer list, it is added automatically to the All Computers list as well. C Smart computer lists: A smart computer list is a list of computers which is a subset of the client computers in the All Computers list that meet a predetermined criteria. Smart Computer lists update themselves based on your criteria compared to the contents of the All Computers list. D Group folders: Groups are tools to help you organize all your possible lists, tasks, and scanners. Groups look like folders, and can be collapsed to hide the group contents. E Saved tasks: Saved tasks are listed in the left portion of the main window. They have the icon of the type of task and have a user-changeable name. A B C D E F G I H K L J30 Chapter 2 Getting to Know Remote Desktop F Scanner: Scanners find clients to add to the All Computers list. You can make new scanners and customize them for your needs. See “Making a New Scanner” on page 52. G Task server list: This lists tasks delegated to the Task Server, rather than run those run directly from the application. When all the target computers have come online and participated in the task, the task is labeled as complete. H Active tasks list: This list shows all tasks that are currently running or scheduled and uncompleted. I Task history list: The task history list shows a list of most recently run tasks, as defined in the Remote Desktop preferences. You can inspect each task by double-clicking it. Once a task is completed (whether successfully or not) it is moved to the Task History list. J Task status icon: These icons represent the current state of a task. See “Task Status Icons” on page 162. K Client status icon: Icon representing the current state of a client computer. See “Client Status Icons” on page 161. L Customizable toolbar: The toolbar can be fully customized with icons of your most-used Apple Remote Desktop features.Chapter 2 Getting to Know Remote Desktop 31 Task Dialogs When you click a task, a dialog appears to let you set task parameters or confirm the task. A Task type header: This header area shows you the kind of task represented. B Saved task name: When you save a task, you name it for your own use. C Task configuration area: This area is different for every task. It’s where you set operating parameters for the task to be performed. D Participating computers: This area shows you the computers that will be affected by the task. You can add or remove computers in this area without changing computer list membership. E Schedule task button: When you click this button in a task dialog, you can set a time to perform the task as well as repeat the task. See “Scheduled Tasks” on page 155 for more information. F Save task button: When you click this button in a task dialog, you can name and save the task as configured. Saved tasks appear in the left side of Remote Desktop’s main window. G Task templates: This control allows you to save current task configuration settings, or apply previously saved settings to the current task. These templates are stored on a per-task basis. For example, the Send UNIX Commands template pop-up has an extensive list of built-in templates, while other tasks may have none. A B G C D E F32 Chapter 2 Getting to Know Remote Desktop Control and Observe Window This window is the same for both controlling and observing a single client. The only difference is the state of the Observe or Control toggle button. When it’s selected, you have control over the remote client. A Observe or control toggle: When this button is selected, you have control over the remote client. B Share mouse control: When this button is selected, you share mouse control with the user. C Fit screen in window: When this button is selected, the remote client is scaled to the Control window size. D Lock computer screen for control: When this button is selected, the remote client screen shows a lock, and your view allows you to view the client desktop normally. E Capture screen to file: When this button is clicked, the remote client screen is saved to a local file at the selected image quality. F Fit screen to full display: When this button is selected, your display doesn’t show your computer desktop, only that of the remote computer, at full possible resolution. G Get clipboard from client: When this button is clicked, the contents of the remote client Clipboard are transferred to the local Clipboard. A B C D E F G H J IChapter 2 Getting to Know Remote Desktop 33 Multiple-Client Observe Window When you observe many clients at the same time, they all appear in the same window. If you have more computers than will fit in the window, they are divided across several pages. H Send clipboard to the client: When clicked, the remote client Clipboard receives the contents of the local Clipboard. I Image Quality: Adjusts the screen color depth from black and white to millions of colors. J Desktop of Controlled Computer: Resize this window from the lower right corner. A Page Delay: Adjusts the number of seconds before automatically advancing to the next page of screens. B Computers Per Page: Adjusts the number of client screens visible on each page. C Image Quality: Adjusts the screen color depth from black and white to millions of colors. D Display Computer Information: Shows the computer information area, which contains desktop titles, account pictures, and status icons. E Computer title selector: Changes the titles displayed underneath the client screens (you can choose the computer name, IP address, or hostname). F Account picture: Shows the login icon of the currently logged in user. H A B C I G E I D F34 Chapter 2 Getting to Know Remote Desktop Report Window Reports serve as valuable shortcuts when you’re copying files and organizing computer lists. G Computer status: Shows basic computer status beneath each client screen. H Cycle through pages: Manually advances to the next page of screens. I View Options: Reveals the view option controls. J Observed computers: Contains the scaled desktops of the observed client computers. A Report category: Most reports have subcategories to help you find the information you want. In the report window, you switch between the subcategories using these tabs. B Save report to file: Saves the report to a plain text file. C Print: Formats and prints the report window. D Open selected: Opens the item selected in the report. The item opens on the client computer. C B A C B D E FChapter 2 Getting to Know Remote Desktop 35 Changing Report Layout You can customize report layouts for your own purposes. By default, reports include a column for each information type you selected before running the report, in the order presented in the report dialog. The columns in the report are initially sorted by computer name. You can resize or rearrange the columns of a report, as well as sort the rows by column. Additionally, in the File Search report, you can choose what information is displayed about a found item. By default, the item name, kind, parent path, actual size, and modification date are displayed. To change what information is displayed: 1 In the File Search report window, select or deselect each report column as desired. 2 After making your selections, click Generate Report as usual. When the report window appears, you can rearrange the columns or sort by a different column. E Delete selected: Deletes the item selected in the report from the remote computer. F Copy to this computer: Copies selected items to the administrator computer. Report column If checked, will show Name The item name Parent path The path to the folder that the item is in Full path The full file path Extension The file extension indicating the file type (.app, .zip, .jpg) Date modified The last date and time the file was changed and saved Date created The date and time the file was created Actual size Actual file size, in kilobytes or megabytes Size on disk Amount of disk space used by the file, in kilobytes Kind File, folder, or application Invisible A checkmark indicating whether it is visible in the Finder Version number If an application, the version reported Version string If an application, the version reported Owner The item owner’s short name Group The item’s group name Permissions The item’s UNIX permissions (for example, -rw-r--r--) Locked A checkmark indicating whether it is a locked file36 Chapter 2 Getting to Know Remote Desktop Configuring Remote Desktop You can configure the Remote Desktop administrator application to meet your work needs. Remote Desktop has an interface that is both flexible and functional. Customizing the Remote Desktop Toolbar The Remote Desktop application has a fully customizable toolbar, which provides a quick way to perform tasks. To perform a task, just click the appropriate icon in the toolbar. To show or hide the toolbar, click the toolbar button in the upper-right corner of the application window. You can add, remove, or rearrange the task icons in the toolbar to suit your needs. To customize the application toolbar: 1 Choose Window > Customize Toolbar. 2 Drag your favorite toolbar items or the default set of items to the toolbar. To remove an item, drag it from the toolbar. To rearrange items, drag them into the order you prefer. 3 Choose whether to display toolbar items as text, icons, or both. Selecting “Use Small Size” shrinks the items in the toolbar. Setting Preferences for the Remote Desktop Administrator Application In Remote Desktop preferences, you can select options that affect how the administrator application interacts with client computers. To open the Preferences window:  Choose Remote Desktop > Preferences. In the General pane, you can set:  What double-clicking a client computer does (Get Info, Control, Observe, Text Chat)  Whether to show the client idle time  What warnings may appear when quitting the application  A new serial number  A new Remote Desktop application password In the Control & Observe pane, you can set:  Whether a remote screen is shown in a window or a full screen  Whether control of the mouse and keyboard is shared with the client computer when the client is controlled  Whether a remote screen is shown at its actual size in a window or if it shrinks to fit the window In the Task Server pane, you can set:  Whether Remote desktop is using another computer as a Task Server, or whether this copy of Remote Desktop is being used as a Task ServerChapter 2 Getting to Know Remote Desktop 37  Whether other Apple Remote Desktop administrators can access your local Task Server  Whether clients collect user and application tracking data  A saved template for scheduling client reporting policies In the Labels pane, you can set:  Label colors and text for labeling computers In the Tasks pane, you can set:  Whether to automatically change focus to the active task  Whether to execute a notification script on task completion  Limits on task history list contents and time until removed In the Security pane, you can set:  Whether to accept messages from client users  Whether to allow control of the computer while Remote Desktop is active  The default encryption preference for control and observe sessions  The default encryption preference for Copy Items and Install Packages tasks  Which features of Remote Desktop are available to nonadministrator users See “Apple Remote Desktop Nonadministrator Access” on page 66. Interface Tips and Shortcuts There are a number of features of the Remote Desktop interface which make it particularly flexible and powerful. The following lists a few built-in shortcuts to features which can make using Remote Desktop more productive. Computers can be selected from any window Any computer in any window—report windows, task windows, computer lists, observe windows—can be a target for some task. For example, if you are observing 10 computer screens and need to send a text message to one, select the screen with a single click and then choose Interact > Send Text Message. Likewise, if you get a software report on 50 computers and notice that one of the computers is missing some vital piece of software, you can drop that software onto the selected computer within the report window. Treating all windows as possible computer selection lists for tasks may save you lots of time switching between the Remote Desktop window and other windows as you accomplish your work.38 Chapter 2 Getting to Know Remote Desktop Drag and drop works on configuration dialogs Configuration dialogs accept dragged items. Computer lists in the dialogs accept dragged computers. The Copy Items dialog accepts dragged files to copy, without having to browse the file system for them. Save yourself time and effort by dragging available items to dialogs rather than browsing for them. Making lists from reports or other lists You may need to make a list based on the outcome of some report, but you don’t know which computers will need to be included. After getting a report and sorting on the desired column, you can select the computers and make a new list from the selection. If you double-click the list icon, you open another window containing the computers in the list. This is useful for comparing lists, or for using the new window as a source from which to drag computers to other lists. Saved Tasks and Task Templates save you time You may spend a lot of time coming up with the perfect software search to find exactly what you need. You shouldn’t recreate that search every time you need it. Save your tasks, and duplicate them. With a little editing, you can have a number of similar saved tasks for specific uses. Alternatively, you can use task templates to save settings across task dialogs, applying the same settings through various tasks.3 39 3 Installing Apple Remote Desktop To use Apple Remote Desktop, install the administration software on the administrator computer first, and then install and enable the client software on the computers you want to manage. You’ll need your install disc, the serial number, and either the printed Welcome instructions, or these instructions. This chapter describes how to install Apple Remote Desktop for system administration and user interaction and gives complete setup instructions. You can learn about:  “System Requirements for Apple Remote Desktop” on page 39  “Installing the Remote Desktop Administrator Software” on page 40  “Setting Up an Apple Remote Desktop Client Computer for the First Time” on page 41  “Upgrading the Remote Desktop Administrator Software” on page 41  “Upgrading the Client Software” on page 42  “Creating a Custom Client Installer” on page 44  “Considerations for Managed Clients” on page 46  “Removing or Disabling Apple Remote Desktop” on page 46 System Requirements for Apple Remote Desktop Administrator and client computers:  Mac OS X or Mac OS X Server version 10.3.9 or later (Mac OS X version 10.4 or later is required for some features).  Mac OS Extended (HFS+) formatted hard disk.  For observing and controlling other platforms: a system running VNC-compatible server software. NetBoot and Network Install (optional)  Mac OS X Server version 10.3 or 10.4 with NetBoot and Network Install services enabled40 Chapter 3 Installing Apple Remote Desktop Network Requirements  Ethernet (recommended), AirPort, FireWire, or other network connection See “Setting Up the Network” on page 71 for more information. Installing the Remote Desktop Administrator Software To set up Apple Remote Desktop on administrator computers, you install the software on the computer you plan to use to administer remote computers. Then, you open the application setup assistant, and add to the main list of computers. To install Apple Remote Desktop on an administrator computer: 1 Insert the Apple Remote Desktop installation disc. 2 Double-click the Remote Desktop installer package and follow the onscreen instructions. The Remote Desktop application will be installed in the Applications folder. 3 Launch Remote Desktop (in the Applications folder). The Remote Desktop Setup Assistant appears. 4 Enter the serial number. The serial number can be found on the Apple Remote Desktop Welcome document that came with your software. Optionally, enter a registration name and organization. 5 Click Continue. 6 Enter a Remote Desktop application password and verify it. The Remote Desktop application password is used to encrypt names and passwords of client computers for Apple Remote Desktop. You can store this password in your keychain for convenience, or you can require that the password be entered each time you open Remote Desktop. 7 If you have another unlimited-licensed copy of Apple Remote Desktop acting as a Task Server (a dedicated computer running Remote Desktop for report data collection and delegated install tasks), enter the server address and click Continue. 8 Set the default data collection scope and time for newly administered computers. These settings will be stored as the default upload schedule, which can be applied to computers when you add them for administration. For more detailed information, see “Setting the Client’s Data Reporting Policy” on page 152. 9 Click Done. The main application window appears.Chapter 3 Installing Apple Remote Desktop 41 10 Configure some client computers for administration, find them in a scanner, and add them to a computer list. See:  “Setting Up an Apple Remote Desktop Client Computer for the First Time” on page 41  “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49 Setting Up an Apple Remote Desktop Client Computer for the First Time The following section contains information on setting up Apple Remote Desktop 3 on client computers. Since Apple Remote Desktop v1.2 was included with Mac OS X v10.3 computers and Apple Remote Desktop v2.2 was installed with Mac OS X v10.4 computers, all Apple Remote Desktop 3 client installations are upgrade installations, even if you are setting up clients for the first time. See “Upgrading the Client Software” on page 42 for more information. If the Apple Remote Desktop client software was removed from the computer, you can install a fresh copy of the most recent client software by installing Apple Remote Desktop manually. See “Method #2—Manual Installation” on page 43 for more information. If you’re setting up Mac OS X Server for the first time using Server Setup Assistant, you can enable Apple Remote Desktop as one of the initial services. This allows you to administer a server immediately after server software installation by providing Remote Desktop with the user name and password of the default system administrator. Upgrading the Remote Desktop Administrator Software Upgrading Remote Desktop is just like installing it for the first time. The only difference is that the final button in the installer reads “Upgrade” rather than “Install.” The installer upgrades existing software to its latest version, imports previously created lists, and restarts the underlying processes after completion. See “Installing the Remote Desktop Administrator Software” on page 40, for detailed instructions. If you are upgrading from version 1.2 and changing administrator computers, you’ll need to transfer your existing computer lists. See “Transferring Old v1.2 Computer Lists to a New Administrator Computer” on page 57. Be sure to transfer your lists from Apple Remote Desktop v1.2 to the new computer before upgrading to Apple Remote Desktop 3. If you upgrade from version 1.2 to version 3 on the same administrator computer, this list migration is done for you.42 Chapter 3 Installing Apple Remote Desktop Upgrading the Client Software This section contains information on installing Apple Remote Desktop 3 on client computers. Since Apple Remote Desktop client software was automatically included on the clients running Mac OS X v10.3 and v10.4, all Apple Remote Desktop 3 installations are upgrade installations, even if you are setting up clients for the first time. You can only upgrade Apple Remote Desktop v1.x and v2.x computers if they meet the minimum system requirements (see “System Requirements for Apple Remote Desktop” on page 39). Please note that there is no supported “downgrade” to any previous version, and if you upgrade the client computers to version 3, you will not be able to administer them with earlier versions of Remote Desktop. There are two methods to upgrade the client computer’s software. Method #1—Remote Upgrade Installation This method works best with existing clients already configured using a previous version of Apple Remote Desktop. If used with existing administered clients, use Remote Desktop to identify those clients running a previous version. You may then upgrade them to the latest version. The main benefit of this upgrade method is the ease of installation and the retention of previous client settings, if any. This method only works for Apple Remote Desktop 1.2 clients and later. Earlier versions of Apple Remote Desktop like 1.0 must be upgraded to version 1.2 using Mac OS X’s Software Update, or they must be updated manually. See “Method #2—Manual Installation” on page 43 for more information. To upgrade existing client software remotely using Apple Remote Desktop: 1 Enable the existing version of Apple Remote Desktop on the client computers. 2 Configure the clients for administration. See “Setting Apple Remote Desktop Administrator Access Authorization and Privileges Using Local Accounts” on page 61. 3 If the client computers are not in an existing Remote Desktop computer list, find the client computers using an Apple Remote Desktop scanner. See “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49 for more information. 4 Select the client computers to be upgraded. 5 Choose Manage > Upgrade Client Software. 6 Click Upgrade.Chapter 3 Installing Apple Remote Desktop 43 Method #2—Manual Installation This method works best if you have never enabled Apple Remote Desktop on your clients and have an existing software distribution infrastructure. This method also allows for the greatest power and configuration flexibility. Also, if you don’t want Apple Remote Desktop to upgrade your clients using the Upgrade Client Software feature, you can perform a manual upgrade. The custom installer not only installs the needed software but also prepares and configures the client computer for administration and can be configured to add or edit user names and passwords for Apple Remote Desktop authentication. To manually upgrade the client software: 1 Use Remote Desktop to create a client software installer package. For detailed instructions, see “Creating a Custom Client Installer” on page 44. 2 Copy and install the package on the client computers. You need the name and password of a user with administrator privileges on the computer to install the package. There are several ways to do this. For example, you can:  Distribute the package by removable media, such as a CD.  Copy the installer to the clients over the network using file sharing.  Copy the installer to the clients using command-line tools like scp (if ssh is enabled), and use Apple’s command-line installation tool, “installer,” to install the package remotely. This process is described in detail in “Upgrading Apple Remote Desktop Clients Using SSH” on page 43.  Add the custom installer package to a Network Install image, using System Image Utility to automatically include the software and your custom settings when clients install the operating system using Mac OS X Server 10.4’s NetBoot and Network Install features. Upgrading Apple Remote Desktop Clients Using SSH You may not be able to or want to use Remote Desktop to upgrade existing clients to Apple Remote Desktop 3. If the clients have SSH enabled (called Remote Login in System Preferences), and are available on the network, you can still upgrade the client computers. You still need to use Remote Desktop to create a custom installer package. You also need the user name and password of a user with system administrator privileges on the client computer. Warning: Custom install packages that create user names contain sensitive password data. Take care to store such custom installers securely.44 Chapter 3 Installing Apple Remote Desktop To upgrade existing client software using SSH: 1 Create the custom client installer package. For detailed instructions, see “Creating a Custom Client Installer” on page 44. 2 Open the Terminal application (located in /Applications/Utilities/). 3 Copy the installer package to the client computer by typing: $ scp -r @: For other options, see the scp man page. 4 Log in to the client computer by typing: $ ssh @ For other options, see the ssh man page. 5 On the client computer, install the package by typing: $ sudo installer -pkg -target / For other options, see installer man page. Creating a Custom Client Installer To install the Apple Remote Desktop client software on computers, you use the administrator application, Remote Desktop, to create a custom client installer. The custom client installer not only installs the Apple Remote Desktop system software, but can create user names and passwords on the client computer with their Apple Remote Desktop privileges already assigned. You’ll use an assistant to create a custom client installer package. Any values set in the custom installer will apply to all the computers that receive the installation. While creating a custom installer, you will have a chance to create new Apple Remote Desktop administrator user names with passwords, and automatically set Apple Remote Desktop access privileges and preferences. To create the client installer: 1 Open Remote Desktop. 2 Choose File > Create Client Installer. The Custom Installer Setup Assistant appears. 3 Choose to create a custom installer and click Continue. If you choose not to create a custom installer, you can create a basic installer that sets no preferences on the client computer. Warning: Custom installer packages that create user names contain sensitive password data. Take care to store and transmit such custom installers securely.Chapter 3 Installing Apple Remote Desktop 45 4 Click Continue to begin creating a custom installer. 5 Choose whether to start Remote Desktop sharing at system startup. This changes the setting found in the Sharing pane of System Preferences. 6 Choose whether to hide or show the Apple Remote Desktop menu bar icon. 7 Click Continue. 8 Choose whether to create a new user for Apple Remote Desktop login. Click Continue. A new user account can be created to grant Apple Remote Desktop administrator privileges. Creating a new user account does not overwrite existing user accounts or change existing user passwords. If you choose not to create a new user account, skip to step 10 after clicking Continue. 9 Add a new user by clicking Add and filling in the appropriate information. Click OK after adding each user, and click Continue when you’re ready to go on. 10 Choose whether to assign Apple Remote Desktop administrator access privileges to Directory Services groups. If you choose to do so, select “Enable directory-based administration.” See “Apple Remote Desktop Administrator Access Using Directory Services” on page 62 for more information on using this method to grant Apple Remote Desktop administrator access. 11 Choose whether to assign Apple Remote Desktop administrator access privileges to specific users. Click Continue. If you choose not to assign administrator access privileges, skip to step 14. 12 Click Add to designate a user to receive Apple Remote Desktop access privileges. 13 Provide the user’s short name and set the privileges as desired. See “Apple Remote Desktop Administrator Access” on page 59 for more information. Click OK after each user, and click Continue when you’re ready to go on. 14 Choose whether to allow temporary guest control by requesting permission on the client computers. See “Considerations for Managed Clients” on page 46 for more information. 15 Choose whether to allow non–Apple VNC viewers to control the client computers, and click Continue. See “Virtual Network Computing Access” on page 67 for more information. 16 If desired, select and enter information in any or all of the four System Data fields. This information appears in Apple Remote Desktop System Overview reports. For example, you can enter an inventory number for the computer, a serial number, or a user’s name and telephone number.46 Chapter 3 Installing Apple Remote Desktop 17 Click Continue. 18 Select a location for the installer. 19 Click Continue to create the installer. An installer metapackage (.mpkg file) is created in the designated location. 20 Click Done. Considerations for Managed Clients If you plan on restricting what applications can open on a managed client, you’ll need to make sure that Apple Remote Desktop’s processes are allowed to run. A managed client is a client computer whose environment is governed by Mac OS X Server’s Workgroup Manager. The following options need to be enabled in Workgroup Manager’s client and group application preference settings:  “Allow approved applications to launch non-approved applications”  “Allow UNIX tools to run” Removing or Disabling Apple Remote Desktop Apple Remote Desktop’s client components are bundled as part of Mac OS X and Mac OS X Server. You may choose to remove or disable parts of it to fit your own personal computing needs. The following section describes how to uninstall or disable key Apple Remote Desktop components. Uninstalling the Administrator Software To remove the administrator software completely, you must remove the application, the encrypted list of computer user names and passwords, and the client information database. To remove the administrator software: 1 Drag the Remote Desktop application to the Trash. 2 Empty the Trash. 3 Delete the Apple Remote Desktop database from /var/db/RemoteManagement/ using the following commands in the Terminal application: $ sudo rm -rf /var/db/RemoteManagement 4 Delete the Remote Desktop preferences files using the following commands in the Terminal application. $ sudo rm /Library/Preferences/com.apple.RemoteDesktop.plist $ sudo rm /Library/Preferences/com.apple.RemoteManagement.plist $ rm ~/Library/Preferences/com.apple.RemoteDesktop.plistChapter 3 Installing Apple Remote Desktop 47 5 Delete the Remote Desktop documentation using the following commands in the Terminal application. sudo rm -r /Library/Documentation/Applications/RemoteDesktop 6 Delete the Apple Remote Desktop support files from /Library/Application Support/ using the following commands in the Terminal application: $ rm -rf ~/Library/Application\ Support/Remote\ Desktop/ $ sudo rm -rf /Library/Application\ Support/Apple\ Remote\ Desktop/ 7 Delete the Apple Remote Desktop installation receipts from /Library/Receipts/ using the following commands in the Terminal application: $ rm -r /Library/Receipts/RemoteDesktopAdmin* $ rm -r /Library/Receipts/RemoteDesktopRMDB* 8 Delete the Apple Remote Desktop Dashboard Widget (after closing every instance of the Widget) using the following commands in the Terminal application: $ sudo rm -r /Library/Widgets/Remote\ Desktop/ Disabling the Client Software You may want to temporarily disable Apple Remote Desktop on a client without removing the software. To disable the client software on a client computer: 1 On the client computer, open System Preferences and click Sharing. If necessary, enter the user name and password of a user with administrator privileges on that computer. 2 Deselect Apple Remote Desktop in the Sharing pane. 3 Quit System Preferences. Apple Remote Desktop is now disabled and the underlying software is deactivated. Alternately, you can disable only the administrator privileges by doing the following: a Click Access Privileges. b Deselect each user account that you enabled for Apple Remote Desktop administration. c Click OK. d Quit System Preferences. Warning: Because Apple Remote Desktop is part of the default Mac OS X 10.3 and 10.4 installation, do not remove the Apple Remote Desktop client components.48 Chapter 3 Installing Apple Remote Desktop Uninstalling the Client Software from Client Computers To remove Apple Remote Desktop client software from Mac OS X clients, you need to remove a number of software components from each client system. To uninstall client software: 1 Open Terminal (located in /Applications/Utilities). 2 Delete the client pieces from /System/Library/ using the following commands in the Terminal application: $ sudo rm -rf /System/Library/CoreServices/Menu\ Extras/RemoteDesktop.menu $ sudo rm -rf /System/Library/CoreServices/RemoteManagement/ $ sudo rm -rf /System/Library/PreferencePanes/ARDPref.prefPane $ sudo rm -rf /System/Library/StartupItems/RemoteDesktopAgent/ 3 Delete the client preferences from /Library/Preferences/ using the following command in the Terminal application: $ sudo rm /Library/Preferences/com.apple.ARDAgent.plist $ sudo rm /Library/Preferences/com.apple.RemoteManagement.plist 4 Delete the client installation receipts from /Library/Receipts/ using the following command in the Terminal application: $ sudo rm -r /Library/Receipts/RemoteDesktopClient* $ sudo rm -rf /var/db/RemoteManagement/ Warning: It is not recommended that you uninstall the client software. Disabling the client software is sufficient to stop Apple Remote Desktop system activity. See “Disabling the Client Software” on page 47 for instructions.4 49 4 Organizing Client Computers Into Computer Lists Apple Remote Desktop uses lists of client computers to logically organize the client computers under your control. Connecting to client computers on the network and adding them to your list is necessary to administer them. This chapter describes finding clients and organizing them into lists for Apple Remote Desktop administration and user interaction. You can learn about:  “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49  “Making and Managing Lists” on page 53  “Importing and Exporting Computer Lists” on page 56 Finding and Adding Clients to Apple Remote Desktop Computer Lists Before you can audit, control, or maintain any client, you need to add it to an Apple Remote Desktop computer list. To find computers that aren’t on the local subnet, your local network’s routers and firewalls must be properly configured to pass network “pings,” and TCP/UDP packets on ports 3283 and 5900. Remote Desktop has four different methods for discovering possible clients: searching the local networks, searching a range of IP addresses, using a specific IP address or domain name, and importing a list of IP addresses. Once you have found a potential client, you see the following default information: Search column Description (none) Displays a small icon indicating whether the computer is already in the Master List. (none) Displays a small icon showing what kind of access the client is capable of. See “Client Status Icons” on page 161. Name The name given to the computer in the Sharing pane of System Preferences. IP Address The computer’s IP address, if any.50 Chapter 4 Organizing Client Computers Into Computer Lists If you want to change the default display list for the scanner, you can select Edit > View Options and choose any of the other available options (which include Computer Info Fields, Ethernet ID, Label, or others). To add a computer to a computer list, you first authenticate to the computer. Authenticated computers are found in the All Computers list in the Remote Desktop window. You can add a computer to the All Computers list without authenticating, but you will be unable to administer the client until you provide a valid user name and password. Finding Clients by Searching the Local Network When you select a local network scanner, Remote Desktop sends a subnet broadcast to computers in the same subnets as the administrator computer. All possible clients on the local subnets appear in a list on the right side of the Remote Desktop window. To search for clients on the local network: 1 Select a scanner at the left of the Remote Desktop window. 2 Select Local Network. All responding clients are listed in the Remote Desktop window. 3 Select the desired computers. 4 Drag the selected computers to the All Computers list. 5 Authenticate by providing a user name and password for an Apple Remote Desktop administrator. The computer is now in your All Computers list. Finding Clients by Searching a Network Range To locate computers by network range, you provide a beginning and ending IP address to scan, and Apple Remote Desktop queries each IP address in that range in sequence, asking if the computer is a client computer. This method works best when searching for clients outside the local subnet, but on the local area network. Alternatively, you can use a text file that contains IP address ranges (in this format “192.168.0.1-192.168.3.20”), and use text file import to find clients. See “Finding Clients by File Import” on page 52. DNS Name The computer’s DNS name, found by reverse lookup, if any. ARD Version Apple Remote Desktop client software version. Network Interface Which interface the client responded through. Search column DescriptionChapter 4 Organizing Client Computers Into Computer Lists 51 To search a range of network addresses: 1 Select a scanner at the left of the Remote Desktop window. 2 Select Network Range. 3 Enter the beginning and ending IP address. 4 Click the Refresh button. All responding clients are listed in the Remote Desktop window. 5 Select the desired computers. 6 Drag the selected computers to the All Computers list. 7 Authenticate by providing a user name and password for an Apple Remote Desktop administrator. The computer is now in your All Computers list. Finding Clients by Network Address If you know the exact IP address or fully qualified domain name of a computer, you can use that IP address or domain name to add the computer to your All Computers list. To add a specific address immediately to the All Computers list: 1 Choose File > Add By Address. 2 Enter the IP address or fully qualified domain name. 3 Enter the user name and password. 4 Choose whether to verify the name and password before adding it to the All Computers list. 5 Click Add. Alternatively you use the scanner to try an address or domain name and check availability before attempting to add it to the All Computers list. To search for a specific address: 1 Select a scanner at the left of the Remote Desktop window. 2 Select Network Address. 3 Enter the IP address or fully qualified domain name in the Address field. 4 Click the Refresh button. If the client responds successfully, it is listed in the Remote Desktop window. 5 Select the desired computers. 6 Drag the selected computers to the All Computers list. 7 Authenticate by providing a user name and password for an Apple Remote Desktop administrator. The computer is now in your All Computers list.52 Chapter 4 Organizing Client Computers Into Computer Lists Finding Clients by File Import You can import a list of computers into Apple Remote Desktop by importing a file listing the computers’ IP addresses. The list can be in any file format (text, spreadsheet, word processor) and must contain either IP addresses or fully qualified domain names (such as foo.example.com). File import also allows you to add ranges of IP addresses by expressing the range in the following format: xxx.xxx.xxx.xxx-yyy.yyy.yyy.yyy. For example, a text file with the line “192.168.0.2-192.168.2.200” would add all IP addresses in that address range. To import a list of computers from a file: 1 Select a scanner at the left of the Remote Desktop window. 2 Select File Import. 3 Browse for the file by clicking the Open File button, or drag a file into the window. Alternatively, you can enter the file’s pathname in the File field. All responding clients are listed in the Remote Desktop window. 4 Select the desired computers. 5 Drag the selected computers to the All Computers list. 6 Authenticate by providing a user name and password for an Apple Remote Desktop administrator. The computer is now in your All Computers list. Making a New Scanner You may want several scanners in order to search for specific address ranges or to do other types of searches. You can make and save your own scanner so you can quickly do the search at any time. You can rename scanners to make them easy to identify. To make a custom search list: 1 Choose File > New Scanner. 2 Rename the newly created scanner. 3 Select the scanner icon. 4 Choose a search type from the pop-up menu to the right.Chapter 4 Organizing Client Computers Into Computer Lists 53 5 Customize the search by entering the specific parameters for the search (such as an IP address range, or file location). You can find out how to customize the search in the following sections:  “Finding Clients by Searching the Local Network” on page 50  “Finding Clients by Searching a Network Range” on page 50  “Finding Clients by Network Address” on page 51  “Finding Clients by File Import” on page 52 6 Click the Refresh button. All responding clients are listed in the Remote Desktop window. Select your scanner icon and click the Refresh button whenever you want to run the search. Making and Managing Lists You use lists to organize and perform management tasks on client computers. You can make groups of lists, and rearrange the lists by dragging them up and down the left side of the main window. Apple Remote Desktop has several different kinds of lists. The following section describes the kinds of lists, and explains how to create lists and use them for client management. About Apple Remote Desktop Computer Lists Apple Remote Desktop displays computers in lists in the main section of the Remote Desktop window. The default computer list is called the All Computers list. This is a full list of all possible clients that you have located and authenticated to. You can create other lists to group the computers on your network in any way you wish. Computer lists have the following capabilities:  You can create as many lists as you want.  The All Computers list can have up to the number of computers your license allows.  Computers can appear in more than one list.  Lists can be made in any grouping you can imagine: geographic, functional, hardware configuration, even color.  Click a list name and keep the mouse over the list name, you can edit the list name.  If you double-click the list icon, you open another window containing the computers in the list.54 Chapter 4 Organizing Client Computers Into Computer Lists Creating an Apple Remote Desktop Computer List You can make more specific, targeted lists of computers from your All Computers list. The easiest way to make a new list is to use computers already in the All Computers list. You can also create blank lists and add computers to them later. To create an Apple Remote Desktop computer list: 1 Select the All Computers list icon in the main Remote Desktop window. 2 Select the computers you want to add to the new list. 3 Choose File > New List From Selection. 4 Name the computer list. Alternatively, you can choose File > New List to create a blank list and drag computers from the All Computers list, or from the scanner search results, to the blank list. Deleting Apple Remote Desktop Lists You can delete Apple Remote Desktop computer lists and scanner lists that you created. You cannot delete the All Computers list, Task Server list, or Task History list. To delete a list: m Select the list and press the Delete key. Creating a Smart Computer List You can create a computer list which automatically populates based on custom criteria. Once you create a smart list, any computer added to the All Computers list (or other specified list) which matches the criteria will automatically be added to the smart list. You can match any or all of the following criteria:  Name  IP Address  DNS Name  Label  Apple Remote Desktop version  Startup Volume  Installed RAM  CPU Information  Machine Model  Mac OS version  Computer is in List In order to use a smart list which populates from any list except the All Computers list, you need to add the “Computer is in List” criterion and specify the source list.Chapter 4 Organizing Client Computers Into Computer Lists 55 To create a smart computer list: 1 Choose File > New Smart List. 2 Name the smart computer list. 3 Choose “any” or “all” criteria to match. 4 Select the attribute to select by, using the pop-up windows and text entry field. 5 Add any other criteria with the Add (+) button. 6 Click OK. The new smart list appears in Remote Desktop’s main window. Editing a Smart Computer List You may want to edit the smart lists you have created. The editing window is the same as the one used to create the smart list. The options available are the same as those listed in “Creating a Smart Computer List” on page 54. To edit a smart computer list: 1 Select the smart list in Remote Desktop’s main window. 2 Choose File > Edit Smart List. 3 Change the smart computer list as desired. Creating a List of Computers of from Existing Computer Lists You may want a list which combines the results of several different lists and smart lists. You can create aggregate lists by using the “Computer is in List” option. The list created will have the computers from the source lists, but not indicate which source list they came from. To create an list of computer lists: 1 Create the lists which will serve as the sources of the smart list. See “Creating an Apple Remote Desktop Computer List” on page 54 or “Creating a Smart Computer List” on page 54 for more information. 2 Create the Smart List which will draw its computers from the previously created lists. “Creating a Smart Computer List” on page 54 for more information. 3 In the Smart List creation dialog, choose to match all of the stated conditions. 4 For the first condition, select “Computer is in List.” 5 Select a source list from the pop-up menu. 6 Add another condition by clicking the Add (+) button. 7 Repeat steps 4-6, adding Computer Lists for all of the source lists.56 Chapter 4 Organizing Client Computers Into Computer Lists 8 Add other conditions and criteria as desired. 9 Create the final Smart List by clicking OK. The new Smart List appears in Remote Desktop’s main window. Importing and Exporting Computer Lists When setting up Apple Remote Desktop 3, you may not necessarily use the same computer you used for the previous version of Apple Remote Desktop. Rather than create new lists of client computers, you can transfer existing lists between computers, with benefits and limitations depending on the transfer circumstance. The following sections will help you import or export your computer lists.  “Transferring Computer Lists from Apple Remote Desktop 3 to a New Administrator Computer” on page 56  “Transferring Remote Desktop 2 Computer Lists to a New Remote Desktop 3 Administrator Computer” on page 57  “Transferring Old v1.2 Computer Lists to a New Administrator Computer” on page 57 Transferring Computer Lists from Apple Remote Desktop 3 to a New Administrator Computer You may want to move your existing computer lists to the new administrator computer running Apple Remote Desktop 3. Lists transferred in this way retain their client computers as well as the original name of the list. You can only use these instructions to move computer lists between administrator computers which run Apple Remote Desktop 3. When you import or export a computer list, the user name and password used for Apple Remote Desktop authentication are not exported. Once you’ve imported the computer list, you will still need to authenticate to the computers. To transfer the computer lists: 1 In the main Remote Desktop window, select the list you want to move. 2 Choose File > Export List. 3 Select a name and a file location for the exported list. The default file name is the list name. Changing the file name, however, does not change the list name. 4 Click Save. A .plist file is created in the desired location. The XML-formatted .plist file is a plain text file that can be inspected with Apple’s Property List Editor or a text editor. 5 Copy the exported file to the desired administrator computer. 6 On the new administrator computer, launch Remote Desktop. 7 Choose File > Import List.Chapter 4 Organizing Client Computers Into Computer Lists 57 8 Select the exported list, and click Open. The list now appears in Remote Desktop’s main window. Transferring Remote Desktop 2 Computer Lists to a New Remote Desktop 3 Administrator Computer If you are installing Apple Remote Desktop 3 on a computer different from the version 2.x administrator computer, you may want to move your existing computer lists to the new administrator computer running Apple Remote Desktop 3. When you import or export a computer list, the user name and password used for Apple Remote Desktop authentication are not exported. Once you’ve imported the computer list, you will still need to authenticate to the computers. To transfer the computer lists: 1 In the main Remote Desktop window, select the list you want to move. 2 Make sure Remote Desktop lists the computer’s name and IP address. 3 Choose File > Export Window. 4 Select a name and a file location for the exported list, and click Save. The default file name is the window’s title. 5 Copy the exported file to the desired administrator computer. 6 On the new administrator computer, launch Remote Desktop. 7 Using the Scanner, add the clients by File Import. See “Finding Clients by File Import” on page 52, for detailed instructions. The list now appears in Remote Desktop’s main window. 8 Select the computers in the list. 9 Choose File > New List From Selection. The new list now appears in Remote Desktop’s main window. Transferring Old v1.2 Computer Lists to a New Administrator Computer If you are installing Apple Remote Desktop 3 on a computer other than an older administrator computer using Apple Remote Desktop 1.2, you need to move your existing computer lists to the new administrator computer before installing version 3. These instructions only apply when moving Apple Remote Desktop 1.2 computer lists to a new computer. Throughout these instructions, the computer with the original lists is the “source computer.” The computer that will have Apple Remote Desktop 3 installed is the “target computer.”58 Chapter 4 Organizing Client Computers Into Computer Lists To transfer the computer lists: 1 Open Keychain Access (located in /Applications/Utilities) on the source computer. 2 Choose File > New Keychain. 3 Name the new keychain, and click Create. 4 Enter a password for the new keychain. This is a temporary password that you will use to retrieve the information in the keychain. Do not use your login password or other sensitive password. 5 If necessary, click Show Keychains to show the administrator keychain. 6 Select the source computer’s main keychain. If the keychain is locked, unlock it and authenticate. 7 Select only the Apple Remote Desktop entries in the keychain. 8 Drag the Apple Remote Desktop entries to the newly created keychain. 9 Provide the source computer keychain password for each entry. 10 Quit Keychain Access on the source computer. 11 Copy the newly created keychain from the source computer (~/Library/Keychains/ ) to the same location on the target computer. You can copy the keychain over the network, or use a removable storage drive. 12 On the target computer, open Keychain Access in the Finder. 13 Choose File > Add Keychain. 14 Select the keychain that was copied from the source computer, and click Open. 15 If necessary, click Show Keychains to show the keychains. 16 Unlock the newly imported keychain, using the password designated for that keychain. 17 Select the Apple Remote Desktop entries. 18 Drag the Apple Remote Desktop entries to the main keychain on the target computer. Provide the temporary keychain password for each entry. 19 Quit Keychain Access on the source computer. When you open Apple Remote Desktop on the new computer, you will notice that the computer lists from the old computer are available.5 59 5 Understanding and Controlling Access Privileges There are several different ways to access and authenticate to Apple Remote Desktop clients. Some depend on Apple Remote Desktop settings, and others depend on other client settings, or third-party administration tools. This chapter explains the various access types, their configuration, and their uses. You can learn about:  “Apple Remote Desktop Administrator Access” on page 59  “Apple Remote Desktop Administrator Access Using Directory Services” on page 62  “Apple Remote Desktop Guest Access” on page 65  “Apple Remote Desktop Nonadministrator Access” on page 66  “Virtual Network Computing Access” on page 67  “Command-Line SSH Access” on page 68  “Managing Client Administration Settings and Privileges” on page 68 Apple Remote Desktop Administrator Access Access privileges allow an Apple Remote Desktop administrator to add computers to a list and then interact with them. If no access privileges are allowed on a client computer, that computer cannot be used with Apple Remote Desktop. Access privileges are defined in the Apple Remote Desktop section of the Sharing pane of the client computers’ System Preferences. The recommended access privileges for a client computer depend on how it’s used.  If the computer is used in a public area, such as a computer lab, you may want to allow administrators full access privileges.  If the computer is used by one person, you may not want to give administrators full access privileges. Also, you may want a user who administers his or her own computer to take responsibility for creating passwords and setting the access privileges for the computer60 Chapter 5 Understanding and Controlling Access Privileges The following table shows the settings in the Apple Remote Desktop settings in the Sharing Preference pane and the features of Remote Desktop that they correspond to. For example, if you want a certain administrator to be rename computer file sharing names, you will need to grant that user that privilege by selecting “Change Settings”. checkbox in the Apple Remote Desktop settings in the Sharing Preference pane on the client computer. Select To allow administrators to Select any other privileges. (If you select only this box, the administrator can see the client computer in the Computer Status window and include it in Network Test reports.) Generate reports Create hardware and software reports using the Report menu; use Set Reporting Policy and Spotlight Search. Open and quit applications Use these Manage menu commands: Open Application, Open Items, Send UNIX Command and Log Out Current User. Change settings Use these Manage menu commands: Rename Computer, Send UNIX Command and Set Startup Disk. Delete and replace items Use these Manage menu commands: Copy Items, Install Packages, Send UNIX Command and Empty Trash. Also delete items from report windows. This item must be enabled in order to use the Upgrade Client Software feature. Send text messages Use these Interact menu commands: Send Message and Chat. Restart and shut down Use these Manage menu commands: Sleep, Wake Up, Restart, Send UNIX Command, and Shut Down. This item must be enabled in order to use the Upgrade Client Software feature. Copy items Use these Manage menu and Server menu commands: Copy Items, Send UNIX Command and Install Packages. This item must be enabled in order to use the Upgrade Client Software and Change Client Settings features. Control Use these Interact menu commands: Control, Share Screen, Lock and Unlock Screen. This item must be enabled in order to use the Upgrade Client Software and Change Client Settings features.Chapter 5 Understanding and Controlling Access Privileges 61 Setting Apple Remote Desktop Administrator Access Authorization and Privileges Using Local Accounts To prepare a client for administration, you activate the existing version of Apple Remote Desktop on the client computer and set Apple Remote Desktop administrator access privileges by using the Sharing pane of the computer’s System Preferences. You set access privileges separately for each user account on the computer. Follow the steps in this section to set access privileges on each client computer. Note: You can skip this step if you create a custom installer that automatically enables your desired client settings. To make changes on a client computer, you must have the name and password of a user with administrator privileges on the computer. To set administrator privileges on a computer: 1 On the client computer, open System Preferences and click Sharing. If the preference pane is locked, click the lock and then enter the user name and password of a user with administrator privileges on that computer. 2 Select Apple Remote Desktop in the Sharing service pane. 3 Click Access Privileges. 4 Select each user that you want enabled for Apple Remote Desktop administration authentication. 5 Select a listed user whose access privileges you want to set, and then make the changes you want to the access privileges. Your changes take effect immediately. Hint: Holding down the Option key while clicking the user’s checkbox will automatically select all the following checkboxes for access. See “Apple Remote Desktop Administrator Access” on page 59 for more information. 6 Repeat for additional users whose access privileges you want to set. 7 If desired, enter information in any or all of the four Computer Information fields. This information appears in Apple Remote Desktop System Overview reports and optionally in the computer list views. For example, you can enter an inventory number for the computer, a serial number, or a user’s name and telephone number. 8 Click OK. 9 To activate the Apple Remote Desktop client, make sure to select the Apple Remote Desktop checkbox, or select Apple Remote Desktop and click Start.62 Chapter 5 Understanding and Controlling Access Privileges Apple Remote Desktop Administrator Access Using Directory Services You can also grant Apple Remote Desktop administrator access without enabling any local users at all by enabling group-based authorization if the client computers are bound to a directory service. When you use specially named groups from your Directory Services master domain, you don’t have to add users and passwords to the client computers for Apple Remote Desktop access and privileges. When Directory Services authorization is enabled on a client, the user name and password you supply when you authenticate to the computer are checked in the directory. If the name belongs to one of the Apple Remote Desktop access groups, you are granted the access privileges assigned to the group. Creating Administrator Access Groups In order to use Directory Services authorization to determine access privileges, you need to create groups and assign them privileges. There are two ways of doing this: Method #1 You can create groups and assign them privileges through the mcx_setting attribute on any of the following records: any computer record, any computer list record, or the guest computer record. To create an administrator access group: 1 Create groups as usual. If you are using Mac OS X Server, you use Workgroup Manager to make them. 2 After you have created groups, you edit either the computer record of the computer to be administered, its computer list record, or the guest computer record. 3 Use a text editor, or the Apple Developer tool named Property List Editor to build the mcx_setting attribute XML. The XML contains some administrator privilege key designations (ard_admin, ard_reports, etc.), and the groups that you want to possess those privileges. The following privilege keys have these corresponding Remote Desktop management privileges:Chapter 5 Understanding and Controlling Access Privileges 63 In the XML, you name a privilege key and make the value the name of the group or groups you want to possess the privilege. Use the sample XML below to make your management/key designation XML. 4 When you have created the snippet of XML, you enter this whole snippet into a computer record or computer list record. If you are using Workgroup Manager, you enable the preference to “Show All Records Tab and Inspector” and use the Inspector to copy the entire snippet of XML the value which corresponds to the “MCXSettings” attribute name. Management Privilege ard_admin ard_reports ard_manage ard_interact Generate reports X X X Open and quit applications X X Change settings X X Copy items X X Delete and replace items X X Send messages X X X Restart and shut down X X Control X X Observe X X Show being observed X X64 Chapter 5 Understanding and Controlling Access Privileges For more information on using Workgroup Manager, and Open Directory, see their documentation at: www.apple.com/server/documentation The following is the sample XML format you need to use to assign management privileges via MCX keys. It assigns the above “ard_interact” privileges to the groups named “some_group” and “staff.” It also assigns the “ard_manage” privileges to the group named “staff,” the “ard_admin” privileges to the group “my_admin_group,” and leaves no group with the “ard_reports” privilege set. Here’s the XML: mcx_application_data com.apple.remotedesktop Forced mcx_preference_settings ard_interact some_group staff ard_manage staff ard_admin my_admin_group ard_reports This example attribute defines four privileges, although any of them may be left out.Chapter 5 Understanding and Controlling Access Privileges 65 Method #2 You can create groups with special names that correspond to the privilege keys above: ard_admin, ard_reports, ard_manage, and ard_interact. The corresponding privileges are automatically assigned to these specially named groups. If you have already created these groups for use with Apple Remote Desktop 2, they will continue to work as expected with Apple Remote Desktop 3. Enabling Directory Services Group Authorization In order to enable group-based authorization for Apple Remote Desktop access, you create the appropriate groups in your Directory Services master directory domain. To complete this task, you need to be the Directory Services administrator and have access to your organization’s users and groups server. To enable Apple Remote Desktop authorization by group: 1 Use one of the methods in the section “Creating Administrator Access Groups” to create groups with Apple Remote Desktop access privileges assigned to them. 2 Add users to the groups. 3 Make sure the client computers to be administered are bound to your directory system. 4 Set the clients to use directory authorization by using the Change Client Settings feature or make a custom installer. 5 Choose to enable directory-based administration on the clients using Directory Access found in /Applications/Utilities/. Apple Remote Desktop Guest Access You can configure an Apple Remote Desktop client to give temporary, one-time access to an Apple Remote Desktop administrator who does not have a user name or password for the client computer. Each time the Apple Remote Desktop administrator would like to control the client computer, he or she must request permission from the remote client’s user. Warning: Granting access to control a screen is the most powerful feature in Apple Remote Desktop, and can be equivalent to unrestricted access.66 Chapter 5 Understanding and Controlling Access Privileges To allow guest access: 1 On the client computer, open System Preferences and click Sharing. If prompted, enter the user name and password of a user with administrator privileges on that computer. 2 Select Apple Remote Desktop in the Sharing pane. 3 Click Access Privileges. 4 Select “Guests may request permission to control screen.” 5 Click OK. Apple Remote Desktop Nonadministrator Access Remote Desktop can operate in what is referred to as “user mode.” User mode is activated when a nonadministrator user opens Remote Desktop to administer Apple Remote Desktop client computers. The administrator of the computer with Remote Desktop installed can choose which features and tasks are available to nonadministrator users. Limiting Features in the Administrator Application User mode is a great way to delegate administrative tasks, or give users only the features of Remote Desktop that they really use. For example, you might not allow nonadministrators to copy or delete files, but you may want them to be able to observe client screens and send messages to client users. You can choose to allow nonadministrators to:  Observe, control, and share screens  Lock and unlock screens  Send text messages and chat  Sleep and wake client computers  Log out users  Restart and shut down computers  Open or quit files and applications  Rename computers  Generate reports and software searches  Copy items, delete items, and empty the Trash  Create Apple Remote Desktop custom client installers  Upgrade clients and change client settings  Install packages  Set the client computer’s startup volume  Set the client’s data reporting policy  Send UNIX commandsChapter 5 Understanding and Controlling Access Privileges 67 Each of these features can be enabled or disabled independently of each other, or you can enable all of Remote Desktop’s features for nonadministrator users. To enable User Mode: 1 Make sure you are logged in as an administrator user. 2 Open Remote Desktop. 3 Choose Remote Desktop > Preferences. 4 Click the Security button. 5 Enable or disable features, as desired. 6 Close the Preference’s window. Virtual Network Computing Access You can use Apple Remote Desktop to access a Virtual Network Computing (VNC) server and view and interact with the server’s screen. VNC access is determined by the VNC server software. To access a VNC server, it is only necessary to know the IP address or fully qualified domain name and the password designated in the VNC server software. This password does not necessarily correspond to any other password on the system, and is determined by the VNC configuration. VNC access is similar to Apple Remote Desktop’s Control command. It allows you to use your keyboard and mouse to control a VNC server across a network. It doesn’t give any other Apple Remote Desktop administrator privileges except those of the currently logged-in user. Non-Apple VNC viewers can control Apple Remote Desktop clients if the client allows it. Allowing a non-Apple VNC viewer access to an Apple Remote Desktop client is less secure than using Apple Remote Desktop to control the client. The VNC protocol implemented in third-party VNC viewers may not encrypt keystrokes sent over the network, so sensitive information can be intercepted. Warning: Granting VNC access to control a screen is the most powerful feature in Apple Remote Desktop, and can be equivalent to unrestricted access.68 Chapter 5 Understanding and Controlling Access Privileges To allow VNC access: 1 On the client computer, open System Preferences and click Sharing. If prompted, enter the user name and password of a user with administrator privileges on that computer. 2 Select Apple Remote Desktop in the Sharing pane. 3 Click Access Privileges. 4 Select “VNC viewers may control screen with password.” 5 Enter a VNC password. Command-Line SSH Access Command-line SSH access is not granted or managed using Remote Desktop. This type of access is managed in the Sharing pane of System Preferences (called “Remote Login”) and is separate from Apple Remote Desktop access types. When you log in to a client remotely using SSH, you have the user privileges assigned to the user name and password. These may or may not include computer administrator privileges. You can use SSH to access a client using a user account created for Apple Remote Desktop, but you are limited to performing whatever tasks were allowed to that user when the account was created. Conversely, only the users specified in the Apple Remote Desktop access privileges can access a computer using Apple Remote Desktop. Apple Remote Desktop privileges are completely separate and distinct from local computer administrator UNIX privileges. Managing Client Administration Settings and Privileges Regular audits of administration settings can help maintain a secure Remote Desktop administration environment. Using the various administrator options given with Apple Remote Desktop administrator privileges, you can create specialized logins for certain tasks, limiting potentially disruptive power of certain sub-administrators. The following section gives detailed instructions for checking the administrator privilege settings of client computers, and changing those settings. Warning: Do not use the same password as any local user or Apple Remote Desktop login.Chapter 5 Understanding and Controlling Access Privileges 69 Getting an Administration Settings Report You can query active Apple Remote Desktop clients for a report on what commands they are accepting from your administrator authentication. The report is a list of the Apple Remote Desktop administrator access types each with an “On” or “Off” to indicate whether that access type is available to you. To get an administration settings report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Administration Settings. 4 Click Get Report. Changing Client Administrator Privileges Once the client computers are able to be administered, you can change the administrator access privileges for multiple computers simultaneously, using the Change Client Settings command. If you are using Directory Services to designate administrator privileges, you don’t need to change the settings on the clients. To make changes on a client, you must have the name and password of a user with administrator privileges on the computer. Additionally, you must already have the Control privilege. Note: You do not have to make a selection on every page of the assistant. You can click Continue to move to the next set of settings. To change administrator privileges on each computer: 1 Select a computer list. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Change Client Settings. The client assistant appears. Click Continue. 4 Choose whether to start Remote Desktop sharing at system startup. This changes the setting found in the Sharing pane of System Preferences. 5 Choose whether to hide or show the Apple Remote Desktop menu bar icon. 6 Click Continue. 7 Choose whether to create a new user for Apple Remote Desktop login. Click Continue. New users can be used to grant Apple Remote Desktop administrator privileges. Creating a new user does not overwrite existing users or change existing user passwords. If you choose not to create a new user, skip to step 9 after clicking Continue.70 Chapter 5 Understanding and Controlling Access Privileges 8 Add a new user by clicking Add and filling in the appropriate information. Click OK after adding each user, and click Continue when you’re ready to go on. 9 Choose whether to assign Apple Remote Desktop administrator access privileges to Directory Services groups. If you choose to do so, select “Enable directory-based administration.” See “Apple Remote Desktop Administrator Access Using Directory Services” on page 62 for more information on using this method to grant Apple Remote Desktop administrator access. 10 Choose whether to assign Apple Remote Desktop administrator access privileges to specific users. Click Continue. If you choose not to assign administrator access privileges, skip to step 13. 11 Click Add to designate a user to receive Apple Remote Desktop access privileges. 12 Provide the user’s short name and assign the privileges as desired. See “Apple Remote Desktop Administrator Access” on page 59 for more information. Click OK after each user, and click Continue when you’re ready to go on. 13 Choose whether to allow temporary guest control by requesting permission on the client computers. 14 Choose whether to allow non-Apple VNC viewers to control the client computers, and click Continue. See “Virtual Network Computing Access” on page 67 for more information. 15 If desired, select and enter information in any or all of the four System Data fields. This information appears in Apple Remote Desktop System Overview reports. For example, you can enter an inventory number for the computer, a serial number, or a user’s name and telephone number. 16 Click Continue to review the clients’ settings. 17 Choose whether to execute the change using the application or a dedicated task server. 18 Click Change to change the clients’ settings The client configuration assistant contacts all of the selected computers and changes their administration settings.6 71 6 Setting Up the Network and Maintaining Security This chapter describes the main aspects of setting up your network for use with Apple Remote Desktop system administration, as well as best-practice tips for your network. Additionally, it contains information about Apple Remote Desktop security features, and detailed instructions for enabling them. You can learn about:  “Setting Up the Network” on page 71  “Using Apple Remote Desktop with Computers in an AirPort Wireless Network” on page 72  “Getting the Best Performance” on page 73  “Maintaining Security” on page 73 Setting Up the Network Your network configuration determines Apple Remote Desktop’s performance and usability. AirPort and AirPort Extreme networks offer slower performance than almost any Ethernet network. Therefore, file copying, client monitoring, and reporting are slower over AirPort and AirPort Extreme connections. Network routers and firewalls also shape, direct, or block network traffic; these things can have an effect on Apple Remote Desktop’s reliability and efficiency. Here are a few guidelines to keep in mind when setting up Apple Remote Desktop on your network:  The more AirPort clients connected to a base station, the lower the bandwidth for each computer. AirPort Base Stations are not considered “switched networks.”  Local Hostname (name using Apple’s Bonjour technology, that looks like: name.local) browsing does not extend beyond the local subnet. Local Hostnames do not resolve across routers like domain names do.  Networks with switches have fewer collisions and packet errors than networks with hubs. This means greater reliability and speed. Consider using switches instead of hubs.72 Chapter 6 Setting Up the Network and Maintaining Security  Organize computers you’re administering using Apple Remote Desktop into small groups, and close the Remote Desktop administrator application when not in use. This helps reduce the number of status queries, thus reducing network traffic.  If a client has a slow network type, consider running it in a list separate from the faster clients. A single slow client can slow down network operations.  If network traffic passes through firewalls, make sure you have a large Maximum Transmission Unit (MTU) setting (1200 or greater). Too small an MTU setting can result in black screens when sharing or sending screens.  If you are using a wide-area network (WAN), or metropolitan area network (MAN), make sure that the defrag bit is turned off in your router so packets don’t get chunked up. This can result in black screens when sharing or sending screens.  Network Address Translation (NAT) networks (such as those that use the Mac OS X Internet Sharing feature) can pose configuration and access difficulties. If you want to use Remote Desktop from behind a NAT router to access computers beyond the NAT router, you need to set TCP and UDP port forwarding for ports 3283 and 5900 to your administrator computer. Similarly, if you wish to access a single client computer that is behind a NAT router, you need to set the router to forward TCP and UDP ports 3283 and 5900 to the client computer you wish to access. Using Apple Remote Desktop with Computers in an AirPort Wireless Network Using Apple Remote Desktop to observe or control client computers connected using AirPort wireless technology can sometimes result in impaired performance or cause communication errors to appear in the Computer Status window. To get the best performance from Apple Remote Desktop with computers in an AirPort wireless network:  Make sure that all AirPort Base Stations and all Apple Remote Desktop client computers have the latest versions of Apple Remote Desktop software, AirPort software, and Mac OS X software installed.  Limit the number of clients that connect to an AirPort Base Station. AirPort clients on a base station receive all network communication packets sent to any one client on that base station. Although clients ignore packets that aren’t addressed to them, CPU resources are used to identify and discard the packet.  Scale the Control and Observe window. Apple Remote Desktop has server-side scaling that will allow for less traffic across the network as you scale the window to smaller sizes.  Try not to use tasks that multicast traffic such as Share Screen and File Copy. File Copy tries to initiate a series of individual copies if there is a significant number of multicast networking errors.Chapter 6 Setting Up the Network and Maintaining Security 73  Wireless networks also are not suited for multicast traffic. However Apple Remote Desktop’s multi-observe feature is different because it doesn’t use multicast traffic.  Display shared screens in black and white rather than in color.  Configure your AirPort Base Station with a station density of High and increase the multicast rate to 11 Mbps using AirPort Admin Utility. Using the base station density and multicast rate settings limits the range of each AirPort Base Station’s network, requiring client computers to be fewer than 50 meters from a base station. Getting the Best Performance To get the best performance when using the Share Screen, Observe, and Control commands:  Use the fastest network possible. This means favoring Ethernet over AirPort, 1000Base-T over 100Base-T, and 100Base-T over 10Base-T.  If you’re using AirPort, adjust the multicast speed higher.  Don’t mix network speeds if possible.  Reduce the use of animation on remote computers. For example, you can simplify Dock preference settings by turning off animation, automatic hiding and showing, and magnification effects.  View the client’s screen in a smaller window when using the “fit to window” option.  View the client’s screen with fewer colors.  Use a solid color for the desktop of the screen you’re sharing.  Share screens only on local networks. If you share a screen with a computer connected across a router, screen updates happen more slowly.  Set the Control and Observe image quality to the lowest acceptable for the given circumstance. Maintaining Security Remote Desktop can be a powerful tool for teaching, demonstrating, and performing maintenance tasks. For convenience, the administrator name and password used to access Remote Desktop can be stored in a keychain or can be required to be typed each time you open the application. However, the administrator name and password for each client computer are stored in the administrator’s preferences and are strongly encrypted.74 Chapter 6 Setting Up the Network and Maintaining Security Administrator Application Security  Make use of user mode to limit what nonadministrator users can do with Remote Desktop. See “Apple Remote Desktop Nonadministrator Access” on page 66.  If you leave the Remote Desktop password in your keychain, be sure to lock your keychain when you are not at your administrator computer.  Consider limiting user accounts to prevent the use of Remote Desktop. Either in a Managed Client for Mac OS X (MCX) environment, or using the Accounts pane in System Preferences, you can make sure only the users you designate can use Remote Desktop.  Check to see if the administrator computer is currently being observed or controlled before launching Remote Desktop (and stop it if it is). Remote Desktop prevents users from controlling a client with a copy of Remote Desktop already running on it at connection time, but does not disconnect existing observe or control sessions to the administrator computer when being launched. Although this functionality is helpful if you want to interact with a remote LAN which is behind a NAT gateway, it is possible to exploit this feature to get secretly get information about the administrator, administrator’s computer, and its associated client computers. User Privileges and Permissions Security  To disable or limit an administrator’s access to an Apple Remote Desktop client, open System Preferences on the client computer and make changes to settings in the Remote Desktop pane in the Sharing pane of System Preferences. The changes take effect after the current Apple Remote Desktop session with the client computer ends.  Remember that Apple Remote Desktop keeps working on client computers as long as the session remains open, even if the password used to administer the computer is changed.  Don’t use a user name for an Apple Remote Desktop access name and password. Make “dummy” accounts specifically for Apple Remote Desktop password access and limit their GUI and remote login privileges. Password Access Security  Never give the Remote Desktop password to anyone.  Never give the administrator name or password to anyone.  Use cryptographically sound passwords (no words found in a dictionary; eight characters or more, including letters, numbers and punctuation with no repeating patterns).  Regularly test your password files against dictionary attack to find weak passwords.Chapter 6 Setting Up the Network and Maintaining Security 75  Quit the Remote Desktop application when you have finished using it. If you have not stored the Remote Desktop password in your keychain, the application prompts you to enter the administrator name and password when you open it again. Physical Access Security  If you have stored the Remote Desktop password in your keychain, make sure the keychain is secured and the application isn’t running while you are away from the Remote Desktop window.  If you want to leave the Remote Desktop application open but need to be away from the computer, use a password-protected screen saver and select a hot corner so you can instantly activate the screen saver. Remote Desktop Authentication and Data Transport Encryption Authentication to Apple Remote Desktop clients uses an authentication method based on a Diffie-Hellman Key agreement protocol that creates a shared 128-bit key. This shared key is used to encrypt both the name and password using the Advanced Encryption Standard (AES). The Diffie-Hellman key agreement protocol used in Remote Desktop 3 is very similar to the one used in personal file sharing, with both of them using a 512-bit prime for the shared key calculation. With Remote Desktop 3, keystrokes and mouse events are encrypted when you control Mac OS X client computers. Additionally, all tasks except Control and Observe screen data, and files copied via Copy Items and Install Packages are encrypted for transit (though you may choose to encrypt these as well by changing your application preferences). This information is encrypted using the Advanced Encryption Standard (AES) with the 128-bit shared key that was derived during authentication. Encrypting Observe and Control Network Data Although Remote Desktop sends authentication information, keystrokes, and management commands encrypted by default, you may want additional security. You can choose to encrypt all Observe and Control traffic, at a certain performance cost. Encryption is done using an SSH tunnel between the participating computers. In order to use encryption for Observe and Control tasks, the target computers must have SSH enabled (“Remote Login” in the computer’s Sharing Preference pane). Additionally, firewalls between the participating computers must be configured to pass traffic on TCP port 22 (SSH well known port). If the you are trying to control a VNC server which is not Remote Desktop, it will not support Remote Desktop keystroke encryption. If you try to control that VNC server, you will get a warning that the keystrokes aren’t encrypted which you will have to acknowledge before you can control the VNC server. If you chose to encrypt all network data, then you will not be able to control the VNC server because Remote Desktop is not able to open the necessary SSH tunnel to the VNC server. 76 Chapter 6 Setting Up the Network and Maintaining Security To enable Observe and Control transport encryption: 1 Choose Remote Desktop > Preferences. 2 Click the Security button. 3 In the “Controlling computers” section, select “Encrypt all network data.” Encrypting Network Data During Copy Items and Install Packages Tasks Remote Desktop can send files for Copy Items and Install Packages via encrypted transport. This option is not enabled by default, and you must either enable it explicitly for each copy task, or in a global setting in Remote Desktop’s preferences. Even installer package files can be intercepted if not encrypted. To encrypt individual file copying and package installation tasks: m In the Copy Items task or Install Packages task configuration window, select “Encrypt network data.” To set a default encryption preference for file copies: 1 In the Remote Desktop Preferences window, select the Security pane. 2 Check “Encrypt transfers when using Copy Items,” or “Encrypt transfers when using Install Packages” as desired. Alternatively, you could encrypt a file archive before copying it. The encrypted archive could be intercepted, but it would be unreadable.7 77 7 Interacting with Users Apple Remote Desktop is a powerful tool for interacting with computer users across a network. You can interact by controlling or observing remote screens, text messaging with remote users, or sharing your screen with others. This chapter describes Remote Desktop’s user interaction capabilities and gives complete instructions for using them. You can learn about:  “Controlling” on page 78  “Observing” on page 85  “Sending Messages” on page 92  “Sharing Screens” on page 93  “Interacting with Your Apple Remote Desktop Administrator” on page 9478 Chapter 7 Interacting with Users Controlling Apple Remote Desktop allows you to control remote computers as if you were sitting in front of them. You can only control the keyboard and mouse of any one computer at a time. There are two kinds of remote computers that Apple Remote Desktop can control: Apple Remote Desktop clients and Virtual Network Computing (VNC) servers. Controlling Apple Remote Desktop Clients Apple Remote Desktop client computers can be controlled by any administrator computer that has the Control permission set. See “Apple Remote Desktop Administrator Access” on page 59 for more information about Apple Remote Desktop permissions. While you control an Apple Remote Desktop client computer, some keyboard shortcut commands are not sent to the remote computer, but they affect the administrator computer. These include:  Change Active Application (Command-Tab and Command-Shift-Tab)  Show or Hide Dock (Command-Option-D)  Log Out User (Command-Shift-Q)  Take Screen Shot (Command-Shift-3, -4)  Force Quit (Command-Option-Escape)Chapter 7 Interacting with Users 79 Also, special keys including the sound volume, screen brightness, and Media Eject keys do not affect the client computer. These instructions assume the that observed computer has Apple Remote Desktop installed and configured properly (see “Setting Up an Apple Remote Desktop Client Computer for the First Time” on page 41) and that the computer has been added to an Apple Remote Desktop computer list (see “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49). To control an Apple Remote Desktop client: 1 Select a computer list in the Remote Desktop window. 2 Select one computer from the list. 3 Choose Interact > Control. 4 To customize the control window and session, see “Control Window Options” on page 79. 5 Use your mouse and keyboard to perform actions on the controlled computer. If your Remote Desktop preferences are set to share keyboard and mouse control, the remote computer’s keyboard and mouse are active and affect the computer just as the administrator computer’s keyboard and mouse do. If your preferences aren’t set to share control, the remote computer’s keyboard and mouse do not function while the administrator computer is in control. Control Window Options When controlling a client, the control window contains several buttons in the window title bar which you can use to customize your remote control experience. There are toggle buttons that switch your control session between two different states, and there are action buttons that perform a single task. In addition to the buttons, there is a slider for image quality. The toggle buttons are:  Control mode or Observe mode  Share mouse control with user  Fit screen in window  Lock computer screen while you control  Fit screen to full display The action buttons are:  Capture screen to a file  Get the remote clipboard contents  Send clipboard contents to the remote clipboard80 Chapter 7 Interacting with Users Switching the Control Window Between Full Size And Fit-To-Window When controlling a client, you can see the client window at full size, or scaled to fit the control window. Viewing the client window at full size will show the client screen at its real pixel resolution. If the controlled computer’s screen is larger than your control window, the screen show scroll bars at the edge of the window. To switch in-a-window control between full size and fit-to-window modes: 1 Control a client computer. 2 Click the Fit Screen In Window button in the control window toolbar. Switching Between Control and Observe Modes Each control session can be switched to a single-client observe session, in which the controlled computer no longer takes mouse and keyboard input from the administrator computer. This allows you to easily give control over to a user at the client computer keyboard, or place the screen under observation without accidentally affecting the client computer. See “Observing a Single Computer” on page 90 for more information on Apple Remote Desktop observe mode. To switch between control and observe modes: 1 Control a client computer. 2 Click the Control/Observe toggle button in the control window toolbar. Sharing Control with a User You can either take complete mouse and keyboard control or share control with an Apple Remote Desktop client user. This allows you to have more control over the client interaction as well as prevents possible client side interference. This button has no effect while controlling VNC servers. See “Controlling VNC Servers” on page 82 for more information. To switch between complete control and shared mouse modes: 1 Control a client computer. 2 Click the “Share mouse and keyboard control” button in the control window toolbar.Chapter 7 Interacting with Users 81 Hiding a User’s Screen While Controlling Sometimes you may want to control a client computer with a user at the client computer, but you don’t want the user to see what you’re doing. In such a case, you can disable the client computer’s screen while preserving your own view of the client computer. This is a special control mode referred to as “curtain mode.” You can change what’s “behind the curtain” and reveal it when the mode is toggled back to the standard control mode. To switch between standard control and curtain modes: 1 Control a client computer. 2 Click the “Lock computer screen while you control” button in the control window toolbar. Capturing the Control Window to a File You can take a picture of the remote screen, and save it to a file. The file is saved to the administrator computer, and is the same resolution and color depth as the controlled screen in the window. To screen capture a controlled client’s screen: 1 Control a client computer. 2 Click the “Capture screen to a file” button in the control window toolbar. 3 Name the new file. 4 Click Save. Switching Control Session Between Full Screen and In a Window You can control a computer either in a window, or using the entire administrator computer screen. The “Fit screen to full display” toggle button changes between these two modes. In full screen mode, the client computer screen is scaled up to completely fill the administrator screen. In addition to the client screen, there are a number of Apple Remote Desktop controls still visible overlaying the client screen. In in-a-window mode, you can switch between fitting the client screen in the window or showing it actual size, possibly scrolling around the window to see the entire client screen. See “Switching the Control Window Between Full Size And Fit-To-Window” on page 80 for more information. To switch between full screen and in-a-window modes: 1 Control a client computer. 2 Click the “Fit screen to full display” button in the control window toolbar.82 Chapter 7 Interacting with Users Sharing Clipboards for Copy and Paste You can transfer data between the Clipboards of the administrator and client computer. For example, you may want to copy some text from a file on the administrator computer and paste it into a document open on the client computer. Similarly, you could copy a link from the client computer’s web browser and paste it into the web browser on the administrator computer. The keyboard shortcuts for Copy, Cut, and Paste are always passed through to the client computer. To share clipboard content with the client: 1 Control a client computer. 2 Click the “Get the remote clipboard contents” button in the control window toolbar to get the client’s Clipboard content. 3 Click the “Send clipboard contents to the remote clipboard” button in the control window toolbar to send content to the client’s Clipboard. Controlling VNC Servers Virtual Network Computing (VNC) is remote control software. It allows a user at one computer (using a “viewer”) to view the desktop and control the keyboard and mouse of another computer (using a VNC “server”) connected over the network. For the purposes of these instructions, VNC-enabled computers are referred to as “VNC clients.” VNC servers and viewers are available for a variety of computing platforms. Remote Desktop is a VNC viewer and can therefore control any computer on the network (whether that computer is running Mac OS X, Linux, or Windows) that is:  Running the VNC server software  In an Apple Remote Desktop computer list If the you are trying to control a VNC server which is not Remote Desktop, it will not support Remote Desktop keystroke encryption. If you try to control that VNC server, you will get a warning that the keystrokes aren’t encrypted which you will have to acknowledge before you can control the VNC server. If you chose to encrypt all network data, then you will not be able to control the VNC server because Remote Desktop is not able to open the necessary SSH tunnel to the VNC server. For more information, see “Encrypting Observe and Control Network Data” on page 75. These instructions assume the observed computer has been added to an Apple Remote Desktop computer list (see “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49). When adding a VNC server to an Apple Remote Desktop computer list, you only need to provide the VNC password, with no user name. To control a VNC client computer: 1 Select a computer list in the Remote Desktop window.Chapter 7 Interacting with Users 83 2 Select one computer from the list. 3 Choose Interact > Control. If the controlled computer’s screen is larger than your control window, the screen scrolls as the pointer approaches the edge of the window. 4 To customize the control window and session, see “Control Window Options” on page 79. 5 Use your mouse and keyboard to perform actions on the controlled computer. Regardless of your Apple Remote Desktop preferences, controlled VNC servers share keyboard and mouse control. The remote computer’s keyboard and mouse are active and affect the computer just as the administrator computer’s keyboard and mouse do. Setting up a Non–Mac OS X VNC Server This section contains very basic, high-level steps for setting up a non–Mac OS X client to be viewed with Remote Desktop. This section cannot give detailed instructions, since the client operating system, VNC software, and firewall will be different. The basic steps are: 1 Install VNC Server software on the client computer (for example, a PC, or a Linux computer). 2 Assign a VNC password on the client computer. 3 Make sure the client’s firewall has the VNC port open (TCP 5900). 4 Make sure “Encrypt all network data” is not selected in the Security section of the Remote Desktop Preferences. 5 Add the computer to the Remote Desktop’s All Computers list using the client’s IP address. 6 Put the client computer’s VNC password in the Remote Desktop authentication box. There is no user name for a VNC server, just a password. Apple Remote Desktop Control and the PC’s Ctrl-Alt-Del If you use Remote Desktop to administer a PC that’s running VNC, you may be wondering how to send the Ctrl-Alt-Del command (Control-Alternate-Delete) from a Mac to the PC. Though Mac and PC key mappings differ, you can use an alternate key combination to send the command.  For full-size (desktop) keyboards, use Control-Option-Forward Delete.  For abbreviated keyboards (on portable computers), use Function-Control-OptionCommand-Delete.84 Chapter 7 Interacting with Users VNC Control Options After you have added a VNC server to a computer list (or when you are first adding it), you can set a custom port for VNC communication, and you can designate a display to control. To set a custom port on an existing computer list member: 1 Select a computer list in the Remote Desktop window. 2 Select a VNC Server computer in the Remote Desktop window. 3 Choose File > Get Info. 4 Click Edit in the Info window. 5 At the end of the IP Address or fully qualified domain name, add a colon followed by the desired port. For example, if you want to connect to a VNC server (vncserver.example.com) that is listening on TCP port 15900, you would enter: vncserver.example.com:15900 6 Click Done. To set a custom VNC port when adding a computer by address: 1 Choose File > Add By Address. 2 Enter the IP address or fully qualified domain name. 3 At the end of the IP Address or fully qualified domain name, add a colon followed by the desired port. For example, if you want to connect to a VNC server (vncserver.example.com) that is listening on TCP port 15900, you would enter: vncserver.example.com:15900 4 Enter the user name and password. 5 Click Add. To designate a display to control: 1 Add a custom port number, as described above. 2 Use the display number for the last number in the custom port designation (display designations start at 0 for the default primary display). For example, f you want to control the default display on a VNC server (vncserver.example.com) that is listening on TCP port 5900, you would enter: vncserver.example.com:5900 If you want to control the second display, you would enter: vncserver.example.com:5901Chapter 7 Interacting with Users 85 If you want to control the third display, you would enter: vncserver.example.com:5902 Configuring an Apple Remote Desktop Client to be Controlled by a VNC Viewer When configured to do so, an Apple Remote Desktop client can be controlled with a non–Apple VNC viewer. Allowing a non–Apple VNC viewer access to an Apple Remote Desktop client is less secure than using Remote Desktop to control the client. The non–Apple VNC software expects the password to be stored in a cryptographically unsecured form and location. To configure a client to accept VNC connections: 1 On the client computer, open System Preferences. 2 Click Sharing, select Apple Remote Desktop, then click Access Privileges. 3 Select “VNC viewers may control screen with the password.” 4 Enter a VNC password. 5 Click OK. Observing You may not want to control a computer, but merely monitor what is on its screen. Observing a remote computer is similar to controlling one, except your mouse movements and keyboard input are not sent to the remote computer. Apple Remote Desktop client computers can be observed on any administrator computer that has the “Observe” permission set. See “Apple Remote Desktop Administrator Access” on page 59 for more information about Apple Remote Desktop permissions. Warning: Do not use the same password as any user or Apple Remote Desktop administrator. The password may not be secure.86 Chapter 7 Interacting with Users Remote Desktop allows you to observe multiple clients on the same screen, cycling through the list of observed computers. This allows you to monitor many screens without having to select each one individually. Dealing With Many Client Screens When observing a single client, you can see the client window at full size, or scaled it to fit the observe window. To switch between the full size and fitting to the window, click the Fit to Window button, just as you would in a control window. If you’re observing more clients than you’ve chosen to fit on one screen, you can cycle through multiple pages by clicking the Previous or Next button. Cycle Pages: Use these buttons to manually switch to the previous or next page of screens. Getting More Information on Observed Clients There is a computer information area beneath each of the observed desktops. It’s automatically disabled when the administrator is viewing more computers than the computer information area is able to show effectively (a threshhold of about 220 pixels across). This could happen if:  the initial selection of computers is too great for the window sizeChapter 7 Interacting with Users 87  the observe window is resized, shrinking the information beneath the threshold  the setting for the number of viewed machines is changed The computer information area is reenabled when the sizes are returned to more than the image size threshhold. Changing Observe Settings While Observing While you are observing multiple computers, you can adjust the Apple Remote Desktop observe settings using the controls at the top of the observe window. These settings will be visible after clicking View Options in the toolbar. To change your observe settings:  Page Delay: Adjust the number of seconds before automatically advancing to the next page of screens.  Computers per page: Adjust the number of client screens visible on each page.  Image Quality: Adjust the screen color depth from black and white to millions of colors.  Titles: Change the titles of the displayed screens in the computer information area.  Account Picture: Add the currently logged-in user’s account picture under each observed desktop. See “Viewing a User’s Account Picture While Observing” on page 88 for more information.  Computer Status: Add a status overview icon underneath the observed desktop. See “Viewing a Computer’s System Status While at the Observe Window” on page 88 for more information.88 Chapter 7 Interacting with Users Changing Screen Titles While Observing While you are observing multiple computers, you can change the title underneath the desktops shown in the observe window. The main title can be the:  Name (the computer sharing name)  IP Address  Host Name To change your observe window titles: 1 Click View Options in the observe window’s toolbar. 2 Select Display Computer Information. 3 From the Title pop-up menu, select the desired title. 4 Click Done. Viewing a User’s Account Picture While Observing Remote Desktop can display the user’s account picture and a user-created status underneath the observed desktop. The user’s account picture is their system login icon, so it might be either a picture taken from an iSight camera, or a custom image selected in the Accounts pane of System Preferences. To view a user’s account picture: 1 Click View Options in the observe window’s toolbar. 2 Select Display Computer Information. 3 Select Account Picture. 4 Click Done. Viewing a Computer’s System Status While at the Observe Window Remote Desktop can display certain system status information underneath the observed desktop. This information gives you a basic assessment of the following service statistics:  CPU Usage  Disk Usage  Free MemoryChapter 7 Interacting with Users 89 There are two levels of detail for system statistics. The top level is a single icon (a red, yellow, or green icon). You show the second level of detail by placing the mouse pointer over the high-level status icon. The icon changes to an “i” and you can click the “i” to get more information. Clicking the icon exposes per-service status icons: Icon Indicates or One or more service statistic is red. This takes precedence over any yellow or green indicator. or One or more service statistic is yellow This takes precedence over any green indicator. Service is operating within established parameters. No service informaiton available. Service Icon Status CPU Usage Usage is at 60% or less Usage is between 60% to 85% Usage is at 85% or higher No status information is available DIsk Usage Usage is at 90% or less Usage is between 90% and 95% Usage is at 95% or higher No status information is available Free Memory Less than 80% used Between 80% and 95% used90 Chapter 7 Interacting with Users To show system status in the observe window: 1 Click View Options in the observe window’s toolbar. 2 Select Display Computer Information. 3 Select Computer Status. 4 Click Done. Shortcuts in the Multiple Screen Observe Window You can access several Apple Remote Desktop commands using icons in the observe window. You can customize the observe window with the commands that are most useful to you. For example, you may want to access the Copy Items command, the Text Chat command, and the Lock Screen command, using the buttons in the observe window toolbar. You perform Remote Desktop tasks on any computer by selecting its screen and choosing a task from the Remote Desktop menus or the observe window toolbar. Regardless of your toolbar customizations, you’ll be able to advance through pages manually, change the titling of the observed screens, change the number of client screens per page, change the number of seconds before paging, or change the color depth of the observed screens. Observing a Single Computer When you observe a single computer, the observed screen appears in a window on your administrator computer. If a screen saver is active when you observe the screen, the screen saver remains in effect. The observe window contains a “Share mouse control” button to switch to controlling the screen. To observe a single computer: 1 Select a computer list in the Remote Desktop window. 2 Select a computer in the Remote Desktop window. 3 Choose Interact > Observe. If the observed computer’s screen is larger than the observe window, the screen will scroll as the pointer approaches the edge of the window. 4 To customize the single-client observe window and session, see “Control Window Options” on page 79. The observe window’s options are the same as those of the control window. Over 95% used No status information available Service Icon StatusChapter 7 Interacting with Users 91 Observing Multiple Computers When you observe multiple client computers, each client screen is scaled down, so that several computers can be viewed at the same time. You can set the number of client screens that appear at any one time. See “Setting Preferences for the Remote Desktop Administrator Application” on page 36 for more information. If a client has a screen saver running when you start observing, the screen saver remains in effect. The screens will cycle through the entire list of selected computers, a few at a time, switching every 30 seconds, altered by the speed setting. To observe multiple computers: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Interact > Observe. The remote computer screens appear in a window. Observing a Computer in Dashboard If you are using Mac OS X version 10.4 or later, you can use the Dashboard widget to observe one client computer. The computer must be in your All Computers list and be authenticated with permission to Observe. Apple Remote Desktop does not have to be launched to use the widget. To observe using Dashboard: 1 Add the computer to your All Computers list. See “Finding and Adding Clients to Apple Remote Desktop Computer Lists” on page 49 for detailed information. 2 Activate Dashboard, and click the widget’s icon to run it. 3 Click the widget’s “Info” button to flip the widget over. 4 Supply a hostname or IP address, login name, and password or simply select the computer you want to observe (if it’s listed). 5 Click Done.92 Chapter 7 Interacting with Users Sending Messages Apple Remote Desktop allows you to communicate with users of Apple Remote Desktop client computers using text messaging. You can use text messages to give instructions or announcements, to collaborate remotely, or troubleshoot with users. There are two types of text messaging: one-way messages and two-way interactive chat. Text messages and chat are available only to Apple Remote Desktop client computers; they are not available to VNC client computers. Sending One-Way Messages You can use a one-way text message to send announcements or information to users client computers. The announcements appear in front of open application windows and can be dismissed by the user. To send a one-way text message: 1 Select a computer list in the Remote Desktop window. 2 Select one computer from the list. 3 Choose Interact > Send Message. 4 Enter your message. 5 Click Send. The text message appears on the screen of all the selected computers. Interactive Chat You can start an interactive text chat with the user of an Apple Remote Desktop client computer. This allows instant feedback from users, so you can collaborate or troubleshoot. To begin an interactive chat: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Interact > Chat. 4 Enter your message, one line at a time. The message appears real-time on the user’s screen as you type.Chapter 7 Interacting with Users 93 5 Press the Return key to complete and send each line. Viewing Attention Requests After a client user sends an attention request, the Apple Remote Desktop administrator can read the attention request text. To view attention requests: 1 Choose Window > Messages From Users. 2 Select the message you want to view. 3 Click Display to view the request’s message. Sharing Screens Apple Remote Desktop allows you to show your screen (or the screen of a client computer in your list) to any or all Apple Remote Desktop client computers in the same computer list. You can, for example, show a presentation to a classroom of computers from a single computer. Sharing a Screen with Client Computers You can share a client computer’s screen, or the administrator’s screen, with any number of clients. The client screen displays what is on the shared screen, but cannot control it in any way. To share a computer’s screen: 1 Select a computer list in the Remote Desktop window. 2 Select on or more computers in the selected computer list. These computers include the target computers and the source computer. 3 Choose Interact > Share Screen. 4 Select the screen to be shared. If you want to share the Apple Remote Desktop administrator screen, select “Share your screen.” If you want to share a client screen, select “Share a different screen,” and drag a computer from an Apple Remote Desktop computer list to the dialog. 5 Click Share Screen. The selected computer shows the shared computer screen. If the target computer’s screen resolution is lower than the shared computer’s, only the top left part of the shared screen (up to the lowest screen resolution) is seen on the target screen.94 Chapter 7 Interacting with Users Monitoring a Screen Sharing Tasks You may want to keep track of the screen sharing tasks you have begun. You can get information on all active screen sharing tasks, and can sort the tasks by time started, source screen, or target computers. To view current active screen sharing tasks: m Choose Window > Active Share Screen Tasks. Interacting with Your Apple Remote Desktop Administrator Users of Apple Remote Desktop client computers can initiate contact with a Remote Desktop administrator. Clients can ask for attention from the administrator, or cancel that attention request. Additionally, users of Apple Remote Desktop client computers can set an identifying icon for a Remote Desktop administrator to view. The Remote Desktop administrator can choose whether to view the icon or not. Requesting Administrator Attention At times, Apple Remote Desktop client computer users need to get the attention of the Apple Remote Desktop administrator. If an Apple Remote Desktop administrator is currently monitoring the client computer, the client user can send an attention request. To request administrator attention: 1 Click the Apple Remote Desktop status icon and choose Message to Administrator. The attention request window appears. 2 If the network has more than one Apple Remote Desktop administrator available, choose an administrator from the “Send message to” pop-up menu. 3 Enter the message. 4 Click Send. The attention request icon appears on the administrator’s screen.Chapter 7 Interacting with Users 95 Canceling an Attention Request If a user no longer needs the Apple Remote Desktop administrator’s attention, he or she can cancel the attention request after it has been sent. To cancel an attention request: 1 Click the Apple Remote Desktop status icon and choose Message to Administrator. 2 Click the Apple Remote Desktop status icon in the menu bar and choose Cancel Message. Changing Your Observed Client Icon By default, the icon that the Remote Desktop administrator sees while observing is the login icon for the currently logged-in user. If you had an iSight camera active when setting up your computer, you may have taken a picture of yourself for your user icon. You can change this icon, and it will change on the administrator’s observation screen. To change your login icon: 1 Prepare the picture you want to use. You could use a graphic file, or take a picture using an iSight camera. 2 Open System Preferences. The System Preferences application launches. 3 Select the Accounts pane. 4 Select your account, and choose the Picture button. 5 Replace your current account picture with the new picture. 6 Close System Preferences.8 96 8 Administering Client Computers Apple Remote Desktop gives you powerful administrative control. You can manually or automatically get detailed information about every computer, install software, and maintain systems from a single administrator computer. This chapter describes Remote Desktop’s capabilities and gives complete instructions for using them. You can learn about:  “Keeping Track of Task Progress and History” on page 96  “Installing Software Using Apple Remote Desktop” on page 101  “Upgrading Software” on page 105  “Copying Files” on page 106  “Creating Reports” on page 111  “Maintaining Systems” on page 127  “Managing Computers” on page 135  “UNIX Shell Commands” on page 143  “Automating Functions” on page 152 Keeping Track of Task Progress and History The task history area is on the left side of the Remote Desktop window (see “Remote Desktop Main Window” on page 29) with all computer lists and scanners. Every time you execute a task (generating a report, copying a file, restarting a computer), the task name, affected computers, task result, and time you execute it is stored in the Task History window (accessible via Window > Task History). The Task History list, in the main Remote Desktop window, shows the task name and result. You can collapse the Task History list to reduce its size. You can select a task in the Task History list to see some information about it, and double-click it to view a more detailed description of the task, as well as the computers involved with it. Tasks in progress appear in the Active Tasks list, where you can stop and restart them.Chapter 8 Administering Client Computers 97 Remote Desktop keeps track of three kinds of task progress: active, Task Server, and completed. Active tasks are those which are currently being processed by the client computers, and the client computers have not all reported back to the administrator console. Some tasks are so short that they only briefly appear in the list of current tasks; other tasks may take a long time and remain there long enough to return to the task and view the progress as it happens. The Active Tasks list is located in the left side of the Remote Desktop window, and has a disclosure triangle to expand or hide the list. Task Server tasks are those which have been assigned to the task server (either the one running on the administrator’s computer, or a remote one) which have not yet completed for all the task participants. Completed tasks are those which have received a task status for all participating client computers. The task description and computer list then moves to the task history list. The task history list is located in the left side of the Remote Desktop window, and has a disclosure triangle for expanding or hiding the list. In addition to the task status and notification features of Remote Desktop, you can set a task notification shell script to run when any task has completed. This script is for all tasks, but it can be as complex as your needs require. Enabling a Task Notification Script When a task completes, Remote Desktop can run a script that you create. This script is for all completed tasks, and it must be a shell script. There is a default notification script provided, which you can customize for your needs. The script must be a shell script, but you can use various other scripting environments like AppleScripts with the osascript command. To enable a task notification script: 1 Make sure you are logged in as an administrator user. 2 Open Remote Desktop. 3 Choose Remote Desktop > Preferences. 4 Click the Tasks button. 5 Select “Enable task notification script.” 6 Choose the location of the script. The default notification script is located at /Library/Application Support/Apple/Remote Desktop/Notify. 7 Close the Preferences window.98 Chapter 8 Administering Client Computers Getting Active Task Status When you get a task’s current status, you see the progress of the task, the computers involved, and their feedback to the administrator computer. To get status on a currently running task: 1 Select the Active Tasks list. 2 Select the desired task in the Remote Desktop window. The task status and computers involved are shown in the Remote Desktop window. You can make sure the main window always shows the currently running task in the main work area by setting a preference. Otherwise, the main window will continue to show the last selected computer list. To automatically show task status in the main window: 1 Make sure you are logged in as an administrator user. 2 Open Remote Desktop. 3 Choose Remote Desktop > Preferences. 4 Click the Tasks button. 5 Select “Always change focus to active task.” 6 Close the Preference’s window. Using the Task Feedback Display You can use the task feedback display to:  Retry a task on selected computers  Cancel a task in progress Tasks in progress appear in the Active Tasks list, where you can stop them, or run them again. To use the task feedback window: 1 Select the task in the task history list or active task list. 2 Change the task as desired: a Click the retry button to perform the task again. b Click the stop button to cancel the active task. Stopping a Currently Running Task If a task is in progress and Remote Desktop is still waiting for feedback from the client computers, you can stop the task. You use the Active Tasks list to stop the command in progress.Chapter 8 Administering Client Computers 99 To stop a currently running task: 1 Select the Active Tasks list. 2 Select the desired task in the Remote Desktop window. The task status and computers involved are shown in the Remote Desktop window. 3 Click the Stop button in the top-right of the main window. Getting Completed Task History After a task has received feedback from all the involved client computers, or they have experienced a communication time-out, the task is moved to the Task History list. The Task History list is located in the left side of the Remote Desktop window, and has a disclosure triangle to expand or hide the list. This list stays populated as long you’ve set in the Remote Desktop preferences. The Task History list can also be viewed in a separate window with the tasks sorted by date. To get status on a completed task: 1 Open the Task History list using the disclosure triangle. 2 Select the desired task in the Remote Desktop window. The final task status and computers involved are shown in the Remote Desktop window. or m Select Window > Task History. The final task status and computers involved are shown in a separate window. Saving a Task for Later Use You may want to save a task for later, repeated use. If you find yourself repeating certain tasks, you can save those tasks and the information about which computers go with them. Observe and Control tasks cannot be saved. Saved tasks appear in a list on the left side of the Remote Desktop main window. To save a task for later use: 1 Open the task you want to save. For example, if you want to save a Copy Items task, select Manage > Copy Items. 2 Configure the task as desired. 3 Before executing the task, click Save. 4 Name the saved task. The task appears in a list on the left side of the Remote Desktop main window.100 Chapter 8 Administering Client Computers Creating and Using Task Templates In each task configuration dialog, you can save a task’s settings to a template to reuse for future tasks of that same type. For example, if you always use certain copy options for a Copy Items task, you can save those settings as a template, and have them apply to any newly created Copy Items task. Once a task template is saved, you can select any one of the saved templates from the Templates pop-up menu. Selecting a template automatically configures the dialog box according to the saved template. If you want to perform a task similar to an existing template, you start with that template using the Template pop-up menu, then you customize the resulting task configuration dialog after applying the template. For example, if you always want to use the same Copy Items options, but you want vary the group of computers you apply it to, you create a task template by configuring the copy options dialog without selecting target computers and then saving it via the Templates pop-up menu. Then whenever you make a new Copy Items task with target computers selected, you can apply the saved settings by selecting those settings from out of the Templates pop-up menu and add your own settings afterward. You are free to make as many templates as you want either from existing templates or from scratch. Once saved, a template can be made the task’s default, with all new instances of the task opening with the default template settings. You can also edit the task template list from the Template pop-up list, removing a template, or making it the task default. There are existing, built-in templates for the Send UNIX Command task which can not be removed, see “Send UNIX Command Templates” on page 143 for more information. Note: Templates are only stored for their own task type. For example, Copy Items saved templates are not available for use with Rename Computer tasks, etc. To create a task template: 1 Open a task configuration window. You can use existing saved tasks, or a newly created task. 2 Configure the task as desired. 3 Click the Template pop-up menu, and select Save as Template. 4 Name the template, and click OK. To apply a task template: 1 Open a task configuration window. You can use existing saved tasks, or a newly created task. 2 Click the Template pop-up menu, and select the template you want. The settings in the template are now applied to the dialog window. 3 If desired, customize the task further.Chapter 8 Administering Client Computers 101 Editing a Saved Task You may want to change a previously saved task, changing whether what the task does or changing the target computers. To edit a saved task: 1 Double-click the saved task you want to edit. Alternatively, you could use Control-click or right-click and choose Edit Task from contextual menu. 2 In the task description window, change the task parameters. You can alter task preferences, and change the computer list. Remove computers by selecting them and pressing the Delete key; add computers by dragging them from a list to the task. After a task is completed, the task name, result, and time you last ran it are stored for review. The task feedback window gives a detailed account of the task, and reports success or failure for each participating client computer. To view the task feedback window: m Select the task in the Task History list. Installing Software Using Apple Remote Desktop There are several methods you can use to install software with Apple Remote Desktop. The following section describes how to install software using installer packages and metapackages, using the copy command in Remote Desktop, using installers made by other software companies, or using NetBoot or Network Install. Installing by Package and Metapackage You can install new software automatically and without user intervention by copying installer packages (.pkg or .mpkg files) to one or more remote clients. Apple Remote Desktop copies the package to the computers you choose, runs the installer with no visible window or user interaction required, and then erases the installer files on completion. Warning: Distributing copyrighted software without the appropriate license agreement is a violation of copyright law.102 Chapter 8 Administering Client Computers You can choose to initiate the installation of a package from the designated Task Server rather from a Remote Desktop task. This allows you to install packages on to computers that may not be connected to the network (with a status of “Offline”) when you run the task. The Task Server monitors the network for the next time the offline client comes online again. Then the Task Server performs the installation. For more information about designating a Task Server, see “Using a Task Server for Report Data Collection” on page 112 and “Designating the Task Server and Setting the Report Data Collection Location” on page 154. For detailed instructions about installing via the Task Server, see “Installing Software on Offline Computers” on page 103. You can install multiple packages in succession. When you execute installation of multiple packages, Remote Desktop copies over all the selected packages and then installs them. It also detects whether a restart is required and will give you a visual cue. You can tell the task to restart the computers upon completion, or restart the computers manually later. It is not possible to stop the installation of a package. Once the installation starts, it will complete (assuming no errors occur on the client). However, you can click the Stop button to stop remaining packages from being copied over and therefore halt the install. Alternatively, an administrator can use the PackageMaker application (available on the Apple Remote Desktop CD or with the Apple Developer Tools) to create a metapackage that contains several installers to be run in sequence. In addition to creating metapackages, you can also use PackageMaker to create packages for custom software that your organization may have developed. More information about making and using packages and metapackages is available on the Apple Developer Connection website: developer.apple.com To copy and install software using a .pkg file: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Install Packages. 4 Select a .pkg or .mpkg file to install. Alternatively, you can drag an installer package on to the package list window. 5 Select whether to restart the target computers after installation. 6 Select the option to run the task from “This application.” This option is preferable when installing on computers that are all currently online. If you want to install the software via a Task Server, see “Installing Software on Offline Computers” on page 103.Chapter 8 Administering Client Computers 103 7 Select other installation parameters, as desired. For more information on the available options, see “Copy Options” on page 107. Note: Client computers are not restarted automatically after an installation is complete unless explicitly selected in the task command. 8 Click Install. During installation, a progress bar appears in the task header in the main window. No progress bars appear on the client computer. The copied package is deleted from the client computer if an error occurs during installation. However, a failed installation may leave behind other files created by the installer. Installing Software on Offline Computers Using Apple Remote Desktop, you can install software on a computer that is not currently connected to the network (with a status of “Offline”). The installation does not occur when initially ordered, but when the offline computer next becomes available. The installation itself is handled by a designated Task Server. The Task Server will continue to monitor the network for the next time the offline client comes online again. For more detailed information about setting up and using a Task Server, see “Designating the Task Server and Setting the Report Data Collection Location” on page 154. To install software on offline clients: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. Any or all may be offline. 3 Choose Manage > Install Packages. 4 Select a .pkg or .mpkg file to install. Alternatively, you can drag an installer package into the Packages list. 5 Choose whether to run the task from the Task Server designated by Remote Desktop’s preferences. To set up or alter the Task Server, see “Using a Task Server for Report Data Collection” on page 112 and “Designating the Task Server and Setting the Report Data Collection Location” on page 154. 6 Select other installation parameters, as desired. For more information on the available options, see “Copy Options” on page 107 and “Installing by Package and Metapackage” on page 101. 7 Click Install.104 Chapter 8 Administering Client Computers Installing by Using the Copy Items Command Many applications can be installed simply by copying the application or its folder to the client computer. Consult the application’s documentation to verify that you can simply copy the application to the hard disk to install it. To install software by copying: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Copy Items. 4 Add software to the “Items to copy” list. For more information, see “Copying Files” on page 106. Repeat this step until all the software you want to copy is in the list. 5 Select a destination. There are several preset locations available in the “Place items in” pop-up menu, including the Applications folder. If you do not see the location you want, you can specify a full pathname. 6 Select your copy options. See “Copy Options” on page 107 for more information on the available options. 7 Click Copy. The software is copied to the indicated location. If the copy operation is unsuccessful, an error message appears in the task feedback window. Using Installers from Other Companies The Install Packages command only works with installers that use the .pkg or .mpkg file format, and some applications can’t be installed by simply copying the application to the hard disk. To install software using installers with different file formats, you use a combination of tasks. To install software with third-party installers: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Copy Items. 4 Add the software installer to the “Items to copy” list. For more information, see “Copying Files” on page 106. 5 Select a copy destination. 6 Select After Copying Open Items. 7 Click Copy.Chapter 8 Administering Client Computers 105 The software is copied to the indicated destination. If the copy is operation unsuccessful, an error message appears in the task feedback window. 8 Select a computer that received the copy of the installer. 9 Choose Interact > Control. 10 Control the screen of the selected computer and complete the installation process interactively. Upgrading Software Upgrading software is similar to installing software. However, the method of upgrading software depends on the original method of installation. As a general rule, upgrades should not be done while users have their applications open. Make sure the software to be upgraded is not running. Upgrading consists of three main tasks:  Finding out if a piece needs to be updated  Removing the old version  Installing the new version To upgrade software on client computers: 1 Run a Software Version report to determine what version of the software client computers have. See “Generating a Software Version Report” on page 118 to learn how to run the report. 2 Remove the old version of the software. If the software was originally installed using a package or metapackage, it should be removed automatically when you install the new version. If the software was originally installed using the Copy Items command, you can delete the old version, or simply replace the old version with the new version when you install the new version. If the software was originally installed using another company’s installer application, you may need to use an uninstaller before installing the new version. Consult the software’s manual for instructions on removing its software. If an uninstaller application is necessary, you can copy it to each of the client computers and run it remotely. Warning: Distributing copyrighted software without the appropriate license agreement is a violation of copyright law.106 Chapter 8 Administering Client Computers 3 Use the appropriate installation method to install the new version of the software. For more information, see:  “Installing by Package and Metapackage” on page 101  “Installing by Using the Copy Items Command” on page 104  “Using Installers from Other Companies” on page 104 Copying Files Apple Remote Desktop makes it easy to copy items (other than the system software) on one or more client computers. Copying files works fastest with a small number of files. For example, ten files that are 10 KB each generally take longer than one file that is 100 KB. Consider copying a single file archive (like a .zip or .sit file) to remote computers for faster copying. Remember that Mac OS X applications are bundles of many smaller files. Although the application you want to copy looks like a single file in the Finder, it may contain hundreds, or even thousands of smaller files. If a client computer is asleep when you attempt to copy items, Remote Desktop tries to wake the client. If it can’t wake the client and the copy does not proceed, you should use Remote Desktop to wake the target computer, and then attempt the copy again.Chapter 8 Administering Client Computers 107 If you choose to copy out to many client computers simultaneously, Remote Desktop uses network multicasts to send the files. If there is a significant number of multicast networking errors, Remote Desktop tries to copy individually to each client computer. Copy Options Each time you copy an item to a remote computer, you have the chance to customize the operation to allow fine-grained control of the location and file owner of the copied file, the network bandwidth used, and what to do in case of failure or duplicate files. Copy Destination Locations There are several preset destinations available in the “Place Items In” destination popup menu, including the Applications folder. If you do not see the destination you want, you can specify a full pathname. Owner and Group for Copied File By default, the copied files inherit the owner and group of the enclosing destination folder. For additional flexibility, you have several options for handing file ownership. You can:  Preserve current owner  Set the owner to the current console user  Specify user and group Encryption You can encrypt the copy transport stream to protect the data sent across the network. By selecting the “Encrypt network data” option, you exchange performance for security. This option is also available in the Install Packages dialog. Copy Failure Handling By default, if a single computer fails to get the copied file, the copy operation continues to all participating computers. However, there may be times when you want a copy operation to stop if one of the copies fails. You can choose to cancel the entire copy operation if one participating computer reports a failure. This option is also available in the Install Packages dialog. Network Bandwidth Limits File copies are done at the maximum sustainable rate for the network. This allows Apple Remote Desktop to use all the resources at its disposal to quickly and efficiently finish the copy. Depending on what else is being done on the network, you may want to explicitly limit the copy data transfer rate. You can set an approximate maximum data rate in kilobytes per second for file copies. This option is also available in the Install Packages dialog.108 Chapter 8 Administering Client Computers More Options When the Item Already Exists If an item with the same name as the item you selected to copy already exists at the destination, you have several options for handing the name conflict. You can:  replace the existing item  replace the existing item if the existing item is older  rename the existing item  rename the item being copied  always ask which of the above options you want to use Post-Copy Action You can choose to open a copied item immediately after it’s copied. If you select this option, the file will open with the parent application that created it. Copying from Administrator to Clients Using Apple Remote Desktop, you can copy items to any number of client computers simultaneously. To copy items to clients: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the Remote Desktop window (or any window). 3 Choose Manage > Copy Items. 4 Add software to the “Items to copy” list. Click the Add button to browse local hard disks for items to copy, or drag files and folders to the list. If you want to remove an item from the list, select the item and click Remove. Repeat this step until all the software you want to copy is in the list. 5 Select your copy options. See “Copy Options” on page 107 for more information on the available options. 6 If you want to schedule this event for another time, or set it to repeat, click the Schedule button. See “Scheduled Tasks” on page 155 for more information about scheduling events. 7 Click Copy. The software is copied to the indicated destination. If the copy is unsuccessful, an error message appears in the task feedback window.Chapter 8 Administering Client Computers 109 Copying Using Drag and Drop Using Apple Remote Desktop, you can copy items by dragging them between Finder windows on your administrator computer, the Remote Desktop window, and control windows. For example, you can drag an item from a Finder window to a selected computer in the Remote Desktop window. You can use this feature to collect needed files from remote computers or distribute files between remote computers. Copying from the Finder to a Client You can copy files, applications, or folders from the administrator’s Finder windows to remote computers. You can also drag items directly on to a control window. To copy items from the Finder to a client: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers or select the desired Control window. 3 Switch to the Finder. 4 Locate the item you want to copy in the Finder. 5 Drag the item you want to copy from the Finder to the selected clients in the Remote Desktop window or control window. Copying onto a Control window puts the file wherever you drop it. 6 Select your copy options. See “Copy Options” on page 107 for more information on the available options for copy tasks. 7 Click Copy. Copying from a Client to the Finder Using Apple Remote Desktop, you can copy files, applications, or folders from a remote computer to the administrator’s computer. The process requires that you find the file you want to copy, using a report or locating them in a control window. Note: Copied items retain their original owners and permissions. To copy items from a client to the administrator’s computer: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose a file search report to find the item. See “Finding Files, Folders, and Applications” on page 116 for more information. 4 Select the item you want to copy in the report window. 5 Drag the item you want to copy from the report window to the administrator’s Finder, or click the Copy To This Computer button in the menu bar of the report window.110 Chapter 8 Administering Client Computers Alternatively, you can drag items from a control window to the administrator computer’s desktop. Restoring Items from a Master Copy Your client computers can restore non-system software from a master copy. This is helpful if you want to make sure each client computer has the same software. You can automate the software restore process by using the instructions in “Automating Functions” on page 152. You may want to start by creating a disk image that contains the Mac OS X applications and items you want to copy. Alternatively, you can copy files from any local disk, such as a hard disk, CD, disk partition, or other disk. The Copy Items command does not copy system software that is hidden (that is, not visible in the Finder). It can copy the Applications folder, Library folder, and Users folder, as well as any folders at the root of the hard disk that were created by the computer’s administrator user. Important: You cannot use the Copy Items feature to copy Mac OS X system software to client computers To restore files using the Copy Items command: 1 Make a master copy of the volume that has the files to be restored. You can use any volume, such as a spare hard disk, a CD, or a mounted disk image (.dmg) file. 2 Mount the master copy volume on the administrator computer. Master copy volumes must be local volumes, not mounted from over a network. 3 Open Remote Desktop. 4 Select a computer list in the Remote Desktop window. 5 Select one or more computers in the selected computer list. 6 Choose Manage > Copy Items. 7 Add the master copy volume to the Copy Items list. 8 Select your copy options. See “Copy Options” on page 107 for more information on the available options for copy tasks. 9 If you want to schedule this event for another time or set it to repeat, click the Schedule button. See “Scheduled Tasks” on page 155 for more information about scheduling events. 10 Click Copy.Chapter 8 Administering Client Computers 111 Creating Reports Apple Remote Desktop allows you to query client computers for many kinds of information, from installed software to network speed and reliability. Creating reports gives you valuable information about the client computers. Reports also help when you’re copying files and organizing computer lists. Collecting Report Data There are three search strategies that Apple Remote Desktop uses when searching for report information: new data, cached data, and Spotlight data. With a new data search, the Remote Desktop application queries a client directly, and waits for the client computer to respond with the desired information. A new data search gets the most recent information, but takes longer since the client computer has to gather all the data and send it over the network to the waiting administrator computer. New data reports are also generated by clients whose reporting policy is set to send data only in response to a report query. See “Setting the Client’s Data Reporting Policy” on page 152. The next source of information is a cached data search. With a cached data search, the application queries Apple Remote Desktop’s internal database of collected system information (such as hardware information and system settings), file information (including installed applications and versions, and software names), or both. You determine how often the data is collected, and what type of data is stored. See “Setting the Client’s Data Reporting Policy” on page 152.112 Chapter 8 Administering Client Computers The database, which is a PostgreSQL database located at /var/db/RemoteManagement/ RMDB/ can be accessed using other tools besides Remote Desktop. To find out more about the database schema, see “PostgreSQL Schema Sample” on page 180. The last kind of new data search is a Spotlight search. This is not a static report on saved data in a database, but it’s an interactive search of the client computers. A Spotlight search can only be done on client computers running Mac OS X 10.4 or later. Spotlight searches a comprehensive, constantly updated index that sees all the metadata inside supported files—the “what, when and who” of every piece of information saved on your Mac—including the kind of content, the author, edit history, format, size, and many more details. Spotlight searches are “live” meaning that the window reflects changes in the found files even after the command is executed. Using a Task Server for Report Data Collection You can use a computer other than the administrator computer to collect your report data, if you have another unlimited-managed computer license for Apple Remote Desktop. Using a server that is always running and has the benefits of uninterrupted power and steady uptime, you can dedicate those computing resources to report data collection. Such a server is referred to as a Task Server. To use a Task Server, you need:  a computer that will be running when the clients are set to upload their report data  an unlimited license for the Remote Desktop server  a separate unlimited license for the administrator computer To set up a Task Server, you need to: 1 Install Remote Desktop on the server. See “Installing the Remote Desktop Administrator Software” on page 40. 2 Configure the server to be the Task Server. You do this via the server settings in the Remote Desktop preferences. See “Designating the Task Server and Setting the Report Data Collection Location” on page 154 3 Install Remote Desktop on the administrator computer. See “Installing the Remote Desktop Administrator Software” on page 40. 4 Configure Remote Desktop on the administrator computer to use the Task Server as its source for report data. You do this using the server settings in the Remote Desktop preferences. See “Designating the Task Server and Setting the Report Data Collection Location” on page 154. 5 Set the client reporting policy to tell clients to send report information to the Task Server.Chapter 8 Administering Client Computers 113 You do this using the Get Info window of any client computer or the client’s own Apple Remote Desktop preferences. See “Setting the Client’s Data Reporting Policy” on page 152 and “Creating a Template Data Reporting Policy” on page 153. Report Database Recommendations and Bandwidth Usage You can have a single Apple Remote Desktop data collection database for any number of clients. However, avoid having all the clients upload their report information at the same time. As the number of clients grows, the network usage from the clients as they upload their report data could come in bursts over a short period of time overwhelming the network buffer on the Task Server. In such a case, you will probably give yourself your own denial-of-service attack. Increasing the number of Task Server computers can divide the network and computing load among several computers for better performance and better network citizenship. However, since there is no way to aggregate report data across several collectors and display it on one administrator computer, you would need multiple administrators to balance your network load in this manner. If you use a single database for a large number of clients, it is recommended that you stagger the generation of report caches over the time between which you want to run reports. For example, if you normally run a report every week, then set 1/7th of your clients to rebuild caches on day one, another 1/7th for the next day and so on. Additionally, they should stagger the cache rebuild over the course of the day as well. It is recommended that you keep in a given list the minimum number of computers necessary for your purposes. When a list is selected, the clients in the list send status updates at a minimum of every 20 seconds. If you have a large number of clients in a list (for example, 1000), this makes about 50 updates a second. Creating more lists doesn’t create more resource overhead for Remote Desktop, and can allow you to quickly and easily administer the clients you want with a minimum wait. Depending on your network and list sizes, you may find that smaller lists may result in more productive and reliable administration. What Bandwidth Does the Default System Overview Report Use on a LAN? The average System Overview Report cache is about 20 KB. While reporting, the admin and clients will always try to use all available bandwidth (most IP-based client/server applications work this way). Therefore, on a 10Mbit/sec. network, the report data collection for a single client may use 100% of the bandwidth for a period of 0.016 seconds. Assuming a list of 1000 computers, all trying to report at the same time, this may use 100% of the bandwidth for 16 seconds. Naturally, faster networks will perform better, and networks with a slow bottleneck like a DSL or modem line perform worse.114 Chapter 8 Administering Client Computers System Report Size The file system data which is uploaded to the report database (labeled “File Search data” in the Scheduling sheet of the Task Server preference pane) contains a significant amount of data. For a client with 10 GB of files on the hard disk, the report data uploaded can easily reach 5 MB in size. With hundreds or thousands of clients, this amount can add up quickly and might tax network resources. In addition, by choosing to upload user accounting data and application usage data, you are further increasing the size of the uploaded data for any one client. Since you may not want to store all the possible information for a given client computer, you can customize which type of data is collected, as desired. Auditing Client Usage Information With Apple Remote Desktop, you can get detailed information about who has been using the client computers and how. There are two reports that help you audit information about how the clients are being used:  the User History report  the Application Usage report Generating a User History Report The User History report is used to track who has logged in to a computer, when they logged in and out, and how they accessed the computer. The client stores 30 days of accumulated data, so the requested time can’t be more than the last 30 days. The report shows the following information:  computer name  user’s short name  access type (login window, tty, SSH)  login time  logout time  remote login host (originating host to the login session: localhost, or some remote computer) Note: Multiple users logged in via Fast User Switching can lead to confusing or conflicting reports. When a second or third user logs in to a computer, there is no way of knowing which user is the active user. Session length may not reflect actual usage, and login and logout times overlap. User History report information is collected by default if you are installing Remote Desktop for the first time. If you have upgraded an older version of Remote Desktop, you need to enable its collection explicitly in the clients’ reporting policy. See “Setting the Client’s Data Reporting Policy” on page 152 for instructions.Chapter 8 Administering Client Computers 115 To generate a User History report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > User History. 4 Select the time frame for the user history information. 5 Click Generate Report. The newly generated report window appears. Generating an Application Usage Report The Application Usage report shows which applications have been running on a given client, their launch and quit time, and who launched them. The client stores 30 days of accumulated data, so the requested time can’t be more than the last 30 days. The following fields are shown by default in the report:  Computer name  Name of application  Launch date  Total running time  Time as frontmost application  User name of process owner  Current state of application Application Usage report information is collected by default if you are installing Remote Desktop for the first time. If you have upgraded an older version of Remote Desktop, you need to enable its collection explicitly in the clients’ reporting policy. See “Setting the Client’s Data Reporting Policy” on page 152 for instructions. To generate an Application Usage report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Application Usage. 4 Select the time frame for application usage. 5 Click Generate Report. The newly generated report window appears.116 Chapter 8 Administering Client Computers Finding Files, Folders, and Applications Apple Remote Desktop allows you to search the contents of client computer hard disks for specific files, folders, or applications. Additionally, it can compare the results of such searches to the items on the administrator computer. These searches can compare software versions, fonts, applications, or installed packages. Using Spotlight to Find Items You can use Spotlight to find items on client computers. A Spotlight search can be done only on client computers running Mac OS X v10.4 or later. Spotlight searches are “live,” meaning that the window reflects changes in the found files even after the command is executed. Spotlight searches cannot be used for offline client computers. The Spotlight Search window is similar to the Spotlight Search window found locally on a Mac OS X v10.4 computer. It supports many of the same features and queries as Spotlight on a local computer. For more information on running a Spotlight search, see Spotlight Help. To search for software items using Spotlight: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Interact > Spotlight Search. 4 Choose the desired search parameters and enter a search term. The results are updated immediately in the window.Chapter 8 Administering Client Computers 117 The results of the search are listed in the pane at the bottom of the window. Note: The “Home” Spotlight search location means the Home folder of the currently logged in user. Generating a File Search Report The File Search report allows you to find up to a total of 32,000 items on selected computers. The items can be files, folders, or applications, but they can only be items accessible (or visible) in the Finder. The search parameters include:  Name  Parent path  Full path  Extension  Date created  Date modified  Size on disk  Kind  Version number  Version string  Owner  Group  Lock status The search parameters for Apple Remote Desktop are slightly different from those used by the Finder’s Find command. For example, Apple Remote Desktop does not search by visibility or by label. The report display can be customized as well. See “Changing Report Layout” on page 35 for more information. To search for software items: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > File Search. 4 Choose the desired search parameter from the pop-up menu and enter a search term. 5 If you want to customize the report display, do so now. For more information about the report display, see “Changing Report Layout” on page 35 for more information. 6 To search using new data, check Rebuild Data For Report; to search using saved data only, uncheck Rebuild Data For Report.118 Chapter 8 Administering Client Computers 7 Click Search. The newly generated report window appears. Comparing Software Apple Remote Desktop has several specialized reports for comparing software on client computers with software on the administrator computer. These reports can’t be run comparing two client computers. One computer in the comparison must be the administrator computer. Generating a Software Version Report The Software Version report compares application versions on client computers with application versions on the administrator computer. You can select up to 10 applications to compare. Command-line tools and unbundled Java (.jar) applications do not report their version. To generate a Software Version report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Software Version. 4 Select the software you want to compare, from the application list. You can select up to 10 applications. If the application you want doesn’t appear in the list, click the Add (+) button to browse for the application. 5 To search using new data, check Rebuild Data For Report. 6 Click Generate Report. The newly generated report window appears. Generating a Software Difference Report The Software Difference report compares the applications, fonts, and installed packages of the selected client computers with those on the administrator computer. The resulting report lists the items compared, their version, location, and whether or not they were found on the selected client computers. The Software Difference report can compare all executable Mac OS X and Classic applications. Unbundled Java (.jar) applications and command-line utilities are not included in the report. The report can compare all the fonts in the /System/Library/ Fonts/ and /Library/Fonts/, as well as the Fonts folder for the currently logged in user. Comparing installed packages returns a list of all package receipts in /Library/Receipts/. You can use this report to find out if your clients have the applications or fonts they need. Comparing differences in installed packages can help you troubleshoot software conflicts, and keep your client computers up to date.Chapter 8 Administering Client Computers 119 To generate a Software Difference report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Software Difference. 4 Select the software type you want to compare. Selecting Applications compares all executable applications. You can limit which folder on the administrator computer Remote Desktop uses to look for applications. Selecting Fonts compares all fonts in /Library/Fonts/, /System/Library/Fonts/, and user font directories. Selecting Installed Packages compares all package receipts in /Library/Receipts/. 5 To search using new data, select Rebuild data for report. 6 Click Generate Report. The newly generated report window appears. Auditing Hardware You can get a report about the hardware of any client computer. Hardware information can be accessed using a number of different reports. Although some basic hardware information can be found in the System Overview report, several more focused hardware reports provide more detailed information. To get a basic System Overview report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > System Overview. 4 Select or deselect hardware items as desired. 5 To search using new data, select Rebuild data for report. 6 Click Get Report. The newly generated report window appears.120 Chapter 8 Administering Client Computers Getting Serial Numbers Although there is no specific serial number report for Apple Remote Desktop, the serial number of any client is in the Computer section of the System Overview Report. In addition to using Apple Remote Desktop to retrieve a computer’s serial number, you could use the command-line tool systemprofiler with Apple Remote Desktop’s Send UNIX Command feature. To generate a serial number report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > System Overview. 4 Select Serial Number from the Computer section. 5 Select or deselect other items as desired. 6 To search using new data, check Rebuild Data For Report. 7 Click Get Report. The newly generated report window appears. Getting Storage Information The Storage report collects information about the client computer’s internal hard disks. It can get information about the hardware itself, the volumes on the disk, file system information, and journaling information for the disk. For a complete listing of Storage report options, see “Report Field Definitions Reference” on page 165. Basic information about hard disk volumes and size can also be found in the storage section of the System Overview report. To generate a Storage report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Storage. 4 Select the hard disk information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Get Report. The newly generated report window appears.Chapter 8 Administering Client Computers 121 Getting FireWire Device Information The FireWire Devices report gets information about FireWire devices connected to the client computer. It can get the following information from a device:  Manufacturer  Model  Device speed  Software version  Firmware revision For more information about FireWire Devices report options, see “Report Field Definitions Reference” on page 165. The number of attached FireWire devices can also be found in the Devices section of System Overview report. To generate a FireWire Devices report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > FireWire Devices. 4 Select the FireWire information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Get Report. The newly generated report window appears. Getting USB Device Information The USB Devices report gets information on Universal Serial Bus devices (scanners, keyboards, mice, and so forth) connected to the client computer. It can get the following information from a device:  Product name and ID  Vendor name and ID  Device speed  Bus power amps For more information about the USB Devices report options, see “Report Field Definitions Reference” on page 165. Basic information about attached USB devices can also be found in the Devices section of the System Overview report.122 Chapter 8 Administering Client Computers To generate a USB Devices report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > USB Devices. 4 Select the USB device information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Get Report. The newly generated report window appears. Getting Network Interface Information The Network Interfaces report gets information for all network interfaces, including inactive interfaces. It also gets detailed network, output, and Ethernet statistics from client computers. The Network Interfaces report can be used to find network errors or faulty network equipment, troubleshoot network performance, and query the network settings of the client computers. All detailed statistics are refreshed when the client restarts, and address information may change if your client uses DHCP to get a network address. For a complete listing of Network Interfaces report options, see “Report Field Definitions Reference” on page 165. Basic information about network settings can also be found in the Network and AirPort section of the System Overview report. To generate a Network Interfaces report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Network Interfaces. 4 Select the interface information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Generate Report. The newly generated report window appears.Chapter 8 Administering Client Computers 123 Getting Memory Information The Memory report gets specific information about the installed memory in a client computer. In addition to reporting how much memory the client has, it shows information about each memory module, including the module’s:  Slot identifier  Size, type, and speed Memory reports can be used for managing computer resources, hardware troubleshooting, or deciding which client computer can handle a memory-intensive application or task. For more information about the Memory report options, see “Report Field Definitions Reference” on page 165. Basic information about system memory can also be found in the Computer section of the System Overview report. To generate a Memory report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Memory. 4 Select the module information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Get Report. The newly generated report window appears. Getting PCI Card Information The PCI Cards report gets information about the PCI cards installed in a client computer. It shows information about each PCI card, including each card’s:  Slot name  Card name, type, memory, and revision  Vendor and device IDs  ROM revision For more information about the PCI Cards report options, see “Report Field Definitions Reference” on page 165. Basic information about a client’s PCI cards can also be found in the Computer section of the System Overview report.124 Chapter 8 Administering Client Computers To generate a PCI Cards report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > PCI Cards. 4 Select the PCI card information desired. 5 To search using new data, select Rebuild Data For Report. 6 Click Get Report. The newly generated report window appears. Testing Network Responsiveness Apple Remote Desktop can test network responsiveness between your administrator computer and client computers. It sends network packets to the clients and reports the time taken to receive confirmation from the clients. You can choose how many network packets to send, how often they are sent, and how long the administrator computer waits for a reply before listing a packet as lost. To generate a Network Test report: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > Network Test. 4 Select the options you want. Choose the number of packets sent from the Packets pop-up menu (Total Packets to Send). Choose how often to send the send packets from the Interval pop-up menu (Interval Between Packets). Choose how long to wait before reporting a packet as lost from the Time Out pop-up menu (Packet Time Out). 5 Click Get Report. The newly generated report window appears. Evaluating the Network Test Report You can use the Network Test report to diagnose whether task failures in Apple Remote Desktop are due to network congestion or to some other factor. You may, for example, find that a Copy Items task is failing on a particular subnet, due to network congestion on that subnet.Chapter 8 Administering Client Computers 125 Here are some suggestions for evaluating your network performance based on this report:  The number of routers between your computer and another computer can affect the time the packets take to return. When you evaluate the times for a computer, you should compare them to the times for a computer in the same area of the network or with the same number of intervening routers.  If the maximum time for a packet to return from a computer is significantly greater than the time for other computers in the same area of the network, there may be a problem with the computer.  If a single computer has a large number of lost packets, there may be a problem with the network connection to that computer.  If several computers in the same area of the network have a large number of lost packets, there may be a network connection problem or a problem with an intervening router or bridge. Exporting Report Information You can export reports into a comma-delimited or tab-delimited text file. All the columns of information in the report window are included, and the report rows are exported in the order they’re sorted at the time of export. Exported reports can be put into a database, spreadsheet, or word processor for further analysis or organization, or be sent to another administrator. You could even use certain reports as input files for network scanners for Remote Desktop. Alternatively, you could access the report’s SQL database directly with your own SQL query tools or applications. Using standard SQL database queries you can get any or all information out of the report database for use with other applications or databases. To export a report: 1 Generate any report, and bring the report window to the front. 2 If desired, sort the report rows by selecting a new column to sort by. 3 If you do not want to export the entire report, select the rows to be exported. 4 Choose File > Export Window. 5 Name the file, and choose a location to save to. 6 Select a text encoding.  Western (Mac OS Roman): Best choice if the report information uses the Roman alphabet, and the exported document will be opened in an application or on an operating system that does not support Unicode text encoding (for example, some installations of Mac OS 9).  Unicode (UTF-8): Best choice if the exported file will be opened on Mac OS X and contains no Asian language characters (such as Chinese or Japanese).126 Chapter 8 Administering Client Computers  Unicode (UTF-16): Best choice if the report contains Asian language characters. 7 Select a field separator.  Tab: Inserts a Tab character between column values.  Comma: Inserts a comma between column values. 8 If you have selected only some rows of the report and want to export only the selected rows, select Export Selected Items Only. 9 Click Save. Using Report Windows to Work with Computers After you’ve created a report, you can use it to select computers and then do any of the following:  Create new computer lists. Select computers in the report window and select File > New List From Selection.  Generate other reports. Select any number of rows in a report window; then choose another report from the Report menu. The new report will be generated based on the computers in the selected rows.  Initiate any management task. Select any row in a report window; then choose a management task from the Manage menu. This has the same effect as selecting the computer in an Apple Remote Desktop computer list.  Interact with users. Select any row in a report window; then choose a task from the Interact menu. This has the same effect as selecting the computer in an Apple Remote Desktop computer list.  Delete a file from a computer. Select a file in any file or software report window and click the Delete button.  Copy an item to your computer. Select an item in any software report window and click Copy to This Computer.Chapter 8 Administering Client Computers 127 Maintaining Systems Apple Remote Desktop provides easy and powerful tools for maintaining client computers, including tasks such as deleting files, emptying the Trash, and setting computer startup options. Deleting Items If you delete a file from a client computer, it is moved to the client’s Trash. To delete an item from a client: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Report > File Search. 4 Find the software you want to delete, using the File Search report. For more information, see “Finding Files, Folders, and Applications” on page 116. 5 Select the item or items you want to delete in the File Search report window. 6 Click Delete Selected in the report window. 7 Click Delete.128 Chapter 8 Administering Client Computers Emptying the Trash Apple Remote Desktop allows you to empty the Trash on clients to free up disk space. To find out how much free disk space is on a computer, create a System Overview or Storage report using the Report menu. As a part of routine maintenance for client computers, you can free disk space by emptying the Trash. Emptying the Trash completely removes any items you’ve previously deleted on the client. You can use the System Overview report to see how much disk space you can recover by emptying the Trash. To empty the Trash: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Empty Trash. 4 Click Empty. Setting the Startup Disk Apple Remote Desktop can set the startup disk on any client computer. You can choose between a volume on a local hard disk or any available NetBoot volume. The startup disk must have a valid operating system installed on it. To set the startup volume on a local hard disk for multiple computers at once, the local volume name must be the same for all computers. Alternatively, you can set the startup disk to be a NetBoot volume provided by Mac OS X Server. This allows you to start up a number of clients from a NetBoot server. To set the startup disk: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Set Startup Disk. The list that appears shows the client’s local hard disk, a custom NetBoot server item, and a list of all available NetBoot and Network Install servers available on the local network subnet. 4 Choose the client’s local hard disk or a NetBoot server volume. 5 If you want to choose a specific local hard disk volume, select Hard Disk, click Edit, and enter the desired volume name. 6 If you want to choose a custom NetBoot server volume, enter the server IP address or fully qualified domain name, and the NetBoot volume name. 7 If desired, select Restart When Done.Chapter 8 Administering Client Computers 129 If you select Restart When Done, the client computer will restart after having its startup volume set. You need to have Restart privileges to use this option. 8 Click Set. Renaming Computers Apple Remote Desktop can set the name that a client computer uses for file sharing. You can rename multiple computers with the same name followed by a number (such as Computer1, Computer2, and so on). This is especially useful for differentiating client computers after a clean system installation. Note: The Rename Computer feature does not change the Local Hostname or the DNS name of a client computer. To rename a computer: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Rename Computers. 4 Enter the new computer name. 5 If desired, select “Append a unique number for each computer.” Selecting this option appends a unique number to the end of the computer name. For example, if you rename three computers “Computer,” the computers will be named “Computer1,” “Computer2,” and “Computer3.” 6 Click Rename. Synchronizing Computer Time Maintaining synchronized clocks across your clients is essential for management reliability. Synchronized times allow for more precise audits and allow you to accurately correlate events between clients on the network. In addition, many internet services rely on, or benefit from, clock times that are synchronized to a Network Time Protocol (NTP) server. Any scheduled event benefits from synchronized client time. All Mac OS X clients can be set to automatically synchronize their clocks with an NTP server. Mac OS X Server can be configured to act as an NTP server as well. In order to maintain synchronization across your clients, you should choose a single NTP server to synchronize to. Apple provides an NTP server at time.apple.com. Setting computer time requires the use of Apple Remote Desktop’s Send UNIX Command feature and its built-in command-line tool, systemsetup. See “Built-in Command-Line Tools” on page 147 for more information about the tool.130 Chapter 8 Administering Client Computers To synchronize client computer clocks: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Use the provided Templates for Send UNIX Command to set the time server (see “Send UNIX Command Templates” on page 143 for more information). a Select System Setup > Network Time from the Template pop-up menu. b Click Send. c Select System Setup > Network Time Server from the Template pop-up menu. Change the time server from time.apple.com to whichever time server you want, if desired. 5 Alternatively, manually enter the UNIX command. a Type or paste the following UNIX command: systemsetup -setusingnetworktime on -setnetworktimeserver b Set the user permissions for this command to be sent as the user “root.” 6 Click Send. Setting Computer Audio Volume You may want to standardize or otherwise configure the output volume of your computers. You could use this to silence a lab of computers all playing music, or turn up the volume on a single remote computer for a user’s benefit. You can also set the alert volume separately from the output volume and input volume. Additionally you can set “output muted.” Muting the volume causes the computer to remember what the previous volume level was and return to it when the sound is enabled again. Setting computer audio volume requires the use of Apple Remote Desktop’s Send UNIX Command feature, AppleScript, and the command-line tool osascript. See “UNIX Shell Commands” on page 143 for more information. See AppleScript’s StandardAdditions dictionary for information about using this tool. To set a computer’s audio volume: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Use the provided Templates for Send UNIX Command to set the computer volume (see “Send UNIX Command Templates” on page 143 for more information). a Select Miscellaneous > Volume On from the Template pop-up menu. b Set the desired volume level in the Send UNIX Task dialog.Chapter 8 Administering Client Computers 131 5 Alternatively, manually enter the UNIX command. a Type or paste the following UNIX command: osascript -e 'set volume output volume any_number_from_0-100' b or for Mac OS X v.10.3 clients enter or paste the following: osascript -e 'set volume any_number_from_0-7' 6 Click Send. Repairing File Permissions Sometimes a client’s system file permissions can be corrupted or changed from their expected values. In such a case, it may be necessary to manually repair the permissions on the client. Repairing permissions returns system and library files to their default settings. Repairing file permissions requires the use of Apple Remote Desktop’s Send UNIX Command feature, and the command-line tool diskutil. See “UNIX Shell Commands” on page 143 for more information. For information about using this tool, see diskutil’s man page. To repair a computer’s file permissions: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Type or paste the following UNIX command: diskutil repairPermissions / 5 Set the user permissions for this command to be sent as the user “root.” 6 Click Send. Adding Items to the Dock If you install software on your client computers by dragging and dropping, the file, folder, or application isn’t immediately added to the user’s Dock. The instructions provided here are a workaround for clients that are not part of a managed client environment. Note: Dock management is best done in a Mac OS X Server Workgroup Management environment. If you use Mac OS X Server to manage client settings and preferences, the correct place to change the Dock is within the management settings of Workgroup Manager. To add an application or other item to the Dock: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command.132 Chapter 8 Administering Client Computers 4 Type or paste the following UNIX command (replace /Path_To_Application with your own path to the desired application, and be sure to include the application file extension, .app): defaults write com.apple.dock persistent-apps -array-add 'tiledatafile-data _CFURLString/Path_To_Application _CFURLStringType0 ';killall -HUP Dock Use “persistent-others” instead of “persistent-apps” if the item is anything other than an application. 5 Set the permissions for those of currently logged-in user. 6 Click Send. Changing Energy Saver Preferences You can get and change the settings found in the Energy Saver pane of System Preferences. You can change the computer sleep time, as well as other Energy Saver Options. You can set all the clients to have the same sleep time and even turn on the preference necessary for them to respond to the Apple Remote Desktop Wake command (“Wake for Ethernet network administrator access”). Changing the Energy Saver preferences requires the use of Apple Remote Desktop’s Send UNIX Command, and its built-in systemsetup command-line tool. See “Built-in Command-Line Tools” on page 147 for more detailed information about the systemsetup tool. To change the Energy Saver preferences: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Use the provided Templates for Send UNIX Command to set the energy saver preferences. a Select any one of the following Energy Saver items from the System Setup group:  Restart After Freeze  Restart After Power Failure  System Sleep Time  Display Sleep Time  Wake On Network Access  Wake On Modem Activity b Change the template values to the desired values, and click Send. 5 Alternatively, manually enter the UNIX command.Chapter 8 Administering Client Computers 133 a Type or paste the following UNIX command: systemsetup -setsleep minutes number_of_minutes_to_sleep -setwakeonmodem (on | off) -setwakeonnetworkaccess (on | off) -setrestartpowerfailure (on | off) -setrestartfreeze (on | off) b Set the permissions for this command to root. 6 Click Send. Changing Sharing Preferences for Remote Login Mac OS X’s Sharing System Preference pane allows you to enable or disable SSH login access to the computer. You can use Remote Desktop to change enable or disable a remote computer’s preference. Setting the remote login sharing preference requires the use of Apple Remote Desktop’s built-in command-line tool, systemsetup. See “Built-in Command-Line Tools” on page 147 for more detailed information about the tool. To change the Remote Login sharing preference: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Use the provided Templates for Send UNIX Command to set the Remote Login (SSH) setting (see “Send UNIX Command Templates” on page 143 for more information). a Select System Setup > Remote Login (SSH) from the Template pop-up menu. b Set the login for on or off. 5 Alternatively, manually enter the UNIX command. a Type or paste the following UNIX command: systemsetup -setremotelogin (on | off) b Set the permissions for this command to root. 6 Click Send. Setting Printer Preferences You can set the default printer for your client computers so that they all have the same default and configured printer. There are several ways to set up printer preferences for a client computer. If you have a computer whose printer setup is correct, you can use Remote Desktop to copy the necessary configuration files to the client computers. If you don’t have a configured computer available, you can use the command-line tools in Mac OS X to set the printer preference. Setting the printer preference via Remote Desktop involves using the Copy Items task. See “Copying from Administrator to Clients” on page 108 for more information.134 Chapter 8 Administering Client Computers To set up printer preferences using Copy Items: 1 Set up a client computer’s print preference using the Printer Setup Utility. 2 Use the Copy Items task to copy the following file and folder to all the target computers: /private/etc/cups/printers.conf /private/etc/cups/ppd/ Because these files are hidden in the Finder, you may have to use the Terminal or the Finder’s “Go to Folder” command to add them to the “Items to copy” list. 3 Choose a “Same relative location” as the copy destination. 4 Choose to replace existing items. 5 Click Copy. 6 Restart the client computers’ printer process by restarting the clients. If you are comfortable with the command-line, you can use Remote Desktop’s Send UNIX Command to configure all the client computer preferences at once. Setting printer preferences using Send UNIX Command requires the use of the built-in lpadmin command-line tool. For more information, see the lpadmin man page. To set up printer preferences using Send UNIX Command: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Type or paste the following UNIX command: lpadmin -p printer_name -E -v lpd://printer_and_queue_address -m printer_model_ppd_file -L “text_description_of_printer_location” 5 Set the user permissions for this command to “root.” 6 Click Send.Chapter 8 Administering Client Computers 135 Managing Computers Using Apple Remote Desktop, you can control multiple client computers simultaneously, issuing commands that are found in Mac OS X’s Apple menu (Log Out, Sleep, Restart, etc.), as well as other commands. Opening Files and Folders Apple Remote Desktop can open existing items (files, folders, and applications) on client computers. The item to open must be on the administrator computer, in addition to being on the client computers, and must have the same name, type, size, permissions, and file creation date as the item on the administrator computer. The Open Items command opens files in the application used to create them, if it exists on the client computer, or in the application assigned to open files with that file’s extension. Folders open in the Finder. Applications are opened, or brought to the front, if already open.136 Chapter 8 Administering Client Computers To open an item: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Open Items. 4 Click the Add (+) button and browse for the item on the administrator computer. Alternatively, drag the item from the administrator computer’s Finder to the Open Items dialog. 5 Click Open when the item is selected. The Open Items dialog shows the icon and name of the item to open. 6 Click Open. Opening Applications Apple Remote Desktop can open applications on client computers. The application to open must be on the administrator computer, in addition to being on client computers. If the application is already open, the Open Application command brings it to the front. You can open both Mac OS X and Classic applications with this command. The application on the administrator computer must have the same name, type, and permissions as the one to be opened on the client computer. To open an application: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Open Application. The Open Application dialog shows the applications installed and found in the Applications folder at the top level of the hard disk of the administrator’s computer. 4 Select the application or click the Add (+) button and browse to find the desired application on the administrator computer. Alternatively, drag the item from the administrator computer’s Finder to the Open Application dialog. The Open Application dialog shows the icon and name of the application to open. 5 Click Open.Chapter 8 Administering Client Computers 137 Quitting Applications Without Logging Out the User Apple Remote Desktop can quit running applications on client computers. You can quit both Mac OS X and Classic applications with this command. The administrator must be able to use the Send UNIX Command on the client computer. You can get more information on the killall command by seeing its man page. Note: Unsaved changes to documents on the client will be lost. To quit an open application: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Use the provided Templates for Send UNIX Command to quit an application (see “Send UNIX Command Templates” on page 143 for more information). a Select Miscellaneous > Quit Application from the Template pop-up menu. b Fill in the desired Application Name. 5 Alternatively, manually enter the UNIX command. a Type or paste the following UNIX command: killall “application_name” b Set the user permissions for this command to be sent as the user “root.” 6 Click Send. Putting a Computer to Sleep Apple Remote Desktop can put client computers to sleep. This has the same result as choosing the Sleep command on the client: the display sleeps, the hard disks spin down, and the computer’s central processor and network interface are put in a lowpower mode. Note: Although you can put computers to sleep which are on other network subnets besides your own, and via AirPort, you will not be able to wake them using Remote Desktop. To put a computer to sleep: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Sleep. 4 Click Sleep.138 Chapter 8 Administering Client Computers Waking Up a Computer Apple Remote Desktop can wake up computers that have gone to sleep or been put to sleep with Remote Desktop. To wake a computer using Remote Desktop, the computer’s networking hardware must support waking via network packet (wakeonlan), and the computer must have “Wake For Ethernet Network Administrator Access” enabled in the Wake Options of Energy Saver preferences. You cannot wake up computers connected to the network via AirPort or computers not located on your local subnet. Apple Remote Desktop uses a “wakeonlan” packet to wake sleeping client computers. The packet can only be delivered by way of a local broadcast address, so it only works on a local area network. Also, the network hardware still needs to be powered to receive and act on the packet. AirPort and other wireless network interfaces completely power down on sleep and therefore can’t receive or act on a wakeonlan packet. If you must wake computers on a different subnet, you may want to use a computer on that subnet as a type of sentry. It never sleeps, and runs another licensed copy of Remote Desktop, as well as allows itself to be controlled by your local copy of Remote Desktop. That way you can control the “sentry” computer and instruct it to wake client computers on its local subnet. To wake a computer: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers from the list that show a status as “Sleeping” or offline. 3 Choose Manage > Wake. 4 Click Wake. Locking a Computer Screen Apple Remote Desktop can lock a computer screen. When you lock a computer screen, no one can see the desktop or use the mouse and keyboard on that computer. By default, Apple Remote Desktop displays a picture of a padlock on locked screens, but you can display a custom picture. See “Displaying a Custom Picture on a Locked Screen” on page 139 for more information. You can continue to work with computers using Remote Desktop after you’ve locked their screens.Chapter 8 Administering Client Computers 139 To lock a computer screen: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Interact > Lock Screen. 4 Enter a message to be displayed on the locked screen, if desired. 5 Click Lock Screen. The client screen goes black, except for the administrator’s name, the default picture, and any message text. Displaying a Custom Picture on a Locked Screen You can display a picture of your choice on the client screen while it is locked by Apple Remote Desktop. When creating images, make sure the image size will fit on the client computer’s screen. For example, if you have clients with 800 x 600 screens, a picture that is 1024 x 768 will be scaled down to fit the screen. To create a custom locked screen picture: 1 Create a picture using a graphics program, such as AppleWorks. 2 Save the picture in PICT, TIFF, GIF, JPEG, or any other QuickTime-compatible static image format. QuickTime-compatible movies or QuickTime VR objects cannot be used. 3 Name the picture “Lock Screen Picture”. 4 Copy the “Lock Screen Picture” file to /Library/Preferences/ on the client computer. Unlocking a Computer Screen You must use Apple Remote Desktop to unlock any computer screen locked by Remote Desktop. When you unlock a computer screen, you restore the desktop and use of the mouse and keyboard on that computer. To unlock a computer screen: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers from the list that show a “Locked Screen” status. 3 Choose Interact > Unlock Screen. 4 Click Unlock Screen.140 Chapter 8 Administering Client Computers Disabling a Computer Screen Sometimes you may want to control a client computer with a user at the client computer, but you don’t want the user to see what you’re doing. In such a case, you can disable the client computers screen while preserving your own view of the client computer. This is a special control mode referred to as “curtain mode.” You can change what’s “behind the curtain” and reveal it when the mode is toggled back to the standard control mode. This feature only works with Mac OS X v.10.4 clients. To disable a computer screen while you work: 1 Control a client computer. See “Controlling Apple Remote Desktop Clients” on page 78 or “Controlling VNC Servers” on page 82 for detailed information. 2 Click the Lock Computer Screen While You Control button in the control window toolbar. Alternatively, if you are not currently in a Control window and have added the “Control Computer in Curtain Mode” button to your toolbar, click that toolbar icon. You can also select Interact > Curtain. Logging In a User at the Login Window Apple Remote Desktop can log in any user on a client computer by using AppleScript System Events and the Send UNIX Command feature. Using these powerful features you can log in any number of client computers to the same user name simultaneously from the login window. This script is for use on computers at the login screen only. To log in a user: This method uses the osascript command. For detailed information on osascript, see the osascript man page. 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Type the following AppleScript in the UNIX Command window, adding the user name and password: osascript <" keystroke tab delay 0.5 keystroke "" delay 0.5 Chapter 8 Administering Client Computers 141 keystroke return end tell EndOfMyScript 5 Choose user “root” to run the command. 6 Click Send. The client computer executes the script. Logging Out the Current User Apple Remote Desktop can log out the current user on a client computer. Other users, besides the current active user, who are logged in using Fast User Switching are not logged out using this command. Using this command returns the client computer to the login window. Unsaved work will stop the logout process. To log out a user: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Log Out Current User. 4 Click Log Out. Restarting a Computer Apple Remote Desktop can restart a client computer. This has the same result as choosing the Restart command from the client computer’s Apple menu. This feature is especially useful when used with the Install Packages command. Install Packages doesn’t restart the computer, even if the package requires it. You can restart the computer using Remote Desktop after installing a package. To restart a computer: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Restart. 4 Select the type of restart. You can allow users to save files or cancel the restart, or you can force an immediate restart, which will cause the users to lose unsaved changes to any open files. 5 Click Restart.142 Chapter 8 Administering Client Computers Shutting Down a Computer Apple Remote Desktop can shut down a client computer. This has the same result as choosing the Shut Down command from the client computer’s Apple menu. Note: If you shut down an Apple Remote Desktop client, you cannot start it up using Remote Desktop. This command is especially useful when used with Energy Saver preferences. You can set your client computers to start up every morning at a designated time and use Remote Desktop to shut them down at night. The next morning, they will start up and be ready to administer. To shut down a computer: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Shut Down. 4 Select the type of shutdown. You can choose to allow users to save files or cancel the shutdown, or you can force an immediate shutdown, which will cause the users to lose unsaved changes to any open files. 5 Click Shut Down.Chapter 8 Administering Client Computers 143 UNIX Shell Commands In addition to its own tasks, Apple Remote Desktop provides a way to easily execute UNIX commands on client computers. In order to send UNIX commands to the client computers, the client computers must have the BSD subsystem installed. The UNIX commands are shell command, which means you can write a script with conditionals, loops, and other functions of the shell, and not just send a single command. Send UNIX Command Templates Remote Desktop has a few built-in UNIX shell command templates for use with Send UNIX Command. In the Send UNIX Command task configuration dialog, you can select any one of the commands from the Templates pop-up menu. Selecting a template pastes a generic script into the UNIX command field. All you have to do is customize the script to your situation. For example, if you want to set a manual IP address for a client computer, you would select the Manual IP template from the Template > Network Setup pop-up menu, replace the placeholder indicated in the pasted-in UNIX command with the real IP address, and send the command. You are free to make as many templates as your want from either existing templates or from scratch. Once saved, a template can be made the task’s default, with all new instances of the task opening with the default template settings.144 Chapter 8 Administering Client Computers For more information about Task Templates, see “Creating and Using Task Templates” on page 100. The built-in Send UNIX Command templates include: Template sub-menu Template name Network Setup  List All Services  Manual IP  DHCP  BOOTP  Manual with DHCP Router  DNS Servers  Search Domains  Web Proxy System Setup  Allow Power Button To Sleep  Bonjour Name  Current Date  Current Time  Time Zone  Network Time  Network Time Server  Remote Apple Events  Remote Login (SSH)  Restart After Freeze  Restart After Power Failure  System Sleep Time  Display Sleep Time  Hard Disk Sleep Time  Delay After Power Failure  Wake On Modem Activity  Wake On Network Access Miscellaneous  Login User  Quit Application  Volume Off  Volume On  List Required Software Updates  Install Required Software Updates  Repair Disk Permissions  Computer Uptime  Free Swap Space  Top UsersChapter 8 Administering Client Computers 145 Executing a Single UNIX Command Using the UNIX Command window, you can send a single command to the selected client computers. The command is executed using the bash shell. To execute a single UNIX command: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Type or paste the command. If your command is a multi-line script, enter each command on its own line. If you want to break up a single-line command for better readability, use a backslash (\) to begin a new line. 5 Set the permissions used to execute the command. You can choose the currently logged-in user, or choose the name of another user on the client computers. 6 Click Send. Executing Scripts Using Send UNIX Command There are two kinds of scripts you can execute via the command line. First, and most common with command lines, is a shell script. A shell script is a file containing a collection of UNIX commands that are all executed in sequence. Shell scripts can have normal programming procedures like loops, conditionals, and variables. Shell scripts are text files with UNIX line endings. Shell scripts are interpreted using the bash shell. The second kind of script you can execute, and the most common in the Mac OS X environment, is an AppleScript. AppleScripts are files that contain English-like commands, using the AppleScript programming language and they are created using the Script Editor application. Running a UNIX command as the current user will fail if the target computer is at the login window, since there is no current user at that point. You can use root user for tasks by entering root in the specified user field of the task dialog. You don’t actually need to have the root account enabled on the client computer to specify the root user. You should never use sudo or su to do tasks as the root user. They are interactive and expect further input and response from your script. Instead, run your script as root or whatever user you were planning on. Executing Shell Scripts with Remote Desktop Shell scripts can be copied, then executed. If a script has any degree of complexity, or if it cannot be expressed on a single line, you can use Copy Items to copy the script file to the client computers, then execute it using Send UNIX Command. To send a single-line command you can simply use Send UNIX Command.146 Chapter 8 Administering Client Computers To copy and execute a script: 1 Prepare and save your script. Make sure your script is saved as plain text with UNIX line breaks. 2 Open Remote Desktop. 3 Select a computer list in the Remote Desktop window. 4 Select one or more computers in the selected computer list. 5 Use the Copy Items command to copy your script to the client computers. See “Copy Options” on page 107 and “Copying from Administrator to Clients” on page 108 for more information. 6 After copying the script, choose Manage > Send UNIX Command. 7 Execute the script by typing: sh script pathname 8 Click Send. Executing AppleScripts with Remote Desktop AppleScripts can be executed on client computers in two ways. They can be saved and executed as an application, or sent at once using the command line. To learn more about AppleScript, see AppleScript Help in Help Viewer or go to: www.apple.com/applescript/. To send and execute an AppleScript: 1 Save the AppleScript as an application. 2 Open Remote Desktop. 3 Select a computer list in the Remote Desktop window. 4 Select one or more computers in the selected computer list. 5 Use the Copy Items command with the Open Items option selected in the Copy Items dialog. See “Copy Options” on page 107 for more information. To execute an AppleScript using the Send UNIX Command: This method uses the osascript command. See the osascript man page for more information. 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose Manage > Send UNIX Command. 4 Type or paste the AppleScript in the UNIX Command window, like this: osascript -e 'First line of script' -e 'Next line of script' [ -e ... ]Chapter 8 Administering Client Computers 147 Alternatively, you could use a UNIX “read standard input” redirection which looks like: osascript < value must be a multiple of 30 seconds. Example: systemsetup - setWaitForStartupAfterPowerFailure 30 -setwakeonmodem ( on | off ) Use this command to specify whether or not the server will wake from sleep when modem activity is detected. Example: systemsetup -setwakeonmodem on -setwakeonnetworkaccess ( on | off ) Use this command to specify whether the server wakes from sleep when a network admin packet is sent to it. Example: systemsetup -setwakeonnetworkaccess on Flag DescriptionChapter 8 Administering Client Computers 151 Any command in the Mac OS X Server command-line guide that uses systemsetup can be used in Remote Desktop using the Send UNIX Command task. Using kickstart The kickstart command-line utility is embedded within the Apple Remote Desktop client software. It allows you to install, uninstall, activate, configure, and restart components of Apple Remote Desktop without restarting the computer. You can configure all the features found in the Remote Desktop section of the Sharing System Preferences. The kickstart utility can be used via SSH to configure remote computers, including Xserves. The kickstart utility is located at: /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/ Resources/kickstart. The syntax and list of actions possible with kickstart are available by running kickstart as follows: $sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/ Resources/kickstart -help If you are running the kickstart utility through Apple Remote Desktop’sSend UNIX Command function, you don’t need the full path, just the name kickstart and root as the command’s user. You can use the sudo command with an administrator account to use the kickstart utility, or you can use the root user via Send UNIX Command. All commands presented in this section should be typed as one line of text. It’s OK if the text wraps as you enter it; just be sure not to enter return characters. The following are some examples of actions possible with kickstart:  Activate Remote Desktop sharing, enable access privileges for all users, and restart the Apple Remote Desktop Agent: $ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/ Contents/Resources/kickstart -activate -configure -access -on -restart -agent -privs -all  Activate Remote Desktop sharing, enable access privileges for the users “admin”, grant full privileges for the users “admin,” and restart the Apple Remote Desktop Agent and Menu item: $ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/ Contents/Resources/kickstart -activate -configure -access -on -users admin -privs -all -restart -agent -menu  Activate Remote Desktop sharing, and disable access privileges for all users: $ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/ Contents/Resources/kickstart -activate -configure -access -off  Shut down the Apple Remote Desktop Agent process: $ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/ Contents/Resources/kickstart -agent -stop152 Chapter 8 Administering Client Computers  Deactivate Remote Desktop access for a computer: $ sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/ Contents/Resources/kickstart -deactivate -configure -access -off Automating Functions You can automate any command or function in Remote Desktop. Additionally, Remote Desktop supports scripting (either UNIX or AppleScript) to help automate their client management. Setting the Client’s Data Reporting Policy To speed up reporting and allow reporting from offline clients, Apple Remote Desktop uses saved client system and file information. You can automate the collection of this information by setting the data reporting policy. This schedule determines how often the client updates its system and file information for reports. In accordance with the collection schedule you set, each client computer connects to a central reporting database and uploads the information you designate. There are certain trade-offs to the frequency of these updates. If you require all the clients to update their information too often, you run the risk of added network traffic and slower client performance during updates. If you don’t require the clients to update often enough, the report data that you receive may be out of date. You should take care to balance your reporting needs and your network and client performance needs. The collection policy includes four kinds of information: system data, file data, user accounting data, and application usage data. System data includes all possible reported information for the following reports:  System Overview  Storage  USB Devices  FireWire Devices  Memory  PCI Cards  Network Interfaces The file data includes all possible reported information for the following reports:  File Search  Software Version  Software DifferenceChapter 8 Administering Client Computers 153 The user accounting data includes all possible reported information for the following report:  User History The application usage data includes all possible reported information for the following report:  Application Usage To set a client’s data reporting policy: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose File > Get Info. 4 If you have selected only one computer, select the Data Settings tab, and click the Edit button. If you have selected more than one computer, this tab is already selected. 5 Select “Upload on a schedule.” To disable a client’s automatic data collection, deselect “Upload on a schedule.” 6 If you have already made a default schedule, you can use it by clicking “Use default schedule” to automatically fill in the appropriate information and click Done. Otherwise, choose the day or days the data collection should occur. For more information about setting a default schedule, see “Creating a Template Data Reporting Policy” on page 153. 7 Set the time at which the collection occurs. 8 Choose which data types to upload: System Data, File Search Data, Application Usage Data or User Accounting Data, or any combination. 9 In order to upload Application Usage Data and User Accounting Data, you need to specify collection of that data. Choose Collect Application Usage Data to tell a client computer to save report information for the Application Usage Report. Choose User Accounting Data to tell a client computer to save report information for the User History Report. 10 Click Apply. Creating a Template Data Reporting Policy To speed up client configuration for data reporting, you can set a default time and frequency of report data collection. This template must be applied to any computer or group of computers that you want to use it. Afterwards, the setting can be customized on a per-computer or group basis.154 Chapter 8 Administering Client Computers To set the default data reporting policy template: 1 Choose Remote Desktop > Preferences. 2 Select Task Server. 3 Check which additional data types the clients will collect: Application Usage Data, User Accounting Data, or both. 4 Check “Upload report data to the Task Server on a schedule.” 5 Click Change Schedule. 6 Choose the day or days the data collection should occur. 7 Set the time at which the collection should occur. 8 Choose which data types to upload: “System Data,” “File Search Data,” “Application Usage Data,” “User Accounting Data,” or any combination. 9 Click OK. Designating the Task Server and Setting the Report Data Collection Location To speed up reporting, Apple Remote Desktop uses a database of client system and file information. You can automate the collection of this data for reports, and determine where the database will reside. By default, the database is stored on the administrator computer. Use these instructions to change the data collection location. First, determine where the data will be located: on the administrator computer, or a remote computer (called a Task Server). A Task Server needs to be an unlimited-client licensed Apple Remote Desktop administrator computer and have TCP and UDP ports 3283 open to all of the reporting client computers (and TCP port 5900 open, if you want to control the clients). If you choose to use another Apple Remote Desktop administrator computer’s database, you must configure it to allow data access to other Apple Remote Desktop administrators. The default Task Server is the computer upon which you installed Remote Desktop. See also “Using a Task Server for Report Data Collection” on page 112. If you choose to store the data locally and you have an unlimited client license, you can allow other Apple Remote Desktop administrators with unlimited-managed computer licenses to access the database on your computer by selecting the “Allow remote connections to this server” option. Warning: If you change the location of the report database from the one selected in the initial setup, you will need to reset the collection policies for the client computers. The database will not be moved, but will be regenerated at the next collection interval.Chapter 8 Administering Client Computers 155 To set the Task Server location: 1 Open Remote Desktop. 2 Choose Remote Desktop > Preferences. 3 Click Task Server. 4 If you want to use the database on this administrator computer, select “Use Task Server on this computer.” 5 If you use your Remote Desktop administration computer as a Task Server on the local administrator computer, click “Allow remote connections to this server.” 6 If you want to use a database on another administrator computer, select “Use remote Task Server.” Then, enter the IP address or fully qualified domain name of the other Apple Remote Desktop administrator computer, and click Select. 7 Close the window to save changes. Scheduled Tasks You can use Apple Remote Desktop to automate and schedule almost any task. For example, you can make sure a particular application or a specific set of fonts is always available on a client computer by setting Remote Desktop to copy applications and fonts to the client every night. When you schedule an automated task, information about the scheduled task is saved on the administrator computer. At the appointed time, the client software on that computer activates and initiates the task. Remote Desktop must be open to perform a scheduled task. Setting Scheduled Tasks Any task with the Schedule Task button in the task configuration window can be scheduled. Tasks that you have scheduled appear on the left in the main Remote Desktop window. To schedule a task: 1 Select a computer list in the Remote Desktop window. 2 Select one or more computers in the selected computer list. 3 Choose the task you want to schedule from the menu bar. 4 Configure the task as needed. 5 Before executing the task, click the Schedule button. The scheduling information is revealed. 6 Choose when and how often you want the task to execute. 7 If you want the task to repeat, click Repeating Every then set the repeat interval.156 Chapter 8 Administering Client Computers 8 Click OK. 9 Save the task and choose where the task will appear in the Remote Desktop window. Editing Scheduled Tasks Once saved, a task can be changed and all future executions of the task will reflect the changes. You may want to edit which computers are affected by the task or any other task parameter. To edit a task schedule: 1 Double-click a scheduled task in the Remote Desktop window. 2 Edit the task, as needed. 3 Click the Schedule Task button. 4 Edit the task schedule, as needed. 5 Click OK. 6 Click Save. Deleting Scheduled Tasks Unneeded tasks can be deleted. If you want to keep the task, but stop it from repeating, you should edit the scheduled task instead of deleting it. See “Editing Scheduled Tasks” for more information. To delete a scheduled task: 1 Select the saved task in the Remote Desktop window. 2 Press the Delete key. 3 Click Delete. Using AppleScript with Remote Desktop AppleScript is a powerful and versatile scripting language that is built into Mac OS X. You can use AppleScript to create shortcuts, automate repetitive tasks, or even make custom applications that save you a great amount of time. AppleScript is an Englishlike language you can use to write scripts that contain commands. Scripts can make decisions based on user interaction, or by parsing and analyzing data, documents, or situations. Remote Desktop is scriptable, as are many other Mac OS X applications, and it can be controlled with AppleScript commands. AppleScript is a complete language with conditional statements, comparison and arithmetic operations, and the ability to store variables. This documentation doesn’t teach AppleScript language syntax or programming practices. For information about learning how to program with AppleScript, see the AppleScript online help. This section provides a brief description of AppleScript, a brief discussion of using the Remote Desktop AppleScript Dictionary, and a sample script.Chapter 8 Administering Client Computers 157 Remote Desktop’s AppleScript Basics AppleScript scripts consist of commands that are sent to objects. Objects can be a wide variety of things, including applications, scripts, windows, settings, or the Finder. These objects can receive a specific set of commands and respond with the desired actions. Essentially, a script tells an application (Remote Desktop in this case) to either complete a certain task or retrieve information. You can give the script decision-making capabilities by using conditional statements; you can give the script a memory by defining variables. Remote Desktop has made all of its fundamental functions scriptable. The tasks that you perform as an administrator by pointing and clicking the mouse can all be accomplished by running an AppleScript. For example, you can:  Get information on or rename a computer  Add computers to a list  Copy or install items  Execute a report task Using the Remote Desktop AppleScript Dictionary Each scriptable application contains an AppleScript dictionary—the list of objects and messages that an application can understand. For example, in Remote Desktop’s dictionary there is an object named “computer list” that has this entry: A “computer list” is an object which contains other objects (“computers” in this case) and has properties like its “id” and its “name.” When queried, this object can return the values for the properties (in Unicode text as indicated), but you can’t change “id” from within the script (it’s labeled r/o for read-only). This object can be acted upon by the “verbs,” or messages, in a script. The dictionary also contains “verbs,” or messages. These verbs are commands that act on the objects in the dictionary. For example, in Remote Desktop’s dictionary there is a verb named “add,” and this is its entry: computer list n [inh. item] : A list which holds computers. ELEMENTS contains computers; contained by application. PROPERTIES id (Unicode text, r/o) : The unique identifier (UUID) of the computer list. name (Unicode text) : The name of the computer list. add v : Add a computer to a task. add computer : The computer. to computer list : The computer list (or task) to add the computer to.158 Chapter 8 Administering Client Computers This entry tells you what the verb can act on and how. This entry says that Remote Desktop can add a specified computer to a computer list. The objects “computer” and “computer list” are being acted upon by “add.” To access the full AppleScript dictionary for Remote Desktop: 1 Launch Script Editor in the /Applications/AppleScript/ folder. 2 Select File > Open Dictionary. 3 Choose Remote Desktop. 4 Click Open. The AppleScript Dictionary for Remote Desktop is also available in Appendix C, “AppleScript Remote Desktop Suite.” Sample AppleScript This AppleScript is one that could be used to do a quick cleanup of a group of computers. First, it locks the computer screens to prevent interference. Second, it deletes all items left on the currently active desktops of the client computers. Finally, it finishes by emptying the clients’ trash and unlocking the screens. This script is for educational use only and no warranty is explicit or implied as to the suitability of this script for your computing environment. Additionally, this sample script deletes items on the target computers. Use at your own risk. -- Start commanding the local copy of Remote Desktop tell application "Remote Desktop" -- decide which list to perform this on, in this case it's called "Classroom" set these_computers to computer list "Classroom" -- decide what locked screen text you want displayed set screen_message to "Please wait" as Unicode text -- make a UNIX script which executes an AppleScript on the remote computers set the UNIX_script to "osascript -e 'tell application \"Finder\" to delete every item of the desktop whose class is not disk'" -- set the lock task parameters set lock_task to make new lock screen task with properties {name:”Lock Classroom”, message:screen_message} -- perform the task execute lock_task on these_computers -- set the UNIX script parameters set clean_task to make new send unix command task with properties {name:”Clean Desktop”, showing output:false, script:UNIX_script}Chapter 8 Administering Client Computers 159 -- perform the task execute clean_task on these_computers -- empty the trash afterward execute (make new empty trash task) on these_computers -- unlock the screen when finished execute (make new unlock screen task) on these_computers end tell Using Automator with Remote Desktop Accomplish all of your time-consuming, repetitive manual tasks quickly, efficiently, and effortlessly with Automator workflows. It’s simple to create custom workflows just by dragging items, pointing, and clicking. You can easily automate Remote Desktop tasks such as Lock Screen or Install Packages, then repeat those tasks again and again. Simple and easy-to-understand application actions are the building blocks, so you don’t have to write any code. Each actions has all of the options and settings available to you. Here’s the sample AppleScript above, but done using Automator:160 Chapter 8 Administering Client Computers Using Automator actions, you can even create your own interfaces to Apple Remote Desktop functions without having to give users access to Remote Desktop. For instance, say you wanted to give all your teachers a tool to lock and unlock screens in their classrooms. You still need to configure Remote Desktop and set up computer lists, but instead of giving the teachers all access to Remote Desktop, you can create an Automator plug-in or application. This plug-in lets them select only the computers in their classroom, and the plug-in does the rest of the work for them. You can create an Automator workflow, application, Finder plug-in, or iCal alarm similar to the AppleScript mentioned above. By stringing together Remote Desktop actions in Automator, you accomplish the same work as an AppleScript, but without having to write code. 161 A Appendix A Icon and Port Reference The following tables illustrate some of the icons found in the main window of Remote Desktop. The final table shows which network port numbers are in use by Apple Remote Desktop. Client Status Icons The following icons appear next to the names of computers in a scanner search results list. The icons show the status of each computer in the list. Apple Remote Desktop Status Icons The Apple Remote Desktop status icon appears in the menu bar of each Apple Remote Desktop client. The status icon has several states, depending on the status of the client computer. Icon What it means Accessible to Apple Remote Desktop Offline Apple Remote Desktop client Ping response at IP address, but no Apple Remote Desktop client response Icon What it means Not Active Apple Remote Desktop is installed but is not currently running on the client computer. Ready Apple Remote Desktop is installed and running on the client. Administered Apple Remote Desktop is installed and running on the client computer, the administrator is actively observing or controlling, and the client is set to indicate when it is being observed.162 Appendix A Icon and Port Reference List Menu Icons The following icons are used in the Apple Remote Desktop list area of Remote Desktop’s main window. Task Status Icons The following icons are used in task list areas of Remote Desktop’s main window. Icon What it means Master list Apple Remote Desktop list Smart list Scanner Active Task list Task History list Task Server queue Icon What it means Running Finished successfully Exited with error Incomplete Queued ScheduledAppendix A Icon and Port Reference 163 System Status Icons (Basic) The following icons are shown as initial high-level status indicators for observed client computers. System Status Icons (Detailed) The following icons are shown after further inspection of observed client computer status indicators. Icon Indicates or One or more service statistic is red. This takes precedence over any yellow or green indicator. or One or more service statistic is yellow This takes precedence over any green indicator Service is operating within established parameters. No service informaiton available. Service Icon Status CPU Usage Usage is at 60% or less Usage is between 60% to 85% Usage is at 85% or higher No status information is available DIsk Usage Usage is at 90% or less Usage is between 90% and 95% Usage is at 95% or higher No status information is available Free Memory Less than 80% used Between 80% and 95% used164 Appendix A Icon and Port Reference TCP and UDP Port Reference Apple Remote Desktop uses the following TCP and UDP ports for the functions indicated. Over 95% used No status information is available Service Icon Status Port Protocol Function 5900 TCP Observe and Control 5900 UDP Send screen, share screen 3283 TCP Reporting 3283 UDP Everything else 22 TCP Encrypted file transfer, observe, and control (via SSH tunnel) 165 B Appendix B Report Field Definitions Reference The following sections describe the available fields in some of the Apple Remote Desktop reports. For information on generating reports, see “Creating Reports” on page 111. The file search reports (File Search, Software Version, and Software Difference) are not included because their fields closely match those already found in the Finder. System Overview Report List category Field name Notes or example AirPort AirPort Active Yes/No AirPort Firmware Version Version number AirPort Hardware Address 00:30:65:01:79:EC AirPort Locale AirPort Type AirPort Installed Yes/No AirPort Network Channel Channel number 1-11 AirPort Network Name Network name AppleTalk AppleTalk Active Yes/No AppleTalk Network AppleTalk Node AppleTalk Zone Computer Active Processors Number of processors Available user memory Memory in KB Boot ROM ROM version number Bus Clock Speed In MHz Bus Data Size CPU Speed In MHz Serial number 166 Appendix B Report Field Definitions Reference Velocity Engine Yes/No L2 Cache Size In KB L3 Cache Size In KB Machine Model Memory In KB Empty RAM Slots PCI slots Used Processor Count CPU Type Internal value Sales Order Number VM Size Total RAM Slots Devices ATA Device Count Firewire Device Count Keyboard Connected Mouse Connected Optical Drive Type SCSI Device Count USB Device Count Display 2nd Monitor Depth In bits 2nd Monitor Type 2nd Monitor Resolution Pixels horizontal and vertical Monitor Depth In bits Monitor Type Monitor Resolution Pixels horizontal and vertical Modem Modem Country Modem Driver Modem Firmware Version Modem Installed Yes/No Modem Interface Modem Model Network First Ethernet Address en0 MAC address NetBooted Yes/No Primary IP Address Primary Network Collisions Primary Network Flags List category Field name Notes or exampleAppendix B Report Field Definitions Reference 167 Primary Network Hardware Address Primary Network Input Errors Primary Network Input Packets Primary Network Output Errors Primary Network Output Packets Primary Network Preferences Sleep Display Yes/No Sleep Hard Disk Yes/No Sleep Computer Yes/No Wake for Ethernet Access Yes/No Printing Printer Name Printer Sharing Yes/No Printer Type Printer Version Remote Desktop Computer Info #1 Computer Info #2 Computer Info #3 Computer Info #4 Sharing Computer Name File sharing name, “Bob’s Computer” FTP Access Yes/No Remote AppleEvents Yes/No Remote Login Yes/No UNIX hostname foo.example.com Web Sharing Yes/No Windows Sharing Yes/No Software Kernel Version System Version Mac OS X v10.4.2 (8C46) Storage Free Disk Space In KB, MB, or GB Total Disk Space In KB, MB, or GB Trash Size In KB, MB, or GB List category Field name Notes or example168 Appendix B Report Field Definitions Reference Storage Report List category Field name Notes or example Hardware Options Drive Manufacturer Drive Model Drive Revision Drive Protocol Removable Yes/No Serial Number Logical Unit Number Detachable Volume Options Creation date UNIX GMT format Disk Name Macintosh HD File Count Folder Count Total Disk Space Free Space In KB, MB, or GB Startup Disk UNIX Mount Point /dev/disk0s10 File System Options Disk Format HFS, HFS+, UFS Owner Group Yes/No Permission Modes Permissions Yes/No Write Access Modification date UNIX GMT format Case Sensitive Yes/No Preserves Case Yes/No Backup Options Journaling Capable Yes/No Journaled Yes/No Last Backup date UNIX GMT format Last Check date UNIX GMT formatAppendix B Report Field Definitions Reference 169 USB Devices Report FireWire Devices Report Memory Report PCI Cards Report Field name Notes or example Product Name Product ID Vendor ID Vendor Name Device Speed 1.5Mb, 12Mb Bus Power In mA Date collected Field name Notes or example Device Speed 200, 400, 800 Mbits per second Software Version Manufacturer Model Firmware Revision Date collected Field name Notes or example Slot Identifier DIMM0/J21 Size In MB Speed PC133-222 (Mac OS X 10.3 only) Type SDRAM Date collected Field name Notes or example Card Name Slot Name Slot4 Card Type Display Vendor ID Device ID170 Appendix B Report Field Definitions Reference Network Interfaces Report ROM Revision Displays only Card Revision Card Memory Displays only Date collected Field name Notes or example List category Field name Notes or example Network Overview Name Location name Active Yes/No Primary Yes/No Configured With Ethernet Hardware Address 00:30:65:01:79:EC Interface Name en0 Flags Active Interface Domain example.com Router Address IP Address Broadcast Address DNS Server Subnet Mask IP Addresses Broadcast Addresses DNS Servers Subnet Masks Network Statistics Network Collisions Network Input Errors Network Input Packets Network Output Errors Network Output Packets Output Statistics Output Queue Capacity Output Queue Size Output Queue Peak Size Output Queue Drop Count Output Queue Output Count Output Queue Retry CountAppendix B Report Field Definitions Reference 171 Output Queue Stall Count Ethernet Statistics Ethernet Alignment Errors Ethernet FCS Errors Frame Check Sequence errors Ethernet Single Collision Frames Ethernet Multiple Collision Frames Ethernet SQE Test Errors “heartbeat” test errors Ethernet Deferred Transmissions Ethernet Late Collisions Ethernet Excessive Collisions Ethernet Internal MACTransmit Errors Ethernet Carrier Sense Errors Ethernet Frame Too Long Ethernet Internal Mac Receive Errors Ethernet Chip Set Ethernet Missed Frames Ethernet Receiver Overruns Ethernet Receiver Watchdog Timeouts Ethernet Receiver Frame Too Short Ethernet Receiver Collision Errors Ethernet Receiver PHY Errors Ethernet Receiver Timeouts Ethernet Receiver Interrupts Ethernet Receiver Resets Ethernet Receiver Resource Errors Ethernet Transmitter Underruns Ethernet Transmitter Jabber Events Ethernet Transmitter PHY Errors Physical Errors Ethernet Transmitter Timeouts Ethernet Transmitter Interrupts Ethernet Transmitter Resets List category Field name Notes or example172 Appendix B Report Field Definitions Reference Network Test Report Administration Settings Report Ethernet Transmitter Resource Errors Ethernet Collision Frequencies List category Field name Notes or example Field name Notes or example Computer Computer sharing name Min,. Time Shortest time for ping response Max. TIme Longest time for a ping response Avg. Time Average time for ping response Lost Packets Number of pings without a response Total Packets Number of pings sent. List category Field name Notes or example Computer Computer sharing name Privileges Generate Reports On or off Send Messages On or off Open & Quit On or off Restart & Shutdown On or off Change Settings On or off Copy Items On or off Delete Items On or off Control On or off Observe On or off Show Observe On or off Data Settings Collect Application Usage Data On or off Collect User Accounting Data On or off Upload Schedule Time and days to upload information Upload System Data On or off Upload File Data On or off Upload Application Usage Data On or off Upload User Accounting Data On or offAppendix B Report Field Definitions Reference 173 Application Usage Report User History Report General Version Apple Remote Desktop version and build number Last Contacted Relative date List category Field name Notes or example Field name Notes or example Computer name File sharing computer name Name Application name Launch date 24 hour local time and date Total run time Length of time the application was running Frontmost Length of time the application was the frontmost application User name Short user name of application process owner State What the application is doing now (running, terminated, etc.) Field name Notes or example Computer name file sharing computer name User name Login type) Console, tty, ssh Login time Date and 24 hour format local time Logout time Date 24 hour format local time Remote Login Host Originating host to the login session, localhost, or some remote computer174 C Appendix C AppleScript Remote Desktop Suite This appendix shows the contents of Remote Desktop’s AppleScript Dictionary. This appendix is not a substitute for the AppleScript Dictionary view in Script Editor. It is included as a quick reference so that AppleScript commands might be found by a search of PDF contents. The Dictionary itself has the most recent information about scriptable objects and events in Remote Desktop, and better usability. Classes and Commands for the Remote Desktop Application. add v: Add a computer to a task. add computer: The computer. to computer list: The computer list (or task) to add the computer to. control v: Start a control session with the computer. control computer: The computer to control. execute v: Executes a task. execute task: The task to execute. [on computer list]: The computer list (or computer) on which to run the task. observe v: Start an observation session. observe item: The computer, list, or computer list to observe. release v: Release computers from a control or observation session. release item: The computer, list, or computer list to release. remove v: Remove a computer from a task. remove computer: The computer to remove. from computer list: The computer list (or task) to remove the computer from. stop v: Stops an executing share screen task. stop task: The task to stop.Appendix C AppleScript Remote Desktop Suite 175 application n [inh. application; see also Standard Suite]: Remote Desktop’s top level scripting object. ELEMENTS contains computers, computer lists, copy items tasks, copy to me tasks, documents, empty trash tasks, install package tasks, lock screen tasks, logout tasks, open application tasks, open item tasks, rename computer tasks, restart tasks, send message tasks, send unix command tasks, set local startup disk tasks, set network startup disk tasks, share screen tasks, shutdown tasks, sleep tasks, unlock screen tasks, upgrade client tasks, wake up tasks, windows. PROPERTIES selection (item, r/o): The current selection. computer n [inh. item]: A physical computer. ELEMENTS contained by application, computer lists. PROPERTIES boot volume (Unicode text, r/o): The boot volume of the computer. CPU (Unicode text, r/o): The CPU type of the computer. current application (Unicode text, r/o): The current frontmost application on the computer. current user (Unicode text, r/o): The currently logged in user on the computer. DNS name (Unicode text, r/o): The DNS name of the computer. id (Unicode text, r/o): The unique identifier (UUID) of the computer. Internet address (Unicode text, r/o): The Internet address of the computer. last activity (date, r/o): The time of the most recent activity on the computer. last contacted (date, r/o): The time of last contact with the computer. machine model (Unicode text, r/o): The model of the computer. name (Unicode text, r/o): The name of the computer. physical memory (Unicode text, r/o): The physical ram installed in the computer. primary Ethernet address (Unicode text, r/o): The primary ethernet address of the computer. remote desktop version (Unicode text, r/o): The version of the Remote Desktop client running on the computer. status message (Unicode text, r/o): The current status of the computer. system version (Unicode text, r/o): The Mac OS version running on the computer. computer list n [inh. item]: A list which holds computers. ELEMENTS contains computers; contained by application. PROPERTIES id (Unicode text, r/o): The unique identifier (UUID) of the computer list. name (Unicode text): The name of the computer list.176 Appendix C AppleScript Remote Desktop Suite copy items task n [inh. task > item]: Copy items to the target computers. ELEMENTS contained by application. PROPERTIES bandwidth limit (integer): Network usage limit in kilobytes per second (0 = unlimited). conflict resolution (ask what to do/rename the existing item/rename the item being copied/replace/replace if older): Specifies what to do if the item(s) already exist in this location. copy items (list): A list of files and/or folders to copy. destination group (Unicode text): If ownership is set to a ‘specific owner’, a valid group name on the destination computer. destination owner (Unicode text): If ownership is set to a ‘specific owner’, a valid user name on the destination computer. destination path (alias): If the location is ‘specific folder’, a fully specified path to the destination folder. encrypting (boolean): Should the items be encrypted during copying location (applications folder/current users desktop folder/current users home directory/ same relative location/specific folder/system folder/system fonts folder/system preferences folder/top folder of the boot disk): The target location to copy to. ownership (current console user/current owner/destination folder owner/specific owner): Specifies the new ownership of the copied item(s). should open (boolean): Should the items be opened after being copied stopping on error (boolean): Should the copy terminate if an error occurs during copying copy to me task n [inh. task > item]: Copy items from the target computers to the administrator computer. ELEMENTS contained by application. PROPERTIES bandwidth limit (integer): Network usage limit in kilobytes per second (0 = unlimited). conflict resolution (ask what to do/rename the existing item/rename the item being copied/replace/replace if older): Specifies what to do if the item(s) already exist in this location. copy items (list): A list of files and/or folders to copy. destination path (alias): If the location is ‘specific folder’, a fully specified path to the destination folder. encrypting (boolean): Should the items be encrypted during copying location (applications folder/current users desktop folder/current users home directory/ same relative location/specific folder/system folder/system fonts folder/system preferences folder/top folder of the boot disk): The target location to copy to.Appendix C AppleScript Remote Desktop Suite 177 empty trash task n [inh. task > item]: Empty the trash on the target computers. ELEMENTS contained by application. install package task n [inh. task > item]: Install package(s) on the target computers. ELEMENTS contained by application. PROPERTIES after installing (attempt restart/do nothing/force immediate restart): Specifies what to do after installing the package(s). bandwidth limit (integer): Network usage limit in kilobytes per second (0 = unlimited). delegating to task server (boolean): Should this task be delegated to the task server encrypting (boolean): Should the packages be encrypted during copying packages (list): A list of packages to install. stopping on error (boolean): Should the copy terminate if an error occurs during copying lock screen task n [inh. task > item]: Lock the screen(s) on the target computers. ELEMENTS contained by application. PROPERTIES message (Unicode text): Message to display on the screen(s). logout task n [inh. task > item]: Log out the current user on the target computers. ELEMENTS contained by application. open application task n [inh. task > item]: Launch an application on the target computers. ELEMENTS contained by application. PROPERTIES application (alias): The path to the application to open. open item task n [inh. task > item]: Open files on the target computers. ELEMENTS contained by application. PROPERTIES files (list): A list of files to open. rename computer task n [inh. task > item]: Change the name of the target computers. ELEMENTS contained by application. PROPERTIES178 Appendix C AppleScript Remote Desktop Suite naming uniquely (boolean): Should each machine be forced to have a numerically unique name target name (Unicode text): The new name for the computer. restart task n [inh. task > item]: Restart the target computers. ELEMENTS contained by application. PROPERTIES user can save changes or cancel (boolean): Is the user allowed to save changes or cancel the restart send message task n [inh. task > item]: Send a text message to the target computers. ELEMENTS contained by application. PROPERTIES message (Unicode text): Message to display on the screen(s). send unix command task n [inh. task > item]: Send a UNIX command or script to the target computers. ELEMENTS contained by application. PROPERTIES script (Unicode text): The command string to be executed. showing output (boolean): Should the complete output of command be displayed in a window user (Unicode text): The user to execute the command as. set local startup disk task n [inh. task > item]: Set the startup volume on the target computers. ELEMENTS contained by application. PROPERTIES boot volume (Unicode text): Specific volume of drive to boot (optional). restarting (boolean): Should the machine be restarted after setting the startup volume set network startup disk task n [inh. task > item]: Set the startup volume on the target computers. ELEMENTS contained by application. PROPERTIES from server (Unicode text): Internet address of the server to boot from. mount volume (Unicode text): Volume name on server to mount. restarting (boolean): Should the machine be restarted after setting the startup volume Appendix C AppleScript Remote Desktop Suite 179 share screen task n [inh. task > item]: Share a computers screen to the target computers. ELEMENTS contained by application. PROPERTIES source computer (computer): The computer (other than the admin) whose screen to share. shutdown task n [inh. task > item]: Shutdown the target computers. ELEMENTS contained by application. PROPERTIES user can save changes or cancel (boolean): Is the user allowed to save changes or cancel the shutdown sleep task n [inh. task > item]: Put the target computers to sleep. ELEMENTS contained by application. task n [inh. item]: A task. This abstract class represents the tasks which can be executed by Remote Desktop. There are subclasses for each specific type of task. ELEMENTS contained by application. PROPERTIES computer list (computer list): The computer list associated with the task. id (Unicode text, r/o): The unique identifier (UUID) of the computer. name (Unicode text): The name of the task. recurrence (Unicode text, r/o): A string which describes the task recurrence, if defined. starting at (date): If the task is scheduled, the date and time of the first execution. unlock screen task n [inh. task > item]: Release the screen(s) of the target computers. ELEMENTS contained by application. upgrade client task n [inh. task > item]: Upgrade the Remote Desktop client on the target computers. ELEMENTS contained by application. wake up task n [inh. task > item]: Wake up the target computers. ELEMENTS contained by application.180 D Appendix D PostgreSQL Schema Sample This chapter contains SQL commands to assist SQL programmers in obtaining the database schema used in Apple Remote Desktop’s report database. You can use this knowledge about the schema to create your own applications that access Apple Remote Desktop report information. Sample list of main database schema Command: /System/Library/CoreServices/RemoteManagement/rmdb.bundle/bin/psql -U ard -c "\\d propertynamemap" ard Output: Table "public.propertynamemap" Column | Type | Modifiers ---------------+------------------------+----------- objectname | character varying(128) | not null propertyname | character varying(128) | not null propertymapid | integer | Sample list of system information table Command: /System/Library/CoreServices/RemoteManagement/rmdb.bundle/bin/psql -U ard -c "\\d systeminformation" ard Output: Table "public.systeminformation" Column | Type | Modifiers --------------+--------------------------+----------- computerid | character(17) | not null objectname | character varying(128) | not null propertyname | character varying(128) | not null itemseq | integer | value | character varying(512) | Appendix D PostgreSQL Schema Sample 181 lastupdated | timestamp with time zone | Sample list of property names Command: /System/Library/CoreServices/RemoteManagement/rmdb.bundle/bin/psql -U ard -c "select * from propertynamemap" ard Output: objectname | propertyname | propertymapid -----------------------+------------------------------+--------------- Mac_SystemInfoElement | WirelessCardIsActive | 0 Mac_SystemInfoElement | WirelessCardFirmwareVersion | 1 Mac_SystemInfoElement | WirelessCardHardwareAddress | 2 Mac_SystemInfoElement | WirelessCardLocale | 3 Mac_SystemInfoElement | WirelessCardType | 4 Mac_SystemInfoElement | WirelessCardInstalled | 5 Mac_SystemInfoElement | WirelessChannelNumber | 6 Mac_SystemInfoElement | WirelessNetworkAvailable | 7 Mac_SystemInfoElement | WirelessIsComputerToComputer | 8 ...... Sample list of table from one computer Command: /System/Library/CoreServices/RemoteManagement/rmdb.bundle/bin/psql -U ard -c "select * from systeminformation" ard Output: computerid | objectname | propertyname | itemseq | value | lastupdated -------------------+----------------------+-----------------+---------+----- ----------------+------------------------ 00:03:93:af:15:cc | Mac_HardDriveElement | CreationDate | 0 | 2005-02-25T03:30:07Z| 2005-02-26 22:21:38-08 00:03:93:af:15:cc | Mac_HardDriveElement | FileSystemType | 0 | 18475 | 2005-02-26 22:21:38-08 00:03:93:af:15:cc | Mac_HardDriveElement | FreeSpace | 0 | 4101610 | 2005-02-26 22:21:38-08 00:03:93:af:15:cc | Mac_HardDriveElement | GroupName | 0 | admin | 2005-02-26 22:21:38-08Index 182 Index A aborting a task 98 access changing privileges 69 group-based 62 via local account 61 Access Privileges 59 adding Dock items 131 administrator announce 92 Apple keyboard keys 79 Apple Remote Desktop menu icon 94, 95 application use report 115 asset tracking application use 115 FireWire devices 121 hardware 119 management 118 memory 123 PCI cards 123 software 118 software changes 118 USB devices 121 B basic file copy 108 best practices networking 71 reporting 113–114 security 73 C chat 92 cleaning up hard disks 128 client data upload policy 152 clipboard sharing 82 computer audio volume 130 computer list making a new 54 removing 54 smart 54 computer lists 49 description of 53 computer sharing names 129 Control/Observe preferences 36 controlling a client 78 control window 32 buttons 79–82 Copy and Open 108 copying items data encryption 107 overview 106 UNIX permissions 107 copying to relative locations 107 Copy Items options 107 CPU serial number, accessing 120 Create Custom Installer 43, 44 curtain mode 81, 140 customizing reports 35 D Dashboard observe 91 deleting files 128 demonstration mode 93 designated data collector 112 directory services 62 drag and drop copies 109 installation 104 E enabling SSH on clients 133 encryption one-time use 76 scheme description 75 setting defaults 75 Ethernet address tracking 122 F file mirroring 110 file system maintenance 131 finding free disk space 120 firewall settings 49 full screen display 81Index 183 G General preferences 36 group-based authorization 65 guest access 65 H hard disk maintenance 131 hardware asset management 119 Help Desk Mode. See sharing control human interface customizing 36 icons 29 tips and shortcuts 37 I installation, Remote Desktop 40 Install Packages options 107 K keyboard shortcut exceptions 78 kickstart tool 147, 151 L launching remote applications 136 limiting access privileges 66 limiting features to administrators 66 logging in remote users 140 logging out users 141 M main window 29 Managed Client settings 46 mcx_setting attribute 62, 64 metadata search 116 mirroring a folder 110 moving computer lists 56–57 multi-observe 85, 91 window 33 muting a computer 130 N NetBoot 128 networking best practices 71 networking with AirPort 72 Network Install 128 network interface audit 122 network performance tuning 73 networksetup tool 147 Network Time Protocol (NTP) server 129 notification script 97 O observation settings 87, 88 Observe Widget 91 observe window 32, 33 offline installation 103 Open Directory 62 P package installation 101, 105 preferences 36 preference standardization 133 printer setup 133 Property List Editor tool 62 putting wired clients to sleep 137 Q quitting applications 137 R reclaiming hard disk space 127 Remote 42 removing client software 47, 48 removing files 127 removing Remote Desktop 46 renaming copied items 108 multiple computers 129 repairing UNIX permissions 131 replacing copied items 108 report access privileges 69 Application Usage 115 File Search 117 Software Difference 118 Software Version 118 System Overview 119 User History 114 report data sources 111 reporting best practices 113–114 reporting policy template 153 report window 34 restarting client computers 141 reusing tasks 99, 100 S saving reporting policy preferences 153 saving reports 125 saving settings 99 saving tasks 99, 100 scan file import 52 IP range 50, 52 LAN 50 scanner display 49 scanners 49 screen pushing 93 screen sharing console 94 Scripting Remote Desktop AppleScript 156–159184 Index Automator 159 Secure Screen Blanking. See curtain mode. security best practices 73 preferences 36 sending scripts via UNIX command 145–147 serial number 40 setting boot disk 128 setting encryption defaults 75 setting Energy Saver preferences 132 setting up a Task Server 154 setting wake-on-LAN 132 sharing control 80 Sharing Preference 59 sharing screens 93 software installation 101 software version report 105 Spotlight search 116 SSH access description 68 start VNC server 68 system requirements 39 systemsetup tool 132, 133, 147, 149 T task history 96 task progress 96, 98 task results 99 task schedules 155 Task Server data collection 112 Install Package 103 preferences 36 setup 154 task status 98 task templates saving 100 UNIX commands 143 templates UNIX commands 143 temporary access 65 testing network performance 124–125 text announce 92 text chat 92 third-party installers 104 Tiger-only features Spotlight search 116 tips using report windows 126 using the observe window 90 tracking. See asset tracking. trashing files 127, 128 U uninstalling client software 47, 48 uninstalling Remote Desktop 46 unique computer names 129 UNIX command templates 143 updating software 118 upgrading client software 42 Remote Desktop 41 user history report 114 user interface. See human interface. user login report 114 user mode 66 user requests, viewing 93 using a time server 129 V VNC 67 connecting to server 82 Control-Alt-Delete 83 custom display designation 84 Mac OS X Client as VNC server 85 non–Mac OS X basic set-up 83 port customization 84 W wakeonlan packet 138 waking wired clients 138 window, shortcuts 37 Workgroup Manager 46, 131 X XML 64 Finger Tips Quick Start Guide Welcome to iPhone. This Quick Start guide tells you how to set up your iPhone and use its key features. To start, turn on your iPhone by pressing and holding the On/Off button for a few seconds. Then follow the onscreen instructions to set up your iPhone. Button basics. To turn off or restart iPhone, press and hold the On/Off button for a few seconds, then drag the slider to confirm. To turn off the screen but still receive calls, press On/Off once. Press the Home button at any time to return to the Home screen. To quickly switch between recently used apps, double-click the Home button and tap an app icon. Voice Control. Use Voice Control to make a hands-free call or play music. To activate Voice Control, hold down the Home button or the center button on the iPhone headset until the Voice Control screen appears. After the tone, speak a command such as “call Elliot” or “dial 555-1212.” You can also ask iPhone to play a specific album, artist, or playlist or to “play more songs like this.” You can even ask iPhone “what’s playing?” or say “play songs by the Rolling Stones,” for example. Notifications. When you receive a notification, it appears briefly at the top of the screen without interrupting what you’re doing. Ignore it or tap it to respond right away. To see a summary of your recent notifications, swipe down from the top of any screen. You can access a new notification from the Lock screen by sliding its icon to the right. Messages. Tap the Messages icon to send an iMessage to other iPhone, iPad, and iPod touch users running iOS 5, or to send an SMS or MMS to other mobile phone users. Type a name or phone number in the To field or select someone from your contacts. Type your message, then tap Send. To send photos or video, tap the Camera button. Make a call. Tap a phone number in Contacts, Favorites, an email, a text message, or almost anywhere in iPhone to make a call. Or open the Phone app and tap the Keypad button to dial manually. To silence an incoming call, press the On/Off button once. To send a call directly to voicemail, press On/Off twice. To answer a call while using the iPhone headset, press the center button once. Press it again to end your call. Search. To search your iPhone or the web, go to the main Home screen and press the Home button or swipe the screen from left to right. Type in what you’d like to find—a name, app, song, artist, movie, or any keyword. iPhone offers suggestions as you type to make searching even faster. To search within an app like Mail, Contacts, or Messages, tap the status bar. Intelligent keyboard. iPhone automatically corrects and suggests words as you type. So if you tap a wrong letter, just keep typing. To accept the suggested word, tap the space bar. Or tap the “x” to ignore the suggestion. The keyboard automatically inserts apostrophes in contractions. If you tap the space bar twice, it adds a period. You can double-tap a word to look it up in the dictionary. Cut, copy, and paste. Tap the text you want to edit, or touch and hold to bring up the magnifying glass, then slide your finger to move the insertion point. You can select a word by double-tapping it, and select more or less text by dragging the grab points. Then tap to cut, copy, or paste. To copy text from web pages, email, or text messages, touch and hold to select the text, then tap Copy. On/Off Sleep/Wake Ring/Silent Volume Up/Down HomeNot all features are available in all areas. TM and © 2011 Apple Inc. Designed by Apple in California. Printed in China. 034-6177-A Learn more. Learn more about iPhone features at www.apple.com/iphone. For the iPhone User Guide and important information, visit support.apple.com/manuals/ iphone. To view the guide on iPhone, download it from the iBookstore or use the Safari bookmark. Get support. Contact your wireless service provider for support on network services, voicemail, and billing. Visit www.apple.com/support/ iphone for support on iPhone and iTunes. Photos. Tap the Photos icon on the Home screen to see your pictures. Flick right or left to move between images. Double-tap or pinch to zoom. Tap once to bring up the onscreen controls. You can edit or enhance a photo, share it, print it, and more. If you have Photo Stream enabled in iCloud, new pictures you take are automatically pushed to all your other devices. Cars 2 will be available on iTunes beginning November 1, 2011. Cars 2 © Disney/Pixar. *Requires second-generation Apple TV. Video and song controls. While playing music or watching a movie, tap anywhere on the screen to bring up the controls. Tap again to hide them. To stream your music or video to an Apple TV, tap the AirPlay button.* From the Lock screen, you can double-click the Home button to quickly access your audio controls. See the web up close. In Safari, double-tap any element on a web page—picture or text—to zoom in. Doubletap again to zoom back out. Rotate iPhone to see the web in widescreen. Tap the Reader button at the top of the screen to view an article without clutter. Tap the Multi-page button to flick between multiple web pages or open a new one. Google, the Google logo, and Google Maps are trademarks of Google Inc. © 2011. All rights reserved. Find location. Search surroundings. To see where you are on a map, tap the Location button. A blue dot appears at your current position. To see which way you’re facing, tap the Location button again to turn on compass view. Find places around you by typing words like “Starbucks” or “pizza” in the search field. Double-tap to zoom in. Tap once with two fingers to zoom out. You can also get directions or tap the Page Curl button for additional map views. App Store. Tap the App Store icon to browse hundreds of thousands of apps in categories like games, business, travel, social networking, and more. Browse by Featured, Categories, or Top 25 or search by name. To purchase and download an app directly to your iPhone, tap Buy Now. Many apps are free. iTunes Store. You can access the iTunes Store by tapping the iTunes icon. Search the store for music, movies, TV shows, music videos, and more. Browse, purchase, and download from the store directly to your iPhone. Tap any item to hear or see a preview. Create folders. Organize apps. Touch and hold any app icon until it starts to jiggle. Then drag one app onto another to create a folder. Folders are automatically named by category, or you can rename them. You can customize your Home screen by dragging apps and folders to different positions and screens. When you’re done, press the Home button. Get directions. In Maps, tap Directions, then enter start and end points. You can use your current location, type in an address, or select an address from your contacts or bookmarked locations. Tap Route to display driving directions. Tap the Walk button for walking directions or the Bus button to view transit routes and times. iPhone can track and show your progress along whichever route you take. iCloud. iCloud stores your music, photos, apps, calendars, documents, and more. It’s seamlessly integrated into your apps and wirelessly pushes your content to all your devices. Tap the Settings icon and choose iCloud to turn on Photo Stream and other iCloud features. You can also download music and apps you’ve previously purchased from the iTunes Store and the App Store. This guide contains all the information you need to get from setup to your sofa. Welcome. You’re watching Apple TV.Contents 3 Contents Chapter 1: Connect. 7 What’s in the Box 8 Apple TV at a Glance 10 What You Need 11 Setting Up Apple TV Chapter 2: Configure. 16 Network Configuration 17 Connecting to iTunes Chapter 3: Watch. 20 Using Your Apple Remote 21 Basic Remote Functions 21 Pairing Apple TV with a Remote 22 Unpairing Apple TV from a Remote 23 Changing the Remote Battery 24 Renting Movies and Purchasing TV Shows4 Contents Chapter 4: Problem? No Problem. 26 Troubleshooting 31 Status Light 32 Service and Support 32 Serial Number 33 Care and Cleaningwww.apple.com/support/appletv Connect. 16 Chapter 1 Connect. Chapter 1 Connect. With Apple TV, you can rent high-definition movies, purchase TV shows, watch streaming content from Netflix, and enjoy podcasts, YouTube and Vimeo videos, and Internet radio. And, you can stream your personal iTunes content wirelessly from a Mac or PC, and view photos from your computer or Flickr on your widescreen HDTV, from the comfort of your couch. And with AirPlay, you can wirelessly stream videos, music, and photos from your iPhone, iPad, and iPod touch to Apple TV. Note:  Content availability varies by region. For information about See What you need to get started “What You Need” on page 10 Setting up Apple TV “Setting Up Apple TV” on page 11 Setting up your network connection “Network Configuration” on page 16 Using the Apple Remote “Using Your Apple Remote” on page 20 Troubleshooting Apple TV “Troubleshooting” on page 26 Apple TV safety and warranty The Apple TV Important Product Information GuideChapter 1 Connect. Chapter 1 Connect. 7 What’s in the Box AC power cord Apple Remote Note:  Your power cord may look different from the one pictured here.8 Chapter 1 Connect. Chapter 1 Connect. Apple TV at a Glance IR receiver Status light £ HDMI port d Micro USB port Optical digital audio port Power port G Ethernet portChapter 1 Connect. Chapter 1 Connect. 9 IR receiver Use with the included Apple Remote to control Apple TV. Status light The status light flashes slowly when Apple TV starts up.When Apple TV is on, the status light glows. See “Status Light” on page 31. d Micro USB port For service and diagnostics. ≤ Power port Connect the included AC power cord to the power port on Apple TV. G Ethernet port If your network is Ethernet-based, connect an Ethernet cable. £ HDMI port Connect Apple TV to the HDMI port of a high-definition TV using an HDMI cable. Optical digital audio port Connect Apple TV to a home theater receiver that has an optical digital audio port, using an optical digital audio (also called S/PDIF or TOSLINK) cable. Z Built-in 802.11n Wi-Fi technology Connect Apple TV to your wireless network.10 Chapter 1 Connect. Chapter 1 Connect. What You Need To start using Apple TV, you need the following: High-Definition TV A high-definition TV capable of displaying 720p video Cables  An HDMI cable to connect Apple TV to your TV  An optical digital audio cable (if you plan to use one) Network  An 802.11b, g, or n Wi-Fi wireless network (wireless video streaming requires 802.11g or 802.11n), or 10/100Base-T Ethernet network  A broadband Internet connection (DSL, cable, or LAN)  Your wireless network name and password (if you use one) Software and Accounts To play content from a Mac or PC on Apple TV, you need the following:  An Apple ID to rent movies or purchase TV shows from the iTunes store, and to use Home Sharing to stream content from a Mac or PC  iTunes 10.2 or later  A Netflix account to stream contentChapter 1 Connect. Chapter 1 Connect. 11 Setting Up Apple TV Apple TV connects to your TV through an HDMI port that delivers both audio and video. Before you set up Apple TV, look at the ports on the back of your TV to make sure you have the right cables. You can connect Apple TV to a high-definition TV or home theater receiver that has an HDMI port, using an HDMI cable for both video and audio. You can also use an optical digital audio cable to connect Apple TV to a receiver for audio. Important:  Before you connect Apple TV to a power outlet, carefully read these installation instructions and the safety information in the included Important Product Information Guide.12 Chapter 1 Connect. Chapter 1 Connect. Step 1: Connecting the cables 1 Connect one end of an HDMI cable to the back of your TV. 2 Connect the other end of the cable to the HDMI port on the back of Apple TV. 3 If you’re using an optical digital audio cable for audio, connect one end of the cable to the audio input port on your receiver or TV, and the other end to the optical digital audio port on the back of Apple TV. Apple TV Television HDMI port HDMI port HDMI cable Note:  The built-in 802.11 Wi-Fi technology connects Apple TV to your wireless network. If your network is Ethernet-based, connect Apple TV to your network using an Ethernet cable.Chapter 1 Connect. Chapter 1 Connect. 13 Step 2: Connect the power cord Connect one end of the power cord to the power port on the back of Apple TV and the other end to a power outlet. Power port Important:  Don’t place anything on top of Apple TV. Objects placed on top may interfere with the wireless signal. Don’t place Apple TV on other electronic equipment in a media cabinet. Step 3: Turn on your TV and select the input The first time you use Apple TV, it helps you choose a language, select a network, and configure Apple TV to work with your network (if necessary). See Chapter 2, “Configure.” on page 15. If you see just a black screen the first time you use Apple TV, make sure the input setting you’ve selected on your TV matches the input you connected the cables to on your TV or home theater receiver. See Chapter 4,“Problem? No Problem.” on page 25, and refer to the documentation that came with your TV for information about its inputs.www.apple.com/support/appletv Configure. 216 Chapter 2 Configure. Chapter 2 Configure. Apple TV helps you select and configure your wireless network connection, and, if you want to watch or listen to the contents of your iTunes library, connect to iTunes on your computer. Network Configuration Have your network name and password (if you use one) and your Apple Remote handy when you configure Apple TV. Make sure there are no obstructions between the remote and Apple TV. For information about using your remote, see Chapter 3,“Watch.” on page 19. If you:  Use a wired Ethernet network to connect, Apple TV automatically detects your network.  Use a wireless network to connect, Apple TV helps you select and configure your network connection. Connecting to Your Wireless Network Apple TV helps you connect to your wireless network. If you use a name and password to access your network, have them ready. Use the Apple Remote to: 1 Select your network from the list, or enter your network name if the network is hidden. 2 Enter your network password (if you use one).Chapter 2 Configure. Chapter 2 Configure. 17 If you don’t connect using DHCP, you may need to enter your IP address, subnet mask, router address, and DNS address. To complete the network connection, follow the onscreen instructions. Connecting to iTunes To access the content in your iTunes library on Apple TV, you need iTunes 10.2 or later installed on your computer. For a complete list of system requirements, see “Software and Accounts” on page 10. Updating Your iTunes Software You can update to the latest version of iTunes.  On a Mac, use Software Update to update to the latest version of iTunes. To use Software Update, choose Apple () > Software Update.  On a Windows-based computer, go to iTunes Help to update to the latest version of iTunes. Open iTunes, and then choose Help > Check for Updates. Setting Up Home Sharing After you set up your network connection, you need to set up iTunes and Apple TV to share the contents of your iTunes library. Use Home Sharing in iTunes and on Apple TV to share the iTunes library of any computer on your local network that has Home Sharing set up.18 Chapter 2 Configure. To set up Home Sharing in iTunes: 1 Open iTunes on your computer. 2 Choose Advanced > Turn On Home Sharing. 3 Type your Apple ID and password, and then click Create Home Share. 4 Repeat steps 1 through 3 on each computer you want to use for Home Sharing. For more information about iTunes, open iTunes and choose Help > iTunes Help. To set up Home Sharing on Apple TV: 1 On Apple TV, choose Settings > Computers. 2 Choose Turn On Home Sharing, and then enter the same Apple ID and password you entered on your computer.www.apple.com/support/appletv Watch. 320 Chapter 3 Watch. Chapter 3 Watch. Read on to learn about pairing and using your Apple Remote with Apple TV. Using Your Apple Remote Use the Apple Remote to control Apple TV settings and navigate your content. Make sure there are no obstructions between the remote and Apple TV. MENU Up Down Menu Play/Pause Left Right SelectChapter 3 Watch. Chapter 3 Watch. 21 Basic Remote Functions Your Apple Remote has the basic functions described below. To Do this Move through the menu options Press Up, Down, Left, or Right Select an option from a menu Press Select Return to a previous menu Press Menu Return to the main menu Hold down Menu Reset Apple TV Hold down Menu and Down until the Apple TV status light blinks rapidly Pair Apple TV and a remote Hold down Menu and Right for 6 seconds Up and Down on the Apple Remote don’t control the volume on your TV or home theater receiver. Use the remote that came with your TV or receiver to change the volume. Pairing Apple TV with a Remote The Apple Remote works with the built-in IR receiver on Apple TV. You can set Apple TV to work only with the included remote by pairing Apple TV and the remote.22 Chapter 3 Watch. Chapter 3 Watch. To pair Apple TV with the included remote: 1 Choose Settings from the Apple TV main menu. 2 Choose General > Remotes > Pair Apple Remote. You can also hold down Menu and Right for 6 seconds to pair Apple TV and the Apple Remote. When you successfully pair your Apple Remote, Apple TV displays a chainlink symbol ( ) above a picture of a remote. Apple TV now works only with the paired remote. Unpairing Apple TV from a Remote If you lose the Apple Remote that you paired Apple TV with, you can use any Apple Remote to unpair Apple TV from the lost remote by holding down Menu and Left for 6 seconds. You can also follow these steps. To unpair Apple TV from a paired remote: 1 Choose Settings from the Apple TV main menu. 2 Choose General > Remotes > Unpair Apple Remote. When you successfully unpair the lost remote, Apple TV displays a broken chainlink symbol ( ) above a picture of a remote. You can now pair Apple TV with a different remote.Chapter 3 Watch. Chapter 3 Watch. 23 Changing the Remote Battery When the battery charge in your Apple Remote is low, Apple TV displays a picture of a remote and a warning symbol (·). Replace the battery with a CR2032 battery. Battery compartment To replace the battery: 1 Use a coin to remove the battery compartment cover. 2 Remove the battery. 3 Insert a CR2032 battery with the positive side (∂) facing up. 4 Replace the battery compartment cover and use a coin to tighten it. Important:  Dispose of the used battery according to your local environmental laws and guidelines.24 Chapter 3 Watch. Renting Movies and Purchasing TV Shows You can rent standard or high-definition movies and purchase TV shows directly on Apple TV (where available). Follow the onscreen instructions to find out when a rented movie expires. Purchased TV shows don’t expire. When a rented movie expires, it’s no longer available for playback. To watch it again, you can rent it again from iTunes. Note:  Rented movies are not available in all regions.www.apple.com/support/appletv Problem? No Problem. 426 Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. Most problems with Apple TV can be solved quickly by following the advice in this chapter. For additional tips and troubleshooting information, see the Apple TV Support page at www.apple.com/support/appletv. Troubleshooting If you have a problem with Apple TV, there’s usually a quick and simple solution. First, make sure:  The cables between Apple TV and your TV are pushed in all the way.  The power cords for Apple TV and your TV are securely connected to a working power source.  Your TV is turned on and set to the correct input.  Apple TV is connected to your network. Go to the Settings menu on Apple TV, select Network, and see if Apple TV has an IP address.  Your network and Internet connections are on and working properly. If you still have trouble, try resetting your equipment by disconnecting Apple TV, your TV, your wireless networking equipment or base station, and your router from the power outlet.Wait 30 seconds, and then reconnect everything. If the remote isn’t working  Point the remote directly at Apple TV.  If you paired Apple TV with an Apple Remote, make sure you’re using the paired remote.Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. 27  If the Apple TV status light flashes once when you press buttons on the paired remote, the problem isn’t with the remote. See “If you can see a picture but Apple TV isn’t responding” on page 28.  If you’re using an unpaired remote, the Apple TV status light flashes three times.  If you paired Apple TV with an Apple Remote and you can’t find the paired remote, set Apple TV to work with any Apple Remote by holding down Menu and Left for 6 seconds on another remote.  Make sure the front of Apple TV isn’t blocked.  If Apple TV displays a picture of a remote and a warning symbol (·), you need to replace the battery in the remote. See “Changing the Remote Battery” on page 23. If Apple TV can’t access the network  Check the IP address Apple TV is using. If it starts with 169.x.x.x, the router or base station may not be configured properly. Check to see if DHCP access is available, or configure Apple TV with a manual IP address.  Check for any obstructions, and adjust the location of the base station or Apple TV.  If security is enabled on the network, temporarily disable it on the base station and try connecting again.  Apple TV cannot connect to a wireless network that contains high (extended) ASCII or double-byte (Unicode) characters (such as Japanese, Korean, or Chinese) in the name or password.  If your network has security enabled, make sure you enter the correct password.28 Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. If your TV screen appears fuzzy or black  Make sure you’re using the correct HDMI cable and that it’s connected firmly to Apple TV and to your TV.  Make sure the input setting on your TV matches the input port the HDMI cable is connected to. For information, see the documentation that came with your TV.  Make sure your HDTV supports 720p video. If you can see a picture but Apple TV isn’t responding  Hold down Menu on the Apple Remote to return to the Apple TV main menu.  Make sure your TV is turned on and functioning properly. For information, see the documentation that came with your TV.  If you paired an Apple Remote with Apple TV, make sure you’re using the paired remote. See “Pairing Apple TV with a Remote” on page 21.  Reset Apple TV by doing one of the following:  Hold down both Menu and Down on the Apple Remote until the Apple TV status light blinks rapidly.  Disconnect Apple TV from the power outlet, wait about five seconds, and then reconnect it.  Choose General > Reset Settings from the main menu on Apple TV.Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. 29 If Apple TV doesn’t respond, try restoring it  On Apple TV, choose Settings > General > Reset, and then select Restore. Restoring Apple TV can take some time, so be patient.  If your network doesn’t use DHCP, choose Configure TCP/IP and enter the TCP/IP configuration.  If Apple TV still doesn’t respond:  Disconnect the power and HDMI cables from Apple TV.  Connect one end of a micro USB cable (sold separately) to the back of Apple TV, and the other end to your computer.  Open iTunes on your computer, select Apple TV in the Source list, and then click Restore. If you can’t hear sound  If Apple TV is connected to a home theater receiver, make sure the receiver is turned on.  Make sure the input setting you selected on your TV or receiver matches the input you have your audio cable connected to. For more information, see the documentation that came with your receiver.  Make sure the volume on your TV or receiver is turned up and isn’t muted.  Make sure you’re using the correct audio cable and that it’s connected firmly to Apple TV and to your TV or receiver.  If you’re using the HDMI port for audio, make sure your TV supports audio through its HDMI port. The HDMI ports on some older TVs support only video.30 Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. If Apple TV isn’t playing your photo albums or slideshows  Make sure you have photos in your photo library or in a folder on your computer.  Make sure Apple TV and the computer you’re using are set up for Home Sharing. See “Setting Up Home Sharing” on page 17.  Make sure the photos you want to share are selected. In iTunes, choose Advanced >“Choose Photos to Share,” and then select the photos you want to share.  Make sure Apple TV and your computer are on the same local network.  Make sure Apple TV and your computer are using the same Home Sharing account. If noise is coming from your TV speakers:  If your TV or speakers support Dolby Digital audio, make sure the Dolby Digital Out setting is correct for your TV or speakers. On Apple TV, choose Settings > Audio & Video > Dolby Digital Out, and select On or Off. If you don’t see your iTunes library under Computers on Apple TV:  Make sure Apple TV and your computer are on the same local network.  Make sure Apple TV and iTunes are using the same account name and password.Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. 31 Status Light The status light on the front of Apple TV indicates what’s happening. If Apple TV is The status light On Glows Off or in standby Is off Starting up Flashes slowly Accepting a command from the remote Flashes once Rejecting a command from the remote (you paired a remote with Apple TV, but you’re using a remote that’s not paired) Flashes three times Having problems Flashes quickly32 Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. Service and Support More information about using Apple TV is available in iTunes onscreen help and on the web. The following table describes where to get software and service information. To learn about Do this Service and support, discussions, tutorials, and Apple software downloads Go to: www.apple.com/support/appletv Using iTunes Open iTunes and choose Help > iTunes Help. For an onscreen iTunes tutorial (available in some areas only), go to: www.apple.com/support/itunes Using iPhoto (in Mac OS X) Open iPhoto and choose iPhoto > iPhoto Help Safety and regulatory compliance information See the Important Product Information Guide that comes with Apple TV. Serial Number The serial number is printed on the bottom of Apple TV. You can also find the serial number in the Apple TV Settings menu. On Apple TV, choose Settings > General > About.Chapter 4 Problem? No Problem. Chapter 4 Problem? No Problem. 33 Care and Cleaning NOTICE:  Failure to follow these care and cleaning instructions could result in damage to Apple TV or other property. Using Connectors and Ports Never force a connector into a port. Check for obstructions on the port. If the connector and port don’t join with reasonable ease, they probably don’t match. Make sure that the connector matches the port and that you have positioned the connector correctly in relation to the port. Keeping Apple TV Within Acceptable Temperatures Operate Apple TV in a place where the temperature is always between 0º and 40º C (32º to 104º F). Keeping the Outside of Apple TV Clean To clean Apple TV, unplug the power cord and all cables. Then use a soft, lint-free cloth. Avoid getting moisture in openings. Don’t use window cleaners, household cleaners, aerosol sprays, solvents, alcohol, ammonia, or abrasives to clean Apple TV. Disposing of Apple TV Properly For information about the proper disposal of Apple TV, and for other important regulatory compliance information, see the Important Product Information Guide.K Apple Inc. © 2011 Apple 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. 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 1 Infinite Loop Cupertino, CA 95014 408-996-1010 www.apple.com The Apple logo is a trademark of Apple 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. Apple, the Apple logo, AirPlay, Apple TV, iPad, iPhone, iPhoto, iPod touch, iTunes, Mac, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. Apple Store and iTunes Store are service marks of Apple Inc., registered in the U.S. and other countries. Manufactured under license from Dolby Laboratories.“Dolby,”“Pro Logic,” and the double-D symbol are trademarks of Dolby Laboratories. Confidential Unpublished Works, © 1992-1997 Dolby Laboratories, Inc. All rights reserved. Other company and product names mentioned herein may be trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. USB Device Interface GuideContents Introduction to USB Device Interface Guide 4 Organization of This Document 4 See Also 4 USB Device Overview 6 USB Device Types and Bus Speeds 6 USB Device Architecture and Terminology 7 USB Device Component Descriptors 8 USB Composite Class Devices 8 USB Transfer Types 8 Stalls and Halts 9 Data Synchronization in Non-Isochronous Transfers 10 USB 2.0 and Isochronous Transfers 10 USB Devices on OS X 11 Finding USB Devices and Interfaces 12 USB Family Error Codes 14 Determining Which Interface Version to Use 14 Tasks and Caveats 15 Handling Stalls, Halts, and Data Toggle Resynchronization 15 Using the Low Latency Isochronous Functions 15 Errors Reported by the EHCI Hub 17 Changes in Isochronous Functions to Support USB 2.0 17 USB Device Access in an Intel-Based Macintosh 18 Working With USB Device Interfaces 20 Using USB Device Interfaces 20 Accessing a USB Device 22 Definitions and Global Variables 22 The main Function 23 Working With the Raw Device 27 Working With the Bulk Test Device 34 Working With Interfaces 36 Document Revision History 46 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 2Tables and Listings USB Device Overview 6 Table 1-1 Examples of USB devices 6 Table 1-2 Keys for finding a USB device 12 Table 1-3 Keys for finding a USB interface 13 Working With USB Device Interfaces 20 Listing 2-1 Definitions and global variables 22 Listing 2-2 The main function 24 Listing 2-3 Accessing and programming the raw device 27 Listing 2-4 Releasing the raw device objects 30 Listing 2-5 Configuring a USB device 30 Listing 2-6 Two functions to download firmware to the raw device 32 Listing 2-7 Accessing the bulk test device 34 Listing 2-8 Finding interfaces on the bulk test device 36 Listing 2-9 Two asynchronous I/O completion functions 43 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 3Note: This document was previously titled Working With USB Device Interfaces. The I/O Kit provides a device interface mechanism that allows applications to communicate with and control hardware from outside the kernel. This document focuses on how to use that mechanism to create an application that detects the attachment of a USB device, communicates with it, and detects its detachment. This document does not describe how to develop an in-kernel driver for a USB modem or networking device. If you need to do this, refer to the documentation and sample code listed in “See Also” (page 4). Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. Organization of This Document This document contains the following chapters: ● “USB Device Overview” (page 6) provides an overview of USB device architecture and terminology and describes how USB devices are represented in OS X. ● “Working With USB Device Interfaces” (page 20) describes how to use the device interface mechanism to create a command-line tool that accesses a USB device. ● “Document Revision History” (page 46) lists the revisions of this document. See Also The ADC Reference Library contains several documents on device driver development for OS X and numerous sample drivers and applications. ● Accessing Hardware From Applications describes various ways to access devices from outside the kernel, including the device interface mechanism provided by the I/O Kit. For an overview of the I/O Kit terms and concepts used in this document, read the chapter Device Access and the I/O Kit. 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 4 Introduction to USB Device Interface Guide● I/O Kit Framework Reference contains API reference for I/O Kit methods and functions and for specific device families. ● Sample Code > Hardware & Drivers > USB includes both application-level and in-kernel code samples. Of particular relevance to this document is the application-level sample USBPrivateDataSample . ● OS X Man Pages provides access to existing reference documentation for BSD and POSIX functions and tools in a convenient HTML format. ● The usb mailing list provides a forum for discussing technical issues relating to USB devices in OS X. If you need to develop an in-kernel driver for a USB modem or networking device, refer to the following: ● I/O Kit Fundamentals describesthe architecture ofthe I/OKit,the object-oriented framework for developing OS X device drivers. ● ADC members can view the AppleUSBCDCDriver project in the source code for OS X v10.3.7 and later, available at Darwin Releases. To find the source code, select a version of OS X equal to or greater than v10.3.7 and click Source (choose the source for the PPC version, if there's a choice). This displays a new page, which lists the open source projects available for the version of OS X you've chosen. Scroll down to AppleUSBCDCDriver and click it to view the source. Be prepared to supply your ADC member name and password. ● Additional code samples that demonstrate specific in-kernel driver programming techniques are included as part of the OS X Developer Toolsinstallation package in /Developer/Examples/Kernel/IOKit/usb. If you're ready to create a universal binary version of your USB device-access application to run in an Intel-based Macintosh,seeUniversalBinaryProgrammingGuidelines.TheUniversalBinaryProgrammingGuidelines describes the differences between the Intel and PowerPC architectures and provides tips for developing a universal binary. If you are working with a device that complies with the USB mass storage specification but declares its device class to be vendor specific, see Mass Storage Device Driver Programming Guide for information on how to ensure the correct built-in driver loads for the device. Apple provides additional USB information (including the OS X USB Debug Kits) at http://developer.apple.com/hardwaredrivers/usb/index.html. A detailed description of the USB device specification is beyond the scope of this document—for more information, see Universal Serial Bus Specification Revision 2.0 available at http://www.usb.org. Introduction to USB Device Interface Guide See Also 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 5This chapter provides a summary of USB device architecture and describes how USB devices are represented in OS X. It also presents a few specific guidelines for working with USB devices in an application.For details on the USB specification, see http://www.usb.org. USB Device Types and Bus Speeds The USB specification supports a wide selection of devices that range from lower-speed devices such as keyboards, mice, and joysticks to higher-speed devices such as scanners and digital cameras. The specification lists a number of device classes that each define a set of expected device behaviors. Table 1-1 (page 6) lists some examples of USB devices, categorized by class. Table 1-1 Examples of USB devices USB device class USB devices in class Audio class Speakers, microphones Chip Card Interface Device Class Smart cards, chip cards Communication class Speakerphone, modem A device in which all class-specific information is embedded in its interfaces Composite class HID class Keyboards, mice, joysticks, drawing tablets Hub class Hubs provide additional attachment points for USB devices Hard drives, flash memory readers, CD Read/Write drives, digital cameras, and high-end media players Mass storage class Printing class Printers A device that doesn’t fit into any other predefined class or one that doesn’t use the standard protocols for an existing class Vendor specific Digital camcorders, webcams, digital still cameras that support video streaming Video class 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 6 USB Device OverviewVersion 1.1 of the USB specification supports two bus speeds: ● Low speed (1.5 Mbps) ● Full speed (12 Mbps) Version 2.0 of the specification adds another bus speed to this list: ● High speed (480 Mbps) The USB 2.0 specification is fully compatible with low-speed and full-speed USB devices and even supports the use of cables and connectors made to meet earlier versions of the specification. Apple provides USB 2.0 ports on all new Macintosh computers and fully supports the new specification with Enhanced Host Controller Interface (EHCI) controllers and built-in, low-level USB drivers. For the most part, you do not have to change existing applications to support the faster data rate because the speed increase and other enhancements are implemented at such a low level. The exceptions to this are some differences in isochronous transfers. For information on how the USB 2.0 specification affects isochronous transfers, see “USB 2.0 and Isochronous Transfers” (page 10). USB Device Architecture and Terminology The architecture of a generic USB device is multi-layered. A device consists of one or more configurations, each of which describes a possible setting the device can be programmed into. Such settings can include the power characteristics of the configuration (for example, the maximum power consumed by the configuration and whether it is self-powered or not) and whether the configuration supports remote wake-up. Each configuration contains one or more interfacesthat are accessible after the configuration isset. An interface provides the definitions of the functions available within the device and may even contain alternate settings within a single interface. For example, an interface for an audio device may have different settings you can select for different bandwidths. Each interface contains zero or more endpoints. An endpoint is a uniquely identifiable portion of a USB device that is the source or sink of information in a communication flow between the host and the device. Each endpoint has characteristics that describe the communication it supports, such as transfer type (control, isochronous, interrupt, or bulk, described in “USB Transfer Types” (page 8)), maximum packet size, and transfer direction (input or output). Communication with a USB device is accomplished through a pipe, a logical association between an endpoint and software running on the host. Endpoint and pipe are often used synonymously although an endpoint is a component of a USB device and a pipe is a logical abstraction of the communications link between endpoint and host. USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 7USB Device Component Descriptors Each layer of a USB device providesinformation about its attributes and resource requirementsin its descriptor, a data structure accessible through device interface functions. By examining the descriptors at each layer, you can determine exactly which endpoint you need to communicate successfully with a particular device. At the top layer is the device descriptor, which has fields associated with information such as the device’s class and subclass, vendor and product numbers, and number of configurations. Each configuration in turn has a configuration descriptor containing fields that describe the number of interfaces it supports and the power characteristics of the device when it is in that configuration, along with other information. Each interface supported by a configuration has its own descriptor with fields for information such as the interface class, subclass, and protocol, and the number of endpoints in that interface. At the bottom layer are the endpoint descriptors that specify attributes such as transfer type and maximum packet size. The USB specification defines a name for each descriptor field, such as the bDeviceClass field in the device descriptor and the bNumInterfaces field in the configuration descriptor, and each field is associated with a value. For a complete listing of all descriptor fields, see the USB specification at www.usb.org. The USB family defines structures that represent the descriptors defined by the USB specification. For the definitions of these structures, see USB in Kernel Framework Reference . USB Composite Class Devices The USB specification defines a composite class device as a device whose device-descriptor fields for device class (bDeviceClass) and device subclass (bDeviceSubClass) both have the value 0. A composite class device appears to the system as a USB device using a single bus address that may present multiple interfaces, each of which represents a separate function. A good example of a composite class device is a multifunction device, such as a device that performs printing, scanning, and faxing. In such a device, each function is represented by a separate interface. In OS X, the I/O Kit loads the AppleUSBComposite device driver for composite class devices that do not already have vendor-specific device drivers to drive them. The AppleUSBComposite driver configures the device and causes drivers to be loaded for each USB interface. Although most multifunction USB devices are composite class devices, not all composite class devices are multifunction devices. The manufacturer of a single-function USB device is at liberty to classify the device as a composite class device as long as the device meets the USB specifications. For more information on how OS X represents USB devices and interfaces, see “USB Devices on OS X” (page 11). USB Transfer Types The USB specification defines four types of pipe transfer: ● Control—intended to support configuration, command, and status communication between the host software and the device. Control transfers support error detection and retry. USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 8● Interrupt—used to support small, limited-latency transfers to or from a device such as coordinates from a pointing device or status changes from a modem. Interrupt transfers support error detection and retry. ● Isochronous—used for periodic, continuous communication between the host and the device, usually involving time-relevant information such as audio or video data streams. Isochronous transfers do not support error detection or retry. ● Bulk—intended for non-periodic, large-packet communication with relaxed timing constraints such as between the host software and a printer or scanner. Bulk transfers support error detection and retry. Pipes also have a transfer direction associated with them. A control pipe can support bidirectional communication but all other pipes are strictly uni-directional. Therefore, two-way communication requires two pipes, one for input and one for output. Every USB device is required to implement a default control pipe that provides access to the device’s configuration, status, and control information. This pipe, implemented in the IOUSBDevice nub object (described in “USB Devices on OS X” (page 11)), is used when a driver such as the AppleUSBComposite driver configures the device or when device-specific control and status information is needed. For example, your application would use the default control pipe if it needs to set or choose a configuration for the device. The default control pipe is connected to the default endpoint (endpoint 0). Note that endpoint 0 does not provide an endpoint descriptor and it is never counted in the total number of endpoints in an interface. The interfaces associated with a configuration can contain any combination of the three remaining pipe types (interrupt, isochronous, and bulk), implemented in the IOUSBInterface nub objects (described in “USB Devices on OS X” (page 11)). Your application can query the interface descriptors of a device to select the pipe most suited to its needs. Stalls and Halts Although a stall and a halt are different, they are closely related in their effect on data transmission. Halt is a feature of an endpoint and it can be set by either the host or the device itself in response to an error. A stall is a type of handshake packet an endpoint returns when it is unable to transmit or receive data or when its halt feature is set (the host never sends a stall packet). When an endpoint sends a stall packet, the host can halt the endpoint. Depending on the precise circumstances and on how compliant the device is, the halt feature must be cleared in the host, the endpoint, or both before data transmission can resume. When the halt is cleared the data toggle bit, used to synchronize data transmission, is also reset (see “Data Synchronization in Non-Isochronous Transfers” (page 10) for more information about the data toggle). For information on how to handle these conditions in your application, see “Handling Stalls, Halts, and Data Toggle Resynchronization” (page 15). USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 9Data Synchronization in Non-Isochronous Transfers The USB specification defines a simple protocol to provide data synchronization across multiple packets for non-isochronoustransfers(recall that isochronoustransfers do notsupport error recovery or retry). The protocol is implemented by means of a data toggle bit in both the host and the endpoint which is synchronized at the start of a transaction (or when a reset occurs). The precise synchronization mechanism varies with the type of transfer; see the USB specification for details. Both the host and the endpoint begin a transaction with their data toggle bitsset to zero. In general, the entity receiving data toggles its data toggle bit when it is able to accept the data and it receives an error-free data packet with the correct identification. The entity sending the data toggles its data toggle bit when it receives a positive acknowledgement from the receiver. In this way, the data toggle bits stay synchronized until, for example, a packet with an incorrect identification is received. When this happens, the receiver ignores the packet and does not increment its data toggle bit. When the data toggle bits get out of synchronization (for this or any other reason), you will probably notice that alternate transactions are not getting through in your application. The solution to this is to resynchronize the data toggle bits. For information on how to do this, see “Handling Stalls, Halts, and Data Toggle Resynchronization” (page 15). USB 2.0 and Isochronous Transfers The USB 2.0 specification supports the same four transfer types as earlier versions of the specification. In addition to supporting a higher transfer rate, the new specification defines an improved protocol for high-speed transfers and new ways of handling transactions for low-speed and full-speed devices. For details on the protocols and transaction-handling methods, see the specification at http://www.usb.org. For the most part, these enhancements are implemented at the hostsoftware level and do not require changes to your code. For isochronous transfers, however, you should be aware of the following differences: ● Earlier versions of the specification divide bus time into 1-millisecond frames, each of which can carry multiple transactionsto multiple destinations. (A transaction containstwo or more packets: a token packet and one or more data packets, a handshake packet, or both.) The USB 2.0 specification divides the 1-millisecond frame into eight, 125-microsecond microframes, each of which can carry multiple transactions to multiple destinations. ● The maximum amount of data allowed in a transaction is increased to 3 KB. ● Any isochronous endpoints in a device’s default interface must have a maximum packet size of zero. (This means that the default setting for an interface containing isochronous pipes is alternate setting zero and the maximum packet size for that interface’s isochronous endpoints must be zero.) This ensures that the host can configure the device no matter how busy the bus is. For a summary of how these differences affect the OS X USB API, see “Changes in Isochronous Functions to Support USB 2.0” (page 17). USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 10USB Devices on OS X When a USB device is plugged in, the OS X USB family abstracts the contents of the device descriptor into an I/O Kit nub object called an IOUSBDevice. This nub object is attached to the IOService plane of the I/O Registry as a child of the driver for the USB controller. The IOUSBDevice nub object is then registered for matching with the I/O Kit. If the device is a composite class device with no vendor-specific driver to match against it, the AppleUSBComposite driver matches against it and starts as its provider. The AppleUSBComposite driver then configures the device by setting the configuration in the device’s list of configuration descriptors with the maximum power usage that can be satisfied by the port to which the device is attached. This allows a device with a low power and a high power configuration to be configured differently depending on whether it’s attached to a bus-powered hub or a self-powered hub. In addition, if the IOUSBDevice nub object has the “Preferred Configuration” property, the AppleUSBComposite driver will always use that value when it attempts to configure the device. The configuration of the device causes the USB family to abstract each interface descriptor in the chosen configuration into an IOUSBInterface nub object. These nub objects are attached to the I/O Registry as children of the original IOUSBDevice nub object and are registered for matching with the I/O Kit. Important: Because a composite class device is configured by the AppleUSBComposite driver, setting the configuration again from your application will result in the destruction of the IOUSBInterface nub objects and the creation of new ones. In general, the only reason to set the configuration of a composite class device that’s matched by the AppleUSBComposite driver is to choose a configuration other than the first one. For non-composite class devices or composite class devices with vendor-specific drivers that match against them, there is no guarantee that any configuration will be set and you may have to perform this task within your application. It's important to be mindful of the difference between a USB device (represented in the I/O Registry by an IOUSBDevice nub object) and its interfaces (each represented by an IOUSBInterface nub object). A multifunction USB device, for example, is represented in the I/O Registry by one IOUSBDevice object and one IOUSBInterface object for each interface. The distinction between interface and device isimportant because it determines which object your application must find in the I/O Registry and which type of device interface to get. For example, if your application needs to communicate with a specific interface in a multifunction USB device, it must find that interface and get an IOUSBInterfaceInterface to communicate with it. An application that needs to communicate with the USB device as a whole, on the other hand, would need to find the device in the I/O Registry and get an IOUSBDeviceInterface to communicate with it. For more information on finding devices and interfaces in USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 11the I/O Registry, see “Finding USB Devices and Interfaces” (page 12); for more information on how to get the proper device interface to communicate with a device or interface, see “Using USB Device Interfaces” (page 20). Finding USB Devices and Interfaces To find a USB device or interface, use the keys defined in the Universal Serial Bus Common Class Specification, Revision 1.0 (available for download from http://www.usb.org/developers/devclass_docs/usbccs10.pdf) to create a matching dictionary that defines a particular search. If you are unfamiliar with the concept of device matching, see the section “Finding Devices in the I/O Registry” in Accessing Hardware From Applications. The keys defined in the specification are listed in the tables below. Each key consists of a specific combination of elements in a device or interface descriptor. In the tables below, the elements in a key are separated by the ‘+’ character to emphasize the requirement that all a key’s elements must appear together in your matching dictionary. Both tables present the keys in order of specificity: the first key in each table defines the most specific search and the last key defines the broadest search. Before you build a matching dictionary, be sure you know whether your application needs to communicate with a device or a specific interface in a device. It’s especially important to be aware of this distinction when working with multifunction devices. A multifunction device is often a composite class device that defines a separate interface for each function. If, for example, your application needs to communicate with the scanning function of a device that does scanning, faxing, and printing, you need to build a dictionary to match on only the scanning interface (an IOUSBInterface object), not the device as a whole (an IOUSBDevice object). In this situation, you would use the keys defined for interface matching (those shown in Table 1-3 (page 13)), not the keys for device matching. Table 1-2 (page 12) lists the keys you can use to find devices (not interfaces). Each key element is a piece of information contained in the device descriptor for a USB device. Table 1-2 Keys for finding a USB device Key Notes bcdDevice contains the release number of the device idVendor + idProduct + bcdDevice idVendor + idProduct Use this key only if the device’s bDeviceClass is $FF idVendor + bDeviceSubClass + bDeviceProtocol Use this key only if the device’s bDeviceClass is $FF idVendor + bDeviceSubClass USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 12Key Notes Use this key only if the device’s bDeviceClass is not $FF bDeviceClass + bDeviceSubClass + bDeviceProtocol Use this key only if the device’s bDeviceClass is not $FF bDeviceClass + bDeviceSubClass Table 1-3 (page 13) lists the keys you can use to find interfaces (not devices). Each key element is a piece of information contained in an interface descriptor for a USB device. Table 1-3 Keys for finding a USB interface Key Notes idVendor + idProduct + bcdDevice + bConfigurationValue + bInterfaceNumber idVendor + idProduct + bConfigurationValue + bInterfaceNumber Use this key only if bInterfaceClass is $FF idVendor + bInterfaceSubClass + bInterfaceProtocol Use this key only if bInterfaceSubClass is $FF idVendor + bInterfaceSubClass Use this key only if bInterfaceSubClass is not $FF bInterfaceClass + bInterfaceSubClass + bInterfaceProtocol Use this key only if bInterfaceSubClass is not $FF bInterfaceClass + bInterfaceSubClass For a successful search, you must add the elements of exactly one key to your matching dictionary. If your matching dictionary contains a combination of elements not defined by any key, the search will be unsuccessful. For example, if you create a matching dictionary containing values representing a device’s vendor, product, and protocol, the search will be unsuccessful even if a device with those precise values in its device descriptor is currently represented by an IOUSBDevice nub in the I/O Registry. This is because there is no key in Table 1-2 (page 12) that combines the idVendor, idProduct, and bDeviceProtocol elements. USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 13USB Family Error Codes As you develop an application to access a USB device or interface, you will probably encounter error codes specific to the OS X USB family. If you are using Xcode, you can search for information about these error codes in the Xcode documentation window. To find error code documentation, select Documentation from the Xcode Help menu. Select Full-Text Search from the pull-down menu associated with the search field (click the magnifying glass icon to reveal the menu). Select Reference Library in the Search Groups pane at the left of the window. Type an error code number in the search field, such as 0xe0004057, and press Return. Select the most relevant entry in the search results to display the document in the lower portion of the window. Use the Find command (press Command-F) to find the error code in this document. Using the example of error code 0xe0004057, you’ll see that this error is returned when the endpoint has not been found. For help with deciphering I/O Kit error codes in general, see Technical Q&A QA1075, “Making sense of I/O Kit error codes.” Determining Which Interface Version to Use As described in “USB Devices on OS X” (page 11), the OS X USB family provides an IOUSBDeviceInterface object you use to communicate with a USB device as a whole and an IOUSBInterfaceInterface object you use to communicate with an interface in a USB device. There are a number of different versions of the USB family, however, some of which provide new versions of these interface objects. (One way to find the version of the USB family installed in your computer is to view the Finder preview information for the IOUSBFamily.kext located in /System/Library/Extensions.) This section describes how to make sure you use the correct interface object and how to view the documentation for the interface objects. The first version of the USB family was introduced in OS X v10.0 and contains the first versions of the interface objects IOUSBDeviceInterface and IOUSBInterfaceInterface. When new versions of the USB family introduce new functions for an interface object, a new version of the interface object is created, which gives access to both the new functions and all functions defined in all previous versions of that interface object. For example, the IOUSBDeviceInterface197 object provides two new functions you can use with version 1.9.7 of the USB family (available in OS X v10.2.3 and later), in addition to all functions available in the previous device interface objects IOUSBDeviceInterface187, IOUSBDeviceInterface182, and IOUSBDeviceInterface. As you develop an application that accesses a USB device or interface, you should use the latest version of the interface object that is available in the earliest version of OS X that you want to support. For example, if your application must run in OS X v10.0, you must use the IOUSBDeviceInterface and IOUSBInterfaceInterface objects. If, however, you develop an application to run in OS X v10.4 and later, you use the IOUSBDeviceInterface197 object to access the device as a whole and the USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 14IOUSBInterfaceInterface220 object to access an interface in it. This is because IOUSBDeviceInterface197 is available inOS X version 10.2.3 and later and IOUSBInterfaceInterface220 is available in OS X v10.4 and later. Note: When you view the documentation for these interface objects, notice that each version is documented separately. For example, the documentation for IOUSBDeviceInterface197 contains information about the two new functions introduced in this version, but does not repeat the documentation for the functions introduced in IOUSBDeviceInterface187, IOUSBDeviceInterface182, and IOUSBDeviceInterface. Tasks and Caveats This section presents some specific tasks your application might need to perform, along with some caveats related to USB 2.0 support of which you should be aware. Handling Stalls, Halts, and Data Toggle Resynchronization As described in “Stalls and Halts ” (page 9), stalls and halts are closely related in their effect on data transmission. To simplify the API, the USB family uses the pipe stall terminology in the names of the functions that handle these conditions: ● ClearPipeStall ● ClearPipeStallBothEnds The ClearPipeStall function operates exclusively on the host controller side, clearing the halt feature and resetting the data toggle bit to zero. If the endpoint’s halt feature and data toggle bit must be reset as well, your application must do so explicitly, using one of the ControlRequest functions to send the appropriate device request. See the documentation for the USB.h header file in I/O Kit Framework Reference for more information about standard device requests. In OS X version 10.2 and later, you can use the ClearPipeStallBothEnds function which, as its name suggests, clears the halt and resets the data toggle bit on both sides at the same time. Using the Low Latency Isochronous Functions In OS X, the time between when an isochronous transaction completes on the USB bus and when you receive your callback can stretch to tens of milliseconds. This is because the callback happens on the USB family work loop, which runs at a lower priority than some other threads in the system. In most cases, you can work around USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 15this delay by queuing read and write requests so that the next transaction is scheduled and ready to start before you receive the callback from the current transaction. In fact, this scheme is a good way to achieve higher performance whether or not low latency is a requirement of your application. In a few cases, however, queuing isochronous transactions to keep the pipe busy is not enough to prevent a latency problem that a user might notice. Consider an application that performs audio processing on some USB input (from a musical instrument, for example) before sending the processed data out to USB speakers. In this scenario, a user hears both the raw, unprocessed output of the instrument and the processed output of the speakers. Of course, some small delay between the time the instrument creates the raw sound waves and the time the speaker emits the processed sound waves is unavoidable. If this delay is greater than about 8 milliseconds, however, the user will notice. In OS X version 10.2.3 (version 1.9.2 of the USB family) the USB family solves this problem by taking advantage of the predictability of isochronous data transfers. By definition, isochronous mode guarantees the delivery of some amount of data every frame or microframe. In earlier versions of OS X, however, it was not possible to find out the exact amount of data that was transferred by a given time. This meant that an application could not begin processing the data until it received the callback associated with the transaction, telling it the transfer status and the actual amount of data that was transferred. Version 1.9.2 of the USB family introduced the LowLatencyReadIsochPipeAsync and LowLatencyWriteIsochPipeAsync functions. These functions update the frame list information (including the transferstatus and the number of bytes actually transferred) at primary interrupt time. Using these functions, an application can request that the frame list information be updated as frequently as every millisecond. This means an application can retrieve and begin processing the number of bytes actually transferred once a millisecond, without waiting for the entire transaction to complete. Important: Because these functions cause processing at primary interrupt time, it is essential you use them only if it is absolutely necessary. Overuse of these functions can cause degradation of system performance. To support the low latency isochronous read and write functions, the USB family also introduced functions to create and destroy the buffers that hold the frame list information and the data. Although you can choose to create a single data buffer and a single frame list buffer or multiple buffers of each type, you must use the LowLatencyCreateBuffer function to create them. Similarly, youmust use the LowLatencyDestroyBuffer function to destroy the buffers after you are finished with them. This restricts all necessary communication with kernel entities to the USB family. For reference documentation on the low latency isochronous functions, see the IOUSBLib.h documentation in I/O Kit Framework Reference . USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 16Errors Reported by the EHCI Hub The EHCI hub that supports high-speed devices (as well as low-speed and full-speed devices) provides coarser-grained error reporting than the OHCI hub does. For example, with an OHCI hub, you might receive an “endpoint timed out” error if you unplug the device while it is active. If you perform the same action with an EHCI hub, you might receive a “pipe stalled” error instead. The Apple EHCI hub driver cannot get more detailed error information from the hub, so it alternates between reporting “device not responding” and “pipe stalled” regardless of the actual error reported by the device. To avoid problems with your code, be sure your application does not rely on other, more specific errors to make important decisions. Changes in Isochronous Functions to Support USB 2.0 Recall that the USB 2.0 specification divides the 1-millisecond frame into eight, 125-microsecond microframes. The USB family handles this by reinterpreting some function parameters (where appropriate) and adding a couple of new functions. This section summarizes these changes; for reference documentation, see documentation for IOUSBLib.h in I/O Kit Framework Reference . The functions you use to read from and write to isochronous endpoints are ReadIsochPipeAsync and WriteIsochPipeAsync. Both functions include the following two parameters: ● numFrames—The number of frames for which to transfer data ● frameList—A pointer to an array of structures that describe the frames If you need to handle high-speed isochronous transfers, you can think of these parameters as referring to “transfer opportunities” instead of frames. In other words, numFrames can refer to a number of frames for full-speed devices or to a number of microframes for high-speed devices. Similarly, frameList specifies the list of transfers you want to occur, whether they are in terms of frames or microframes. Note: The ReadIsochPipeAsync and WriteIsochPipeAsync functions also have the frameStart parameter in common, but it does not get reinterpreted. Thisis because all isochronoustransactions, including high-speed isochronoustransactions,start on a frame boundary, not amicroframe boundary. To help you determine whether a device isfunctioning in full-speed or high-speed mode, the USB family added the GetFrameListTime function, which returns the number of microseconds in a frame. By examining the result (kUSBFullSpeedMicrosecondsInFrame or kUSBHighSpeedMicrosecondsInFrame) you can tell in which mode the device is operating. USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 17The USB family also added the GetBusMicroFrameNumber function which is similar to the GetBusFrameNumber function, except that it returns both the current frame and microframe number and includes the time at which that information was retrieved. To handle the new specification’s requirement that isochronous endpoints in a device’s default interface have a maximum packetsize of zero, the USB family added functionsthat allow you to balance bandwidth allocations among isochronous endpoints. A typical scenario is this: 1. Call GetBandwidthAvailable (available inOS X version 10.2 and later)to determine howmuch bandwidth is currently available for allocation to isochronous endpoints. 2. Call GetEndpointProperties (available in OS X version 10.2 and later) to examine the alternate settings of an interface and find one that uses an appropriate amount of bandwidth. 3. Call SetAlternateInterface (available in OS X version 10.0 and later) to create the desired interface and allocate the pipe objects. 4. Call GetPipeProperties (available in OS X version 10.0 and later) on the chosen isochronous endpoint. Thisis a very importantstep because SetAlternateInterface willsucceed, even if there is not enough bandwidth for the endpoints. Also, another device might have claimed the bandwidth that was available at the time the GetBandwidthAvailable function returned. If this happens, the maximum packet size for your chosen endpoint (contained in the maxPacketSize field) is now zero, which means that the bandwidth is no longer available. In addition, in OS X version 10.2, the USB family added the SetPipePolicy function, which allows you to relinquish bandwidth that might have been specified in an alternate setting. USB Device Access in an Intel-Based Macintosh This section provides an overview of some of the issues related to developing a universal binary version of an application that accesses a USB device. Before you read this section, be sure to read Universal Binary Programming Guidelines. That document covers architectural differences and byte-ordering formats and provides comprehensive guidelines for code modification and building universal binaries. The guidelines in that document apply to all types of applications, including those that access hardware. Before you build your application as a universal binary, make sure that: ● You port your project to GCC 4 (Xcode uses GCC 4 to target Intel-based Macintosh computers) ● You install the OS X v10.4 universal SDK ● You develop your project in Xcode 2.1 or later USB Device Overview USB Device Access in an Intel-Based Macintosh 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 18The USB bus is a little-endian bus. Structured data appears on the bus in the little-endian format regardless of the native endian format of the computer an application isrunning in. If you've developed a USB device-access application to run in a PowerPC-based Macintosh, you probably perform some byte swapping on data you read from the USB bus because the PowerPC processor uses the big-endian format. For example, the USB configuration descriptor structure contains a two-byte field that holds the descriptor length. If your PowerPC application reads this structure from the USB bus (instead of receiving it from a USB device interface function), you need to swap the value from the USB bus format (little endian) to the PowerPC format (big endian). The USB family provides several swapping macros that swap from USB to host and from host to USB (for more information on these macros, see USB.h). The Kernel framework also provides byte-swapping macros and functions you can use in high-level applications (see the OSByteOrder.h header file in libkern). If you use these macros in your application, you shouldn't have any trouble developing a universal binary version of your application. This is because these macros determine at compile time if a swap is necessary. If, however, your application uses hard-coded swaps from little endian to big endian, your application will not run correctly in an Intel-based Macintosh. As you develop a universal binary version of your application, therefore, be sure to use the USB family swapping macros or the macros in libkern/OSByteOrder.h for all byte swapping. Although you may need to perform byte swapping on values your application reads from the USB bus, you do not need to perform any byte swapping on values you pass in arguments to functions in the USB family API. You should pass argument values in the computer's host format. Likewise, any values you receive from the USB family functions will be in the computer's host format. USB Device Overview USB Device Access in an Intel-Based Macintosh 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 19This chapter describes how to develop a user-space tool that finds and communicates with an attached USB device and one of its interfaces. Important: The sample code featured in this document isintended to illustrate how to access a USB device from an application. It is not intended to provide guidance on error handling and other features required for production-quality code. Using USB Device Interfaces Applications running in OS X get access to USB devices by using I/O Kit functions to acquire a device interface, a type of plug-in that specifies functions the application can call to communicate with the device. The USB family provides two types of device interface: ● IOUSBDeviceInterface for communicating with the device itself ● IOUSBInterfaceInterface for communicating with an interface in the device Both device interfaces are defined in /System/Library/Frameworks/IOKit.framework/Headers/usb/IOUSBLib.h. Communicating with the device itself is usually only necessary when you need to set or change its configuration. For example, vendor-specific devices are often not configured because there are no default drivers that set a particular configuration. In this case, your application must use the device interface for the device to set the configuration it needs so the interfaces become available. Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. The process of finding and communicating with a USB device is divided into two sets of steps. The first set outlines how to find a USB device, acquire a device interface of type IOUSBDeviceInterface for it, and set or change its configuration. The second set describes how to find an interface in a device, acquire a device interface of type IOUSBInterfaceInterface for it, and use it to communicate with that interface. If you need to communicate with an unconfigured device or if you need to change a device’s configuration, you follow both sets of steps. If you need to communicate with a device that is already configured to your 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 20 Working With USB Device Interfacesspecification, you follow only the second set of steps. The sample code in “Accessing a USB Device” (page 22) follows both sets of steps and extends them to include setting up notifications it can receive when devices are dynamically added or removed. Follow this first set of steps only to set or change the configuration of a device. If the device you’re interested in is already configured for your needs, skip these steps and follow the second set of steps. 1. Find the IOUSBDevice object that represents the device in the I/O Registry. This includes setting up a matching dictionary with a key from the USB Common Class Specification (see “Finding USB Devices and Interfaces” (page 12)). The sample code usesthe key elements kUSBVendorName and kUSBProductName to find a particular USB device (this is the second key listed in Table 1-2 (page 12)). 2. Create a device interface of type IOUSBDeviceInterface for the device. This device interface provides functionsthat perform taskssuch assetting or changing the configuration of the device, getting information about the device, and resetting the device. 3. Examine the device’s configurations with GetConfigurationDescriptorPtr, choose the appropriate one, and call SetConfiguration to set the device’s configuration and instantiate the IOUSBInterface objects for that configuration. Follow thissecond set ofstepsto find and choose an interface, acquire a device interface for it, and communicate with the device. 1. Create an interface iterator to iterate over the available interfaces. 2. Create a device interface for each interface so you can examine its properties and select the appropriate one. To do this, you create a device interface of type IOUSBInterfaceInterface. This device interface providesfunctionsthat perform taskssuch as getting information about the interface,setting the interface’s alternate setting, and accessing its pipes. 3. Use the USBInterfaceOpen function to open the selected interface. This will cause the pipes associated with the interface to be instantiated so you can examine the properties of each and select the appropriate one. 4. Communicate with the device through the selected pipe. You can write to and read from the pipe synchronously or asynchronously—the sample code in “Accessing a USB Device” (page 22) shows how to do both. Working With USB Device Interfaces Using USB Device Interfaces 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 21Accessing a USB Device This section provides snippets of sample code that show how to access a Cypress EZ-USB chip with an 8051 microcontroller core. The sample code followsthe firstset ofstepsin section “Using USB Device Interfaces” (page 20) to find the Cypress EZ-USB chip in its default, unprogrammed state (also referred to as the “raw device”). It then configures the device and downloads firmware provided by Cypress to program the chip to behave as a device that echoes all information it receives on its bulk out pipe to its bulk in pipe. Once the chip has been programmed, the device nub representing the default, unprogrammed device is detached from the I/O Registry and a new device nub, representing the programmed chip, is attached. To communicate with the programmed chip (also referred to as the “bulk test device”), the sample code must perform the first set of steps again to find the device, create a device interface for it, and configure it. Then it performs the second set of steps to find an interface, create a device interface for it, and test the device. The sample code also shows how to set up notifications for the dynamic addition and removal of a device. Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. Definitions and Global Variables The code in the USB Notification Example uses the definitions and global variables shown in Listing 2-1 (page 22). The definition of USE_ASYNC_IO allows you to choose to use either synchronous or asynchronous calls to read from and write to the chip by commenting out the line or leaving it in, respectively. The definition of kTestMessage sets up a simple message to write to the device. The remaining definitions are specific to the Cypress EZ-USB chip. Listing 2-1 Definitions and global variables #define USE_ASYNC_IO //Comment this line out if you want to use //synchronous calls for reads and writes #define kTestMessage "Bulk I/O Test" #define k8051_USBCS 0x7f92 #define kOurVendorID 1351 //Vendor ID of the USB device #define kOurProductID 8193 //Product ID of device BEFORE it //is programmed (raw device) #define kOurProductIDBulkTest 4098 //Product ID of device AFTER it is //programmed (bulk test device) //Global variables Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 22static IONotificationPortRef gNotifyPort; static io_iterator_t gRawAddedIter; static io_iterator_t gRawRemovedIter; static io_iterator_t gBulkTestAddedIter; static io_iterator_t gBulkTestRemovedIter; static char gBuffer[64]; The main Function The main function in the USB Notification Example project (contained in the file main.c) accomplishes the following tasks. ● It establishes communication with the I/O Kit and sets up a matching dictionary to find the Cypress EZ-USB chip. ● It sets up an asynchronous notification to be called when an unprogrammed (raw) device is first attached to the I/O Registry and another to be called when the device is removed. ● It modifies the matching dictionary to find the programmed (bulk test) device. ● It sets up additional notifications to be called when the bulk test device is first attached or removed. ● It starts the run loop so the notifications that have been set up will be received. The main function uses I/O Kit functions to set up and modify a matching dictionary and set up notifications, and Core Foundation functions to set up the run loop for receiving the notifications. It calls the following functions to access both the raw device and the bulk test device. ● RawDeviceAdded, shown in Listing 2-3 (page 27), iterates over the set of matching devices and creates a device interface for each one. It calls ConfigureDevice (shown in Listing 2-5 (page 30)) to set the device’s configuration, and then DownloadToDevice (shown in Listing 2-6 (page 32)) to download the firmware to program it. ● RawDeviceRemoved,shown in Listing 2-4 (page 30), iterates over the set of matching devices and releases each one in turn. ● BulkTestDeviceAdded, shown in Listing 2-7 (page 34), iterates over the new set of matching devices, creates a device interface for each one, and calls ConfigureDevice (shown in Listing 2-5 (page 30)) to set the device’s configuration. It then calls FindInterfaces (shown in Listing 2-8 (page 36)) to get access to the interfaces on the device. ● BulkTestDeviceRemoved iterates over the new set of matching devices and releases each one in turn. This function is not shown in this chapter; see RawDeviceRemoved (Listing 2-4 (page 30)) for a nearly identical function. Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 23Listing 2-2 The main function int main (int argc, const char *argv[]) { mach_port_t masterPort; CFMutableDictionaryRef matchingDict; CFRunLoopSourceRef runLoopSource; kern_return_t kr; SInt32 usbVendor = kOurVendorID; SInt32 usbProduct = kOurProductID; // Get command line arguments, if any if (argc > 1) usbVendor = atoi(argv[1]); if (argc > 2) usbProduct = atoi(argv[2]); //Create a master port for communication with the I/O Kit kr = IOMasterPort(MACH_PORT_NULL, &masterPort); if (kr || !masterPort) { printf("ERR: Couldn’t create a master I/O Kit port(%08x)\n", kr); return -1; } //Set up matching dictionary for class IOUSBDevice and its subclasses matchingDict = IOServiceMatching(kIOUSBDeviceClassName); if (!matchingDict) { printf("Couldn’t create a USB matching dictionary\n"); mach_port_deallocate(mach_task_self(), masterPort); return -1; } //Add the vendor and product IDs to the matching dictionary. //This is the second key in the table of device-matching keys of the //USB Common Class Specification Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 24CFDictionarySetValue(matchingDict, CFSTR(kUSBVendorName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbVendor)); CFDictionarySetValue(matchingDict, CFSTR(kUSBProductName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbProduct)); //To set up asynchronous notifications, create a notification port and //add its run loop event source to the program’s run loop gNotifyPort = IONotificationPortCreate(masterPort); runLoopSource = IONotificationPortGetRunLoopSource(gNotifyPort); CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopDefaultMode); //Retain additional dictionary references because each call to //IOServiceAddMatchingNotification consumes one reference matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); //Now set up two notifications: one to be called when a raw device //is first matched by the I/O Kit and another to be called when the //device is terminated //Notification of first match: kr = IOServiceAddMatchingNotification(gNotifyPort, kIOFirstMatchNotification, matchingDict, RawDeviceAdded, NULL, &gRawAddedIter); //Iterate over set of matching devices to access already-present devices //and to arm the notification RawDeviceAdded(NULL, gRawAddedIter); //Notification of termination: kr = IOServiceAddMatchingNotification(gNotifyPort, kIOTerminatedNotification, matchingDict, RawDeviceRemoved, NULL, &gRawRemovedIter); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 25//Iterate over set of matching devices to release each one and to //arm the notification RawDeviceRemoved(NULL, gRawRemovedIter); //Now change the USB product ID in the matching dictionary to match //the one the device will have after the firmware has been downloaded usbProduct = kOurProductIDBulkTest; CFDictionarySetValue(matchingDict, CFSTR(kUSBProductName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbProduct)); //Now set up two notifications: one to be called when a bulk test device //is first matched by the I/O Kit and another to be called when the //device is terminated. //Notification of first match kr = IOServiceAddMatchingNotification(gNotifyPort, kIOFirstMatchNotification, matchingDict, BulkTestDeviceAdded, NULL, &gBulkTestAddedIter); //Iterate over set of matching devices to access already-present devices //and to arm the notification BulkTestDeviceAdded(NULL, gBulkTestAddedIter); //Notification of termination kr = IOServiceAddMatchingNotification(gNotifyPort, kIOTerminatedNotification, matchingDict, BulkTestDeviceRemoved, NULL, &gBulkTestRemovedIter); //Iterate over set of matching devices to release each one and to //arm the notification. NOTE: this function is not shown in this document. BulkTestDeviceRemoved(NULL, gBulkTestRemovedIter); //Finished with master port mach_port_deallocate(mach_task_self(), masterPort); masterPort = 0; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 26//Start the run loop so notifications will be received CFRunLoopRun(); //Because the run loop will run forever until interrupted, //the program should never reach this point return 0; } Working With the Raw Device Now that you’ve obtained an iterator for a set of matching devices, you can use it to gain access to each raw device, configure it, and download the appropriate firmware to it. The function RawDeviceAdded (shown in Listing 2-3 (page 27)) uses I/O Kit functions to create a device interface for each device and then calls the following functions to configure the device and download firmware to it. ● ConfigureDevice, shown in Listing 2-5 (page 30), uses device interface functions to get the number of configurations, examine the first one, and set the device’s configuration. ● DownloadToDevice, shown in Listing 2-6 (page 32), downloads the firmware in bulktest.c to the device. Listing 2-3 Accessing and programming the raw device void RawDeviceAdded(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t usbDevice; IOCFPlugInInterface **plugInInterface = NULL; IOUSBDeviceInterface **dev = NULL; HRESULT result; SInt32 score; UInt16 vendor; UInt16 product; UInt16 release; while (usbDevice = IOIteratorNext(iterator)) { //Create an intermediate plug-in Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 27kr = IOCreatePlugInInterfaceForService(usbDevice, kIOUSBDeviceUserClientTypeID, kIOCFPlugInInterfaceID, &plugInInterface, &score); //Don’t need the device object after intermediate plug-in is created kr = IOObjectRelease(usbDevice); if ((kIOReturnSuccess != kr) || !plugInInterface) { printf("Unable to create a plug-in (%08x)\n", kr); continue; } //Now create the device interface result = (*plugInInterface)->QueryInterface(plugInInterface, CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID), (LPVOID *)&dev); //Don’t need the intermediate plug-in after device interface //is created (*plugInInterface)->Release(plugInInterface); if (result || !dev) { printf("Couldn’t create a device interface (%08x)\n", (int) result); continue; } //Check these values for confirmation kr = (*dev)->GetDeviceVendor(dev, &vendor); kr = (*dev)->GetDeviceProduct(dev, &product); kr = (*dev)->GetDeviceReleaseNumber(dev, &release); if ((vendor != kOurVendorID) || (product != kOurProductID) || (release != 1)) { printf("Found unwanted device (vendor = %d, product = %d)\n", vendor, product); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 28(void) (*dev)->Release(dev); continue; } //Open the device to change its state kr = (*dev)->USBDeviceOpen(dev); if (kr != kIOReturnSuccess) { printf("Unable to open device: %08x\n", kr); (void) (*dev)->Release(dev); continue; } //Configure device kr = ConfigureDevice(dev); if (kr != kIOReturnSuccess) { printf("Unable to configure device: %08x\n", kr); (void) (*dev)->USBDeviceClose(dev); (void) (*dev)->Release(dev); continue; } //Download firmware to device kr = DownloadToDevice(dev); if (kr != kIOReturnSuccess) { printf("Unable to download firmware to device: %08x\n", kr); (void) (*dev)->USBDeviceClose(dev); (void) (*dev)->Release(dev); continue; } //Close this device and release object kr = (*dev)->USBDeviceClose(dev); kr = (*dev)->Release(dev); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 29} } The function RawDeviceRemoved simply uses the iterator obtained from the main function (shown in Listing 2-2 (page 24)) to release each device object. This also has the effect of arming the raw device termination notification so it will notify the program of future device removals. RawDeviceRemoved is shown in Listing 2-4 (page 30). Listing 2-4 Releasing the raw device objects void RawDeviceRemoved(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t object; while (object = IOIteratorNext(iterator)) { kr = IOObjectRelease(object); if (kr != kIOReturnSuccess) { printf("Couldn’t release raw device object: %08x\n", kr); continue; } } } Although every USB device has one or more configurations, unless the device is a composite class device that’s been matched by the AppleUSBComposite driver which automatically sets the first configuration, none of those configurations may have been set. Therefore, your application may have to use device interface functions to get the appropriate configuration value and use it to set the device’s configuration. In the sample code, the function ConfigureDevice (shown in Listing 2-5 (page 30)) accomplishes this task. In fact, it is called twice: once by RawDeviceAdded to configure the raw device and again by BulkTestDeviceAdded (shown in Listing 2-7 (page 34)) to configure the bulk test device. Listing 2-5 Configuring a USB device IOReturn ConfigureDevice(IOUSBDeviceInterface **dev) Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 30{ UInt8 numConfig; IOReturn kr; IOUSBConfigurationDescriptorPtr configDesc; //Get the number of configurations. The sample code always chooses //the first configuration (at index 0) but your code may need a //different one kr = (*dev)->GetNumberOfConfigurations(dev, &numConfig); if (!numConfig) return -1; //Get the configuration descriptor for index 0 kr = (*dev)->GetConfigurationDescriptorPtr(dev, 0, &configDesc); if (kr) { printf("Couldn’t get configuration descriptor for index %d (err = %08x)\n", 0, kr); return -1; } //Set the device’s configuration. The configuration value is found in //the bConfigurationValue field of the configuration descriptor kr = (*dev)->SetConfiguration(dev, configDesc->bConfigurationValue); if (kr) { printf("Couldn’t set configuration to value %d (err = %08x)\n", 0, kr); return -1; } return kIOReturnSuccess; } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 31Now that the device is configured, you can download firmware to it. Cypress makes firmware available to program the EZ-USB chip to emulate different devices. The sample code in this document uses firmware that programs the chip to be a bulk test device, a device that takes the data it receives from its bulk out pipe and echoesit to its bulk in pipe. The firmware, contained in the file bulktest.c, is an array of INTEL_HEX_RECORD structures (defined in the file hex2c.h). The function DownloadToDevice uses the function WriteToDevice (shown together in Listing 2-6 (page 32)) to prepare the device to receive the download and then to write information from each structure to the appropriate address on the device. When all the firmware has been downloaded, DownloadToDevice calls WriteToDevice a last time to inform the device that the download is complete. At this point, the raw device detaches itself from the bus and reattaches as a bulk test device. This causes the device nub representing the raw device to be removed from the I/O Registry and a new device nub, representing the bulk test device, to be attached. Listing 2-6 Two functions to download firmware to the raw device IOReturn DownloadToDevice(IOUSBDeviceInterface **dev) { int i; UInt8 writeVal; IOReturn kr; //Assert reset. This tells the device that the download is //about to occur writeVal = 1; //For this device, a value of 1 indicates a download kr = WriteToDevice(dev, k8051_USBCS, 1, &writeVal); if (kr != kIOReturnSuccess) { printf("WriteToDevice reset returned err 0x%x\n", kr); (*dev)->USBDeviceClose(dev); (*dev)->Release(dev); return kr; } //Download firmware i = 0; while (bulktest[i].Type == 0) //While bulktest[i].Type == 0, this is Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 32{ //not the last firmware record to //download kr = WriteToDevice(dev, bulktest[i].Address, bulktest[i].Length, bulktest[i].Data); if (kr != kIOReturnSuccess) { printf("WriteToDevice download %i returned err 0x%x\n", i, kr); (*dev)->USBDeviceClose(dev); (*dev)->Release(dev); return kr; } i++; } //De-assert reset. This tells the device that the download is complete writeVal = 0; kr = WriteToDevice(dev, k8051_USBCS, 1, &writeVal); if (kr != kIOReturnSuccess) printf("WriteToDevice run returned err 0x%x\n", kr); return kr; } IOReturn WriteToDevice(IOUSBDeviceInterface **dev, UInt16 deviceAddress, UInt16 length, UInt8 writeBuffer[]) { IOUSBDevRequest request; request.bmRequestType = USBmakebmRequestType(kUSBOut, kUSBVendor, kUSBDevice); request.bRequest = 0xa0; request.wValue = deviceAddress; request.wIndex = 0; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 33request.wLength = length; request.pData = writeBuffer; return (*dev)->DeviceRequest(dev, &request); } Working With the Bulk Test Device After you download the firmware to the device, the raw device is no longer attached to the bus. To gain access to the bulk test device, you repeat most of the same steps you used to get access to the raw device. ● Use the iterator obtained by a call to IOServiceAddMatchingNotification in the main function (shown in Listing 2-2 (page 24)) to iterate over a set of matching devices. ● Create a device interface for each device. ● Configure the device. This time, however, the next step is to find the interfaces on the device so you can choose the appropriate one and get access to its pipes. Because of the similarities of these tasks, the function BulkTestDeviceAdded follows the same outline of the RawDeviceAdded function except that instead of downloading firmware to the device, it calls FindInterfaces (shown in Listing 2-8 (page 36)) to examine the available interfaces and their pipes. The code in Listing 2-7 (page 34) replaces most of the BulkTestDeviceAdded function’s code with comments, focusing on the differences between it and the RawDeviceAdded function. Listing 2-7 Accessing the bulk test device void BulkTestDeviceAdded(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t usbDevice; IOUSBDeviceInterface **device=NULL; while (usbDevice = IOIteratorNext(iterator)) { //Create an intermediate plug-in using the //IOCreatePlugInInterfaceForService function //Release the device object after getting the intermediate plug-in Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 34//Create the device interface using the QueryInterface function //Release the intermediate plug-in object //Check the vendor, product, and release number values to //confirm we’ve got the right device //Open the device before configuring it kr = (*device)->USBDeviceOpen(device); //Configure the device by calling ConfigureDevice //Close the device and release the device interface object if //the configuration is unsuccessful //Get the interfaces kr = FindInterfaces(device); if (kr != kIOReturnSuccess) { printf("Unable to find interfaces on device: %08x\n", kr); (*device)->USBDeviceClose(device); (*device)->Release(device); continue; } //If using synchronous IO, close and release the device interface here #ifndef USB_ASYNC_IO kr = (*device)->USBDeviceClose(device); kr = (*device)->Release(device); #endif } } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 35The function BulkTestDeviceRemoved simply uses the iterator obtained from the main function (shown in Listing 2-2 (page 24)) to release each device object. This also has the effect of arming the bulk test device termination notification so it will notify the program of future device removals.The BulkTestDeviceRemoved function is identical to the RawDeviceRemoved function (shown in Listing 2-4 (page 30)), with the exception of the wording of the printed error statement. Working With Interfaces Now that you’ve configured the device, you have access to its interfaces. The FindInterfaces function (shown in Listing 2-8 (page 36)) creates an iterator to iterate over all interfaces on the device and then creates a device interface to communicate with each one. For each interface found, the function opens the interface, determines how many endpoints (or pipes) it has, and prints out the properties of each pipe. Because opening an interface causes its pipes to be instantiated, you can get access to any pipe by using its pipe index. The pipe index is the number of the pipe within the interface, ranging from one to the number of endpoints returned by GetNumEndpoints. You can communicate with the default control pipe (described in “USB Transfer Types” (page 8)) from any interface by using pipe index 0, but it is usually better to use the device interface functions for the device itself (see the use of IOUSBDeviceInterface functions in Listing 2-5 (page 30)). The sample code employs conditional compilation using #ifdef and #ifndef to demonstrate both synchronous and asynchronous I/O. If you’ve chosen to test synchronous I/O, FindInterfaces writes the test message (defined in Listing 2-1 (page 22)) to pipe index 2 on the device and readsits echo before returning. For asynchronous I/O, FindInterfaces first creates an event source and adds it to the run loop created by the main function (shown in Listing 2-2 (page 24)). It then sets up an asynchronous write and read that will cause a notification to be sent upon completion. The completion functions WriteCompletion and ReadCompletion are shown together in Listing 2-9 (page 43). Listing 2-8 Finding interfaces on the bulk test device IOReturn FindInterfaces(IOUSBDeviceInterface **device) { IOReturn kr; IOUSBFindInterfaceRequest request; io_iterator_t iterator; io_service_t usbInterface; IOCFPlugInInterface **plugInInterface = NULL; IOUSBInterfaceInterface **interface = NULL; HRESULT result; SInt32 score; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 36UInt8 interfaceClass; UInt8 interfaceSubClass; UInt8 interfaceNumEndpoints; int pipeRef; #ifndef USE_ASYNC_IO UInt32 numBytesRead; UInt32 i; #else CFRunLoopSourceRef runLoopSource; #endif //Placing the constant kIOUSBFindInterfaceDontCare into the following //fields of the IOUSBFindInterfaceRequest structure will allow you //to find all the interfaces request.bInterfaceClass = kIOUSBFindInterfaceDontCare; request.bInterfaceSubClass = kIOUSBFindInterfaceDontCare; request.bInterfaceProtocol = kIOUSBFindInterfaceDontCare; request.bAlternateSetting = kIOUSBFindInterfaceDontCare; //Get an iterator for the interfaces on the device kr = (*device)->CreateInterfaceIterator(device, &request, &iterator); while (usbInterface = IOIteratorNext(iterator)) { //Create an intermediate plug-in kr = IOCreatePlugInInterfaceForService(usbInterface, kIOUSBInterfaceUserClientTypeID, kIOCFPlugInInterfaceID, &plugInInterface, &score); //Release the usbInterface object after getting the plug-in kr = IOObjectRelease(usbInterface); if ((kr != kIOReturnSuccess) || !plugInInterface) { printf("Unable to create a plug-in (%08x)\n", kr); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 37break; } //Now create the device interface for the interface result = (*plugInInterface)->QueryInterface(plugInInterface, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID), (LPVOID *) &interface); //No longer need the intermediate plug-in (*plugInInterface)->Release(plugInInterface); if (result || !interface) { printf("Couldn’t create a device interface for the interface (%08x)\n", (int) result); break; } //Get interface class and subclass kr = (*interface)->GetInterfaceClass(interface, &interfaceClass); kr = (*interface)->GetInterfaceSubClass(interface, &interfaceSubClass); printf("Interface class %d, subclass %d\n", interfaceClass, interfaceSubClass); //Now open the interface. This will cause the pipes associated with //the endpoints in the interface descriptor to be instantiated kr = (*interface)->USBInterfaceOpen(interface); if (kr != kIOReturnSuccess) { printf("Unable to open interface (%08x)\n", kr); (void) (*interface)->Release(interface); break; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 38} //Get the number of endpoints associated with this interface kr = (*interface)->GetNumEndpoints(interface, &interfaceNumEndpoints); if (kr != kIOReturnSuccess) { printf("Unable to get number of endpoints (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } printf("Interface has %d endpoints\n", interfaceNumEndpoints); //Access each pipe in turn, starting with the pipe at index 1 //The pipe at index 0 is the default control pipe and should be //accessed using (*usbDevice)->DeviceRequest() instead for (pipeRef = 1; pipeRef <= interfaceNumEndpoints; pipeRef++) { IOReturn kr2; UInt8 direction; UInt8 number; UInt8 transferType; UInt16 maxPacketSize; UInt8 interval; char *message; kr2 = (*interface)->GetPipeProperties(interface, pipeRef, &direction, &number, &transferType, &maxPacketSize, &interval); if (kr2 != kIOReturnSuccess) printf("Unable to get properties of pipe %d (%08x)\n", pipeRef, kr2); else Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 39{ printf("PipeRef %d: ", pipeRef); switch (direction) { case kUSBOut: message = "out"; break; case kUSBIn: message = "in"; break; case kUSBNone: message = "none"; break; case kUSBAnyDirn: message = "any"; break; default: message = "???"; } printf("direction %s, ", message); switch (transferType) { case kUSBControl: message = "control"; break; case kUSBIsoc: message = "isoc"; break; case kUSBBulk: message = "bulk"; break; case kUSBInterrupt: message = "interrupt"; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 40break; case kUSBAnyType: message = "any"; break; default: message = "???"; } printf("transfer type %s, maxPacketSize %d\n", message, maxPacketSize); } } #ifndef USE_ASYNC_IO //Demonstrate synchronous I/O kr = (*interface)->WritePipe(interface, 2, kTestMessage, strlen(kTestMessage)); if (kr != kIOReturnSuccess) { printf("Unable to perform bulk write (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } printf("Wrote \"%s\" (%ld bytes) to bulk endpoint\n", kTestMessage, (UInt32) strlen(kTestMessage)); numBytesRead = sizeof(gBuffer) - 1; //leave one byte at the end //for NULL termination kr = (*interface)->ReadPipe(interface, 9, gBuffer, &numBytesRead); if (kr != kIOReturnSuccess) { printf("Unable to perform bulk read (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 41break; } //Because the downloaded firmware echoes the one’s complement of the //message, now complement the buffer contents to get the original data for (i = 0; i < numBytesRead; i++) gBuffer[i] = ~gBuffer[i]; printf("Read \"%s\" (%ld bytes) from bulk endpoint\n", gBuffer, numBytesRead); #else //Demonstrate asynchronous I/O //As with service matching notifications, to receive asynchronous //I/O completion notifications, you must create an event source and //add it to the run loop kr = (*interface)->CreateInterfaceAsyncEventSource( interface, &runLoopSource); if (kr != kIOReturnSuccess) { printf("Unable to create asynchronous event source (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopDefaultMode); printf("Asynchronous event source added to run loop\n"); bzero(gBuffer, sizeof(gBuffer)); strcpy(gBuffer, kTestMessage); kr = (*interface)->WritePipeAsync(interface, 2, gBuffer, strlen(gBuffer), WriteCompletion, (void *) interface); if (kr != kIOReturnSuccess) Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 42{ printf("Unable to perform asynchronous bulk write (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } #endif //For this test, just use first interface, so exit loop break; } return kr; } When an asynchronous write action is complete, the WriteCompletion function is called by the notification. WriteCompletion then calls the interface function ReadPipeAsync to perform an asynchronous read from the pipe. When the read is complete, control passes to ReadCompletion which simply prints status messages and adds a NULL termination to the global buffer containing the test message read from the device. The WriteCompletion and ReadCompletion functions are shown together in Listing 2-9 (page 43). Listing 2-9 Two asynchronous I/O completion functions void WriteCompletion(void *refCon, IOReturn result, void *arg0) { IOUSBInterfaceInterface **interface = (IOUSBInterfaceInterface **) refCon; UInt32 numBytesWritten = (UInt32) arg0; UInt32 numBytesRead; printf("Asynchronous write complete\n"); if (result != kIOReturnSuccess) { printf("error from asynchronous bulk write (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 43printf("Wrote \"%s\" (%ld bytes) to bulk endpoint\n", kTestMessage, numBytesWritten); numBytesRead = sizeof(gBuffer) - 1; //leave one byte at the end for //NULL termination result = (*interface)->ReadPipeAsync(interface, 9, gBuffer, numBytesRead, ReadCompletion, refCon); if (result != kIOReturnSuccess) { printf("Unable to perform asynchronous bulk read (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } } void ReadCompletion(void *refCon, IOReturn result, void *arg0) { IOUSBInterfaceInterface **interface = (IOUSBInterfaceInterface **) refCon; UInt32 numBytesRead = (UInt32) arg0; UInt32 i; printf("Asynchronous bulk read complete\n"); if (result != kIOReturnSuccess) { printf("error from async bulk read (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } //Check the complement of the buffer’s contents for original data for (i = 0; i < numBytesRead; i++) gBuffer[i] = ~gBuffer[i]; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 44printf("Read \"%s\" (%ld bytes) from bulk endpoint\n", gBuffer, numBytesRead); } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 45This table describes the changes to USB Device Interface Guide . Date Notes 2012-01-09 Added information about App Sandbox. 2007-09-04 Made minor corrections. Described how to determine which version of an interface object to use when accessing a USB device or interface. 2007-02-08 2006-04-04 Made minor corrections. Emphasized which type of device interface to get for USB devices and interfaces and clarified definition of composite class device. 2006-03-08 2005-11-09 Made minor corrections. Added information about creating a universal binary for an application that accesses a USB device. 2005-09-08 2005-08-11 Made minor bug fixes. Added information about low latency isochronous transactions and functions. 2005-06-04 Included discussion of USB 2.0 and associated changes to isochronous functions. Changed title from "Working With USB Device Interfaces." 2005-04-29 2004-05-27 Fixed URL for USB Common Class Specification. 2002-11-15 First version. 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 46 Document Revision HistoryApple Inc. © 2002, 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, Finder, Mac, Macintosh, OS X, Pages, Sand, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Intel and Intel Core are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. PowerPC and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. 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. Core Data Model Versioning and Data Migration Programming GuideContents Core Data Model Versioning and Data Migration 5 At a Glance 5 Prerequisites 6 Understanding Versions 7 Model File Format and Versions 10 Lightweight Migration 12 Core Data Must Be Able to Infer the Mapping 12 Request Automatic Migration Using an Options Dictionary 13 Use a Migration Manager if Models Cannot Be Found Automatically 14 Mapping Overview 17 Mapping Model Objects 17 Creating a Mapping Model in Xcode 19 The Migration Process 20 Overview 20 Requirements for the Migration Process 20 Custom Entity Migration Policies 21 Three-Stage Migration 21 Initiating the Migration Process 23 Initiating the Migration Process 23 The Default Migration Process 24 Customizing the Migration Process 26 Is Migration Necessary 26 Initializing a Migration Manager 27 Performing a Migration 28 Multiple Passes—Dealing With Large Datasets 29 Migration and iCloud 30 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 2Document Revision History 31 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsFigures and Listings Understanding Versions 7 Figure 1-1 Recipes models “Version 1.0” 7 Figure 1-2 Recipes model “Version 1.1” 7 Figure 1-3 Recipes model “Version 2.0” 8 Model File Format and Versions 10 Figure 2-1 Initial version of the Core Recipes model 10 Figure 2-2 Version 2 of the Core Recipes model 11 Mapping Overview 17 Figure 4-1 Mapping model for versions 1-2 of the Core Recipes models 19 Initiating the Migration Process 23 Listing 6-1 Opening a store using automatic migration 24 Customizing the Migration Process 26 Listing 7-1 Checking whether migration is necessary 26 Listing 7-2 Initializing a Migration Manager 27 Listing 7-3 Performing a Migration 28 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 4Core Data provides support for managing changes to a managed object model as your application evolves. You can only open a Core Data store using the managed object model used to create it. Changing a model will therefore make it incompatible with (and so unable to open) the stores it previously created. If you change your model, you therefore need to change the data in existing stores to new version—changing the store format is known as migration. To migrate a store, you need both the version of the model used to create it, and the current version of the model you want to migrate to. You can create a versioned model that contains more than one version of a managed object model. Within the versioned model you mark one version as being the current version. Core Data can then use this model to open persistent stores created using any of the model versions, and migrate the stores to the current version. To help Core Data perform the migration, though, you may have to provide information about how to map from one version of the model to another. This information may be in the form of hints within the versioned model itself, or in a separate mapping model file that you create. At a Glance Typically, as it evolves from one version to another, numerous aspects of your application change: the classes you implement, the user interface, the file format, and so on. You need to be aware of and in control of all these aspects; there is no API that solves the problems associated with all these—for example Cocoa does not provide a means to automatically update your user interface if you add a new attribute to an entity in your managed object model. Core Data does not solve all the issues of how you roll out your application. It does, though, provide support for a small—but important and non-trivial—subset of the tasks you must perform as your application evolves. ● Model versioning allows you to specify and distinguish between different configurations of your schema. There are two distinct views of versioning: your perspective as a developer, and Core Data’s perspective. These may not always be the same. The differences are discussed in “Understanding Versions” (page 7). The format of a versioned managed object model, and how you add a version to a model, is discussed in “Model File Format and Versions” (page 10). ● Core Data needs to know how to map from the entities and properties in a source model to the entities and properties in the destination model. 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 5 Core Data Model Versioning and Data MigrationIn many cases, Core Data can infer the mapping from existing versions of the managed object model. This is described in “Lightweight Migration” (page 12). If you make changes to your models such that Core Data cannot infer the mapping from source to destination, you need to create a mapping model. A mapping model parallels a managed object model, specifying how to transform objects in the source into instances appropriate for the destination. How you create a mapping model is discussed in “Mapping Overview” (page 17). ● Data migration allows you to convert data from one model (schema) to another, using mappings. The migration process itself is discussed in “The Migration Process” (page 20). How you perform a migration is discussed in “Initiating the Migration Process” (page 23). You can also customize the migration process—that is, how you programmatically determine whether migration is necessary; how you find the correct source and destination models and the appropriate mapping model to initialize the migration manager; and then how you perform the migration. You only customize the migration process if you want to initiate migration yourself. You might do this to, for example, search locations other than the application’s main bundle for models or to deal with large data sets by performing the migration in several passes using different mapping models. How you can customize the process is described in “Customizing the Migration Process” (page 26). ● If you are using iCloud, there are some constraints on what migration you can perform. If you are using iCloud, you must use lightweight migration. Other factors to be aware of are described in “Migration and iCloud” (page 30). Although Core Data makes versioning and migration easier than would typically otherwise be the case, these processes are still non-trivial in effect. You still need to carefully consider the implications of releasing and supporting different versions of your application. Prerequisites This document assumes that you are familiar with the Core Data architecture and the fundamentals of using Core Data. You should be able to identify the parts of the Core Data stack and understand the roles of the model, the managed object context, and the persistent store coordinator. You need to know how to create a managed object model, how to create and programmatically interact with parts of the Core Data stack. If you do not meet these requirements, you should first read the Core Data Programming Guide and related materials. You are strongly encouraged also to work through the Core Data Utility Tutorial . Core Data Model Versioning and Data Migration Prerequisites 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 6There are two distinct views of versioning: your perspective as a developer, and Core Data’s perspective. These may not always be the same—consider the following models. Figure 1-1 Recipes models “Version 1.0” Recipe Attributes cuisine directions name Relationships chef ingredients Chef Attributes name training Relationships recipes Ingredient Attributes amount name Relationships recipes Figure 1-2 Recipes model “Version 1.1” Recipe Attributes cuisine directions name Relationships chef ingredients Chef Attributes name training Relationships recipes Ingredient Attributes amount name Relationships recipes Recipe changes: • Add validation rules • Change User Info values • Use custom class 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 7 Understanding VersionsFigure 1-3 Recipes model “Version 2.0” Recipe Attributes directions name rating Relationships chef cuisines ingredients Chef Attributes firstName lastName Relationships recipes Ingredient Attributes amount name Relationships recipe Cuisine Attributes name Relationships recipes As a developer, your perspective is typically that a version is denoted by an identifier—a string or number, such as “9A218”, “2.0.7”, or “Version 1.1”. To support this view, managed object models have a set of identifiers (see versionIdentifiers)—typically for a single model you provide a single string (the attribute itself is a set so that if models are merged all the identifiers can be preserved). How the identifier should be interpreted is up to you, whether it represents the version number of the application, the version that was committed prior to going on vacation, or the last submission before it stopped working. Core Data, on the other hand, treats these identifiers simply as “hints”. To understand why, recall that the format of a persistent store is dependent upon the model used to create it, and that to open a persistent store you must have a model that is compatible with that used to create it. Consider then what would happen if you changed the model but not the identifier—for example, if you kept the identifier the same but removed one entity and added two others. To Core Data, the change in the schema is significant, the fact that the identifier did not change is irrelevant. Core Data’s perspective on versioning isthat it is only interested in features of the model that affect persistence. This means that for two models to be compatible: ● For each entity the following attributes must be equal: name, parent, isAbstract, and properties. className, userInfo, and validation predicates are not compared. ● For each property in each entity, the following attributes must be equal: name, isOptional, isTransient, isReadOnly, for attributes attributeType, and for relationships destinationEntity, minCount, maxCount, deleteRule, and inverseRelationship. userInfo and validation predicates are not compared. Notice that Core Data ignores any identifiers you set. In the examples above, Core Data treats version 1.0 (Figure 1-1 (page 7)) and 1.1 (Figure 1-2 (page 7)) as being compatible. Understanding Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 8Rather than enumerating through all the relevant parts of a model, Core Data creates a 32-byte hash digest of the components which it compares for equality (see versionHash (NSEntityDescription) and versionHash (NSPropertyDescription)). These hashes are included in a store’s metadata so that Core Data can quickly determine whether the store format matches that of the managed object model it may use to try to open the store. (When you attempt to open a store using a given model, Core Data compares the version hashes of each of the entities in the store with those of the entities in the model, and if all are the same then the store is opened.) There is typically no reason for you to be interested in the value of a hash. There may, however, be some situations in which you have two versions of a model that Core Data would normally treat as equivalent that you want to be recognized as being different. For example, you might change the name of the class used to represent an entity, or more subtly you might keep the model the same but change the internal format of an attribute such as a BLOB—this is irrelevant to Core Data, but it is crucial for the integrity of your data. To support this, Core Data allows you to set a hash modifier for an entity or property see versionHashModifier (NSEntityDescription) and versionHashModifier (NSPropertyDescription). In the examples above, if you wanted to force Core Data to recognize that “Version 1.0” (Figure 1-1 (page 7)) and “Version 1.1” (Figure 1-2 (page 7)) of your models are different, you could set an entity modifier for the Recipe entity in the second model to change the version hash Core Data creates. Understanding Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 9A managed object model that supports versioning is represented in the filesystem by a .xcdatamodeld document. An .xcdatamodeld document is a file package (see “Document Packages”) that groups versions of the model, each represented by an individual .xcdatamodel file, and an Info.plist file that contains the version information. The model is compiled into a runtime format—a file package with a .momd extension that containsindividually compiled model files with a .mom extension. You load the .momd model bundle using NSManagedObjectModel’s initWithContentsOfURL:. To add a version to a model, you start with a model such as that illustrated in Figure 2-1. Figure 2-1 Initial version of the Core Recipes model 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 10 Model File Format and VersionsTo add a version, select Editor > Add Model Version. In the sheet that appears, you enter the name of the new model version and select the model on which it should be based. To set the new model asthe current version of the model,select the .xcdatamodeld document in the project navigator, then select the new model in the pop-up menu in the Versioned Core Data Model area in the Attributes Inspector (see Figure 2-2). Figure 2-2 Version 2 of the Core Recipes model Model File Format and Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 11If you just make simple changes to your model (such as adding a new attribute to an entity), Core Data can perform automatic data migration, referred to aslightweightmigration. Lightweight migration isfundamentally the same as ordinary migration, except that instead of you providing a mapping model (as described in “Mapping Overview” (page 17)), Core Data infers one from differences between the source and destination managed object models. Lightweight migration is especially convenient during early stages of application development, when you may be changing your managed object model frequently, but you don’t want to have to keep regenerating test data. You can migrate existing data without having to create a custom mapping model for every model version used to create a store that would need to be migrated. A further advantage of using lightweight migration—beyond the fact that you don’t need to create the mapping model yourself—is that if you use an inferred model and you use the SQLite store, then Core Data can perform the migration in situ (solely by issuing SQL statements). This can represent a significant performance benefit as Core Data doesn’t have to load any of your data. Because of this, you are encouraged to use inferred migration where possible, even if the mapping model you might create yourself would be trivial. Core Data Must Be Able to Infer the Mapping To perform automatic lightweight migration, Core Data needs to be able to find the source and destination managed object models itself at runtime. Core Data looks for models in the bundles returned by NSBundle’s allBundles and allFrameworks methods. If you store your models elsewhere, you must follow the steps described in “Use a Migration Manager if Models Cannot Be Found Automatically ” (page 14). Core Data must then analyze the schema changes to persistent entities and properties and generate an inferred mapping model. For Core Data to be able to generate an inferred mapping model, changes must fit an obvious migration pattern, for example: ● Simple addition of a new attribute ● Removal of an attribute ● A non-optional attribute becoming optional ● An optional attribute becoming non-optional, and defining a default value 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 12 Lightweight Migration● Renaming an entity or property If you rename an entity or property, you can set the renaming identifier in the destination model to the name of the corresponding property or entity in the source model. You set the renaming identifier in the managed object model using the Xcode Data Modeling tool’s property inspector (for either an entity or a property). For example, you can: ● Rename a Car entity to Automobile ● Rename a Car’s color attribute to paintColor The renaming identifier creates a “canonical name,” so you should set the renaming identifier to the name of the property in the source model (unless that property already has a renaming identifier). This means you can rename a property in version 2 of a model then rename it again version 3, and the renaming will work correctly going from version 2 to version 3 or from version 1 to version 3. In addition, Core Data supports: ● Adding relationships and changing the type of relationship ● You can add a new relationship or delete an existing relationship. ● Renaming a relationship (by using a renaming identifier, just like an attribute) ● Changing a relationship from a to-one to a to-many, or a non-ordered to-many to ordered (and visa-versa) ● Changing the entity hierarchy ● You can add, remove, rename entities ● You can create a new parent or child entity and move properties up and down the entity hierarchy ● You can move entities out of a hierarchy You cannot, however, merge entity hierarchies; if two existing entities do not share a common parent in the source, they cannot share a common parent in the destination Request Automatic Migration Using an Options Dictionary You request automatic lightweight migration using the options dictionary you pass in addPersistentStoreWithType:configuration:URL:options:error:, by setting values corresponding to both the NSMigratePersistentStoresAutomaticallyOption and the NSInferMappingModelAutomaticallyOption keys to YES: NSError *error = nil; Lightweight Migration Request Automatic Migration Using an Options Dictionary 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 13NSURL *storeURL = <#The URL of a persistent store#>; NSPersistentStoreCoordinator *psc = <#The coordinator#>; NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys: [NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption, [NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, nil]; BOOL success = [psc addPersistentStoreWithType:<#Store type#> configuration:<#Configuration or nil#> URL:storeURL options:options error:&error]; if (!success) { // Handle the error. } If you want to determine in advance whether Core Data can infer the mapping between the source and destination models without actually doing the work of migration, you can use NSMappingModel’s inferredMappingModelForSourceModel:destinationModel:error: method. Thisreturnsthe inferred model if Core Data is able to create it, otherwise nil. Use a Migration Manager if Models Cannot Be Found Automatically To perform automatic migration, Core Data has to be able to find the source and destination managed object models itself at runtime (see “Core Data Must Be Able to Infer the Mapping” (page 12)). If you need to put your models in the locations not checked by automatic discovery, then you need to generate the inferred model and initiate the migration yourself using a migration manager (an instance of NSMigrationManager). The following code sample illustrates how to generate an inferred model and initiate the migration using a migration manager. The code assumes that you have implemented two methods—sourceModel and destinationModel—that return the source and destination managed object models respectively. - (BOOL)migrateStore:(NSURL *)storeURL toVersionTwoStore:(NSURL *)dstStoreURL error:(NSError **)outError { // Try to get an inferred mapping model. NSMappingModel *mappingModel = [NSMappingModel inferredMappingModelForSourceModel:[self sourceModel] destinationModel:[self destinationModel] error:outError]; Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 14// If Core Data cannot create an inferred mapping model, return NO. if (!mappingModel) { return NO; } // Create a migration manager to perform the migration. NSMigrationManager *manager = [[NSMigrationManager alloc] initWithSourceModel:[self sourceModel] destinationModel:[self destinationModel]]; BOOL success = [manager migrateStoreFromURL:storeURL type:NSSQLiteStoreType options:nil withMappingModel:mappingModel toDestinationURL:dstStoreURL destinationType:NSSQLiteStoreType destinationOptions:nil error:outError]; return success; } Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 15Note: Prior to OS X v10.7 and iOS 4, you need to use a store-specific migration manager to perform lightweight migration. You get the migration manager for a given persistent store type using migrationManagerClass, as illustrated in the following example. - (BOOL)migrateStore:(NSURL *)storeURL toVersionTwoStore:(NSURL *)dstStoreURL error:(NSError **)outError { // Try to get an inferred mapping model. NSMappingModel *mappingModel = [NSMappingModel inferredMappingModelForSourceModel:[self sourceModel] destinationModel:[self destinationModel] error:outError]; // If Core Data cannot create an inferred mapping model, return NO. if (!mappingModel) { return NO; } // Get the migration manager class to perform the migration. NSValue *classValue = [[NSPersistentStoreCoordinator registeredStoreTypes] objectForKey:NSSQLiteStoreType]; Class sqliteStoreClass = (Class)[classValue pointerValue]; Class sqliteStoreMigrationManagerClass = [sqliteStoreClass migrationManagerClass]; NSMigrationManager *manager = [[sqliteStoreMigrationManagerClass alloc] initWithSourceModel:[self sourceModel] destinationModel:[self destinationModel]]; BOOL success = [manager migrateStoreFromURL:storeURL type:NSSQLiteStoreType options:nil withMappingModel:mappingModel toDestinationURL:dstStoreURL destinationType:NSSQLiteStoreType destinationOptions:nil error:outError]; return success; } Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 16In many cases, Core Data may be able to infer how to transform data from one schema to another (see “Lightweight Migration” (page 12). If Core Data cannot infer the mapping from one model to another, you need a definition of how to perform the transformation. This information is captured in a mapping model. A mapping model is a collection of objects that specifies the transformations that are required to migrate part of a store from one version of your model to another (for example, that one entity is renamed, an attribute is added to another, and a third split into two). You typically create a mapping model in Xcode. Much as the managed object model editor allows you to graphically create the model, the mapping model editor allows you to customize the mappings between the source and destination entities and properties. Mapping Model Objects Like a managed object model, a mapping model is a collection of objects. Mapping model classes parallel the managed object model classes—there are mapping classes for a model, an entity, and a property (NSMappingModel, NSEntityMapping, and NSPropertyMapping respectively). ● An instance of NSEntityMapping specifies a source entity, a destination entity (the type of object to create to correspond to the source object) and mapping type (add, remove, copy as is, or transform). ● An instance of NSPropertyMapping specifiesthe name of the property in the source and in the destination entity, and a value expression to create the value for the destination property. The model does not contain instances of NSEntityMigrationPolicy or any of its subclasses, however amongst other attributes instance of NSEntityMapping can specify the name of an entity migration policy class (a subclass of NSEntityMigrationPolicy) to use to customize the migration. For more about entity migration policy classes, see “Custom Entity Migration Policies” (page 21). You can handle simple property migration changes by configuring a custom value expression on a property mapping directly in the mapping model editor in Xcode. For example, you can: ● Migrate data from one attribute to another. To rename amount to totalCost, enter the custom value expression for the totalCost property mapping as $source.amount. ● Apply a value transformation on a property. 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 17 Mapping OverviewTo convert temperature from Fahrenheit to Celsius, use the custom value expression ($source.temperature - 32.0) / 1.8. ● Migrate objects from one relationship to another. To rename trades to transactions, enter the custom value expression for the transactions property mapping as FUNCTION($manager, "destinationInstancesForEntityMappingNamed:sourceInstances:", "TradeToTrade", $source.trades). (This assumes the entity mapping that migrates Trade instances is named TradeToTrade.) There are six predefined keys you can reference in custom value expressions. To access these keys in source code, you use the constants as declared. To access them in custom value expression strings in the mapping model editor in Xcode, follow the syntax rules outlined in the predicate format string syntax guide and refer to them as: NSMigrationManagerKey: $manager NSMigrationSourceObjectKey: $source NSMigrationDestinationObjectKey: $destination NSMigrationEntityMappingKey: $entityMapping NSMigrationPropertyMappingKey: $propertyMapping NSMigrationEntityPolicyKey: $entityPolicy Mapping Overview Mapping Model Objects 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 18Creating a Mapping Model in Xcode From the File menu, you select New File and in the New File pane select Design > Mapping Model. In the following pane, you select the source and destination models. When you click Finish, Xcode creates a new mapping model that contains as many default mappings as it can deduce from the source and destination. For example, given the model files shown in Figure 1-1 (page 7) and Figure 1-2 (page 7), Xcode creates a mapping model as shown in Figure 4-1. Figure 4-1 Mapping model for versions 1-2 of the Core Recipes models Reserved words in custom value expressions: If you use a custom value expression, you must escape reserved words such as SIZE, FIRST, and LAST using a # (for example, $source.#size). Mapping Overview Creating a Mapping Model in Xcode 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 19During migration, Core Data creates two stacks, one for the source store and one for the destination store. Core Data then fetches objects from the source stack and inserts the appropriate corresponding objects into the destination stack. Note that Core Data must re-create objects in the new stack. Overview Recall that stores are bound to their models. Migration is required when the model doesn't match the store. There are two areas where you get default functionality and hooks for customizing the default behavior: ● When detecting version skew and initializing the migration process. ● When performing the migration process. To perform the migration processrequirestwo Core Data stacks—which are automatically created for you—one for the source store, one for the destination store. The migration process is performed in 3 stages, copying objects from one stack to another. Requirements for the Migration Process Migration of a persistent store is performed by an instance of NSMigrationManager. To migrate a store, the migration manager requires several things: ● The managed object model for the destination store. This is the persistent store coordinator’s model. ● A managed object model that it can use to open the existing store. ● Typically, a mapping model that defines a transformation from the source (the store’s) model to the destination model. You don’t need a mapping model if you’re able to use lightweight migration—see “Lightweight Migration” (page 12). 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 20 The Migration ProcessYou can specify custom entity migration policy classes to customize the migration of individual entities. You specify custom migration policy classesin the mapping model (note the “Custom Entity Policy Name” text field in Figure 4-1 (page 19)). Custom Entity Migration Policies If your new model simply adds properties or entities to your existing model, there may be no need to write any custom code. If the transformation is more complex, however, you might need to create a subclass of NSEntityMigrationPolicy to perform the transformation; for example: ● If you have a Person entity that also includes address information that you want to split into a separate Address entity, but you want to ensure uniqueness of each Address. ● If you have an attribute that encodes data in a string format that you want to change to a binary representation. The methods you override in a custom migration policy correspond to the different phases of the migration process—these are called out in the description of the process given in “Three-Stage Migration.” Three-Stage Migration The migration process itself is in three stages. It uses a copy of the source and destination models in which the validation rules are disabled and the class of all entities is changed to NSManagedObject. To perform the migration, Core Data sets up two stacks, one for the source store and one for the destination store. Core Data then processes each entity mapping in the mapping model in turn. It fetches objects of the current entity into the source stack, creates the corresponding objects in the destination stack, then recreates relationships between destination objects in a second stage, before finally applying validation constraints in the final stage. Before a cycle starts, the entity migration policy responsible for the current entity is sent a beginEntityMapping:manager:error: message. You can override this method to perform any initialization the policy requires. The process then proceeds as follows: 1. Create destination instances based on source instances. At the beginning of this phase, the entity migration policy is sent a createDestinationInstancesForSourceInstance:entityMapping:manager:error:message; at the end it is sent a endInstanceCreationForEntityMapping:manager:error: message. In this stage, only attributes (not relationships) are set in the destination objects. The Migration Process Custom Entity Migration Policies 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 21Instances of the source entity are fetched. For each instance, appropriate instances of the destination entity are created (typically there is only one) and their attributes populated (for trivial cases, name = $source.name). A record is kept of the instances per entity mapping since this may be useful in the second stage. 2. Recreate relationships. At the beginning of this phase, the entity migration policy is sent a createRelationshipsForDestinationInstance:entityMapping:manager:error: message; at the end it is sent a endRelationshipCreationForEntityMapping:manager:error: message. For each entity mapping (in order), for each destination instance created in the first step any relationships are recreated. 3. Validate and save. In this phase, the entity migration policy is sent a performCustomValidationForEntityMapping:manager:error: message. Validation rules in the destination model are applied to ensure data integrity and consistency, and then the store is saved. At the end of the cycle, the entity migration policy issent an endEntityMapping:manager:error: message. You can override this method to perform any clean-up the policy needs to do. Note that Core Data cannot simply fetch objects into the source stack and insert them into the destination stack, the objects must be re-created in the new stack. Core Data maintains “association tables” which tell it which object in the destination store isthe migrated version of which object in the source store, and vice-versa. Moreover, because it doesn't have a means to flush the contexts it is working with, you may accumulate many objects in the migration manager as the migration progresses. If this presents a significant memory overhead and hence gives rise to performance problems, you can customize the process as described in “Multiple Passes—Dealing With Large Datasets” (page 29). The Migration Process