ADC Home > Reference Library > Guides > Tools > Xcode > Xcode Workspace Guide >

< Previous PageNext Page > Hide TOC

The Text Editor

Xcode contains a full-featured text editor for editing your project’s text files. You have many options for using this editor to view and modify the text files in your project; you can edit files in a dedicated editor window or use the editor pane attached to most Xcode windows. You can also choose whether to have multiple editor windows open at once or use a single editor window for all the text files that you open.

This chapter describes the Xcode text editor, shows how to open files in a standalone window or in an editor pane, and how to control the appearance of the editor.

In this section:

A Tour of the Text Editor
Laying Out Code
Formatting Code
Completing Code
Scoping Code
Editing Symbol Names
Repeating Code
Viewing Project Messages
Executing Shell Commands in Selection
Searching Source Files
Customizing the Editor


A Tour of the Text Editor

You can view the text editor in two ways:

In either case, the content looks the same and the same controls are available. When you open a file in the text editor, you see something similar to Figure 4-1.


Figure 4-1  The text editor view

The text editor view

Here’s what the text editor contains:

Note: Sometimes an editor pane may display the message “No Editor.” This means that there is no file selected in the detail view or the Groups & Files list.

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.


Figure 4-2  Text editor navigation bar

Text editor navigation bar

Here is what the navigation bar contains:

The File History Menu

The File History menu lists the files that you have viewed in the current editor, with the current file at the top of the menu. To go to any of these files, simply choose it from the list. The menu has a couple of commands: Clear File History and History Capacity.

You can clear the File History menu by choosing Clear File History. This removes all but the current file in the editor from the list. By default, Xcode places no limit on the number of files that it places in this menu. You can limit the size of the File History menu with the History Capacity command.

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:

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


Figure 4-3  The Function menu

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:

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 -

Supported languages: The Function menu works with C, Objective-C, C++, Java, Perl, Python, and Ruby.

Jumping to the Counterpart of a File or Symbol

Clicking the Counterpart button opens the related header or source file for the file currently open in the text editor. For example, if the file currently open in the editor is MyFile.c, clicking this button opens MyFile.h, and vice versa. When your project contains files with the same name, Xcode gives preference to files located in the same folder as their counterparts. You can also open the current file’s related header or implementation file by choosing View > Switch to Header/Source File.

Option-clicking the Counterpart button displays the counterpart of the currently selected symbol—class, method, function, and so on—opening the corresponding file and scrolling to the appropriate section within it if necessary. If the selected symbol is a class, method, or function declaration, the editor scrolls to the definition for that item. If a class, function, or method definition is currently selected, the editor scrolls to the symbol’s declaration.

By default, Xcode opens the file or symbol counterpart in the current editor; however, you can have Xcode open counterparts in a separate editor window. This makes it easy to view both a header and its implementation file, or a symbol declaration and its definition, at once. To have Xcode open counterparts in a separate window, go to General preferences, and deselect the “Open counterparts in same editor” option.

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:

Figure 4-4 shows a text editor window.


Figure 4-4  The text editor in a standalone window

The text editor in a standalone 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:

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.


Figure 4-5  The text editor pane in a project window

The text editor pane in a project window

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.


Figure 4-6  Splitting a text editor

Splitting a text editor

Note: You can split a text editor whether that editor appears in an editor window or an editor pane.

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

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.

Laying Out Code

Xcode provides a number of layout options to help you keep your code well formed and readable. Syntax-aware indenting helps you keep your code neat by automatically indenting code as you type. This section describes options for indenting code and matching parentheses.

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.

Syntax-Aware Indenting

The syntax-aware indenting feature of the Xcode text editor gives you a number of ways to control how it automatically lays out your code. When you use syntax-aware indenting, the editor automatically indents your code as you type; pressing Return or Tab moves the insertion point to the appropriate level by examining the syntax of the surrounding lines. You can control which characters cause the editor to indent a line, what happens when you press the Tab key, and how the editor indents braces and comments.

To turn on syntax-aware indenting, select the “Syntax-aware indenting” option in Indentation preferences. See “Indentation Preferences” for details.

