Get Oriented

Open Work in Tabs and Windows

For fast switches between different editors or files, you can add tabs to the Xcode workspace window, or you can open additional windows. To activate tabs, choose View > Show Tab Bar, or add a new tab by choosing File > New > Tab. To open a new workspace window, choose File > New > Window. You configure each tab or workspace window independently of the others. For example, you can use one window to debug and another to edit source code. If you open the same file in two tabs or two windows, the changes you make in one tab or window are reflected in the other.

You can reorder tabs, close them independently, or drag them out of the tab bar to create a window, just as you can do in Safari. You can use items in the Window menu (or their keyboard equivalents) to move between tabs. You can also give a tab a name for use in Behaviors preferences (see “Customize Your Build and Run Workflow”).

Xcode remembers the windows and tabs you had open when you last closed a workspace and reopens them in the same configuration when you start Xcode.

Work with the Files in Your Workspace

The project navigator shows projects, groups, folders, and files:

• The project or projects in your workspace window are the highest level of the hierarchy in the project navigator. Open the project’s disclosure triangle to see the groups, folders, and files in the project. Select a project to view project information about the project in the project editor.

• A group appears in the project navigator as a yellow folder icon. A group collects files in the project but does does not represent a folder on disk. Although you can organize your project in Xcode to reflect the organization of files on disk, moving files into and out of groups does not affect the content of the folders on disk.

• A folder is a reference to a folder on disk and appears in the project navigator as a blue folder icon. The contents of the folder in the project navigator reflect the contents of the folder on disk. It’s important to note, however, that the files that appear in a folder icon in the project navigator are not part of your project unless you have added them to the project explicitly (in which case they appear directly under the project or in a group, as well as in the folder). You can view and edit the files in a folder, but to move files in and out of the folder you must use the Finder.

• A file in the project navigator is a reference to a file on disk.

Figure 1-5 shows a project (FolderFinder) containing both a group and a folder named ExtraFiles. Although in the figure the group contains the same files as the folder, you could modify the contents of either the group or the folder without affecting the contents of the other container.

To add existing files to a project

1. In the project navigator, select the project or group to which you want to add the files.

   Note that you can’t add files to a folder in the project navigator. When you add a folder reference to a project, changes you make to the contents of the folder in the Finder appear immediately in the project navigator.

2. Choose File > Add Files to “<ProjectName>”.

3. Select the file or files you want to add, and click Add.

   If the file is not in your project folder on disk, you can choose to copy the file into your project folder.

   If you select a folder in the dialog and select the “Create folder references for any added folders” option, Xcode adds a folder reference to the project. Although the project navigator shows the files that are in that folder on disk, Xcode does not add those files to your project. To add files in a folder to your project, select the files individually, or select the “Create groups for any added folders” option.

   

   Click the New Folder button to add a folder to the disk and a reference to that folder to the project navigator. Doing so does not add any files to your project.

You can use the project navigator to organize the files in your project into groups and to list the files and groups in any order you like. Jump bars in editor panes (such as the primary editor pane or assistant editor panes) show the same organization that the project navigator displays, down to the file that’s open in the editor. Editors such as the source editor show additional elements within the file, such as methods and user interface objects.

Click the name of a file in the project navigator to see the file in the primary editor pane. The type of editor or viewer that displays the file depends on the type of file you select.

To create a group

Do one of the following:

• Place the pointer at the location in the project navigator where you want the group, Control-click, and choose New Group from the shortcut menu. You can drag files into the group, and you can drag the group to a new location in the navigator.

• Select the files that you want to place in a new group, Control-click, and choose New Group from Selection. Note that you can Command-click items in the navigator to get a discontinuous selection.

  

  Click the name of the group to edit the name.

  

The project navigator has filters for recently edited files, files with source control status, unsaved files, and filename strings. Figure 1-6, for example, shows a project filtered to show only implementation (.m) files. The filter field and buttons are at the bottom of the navigator area.

When you navigate to a file in the project navigator, the jump bar in the primary editor pane shows the path to that file (Figure 1-7).

You can use the jump bar to navigate through your project.

Use a jump bar to directly navigate to items at any level in your workspace.

