Lập trình Wrox Professional Xcode 3 cho Mac OS part 28 docx

214 ❘ CHAPTER 12 HELP AND DOCUMENTATION These commands are: COMMAND ACTION Open Link Same as clicking the link Open Link in New Window Creates a second Xcode help window with the contents of the link Copy Link Copies the URL of the link to the clipboard Open Link in Browser Sends the URL of the link to your default browser Find Text in Documentation Enters the link or selected text as the search term (see the “ Searching Documentation ” section later in this chapter) Open Page in New Window Creates a second Xcode help window with the same content Open Page in Browser Sends the URL of the current page to your default browser The “ in New Window ” commands are the only way of creating multiple help windows. The original help window remains the principal help window for your project; shortcuts, for example, are always directed to the principal help window. Opening a link or page in your browser is a great way of keeping multiple documentation pages open at once. Modern browsers, with their tabs and workspace sets, can be much more effective at organizing, remembering, and managing multiple help documents than the simple Xcode help window. SAMPLE PROJECTS A special kind of external link is found in sample project pages. Recently, the Xcode developer tools suite has moved away from providing sample projects as part of the installation to providing links to sample projects in the documentation, going so far as to cross - reference each API with the example FIGURE 12-7 c12.indd 214c12.indd 214 1/21/10 3:30:50 PM1/21/10 3:30:50 PM Download at getcoolebook.com projects that use it. Figure 12 - 8 shows the ButtonMadness sample project page. I got to this page from the insertMenu:atIndex: method reference document. FIGURE 12-8 You have two ways of exploring a sample project. The fi rst is simply to view the source fi les in the help window using the pop - up menu, also shown in Figure 12 - 8. The other method is to click the Open Project in Xcode button. You ’ ll be prompted for a location on your disk. Choose a location and Xcode downloads the project archive to the selected folder, extracts the project fi les, and opens the project. If it did anything more for you, you ’ d be obligated to tip it afterwards. SEARCHING DOCUMENTATION Browsing the ADC documentation is great way to get an overview of a technology or work through a tutorial. During actual development, however, you usually just want to fi nd something specifi c — and you want to fi nd it in a hurry. The simplest way is to enter a search term into the search fi eld. Search Field The help window ’ s search fi eld is in the toolbar, as shown in Figure 12 - 9. Entering anything into the search fi eld activates the help window ’ s search mode and adds two additional sets of controls. Searching Documentation ❘ 215 c12.indd 215c12.indd 215 1/21/10 3:30:50 PM1/21/10 3:30:50 PM Download at getcoolebook.com 216 ❘ CHAPTER 12 HELP AND DOCUMENTATION The search control bar appears underneath the toolbar and a search results sidebar appears on the left of the content area. These controls let you refi ne the search and browse its results. Your search term is instantly and simultaneously used to search the documentation in three ways: API Symbols Article Titles Article Text The results of each search appear in its own group in the search results sidebar. Each group always shows the most likely matches. If there are more, you can expand the results list by clicking one of the Show More Results buttons. The API symbols group only searches the Application Programming Interface index of the documentation. These are the class, method, function, variable, and constant names documented in the API reference material. If you ’ re looking for some specifi c framework or symbol, this is where you are mostly like to fi nd it. The article title and text groups search the titles and complete text of every article, technical note, guide, and reference page for a match. If you are trying to fi nd a description of a particular technology or topic, these are the search groups you are most likely to fi nd it in. A search term can contain multiple keywords and operators. The search fi eld recognizes the following operators: ➤ ➤ ➤ FIGURE 12-9 c12.indd 216c12.indd 216 1/21/10 3:30:51 PM1/21/10 3:30:51 PM Download at getcoolebook.com OPERATOR MEANING ( ) Logical group. Treats the terms between the parentheses as a single term. ! Not. Inverts the sense of the search term. & And. Requires that the term on the left and right are both found. This is the default when you ’ re searching for multiple keywords. | Or. Matches if either the term on the right or the term on the left is found. + Required word. Equivalent to just searching for a keyword. - Unwanted word. Excludes any results that contain that keyword. * Wildcard. Creates a keyword that matches a partial word (for example, menu* or *Notification ). For example, the following search term locates all articles that contain the word “ services, ” and either the word “ sync ” or “ system, ” but do not contain the word “ audio ” : (sync | system) services -audio Every symbol in the API index is considered to be a single word. No multi- keyword search will ever match an API symbol, even if the symbol contains all of the keywords. Clearing the search fi eld hides the search control bar and the results sidebar again. Search Control Bar The search control bar further refi nes how the search keywords are applied, and the scope of what ’ s searched. The search control bar has three controls, all shown in Figure 12 - 9. Word Boundary The word boundary control determines how each search keyword must match a symbol or word in the documentation: WORD BOUNDARY SETTING MATCH RULE Contains Keyword can appear anywhere in the word Prefi x Keyword must match the beginning of the word Exact Keyword must match the whole word Searching Documentation ❘ 217 c12.indd 217c12.indd 217 1/21/10 3:30:51 PM1/21/10 3:30:51 PM Download at getcoolebook.com 218 ❘ CHAPTER 12 HELP AND DOCUMENTATION The prefi x setting is most useful when searching the API reference documents for symbols. It allows you to type the beginning of a known symbol and quickly narrow down the list of symbols you ’ re looking for. Contains and Exact apply equally to API and text searches. The wildcard operator may defeat or interact with the word boundary setting. For example, searching for menu* using the Exact setting is the same as searching for menu with the Prefi x setting. Documentation Sets You can limit which sets of documentation Xcode searches by selecting them in the Doc Sets control, shown in Figure 12 - 10. FIGURE 12-10 Select only the platforms or technologies that you ’ re using for development right now. That limits the scope of your searches to just the documentation that ’ s appropriate for your development. If you are doing cross development that targets several versions of an operating system, you might also want to uncheck the modern documentation sets. That way, you ’ re unlikely to accidentally use an API that only exists in the more recent OS. Language Sets The language sets control, shown in Figure 12 - 11, further limits your API symbol searches to only those symbols defi ned in the selected languages. For example, if you ’ re programming in Objective - C, check C and Objective - C. If you ’ re programming in JavaScript, uncheck everything except JavaScript. If you ’ re programming in Objective - C++, you may want to check C, C++, and Objective - C. c12.indd 218c12.indd 218 1/21/10 3:30:57 PM1/21/10 3:30:57 PM Download at getcoolebook.com Text Search The help document browser includes a simplifi ed text search tool, very much like the single fi le search tool described in Chapter 8, for searching through the text of the current document. Press Command+F to reveal the search tool, as shown in Figure 12 - 12. FIGURE 12-11 FIGURE 12-12 The document search tool has no options, but responds to the same Find Next (Command+G) and Find Previous (Shift+Command+G) commands that the single fi le search tool does. Click the Done button to dismiss the tool. Searching Documentation ❘ 219 c12.indd 219c12.indd 219 1/21/10 3:31:02 PM1/21/10 3:31:02 PM Download at getcoolebook.com 220 ❘ CHAPTER 12 HELP AND DOCUMENTATION Command and Xcode Help Search To fi nd a command or a particular Xcode help topic, enter a term directly into the help menu ’ s search fi eld, as shown in Figure 12 - 13. FIGURE 12-13 In Figure 12 - 13, the keyword “ breakpoint ” fi nds several Xcode commands and a variety of help documents. Hovering over one of the commands results reveals that command in the menu structure so that you can fi nd it again in the future. This is a great way to fi nd menu commands. There are a lot of commands in the Xcode menus, and it ’ s easy to lose track of where they are. Also, it seems that every new release of Xcode moves or renames about a third of the commands, so even seasoned Xcoders need to reorient themselves from time to time. The lower portion of the menu lists the Xcode help document topics that match the search term. These open the help window to a specifi c Xcode help document. Finally, the Search in Documentation Window command at the very bottom of the menu opens the help window and performs the same search, for those times where you don ’ t fi nd what you ’ re looking for in the menu. c12.indd 220c12.indd 220 1/21/10 3:31:03 PM1/21/10 3:31:03 PM Download at getcoolebook.com DOCUMENTATION SHORTCUTS A number of shortcuts are available for accessing the help window and for quickly looking up key terms. The global shortcuts are: SHORTCUT ACTION Option+Shift+Command+? Opens the help window Control+Shift+Command+? Opens the quick help window Shift+Command+? Activates the Help menu These three shortcuts are available almost universally in Xcode. The quick help window is described in the “ Quick Help ” section a little later in this chapter. The next few sections describe other kinds of documentation shortcuts and how to access them. Editing Shortcuts You will most likely want to consult the documentation for a particular function or method while editing code. With a symbol name selected in the text editor pane, you have the following menu command and shortcuts available to you: SHORTCUT ACTION Option+Shift+double - click Searches for symbol in documentation Option+double - click Opens quick help window for symbol Control/Right - click ➪ Find Text in Documentation Searches for selected text in documentation Help ➪ Find Documentation for Selected Text Same as Find Text in Documentation The two most useful shortcuts are the Option+Shift+double - click and Option+double - click gestures. These immediately select the word (symbol) underneath the cursor and search for its defi nition in either the help window or the quick help window (described in the next section). Quick Help The quick help window, shown in Figure 12 - 14, is a miniature help window that presents a succinct summary of a single API symbol. It operates in two modes: transient and persistent. FIGURE 12-14 Documentation Shortcuts ❘ 221 c12.indd 221c12.indd 221 1/21/10 3:31:03 PM1/21/10 3:31:03 PM Download at getcoolebook.com . 219 1/21/10 3: 31:02 PM1/21/10 3: 31:02 PM Download at getcoolebook.com 220 ❘ CHAPTER 12 HELP AND DOCUMENTATION Command and Xcode Help Search To fi nd a command or a particular Xcode help topic,. performs the same search, for those times where you don ’ t fi nd what you ’ re looking for in the menu. c12.indd 220c12.indd 220 1/21/10 3: 31: 03 PM1/21/10 3: 31: 03 PM Download at getcoolebook.com DOCUMENTATION. persistent. FIGURE 12-14 Documentation Shortcuts ❘ 221 c12.indd 221c12.indd 221 1/21/10 3: 31: 03 PM1/21/10 3: 31: 03 PM Download at getcoolebook.com