---

The Project Window and its Components

When you first launch Xcode as a new user, Xcode displays the default project window configuration, shown here.

The project window contains the following key tools for navigating your project:

• The Groups & Files list provides an outline view of your project contents. You can move files and folders around and organize your project contents in this list. The current selection in the Groups & Files list controls the contents displayed in the detail view.

• The detail view shows the item or items selected in the Groups & Files list. You can browse your project’s contents in the detail view, search them using the Search field, or sort them according to column. The detail view helps you rapidly find and access your project’s contents.

• The toolbar provides quick access to the most common Xcode commands.

• The status bar displays status messages for the project. During an operation—such as building or indexing—Xcode displays a progress indicator in the status bar to show the progress of the current task.

• The Favorites bar optionally lets you store and quickly return to commonly accessed locations in your project. The Favorites bar is described in “The Favorites Bar.”

The project window can also contain an attached editor that lets you edit files directly in the project window. You can navigate through the views in a window, including the attached editor, by pressing the Tab key. To take the focus away from the editor, press Control-Tab.

The exact configuration of the project window depends on the current layout; nonetheless, each layout uses these components help you view and access project items. For a description of each of the available project window layouts, see “Project Window Layouts.”

In this section:

The Groups & Files List
The Detail View
The Project Window Toolbar
The Project Window Status Bar

The Groups & Files List

The Groups & Files list provides an outline view of your project’s contents. The contents of your project—files, folders, targets, executables, and other project information—are organized into groups. A group lets you collect related files or information together. The Groups & Files list gives you a hierarchical view of these groups.

Using the Groups & Files list, you can:

• View your project’s contents, organized hierarchically. You can have as much or as little of your project’s contents as you want visible at once.

• Create additional Groups & Files list views to focus on multiple groups at once.

• Drag files, folders, groups, and other project items to rearrange and organize them.

• Rename files, folders, and other project items. To do so, Option-click the item and type the new name; or Control-click and choose Rename from the menu.

Groups in Xcode

Xcode supports two types of groups; you can view and edit groups of either type in the Groups & Files list:

• Source groups organize your project’s source files, including implementation files, resources, frameworks, headers, and other files. A source group, indicated by a yellow folder icon, can contain any number of files and other source groups. Source groups help you organize the files in your project into more manageable chunks. The project group, represented by the project icon at the top of the Groups & Files list, is a source group that contains all of the files, frameworks, and libraries included in your project.

• Smart groups collect files or information that match a certain rule or pattern. Xcode provides several built-in smart groups:

  • The Targets group contains all of the targets in your project. As mentioned earlier, a target contains the instructions for creating a single software product. Targets are described in more detail in “Targets.”

  • The Executables group contains all of the executables defined in your project.

  • The Errors and Warnings smart group lists the errors and warnings generated when you build. This group is described further in “Viewing Errors and Warnings.”

  • The Find Results smart group contains the results of any searches you perform in your project. Each search creates a new entry in this group. For more information on the Find Results group, see “Viewing Search Results.”

  • The Bookmarks smart group lists those commonly accessed locations—files or specific locations within a file—that you have saved in order to return to them easily. For more information on the Bookmarks smart group, see “Saving Commonly Accessed Locations as Bookmarks.”

  • The SCM smart group lists all of the files that have source control information. This group is described further in “Viewing File Status.”

  • The Project Symbols smart group lists all of the symbols defined in your project. This group is described further in “Viewing the Symbols in Your Project.”

Xcode also lets you create your own smart groups and define your own rules for what they contain; these smart groups are indicated with a purple folder icon. For more information on using smart groups and source groups to organize your project contents, see “Organizing Files.”

Hiding and Showing Groups

Xcode provides a number of smart groups to help you organize and find information; however, you may not need all of those smart groups all of the time. You can customize the display of the current Groups & Files list to show only those smart groups that you currently need. You can rearrange or delete any of the smart groups that appear in a Groups & Files list view, including those that Xcode supplies.

To rearrange a smart group, drag it to its new position in the Groups & Files list. To hide a smart group in the current Groups & Files list, select it and press Delete or choose Edit > Delete. To view the smart group again, choose it from the View > Show menu, as described in the next section.

