Web Kit Objective-C Programming Guide 2006-05-23 WebScript is a trademark of NeXT Software, Apple Computer, Inc. Inc. © 2003, 2006 Apple Computer, Inc. Java and all Java-based trademarks are All rights reserved. trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other No part of this publication may be countries. reproduced, stored in a retrieval system, or transmitted, in any form or by any means, Simultaneously published in the United mechanical, electronic, photocopying, States and Canada. recording, or otherwise, without prior Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR written permission of Apple Computer, Inc., REPRESENTATION, EITHER EXPRESS OR with the following exceptions: Any person IMPLIED, WITH RESPECT TO THIS is hereby authorized to store documentation DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A on a single computer for personal use only PARTICULAR PURPOSE. AS A RESULT, THIS and to print copies of documentation for DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE personal use provided that the ENTIRE RISK AS TO ITS QUALITY AND documentation contains Apple’s copyright ACCURACY. notice. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, The Apple logo is a trademark of Apple OR CONSEQUENTIAL DAMAGES Computer, Inc. RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if Use of the “keyboard” Apple logo advised of the possibility of such damages. (Option-Shift-K) for commercial purposes THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN without the prior written consent of Apple LIEU OF ALL OTHERS, ORAL OR WRITTEN, may constitute trademark infringement and EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any unfair competition in violation of federal modification, extension, or addition to this and state laws. warranty. No licenses, express or implied, are granted Some states do not allow the exclusion or limitation of implied warranties or liability for with respect to any of the technology incidental or consequential damages, so the described in this document. Apple retains above limitation or exclusion may not apply to you. This warranty gives you specific legal all intellectual property rights associated rights, and you may also have other rights which with the technology described in this vary from state to state. document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, Mac, Mac OS, Pages, QuickTime, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Safari is a trademark of Apple Computer, Inc. Objective-C is a registered trademark of NeXT Software, Inc. Contents Introduction to Web Kit Objective-C Programming Guide 9 Who Should Read This Document? 10 Organization of This Document 10 See Also 11 Why Use the Web Kit? 13 Core Web Kit Classes 15 Frame Model and View Classes 15 Data Model and View Classes 16 Provisional vs. Committed Data Sources 18 WebView Delegates 19 Simple Browsing 21 Multiple Windows 23 Opening Windows 23 Entering URLs 24 Handling New Window Requests 24 Loading Pages 27 Sequence of Frame Load Delegate Messages 27 Testing for the Main Frame 28 Displaying the Current URL 28 Displaying the Page Title 29 Displaying Load Status 29 Loading Resources 31 Sequence of Resource Load Delegate Messages 31 Identifying Resources 32 Tracking Resource Load Progress 32 3 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Paging Back and Forward 35 Enabling and Disabling the Back-Forward List 35 Adding Back and Forward Buttons 35 Setting the Page Cache 36 Setting the Capacity 36 The Current Item 36 Managing State 36 Managing History 39 Sharing History Objects 39 Adding and Removing History Items 39 Loading a History Item 40 Saving and Loading History Objects 40 Making Policy Decisions 41 Enabling Editing 43 Saving and Loading Web Content 45 Modifying the Current Selection 47 Changing Editing Behavior 49 Should Methods 49 Did Methods 50 Using Undo When Editing 51 Using the Document Object Model from Objective-C 53 Interpreting the DOM Specification 53 Handling Exceptions 55 4 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Using the Document Object Model Extensions 57 Using JavaScript From Objective-C 59 Spoofing 61 Accessing the Web Kit From Carbon Applications 63 Determining Web Kit Availability 65 Testing for URL Loading System Availability 65 Testing for Web Kit Availability 65 Isolating Your Web Kit and URL Loading System Symbols 66 Conditionally Loading Code 66 Weak Linking Symbols 66 Document Revision History 69 5 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. 6 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Figures and Listings Core Web Kit Classes 15 Figure 1 WebView and WebFrameView objects 16 Figure 2 WebFrame and WebDataSource objects 17 Figure 3 Typical website 18 Determining Web Kit Availability 65 Listing 1 Determining if the URL Loading system is available. 65 Listing 2 Determining if the Web Kit framework is available 66 Listing 3 Loading Web Kit constants dynamically using CFBundle 67 7 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. 8 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to Web Kit Objective-C Programming Guide Note: This document was previously titled Displaying Web Content. Important: Web Kit is available as an Objective-C API for Mac OS X version 10.3 and later. The HTML editing, JavaScript, and DOM APIs are available in Mac OS X version 10.3.9 and later. What Is the Web Kit? The Web Kit provides a set of core classes to display web content in windows, and by default, implements features such as following links clicked by the user. The Web Kit greatly simplifies the complicated process of loading webpages—that is, asynchronously requesting web content from an HTTP server over the network where the response may arrive incrementally, in random order, or partially due to network errors. The Web Kit also simplifies the process of displaying content that can contain various MIME types, and multiple frames each with their own set of scrollbars. You use the Web Kit to display web content in a window of your application. It’s as simple as creating a view, placing it in a window, and sending a URL load request message. By default, your Web Kit application behaves as you would expect without error. The Web Kit conveniently creates and manages all the views needed to handle different MIME types. When the user clicks on a link in a page, the Web Kit automatically creates the views needed to display the next page. However, the Web Kit doesn’t implement a complete set of web browser features. You can, however, extend the Web Kit by implementing custom delegate, view, and model objects. For example, you can implement a delegate to display load status, and the current URL. The Web Kit also offers web content editing. If you enable editing in your WebView, users can edit the web content it displays. You can programmatically control the current selection and control editing behavior using a WebView delegate. You can also modify the Document Object Model directly using an Objective-C API. You can also access JavaScript from Objective-C and visa versa. What Is the Web Kit? 9 2006-05-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to Web Kit Objective-C Programming Guide Who Should Read This Document? The Web Kit Objective-C API is specifically designed for embedding web content in your Cocoa or Carbon applications—developing web client applications not web server applications or web content. It is also not suitable for implementing non-GUI applications such as web crawlers. If you are a web content creator or JavaScript programmer, refer to Safari JavaScript Programming Topics. Important: Currently, this API is available in Objective-C only. A minimal C API is provided for embedding web browser views in Carbon applications. You can use Objective-C in combination with C. The Web Kit works with all versions of Mac OS X 10.2 that have Safari 1.0 installed. Organization of This Document The following articles cover key concepts in understanding how the Web Kit works: ■ "Why Use the Web Kit?" (page 13) describes the purpose of the Web Kit and why you might want to use it in your applications. ■ "Core Web Kit Classes" (page 15) describes the core Web Kit classes and the object-oriented design that is fundamental to understanding how the Web Kit works. The following articles explain how to display web content in views: ■ "Simple Browsing" (page 21) shows how to embed web content in your application by following a few simple steps. ■ "Multiple Windows" (page 23) shows how to add support for multiple windows, and open windows automatically. ■ "Loading Pages" (page 27) shows how to track the progress of loading frame content. ■ "Loading Resources" (page 31) shows how to track the progress of loading individual resources on a page. ■ "Paging Back and Forward" (page 35) shows how to implement a back-forward list and add Back and Forward buttons to your application. ■ "Managing History" (page 39) shows how to maintain a history of all the visited pages, and allow the user to go to a previously visited page. ■ "Spoofing" (page 61) shows how to use user-agent strings.