142 ❘ CHAPTER 7 SYNTAX-AWARE EDITING exit(3); // terminate immediately // returning a status of 3 When you use both comment formatting options, you should get in the habit of inserting a blank line before starting a new C/C + + - style comment on its own line. Otherwise, it may get indented to the level of the comment on the previous line. Re - indenting Text As mentioned earlier, re - indenting text uses the language - specifi c rules to determine the appropriate indentation level for each line. This can happen automatically as you type, depending on which syntax - aware indentation options you have enabled, or manually when you use Control + I or the Edit ➪ Format ➪ Re - indent command. It also happens whenever text is pasted from the clipboard. You can always manually alter the indentation level of a line, or lines, using the Edit ➪ Format ➪ Shift Right (Command + ]) and Edit ➪ Format ➪ Shift Left (Command + [) commands. These either increase or decrease the indentation of every line in the selection by indentation width. Lines that are already at the left margin cannot be decreased any further. This is just a manual adjustment of the amount of white space at the beginning of the line. A subsequent re - indent recalculates the appropriate indentation level based on the language rules, undoing any effect of Shift Right or Shift Left. CODE COMPLETION The most sophisticated feature of syntax - aware editing is Code Completion, Xcode ’ s auto - completion technology. Code completion analyzes the context of the code you are typing and interactively offers suggestions for completing the statement. Code completion supports the C, C + + , Objective - C, Objective - C + + , Java, and AppleScript languages. It works by assembling a list of symbol names from the Code Sense index that would be appropriate at that point in your code. If you are starting a new statement, the appropriate symbols will include any global variable, function, class name, or language keyword, but if you typed a class or structure name, the appropriate symbols would be only the member functions or instance variables in that class or structure. Figure 7 - 10 shows the available completions for the CGSize structure nested inside a CGRect structure. FIGURE 710 c07.indd 142c07.indd 142 1/22/10 12:24:37 PM1/22/10 12:24:37 PM Download at getcoolebook.com Code Completion ❘ 143 Code completion uses the context, scope, and type of variables found in the Code Sense index. Consequently, code completion is very accurate and is not easily fooled by namespace, scope, or preprocessor macros. Accepting Suggestions Code completion appears in two forms: suggestions and completion lists. Suggestions appear ahead of your typing, as shown in Figure 7 - 11. In this example I typed the text NSDic and code completion suggested the rest. The portion of grey text to the right of the insertion point is the suggestion. You can accept a suggestion by pressing the Tab key. To ignore a suggestion, just keep typing. The highlighted portion of the suggestion is what will be inserted if you press the Tab key. Xcode recognizes that many symbol names are very similar. In the code in Figure 7 - 11, you might want to type NSDictionary or NSDictionaryController. If you wanted NSDictionary, press Tab once (to accept the NSDictionary portion) and continue typing. If you wanted NSDictionaryController instead, start by pressing the Tab key once to accept the tionary suggestion. Code completion immediately returns with all of the suggestions that begin with NSDictionary, which include NSDictionaryController, as shown in Figure 7 - 12. Pressing Tab a second time accepts the Controller suggestion and the classname is complete. FIGURE 7-12 FIGURE 7-11 c07.indd 143c07.indd 143 1/22/10 12:24:37 PM1/22/10 12:24:37 PM Download at getcoolebook.com 144 ❘ CHAPTER 7 SYNTAX-AWARE EDITING This successive refi nement of suggestions permits you to narrow down your choice quickly from huge families of class and constant names that share common prefi xes. Symbol completion is case-insensitive and retroactively corrects the case of what you’ve already typed. In the example in Figure 7-11, I could have just as easily typed nsdic instead of NSDic. If I accepted Xcode’s suggestion of NSDictionary, the case of the letters I had already typed would have been changed to agree with the symbol. If I ignored the suggestion, the text would have reverted to its origi- nal lowercase form. Suggestion Display Settings The appearance of suggestions is controlled by the Automatically Suggest option in the Code Sense panel of the preferences, as was shown in Figure 7 - 1. The possible settings are: Never Immediately With Delay Never means suggestions never appear while you ’ re typing, but those suggestions and the completion lists are still available. Immediately and With Delay automatically present suggestions either all the time, or only after you ’ ve stopped typing for a moment. Suggestions never appear unless Xcode thinks it can make a reasonably accurate guess about what you ’ re typing. For example, thousands of symbols begin with NS in the Cocoa framework. Typing NS will not present any suggestions. Neither will typing NSFile — almost 100 symbols begin with NSFile . But typing NSFileW will suggest either NSFileWrite or NSFileWrapper , followed by the two dozen or so symbols that begin with those prefi xes. Getting Another Suggestion At any time — even when a suggestion isn ’ t being presented in your text — you can prompt Xcode to offer the next suggestion in its list of candidates by choosing Edit ➪ Next Completion (Control + .). This command inserts the next suggestion in the list, sort of on a trial basis, as shown in Figure 7 - 13. While a suggestion appears ahead of your insertion point in grey text, Next Completion inserts the suggestion but remembers what it inserted. ➤ ➤ ➤ FIGURE 7-13 c07.indd 144c07.indd 144 1/22/10 12:24:38 PM1/22/10 12:24:38 PM Download at getcoolebook.com Code Completion ❘ 145 If you like the suggestion, just keep typing — the suggestion is already part of your text. If you don ’ t, choose Edit ➪ Undo (Command + Z) or choose Next Completion again. Next Completion erases the previous suggestion and inserts the next one. You can do this repeatedly, cycling through every suggestion until you fi nd the one you want. Using Completion Lists Choose Edit ➪ Completion List (Esc) to see the entire list of possible completions. You can do this at any time; you don ’ t have to wait for Xcode to make a suggestion fi rst. The completion list menu shows every possible completion based on the context of your current insertion point. A completion list for an NSNotification object is shown in Figure 7 - 14. FIGURE 7-14 The list can be extensive. In this example, it includes every method of NSNotification , every method of its NSObject superclass, and every category of NSObject . The list can be navigated using the mouse or keyboard (up arrow, down arrow, home, end, page up, page down). You can also continue to type; the completion list will refi ne itself as you do. Press Tab or Return to accept the currently selected suggestion from the list, or Esc again to close the list. Code completion requires some practice. Don ’ t get discouraged at fi rst. Once you become used to the “ rhythm ” of suggestions and the keyboard shortcuts to accept, pick, and reject suggestions, coding even the longest symbol names becomes rapid and accurate. The typical technique is to use the completion list as a guide to what symbols exist. Type enough of the fi rst portion of the symbol you want, until the list becomes short enough to use the keyboard arrows to select the desired symbol from the list. Then press Tab or Return to insert the suggestion. c07.indd 145c07.indd 145 1/22/10 12:24:44 PM1/22/10 12:24:44 PM Download at getcoolebook.com 146 ❘ CHAPTER 7 SYNTAX-AWARE EDITING Completion Arguments When Xcode completes a function or method name, it inserts placeholders for its arguments, as shown in Figure 7 - 15. FIGURE 7-15 After the completion, the fi rst placeholder is selected automatically. To provide a value for the fi rst placeholder just begin typing — with code completion, of course. The special Edit ➪ Select Next Placeholder (Control + /) command fi nds the next placeholder in the fi le and selects it. To fi nish the method or function call, repeatedly replace the placeholders with the required arguments. You don ’ t have to replace them in any particular order, and you can leave placeholders in your code indefi nitely. The Show Arguments in Pop - Up List option of the Code Sense Preferences pane (see Figure 7 - 1) controls whether argument placeholders appear in suggestion or the completion list. C, C + + , and Java programmers should turn this option on. These languages use method overloading and without the argument placeholders it ’ s impossible to distinguish between multiple functions that differ only in their argument types. Objective - C programmers, on the other hand, will probably want to turn this off because Objective - C method names are unique and tend to be descriptive of their argument types. TEXT MACROS Text macros are another kind of auto - completion. These are text fragments that can be inserted whenever you need them. The text macros supplied by Xcode include a variety of common control structures and programming conventions, the kind that programmers tend to reuse repeatedly. This section discusses how to use text macros. Text macros are organized by language in the Edit ➪ Insert Text Macro menu. Select the desired macro, and its contents are inserted into the editor pane. When using the menu, you can choose any macro you want, but it really only makes sense to choose a macro that is appropriate to the language you ’ re writing in. Text macros can contain placeholders, just like code completions for methods and functions. They may also contain a special placeholder that is replaced by the current selection in the editor. For c07.indd 146c07.indd 146 1/22/10 12:24:49 PM1/22/10 12:24:49 PM Download at getcoolebook.com Text Macros ❘ 147 instance, on the left in Figure 7 - 16 the statement free(byteArray); is selected. After you select Edit ➪ Insert Text Macro ➪ C ➪ If Block, the text is replaced with the code on the right. If you don ’ t have anything selected, a statements placeholder is inserted instead. FIGURE 7-16 Like function arguments inserted by code completion, the fi rst placeholder in the macro is automatically selected. Use the same Select Next Placeholder (Control + /) command to jump to any additional placeholders. Code completion can also insert text macros. Each text macro has a name property. These names appear in the completion list alongside other top - level function and symbol names. The following table lists a few of the text macros — accessible via code completion — that will save you a lot of typing. CODE COMPLETION NAME INSERTS init Skeleton Objective - C - (id)init method dealloc Skeleton Objective - C - (void)dealloc method if/for/while/do/switch/case C control blocks @try Objective - C @try / @catch / @finally block Unlike the menu, only those macros appropriate to your fi le ’ s language appear. Selecting one inserts the entire text macro. Because you have to be typing the name of the macro to invoke code completion, you cannot simultaneously select text to replace the statements placeholder. If you want to use this feature, you have to invoke the macro by using the menu. Macros can have several variations. Inserting the C ➪ If Block macro inserts a simple conditional block guarded by a conditional. Without editing anything, select the macro from the menu again. The second time, the simple conditional block is replaced by a compound if / else statement with two blocks. The following code listing shows these two iterations. Some HTML macros have four or more variations for a single macro. c07.indd 147c07.indd 147 1/22/10 12:24:50 PM1/22/10 12:24:50 PM Download at getcoolebook.com 148 ❘ CHAPTER 7 SYNTAX-AWARE EDITING First Use of Edit ➪ Insert Text Macro ➪ C ➪ If Block int foo( int bar ) { if ( < #condition# > ) { < #statements# > } } Immediately Selecting Edit ➪ Insert Text Macro ➪ C ➪ If Block Again int foo( int bar ) { if ( < #condition# > ) { < #statements# > } else { < #statements# > } } When inserting macros from code completion, use the Edit ➪ Next Completion (Control + .) command to cycle through the variants of a text macro. The text < #statements# > in these listings appears as a single statements placeholder in the Xcode editor. If you save the fi le, it will contain the text “ < #statements# > ” where the placeholder is. If you add text to your fi le using this form (that is, < # name # > ), it won ’ t appear as a placeholder, but the Edit ➪ Next Completion command will jump to it like any other placeholder. EDITING SYMBOL NAMES The editor provides a small, eclectic set of shortcuts for fi nding and editing symbol names. These are referred to collectively as the “ Edit All in Scope ” feature, although that ’ s just one of its functions. This feature is enabled in the Code Sense pane (see Figure 7 - 1 again) of the preferences and can be set to Never, Immediate, or With Delay. When enabled, hovering your cursor over a symbol name that ’ s selected or is at the current insertion point presents a pop - up menu button, as shown in Figure 7 - 17. c07.indd 148c07.indd 148 1/22/10 12:24:52 PM1/22/10 12:24:52 PM Download at getcoolebook.com Clicking this button presents three commands. The Edit All in Scope command is a quick means of renaming all occurrences of that symbol within the block of code that contains it. To use it, choose Edit All in Scope and type a replacement name. The editor highlights all occurrences of the symbol so you can see what is about to be changed, and then simultaneously replaces all occurrences as you type. The results are shown in Figure 7 - 18. FIGURE 7-17 FIGURE 7-18 Alternatively, you can also select a symbol name and choose the Edit ➪ All In Scope (Control + Command + T) command. Use the command if you ’ re in a hurry or have set the Edit All in Scope setting to Never. The Find in Project command makes the current symbol the search text and opens the Find in Project window. Learn more about searching projects in Chapter 8. The Jump to Defi nition command is the same one described in the “ Jumping to a Defi nition ” section in Chapter 6. Editing Symbol Names ❘ 149 c07.indd 149c07.indd 149 1/22/10 12:24:57 PM1/22/10 12:24:57 PM Download at getcoolebook.com 150 ❘ CHAPTER 7 SYNTAX-AWARE EDITING SUMMARY Xcode ’ s editor provides powerful, language - specifi c tools that help you write code quickly and accurately. Code coloring and folding make visualizing the structure and meaning of your code much easier. Code completion helps you choose the right name in the right place, and text macros save you from many repetitive coding tasks. You probably won ’ t absorb all of Xcode ’ s editing features in a single day. As you use Xcode to edit fi les, revisit these two chapters from time to time to reacquaint yourself with some of the more esoteric features. Though the editor provides a number of navigation features that will jump to predetermined or saved locations, sometimes you just need to go looking for something, or replace occurrences of one thing with something else. The next chapter explains how. c07.indd 150c07.indd 150 1/22/10 12:24:59 PM1/22/10 12:24:59 PM Download at getcoolebook.com . using the menu, you can choose any macro you want, but it really only makes sense to choose a macro that is appropriate to the language you ’ re writing in. Text macros can contain placeholders,. argument types. TEXT MACROS Text macros are another kind of auto - completion. These are text fragments that can be inserted whenever you need them. The text macros supplied by Xcode include a variety. repeatedly. This section discusses how to use text macros. Text macros are organized by language in the Edit ➪ Insert Text Macro menu. Select the desired macro, and its contents are inserted into the