94 ❘ CHAPTER 6 EDITING TEXT Some actions cause the Save All window to appear automatically. Closing a project forces you to save or abandon the changes made in all unsaved project fi les. You can confi gure the Build commands in the Xcode Preferences to automatically save all unsaved fi les or prompt you for which ones to save before building. THE EDITOR PANE It ’ s now time to take a detailed look at the Xcode editor pane, shown in Figure 6 - 9. The editor pane has a number of controls and features. In the center, naturally, is the editor with the content of the fi le being edited. Across the top edge is the navigation bar, the various functions of which are explained later in the “ Navigating Within a File ” section. Along the right edge are the scrollbars and split pane controls. On the left edge is the gutter and ribbon, explained later in the “ Gutter ” section. The line running down the right side of the main editing region is the page guide. Depending on your display preferences and the kind of fi le being edited, some of these features may not be visible. See the “ Display Options ” section to fi nd out how to enable or disable them. FIGURE 6-8 The File ➪ Save (Command+S) command immediately writes the changes made in the active editor pane to the fi le. The File ➪ Save All (Option+Command+S) command presents a dialog box, like the one in Figure 6 - 8, that lists all of the unsaved fi les. Select the fi les to save and click the Save All/ Selected button. c06.indd 94c06.indd 94 1/22/10 12:19:14 PM1/22/10 12:19:14 PM Download at getcoolebook.com The active pane always has a blinking text cursor or a shaded text selection. You might get the idea that the text insertion cursor and the current text selection mentioned throughout this book are separate concepts. In reality, they are usually equivalent. The blinking text cursor is logically a text selection of zero characters. Both indicate the current location in the fi le. At times the behavior of a command is different when the selection is empty (when the text cursor is visible), but unless stated explicitly to the contrary, if you read one assume it applies equally to the other. Scrollbars The scrollbar controls are standard and shouldn ’ t surprise anyone who has used a modern graphical user interface. Xcode enhances their basic behavior with a few extras. Holding down the Option key when you click the arrow buttons scrolls the window slightly less than one screen ’ s worth of text. The editor is scroll - wheel aware, although a scroll - wheel is not an Xcode - specifi c feature. If your mouse, trackball, or trackpad has a scroll - wheel, the active editor pane will respond to it. I personally consider a multi - button trackball with a scroll - wheel an indispensable development tool. FIGURE 6-9 The Editor Pane ❘ 95 c06.indd 95c06.indd 95 1/22/10 12:19:14 PM1/22/10 12:19:14 PM Download at getcoolebook.com 96 ❘ CHAPTER 6 EDITING TEXT The gutter, described in more detail later, indicates compiler errors and warnings for the text that is visible in the window. Warnings and errors above or below the visible text are indicated as thin black (warning) or red (error) lines in the vertical scrollbar, as shown in Figure 6 - 9. This allows you to scroll quickly through the window to reveal other warnings or errors in the fi le. In your System Preferences, the Appearance pane has a Jump to the Spot That ’ s Clicked option. If selected, clicking in the empty part of the scrollbar jumps immediately to that point in the fi le. Though this is a system - wide preference change, it makes jumping to relative locations in source fi les particularly convenient. Split - Pane Editing Above the scrollbar is the split pane button. Clicking it splits that editor pane into two independent panes, one above the other, separated by a divider bar, as shown in Figure 6 - 10. FIGURE 610 You can achieve the same effect using the View ➪ Split fi lename Vertically command (Command + Shift + ” ), which splits the pane with the active text selection or cursor. Each new pane contains a split pane and a close pane button. The split pane button splits the pane again. The close pane button closes that pane; the adjacent pane assumes its space. c06.indd 96c06.indd 96 1/22/10 12:19:26 PM1/22/10 12:19:26 PM Download at getcoolebook.com Unlike the pane divider between the editor pane and the details list, the divider between editing panes does not respond to a double - click. However, it is possible to drag the divider all the way to one edge if you want to hide a pane from view. Drag it back out to the middle again, or close the visible pane, to reveal the hidden pane. The panes that result from a split are truly independent editing environments. The “ Jumping to Other Files ” section explains how to switch from one fi le to another in the same pane. You can do this with split panes, which allows you to edit two or more different fi les in a single editor window — very handy for editing a code fi le and its header in the same window. Notice back in Figure 6 - 11 that the right pane is displaying the MakePromiseViewController.m fi le and the left pane is editing its companion .h fi le. Gutter The gutter is the shaded bar running down the left edge of the editor pane. If it is not visible, enable it by selecting Show Gutter in the Text Editing pane of the Xcode Preferences. The gutter, shown in Figure 6 - 12, can display a variety of annotations. FIGURE 6-11 Holding down the Option key splits the pane horizontally, as shown in Figure 6 - 11. Choosing to split a pane horizontally or vertically only works for the fi rst pane. After a pane is split horizontally, all subsequent splits are horizontal regardless of whether you select a horizontal or vertical split. The same is true for vertical splits. (This is considered a bug by the Xcode development team and may be fi xed in a future version.) The Editor Pane ❘ 97 c06.indd 97c06.indd 97 1/22/10 12:19:35 PM1/22/10 12:19:35 PM Download at getcoolebook.com 98 ❘ CHAPTER 6 EDITING TEXT The gutter displays errors or warnings for a particular line, breakpoints, the current execution location of the debugger, and (optionally) line numbers. The display of line numbers is set in the Xcode Preferences. Warnings and errors are indicated by the yellow caution and red stop - sign symbols. Breakpoints show up as wide blue tabs. Active breakpoints are dark blue. Inactive ones are light grey. A large red arrow indicates where program execution is currently paused in the debugger. Clicking an error or warning icon in the gutter toggles its description in the text, enabling you to hide error descriptions selectively — which can be a bit distracting if you ’ re trying to fi x the problem. Clicking a breakpoint alternately enables or disables the breakpoint. You can set new breakpoints by clicking anywhere in the background of the gutter. Breakpoints can only be set in fi le types that Xcode recognizes as program source (C, C++, Objective - C, Java, AppleScript, and so on). You cannot set a breakpoint in XML or other types of non - program text fi les. You can relocate breakpoints to another line by dragging them there, or delete them by dragging them out of the gutter. Right/Control+click a breakpoint, or in the gutter, to add, remove, edit, or review breakpoints. Double - clicking a breakpoint opens the Breakpoints window. See Chapter 18 for more about breakpoints. Navigation Bar The navigation bar, shown in Figure 6 - 13, occupies the top edge of the editor pane and contains several status and navigation controls. You can hide the navigation bar of the active editor pane with the View ➪ Hide Navigation Bar command, and reveal it again with View ➪ Show Navigation Bar. FIGURE 6-12 FIGURE 6-13 c06.indd 98c06.indd 98 1/22/10 12:19:37 PM1/22/10 12:19:37 PM Download at getcoolebook.com The following table lists the functions of the navigation bar controls. CONTROL FUNCTION File History Jumps to a fi le that has been edited in this pane Functions Jumps to a function, defi nition, or marker in the fi le Bookmarks Jumps to a bookmark set in the fi le Breakpoints Jumps to a breakpoint set in the fi le Class Hierarchy Jumps to related class defi nitions Included Files Jumps to an included fi le, or a fi le that includes this fi le Counterpart Jumps to the counterpart of this fi le Lock Locks or unlocks the fi le The Lock button toggles the lock (read - only) attribute of the fi le. If you lock a fi le, or the fi le was locked when it was opened, the editor will be in display - only mode. If you attempt to change the document, Xcode warns you that you cannot edit the fi le. You can override this mode in the dialog box and make changes to the document, but that does not change the permissions of the fi le and you will not be able to save changes until the fi le is made writable. Unlocking a fi le automatically switches the editor to its normal editing mode. See the option Save Files As Writable in the “ Display Options ” section of this chapter. Numerous Xcode features rely on knowledge about your program ’ s symbols and source fi les obtained from the Code Sense index. This includes features like jumping to a symbol defi nition, the Class Hierarchy menu, Included Files menus, and auto - completion — just to name a few. By default, Code Sense is enabled for all projects so this shouldn ’ t present an obstacle, but if any of these features aren ’ t working, see the “ Code Sense ” section in Chapter 7. You may need to turn on Code Sense or reindex your project. All of the other navigation controls are explained in the “ Navigating Within a File ” section, later in this chapter. DISPLAY OPTIONS The appearance of an editor pane can be customized in a number of different ways and a variety of options determine how the text itself is interpreted and displayed. The following table lists the principal display options. Display Options ❘ 99 c06.indd 99c06.indd 99 1/22/10 12:19:38 PM1/22/10 12:19:38 PM Download at getcoolebook.com . and reveal it again with View ➪ Show Navigation Bar. FIGURE 6 -12 FIGURE 6- 13 c06.indd 98c06.indd 98 1/22/10 12: 19 :37 PM1/22/10 12: 19 :37 PM Download at getcoolebook.com The following table lists. considered a bug by the Xcode development team and may be fi xed in a future version.) The Editor Pane ❘ 97 c06.indd 97c06.indd 97 1/22/10 12: 19 :35 PM1/22/10 12: 19 :35 PM Download at getcoolebook.com 98. close pane button. The split pane button splits the pane again. The close pane button closes that pane; the adjacent pane assumes its space. c06.indd 96c06.indd 96 1/22/10 12: 19:26 PM1/22/10 12: 19:26