Identifying the basic workspace components
Setting up your workspace style
Customizing windows and panes
Getting information about items in your project
Now that you have a bird's eye view of how Xcode is organized, drop a few hundred feet and look at the visual layout of Xcode. In this chapter, you learn how items are organized in the Xcode project window, how to choose a window layout style that you like, how to arrange and customize windows, and how to get information about your project.
The project window, shown in Figure 3-1, represents your project and is your home base in Xcode. All of the components that make up your project are organized here. It is also the central means of browsing your project, allowing you to see the products that your project produces, symbols defined in your project, bookmarks you've saved, and other aspects. All other windows in your project are subordinate to your project window. Closing the project window closes the project and all other windows related to the project.
Project content (source files, property lists, details, log output) is presented in individual windows or in one or more panes that share a single window. Some windows are always organized into multiple panes, like the project and debugger windows. Other windows, like editing windows, usually consist of a single pane, but can often be split into multiple panes if you like. You learn more about this later in this chapter and in Chapter 6.
Broadly, content presented in Xcode can be divided into five categories: the project window, editing panes, Info windows, floating windows, and utility windows.
The project window is unique. It contains the Groups & Files pane and the details pane. These panes do not appear in any other window. Depending on your project layout style, the project window can also include editing panes and present the content of other utility windows.
Editing panes edit the content of source files, and are where you will be spending much of your time during development. Editing panes are often contained in their own window.
Info windows display detailed information about an item in your project. This is where you examine the details and options for each item. You can usually open an Info window by choosing Get Info, either by clicking the toolbar button or choosing View
Xcode also presents transient information in floating windows and tool tips. These include suggested code completions, API documentation, detailed error descriptions, and variable inspectors. An example of a Quick Help window is shown in Figure 3-3.
Utility windows are the catch-all category for all of the other kinds of windows that appear in Xcode. There are windows for browsing the documentation, building your project, debugging your executable, searching multiple files, and so on.
Xcode provides three different strategies for organizing your windows and panes, called a layout style. You can change the layout style as often as you like. It doesn't have any material effect on the content or functionality of your project; it just defines its visual organization and navigation. You should have a basic understanding of the layout styles offered by Xcode, because they influence how the project window is organized and where information about its content is displayed. It also affects Xcode's use of separate windows for various tasks.
Note
Xcode saves your layout preferences — open windows, window position, list order, table columns, and other display options — in a per-user, per-layout preference file stored in the project's document. The window positions and display options you establish in one layout will be ignored by other layout styles. Similarly, your view preferences will be independent of those of other users working on the same project (assuming they have a different POSIX account name).
Xcode offers the following three layout styles:
STYLE | DESCRIPTION |
|---|---|
| All of the project groups and items are in a single browser shared with a combination details and editor pane. Source files may be edited here, or in separate windows. Build, debug, and other tasks open in separate windows. |
| The project window contains only the project groups and items. All tasks, including editing, are performed in separate windows. There is no details pane. |
| The project and most tasks are confined to a single window. |
The Default layout style, which was shown in Figure 3-1, is the traditional Xcode windowing style. The project window contains all of the groups and items in a single browser. The window shares a split pane with item detail and editing panes on the right side. You can view and edit source files immediately in the right pane, or you can open them in separate windows. Build, Debugging, and other tasks appear in their own window. This is a good choice for general development on a moderate-sized screen.
The Condensed layout style, shown in Figure 3-4, could also have been named the "Everything-In-A-Separate-Window" style. The project window contains only the project's group and items. The groups are further subdivided by a tab control at the top of the window. The tab selects between the source groups, the target groups, and all other types of smart groups. This chapter shows you how you can customize this organization a little later. Everything else you work with, or open, appears in a separate window. This is a good style for complex projects and for developers with large monitors.
The descriptively named All-In-One layout style, shown in Figure 3-5, is essentially the opposite of the Condensed style. The project, editing, and all tasks (build results, multifile searches, source control) are contained in a single window. You can switch which view you are working with using one of several tab controls. The tab control in the upper-left corner of the window switches the entire window between the project and debugger views. While in the project view, another tab control above the right editor pane switches the upper portion of the pane between the Detail, Project Find, SCM Results, and Build Results. This is a good style for developers with small monitors or those who want to avoid the clutter of having many different windows open. It can be particularly useful when you're working with multiple projects at the same time — it's often difficult to identify to which project an auxiliary window belongs. This problem is explained in more detail in the "Opening One or More Projects" section in Chapter 4.
Despite its name, the All-In-One style does not force everything into a single window. You can still cause selected source files to open in separate windows for more convenient editing. Additionally, Info and Quick Help windows are always separate, regardless of the layout style you are using.
Xcode's layout style is global. After you have set it, it applies to all projects that you open. To change Xcode's layout style, choose Xcode
The global layout style is selected with the Layout pop-up menu. Other options control the behavior for edit panes, whether projects are automatically reopened when Xcode is launched again, and whether open windows are restored when a project is reopened.
Note
The layout style cannot be changed while there are any open windows that are influenced by Xcode's layout style. If the Layout option in the preferences window is disabled, close all projects and utility windows until it becomes enabled.
The next few sections explain the details of the project window and how the layout styles influence their layout and navigation.
All of the components of your project are represented as icons in the Groups & Files pane of your project window. Icons with a small grey expansion triangle next to them indicate a group of items. Groups contain items and sometimes other groups.
The very first group is the project structure group, or just project group. This has the same name as the project and contains all of the project's assets. The remaining groups are called smart groups. Smart groups change to reflect the state of the project. Figure 3-7 points out the source and smart groups in a layout.
Search for something and the search and its results appear in the Find Results group for future reference. Edit a file checked out from source control and it appears in the SCM group. Check in the changes and it disappears again.
You can expand or collapse the contents of any group by clicking the small triangle next to the group's icon. Holding down the Option key when expanding or collapsing expands or collapses all subgroups as well.
The most flexible group is the project structure group. Within this group, you add the source assets (source files, image files, Interface Builder documents, property lists, and so on) that will be used to build your project. All of the groups in the project structure group are generically referred to as source groups. These can be organized into any arbitrary arrangement of subgroups that you like. When you create a project, Xcode automatically creates source groups for Classes, Other Sources, Resources, Frameworks, Products, and possibly others depending on the project template. Within the Frameworks groups you'll usually find subgroups for Linked Frameworks and Other Frameworks.
How many source groups you create, their names, and how you organize them is entirely up to you. Xcode does not impose any kind of organization or convention when it comes to the project structure group. You are free to put a movie file in the Classes groups or rename the Classes group to "Wonkavator." You can just as easily move all of your assets to the top-level project structure group and delete all subgroups. This is not a bad idea for very small projects, because many small groups can just get in the way.
Note
Although you generally have carte blanche to organize the source groups however you see fit, there is one exception: the Products subgroup. Although Products appears to be just another source group, it's actually a smart group. Products are the end result of targets (see Chapter 16). You cannot delete or rename the Products groups or any of the products contained therein. Products are added, removed, and renamed by editing the targets that define them.
The remaining groups in the project window are the smart groups. If you have used smart groups in iTunes or Mail lately, this concept will be immediately clear. A smart group contains items that reflect some property or information about your project, and have a fixed or restricted structure. Files or items that meet that criterion appear in the group automatically, and disappear as soon as they no longer qualify. Xcode defines several smart groups, as listed in the following table:
SMART GROUP | CONTENTS |
|---|---|
Targets | The targets defined in the project. Expand a target to reveal its build phases. See Chapter 13. |
Executables | Executable programs produced by the project. |
Find Results | The results of the last several searches that were performed. |
Bookmarks | Bookmarks you have created. |
SCM | Pending Source Control actions for this project. See Chapter 21. |
Project Symbols | The symbols defined in the project. |
Breakpoints | The debugger breakpoints set in the project. This group is not shown by default. |
Implementation Files | All of the source files (.c, .cpp, .m, .mm, .java, .sh, and so on) in the project. |
Interface Builder Files | All of the NIB documents in the project. |
Reorder your source or smart groups by dragging them to a new position in the list. Reorganize source groups and source items by dragging them to a new position in the source group, or dropping them into another source group. A drop indicator will tell you if are you about to drop the item(s) adjacent the group, or inside it.
You can create a new, empty source group by selecting a source group or file and choosing File
You can gather an arbitrary set of files or groups and move them inside a newly created group in a single step: select the items and choose the File
You can rename any source group or file by first selecting it and clicking once on the item's name. You can also Right/Control+click an item and choose Rename.
Finally, you can delete a group in one of two ways. The first, and most obvious way, is to choose Delete from either the Edit menu or the Right/Control+click contextual menu. This deletes both the group and its contents. If the group contained file or folder references, you get a confirmation dialog box asking you if you want to delete just the references or the actual files. See Chapter 5 to learn about references.
To delete a group without deleting its contents, select a group and choose the Ungroup command from the Right/Control+click contextual menu (there is no main menu command for this). Ungroup dissolves the group and replaces it with the items it previously contained.
You are free to alter which top-level groups are visible in your project window. For example, if you are not using source control you may want to hide the SCM group.
Right/Control+click any top-level group and locate the Preferences submenu. Here you will see all of the top-level groups in your project. Groups that are checked will be visible in the pane. Check and uncheck whatever groups you wish. When you uncheck a group, Xcode asks for confirmation before deleting it. This is somewhat misleading, because the group is not "deleted" in the strictest sense. Check the group in the Preferences menu again and it reappears.
When using the Condensed layout, you have three sets of groups, defined by the Files, Targets, and Other tabs above the group list. Each set is independent of the others, and you can add or remove groups from any tab. I find it convenient to have the Bookmarks group in the Files tab, because most of my bookmarks are shortcuts to places in my source code. Show or hide the groups that make sense to you.
In the Default and All-In-One layout styles, you can also have multiple views of your groups. In these two layout styles, Xcode places a split-pane control just above the group list scroll bar.
Click the split pane icon, as shown in Figure 3-9, to split the list into two lists. You can now alter which groups appear in the upper and lower panes independently. To return to one list again, click the join pane icon just below the split pane icon of the list you want to discard. Unfortunately, Xcode does not remember which groups were visible in the second list the next time you re-split the pane. If you spend time customizing your groups, it's best to leave the pane split, minimizing one or the other as desired.
You can also, rather erroneously, select any top-level group and apply the Delete command as you would a source group. The Delete command merely hides the group and is equivalent to unchecking it in the Preferences submenu.
After you've spent some time setting up and customizing the organization, panes, and columns of your project, you can save that layout as the new default for all new projects. Here's how:
When using the same layout style, all new projects will have the same size, layout, and organization that your current project has right now.
If you've completely trashed the default layout, or you inherited one that you dislike, you can reset the new project layout to the factory settings. To reset the layout, choose the same command but click the Restore To Factory Default button instead. Note that these two commands only apply to new projects using the current Xcode layout style.
The Implementation Files and Interface Builder Files smart groups automatically collect all of the source files that match a particular naming convention. These groups are actually just predefined custom smart groups, which you can create yourself. The next section will show you how. You edit the criteria of these two by selecting one and choosing the Get Info command. Get Info is available from the File menu, the Right/Control+click contextual menu, and from the toolbar. The Info window for the Implementation Files group is shown in Figure 3-10.
The really useful settings here are the Start From and Using Pattern settings. You can limit the scope of the smart group's search by setting the source group that it searches, and whether it searches just the files in that group or it and all of its subgroups. The Using Pattern establishes the filename pattern that will cause files to appear in the smart group. If you want header files to appear, but not script files, edit the pattern accordingly. You have the choice of using a shell-like globbing pattern or a regular expression. The changes you make affect all projects.
The rest of the options are really only applicable when creating and customizing your own smart groups, and should probably be left as they are.
You can create one kind of smart group yourself. This is limited to collecting source files automatically that match a particular pattern. Xcode comes with two of these "simple" smart groups pre-defined: The Implementation Files group and the NIB Files group that were described in the previous section.
Custom smart groups come in two flavors: Simple Filter smart group and Simple Regular Expression smart group. The Filter flavor matches files based on file name "globbing" used in the shell — where the pattern *.c matches all C source files. The Regular Expression flavor matches files using regular expressions — the pattern .[ch]p{0,2}$ matches file names ending in .c, .h, .cp, .hp, .cpp, or .hpp. See Chapter 8 for an overview of Regular Expressions. The "Searching Lists" section of that same chapter has a brief description of globbing patterns.
In the Info window, edit the name under which the group will appear in the project window. Click on the Choose... button next to the image, or drag an image into the icon preview, to provide the group with something more evocative than the generic "gear folder" icon.
Start From chooses where the smart group looks for files that match the pattern. Project is the default, and refers to the top-level project structure group. You can also choose to restrict the search to a specific group within the project. The Recursively check box causes the Smart Group to search all subgroups of the Start From group for matches.
The Using Pattern field is either the wildcard or regular expression pattern that will be used to match files. If you selected to create a Simple Filter Smart Group, Wildcard will be selected. If you selected to create a Simple Regular Expression Smart Group, Regular Expression will be selected. You can turn a Filter group into a Regular Expression group, and vice versa, at any time by selecting the other radio button.
The Save For menu determines if the Simple smart group you just created will appear in all projects opened on your system, or only the current project. The All My Projects setting is convenient for Smart Groups you plan to use over and over again, as you can elect to use it in any project just by revealing it in the project's group list.
Warning
Be very careful when creating simple smart groups for all projects. There is no way to individually delete smart groups you've created. A procedure to delete all of the global smart groups is described in the next section, but if you want to delete some and preserve others, you will need to reconstruct them.
Warning
Also, be careful when saving a smart group for all projects that have a Start From location that is not the top-level project structure group. There is no clear rule for determining which group will actually be searched in other projects. Those projects might not have a group with that name, or they once did and the group was renamed, or the group has been moved to some other part of the group hierarchy. Any of these conditions can cause a global smart group to search the wrong group for files. When you're creating smart groups that you intend to use in other projects, stick to the top-level project structure group.
You can later open the Info window for any smart group and edit its definition.
One caveat about smart groups is that sometimes they aren't very smart. Although they will usually pick up files that you add to a project, they often fail to update if you rename or remove them from the project. Closing and opening the project will refresh the list.
System-wide smart groups that you define in one project won't automatically appear in other projects. Use the technique described earlier in the "Showing and Hiding Groups" section to add (or remove) your global custom smart group to another project.
One unfortunate omission from the Xcode user interface is the ability to delete smart groups that you've created. Like the predefined smart groups, an attempt to delete them only hides them in the list. Even more irksome is that the data structures used to store smart group definitions are opaque, making it impossible to selectively delete smart groups. What you can do is delete all of the smart groups saved in an individual project, or all of the global smart groups available to all projects. If you have smart groups that you want to save and others that you want to delete, you will need to write down the settings for the ones you want to save and recreate them afterwards.
To delete all of the smart groups saved in an individual project, first close the project. Select the project's file icon in the Finder and use the Right/Control+click contextual menu to choose Show Package Contents. Inside the .xcodeproj package, you will find a series of files beginning with your account's short user name where Xcode preserves the layout and window preferences for each user. The file youraccount.pbxuser contains the smart group definitions that you've saved in this project. Open the file in a text editor, such as TextEdit or BBEdit, and delete the line that begins with com.apple.ide.smrt.PBXUserSmartGroupsKey. Alternatively, this could also be accomplished via the following command line in the Terminal:
james$ cd ~/Desktop/Explore Layout/Explore Layout.xcodeproj/ james$ mv james.pbxuser james.pbxuser.bak james$ grep -v PBXUserSmartGroupsKey james.pbxuser.bak > james.pbxuser
To delete all of the smart groups saved for all projects, first quit Xcode. Using the Property List Editor (you will find this in the /Developer/Applications/Utilities folder), open the com.apple.Xcode.plist file in your account's ~/Library/Preferences folder. Look for an element with the key com.apple.ide.smrt.PBXUserSmartGroupsKey.ver10, shown in Figure 3-11.
Delete this element and save the file. The next time you launch Xcode, it will recreate the default Implementation Files and NIB Files groups. All other user-created smart groups will be gone.
Now that you've learned to organize, customize, and navigate the top groups of your project, you're going to start digging into the details of those groups and what they contain. Details about the content of groups are displayed in a table called the details list. The columns of the table display properties about each item.
In the Default and All-In-One layout styles, the details list is displayed in a pane on the right side of the window, as shown in Figure 3-12. The Condensed layout style does not include a details pane in the project window.
The details pane shares its side of the window with an editor pane. If the details list is not visible, choose View
You can hide the details view and compact the window by double-clicking the expand/collapse control that sits between the Groups & Files list column header and the details list column header, also shown in Figure 3-11. Double-clicking the divider completely collapses the Groups & Files pane, leaving only the details list.
Note
There are some shortcut commands in the View
The details list always displays the set of source items encompassed by the current selection in the Groups & Files list. Selecting an item in the Groups & Files list displays that item. Selecting a group lists the details of all of the items contained in that group and any subgroups. Selecting a target lists all of the items used to build that target. Selecting combinations of groups and items displays the aggregate union of those sets.
Note
A few obscure exceptions to this rule exist. For instance, the content of frameworks and bundles are not included in the details list unless the framework or bundle is explicitly selected in the Groups & Files list. This avoids commingling the individual components of a framework, which might include hundreds of header files, with the source files of your project.
The details list is typically used to see the status of an item; for example, to see whether it contains any compiler errors, has been modified, or needs to be built. Double-clicking an item in the list opens that item and is generally equivalent to opening the corresponding item from the Groups & Files list. A few properties can be edited directly in the details list; most notably, the Target column. An item with a check box in this column can be immediately added or removed from the current target by ticking its check box.
The columns shown in the details list are dependant both on the type of items being listed and which columns you've elected to display. Each group contains only one kind of item: The Project group contains source files, the Find Results group contains search results, the Bookmarks group contains bookmarks, and so on. Some properties that apply to source files (Target membership, compiled size, and so on) do not apply to bookmarks and vice versa. Selecting a set of files displays only the detail columns appropriate to source files. Selecting one or more bookmarks displays columns appropriate only to bookmarks.
Within the set of applicable columns, you are free to choose which are shown by enabling and disabling individual columns. To change the columns in a details list Right/Control+click any column header, as shown in Figure 3-13. A pop-up menu shows all the columns and which are currently displayed. Some detail lists have columns that you cannot hide. For example, the Role column in the Targets group cannot be hidden, and does not appear in the pop-up list.
You can resize columns by dragging the divider line between column headers. Reorder columns by dragging the column header to a new position. The layout for each type of list is remembered separately, so changes to one type of list do not affect others.
In addition to choosing the columns for the details list, you can add selected detail columns directly to the Groups & Files list. Right/Control+click any column header in the Groups & Files list. Not all details apply to all types of items; ones that don't will be blank.
This ability is particularly useful in the Condensed layout style, which does not have a details pane in the project window. For example, in multi-target projects I invariably add the Target Membership column to the Groups & Files list so that I can quickly see (and change) what files are members of the active target.
The Inspector and Info windows are the third, and finest, level of detail in Xcode. The details list shows basic properties about many items at once, but an Info window tells the whole story. It is where you can inspect and modify every aspect, property, and setting of each item. For some items, that's a lot of information.
You can view the information about an item either in an Info window or in the Inspector palette. Info windows are regular windows. One is shown on the left in Figure 3-14. You can have multiple Info windows open at a time, which is particularly useful for comparing the details of two items. To open the Info window for an item, select the item in the project window, or have an editor window active, and choose the File
Changing the properties of the project, target, or executable is such a common activity that Xcode provides additional shortcuts just for those. When you double-click the top-level project group, individual targets, and individual executables, Xcode opens an Info window — rather than expanding or collapsing their contents like other groups. The Project menu contains three commands: Edit Project Settings, Edit Active Target, and Edit Active Executable. All of these commands just open the appropriate Info window.
The Inspector palette, shown on the right in Figure 3-14, is a single floating palette that shows the information for the currently selected item or active window. Getting information about a different item is as easy as selecting the item. The Inspector is always on top of all other windows and disappears when Xcode is not the active application. You can use both the Inspector and Info windows at the same time.
To reveal or hide the Inspector palette, hold down the Option key and select the File
The Inspector and Info windows can display and alter the properties for more than one item at a time. Select multiple items and the Info window presents all of the properties that are common to those items. If you select disparate items, the Info window may only present one or two properties that are common to all, such as the item's Comments. Radically different items result in an Info window that says "Nothing to Inspect."
For each property, Xcode displays the value that is common to all of the items or it presents an indicator that the value of the property varies between the items. Changing the value of the property changes it for all of the items. If the property cannot be logically applied to all items, it is disabled.
Warning
Changes made in the Inspector and Info windows are immediate. There is no opportunity to cancel the change and most changes are not tracked by the Undo facility, so be mindful about making changes that you might want to retract, although there are actually very few changes that you could make in an Info window that aren't easily reversed. The advantage is that you do not have to close the Inspector or Info window for the changes to take effect. This is particularly useful when you're changing values like build settings, because you can edit the setting and build immediately with the new settings. The only exceptions are some text entry fields. You may have to tab out of a field, or switch focus to another control or window, before the change is applied.
The toolbar is a standard Macintosh user-interface element. Toolbars can contain command buttons, pop-up lists, search fields, and other controls right at the top of each window, making them immediately visible and quickly accessible. Refer back to Figure 3-1, or almost any other figure of a window, for an example. The items you want in your toolbar are those functions that you use repeatedly and to which you want fast access, as well as settings and conditions that you want to refer to quickly. If you've been using OS X for any length of time, you are undoubtedly familiar with toolbars. If not, here's a crash course on Mac OS X toolbars:
Toolbars can be shown or hidden by clicking the elongated white button at the right side of the window's title bar, or by choosing View
Toolbars can be customized by choosing View
Add, remove, or rearrange items in the toolbar customization sheet by dragging.
Choose the icon mode and size at the bottom of the sheet.
You can rotate through the toolbar's icon modes and sizes by repeatedly clicking the toolbar button while holding down the Command key.
All like windows share the same toolbar. Customizing the toolbar of an editor window changes the toolbar for all editor windows.
Almost all toolbar controls implement a command, setting, or function found elsewhere in the Xcode system. Toolbars do not add functionality — they merely add convenience. Some toolbar items are specific to certain windows. For example, the Debugger's toolbar can be populated with all kinds of debug-specific items, which do not appear in other toolbars. Explore the toolbars for each window type to discover what items you can use there.
Although most of the controls you can place in the toolbar are self-explanatory, the following table lists three that might need a little more explanation.
FUNCTION | |
|---|---|
Project | An oft-overlooked toolbar shortcut that simply brings you back to your project window, equivalent to View |
The "stop sign" item is used to stop running tasks. Tasks include building, running, and debugging. Click once to stop the most recently started process or application. Hold down the button to reveal a list of running tasks and choose the task you want to terminate. | |
Overview | The Overview pop-up menu is a combination of the Active SDK, Active Build Configuration, Active Target, Active Executable, and Active Architecture tools. If you work with multitarget projects that produce several executables or have more than three build configurations, this is probably the most useful tool to have in your toolbar. |
The project window's toolbar (in the Default and All-In-One layout style) has one oddball tool that you can only add or remove using the View
The thick portion at the bottom of the window's frame (which was visible in Figure 3-1) is not merely decorative — it's the status bar. The status bar displays various progress and status messages for processes like builds and multifile searches. You can hide or show the status bar in most windows using the View
You can reveal the Favorites bar in the project window, shown in Figure 3-15, using the View
Clicking once on a favorites item selects that item in the project window. Double-clicking opens the file. In the case of a bookmark, it jumps to that bookmark location. If you add a source group to the Favorites bar, click and hold on the folder to get a pop-up menu of the files in that group.
The Activity Viewer window is a bit of an odd duck. It's the only window that doesn't really belong to any specific Xcode function, tool, or item. It simply displays the progress of various Xcode tasks. Open it using the Windows
You should now have a good feel for how to get around in Xcode. You know how to choose the visual style that fits your needs, customize the interface a little, organize the items in your projects, and get varying degrees of information about items in a project.
You are now ready to create a working project.