104 ❘ CHAPTER 6 EDITING TEXT open project contains a source fi le item that refers to the fi le being opened, the character encoding recorded in that source item is used. NAVIGATION WITHIN A FILE You ’ ll probably spend more time moving around in your source code than you ’ ll spend writing it. Programming just isn ’ t a linear activity. One rarely sits down and types out a function of any consequence from start to fi nish. Knowing how to move around your source code quickly and decisively will greatly enhance your effi cacy. Cursor Movement Start with just moving around in a single source fi le. The following table lists the key combinations that simply move the cursor around in the text. All of the key combinations in this chapter are based on the key binding set named “ Xcode Defaults. ” This is the default set when Xcode is installed. Key bindings — the mapping of key combinations to actions — are extremely fl exible and can be customized extensively. Xcode includes key binding sets that approximate the key combinations used in BBEdit, Metrowerks ’ CodeWarrior, and the venerable MPW system. You are also free to devise your own key binding sets. See Chapter 23 for a complete description of key bindings and how to alter them. If you have changed the key bindings in the Xcode Preferences, you may want to set them back to the Xcode Default set while working through this chapter. KEY COMBINATION CURSOR MOVEMENT Right arrow, Control + F Next character Command + right arrow, Control+ E End of line Option + right arrow End of next word Control + right arrow End of next subword Left arrow, Control + B Previous character Command + left arrow, Control + A Beginning of line Option + left arrow Beginning of previous word Control + left arrow Beginning of previous subword Up arrow, Control + P One line up Command + up arrow Beginning of document c06.indd 104c06.indd 104 1/22/10 12:19:50 PM1/22/10 12:19:50 PM Download at getcoolebook.com KEY COMBINATION CURSOR MOVEMENT Option + up arrow Previous beginning of line Down arrow, Control + N One line down Command + down arrow End of document Option + down arrow Next end of line Option + Page Up One page up Option + Page Down One page down Memorize this table or earmark this page in the book. It will save you an immense amount of time navigating your source code. The most important thing to remember is that the amount of cursor movement increases depending on the modifi er key used with the left or right arrow keys, as shown in Figure 6 - 16. These are, in increasing order or magnitude: none, Control, Option, and Command. FIGURE 6-16 A word in Xcode is a run of letters, numbers, or the underscore character. A subword is a capital letter followed by a run of lowercase letters, a run of numbers, a run of uppercase letters, or a run of underscore characters between subwords. Leading and trailing underscore characters do not count as subwords. Emacs You may have noticed a few odd synonyms for some of the cursor movements, like Control + P to move up one line, or Control + E to move to the end of the line. Xcode key bindings emulate a number of the standard Emacs editor commands. If you ’ re used to using Emacs, you will want to explore the key bindings in the Xcode Preferences to see what Emacs control sequences are supported. This book doesn ’ t go into all of the Emacs commands that are supported by Xcode, but the following table provides a couple of examples. KEY COMBINATION ACTION Control + Space Sets the mark from the current position Control + X Control + X Swaps the current position with the mark Navigation Within a File ❘ 105 c06.indd 105c06.indd 105 1/22/10 12:19:55 PM1/22/10 12:19:55 PM Download at getcoolebook.com 106 ❘ CHAPTER 6 EDITING TEXT Emacs maintains the concept of a “ mark, ” which is simply a saved location in the fi le, much like a bookmark. You can set the mark by pressing Control + spacebar. You can also “ swap ” the mark with the current cursor position or selection by pressing Control + X Control + X (that ’ s Control + X twice in a row). The current cursor position or selection becomes the new mark, and the cursor position or selection is moved to the previous mark. This can be very handy when copying and pasting between two different sections of the same fi le. Scrolling Besides the scrollbar controls, key combinations also exist that scroll the text without changing the current cursor position or selection, as listed in the following table. KEY COMBINATION SCROLL MOVEMENT Page Up, Control + up arrow One page up Page Down, Control + down arrow One page down Home To beginning of document Command + Home One line up End To end of document Command + End One line down Command + J Jump to Selection These can often result in scrolling the text so that the current cursor position is no longer visible. Every cursor movement includes an implied request to scroll the window so that the new cursor position is visible. To scroll the window so that the current cursor or selection is visible again, use the Edit ➪ Find ➪ Jump to Selection (Command + J) command. Jumping to Functions, Breakpoints, and Bookmarks The navigation bar provides several tools for navigating to locations within the current fi le, as shown in Figure 6 - 13. All of these controls are drop - down menus. Select an item in the menu and the cursor moves immediately to that location in the fi le. Keyboard shortcuts also exist for these menus, as listed in the following table. Using one of the shortcuts drops the menu down. You can then navigate the menu with the up and down arrows or by typing the fi rst few letters of the desired item. Press Return when the desired item is highlighted. Press Esc to dismiss the menu. c06.indd 106c06.indd 106 1/22/10 12:20:04 PM1/22/10 12:20:04 PM Download at getcoolebook.com KEYBOARD SHORTCUT NAVIGATION MENU Control + 1, Control + Option + 1 File History Control + 2, Control + Option + 2 Functions Control + 3 Class Hierarchy Control + 4 Bookmarks Control + 5 Breakpoints Control + 6 Included Files The File History, Class Hierarchy, and Included Files menus are described a little later in the “ Jumping to Other Files ” section. The remaining menus navigate within the current fi le. Functions The Functions menu, shown in Figure 6 - 17, parses the defi nitions in the source fi le and dynamically builds a list of functions, classes, methods, types, defi nes, and markers. This is one of the syntax - aware editing features of Xcode and only works when you ’ re editing fi le types that Xcode recognizes as being program source fi les. FIGURE 6-17 The menu includes an item for each of the following that Xcode discovers in your source code: A class, method, or function (declaration or defi nition) A type ( typedef ) declaration #define directives ➤ ➤ ➤ Navigation Within a File ❘ 107 c06.indd 107c06.indd 107 1/22/10 12:20:05 PM1/22/10 12:20:05 PM Download at getcoolebook.com 108 ❘ CHAPTER 6 EDITING TEXT #pragma mark directives Any comment that contains the (case - sensitive) text: MARK: TODO: FIXME: !!!: ???: Normally, the menu is in the order that the declarations appear in the fi le. Hold down the Option key when clicking the menu or using the keyboard shortcut to sort the items in alphabetical order. Method names in Java and Objective - C classes are sorted as though their names were fully qualifi ed (for example, MyReader::isEOF ), so all of the methods for a class cluster together in the list, subsorted by method name. You can choose to switch the default order by setting the Sort List Alphabetically option in the Code Sense pane of the Xcode Preferences. When this option is set, the list is sorted alphabetically by default and in fi le order when the Option key is used. Declarations are italicized in the menu. Declarations can be excluded by turning off the Show Declarations option in the Code Sense pane of the Xcode Preferences. The most fl exible means of adding arbitrary entries to the Functions menu is to insert a #pragma mark directive to your source code, as shown in Figure 6 - 17. The statement #pragma mark - adds a menu divider. Finally, the Functions menu acts as a location indicator. Whenever the cursor or selection is in a defi nition or the body of a class, function, or method, the menu indicates the name of the current location. When the menu is popped open, the current location is indicated with a check mark. If the cursor position is not within any defi nition, the message “ < No Selected Symbol > ” is displayed. Bookmarks The Bookmarks menu lists all of the bookmarks set in the fi le. It does not list bookmarks set in other fi les. Use the Bookmarks window or the Bookmarks smart group in the project window to see those. Bookmarks are always listed in the order they appear in the fi le. To set a bookmark, position the cursor or make a selection and choose the Edit ➪ Add to Bookmarks (Command + D) command or Right/Control + click a text selection and choose Add to Bookmarks. This presents a bookmark name dialog sheet. The default name of a new bookmark will be its location in the fi le, which you can change if you want something more descriptive. Bookmarks are stored in the project document; you can only set bookmarks in fi les that are assets of an open project. Breakpoints The Breakpoints menu jumps to any breakpoints set in the fi le. Each breakpoint is displayed as the function or method name containing the breakpoint plus a line number. ➤ ➤ ➤ ➤ ➤ ➤ ➤ c06.indd 108c06.indd 108 1/22/10 12:20:14 PM1/22/10 12:20:14 PM Download at getcoolebook.com Jumping to Other Files Just as important as being able to move around quickly within a fi le is the ability to move quickly between fi les. You ’ ve already seen how to open and browse fi les from the project window, but Xcode provides a variety of other ways to switch directly from one fi le to another. MOST PRODUCTIVE SHORTCUTS Before I get into some of the more mundane ways of navigating between fi les, let me point out probably the two most useful shortcuts in Xcode: SHORTCUT COMMAND EFFECT Command + double - click Edit ➪ Find ➪ Jump to Defi nition Quickly jumps to the source code where the symbol is defi ned. Option + double - click Help ➪ Quick Help Opens the symbol ’ s documentation in a Quick Help window. The double - click action selects the word or symbol at your cursor location, so these shortcuts perform two actions simultaneously: select the symbol and jump to its defi nition or documentation. These shortcuts are described in this and the help chapters, but they ’ re so useful that I encourage you to take a moment to memorize them now. File History The File History menu in the navigation bar maintains a list of the fi les that have been displayed in that editor pane, as shown in Figure 6 - 18. Select a fi le from the list and the pane switches to that fi le. The keyboard shortcut for the File History menu is Control + 1. FIGURE 6-18 Navigation Within a File ❘ 109 c06.indd 109c06.indd 109 1/22/10 12:20:14 PM1/22/10 12:20:14 PM Download at getcoolebook.com 110 ❘ CHAPTER 6 EDITING TEXT File history is maintained individually for each editor pane. Even multiple panes within the same window have their own history. For the editor pane in the project window, or when you ’ re using the Grouped window mode, this can be quite a long list. For separate editor windows, it tends to be just the fi le that is being edited. All new panes have an empty history, and closing a pane discards the history for that pane. The only exception is when Xcode saves the state of a window in the project document. It always does this for the project window, and it saves the state of other open windows if the Save Window State option in the General preferences is set. Thus, the history of the project window ’ s editor pane is always preserved and so is, possibly, the state of all open editor windows. To limit (or not) how much fi le history is retained, the File History menu has two special items, as previously shown in Figure 6 - 18. The Clear File History item does just that. It forgets all previously visited fi les except the current one. The History Capacity item sets the limit for the number of fi les in the list. The capacity defaults to Unlimited. For most editor panes, this isn ’ t an issue because they rarely get past two. For editor panes, like those in the project window that are constantly being reused, you may want to limit the size of the history, or the list may become unwieldy. Like the fi le history itself, this setting is stored separately for each editor pane and is saved in the window ’ s state. The two arrow buttons to the left of the File History menu move through the history list, like the previous and next buttons in a browser. The File History menu lists each fi le in alphabetical order, but the history buttons are really a browser - like history of the locations that have been visited, in the order that they were visited. Clicking the Previous button takes you to the location previously visited, not the fi le above the current one in the menu. It is unlike the File History menu in two other respects: it remembers your location within each fi le, not just fi les. This appears as a fi lename and line number, such as “ main.c:27. ” A fi le and location may occur more than once. The history and the menu are both limited to the number of items set in the History Capacity menu. Aggregate History Hold down the Option key when popping up the File History menu to see the aggregate fi le history. The aggregate fi le history is a combined list of the history items from every open window. Be careful about using the feature too liberally with multiple projects open, because the list will include fi les from all of your projects. You can easily open the project window for project A and switch to a source fi le that belongs to project B. Adding an Arbitrary File to the History Xcode windowing options tend either to open all fi les in a single editor pane, or every fi le in a separate window. Consequently, the fi le history consists of every fi le you ’ ve ever visited or just the fi le opened in that window. There are some times when you ’ d like to work with a select number of fi les in a single, separate, editor window. You have three ways of accomplishing this. The fi rst method is to use the Group window, described in the “ Using a Group Editor Window ” section earlier. This directs all new fi les to the same window. Use the File History menu to switch between all of the fi les that have occupied that window. The second method is to use the aggregate fi le history to switch to a fi le that has been visited in some other editor pane. Once the fi le is brought into the current window, it becomes part of its history. This is the simplest way of adopting a fi le that is, or has been, opened elsewhere. c06.indd 110c06.indd 110 1/22/10 12:20:16 PM1/22/10 12:20:16 PM Download at getcoolebook.com The last method is to drag a fi le and drop it directly into the navigation bar, as shown in Figure 6 - 19. This switches the editor pane to that fi le and adds it to its history. FIGURE 6-19 The source of the drag can be a source item in the project window, a fi le from the Finder, or the fi le icon in the title bar of a document window. This technique can only be used to add one fi le at a time. Included Files The Included Files menu is another syntax - aware feature for C and C - like language fi les. Each #include or #import directive that it fi nds is listed in the top portion of the menu, as shown in Figure 6 - 20. Selecting an item from the list jumps to that fi le. The keyboard shortcut is Control + 6. FIGURE 6-20 When used in a header fi le, the Included Files menu also lists the fi les that include this fi le at the bottom of the menu. In Figure 6 - 20, the current fi le, MyViewController.h , includes one header fi le, UIKit.h , and is included by two other fi les in the project, AppDelegate.m and MyViewController.m . Navigation Within a File ❘ 111 c06.indd 111c06.indd 111 1/22/10 12:20:24 PM1/22/10 12:20:24 PM Download at getcoolebook.com 112 ❘ CHAPTER 6 EDITING TEXT Switching Between a Header and its Source File The convention for C, C + + , and Objective - C languages is to place the declarations for functions and data types in a header fi le with an .h or .hpp fi lename extension, and write the implementation of those functions in a source fi le of the same name. If you use this convention, Xcode lets you quickly jump back and forth between the two using the View ➪ Switch to Header/Source File (Option + Command + ↑) command, or click the Counterpart button in the navigation bar. Your editor focus switches immediately to the companion header or source fi le. Whether the counterpart fi le opens in a new editing window depends on your layout style and the setting of the Open Counterparts in Same Editor option in the General pane of the Xcode preferences. Jumping to a Defi nition As mentioned earlier in this section, one of the most useful navigation tools in Xcode is the Edit ➪ Find ➪ Jump to Defi nition command. This command doesn ’ t have a keyboard combination. To access it quickly, double - click a word in a source fi le while holding down the Command key. Jump to Defi nition uses the syntax - aware symbols table to index all of the class, function, type, and constant names that are defi ned in your project. Command + double - clicking a word, or selecting a symbol name and choosing Edit ➪ Find ➪ Jump to Defi nition, immediately jumps to the implementation of that function or method, or to the defi nition of that class, type, or constant. If the current selection is the function or method implementation, it jumps to the declaration of that function or method. If there are multiple symbols with the same name, or if you choose a class name with multiple implementations, Xcode pops up a list of the possible matches, as shown in Figure 6 - 21. Select the desired symbol and the editor jumps there. FIGURE 6-21 Code Sense indexing must be enabled for this feature to work. See the “ Code Sense ” section in Chapter 7. c06.indd 112c06.indd 112 1/22/10 12:20:25 PM1/22/10 12:20:25 PM Download at getcoolebook.com EDITING All of the standard text selection and editing features supplied by the operating system ’ s text editing framework work in Xcode. If you need a refresher on the basics, refer to the Mac OS X Help. The following sections highlight a few obscure features that are particularly useful when editing source code. In addition, Xcode adds its own set of features and commands. Selecting Text All of the standard text selection gestures work in Xcode. Click and drag to select some text. Hold down the Shift key to extend a selection. Selecting text by dragging is dependent on timing; see the “ Drag and Drop ” section later for an explanation. The standard Mac OS X text editor is sensitive to word boundaries when extending text selections. It ’ s an obscure quirk that most people don ’ t notice, but may impact your coding. When you Shift - click to extend a selection, Xcode examines the other end of the selection (the end not being moved). If that end lies on a word boundary, the end being extended snaps to word boundaries. If the stationary end is in the middle of a word or between non - word characters, the extended end can be positioned at any character. This makes it very quick and easy to extend a selection to include additional words or symbols, because you don ’ t have to select the edge of the word; dragging anywhere into the word will suffi ce. If you start with a selection on a word boundary, and want to extend it to a non - word boundary, extend the selection using the keyboard (Shift + right arrow or Shift + left arrow) instead. This might be a good time to review the cursor movement modifi ers back in the “ Cursor Movement ” section. Selecting Columns One of the more obscure features of the editor is the ability to select columns of text. You can select all of the characters between two column positions across multiple lines by holding down the Option key and dragging out a selection. Figure 6 - 22 shows a column selection. Hold down the Shift and Option keys to extend or contract an existing column selection. Editing ❘ 113 c06.indd 113c06.indd 113 1/22/10 12:20:28 PM1/22/10 12:20:28 PM Download at getcoolebook.com . emulate a number of the standard Emacs editor commands. If you ’ re used to using Emacs, you will want to explore the key bindings in the Xcode Preferences to see what Emacs control sequences are supported the project window to see those. Bookmarks are always listed in the order they appear in the fi le. To set a bookmark, position the cursor or make a selection and choose the Edit ➪ Add to Bookmarks. Counterparts in Same Editor option in the General pane of the Xcode preferences. Jumping to a Defi nition As mentioned earlier in this section, one of the most useful navigation tools in Xcode