Choosing What the Tab Key Does

When you use syntax-aware indenting, you usually press the Tab key to tell the editor to indent the text on the current line. But when you’re at the end of the line, you may want to insert a tab character before, say, you insert a comment. To choose the circumstances for which pressing the Tab key reindents a line, use the “Tab indents” menu in Indentation preferences..

You can choose among always indenting, never indenting, or indenting only at the beginning of a line or after a space. See “Indentation Preferences” for more information.

To insert a tab character regardless of how “Tab indents” is set, press Option-Tab. Similarly, to perform syntax-aware indenting regardless of this option’s setting, press Control-I.

Choosing How to Indent Braces

You can have the editor automatically indent braces to help you easily see the level of nesting in your code and to keep your code readable. In addition, to help you keep braces balanced, you can have the editor automatically insert a closing brace when you type an opening brace.

To set how much an opening brace is indented when it appears on a line by itself, use the “Indent solo “{” by” text field in Indentation preferences.

When the value of the field is greater than 0, Xcode automatically indents opening braces to the level of the previous line plus the specified number of characters.

To specify whether to insert a closing brace automatically when you type an opening brace, select the “Automatically insert closing “}”” option.

Choosing Which Characters Reindent a Line

To set which characters cause the text editor to automatically indent a line whenever they’re typed, use the options under “Automatically indented characters” in Indentation preferences. See “Indentation Preferences” for details.

Choosing How to Indent C++-Style Comments

You can choose how to indent C++–style (//) comments when they appear on lines by themselves.

Note: You cannot automatically indent C++–style comments that appear at the end of code lines.

To specify whether to indent // comments and whether to align consecutive // comments, use the options for these comments in Indentation preferences.

Manual Indenting

If you choose not to use syntax-aware indenting, you must manually indent code you want indented. When syntax-aware indenting is turned off, pressing Tab inserts a tab character and pressing Return inserts a carriage return and moves the cursor to the same level as the previous line. You can also indent a block of text to the left or right by selecting the text and choosing Edit > Format > Shift Left or Edit > Format > Shift Right.

When syntax-aware indenting is turned off, the text editor may still indent newly added lines to the level of the previous line when you press Return. You can turn this indenting off in Key Binding preferences. Click Text Key Bindings and add the Return key to the keyboard shortcuts list of the Insert Newline action. See “Keyboard Shortcuts” for details.

Tab and Indent Layout Options

Whether you indent a line manually or rely on syntax-aware indenting, you can control the width of tabs and indents, and you can specify whether the text editor inserts tab characters or spaces. You can specify default values for all files you open in the text editor and customize these settings for individual files.

Changing the Indent and Tab Width

You can set how many spaces to indent when the editor automatically indents or when you press the Tab key. To set the default indent or tab width for every file you open, use the “Tab width” and “Indent width” text fields in Indentation preferences.

To override the default indent or tab width for one or more specific files, select the files in the Groups & Files list and open the File Info window. In the General pane, change the Indent Width or Tab Width setting.

Note: If you change a file’s default indent or tab width, those settings are in effect for everyone who views that file.

Using Spaces Instead of Tabs

To ensure that your code looks the same to other developers regardless of their tab layout settings, you can have the editor insert a series of spaces instead of a tab character whenever it indents code or when you press Tab.

To specify that the text editor use tabs instead of spaces, select the “Tab key inserts tab, not spaces” option in Indentation preferences..

Important: When “Tab key inserts tab, not spaces” is selected, changing the width of tabs won’t affect code you’ve already written.

These options are saved in your own Xcode preferences but not in the file itself. When other people edit the file, their preferences for that file take effect.

You can also specify this setting on a per-file basis. To choose whether the editor uses tabs or spaces when editing a certain file, select the file in the Groups & Files list, open the File Info window, and in the General pane select “Editor uses tabs.”

Matching Parentheses, Braces, and Brackets

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

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.

Note: When “Wrap lines in editor” is not selected, the text editor does not move text to the next line until you insert a carriage return.

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

Formatting Code

Syntax formatting makes it easy to identify elements of your code by using different fonts and colors to identify particular elements, such as keywords and comments. For example, you can display comments in green and keywords in boldface.

Xcode supports syntax formatting for many programming languages; to see the languages that it supports, choose View > Syntax Coloring.

The same menu allows you to toggle syntax formatting for the selected file:

To specify whether Xcode applies syntax formatting to all files that you open, select the “Use syntax-based formatting” option in Fonts & Colors preferences.

When syntax formatting is active, Xcode uses element categories to determine the formatting to apply to particular elements in a file. An element category is a name that identifies a type of source-code element or text-editor user interface. You can see a list of the categories and change the font and color for each in Fonts & Colors preferences.

Xcode provides several syntax formatting themes, which assign colors and fonts to all the element categories. You can also create your own themes.

Using its knowledge of the syntax of a programming language, Xcode assigns keywords or textual constructs in a file, such as numbers or strings (text within quotation marks) to an element category to determine how it's formatted in the editor. In addition, you can tell Xcode to use a project’s Code Sense index to provide a richer store of symbol information to assign code fragments to element categories. That is, instead of only the current file, Xcode uses information about all the source files in the project to associate code fragments to categories.

For further details about configuring syntax formatting, see “Fonts & Colors Preferences.”

Completing Code

When you are writing code, you often must type out or copy and paste long identifier names and lists of arguments. Code completion offers you a shortcut. As you type the beginning of an identifier or a keyword, code completion suggests likely completions, based on the text you have already typed and the surrounding context within the file.

Code completion is implemented using Code Sense, which maintains a rich store of information about the symbols defined in your project and its included files. Xcode supports code completion for C, C++, Objective-C, Objective-C++, Java, and AppleScript. To learn more about Code Sense, see “Code Sense” in Xcode Project Management Guide.

This section describes how to use code completion and how to set code completion options.

Important: Code completion relies on your project’s Code Sense index. Code completion does not work when indexing is turned off or incomplete. See "Source Code Indexing" in Xcode Overview for more information.

To turn on code completion, use the Automatically Suggest menu in Code Sense preferences.

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).


