Help
An Xcode project must embody a lot of information about what files constitute the project and how they are to be used when building the app, such as:
- The source files (your code) that are to be compiled
- Any resources, such as icons, images, or sound files, as well as nib files, that are to be part of the app
- Any frameworks to which the code must be linked as the app is built
- All settings (instructions to the compiler, to the linker, and so on) that are to be obeyed as the app is built
Xcode presents this information in graphical form, and this is one reason why a project window is so elaborate, and why learning to navigate and understand it takes time. Also, this single window must let you access, edit, and navigate your code, as well as reporting the progress and results of such procedures as building or debugging an app. In short, the single project window displays a lot of information and embodies a lot of functionality. You won’t lose your way, however, if you just take a moment to explore this window and see how it is constructed.
Figure 6-1 shows the project window, configured in rather an extreme manner, in order to display as many parts of the window as possible. In real life, you’d probably never show all these parts of the window at the same time, except very briefly, unless you had a really big monitor.
Figure 6-1. The project window, on steroids
- On the left is the Navigator pane. Show and hide it with View → Navigators → Show/Hide Navigator (Command-0) or with the first button in the View segmented control in the toolbar.
- In the middle is the Editor pane (or simply “editor”). A project window always contains at least one Editor pane. I could have displayed this window with multiple Editor panes, but I was afraid that might make you run screaming from the room.
- On the right is the Utilities pane. Show and hide it with View → Utilities → Show/Hide Utilities (Command-Option-0) or with the third button in the View segmented control in the toolbar.
- At the bottom is the Debugger pane. Show and hide it with View → Show/Hide Debug Area (Shift-Command-Y) or with the second button in the View segmented control in the toolbar.
Note: All Xcode keyboard shortcuts can be customized; see the Key Bindings pane of the Preferences window. Keyboard shortcuts that I cite are the defaults.
The Navigator Pane
All navigation of the project window begins ultimately with the Navigator pane, the column of information at the left of the window. It is possible to toggle the visibility of the Navigator pane (View → Navigators → Hide/Show Navigator, or Command-0); for example, once you’ve used the Navigator pane to reach the item you want to see or work on, you might hide the Navigator pane temporarily to maximize your screen real estate (especially on a smaller monitor). You can change the Navigator pane’s width by dragging the vertical line at its right edge.
The Navigator pane itself can display seven different sets of information; thus, there are actually seven navigators. These are represented by the seven icons across its top; to switch among them, use these icons or their keyboard shortcuts (Command-1, Command-2, and so on). You will quickly become adept at switching to the navigator you want; their keyboard shortcuts will become second nature. If the Navigator pane is hidden, pressing a navigator’s keyboard shortcut both shows the Navigator pane and switches to that navigator.
Depending on your settings in the behaviors pane of Xcode’s preferences, a navigator might show itself automatically when you perform a certain action. For example, by default, when you build your project, if warning messages or error messages are generated, the Issue navigator will appear. This automatic behavior will not prove troublesome, because it is generally precisely the behavior you want, and if it isn’t, you can change it; plus you can easily switch to a different navigator at any time.
The most important general use pattern for the Navigator pane is: you select something in the Navigator pane, and that thing is displayed in the main area of the project window. Let’s begin experimenting immediately with the various navigators:
Project navigator (Command-1)
Click here for basic navigation through the files that constitute your project. For example, in the Empty Window folder (these folder-like things in the Project navigator are actually called groups) click Empty_WindowAppDelegate.m to view its code (Figure 6-2).
At the top level of the Project navigator, with a blue Xcode icon, is the Empty Window project itself; click it to view the settings associated with your project and its targets. Don’t change anything here without knowing what you’re doing! I’ll talk later in this chapter about what these settings are for.
At the top level of the Project navigator, with a blue Xcode icon, is the Empty Window project itself; click it to view the settings associated with your project and its targets. Don’t change anything here without knowing what you’re doing! I’ll talk later in this chapter about what these settings are for.
Figure 6-2. The Project navigator
Symbol navigator (Command-2)
A symbol is a name, typically the name of a class or method. Depending on which of the three icons in the filter bar at the bottom of the Symbol navigator you highlight, you can view Cocoa’s built-in symbols or the symbols defined in your project. The former can be a useful form of documentation; the latter can be helpful for navigating your code. For example, highlight the first two icons in the in the filter bar (the first two are light-colored, the third is dark), and see how quickly you can reach the definition of the
Feel free to highlight the filter bar icons in various ways to see how the contents of the Symbol navigator change. Note too that you can type in the search field in the filter bar to limit what appears in the Symbol navigator; for example, try typing “active” in the search field, and see what happens.
applicationDidBecomeActive: method.Feel free to highlight the filter bar icons in various ways to see how the contents of the Symbol navigator change. Note too that you can type in the search field in the filter bar to limit what appears in the Symbol navigator; for example, try typing “active” in the search field, and see what happens.
Search navigator (Command-3)
This is a powerful search facility for finding text globally in your project, and even in the headers of Cocoa frameworks. You can also summon the Search navigator with Edit → Find → Find in Workspace (Shift-Command-F). To access the full set of options, click the magnifying glass and choose Show Find Options. For example, try searching for “delegate” (Figure 6-3). Click a search result to jump to it in your code.
Figure 6-3. The Search navigator
Issue navigator (Command-4)
You’ll need this navigator primarily when your code has issues. This doesn’t refer to emotional instability; it’s Xcode’s term for warning and error messages emitted when you build your project.
To see the Issue navigator in action, you’ll need to give your code an issue. For example, navigate (as you already know how to do, in at least three different ways) to the file Empty_WindowAppDelegate.m, and in the blank line after the last comment at the top of the file, above the
To see the Issue navigator in action, you’ll need to give your code an issue. For example, navigate (as you already know how to do, in at least three different ways) to the file Empty_WindowAppDelegate.m, and in the blank line after the last comment at the top of the file, above the
#import line, type howdy. Save (Command-S) and build (Command-B). The Issue navigator will display five error messages, showing that the compiler is totally unable to cope with this illegal word appearing in an illegal place. Click an issue to see it within its file. (Now that you’ve made Xcode miserable, select “howdy” and delete it; build again, and your issues will be gone. If only real life were this easy!)Debug navigator (Command-5)
By default, this navigator will appear when your code is paused while you’re debugging it. There is not a strong distinction in Xcode between running and debugging; the milieu is the same. (The difference is mostly a matter of whether breakpoints are obeyed.) However, if your code runs and doesn’t pause, the Debug navigator by default won’t come into play.
To see the Debug navigator in action, you’ll need to give your code a breakpoint. Navigate once more to the file Empty_WindowAppDelegate.m, select in the line that says
This overall layout (Figure 6-4) will rapidly become familiar as you debug your projects. The Navigator pane displays the call stack, with the names of the nested methods in which the pause occurs; as you would expect, you can click on a method name to navigate to it. You can shorten or lengthen the list with the slider at the bottom of the pane. The Debug pane, which can be shown or hidden at will (View → Hide/Show Debug Area, or Shift-Command-Y) consists of two subpanes, either of which can be hidden using the segmented control at the top right of the pane.
You can also use the console to communicate via text with the debugger. This can often be a better way to explore variable values during a pause than the variables list.
To see the Debug navigator in action, you’ll need to give your code a breakpoint. Navigate once more to the file Empty_WindowAppDelegate.m, select in the line that says
return YES, and choose Product → Debug → Add Breakpoint at Current Line to make a blue breakpoint arrow appear on that line. Run the project. (If the project is already running, the Stop dialog will appear; click Stop to terminate the current run and begin a new one.) By default, as the breakpoint is encountered, the Navigator pane switches to the Debug navigator, and the Debug pane appears at the bottom of the window.This overall layout (Figure 6-4) will rapidly become familiar as you debug your projects. The Navigator pane displays the call stack, with the names of the nested methods in which the pause occurs; as you would expect, you can click on a method name to navigate to it. You can shorten or lengthen the list with the slider at the bottom of the pane. The Debug pane, which can be shown or hidden at will (View → Hide/Show Debug Area, or Shift-Command-Y) consists of two subpanes, either of which can be hidden using the segmented control at the top right of the pane.
- On the left, the variables list is populated with the variables in scope for the selected method in the call stack (and you can optionally display processor registers as well).
- On the right is the console, where the debugger displays text messages; that’s how you learn of exceptions thrown by your running app. Exceptions are extremely important to know about, and this is your only way to know about them, so keep an eye on the console as your app runs.
You can also use the console to communicate via text with the debugger. This can often be a better way to explore variable values during a pause than the variables list.
Figure 6-4. The Debug layout
Breakpoint navigator (Command-6)
This navigator lists all your breakpoints. At the moment you’ve only one, but when you’re actively debugging a large project, you’ll be glad of this navigator. Also, this is where you create special breakpoints (such as symbolic breakpoints), and in general it’s your center for managing existing breakpoints.
Log navigator (Command-7)
This navigator lists your recent major actions, such as building or running (debugging) your project. Click on a listing to see the log file generated when you performed that action. The log file might contain information that isn’t displayed in any other way, and also it lets you dredge up messages from the recent past (“What was that exception I got while debugging a moment ago?”).
For example, by clicking on the listing for a successful build, and by choosing to display All and All Messages using the filter switches at the top of the log, we can see the steps by which a build takes place (Figure 6-5). To reveal the full text of a step, click on that step and then click the Expand Transcript button that appears at the far right (and see also the menu items in the Editor menu).
For example, by clicking on the listing for a successful build, and by choosing to display All and All Messages using the filter switches at the top of the log, we can see the steps by which a build takes place (Figure 6-5). To reveal the full text of a step, click on that step and then click the Expand Transcript button that appears at the far right (and see also the menu items in the Editor menu).
Figure 6-5. Viewing a log
When navigating by clicking in the Navigator pane, modifications to your click can determine where navigation takes place. For the settings that govern these click modifications, see the General pane of Xcode’s preferences. For example, if you haven’t changed the original settings, Option-click navigates in an assistant pane (discussed later in this chapter), and double-click navigates by opening a new window.
The Utilities Pane
The Utilities pane, the column at the right of the project window, consists partly of inspectors that provide information about, and in some cases let you change the specifications of, the current selection, and partly of libraries that function as a source of objects you may need while editing your project. Its importance emerges mostly when you’re working in the nib editor, and you’ll probably keep it hidden the rest of the time. But if you have sufficient screen real estate, you might like to keep it open while editing code, because Quick Help, a form of documentation, is displayed here as well; plus, the Utilities pane is the source of code snippets. To toggle the visibility of the Utilities pane, choose View → Utilities → Hide/Show Utilities (Command-Option-0). You can change the Utilities pane’s width by dragging the vertical line at its left edge.
Many individual inspectors and libraries are discussed in subsequent chapters. Here, I’ll just describe the overall physical characteristics of the Utilities pane.
The Utilities pane consists of a set of palettes. Actually, there are so many of these palettes that they are clumped into multiple sets, divided into two major groups: the top half of the pane and the bottom half of the pane. You can change the relative heights of these two halves by dragging the horizontal line that separates them.
The top half
What appears in the top half of the Utilities pane depends on what’s selected in the current editor. There are two main cases:
A code file is being edited
A nib file is being edited
A code file is being edited
The top half of the Utilities pane shows either the File inspector or Quick Help. Toggle between them with the icons at the top of this half of the Utilities pane, or with their keyboard shortcuts (Command-Option-1, Command-Option-2). The File inspector is rarely needed, but Quick Help can be useful as documentation. The File inspector consists of multiple sections, each of which can be expanded or collapsed by clicking its header.
A nib file is being edited
The top half of the Utilities pane shows, in addition to the File inspector and Quick Help, the Identity inspector (Command-Option-3), the Attributes inspector (Command-Option-4), the Size inspector (Command-Option-5), and the Connections inspector (Command-Option-6). Like the File inspector, these can consist of multiple sections, each of which can be expanded or collapsed by clicking its header.
The bottom half
The bottom half of the Utilities pane shows one of four libraries. Toggle between them with the icons at the top of this half of the Utilities pane, or with their keyboard shortcuts. They are the File Template library (Command-Option-Control-1), the Code Snippet library (Command-Option-Control-2), the Object library (Command-Option-Control-3), and the Media library (Command-Option-Control-4). The Object library is the most important; you’ll use it heavily when editing a nib.
To see a help pop-up describing the currently selected item in a library, press Spacebar.
To see a help pop-up describing the currently selected item in a library, press Spacebar.
The Editor
In the middle of the project window is the editor. This is where you get actual work done, reading and writing your code, or designing your interface in a nib file. The editor is the core of the project window. You can eliminate the Navigator pane, the Utilities pane, and the Debug pane, but there is no such thing as a project window without an editor (though you can cover the editor completely with the Debug pane).
The editor provides its own form of navigation, the jump bar across the top. I’ll talk more later about the jump bar, but for now, observe that not only does it show you hierarchically what file is currently being edited, but also it allows you to switch to a different file. In particular, each path component in the jump bar is also a pop-up menu. These pop-up menus can be summoned by clicking on a path component, or by using keyboard shortcuts (shown in the second section of the View → Editor submenu). For example, Control-4 summons a hierarchical pop-up menu, which can be navigated entirely with the keyboard, allowing you to choose a different file in your project to edit. Thus you can navigate your project even if the Project navigator isn’t showing.
It is extremely likely, as you develop a project, that you’ll want to edit more than one file simultaneously, or obtain multiple views of a single file so that you can edit two areas of it simultaneously. This can be achieved in three ways: assistants, tabs, and secondary windows.
Assistants
You can split the editor into multiple editors by summoning an assistant pane. To do so, click the second button in the Editor segmented control in the toolbar, or choose View → Editor → Assistant (Command-Option-Return). Also, by default, adding the Option key to navigation opens an assistant pane; for example, Option-click in the Navigator pane, or Option-choose in the jump bar, to navigate by opening an assistant pane (or to navigate in an existing assistant pane if there is one). To remove the assistant pane, click the first button in the Editor segmented control in the toolbar, or choose View → Editor → Standard (Command-Return).
Your first task will be to decide how you want multiple editor panes arranged with respect to one another. To do so, choose from the View → Assistant Layout submenu. I usually prefer All Editors Stacked Vertically, but it’s purely a matter of personal taste and convenience.
Once you’ve summoned an assistant pane, you can split it further into additional assistant panes. To do so, click the “+” button at the top right of an assistant pane. To dismiss a secondary assistant pane, click the “x” button at its top right. Note, however, that clicking the “x” button at the top right does not work to dismiss the last remaining assistant pane; you have to switch to Standard view (View → Editor → Standard or Command-Return).
An assistant pane is not merely split-pane editing; an assistant pane can bear a special relationship to the primary editor pane. The primary editor pane is the one whose contents, by default, are determined by what you click on in the Navigator pane; an assistant pane, meanwhile, can respond to what file is being edited in the primary editor pane by changing intelligently what file it (the assistant pane) is editing. This is called tracking.
To see tracking in action, open a single assistant pane and set the first component in its jump bar to Counterparts (Figure 6-6). Now use the Project navigator to select Empty_WindowAppDelegate.m; the primary editor pane displays this file, and the assistant automatically displays Empty_WindowAppDelegate.h. Next, use the Project navigator to select Empty_WindowAppDelegate.h; the primary editor pane displays this file, and the assistant automatically displays Empty_WindowAppDelegate.m. There’s a lot of convenience and power lurking here, which you’ll explore as you need it.
Your first task will be to decide how you want multiple editor panes arranged with respect to one another. To do so, choose from the View → Assistant Layout submenu. I usually prefer All Editors Stacked Vertically, but it’s purely a matter of personal taste and convenience.
Once you’ve summoned an assistant pane, you can split it further into additional assistant panes. To do so, click the “+” button at the top right of an assistant pane. To dismiss a secondary assistant pane, click the “x” button at its top right. Note, however, that clicking the “x” button at the top right does not work to dismiss the last remaining assistant pane; you have to switch to Standard view (View → Editor → Standard or Command-Return).
An assistant pane is not merely split-pane editing; an assistant pane can bear a special relationship to the primary editor pane. The primary editor pane is the one whose contents, by default, are determined by what you click on in the Navigator pane; an assistant pane, meanwhile, can respond to what file is being edited in the primary editor pane by changing intelligently what file it (the assistant pane) is editing. This is called tracking.
To see tracking in action, open a single assistant pane and set the first component in its jump bar to Counterparts (Figure 6-6). Now use the Project navigator to select Empty_WindowAppDelegate.m; the primary editor pane displays this file, and the assistant automatically displays Empty_WindowAppDelegate.h. Next, use the Project navigator to select Empty_WindowAppDelegate.h; the primary editor pane displays this file, and the assistant automatically displays Empty_WindowAppDelegate.m. There’s a lot of convenience and power lurking here, which you’ll explore as you need it.
Figure 6-6. Telling an assistant pane to display counterparts
Tabs
You can embody the entire project window interface as a tab. To do so, choose File → New → New Tab (Command -T), revealing the tab bar (just below the toolbar) if it wasn’t showing already. Use of a tabbed interface will likely be familiar from applications such as Safari. You can switch between tabs by clicking on a tab, or with Command-Shift-}. At first, your new tab will look identical to the original window from which it was spawned. But now you can make changes in a tab — change what panes are showing or what file is being edited, for example — without affecting any other tabs. Thus you can get multiple views of your project.
Secondary windows
A secondary project window is similar to a tab, but it appears as a separate window instead of a tab in the same window. To create one, choose File → New → New Window (Command-Shift-T). Alternatively, you can promote a tab to be a window by dragging it right out of its current window. Yet another way to make a secondary project window is to choose Navigate → Open In and navigate left in the resulting dialog until the dialog offers to make a new window.
There isn’t a strong difference between a tab and a secondary window; which you use, and for what, will be a matter of taste and convenience. I find that the advantage of a secondary window is that you can see it at the same time as the main window, and that it can be small. Thus, when I have a file I frequently want to refer to, I often spawn into a secondary window an editor displaying that file, making it fairly small and without any additional panes.
Learn more about this topic from Programming iOS 4.
Get a solid grounding in all the fundamentals of Cocoa Touch, and avoid problems during iPhone and iPad app development. With Programming iOS 4, you'll dig into Cocoa and learn how to work effectively with Objective-C and Xcode. This book covers iOS 4 in a rigorous, orderly fashion—ideal whether you’re approaching iOS for the first time or need a reference to bolster existing skills.