To use the jump bar

 

Note that every element in the path in the jump bar is a pop-up menu that you can use to navigate through your project. Hold down the Option key when selecting a file in the jump bar to open the file in an assistant editor pane (you can change this behavior in the General pane of Xcode preferences).

The contents of an editor jump bar depend on the type of file open in the editor. When editing a user interface file, for example, you can use the jump bar to navigate to individual user interface elements (Figure 1-8).

The jump bar also has back and forward buttons for moving through previously viewed files, and a pop-up menu () that displays a variety of useful information about related items, as shown in Figure 1-9.

Find Information to View or Edit

Xcode provides two ways to navigate through your project: navigators and jump bars. Most of the navigators include text fields for searching through the project or filtering the items in the navigator; some include buttons to restrict the scope of items displayed. Jump bars appear at the top of primary and assistant editor panes and provide an alternate way to navigate through the files and symbols in the project. Because jump bars are always available, you can use them to find items in the project even when the navigator area is closed.

Use the navigator selector bar at the top of the navigator area to display a navigator (Figure 1-10).

These are the navigators in the navigator area:

• Project navigator

• Symbol navigator

• Search navigator

• Issue navigator

• Debug navigator

• Breakpoint navigator

• Log navigator

This section introduces most of these navigators, and describes how to jump directly to a file with jump bars. (“Work with the Files in Your Workspace” describes the project navigator.) When you need help using a displayed navigator, Control-click in the navigator to get a list of help articles that further describe the use of the navigator.

Browse Project Symbols with the Symbol Navigator

Note that you need to wait until Xcode finishes indexing your project before you can use the symbol navigator.

To browse the class hierarchy

Do one of the following:

• Display symbols in a hierarchical or flat list using the buttons at the top of the symbol navigator.

  Refine which symbols are displayed using the filter bar buttons at the bottom of the navigator. Filter buttons are blue when the corresponding filter is active and black when the filter is inactive:

  • The Class button: Shows classes and their members, including protocols, functions, structs, enums, unions, types, and globals.

  • The Project button: Shows only symbols defined in the project or workspace.

  • The Method button: Shows containers, hiding symbols defined within them such as methods, properties, and variables.

  • Filter field: Shows items that match the text entered.

  Select a symbol to display its header file definition in the source editor.

  Figure 1-11 shows one filter active and the text drawing in the filter field. In the resulting list, the bezierPathForDrawing method is selected and its definition is highlighted in the primary editor pane.

  

• Click an element in the jump bar to see a list of symbols at that level in the project hierarchy, as shown in Figure 1-12.

  

Find Text Strings with the Search Navigator

Find text strings in your project or workspace with the search navigator.

Search a workspace or a find scope for text that matches specific criteria.

To search for text in projects and frameworks

 

To customize the search, click the magnifying glass in the search field and choose Show Find Options. You can specify the type of text and the scope of the search.

You can also replace text you’ve found. See “Replace Text Strings” for details.

Investigate Problems in your Project with the Issue Navigator

The issue navigator lists messages, warnings, and errors that Xcode identifies in your code and your project, including issues found by Fix-it, the static analyzer, and the compiler.

When a build fails, the issue navigator opens, displaying the problems found in the project. Select an issue to see it displayed in the primary editor pane. You can also navigate through the issues using the arrows and pop-up menu at the right end of the primary editor jump bar. See “Locate and Display Build Issues” for more information on the issue navigator.

View Threads and Stacks in the Debug Navigator

When your running code hits a breakpoint (or you use the debug bar in the debug area to pause execution), the debug navigator shows the current state of the stack in each running thread. Click an item in the navigator to see it in your source code and to see the values of variables in the debug area.

For more information on using the debug navigator while debugging your code, see “Examine Threads, Stacks, Variables, and Memory.”

Manage Breakpoints with the Breakpoint Navigator

Whereas you set breakpoints in the source editor, the breakpoint navigator is where you can see all your breakpoints in one place. In addition, you use the breakpoint navigator to add conditions and options to breakpoints.

For more information on using breakpoints in debugging your code, see “Manage Breakpoints.”

View Build, Source Control, and Debug Session Logs with the Log Navigator

