DOCUMENTATION SHORTCUTS A number of shortcuts are available for accessing the help window and for quickly looking up key terms.. The quick help window is described in the “ Quick Help ”
Trang 1DOCUMENTATION SHORTCUTS
A number of shortcuts are available for accessing the help window and for quickly looking up key terms The global shortcuts are:
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:
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
Documentation Shortcuts ❘ 221
Trang 2The 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:
Command+[ Previous page in history
Trang 3SHORTCUT ACTION
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
Trang 4Managing 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
Trang 5The 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
Trang 6Customizing 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 http://lists.apple.com/mailman/listinfo 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
➤
➤
➤
➤
Trang 7SUMMARY
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 ( http://developer.apple.com/ ) 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