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