When you perform an operation that is normally recorded, such as building or analyzing your code, or that has output to the console, such as a source control operation or a debug session, the record of that operation is listed in the log navigator. Select an item in the log navigator to see the log in the editor pane.

You can use the filter button and text field at the bottom of the navigator to limit the logs displayed to recent logs or logs whose names match the text string you enter.

The log viewer has two distinct displays:

• For noninteractive tasks, such as building and source control, the log viewer displays a scope bar that you can use to specify the content to display, such as all messages or only errors (see Figure 1-13).

  

  Successful operations have a green checkmark icon next to them. Operations with warnings have a warning icon (an exclamation mark in a yellow triangle). Operations with errors have an error icon (an exclamation mark in a red octagon) next to them. The right side of the operation indicates the number of warnings and errors the operation produced.

  To view an operation’s warning or error messages, click the disclosure triangle on the left side of the operation.

  To view an operation’s transcript, click the transcript button () on the right side of the operation.

• For interactive tasks, such as debugging sessions, the log viewer displays a transcript of the session.

Edit and View Many Types of Data

Xcode includes editors for many types of data, including:

• User interface files

• 3D scene files

• Source code files

• Property list files

• Rich text files

• Core Data models

• Core Data mapping models

• Project and build settings

• AppleScript files

• Scripting dictionary files

Xcode also has viewers that can display graphics, videos, and a variety of other file types. Control-click in an editor to get help using it.

A file for which Xcode does not have an editor is displayed using Quick Look. (Quick Look is also used by the Finder. In the Finder, select a file and press the Space bar or choose Quick Look from the File menu to see it in use.)

Each document-type editor has custom commands in the Navigate and Editor menus to act on the information in that type of document. Note that the Navigate menu—like several of the menus in Xcode—shows different menu items when you hold down the Option, Shift, or Option and Shift keys.

Edit User Interface Files

Interface Builder is the editor you use to edit user interface documents (nib files). With this editor you design the user interface of your app by adding user interface controls from a library and by specifying properties for those controls, such as their behavior and their position in a view.

For more information on editing user interfaces with Interface Builder, see “Edit User Interfaces.”

Edit Source Code Files

The source editor has many features to help you develop source code. Among other features, you can write and edit source code (see “Edit Source Code”), set and enable or disable breakpoints (see “Manage Breakpoints”), and control program execution during a debugging session (see “Control Program Execution”). Control-click in the source editor to see a list of help topics describing features of the editor and tasks you can accomplish (Figure 1-1).

Edit in Hexadecimal Format with the Hex Editor

You can view most file types in hexadecimal format by Control-clicking the file in the project navigator and choosing Open As > Hex from the shortcut menu. Some file types that are not editable in the default viewer, such as image files, can be edited in hexadecimal format.

You can edit the hexadecimal code directly, or you can edit in the plain text column. Editing either format updates the other.

When the hex editor has focus, you can use the Editor menu to customize its display.

View and edit a file in its binary format by opening it in the hex editor.

To open a file with the hex editor

 

Edit Project Information

When you click the project icon in the project navigator, the project editor appears to the right of the project navigator, displaying project and target information. Figure 1-15 shows some of the target information in the project editor.

Click the Basic button to view basic build settings or click the All button to view all settings. The values of build settings can be set at the default, project, or target level. You can edit a build setting at the project or target levels. Click the Levels button to see all the levels of build settings simultaneously, as in Figure 1-16. If you have changed or customized a setting, it’s shown in boldface. Click the Combined button to see just the resolved build settings.

See “To add a new build configuration” for more information on using build settings.

Edit Property List Files

In addition to the Info.plist file required for every application, the property list editor opens a variety of other property list file types.

To edit a key or a value, double-click the item and type a new string into the text field. In some cases, a pop-up menu is available, indicated by small vertical arrows. Click the arrows to see the choices.

You can add a new property or you can add a new child property for an array or dictionary. The property list editor warns you if you attempt to add a key that already exists in the file.

Add a new property to a property list using the property list editor.

To add a property to a property list

 

Click the minus (–) sign next to any item to remove it from the file.