Figure 4-7  Code completion inline

Code completion inline

In this case, the text typed is SKTD. Xcode has built a list of possible completions and shown the completion that it guesses is the most appropriate, SKTDocumentOldTypeName. In addition the ocument token is highlighted because, in the list that Xcode built, all possible completions start with SKTDocument. Pressing Tab accepts the highlighted portion of the completion.

When the accepted completion is an indexed symbol, Xcode removes the original suggestion. In this example, SKTDocument is an indexed symbol; therefore, after pressing Tab, only the SKTDocument token remains.

With the cursor to the right of SKTDocument, after typing P Xcode suggests SKTDocumentPrintInfoKey because there’s only one indexed symbol that begins with the token SKTDocumentP that would be appropriate in the token’s context. Pressing Tab accepts that completion.

After accepting a completion, you can still choose the next completion in the completion list using Edit > Next Completion.

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.


Figure 4-8  Code completion list

Code completion list

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 or Tab.

For symbols that include parameters, such as methods, Xcode optionally inserts placeholders for the arguments, as shown in Figure 4-9. To move between placeholders, use Edit > Select Next Placeholder.


Figure 4-9  Code completion argument placeholders

Code completion argument placeholders

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.

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:

For more information on keyboard shortcuts, see “Keyboard Shortcuts.”

Scoping Code

The text editor provides two ways for you to focus on the part of the source file that interests you:

This section shows how to survey a source file’s scope levels and how to hide areas of a file in which you’re not interested.

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-10 shows the code focus interface.


Figure 4-10  Code focus in action

Code focus in action

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.

Map of the code: If you have a mouse with a scroll wheel or scroll ball, you can ”fly over” your source file’s scope levels by turning it up or down while the pointer remains in the same spot on the screen.

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-10 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:

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

Code folding supported languages: C, Objective-C, C++, and XML.

Editing Symbol Names