Xcode also provides contextual menu items to show and hide smart groups in the Groups & Files list. Control-click in the Groups & Files list to show the contextual menu and choose the smart group from the Preferences menu. If the smart group is currently visible, choosing it from this menu hides the smart group. Otherwise, it shows the smart group in the Groups & Files list. A checkmark next to the smart group’s name in the Preferences menu indicates that the smart group is currently visible. You can show and hide Xcode’s built-in smart groups, as well as any smart groups that you have defined for your projects.

Viewing the Contents of a Group

You have a couple of options for viewing the contents of a group in the Groups & Files list. If you prefer the outline view, you can disclose the group’s contents directly in the Groups & Files list. You can also select one or more groups to view their contents in a simple, searchable list in the detail view, described in “The Detail View.”

To view the contents of a group in the Groups & Files list you can:

1. Double-click the group to expand its contents in the outline view, shown below. Double-clicking the group a second time closes the group.

2. Click the disclosure triangle next to the group to show its contents in the outline view.

3. Choose any of Xcode’s built-in smart groups from the View > Show menu to disclose that group’s contents in the outline view. Xcode also selects the group and displays its contents in the detail view. Choosing View > Show > All Files discloses the contents of the project group. You can use the Vie w > Show menu to display a smart group, even if you had previously deleted from the current Groups & Files list.

4. Select the group to show the contents of the group, and of any other groups it contains, in the detail view.

You can sort the contents of a source group in the Groups & Files list by choosing an item from the View > Sort menu. You can sort by name or by file types. Xcode sorts the contents of the currently selected group.

The Groups & Files list can display additional information for files in the list. You can view status for files under version control or see whether a file is included in the active target. To see this information in the Groups & Files list, choose View > Groups & Files Columns > SCM or View > Groups & Files Columns > Target Membership, respectively.

To view more information on any item in the Groups & Files list, select that item. Xcode displays additional information about that item in the associated detail view, if one is open.

Splitting the Groups & Files View

In large projects, the Groups & Files list can get quite long, making it difficult to move items around. You can split the Groups & Files view by clicking the icon in the scrollbar next to the Groups & Files list, as shown here. You can also split a view by choosing View > Split 'Files' Vertically or typing Command–double-quote. Xcode splits the view that currently has focus.

Each view can display a different location, making it easy to keep commonly accessed groups handy or to move items between groups. You can drag the resize control between the Groups & Files views to repartition the space between them as you see fit. Each view has its own split-view button; you can split each of these views, creating as many split-views as you need. After you create a split, a new button appears below the split-view button; to close a split Groups & Files view, click this second button. You can also close a split view by choosing View > Close Split 'Files'.

By default, Xcode splits the view vertically. However, you can also split a view horizontally. To split a view horizontally, hold down the Option key while clicking the split-view button or choosing View > Split 'Files' Horizontally. You can also type Option–Command–double-quote.

The Detail View

As you learned, the Groups & Files view lets you see the contents of your project in an organized outline. In contrast, the detail view shows you items in a flat list. You can quickly search and sort the items in this list, gaining rapid access to important information in your project.

You control the scope of the information shown in the detail view with your selection in the Groups & Files list. If the selected item is a group, the detail view displays information for all of the members of that group and of any sub-groups that it contains. You can select multiple items in the Groups & Files list; the detail view displays all of the selected items and their members. This applies to both contiguous selections and to selections of items that are not adjacent.

The Information Displayed in the Detail View

The type of information displayed in the detail view varies, depending on the item selected in the Groups & Files list. For example, if you select a group of source files in the Groups & Files list, the detail view displays each of the files in that group, along with information about those files, such as the file’s build status or code size. However, build status and code size make no sense for errors and warnings, so when you select the Errors and Warnings group, you see a list of error and warning messages and the locations at which they occurred.

You can choose what information Xcode shows in the detail view by choosing which columns are visible. To make a column visible, choose it from the View > Detail View Columns menu. You can also Control-click any of the column headings; Xcode brings up a menu like the one shown below, which allows you to choose which columns are visible.

You can display the columns of the detail view in any order. To reorder the columns, drag the heading of any column to its new position.

You can use the menu items View > Previous Detail and View > Next Detail, or their keyboard shortcuts, to move the selection up or down in the detail view. To disclose the currently selected detail in the Groups & Files list, choose View > Reveal in Group Tree. For example, if the current selection in the detail view is an individual source file, Xcode selects that file in the Groups & Files list, disclosing the contents of any source groups that the file belongs to, as necessary.

To rename an item in the detail view, Option-click the item and type the new name; or Control-click the item and choose Rename from the menu.