For known property list key types, the Key column in the property list editor shows the descriptive name of the key instead of the key’s literal text. Choose Editor > Show Raw Keys & Values to display the literal text instead. You can also see both the name and the raw key value in Quick Help in the utility area (Figure 1-17).

Control-click in the editor and select Property List Type to see a list of possible file types for property lists. The type of the current file is indicated by a dash to the left of the file name. You can use this menu to change from the default to a specific property type.

Set the property list type when creating or editing a property list. If Xcode cannot determine the type of a property list, you may need to set the type manually.

To set the property list type

 

Edit Data Model Documents

If your project uses the Core Data framework, you can use the data model editor to implement or modify your Core Data model (see Core Data Starting Point).

Get a jump-start on your Core Data-based project by using one of the project templates that incorporate Core Data.

To create a project that uses Core Data

 

The managed object model is a representation of the schema that describes your model objects, including the relationships between them. Figure 1-18 shows the data model editor.

The top-level components area lists the entities, fetch requests, and configurations defined in the model. You can select one or more items at a time within a single group. Use the Add Entity button to add an entity, fetch request, or configuration. To add a fetch request or configuration, press and hold the Add Entity button until it shows the other options. The button retains the label from the last time it was used.

The detail area shows the attributes, relationships, and fetched properties associated with the item or items you select in the top-level components area. You can select one or more items from the same group at the same time. There are two styles for the detail area: table and graph. You select the style using the Editor Style buttons at the bottom-right corner of the editor area. You can use the graph style only if you select an entity in the top-level components area. You can use either style to edit the model, however the table style is typically better for detailed editing and inspection, and the graph style is better for visualizing your schema.

The Core Data Model inspector in the utility area displays information about the item or items you select in the detail area. By selecting more than one property in the detail area, you can edit several properties at the same time. For example, you can set the Attribute Type for a number of attributes simultaneously.

Edit Core Data Mapping Files

If you change your Core Data model extensively enough that you need a mapping between an old store and a new one, you can use the Core Data mapping model editor to graphically create the mapping model.

A Core Data mapping model describes the transformations needed to convert data described by a Core Data model to another Core Data model with a different schema. The Core Data mapping model editor provides table-based tools to create and edit a mapping model.

The mapping model editor is shown in Figure 1-19.

Click the Add Entity Mapping button to display a series of dialogs that you use to configure the new mapping. If necessary, choose the source and destination models for the entity using the corresponding pop-up menus.

For complete flexibility, you can implement a subclass of NSEntityMigrationPolicy to set it as the custom policy for a mapping.

Standard Editing, Assisted Editing, and Versions Editing

Xcode provides three editing modes targeted for three particular editing workflows:

• Standard editing: One document editor uses the entire editing area. Standard editing is appropriate when a single file or information type requires most of your attention.

  

• Assisted editing: One primary editor pane and one or more assistant editor panes occupy the editor area. Assisted editing is useful when you work on more than one aspect of your project at the same time. For example, use assisted editing when you are connecting user interface elements to implementation code.

  You can display two or more different views of a file, or two or more files in the editor panes (side by side or one above the other).

  Although you can specify which file to show in each editor pane, it is often helpful to let Xcode find and open a related file for you in assistant editor panes.

  

  For more information about assisted editing, see “Split the Editor Area to Display Related Content.”

• Version editing: In version editing, the versions browser takes up the entire editor area. The versions browser contains a document editor for editing your version of a file, a document viewer for viewing earlier versions of the file, and a version selector to select the version to view. Version editing mode is useful in projects using source control management (SCM) when you want to compare your version of the file with earlier versions.

  

  For more information on the comparison editor, see “Compare Revisions.”

Find Information that Supplements the Primary Editor

The utility area contains two subareas: the inspector area and the library area. You use the inspector area to view and set properties of the content open in the primary editor. The library area contains file templates you can use to create files, code snippets you can add to your code, and user interface controls you can add to your user interface files. You can also access all the media files in your project or workspace.

To open the utility area, choose View > Utilities.

View and Edit the Properties of Specific Items

Inspectors are panes in the inspector area of the utility area that you use to read or enter data about the content in the primary editor (which can be a file, and item in the file, or project information).

