Navigation Bar

The navigation bar contains a number of controls that you can use to move between files you’ve viewed, jump to symbols, and open related files. Figure 4-2 shows the navigation bar.

Here is what the navigation bar contains:

• Go Back/Go Forward. Move between and within open files in the editor. See Navigating Code for details.

• File History menu. Lists the files recently viewed in the current text editor. Choosing a file from this menu displays that file in the editor, without having to repeatedly click the Next or Previous arrows.

• Function menu. Shows the function and method definitions in the current file. When you choose a definition from this menu, the editor scrolls to the location of that definition. For information on how to configure the Function menu, see The Function Menu.

• Bookmarks menu. Contains any bookmarked locations in the current file. When you choose a bookmark from this menu, the editor scrolls to the location of the bookmark. See Defining Bookmarks to learn more about bookmarks in your project.

• Breakpoints menu. Lists breakpoints in the current file. Choosing a breakpoint from this menu scrolls the editor to the location at which the breakpoint is set. See Managing Program Execution to learn more about breakpoints.

• Class Hierarchy menu. Allows you to navigate the class hierarchy of an Objective-C class.

• Counterpart button. Opens the counterpart of the current file or jumps to the symbolic counterpart of the currently selected symbol. See Jumping to the Counterpart of a File or Symbol for more information on the Counterpart button.

• Included Files menu. Lists the files included by the current file, as well as the files that include the current file. Choosing a file from this menu opens that file in the editor. This menu is described more in Opening Header Files and Other Related Files.

