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

Apple-URL-Loading-System-Programming-Guide-manuel

Apple-URL-Loading-System-Programming-Guide-manuel

Apple-Document-Based-App-Programming-Guide-for-iOS-Guide-manuel

Apple-Core-Text-Programming-Guide-manuel

Apple-OpenCL-Programming-Guide-for-Mac-manuel

Apple-Event-Driven-XML-Guide-manuel

Apple-Date-and-Time-Guide-manuel

Apple-Windows-Guide-manuel

Apple-AV-Foundation-Programming-Guide-manuel

Apple-Preferences-and-Settings-Programming-Guide-manuel

Apple-OpenGL-Programming-Guide-for-Mac-Guide-manuel

Apple-View-Programming-Guide-for-iOS-Guide-manuel

Apple-Stream-Programming-Guide-manuel

Apple-multimediaprogrammingguide.pdf-Guide-manuel

Apple-External-Accessory-Programming-Topics-Guide-manuel

Apple-Blocks-Programming-Topics-Guide-manuel

Apple-CocoaEncyclopedia.pdf-Guide-manuel

Apple-Mac-App-Programming-Guide-manuel

Apple-Local-and-Push-Notification-Programming-Guide-manuel

Apple-Objective-C-Runtime-Programming-Guide-manuel

Apple-Universal-Binary-Programming-Guidelines-Second-Edition-Guide-manuel

Apple-TableView_iPhone.pdf-Guide-manuel

Apple-Object-Oriented-Programming-with-Objective-C-Guide-manuel

Apple-airportextremebasestationsetupguide.pdf-Guide-manuel

Apple-iPhone_4_Deux_doigts_d_astuces.pdf-Guide-manuel

Apple-iPod_nano_4th_gen_UserGuide.pdf-Guide-manuel

Apple-livetype_2_user_manual.pdf-Guide-manuel

Apple-TV_2nd_gen_Setup_Guide.pdf-manuel

Apple-Archives-and-Serializations-Programming-manuel

Apple-SafariWebContent.pdf-Guide-manuel

Apple-iTunes_ExtrasandiTunes_LPTestGuide1.1.pdf-manuel

Apple-Text-System-User-Interface-Layer-Programming-manuel

Apple-CocoaTextArchitecture.pdf-manuel

Apple-Key-Value-Observing-Programming-Guide-manuel

Apple-Location-Awareness-Programming-Guide-manuel

Apple-SharkUserGuide.pdf-manuel

Apple-drawingprintingios.pdf-manuel

Apple-QuickTime7_User_Guide.pdf-manuel

Apple-Event-Handling-Guide-for-iOS-manuel

Apple-ipod_nano_3rd_gen_features_guide.pdf-manuel

Apple-iTunes_VideoandAudio_Asset_Guide5.0.pdf-manuel

Apple-ARD3_AdminGuide.pdf-manuel

Apple-SafariWebContent.pdf-Guide-manue

Apple-iphone_3gs_finger_tips.pdf-manuel

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-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

Cocoa Bindings Programming TopicsContents Introduction to Cocoa Bindings Programming Topics 7 Who Should Read This Document 7 Organization of This Document 7 See Also 8 What Are Cocoa Bindings? 10 The Advantages of Using Bindings 10 The Model-View-Controller Design Pattern 11 What Is a Binding? 12 A Simple Example 12 Binding Options 14 Extending the MVC Design Pattern 15 Supporting Technologies 16 Key-Value Binding 16 Key-Value Coding 17 Key-Value Observing 18 Why Are NSControllers Useful? 19 NSController Classes 19 What Can You Bind? 20 Real-World Example 20 How Do Bindings Work? 23 Overview of the Supporting Technologies 23 The Supporting Technologies in Detail 25 Establishing Bindings with Key-Value Binding 26 NSEditor/NSEditorRegistration 26 Key-Value Coding 26 Key-Value Observing 27 Unbinding 29 Bindings in More Detail 29 Responding to Changes 32 View-Initiated Updates 32 Model-Initiated Updates 34 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 2Providing Controller Content 37 Setting the Content of a Controller 37 Traversing Tree Content with an NSTreeController 39 Specifying the Class of a Controller’s Content 40 Automatically Prepares Content 40 Programmatically Modifying a Controller’s Contents 41 Modifying Controller Content by Target-Action 42 De-coupling a Controller from its Content Bindings 44 Working With a Controller’s Selection 45 Getting a Controller’s Currently Selected Objects 45 Changing the Current Selection 46 Changing the Selection by Object 46 Getting and Setting Selection by Index 47 Setting the Selection Behaviors 48 Avoids Empty Selection 48 Selecting Objects Upon Insertion 49 Always Uses Multiple Values Marker 49 Preserves Selection 50 Selects All When Setting Content 50 Bindings Message Flow 52 Changing the Value of a Model Property 53 User Updates a Value in the User Interface 56 User Defaults and Bindings 61 What Is NSUserDefaultsController? 61 The Shared User Defaults Controller 61 Binding to the Shared User Defaults Controller 62 initialValues Versus NSUserDefaults registerDefaults: 62 Search Order for Defaults Values 64 Programmatically Accessing NSUserDefaultsController Values 64 Creating a Master-Detail Interface 65 What’s a Master-Detail Interface? 65 Creating Models 66 Creating Views 67 Creating Controllers 68 Binding Controllers to Models 69 Binding Views to Controllers 70 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 3Binding the Master Interface 70 Binding the Detail Interface 71 Displaying Images Using Bindings 73 Creating Models 73 Creating Views 74 Creating Controllers 74 Binding Views to Controllers 74 Using a Value Transformer to Convert Paths 75 Creating Custom Value Transformers 75 Registering Value Transformers 76 Binding Views to Controllers Using Transformers 76 Implementing To-One Relationships Using Pop-Up Menus 78 Creating Models and Controllers 78 Creating Views 79 Binding Views to Controllers 79 Filtering Using a Custom Array Controller 81 Overriding arrangeObjects: 81 Updating the Search String 82 Controller Key-Value Observing Compliance 83 NSUserDefaultsController 83 NSObjectController 83 NSArrayController 84 NSTreeController 84 Troubleshooting Cocoa Bindings 86 My collection controller isn’t displaying the current data 86 Changing the value in the user interface programmatically is not reflected in the model 86 Changing the value of a model property programmatically is not reflected in the user interface 87 Binding to the incorrect key path 87 The bindings of my custom view are disabled in Interface Builder 88 An uneditable/visible/disabled NSTextField becomes editable/hidden/enabled 89 Binding a control to a value that is an unsigned int causes an exception 89 The view bound to an NSTreeController is not displaying data 89 A table column containing NSPopUpButtonCell items is not sortable 89 Document Revision History 90 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 4Figures and Listings What Are Cocoa Bindings? 10 Figure 1 Controllers provide glue code 11 Figure 2 A simple Cocoa application 12 Figure 3 Slider example using target-action 13 Figure 4 Slider demonstration using bindings 13 Figure 5 Displaying temperature using transformers 14 Figure 6 Typical bindings configuration using existing controller 15 Figure 7 Bindings established using key-value binding 16 Figure 8 Using key-value-coding to update values 17 Figure 9 Key-value observing—registering observers 18 Figure 10 Key-value observing—notification of observers 18 Figure 11 User interface for Combatants application 20 Figure 12 Combatant class 21 Figure 13 Combatants application managed by bindings 21 How Do Bindings Work? 23 Figure 1 Example drawing application 24 Figure 2 Bindings for example graphics application 24 Figure 3 The complete edit cycle 25 Figure 4 Key-value coding in Cocoa bindings 27 Figure 5 Key-value observing in Cocoa bindings 28 Figure 6 Bindings for a joystick’s angle in Interface Builder 29 Listing 1 Interface for the Joystick class 30 Listing 2 Partial implementation of the bind:toObject:withKeyPath:options method for the Joystick class 31 Listing 3 Update method for the Joystick class 33 Listing 4 Observing method for the Joystick class 35 Providing Controller Content 37 Figure 1 Master-detail interface with and without contentArrayForMultipleSelection 38 Working With a Controller’s Selection 45 Figure 1 Preserves selection example 50 Figure 2 Selects all when setting content example 51 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 5Bindings Message Flow 52 Figure 1 Message flow when modifying the value of a model object property 53 Figure 2 Message flow in response to the user changing a value in an NSTextField 57 Figure 3 Message flow in response to the user changing a value in an NSTextField, view-controller validation 58 User Defaults and Bindings 61 Listing 1 Binding the userName defaults key to an NSTextField programmatically 62 Listing 2 Changing the initial values of the sharedUserDefaultsController instance 63 Creating a Master-Detail Interface 65 Figure 1 A master-detail interface 66 Figure 2 An object model 67 Figure 3 An array controller Attributes pane 68 Figure 4 An array controller Bindings pane 69 Figure 5 NSTableColumn Bindings pane 71 Displaying Images Using Bindings 73 Figure 1 Using an NSImageCell in an NSTableColumn 73 Figure 2 Bindings pane of an NSTableColumn 77 Listing 1 PathTransformer implementation file 75 Implementing To-One Relationships Using Pop-Up Menus 78 Figure 1 Using pop-up menus to represent to-one relationships 78 Filtering Using a Custom Array Controller 81 Listing 1 Filtering implementation of arrangeObjects: 81 Listing 2 Updating searchString 82 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 6Cocoa bindings is a collection of technologies you can use in your applications to fully implement a Model-View-Controller paradigm where models encapsulate application data, views display and edit that data, and controllers mediate between the two. Cocoa bindings reduces the code dependencies between models, views and controllers, supports multiple ways of viewing your data, and automatically synchronizes views when models change. Cocoa bindings provides extensible controllers, protocolsfor models and viewsto adopt, and additions to classes in Foundation and the Application Kit. You can eliminate most of your glue code by using bindings available in Interface Builder to connect controllers with models and views. Who Should Read This Document Cocoa bindings is ideal for developers writing new applications who have some familiarity with Cocoa, and for developers of existing applications who want to simply clean up or eliminate their existing glue code. In most cases, Cocoa bindings can be used to replace traditional Cocoa mechanisms such as target-action, delegation, and some data source protocols. However, great care has been taken to ensure that both approaches can be used side by side within the same application. This document assumes that you have read Key-Value Coding Programming Guide , Key-Value Observing Programming Guide and Value Transformer Programming Guide . Important: Cocoa bindings is available to Cocoa Objective-C applications running OS X version 10.3 and later. Organization of This Document The following articles cover key concepts in understanding how Cocoa bindings works: ● "What Are Cocoa Bindings?" (page 10) describes the advantages that Cocoa bindings offers developers; provides a brief summary of how they work; and what design patterns you should use to adopt the technology. ● "How Do Bindings Work?" (page 23) describes in detail the technologies supporting Cocoa bindings and how they interact. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 7 Introduction to Cocoa Bindings Programming Topics● "User Defaults and Bindings" (page 61) describes the role of the NSUserDefaultsController and how it works with NSUserDefaults. ● "Providing Controller Content" (page 37) describes how to set and modify the content of NSObjectController and its subclasses. ● "Working With a Controller’s Selection" (page 45) describes how to get a controller’s selection and change the current selection. ● "Bindings Message Flow" (page 52) illustrates the flow of messages between model, view and controller objects in a bindings application. These articles contain tasks that teach you how to use Cocoa bindings: ● "Creating a Master-Detail Interface" (page 65) explains how to implement a basic master-detail interface where a table view is used in the master interface to display a collection of objects, and other views used in the detail interface to display the selected object in the collection. ● "Displaying Images Using Bindings" (page 73) describes the various options when displaying images in columns and contains an example of a custom value transformer. ● "Implementing To-One Relationships Using Pop-Up Menus" (page 78) explains how to implement editable to-one relationship as pop-up menus. ● "Filtering Using a Custom Array Controller" (page 81) explains how to add a search field to the master interface to filter the objects it displays. ● "Controller Key-Value Observing Compliance" (page 83) details the properties for which the controller classes provide key-value observing change notifications. ● "Troubleshooting Cocoa Bindings" (page 86) describes a number of common problems encountered with Cocoa bindings applications and provides methods for correcting the issues. See Also There are other technologies, not fully covered in this topic, that are fundamental to how bindings work. You may want to read these topics if you want a better understanding of the underpinnings of Cocoa bindings, or if you want to use these technologies independent from bindings. For example, this topic does not explain how to use the methods defined in the key-value observing protocol. Refer to these documents for more details: ● Developing Cocoa Applications Using Bindings: A Tutorial takes you through the steps of building the familiar Currency Converter application using Cocoa bindings. Introduction to Cocoa Bindings Programming Topics See Also 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 8● Cocoa Bindings Reference enumerates the classes that support Cocoa bindings and provides descriptions of the bindings for each class, along with the supported options and placeholders. ● Key-Value Coding Programming Guide covers all the features of the key-value coding protocol that allows objects to indirectly access the properties of other objects. ● Key-Value Observing Programming Guide covers all the features of the key-value observing protocol that allows objects to observe changes in other objects. ● Value Transformer Programming Guide describes how to use value transformers to convert values from one type to another. ● Sort Descriptor Programming Topics describes how to use sort descriptors that specify how collections are sorted. Introduction to Cocoa Bindings Programming Topics See Also 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 9In the simplest functional sense, the Cocoa bindings technology provides a means of keeping model and view values synchronized without you having to write a lot of “glue code.” It allows you to establish a mediated connection between a view and a piece of data, “binding” them such that a change in one is reflected in the other. This article describes what the technology offers and how it makes writing applications easier. It also introduces the idea that rather than completely reimplementing an existing application to make use of bindings, you can incorporate bindings in stages. This article also describes on a conceptual level how Cocoa bindings work, and the design patterns you should adopt. It gives a brief overview of the Model-View-Controller design pattern, and why it is beneficial. It then gives a conceptual overview of how the main technologies that underpin Cocoa bindings—key-value coding, key-value observing, and key-value binding—work, and how they inter-relate. The article finally explains the role of the controller classes that Cocoa bindings provide and why you should use them. "How Do Bindings Work?" (page 23) describes the supporting technologies in greater detail. The Advantages of Using Bindings The Cocoa bindings technology offers a way to increase the functionality and consistency of your application while at the same time decreasing the amount of code you have to write and maintain. It takes care of most aspects of user interface management for you by allowing you to off load the work of custom glue code onto reusable pre-built controllers. It helps you build polished, easy-to-use applications that leverage object relationships, provide sortable tables, and include intelligent selection management. Typically you do not need to completely rewrite your application in order to adopt Cocoa bindings. For example, it is likely that you can factor out User Preferences to be managed by Cocoa bindings without affecting the rest of an application. You will find it easier to make use of Cocoa bindings if your application adopts the recommended design patterns. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 10 What Are Cocoa Bindings?The Model-View-Controller Design Pattern Cocoa applications generally adopt the Model-View-Controller (MVC) design pattern. When you develop a Cocoa application, you typically use model, view, and controller objects, each of which performs a different function. Model objects represent data and are typically saved to a file or some other permanent data store. View objects display model attributes. Controller objects act as go-betweens, to make sure that what a view displays is consistent with the corresponding model value and that any updates a user makes to a value in a view are propagated to the model. An understanding of the MVC design pattern is essential to fully understand and leverage Cocoa bindings. If you need to know more, read “The Model-View-Controller Design Pattern.” If you adopt the MVC design pattern, much of your application code is easier to reuse and extend—you can reuse model and view classes in different applications. Much of the implementation of a controller object consists of what is commonly referred to as “glue code.” Glue code is the code that keeps the model values and views synchronized, and is unique to each application. It is typically tedious and cumbersome to write, contributes little to the fundamental function of the application, but you must do it well to provide a good user experience. Figure 1 Controllers provide glue code firstName = "Jo" lastName = "Jackson" Employee glue Document Window First Jo Last Jackson Cocoa bindings replace much of the glue code with reusable controllers and provide an infrastructure that allows you to connect the user interface with an application’s data. Cocoa uses a number of terms that are commonly used in computer science. To avoid misunderstanding, they are defined in the “Terminology”section of Key-Value Coding ProgrammingGuide with their particularmeaning in the context of Cocoa bindings. What Are Cocoa Bindings? The Model-View-Controller Design Pattern 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 11What Is a Binding? A binding is an attribute of one object that may be bound to a property in anothersuch that a change in either one isreflected in the other. For example, the “value” binding of a text field might be bound to the temperature attribute of a particular model object. More typically, one binding might specify that a controller object “presents” a model object and another binding might specify that the value of a text field be tied to the temperature property of the object presented by the controller. Although the following examples concentrate on simple cases, bindings are not restricted to the display of textual or numeric values. Among other things, a binding might specify the color in which text should be displayed, whether a view is hidden or not, or what message and arguments should be sent when a button is pressed. A Simple Example Take as an example a very simple application in which the valuesin a text field and a slider are keptsynchronized. Consider first an implementation that does not use bindings. The text field and slider are connected directly to each other using target-action, where each is the other’s target and the action is takeFloatValueFrom: as shown in Figure 2. (If you do not understand this, you should read Getting Started With Cocoa.) Figure 2 A simple Cocoa application Window Number 6.2 takeFloatValueFrom: This example illustrates the dynamism of the Cocoa environment—the values of two user interface objects are kept synchronized without writing any code, even without compiling. It also serves to illustrate the target-action design pattern (for more details, read “The Target-Action Paradigm”). What Are Cocoa Bindings? What Is a Binding? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 12The major flaw from which this example suffers is that, as it is, it has almost no real-world application. In order to find out the value to which either the slider or the text field has been set, and update a model attribute accordingly, you need connections to the text field and slider, and have to write some code. You typically use a controller that is connected to both (using outlets) and to which both are connected (using target-action), as illustrated in Figure 3 (page 13). Figure 3 Slider example using target-action Window Number 6.2 slider = slider textfield = textfield number = number Controller number = "6.2" MyObject updateNumberFrom: Instance variable setFloatValue: When a user moves the slider, it sends an action message to its target (the controller). The controller in turn updates the value in the model, and synchronizes the user interface (the text field and the slider). Although this example is not particularly difficult, the situation becomes more complex if you use more complicated models and displays, especially if you use, for example, table views that allow multiple selections, or if a value may be displayed in a different window. And you have to write all the code to support this functionality. Cocoa bindings uses prebuilt controller objects (subclasses of NSController) and supporting technologies to keep values synchronized automatically. The application design for an implementation of the slider example that uses bindings is shown in Figure 4. Figure 4 Slider demonstration using bindings Bind content to object Window Number 6.2 number = "6.2" MyObject content = object NSObjectController Bind value to object's number What Are Cocoa Bindings? What Is a Binding? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 13Note that this implementation does not use the target-action pattern. The slider does not send an action message to the controller. Instead, as the slider moves, it informs the controller directly that the value of its content’s number has changed and what the value is. The controller updates the model and in turn informs the text field and slider that the value they are displaying has changed. (In examples assimple asthis controllers are not really necessary, however in most cases they are.) The mechanisms used to relay information are explained later in this article and in greater detail in "How Do Bindings Work?" (page 23), but it is important to appreciate that in most cases you will not have to write any glue code. Binding Options Many bindings allow you to specify options to customize their behavior. There are three types of option: value transformers, placeholders, and other parameters. A value transformer, as its name implies, applies a transformation to a value. A value transformer may also allow reverse transformations. The Foundation framework provides the abstract NSValueTransformer class and several convenient transformers, including one that negates a value—that is, it turns a Boolean YES into NO (and vice versa). You can also implement your own transformers. To see how transformers might be useful, suppose that in the previous example the number in the model represents temperature in degrees Fahrenheit, but that you want to display the value in Celsius. You could implement a reversible value transformer that converts values from one scale to the other. If you then specify it as the transformer option for the text field and slider, as shown in Figure 5 (page 14), the user interface displays the temperature in Celsius, and any new values entered using the slider or text field converted to Fahrenheit. Figure 5 Displaying temperature using transformers WWiinnddooww Bind content to object temperature = 77.0 MyObject content = object NSObjectController Celsius 25.0 Bind value to object's temperature using Fahrenheit to Celsius transformer To learn more about transformers read Value Transformer Programming Guide (the article also shows an implementation of the Fahrenheit to Celsius transformer). What Are Cocoa Bindings? What Is a Binding? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 14Placeholder options allow you to specify what a view should display: if the value of the property to which it is bound is null (nil); if there is no selection; if there is a multiple selection; or if for some other reason the value is not applicable. In addition to value transformers and placeholders, some bindings offer a variety of other options, such as whether the value of the binding is updated as edits are made to the user interface item, or whether the editable state of a user interface item is automatically configured based on the controller’s selection. For a complete list of all the binding options available, see Cocoa Bindings Reference . Extending the MVC Design Pattern The Cocoa bindings architecture extends the traditional Cocoa MVC configuration, where there is a single custom-built controller that manages the user interface. It provides a set of reusable controller classes that inherit from an abstract superclass, NSController. In a bindings-based application there may be several controllers—your own (such as an NSWindowController subclass, managing a document’s user interface) and others that are subclasses of NSController and manage different parts of the user interface. You might also create your own subclasses of the standard Application Kit controller classes—in particular you might subclass NSArrayController to customize sorting and filtering behavior. Other figures in this document present a convenient shorthand. Although the NSController instance is conceptually bound directly to its model object, in most situations the binding will be “indirect,” to a variable in your document object, as shown in Figure 6. Figure 6 Typical bindings configuration using existing controller WWiinnddooww Celsius 25.0 Instance variable temperature = "6.2" MyObject object = myObject MyDocument content = object NSObjectController Bind value to selection's temperature Bind content to controller.object What Are Cocoa Bindings? What Is a Binding? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 15Supporting Technologies Cocoa bindings rely primarily on two other technologies, key-value coding (KVC) and key-value observing (KVO). Bindings themselves are established using key-value binding (KVB) as illustrated in Figure 7. In practice you typically need to understand these technologies only if you want to create your own custom view with bindings. If you want to use bindings, the only requirement that is imposed on you is that your model classes must be compliant with key-value coding conventions for any properties to which you want to bind. Key-Value Binding A binding is established with a bind:toObject:withKeyPath:options: message which tells the receiver to keep its specified attribute synchronized—modulo the options—with the value of the property identified by the key path of the specified object. The receiver must watch for relevant changes in the object to which it is bound and react to those changes. The receiver must also inform the object of changes to the bound attribute. After a binding is established there are therefore two aspects to keeping the model and views synchronized: responding to user interaction with views, and responding to changes in model values. Figure 7 Bindings established using key-value binding Establish binding using Key-Value Binding temperature = 77.0 MyObject content = object NSObjectController WWiinnddooww Celsius 25.0 Establish binding using Key-Value Binding In a view-initiated update a value changed in the user interface is passed to the controller, which in turn pushes the new value onto the model. To preserve the abstraction required to allow this to work with any controller or model object, the system uses a common access protocol—key-value coding. In a model-initiated update models notify controllers, and controllers notify views, of changes to values in which interest has been registered using a common protocol—key-value observing. Note that a model-initiated update can be triggered by direct manipulation of the model—for example by a Scripted Apple event—or as the result of a view-initiated update—a change to the temperature made by editing the Celsius field must be propagated back to the slider. What Are Cocoa Bindings? Supporting Technologies 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 16Key-Value Coding Key-value coding is a mechanism whereby you can access a property in an object using the property’s name as a string—the “key.” You can also use key paths to follow relationships between objects. For example, given an Employee class with an attribute firstName, you could retrieve an employee’s first name using key-value coding with the key firstName. If Employee has a relationship called “manager” to another Employee, you could retrieve an employee’s manager’s first name using key-value coding with the key path manager.firstName. For more details, see Key-Value Coding Programming Guide . Recall that a binding specifies the key path to a property to which a given attribute is bound. If the value in the slider or the text field is changed, it uses key-value coding—using the key path specified by the binding as the key—to communicate that change directly to the controller, as illustrated in Figure 8. Note that the arrows in this figure represent the direction in which messages are sent and in which information flows. The new value is passed from the user interface widget to the controller, and from the controller to the model. Figure 8 Using key-value-coding to update values temperature = 77.0 MyObject content = object NSObjectController WWiinnddooww Celsius 25.0 Update temperature using Key-Value Coding Update values using Key-Value Coding What Are Cocoa Bindings? Supporting Technologies 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 17Key-Value Observing Key-value observing is a mechanism whereby an object can register with another to be notified of changes to the value of a property. When one object is bound to another object, it registers itself as an observer of the relevant property of that object. In the current example, the text field and slider register as observers of the temperature property of the controller’s content, as illustrated in Figure 9. Figure 9 Key-value observing—registering observers temperature = 77.0 MyObject content = object NSObjectController WWiinnddooww Celsius 25.0 Register as an observer of the temperature property Register as an observer of the object Note that the arrows shown in Figure 9 indicate direction of observation, not of data flow. Observation is a “passive” process (akin to registering to receive notifications from an NSNotificationCenter). When a value changes, the observed object sends a message to interested observers to notify them, as illustrated in Figure 10. The arrows in Figure 10 show the direction in which messages are sent. Figure 10 Key-value observing—notification of observers WWiinnddooww temperature = 77.0 MyObject content = object NSObjectController Celsius 25.0 Notify that temperature has changed Notify that temperature has changed What Are Cocoa Bindings? Supporting Technologies 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 18Why Are NSControllers Useful? Bindings can, in principle, be made between almost any two objects, provided that they are KVC-compliant and KVO-compliant. A view could bind directly to a model object. Bindings-based applications, however, use controller objects to manage individual model objects and collections of model objects and to interface to the user preferences system. It is possible to make bindings directly to your model objects or to controllers that do not inherit from NSController—however you lose (or must reimplement) functionality provided by the Application Kit’s controller objects. ● NSController instances manage their currentselection and placeholder values. This allows a view to display an appropriate value if the controller’s selection is null, or if there is a multiple selection. ● NSController (and Application Kit user interface elements that support binding) implements the NSEditor and NSEditorRegistration protocols. The NSEditorRegistration protocol provides a means for an editor (a view) to inform a controller when it has uncommitted changes. The NSEditor protocol provides a means for requesting that the receiver commit or discard any pending edits. For example, if a user istyping in a text field and then clicks a button, the controller ensuresthat the model object is updated with the complete contents of the text field before the button action takes place. Although the methods are typically invoked on user interface elements by a controller they can also be sent to a controller, for example in response to a user’s attempt to save a document or quit an application. NSController Classes NSController is an abstract class. Its concrete subclasses are NSObjectController, NSUserDefaultsController, NSArrayController, and NSTreeController. NSObjectController manages a single object and provides the functionality discussed so far. NSUserDefaultsController provides a convenient interface to the preferences system. NSArrayController and NSTreeController manage collections of model objects and track the current selection. The collection controllers also allow you to add objects to, and remove objects from, the content collection. The objects that the collection controllers manage don’t even have to be in an array—your container can implement suitable methods (“indexed accessor” methods, defined in the NSKeyValueCoding protocol) to present the values to the controller as if they were in an array. What Are Cocoa Bindings? Why Are NSControllers Useful? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 19What Can You Bind? You can make bindings for most of the Application Kit view classes, such as NSButton and NSTableView. Using an array controller, for example, you can bind the contents of a pop-up menu to objects in an array. The remainder of this article presents an example that is moderately complex. Although the details are intentionally left vague it nevertheless serves to illustrate a number of points, and provides examples of more complex bindings. Real-World Example Consider a game application in which the user manages a number of combatants, from which they can select one as an attacker. A combatant can carry three weapons, one of which isselected at any time. In the application, the list of combatants is shown in a table view, the window’s title shows the attacker’s name, and a pop-up menu shows the currently selected weapon, as shown in Figure 11 (page 20). Figure 11 User interface for Combatants application Vlad Selected Weapon Dagger Sword Pike Atilla Attacker Vlad Doris What Are Cocoa Bindings? What Can You Bind? 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 20Combatants are represented by instances of the Combatant class. In the Combatant class, each weapon is referenced as a separate instance variable, as shown in Figure 12. By implementing suitable “indexed” accessor methods(defined by the key-value coding protocol), however, the Combatant class can allow an array controller to access the weapons as if they were in an array. Figure 12 Combatant class weapon1 = dagger weapon2 = sword weapon3 = pike selectedWeapon = weapon2 name = "Vlad" Combatant When the user chooses an attacker from the table view, the window title is updated to reflect the attacker’s name, and the title of the pop-up menu is updated to reflect the attacker’s selected weapon. When the user activates the pop-up its contents are created dynamically from the set of weapons carried by the combatant. When the user selects a menu item, the combatant’s selected weapon is set to that corresponding to that menu item. If a different attacker is selected, the pop-up, selection and window title update accordingly. Figure 13 (page 21) illustrates how the user interface of the Combatants application can be implemented using bindings. The table view is bound to an array controller that manages an array of combatants. The window title is bound to the name of the selected combatant. The pop-up menu retrieves its list of items from an array controller bound to the attacker’s weapons“array,” and itsselection is bound to the attacker’sselected weapon. Figure 13 Combatants application managed by bindings contentArray = combatants NSArrayController contentArray = selection.weapons NSArrayController Vlad Selected Weapon Dagger Sword Pike Atilla Attacker Vlad Doris weapon1 = dagger weapon2 = sword weapon3 = pike selectedWeapon = weapon2 name = "Vlad" Combatant selection Bind title to selection.name Bind value to arrangedObjects.name Bind contentArray to selection.weapons Bind content to arrangedObjects Bind selectedObject to selection.selectedWeapon What Are Cocoa Bindings? Real-World Example 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 21This example illustrates a number of points: ● In an application you can use more than one controller object. ● Different aspects of a user interface element may be bound to different controllers. ● You can use your own custom model classes. Finally, it should be emphasized that the example requires no actual code to set up the user interface—the controllers and bindings can all be created in Interface Builder. This represents a considerable reduction in programming effort compared with the traditional target-action based approach. What Are Cocoa Bindings? Real-World Example 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 22This article provides a conceptual explanation of how Cocoa bindings work. It describes: ● How connections between model and controller, and controller and view, are established using key-value binding ● Unbinding ● The NSEditor and NSEditorRegistration protocols ● The technologies that Cocoa bindings use to support communication between the model, view, and controller, namely key-value coding, and key-value observing ● How the various technologies interact You should already be familiar with the concepts presented in "What Are Cocoa Bindings?" (page 10). Overview of the Supporting Technologies This section presents an overview of the technologies that make Cocoa bindings work and how they interact. They are discussed in greater detail in the following sections. Cocoa bindings rely on other technologies—key-value coding (KVC) and key-value observing (KVO)—to communicate changes between objects, and on key-value binding (KVB) to bind a value in one object to a property in another. Cocoa bindings also use two protocols—NSEditor and NSEditorRegistration—that help to ensure that any pending edits are either discarded or committed before user interface elements are disposed of. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 23 How Do Bindings Work?To understand how these technologies work together, consider a drawing application that allows the user to draw graphic objects such as circles and rectangles on screen. Among other properties, a graphic object has a shadow that may be offset a variable distance from the center of the graphic at an arbitrary angle. An inspector displays the offset and angle of the selected graphic object’s shadow in a pair of text fields and a custom view—a joystick—as shown in Figure 1. Figure 1 Example drawing application Shadow Offset: 15.0 Angle: 28.00 + Document Joystick The implementation of the inspector is illustrated in Figure 2. Both the text fields and the joystick are bound to the selection of an NSArrayController. The controller’s contentArray is bound to an array of Graphic objects. A Graphic hasinstance variablesto represent itsshadow’s angle in radians and its offset from its center. Figure 2 Bindings for example graphics application shadowOffset = 15.00 shadowAngle = 0.86 Graphic selection = graphic NSArrayController Shadow Offset: 15.0 Angle: 28.00 value bound to selection.shadowOffset value bound to selection.shadowAngle using radians to degrees value transformer selection + offset bound to selection.shadowOffset angle bound to selection.shadowAngle using radians to degrees value transformer How Do Bindings Work? Overview of the Supporting Technologies 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 24The text fields’ values are bound to the angle and offset of the graphic object’s shadow; the joystick provides a graphical representation of angle and offset. The angle in the text field is displayed in degrees, and the angle used internally by the joystick is specified in radians. The bindings for both of these specify a reversible value transformer that converts between radians and degrees. The complete sequence of events that occurs when a user edits a value in the angle text field is illustrated in Figure 3 (page 25). Figure 3 The complete edit cycle shadowOffset = 15.00 shadowAngle = 0.86 Graphic selection = graphic NSArrayController Shadow Offset: 15.0 Angle: 28.00 + + KVC + degrees to radians transformation KVC KVO 2 3 1 4 + KVO + degrees to radians transformation 1. The user enters a new value in the Angle text field. The text field uses the NSEditorRegistration protocol to indicate that an edit has begun, and when it is complete. The text field’s binding specifies a reversible radians-to-degrees value transformer, so the new value is converted to radians. 2. Using KVC, through the controller the view updates the model object’s shadowAngle variable. 3. Through KVO, the model informsthe controller that an update has been made to its shadowAngle variable. 4. Through KVO, the controller informs the joystick and the angle text field that an update has been made to its content’s shadowAngle variable. Notice that the Offset text field was not involved in the cycle in any way. Cocoa bindings impose no more overhead than is necessary. The next sections explain in greater detail how bindings are established and how the underlying technologies operate. The Supporting Technologies in Detail This section first describes the technologies that support bindings and shows how they play their parts. It also explains what steps you must take in order to take advantage of these technologies. How Do Bindings Work? The Supporting Technologies in Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 25Establishing Bindings with Key-Value Binding Key-value binding is used to establish bindings. The NSKeyValueBindingCreation informal protocol declares methods to establish and remove bindings between objects. In addition, it provides a means for a class to advertise the bindings that it exposes. In most cases you need to use bind:toObject:withKeyPath:options:, and then only when you establish bindings programatically. Use of the unbind: is discussed in “Unbinding.” The other methods—the class method exposeBinding: and the instancemethods exposedBindings and valueClassForBinding:—are useful only in an Interface Builder palette. NSEditor/NSEditorRegistration Together the NSEditorRegistration and NSEditor protocols allow views to notify a controller that an edit is underway and to ensure that any pending edits are committed as and when necessary. The NSEditorRegistration informal protocol isimplemented by controllersto provide an interface for a view—the editor—to inform the controller when it has uncommitted changes. When an edit is initiated, the view sends the controller an objectDidBeginEditing: message. When the edit is complete (for example when the user presses Return) the view sends an objectDidEndEditing: message. The controller is responsible for tracking which editors have uncommitted changes and requesting that they commit or discard any pending edits when appropriate—for example, if the user closes the window or quits the application. The request takes the form of a commitEditing or discardEditing message, defined by the NSEditor informal protocol. NSController provides an implementation of this protocol, as do the Application Kit user interface elements that support binding. Key-Value Coding Key-value coding (KVC) provides a unified way to access an object’s properties by name (key) without requiring use of custom accessor methods. The NSKeyValueCoding protocol specifies among others two methods, valueForKey: and setValue:forKey:, that give access to an object’s property with a specified name. In addition, the methods setValue:forKeyPath: and valueForKeyPath: give access to properties across relationships using key paths of the form relationship.property , for example, content.lastName. How Do Bindings Work? The Supporting Technologies in Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 26A binding for a given property specifies an object and a key path to a property of that object. Given this information, the bound object can use key-value coding—specifically setValue:forKeyPath:—to update the object to which it is bound without having to hard-code an accessor method, as illustrated in Figure 4. Figure 4 Key-value coding in Cocoa bindings shadowOffset = 15.00 shadowAngle = 0.86 Graphic selection = graphic NSArrayController Shadow Offset: 15.0 Angle: 28.00 + + setValue: forKeyPath: setValue: forKeyPath: Update to value in controller passed to model using KVC Update to value in view passed to controller using KVC + + Since Cocoa bindings rely on KVC, your model and controller objects must be KVC-compliant for other objects to be able to bind to them. To support KVC you simply have to follow a set of conventions for naming your accessor methods, briefly summarized here: ● For an attribute or to-one relationship named , implement methods named and, if the attribute is read-write, set:—the case is important. ● For a to-many relationship implement either a method named or both countOf and objectInAtIndex:. The latter pair is useful if the related objects are not stored in an array. It is up to you to retrieve an appropriate value for the specified index—it does not matter how the value is derived. For a mutable to-many relationship, you should also implement either set (if you implemented ) or insertObject:inAtIndex: and removeObjectFromAtIndex:. For full details of all the methods declared by the NSKeyValueCoding protocol, see Key-Value Coding Programming Guide . Key-Value Observing KVO is a mechanism that allows an object to register to receive notifications of changes to values in other objects. To register, an observer sends the object it wants to observe an addObserver:forKeyPath:options:context: message that specifies: ● The object that is observing (very often self) ● The key path to observe (for example, selection.name) How Do Bindings Work? The Supporting Technologies in Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 27● What information will be sent on notification (for example, old value and new value) ● Optionally, contextual information to be sent back on notification (for example, a flag to indicate what binding is being affected) An observed object communicates changes directly to observers by sending them an observeValueForKeyPath:ofObject:change:context: message (defined by the NSKeyValueObserving informal protocol)—there is no independent notifier object akin to NSNotificationCenter. Figure 5 illustrates how a change to a model value (the shadow angle) is communicated to views using KVO. Figure 5 Key-value observing in Cocoa bindings shadowOffset = 15.00 shadowAngle = 0.49 Graphic selection = graphic NSArrayController Shadow Offset: 15.0 Angle: 28.00 + + observeValueForKeyPath: ofObject:change:context Update to value in model passed to controller using KVO + observeValueForKeyPath: ofObject:change:context Update to value in controller passed to views using KVO The message is sent to observers for every change to an observed property, independently of how the change wastriggered. (Note that the protocol itself makes no assumptions about what the observer actually does with the information.) One other important aspect of KVO is that you can register the value of a key as being dependent on the value of one or more others. A change in the value associated with one of the “master” keys triggers a change notification for the dependent key’s value. For example, the drawing bounds of a graphic object may be dependent on the offset and angle of the associated shadow. If either of those values changes, any objects observing the drawing bounds must be notified. The main requirement to make use of KVO is that your model objects be KVO-compliant. In most cases this actually requires no effort—the runtime system adds support automatically. By default, all invocations of KVC methods result in observer notifications. You can also implement manual support—see Key-Value Observing Programming Guide for more details. How Do Bindings Work? The Supporting Technologies in Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 28Unbinding Typically the only reason you would explicitly unbind an object isif you modify the user interface programatically and want to remove a binding. If you change an objects binding’s values it should first clear any preexisting values. If you implement a custom view or controller with custom bindings, you should ensure that it clears any bindings before it is deallocated—in particular itshould release any objectsthat were retained for the specified binding in the bind:toObject:withKeyPath:options: method and should deregister as an observer of any objects for which it registered as an observer. It may be convenient to implement this logic in an unbind: method that you then call as the first step in dealloc. Bindings in More Detail This section examines bindings in more detail. It decomposes—from the perspective of a custom view, a joystick—what happens when a binding is established. This serves two purposes: it makes explicit what code is involved in establishing a binding and responding to changes, and it gives a conceptual overview of how to create your own bindings-enabled views. A binding specifies what aspect of one objectshould be bound to what property in another,such that a change in either is reflected in the other. For a given binding, an object therefore records the target object for the binding, the associated key path, and any options that were specified. You can establish bindings easily in Interface Builder using the Bindings pane of the Info window. In Interface Builder, the angle binding for a joystick that displays the offset and angle of graphics object’s shadow might look like Figure 6. Figure 6 Bindings for a joystick’s angle in Interface Builder Binding name Object Key path Options How Do Bindings Work? Bindings in More Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 29Establishing this binding in Interface Builder is equivalent to programatically sending this message to the joystick: [joystick bind:@"angle" toObject:GraphicController withKeyPath:@"selection.shadowAngle" options:options]; The arguments have the following meanings: @"angle" Identifies an attribute whose value can be bound to the value of a property in another object. Note that the binding name need not necessarily correspond to the name of an actual instance variable. GraphicController The object containing the bound-to property. @"selection.shadowAngle" The key path that identifies the bound-to property. options A dictionary that specifies any options such as placeholders, or in this case, a value transformer. The information defined by the arguments can be stored in the bound object (in this case the joystick) as instance variables, as discussed next. This example, and those that follow, assume that the joystick is represented by the class Joystick with instance variables as defined in the interface shown in Listing 1. Listing 1 Interface for the Joystick class @interface Joystick : NSView { float angle; id observedObjectForAngle; NSString *observedKeyPathForAngle; NSValueTransformer *angleValueTransformer; // ... } In its bind:toObject:withKeyPath:options: method an object must as a minimum do the following: ● Determine which binding is being set How Do Bindings Work? Bindings in More Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 30● Record what object it is being bound to using what keypath and with what options ● Register as an observer of the keypath of the object to which it is bound so that it receives notification of changes The code sample in Listing 2 shows a partial implementation of Joystick’s bind:toObject:withKeyPath:options: method dealing with just the angle binding. Listing 2 Partial implementation of the bind:toObject:withKeyPath:options method for the Joystick class static void *AngleBindingContext = (void *)@"JoystickAngle"; - (void)bind:(NSString *)binding toObject:(id)observableObject withKeyPath:(NSString *)keyPath options:(NSDictionary *)options { // Observe the observableObject for changes -- note, pass binding identifier // as the context, so you get that back in observeValueForKeyPath:... // This way you can easily determine what needs to be updated. if ([binding isEqualToString:@"angle"]) { [observableObject addObserver:self forKeyPath:keyPath options:0 context:AngleBindingContext]; // Register what object and what keypath are // associated with this binding observedObjectForAngle = [observableObject retain]; observedKeyPathForAngle = [keyPath copy]; // Record the value transformer, if there is one angleValueTransformer = nil; NSString *vtName = [options objectForKey:@"NSValueTransformerName"]; if (vtName != nil) How Do Bindings Work? Bindings in More Detail 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 31{ angleValueTransformer = [NSValueTransformer valueTransformerForName:vtName]; } } // Implementation continues... This partial implementation does not record binding options other than a value transformer (although it may simply be that the binding does not allow for them). It neverthelessillustratesthe basic principles of establishing a binding. Notice in particular the contextual information passed in the addObserver:forKeyPath:options:context: message; this is returned in the observeValueForKeyPath:ofObject:change:context: method and can be used to determine which binding is affected by the value update. Responding to Changes As noted earlier, there are two aspects to change management—responding to view-initiated changes that must be propagated ultimately to the model, and responding to model-initiated changesthat must be reflected in the view. This section illustrates both, and shows how KVC and KVO play their parts. View-Initiated Updates Recall that the joystick was bound to the controller with the following method: [joystick bind:@"angle" toObject:GraphicController withKeyPath:@"selection.shadowAngle" options:options]; From the perspective of view-initiated updates the method can be interpreted as follows: bind: @"angle" If whatever is associated with angle changes, toObject: GraphicController tell the specified object (GraphicController) that withKeyPath: @"selection.shadowAngle" the value of its (the GraphicController’s) selection.shadowAngle has changed How Do Bindings Work? Responding to Changes 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 32options: options using any of these options that may be appropriate. If the value associated with angle changes—typically when a user clicks or drags the mouse within the view—the joystick should pass the new value to the controller using KVC, as illustrated in Figure 4. The joystick should therefore respond to user input as follows: ● Determine new values for angle and offset ● Update its own display as appropriate ● Communicate new values to the controller to which it is bound Listing 3 shows a partial implementation of an update method for the Joystick class. The excerpt deals just with the angle binding. It illustrates the use of key-value coding to communicate the new value (transformed by the value transformer if appropriate) to the observed object. Listing 3 Update method for the Joystick class -(void)updateForMouseEvent:(NSEvent *)event { float newAngleDegrees; // calculate newAngleDegrees... [self setAngle:newAngleDegrees]; if (observedObjectForAngle != nil) { NSNumber *newControllerAngle = nil; if (angleValueTransformer != nil) { newControllerAngle = [angleValueTransformer reverseTransformedValue: [NSNumber numberWithFloat:newAngleDegrees]]; } else { newControllerAngle = [NSNumber numberWithFloat:newAngleDegrees]; How Do Bindings Work? Responding to Changes 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 33} [observedObjectForAngle setValue: newControllerAngle forKeyPath: observedKeyPathForAngle]; } // ... } Note that this example omits several important details, such as editor registration and checking that the value transformer allows reverse transformations. Model-Initiated Updates Recall again that the joystick was bound to the controller with the following method: [joystick bind:@"angle" toObject:GraphicController withKeyPath:@"selection.shadowAngle" options:options]; From the perspective of model-initiated updates the method can be interpreted as follows: toObject: GraphicController If the GraphicController’s withKeyPath:@"selection.shadowAngle" selection.shadowAngle changes bind:@"angle" update whatever is associated with the exposed angle key options:options using the options specified (for example, using a value transformer). The receiver therefore registered as an observer of the specified object’s key path (selection.shadowAngle) in its bind:toObject:withKeyPath:options: method, as wasshown in Listing 2. Observed objects notify their observers by sending them an observeValueForKeyPath:ofObject:change:context: message. Listing 4 shows a partial implementation for the Joystick class for handling the observer notifications that result. The fundamental requirement of the observeValueForKeyPath:ofObject:change:context: method is that the value associated with the relevant attribute is updated. This excerpt also shows how it can capture placeholder information that might be used in the display method to give visual feedback to the user, in this case using an instance variable that indicates that for some reason the angle is “bad.” How Do Bindings Work? Responding to Changes 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 34Listing 4 Observing method for the Joystick class - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context { // You passed the binding identifier as the context when registering // as an observer--use that to decide what to update... if (context == AngleObservationContext) { id newAngle = [observedObjectForAngle valueForKeyPath:observedKeyPathForAngle]; if ((newAngle == NSNoSelectionMarker) || (newAngle == NSNotApplicableMarker) || (newAngle == NSMultipleValuesMarker)) { badSelectionForAngle = YES; } else { badSelectionForAngle = NO; if (angleValueTransformer != nil) { newAngle = [angleValueTransformer transformedValue:newAngle]; } [self setValue:newAngle forKey:@"angle"]; } } // ... [self setNeedsDisplay:YES]; } How Do Bindings Work? Responding to Changes 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 35In most controls the display method alters the visual representation depending on the current selection. How Do Bindings Work? Responding to Changes 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 36Controllers require content to manipulate and there are a number of options for setting this content. It can be done programmatically, through bindings, or automatically in response to actions configured in Interface Builder. This article describes the various methods of setting and modifying a controller’s content. Setting the Content of a Controller NSObjectController and its subclasses are initialized with the method initWithContent:, passing a content object or nil if you intend to use the content bindings. You can explicitly set the content of an existing controller using the setContent: method. It is far more common to provide content for controllers by establishing a binding to one of their exposed Controller Content bindings. NSObjectController exposes a single binding for content called contentObject. You can establish a binding from contentObject to any object that is key-value-coding and key-value-observing compliant for the keys that you intend to have the controller operate on. The collection controllers expose additional bindings: contentArray, contentSet, and contentArrayForMultipleSelection. The contentArray binding is bound to an NSArray or an object that implementsthe appropriate array indexed accessor methods. Similarly the contentSet binding is bound to an NSSet object or an object that implements the appropriate set indexed accessor methods. The indexed accessor patterns are described in Indexed Accessor Patterns for To-Many Properties in the Key-Value Coding Programming Guide . The contentArrayForMultipleSelection bindingsis a special binding thatis enabled only after establishing the contentArray or contentSet binding. The contentArrayForMultipleSelection binding is used as a fallback for the content of the controller when the contentArray or contentSet bindings return the multiple values marker. It allows you to use a different object and key path as the collection content in these cases and is often used when implementing a master-detail style interface. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 37 Providing Controller ContentFor example, Figure 1 shows a typical master-detail interface. The array controller that provides the list of activities is designated as the master controller and the names of the activities are displayed in the table view on the left. A second array controller is the detail controller and provides the names of members displayed in the table view on the right. Figure 1 Master-detail interface with and without contentArrayForMultipleSelection When only the contentArray is bound to selection.members the detail table view is empty when the master array controller has a multiple selection. When the contentArrayForMultipleSelection binding is also bound to selection.@distinctUnionOfArrays.members the detail table view displays the members in all the selected activities. The detail array controller’s contentArray binding is bound to the master array controller object with the key path selection.members. The value binding of the column in the detail table view is bound to the detail array controller’s arrangedObjects.name key path. When a single activity is selected in the master table view, the detail table view displays the names of the to-many members relationship. However, what happens if the master table view is configured to allow multiple selection? If only the detail array controller’s contentArray is bound, the detail table view is empty. While thisislogical, it isn’t necessarily the desired results. A better option might be to display a unique list of the members in the selected activities. This is where the contentArrayForMultipleSelection binding and the key-value coding collection operators come into play. By establishing a binding from contentArrayForMultipleSelection to the master array controller using the key path selection.@distinctUnionOfArrays.members, the detail table view will be populated with the names of the users in all the selected activities. Because the @distinctUnionOfArrays operator was used, members that are common to both activities do not appear as duplicate names in the detail table view. Providing Controller Content Setting the Content of a Controller 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 38The contentArrayForMultipleSelection binding expects an array of data; it is not directly compatible with set collections that are bound to the contentSet binding. You must use the @distinctUnionOfSets or @unionOfSets set operator to convert the set to an array. The collection operators are described in “Set and Array Operators” in the Key-Value Coding Programming Guide . Note that when the master array controller has a multiple selection the detail array controller’s add and remove buttons are disabled. The buttons’ enabled bindings are bound to the detail array controller’s canAdd and canRemove methods. The detail array controller automatically knowsthat it is unable to add and remove items to the composite array and updates the canAdd and canRemove state, causing the buttons to be disabled. Traversing Tree Content with an NSTreeController An NSTreeController requires that you describe how it should traverse the tree of objects, by specifying a child key path. This key path can be set programmatically using theNSTreeControllermethod setChildrenKeyPath: or specified in the tree controller’s inspector panel in Interface Builder. All child objects for the tree must be key-value-coding compliant for the same child key path. If necessary you should implement accessor methods in your model classes, or categories on those classes, that map the child key to the appropriate class-specific method name. An optional count key path can be specified that, if provided, returns the number of child objects available. The count key path is set programmatically using the setCountKeyPath: method, or in the controller’s inspector panel in Interface Builder. Your model objects are expected to update the value of the count key path in a key-value-observing compliant method. Warning: Providing the count key path to an NSTreeController instance disablesthe add:, addChild:, remove:, removeChild:, or insert: methods. You can optionally provide a leaf key path that specifies a key in your model object that returns YES if the object is a leaf node, and NO if it is not. Providing this key path prevents the NSTreeController from having to determine if a child object is a leaf node by examining the child object and as a result improve performance. The leaf key path isset programmatically using the setLeafKeyPath: method, or in the controller’sinspector panel in Interface Builder. This key path affects how an NSOutlineView or NSBrowser bound to the tree controller displays disclosure triangles: ● If the leaf key path for the model object returns YES, the outline view or browser does notshow a disclosure triangle. ● If the leaf key path for the model object returns NO, then it always shows the disclosure triangle. Providing Controller Content Traversing Tree Content with an NSTreeController 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 39● If no leaf key path is configured for the controller, then the count or child key path of the model is queried to determine how many child objects are present. If there are 0 child objects, the disclosure triangle is not displayed, otherwise it is. Specifying the Class of a Controller’s Content In order for a controller to create new content objects automatically or in response to the target-action methods, it must know the appropriate class to use. Controllers can be configured in one of two modes: object mode or entity mode. In object mode the content class is specified by the method setObjectClass: or in the controller inspector panel in Interface Builder. If the controller is configured in entity mode, the class is determined by the name of the entity or by the relationship that the entity definesfor the key. The entity name isset using setEntityName: or in the controller inspector panel in Interface Builder. If the controller is in object mode, the method newObject is used to create new objects. The default implementation simply allocates a new object of the class specified by objectClass or the entityName and sends the object a standard init message with no arguments. If your content objects require more complex initialization, you can subclass the appropriate controller class and override the newObject method. An NSObjectController expects the content object to be of the class specified by the object class or entity name. When using the NSArrayController and NSTreeController the object classrefersto the individual content objects, rather than the collection that holds the objects. In both cases the collections are expected to be key-value-coding compatible with arrays or sets, depending on the binding providing the content for the controller. You are not restricted to having content of a single object class. You can create and insert objects of any class using one of the programmatic manipulation methods discussed in "Programmatically Modifying a Controller’s Contents" (page 41). Automatically Prepares Content NSObjectController and its classes provide support for automatically creating content for a controller when it is loaded from a nib file. This is typically configured in the controller inspector in Interface Builder by enabling the “Automatically Prepares Content” option. When this option is enabled, the controller creates and populates the content object or content collection when the controller is loaded from a nib file by calling the controller’s prepareContent method. Providing Controller Content Specifying the Class of a Controller’s Content 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 40For example, when an NSObjectController that has an object class of NSMutableDictionary is loaded from a nib and automatically prepares content is selected, the content of the object controller will be set to a newly instantiated, empty NSMutableDictionary instance. Similarly, if an NSArrayController that has an object class of Activity is loaded, the content is set to a newly instantiated NSMutableArray containing a single instance of Activity. NSTreeController acts the same way. If the controller that is loaded is in entity mode, then the data corresponding to the entity name is fetched and is filtered using the controller’s configured filter predicate. Programmatically Modifying a Controller’s Contents When you modify a controller’s content object the only restriction isthat you must do it in a key-value-observing compliant manner so that the controller is informed of the changes. NSObjectController and its subclasses provide a number of methods that allow you to modify the contents of a controller programmatically. NSObjectController offers the addObject: and removeObject: methods. When used with an NSObjectController, they are synonymous with the setContent: method, passing the parameter object or nil respectively. The addObject: and removeObject: methods have somewhat different behavior for NSArrayController. In this case their behavior isthe same as NSArray's addObject: and removeObject: methods. Unlike NSArray’s implementations, these methods inform the array controller of the changes so that they can be reflected in the user interface. NSArrayController extends the basic add and remove functionality with the following methods: - (void)addObjects:(NSArray *)objects; - (void)removeObjects:(NSArray *)objects; - (void)removeObjectsAtArrangedObjectIndexes:(NSIndexSet *)indexes; - (void)removeObjectAtArrangedObjectIndex:(unsigned int)index; - (void)insertObjects:(NSArray *)objects atArrangedObjectIndexes:(NSIndexSet *)indexes; - (void)insertObject:(id)object atArrangedObjectIndex:(unsigned int)index; Providing Controller Content Programmatically Modifying a Controller’s Contents 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 41The addObjects: and removeObjects: methods add or remove the objects passed as parameters from the collection. The method removeObjectsAtArrangedObjectIndexes: method iterates through the passed indexes, removing each object from the collection. The method removeObjectAtArrangedObjectIndex: removes the single object at the specified index. The insertObjects:atArrangedObjectIndexes: iterates through the array of objects passed as the first parameter, inserting each object into the arranged collection at the corresponding index in the NSIndexSet. Similarly, the insertObject:atArrangedObjectIndex: method inserts the single object specified as the first parameter into the collection at the specified index. NSTreeController provides four additional methods that operate in a similar fashion, but use NSIndexPaths to specify the location in the collection rather than simple indexes: -(void)removeObjectsAtArrangedObjectIndexPaths:(NSArray *)indexPaths; -(void)removeObjectAtArrangedObjectIndexPath:(NSIndexPath *)indexPath; -(void)insertObject:(id)object atArrangedObjectIndexPath:(NSIndexPath *)indexPath; -(void)insertObjects:(NSArray *)objects atArrangedObjectIndexPaths:(NSArray *)indexPath; Note: NSArrayController and NSTreeController are optimized for insertions and deletions made with these methods. Using these methods can provide a performance increase over modifying the model objects directly and relying on key-value observing. Modifying Controller Content by Target-Action In addition to the programmatic add, insert, and remove methods, the controller classes implement several target-action methods for modifying the controller’s content. These methods are typically configured as the actions for buttons in Interface Builder. Note: In OS X v10.4 the target-action methods are deferred so that the error mechanism can provide feedback as a sheet. NSObjectController provides the following target-action methods: - (void)add:(id)sender; Providing Controller Content Modifying Controller Content by Target-Action 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 42- (void)remove:(id)sender; The add: method creates a new content object using the controller’s newObject method and sets it as the content object of the controller if there is currently no content. The remove: method sets the content object to nil. NSArrayController overrides NSObjectController’s add: and remove: methods and addsthe following method: - (void)insert:(id)sender; With an array controller add: creates a new object using the controller’s newObject method and appends it to the controller’s content collection. The remove: method removesthe currently selected objectsin the array controller from the collection. The insert: method creates a new object using the controller’s newObject method, and inserts it after the current selection. When the controller isin entity mode the remove semantics are dependent on the configuration of the binding and on the entities definition of the relationship. A remove may result in the current selection being removed from a relationship or being removed from the object graph entirely. NSTreeController adds the following methods: - (void)addChild:(id)sender; - (void)insertChild:(id)sender; The addChild: method creates and inserts a new object at the end of the tree controller’s collection. The insertChild: method inserts a new child object relative to the current selection. Again, the semantics are slightly different if the controller is in entity mode. The add: and insert: actions use the newObject method to create the object that is added to the collection. In object mode the addChild:, and insertChild: create objects of the class specified by objectClass, but do not use the newObject method to do so. In entity mode or if the parent object is a managed object subclass, the entity defines the class of object created for and newObject is never called. In order to enable and disable the target-action buttons as appropriate, the object controller classes provide several methodsthat return Boolean valuesindicating which actions are currently possible, taking into account the controller’s current selection and configuration. //NSObjectController - (BOOL)canAdd; Providing Controller Content Modifying Controller Content by Target-Action 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 43- (BOOL)canRemove; - (BOOL)isEditable; //NSArrayController - (BOOL)canInsert; //NSTreeController - (BOOL)canAddChild; - (BOOL)canInsertChild; The enabled binding of controls are typically bound to the controller using one of these methods. As the controller’sselection changesthe valuesreturned by these methods are updated and the bound user interface items are automatically enabled or disabled as appropriate. De-coupling a Controller from its Content Bindings In order to programmatically de-couple a controller from a content object that is bound to contentObject, contentArray or contentSet, you must break the binding connection and set the controller’s content to nil. [theController unbind:@"contentArray"]; [theController setContent:nil]; Providing Controller Content De-coupling a Controller from its Content Bindings 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 44NSObjectController and itssubclasses NSArrayController and NSTreeControllersupport tracking of the currently selected object or objects. This article explains how to get a controller’s current selection, change the current selection, and fine-tune the selection behaviors. Getting a Controller’s Currently Selected Objects There are two methods that are commonly used to access the objects that are currently selected: selection and selectedObjects. NSObjectController and itssubclassesimplement the selection method. This method returns a proxy object that represents the receiver’s current selection. The proxy is fully key-value-coding compliant. When you request a key’s value from the selection proxy it returnsthe value, or a selection marker. Placeholder markers provide additional information about the selection. There are three placeholder markers defined in the NSPlaceholders informal protocol: ● NSNoSelectionMarker The NSNoSelectionMarker indicates that there are no items selected in the controller. ● NSNotApplicableMarker The NSNotApplicableMarker indicates that the underlying object is not key-value-coding compliant for the requested key. ● NSMultipleValuesMarker The NSMultipleValuesMarker indicates that more than one object is selected in the controller and the values for the requested key aren’t the same. By default controllers return the NSMultipleValuesMarker only when the values for the requested key differ. For example, if the value for selection.name returns an array containing three strings—”Tony”, “Tony”, “Tony”—the string “Tony” is returned instead of the NSMultipleValuesMarker. A collection controller can be configured—either programmatically using the method setAlwaysUsesMultipleValuesMarker: or by checking the “Always uses multiple values marker” checkbox in Interface Builder—such that it always returns NSMultipleValuesMarker when multiple items are selected, even if the values are equal. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 45 Working With a Controller’s SelectionSome bindings, such as NSTextField’s value binding, allow you to replace selection markers with custom values that are treated as placeholder values by the controls. These replacement values are specified in the Bindings inspector in Interface Builder. Bindings established programmatically can provide values for the NSNoSelectionPlaceholderBindingOption, NSNotApplicablePlaceholderBindingOption, NSNullPlaceholderBindingOption or NSRaisesForNotApplicableKeysBindingOption keys, defined in the NSKeyValueBindingCreation informal protocol, in the options dictionary passed to bind:toObject:withKeyPath:options:. The NSPlaceholders protocol also provides two class methods setDefaultPlaceholder:forMarker:withBinding: and defaultPlaceholderForMarker:withBinding: that allow you to provide default placeholders for the specified selection markers for a binding. Often you need to directly access the objects currently selected by the controller, rather than the proxy object returned by selection. NSObjectController and its subclasses provide the selectedObjects method to allow you to do just that. This method returns an array containing the objects that are currently selected by the receiver. NSObjectController’s implementation returns an array containing a single object, the content object. Note: You can establish bindings to a controller’s selection method or the selectedObjects method. However, you should avoid binding through the selectedObjects array, for example selectedObjects.name. Instead, you should use selection.name. Similarly, you should avoid observing keysthrough the array returned by selectedObjects. The proxy returned by selection is more efficient at managing changes in key-value observing as the selection changes. Changing the Current Selection The collection controllers provide methods that allow you to modify the current selection by adding and removing objects, or replacing the selection entirely. All the methods that change a controller’s selection return a boolean value that indicates if the selection was successfully changed. Thisis because an attempt to change the selection may cause a commitEditing message to be sent which may fail or be denied, perhaps due to a value failing validation. If the selection is changed successfully, these methods return YES, otherwise they return NO. Changing the Selection by Object NSArrayController providesthe following methodsfor replacing the controller’sselection completely or adding and removing objects from the current selection: Working With a Controller’s Selection Changing the Current Selection 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 46- (BOOL)addSelectedObjects:(NSArray *)objects; - (BOOL)removeSelectedObjects:(NSArray *)objects; - (BOOL)setSelectedObjects:(NSArray *)objects; All three methods require that you pass an array containing the objects as the parameter. Getting and Setting Selection by Index The collection controller classes provide additional methods to get the current selection as a set of indexes to the objects in the collection. NSArrayController provides the following methods for getting and setting the selection by index: - (unsigned int)selectionIndex; - (BOOL)setSelectionIndex:(unsigned int)index; - (NSIndexSet *)selectionIndexes; - (BOOL)setSelectionIndexes:(NSIndexSet *)indexes; - (BOOL)addSelectionIndexes:(NSIndexSet *)indexes; - (BOOL)removeSelectionIndexes:(NSIndexSet *)indexes; The selectionIndexes method returns an NSIndexSet that specifies the indexes of all the selected objects. The convenience method selectionIndex returns the index of the first selected object as an unsigned integer. You can explicitly set the selection of the controller using the setSelectionIndexes: method, passing an NSIndexSet thatspecifiesthe indexes of the itemsthatshould become the selection. The setSelectionIndex: method is a convenience method that lets you set the selection to a single index. If the selection is changed successfully, these methods return YES. The addSelectionIndexes: method attempts to add objects specified in the NSIndexSet parameter to the current selection. Similarly, the removeSelectionIndexes: attempts to remove the objects specified by index in the NSIndexSet parameter from the selection. If the selection is changed successfully, the methods return YES. NSTreeController treats data as an array of dictionaries of arrays,so a simple index of the selection isn’tsufficient. Instead NSTreeController uses an NSIndexPath to specify the location of an object in the tree. An NSIndexPath specifies the “path” to the selection as a series of indexes into the arrays, for example “1.4.2.3”. NSTreeController provides the following methods for getting and setting the selection by index path: Working With a Controller’s Selection Changing the Current Selection 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 47-(NSIndexPath *)selectionIndexPath -(NSArray *)selectionIndexPaths -(BOOL)setSelectionIndexPath:(NSIndexPath *)indexPath -(BOOL)setSelectionIndexPaths:(NSArray *)indexPaths -(BOOL)addSelectionIndexPaths:(NSArray *)indexPaths -(BOOL)removeSelectionIndexPaths:(NSArray *)indexPaths The selectionIndexPaths: method returns an array of NSIndexPath objects that represent each of the currently selected objects. The convenience method selectionIndexPath returns the first selected object as an NSIndexPath. You explicitly set the current selection using the setSelectionIndexPaths: method, passing an NSArray of NSIndexPath objects as the parameter. The convenience method setSelectionIndexPath: sets the selection to the single object specified by the NSIndexPath parameter. The methods addSelectionIndexPaths: and removeSelectionIndexPaths: add or remove the objects at the index paths specified in the array from the selection. As with the other selection modifying methods they return a boolean value of YES if the selection was successfully changed. Setting the Selection Behaviors The collection controllers provide several methods that allow you to fine-tune how selection is maintained by a controller, and how values are returned by the selection method. Avoids Empty Selection Often it is desirable to attempt to always have at least one item in a collection selected after an action such as removing an item. This is the default behavior of the collection controllers. You can modify this behavior using the method setAvoidsEmptySelection: passing NO as the parameter. This allows the controller to have an empty selection, even if there are objects in the content. You can query the current behavior using the method avoidsEmptySelection. Interface Builder allows you to change this behavior for a collection controller by unchecking the “Avoids empty selection” checkbox in the controller’s inspector panel. Working With a Controller’s Selection Setting the Selection Behaviors 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 48Selecting Objects Upon Insertion By default a collection controller automatically selects objects asthey are inserted. While thisis often the correct behavior, if you are inserting many objects into the collection it is inefficient and can degrade performance. You can turn off this behavior using the setSelectsInsertedObjects: method. Passing YES as the parameter causes all newly inserted objectsto be selected. If NO is passed asthe parameter, the currentselection is unchanged as objects are inserted. The method selectsInsertedObjects returns a boolean indicating if newly inserted objects will be selected. You can also change this setting in Interface Builder by unchecking the “Selects inserted objects” checkbox in the controller’s inspector panel. Always Uses Multiple Values Marker The NSMultipleValuesMarker indicates that more than one object is selected in the controller and the values for the requested key aren’t the same. If the values are the same the value is returned rather than the selection marker. While this allows editing of that common value across all the selected objects, it may not be the desired result. You can force all multiple selections to always return the NSMultipleValuesMarker using the method setAlwaysUsesMultipleValuesMarker:, passing YES asthe parameter. You query the state of thissetting using the method alwaysUsesMultipleValuesMarker. This setting can also be changed in Interface Builder by checking the “Always use multiple values marker” checkbox. With large selections, enabling this option can improve performance. Working With a Controller’s Selection Setting the Selection Behaviors 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 49Preserves Selection When the content of a collection controller changes, the default behavior isto attempt to find matching objects for the current selection in the new content. Figure 1 shows a master-detail interface in which the selected object in the detail NSTableView is automatically selected when the user selects a different activity in the master NSTableView. Figure 1 Preserves selection example Daniel is selected in the “Chess Club” activity list. Changing the selection to “Swim Team” in the activity list, the Daniel member is selected. This behavior can be disabled by calling the setPreservesSelection: method, passing NO asthe parameter. The current state is queried using the preservesSelection method which returns a boolean. You can also change this setting in Interface Builder by unchecking the “Preserves selection” option in the controller’s inspector. While the default behavior is often appropriate, there can be performance implications. When the content changes, the current selection must first be cached, and then the new content collection must be searched for matching objects. This can become costly when dealing with large collections and multiple selections. Selects All When Setting Content There is a per-binding option that allows you further control over the selection when using an NSArrayController. Working With a Controller’s Selection Setting the Selection Behaviors 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 50The NSSelectsAllWhenSettingContentBindingOption causesthe array controller to automatically select all the items in the array when the application changes the contentArray, contentSet, contentObject or contentArrayForMultipleSelection value of the controller. Figure 2 Selects all when setting content example Initially Daniel is selected in the “Chess Club” member list. Changing the selection to “Swim Team” causes all team members to be selected. Figure 2 shows an application with a master-detail interface. The detail NSTableView displays a single member selection “Daniel”. When the user selects the “Swim Team” item in the master NSTableView all the members are selected automatically. This option is set either in the Bindings inspector in Interface Builder, or by setting an NSNumber object with a boolean value of YES as the NSSelectsAllWhenSettingContentBindingOption value in the options dictionary passed to bind:toObject:withKeyPath:options:. The “Selects All When Setting Content” option is also useful when creating inspectorsfor master-detail interfaces that allow multiple selections to occur in the master interface. The selection that is to be inspected is predetermined by the master array controller. The inspector array controller is bound to the master array controller's selectedObjects binding,specifying the “Selects All When Setting Content” option. This ensures that all items in the master controller's current selection are always selected in the inspector. In an NSDocument-based application, the detail array controller's contentArray binding is typically bound to the NSApplication instance using the mainWindow.windowController.document. key path, substituting the master array controller's key for the final key in the key path. Working With a Controller’s Selection Setting the Selection Behaviors 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 51A binding has a number of possible options that can be configured, and many of these will influence the flow of messages between the controller, view and model objects. Value transformers, NSFormatters, key-value validation, placeholders, selection value markers, and other binding options, all affect changes made in the user interface, and in the model values. This article describes the flow of messages between the objects for common interactions with the view, controller, and model objects. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 52 Bindings Message FlowChanging the Value of a Model Property The diagram in Figure 1 showsthe flow of messages between the model, controller and view objectsin response to changing the value of a property in the model object. Figure 1 Message flow when modifying the value of a model object property View Controller Model Yes Yes No No No Yes Is the value a selection marker? 9 NSTextField contents are updated using setObjectValue:. 11 NSTextField applies its NSFormatter, if specified. 12 Updated value is displayed in the NSTextField. 17 Objects observing the binding property of the controller are notified of the value change. 6 Controller generates a key-value observing message, mapping the model key-path to the appropriate controller key-path. 5 Objects observing binding properties that have changed as a result of the new content are notified. 14 Does the binding specify a placeholder for the selection marker? 15 NSTextField's placeholder is set with the view-controller's placeholder value. 16 Content object is transformed using the controller-model value transformer, if specified. 13 Objects observing the property of the model object are notified that the value has changed. 2 Value of a property is modified using a key-value observing compliant method. 1 Controller receives the notification that the value has changed. 3 Does the controller-model binding have "Handle as Compound Value" enabled? 4 NSTextField gets the current value from the controller using key-value coding. 8 Value is transformed using the view-controller binding value transformer, if specified. 10 NSTextField receives notification of the value change. 7 Bindings Message Flow Changing the Value of a Model Property 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 53Specifically, this example is of an NSTextField with its value binding bound to an NSObjectController’sselection using the selection.firstName key path. The NSObjectController’s content binding is bound to a model object that encapsulates a person’s name and address. 1. A property of the model object is changed using a key-value-observing compliant means. 2. The objects that are registered with the model object to receive key-value observing change notifications are sent an observeValueForKeyPath:ofObject:change:context: message by the model object’s inherited key-value observing implementation. 3. The controller receives the observeValueForKeyPath:ofObject:change:context: message. The controller is registered with the model object as a result establishing the binding to the model object. 4. The controller tests to see if the controller-model binding has the “Handles as Compound Value” option set. If “Handles as Compound Value” is enabled, proceed to Step 13. 5. The controller generates a key-value observing message for the value that has changed, mapping the model key-path to the appropriate controller key-path. For example, if the key path of the property in the model objectis“firstName”then the key-value observing change ismapped to “selection.firstName”. 6. The objectsthat are registered with the controller object to receive key-value observing change notifications are sent an observeValueForKeyPath:ofObject:change:context: message by the controller object’s inherited key-value observing implementation. 7. The view receives the observeValueForKeyPath:ofObject:change:context: message. The view is registered with the controller object as a result establishing the binding to the controller object. 8. The view objects gets the current value for the changed property from the controller using key-value coding. 9. The view tests the value retrieved in Step 8. If the value is one of the selection markers, or nil, proceed to Step 15. 10. If the view-controller binding specifies a value transformer, the value retrieved in Step 8 is passed to the value transformer’s transformedValue: method. The value returned by the transformedValue: method is passed to the next step. 11. The view setsits contentsto the updated, possibly transformed, value using the view’s setObjectValue: method. 12. If the view has an NSFormatter attached to it, the value is formatted by the NSFormatter instance. Proceed to Step 17. 13. If the controller-model binding specifies a value transformer the entire model is transformed using the transformedValue: method. 14. The controller generates a key-value observing message, mapping the key path to the selection. This generates the same type of key-value observing change notification that would result in replacing the content object. Proceed to Step 7. Bindings Message Flow Changing the Value of a Model Property 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 5415. If the binding specifies a placeholder for the view-controller binding for the value marker it is used in Step 16. If no custom placeholder value is specified as part of the binding, and a custom default placeholder has been set for the view class and this particular binding, it is used in Step 16. Otherwise, flow returns to Step 11. An application can assign a custom default placeholder for a class and binding combination using the NSPlaceholders class method setDefaultPlaceholder:forMarker:withBinding:. 16. The placeholder value is set for the view using the setPlaceholderString: or setPlaceholderAttributedString: method. 17. The updated value is displayed in the user interface. Bindings Message Flow Changing the Value of a Model Property 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 55User Updates a Value in the User Interface The diagrams in Figure 2 and Figure 3 (page 58) show the flow of messages between the model, controller and view objects in response to changing the value of a property in the model object. Bindings Message Flow User Updates a Value in the User Interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 56Figure 2 Message flow in response to the user changing a value in an NSTextField View Controller Model Yes Yes User enters new value into the NSTextField. 1 Is "Handle as Compound Value" enabled for the controller-model binding? 6 Is "Validates immediately" enabled for the controller-model binding? 19 Invokes setValue:forKeyPath on the model with the new content object. 22 User is notified that value is invalid. 21 Invokes setValue:forKeyPath: on the new content object with the new property value. 17 New content object is transformed using the controller-model binding value transformer, if specified. 16 Gets the current content object from the model using valueForKeyPath:. 15 Invokes setValue:forKeyPath on the model passing the object value and the bound key path. 7 Invokes setValue:forKeyPath on the controller passing the object value and the binding's key path. 5 NSTextField attempts to validate the value using the NSFormatter, if specified. 2 Is "Validates immediately" enabled for the view-controller binding? 4 Value is transformed using the view-controller binding value transformer, if specified and if it supports reverse transformation. 3 Content object is transformed using the controller-model binding value transformer, if specified and if it supports reverse transformation. 18 Attempts to validate the new content object using key-value validation by invoking validateValue:forKeyPath:error: on the model. 20 Updated value now stored in model object. Key-value observing notifications are sent to observers of this model property. 23 Yes Valid No No No Valid or Invalid coerced value 8 See Figure 3. 13 See Figure 3. Bindings Message Flow User Updates a Value in the User Interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 57Figure 3 Message flow in response to the user changing a value in an NSTextField, view-controller validation View Controller Model Attempts to validate the value using key-value validation by invoking validate:error: on self. 11 10 Returns original valid value coerced value, or invalid Returns original valid value coerced value, or invalid Attempts to validate the value using key-value validation by invoking validateValue:forKeyPath:error: on the controller. 8 Attempts to validate the value using key-value validation by invoking validateValue:forKeyPath:error: on the model. 12 9 Valid or coerced value Invalid 4 Yes See Figure 2. 5 See Figure 2. User is notified that value is invalid. 14 Is the value valid, was coerced valid, or invalid? 13 As in “"Changing the Value of a Model Property" (page 53)” this specific example is of an NSTextField with its value binding bound to an NSObjectController’s selection using the selection.firstName key path. The NSObjectController’s content binding is bound to a model object that encapsulates a person’s name and address. 1. The user enters a new value into the NSTextField. 2. If an NSFormatter is attached to the NSTextField the formatter attemptsto validate the value. If the formatter fails to validate the value it provides failure feedback and returns control to the user. The view-controller binding option “Continuously Updates Value” determines when the view notifies the controller of changes in the text field. If it this option is specified, the controller will be updated for each keystroke. If it is disabled then the controller is only updated when the user hits return, tab, or the text field loses first responder status. 3. If the view-controller binding specifies a value transformer and the value transformer supports inverse transformations, the new value is transformed using the inverseTransformedValue: method. The value returned by the inverseTransformedValue: method is passed to the next step. 4. If the view-controller binding option “Validates Immediately” is enabled, then proceed to Step 8. Bindings Message Flow User Updates a Value in the User Interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 585. The view object invokes setValue:forKeyPath: on the controller object, passing the new, possibly transformed, object value and the binding’s key path as arguments. 6. If the controller-model binding option “Handle as Compound Value” is enabled, then proceed to Step 15. 7. The controller invokes setValue:forKeyPath: on the model object, passing the new content value from Step 5 and the key path for the property in the model object as arguments. Proceed to Step 23. 8. The view attempts to validate the value from Step 4 using key-value validation. It does this by invoking validateValue:forKeyPath:error: on the controller, passing the proposed value, the binding’s key path, and an NSError pointer reference as arguments. 9. The controller receivesthe validateValue:forKeyPath:error: message and forwardsthe validation request to the model object’s validateValue:forKeyPath:error: implementation, modifying the key path so that it references the appropriate model object property. 10. The model object receivesthe validateValue:forKeyPath:error: message and attemptsto validate the proposed value by invoking validate:error: on self. The specific method signature will be dependent on the name of the property. The model object’simplementation of validate:error: returns a Boolean value indicating if the value was valid. If the result is YES, then the proposed value was valid, or was replaced with a validated value. If the result is NO, then the proposed value is invalid and the error reference should contain a description of why the validation failed. 11. The validation result, value, and a possible error are returned by the model’s implementation of validate:error: to the controller’s validateValue:forKeyPath:error: method. 12. The validation result, value, and a possible error are returned by the controller’s validateValue:forKeyPath:error: method to the view. 13. If the validation result is YES, then the valid or coerced value are returned to Step 5, otherwise proceed to Step 14. 14. The user is notified that the value is invalid. How the error is presented to the user is dependent on the view-controller binding’s “Always Presents Application Modal Alert Panels” option. If this option is enabled, then the error is displayed to the user as a modal alert panel. If it is not enabled, then the error is presented to the user as a sheet. 15. The controller gets the current content object using valueForKeyPath: on the model object. This is the message flow path for “Handle as Compound Value”. The original content object specified by the contentObject, contentArray or contentSet binding is retrieved from the model, transformed, the new value from the user inserted, the content object isinverse transformed, and set asthe new content object. 16. If the controller-model binding specifies a value transformer the content object retrieved in Step 15 is transformed using the transformedValue: method. The value returned by the transformedValue: method is passed to the next step. Bindings Message Flow User Updates a Value in the User Interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 5917. The controller invokes setValue:forKeyPath: on the retrieved, possibly transformed, content object. The value from Step 5 and the key path for the property in the model object as arguments. 18. If the controller-model binding specifies a value transformer and the value transformer supports inverse transformations, the content object from Step 17 istransformed using the inverseTransformedValue: method. The value returned by the inverseTransformedValue: method is passed to the next step. 19. If the controller-model binding option “Validates Immediately” is enabled, proceed to Step 20, otherwise proceed to Step 22. 20. The controller attempts to validate the new, possibly transformed, content object by invoking validateValue:forKeyPath:error: on the model object. If validateValue:forKeyPath:error: returns YES, then the valid or coerced valid value is passed to Step 22. If the result is invalid, proceed to Step 21. 21. The user is notified that the value is invalid. How the error is presented to the user is dependent on the controller-controller binding’s“Always Presents Application Modal Alert Panels” option. If this option is enabled, then the error is displayed to the user as a modal alert panel. If it is not enabled, then the error is presented to the user as a sheet. 22. The controller invokes setValue:forKeyPath: on the model object using the new, possibly validated content object and the content key path as arguments. 23. The updated value is now stored in the model object. Changing the model object resultsin key-value observing change notifications being sent to the observers of the model property. Bindings Message Flow User Updates a Value in the User Interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 60Many applications provide a preferences window that allows the user to customize an application’s settings. NSUserDefaultsController provides a layer on top of NSUserDefaults and allows you to bind attributes of user interface items to the corresponding key in an application’s user defaults. What Is NSUserDefaultsController? NSUserDefaultsController is a concrete subclass of NSController that implements a bindings-compatible interface to NSUserDefaults. Properties of an instance of NSUserDefaultsController are bound to user interface items to access and modify values stored using NSUserDefaults. NSUserDefaultsController istypically used when implementing your application’s preference window interface, or when you can bind a user interface item directly to a default value. NSUserDefaults remains the primary programmatic interface to your application’s default values for the rest of your application. By default NSUserDefaultsController immediately applies any changes made to its properties. It can be configured so that changes are not applied until it receives an applyChanges: message, allowing the preferences dialog to support an Apply button. NSUserDefaultsController also supports reverting to the last applied set of values, using the revert: method. NSUserDefaultsController also allows you to provide a dictionary of factory defaults that can be used to reset the user configurable valuesfor your application, usually done in response to a user clicking a Revert to Factory Defaults button. The Shared User Defaults Controller NSUserDefaultsController provides a shared instance of itself via the class method sharedUserDefaultsController. This shared instance uses the NSUserDefaults instance returned by the method standardUserDefaults as its model, has no initial values, and immediately applies changes made through its bindings. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 61 User Defaults and BindingsCare must be taken that changes to the settings of the shared user defaults controller are made before any nib files containing bindingsto the shared controller are loaded. To ensure that these changes are made before any nib files are loaded, they are often implemented in the initialize class method of the application delegate, or in your preferences window controller. Binding to the Shared User Defaults Controller The shared NSUserDefaultsController is always available as a bindable controller in the Bindings Info window in Interface Builder. When establishing a binding to a user default, set the Controller Key to values, and the Model Key Path to the key of the default. Creating bindings programmatically requires that you retrieve the shared user defaults controller using the NSUserDefaultsController class method sharedUserDefaultsController. You then provide that object as the observableController to the bind:toObject:withKeyPath:options: method. The example in Listing 1 establishes a binding between an NSTextField (theTextField) and the userName default using the shared user defaults controller. Listing 1 Binding the userName defaults key to an NSTextField programmatically [theTextField bind:@"value" toObject:[NSUserDefaultsController sharedUserDefaultsController] withKeyPath:@"values.userName" options:[NSDictionary dictionaryWithObject:[NSNumber numberWithBool:YES] forKey:@"NSContinuouslyUpdatesValue"]]; initialValues Versus NSUserDefaults registerDefaults: The initial values dictionary allows you to provide a means to reset the user configurable default values to the factory defaults. Typically these values represent a subset of the defaults that your application registers using the NSUserDefaults method registerDefaults:. Calling the NSUserDefaultsController method setInitialValues: should not be considered a replacement for registering your application's preference defaults using NSUserDefault's registerDefaults: method. User Defaults and Bindings Binding to the Shared User Defaults Controller 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 62The example in Listing 2 loads the default values from a file in the application wrapper, registers those values with NSUserDefaults, and then registers a subset of the values as the initial values of the shared user defaults controller. The setupDefaults method would be called from your application delegate’s initialize class method. Listing 2 Changing the initial values of the sharedUserDefaultsController instance + (void)setupDefaults { NSString *userDefaultsValuesPath; NSDictionary *userDefaultsValuesDict; NSDictionary *initialValuesDict; NSArray *resettableUserDefaultsKeys; // load the default values for the user defaults userDefaultsValuesPath=[[NSBundle mainBundle] pathForResource:@"UserDefaults" ofType:@"plist"]; userDefaultsValuesDict=[NSDictionary dictionaryWithContentsOfFile:userDefaultsValuesPath]; // set them in the standard user defaults [[NSUserDefaults standardUserDefaults] registerDefaults:userDefaultsValuesDict]; // if your application supports resetting a subset of the defaults to // factory values, you should set those values // in the shared user defaults controller resettableUserDefaultsKeys=[NSArray arrayWithObjects:@"Value1",@"Value2",@"Value3",nil]; initialValuesDict=[userDefaultsValuesDict dictionaryWithValuesForKeys:resettableUserDefaultsKeys]; // Set the initial values in the shared user defaults controller [[NSUserDefaultsController sharedUserDefaultsController] setInitialValues:initialValuesDict]; } User Defaults and Bindings initialValues Versus NSUserDefaults registerDefaults: 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 63Search Order for Defaults Values When a method that is key-value coding compliant attempts to get a value for a key from an NSUserDefaultsController the following search pattern is used: 1. The value of a corresponding key in values 2. The value of a corresponding key in the NSUserDefaultsinstance returned by the NSUserDefaultsController method defaults. 3. The value of a corresponding key in the initial values dictionary If no corresponding value is found, nil is returned. The search path is somewhat different when you retrieve the result directly from the NSUserDefaults instance associated with the NSUserDefaultsController. In that case, any unapplied valuesin the NSUserDefaultsController, as well as the values in the initial values dictionary are ignored. Programmatically Accessing NSUserDefaultsController Values Although NSUserDefaults should remain your primary programmatic interface to the user defaults, some circumstancesrequire that you get and set the default values contained in an NSUserDefaultsController instance directly. For example, when implementing portions of your preferences window that don’t directly interact with an existing binding, such as setting a font or choosing a directory path. The NSUserDefaultsController method values returns a KVC-compliant object that is used to access these default values. To get the value of a default, use the valueForKey: method. [[theDefaultsController values] valueForKey:@"userName"]; Similarly, to set a value for a default, use setValue:forKey:. [[theDefaultsController values] setValue:newUserName forKey:@"userName"]; The NSUserDefaultsController automatically provides notification of the value change to any established bindings for that key path. User Defaults and Bindings Search Order for Defaults Values 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 64This article explains how to use bindings to implement a basic master-detail interface. In the master interface portion, a table view is used to display your collection of objects. In the detail interface portion, other views are used to display the selected object. This article contains examples of binding table columns to array controllers. A master-detail interface can be extended in a variety of ways that are not fully covered in this article. In particular, there are many aspects of a table view that work seamlessly with Cocoa bindings. Refer to these other articles for specific tasks: ● "Displaying Images Using Bindings" (page 73) describes the various options used when displaying images in columns and contains an example of a custom value transformer. ● "Implementing To-One Relationships Using Pop-Up Menus" (page 78) explains how to implement editable to-one relationship as pop-up menus. ● "Filtering Using a Custom Array Controller" (page 81) explains how to add a search field to the master interface in order to filter the objects it displays. What’s a Master-Detail Interface? In a master-detail interface, the user can select objects from a list of objects and inspect the selected objects. The master interface displays the collection of objects, and the detail interface implements an inspector of the selected object. Whenever the user changes the selection in the master interface, the detail interface is updated to show the new selection. If no object is selected, the detail interface displays nothing or disables itself (if it is editable). If multiple objects are selected (assuming multiple selection is allowed), the detail interface is disabled or it applies to all selected objects. Typically, such an interface also allows users to add and remove objects from the collection. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 65 Creating a Master-Detail InterfaceWhat components you use to implement a master-detail interface depend on your application. Often, the master interface is implemented by a table view and the detail interface is a collection of views located above or below the master interface. Figure 1 shows a master-detail interface in a media asset application. In this example, the table view displays a collection of media objects and the views below display the properties of the selected media object. Figure 1 A master-detail interface Master interface Detail interface Creating Models This article assumes that you have already designed your model classes, the objects that encapsulate your application data and provide methods to operate on that data. A master-detail interface is used to display a collection of model objects. Therefore, your root model object is expected to be a collection of these objects. Creating a Master-Detail Interface Creating Models 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 66For example, Figure 2 illustratesthe object diagram of the modelsin a media asset application. In this example, assume the application uses a document-based architecture in which MyDocument (the File’s Owner of the MyDocument.nib file) has a mediaAssets instance variable that is initialized to an array of Media objects. Figure 2 An object model anImage ... aMedia title date image author anAddress street city zip county aPhone work home aPerson mobile firstName lastName phone address Creating Views The master interface shown in Figure 1 (page 66) uses a table view in which each column in the table corresponds to a property of the displayed objects. Note that the table view displays attributes such as the title and date, as well as relationships such as the author. The author property is a to-one relationship (see Figure 2 (page 67)) in which the destination object is a Person object. You can display to-one relationships in a variety of ways. For example, the master interface displays only the author’s last name. The detail interface lets you select the author from a pop-up menu. Using Interface Builder, lay out your master-detail interface similar to Figure 1 (page 66). In this example, an image cell was dragged to the Image column to display a scaled version of the media image and a date formatter was dragged to the Date column. The Author column displays the last name of the authors but could be configured to display a menu as well by dragging a pop-up menu cell, NSPopUpButtonCell, to the Author column. Creating a Master-Detail Interface Creating Views 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 67Creating Controllers Next you need to connect your viewsto your models via a controller. NSArrayController isspecifically designed to manage selectable collections of objects. For thisreason, it isideal for implementing a master-detail interface. After you create an array controller, you specify its content to be your collection of model objects. If the array controller is editable, it can also create instances of models and add them to the collection. For this to work, you also need to tell the array controller the class name the entity it is managing. Follow these steps to create and configure an array controller for a master-detail interface: 1. Create an array controller by dragging an NSArrayController from the Interface Builder Controllers palette to your nib file, and optionally change the name of the controller. For example, change the name to MediaAssetsController. 2. Enter the class name of your model in the Object Class Name field on the Attributes pane of the Info window as shown in Figure 3. In the media asset application example, you would enter Media as the class name. 3. Deselect Editable on the Attributes pane if you don’t want the user to edit the models, or add and remove them from the collection. Figure 3 An array controller Attributes pane Creating a Master-Detail Interface Creating Controllers 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 68Binding Controllers to Models Each view and controller class exposes a set of bindings. You can inspect the bindings of an object using Interface Builder by selecting it and displaying the Bindings pane in the Info window. Select your array controller in the nib file and display its bindings as shown in Figure 4 (page 69). You specify the content of an array controller by configuring its contentArray binding. For example, assuming the File’s Owner maintains a collection of Media objects called mediaAssets, you would configure the contentArray binding as follows: 1. Set the Bind to aspect to the object that maintains the collection of model objects (for example, the File’s Owner). 2. Leave the Controller Key blank. 3. Set the Model Key Path to the name of the array (for example, mediaAssets). Figure 4 shows what the Bindings pane should look like when the contentArray binding is revealed. Figure 4 An array controller Bindings pane Now this controller is configured to manage a collection of Media objects including adding and removing Media objects from the array. Go back to the Attributes pane if you want to change the default behavior of this controller—deselect Editable if you don’t want the user to edit the collection. Creating a Master-Detail Interface Binding Controllers to Models 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 69Binding Views to Controllers Next, connect your views to your array controller by configuring the bindings of your view objects—bind each view in the master and detail interfaces to the array controller. Setting some of these bindings can be complex if, for example, you want to represent an editable to-one relationship. This article covers the most common types of value bindings. See "Displaying Images Using Bindings" (page 73) and "Implementing To-One Relationships Using Pop-Up Menus" (page 78) for examples of more complex bindings. In general, it helps to remember that most views that display some content have a binding called value or a binding that contains the word “value.” Also, because you bind a view to a controller, you need to be familiar with the properties of controllers. These are the primary properties of an array controller that you typically use as the value of the Controller Key aspect: ● arrangedObjects—specifies the collection of objects being displayed. ● selection—specifies the selected object in arrangedObjects. ● selectedObjects—specifies the selected objects in arrangedObjects for a multiple selection. Binding the Master Interface In the master interface, you actually configure the bindings of the table columns, not the bindings of a table view. Even if you use a special type of cell in the table column, for example, an image cell or NSPopUpButtonCell, you configure the table column, not the cell. The bindings for an NSTableColumn may change depending on its cell. In this example, each row in the table view needs to correspond to a single Media object, and each column needs to display a property of that Media object. To display properties, you first select a table column in the table view, display the Bindings pane, and reveal the value binding. You will then bind the table column to the controller’s arrangedObjects key because you are specifying the contents of the entire column, not a single cell. Configure each value binding to display a property of the Media object as follows: 1. Set the Bind to aspect to your array controller object. For example, MediaAssetsController. 2. Set the Controller Key to arrangedObjects (the collection of objects being displayed). 3. Set the Model Key Path to the property you want to appear in that column. For example, in the media asset application, set the Model Key Path to date in the Date column. Creating a Master-Detail Interface Binding Views to Controllers 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 70Figure 5 shows what the Bindings pane should look like when the value binding of the Title column isrevealed. Figure 5 NSTableColumn Bindings pane In the case of the author property, you can set the Model Key Path to author.lastname if you want to simply display the last name. However, by default column cells are editable, so when you run your application, users will be able to change the author’s last name by editing the text in the Author column. If you don’t want this behavior, select the column and deselect Editable on the Attributes pane in the Info window. Note that some Cocoa views already display lists of objects that work well with key-value coding. The Controller Key and Model Key Path aspects of a binding are concatenated to retrieve the value from the bound object. In the case of a table column, the Controller Key identifies an array; therefore the returned value is an array. For example, the Author table column uses the arrangedObjects.author.lastname key path to get an array of last names, instances of NSString, from the bound object. Binding the Detail Interface You bind the views in the detail interface similarly to the way you bind the master interface except that you set the Controller Key for each binding to selection, the currently selected object. For example, you configure the value binding for the Title text field in the detail interface depicted in Figure 1 (page 66) as follows: 1. Set the Bind to aspect to your array controller object. For example, MediaAssetsController. Creating a Master-Detail Interface Binding Views to Controllers 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 712. Set the Controller Key to selection (the currently selected object). 3. Set the Model Key Path to the property you wish displayed in that view. For example, title. Creating a Master-Detail Interface Binding Views to Controllers 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 72You typically display images using either an NSImageCell or an NSImageView. You might display images in table columns in a master interface, or an image view in a detail interface. Both of these components have similar bindings and therefore are both discussed in this article. When using these components, you also need to make similar decisions about how you want to store and access your images. The value bindings of these components support a variety of formats. You can specify the value binding using an NSImage, a file path or a URL. The example presented in this article is an extension of those in "Creating a Master-Detail Interface" (page 65). Specifically, this article explains how to add an NSImageCell to a table column in the master interface (shown in Figure 1) and an NSImageView to the detail interface. This article also contains an example of a custom value transformer that converts image filenames to absolute paths. See "Creating a Master-Detail Interface" (page 65) for the steps to create a basic master-detail interface. Figure 1 Using an NSImageCell in an NSTableColumn Creating Models How you define image properties in your models depends on your application—it depends on how you want to store and accessthe images. If the images are stored on disk or in your project folder on the same computer, then you can access them via a file path. If the images are stored not on disk but on a remote server, then you can access them via a URL. If the images are stored in some data source, then you might load the images directly into memory. If you load them, you might define your image properties as simply NSImage objects. Fortunately, Cocoa bindings supports all these options. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 73 Displaying Images Using BindingsIn this example, the model uses an NSImage to represent the image property of a Media object as shown in Figure 2 (page 67) in "Creating a Master-Detail Interface" (page 65). In the case of a file path or URL, you typically store only the filename in the model not the absolute path or URL (for example, you don’t want to update your models every time you move the image folder). However, the bindings expect an absolute path or URL. One solution is to implement a custom value transformer that takes an image filename and returns a file path or URL based on some variables you define. See "Using a Value Transformer to Convert Paths" (page 75) to modify this example to use file paths instead of NSImage objects. Creating Views Next, you create the image views by either dragging an NSImageView to a window or an NSImageCell to the column that will display the images. Creating Controllers This example assumes you already have a working master-detail interface. Follow the steps in "Creating Controllers" (page 68) in “Creating a Master-Detail Interface” if you need to create an array controller. Binding Views to Controllers Next, you bind the image views to the controllers. A subset of the value bindings of an NSImageView and an NSTableColumn (containing an NSImageCell) to choose from are: ● value—an NSImage object. ● valuePath—an absolute path to the image file. ● valueURL—a URL that returns the image file. Note: When using an NSImageCell in a table column, you need to configure the bindings of the table column, not the cell. When you drag an NSImageCell to a column, the Value category on the NSTableColumn Bindings pane changes to reveal additional value bindings (displays the same value bindings as an NSImageView). For example, you configure the value binding for the Image table column in Figure 1 (page 73) as follows: 1. Set Bind to to your array controller object. For example, MediaAssetsController. Displaying Images Using Bindings Creating Views 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 742. Set Controller Key to arrangedObjects (the collection of objects being displayed). 3. Set Model Key Path to the NSImage property to display in that column. For example, in the media asset application, set the key path to image. You configure the value binding for the NSImageView in the detail interface similarly, except that you set the Controller Key value to selection (that is, the currently selected object). See "Using a Value Transformer to Convert Paths" (page 75) for a variation of this example that uses the valuePath binding. Using a Value Transformer to Convert Paths If you want to access your images using a file path, then you bind your views to your controllers using the valuePath binding instead. However, valuePath is expected to be an absolute file path. Typically, you do not store absolute paths in your models, just filenames or relative paths. You can convert a filename or relative path to an absolute path using a custom value transformer as follows. Creating Custom Value Transformers First create a custom value transformer that takes the filename or relative path and converts it to an absolute path. You do this by subclassing NSValueTransformer and overriding the transformedValueClass and allowsReverseTransformation class methods, as shown in Listing 1 (page 75). You implement the transformedValue: method to perform the transformation. For example, the transformedValue: method implementation in Listing 1 assumes the images are located in the project Resources folder and uses NSBundle’s resourcePath: method to convert the filename to an absolute path. Note that you need to modify this example if you store the images somewhere else on the file system. Listing 1 PathTransformer implementation file #import "PathTransformer.h" @implementation PathTransformer + (Class)transformedValueClass { return [NSString self]; } Displaying Images Using Bindings Using a Value Transformer to Convert Paths 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 75+ (BOOL)allowsReverseTransformation { return NO; } - (id)transformedValue:(id)beforeObject { if (beforeObject == nil) return nil; id resourcePath = [[NSBundle mainBundle] resourcePath]; return [resourcePath stringByAppendingPathComponent:beforeObject]; } @end Registering Value Transformers In order to use your custom value transformer, you must first register it with NSValueTransformer. Note that you register instances of a value transformer, not a subclass. You typically register value transformers in an initialize method or the application delegate’s applicationDidFinishLaunching: method. When you register a value transformer, you give it a logical name you can use later when configuring a bindings. For example, add the following code fragment to applicationDidFinishLaunching: to register an instance called PathTransformer: id transformer = [[[PathTransformer alloc] init] autorelease]; [NSValueTransformer setValueTransformer:transformer forName:@"PathTransformer"]; Binding Views to Controllers Using Transformers Finally, you specify the value transformer when binding your views to your controllers using the valuePath binding. For example, you configure the valuePath binding for the Image table column as follows: 1. Set the Bind to aspect to your array controller object—for example, MediaAssetsController. 2. Set the Controller Key aspect to arrangedObjects (the collection of objects being displayed). 3. Set the Model Key Path aspect to the property containing the image filename. For example, in the media asset application, set the key path to imagePath. Displaying Images Using Bindings Using a Value Transformer to Convert Paths 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 764. Enter the transformer’s logical name, PathTransformer , in the Value Transformer text field. Figure 2 shows the Bindings pane of an NSTableColumn in Interface Builder with the valuePath binding revealed and configured to use a custom value transformer. Figure 2 Bindings pane of an NSTableColumn To use the valueURL binding instead, implement a similar value transformer to convert filenames or relative paths to an appropriate NSURL object. Optionally, you can enhance the PathTransformer class to handle other types of filename transformations. In the latter case, register different instances using different names (for example, PathTransformer and URLTransformer) to handle each type of transformation. Displaying Images Using Bindings Using a Value Transformer to Convert Paths 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 77You can implement an editable to-one relationship using an NSPopUpButtonCell or NSPopUpButton. That is, allow the user to select a menu item from a pop-up menu in order to change the destination object of a to-one relationship in your model. This article extendsthe example presented in "Creating a Master-Detail Interface" (page 65) by adding a pop-up menu to the table view in the master interface. Instead of displaying the author’s last name in the Author column, you might allow users to select an author from a pop-up menu, as shown in Figure 1. Note that if you display just the last name, you have essentially flattened the to-one relationship. Consequently, if the user enters text in an editable Author column text cell, the user changes the value of the last name property belonging to the Person object, not the destination of the to-one relationship belonging to the Media object. Using pop-up menus is one way to implement an editable to-one relationship. See "Creating a Master-Detail Interface" (page 65) for the steps to create a master-detail interface. Figure 1 Using pop-up menus to represent to-one relationships Creating Models and Controllers To do this, you first need the supporting model and controller objects. Assuming you already have a master interface, you create an array of models that will be displayed in the pop-up menu, and you create an array controller to manage it. How you initialize the collection of objectsto display in the pop-up depends on your application. This example assumes that a collection already exists and is a property of the File’s Owner (for example, a property called authors containing Person objects). 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 78 Implementing To-One Relationships Using Pop-Up MenusCreate an NSArrayController by dragging it from the Cocoa-Controllers palette to your nib file, and rename it appropriately (for example, AuthorsController). It’s common to have multiple controller objects per nib file so renaming them helps to identify them. Now, bind the model to the controller as follows. Select the array controller, display the Bindings pane in the Info window, reveal the contentArray binding, and configure it as follows: 1. Set the Bind to aspect to the object that maintains the collection of model objects (for example, the File’s Owner). 2. Leave the Controller Key blank. 3. Set the Model Key Path to the name of the array (for example, authors). Also enter the appropriate class name in the Object Class Name field on the Attributes pane (for example, enter the Person class name). Creating Views Next, you create the pop-up views by dragging an NSPopUpButton to a window or an NSPopUpButtonCell to the column that will display the to-one relationship. Binding Views to Controllers The primary bindings of an NSPopUpMenu and NSTableColumn (containing an NSPopUpButtonCell) that you will use to set up an editable to-one relationship are: ● content—the collection of objects to display in the pop-up menu. ● contentValues—the property of the objects in content that you want to display in the pop-up menu. ● selectedObject—the to-one relationship that users change when selecting an item from the pop-up menu. Note: When using an NSPopUpButtonCell, you need to configure the bindings of the table column, not the cell. When you drag an NSPopUpButtonCell to a column, the Value category on the NSTableColumn Bindings pane changes to a Value Selection category containing the same bindings as an NSPopUpButton. For example, if you want to display a pop-up menu in a column, configure the content binding to specify the content of the pop-up menu as follows: Implementing To-One Relationships Using Pop-Up Menus Creating Views 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 791. Set the Bind to aspect to AuthorsController. 2. Set the Controller Key aspect to arrangedObjects . 3. Leave the Model Key Path aspect blank. Then configure the contentValues binding to specify whatshould be displayed in the menu items asfollows: 1. Set the Bind to aspect to AuthorsController. 2. Set the Controller Key aspect to arrangedObjects. 3. Set the Model Key Path aspect to lastName. Finally, configure the selectedObject binding to specify the actual to-one relationship this pop-up menu changes as follows: 1. Set the Bind to aspect to MediaAssetsController. 2. Set the Controller Key aspect to arrangedObjects. 3. Set the Model Key Path aspect to author (a to-one relationship). Now, when you run your application, a pop-up menu appears in each of the table column cells, displaying the current value of the to-one relationship. When the user selects another item from the menu, the controller changes the destination object of that to-one relationship. Follow the same steps above to configure an NSPopUpButton as an editable to-one relationship. If you are implementing a master-detail interface and this pop-up button appears in the detail interface, then set the Controller Key for the selectedObject binding to selection, that is, to the currently selected object. Implementing To-One Relationships Using Pop-Up Menus Binding Views to Controllers 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 80This article explains how to use a search field and custom array controller to filter a collection of objects. Although you typically use a search field in conjunction with a table view to implement this style of interface, the tasks discussed in this article are not limited to these components. Overriding arrangeObjects: The arrangeObjects: method sorts the content of the array controller using the current sort descriptors. To restrict the displayed content to a subset of the content you must override arrangeObjects:, create a new array containing the subset, and then call the superclass’s implementation of arrangeObjects: to provide any appropriate sorting. The arrangeObjects: implementation in Listing 1 performs an anchored search of the title property. In an anchored search, only those objects whose title property matches searchString are added to the returned array. Listing 1 Filtering implementation of arrangeObjects: - (NSArray *)arrangeObjects:(NSArray *)objects { if (searchString == nil) { return [super arrangeObjects:objects]; } NSMutableArray *filteredObjects = [NSMutableArray arrayWithCapacity:[objects count]]; NSEnumerator *objectsEnumerator = [objects objectEnumerator]; id item; while (item = [objectsEnumerator nextObject]) { if ([[item valueForKeyPath:@"title"] rangeOfString:searchString options:NSAnchoredSearch].location != NSNotFound) { [filteredObjects addObject:item]; 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 81 Filtering Using a Custom Array Controller} } return [super arrangeObjects:filteredObjects]; } Updating the Search String You implement the search: action method to invoke rearrangeObjects, which triggers the invocation of the arrangeObjects: method. Listing 2 shows an implementation of a search: action. The searchString is set to the string value of the sender object, and rearrangeObjects is called. Listing 2 Updating searchString - (void)search:(id)sender { // set the search string by getting the stringValue // from the sender [self setSearchString:[sender stringValue]]; [self rearrangeObjects]; } - (void)setSearchString:(NSString *)aString { [aString retain]; [searchString release]; searchString=aString; } @end The search: action is invoked by an NSSearchField. The target of the search field is set to the array controller, and the action to the search: method. The search field should be configured so that it does not send the whole string as it changes. Turning this option off causes the search: method to be invoked each time that a keystroke occurs in the search field. Filtering Using a Custom Array Controller Updating the Search String 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 82The Cocoa bindings controller classes only provide key-value observing notifications for selected properties. This article enumerates the key-value-observing compliant properties for each class. Important: The Cocoa bindings controller classes do not provide change values when sending key-value observing notificationsto observers. It isthe developer’sresponsibility to query the controller to determine the new values. NSUserDefaultsController NSUserDefaultsController is key-value-observing compliant for the following properties: ● appliesImmediately ● defaults ● hasUnappliedChanges ● initialValues ● values NSObjectController NSObjectController is key-value-observing compliant for the following properties: ● canAdd ● canRemove ● content ● isEditable ● objectClass ● selectedObjects ● selection 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 83 Controller Key-Value Observing ComplianceNSArrayController NSArrayController is key-value-observing compliant for the following properties: ● alwaysUsesMultipleValuesMarker ● arrangedObjects ● avoidsEmptySelection ● canAdd ● canInsert ● canRemove ● canSelectNext ● canSelectPrevious ● clearsFilterPredicateOnInsertion ● content ● filterPredicate ● isEditable ● preservesSelection ● selectedObjects ● selection ● selectionIndex ● selectionIndexes ● selectsInsertedObjects ● sortDescriptors NSTreeController NSTreeController is key-value-observing compliant for the following properties: ● alwaysUsesMultipleValuesMarker ● arrangedObjects ● avoidsEmptySelection ● canAdd ● canAddChild Controller Key-Value Observing Compliance NSArrayController 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 84● canInsert ● canInsertChild ● canRemove ● canSelectNext ● canSelectPrevious ● content ● isEditable ● preservesSelection ● selectedObjects ● selection ● selectionIndexPath ● selectionIndexPaths ● selectsInsertedObjects ● sortDescriptors Note: The value returned by NSTreeController's arrangedObjects method is opaque. You should only observe this property to determine that a change has occurred. Controller Key-Value Observing Compliance NSTreeController 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 85Applications that use Cocoa bindings can provide a challenge when attempting to troubleshoot problems. This article outlines some of the common issues encountered in applications that use Cocoa bindings and provides clues as to correcting the problem. My collection controller isn’t displaying the current data This is typically due to your application modifying the collection content in a manner that is not key-value-observing compliant. Modifying an array using addObject: or removeObject: is not sufficient. You must either implement the indexed accessors for the collection key in your model class, or ask the model for a key-value-observing aware collection proxy using one of the following methods: - (NSMutableArray *)mutableArrayValueForKey:(NSString *)key - (NSMutableArray *)mutableArrayValueForKeyPath:(NSString *)keyPath - (NSMutableSet *)mutableSetValueForKey:(NSString *)key - (NSMutableSet *)mutableSetValueForKeyPath:(NSString *)keyPath These return collection proxy objectsthat you can then use with the NSMutableArray or NSMutableSet mutation methods, and the appropriate key-value observing notifications are sent. You can also modify the contents through the collection controller using the methods described in "Programmatically Modifying a Controller’s Contents" (page 41). Changing the value in the user interface programmatically is not reflected in the model If you change the value of an item in the user interface programmatically, for example sending an NSTextField a setStringValue: message, the model is not updated with the new value. This is the expected behavior. Instead you should change the model object using a key-value-observing compliant manner. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 86 Troubleshooting Cocoa BindingsChanging the value of a model property programmatically is not reflected in the user interface If changes made to a model value programmatically are not being reflected in the user interface, this typically indicatesthat the model object is not key-value-observing compliant for the property, or that you are modifying the value in a manner that is bypassing key-value observing. You should ensure that: ● The model class has automatic key-value observing enabled or implements manual key-value observing for the property. ● That you are changing the value using an accessor method, or using a key-value-coding compliant method. Changing the value of an instance variable directly does not provide key-value observing change notifications. ● If your model property is a collection, that you're modifying the content in a key-value-observing compliant manner. See "My collection controller isn’t displaying the current data" (page 86) for more information. Binding to the incorrect key path A common source of problems when using bindings is that a binding is established to the wrong key path. It is easy to missthe debug messagesin the run log or console when the application doesn’t behave as expected. The following is an example of a debug message that is output to the run log or console: 2005-05-10 03:53:29.764 VuesActivity[2216] *** NSRunLoop ignoring exception '[ valueForUndefinedKey:]: this class is not key value coding-compliant for the key named.' that raised during posting of delayed perform with target 37f6d0 and selector 'invokeWithTarget:' This message indicates that the instance of the Member class is not key-value-coding compliant for the key "named". In this case the error is that the correct Member key is in fact "name". You can get more information about an error by setting the bindings debug level default. This can be done on the command line as follows: defaults write com.yourdomain.yourapplication NSBindingDebugLogLevel 1 You can also set the debugging level in Xcode: 1. Select the application executable in the Executables group. Troubleshooting Cocoa Bindings Changing the value of a model property programmatically is not reflected in the user interface 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 872. Choose the Get Info menu item in the File menu. 3. Select the Arguments tab in the executables info panel. 4. Add -NSBindingDebugLogLevel 1 to the “Arguments to be passed at launch” list. Aftersetting the debug level default, the same problem that generated the above error message now generates the following error: 2005-05-10 04:02:32.146 VuesActivity[2241] Cocoa Bindings: Error accessing value for key path selection.named of object [object class: Member, number of selected objects: 1] (from bound object ): [ valueForUndefinedKey:]: this class is not key value coding-compliant for the key named. This provides more information that can aid you in tracking down which item in Interface Builder has been bound to the wrong key path. In this case it indicates that the binding is between an NSTextField and an NSArrayController with an object class of Member, using the selection.named key path. With the binding debug level set to 1, any binding made to a non-existent key will cause a debug message to be printed to the console, even if the binding has disabled the “Raises For Not Applicable Keys” option. Currently only a debug level of 1 is supported. Note: The bindings error messages are logged after the exception is raised. If your application is set to break on [NSException raise] you will not see the error message in the run log or gdb. Be sure to check your .gdbinit file for a breakpoint if you still do not see the bindings error messages. The bindings of my custom view are disabled in Interface Builder If you implement a subclass of NSView and create an Interface Builder palette for that subclass, your subclass’ implementation of bind:toObject:withKeyPath:options: must call the super implementation. If you don’t when you establish a binding in Interface Builder, the binding values disappear and the binding names become disabled and uneditable. Troubleshooting Cocoa Bindings The bindings of my custom view are disabled in Interface Builder 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 88An uneditable/visible/disabled NSTextField becomes editable/hidden/enabled If you disable editing for an NSTextField in Interface Builder, and then establish a binding to it, you may find that the field then becomes editable when your application isrunning. Thisistypically due to the value binding having the “Conditionally Sets Editable” binding option enabled. Similarly, if a control becomes hidden or enabled, you should check that the “Conditionally Sets Hidden” and “Conditionally Sets Enabled” options of the value binding have the expected settings. Binding a control to a value that is an unsigned int causes an exception Key-value coding handlesthe conversion of NSNumbers and NSValuesto some well-known scalar and structure types, but unsigned int is not currently supported. In the context of bindings, you should consider transforming the value using an NSValueTransformer, or in the specific case of NSTextField, NSFormatter. The view bound to an NSTreeController is not displaying data This is often caused because the NSTreeController’s children key path has not been set. You can verify that this is the cause by checking the console or run log for debug messages. See "Traversing Tree Content with an NSTreeController" (page 39) for more information. 2005-06-23 02:46:53.198 MyApplication[6777] Cocoa Bindings: Cannot perform operation if childrenKeyPath is nil. A table column containing NSPopUpButtonCell itemsis notsortable Tableview columns that contain NSPopUpButtonCell, or any cell type other than NSTextField can’t be sorted if the cell’s selection is bound using the selectedObject or selectedObjects bindings. If the selection is bound to selectedValue, selectedTag or selectedIndex, the column is sortable. Troubleshooting Cocoa Bindings An uneditable/visible/disabled NSTextField becomes editable/hidden/enabled 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 89This table describes the changes to Cocoa Bindings Programming Topics. Date Notes Added warning about lack of key-value observing change values to Controller Key-Value Observing Compliance. 2009-03-08 2007-05-22 Clarified why you would use a controller. 2006-07-24 Corrected minor typos. 2006-06-28 Updated the prerequisite section in the introduction. 2006-05-23 Clarified Figure 3 in "Bindings Message Flow." Corrected the NSBindingDebugLogLevel flag in the "Troubleshooting Cocoa Bindings." 2006-03-08 Added "Controller Key-Value Observing Compliance " article. Added additional troubleshooting information. Corrected minor typos. 2005-08-11 Added four new articles on controller content, controller selection, message flow between model-view-controller, and troubleshooting Cocoa bindings. Made other minor changes. 2005-07-07 Corrected minor typo. Added retain to example code in "How Do Bindings Work?". 2005-04-29 2004-08-31 Corrected minor typos. 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 90 Document Revision HistoryDate Notes This version represents a major revision of Cocoa Bindings. "What Are Cocoa Bindings?" (page 10) and "How Do Bindings Work?" (page 23) replace the “Why Use Cocoa Bindings?” and “Support for the MVC Paradigm” articles. The “How to Use Bindings” article was removed. "User Defaults and Bindings" (page 61) was added to the topic. "Filtering Using a Custom Array Controller" (page 81) was edited to remove model dependencies. “Example: Currency Converter With Bindings” was moved to a separate book Developing Cocoa Applications Using Bindings: A Tutorial . “Example: Enhanced Currency Converter” and “Example:Preferences Pane” were removed from the topic. 2004-04-20 Added a link to Cocoa Bindings Reference from "Introduction to Cocoa Bindings Programming Topics" (page 7). Corrected a bug in "Filtering Using a Custom Array Controller" (page 81) that caused the NSSearchField to loose focus. 2004-02-22 Renamed to Cocoa Bindings from Controller Layer. Made minor edits to “Supporting the MVC Paradigm” and “Object Modeling”. Revised “Core Classes and Protocols” and renamed it “How to Use Bindings”. Added four new articles on how to create a master-detail interface, display images using bindings, use pop-up menus to represent to-one relationships, and filter an array controller’s arranged objects. 2003-12-16 Renamed to Controller Layer from The Cocoa Controller Layer. Revised and reorganized all the conceptual articles in this topic. Enhanced the tutorials by numbering the steps, adding a Converter model, and fixing other errors. 2003-10-14 2003-08-07 First version of The Cocoa Controller Layer. Document Revision History 2009-03-08 | © 2003, 2009 Apple Inc. All Rights Reserved. 91Apple Inc. © 2003, 2009 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, Numbers, Objective-C, OS X, and Xcode 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. Document-Based App Programming Guide for iOSContents About Document-Based Applications in iOS 6 At a Glance 7 Document Objects Are Model Controllers 7 When Designing an Application, Consider Document-Data Format and Other Issues 7 Creating a Subclass of UIDocument Requires Two Method Overrides 7 An Application Manages a Document Through Its Life Cycle 7 An Application Stores Document Files in iCloud Upon User Request 8 An Application Ensures That Document Data is Saved Automatically 8 An Application Resolves Conflicts Between Different Document Versions 8 How to Use This Document 8 Prerequisites 9 See Also 9 Designing a Document-Based Application 10 Why Create a Document-Based Application? 10 A Document in iOS 11 A Document in iCloud Storage 12 Properties of a UIDocument Object 12 Design Considerations for Document-Based Applications 13 Defining Object Relationships 13 Designing the User Interface 14 Choosing Types, Formats, and Strategies for Document Data 15 Document-Based Application Preflight 18 What You Must Do to Make a Document-Based Application 18 Creating and Configuring the Project 19 How iOS Identifies Your Application’s Documents 20 Declare a Document Type 20 Exporting the Document UTI 22 Creating a Custom Document Object 23 Declaring the Document Class Interface 23 Loading Document Data 24 Supplying a Snapshot of Document Data 26 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Storing Document Data in a File Package 27 Other Method Overrides You Might Make 28 Managing the Life Cycle of a Document 30 Setting the Preferred Storage Location for Document Files 30 Creating a New Document 31 Document Filename Versus Document Name 31 Composing the File URL and Saving the Document File 31 Opening and Closing a Document 33 Discovering an Application’s Documents 33 Downloading Document Files from iCloud 36 Opening a Document 36 Closing a Document 38 Moving Documents to and from iCloud Storage 39 Getting the Location of the iCloud Container Directory 39 Moving a Document to iCloud Storage 40 Removing a Document from iCloud Storage 42 Monitoring Document-State Changes and Handling Errors 43 Deleting a Document 45 Change Tracking and Undo Operations 48 How UIKit Saves Document Data Automatically 48 Implementing Undo and Redo 48 Implementing Change Tracking 50 Resolving Document Version Conflicts 51 Learning About Document Version Conflicts 51 Strategies for Resolving Document Version Conflicts 51 How to Tell iOS That a Document Version Conflict Is Resolved 52 An Example: Letting the User Pick the Version 53 Document Revision History 56 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsFigures, Tables, and Listings Designing a Document-Based Application 10 Figure 1-1 Document file, document object, and model objects managed by the document object 12 Figure 1-2 A view controller manages both a document object and the view that presents document data 14 Document-Based Application Preflight 18 Figure 2-1 iOS looking up a document UTI from the extension of its file URL 20 Figure 2-2 Specification of a document type in Xcode 21 Figure 2-3 Exporting a custom document UTI in Xcode 22 Table 2-1 Properties for defining a document type (CFBundleDocumentTypes) 21 Table 2-2 Properties for exporting a document UTI (UTExportedTypeDeclarations) 22 Creating a Custom Document Object 23 Figure 3-1 Structure of a file package 27 Listing 3-1 Document subclass declarations (NSData) 23 Listing 3-2 Document subclass declarations (NSFileWrapper) 24 Listing 3-3 Loading a document’s data (NSData) 25 Listing 3-4 Loading a document’s data (NSFileWrapper) 25 Listing 3-5 Returning a snapshot of document data (NSData) 26 Listing 3-6 Returning a snapshot of document data (NSFileWrapper) 26 Managing the Life Cycle of a Document 30 Table 4-1 UIDocumentState constants 43 Listing 4-1 Getting a URL to the application’s Documents directory in the local sandbox 32 Listing 4-2 Saving a new document to the file system 32 Listing 4-3 Getting the locations of documents stored locally and in iCloud storage 34 Listing 4-4 Collecting information about documents in iCloud storage 35 Listing 4-5 Responding to a request to open a document 37 Listing 4-6 Opening a document 38 Listing 4-7 Closing a document 39 Listing 4-8 Getting the iCloud container directory URL 40 Listing 4-9 Moving a document file to iCloud storage from local storage 41 Listing 4-10 Moving a document file from iCloud storage to local storage 42 Listing 4-11 Adding an observer of the UIDocumentStateChangedNotification notification 43 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4Listing 4-12 Evaluating the current document state 44 Listing 4-13 Updating a document’s user interface to reflect its state 45 Listing 4-14 Deleting a selected document 46 Change Tracking and Undo Operations 48 Listing 5-1 Implementing undo and redo for a text field 49 Listing 5-2 Updating the change count of a document 50 Resolving Document Version Conflicts 51 Listing 6-1 Detecting a conflict in document versions 53 Listing 6-2 Showing the user interface for resolving document version conflicts 54 Listing 6-3 Resolving a document version conflict 54 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5 Figures, Tables, and ListingsThe UIKit framework offers support for applications that manage multiple documents, with each document containing a unique set of data that is stored in a file located either in the application sandbox or in iCloud. iCloud Daemon iCloud Daemon Central to this support is the UIDocument class, introduced in iOS 5.0. A document-based application must create a subclass of UIDocument that loads document data into its in-memory data structures and supplies UIDocument with the data to write to the document file. UIDocument takes care of many details related to document management for you. Besides its integration with iCloud, UIDocument reads and writes document data in the background so that your application’s user interface does not become unresponsive during these operations. It also saves document data automatically and periodically, freeing your users from the need to explicitly save. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6 About Document-Based Applications in iOSAt a Glance Although a document-based application is responsible for a range of behaviors, making an application document-based is usually not a difficult task. Document Objects Are Model Controllers In the Model-View-Controller design pattern, document objects—that is, instances of subclasses of UIDocument—are model controllers. A document object manages the data associated with a document, specifically the model objects that internally represent what the user is viewing and editing. A document object, in turn, is typically managed by a view controller that presents a document to users. Relevant Chapter: “Designing a Document-Based Application” (page 10) When Designing an Application, Consider Document-Data Format and Other Issues Before you write a line of code you should consider aspects of design specific to document-based applications. Most importantly, what is the best format of document data for your application, and how can you make that format work for your application in iOS and Mac OS X? What is the most appropriate document type? You also need to plan for the view controllers(and views) managing such tasks as opening documents, indicating errors, and moving selected documents to and from iCloud storage. Relevant Chapters: “Designing a Document-Based Application” (page 10), “Document-Based Application Preflight” (page 18) Creating a Subclass of UIDocument Requires Two Method Overrides The primary role of a document object is to be the “conduit” of data between a document file and the model objects that internally represent document data. It gives the UIDocument class the data to write to the document file and, after the document file isread, it initializesits model objects with the data that UIDocument givesit. To fulfill thisrole, yoursubclass of UIDocument must override the contentsForType:error: method and the loadFromContents:ofType:error: method, respectively. Relevant Chapter: “Creating a Custom Document Object” (page 23) An Application Manages a Document Through Its Life Cycle An application is responsible for managing the following events during a document’s lifetime: ● Creation of the document ● Opening and closing the document About Document-Based Applications in iOS At a Glance 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7● Monitoring changes in document state and responding to errors or version conflicts ● Moving documents to iCloud storage (and removing them from iCloud storage) ● Deletion of the document Relevant Chapter: “Managing the Life Cycle of a Document” (page 30) An Application Stores Document Files in iCloud Upon User Request Applications give their users the option for putting all document files in iCloud storage or all document files in the local sandbox. To move document files to iCloud, they compose a file URL locating the document in an iCloud container directory of the application and then call a specific method of the NSFileManager class, passing in the file URL. Moving document filesfrom iCloud storage to the application sandbox follows a similar procedure. Relevant Chapter: “Managing the Life Cycle of a Document” (page 30) An Application Ensures That Document Data is Saved Automatically UIDocument follows the saveless model and automatically saves a document’s data at specific intervals. A user usually never has to save a document explicitly. However, your application must play its part in order for the saveless model to work, either by implementing undo and redo or by tracking changes to the document. Relevant Chapter: “Change Tracking and Undo Operations” (page 48) An Application Resolves Conflicts Between Different Document Versions When documents are stored in iCloud, conflicts between versions of a document can occur. When a conflict occurs, UIKit informs the application about it. The application must attempt to resolve the conflict itself or invite the user to pick the version he or she prefers. Relevant Chapter: “Resolving Document Version Conflicts” (page 51) How to Use This Document Before you start writing any code for your document-based application, you should at least read the first two chapters, “Designing a Document-Based Application” (page 10) and “Document-Based Application Preflight” (page 18). These chapters talk about design and configuration issues, and give you an overview of the tasks required for well-designed document-based applications About Document-Based Applications in iOS How to Use This Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8Prerequisites Before you read Document-Based Application Programming Guide for iOS you should become familiar with the information presented in iOS App Programming Guide . See Also The following documents are related in some way to Document-Based Application Programming Guide for iOS : ● Uniform Type Identifiers Overview and the related reference discuss Uniform Type Identifiers (UTIs), which are the primary identifiers of document types. ● FileMetadataSearchProgrammingGuide describeshowtoconductsearchesusingtheNSMetadataQuery class and related classes. You use metadata queries to locate an application’s documents stored in iCloud. ● iCloud Design Guide provides an introduction to iCloud document support. About Document-Based Applications in iOS Prerequisites 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9The UIDocument class, introduced in iOS 5.0, plays the principal role in document-based applications for iOS. It is an abstract base class—meaning that for you to have something useful, you must create a subclass of it that is tailored to the needs of your application. The application-specific code that you add to the subclass augments what UIDocument makes possible: efficient behavior of documents in a mobile environment integrated with iCloud storage. Why Create a Document-Based Application? When you have an idea for any application and sit down to design it, you must evaluate a multitude of options. What style of application should you use (master-detail, page-based utility, OpenGL game, and so on)? Will the application do its own drawing, will it respond to gestures or touch events, and will it incorporate audiovisual assets? What will the data model be—for example, should the application use Core Data? The decision whether to make your application document-based might seem to complicate that series of choices, but it really boils down to how you anticipate people will use your application. Document-based applications are ideal, even necessary, when users expect to enter and edit content in a visual container and store that content under a name they specify. Each container of information—a document—is unique. You are no doubt familiar with several types of document-based applications found in both desktop and mobile systems. To name a few, there are word processors, spreadsheets, and drawing programs. With the iCloud technology, you have an even more compelling reason to make your application document-based. Your users, for example, could create a document using your application on a OS X desktop system and then later, without having to do any syncing or copying, edit that document on an iPad using the iOS version of your application. This feature gives them an additional incentive to buy your application. When you adopt the UIDocument approach to document-based applications, your application gets a lot of behavior “for free” or with minimal coding effort on your part. ● Integration with iCloud storage. The UIDocument object coordinates all reading and writing of document data from and to iCloud storage. It does this by adopting the NSFilePresenter protocol and by calling methods of the NSFileCoordinator and NSFileManager classes. ● Background writing and reading of document data. If your application reads and writes a document synchronously, it can become momentarily unresponsive. The UIDocument object avoids this problem by reading and writing document data asynchronously on a background dispatch queue. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10 Designing a Document-Based Application● Savelessmodel. In the saveless model, a user of a document-based application rarely hasto save documents explicitly; The UIDocument object saves document data automatically at intervals optimized for what the user is doing with the document. You make your document-based application “saveless” by implementing undo management or change tracking (see “Change Tracking and Undo Operations” (page 48) for information). ● Safe saving. The UIDocument object saves document data safely; consequently, if some external event interrupts a save operation, document data won’t be left in an inconsistent state. The object implements safe saving by first writing the newest version of a document to a temporary file and then replacing the current document file with it. ● Support for handling errors and version conflicts. When the UIDocument object detects a conflict between different versions of a document, it notifies the application. The application can then attempt to resolve the conflict itself, or it can ask the user to pick the desired document version. The UIDocument object also notifies an application when a save operation does not succeed. “Managing the Life Cycle of a Document” (page 30) describes how to observe these notifications; “Resolving Document Version Conflicts” (page 51) discusses strategies for dealing with document-version conflicts. A Document in iOS Although the broad definition of a document is a “container of information,” that container can be viewed in several ways. To a user, a document is the text, images, shapes, and other forms of information that he or she creates, edits, and saves under a unique name. A document can also refer to a document file: the persistent, on-disk representation of document data. And a document can mean a UIDocument object that represents and manages the in-memory representation of that same data. A document object also plays a key role in converting document data between its representation on disk to its representation in memory. It cooperates with the UIDocument class in the writing of document data to a file and the reading of that data. For writing, a document typically provides a snapshot of data that can be Designing a Document-Based Application A Document in iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11written to the document file; for reading, it receives data and initializes the document’s model objects with it. A document, in a sense, is a conduit between data stored in a file and the internal representation of that data. Figure 1-1 illustrates these relationships. Figure 1-1 Document file, document object, and model objects managed by the document object Document Model Model Model Model Document File A Document in iCloud Storage In iCloud, files reside locally in a container directory that is associated with an application. That directory has an internal structure that includes, most importantly, a Documents subdirectory. In the iCloud scheme, files and file packages written to the Documents subdirectory are considered document files—even if they don’t originate from document-based applications. Filesthat are written to other locationsin the container directory are considered data files. Document objects are file presenters because the UIDocument class adopts the NSFilePresenter protocol. A file presenter is used together with NSFileCoordinator objects to coordinate access to a file or directory among the objects of an application and between an application and other processes. A file presenter is involved in other clients’ access of the same presented file or directory. When users ask to store document files in iCloud storage, a document-based application should save those files (including file packages) in the Documents subdirectory of the iCloud container directory. See “Managing the Life Cycle of a Document” (page 30) for specifics. For more information about iCloud mobile containers, see iCloud Design Guide . Properties of a UIDocument Object A document object has several defining properties, most of which relate to its role as a manager of document data. These properties are declared by the UIDocument class. Designing a Document-Based Application A Document in iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12● File URL. A document must have a location where it can be stored, whether that location is in the local file system or in iCloud storage. The fileURL property identifies this location. When you create a UIDocument object, you must specify a file URL as the parameter of the initWithFileURL: initializer method of UIDocument. ● Document name. A UIDocument object obtains a default document name from the filename component of the file URL and stores it in the localizedName property. You can override the getter method of this property to provide a custom, localized document name. Note: The display name of a document does not have to correspond to the filename of the document. In addition, usersshould not be required to specify a document name. See “Creating a New Document” (page 31) for more information on this subject. ● File type. The file type is a Uniform Type Identifier (UTI) derived from the extension of the file URL and assigned to the fileType property. For more information, see “How iOS Identifies Your Application’s Documents” (page 20). ● Modification date. The date the document file was last modified. This value is stored in the fileModificationDate property. It can be use for (among other things) resolving document-version conflicts. ● Document state. A document is in one of several possible states during its runtime life. These states can indicate, for example, that there was an error in saving the document or that there are conflicting document versions. UIDocument storesthe current documentstate in the documentState property. For information about observing changes in document state, see “Monitoring Document-State Changes and Handling Errors” (page 43). Design Considerations for Document-Based Applications Before you write a line of code for your document-based application, it’s worth your while to think about a few design issues. Defining Object Relationships As with all applications, you should devise an overall design for the objects of your document-based application that is based on the Model-View-Controller design pattern (MVC). Although the following MVC design for documents is recommended, you are free to come up with your own object-relationship designs. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13In MVC terms, a document is a model controller; it “owns” and manages the model objects that represent the document’s content. The document object itself is owned and managed by a view controller. The view controller, by definition, also manages a view that presents the content managed by the document object. It is thus a mediating controller in this network of relationships, obtaining the data it needs to present in the view from the document object and passing data entered or changed by usersto the document object. Figure 1-2 depicts these object relationships. Figure 1-2 A view controller manages both a document object and the view that presents document data Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. manages manages View controller Document Model Model Model Just as a view controller embeds its view, a view controller might embed the document object as a declared property. When your application instantiates the view controller, it initializes it with the document object or with the document’s file URL (from which the view controller itself can create the document object). Of course, a document-based application will have other view controllers (with their views) and possibly other model objects. To get an idea of what other view controllers might be required, see “Designing the User Interface” (page 14). Designing the User Interface Neither UIKit nor the developer tools provide any support for the user interface of a document-based application. For instance, there is no UIDocumentView class or UIDocumentViewController class and there is no standard interface for selecting documents. Rather than regret the absence, take it as an opportunity to create a user interface for your document-based application that makes it stand out from the competition. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14Nonetheless, all document-based applications should enable their users to do certain things that require user interface elements; these include the following: ● Viewing and editing a document ● Creating a new document ● Selecting a document from a list of documents owned by the application ● Opening, closing, and deleting a selected document ● Putting a selected document in iCloud storage (and removing a selected document from iCloud storage) ● Indicating error conditions, including document-version conflicts ● Undoing and redoing changes (recommended but not required) When you design your application, be sure to include the view controllers, views, and controlsthat are necessary to implement these actions. Choosing Types, Formats, and Strategies for Document Data When designing the data model for your document-based application, it’s critical that you ask and answer the following questions: What is the type of my document? A document must have a document type, a collection of information that characterizes the document and associatesit with an application. A document type has a name, an icon (optional), a handler rank, and a Uniform Type Identifier (UTI) that is paired with one or more filename extensions. For an application to edit the same document in iOS and in OS X, the document-type information should be consistent. “Creating and Configuring the Project” (page 19) explains how to specify document typesin a document-based iOS application. See Uniform Type Identifiers Overview for a description of UTIs and Uniform Type Identifiers Reference for descriptions of common Uniform Type Identifiers. How should I represent the document data that is written to a file? You have basically three choices: ● Core Data (database). Core Data is a technology and framework for object-graph management and persistence. It can use the built-in SQLite data library as a database system. The UIManagedDocument class, a subclass of UIDocument, is intended for document-based applications that use Core Data. ● Supported object formats. UIDocument supports the NSData and NSFileWrapper objects as native typesfor document-data representation. NSData isintended for flat files, and NSFileWrapper isintended for file packages, which are directories that iOS treats as a single file. If you give UIDocument one of these objects, it saves it to the file system without further involvement on your part. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15● Custom object formats. If you want the document data written to a file to be of a type other than NSData or NSFileWrapper, you can write it to the file yourself in an override of a specific UIDocument method. Keep in mind that your code will have to duplicate what UIDocument does for you, and so you must deal with greater complexity and a greater possibility of error. See UIDocument Class Reference for further information. Why would I want to store my document data in a database instead of a file? If the data set managed by your document object is primarily a large object graph but your application uses only a subsection of that graph at any time, then UIManagedDocument and Core Data are a good option. Core Data brings many benefits to a document-based application: ● Incremental reading and writing of document data ● Support for undo and redo operations ● Automatic support for resolving document-version conflicts ● Data compatibility for cross-platform applications The “downside” to Core Data isthat it is a complex technology; it takestime to become familiar with its concepts, classes, and techniques. To learn more, read Core Data Programming Guide and UIManagedDocument Class Reference . Which of the supported object formats (NSData or NSFileWrapper) is best for my application? Whether you use an NSData or NSFileWrapper object for document data depends on how complex that data is and on whether part of your document’s model-object graph can be written out separately to a file. For example, if your document data is plain text and nothing else, then NSData is a suitable container for it. If, however, the data has multiple components—for example, text and images—use NSFileWrapper methods to create a file package for the data. File wrapper objects—and file packages which they represent—offersome advantages over binary data objects. ● File wrappers support incremental saving. In contrast with a single binary data object, if a file wrapper contains your document data—for example, text and an image—and the text changes, only the file containing the text has to be written out to disk. This capability results in better performance. ● File wrappers (and file packages) make it easier to version documents. A file package, for example, can contain a property list file that holds version information and other metadata about a document. “Storing Document Data in a File Package” (page 27) discusses(and illustrates) how you use an NSFileWrapper object to represent document data in a form that can be written out as a file package. Can I archive my model-object graph and have that NSData object written to the document file? Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16Yes, that is possible, but some of the caveats previously mentioned apply. If any part of your document’s model-object graph can be written to a separate file, don’t archive that part. Instead, store the NSData archive and the partitioned-out items as separate components of a file package. What if my document file is very large? If the data stored in a document file can be large, you might have to write and read the data incrementally to ensure a good user experience. There are a few approaches you might take: ● Use UIManagedDocument. Remember, Core Data gives you incremental reading and writing “for free.” ● Store the separable components of your document data in a file package. ● Override lower-level methods of UIDocument and do the incremental reading and writing of data yourself. (See UIDocument Class Reference for particulars.) You should always use an API for incremental reading and writing that is appropriate to the data type; for example, the AV Foundation framework has methods for incremental reading of large multimedia files. What should I be thinking about if I want my documents to be editable on both platforms? Your application will have a competitive advantage if your users can create and edit documents both on iOS mobile devices (iPhone, iPad, and iPad touch) and on OS X desktop systems. But for this to be possible, the format of the document data on both platforms should be compatible. Some important considerations for document-data compatibility are: ● Some technologies are available on one platform but not the other. For example, if you’re using RTF as a document format in OS X, that format won’t work in iOS because its text system doesn’t support rich text. ● The corresponding classesin each platform are not compatible. Thisis especially true with colors(UIColor and NSColor), images (UIImage and NSImage), and Bezier paths (UIBezierPath and NSBezierPath). NSColor objects, for example, are defined in terms of a color space (NSColorSpace), but there is no color space class in UIKit. If you define a document property with one of these classes, you must devise a way (when preparing the document data for writing) to convert the property into a form that can be accurately reconstituted on the other platform. One way to do this is to “drop down” to a lower-level framework that is shared by both platforms. For example, UIColor defines a CIColor property holding a Core Image object representing the color; on the OS X side, your application can create an NSColor object from the CIColor object using the colorWithCIColor: class method. ● The default coordinate system for each platform is different, and this difference can affect how content is drawn. (See “Default Coordinate Systems and Drawing in iOS” in Drawing and Printing Guide for iOS for a discussion of this topic). ● If you archive a document’s model-object graph, partially or entirely, then you might have to perform platform-sensitive conversions using NSCoder methods when you encode and decode the model objects. Designing a Document-Based Application Design Considerations for Document-Based Applications 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17For most developers, making a document-based application doesn’t require much more effort than making an application that isn’t document based. The basic difference is that you must create a custom subclass of UIDocument and then manage a document through the phases of its runtime life, including its integration with iCloud storage. This chapter outlines those document-specific tasks performed by most applications and describes the general steps for creating and configuring a document-based application project in iOS. What You Must Do to Make a Document-Based Application To create a document-based application, you should complete the following tasks: ● Create a custom subclass of UIDocument that provides the UIKit framework with a snapshot of document data and that initializes the document’s model objects from the contents of the document file. “Creating a Custom Document Object” (page 23) describesthe required method overrides and, if document data isto be stored as a file package, explains how to go about using NSFileWrapper objectsfor document data. ● Allow users to create new documents and select and open existing ones. You should also implement the complementary tasks of closing documents and deleting selected documents. Note that the follow-on task to creating or opening a document is displaying the document’s content in a view. “Creating a New Document” (page 31), “Opening and Closing a Document” (page 33), and “Deleting a Document” (page 45) describe the requirements and procedures for these tasks. These discussions also include examples of managing the display of document data. ● Implement undo management or change tracking to enable the automatic saving of document data (saveless model). See “Change Tracking and Undo Operations” (page 48) for details. ● Put documents—typically those selected by users—into iCloud storage. Also remove documents from iCloud storage when users request this. “Moving Documents to and from iCloud Storage” (page 39) discusses these procedures. ● Observe notifications of changes in document state and, if an error occurs, respond appropriately. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18 Document-Based Application Preflight“Monitoring Document-State Changes and Handling Errors” (page 43) describes the general procedure for doing this. ● If conflicts between different versions of a document occur, notify the user and offer ways to resolve the conflicts. “Resolving Document Version Conflicts” (page 51) describes how to notify users of version conflicts and discusses strategies for resolving these conflicts. You can also add extra features to your document-based application, such as the capability for printing the document, spell-checking it, or emailing it to others. If your application has advanced requirements—for example, incremental reading and writing of large document files or dealing with document-data formats other than the supported ones—see UIDocument Class Reference . All of these advanced tasks involve overriding UIDocument methods. Creating and Configuring the Project When you create the Xcode project for your document-based application, choose a suitable template. (Note that there is no template specifically for document-based applications.) Generally, you want the first view of the application to be one in which users can choose existing documents and create new ones. Because the Master-Detail Xcode template is suitable for this purpose, it is used in the code examples throughout this document. Thistemplate gives you an initial table view for the iPhone and a split view for the iPad. Your project should use a storyboard, so be sure to select this option. Note: If you are using Core Data to manage document data, be sure to select the “Use Core Data” option in the New Project assistant. Based on the design for your application (see “Designing a Document-Based Application” (page 10)), create the view-controller subclasses that your application requires. All you need are minimally declared header and source files at this point. Then, create the user interface of your application in the project storyboard (or storyboards, if yours is a universal application); associate your custom view controllers with the view-controller placeholders in the storyboard. Next, you need to configure the project for documents by specifying, in the Xcode target settings, the type or types of the documents that the application knows about. Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19How iOS Identifies Your Application’s Documents The most important attribute of a document object in iOS is its file URL (fileURL). The file URL is important, among other reasons, because it tells iOS which applications understand the document’s format. The file URL ends with an extension (for example, html) and this extension is matched with a Uniform Type Identifier (for example, public.html). The Uniform Type Identifier (UTI) is the principal identifier of document type. Using the extension, UIDocument looks up the document-type UTI (as shown in Figure 2-1) and assigns it to the fileType property. Unlike document-based applications in OSX, those in iOS don’t need to associate the UIDocument subclass with the document type. Figure 2-1 iOS looking up a document UTI from the extension of its file URL File /Documents/foo.mydoc Application File System Document fileURL CFBundleDocumentTypes (Document Type 1) CFBundleTypeExtensions mydoc LSItemContentTypes com.acme.app.mydoc ... A document-type UTI can be defined by the system; see “System-Declared Uniform Type Identifiers” in Uniform Type Identifiers Reference for a list of these common identifiers. A document-based application can also define its own proprietary UTI for its documents (and often does). If it does declare a custom UTI, it must also export that UTI to make the operating system aware of it. Declare a Document Type To declare a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Document Type from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-1. Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20Table 2-1 Properties for defining a document type (CFBundleDocumentTypes) Key Xcode field Value and comments An array of UTIstrings. Only one istypically specified per document type. LSItemContentTypes Types CFBundleTypeName Name An optional name for the document type. An array of paths to icon image files in the application bundle. CFBundleType- Icon IconFiles An array of filename extensions paired with the document UTI. In “Additional document type properties” table. CFBundleTypeExtensions Owner, Alternate, None. (Typically Owner). In “Additional document type properties” table. LSHandlerRank If document data isstored in a file package, set this property to YES. Otherwise omit. In “Additional document type properties” table. LSTypeIsPackage Formore information aboutthese keys,see “CFBundleDocumentTypes” in Information Property List Key Reference . When you have finished entering the properties for a document type, The Document Types area of Xcode should look similar to the example in Figure 2-2. Figure 2-2 Specification of a document type in Xcode An application could have multiple types of documents—for example, a word-processing application could have a type for regular (blank) documents and another type for pre-formatted documents. For each type, you need to go through the procedure given above . Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21Exporting the Document UTI If you define a custom UTI for your documents, you must also export it. To export a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Exported UTI from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-2. Note: The procedure for declaring and exporting UTIs is described in “Declaring New Uniform Type Identifiers” in Uniform Type Identifiers Overview. Table 2-2 Properties for exporting a document UTI (UTExportedTypeDeclarations) Key Xcode field Value and comments UITypeIdentifier Identifier The custom document UTI, a string. The UTI that the custom document UTI conforms to. If the data representation is a file package, specify com.apple.package. UTTypeConformsTo Conforms to UTTypeDescription Description Description of the exported type (optional). Create an array named public.filename-extension. Then add as items all extensions of the document file. In “Additional exported UTI properties” table. UTTypeTagSpecification Formore information aboutthese keys,see “CFBundleDocumentTypes” in Information Property List Key Reference . When you have finished entering the properties for a document type, The Exported UTIs area of Xcode should look similar to the example in Figure 2-3. Figure 2-3 Exporting a custom document UTI in Xcode Document-Based Application Preflight Creating and Configuring the Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22A document-based application must have an instance of a subclass of UIDocument that represents and manages document data. This chapter discusses the method overrides most applications need to make and offers suggestions for overriding other methods. For the core override points—the loadFromContents:ofType:error: and contentsForType:error: methods—examples are given for both NSData and NSFileWrapper astypes of document data read from and written to a file.“Storing Document Data in a File Package” (page 27) further explains how to use file-wrapper objects for document data. You can override methods of UIDocument other than the ones discussed in this chapter to read and write document data for particular purposes—for example, to write and read document data incrementally. However, these more advanced overrides have more complex requirements and should be avoided if possible. See UIDocument Class Reference for discussions of these overrides. Declaring the Document Class Interface In Xcode, add new Objective-C source and header files to your project, naming them appropriately (suggestion: work “Document” into the name). In the header file, change the superclass to UIDocument and add properties to hold the document data. In Listing 3-1, the document data is plain text, so an NSString property is all that is needed to hold it. (The text will be converted to an NSData object that is written to the document file.) Listing 3-1 Document subclass declarations (NSData) @interface MyDocument : UIDocument { } @property(nonatomic, strong) NSString *documentText; @end Listing 3-2 illustrates set of declarations for another application that uses an NSFileWrapper object as the data-representation type. (The code examples in the chapter alternate between the two applications.) Not only is there a property to hold the file-wrapper object, there are properties to hold the text and image components of the represented file package. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23 Creating a Custom Document ObjectListing 3-2 Document subclass declarations (NSFileWrapper) @interface ImageNotesDocument : UIDocument @property (nonatomic, strong) NSString* text; @property (nonatomic, strong) UIImage* image; @property (nonatomic, strong) NSFileWrapper *fileWrapper; @property (nonatomic, weak) id delegate; @end @protocol ImageNotesDocumentDelegate -(void)noteDocumentContentsUpdated:(ImageNotesDocument*)noteDocument; @end This code shows additional declarations for a delegate and the protocol that it adopts. The document object’s view controller makes itself the delegate of the document object (and adopts the protocol) so that it can be notified (via noteDocumentContentsUpdated: messages) of modifications to the document file. Listing 3-4 (page 25) shows when and how the noteDocumentContentsUpdated: message is sent. Loading Document Data When an application opens a document (at the user’srequest), UIDocument readsthe contents of the document file and calls the loadFromContents:ofType:error: method, passing in an object encapsulating the document data. That object can be an NSData object or an NSFileWrapper object. In your override of the method, initialize the document’s internal data structures (that is, its model objects) from the contents of the passed-in object. The example in Listing 3-3 creates a string from the passed-in NSData object and assigns it to the documentText property. It also informs its delegate (in this case, the document’s view controller) of the updated document contents by invoking a protocol method. The motivation behind this delegation message isthatthe loadFromContents:ofType:error:method is called not only asthe result of opening a document, but also because of iCloud updates and reversion operations (revertToContentsOfURL:completionHandler:). Creating a Custom Document Object Loading Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Listing 3-3 Loading a document’s data (NSData) - (BOOL)loadFromContents:(id)contents ofType:(NSString *)typeName error:(NSError **)outError { if ([contents length] > 0) { self.documentText = [[NSString alloc] initWithData:(NSData *)contents encoding:NSUTF8StringEncoding]; } else { self.documentText = @""; } if ([_delegate respondsToSelector:@selector(noteDocumentContentsUpdated:)]) { [_delegate noteDocumentContentsUpdated:self]; } return YES; } If you have more than one document type, check the typeName parameter; a different document type might affect how your code handles the document-data object. If your code experiences an error that prevents it from loading document data, return NO; optionally, you can return by reference an NSError object that describes the error. The example in Listing 3-4 handles document data in the form of an NSFileWrapper object. It simply assigns this object to its property. Listing 3-4 Loading a document’s data (NSFileWrapper) -(BOOL)loadFromContents:(id)contents ofType:(NSString *)typeName error:(NSError **)outError { self.fileWrapper = (NSFileWrapper *)contents; if ([_delegate respondsToSelector:@selector(noteDocumentContentsUpdated:)]) { [_delegate noteDocumentContentsUpdated:self]; } return YES; } In this code, the method implementation does not extract the text and image components of the file wrapper and assign them to their properties. That is done lazily in the getter methodsfor the text and image properties. Creating a Custom Document Object Loading Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25Supplying a Snapshot of Document Data When a document is closed or when it is automatically saved, UIDocument sends the document object a contentsForType:error: message. You must override this method to return a snapshot of the document’s data to UIDocument, which then writes it to the document file. Listing 3-5 gives an example of returning a snapshot of document data in the form of an NSData object. Listing 3-5 Returning a snapshot of document data (NSData) - (id)contentsForType:(NSString *)typeName error:(NSError **)outError { if (!self.documentText) { self.documentText = @""; } NSData *docData = [self.documentText dataUsingEncoding:NSUTF8StringEncoding allowLossyConversion:NO]; return docData; } If the documentText property has not yet been assigned any string value yet, it is assigned an empty string before it’s used to create an NSData object. Listing 3-6 shows an implementation of the same method that returns an NSFileWrapper object. Basically, if a top-level (directory) file-wrapper object doesn’t exist, the code creates it; and if the two contained (regular file) file-wrapper objects do not exist, the code createsthem from the values of the text and image properties. Then, it returns the top-level file wrapper to UIDocument, which creates a file package in the file system. See “Storing Document Data in a File Package” (page 27) for a more detailed explanation of file packages and documents. Listing 3-6 Returning a snapshot of document data (NSFileWrapper) -(id)contentsForType:(NSString *)typeName error:(NSError **)outError { if (self.fileWrapper == nil) { self.fileWrapper = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil]; } NSDictionary *fileWrappers = [self.fileWrapper fileWrappers]; if (([fileWrappers objectForKey:TextFileName] == nil) && (self.text != nil)) { NSData *textData = [self.text dataUsingEncoding:TextFileEncoding]; Creating a Custom Document Object Supplying a Snapshot of Document Data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26NSFileWrapper *textFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:textData]; [textFileWrapper setPreferredFilename:TextFileName]; [self.fileWrapper addFileWrapper:textFileWrapper]; } if (([fileWrappers objectForKey:ImageFileName] == nil) && (self.image != nil)) { @autoreleasepool { NSData *imageData = UIImagePNGRepresentation(self.image); NSFileWrapper *imageFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:imageData]; [imageFileWrapper setPreferredFilename:ImageFileName]; [self.fileWrapper addFileWrapper:imageFileWrapper]; } } return self.fileWrapper; } Storing Document Data in a File Package A file package has an internal structure that is reflected in the methods of the NSFileWrapper class. A file wrapper is a runtime representation of a file-system node, which is either a directory, a regular file, or a symbolic link. As shown in Figure 3-1, a file package is a file-system node, typically a directory and its contents, that the operating system treats as a single, opaque entity. It is similar in concept to a bundle. Figure 3-1 Structure of a file package File File File Directory ArchivedObjects theImage.png Creating a Custom Document Object Storing Document Data in a File Package 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27You programmatically compose a file package by creating a top-level directory file wrapper and then adding to that container regular files and subdirectories, each represented by other NSFileWrapper objects. File wrappers inside the top-level directory should have preferred names associated with them. With this brief overview in mind, look again at the following lines of code from the contentsForType:error: method in Listing 3-6 (page 26). The file package created in this method has two components, a text file and an image file. (The creation of the image file wrapper is not shown in the snippet.) if (self.fileWrapper == nil) { self.fileWrapper = [[NSFileWrapper alloc] initDirectoryWithFileWrappers:nil]; } NSDictionary *fileWrappers = [self.fileWrapper fileWrappers]; if (([fileWrappers objectForKey:TextFileName] == nil) && (self.text != nil)) { NSData *textData = [self.text dataUsingEncoding:TextFileEncoding]; NSFileWrapper *textFileWrapper = [[NSFileWrapper alloc] initRegularFileWithContents:textData]; [textFileWrapper setPreferredFilename:TextFileName]; [self.fileWrapper addFileWrapper:textFileWrapper]; } The code creates a top-level directory if it doesn’t exist. If a file wrapper doesn’t exist for the text file, it creates one from the string contents of the text property. It gives this file wrapper a preferred filename and then adds it to the top-level directory file wrapper. Formore on NSFileWrapper,seeNSFileWrapper Class Reference ; also see “Exporting theDocumentUTI” (page 22) for the required Info.plist property for document file packages. Other Method Overrides You Might Make There are a few other UIDocument overrides that many document-based applications might want to make: ● disableEditing...enableEditing—UIDocument calls the first method when it is unsafe for the user to make changes to document content, such as when there are updates from iCloud or a revert operation is underway. You can implement this method to prevent editing during this period. When editing becomes safe again, UIDocument calls the second method. Creating a Custom Document Object Other Method Overrides You Might Make 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Note: As an alternative to these overrides, you can observe notifications posted when the document state changes and, if the new document state is UIDocumentStateEditingDisabled, prevent editing until the document state changes again. More more on this topic, see “Monitoring Document-State Changes and Handling Errors” (page 43). ● savingFileType—This method by default returns the value of the fileType property. If the current document should be saved under a different file type for any reason, you can override this method to return the replacement file-type UTI. An example (from Mac OS X) is that when an image is added to an RTF file, it should be saved as an RTFD file package. Creating a Custom Document Object Other Method Overrides You Might Make 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29A document goes through a typical life cycle. A document-based application is responsible for managing its progress through that cycle. As you can see from the following list, most of these life-cycle events are initiated by the user: ● The user first creates a document. ● The user opens an existing document and the application displays it in the document’s view or views. ● The user edits the document. ● A user may ask to put a document in iCloud storage or may request the removal of a document from iCloud storage. ● During editing, saving, or other actions, errors or conflicts can happen; the application should learn about these errors and conflicts and either attempt to handle them or inform the user. ● The user closes a selected document. ● The user deletes an existing document. The following sections discussthe procedures a document-based application must complete for these life-cycle operations. Setting the Preferred Storage Location for Document Files All documents of an application are stored either in the local sandbox or in an iCloud container directory. A user should not be able to select individual documents for storage in iCloud. When an application launches for the first time on a device, it should do the following: ● If iCloud is not configured, ask users if they want to configure it (and, preferably, transfer them to Launch Settings if they want to configure iCloud). ● If iCloud is configured but not enabled for the application, ask users if they want to enable iCloud—in other words, ask if they want all of their documentssaved to iCloud. Store the response as a user preference. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30 Managing the Life Cycle of a DocumentBased on this preference, an application writes document files either to the local application sandbox or the iCloud container directory. (For details, see “Moving Documents to and from iCloud Storage” (page 39).) An application should expose a switch in the Settings application that enables usersto move documents between local storage and iCloud storage. Creating a New Document A document object (that is, an instance of your custom UIDocument subclass) must have a file URL that locates the document file either in the local application sandbox or in an iCloud container directory, whichever is the user’s preference. In addition, a new document can be given a name. The following discusses guidelines and procedures related to file URLs, document names, and the creation of new documents. Document Filename Versus Document Name The UIDocument class assumes a correspondence between the filename of a document and the document name (also known the display name). By default, UIDocument stores the filename as the value of the localizedName property. However, an application should not require a user to provide the document filename or display name when he or she creates a new document. For your application, you should devise some convention for automatically generating the filenames for your new documents. Some suggestions are: ● Generate a UUID (universally unique identifier) for each document, optionally with an application-specific prefix. ● Generate a timestamp (date and time) for each document, optionally with an application-specific prefix. ● Use a sequential numbering system, for example: “Notes 1”, “Notes 2”, and so on. For the document (display) name, you might initially use the document filename if that makes sense (such as with “Notes 1”). Or, if the document contains text and the user enters some text in the document, you might use the first line (or some part of the first line) as the display name. Your application can give users some way to customize the document name after the document has been created. Composing the File URL and Saving the Document File You cannot create a document object without a valid file URL. The file URL has three parts of interest: the path to the Documents directory in the user’s preferred document location, the document filename, and the extension of the document file. You can get a URL representing the path to the Documents directory in the local application sandbox through a method such asthe one in “Document Filename Versus Document Name.” Managing the Life Cycle of a Document Creating a New Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31Listing 4-1 Getting a URL to the application’s Documents directory in the local sandbox -(NSURL*)localDocumentsDirectoryURL { static NSURL *localDocumentsDirectoryURL = nil; if (localDocumentsDirectoryURL == nil) { NSString *documentsDirectoryPath = [NSSearchPathForDirectoriesInDomains( NSDocumentDirectory, NSUserDomainMask, YES ) objectAtIndex:0]; localDocumentsDirectoryURL = [NSURL fileURLWithPath:documentsDirectoryPath]; } return localDocumentsDirectoryURL; } The file extension must be one that you specified for the document type (see “Creating and Configuring the Project” (page 19)). You can declare a global string to represent the extension. For example: static NSString *FileExtension = @"imageNotes"; The final part of a document’s file URL is the filename component. As “Document Filename Versus Document Name” (page 31) explains, the application should initially generate the document filename according to some convention that makes sense for the application. This generated filename can be used as the document name, or the first line (or part thereof) can be used as the document name. The application can give the user the option of customizing the document name after the document object has been created. After you concatenate the base URL, the document filename, and the file extension, you can allocate an instance of your custom UIDocument subclass and initialize it with the initWithFileURL: method, passing in the constructed file URL. The final step in creating a new document is to save it to the preferred document storage location (even though there is no content at this point). Asillustrated by “Setting the Preferred Storage Location for Document Files ,” you do this by calling the saveToURL:forSaveOperation:completionHandler: method on the document object. Listing 4-2 Saving a new document to the file system -(void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; if (_createFile) { [self.document saveToURL:self.document.fileURL Managing the Life Cycle of a Document Creating a New Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) { if (success) _textView.text = self.document.text; }]; _createFile = NO; } // ..... } The save-operation parameter of the method call should be UIDocumentSaveForCreating. The final parameter of the call is a completion hander: a block that is invoked after the save operation concludes. The parameter of the block tells you whether the operation succeeded. If it did succeed, this code assigns the document text to the text property of the text view displaying the document content. Note: If you want to save a new document to the application’s iCloud container directory, it is recommended that you first save it locally and then call the NSFileManager method setUbiquitous:itemAtURL:destinationURL:error: to move the document file to iCloud storage. (This call could be made in the completion handler of the saveToURL:forSaveOperation:completionHandler: method.) See “Moving Documents to and from iCloud Storage” (page 39) for further information. Opening and Closing a Document Opening a document might at first glance seem to be a fairly easy procedure. Your application scans the contents of its Documents directory for files having the document’s extension and presents those documents to the user for selection. However, when iCloud storage is factored in, things get a bit more complicated. Your application’s documents could be in the Documents directory of the application sandbox or they could be in the Documents directory of the iCloud container directory. Discovering an Application’s Documents To obtain a list of an application’s documents in iCloud storage, run a metadata query. A query is an instance of the NSMetadataQuery class. After creating a NSMetadataQuery object, you give it a scope and a predicate. For iCloud storage, the scope should be NSMetadataQueryUbiquitousDocumentsScope. A predicate is an NSPredicate object that, in this case, constrains a search by filename extension. Before you start running the Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33query, register to observe the NSMetadataQueryDidFinishGatheringNotification and NSMetadataQueryDidUpdateNotification notifications. The method accepting delivery of these notifications processes the results of the query. Listing 4-3 illustrates how you set up and run a metadata query to get the list of application documents in the iCloud mobile container. The method first tests the user’s preferred storage location for documents (the documentsInCloud property). If that location isthe mobile container, it runs a metadata query. If the location is the application sandbox, it iterates through the contents of the application’s Documents directory to get the names and locations of all local document files. Listing 4-3 Getting the locations of documents stored locally and in iCloud storage -(void)viewDidLoad { [super viewDidLoad]; // set up Add and Edit navigation items here.... if (self.documentsInCloud) { _query = [[NSMetadataQuery alloc] init]; [_query setSearchScopes:[NSArray arrayWithObjects:NSMetadataQueryUbiquitousDocumentsScope, nil]]; [_query setPredicate:[NSPredicate predicateWithFormat:@"%K LIKE '*.txt'", NSMetadataItemFSNameKey]]; NSNotificationCenter* notificationCenter = [NSNotificationCenter defaultCenter]; [notificationCenter addObserver:self selector:@selector(fileListReceived) name:NSMetadataQueryDidFinishGatheringNotification object:nil]; [notificationCenter addObserver:self selector:@selector(fileListReceived) name:NSMetadataQueryDidUpdateNotification object:nil]; [_query startQuery]; } else { NSArray* localDocuments = [[NSFileManager defaultManager] contentsOfDirectoryAtPath: [self.documentsDir path] error:nil]; for (NSString* document in localDocuments) { [_fileList addObject:[[[FileRepresentation alloc] initWithFileName:[document lastPathComponent] url:[NSURL fileURLWithPath:[[self.documentsDir path] stringByAppendingPathComponent:document]]] autorelease]]; Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34} } } In this example, the predicate format is @"%K LIKE '*.txt’", which means to return all filenames (the NSMetadataItemFSNameKey key) that have a extension of txt, the file extension of this application’s document files. After the initial query concludes, and again if there are subsequent updates, the notification method specified in Listing 4-3 (fileListReceived) isinvoked again. Listing 4-4 showsthis method’simplementation. If query updates arrive after the user has made a selection, the code also tracks the current selection. Listing 4-4 Collecting information about documents in iCloud storage -(void)fileListReceived { NSString* selectedFileName=nil; NSInteger newSelectionRow = [self.tableView indexPathForSelectedRow].row; if (newSelectionRow != NSNotFound) { selectedFileName = [[_fileList objectAtIndex:newSelectionRow] fileName]; } [_fileList removeAllObjects]; NSArray* queryResults = [_query results]; for (NSMetadataItem* result in queryResults) { NSString* fileName = [result valueForAttribute:NSMetadataItemFSNameKey]; if (selectedFileName && [selectedFileName isEqualToString:fileName]) { newSelectionRow = [_fileList count]; } [_fileList addObject:[[[FileRepresentation alloc] initWithFileName:fileName url:[result valueForAttribute:NSMetadataItemURLKey]] autorelease]]; } [self.tableView reloadData]; if (newSelectionRow != NSNotFound) { NSIndexPath* selectionPath = [NSIndexPath indexPathForRow:newSelectionRow inSection:0]; [self.tableView selectRowAtIndexPath:selectionPath animated:NO scrollPosition:UITableViewScrollPositionNone]; Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35} } The example application now has an array (_fileList) of custom model objects that encapsulate the name and file URL of each of the application’s documents. (FileRepresentation is the custom class of those objects.) The root view controller populates a plain table view with the document names Note: You should leave metadata queries running only while your application is in the foreground. You should stop the queries when your application moves to the background. Downloading Document Files from iCloud When you run a metadata query to learn about an application’s iCloud documents, the query results are placeholder items (NSMetadataItem objects) for document files. The items contain metadata about the file, such as its URL and its modification date. The document file is not in the iCloud container directory. The actual data for a document is not downloaded until one of the following happens: ● Your application attempts to open or access the file, such as by calling openWithCompletionHandler:. ● Your application callsthe NSFileManagermethod startDownloadingUbiquitousItemAtURL:error: to download the data explicitly. Because downloading large document files from iCloud might result in a perceptible delay in displaying the document data, you should indicate to the user that the download has begun (for example, show “loading” or “updating”) and that the file is not currently accessible. Remove this indication when the download has completed. Note: The NSURLUbiquitousItemIsDownloadedKey associated with the document file’s URL tells you the document’s current download status. You can retrieve the value of this key using the getResourceValue:forKey:error: method of the NSURL class. Other keys are also available to tell you related information about the upload and download status of the file. For more information, see NSURL Class Reference . Opening a Document The sample document-based application lists known documents in a table view. When the user taps a listed document to open it, UITableView invokes the tableView:didSelectRowAtIndexPath: method of its delegate. The implementation of this method, shown in Listing 4-5, is typical for the navigation pattern: The Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36root view controller allocates the next view controller in the sequence—in this case, the view controller presenting document data—and initializes with essential data—in this case, the document’s file URL. Based on whether the device idiom is iPad or iPhone (or iPhone touch), the root view controller adds the view controller to the split view or pushes it on the navigation controller’s stack. Listing 4-5 Responding to a request to open a document -(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath { [self selectFileAtIndexPath:indexPath create:NO]; } -(void)selectFileAtIndexPath:(NSIndexPath*)indexPath create:(BOOL)create { NSArray* fileList = indexPath.section == 0 ? _localFileList : _ubiquitousFileList; DetailViewController* detailViewController = [[DetailViewController alloc] initWithFileURL:[[fileList objectAtIndex:indexPath.row] url] createNewFile:create]; if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad) { self.splitViewController.viewControllers = [NSArray arrayWithObjects:self.navigationController, detailViewController, nil]; } else { [self.navigationController pushViewController:detailViewController animated:YES]; } [detailViewController release]; } In itsinitializer method (notshown), the document’s view controller (DetailViewController in the example) allocates an instance of the UIDocument subclass and initializesit by calling the initWithFileURL: method, passing in the file URL. It assigns the newly created document object to a document property. Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37The final step in opening a document is to call the openWithCompletionHandler: method on the UIDocument object; the document’s view controller in our sample application calls this method in viewWillAppear:, as shown in Listing 4-6. The code checks the document state to verify that the document is closed before attempting to open it—there’s no need to open an already opened document. Listing 4-6 Opening a document -(void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; if (_createFile) { [self.document saveToURL:self.document.fileURL forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success) { _textView.text = self.document.text; }]; _createFile = NO; } else { if (self.document.documentState & UIDocumentStateClosed) { [self.document openWithCompletionHandler:nil]; } } } When openWithCompletionHandler: is called, UIDocument reads data from the document file, and the document object itself creates its model objects from the data. At the conclusion of this sequence of actions, the completion handler of the openWithCompletionHandler: method is executed. Although the view controller in the example does not implement the completion block, the completion handler is sometimes used to assign the document data to the document’s view or views for display. (To recall what DetailViewController doesinstead to update document views,see Listing 3-4 (page 25) and accompanying text.) Closing a Document To close a document,send a closeWithCompletionHandler: method to the document object. This method saves the document data, if necessary, and then executes the completion handler in its sole parameter. Managing the Life Cycle of a Document Opening and Closing a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38A good time to close a document is when the document’s view controller is dismissed, such as when the user taps the back button. Before the view controller’s view disappears, the viewWillDisappear: method is invoked. Your view controller subclass can override this method in order to call closeWithCompletionHandler: on the document object, as shown in Listing 4-7. Listing 4-7 Closing a document -(void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.document closeWithCompletionHandler:nil]; } Moving Documents to and from iCloud Storage As noted in “Setting the Preferred Storage Location for Document Files ” (page 30), an application should give its users the option of storing all documents in the local file system (the application sandbox) or in iCloud (the container directory). It stores this option as a user preference and refers to this preference when saving and opening documents. When the user changes the preference, the application should move all document files in the application sandbox to iCloud or move all files in the other direction, depending on the nature of the change. Getting the Location of the iCloud Container Directory When you move a document file from local storage to the Documents subdirectory of the iCloud container directory, its filename is unchanged. The only part of the file-URL path that is different is the part leading up to Documents. To get that part of the path, you need to call the URLForUbiquityContainerIdentifier: method of NSFileManager. Most of the time, you pass nil to this method to get your app’s default container directory. If your app supports multiple containers, you can request containers explicitly by passing in a string with the corresponding iCloud container identifier—a concatenation of your team ID and an application bundle ID, separated by a period. These container identifier strings are the same ones you specify in the Identifier field of your app target’s Summary view in Xcode. It is a good idea to declare a string constant for each of your app’s container identifiers, as in this example: static NSString *UbiquityContainerIdentifier = @"A93A5CM278.com.acme.document.billabong"; The two methods in Listing 4-8 get the iCloud container identifier and append “/Documents” to it. Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39Listing 4-8 Getting the iCloud container directory URL -(NSURL*)ubiquitousContainerURL { return [[NSFileManager defaultManager] URLForUbiquityContainerIdentifier:nil]; } -(NSURL*)ubiquitousDocumentsDirectoryURL { return [[self ubiquitousContainerURL] URLByAppendingPathComponent:@"Documents"]; } Note: For an example of getting the base URL for the application sandbox, see “Composing the File URL and Saving the Document File” (page 31). Moving a Document to iCloud Storage Programmatically, you put a document in iCloud storage by calling the NSFileManager method setUbiquitous:itemAtURL:destinationURL:error:. This method requiresthe file URL of the document file in the application sandbox (source URL) and the destination file URL of the document file in the application’s iCloud container directory. The first parameter takes a Boolean value, which should be YES. Important: You should not call setUbiquitous:itemAtURL:destinationURL:error: from your application’s main thread, especially if the document is not closed. Because this method performs a coordinated write operation on the specified file, calling this method from the main thread can trigger a deadlock with any file presenter monitoring the file. (In addition, this method executing on the main thread can take an indeterminate amount of time to complete.) Instead, call the method in a block running in a dispatch queue other than the main-thread queue. You can always message your main thread after the call finishes to update the rest of your application’s data structures. The method in Listing 4-9 illustrates how to move a document file from an application sandbox to iCloud storage. In the sample application, when the user’s preferred storage location (iCloud or local) changes, this method is called for every document file in the application sandbox. There are roughly three parts to this method: ● Compose the source URL and the destination URL. ● On a secondary dispatch queue: Call the setUbiquitous:itemAtURL:destinationURL:error: method and cache the result, a Boolean value (success) that indicates whether the document file successfully moved to the iCloud container directory. Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40● On the main dispatch queue: If the callsucceeds, update the document’s model objects and its presentation of those objects; if the call does not succeed, log the error (or otherwise handle it). Listing 4-9 Moving a document file to iCloud storage from local storage - (void)moveFileToiCloud:(FileRepresentation *)fileToMove { NSURL *sourceURL = fileToMove.url; NSString *destinationFileName = fileToMove.fileName; NSURL *destinationURL = [self.documentsDir URLByAppendingPathComponent:destinationFileName]; dispatch_queue_t q_default; q_default = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_async(q_default, ^(void) { NSFileManager *fileManager = [[[NSFileManager alloc] init] autorelease]; NSError *error = nil; BOOL success = [fileManager setUbiquitous:YES itemAtURL:sourceURL destinationURL:destinationURL error:&error]; dispatch_queue_t q_main = dispatch_get_main_queue(); dispatch_async(q_main, ^(void) { if (success) { FileRepresentation *fileRepresentation = [[FileRepresentation alloc] initWithFileName:fileToMove.fileName url:destinationURL]; [_fileList removeObject:fileToMove]; [_fileList addObject:fileRepresentation]; NSLog(@"moved file to cloud: %@", fileRepresentation); } if (!success) { NSLog(@"Couldn't move file to iCloud: %@", fileToMove); } }); }); } Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41Removing a Document from iCloud Storage To move a document file from an iCloud container directory to the Documents directory of the application sandbox, follow the same procedure described in “Moving a Document to iCloud Storage” (page 40), except switch the source URL (now the document file in the iCloud container directory) and the destination URL (now the document file in the application sandbox). In addition, the first parameter of the setUbiquitous:itemAtURL:destinationURL:error: method should now be NO. Listing 4-10 shows a method implementing this procedure; it is called for each file in the iCloud container directory, moving it to the application sandbox. Listing 4-10 Moving a document file from iCloud storage to local storage - (void)moveFileToLocal:(FileRepresentation *)fileToMove { NSURL *sourceURL = fileToMove.url; NSString *destinationFileName = fileToMove.fileName; NSURL *destinationURL = [self.documentsDir URLByAppendingPathComponent:destinationFileName]; dispatch_queue_t q_default; q_default = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0); dispatch_async(q_default, ^(void) { NSFileManager *fileManager = [[[NSFileManager alloc] init] autorelease]; NSError *error = nil; BOOL success = [fileManager setUbiquitous:NO itemAtURL:sourceURL destinationURL:destinationURL error:&error]; dispatch_queue_t q_main = dispatch_get_main_queue(); dispatch_async(q_main, ^(void) { if (success) { FileRepresentation *fileRepresentation = [[FileRepresentation alloc] initWithFileName:fileToMove.fileName url:destinationURL]; [_fileList removeObject:fileToMove]; [_fileList addObject:fileRepresentation]; NSLog(@"moved file to local storage: %@", fileRepresentation); } if (!success) { NSLog(@"Couldn't move file to local storage: %@", fileToMove); Managing the Life Cycle of a Document Moving Documents to and from iCloud Storage 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42} }); }); } Monitoring Document-State Changes and Handling Errors A document can go through different states during its runtime life. A state can tell you whether a document is experiencing an error, a version conflict, or some other condition that is not normal. UIDocument declares constants (of type UIDocumentState) to represent document states and sets the documentState property with one of these constants when a change is a document’sstate occurs. Table 4-1 describesthe state constants. Table 4-1 UIDocumentState constants Document state constant What it means The document is open and is experiencing no conflicts or other problems. UIDocumentStateNormal The document is closed. A document is in this state if UIDocument cannot open a document, in which case document properties might not be valid. UIDocumentStateClosed UIDocumentStateInConflict There are versions of the document that are in conflict. UIDocumentStateSavingError An error prevents UIDocument from saving the document. UIDocumentStateEditingDisabled It is not currently safe to allow users to edit the document. UIDocument also posts a notification of type UIDocumentStateChangedNotification when a change in document state occurs. Your application should observe this notification and respond appropriately. The initializer method of the document’s view controller is a good place to add an observer, as shown in Listing 4-11. The observer in this case is the view controller. Listing 4-11 Adding an observer of the UIDocumentStateChangedNotification notification -(id)initWithFileURL:(NSURL*)url createNewFile:(BOOL)createNewFile { NSString* nibName = [[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad ? @"DetailViewController_iPad" : @"DetailViewController_iPhone"; Managing the Life Cycle of a Document Monitoring Document-State Changes and Handling Errors 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43self = [super initWithNibName:nibName bundle:nil]; if (self) { _document = [[ImageNotesDocument alloc] initWithFileURL:url]; // other code here.... [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(documentStateChanged) name:UIDocumentStateChangedNotification object:_document]; } return self; } Be sure to remove the observer from the notification center in the class’s dealloc method. When the document’s state changes, UIDocument posts the UIDocumentStateChangedNotification notification, and the notification center deliversit by invoking the notificationmethod (documentStateChanged in the example). In Listing 4-12, the observing view controller gets the current state from the documentState property and evaluates it. If the state is UIDocumentStateEditingDisabled, it hides the keyboard. If there are conflicts between different versions of the document (UIDocumentStateInConflict), it displays a Show Conflicts button in the document view’s toolbar. (For detailed information on handling document-version conflicts, see “Resolving Document Version Conflicts” (page 51).) Listing 4-12 Evaluating the current document state -(void)documentStateChanged { UIDocumentState state = _document.documentState; [_statusView setDocumentState:state]; if (state & UIDocumentStateEditingDisabled) { [_textView resignFirstResponder]; } if (state & UIDocumentStateInConflict) { [self showConflictButton]; } else { [self hideConflictButton]; [self dismissModalViewControllerAnimated:YES]; } Managing the Life Cycle of a Document Monitoring Document-State Changes and Handling Errors 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 44} The notification-handling method also calls a setDocumentState: method implemented by a private view class. This method, shown in Listing 4-13, changes other items of the document view’s toolbar depending on the document state. Listing 4-13 Updating a document’s user interface to reflect its state -(void)setDocumentState:(UIDocumentState)documentState { if (documentState & UIDocumentStateSavingError) { self.unsavedLabel.hidden = NO; self.circleView.image = [UIImage imageNamed:@"Red"]; } else { self.unsavedLabel.hidden = YES; if (documentState & UIDocumentStateInConflict) { self.circleView.image = [UIImage imageNamed:@"Yellow"]; } else { self.circleView.image = [UIImage imageNamed:@"Green"]; } } } If the document could not be saved (UIDocumentStateSavingError), the view controller changesthe status indicator to red and displays Unsaved next to it. If there are conflicting document versions, it makes the status indicator yellow (this is in addition to the Show Conflicts button mentioned earlier). Otherwise, the status indicator is green. Deleting a Document Just as you want to allow users to create a document, you also want to let them delete selected documents. Deletion of a document requires you to do three things: ● Remove the document file from storage (either from the local sandbox or the iCloud container directory). ● Remove the model objects used to represent the document data in memory. Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 45● Remove the document data presented in the document view. When you delete a document from storage, your code should approximate what UIDocument doesfor reading and writing operations. It should perform the deletion asynchronously on a background queue, and it should use file coordination. Listing 4-14 illustrates this procedure. It dispatches a task on a background queue that creates an NSFileCoordinator object and calls the coordinateWritingItemAtURL:options:error:byAccessor: method on it. The byAccessor block of this method calls the NSFileManager method for deleting the file, removeItemAtURL:error:. Listing 4-14 Deleting a selected document -(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath { NSMutableArray* fileList = nil; if (indexPath.section == 0) { fileList = self.localFileList; } else { fileList = self.ubiquitousFileList; } NSURL* fileURL = [[fileList objectAtIndex:indexPath.row] url]; dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^(void) { NSFileCoordinator* fileCoordinator = [[NSFileCoordinator alloc] initWithFilePresenter:nil]; [fileCoordinator coordinateWritingItemAtURL:fileURL options:NSFileCoordinatorWritingForDeleting error:nil byAccessor:^(NSURL* writingURL) { NSFileManager* fileManager = [[NSFileManager alloc] init]; [fileManager removeItemAtURL:writingURL error:nil]; }]; }); [fileList removeObjectAtIndex:indexPath.row]; [tableView deleteRowsAtIndexPaths:[[NSArray alloc] initWithObjects:&indexPath count:1] withRowAnimation:UITableViewRowAnimationLeft]; } Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 46In this example, the user triggers the invocation of the method when he or she taps the Delete button in a row while the table view is in editing mode. Managing the Life Cycle of a Document Deleting a Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 47The saveless-model feature of the UIDocument class ensures that document data is automatically saved at frequent intervals, relieving users of the need to explicitly save their documents. UIDocument implements much of the behavior for the saveless model, but a document-based application must play its own part to make the feature work. How UIKit Saves Document Data Automatically The saveless model implemented by the UIKit framework for documents has two main parts: a mechanism for marking a document as needing to be saved and a variable period for when the framework checks that flag. Periodically, UIKit callsthe hasUnsavedChanges method of a UIDocument object and evaluatesthe returned value. If the value is YES, it saves the document data to the document file. The period between checks of the hasUnsavedChanges value varies according to several factors, including the rate of input by the user. A document-based application sets the value returned by hasUnsavedChanges indirectly, either by implementing undo and redo or by tracking changesto the document. Change tracking requiresthe application to call the updateChangeCount: method, passing in UIDocumentChangeDone (a constant of type UIDocumentChangeKind). When an application registers an undo action and then sends undo or redo messages to the document’s undo manager, UIDocument calls updateChangeCount: on its behalf. Because giving users the ability to undo and redo changes can be a differentiating feature, that approach is recommended for most applications. Implementing Undo and Redo You can implement undo and redo operations in your application by following the procedures and recommendations in Undo Architecture . Note that UIDocument defines an undoManager property. You can get the default NSUndoManager object by accessing this property, or you can assign your own NSUndoManager object to it. The undo manager must be associated with the UIDocument object through the property in order to enable change tracking and thus automatic saving of document data. Listing 5-1 illustrates an implementation of undo and redo for a text field. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 48 Change Tracking and Undo OperationsListing 5-1 Implementing undo and redo for a text field - (void)textFieldDidEndEditing:(UITextField *)textField { self.undoButton.enabled = YES; self.redoButton.enabled = YES; if (textField.tag == 1) { [self setLocationText:textField.text]; } // code for other text fields here.... } - (void)setLocationText:(NSString *)newText { NSString *currentText = _document.location; if (newText != currentText) { [_document.undoManager registerUndoWithTarget:self selector:@selector(setLocationText:) object:currentText]; _document.location = newText; self.locationField.text = newText; } } - (IBAction)handleUndo:(id)sender { [_document.undoManager undo]; if (![_document.undoManager canUndo]) self.undoButton.enabled = NO; } - (IBAction)handleRedo:(id)sender { [_document.undoManager redo]; if (![_document.undoManager canRedo]) self.redoButton.enabled = NO; } Change Tracking and Undo Operations Implementing Undo and Redo 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 49Implementing Change Tracking To implement change tracking instead of implementing undo/redo, call the updateChangeCount: method on the UIDocument object at the appropriate points in your code. Just as when you register an undo action, it’s typically at the point where you update the document’s model object with data the user has just entered. The parameter passed in should be a UIDocumentChangeDone constant. Listing 5-2 shows how you might call updateChangeCount: from within a UITextViewDelegate method that is called when a change is made in a text view. Listing 5-2 Updating the change count of a document -(void)textViewDidChange:(UITextView *)textView { _document.documentText = textView.text; [_document updateChangeCount:UIDocumentChangeDone]; } Change Tracking and Undo Operations Implementing Change Tracking 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 50In an iCloud world, when a user has installed a document-based application on multiple devices or desktop systems, there can be conflicts between different versions of the same document. Recall that an application updates a document file in the local container directory and those changes are then transmitted—usually immediately—to iCloud. But what if this transmission is not immediate? For example, you edit a document using the Mac OS X version of your application, but you’ve also edited the same document using the iPad version of the application—and you did so while the device wasin Airplane Mode. When you switch off Airplane Mode, the local change to the document is transferred to iCloud. iCloud notices a conflict and notifies the application. Learning About Document Version Conflicts As “Monitoring Document-State Changes and Handling Errors” (page 43) describes, your application becomes aware of document-version conflicts by observing the UIDocumentStateChangedNotification notification. If the documentState property changes to UIDocumentStateInConflict, multiple versions of the same document exist. The application isresponsible for resolving those conflicts assoon as possible, with or without the user’s help. You learn about the conflicting versions of a document through two class methods of the NSFileVersion class. The currentVersionOfItemAtURL: method returns an NSFileVersion object representing what’s referred to as the current file ; the current file is chosen by iCloud on some basis as the current “conflict winner” and is the same across all devices. By calling the unresolvedConflictVersionsOfItemAtURL: method, you get an array of NSFileVersion objects; these objects are called conflict versions, and each represents an unresolved version conflict for the file located at the specified URL. NSFileVersion objects can give you information helpful in resolving conflicts, such as modification dates, localized document names, and localized names of saving computers. Strategies for Resolving Document Version Conflicts Your application can follow one of three strategies for resolving document-version conflicts: ● Merge the changes from the conflicting versions. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 51 Resolving Document Version Conflicts● Choose one of the document versions based on some pertinent factor, such as the version with the latest modification date. ● Enable the user to view conflicting versions of a document and select the one to use. Which strategy is best to use depends a lot upon your document data. If you can merge the contents of different document versions without introducing contradictory elements, then follow that strategy. Or choose the document version with the latest modification date if your application doesn’tsuffer any loss of data as a result. Generally, you should try to resolve the conflict without involving the user, but for some applications that might not be possible. If an application takes the user-centered approach, it should discreetly inform the user about the version conflict and expose a button or other control that initiates the resolution procedure. “An Example: Letting the User Pick the Version” (page 53) examines the code of an application that lets the user select the document version to use. How to Tell iOS That a Document Version Conflict Is Resolved When your application or its users resolve a document version conflict by picking a version of a document, your application should complete the following steps: ● If the chosen version is a conflict version, replace the current document file with the conflict-version document file. To to this, call the replaceItemAtURL:options:error: method on the NSFileVersion object representing the version, passing in the document’s current-file URL. ● If the chosen version is a conflict version, revert the document so that it displays the new data in the document file To do this, call the UIDocument method revertToContentsOfURL:completionHandler: on the document object, passing in the document’s current-file URL. ● Disassociate all conflict versions with the document’s file URL. To do this, call the NSFileVersion class method removeOtherVersionsOfItemAtURL:error:, passing in the document’s file URL. ● Mark each conflict version as resolved so that iOS doesn’t raise it again as a conflicting version. To do this, set the resolved property of each NSFileVersion object representing a conflict version to YES. This step should always be done last. ● Remove the resolved versions of the document. For any versions you no longer need, call the removeAndReturnError: method of NSFileVersion to reclaim the storage for the file. Document revisions remain on the server until you delete them. Resolving Document Version Conflicts How to Tell iOS That a Document Version Conflict Is Resolved 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 52An Example: Letting the User Pick the Version Our sample document-based application is a simple text editor. It would be difficult for such an application to locate and merge textual differences in conflicting versions of the document, and even if it did, the resulting document might not be what the user wants. The application could pick the document version with the most recent modification date, but then again there’s no way to be certain that is the version the user wants. A good conflict-resolution strategy in this case is to let the user, who is most familiar with the document’s contents, pick the version she or he wants. You might recall the code shown in Listing 6-1 from “Monitoring Document-State Changes and Handling Errors” (page 43). This code shows the method of the document’s view controller that handles the UIDocumentStateChangedNotification notification posted by UIDocument when there is a change in document state. If the new document state is UIDocumentStateInConflict, the view controller shows a Resolve Conflicts button in a custom status view. (It also sets the color of the status indicator to red.) Listing 6-1 Detecting a conflict in document versions -(void)documentStateChanged { UIDocumentState state = _document.documentState; [_statusView setDocumentState:state]; if (state & UIDocumentStateEditingDisabled) { [_textView resignFirstResponder]; } if (state & UIDocumentStateInConflict) { [self showConflictButton]; // <------ Shows "Resolve Conflicts" button } else { [self hideConflictButton]; [self dismissModalViewControllerAnimated:YES]; } } When the user taps the button, UIKit invokes the method in Listing 6-2. This method displays modally the view of a custom conflict-resolver view controller. Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 53Listing 6-2 Showing the user interface for resolving document version conflicts -(void)conflictButtonPushed { ConflictResolverViewController* conflictResolver = [[ConflictResolverViewController alloc] initWithURL:_document.fileURL delegate:self]; [self presentViewController:conflictResolver animated:YES completion:nil]; [conflictResolver release]; } The ConflictResolverViewController object creates a page view controller (UIPageViewController object) that allows user to page between, and examine, the current-file document and each conflict-version document. In the tool bar of each document view is a Select Version button. If the user taps that button, one of the two custom delegation methods shown in Listing 6-3 is called, depending on whether the chosen document is the current-file document or a conflict-version document. Listing 6-3 Resolving a document version conflict -(void)conflictResolver:(ConflictResolverViewController *)conflictResolver didResolveWithFileVersion:(NSFileVersion *)fileVersion { [self dismissViewControllerAnimated:YES completion:nil]; [fileVersion replaceItemAtURL:_document.fileURL options:0 error:nil]; [NSFileVersion removeOtherVersionsOfItemAtURL:_document.fileURL error:nil]; [_document revertToContentsOfURL:_document.fileURL completionHandler:nil]; NSArray* conflictVersions = [NSFileVersion unresolvedConflictVersionsOfItemAtURL:_document.fileURL]; for (NSFileVersion* fileVersion in conflictVersions) { fileVersion.resolved = YES; } } -(void)conflictResolverDidResolveWithCurrentVersion:(ConflictResolverViewController*)conflictResolver { [self dismissViewControllerAnimated:YES completion:nil]; [NSFileVersion removeOtherVersionsOfItemAtURL:_document.fileURL error:nil]; NSArray* conflictVersions = [NSFileVersion unresolvedConflictVersionsOfItemAtURL:_document.fileURL]; Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 54for (NSFileVersion* fileVersion in conflictVersions) { fileVersion.resolved = YES; } } These methods illustrate the steps described in “How to Tell iOS That a Document Version Conflict Is Resolved” (page 52). If the chosen document is a conflict version, the delegate calls replaceItemAtURL:options:error: on the passed-in NSFileVersion object to replace the document file in the iCloud container directory with the chosen document. The delegate then enumerates the array containing NSFileVersion objectsrepresenting all conflict versions of the document and setsthe resolved property of each object to YES. It then asks NSFileVersion to remove all other conflict versions of the document associated with the document’sfileURL and calls revertToContentsOfURL:completionHandler: to revert the displayed document to the new contents of the document file. The second delegation method, invoked when the current document file is selected, is much simpler. It sets the resolved property of all NSFileVersion objects representing conflict versions to YES and removes all conflict versions associated with the document file URL. Resolving Document Version Conflicts An Example: Letting the User Pick the Version 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 55This table describes the changes to Document-Based App Programming Guide for iOS . Date Notes 2012-09-19 Updated the document's iCloud-related information. Changed the operator used in the predicate of metadata query searches to LIKE. 2012-01-09 New document that explains how to create an iOS application whose documents are integrated with iCloud storage. 2011-10-12 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 56 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, iPad, iPhone, Mac, Mac OS, Objective-C, OS X, and Xcode 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. 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. Core Text Programming GuideContents Introduction 4 Organization of This Document 4 See Also 4 Core Text Overview 6 OS X Text Technologies 6 Design Goals and Principles 7 Core Text Features and Capabilities 8 System Data Types and Services 8 Core Text Input 8 Characters and Glyphs 9 Core Text Objects 10 Layout Objects 10 Font Objects 13 Common Operations 15 Simple Paragraphs 15 Simple Text Labels 16 Columnar Layout 17 Manual Line Breaking 20 Font Creation and Storage 21 Accessing Font Metrics 25 Creating Related Fonts 27 Document Revision History 29 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 2Figures and Listings Core Text Overview 6 Figure 1-1 Glyphs of the character A 9 Figure 1-2 Ligatures 9 Figure 1-3 Text layout data flow 10 Figure 1-4 A frame object containing lines and glyph runs 12 Figure 1-5 Creating a font from a font descriptor 14 Common Operations 15 Listing 2-1 Typesetting a simple paragraph 15 Listing 2-2 Typesetting a simple text label 17 Listing 2-3 Performing columnar text layout 18 Listing 2-4 Performing manual line breaking 20 Listing 2-5 Creating a font descriptor from a name and point size 21 Listing 2-6 Creating a font descriptor from a family and traits 21 Listing 2-7 Creating a font from a font descriptor 23 Listing 2-8 Serializing a font 23 Listing 2-9 Creating a font from serialized data 24 Listing 2-10 Calculating line height 26 Listing 2-11 Getting glyphs for characters 26 Listing 2-12 Changing traits of a font 27 Listing 2-13 Converting a font to another family 28 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 3Core Text is an advanced, low-level technology for laying out text and handling fonts. It is designed for high performance and ease of use. The Core Text API, introduced in OS X v10.5, is accessible from all OS X application environments. It is also available in iOS 3.2. The Core Text layout engine is designed specifically to make simple text layout operations easy to do and to avoid side effects. The Core Text font programming interface is complementary to the Core Text layout engine and is designed to handle Unicode fonts natively, unifying disparate OS X font facilities into a single comprehensive programming interface. This document is intended for developers who need to do text layout and font handling at a low level. If you can develop your application using higher-level constructs, such as NSTextView, then you should use the Cocoa text system, introduced in Text System Overview. If, on the other hand, you need to render text directly into a Core Graphics context, then you should use Core Text. More information about the position of Core Text among other OS X text technologies is presented in “OS X Text Technologies” (page 6). Important: This document has not been updated to address the use of Core Text in iOS 3.2. Organization of This Document This document is organized into the following chapters: “Core Text Overview” (page 6) describes the Core Text system in terms of its design goals and feature set. It also introducesthe opaque typesthat encapsulate the text layout and font handling capabilities of the system. “Common Operations” (page 15) presents snippets of code with commentary illustrating typical uses of the main Core Text opaque types. See Also In addition to this document, there are several that cover more specific aspects of Core Text or describe the software services used by Core Text. 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 4 Introduction● Core Text Reference Collection provides complete reference information for the Core Text layout and font API. ● CoreTextTest is a sample code project thatshows how to use Core Text in the context of a complete Carbon application. ● CoreTextArcCocoa is a sample code project that illustrates the use of fonts, lines, and runs in a Core Text Cocoa application. ● Core Foundation Design Concepts and Core Foundation Framework Reference describe Core Foundation, a framework that provides abstractions for common data types and fundamental software services used by Core Text. The following documents provide entry points to the documentation describing the Cocoa text system. ● Text System Overview gives an introduction to the Cocoa text system. ● Text Layout Programming Guide for Cocoa describes the Cocoa text layout engine. Introduction See Also 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 5The Core Text framework is an advanced, low-level technology for laying out text and handling fonts. Designed for high performance and ease of use, the Core Text layout engine is up to twice as fast as ATSUI (Apple Type Services for Unicode Imaging). The Core Text layout API is simple, consistent, and tightly integrated with Core Foundation, Core Graphics, and Cocoa. The Core Text font API is complementary to the Core Text layout engine. Core Text font technology is designed to handle Unicode fonts natively, bridging the gap between Carbon and Cocoa font references, and providing efficient font handling for Core Text layout. Core Text brings the capabilities and coherent design of Cocoa text and fonts to a broader, lower-level client base. OS X Text Technologies The Macintosh operating system has provided sophisticated text handling and typesetting capabilities from its beginning. In fact, these features sparked the desktop publishing revolution. Core Text is the most modern text-handling technology on the platform. It is designed specifically for OS X and is written in C, so it can be called from any language in the system. It is positioned as a core technology to provide consistent, high-performance textservicesto other frameworksthroughout the system, and the Core Text API is accessible to applications that need to use it directly. Core Text resides in the Application Services umbrella framework (ApplicationServices) so that it is callable from both Carbon and Cocoa and has all of the lower-level services it needs. Core Text is not meant to replace the Cocoa text system, although it provides the underlying implementation for many Cocoa text technologies. If you can deal with high-level constructs, such as text views, you can probably use Cocoa. For this reason, Cocoa developers typically have no need to use Core Text directly. Carbon developers, on the other hand, will find Core Text faster and easier to use, in many cases, than preexisting OS X text layout and font APIs. To decide whether Core Text isthe right OS X text technology for your application, apply the following guidelines: ● If you can, use Cocoa text. The NSTextView class is the most advanced, full-featured, flexible text view in OS X. For small amounts of text, use NSTextField. ● To display web content in your application, use Web Kit. ● If you need to use Carbon only, consider using NSTextView with HICocoaView. 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 6 Core Text Overview● If you need a lower-level API for drawing any kind of text into a Quartz graphics context (CGContext), consider using Core Text directly. Generally speaking, Core Text is for applications that need a low-level text-handling technology correlating with the Core Graphics framework (Quartz). If you work directly with Quartz and you need to draw some text, use Core Text. If, for example, you have your own page layout engine—you have some text and you know where it needs to go in your view—you can use Core Text to generate the glyphs and position them relative to each other with all the features of fine typesetting,such as kerning, ligatures, line-breaking, and justification. Design Goals and Principles Core Text is designed to provide the following benefits: ● A comprehensive, unified set of text-layout and font APIs ● High performance and ease of use ● Tight integration with Cocoa, Core Foundation, and Core Graphics (Quartz) ● Native Unicode handling ● 64-bit application support ● Clean, simple, consistent API design ● Simple interfaces for simple operations ● A flexible interface to layout and glyph data ● A predictable cost structure and rational division of labor A primary design goal of Core Text layout is to make simple things easy to do. So, for example, if you want to draw a paragraph of text or a simple text label on the screen, you don’t need much code. A corollary principle of the Core Text design is that clients are not required to pay for features they don’t use. The objects defined by Core Text opaque types provide a progression from simplicity to complexity, in terms of their use and interface. That is, higher-level objects do more for you, and so they are easier to use (although they may be more complex internally). For example, the highest-level object in Core Text is the framesetter, which fills a path (defined by a CGPath object representing a rectangle) with text. The framesetter object uses other Core Text objects, such as typesetter, line, and glyph run objects, to accomplish its work: creating frame objects, which are lines of glyphs laid out within a shape. Clients who simply need to lay out a paragraph need only work with the framesetter. Clients who need to intervene in the text layout process at a lower level can deal with lower level objects, such as line objects. Line objects can draw themselves individually or be used to obtain glyph information. With Core Text you use the highest-level object you can to get your job done. Core Text Overview Design Goals and Principles 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 7Core Text Features and Capabilities Core Text performs text layout and font access. The text layout engine generates glyphs from characters and positionsthe glyphsinto glyph runs, lines, and multiline frames. It also provides glyph- and layout-related data, such as glyph positioning and measurement of lines and frames. The API handles character attributes and paragraph styles, including various types of tab styles and positioning. The Core Text font API bringsto Carbon developersthe same capabilities enjoyed by Cocoa developersthrough NSFont and NSFontDescriptor. The API provides font viewing and selecting. It provides font references, font descriptors (objects that encapsulate font data sufficient to instantiate a font reference), and easy access to font data. It also provides support for multiple master fonts, font variations, font cascading, and font linking. The Core Text font API is designed to be very complete, so that you don’t have to go to different layers to do what you need to do. System Data Types and Services Core Text uses system data types and services wherever possible, and you use the same conventions that pertain to the other core frameworks in OS X. So, for example, Core Text uses Core Foundation objects for many input and output parameters, enabling them to be retained, released, and stored in Core Foundation collection classes. Other objects handled by Core Text are provided by the Core Graphics framework, for example, CGPath objects. Moreover, because many Core Foundation objects are toll-free bridged with Cocoa Foundation objects, you can usually use Foundation objects in place of Core Foundation objects passed into Core Text functions. Use of these standard types and toll-free bridging ensure that you don’t have to perform expensive type conversions to get data into and out of Core Text. Core Text is built to work directly with Core Graphics, also known as Quartz, which is the high-speed graphics rendering engine that handles two-dimensional imaging at the lowest level in OS X. Quartz is the only way to get glyphs drawn at a fundamental level, and, because Core Text provides all data in a form directly usable by Quartz, the result is high-performance text rendering. Core Text Input The input type most basic to Core Text is the Core Foundation attributed string, represented by CFAttributedStringRef or its Cocoa counterpart, NSAttributedString, which are toll-free bridged. The attributes are key-value pairs that define style characteristics of the characters in the string, which are grouped in rangesthatshare the same attributes. Examples of text attributes are font and color. The attributesthemselves are passed into attributed strings, and retrieved from them, using CFDictionary objects. (Though CFDictionaryRef and NSDictionary are also toll-free bridged, the individual attribute objects stored in the dictionary may not be.) The typesetting mechanism in Core Text uses the information in the attributed string to perform character-to-glyph conversion. Core Text Overview Core Text Features and Capabilities 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 8Characters and Glyphs One of the most important capabilities of fine typesetting is character-to-glyph conversion. It is important to distinguish between characters and glyphsin discussing a text layout engine. Characters are essentially numbers representing code points in a character set or encoding scheme, such as Unicode, the character set used for all text in OS X. 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. A glyph is a graphic shape used to depict a character. Glyphs are also represented by numeric codes, called glyph codes, that are indexesinto a particular font. Glyphs are selected during composition and layout processing by the character-to-glyph conversion process. There are any number of glyphs that correspond to a particular character. For example, the character“uppercase A” has different glyphsfor different typefaces(such as Helvetica and Times) and type styles (such as bold and italic). Figure 1-1 shows various glyphs, all of which represent an “uppercase A.“ Figure 1-1 Glyphs of the character A Moreover, the correspondence between characters and glyphs is not one to one, and the context within which a character appears can affect the glyph chosen to represent it. For example, in many fonts an “f” and “l” appearing side-by-side in a character string are replaced by a ligature, which is a single glyph depicting the letters joined together. Figure 1-2 shows two examples of individual characters and the single-glyph ligatures often used when they are adjacent. Character-to-glyph conversion is a complex and difficult task that Core Text performs quickly and efficiently. Figure 1-2 Ligatures + = + = Core Text Overview Core Text Features and Capabilities 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 9Core Text Objects Core Text objects are based on the corresponding opaque types defined by the framework. In the sections that follow, you learn how the primary Core Text objects interact to accomplish various client tasks. Layout Objects Layout objects make up the Core Text layout engine. This section discusses the primary layout objects: framesetter, frame, typesetter, line, and glyph run objects. In addition this section briefly discusses the other Core Text layout objects: paragraph styles, text tabs, and glyph info objects. Framesetters and Frames The framesetter is the highest-level object in the Core Text layout engine, represented by the CTFramesetter opaque type. A framesetter generates text frames by filling a path with text. That is, CTFramesetter is an object factory for CTFrame objects that are ready to draw. The framesetter takes an attributed string object (CFAttributedString) and a shape descriptor object (CGPath) and calls into the typesetter to create line objects that fill that shape. The output is a frame object containing an array of lines. This array of lines is a paragraph, a multiline layout. The frame can draw itself directly into a graphic context. You can also retrieve the lines to manipulate before drawing. For example, you might adjust their positioning. Figure 1-3 shows the data flow among objects performing text layout. Figure 1-3 Text layout data flow CFAttributedString CTFramesetter CTTypesetter CTFrame CGPath The framesetter applies paragraph styles to the frame text as it is laid out. Paragraph styles are represented in Core Text by objects storing attributes that affect paragraph layout. Among these attributes are alignment, tab stops, writing direction, line-breaking mode, and indentation settings. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 10It’s advantageousto use the framesetter to perform the common operation of typesetting a multiline paragraph because it handles all of the details of producing frames, instantiating other objects, such as the typesetter, as needed. The CTFramesetter opaque type provides functions to create a framesetter with an attributed string, to create frame objects, and to return itstypesetter. As with all Core Text objects, CTFramesetter can also return its Core Foundation type identifier. Typesetters A typesetter performsthe fundamental text layout operations of character-to-glyph conversion and positioning of those glyphs into lines. That is, it determines which glyphs to use and where to place them relative to each other, producing line objects. Typesetters are represented by the CTTypesetter opaque type. The typesetter also suggests line breaks. It finds how many glyphs can fit within a single line within a given space. It then determines the length of the line by using word breaks, word wrapping, or finer-grained cluster breaks. Simple word wrapping is the default method of creating line breaks. The framesetter instantiates a typesetter and uses it to create the line objects used to fill a frame. You can also use a typesetter directly, as described in “Manual Line Breaking” (page 20). Lines and Glyph Runs A line object represents a line of text and is represented in Core Text by the CTLine opaque type. A CTLine object contains an array of glyph runs. Line objects are created by the typesetter during a framesetting operation and, like frames, can draw themselves directly into a graphics context. Line objects hold the glyphs that are the result of the text layout process, created from text and style information. A line corresponds to a range of characters. It could be miles long or, more often, one of a series of lines contained within a paragraph. The paragraph is represented in Core Text by a CTFrame object, which contains the paragraph’s line objects. Accordingly, you can retrieve line objects from their frame object. A line object contains glyph-run objects, represented by the CTRun opaque type. A glyph run is a set of consecutive glyphs sharing the same attributes and direction. The typesetter creates glyph runs as it produces lines from character strings, attributes, and font objects. That is, a line is constructed of one or more glyphs Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 11runs. Glyph runs can draw themselves into a graphic context, if desired, although most clients have no need to interact directly with glyph runs. Figure 1-4 shows the conceptual hierarchy of a frame object containing line objects that, in turn, contain glyph-run objects. Figure 1-4 A frame object containing lines and glyph runs CTRun CTLine CTFrame a glyph run CTLine has a convenience method for creating a freestanding line independent of a frame, CTLineCreateWithAttributedString. You can use this method to create a line object directly from an attributed string without needing to create and manage a typesetter. Without a typesetter, however, there’s no way to calculate line breaks, so this method is meant for a single line only (for example, creating a text label). After you have a line object, you can do a number of things with it. For example, you can have the line create a justified or truncated copy of itself, and you can ask the line for pen offsets for various degrees of flushness. You can use these pen offsets to draw the line with left, right, or centered alignments. You can also ask the line for measurements, such as its image bounds and typographic bounds. Image bounds represent the rectangle tightly enclosing the graphic shapes of the glyphs actually appearing in the line. Typographic bounds include the height of the ascenders in the font and the depth of its descenders, regardless of whether those features appear in the glyphs in a given line. Like a frame object, a line object is ready to draw. You simply set the text position in a Core Graphics context and have the line draw itself. Core Text uses the same placement strategy as Quartz, setting the origin of the text on the text baseline. In Quartz, you specify the location of text in user-space coordinates. The text matrix specifies the transform from text space to user space. The text position is stored in the tx and ty variables of the text matrix. When you first create a graphics context, it initializesthe text matrix to the identity matrix; thustext-space coordinates are initially the same as user-space coordinates. Quartz conceptually concatenates the text matrix with the current transformation matrix and other parametersfrom the graphicsstate to produce the final text-rendering matrix, that is, the matrix actually used to draw the text on the page. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 12Other Layout Objects In addition to the framesetter, frame, typesetter, and line objects, Core Text provides other objects to complete the text layout process: paragraph style, text tab, and glyph info objects. Paragraph style objects encapsulate paragraph or ruler attributes in an attributed string and are represented by the CTParagraphStyle opaque type. A paragraph style object is a complex attribute value in an attributed string, storing a number of subattributes that affect paragraph layout for the characters of the string. Among these subattributes are alignment, tab stops, writing direction, line-breaking mode, and indentation settings. The CTTextTab opaque type represents a tab stop in a paragraph style, storing an alignment type and location. The CTGlyphInfo opaque type enables you to override a font's specified mapping from Unicode to the glyph ID. Font Objects Font objects are those Core Text objects dealing directly with fonts: the font reference itself, font descriptor objects, and font collection objects. Fonts Fonts provide assistance in laying out glyphs relative to one another and are used to establish the current font when drawing in a graphics context. The Core Text font opaque type (CTFont) is a specific font instance that encapsulates a lot of information. Its reference type, CTFontRef, is toll-free bridged with NSFont. When you create a CTFont object, you typically specify (or use a default) pointsize and transformation matrix, which gives the font instance specific characteristics. You can then query the font object for many kinds of information about the font at that particular point size, such as character-to-glyph mapping, encodings, font metric data, and glyph data, among other things. Font metrics are parameters such as ascent, descent, leading, cap height, x-height, and so on. Glyph data includes parameters such as bounding rectangles and glyph advances. There are many ways to create font references. The preferred method is from a font descriptor using CTFontCreateWithFontDescriptor. You can also use a number of conversion APIs, depending on what you have to start with. For example, you can use the PostScript name of the typeface (CTFontCreateWithName), an ATS font reference (CTFontCreateWithPlatformFont), a Core Graphics font reference (CTFontCreateWithGraphicsFont), or a QuickDraw font reference (CTFontCreateWithQuickdrawInstance). There’s also CTFontCreateUIFontForLanguage, which creates a reference for the user-interface font for the application you’re using in the localization you’re using. Core Text font references provide a sophisticated, automatic font-substitution mechanism called font cascading. This mechanism takes font traits into account, so it does a better job than previous schemes of picking an appropriate font to substitute for a missing font. Font cascading is based on cascade lists, which are arrays of ordered font descriptors. There is a system default cascade list (which is polymorphic, based on the user's language setting and current font) and a font cascade list that is specified at font creation time. Using the Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 13information in the font descriptors, the cascading mechanism can match fonts according to style as well as matching characters. The CTFontCreateForString function uses cascade lists to pick an appropriate font to encode a given string. You specify and retrieve font cascade lists using the kCTFontCascadeListAttribute property. Font Descriptors Font descriptors, represented by the CTFontDescriptor opaque type, provide a mechanism to describe a font completely with a dictionary of attributes. CTFontDescriptorRef istoll-free bridged to NSFontDescriptor. The attributes are properties such as PostScript name, family, and style, and traits such as bold, italic, and monospace. The font descriptor can then be used to create or modify a CTFont object. Font descriptors can be serialized and stored in a document to provide persistence for fonts. Figure 1-5 illustrates the font system using a font descriptor to create a specific font instance. Figure 1-5 Creating a font from a font descriptor Font System CTFontDescriptor CTFont A font descriptor can also be considered as a query into the font system. You can create a font descriptor with an incomplete specification, that is, with one or just a few values in the attribute dictionary, and the system will choose the most appropriate font from those available. The system can also give you a complete list of font descriptors matching your query via CTFontDescriptorCreateMatchingFontDescriptors. Font Collections Font collections are unions of font descriptors, that is, groups of font descriptors taken as a single object. A font collection is represented by the CTFontCollection opaque type. Font collections provide the capabilities of font enumeration, accessto global and custom font collections, and accessto the font descriptors comprising the collection. You can, for example, create a font collection of all the fonts available in the system by calling CTFontCollectionCreateFromAvailableFonts, and you can use the collection to obtain an array of all of the member font descriptors. There is also a function that takes a callback parameter used to sort the returned array of font descriptors. Core Text Overview Core Text Objects 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 14This chapter describes some common text-layout and font-handling operations and shows, through portions of sample code, how they can be accomplished using Core Text. In addition to the code fragments in this chapter, see the following sample code applications that use Core Text: ● CoreTextTest shows how to use Core Text to typeset blocks of text with varying attributes in the context of a complete Carbon application. ● CoreTextArcCocoa illustrates the use of Core Text fonts, lines, and runs in a Cocoa application that sets type along an arched path. Simple Paragraphs One of the most common operations in typesetting is laying out a multiline paragraph within an arbitrarily sized rectangular area. Core Text makes this operation easy, requiring only a few lines of Core Text–specific code. To lay out the paragraph, you need a graphics context to draw into, a rectangular path to provide the area where the text is laid out, and an attributed string. Most of the code in this example is required to create and initialize the context, path, and string. After that is done, Core Text requires only three lines of code to do the layout. Listing 2-1 uses Cocoa to simplify initialization of the graphics context. To see how that operation is done in Carbon, see the CoreTextTest sample code or “Graphics Contexts“ in the Quartz 2D Programming Guide . Listing 2-1 Typesetting a simple paragraph // Initialize a graphics context and set the text matrix to a known value. CGContextRef context = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGContextSetTextMatrix(context, CGAffineTransformIdentity); // Initialize a rectangular path. CGMutablePathRef path = CGPathCreateMutable(); CGRect bounds = CGRectMake(10.0, 10.0, 200.0, 200.0); CGPathAddRect(path, NULL, bounds); 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 15 Common Operations// Initialize an attributed string. CFStringRef string = CFSTR("We hold this truth to be self-evident, that everyone is created equal."); CFMutableAttributedStringRef attrString = CFAttributedStringCreateMutable(kCFAllocatorDefault, 0); CFAttributedStringReplaceString (attrString, CFRangeMake(0, 0), string); // Create a color and add it as an attribute to the string. CGColorSpaceRef rgbColorSpace = CGColorSpaceCreateDeviceRGB(); CGFloat components[] = { 1.0, 0.0, 0.0, 0.8 }; CGColorRef red = CGColorCreate(rgbColorSpace, components); CGColorSpaceRelease(rgbColorSpace); CFAttributedStringSetAttribute(attrString, CFRangeMake(0, 50), kCTForegroundColorAttributeName, red); // Create the framesetter with the attributed string. CTFramesetterRef framesetter = CTFramesetterCreateWithAttributedString(attrString); CFRelease(attrString); // Create the frame and draw it into the graphics context CTFrameRef frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(0, 0), path, NULL); CFRelease(framesetter); CTFrameDraw(frame, context); CFRelease(frame); Simple Text Labels Another very common typesetting operation is drawing a single line of text to use as a label for a user-interface element. In Core Text thisrequires only two lines of code, one to create the line object with an attributed string and another to draw the line into a graphic context. Common Operations Simple Text Labels 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 16Listing 2-2 omits initialization of the plain text string, font, and graphics context, but it shows how to create an attributes dictionary and use it to create the attributed string. To see how to create a Core Text font, see “Font Creation and Storage” (page 21). Listing 2-2 Typesetting a simple text label CFStringRef string; CTFontRef font; CGContextRef context; // Initialize string, font, and context CFStringRef keys[] = { kCTFontAttributeName }; CFTypeRef values[] = { font }; CFDictionaryRef attributes = CFDictionaryCreate(kCFAllocatorDefault, (const void**)&keys, (const void**)&values, sizeof(keys) / sizeof(keys[0]), &kCFTypeDictionaryCallBacks, &kCFTypeDictionaryValueCallbacks); CFAttributedStringRef attrString = CFAttributedStringCreate(kCFAllocatorDefault, string, attributes); CFRelease(string); CFRelease(attributes); CTLineRef line = CTLineCreateWithAttributedString(attrString); // Set text position and draw the line into the graphics context CGContextSetTextPosition(context, 10.0, 10.0); CTLineDraw(line, context); CFRelease(line); Columnar Layout Laying out text in multiple columns is another common typesetting operation. Strictly speaking, Core Text itself only performs the layout of one column at a time and does not calculate the column sizes or locations. You do those operations before calling Core Text to lay out the text within the rectangular path area you’ve calculated. In this sample, Core Text, in addition to laying out the text in each column, also provides the subrange within the text string for each column. Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 17Listing 2-3 mixes Cocoa method calls in Objective-C with function calls into Carbon frameworks and Core Text. It includes an implementation of the drawRect: method of NSView, which calls the local createColumns function, defined first in this listing. This code resides in an NSView subclass in a Cocoa document-based application. The NSView subclassincludes an attributedString accessor method, which is notshown here but is called in this listing to return the attributed string to be laid out. Listing 2-3 Performing columnar text layout - (CFArrayRef)createColumns { CGRect bounds = CGRectMake(0, 0, NSWidth([self bounds]), NSHeight([self bounds])); int column; CGRect* columnRects = (CGRect*)calloc(_columnCount, sizeof(*columnRects)); // Start by setting the first column to cover the entire view. columnRects[0] = bounds; // Divide the columns equally across the frame's width. CGFloat columnWidth = CGRectGetWidth(bounds) / _columnCount; for (column = 0; column < _columnCount - 1; column++) { CGRectDivide(columnRects[column], &columnRects[column], &columnRects[column + 1], columnWidth, CGRectMinXEdge); } // Inset all columns by a few pixels of margin. for (column = 0; column < _columnCount; column++) { columnRects[column] = CGRectInset(columnRects[column], 10.0, 10.0); } // Create an array of layout paths, one for each column. CFMutableArrayRef array = CFArrayCreateMutable(kCFAllocatorDefault, _columnCount, &kCFTypeArrayCallBacks); for (column = 0; column < _columnCount; column++) { CGMutablePathRef path = CGPathCreateMutable(); CGPathAddRect(path, NULL, columnRects[column]); CFArrayInsertValueAtIndex(array, column, path); CFRelease(path); Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 18} free(columnRects); return array; } - (void)drawRect:(NSRect)rect { // Draw a white background. [[NSColor whiteColor] set]; [NSBezierPath fillRect:[self bounds]]; // Initialize the text matrix to a known value. CGContextRef context = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGContextSetTextMatrix(context, CGAffineTransformIdentity); CTFramesetterRef framesetter = CTFramesetterCreateWithAttributedString( (CFAttributedStringRef)[self attributedString]); CFArrayRef columnPaths = [self createColumns]; CFIndex pathCount = CFArrayGetCount(columnPaths); CFIndex startIndex = 0; int column; for (column = 0; column < pathCount; column++) { CGPathRef path = (CGPathRef)CFArrayGetValueAtIndex(columnPaths, column); // Create a frame for this column and draw it. CTFrameRef frame = CTFramesetterCreateFrame(framesetter, CFRangeMake(startIndex, 0), path, NULL); CTFrameDraw(frame, context); // Start the next frame at the first character not visible in this frame. CFRange frameRange = CTFrameGetVisibleStringRange(frame); startIndex += frameRange.length; Common Operations Columnar Layout 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 19CFRelease(frame); } CFRelease(columnPaths); } Manual Line Breaking You usually don't need to do manual line breaking unless you have a special hyphenation process or a similar requirement. A framesetter performs line breaking automatically. Listing 2-4 shows how to create a typesetter, an object used by the framesetter, and use it directly to find appropriate line breaks and create a typeset line manually. This sample also shows how to center the line before drawing. Listing 2-4 Performing manual line breaking double width; CGContextRef context; CGPoint textPosition; CFAttributedStringRef attrString; // Initialize those variables. // Create a typesetter using the attributed string. CTTypesetterRef typesetter = CTTypesetterCreateWithAttributedString(attrString); // Find a break for line from the beginning of the string to the given width. CFIndex start = 0; CFIndex count = CTTypesetterSuggestLineBreak(typesetter, start, width); // Use the returned character count (to the break) to create the line. CTLineRef line = CTTypesetterCreateLine(typesetter, CFRangeMake(start, count)); // Get the offset needed to center the line. float flush = 0.5; // centered double penOffset = CTLineGetPenOffsetForFlush(line, flush, width); // Move the given text drawing position by the calculated offset and draw the line. CGContextSetTextPosition(context, textPosition.x + penOffset, textPosition.y); CTLineDraw(line, context); Common Operations Manual Line Breaking 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 20// Move the index beyond the line break. start += count; Font Creation and Storage The example function in Listing 2-5 creates a font descriptor from a PostScript font name and a float specifying the point size. Listing 2-5 Creating a font descriptor from a name and point size CTFontDescriptorRef CreateFontDescriptorFromName(CFStringRef iPostScriptName, CGFloat iSize) { assert(iPostScriptName != NULL); return CTFontDescriptorCreateWithNameAndSize(iPostScriptName, iSize); } The example function in Listing 2-6 creates a font descriptor from a font family name and font traits. Listing 2-6 Creating a font descriptor from a family and traits CTFontDescriptorRef CreateFontDescriptorFromFamilyAndTraits(CFStringRef iFamilyName, CTFontSymbolicTraits iTraits, CGFloat iSize) { CTFontDescriptorRef descriptor = NULL; CFMutableDictionaryRef attributes; assert(iFamilyName != NULL); // Create a mutable dictionary to hold our attributes. attributes = CFDictionaryCreateMutable(kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); check(attributes != NULL); if (attributes != NULL) { CFMutableDictionaryRef traits; Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 21CFNumberRef symTraits; // Add a family name to our attributes. CFDictionaryAddValue(attributes, kCTFontFamilyNameAttribute, iFamilyName); // Create the traits dictionary. symTraits = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &iTraits); check(symTraits != NULL); if (symTraits != NULL) { // Create a dictionary to hold our traits values. traits = CFDictionaryCreateMutable(kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); check(traits != NULL); if (traits != NULL) { // Add the symbolic traits value to the traits dictionary. CFDictionaryAddValue(traits, kCTFontSymbolicTrait, symTraits); // Add the traits attribute to our attributes. CFDictionaryAddValue(attributes, kCTFontTraitsAttribute, traits); CFRelease(traits); } CFRelease(symTraits); } // Create the font descriptor with our attributes and input size. descriptor = CTFontDescriptorCreateWithAttributes(attributes); check(descriptor != NULL); CFRelease(attributes); } // Return our font descriptor. return descriptor; Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 22} The example function in Listing 2-7 creates a font from a provided font descriptor. It calls CTFontCreateWithFontDescriptor, passing NULL for the matrix parameter to specify the default (identity) matrix. Listing 2-7 Creating a font from a font descriptor CTFontRef CreateFont(CTFontDescriptorRef iFontDescriptor, CGFloat iSize) { check(iFontDescriptor != NULL); // Create the font from the font descriptor and input size. Pass // NULL for the matrix parameter to use the default matrix (identity). return CTFontCreateWithFontDescriptor(iFontDescriptor, iSize, NULL); } The example function in Listing 2-8 creates XML data to serialize a font for embedding in a document. Alternatively, and preferably, NSArchiver could be used. This is just one way to accomplish this task, but it preserves all data from the font needed to re-create the exact font at a later time. Listing 2-8 Serializing a font CFDataRef CreateFlattenedFontData(CTFontRef iFont) { CFDataRef result = NULL; CTFontDescriptorRef descriptor; CFDictionaryRef attributes; check(iFont != NULL); // Get the font descriptor for the font. descriptor = CTFontCopyFontDescriptor(iFont); check(descriptor != NULL); if (descriptor != NULL) { Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 23// Get the font attributes from the descriptor. This should be enough // information to recreate the descriptor and the font later. attributes = CTFontDescriptorCopyAttributes(descriptor); check(attributes != NULL); if (attributes != NULL) { // If attributes are a valid property list, directly flatten // the property list. Otherwise we may need to analyze the attributes // and remove or manually convert them to serializable forms. // This is left as an exercise for the reader. if (CFPropertyListIsValid(attributes, kCFPropertyListXMLFormat_v1_0)) { result = CFPropertyListCreateXMLData(kCFAllocatorDefault, attributes); check(result != NULL); } } } return result; } The example function in Listing 2-9 creates a font reference from flattened XML data. Itshows how to unflatten font attributes and create a font with those attributes. Listing 2-9 Creating a font from serialized data CTFontRef CreateFontFromFlattenedFontData(CFDataRef iData) { CTFontRef font = NULL; CFDictionaryRef attributes; CTFontDescriptorRef descriptor; check(iData != NULL); // Create our font attributes from the property list. We will create // an immutable object for simplicity, but if you needed to massage Common Operations Font Creation and Storage 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 24// the attributes or convert certain attributes from their serializable // form to the Core Text usable form, you could do it here. attributes = (CFDictionaryRef)CFPropertyListCreateFromXMLData(kCFAllocatorDefault, iData, kCFPropertyListImmutable, NULL); check(attributes != NULL); if (attributes != NULL) { // Create the font descriptor from the attributes. descriptor = CTFontDescriptorCreateWithAttributes(attributes); check(descriptor != NULL); if (descriptor != NULL) { // Create the font from the font descriptor. We will use // 0.0 and NULL for the size and matrix parameters. This // causes the font to be created with the size and/or matrix // that exist in the descriptor, if present. Otherwise default // values are used. font = CTFontCreateWithFontDescriptor(descriptor, 0.0, NULL); check(font != NULL); } } return font; } Accessing Font Metrics For every font, glyph designers provide a set of measurements, called metrics, which describe the spacing around each glyph in the font. The typesetter uses these metrics to determine glyph placement. Font metrics are parameters such as ascent, descent, leading, cap height, x-height, and so on. The sample functionsin thissection illustrate how to query a font for itsfont metric data. The example function in Listing 2-10 shows how to use line metrics accessors to calculate the line height for a font. In most cases you should not need to do this yourself. If you have a CTLineRef object for a line of text , you could call CTLineGetTypographicBounds to get the line metrics for the line. Common Operations Accessing Font Metrics 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 25Listing 2-10 Calculating line height CGFloat GetLineHeightForFont(CTFontRef iFont) { CGFloat lineHeight = 0.0; check(iFont != NULL); // Get the ascent from the font, already scaled for the font's size lineHeight += CTFontGetAscent(iFont); // Get the descent from the font, already scaled for the font's size lineHeight += CTFontGetDescent(iFont); // Get the leading from the font, already scaled for the font's size lineHeight += CTFontGetLeading(iFont); return lineHeight; } The example function in Listing 2-11 demonstrates how to get glyphsfor the charactersin a string with a single font. Most of the time you should just use a CTLine object to get this information because one font may not encode the entire string. In addition, simple character-to-glyph mapping will not get the correct appearance for complex scripts. Thissimple glyph mapping may be appropriate if you are trying to display specific Unicode characters for a font. Listing 2-11 Getting glyphs for characters void GetGlyphsForCharacters(CTFontRef iFont, CFStringRef iString) { UniChar *characters; CGGlyph *glyphs; CFIndex count; assert(iFont != NULL && iString != NULL); Common Operations Accessing Font Metrics 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 26// Get our string length. count = CFStringGetLength(iString); // Allocate our buffers for characters and glyphs. characters = (UniChar *)malloc(sizeof(UniChar) * count); assert(characters != NULL); glyphs = (CGGlyph *)malloc(sizeof(CGGlyph) * count); assert(glyphs != NULL); // Get the characters from the string. CFStringGetCharacters(iString, CFRangeMake(0, count), characters); // Get the glyphs for the characters. CTFontGetGlyphsForCharacters(iFont, characters, glyphs, count); // Do something with the glyphs here, if a character is unmapped // Free our buffers free(characters); free(glyphs); } Creating Related Fonts The example functions in this section show how to query fonts for their attributes. The example function in Listing 2-12 makes a font bold or unbold based on the value of the Boolean parameter passed with the function call. If the current font family does not have the requested style, the function returns NULL. Listing 2-12 Changing traits of a font CTFontRef CreateBoldFont(CTFontRef iFont, Boolean iMakeBold) { CTFontSymbolicTraits desiredTrait = 0; Common Operations Creating Related Fonts 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 27CTFontSymbolicTraits traitMask; // If we are trying to make the font bold, set the desired trait // to be bold. if (iMakeBold) desiredTrait = kCTFontBoldTrait; // Mask off the bold trait to indicate that it is the only trait // desired to be modified. As CTFontSymbolicTraits is a bit field, // we could choose to change multiple traits if we desired. traitMask = kCTFontBoldTrait; // Create a copy of the original font with the masked trait set to the // desired value. If the font family does not have the appropriate style, // this will return NULL. return CTFontCreateCopyWithSymbolicTraits(iFont, 0.0, NULL, desiredTrait, traitMask); } The example function in Listing 2-13 converts a given font to a similar font in another font family, preserving traits if possible. It may return NULL. Listing 2-13 Converting a font to another family CTFontRef CreateFontConvertedToFamily(CTFontRef iFont, CFStringRef iFamily) { // Create a copy of the original font with the new family. This call // attempts to preserve traits, and may return NULL if that is not possible. // Pass in 0.0 and NULL for size and matrix to preserve the values from // the original font. return CTFontCreateCopyWithFamily(iFont, 0.0, NULL, iFamily); } Common Operations Creating Related Fonts 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 28This table describes the changes to Core Text Programming Guide . Date Notes 2010-03-03 Added this document for iOS 3.2. 2010-01-20 Removed links to deprecated documents and sample code. Revised Figure 1-3 "Text layout data flow" to show that a CGPath object is provided in the creation of a CTFrame object. 2008-06-09 2008-02-08 Fixed bad link to sample code in Introduction. 2007-12-11 Made minor editorial corrections. New document that explains how to perform text layout and font-related operations using the Core Text programming interfaces. 2007-07-16 2010-03-03 | © 2010 Apple Inc. All Rights Reserved. 29 Document Revision HistoryApple Inc. © 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, Mac, Macintosh, Objective-C, OS X, Quartz, and QuickDraw 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. 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. OpenCL Programming Guide for MacContents About Open CL for OS X 7 At a Glance 7 Prerequisites 8 See Also 8 Developing OpenCL Programs Using Xcode 9 Concepts 9 Essential Development Tasks 11 Hello World! 12 Creating An Application That Uses OpenCL In Xcode 12 Compiling From the Command Line 18 Debugging 19 Basic Programming Sample 20 Basic Kernel Code Sample 20 Basic Host Code Sample 21 Identifying Parallelizable Routines 29 Using Grand Central Dispatch With OpenCL 32 Discovering Available Compute Devices 32 Enqueueing A Kernel To A Dispatch Queue 33 Determining the Characteristics Of A Kernel On A Device 34 Obtaining the Kernel’s Workgroup Size 35 Sample Code: Creating a Dispatch Queue 37 Creating and Managing Memory Objects in OS X OpenCL 43 Overview 43 Workflow 43 Memory Visibility 44 Memory Consistency 46 Creating and Using Buffers in OpenCL 46 Representing Data With Buffer Objects 46 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 2Allocating Memory For Buffer Objects In OS X v10.7 47 Reading, Writing, and Copying Buffer Objects 48 Kernel Support For Data Processing In OpenCL-C 48 Releasing Buffer Objects 49 Setting the finalizer 49 Example: Allocating, Using, Releasing Buffer Objects 50 Creating and Using Images in OpenCL 54 Image Objects 54 Example 59 IOSurface and GL: What OpenCL Supports 64 How the Kernel Interacts With Data 64 Passing Data To a Kernel 64 Accessing Buffer Objects From a Kernel 64 Retrieving Results From a Kernel 65 OpenCL/ OpenGL Interoperation: Data Sharing 66 Sharegroups 67 Synchronizing Access To Shared OpenCL/OpenGL Objects 68 Example 68 Controlling OpenCL/OpenGL Interoperation With GCD 69 Using GCD To Synchronize A Host With OpenCL 69 Synchronizing A Host With OpenCL Using A Dispatch Semaphore 70 Synchronizing Multiple Queues 75 Using IOSurfaces With OpenCL 76 Creating Or Obtaining An IOSurface 76 Creating An Image Object from An IOSurface 76 Sharing the IOSurface With An OpenCL Device 77 Autovectorizer 79 Features 79 Without the Autovectorizer 79 Writing Optimal Code For the CPU: Let the autovectorizer do the work for you 81 Do 81 Don’t 81 What the autovectorizer does 81 Vectorization Example 81 Xcode 81 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsImproving Performance 82 Before Optimizing Code 82 Reducing Overhead 82 Measuring Performance 86 Measuring Performance On the Host 86 Measuring Performance On Devices 86 Estimating Optimal Performance 87 Tuning OpenCL Code For the CPU 89 In Practice 90 Tuning OpenCL Code For the GPU 99 In Practice 100 Document Revision History 108 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures, Tables, and Listings Developing OpenCL Programs Using Xcode 9 Figure 1-1 OpenCL Development Process 11 Hello World! 12 Figure 2-1 A simple OpenCL kernel in Xcode 12 Figure 2-2 Build settings for kernel files 13 Figure 2-3 OpenCL host code in Xcode 16 Figure 2-4 Adding the OpenCL framework 17 Figure 2-5 OpenCL framework was added 17 Figure 2-6 Results 18 Basic Programming Sample 20 Listing 3-1 Kernel code sample 20 Listing 3-2 Host code sample 21 Identifying Parallelizable Routines 29 Listing 4-1 Pseudocode that computes the final grade for each student 29 Listing 4-2 The isolated grade average task 30 Using Grand Central Dispatch With OpenCL 32 Listing 5-1 Creating a dispatch queue 37 Listing 5-2 Obtaining workgroup information 40 Creating and Managing Memory Objects in OS X OpenCL 43 Figure 6-1 Physical memory of an OpenCL system 45 Listing 6-1 Sample host function creates buffers then calls kernel function 50 Listing 6-2 Sample kernel squares an input array 54 Listing 6-3 Creating a 2D image object 55 Listing 6-4 An image-processing kernel function 58 Listing 6-5 Sample host function creates images then calls kernel function 59 Listing 6-6 Sample kernel swaps the red and green channels 63 OpenCL/ OpenGL Interoperation: Data Sharing 66 Figure 7-1 OpenGL and OpenCL share data using sharegroups 67 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 5Controlling OpenCL/OpenGL Interoperation With GCD 69 Figure 8-1 Rendering loop - each pass on the main thread creates a new frame for display 71 Listing 8-1 Synchronizing the host with OpenCL processing 70 Listing 8-2 Synchronizing a host with OpenCL using a dispatch semaphore 71 Listing 8-3 Synchronizing multiple queues 75 Using IOSurfaces With OpenCL 76 Listing 9-1 Creating an IOSurface-backed CL Image 77 Listing 9-2 Extracting an Image From an IOSurface 77 Autovectorizer 79 Figure 10-1 Before autovectorization: A simple float sent to the CPU and the GPU 80 Listing 10-1 Passing single floats into a kernel 80 Improving Performance 82 Figure 11-1 Memory copy speed in GB/s (read+write) vs buffer size 88 Table 11-1 Benchmarks of boxAvgH5 variants: 103 Table 11-2 Benchmarks of boxAvgH5 variants where each work item processes 4 columns: 106 Listing 11-1 Using the gettimeofday function 86 Listing 11-2 Sample benchmarking loop on the kernel 87 Listing 11-3 Kernel for estimating performance 87 Listing 11-4 The boxAvg kernel in two passes 91 Listing 11-5 Modify the horizontal pass to compute one row per work item instead of one pixel 92 Listing 11-6 Modify the algorithm to read fewer values per pixel and to incrementally update the sum 94 Listing 11-7 Modify the horizontal pass by moving division and conditionals out of the inner loop 95 Listing 11-8 Modify vertical pass to combine rows; each work item computes a block of rows 96 Listing 11-9 Ensure the image width is always a multiple of 4 97 Listing 11-10 A safer variant that will work for any image width 97 Listing 11-11 Fused kernel 98 Listing 11-12 Kernel before optimization 101 Listing 11-13 Move the data to local memory 102 Listing 11-14 Modify the kernel to compute several rows in each work item 103 Listing 11-15 Provide a dedicated kernel for each value of RANGE 104 Listing 11-16 Fastest variant: Unroll the inner loop and convert float data to float4 106 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 6 Figures, Tables, and ListingsOpenCL™ (Open Computing Language) is an open standard for cross-platform, parallel programming of modern processors such as multicore CPUs and programmable GPUs. Introduced with OS X v10.6, OpenCL lets your application tap into the parallel computing power of these processors to improve performance and deliver features made possible by compute-intensive algorithms. OpenCL is comprised of thee parts: a C99-based kernel programing language, a powerful scheduling API and a runtime that efficiently executes kernels on the CPU or GPU. Going beyond the standard, OS X v10.7 adds integration between OpenCL, Grand Central Dispatch and Xcode making it even easer take advantage of the power of the OpenCL in your application. At a Glance Using OpenCL is easier than ever in OS X v10.7: ● OpenCL is fully supported by Xcode. The Xcode offline compiler removes a configuration step that used to have to be performed before the kernel could be run and aids in debugging earlier in the development process. See “Hello World!” (page 12). ● You can write OpenCL functions in separate files and include them in your Xcode project. These files can be compiled as your application is built. This improves application performance because kernels need not be compiled when the application is running ● OpenCL now integrates with Grand Central Dispatch, making it easier for you to focus on making your OpenCL kernels more efficient. See “Using Grand Central Dispatch With OpenCL” (page 32). ● The autovectorizer is used for compiling kernels that will run on the CPU. It accelerates performance up to four times without additional effort. The autovectorizer allows you to write one kernel that runs efficiently on both a CPU and a GPU. It is invoked regardless of whether the openclc compiler is called from Xcode or if the kernel is built at runtime. See “Autovectorizer” (page 79). ● You can, of course, continue to use code you’ve already written to the OpenCL 1.1 standard. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 7 About Open CL for OS XPrerequisites This guide assumes that you program in C and have access to The OpenCL Specification . Although this guide discusses many key OpenCL API functions, it does not provide detailed information on the OpenCL API or the OpenCL-C programming language. See Also The OpenCL Specification , available from the Khronos Group at http://www.khronos.org/registry/cl/ provides information on the OpenCL standard. The OpenCL Programming Guide by Aaftab Munshi, Benedict Gaster, Timothy G. Mattson, James Fung, and Dan Ginsburg, available from Pearson Education, Inc. For more information about Grand Central Dispatch queues, see Concurrency Programming Guide: Dispatch Queues. About Open CL for OS X Prerequisites 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 8This chapter describes a streamlined process in which, using tools provided by OS X v10.7, you can include OpenCL kernels as resources in Xcode projects, compile them along with the rest of your application, and use Grand Central Dispatch as the queuing API for executing OpenCL commands and kernels on the CPU and GPU. If you need to create OpenCL programs at run-time, with source loaded as a string or from a file, or if you want API-level control over queueing, see The OpenCL Specification , available from the Khronos Group at http://www.khronos.org/registry/cl/. Concepts In the OpenCL specification, computational processors are called devices. An OpenCL device has one or more compute units. A workgroup executes on a single compute unit. A compute unit is composed of one or more processing elements and local memory. A Macintosh computer has a single CPU and GPUs. The CPU on a Macintosh has multiple compute units, which is why it is called a multi-core CPU. The number of compute units in a CPU limits the number of workgroups that can execute concurrently. CPUs commonly contain two to eight compute units, with the maximum increasing year-to-year. A graphics processing unit (GPU) typically contains many compute units—the GPUs in current Macintosh systems feature tens of compute units, and future GPUs may contain hundreds. As used by OpenCL, a CPU with eight compute units is considered a single device, as is a GPU with 100 compute units. The OS X v10.7 implementation of the OpenCL API facilitates designing and coding data parallel programs to run on both CPU and GPU devices. In a data parallel program, the same program (or kernel) runs concurrently on different pieces of data and each invocation is called a work item and given a work item ID. The work item IDs are organized in up to three dimensions (called an N-D range). A kernel is essentially a function written in the OpenCL language that enables it to be compiled for execution on any device thatsupports OpenCL. Although kernels are enqueued for execution by host applications written in C, C++, or Objective C, a kernel must be compiled separately to be customized for the device on which it is going to run. You can write your OpenCL kernel source code in a separate file or include it inline in your host application source code. OpenCL kernels can be: 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 9 Developing OpenCL Programs Using Xcode● Compiled at compile time, then run when queued by the host application or ● Compiled and then run at runtime when queued by the host application or ● Run from a previously-built binary A work item is a parallel execution of a kernel on some data. It is analogousto a thread. Each kernel is executed upon hundreds of thousands of work items A workgroup is set of work items. Each workgroup is executed on a compute unit. Workgroup dimensions determine how the input is operated upon in parallel. The application usually specifies the dimensions based on the size of the input. There are constraints: for example, there may be a maximum number of work items that can be launched for a certain kernel on a certain device. The program that calls OpenCL functions to set up the context in which kernels run and enqueue the kernels for execution is known asthe host application. The application isrun by OS X on the CPU. The device on which the host application executes is known as the host device. Before kernels can be run, the host application typically completes the following steps: 1. Determine what compute devices are available, if necessary. 2. Select compute devices appropriate for the application. 3. Create dispatch queues for selected compute devices. 4. Allocate the memory objects needed by the kernels for execution. (This step may occur earlier in the process, as convenient.) Note that the host device (the CPU) can itself be an OpenCL device and can be used to execute kernels. The host application can enqueue commands to read from and write to memory objects. See “Creating and Managing Memory Objects in OS X OpenCL” (page 43). Memory objects are used to manipulate device memory. There are two types of memory objects used in OpenCL: buffer objects and image objects. Buffer objects can contain any type of data; image objects contain data organized into pixels in a given format. Developing OpenCL Programs Using Xcode Concepts 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 10Essential Development Tasks In OS X v10.7, the OpenCL development process includes these major steps: Figure 1-1 OpenCL Development Process Step 1: Parallelize. Step 2: Code kernel. Step 3: Code host. Step 4: Compile. Step 5: Execute. Step 6: Debug. Step 7: Optimize. 1. Identify the tasks to be parallelized. Determining how to parallelize your program effectively is often the hardest part of developing an OpenCL program. See “Identifying Parallelizable Routines” (page 29). 2. In Xcode, write your kernel functions. See “Basic Kernel Code Sample” (page 20). 3. In Xcode, write the host code that will be calling the kernel(s). See “Basic Host Code Sample” (page 21). 4. Compile using Xcode. See “Creating An Application That Uses OpenCL In Xcode” (page 12). 5. Execute. 6. Debug (if necessary). See “Debugging” (page 19). 7. Improve performance (if necessary). See “Improving Performance” (page 82). Developing OpenCL Programs Using Xcode Essential Development Tasks 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 11Creating an OpenCL program in OS X v10.7 is easy with support built into Xcode. This chapter describes step-by-step how to create an OpenCL project in Xcode. If you already have a working OpenCL project, you need not regenerate it, but you can find information in this chapter about support for OpenCL now built into Xcode. Creating An Application That Uses OpenCL In Xcode To create a project that uses OpenCL in OS X v10.7: 1. Create your OpenCL project in Xcode as a new OS X project (empty is fine). 2. Place your kernel code in one or more .cl files in your Xcode project. You can place all your kernels into a single .cl file, or you can separate them as you choose. You can also include non-kernel code that will run on the same OpenCL device as the kernel in each .cl file. Each .cl file is compiled by default into three files containing bitcode for i386, x86_64, and gpu_32 architectures. You can change this using the OpenCL Architectures Build Setting.) At runtime your host application discovers what kind(s) of devices are available, and determines which of the compiled kernels to enqueue and execute. Figure 2-1 A simple OpenCL kernel in Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 12 Hello World!3. You can set the following build settings for your kernel (.cl) files: Figure 2-2 Build settings for kernel files ● OpenCL Compiler Version ● Compiler Version The OpenCL C compiler version supported by the platform. The default is OpenCL C 1.1. To set this parameter from the command line, use: -cl-std=CL1.1 ● OpenCL - Architectures ● Valid Architectures A StringList specifying the list of the architectures for which the product will be built. This is usually set to a predefined build setting provided by the platform. The default is that the product is built for all three architectures. To set this parameter from the command line, use: ● -triple i386-applecl-darwin ● -triple x86_64-applecl-darwin ● -triple gpu_32-applecl-darwin (So to compile for the first two, the command line would read: -triple i386-applecl-darwin -triple x86_64-applecl-darwin ● OpenCL - Preprocessing ● Preprocessor Macros Space-separated list of preprocessor macros of the form "foo" or "foo=bar". To set this parameter from the command line, use: -D Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 13● OpenCL - Code Generation ● Use MAD Boolean. If true, allow expressions of the type a * b + c to be replaced by a Multiply-Add (MAD) instruction. If MAD is enabled, multistep instructions in the form a * b + c are performed in a single step, but the accuracy of the results may be compromised. For example, to optimize performance, some OpenCL devices implement MAD by truncating the result of the a * b operation before adding it to c. The default for this parameter is NO. To set this parameter from the command line, use: -cl-mad-enable ● Relax IEEE Compliance Boolean. If true, allows optimizations for floating-point arithmetic that may violate the IEEE 754 standard and the OpenCL numerical compliance requirements defined in in section 7.4 for single-precision floating-point, section 9.3.9 for double-precision floating-point, and edge case behavior in section 7.5 of the OpenCL 1.1 specification. This is intended to be a performance optimization. This option causes the preprocessor macro __FAST_RELAXED_MATH__ to be defined in the OpenCL program. The default is NO. To set this parameter from the command line, use: -cl-fast-relaxed-math ● Double as single Boolean. If true, double precision floating-point expressions are treated as single precision floating-point expressions. This option is available for GPUs only. The default is NO. To set this parameter from the command line, use: -cl-double-as-single ● Flush denorms to zero Boolean that controls how single precision and double precision denormalized numbers are handled. Ifspecified as a build option, the single precision denormalized numbers may be flushed to zero; double precision denormalized numbers may also be flushed to zero if the optional extension for double precision is supported. This is intended to be a performance hint and the OpenCL compiler can choose not to flush denorms to zero if the device supports single precision (or double precision) denormalized numbers. This option isignored forsingle precision numbersif the device does notsupportsingle precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_SINGLE_FP_CONFIG. This option isignored for double precision numbersif the device does notsupport double precision or if it does support double precision but not double precision denormalized numbers i.e. CL_FP_DENORM bit is not set in CL_DEVICE_DOUBLE_FP_CONFIG. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 14This flag only applies for scalar and vector single precision floating-point variables and computations on these floating-point variables inside a program. It does not apply to reading from or writing to image objects. The default is NO. To set this parameter from the command line, use: -cl-denorms-are-zero ● Auto-vectorizer Auto-vectorizes the OpenCL kernels for the CPU. This setting takes effect only for the CPU. This makes it possible to write a single kernel that is portable and performant across CPUs and GPUs. The default is YES. To set this parameter from the command line, use: -cl-auto-vectorize-enable or -cl-autovectorize-disable ● Optimization Level You can choose whether to optimize for smallest code size or not. The default is fast O1 optimization. To set this parameter from the command line, use: ● -Os sets it to optimize for smallest code size ● -O, O1 sets it to fast ● -O2 sets it to faster ● -O3 sets it to fastest ● -O0 sets it to not optimize Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 154. Place your host code in one or more .c files in your Xcode project. Figure 2-3 OpenCL host code in Xcode 5. Link to the OpenCL framework. a. Click on the target. b. Click the Build Phases tab. c. Open Link Binary With Libraries. d. Click the + sign. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 16e. Select OpenCL.framework from the dropdown. Figure 2-4 Adding the OpenCL framework f. Press Add. Figure 2-5 OpenCL framework was added 6. Build. Hello World! Creating An Application That Uses OpenCL In Xcode 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 177. Run. Figure 2-6 Results See “Basic Programming Sample” (page 20) for a line-by-line description of the host and kernel code in the Hello World sample project. Compiling From the Command Line To compile from the command line, call openclc. Hello World! Compiling From the Command Line 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 18Debugging Here are a few hints to help you debug your OpenCL application: ● Run your kernel on the CPU first. There is no memory protection on GPUs. If an index goes out of bounds on the GPU, it is likely to take the whole system down. If an index goes out of bounds on the CPU, it may crash the program that’s running, but it will not take the whole system down. ● You can use the printf function from within your kernel. ● You can use the gdb debugger to look at the assembly code once you’ve built your program. See GDB website. ● On the GPU, use explicit addressrange checksto look for out-of-range address accesses. (Remember: there is no memory protection on current GPUs.) Hello World! Debugging 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 19This chapter provides a tour through the code of a simple OpenCL application that performs calculations on a test data set. The code in Listing 3-2 (page 21) calls the kernel defined in Listing 3-1 (page 20). The kernel squares each value. Once the kernel completes its work, the host validates that every value was processed by the kernel. Basic Kernel Code Sample Listing 3-1 (page 20) is example kernel code. See to download the project. Listing 3-1 Kernel code sample //////////////////////////////////////////////////////////////////////////////// // Simple OpenCL kernel that squares an input array. // This code is stored in a file called mykernel.cl. kernel void square(global float* input, global float* output) [1] { size_t i = get_global_id(0); output[i] = input[i] * input[i]; } Notes: 1. Wrap your kernel code into a kernel block: kernel void kernelName ( global float* inputParameterName, global float* [anotherInputParameter] , …, global float* outputParameterName) 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 20 Basic Programming Sample{ ... } Note: Kernels always return void. Basic Host Code Sample Listing 3-2 (page 21) is example code that would run on a host. It calls a kernel to square a set of values, then tests to ensure that the kernel processed all the data. See to download the project. Listing 3-2 Host code sample //////////////////////////////////////////////////////////////////////////////// #include #include // This include pulls in everything you need to develop with OpenCL on OS X v10.7. #include // Include the header file generated by Xcode. This header file contains the // kernel block declaration. #include "mykernel.cl.h" [1] // Hardcoded number of values to test, for convenience. #define NUM_VALUES 1024 // A utility function that checks that our kernel execution performs the // requested work over the entire range of data. static int validate(cl_float* input, cl_float* output) { int i; for (i = 0; i < NUM_VALUES; i++) { Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 21// The kernel was supposed to square each value. if ( output[i] != (input[i] * input[i]) ) { fprintf(stdout, "Error: Element %d did not match expected output.\n", i); fprintf(stdout, " Saw %1.4f, expected %1.4f\n", output[i], input[i] * input[i]); fflush(stdout); return 0; } } return 1; } int main (int argc, const char * argv[]) { int i; char name[128]; // First, try to obtain a dispatch queue that can send work to the // GPU in our system. [2] dispatch_queue_t queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // In the event that our system does NOT have an OpenCL-compatible GPU, // we can use the OpenCL CPU compute device instead. if (queue == NULL) { queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); } // This is not required, but let's print out the name of the device // we are using to do work. We could use the same function, // clGetDeviceInfo, to obtain all manner of information about the device. cl_device_id gpu = gcl_get_device_id_with_dispatch_queue(queue); clGetDeviceInfo(gpu, CL_DEVICE_NAME, 128, name, NULL); fprintf(stdout, "Created a dispatch queue using the %s\n", name); Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 22// Now we gin up some test data. This is typically the case: you have some // data in your application that you want to process with OpenCL. This // test_in buffer represents such data. Normally, this would come from // some REAL source, like a camera, a sensor, or some compiled collection // of statistics -- it just depends on the problem you want to solve. float* test_in = (float*)malloc(sizeof(cl_float) * NUM_VALUES); for (i = 0; i < NUM_VALUES; i++) { test_in[i] = (cl_float)i; } // Once the computation using CL is done, we'll want to read the results // back into our application's memory space. Allocate some space for that. float* test_out = (float*)malloc(sizeof(cl_float) * NUM_VALUES); // Our test kernel takes two parameters: an input float array and an // output float array. We can't send the application's buffers above, since // our CL device operates on its own memory space. Therefore, we allocate // OpenCL memory for doing the work. Notice that for the input array, // we specify CL_MEM_COPY_HOST_PTR and provide the fake input data we // created above. This tells OpenCL to copy over our data into its memory // space before it executes the kernel. [3] void* mem_in = gcl_malloc(sizeof(cl_float) * NUM_VALUES, test_in, CL_MEM_READ_ONLY | CL_MEM_COPY_HOST_PTR); // The output array is not initalized; we're going to fill it up when // we execute our kernel. [4] void* mem_out = gcl_malloc(sizeof(cl_float) * NUM_VALUES, NULL, CL_MEM_WRITE_ONLY); // Dispatch your kernel block using one of the dispatch_ commands and the // queue we created above. [5] dispatch_sync(queue, ^{ // Though we COULD pass NULL as the workgroup size, which would tell Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 23// OpenCL to pick the one it thinks is best, we can also ask // OpenCL for the suggested size, and pass it ourselves. [6] size_t wgs; gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(wgs), &wgs, NULL); // The N-Dimensional Range over which we'd like to execute our // kernel. In our example case, we're operating on a 1D buffer, so // it makes sense that our range is 1D. cl_ndrange range = { 1, // The number of dimensions to use. {0, 0, 0}, // The offset in each dimension. We want to // process ALL of our data, so this is 0 for // our test case. [7] {NUM_VALUES, 0, 0}, // The global range -- this is how many items // IN TOTAL in each dimension you want to // process. {workgroup_size, 0, 0} // The local size of each workgroup. This // determines the number of workitems per // workgroup. It indirectly affects the // number of workgroups, since the global // size / local size yields the number of // workgroups. So in our test case, we will // have NUM_VALUE / wgs workgroups. }; // Calling the kernel is easy; you simply call it like a function, // passing the ndrange as the first parameter, followed by the expected // kernel parameters. Note that we case the 'void*' here to the // expected OpenCL types. Remember -- if you use 'float' in your // kernel, that's a 'cl_float' from the application's perspective. [8] Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 24square_kernel(&range,(cl_float*)mem_in, (cl_float*)mem_out); // Getting data out of the device's memory space is also easy; we // use gcl_memcpy. In this case, we take the output computed by the // kernel and copy it over to our application's memory space. [9] gcl_memcpy(test_out, mem_out, sizeof(cl_float) * NUM_VALUES); }); // Now we can check to make sure our kernel really did what we asked // it to: if ( validate(test_in, test_out)) { fprintf(stdout, "All values were properly squared.\n"); } // Don't forget to free up the CL device's memory when you're done. [10] gcl_free(mem_in); gcl_free(mem_out); // And the same goes for system memory, as usual. free(test_in); free(test_out); // Finally, release your queue just as you would any GCD queue. [11] dispatch_release(queue); } Notes: Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 251. Include the header file that contains the kernel block declaration. The name of the header file for a .cl file will be the name of the .cl file with .h appended to it. For example, if the .cl file is named mykernel.cl, the header file you must include will be mykernel.cl.h. 2. Call gcl_create_dispatch_queue to create the dispatch queue. 3. Create memory objects to hold input and output data and write input data to the input objects. Allocate an array on the OpenCL device from which to read kernel results back into host memory. Use gcl_malloc and make sure to use the OpenCL size of the datatype being returned (e.g., gcl_malloc(sizeof(cl_float) * NUM_VALUES). Because the CL device operates on its own memory space, allocate OpenCL memory for the input data upon which the kernel will work. Specify CL_MEM_COPY_HOST_PTR to tell OpenCL to copy over the input data from host memory into its memory space before it executes the kernel. 4. Allocate OpenCL memory in which the kernel will store its results. 5. Dispatch your kernel block using one of the dispatch commands and the queue you created above. In your dispatch call, you can specify workgroup parameters. 6. Describe the data parallel range over which to execute the kernel. You will describe the data-parallel range for the OpenCL kernel in the host code. The cl_ndrange structure is used to specify the data parallel range. OpenCL always executes kernels in a data parallel fashion—that is, instances of the same kernel (work items) execute on different portions of the total data set. See “Representing Data With Buffer Objects” (page 46). (If you want task-parallel execution you must enqueue multiple kernels on different devices.) Each work item is responsible for executing the kernel once and operating on its assigned portion of the data set. It is your responsibility to tell OpenCL the total number of work items that you need to process all of your data. Because data sets are commonly organized in one, two, or three dimensions (representing such things as audio data streams, two- or three-dimensional images, or three-dimensional objects), you also need to indicate to OpenCL in how many dimensions your data extends (that is, how many coordinates to use for each data point). ● Determining the Data Dimensions The first step in preparing a kernel for execution is to identify the number of dimensions that you want to use to represent your data. For example, if your data represents a flat image that is m pixels wide by n pixels high, then you have a two-dimensional data set with each data pointed represented by its coordinates on the m and n axes. On the other hand, if you’re dealing with spatial data that involves the (x, y, z) position of nodes in three-dimensional space, you have a three-dimensional data set. Another way to look at the dimensionality of your data is in terms of nested loops in a traditional, non-parallel processing model. If you can loop through your entire data set with a single loop, then your data is one-dimensional. If you would use one loop nested in another, your data is Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 26two-dimensional, and if you would have loops nested three deep to cycle through all your data, your data is three-dimensional. Whatever your data is, it’s up to you to determine how many dimensions to use. As of OpenCL 1.0, dimensions greater than three are not supported. ● Determining the Number of Work Items The next step in preparing your kernel for execution is determining how many work items you'll need to process all of your data. This is known as the global work size, and it defines the total number of work items needed for all dimensions combined. For one-dimensional data, the global work size equals the number of data items. For two-dimensional data with m data items in one dimension and n items in the second dimension, the global work size is n * m. Similarly, for three-dimensional data with x , y , and z work itemsin the three dimensions, the global work size is x * y * z . There is practically no limit on the number of work items, and this should be a large number (over 1000) for good performance on GPUs. ● Choosing a Workgroup Size When enqueuing a kernel to execute on a device, you can specify the size of the workgroup that you’d like OpenCL to use during execution. A workgroup is a collection of work items that execute on the same compute unit on the same OpenCL device. By providing OpenCL with a suggested workgroup size, you are telling it how you would like it to delegate the work items to the various computational units on the device. The work items executing in the same workgroup can share memory and execute synchronously. In order to take advantage of these features, however, you have to know the maximum workgroup size allowed by the OpenCL device on which your work items are executing. To get this information, use the gcl_get_kernel_block_workgroup_info function and request the CL_KERNEL_WORK_GROUP_SIZE property. This API isrequired to query the workgroup size of a kernel block to use in cl_ndrange.local_work_size. Thisis needed for good performance across devices asthe workgroup sizes vary across devices. This API must be called inside a block submitted to a Grand Central Dispatch queue created using gcl_create_dispatch_queue. If you don’t need to share data among work items, pass a NULL value to the local_work_size parameter when you enqueue your kernel for execution to have OpenCL determine the workgroup size for you. Doing so will ensure the most efficient use of the available devices. Note that you also need to use clGetDeviceInfo with the selector CL_DEVICE_MAX_WORK_ITEM_SIZES to get the maximum workgroup size in each dimension, and call the gcl_get_kernel_block_workgroup_info function with the selector CL_KERNEL_WORK_GROUP_SIZE to get the total workgroup size. Three conditions must be met for the local dimensions to be valid: a. The number of work items in each dimension (local_x, local_y, and local_z) in a single workgroup must be less than the values returned for the device from clGetDeviceInfo(CL_DEVICE_MAX_WORK_ITEM_SIZES). Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 27b. The total number of work items in a workgroup (local_x times local_y times local_z ) must be less than or equal to the value returned by the gcl_get_kernel_block_workgroup_info(CL_KERNEL_WORK_GROUP_SIZE) function. c. The number of work items in each dimension in a single workgroup must divide evenly into the total number of work items in that dimension ( global_n mod local_n = 0). 7. Always pass an offset for each of three dimensions even though the workgroup may have fewer than three dimensions. 8. Call the kernel as you would call a function. Pass the ndrange as the first parameter, followed by the expected kernel parameters. Case the void* types to the expected OpenCL types. Remember -- if you use float in your kernel, that's a cl_float from the application's perspective. The call to the kernel will look something like this: kernelName( &range, (cl_datatype*)inputArray, (cl_datatype *)outputArray ); 9. Retrieve the data from the OpenCL device's memory space with gcl_memcpy. The output computed by the kernel is copied over to the host application's memory space. 10. Free OpenCL memory objects. 11. Call dispatch_release(...) on the dispatch queue you created with gcl_create_dispatch_queue(...) once you are done with it. Basic Programming Sample Basic Host Code Sample 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 28The first step in using OpenCL to improve your application’s performance is to identify what portions of your application are appropriate for parallelization. Whereas in a general application you can spawn a separate thread for a task as long as the functions in the thread are re-entrant and you’re careful about how you synchronize data access, to achieve the level of parallelism for which OpenCL isideal, it is much more important for the work items to be independent of each other. Although work items in the same workgroup can share local data, they execute synchronously and so no work item’s calculations depend on the result from another work item. Parallelization works only when the tasks that you run in parallel do not depend on each other. For example, assume that you are writing a simple application that keeps track of the grades for students in a class. The application consists of two main tasks: 1. Compute the final grade for each student, assuming the final grade is the average of all the students’ grades. 2. Obtain a class average by averaging the final grades of all students. You cannot perform these two tasks in parallel because they are not independent of each other: to calculate the class average, you must have already calculated the final grade for each student. Despite the fact that you cannot perform task 1 and task 2 simultaneously, there is still an opportunity for parallelization. To see how it can be broken down, it helpsto look at a basic pseudocode example for computing the final grade for each student serially. Listing 4-1 Pseudocode that computes the final grade for each student // assume 'class' is a collection of 'student' objects foreach(student in class) { // assume getGrades() returns a collection of integer grades grades = student.getGrades(); sum = 0; count = 0; 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 29 Identifying Parallelizable Routines// iterate through each grade, adding it to sum foreach(grade in grades) { sum += grade; count++; } // cache the average grade in the student object student.averageGrade = sum / count; } The pseudocode in Listing 4-1 (page 29) proceeds through each student in the class, one by one, calculating the average of each student’s grades and caching it in the student object. Although this example computes each grade average one at a time, there’s no reason that the grade averages for all the students couldn’t be calculated at the same time. Because the grades of one student do not affect the grades of another, you can calculate the grade averages for all the students at the same time instead of looping through the same set of instructions for each student, one at a time. This is the idea behind data parallelism. Data parallelism consists of taking a single task (in this case, calculating a student’s average grade), and repeating it over multiple sets of data. Students’ grades do not affect each other, therefore you can process them in parallel. To express this programmatically, you must first separate your task (calculating the grade average of a student) from your data (the students in the class). Listing 4-2 (page 30) shows how you can isolate the grade-averaging task. Listing 4-2 The isolated grade average task task calculateAverageGradeForStudent( student ) { // assume getGrades() returns a collection of integer grades grades = student.getGrades(); sum = 0; count = 0; // iterate through each grade, adding it to sum foreach(grade in grades) Identifying Parallelizable Routines 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 30{ sum += grade; count++; } // store the average grade in the student object student.averageGrade = sum / count; } Now that you have the task isolated, you need to apply it to allstudentsin the classin parallel. Because OpenCL has native support for parallel computing, you can rewrite the task shown in Listing 4-2 (page 30) as an OpenCL kernel function. Using the OpenCL framework API, you can enqueue this kernel to run on a device where each compute unit on the device can apply an instance of the kernel (that is, a work item) to a different set of data. The challenge in parallelizing your application is identifying the tasks that you can distribute across multiple compute units. Sometimes, asin this example, the identification isrelatively trivial and requiresfew algorithmic changes. Other times, it might require designing a new algorithm from scratch that lends itself more readily to parallelization. Although there is no universal rule for parallelizing your application, there are a few tips you can keep in mind: ● Pay attention to loops. Often the opportunities for parallelization lie within a subroutine that is repeated over a range of results. ● Nested loops might be restructured as multi-dimensional parallel tasks. ● Find as many tasks as possible that do not depend on each other. Finding a group of routines that do not share memory or depend on each other’s results is usually a good indicator that you can perform them in parallel. If you have enough such tasks, you can consider writing a task-parallel OpenCL program. ● Due to the overhead of setting up a context and transferring data over a PCI bus, you must be processing a fairly large data set before you see any benefits from using OpenCL. The exact point at which you start to see benefits depends on the OpenCL implementation and the hardware being used, so you will have to experiment to see how fast you can get your algorithm to execute. In general, a high ratio of computation to data access and lots of mathematical computations are good for OpenCL programs. Identifying Parallelizable Routines 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 31Developers already use Grand Central Dispatch (GCD) queues to implement concurrency in their applications. OS X v10.7 adds the ability to enqueue work coded as OpenCL kernels to GCD queues backed by OpenCL compute devices. You can use GCD with OS X v10.7 OpenCL to: ● Investigate the computational environment in which your OpenCL application is running. You can use OS X v10.7 OpenCL to learn about the devicesin the system that would be best for performing particular OpenCL computations and to enqueue kernels to devices: ● You can find out about the computational power and technical characteristics of each OpenCL-capable device in the system. See “Discovering Available Compute Devices” (page 32). ● GCD can suggest which OpenCL device(s) would be best for running a particular kernel. ● You can obtain recommendations about how to configure the kernel - get the suggested optimal size of the workgroup for each kernel on any particular device. See “Obtaining the Kernel’s Workgroup Size” (page 35). ● Enqueue the kernel. ● Synchronize work between the host and OpenCL devices and synchronize work between devices. Your host can wait on completion of work in all queues (See “Using GCD To Synchronize A Host With OpenCL” (page 69)) or one queue can wait on completion of another queue (See “Synchronizing Multiple Queues” (page 75)). Discovering Available Compute Devices OpenCL kernels assume a Single instruction, Multiple Data (SIMD) parallel model of computation. This means (roughly) that you have a large amount of data divided into chunks, and you want the kernel to perform the same computation on each chunk. Some SIMD algorithms will execute better on a CPU rather than on a GPU, or on one GPU rather than another, depending on many factors. Tools in OS X version 7 and later facilitate discovery of the types of devices that are available to process data. A context is needed to share memory objects between devices. If you use The OS X v10.7 gcl_ APIs, you can just retrieve and use the default global context; no context creation is needed. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 32 Using Grand Central Dispatch With OpenCLNote: If you are using APIs defined in the OpenCL specification, you do need to create your own contexts. An OpenCL context is similar to an OpenGL sharegroup. A sharegroup is a set of tools that allow blocks of memory to be accessed by both a GPU and a CPU. See “OpenCL/ OpenGL Interoperation: Data Sharing” (page 66). When you retrieve the default global context in OS X v10.7 OpenCL, you can find out about the environment in which OpenCL kernels execute. The context includes the set of devices, the memory accessible to those devices, and one or more queues used to schedule execution of one or more kernels. From the context, you can discover the types of devices in the system and can obtain recommendations as to the optimal configuration for running a kernel. Your application can call on GCD to create a queue for a particular type of device or to create a queue for a specific device. 1. Call the gcl_get_context function to get the "global" OpenCL context that OS X v10.7 creates for you. Note: Since this context is created by the OpenCL, you should not retain / release it. (You should retain/release any contexts that you explicitly create.) 2. Call the clGetDeviceIds( ... ) function (an API in the OpenCL standard API), specifying the context you just obtained asthe context parameter. This call will return a list of the IDs of the OpenCL devices attached. 3. When you have the IDs of the devices in the context, you can call the clGetDeviceInfo() function for each of the devices to obtain information about the device. The sample code in Listing 5-1 (page 37) requeststhe vendor (the manufacturer) and the device name. You could also use the clGetDeviceInfo() function to request more technical information like the number of compute cores, the cache line size and so on. The types of information you can obtain are described in the OpenCL 1.1 specification. You can choose to send different types of work to a device depending upon its characteristics and capabilities. Enqueueing A Kernel To A Dispatch Queue You must use an OpenCL-compatible dispatch queue for your OpenCL work. You can create a queue for a particular device in the system or you can create a queue for a particular type of device. You can enqueue as many kernels on each queue as you choose. You can create as many different queues as you would like: ● To create a dispatch queue to run on any device so long as it’s of a particular type, call the gcl_create_dispatch_queue function passing CL_DEVICE_TYPE_CPU, CL_DEVICE_TYPE_GPU, or CL_DEVICE_TYPE_ACCELERATOR as the first parameter. Using Grand Central Dispatch With OpenCL Enqueueing A Kernel To A Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 33Note: The dispatch queue you create must be attached to a particular device type. You cannot create an OpenCL-compatible dispatch queue for the default device type (CL_DEVICE_TYPE_DEFAULT). OS X v10.7 OpenCL will create a dispatch queue that uses a GPU or CPU, depending upon the device type you specified. If more than one GPU is available, OS X v10.7 OpenCL will give enqueue the kernel on the device of the type you specify that has the largest number of compute cores. Note: If you've created your dispatch queue specifying CL_DEVICE_TYPE_GPU, you won't know whichGPUis being used. Callthe gcl_get_device_id_with_dispatch_queue function to find out which device is actually attached to a given dispatch queue. ● If you know exactly which OpenCL device id you want to use because you've obtained it with the clGetDeviceIds function and found out about it using the clGetDeviceInfo function, call the cl_create_dispatch_queue function with CL_DEVICE_TYPE_USE_ID and pass the id of the device you want to use. Both of these methods are illustrated in the sample code. See Listing 5-1 (page 37). Note: Always call the dispatch_release(...) function on the dispatch queue you created with the gcl_create_dispatch_queue(...) function once you are done with it. All of the example code contains this call. Once you have created a queue, you can enqueue as many kernels onto that queue as necessary. Or, you can create additional queues with different characteristics. For more information about Grand Central Dispatch queues, see Concurrency Programming Guide: Dispatch Queues. Determining the Characteristics Of A Kernel On A Device To obtain information specific to a kernel/device pair, including how much private and local memory the kernel will consume (on that device), as well as the workgroup size OpenCL thinks will be most optimal for execution, call the gcl_get_kernel_block_workgroup_info function. Thisinformation is useful when you are tuning performance for a particular device or debugging performance issues. Using Grand Central Dispatch With OpenCL Determining the Characteristics Of A Kernel On A Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 34Obtaining the Kernel’s Workgroup Size To find out what OpenCL thinks is the best workgroup size for executing a kernel on a particular device, call the gcl_get_kernel_block_workgroup_info function. You can use this value as the cl_ndrange.local_work_size for a kernel on a particular device. Note: You must call this API inside a block submitted to a GCD dispatch queue created using the gcl_create_dispatch_queue function. In Listing 5-1 (page 37), notice that we first execute this method in a block on a dispatch queue we've created with OpenCL requesting the local memory size: gcl_get_kernel_block_workgroup_info( square_kernel, CL_KERNEL_LOCAL_MEM_SIZE, sizeof(local_memsize), &local_memsize, NULL); Then, in Listing 5-2 (page 40), we call the gcl_get_kernel_block_workgroup_info function to ask OpenCL to return what it considers to be the optimal workgroup size for this kernel, on this device: gcl_get_kernel_block_workgroup_info( square_kernel, // this kernel CL_KERNEL_WORK_GROUP_SIZE, sizeof(workgroup_size), &workgroup_size, NULL); fprintf(stdout, "Workgroup size: %ld\n", workgroup_size); Finally, we call the gcl_get_kernel_block_workgroup_info function to once more to ask OpenCL for a workgroup size multiple. This is a performance hint based on the capabilities of the underlying device: gcl_get_kernel_block_workgroup_info( square_kernel, // this kernel CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE, sizeof(preferred_workgroup_size_multiple), &preferred_workgroup_size_multiple, NULL); Using Grand Central Dispatch With OpenCL Obtaining the Kernel’s Workgroup Size 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 35You can now use these workgroup valuesto craft an appropriate cl_ndrange structure to use in launching your kernel. cl_ndrange range = { 1, // The number of dimensions to use. {0, 0, 0}, // The offset in each dimension. We want to // process ALL of our data, so this is 0 for // our test case. // Always pass an offset for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. {NUM_VALUES, 0, 0}, // The global range -- this is how many items // IN TOTAL in each dimension you want to // process. // Always pass the global range for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. {workgroup_size, 0, 0 } // The local size of each workgroup. This // determines the number of workitems per // workgroup. It indirectly affects the // number of workgroups, since the global // size / local size yields the number of // workgroups. So in our test case, we will // have NUM_VALUE/workgroup_size workgroups. // Always pass the workgroup size for each of the // three dimensions even though the workgroup // may have fewer than three dimensions. }; Using Grand Central Dispatch With OpenCL Obtaining the Kernel’s Workgroup Size 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 36Sample Code: Creating a Dispatch Queue Listing 5-1 (page 37) demonstrates how to get the global OpenCL context, and how to ask that context about the devices it contains. It also shows how to create a dispatch queue by asking for a device type (CPU or GPU), and by specifying the queue's OpenCL device directly. Listing 5-2 (page 40) shows how to obtain workgroup information -- useful for obtaining peak performance -- from the kernel block. Listing 5-1 Creating a dispatch queue #include // Include OpenCL/opencl.h to include everything you need for OpenCL //development on OS X v10.7. #include // In this example, mykernel.cl.h is the header file that contains our kernel block // declaration. // This header file is generated by Xcode. #include "mykernel.cl.h" static void print_device_info(cl_device_id device) { char name[128]; char vendor[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, 128, name, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, 128, vendor, NULL); fprintf(stdout, "%s : %s\n", vendor, name); } #pragma mark - #pragma mark Hello World - Sample 1 // Demonstrates how to get the global OpenCL context, and how to ask that // context about the devices it contains. It also shows how // to create a dispatch queue by asking for a device type (CPU or GPU) and Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 37// by specifying the queue's OpenCL device directly. static void hello_world_sample1 () { int i; // Ask for the global OpenCL context: // Note: If you will not be enqueing to a specific device, you do not need // to retrieve the context. cl_context context = gcl_get_context(); // Query this context to see what kinds of devices are available to us. size_t length; cl_device_id devices[8]; clGetContextInfo( context, CL_CONTEXT_DEVICES, sizeof(devices), devices, &length); // Walk over these devices, printing out some basic information. We could // query any of the information available about the device here. fprintf(stdout, "The following devices are available for use:\n"); int num_devices = (int)(length / sizeof(cl_device_id)); for (i = 0; i < num_devices; i++) { print_device_info(devices[i]); } // To do any work, you need to create a dispatch queue associated // with some OpenCL device. You can either let the system give you // a GPU -- perhaps the only GPU -- or the CPU device. Or, you can // create a dispatch queue with a cl_device_id you specify. This // device id comes from the OpenCL context, as above. Below are three // examples. Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 38// 1. Ask for a GPU-based dispatch queue; notice that we do not provide a // device id - we let the system give us the most capable GPU. dispatch_queue_t gpu_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Get the device from the queue, so we can ask OpenCL questions about it. // Note that we check to make sure there WAS an OpenCL-capable GPU in the // system by checking against a NULL return value. if (gpu_queue != NULL) { cl_device_id gpu_device = gcl_get_device_id_with_dispatch_queue(gpu_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_GPU gives us:\n"); print_device_info(gpu_device); } else { fprintf(stdout, "\nYour system does not contain an OpenCL-compatible " "GPU\n."); } // 2. Let's try the same thing for CL_DEVICE_TYPE_CPU. All Macintosh // systems will have a CPU OpenCL device, so we don't have to worry about // checking for NULL, as we did in the case of a GPU. dispatch_queue_t cpu_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); cl_device_id cpu_device = gcl_get_device_id_with_dispatch_queue(cpu_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_CPU gives us:\n"); print_device_info(cpu_device); // 3. Or perhaps you are in a situation where you want a specific device // from the list of devices you found on the context. Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 39// Notice the difference here: // We pass CL_DEVICE_TYPE_USE_ID and a device_id. We'll just use the // first device on the context from above, whatever that might be. dispatch_queue_t custom_queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_USE_ID, devices[0]); cl_device_id custom_device = gcl_get_device_id_with_dispatch_queue(custom_queue); fprintf(stdout, "\nAsking for CL_DEVICE_TYPE_USE_ID and our own device gives us:\n"); print_device_info(custom_device); // Now we could use any of these dispatch queues to run some kernels! // Use the GCD API to free your queues. dispatch_release(custom_queue); dispatch_release(cpu_queue); if (gpu_queue != NULL) dispatch_release(gpu_queue); } Listing 5-2 Obtaining workgroup information #pragma mark - #pragma mark Hello World - Sample 2 // This listing shows how to obtain workgroup info – // useful for obtaining peak performance - from the kernel block. static void hello_world_sample2() { // Get a queue backed by a GPU for running our squaring kernel. dispatch_queue_t queue = Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 40gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Did we get a GPU? If not, fall back to the CPU device. if (queue == NULL) { gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); } // In any case, print out the device we're using: fprintf(stdout, "\nExamining workgroup info for square_kernel on device "); print_device_info(gcl_get_device_id_with_dispatch_queue(queue)); // Now find out what OpenCL thinks is the best workgroup size for // executing this kernel on this particular device. Notice that we have // to execute this method in a block, on a dispatch queue we've created // with OpenCL. dispatch_sync(queue, ^{ size_t wgs, preferred_wgs_multiple; cl_ulong local_memsize, private_memsize; // The next two calls give us information about how much // memory, local and private, is used by the kernel on this // particular device. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_LOCAL_MEM_SIZE, sizeof(local_memsize), &local_memsize, NULL); fprintf(stdout, "Local memory size: %lld\n", local_memsize); gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_PRIVATE_MEM_SIZE, sizeof(private_memsize), &private_memsize, NULL); Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 41fprintf(stdout, "Private memory size: %lld\n", private_memsize); // Here we ask OpenCL what it considers the optimal workgroup // size for this kernel on this device. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(wgs), &wgs, NULL); fprintf(stdout, "Workgroup size: %ld\n", wgs); // Finally, we can ask OpenCL for a workgroup size multiple. // This is a performance hint. gcl_get_kernel_block_workgroup_info(square_kernel, CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE, sizeof(preferred_wgs_multiple), &preferred_wgs_multiple, NULL); fprintf(stdout, "Preferred workgroup size multiple: %ld\n", preferred_wgs_multiple); // You could now use these workgroup values to craft an // appropriate cl_ndrange structure for use in launching your kernel. }); dispatch_release(queue); } int main(int argc, const char* argv[]) { hello_world_sample1(); hello_world_sample2(); } Using Grand Central Dispatch With OpenCL Sample Code: Creating a Dispatch Queue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 42This chapter provides an overview of how memory is used with OpenCL (since this differsfrom the way memory is used in conventional programs), describes how buffers are created and used in OpenCL, describes how images are created and used in OpenCL, and provides information about using memory in situations such as with IOSurfaces and OpenGL textures. Overview Like all computational processes, processes that run on OpenCL devices consist of: ● Data The data accessed by OpenCL instructions exists as memory buffers and cl_image memory objects. Use image objects for representing 2D or 3D images (see “Creating and Using Images in OpenCL” (page 54)); use buffer objects for containing other types of generic data (see “Creating and Using Buffers in OpenCL” (page 46)). ● Instructions (in kernel functions) that manipulate the data. Even if they are physically contiguous, host memory is distinct from OpenCL memory. Kernel instructions can only access data in the memory of OpenCL devices. The host computer can read and write to device memory, but only to set it up and retrieve results. During computation, a device looks only in device memory, and the host stays out of its way. In other words, in OpenCL, you launch a set of work items against a bolus of data. While this data might have been passed to the OpenCL device by the host, the data resides on the OpenCL device at the time of execution. A kernel cannot read or write to the host memory; it can only access data its own separate memory area. For many devices(like GPUs), the OpenCL is actually a physically distinct piece ofsilicon. For other devices, although the memory is physically on the same chip, it can only be read/written by the OpenCL kernel code. Workflow The basic workflow with OpenCL is: 1. Create memory objects for use by OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 43 Creating and Managing Memory Objects in OS X OpenCLThe host requests that memory be set aside for it on the device. The host can ask for as many memory objects as it wants, up to the memory available. 2. Initialize the contents of the memory objects a. The host can pass data to the device to be stored in its memory objects. Thisisthe data that the kernel will process. The host can also instruct the device to leave some memory objects uninitialized so that when the kernel runs on the device, it can fill up these memory objects as its output. b. The host instructs the device to execute the kernel, passing it the memory objects it has created on the OpenCL device as arguments. The host will wait until the kernel is done. 3. Execute the kernel The kernel runs on the device, processing the data in the input memory, producing output to be stored in the designated output memory. 4. Read results from the memory objects When the host detects that the kernel has completed its tasks, it copies the results the kernel stored in the designated output memory into memory the host can access." 5. Destroy the memory objects Once the host has retrieved the output data, it instructs the device to free up the memory it had set aside for the kernel to use. Memory Visibility In a typical multi-device environment, memory is distributed between devices. No device can access all memory. For example, an OpenCL kernel resides in a separate memory space from the host that calls it. In order for the kernel to accessthe data it isto process, the data must be moved into the device’s memory. However, transferring data between memory areas to allow different devices to work can result in considerable overhead. Minimize the amount of data being transferred to optimize performance. The host specifies the memory space for a given buffer when it declares each kernel argument. Creating and Managing Memory Objects in OS X OpenCL Overview 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 44The memory spaces as an OpenCL device would see them are: Figure 6-1 Physical memory of an OpenCL system OpenCL Device Host Work Item Local Memory Workgroup Global/Constant Memory Host Memory Private Memory Work Item Private Memory Work Item Local Memory Workgroup Private Memory Work Item Private Memory ● Private memory Each work item has memory that only it can see. This is its private memory. ● Local memory Local memory is memory that work items WITHIN a work group can share. Local memory is useful if more than one work item in a group needs to use a particular chunk of global memory. You can write your OpenCL program so that one work item loads from global memory to local memory, and then the rest of the work items that need that piece of data can use the "local" copy. It takes GPU devices much less time to access local memory than to access global memory. ● Global memory This is the (relatively) massive chunk of device memory that ALL work items can "see". Any work item can read / write to a buffer declared to be in global memory. ● Constant memory Creating and Managing Memory Objects in OS X OpenCL Overview 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 45Thisis a specialized section of global memory for data that you the programmer know will remain constant throughout the execution of your kernel. It is more limited in size than global memory (typically), but is faster to access on many devices than other global memory. Memory Consistency Changes a work item has made to global or local memory may not immediately become visible to other work items within a workgroup. An system’s consistency has to do with when changes a work item has made to global or local memory become visible to other work items within a workgroup. OpenCL uses what is called a relaxed memory consistency model, which means that: ● Work items can access data within their own private memory, local memory, constant memory, and global memory. ● Work items can share local memory during the execution of a workgroup. However, memory is only guaranteed to be consistent after specific synchronization points. If a work item needs to read something that another work item has written, then you will need to place a barrier in your OpenCL code at the point where you want the memory to be consistent. The barrier will stop any work item at the barrier until all other work items have "caught up". That's why it works -- every work item in the workgroup has written its memory by that point, so it's safe to go on and read anything any work item in the group has written. See “Using GCD To Synchronize A Host With OpenCL” (page 69). Note: You can create a barrier that appliesto local memory or to global memory, but consistency only appliesto work items within a work group. There is no such thing as a global memory barrier that will make all threads in an execution wait. OpenCL only guarantees memory consistency at a barrier within a work group. Creating and Using Buffers in OpenCL Representing Data With Buffer Objects The OpenCL programming interface provides buffer objects for representing generic data in your OpenCL programs. Instead of having to convert your data to the domain of a specific type of hardware, OpenCL enables you to transfer your data as is to an OpenCL device via buffer objects and operate on the data using the same language features that you are accustomed to in C. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 46OpenCL is designed to share efficiently with OpenGL. Wherever possible, data is shared between OpenCL and OpenGL programs; it is not copied. Because transmitting data is costly, it is best to minimize reads and writes as much as possible. By packaging all of your host data into a buffer object that can remain on the device, you reduce the amount of data traffic necessary to process your data. Allocating Memory For Buffer Objects In OS X v10.7 If you need a cl_mem object, (you will need one of these if you are going to be using a standard OpenCL API call), call the gcl_malloc function to allocate the memory, then call the gcl_create_buffer_from_ptr function to convert the handle gcl_malloc returns for use with the standard OpenCL API. To create buffer objects: ● void * gcl_malloc(size_t bytes, void *host_ptr, cl_malloc_flags flags) The gcl_malloc function returns a void * which is a memory object handle. The bytes parameter is the number of bytes to be allocated. The host_ptr parameter . The flags parameter and can be 0 or CL_MEM_USE_HOST_PTR. Note: The void * value returned cannot be used to directly access the memory region on the host CPU. To access this memory region for reading and writing on the host CPU, use APIs such as cl_memcpy that can be passed in a block to GCD APIs that queue tasks for dispatch. ● cl_mem gcl_create_buffer_from_ptr(void *ptr) The cl_mem gcl_create_buffer_from_ptr function creates a cl_mem buffer object from a ptr returned by cl_malloc. The cl_mem object returned can be used by CL API calls to enable sharing of objects between Grand CL and the OpenCL API. The cl_mem object returned references the data store associated with the ptr parameter. Note: Be sure to release cl_mem objects created using gcl_create_buffer_from_ptr before freeing this pointer using gcl_free. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 47Reading, Writing, and Copying Buffer Objects You can create memory objects outside a dispatch queue and the memory objects you create do not have to be associated with any particular device. But before the memory object is accessed by OpenCL, it must be associated with the device the data will be moving into and out of. You associate a memory object with its device in the dispatch queue.. After you’ve created a buffer object, you can enqueue reads, writes, and copies. You can call the following functions from your host application. These can be passed in a block(s) to the Grand Central Dispatch APIs that queue tasks for dispatch such as dispatch_async. They enable you to move data to and from a host. void gcl_memcpy(void *dst, const void *src, size_t size); void gcl_memcpy_rect(void *dst, const void *src, const size_t dst_origin[3], const size_t src_origin[3], const size_t region[3], size_t dst_row_pitch, size_t dst_slice_pitch, size_t src_row_pitch, size_t src_slice_pitch); void *gcl_map_ptr(void *ptr, cl_map_flags map_flags, size_t cb); void *gcl_map_image(cl_image image, cl_map_flags map_flags, const size_t origin[3], const size_t region[3]); void gcl_unmap(void *ptr); Kernel Support For Data Processing In OpenCL-C By associating your buffer object with specific kernel arguments, you make it possible to process your data from the context of a kernel function. For example, in “Example: Allocating, Using, Releasing Buffer Objects” (page 50), notice how the code sample treats the input data pointer much as you would treat a pointer in C. In this example the input data is an array of float values, and you can process each element of the float array by indexing into the pointer. “Example: Allocating, Using, Releasing Buffer Objects” (page 50) does little more than multiply a value by itself using the * operator, but OpenCL-C provides a wide array of data types and operators that enable you to perform more complex arithmetic. Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 48Because OpenCL-C is based on C99, you are free to process your data in OpenCL-C functions as you would in C with few limitations. Aside from support for recursion and function pointers, there are not many language features that C has that OpenCL-C doesn’t have. In fact, OpenCL-C provides several beneficial features that the C programming language does not offer natively, such as optimized image access functions. OpenCL-C has built-in support for vector intrinsics and offers vector data types. The operators in OpenCL-C are overloaded, and performing arithmetic between vector data typesissyntactically equivalent to performing arithmetic between scalar values. Refer to the TheOpenCL Specification for more details on the built-in functions and facilities of the OpenCL-C language. Releasing Buffer Objects To avoid memory leaks, free buffer objects when they are no longer needed. Call gcl_free to free buffer objects created using gcl_malloc. void gcl_free(void *ptr); The ptr parameter is the handle of the buffer object to be released. OpenCL uses a reference counting system to keep track of the memory objects currently being used. The reference count represents how many other objects hold referencesto the particular memory object. Any time you create a buffer object, it immediately receives a reference count of 1. Any time another object would also like to maintain a reference to it, it should increment the buffer object’s reference count by calling the clRetainMemObject function. When an object wishes to relinquish its reference to a buffer object, it should call clReleaseMemObject. When the reference count for a buffer object reaches zero, OpenCL frees it, returning the memory to the system and making any persisting references to the buffer object invalid. Setting the finalizer A finalizer is a function member of a reference class that is called automatically by the garbage collector when destroying an object. To specify which finalizer function the garbage collector calls for any objects created by gcl_malloc or gcl_create_*** APIs (such as gcl_create_image), call: void gcl_set_finalizer(void *object, void (*gcl_pfn_finalizer)(void *object, void *user_data), void *user_data); Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 49Example: Allocating, Using, Releasing Buffer Objects In the following example, the host creates one input buffer and one output buffer, initializes the input buffer, calls the kernel to square each value in the input buffer, then checks the results. Listing 6-1 Sample host function creates buffers then calls kernel function #include #include #include // Include the automatically-generated header which provides the kernel block // declaration. #include "kernels.cl.h" #define COUNT 2048 static void display_device(cl_device_id device) { char name_buf[128]; char vendor_buf[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, sizeof(char)*128, name_buf, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, sizeof(char)*128, vendor_buf, NULL); fprintf(stdout, "Using OpenCL device: %s %s\n", vendor_buf, name_buf); } static void buffer_test(const dispatch_queue_t dq) { unsigned int i; // We'll use a semaphore to synchronize the host and OpenCL device. dispatch_semaphore_t dsema = dispatch_semaphore_create(0); // Create some input data on the _host_ ... Creating and Managing Memory Objects in OS X OpenCL Creating and Using Buffers in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 50cl_float* host_input = (float*)malloc(sizeof(cl_float) * COUNT); // ... and fill it with some initial data. for (i=0; i #include #include // Include the automatically-generated header which provides the kernel block // declaration. #include "kernels.cl.h" #define COUNT 2048 static void display_device(cl_device_id device) { char name_buf[128]; Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 59char vendor_buf[128]; clGetDeviceInfo(device, CL_DEVICE_NAME, sizeof(char)*128, name_buf, NULL); clGetDeviceInfo(device, CL_DEVICE_VENDOR, sizeof(char)*128, vendor_buf, NULL); fprintf(stdout, "Using OpenCL device: %s %s\n", vendor_buf, name_buf); } static void image_test(const dispatch_queue_t dq) { // As before, we use a dispatch semaphore to achieve synchronization between // the host application and the work done for us by the OpenCL device. dispatch_semaphore_t dsema = dispatch_semaphore_create(0); // Let's create a "fake" RGBA, 8-bit-per channel image, solid red. // In a real program, you would use some real raster data. // Most OpenCL devices support a wide-variety of image formats. unsigned int i; size_t height = 2048, width = 2048; unsigned int *pixels = (unsigned int*)malloc( sizeof(unsigned int) * width * height ); for (i = 0; i < width*height; i++) pixels[i] = 0xFF0000FF; // 0xAABBGGRR: 8bits per channel, all red. // This image data is on the host side. // We need to create two OpenCL images in order to perform some // manipulations: one for the input and one for the ouput. // This describes the format of the image data. cl_image_format format; format.image_channel_order = CL_RGBA; Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 60format.image_channel_data_type = CL_UNSIGNED_INT8; cl_mem input_image = gcl_create_image(&format, width, height, 1, NULL); cl_mem output_image = gcl_create_image(&format, width, height, 1, NULL); dispatch_async(dq, ^{ // Our kernel is written such that each work item processes one pixel. // Thus, we execute over a two-dimensional range, // with the width and height of the image determining the dimensions // of execution. cl_ndrange range = { 2, // We're using a 2-dimensional execution. {0}, // Start at the beginning of the range. {width, height}, // Execute width * height work items. {0} // And let OpenCL decide how to divide the work items // into work-groups. }; // Copy the host-side, initial pixel data to the image memory object on // the OpenCL device. We copy the whole image, but you could use the // origin and region parameters to specify an offset and sub-region of // the image, if you'd like. const size_t origin[3] = { 0, 0, 0 }; const size_t region[3] = { width, height, 1 }; gcl_copy_ptr_to_image(input_image, pixels, origin, region); // Do it! red_to_green_kernel(&range, input_image, output_image); // Read back the results; let's reuse the host-side buffer we started with. gcl_copy_image_to_ptr(pixels, output_image, origin, region); Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 61// Let the host know we're done. dispatch_semaphore_signal(dsema); }); // Do other work, if you'd like... // ... but eventually, you will want to wait for OpenCL to finish up. dispatch_semaphore_wait(dsema, DISPATCH_TIME_FOREVER); // Alright - we expect '0xFF00FF00' for each pixel. Solid green, all the way. int results_ok = 1; for (i = 0; i < width*height; i++) { if (pixels[i] != 0xFF00FF00) { fprintf(stdout, "Oh no. Pixel %d was not correct. Expected 0xFF00FF00, saw %x\n", i, pixels[i]); results_ok = 0; break; } } if (results_ok) fprintf(stdout, "Image results OK!\n"); // Clean up device-size allocations. // Note that we use the "standard" OpenCL API here. clReleaseMemObject(input_image); clReleaseMemObject(output_image); // Clean up host-side allocations. free(pixels); } int main (int argc, const char * argv[]) Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 62{ // Grab a CPU-based dispatch queue. dispatch_queue_t dq = gcl_create_dispatch_queue(CL_DEVICE_TYPE_CPU, NULL); if (!dq) { fprintf(stdout, "Unable to create a CPU-based dispatch queue.\n"); exit(1); } // Display the OpenCL device associated with this dispatch queue. display_device(gcl_get_device_id_with_dispatch_queue(dq)); image_test(dq); fprintf(stdout, "\nDone.\n\n"); dispatch_release(dq); } Listing 6-6 Sample kernel swaps the red and green channels // A simple kernel that swaps the red and green channels. const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE | CLK_FILTER_NEAREST; kernel void red_to_green(read_only image2d_t input, write_only image2d_t output) { size_t x = get_global_id(0); size_t y = get_global_id(1); uint4 tap = read_imageui(input, sampler, (int2)(x,y)); write_imageui(output, (int2)(x,y), tap.yxzw); } Creating and Managing Memory Objects in OS X OpenCL Creating and Using Images in OpenCL 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 63IOSurface and GL: What OpenCL Supports How the Kernel Interacts With Data Passing Data To a Kernel Xcode uses your kernel code to automatically generate the kernel function prototype in the kernel header file. To pass data to a kernel, when you call the kernel from your host code, passthe memory objects as parameters, just as you would pass parameters to any other function. OpenCL kernel arguments can be scoped with a local or global qualifier, designating the memory storage for these arguments. In OS X v10.7, for arguments to OpenCL kernels that would have been declared with the local or __local address qualifier, the argument type used in the block declaration of the kernel will be a size_t. Consider the following kernel that has an argument declared with the local address qualifier: kernel void foo(global float *a, local float *shared); The extern declaration of this kernel block that will be generated for you in the host code will be: extern void (^foo_kernel)(const cl_ndrange *ndrange, float *a, size_t shared); Accessing Buffer Objects From a Kernel Once the data has been enqueued, in order for a device to actually process this data, you have to make this data available to the work items that execute on the device. The following sections show you how to pass your data to the compute kernels for further processing. In your host application source code, it’s your responsibility to: ● Prepare the input data. ● Create a buffer object of the appropriate size. ● Move the input data from host memory. You can do this using the clCreateBuffer function by pointing to the data on the host, or you can use the clEnqueueWriteBuffer function to enqueue a write from host memory. ● Associate the input data with the kernel’s arguments. Use the clSetKernelArg function to do this. Creating and Managing Memory Objects in OS X OpenCL IOSurface and GL: What OpenCL Supports 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 64Kernels written in OpenCL-C need a data structure to describe the data parallel range over which to execute the kernel. In OS X v10.7, you’ll use the cl_ndrange structure for this purpose: typedef struct _cl_ndrange { size_t work_dim; size_t global_work_offset[3]; size_t global_work_size[3]; size_t local_work_size[3]; } cl_ndrange; Retrieving Results From a Kernel To read the results back, call dispatch_sync. For example, dispatch_sync(queue, ^{ gcl_memcpy(ptr_c, device_c,num_floats * sizeof(float)); }); Creating and Managing Memory Objects in OS X OpenCL How the Kernel Interacts With Data 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 65OpenGL (Open Graphics Library) is an API for writing applications that produce 2D and 3D computer graphics. See OpenGL. OpenCL / OpenGL interoperability enables applicationsto share data between OpenCL and OpenGL efficiently. You do not have to create multiple copies of the same content in OpenCL and OpenGL. An OpenCL memory object created from an OpenGL object and the original OpenGL object both refer to the same memory and both GLSL (OpenGL Shading Language) shaders and OpenCL kernels can access the shared data. Another advantage of using OpenCL / OpenGL interoperability isthat the overhead of passing data for compute/display purposes is greatly reduced. If the computation and rendering are performed on the GPU, the data need not be moved between the host and the GPU. This chapter describes the OpenCL APIs that can be used to create OpenCL memory objects from OpenGL vertex buffer objects(VBOs), texture objects, and renderbuffer objects. An OpenCL buffer object may be created from an OpenGL buffer object. An OpenCL image object may be created from an OpenGL texture or renderbuffer object. To create an OpenCL memory object from an OpenGL object, an OpenCL context has to be created from an OpenGL share group (CGLShareGroup) object. An OpenGL share group object manages the OpenGL objects on the devices in the rendering context. When an OpenCL context is connected to an OpenGL share group object, both the OpenCL context and the OpenGL context can reference the same data objects. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 66 OpenCL/ OpenGL Interoperation: Data SharingSharegroups In the example illustrated in Figure 7-1 (page 67), OpenCL is used to generate geometry on the GPU and OpenGL is used to render the shared geometry, also using the GPU. The OpenCL and OpenGL contextsreference the same sharegroup (CGLShareGroupObj). Both OpenCL and OpenGL see the same devices and can access the shared geometry. OpenGL sees the data as a VBO and OpenCL sees it as a buffer memory object. Figure 7-1 OpenGL and OpenCL share data using sharegroups CPU GPU OpenCL CGLShareGroupObj cl_context cl_mem VBO gl_context To use OpenCL / OpenGL interoperability: 1. Set the sharegroup: CGLContextObj cgl_context = CGLGetCurrentContext(); CGLShareGroupObj sharegroup = CGLGetShareGroup(cgl_context); gcl_gl_set_sharegroup(sharegroup); ... 2. After the sharegroup has been set, you can create OpenCL memory objects from the existing OpenGL objects: ● Use the following API to create an OpenCL buffer object from an OpenGL buffer object: void * gcl_gl_create_ptr_from_buffer(GLuint bufobj); ● Use the following API to create an OpenCL image object from an OpenGL texture object: OpenCL/ OpenGL Interoperation: Data Sharing Sharegroups 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 67cl_image gcl_gl_create_image_from_texture( GLenum texture_target, GLint mip_level, GLuint texture); ● Use the following API to create an OpenCL 2D image object from an OpenGL render buffer object: cl_image gcl_gl_create_image_from_renderbuffer(GLuint render_buffer); Synchronizing Access To Shared OpenCL/OpenGL Objects To ensure data integrity, the application is responsible for synchronizing access to shared OpenCL/OpenGL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations. For information about synchronizing OpenCL and OpenGL events and fences, see “Controlling OpenCL/OpenGL Interoperation With GCD” (page 69). Example OpenCL/ OpenGL Interoperation: Data Sharing Synchronizing Access To Shared OpenCL/OpenGL Objects 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 68An application running on a host (a CPU) can route work or data (possibly in disparate chunks) to a device using the standard OpenCL and OpenGL APIs and OS X v10.7 extensions. While the device does the work it has been assigned, the host can continue working asynchronously. But at a certain point, the host will need to wait for the results generated by the device performing the work it was assigned,so it will wait for the device to notify it that the assigned work has been completed. OpenCL and OpenGL can also share work and data. Typically, OpenCL will be used to generate or modify buffer data which will then be rendered by OpenGL. Or, you might use OpenGL to create an image and then post-process it using OpenCL. In either case, you have to make sure you synchronize correctly. This chapter describes how to use GCD to synchronize: ● A host with OpenCL See “Using GCD To Synchronize A Host With OpenCL” (page 69). ● A host with OpenCL using a dispatch semaphore See “Synchronizing A Host With OpenCL Using A Dispatch Semaphore” (page 70). ● Multiple OpenCL Queues See “Synchronizing Multiple Queues” (page 75). You can still use the standard OpenCL and OpenGL APIs to obtain fine-grained synchronization when working on shared data, where you either: ● Call OpenGL then OpenCL ● Call OpenCL then OpenGL See the OpenGL and OpenGL specifications for more information. Using GCD To Synchronize A Host With OpenCL In Listing 8-1 (page 70), the host enqueues data in two queues to Grand Central Dispatch. The queued data is processed while the host continues to do its own work. When the host needs the results, it waits for both queues to complete their work. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 69 Controlling OpenCL/OpenGL Interoperation With GCDListing 8-1 Synchronizing the host with OpenCL processing // Create a workgroup so host can wait for results from more than one kernel. dispatch_group_t group = dispatch_group_create(); // Enqueue some of the data to the add_arrays_kernel on q0. dispatch_group_async(group, q0, ^{ // Because the call is asynchronous, // the host will not wait for the results cl_ndrange ndrange = { 1, {0}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Enqueue some of the data to the add_arrays_kernel on q1. dispatch_group_async(group, q1, ^{ // Because the call is asynchronous, // the host will not wait for the results cl_ndrange ndrange = { 1, {N/2}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Perform more work independent of the work being done by the kernels. ... // At this point, the host needs the results before it can proceed. // So it waits for the entire workgroup (on both queues) to complete its work. dispatch_group_wait(group, DISPATCH_TIME_FOREVER); Synchronizing A Host With OpenCL Using A Dispatch Semaphore The sample Listing 8-2 (page 71) illustrates how you can use OpenCL and OpenGL together in an application. In this example, we create two vertex buffer objects (VBOs) using OpenGL (not shown). These VBOs represent the positions of some objects in an N-body simulation. We then create OpenCL memory objects from these VBOs (line [2]), which allows us to operate directly on the device memory containing this data in our OpenCL kernel. We update these positions according to our desired algorithm, expressed as a per-object operation in the included kernel, and then render the resulting VBO using OpenGL (commented, but not shown, at [4]). Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 70Since we are updating positions using OpenCL on a dispatch queue that runs asynchoronously with respect to the thread that does the OpenGL rendering, we need to take action to ensure that we do not render before the kernel has finished updating the positions. We utilize a mechanism that is common in applications that require synchronization in GCD-compatible applications: a dispatch semaphore. Before entering the main loop, we create a dispatch_semaphore_t (line [1]). In the block that we submit to the dispatch queue created in OpenCL, just after our kernel call, we signal the semaphore. Meanwhile, the "main" thread of execution has been rolling along -- perhaps doing more work -- eventually arriving at the call to dispatch_semaphore_wait(...) (line [3]). The main thread stops at this point and waits until the post-kernel signal "flips" the semaphore. Once that occurs, the code can continue to the OpenGL rendering portion of the code, safe in the knowledge that the position update for this round is complete. Figure 8-1 Rendering loop - each pass on the main thread creates a new frame for display Synchronization point “I’m done” OpenCL-created Dispatch Queue integration_kernel(…) Just might take a bit of time dispatch_semaphore_wait(…) “Main” Thread of Execution dispatch_async(…) Note: that the main thread could do other work here before stopping to wait. But eventually, we call: dispatch_semaphore_wait(…) Here we sit and wait on CL to be done. render_with_OpenGL(…) glFlush(…) Listing 8-2 Synchronizing a host with OpenCL using a dispatch semaphore // In this case, the kernel code will update the position of the vertex. ... // The host code is: // Create the dispatch semaphone. [1] Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 71dispatch_queue_t queue; dispatch_semaphore_t cl_gl_semaphore; void *pos_gpu[2], *vel_gpu[2]; GLuint vbo[2]; float *host_pos_data, *host_vel_data; int num_bodies; int curr_read_index, curr_write_index; // Extern OpenCL kernel declarations extern void (^integrateNBodySystem_kernel)(const cl_ndrange *ndrange, float4 *newPos, float4 *newVel, float4 *oldPos, float4 *oldVel, float deltaTime, float damping, float softening, int numBodies, size_t sharedPos); void initialize_cl() { gcl_gl_set_sharegroup(CGLGetShareGroup(CGLGetCurrentContext()); // Create a CL dispatch queue. queue = gcl_create_dispatch_queue(CL_DEVICE_TYPE_GPU, NULL); // Create a dispatch semaphore used for CL / GL sharing. cl_gl_semaphore = dispatch_semaphore_create(0); // Create CL objects from GL VBOs that have already been created. [2] pos_gpu[0] = gcl_gl_create_ptr_from_buffer(vbo[0]); pos_gpu[1] = gcl_gl_create_ptr_from_buffer(vbo[1]); vel_gpu[0] = gcl_malloc(sizeof(float4)*num_bodies, NULL, 0); vel_gpu[1] = gcl_malloc(sizeof(float4)*num_bodies, NULL, 0); Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 72// Allocate and generate position and velocity data // in host_pos_data and host_vel_data. // ... // Initialize CL buffers with host position and velocity data. dispatch_async(queue, ^{gcl_memcpy(pos_gpu[curr_read_index], host_pos_data, sizeof(float4)*num_bodies); gcl_memcpy(vel_gpu[curr_read_index], host_vel_data, sizeof(float4)*num_bodies);}); } void execute_cl_gl_main_loop() { // Queue CL kernel to dispatch queue. dispatch_async(queue, ^{ ndrange_t ndrange = { 1, {0}, {num_bodies} } ; // Get local workgroup size that kernel can use for // device associated with queue. gcl_get_kernel_block_workgroup_info( integrateNBodySystem_kernel, CL_KERNEL_WORK_GROUP_SIZE, sizeof(size_t), &nrange.local_work_size[0], NULL); // Queue CL kernel to dispatch queue. integrateNBodySystem_kernel(&ndrange, pos_gpu[curr_write_index], vel_gpu[curr_write_index], pos_gpu[curr_read_index], vel_gpu[curr_read_index], Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 73damping, softening, num_bodies, sizeof(float4)*ndrange.local_work_size[0]); // Signal the dispatch semaphore to indicate that // GL can now use resources. dispatch_semaphore_signal(cl_gl_semaphore);}); // Do work not related to resources being used by CL in dispatch block. // Need to use VBOs that are being used by CL so wait for the CL commands // in dispatch queue to be issued to the GPU’s command-buffer. [3] dispatch_semaphore_wait(cl_gl_semaphore, DISPATCH_TIME_FOREVER); // Bind VBO that has been modified by CL kernel. glBindBuffer(GL_ARRAY_BUFFER, pos_gpu[curr_write_index]); // Now render with GL. [4] // Flush GL commands. glFlush(); } void release_cl() { gcl_free(pos_gpu[0]); gcl_free(pos_gpu[1]); gcl_free(vel_gpu[0]); gcl_free(vel_gpu[1]); dispatch_release(cl_gl_semaphore); dispatch_release(queue); } Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing A Host With OpenCL Using A Dispatch Semaphore 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 74Synchronizing Multiple Queues In Listing 8-3 (page 75), the host enqueues data in two queues to Grand Central Dispatch. The second queue waits for the first queue to complete its processing before doing its work. The host application does not wait for completion of either queue. Listing 8-3 Synchronizing multiple queues // Create the workgroup which will consist of just the work items // that must be completed first. dispatch_group_t group = dispatch_group_create(); dispatch_group_enter(group); // Start work on the workgroup. dispatch_async(q0, ^{ cl_ndrange ndrange = { 1, {0}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); dispatch_group_leave(group); }); // Simultaneously enqueue data on q1, // but immediately wait until the workgroup on q0 completes. dispatch_async(q1, ^{ // Wait for the work of the group to complete. dispatch_group_wait(group, DISPATCH_TIME_FOREVER); cl_ndrange ndrange = { 1, {N/2}, {N/2}, {0} }; add_arrays_kernel(&ndrange, a, b, c); }); // Host application does not wait. Controlling OpenCL/OpenGL Interoperation With GCD Synchronizing Multiple Queues 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 75An IOSurface is an abstraction for sharing image data. IOSurfaces are an efficient way to manage image memory because when you use an IOSurface, if no copy is necessary, no time is wasted on making a copy. An IOSurface transcends APIs, architectures, address spaces, and processes. You can get an ID for an IOSurface that can be passed around from process to process, so that each of these completely separate programs can use one single IOSurface. This makessharing an IOSurface between devices very easy. If you create an OpenCL image memory object from an existing IOSurface, you can modify the data contained in the IOSurface either in your "main program" running on the CPU, or in an OpenCL kernel running on either a GPU or a CPU. Creating Or Obtaining An IOSurface You can either create an IOSurface in code (see for an example) or you can request an IOSurface from another running process such as Photo Booth. The underlying texture transfer mechanism for an IOSurface combines GL_UNPACK_CLIENT_STORAGE_APPLE and GL_STORAGE_HINT_CACHED_APPLE together. The transfer is done as a straight DMA to/from system memory and video memory with no format conversions of any kind (other than some GPU-specific memory layout details). No matter how many different OpenGL contexts (in the same process or not) bind a texture to an IOSurface, they all share the same system memory and GPU memory copies of the data. Creating An Image Object from An IOSurface Once you’ve created or obtained an IOSurface, before you use it in OpenCL, you need to create an OpenCL image memory object using the IOSurface. When you create the memory object, you are not making a copy; the image memory object points at the same memory asthe original IOSurface. This makes using the IOSurface very efficient. If you are using GCD to interact with the IOSurface, create the IOSurface-backed CL image as shown in Listing 9-1 (page 77). 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 76 Using IOSurfaces With OpenCLListing 9-1 Creating an IOSurface-backed CL Image cl_image gcl_create_image( const cl_image_format *image_format, size_t image_width, size_t image_height, size_t image_depth, IOSurfaceRef io_surface); // create a 2D image (depth = 0 or 1) or a 3D image (depth > 1). // can also be used to create an image from an IOSurfaceRef. If you are using the standard OpenCL API and not using GCD to create an IOSurface-backed CL object, use clCreateImageFromIOSurface2D as shown in Listing 9-2 (page 77). Listing 9-2 Extracting an Image From an IOSurface cl_image_format image_format; image_format.image_channel_order = CL_RGBA; image_format.image_channel_data_type = CL_UNORM_INT8; cl_mem image = clCreateImageFromIOSurface2D( context, flags, image_format, width, height, surface, &err ); Sharing the IOSurface With An OpenCL Device Sharing an IOSurface in OpenCL is very simple. The key is to lock the IOSurface properly. If your CPU (host) is going to modify the IOSurface and then share it with an OpenCL device, you should lock the IOSurface before reading or writing to it, then unlock it before passing it to a kernel: ● The host creates or obtains the IOSurface and creates its CL image object . ● If the host will be writing to the IOSurface, the host write-locks the IOSurface: IOSurfaceLock(..., write type lock). If the host will only read from the IOSurface, the host read-locks it. ● The host writes to/reads from the IOSurface as necessary. ● The host unlocks the IOSurface: IOSurfaceUnlock(...). This tells the system that you changed the data. You can then use the IOSurface-backed image in OpenCL -- the IOSurface object will handle any necessary read locking internally for you. Using IOSurfaces With OpenCL Sharing the IOSurface With An OpenCL Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 77● The host enqueues the OpenCL kernel, passing it the IOSurface. The locking and unlocking are simply the minimal calls needed to give OS X enough information to ensure that each device always gets the latest, correct data. If you will be using OpenCL to modify the IOSurface, you don't have to lock it. Just access the image memory object directly. Using IOSurfaces With OpenCL Sharing the IOSurface With An OpenCL Device 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 78The autovectorizer detects operations in a scalar program that can be run in parallel and converts them into sequential operations that can be handled efficiently by today's CPUs. The autovectorizer frees you to write simple scalar code. It then vectorizes that code for you so that its performance on the CPU is maximized while the same code runs on the GPU as well. Note: Some GPUs also give higher performance when your code is vectorized. The autovectorizer does not operate on GPU code, but you can vectorize your GPU code manually. If you do manually vectorize your GPU code, test both vectorized and unvectorized versions to see which gives better performance on specific hardware. Features ● Runs by default when compiling to the CPU. ● Packs work items together. ● Generates a loop over the entire workgroup. ● Can provide performance improvement of up to the vector width of the CPU without additional effort. ● Allows you to write one scalar kernel that runs on CPU or GPU. Without the Autovectorizer The issue is that a GPU will process scalar data efficiently, but the CPU needs vectorized data to keep it fully busy. Which means that, without the autovectorizer, you either have to write multiple device-specific kernels that all perform the same function, or your performance will suffer. OpenCL sees devices as having a number of compute cores and within them a number of processing elements. When scalar code runs on the CPU, it will run on each core but will not take advantage of the vector unit. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 79 AutovectorizerFor example, on a SSE4 machine, scalar code would run in one lane of the vector unit when it could be running in four lanes. The monitor would report that the CPU is completely busy because all the cores are running, but the CPU is actually only using a quarter of its vector width. Figure 10-1 Before autovectorization: A simple float sent to the CPU and the GPU CPU GPU If you pass simple floats into a kernel: Listing 10-1 Passing single floats into a kernel kernel void add_arrays(global float* a, global float* b, global float* c) { size_t i = get_global_id(0); c[i] = a[i] + b[i]; } The kernel will be doing a scalar addition; operating on one data element at a time. If you send the scalar float to the CPU and the GPU, the GPU will become fully engaged in processing the data. In the CPU, although all the cores are busy, only one quarter of the vector width of the processing element in each core is used. If you instead passin float4* parametersto the kernel, that makesthe addition a vector addition. The addition is now CPU-only, specialized for that device. That would extract as much work as possible from the CPU but leave the GPU idle. In other words, without the autovectorizer, you would have to write multiple device-specific, non-scalar kernels, one for each type of device. Autovectorizer Without the Autovectorizer 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 80Writing Optimal Code For the CPU: Let the autovectorizer do the work for you Do ● Write one simple (non-vectorized) kernel that can run on any device. Don’t ● Write device-specific optimizations. ● Write work item ID-dependent control flow, if possible. (If this occurs in many places in the code, it would likely prevent autovectorization from succeeding.) What the autovectorizer does ● Runs by default whenever compiling kernels to a CPU. ● Packs work items together into vector instructions. ● Workgroup size can be increased if autovectorization is successful. ● Achieves performance improvements of up to the vector width of the CPU without additional effort on your part. Vectorization Example Xcode Setting Type Default Command Line Flag -cl-auto-vectorize-enable If this is set to NO, the command line flag should be -cl-autovectorize- disable Auto-vectorizer Boolean YES Autovectorizer Writing Optimal Code For the CPU: Let the autovectorizer do the work for you 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 81This chapter providessuggestions asto how to structure OpenCL code so that it runs most efficiently, describes how to measure performance of OpenCL applications, and what to expect - how to set performance objectives. It also provides an example of an iterative process of performance tuning of a simple image filter application. Before Optimizing Code Before you decide to optimize code, it is important to answer the following questions: 1. Does the code really need to be optimized? This is the most important question, and answering it is not trivial when the OpenCL code is used inside a large application. Answering this question is out of the scope of this document, but it should be considered seriously before starting any optimization effort. 2. How to measure the performance of the code? 3. What is the expected performance? Reducing Overhead Here are some general principles you can follow to improve the efficiency of your OpenCL code: ● Choose an efficient algorithm. OpenCL can take advantage of all the devices in the system, but only if the algorithms in your program are written to allow parallel processing. Consider the following when choosing an algorithm: ● The algorithm should be massively parallel, so that the computation can be carried out by a large number of independent work items: For data parallel calculations on a GPU, OpenCL works best where many work items are submitted to the device.. When sending work to a CPU, which typically has fewer cores than the GPU, it is important to match the number of work items to the number of threads the CPU can effectively support. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 82 Improving Performance● Most algorithms are memory-bound. Consequently, algorithms with the fewest memory accesses or algorithms with a high compute:memory ratio are usually best for OpenCL applications. The compute:memory ratio is the ratio between the number of floating-point operations and the number of bytes transferred to and from memory. ● OpenCL is most efficient on large datasets. If possible, select an algorithm that works on large chunks of data or merge several smaller tasks into one. ● For data parallel calculations on a GPU, OpenCL works best where there are a lot of work items submitted to the device; however, some algorithms are much more efficient than others. ● Building an OpenCL program is computationally expensive and should ideally occur only once in a process. Be sure to take advantage of tools in OS X v10.7 that allow you to compile once and then run many times. If you do choose to compile a kernel during runtime, you will need to execute that kernel many times to amortize the cost of compiling it. You can save the binary after the first time the program is run and reuse the compiled code on subsequent invocations, but be prepared to recompile the kernel if the build fails because of an OpenCL revision or a change in the hardware of the host machine. You can also use bitcode generated by the OpenCL compiler instead of source code; compilation will be much faster and you won’t have to ship source code with your application. ● Moving data to or from OpenCL devices is expensive. OpenCL gives you complete control over allocation of memory and host-device memory transfers. Your program will run much faster if you allocate memory on the OpenCL device, move your data to the device, do as much computation as possible on the device, then move it off—rather than repeatedly going through write-compute-read cycles. ● Allocating and freeing OpenCL resources (memory objects, kernels, etc.) takes time. Reuse these objects whenever possible instead of releasing them and recreating them repeatedly. Note, however, that image objects can be reused only if they are the same size and pixel format as needed by the new image. ● Local memory is faster than global memory and private memory is even faster. When using memory on an OpenCL device, the local memory shared by all the work items in a single workgroup is faster than the global memory shared by all the workgroups on the device. Private memory, available only to a single work item, is even faster. ● Experiment with your code to find the kernel size that works best. Using smaller kernels can be efficient because each tiny kernel uses minimal resources and breaking a job down into many small kernels can allow for the creation of very large and efficient workgroups. On the other hand, starting each kernel does take between 10-100 µs. When each kernel exits, the the results must be stored in global memory. Because reading and writing to global memory is expensive, concatenating many small kernels into one large kernel may save considerable overhead. What kernel size is ideal for your application? To figure that out, you will have to experiment with your code to find the kernel size that provides optimal performance. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 83● OpenCL events on the GPU are expensive. You can use eventsto coordinate execution between queues, but there is overhead to doing so. Use events only where needed; otherwise take advantage of the in-order properties of queues. ● When tuning for performance, it's really easy to introduce subtle errors that make the code run faster but produce bad output. After each iteration, always compare the output to a reference output computed on the host. For the same reason, be sure to keep all revisions in case you realize that you need to revert your code. ● Benchmark simple kernelsto estimate upper bounds and set optimization targets. See “Estimating Optimal Performance” (page 87). ● Use OpenCL built-in functions whenever possible. Optimal code will be generated for these functions. ● Balance precision and speed. GPUs are designed for graphics, where the requirements for precision are lower. The fastest variants are exposed in the OpenCL built-ins as fast_, half_, native_ functions. The program build options allow control of some speed optimizations. ● Take advantage of the memory subsystem of the device: ● When writing for the CPU, take advantage of the memory subsystem: reuse data while it’s still in L1 or L2 cache. To achieve this, use loop blocking and access memory in a cache-friendly pattern. ● On the GPU, the memory access pattern is the most important factor. Use faster memory levels (local memory, registers) to counter the effects of a sub-optimal pattern and to minimize accesses to the slower global memory. ● Avoid divergent execution: ● The CPU predicts the result of conditional jump instructions (corresponding to if, for, while, etc.) and starts processing the selected branch before knowing the effective result of the test. If the prediction is wrong, the entire pipeline needs to be flushed, and we lose some cycles. If possible, use conditional assignment instead. ● On the GPU, all threads scheduled together must execute the same code. As a consequence, when executing a conditional, all threads execute both branches, with their output disabled when they are in the wrong branch. It is best to avoid conditionals (replace them with a?x:y operators) or use built-in functions. ● Know what kind of device your code is executing on. OpenCL enables you to determine whether a device is a GPU or a CPU and how many devices are available. You can optimize your code for the hardware on which it is running. The same OpenCL code may run efficiently on both CPU and GPU, but optimal performance will usually require different code for each device. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 84GPUs and CPUs have fundamentally different architectures and so require different optimizations for OpenCL. For example, whereas a CPU has a relatively small number of processing elements and a large amount of memory (both a large cache and a much larger amount of RAM available on the circuit board), a GPU has a relatively large number of processing elements and a comparatively small amount of memory. ● When writing for the CPU: ● Write simple scalar code first. The compiler and the autovectorizer work best on linear code and can generate near-optimal code with no effort required from you. If the autovectorizer providessub-optimal results, add vectors to the code by hand. ● Use the -cl-denorms-are-zero option in clBuildProgram, unless you need to use denormals (denormals are very small numbers with a slightly different floating-point representation). Denormals handling can be extremely slow (100x slower) and can lead to puzzling benchmark results. ● CPUs are not optimized for graphics processing. Avoid using images. CPUs provide no hardware acceleration for images, and image access is slower than the equivalent buffer access. See “Tuning OpenCL Code For the CPU” (page 89) for specific optimization strategies for CPUs. ● When writing for the GPU: ● Keep in mind that each family of GPUs has a unique architecture. To get the best possible performance from a GPU, you need to understand that GPU’s architecture. For example, for a particular GPU it might be more efficient to write to memory in blocks of a certain size, or it might be desirable to have the number of work items in each workgroup a multiple of a particular number. Consult the literature of the manufacturer of any GPU you wish to support to get details about that GPU’s architecture. This document considers only general principles that should be true for any GPU. ● Avoid slow host-device transfers: ● Aggregate several transfers into a single, larger one. ● Design algorithms to keep the data on the device as long as possible. ● Try to maximize the compute/memory ratio and the number of independent dependency chains by grouping the computation of several output elements into one single work item. The GPU has huge computing power and kernels will usually be memory-bound. ● Try to use image objectsinstead of buffers. For certain memory access patterns, the different hardware data path used when accessing images may be more efficient. This is especially the case when you use 16-bit floating-point data (half). See “Tuning OpenCL Code For the GPU” (page 99) for specific optimization strategies for GPUs. Improving Performance Reducing Overhead 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 85Measuring Performance Execution time of OpenCL commands can be measured on the host or on the device. It is best to measure performance on the host, because it is closer to the user-perceived execution time. Measuring Performance On the Host To measure OpenCL command execution time on the host: 1. Call the gettimeofday function to determine the start time. The gettimeofday function provides wall clock time with microsecond granularity: Listing 11-1 Using the gettimeofday function #include // Return wall clock time (s). double getRealTime() { struct timeval tv; gettimeofday(&tv,0); return (double)tv.tv_sec+1.0e-6*(double)tv.tv_usec; } 2. Call clFinish(queue) to block the host thread until all the OpenCL commandsin the queue are executed. 3. When OpenCL processing completes, call the getTimeOfDay function to determine the elapsed time. Measuring Performance On Devices The following APIs allows you to measure time taken for various OpenCL commands and kernels queued in a block to a dispatch queue. ● Start a timer Call this function to start the timer: cl_timer gcl_start_timer(void); ● Stop the timer Call this function to stop the timer and return the elapsed time in seconds between when the call to cl_start_timer associated with the timer parameter and when commands & kernelsin the block have finished execution: Improving Performance Measuring Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 86double gcl_stop_timer(cl_timer timer); Measuring execution time of several consecutive calls to the same kernel(s) usually gives more reliable results. “Warming-up” the device also improves consistency of benchmarking results. Listing 11-2 (page 87) shows an example of benchmarking loop that can be included in kernel code: Listing 11-2 Sample benchmarking loop on the kernel const int iter = 10; // number of iterations to benchmark cl_timer blockTimer; for (int it=-2; it } clFinish(queue); gcl_stop_timer(blockTimer); // t = execution time for one iteration (s) Estimating Optimal Performance Before optimizing code, it is best to know what kind of performance is achievable. The main factor determining the execution speed of an OpenCL kernel is memory usage. This is the case for both CPU and GPU devices. Benchmarking the speed of the kernel function in Listing 11-3 (page 87) provides a way to estimate the memory speed of an OpenCL device. Listing 11-3 Kernel for estimating performance kernel void copyBuffer(global const float * in,global float * out) { int i = get_global_id(0); out[i] = in[i]; // R+W one float } Improving Performance Estimating Optimal Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 87On our test machine we measured the following memory copy speeds for buffer sizes ranging from 1KiB to 16MiB: Figure 11-1 Memory copy speed in GB/s (read+write) vs buffer size 100 1 KiB 4 KiB 16 KiB 64 KiB 256 KiB 1 MiB 4 MiB 16 MiB 75 50 25 0 Standard C library memcpy (running on one single thread) The OpenCL code running on the CPU The OpenCL code running on the GPU Several interesting observations can be made from these curves: ● The measured cost of invoking the OpenCL kernels is in the 10-20 µs range, something like 50,000 CPU clock cycles. For small tasks, it will be larger or comparable to the actual cost of the computation. ● The memcpy curve showsthe 4 different levels of the CPU memory hierarchy: L1 cache (90 GB/s), L2 cache (50 GB/s), L3 cache (30 GB/s), and external memory (12 GB/s). ● The OpenCL GPU curve shows how GPU memory runs much faster than the CPU external memory. We reach 36 GB/s for this mobile GPU, and some desktop GPUs can reach 160 GB/s. Important: OpenCL is more efficient when data size increases. Try to process larger problems in fewer kernel calls. The asymptotic (maximum) value memory speed can be used to estimate the speed of a memory-bound algorithm on large data. Improving Performance Estimating Optimal Performance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 88Take, for example, the following boxAvg kernel. It takes a single channel floating point image as input, and computes a single channel floating point image where each output pixel (x,y) is the average value of all pixels in a square box centered at (x,y). A w by h image is stored in a buffer float * A, where pixel (x,y) is stored in A[x+w*y]. Here is a first version of the code, before optimization: constant int RANGE = 2; kernel void boxAvg1(int w, int h, global const float * in, global float * out) { int x = get_global_id(0); // pixel to process is (x,y) int y = get_global_id(1); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dy=-RANGE;dy<=RANGE;dy++) for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; int yy = y + dy; // Accumulate if inside image if (xx>=0 && xx=0 && yy=0 && xx=0 && yy=0 && xx= 0) { sumA -= inRow[x-RANGE-1]; sum1 -= 1.0f; } if (x+RANGE < w) { sumA += inRow[x+RANGE]; sum1 += 1.0f; } // insert x+RANGE // Store current value out[x+w*y] = sumA/sum1; Improving Performance Tuning OpenCL Code For the CPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 94} } In this variant, we have reduced the memory accesses from 6 to 3 per iteration of the x loop. The execution speed of this variant is now 1366 Mpix/s (and only 822 Mpix/s without the autovectorizer). This is 91% of our upper bound. We can move the conditionals and the division out of the x loop by splitting it into three parts: Listing 11-7 Modify the horizontal pass by moving division and conditionals out of the inner loop // Horizontal pass v4. Global work size: H kernel void boxAvgH4(int w, int h, global const float * in, global float * out) { int y = get_global_id(0); // row to process is y global const float * inRow = in + y*w; // beginning of input row global float * outRow = out + y*w; // beginning of output row float sumA = 0.0f; float sum1 = 0.0f; // Left border int x = -RANGE; for (; x<=RANGE; x++) { // Here, sumA corresponds to segment 0..x+RANGE-1, update to 0..x+RANGE. sumA += inRow[x+RANGE]; sum1 += 1.0f; if (x >= 0) outRow[x] = sumA/sum1; } // x is RANGE+1 here // Internal pixels float k = 1.0f/(float)(2*RANGE+1); // constant weight for internal pixels for (; x+RANGE= number of CPU cores. kernel void boxAvgV3(int w,int h,global const float * in,global float * out) { // Numer of rows to process in each work item (rounded up) int rowsPerItem = (h+get_global_size(0)-1)/get_global_size(0); int y0 = rowsPerItem * get_global_id(0); // we update the range Y0..Y1-1 int y1 = min(h, y0 + rowsPerItem); for (int y=y0; y= number of CPU cores. // AUX[w*global_size(0)] is temporary storage, 1 row for each work item. kernel void boxAvg2(int w, int h, global const float * in, global float * out, global float * aux) { // Number of rows to process in each work item (rounded up) int rowsPerItem = (h+get_global_size(0)-1)/get_global_size(0); int y0 = rowsPerItem * get_global_id(0); // we update the range Y0..Y1-1 int y1 = y0 + rowsPerItem; aux += get_global_id(0) * w; // point to our work item’s row of temporary storage float k = 1.0f/(float)(2*RANGE+1); // constant weight for internal pixels // Process our rows. We need to process extra RANGE rows before and after. for (int y=y0-RANGE; y=h) continue; // out of range // Compute horizontal pass in AUX. // The boxAvg4 code goes here on input row y // The output is stored in AUX[W]. // Accumulate this row on output rows Y-RANGE..Y+RANGE for (int dy=-RANGE; dy<=RANGE; dy++) { int yy = y + dy; if (yy < max(0, y0) || yy >= min(h, y1)) continue; // out of range // Get number of rows accumulated in row YY, to get the weight int nr = 1 + min(h-1, yy+RANGE)-max(0, yy-RANGE); float u = 1.0f/(float)nr; // Accumulate AUX in row YY global float4 * outRow4 = (global float4 *)(out + w*yy); global float4 * aux4 = (global float4 *)(aux); for (int x=0; x<(w/4); x++) outRow4[x] += u * aux4[x]; } } } Thisfused version runs at 1166 Mpix/s. Some rows will be processed twice,since we have to compute horizontal filters on rows y0-RANGE to y1+RANGE-1 to update output rows y0 to y1-1. At any given time during the execution, we will access one row in aux, one input row, and 2*RANGE+1 output rows. For a 4096x4096 image, each row is 16 KiB, and all 7 rows fit in L2 cache. Important: Merging two kernels called one after the other can reduce memory accesses, and works on smaller data chunks fitting in faster cache levels, instead of of forcing the two kernels to resort to communicate via via full round trips to external memory. Tuning OpenCL Code For the GPU The conditions to efficiently use a modern GPU are similar to the conditions we listed for the CPU, but with a few notable differences. Efficient GPU optimization requires: ● Scheduling a large number of work items to use all resources and hide execution latency. ● Using the GPU memory hierarchy efficiently. Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 99The number of workgroups and work items required to efficiently utilize a GPU is much higher than for a CPU. Inside the GPU we have a few cores (typically 2 to 16). Each core schedules work items in small groups (64 work items in the test machine). All these items are executed at the same time and can issue up to five independent arithmetic ops. Instruction latency is much higher for the GPU. When all work items managed by the core are waiting for the result of a previously issued instruction still in the pipeline, the GPU core stalls, and we lose efficiency. One way to avoid this is to increase the number of work items; another solution is to have more independent dependency chains inside each work item. The GPU memory hierarchy can be seen as four levels with the following orders of magnitude for access bandwidth: ● Host memory accessed from the GPU through the PCI-Express bus, 10 GB/s ● OpenCL global memory, VRAM attached to the GPU, 100 GB/s ● OpenCL local memory, attached to each core, 1,000 GB/s ● OpenCL private memory, registers, 10,000 GB/s Memory management is explicit: the host code manages host-device transfers and each variable belongs to a unique address space (global, local, private, constant). The most important factor in OpenCL efficiency is the memory access pattern: at a given time, we may have hundreds of work items issuing a memory access instruction, each one with a different address. The hardware is optimized to processsome of these patterns very quickly. Other access patterns can lead to hardware conflicts. Hardware conflicts are resolved by serializing the accesses: they can’t occur in parallel,so the hardware schedules them one after the other. A bad access pattern can make code run up to 30x slower. A pattern where work item i accesses element x[i] of an array is fast. On the contrary, any pattern with a large stride (especially a power of 2), x[s*i], will be extremely slow when s becomes large enough. With such a large difference of bandwidth between the different layers, keeping reused data in the fastest levels is another key to efficiency. In particular, it is best to avoid host-device transfers: keep data resident on the GPU until it needs to be transferred to the host. If the output of OpenCL needs to be displayed, it is best to use CL/GL interoperability and have the output image mapped to an OpenGL texture. In Practice We will tune the same boxAvg code we used in “Tuning OpenCL Code For the CPU” (page 89), but this time for the GPU. We start from the same initial code for the horizontal pass as we did for the CPU: Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 100Listing 11-12 Kernel before optimization // Horizontal pass v1. Global work size: w x h kernel void boxAvgH1(int w,int h,global const float * in,global float * out) { int x = get_global_id(0); // pixel to process is (x,y) int y = get_global_id(1); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; // Accumulate if inside image if (xx>=0 && xx= 0 && xx < w)?in[xx+w*y]:0.0f; } // Block until all work items in the group finished updating AUX barrier(CLK_LOCAL_MEM_FENCE); // Compute our value float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels for (int dx=-RANGE;dx<=RANGE;dx++) { int xx = x + dx; Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 102sumA += aux[iid+dx+RANGE]; // will add 0 if out or range sum1 += (xx >= 0 && xx < w)?1.0f:0.0f; } // Store output out[x+w*y] = sumA/sum1; } In this example we are using all the work items in the workgroup to copy a segment of the input row to the local memory buffer aux. Note that a barrier call is required to ensure all items in the group have actually finished updating aux before we use the buffer. This kernel runs slightly faster, at 1043 Mpix/s. It can be modified to process several consecutive rows inside each work item, or several consecutive columns. The corresponding benchmarks are: Table 11-1 Benchmarks of boxAvgH5 variants: pix/item Mpix/s 1x1 1044 1x2 1630 1x4 1577 2x1 1300 4x1 1356 8x1 1123 Performance here is significantly improved, but is still far from the copy kernel reference speed of 4500 Mpix/s. Let’s direct our attention to the vertical pass. If it proves to be much faster, we may be able to use it twice with additional transpositions, assuming we can transpose an image efficiently. The boxAvgV1 kernel presented in the CPU section runs at 884 Mpix/s. Let’s modify this kernel to compute several rows in each work item: Listing 11-14 Modify the kernel to compute several rows in each work item // Vertical pass v4. Global work size: W x any Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 103kernel void boxAvgV4(int w, int h, global const float * in, global float * out) { // Number of rows to compute int rowsPerItem = (h+get_global_size(1)-1) / get_global_size(1); int x = get_global_id(0); // column to process int y0 = rowsPerItem * get_global_id(1); // rows to process are y0..y1-1 int y1 = min(h,y0+rowsPerItem); float sumA = 0.0f; // sum of pixel values float sum1 = 0.0f; // number of pixels // Load values y0-RANGE-1..y0+RANGE-1 for (int y=max(0, y0-RANGE-1); y < min(h, y0+RANGE); y++) { sumA += in[x+w*y]; sum1 += 1.0f; } // Process our rows for (int y=y0; y= 0) { sumA -= in[x + w*yy]; sum1 -= 1.0f; } yy = y+RANGE; if (yy < h) { sumA += in[x + w*yy]; sum1 += 1.0f; } // Store value out[x+w*y] = sumA/sum1; } } This one runs at 2296 Mpix/s, and we read+write 2+1 float per pixel instead of 5+1. If we can provide a dedicated kernel for each value of RANGE, we can reduce this to 1+1 float per pixel, by keeping a “ring” of previous 2*RANGE+1 values in registers. Doing so, we won’t need to reload the value for yy = y-RANGE-1 to remove it from the sum. Here is the modified code: Listing 11-15 Provide a dedicated kernel for each value of RANGE // Register ring, RANGE=2 kernel void boxAvgV4_ring(int w,int h,global const float * in,global float * out) Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 104{ // Compute number of rows to compute int rowsPerItem = (h+get_global_size(1)-1)/get_global_size(1); int x = get_global_id(0); // column to process int y0 = rowsPerItem * get_global_id(1); // rows to process are y0..y1-1 int y1 = min(h, y0+rowsPerItem); float2 r0, r1, r2, r3, r4; // ring has 5 values // Load values y0-RANGE-1..y0+RANGE-1 in the ring int yy; r0 = r1 = r2 = r3 = r4 = (float2)(0.0f); yy = y0-2; if (yy>=0) r1 = (float2)(in[x + w*yy],1.0f); yy = y0-1; if (yy>=0) r2 = (float2)(in[x + w*yy],1.0f); yy = y0; r3 = (float2)(in[x + w*yy],1.0f); yy = y0+1; if (yy=0) { r1 = in[x + w*yy]; s1 = 1.0f; } yy = y0-1; if (yy>=0) { r2 = in[x + w*yy]; s2 = 1.0f; } Improving Performance Tuning OpenCL Code For the GPU 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 106yy = y0; { r3 = in[x + w*yy]; s3 = 1.0f; } yy = y0+1; if (yy