As you modify existing code or use code templates, you may want to change the name of function or method parameters to produce self-documenting code, for instance. You may also want to highlight all the places a symbol appears to see how extensively it’s used within a code block. The Edit All in Scope command in the Edit menu facilitates these tasks. This command lets you select a symbol in a code block and highlight or change all occurrences of the symbol within the code block simultaneously.

For example, take this code listing:

- (void)setSearchKey:(NSString *) value {
    if (_searchKey != value) {
        [_searchKey release];
        if (value == nil) value = @"";
        _searchKey = [value copy];
        [self createSearchPredicate];
    }
}

Instead of value you may want to use searchKey to identify the method’s argument. To do that, you select an occurrence of value anywhere within the method and choose Edit > Edit All in Scope.

You can then change value to searchKey once. Xcode replaces all occurrences of value with searchKey within the method while you type the new name, as shown in Figure 4-11.


Figure 4-11  Editing the name of a symbol

Editing the name of a symbol

To exit editing in a scope, click anywhere in the file, outside highlighted text.

To cycle among the symbol occurrences within the code block, choose Edit > Select Next Placeholder (hold the Shift key to select the previous occurrence).

To learn how to customize the behavior of the Edit All in Scope command, see “Code Sense Preferences.”

Note: The Edit All in Scope command is available only with these languages: C, C++, Objective-C, and Objective-C++.

Repeating Code

Using code completion to automatically complete symbol names saves you a lot of typing. In the course of writing source code, however, you still spend a lot of time typing the same basic code constructs—such as alloc and init methods in Objective-C programs—over and over again. To help you with this, Xcode includes a set of text macros. Text macros let you insert common constructs and blocks of code with a menu item or keystroke, instead of typing them in directly.

You can insert a text macro in either of these ways:

The inserted text includes placeholders for arguments, variables, and other program-specific information. For example, choosing Insert Text Macro > C > If Block inserts the following text at the current insertion point in the active editor:


#if <#expression#> <#statements#> #endif

Replace the placeholders expression and statements with your code. You can cycle through the placeholders in a text macro in the same way you can cycle through function arguments with code completion. A text macro can also define one placeholder to be replaced with the current selection, if any. When you select text in the active editor and insert a text macro, Xcode substitutes the selected text for this placeholder. For the If Block text macro described above, Xcode substitutes the selected text for the statement placeholder. For example, if the current selection in the text editor is CFRelease(someString);, inserting the If Block text macro gives you the following:


#if <#expression#> CFRelease(someString); #endif

If there is no selection, Xcode simply inserts the statements placeholder, as in the previous example.

Some text macros have several variants. For example, the text macro for inserting an HTML heading has variants for the different levels of headings. For text macros that have multiple variants, repeatedly choosing that text macro from the Insert Text Macro menus cycles through the different versions of that macro. For example, choosing Insert Text Macro > HTML > Heading a single time produces:


<h1><#text#></h1>

Choosing it again modifies the text to:


<h2><#text#></h2>

To create your own text macros, you have to create a language specification for the language to which you want to apply the macro. Then, place the language specification in:

~/Library/Application Support/Developer/Shared/Specifications

For examples of language specifications, see:

<Xcode>/Applications/Xcode.app/Contents/PlugIns/TextMacros.xctxtmacro

Text Macros with Completion Prefixes

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

Table 4-1  C text macros with completion prefixes

Text macro name

Completion prefix

If Block

if

If / Else Block

ifelse

Else If Block

elseif

For Loop

for

For i Loop

fori

While Loop

while

Do While Loop

do

Switch Block

switch

Case Block

case

Else Block

else

Enum Definition

enum

Struct Definition

struct

Union Definition

union

Type Definition

typedef

Printf() Call

printf

#Pragma Mark

pm

Pragma Mark

pragma

#Import Statement

pim

#Import Statement (System)

pims

#Import Statement (Framework)

pimf

#Include Statement

pin

#Include Statement (System)

pins

#If Block

pif

#Ifdef Block

pifd

#if / Else Block

pife

#Ifdef / Else Block

pifde

#if 0 Block

pifz

Copyright Comment

copyright

Comment Selection

comment

Separator Comment

cseparator

