You enable Code Sense globally for all projects in the Code Sense panel of the Xcode preferences, as shown in Figure 7-1.

Figure 7-1. FIGURE 7-1

The Enable for All Projects option turns all Code Sense–dependent features on or off. This includes some syntax coloring, code completion, jump to definition, the Included Files and Class Hierarchy navigation menus, the Symbols smart group, and the Class Browser. The only real motivation for disabling Code Sense is to avoid the CPU, memory, and disk space required to maintain it, but these seem like small prices to pay for the enormous benefits that Code Sense provides. I would recommend disabling it only if absolutely necessary.

Code Sense works by interacting intimately with the compiler. This also requires that all the source items are members of a "native" target. Native targets are targets that Xcode knows how to build (see Chapter 16), and by extension it knows what compilers will be used to compile each source file. External (non-native) targets defer the actual build process to some external program, such as Make or Ant. Items in external targets cannot use Code Sense.

Because Code Sense works silently in the background, it's sometimes hard to tell whether a symbol isn't in the Code Sense index or whether Code Sense just hasn't reindexed it yet. The Window

If you suspect that the Code Sense index has gotten out of synchronization with your project, open the Info widow for the project (Project

The Code Sense index is stored in your account's ~/Library/Caches folder. If the Code Sense index is ever deleted or is not in synchronization, Xcode automatically rebuilds it.

Figure 7-2. FIGURE 7-2

You control the colors that syntax coloring uses, or whether syntax coloring is done at all, in the Fonts & Colors tab of the Xcode Preferences, shown in Figure 7-3.

Figure 7-3. FIGURE 7-3

Each entry in the table controls the color, and possibly the font, used to display a category of editor element. The entire collection is collectively referred to as a theme. Xcode provides several themes that you can choose from, and you can create your own. The major categories are described in the following table.

You can control syntax-aware coloring globally with the Use Syntax-Based Formatting and Color Indexed Symbols options. Turning the first option off disables all syntax coloring. With syntax coloring enabled, the second option determines whether only basic language elements are colorized, or whether project symbols in the Code Sense index are also colorized.

In addition to the syntax coloring, this preference pane also establishes the font and color scheme used in all editing panes. This includes the background color of the pane and the color used to highlight selected text. The list is broadly organized into three groups of entries:

Text that isn't colorized — either because it's not one of the recognized categories or you've turned off the Use Syntax-Based Formatting or Color Index Symbols options — is displayed using the Plain Text color and font.

Font & Color themes provided by Xcode are not editable. To create a customized theme, begin by clicking the Duplicate button to make a copy of any existing theme. To delete a custom theme, select it as the current theme and click the Delete button. If you attempt to edit a built-in theme, Xcode alerts you and gives you the opportunity to duplicate it.

To customize an element, select the category (or categories) in the list and apply any of the text styling commands found in the Edit

Syntax coloring is naturally dependent on Xcode knowing in what language your source file is written. By default, Xcode uses the file's type (see the "Source Item Attributes" section in Chapter 5) to determine this. The vast majority of time this is correct. If, for any reason, Xcode guesses wrong, you can manually specify that it use a different language when interpreting the file by selecting the correct language (or None) from the View

Figure 7-4. FIGURE 7-4

When Default is selected, the language Xcode has chosen is displayed as a dash in the menu of available languages.

For files that belong to a project, this setting is stored in the project document and is persistent. Otherwise, the selection is lost when the editor pane is closed.

Code focus highlights a block of text in the editor, making it easier to see what the block encompasses, as shown in the bottom window in Figure 7-5. Code focus appears when you hover your cursor over the code folding ribbon. Uncheck the Code Focus option in the preferences to disable this behavior.

If you find code focus really useful, even temporarily, and are tired of moving your cursor over the code folding ribbon, you can have code focus follow your current text selection by choosing View

You have four ways to fold a block of code, listed in the following table.

ACTION OR COMMAND	EFFECT
Collapse button in ribbon	Collapses highlighted block
View	Collapses block containing the current selection
View	Collapses the outmost block of every method or function
View	Collapses all multi-line comments

Folded code is collapsed and replaced with an ellipsis placeholder, as shown in Figure 7-6.

Figure 7-6. FIGURE 7-6

The Fold command folds the block containing the current text selection or insertion point, and is the only fold action that uses the current selection. The Collapse button folds the highlighted block in the ribbon, and the other two commands apply globally to the entire file.

Folding comment blocks only applies to multi-line comments (like /* ... */). The command does not recognize, or fold, successive lines of single-line comments (//).

Have no fear; the text in the folded region is still there. Including a folded block placeholder in a text selection includes all of the text in that block, just as if it weren't folded.

You have six ways to unfold code, listed in the following table.

ACTION OR COMMAND	EFFECT
Expand button in ribbon	Expands collapsed block
View	Expands blocks contained in the selected text or in the selected block
View	Expands the outmost block of every method or function
View	Expands all multi-line comments
View	Expands all collapsed blocks
Display any text in a collapsed block	Expands the block containing the text

The first four actions are symmetric complements to the code folding actions in the previous section. In addition, the Unfold All command unfolds all collapsed blocks of code. Finally, any action that you take that causes some text to be selected or revealed — searching for text or jumping to a symbol definition — automatically expands the block so that the text is visible.

Xcode makes a distinction between the width of the tab stops and the amount by which each line of code is indented. The two numbers do not have to be the same. The Tab Width setting, shown in Figure 7-7, determines the width of the tab stops in characters. The Indent Width setting is the number of columns' worth of white space added to the beginning of a line to indent it one level. Xcode uses the most efficient combination of spaces and tabs that it can. If the indent width is an integer multiple of the tab width, only tab characters are used to indent lines. If not, a combination of tabs and spaces is used to achieve the desired indentation. Say you have a tab width of 8 and an indent width of 4. To indent a line one level requires four space characters. Indenting two levels would cause these spaces to be replaced by a single tab.

The global tab and indent width settings can be overridden for an individual file either in the Info window for the file, or by choosing the View

Figure 7-8. FIGURE 7-8

The Editor Uses Tabs option permits the use of tab characters to indent lines. Turning it off forces Xcode to use spaces for all indenting. This is the safest option when you're sharing code with other programmers who might not be using the same tab width, but it also makes your files substantially larger. I also think it makes deleting the white space in lines awkward, and also makes it easier to inadvertently align text at odd indentations.

The Reset to Text Editing Defaults button returns the file to using the global settings in the Indentation preferences panel. File-specific editor settings are maintained for the file in its project document. The settings will not be remembered for files that are not assets of a project, and the settings are independent of other projects.

Automatic indenting occurs whenever you start a new line by pressing the Return key. The editor inserts the same amount of indentation on the new line as was present on the line above it. This feature is always active. To circumvent it for a single line, type Option+Return at the end of the line. Option+Return starts a new line with no indentation. There is no simple option to turn off auto-indentation globally, but it can be defeated by changing the key binding for the Return key, as explained in Chapter 23.

Enabling Syntax-Aware Indenting in the Indentation pane of the Xcode Preferences turns on a number of additional features that will aid you in indenting source code and forming code blocks. You can have Xcode do any of the following:

Each feature can be independently configured or disabled, as desired.

Syntax-Aware Tab Indenting

The Tab Indents option determines what action occurs when you press the Tab key. It has three settings, as described in the following table.

TAB INDENTS SETTING	TAB KEY ACTION
In Leading White Space	When the text cursor is at the beginning, in, or immediately to the right of any white space at the beginning of the line, pressing the Tab key causes the entire line to be indented one level. When not in this leading non–white space portion of the line, the Tab key inserts a single tab character.
Always	Regardless of where the cursor position is within the line, pressing the Tab key causes the line to be re-indented.
Never	Tab key inserts a tab character.

The In Leading White Space setting is the most useful when you're programming in block-structured languages. At the beginning of the line, pressing the Tab key indents the line. Within the line, typically at the end of a statement where you want to begin a comment, the Tab key simply inserts a tab character.

Note

"White space" refers to the non-graphic, printable characters in the Unicode character set. Practically, that means the tab, space, and end-of-line characters, but, technically, it also includes characters like the non-breaking space (Unicode 0x00A0). White space characters get their name from the fact that they cause subsequent characters in the file to be shifted to new lines or column positions, but are not themselves visible. In other words, they just leave a white space on the page.

Note that the first two settings are not variations on one another. Xcode has two indentation functions: indent and re-indent. Indent increases the indentation level of a line by inserting more white space. Re-indention looks at the indention of the line with respect to the indentation of the line that precedes it, and uses syntax-aware rules to determine what its indentation level should be. Repeatedly indenting a line continues to shift the line further and further to the right. Repeatedly re-indenting a line does nothing. Until you change the contents of the line, or the preceding line, Xcode repeatedly reformats the text to the same indentation level.

You can circumvent the settings for the Tab key at any time by using Option+Tab or Control+I. Option+Tab always inserts a tab character, regardless of the syntax-aware tab settings. Control+I always performs a re-indent of the currently selected line, or lines, and is the same as the Edit

if (a==b)
{
    foo();
}

if (a==b)
    {
    foo();
    }

if (a==b)
  {
    foo();
  }

if (a==b)
{   foo();
}

Automatically Close { ... } Blocks

The Automatically Insert Closing "}" option does two things when you type a { character: it inserts a line with a matching } ahead of the cursor, and then it advances to the next line as if the Return key had been pressed. The effect is simple: typing a { creates a balanced block with the cursor positioned at the first line of the block. Figure 7-9 shows an if statement before and after a single { character was typed.

Figure 7-9. FIGURE 7-9

Controlling When Automatic Indentation Occurs

The Automatically Indented Characters setting selects the characters that trigger an automatic re-indentation of the current line. When a character in the set is checked, typing one of those characters is the same as invoking the Edit

No // Comment Formatting
   int main (int argc, char * const argv[])

   {

   // Check the environment

       char * server_addr = getenv("SERVER");

       if (server_addr==NULL)

           exit(3);        // terminate immediately

                  // returning a status of 3

Indent // Comments Only

   int main (int argc, char * const argv[])

   {

       // Check the environment

       char * server_addr = getenv("SERVER");

       if (server_addr==NULL)

           exit(3);        // terminate immediately

       // returning a status of 3

Indent // Comments and Align Consecutive // Comments

   int main (int argc, char * const argv[])

   {

       // Check the environment

       char * server_addr = getenv("SERVER");

       if (server_addr==NULL)

exit(3);        // terminate immediately

                          // returning a status of 3

As mentioned earlier, re-indenting text uses the language-specific rules to determine the appropriate indentation level for each line. This can happen automatically as you type, depending on which syntax-aware indentation options you have enabled, or manually when you use Control+I or the Edit

You can always manually alter the indentation level of a line, or lines, using the Edit

Code completion appears in two forms: suggestions and completion lists. Suggestions appear ahead of your typing, as shown in Figure 7-11. In this example I typed the text NSDic and code completion suggested the rest.

Figure 7-11. FIGURE 7-11

The portion of grey text to the right of the insertion point is the suggestion. You can accept a suggestion by pressing the Tab key. To ignore a suggestion, just keep typing.

The highlighted portion of the suggestion is what will be inserted if you press the Tab key. Xcode recognizes that many symbol names are very similar. In the code in Figure 7-11, you might want to type NSDictionary or NSDictionaryController. If you wanted NSDictionary, press Tab once (to accept the NSDictionary portion) and continue typing. If you wanted NSDictionaryController instead, start by pressing the Tab key once to accept the tionary suggestion. Code completion immediately returns with all of the suggestions that begin with NSDictionary, which include NSDictionaryController, as shown in Figure 7-12. Pressing Tab a second time accepts the Controller suggestion and the classname is complete.

Figure 7-12. FIGURE 7-12

This successive refinement of suggestions permits you to narrow down your choice quickly from huge families of class and constant names that share common prefixes.

Getting Another Suggestion

At any time — even when a suggestion isn't being presented in your text — you can prompt Xcode to offer the next suggestion in its list of candidates by choosing Edit

Figure 7-13. FIGURE 7-13

If you like the suggestion, just keep typing — the suggestion is already part of your text. If you don't, choose Edit

Choose Edit

Figure 7-14. FIGURE 7-14

The list can be extensive. In this example, it includes every method of NSNotification, every method of its NSObject superclass, and every category of NSObject. The list can be navigated using the mouse or keyboard (up arrow, down arrow, home, end, page up, page down). You can also continue to type; the completion list will refine itself as you do. Press Tab or Return to accept the currently selected suggestion from the list, or Esc again to close the list.

The typical technique is to use the completion list as a guide to what symbols exist. Type enough of the first portion of the symbol you want, until the list becomes short enough to use the keyboard arrows to select the desired symbol from the list. Then press Tab or Return to insert the suggestion.

When Xcode completes a function or method name, it inserts placeholders for its arguments, as shown in Figure 7-15.

Figure 7-15. FIGURE 7-15

After the completion, the first placeholder is selected automatically. To provide a value for the first placeholder just begin typing — with code completion, of course. The special Edit

The Show Arguments in Pop-Up List option of the Code Sense Preferences pane (see Figure 7-1) controls whether argument placeholders appear in suggestion or the completion list. C, C++, and Java programmers should turn this option on. These languages use method overloading and without the argument placeholders it's impossible to distinguish between multiple functions that differ only in their argument types. Objective-C programmers, on the other hand, will probably want to turn this off because Objective-C method names are unique and tend to be descriptive of their argument types.