Lập trình Wrox Professional Xcode 3 cho Mac OS part 29 potx

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
222
❘
CHAPTER 12 HELP AND DOCUMENTATION
The quick help window has two action buttons, in addition to the standard title bar, resize, and
close controls. The button with the little book jumps to the full API documentation for that symbol
in the standard help window — equivalent to any of the other symbol search shortcuts mentioned in
this section.
If you have upgraded from an earlier version of Xcode, quick help replaces
the Research Assistant. The “Persistent Quick Help” section described how to
keep the quick help window open, where it acts very much like the Research
Assistant did.
The optional header button jumps to the defi nition of the symbol in the framework ’ s header ( .h )
fi le. This is equivalent to the Edit ➪ Find ➪ Jump to Defi nition (Command+double - click) shortcut.
Transient Quick Help
Quick help is intended to be just that: quick. When summoned from the editor using the
Option+double - click shortcut, it appears immediately adjacent to the symbol in question. Pressing
the Esc key, or clicking anywhere in the editor pane, dismisses the quick help window and returns
you to your coding.
Persistent Quick Help
If you summon the quick help window and then move or resize it, or open it using the Help ➪ Quick
Help (Control+Shift+Command+?) command, the quick help window becomes persistent; it will
not automatically close when you return to editing. Instead, it acts more like an inspector palette,
constantly updating its content based on the current text selection.
If you fi nd yourself referring to the quick help window a lot, consider letting it be persistent. If

you have limited screen real estate or, like me, only like to see it open when you need it, use the
Option+double - click shortcut to open it on demand and press Esc to close it again.
Documentation Shortcuts
The help document browser responds to the following standard shortcuts, although — oddly —
most are not associated with any of Xcode ’ s menus:
SHORTCUT ACTION
Command+[ Previous page in history
Command+] Next page in history
Command+F Find text, or fi nd next
c12.indd 222c12.indd 222 1/21/10 3:31:04 PM1/21/10 3:31:04 PM
Download at getcoolebook.com
SHORTCUT ACTION
Command+G Find next
Shift+Command+G Find previous
Command+D Add bookmark
MAN PAGES
UNIX man pages are another source of documentation that is loosely integrated with Xcode.
The C functions (section 3) of the man pages are included in the API search index. Looking up or
searching for a POSIX C function displays the man page for that function, but the man pages for
shell commands (section 1), fi le formats (section 5), system utilities (section 8), along with third -
party man pages are not indexed and cannot be found through the help window.
To review any man page installed in your system,
choose the Help ➪ Open man Page command, which
presents the dialog shown in Figure 12 - 15. There is
also a man . . . toolbar button that you can add to
your help window ’ s toolbar.
The man page name option invokes the
man command
with your search term and presents the resulting man
page in the help window.

The search string option invokes the apropos ( man - k ) command. This searches all of the short
descriptions in the man page database for the given keywords and presents the results in the help
window. Each result is linked to its man page, so review the search results and click the entries that
interest you.
CUSTOMIZING HELP
The Documentation pane of the Xcode preferences, shown in Figure 12 - 16, allow you to customize
three things: what documentation sets you subscribe to, what information is presented in the quick
help window, and how small the documentation text fonts are allowed to be.
FIGURE 12-15
Customizing Help
❘
223
c12.indd 223c12.indd 223 1/21/10 3:31:09 PM1/21/10 3:31:09 PM
Download at getcoolebook.com
224
❘
CHAPTER 12 HELP AND DOCUMENTATION
Managing Subscriptions
Any or all of the documentation sets installed in /Developer/Documentation can be maintained
through an RSS feed. Xcode can query these RSS feeds to determine if there are any updates to the
documentation sets. If new documentation is available, Xcode will offer to (or will automatically)
download the updated documentation and install it. Downloading documentation from Apple ’ s
servers requires that you provide your developer connection account ID and password, as shown in
Figure 12 - 17. This information will be saved for future updates. Installing new fi les in your
/Developer folder also requires an administrator ’ s authorization.
FIGURE 12-16
c12.indd 224c12.indd 224 1/21/10 3:31:10 PM1/21/10 3:31:10 PM
Download at getcoolebook.com
The Check For And Install Updates Automatically option instructs Xcode to periodically check for,
and install, new documentation updates. If left unchecked, you will want to manually check for