Table 4-2  Objective-C text macros with completion prefixes

Text macro name

Completion prefix

Try / Catch Block

@try

Catch Block

@catch

Finally Block

@finally

NSLog() Call

log

Alloc / Init Call

a

Array Declaration

aa

Mutable Array Declaration

ma

Array For Loop

fora

Array Foreach Loop

fore

init Definition

init

dealloc Definition

dealloc

observeValueForKeyPath: Definition

observeValueForKeyPath

observeValueForKeyPath: Declaration

observeValueForKeyPath

bind: Definition

bind

bind: Declaration

bind

@interface Definition

@interface

@implementation Definition

@implementation

@protocol Definition

@protocol

NSString

nss

NSMutableString

nsms

NSArray

nsa

NSMutableArray

nsma

NSDictionary

nsd

NSMutableDictionary

nsmd

Table 4-3  C++ text macros with completion prefixes

Text macro name

Completion prefix

#Ifdef Block

pifdcpp

#Ifdef/Else Block

pifdecpp

Static Cast

static_cast

Dynamic Cast

dynamic_cast

Reinterpret Cast

reinterpret_cast

Try / Catch Block

try

Catch Block

catch

Cout Statement

cout

Cout Message

coutm

Namespace Definition

namespace

Class Definition

class

Extern \"C\" Statement

extern

Extern \"C\" Block

externb

Viewing Project Messages

To help keep your attention on as few windows as possible, Xcode can display some information generated as you work on a project in the text editor. The editor displays this information through message bubbles. Message bubbles display project messages in a concise way in the code line from which they are generated (in the case of build messages) or at which they are placed (in the case of breakpoints). You can view and dismiss build messages and modify breakpoints without taking your focus away from the file you’re editing in the text editor.

Figure 4-12 shows a build message bubble.


Figure 4-12  A build message bubble

A build message bubble

To show or hide message bubbles in the text editor, use the Message Bubbles submenu of the View menu.

The Message Bubbles submenu also allows you to display and hide message bubbles as well as specify the kind of messages in which you’re interested.

Executing Shell Commands in Selection

Xcode provides a keyboard shortcut for executing any shell command that appears in a text editor window. To use this feature, select the command text and press Control-R. The results appear below the command in the text editor window, automatically scrolling if necessary to show the output.

Xcode creates a shell each time you execute a command, so there is no shared context between different executions. For example, if you execute a command that changes the directory, the next command you execute does not execute in that directory. To overcome this, you can select two commands and press Control-R.

One way to take advantage of this feature is to keep a file of commonly used commands and execute them as needed. Or you might use an empty text file as a scratch area to type and execute commands.

You can also add custom menu items to execute frequently used shell scripts. Any scripts you execute can take advantage of many special script variables and built-in scripts defined by Xcode. For more information, see “User Scripts.”

Searching Source Files

The Xcode text editor provides many ways to move between files and to find and navigate to information in a file. The navigation bar of the editor provides a number of menus for navigating within and between files. See “Navigation Bar” for details.

This section shows how to search within a file. It also shows some of the shortcuts you can use in the text editor to find text and symbol definitions.

Some tricks for finding information from an editor are described in other chapters. “Opening Files by Filename or Symbol Name” describes shortcuts you can use to open a file whose name or path appears in an editor. “Searching Documentation” describes shortcuts you can use to jump to the documentation for a symbol whose name appears in the editor or search the installed documentation for a word or phrase.

Searching in a File

When editing files in the text editor, it is fairly common to want to make the same change in several places in the current file. For example, when you rename a function, you also have to find all of the places where you call that function and change those calls to use the new name. Xcode provides a single-file find that allows you to search for and replace text within a single file. You can perform a simple textual search or search using regular expressions.

Tip: Xcode refactoring provides a more efficient way of renaming a symbol throughout multiple files. See Xcode Refactoring Guide for details.

Specifying Search Terms

To search for text in a file that you have open in the editor, choose Edit > Find > Single File Find.

Xcode displays the Single File Find window, shown in Figure 4-13.


Figure 4-13  Single File Find window

Single File Find window