Which inspectors are available depends on the type of content open in the primary editor. However, two inspectors are available for any content type: the File inspector and the Quick Help inspector.

Get File Templates, Code Snippets, User Interface Objects, and Media Assets

The library panes in the library area of the utility area provide file templates and code snippets that you can drag into your project or workspace, user interface elements that you can add to your user interface files, and the media files (graphics, sound files, and so forth) contained in your workspace.

For more details on the use of the libraries, see “Incorporate Files and Code from the Xcode Libraries.”

Check on the Progress of Xcode Tasks

The activity viewer in the workspace window toolbar shows the progress of any task Xcode is currently executing. If two or more tasks are currently underway, a small number appears at the left edge of the activity viewer (Figure 1-20). Click the number to open a pop-up window that shows the individual status of each current task (Figure 1-21).

If Xcode finds issues in your workspace, an icon in the activity viewer indicates the number and severity of issues found (Figure 1-22). Click the issues icon to see the issues in the issue navigator, described in “Investigate Problems in your Project with the Issue Navigator.” .

Manage Development Devices in the Devices Organizer

Use the Devices organizer to manage your development devices and the digital assets you need to build apps and install them on your devices. Click the Devices button in the Organizer window toolbar to display the Devices organizer.

For details on managing development devices, see “Manage Your Devices.”

Manage Source Control Repositories in the Repositories Organizer

In the Repositories organizer you can create local repositories, connect to and manage repositories on servers, and so forth. Click the Repositories button in the Organizer window toolbar to open the Repositories organizer.

You perform many common SCM operations, such as submitting files, from the workspace window. See “Keep Track of Changes with Source Control” for details.

Manage Project Snapshots and Derived Data in the Projects Organizer

The Projects organizer lists the projects and workspaces you have opened. You can open a project or workspace by double-clicking its name in the list on the left side of the organizer. By selecting a project or workspace in the list, you can access its derived data and snapshots. Click the Projects button in the Organizer window toolbar to open the Projects organizer.

To learn more about snapshots, see “Take a Snapshot of Your Project.”

Browse and Bookmark Documents

The Documentation organizer is a repository of all of the documentation in your library. Click the Documentation button in the Organizer windows to open the Documentation organizer.

To browse documentation, open the Organizer window, click the Documentation button in the toolbar, and click the Browse button at the top of the navigation pane (Figure 1-23).

While reading any page of a document, you can choose Editor > Add Bookmark or Control-click and choose Add Bookmark for Current Page to bookmark that page. Click the Bookmark button in the navigator pane to see a list of bookmarks (Figure 1-24).

To select which documentation sets to download, use the Downloads pane in Xcode preferences.

To set documentation preferences

• Set preferences for updating developer documentation using the Documentation tab of the Downloads preferences pane.

  Documentation is installed in the form of documentation sets, often called doc sets. Apple doc sets for key developer libraries are installed with Xcode, and access to updates for them is controlled by subscription. For your convenience, Xcode can automatically keep these subscriptions up to date. This feature is controlled by the option “Check for and install updates automatically,” which is selected by default. If this option is selected, Xcode displays the date and time of the last check.

  To check for updates manually, click the “Check and Install Now” button. If no new updates are available, Xcode displays a message to that effect. When an update for a doc set is available but not yet installed on your system, Xcode displays an Install button on the subscription line for that doc set. Click that Install button to download and install the updated doc set on your system.

  To install non-Apple documentation, subscribe to the associated documentation feed. First, obtain the web (RSS) feed URL from the publisher. Click the Add (+) button, as shown in the figure, follow the onscreen instructions to enter the URL, and click Add in the dialog.

  To remove a doc set from your system, select the subscription entry for the doc set, then click the doc set info button. Click the Installed Location link to show the doc set file in the Finder, then delete the file from the Finder.

  To unsubscribe from non-Apple documentation, select the subscription entry for the doc set, click the Remove (-) button, and confirm the removal operation.

  At the bottom of the pane, you can set a minimum font size for Documentation organizer content by selecting the option "Never use font sizes smaller than," and then choosing a font size from the pop-up menu.