• Lock button. Indicates whether the current file is editable and allows you to change the locked status of the file. (When clicked, Xcode attempts to change the file's permissions accordingly.)

The Function Menu

The Function menu lets you jump to many points in the current file, including any identifier it declares or defines. You can also add items that aren’t definitions or declarations. In this menu, you can see:

• Declarations and definitions for classes, functions, and methods

• Type declarations

• #define directives

• #pragma marks

• Comments containing:

  • MARK:

  • TODO:

  • FIXME:

  • !!!:

  • ???:

To scroll to the location of any of these identifiers, choose it from the menu. Figure 4-3 shows the Function menu.

The contents of the Function menu are sorted in the order in which they appear in the file. Hold down the Option key while using the Function menu to toggle the sort order of the items between alphabetical order and the order in which they appear in the source file.

You can also change the default behavior for the Function menu in Code Sense preferences. To choose which items appear in the Function menu and the order they appear in, use:

• The “Show declarations” option to specify whether the menu shows declarations as well as definitions

• The “Sort list alphabetically” option to specify whether the items are sorted alphabetically or in the order they appear in the file

To add a marker to a source file and make that marker appear in the Function menu, use the #pragma mark statement in your source code. For example, the following statement adds “PRINTING FUNCTIONS” to the Function menu:

#pragma mark PRINTING FUNCTIONS

To add a separator to the Function menu use:

#pragma mark -

Using Text Editor Windows

If you prefer, you can use a dedicated window for editing source files. Regardless of your preference for whether Xcode automatically opens the attached text editor in Xcode windows, you can always open a file in a separate editor window by doing either of the following:

• Double-click the file in the Groups & Files list or the detail view in the project window.

• Choose ”Open in Separate Editor” from the file shortcut menu.

Figure 4-4 shows a text editor window.

In addition to the basic editor interface, the standalone editor window also contains a toolbar and a status bar. The status bar is similar to the status bar of other Xcode windows, described in The Project Window Status Bar.

Like the toolbar in other Xcode windows, the toolbar in the text editor window provides easy access to common tasks. In addition to the buttons for building, running, and debugging the current target, it also contains the following buttons:

• Breakpoints menu. Adds breakpoints to the current file. The menu has preconfigured breakpoint actions. When you choose one of these actions Xcode adds a breakpoint at the current location of the insertion point and configures it with the specified action. See Managing Program Execution for more information.

• Activate/Deactivate button. Toggles breakpoints on or off.

• Project button. Jumps to the file in the project window. Clicking this button brings the project window to the front.

• Grouped/Ungrouped button. Controls whether opening a file, using any of the methods described earlier in this section, opens an editor window for that file or opens the file in the current window. Clicking the button toggles the state. If the label is Grouped, indicated by the icon of a single window, double-clicking a file opens it in the current editor. If the label is Ungrouped, indicated by an icon of multiple layered windows, each file opens in a separate editor window.

To preserve the state of any open text editor windows when you close a project, select the “Save window state” option in General preferences.

Using Text Editor Panes

You can also edit your source files from within other Xcode windows, such as the project window and the debugger window, as shown in Figure 4-5. To open a file in a window’s text editor pane, first make sure that the editor is visible in the window. If the editor is not already visible, you can open it by clicking Editor in the toolbar. This reveals the text editor pane of the project window. If the editor pane is at its maximum size, clicking the Editor button returns the pane to its previous size. To adjust the size of the editor pane to a different size, drag the separator to the size that you prefer. Another way to view a file in the editor pane is to select the file and choose View > Zoom Editor In.

Selecting a file, an error or warning, a bookmark, a find result or a project symbol opens the associated file in the editor pane as long as it is visible. You can also have Xcode automatically show the editor pane when you select one of these items in the detail view. Select the “Automatically open/close attached editor” option in General preferences.

Splitting Text Editors

Xcode allows you to simultaneously view multiple files or multiple sections of the same file without increasing the number of open windows. It does this by splitting a text editor. Figure 4-6 shows an editor that has been split to display two parts of the same file.

To split a text editor, make sure that the editor has focus and do one of the following:

• To split the editor vertically click the Split button. The Split button—identical to the Split button in the Groups & Files list, described in Splitting the Groups & Files View—appears above the vertical scrollbar of the editor window.

• To split a code editor horizontally Option-click the Split button.

To close a split, click the Close Split button. You can resize the panes of a split editor by dragging the resize control between them.

Indenting Code

The text editor supports syntax-aware indenting (automatic code indentation) to make it simple to author neat and readable code. You can also choose to indent code manually.

This section shows how to configure syntax-aware indenting, how to manually format text in the text editor, and how to control tab layout and automatic indentation.

Matching Parentheses, Braces, and Brackets

Xcode provides a number of ways to help you match pairs of delimiters (parentheses, braces, and brackets):

• When you type a closing delimiter, Xcode causes its counterpart to blink.

• When syntax-aware indenting is turned on, Xcode can automatically insert a closing brace each time you type an opening brace, as described in Choosing How to Indent Braces.

• When you double-click any delimiter, Xcode selects the entire expression that it and its counterpart enclose. You can also choose to select the delimiters themselves.

• When you choose Edit > Format > Balance, Xcode selects the text surrounding the insertion point, up to the nearest set of enclosing delimiters.

You can further control Xcode’s behavior when selecting text within a pair of enclosing braces or parentheses using the options under Editing Options in Text Editing preferences. See Text Editing Preferences for details.

Wrapping Lines

To keep all your code visible in the text editor, you can have it wrap lines when they reach the right edge of the content pane. To turn on line wrapping for all files you open in the text editor, select the “Wrap lines in editor” option in Indentation preferences.

Using the “Indent wrapped lines by” option, also in Indentation preferences, you can have the text editor automatically indent wrapped lines, to visually distinguish them from other lines.

To wrap lines for an individual file in the current editor, choose View > Text > Wrap Lines.

Completing Code Inline

As you type, Xcode builds a list of the symbols that match the token (string containing no spaces) you’ve entered; it further modifies the list by analyzing the token’s context within the file. When Xcode finds completions, the text editor shows the most likely completion inline, as shown in Figure 4-7 (the following descriptions are based on the Sketch example project).

In this case, the text typed is per. Xcode has built a list of possible completions and shown the completion that it guesses is the most appropriate, performSelector:(SEL)aSelector. In addition, the form text is highlighted because, in the list that Xcode built, all possible completions start with perform. Pressing Tab accepts the highlighted portion of the completion. The gray-text part of the completion, Selector:(SEL)aSelector in this case, can be changed with further typing.

In this example, most of the possible completions start with performS, but there is also one completion that starts with performD. This is why even after typing perform, Xcode doesn’t fully suggest a completion that starts with performSelector: You may mean to type the performDragOperation: method name.

With the cursor to the right of the perform token, typing S makes Xcode fully suggest the performSelector:(SEL)aSelector completion (no gray text) because that symbol name represents an indexed symbol that would be appropriate in the token’s context. Pressing Tab accepts that completion.

Because the performSelector: method has one parameter, after accepting the completion, Xcode displays a placeholder for the method’s parameter and selects it so that you can enter the parameter’s value. With methods with multiple parameters, you can press Tab to move through their placeholders.

If you rather work with parameters as plain text instead of in their placeholder form, you can convert a placeholder to text. To convert a placeholder to text, select the placeholder and press Return.

Before accepting a completion, you can choose the next completion in the completion list by choosing Edit > Next Completion.

You can change the keyboard shortcuts associated with code completion commands in Key Bindings preferences. Click Text Key Bindings and look for the actions that begin with “Code Sense” in the alphabetical list:

• Code Sense Complete List

• Code Sense Next Completion

• Code Sense Previous Completion

• Code Sense Select Next Placeholder

• Code Sense Select Previous Placeholder

For more information on keyboard shortcuts, see Keyboard Shortcuts.

Completing Code Using the Completion List

At any time, you can open the completion list Xcode has built so far for the typed token by choosing Edit > Completion List or pressing Escape.

Figure 4-8 shows the completion list. The button in the bottom-right corner of the list lets you specify the sort order of the completion suggestions. You can sort completions alphabetically or by relevance.

You can choose the appropriate match from this list or continue typing to narrow the list further. To enter a symbol from the completion list, select it and press Return.

Xcode lets you specify whether and how the text editor makes code completion suggestions and how much of a symbol’s information the completion list displays. You make these choices in Code Sense preferences. See Code Sense Preferences for details.

Code Focus

Code focus highlights a source file’s scope levels using a grayscale. The code at the current scope, called the focus center, is demarcated in the focus box, which uses a white background. The editor delineates subsequent scopes in boxes using progressively darker backgrounds. Figure 4-9 shows the code focus interface.

Code focus is toggled on or off in Text Editing preferences.

To survey a source file’s scope levels, use the focus ribbon, which is located to the right of the editor gutter. It also uses levels of gray to identify the scope level of the corresponding code lines. The focus box changes as you move the pointer through the focus ribbon to show the focus center that corresponds to the pointer’s position within the file.

In addition to following the pointer in the focus ribbon, you can have the focus box follow the cursor’s position in the content view by choosing View > Code Folding > Focus Follows Selection.

Code Folding

When you’re trying to focus your attention on a specific aspect of your code, such as methods that deal with a particular instance variable, other aspects (for example, other methods or comments about your code) can get in the way. Code folding helps you zero in on the code you want to see by letting you hide the code you don’t want to see.

In Figure 4-9 the editor reveals only one of the methods of the SKTDocument.m file. The other methods are folded (hidden) away from view.

These are the code folding actions you can perform:

• Fold the focus center. To fold the focus center, click the area in the focus ribbon that corresponds to the focus box.

• Unfold code. To unfold code, click either the corresponding triangle in the focus ribbon or the icon containing the ellipsis (…) in the content pane.

You can perform other code folding actions using the Code Folding submenu of the View menu.

Text Macros with Completion Prefixes

The following tables list the built-in text macros with completion prefixes for C, Objective-C, and C++.

Displaying a Page Guide

To help keep code lines no longer than a specified length, you can have Xcode display a guide line in the editor at that column position in the text view. You activate the guide line in Text Editing preferences. Select “Show page guide” option. Enter the location, in number of characters, at which you want the guide line displayed in the “Display at column” field. Xcode displays a gray line in the right margin of the text editor, at the specified column.

Xcode does not wrap your code lines when they reach the guide line. The line only serves as a visual cue.

Displaying the Gutter

The gutter that appears on the left side of the content pane in the editor helps you quickly locate items in a file. The gutter can display:

• Line numbers for the current file. Line numbers make it easy to find a location in a file. To show line numbers, select the “Show line numbers” option in Text Editing preferences.

• Errors and warnings. To help you locate and fix problems in your code, Xcode displays error and warning icons next to the line at which an error or warning occurred. Clicking the icon or hovering the pointer over the icon displays the error or warning message.

• Breakpoints. You can use the gutter to set, remove, and otherwise control the breakpoints in a file. Xcode indicates the location of a breakpoint by displaying an arrow next to the line at which the breakpoint is set. For more information on using breakpoints, see Using Breakpoints.

To show or hide the gutter in the text editor, use the “Show gutter” option in Text Editing preferences.

Viewing Column and Line Positions

The File History menu in the navigation bar not only lets you move between currently open files, it also shows your current location in the file. The File History menu shows the name of the current file and the line number of the line containing the insertion point. You can also have the File History menu display the column position of the insertion point. Figure 4-12 shows the location of the current insertion point in the File History menu.

To set whether the text editor displays the column position of the insertion point, use the “Show column position” option in Text Editing preferences.

Text Editing Preferences

The Text Editing pane of Xcode preferences contains options that control the appearance and behavior of the text editor. Figure 4-13 shows Text Editing preferences.

Here is what the pane contains:

• Display Options. These options control the appearance of the text editor, whether it appears as a separate window or as a pane attached to another Xcode window. See Customizing the Editor to learn more about changing the appearance of Xcode’s editor. The options are:

  • Show gutter. Specifies when Xcode displays the gutter in the editor. The gutter shows information about the current file such as the location of breakpoints, line numbers, and the location of errors or warnings. If this option is selected, Xcode always shows the gutter in all open editors; otherwise, it shows the gutter only when debugging. See Displaying the Gutter for more information.

  • Show line numbers. Specifies whether Xcode shows a file’s line numbers in the editor gutter. If this option is selected, Xcode shows line numbers for a file whenever the editor gutter is visible. See Displaying the Gutter for more information

  • Show column position. Specifies whether Xcode shows the current position of the cursor in the Function menu of the editor. If this option is selected, Xcode shows the character position of the insertion point along the current line.

  • Show code folding ribbon. Specifies whether the text editor shows the folding ribbon used to view a source file’s scope levels and to perform code folding operations. See Scoping Code for more information.

    Code focus. Specifies whether code focus is active. See Code Focus for details.

  • Show page guide. Specifies whether Xcode displays the page guide in the editor. If this option is selected, Xcode displays a gray guide line in the editor to show you the right margin of the editor; to the right of this margin, Xcode colors the background of the editor light gray. This is just a guide, and does not actually affect the margin width in the editor. See Displaying a Page Guide for more information.

    Display at column. Controls the column position at which Xcode displays the page guide. This position is specified in number of characters. To change the position at which the page guide is shown, enter a new number in the field. See Displaying a Page Guide for more information.

• Editing Options. These options control Xcode’s selection behavior for source code. The options are:

  • Select to matching brace. Specifies whether Xcode automatically selects text contained in braces when you double-click the brace. If this option is selected, double-clicking a brace, bracket, or parenthesis in a source code file automatically selects the text up to, and including, the matching brace. See Matching Parentheses, Braces, and Brackets.

  • Omit braces in selection. Specifies whether Xcode includes the braces themselves in text selected by double-clicking a brace, bracket, or parenthesis. If this option is selected, double-clicking a brace, bracket, or parenthesis selects the text between the braces, but not the braces themselves. See Matching Parentheses, Braces, and Brackets for more information.

• Save Options. These options let you specify how Xcode stores files that you edit in the text editor.

  • Save files as writable. Specifies the permissions that Xcode uses for files that it saves. If this option is selected, Xcode adds write permission to files that you edit and save in Xcode. Otherwise, Xcode preserves permissions for files as they are on disk. Files that you create in Xcode already have write permission.

  • Line Encodings. Controls the default line endings used for files in Xcode. You can use Unix, Windows, or Mac line endings for files that you open and edit in the text editor; the type of line endings used for a file can affect which file editors and other tools can interpret the file. See Changing Line Endings for more information on line endings. The menus are:

    • For new files. Specifies the type of line endings used for files that Xcode creates. You can choose Unix, Mac, or Windows line endings. The default value for this setting is Unix.

    • For existing files. Specifies the type of line endings used for preexisting files that you open and edit in Xcode. If you choose Unix, Mac, or Windows from this menu, Xcode saves all files that you open and edit in Xcode with line endings of this type, changing them the next time it saves the file, if necessary. If you choose Preserve from this menu, Xcode uses whatever type of line endings the file already has.

  • Default File Encoding. Specifies the default file encoding that Xcode uses for new files that you create in Xcode. You can choose any of the file encoding supported by your Mac OS X system from this menu. See Choosing File Encodings for more information.

Indentation Preferences

The Indentation pane of Xcode preferences controls formatting options for files in the text editor. Figure 4-14 shows the Indentation preferences pane.

Here is what the pane contains:

• Tabs. These options specify how the text editor inserts space into files while editing (see Tab and Indent Layout Options for more information):

  • Tab key inserts tab, not spaces. Specifies whether Xcode inserts tab characters when you press the Tab key in the editor. If this option is selected, pressing the Tab key inserts a Tab character. Otherwise, Xcode inserts space characters.

  • Tab width. Specifies the default width, in number of characters, used to display tabs in the editor. To change the width of a tab, type a number in the text field. You can override this setting for individual files, as described in Tab and Indent Layout Options.

  • Indent width. Specifies the default width, in number of characters, used to indent lines in the editor. To change the indentation width, type a number in the text field. You can override this setting for individual files, as described in Tab and Indent Layout Options.

• Line Wrapping. These options specify how the text editor wraps lines in files displayed in the editor. These options affect how the file is displayed onscreen, not line breaks or other information stored with the file. See Wrapping Lines for more information. The options are:

  • Wrap lines in editor. Specifies whether the editor wraps lines. If this option is selected, the editor wraps text to the next line when it reaches the outer edge of the text editing area onscreen. Otherwise, Xcode moves text to the next line only when a carriage return or new line characters is inserted.

  • Indent wrapped lines by. Specifies how the editor indents text that it wraps to the next line. If this number is greater than 0, the editor indents wrapped text by the specified number of characters, as a visual indication that the text has been wrapped (as opposed to being moved to the next line by the insertion of a carriage return or new line character). To change the amount by which lines are indented, type a new number in the field.

• Syntax-Aware Indenting. This option, and the options below it, control automatic formatting for source code in the text editor. If this option is selected, Xcode assists you in writing source code by automatically inserting formatting information appropriate for the current context. See Indenting Code to learn more. The options are:

  • Tab indents. Specifies when pressing Tab in the editor inserts an indentation. You can choose the following:

    • In leading white space: Pressing Tab inserts an indentation only at the beginning of a line or following a space.

    • Never: Pressing Tab never causes an indentation.

    • Always: Pressing Tab always causes an indentation.

  • Indent solo “{“ by. Controls the amount by which a left brace character ({) on a line by itself is indented. If this number is greater than 0, Xcode automatically indents a left brace that appears on a line by itself (that is, a left brace that is preceded by a newline or carriage return) by the specified number of characters. The default value of this field is 0.

  • Automatically insert closing “}”. Controls whether Xcode automatically inserts a matching right brace when you type an opening brace. If this option is selected, typing an opening brace causes Xcode to insert a matching closing brace.

  • Automatically indented characters. Controls which characters trigger Xcode to automatically cause an indentation. When any of the following options is selected, typing that character in an editor causes Xcode to indent the current line or the following line.

  • Indent // comments. Controls whether Xcode automatically indents C++-style comments. If this option is selected, Xcode automatically indents comments beginning with //.

  • Align consecutive //comments. Controls whether Xcode automatically indents consecutive C++-style comments to the same level.

Code Sense Preferences

The Code Sense pane of Xcode preferences contains options for controlling symbol indexing, the text editor’s Function menu, and its code completion interface. Figure 4-15 shows the Code Sense pane. For more information about Code Sense, see Code Sense.

Here’s what the pane contains:

• Indexing.

  • Enable for all projects: Specifies whether symbol indexing is active for the projects you open.

    When inactive, features that rely on this index (such as the Project Symbols smart group, refactoring, and code completion) do not work. For more information about symbol indexing, see Code Sense.

• Editor Function Pop-up. This area contains options for configuring the text editor Function menu (The Function Menu).

  • Show declarations. Specifies whether the Function menu shows function and method declarations (in addition to definitions).

  • Sort list alphabetically. Specifies whether the contents of the Function menu are sorted alphabetically.

    When unselected, the Function menu shows items in the order they appear in the file.

• Code Completion. This area contains options for configuring code completion. For more information about code completion, see Completing Code. (Your code completion settings apply to all projects that you open.)

  • Show arguments in pop-up list. Specifies whether Xcode displays arguments for functions and methods in the completion list. When this option is selected, Xcode displays the return type and arguments for functions and methods in the list of completion suggestions. Otherwise, Xcode shows only the symbol name.

  • Insert argument placeholders for completions. Specifies whether Xcode inserts the arguments to a function or method when you accept a completion suggestion. When selected, inserting a function or method using code completion also inserts placeholders for arguments. Otherwise, Xcode inserts only the symbol name.

  • Automatically Suggest. Specifies whether and when Xcode shows completion suggestions. You can choose between immediate and delayed suggestions.

  • Suggestion delay. The number of seconds the text editor waits before showing its best completion suggestion when using delayed completion suggestions.

• Edit All in Scope. This area contains options for configuring Edit All in Scope behavior (see Editing Symbol Names for details about this feature).

  • Automatically Highlight: Specifies whether and when Xcode highlights the occurrences of a symbol whose name can be edited using Edit All in Scope. You can choose between immediate and delayed suggestions.

  • Highlight delay. The number of seconds the text editor waits before highlighting symbol occurrences when using delayed highlighting.

Fonts & Colors Preferences

The Fonts & Colors pane of Xcode preferences (Figure 4-16) is where you configure syntax formatting, which identifies elements of the source files you edit in the text editor (see Formatting Code for details).

Here is what the pane contains:

• Color Theme: Lists of syntax formatting themes. Each theme applies a set of fonts and colors to all the syntax formatting element categories Xcode supports.

• Duplicate: Duplicates the current syntax formatting theme.

• Delete: Deletes the current syntax formatting theme.

• Category list: List of the syntax formatting element categories.

  To change the font or color for a category, double-click the font or color you want to change to display the Fonts window or the Colors window.

  You can select more than one category to modify the font and color for a set of categories at the same time.

• Use syntax-based formatting: Activates syntax formatting.

• Color indexed symbols: Specifies whether to use the project’s Code Sense index to assign symbols in source files to element categories. When turned off, the text editor uses only the file’s language to assign symbols and text to categories.

• Use colors when printing: Preserves syntax formatting when you print source files from Xcode.

• Copy colors and fonts: Places syntax formatting on the Clipboard when you copy text from the text editor.