You can search using a text string or a regular expression; choose the appropriate search type from the pop-up menu next to the Ignore Case option in the Find Options group. Choosing Textual searches for text matching the string in the Find field. Choosing Regular Expression searches for text matching the regular expression in the Find field; Xcode uses the ICU library for regular expression matching.

Type the text string or regular expression pattern to use for the search in the Find field. To minimize your typing, Xcode keeps track of search strings; to reuse a previous search string, click the arrow in the Find field and choose the string from the menu.

The other options in the Find Options group give you additional control over how the search is performed; these options are:

Use the Next and Previous buttons to continue searching for the same text in a file. You can also use menu commands. Choose Edit > Find > Find Next to move to the next match; to move to the previous match, hold down the Shift key while choosing that sequence.

Pressing Return finds the next (or first) match and dismisses the Single File Find window.

Replacing Text

You can use the Single File Find window to replace some or all occurrences of text matching the string or regular expression specified in the Find field.

To search for and replace text in a file:

  1. Open the Single File Find window and specify the search criteria, as described in “Specifying Search Terms.”

  2. Type the replacement text in the Replace field. As with search strings, Xcode keeps track of substitution strings; to reuse a previous substitution string, choose it from the menu in the Replace field.

Use the replace buttons in the bottom-right portion of the Single File Find window to perform the text substitution. The scope of the replacement varies, depending on the button you choose. Here are the buttons available to you:

Each of these buttons also has a menu item equivalent in the Find submenu: Replace, Replace All, and Replace and Find Next. Holding down the Shift key changes Replace and Find Next to Replace and Find Previous.

Shortcuts for Finding Text and Symbol Definitions

Xcode provides a number of shortcuts for searching that use text or other content that appears in the text editor. You can use these shortcuts to perform single-file and projectwide searches without going through the Single File Find or Project Find windows. When you use these shortcuts, Xcode performs the search using the same options specified the last time you used the Single File Find or Project Find windows. These windows are described in further detail in “Searching in a File” and "Searching in a Project" in Xcode Project Management Guide.

To search the current project for text that appears in the text editor, select the text to search for, and choose Edit > Find > Find Selected Text.

To perform a projectwide search using the current selection in the text editor, use the shortcuts listed in Table 4-4.

Table 4-4  Shortcuts for performing a projectwide search using the current selection in the editor

Search project for

Choose

Selected text

Edit > Find > Find Selected Text in Project

Selected symbol definition

Editor shortcut menu > Find > Find Selected Definition in Project

You can also jump directly to the definition for a symbol identifier by doing either of the following:

Each of the searches described in Table 4-4 uses the last set of search options used when searching your project. If you want to perform a projectwide search using the current selection in the text editor, but do not want to use the last set of search options, you can open a Project Find window with the current selection by doing either of the following:

Customizing the Editor

Xcode gives you a great deal of flexibility to customize the appearance of the editor. You can change the fonts and colors used to display text in the editor to suit your own preferences. You can also control the amount of information that Xcode displays about file locations and contents. This section describes how to change the default font and text editing colors for the text editor, and how to use the gutter, page guide, and file history menu to locate information in a file.

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:

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-14 shows the location of the current insertion point in the File History menu.


Figure 4-14  Line numbers and column positions in the File History menu

Line numbers and column positions 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-15 shows Text Editing preferences.


Figure 4-15  Text Editing preferences pane

Text Editing preferences pane

Here is what the pane contains:

Indentation Preferences

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


Figure 4-16  Indentation preferences pane

Indentation preferences pane

Here is what the pane contains:

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-17 shows the Code Sense pane. For more information about Code Sense, see “Code Sense” in Xcode Project Management Guide.


Figure 4-17  Code Sense preferences pane

Code Sense preferences pane

Here’s what the pane contains:

Fonts & Colors Preferences

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


Figure 4-18  Fonts & Colors preferences pane

Fonts & Colors preferences pane

Here is what the pane contains:

Note: Before you can customize the formatting of text categories, you must create a custom color theme by duplicating one of the predefined themes.



< Previous PageNext Page > Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.