updates occasionally using the Check and Install Now button, preferably when you have a high -
speed Internet connection — documentation updates can be quite large. In Figure 12 - 16, you can
see that the iPhone OS 3.0 and Snow Leopard
Library documentation sets are in the process
of being downloaded. Be patient; even with a
fast network pipe, large documentation sets
can take an hour or more to download and
install. If you ’ re wondering what the progress
of the update is, check Xcode ’ s Activity
window, as shown in Figure 12 - 18.
A number of documentation sets have subscription feeds, but are disabled by default. In Figure 12 - 16,
the original iPhone OS Library, Java Library, and some other sets are not installed. Click the Get button
to download, install, and activate the RSS feed for that document set. If you ’ re curious about where the
fi les for a particular document set are installed, the address of its RSS feed, and other information, click
the small i (Info) button next to the set name.
You cannot delete any of the preinstalled document sets from Apple, but you can install additional
sets generated by you or a third party. The details of generating and installing your own Xcode -
compatible documentation is amply described in the article “ Using Doxygen to Create
Xcode Documentation Sets, ” which is part of the Xcode documentation set.
FIGURE 12-17
FIGURE 12-18
Customizing Help
❘
225
c12.indd 225c12.indd 225 1/21/10 3:31:10 PM1/21/10 3:31:10 PM
Download at getcoolebook.com
226
❘
CHAPTER 12 HELP AND DOCUMENTATION
Customizing Quick Help

To the right of the subscriptions is a panel where you can customize the content, and order, of
information that is presented in the quick help window. Check the sections that you want to appear.
Click and drag to change the order of those included.
Limiting Font Size
The only thing more frustrating than not fi nding what you ’ re looking for is fi nding it and then not
being able to read it. Checking the Never Use Font Sizes Smaller Than option lets you establish a
minimum font size for all text that appears in help windows.
THE XCODE COMMUNITY
This chapter has focused on the help and documentation resources accessible through the Xcode
interface, but one of the most valuable resources for Xcode users is other Xcode users .
In addition to supplementary developer information at Apple ’ s Developer Connection web site,
you ’ ll also fi nd a variety of mailing list and discussion forums. You can see the complete list of the
mailing lists at . Of particular interest is the Xcode -
users mailing list. This list is populated by Xcode users from all over the world and is a phenomenal
resource for solving problems with Xcode. I tapped the talented and helpful individuals of this list
several times while writing this book. I would strongly urge you to join the Xcode - users list.
As with many Internet discussion groups, members contribute their time and knowledge as a
courtesy to others and to support the community of Xcode users. Many are professional software
engineers with busy schedules and none of them are obligated to help you. Be respectful of their
time and efforts by adhering to these guidelines:
The list does not exist to solve your problems for you. Post questions only when you ’ ve read
all the available documentation (which should include this book), searched the list archives
for similar questions, and tried all of the solutions you can think of.
Be clear, concise, complete, and courteous.
Give something back. The list is a community of members helping members. If you know
the answer to a question, or have a helpful suggestion, take the time to post it. You can ’ t
expect others to help you if you never help anyone else.
The list is not your personal soapbox. It ’ s not a forum for rants and personal opinions. If
you want to provide feedback to the Xcode developers, use one of the feedback links on
Apple ’ s website or fi le an enhancement request via the bug reporter (available to registered

developers). In my experience, the Xcode development team is very open to suggestions that
will improve Xcode.
The list is not Apple support. If you need technical, sales, or developer support from Apple,
contact the appropriate party through ADC. Apple engineers have been known to monitor
and answer questions on the list, but they cannot provide you with any kind of offi cial sup-
port through the list.
➤
➤
➤
➤
➤
c12.indd 226c12.indd 226 1/21/10 3:31:11 PM1/21/10 3:31:11 PM
Download at getcoolebook.com
SUMMARY
Xcode includes a massive amount of documentation, and a variety of tools for working with
it. You ’ ve seen how to search for keywords and symbols, and fi nd API documentation from
within the class browser and directly from within your source code. You can even add you own
documentation, if you need to.
You may still not fi nd what you are looking for in the local documentation. Remember to avail
yourself of the Apple Developer Connection web site ( ). Apple ’ s
online resources contain many more articles, documents, and sample code than could ever be
downloaded and stored locally, and these resources are updated constantly.
Summary
❘
227
c12.indd 227c12.indd 227 1/21/10 3:31:11 PM1/21/10 3:31:11 PM
Download at getcoolebook.com
c12.indd 228c12.indd 228 1/21/10 3:31:11 PM1/21/10 3:31:11 PM
Download at getcoolebook.com