Searching and Sorting in the Detail View

With the detail view you have a couple of ways to find and view information. You can sort the contents of the detail view according to the information in any of the visible categories simply by clicking on the column heading for that category. For example, to sort by file name, click the File Name heading.

Using the search field in the toolbar, you can quickly search the contents of the detail view. As you type, Xcode filters the contents of the detail view, displaying only those items that have matching text in at least one of the columns.

The Search field supports several different types of search; you can choose the search type from the pop-up menu in the Search field. Xcode supports the following searches:

1. String Matching. Xcode determines a match using simple string comparison, filtering out items that do not match the string in the Search field. This is the default type of search for the Search field. It is also the fastest.

2. Regular Expression. Xcode uses the regular expression in the Search field to find matching items. For example, to find all C implementation and header files in a source group, enter \.(c|h)$

3. Wildcard Pattern. Xcode uses the wildcard pattern in the Search field to find items that contain the specified characters anywhere in any of the visible columns. For example, enter *View*.h to find all header files with “View” in their name.

For example, in a large list of source files, you can find all of the files with the word “dialog” in their title by choosing a String Matching search and typing “dialog” in the Search field, as shown here.

As you type, the status bar displays the scope of the search—the current selection in the Groups & Files list—and the number of items found. Pressing the “Home” key or choosing the project item (indicated by the project icon) from the search field’s pop-up menu changes the focus of the search field to the whole project.

By default, Xcode clears the Search field when you select a different smart group in the Groups & Files list. To tell Xcode to preserve the contents of the Search field, open the General pane of Xcode Preferences and disable the “Automatically clear smart group filter” option in the Environment options.

The Project Window Toolbar

The project window toolbar gives you quick access to the most common Xcode commands. The project window toolbar for the Default layout contains the following items:

• Active Target pop-up menu. The target menu lists the active target, which is the target that is used whenever you build the project. You can change the active target using this menu.

• The Action button. The Action button lets you perform common operations on the currently selected item in the project window. The actions available from this button are those appropriate for the selected item; they are the same actions available in the contextual menu that appears when you Control-click the selected item. For example, when the current selection is a file, available operations include opening the file in a separate editor, performing version control operations, and grouping files.

• The Build buttons. The Build buttons initiate common build actions, such as building, cleaning, and running. The triangle at the bottom of the Build buttons indicates that there are multiple actions associated with them. A single click on one of these buttons performs the action represented by the button’s icon. If you press and hold the mouse button over one of these buttons, you get a pull down menu of all of the actions associated with the button. You can initiate any of these actions by selecting it.

• Tasks button. The Tasks button allows you to stop any operation that is currently in progress in your project. The badge in the lower right corner of the Tasks button indicates the operation that is stopped when you click the button. If more than one operation is in progress, the Tasks button lets you select the one you want to stop. For example, if you have both a build and a search running, you can stop either operation by pressing and holding the Tasks button. Xcode displays a pop-up list of the tasks currently in operation; choose a task to stop it.

• Editor button. The Editor button shows and hides the code editor in the project window. Using this editor, you can view and edit files directly in the project window. You can also view the source associated with an error or warning or with a search result. The editing features of Xcode are described further in “Editing Source Files.”

• Info button. The Info button brings up an Info window, allowing you to examine and edit groups, files, targets, and other items in your project. See “Inspector and Info Windows” for more information on inspecting items in your project.

• The Search field. The Search field allows you to search the items currently displayed in the detail view. As you type, Xcode filters the list of items in the detail view to include only those items with matching content in one of the visible columns. See “The Detail View” for more information on using the Search field to find items in the detail view.

You can customize the project window’s toolbar by choosing View > Customize Toolbar. Drag one or more toolbar items to or from the toolbar to get the set that is most useful to you.

The Project Window Status Bar

The project window status bar lets you view the progress of the current operation in Xcode. It gives you feedback during potentially lengthy tasks, such as building, as well as displaying the results of those tasks. In particular, the status bar lets you quickly access important information about project operations. From the status bar, you can:

• Click the progress indicator during an operation to open a more detailed account of the currently running operations in the Activity Viewer window, described in “Viewing the Progress of Operations in Xcode.”

• Click the build result message, or error or warning icon, to open the Build Results window and view build system commands and output. For more information on the ways in which Xcode displays the status of build operations, see “Viewing Build Status.”

---