Lập trình Wrox Professional Xcode 3 cho Mac OS part 79 doc

646 ❘ CHAPTER 23 CUSTOMIZING XCODE 2. In the Text Key Bindings table, fi nd the Insert Tab action and double - click its current binding (usually the Tab key). 3. Hold down the Option key and press the Tab key. Click outside the fi eld to set it. 4. Click the OK button to adopt the new key bindings. Editing the text key bindings changes the key combinations that Xcode will use in all text editor panes. In steps 2 and 3, you replaced the key binding for the Insert Tab action — the action with the extra features — with Option+Tab. Because the Option+Tab was previously bound to Insert Tab Without Extra Action, Xcode warned you of the confl ict (see the bottom of Figure 23 - 4) and deleted that binding when you accepted the new one. Now the Tab key (alone) has no binding. Without a special key binding, the Tab key is treated like any other character. No special reformatting or navigation is attached to inserting a single tab character any more. Alternatively, you could have accomplished the same thing by binding the Tab key to the Insert Tab Without Extra Action action. Because the Tab key represents the tab character, both are equivalent. Key bindings are global, and both the menu key bindings and text key bindings share the same table. A key combination can only be assigned to a single menu command or editor action. Keep this in mind when you ’ re assigning non - Command key combinations to menu commands and vice versa. Key bindings are stored by name in your local ~/Library/Application Support/Xcode/Key Bindings folder as .pbxkeys fi les. You can exchange key binding fi les with other users. To install a key binding fi le, quit Xcode, copy a key bindings fi le into the Key Bindings folder, launch Xcode, and select the new set from the Key Bindings Sets pop - up menu. USING AN EXTERNAL EDITOR Is customizing the editor keystrokes and command shortcuts not enough? What if your favorite editing feature isn ’ t included in Xcode ’ s editors? What if Xcode doesn ’ t even have an editor for the kind of fi le you ’ ve added? Fear not; you can elect to use a third - party editor, instead of the built - in editors provided by Xcode, for some or all of your editing needs. Although Xcode ’ s editors are powerful, Xcode has a relatively limited feature set when editing certain types of source fi les, like XML and HTML. The ability to plug a dedicated HTML editor into Xcode adds a powerful new dimension to your development environment. Xcode has several different built - in editors. What you have been exposed to most in this book is the Source Code editor. There is also a Plain Text editor, an RTF (Rich Text File) editor, an XML Properties List editor, an Xcode Confi gurations Settings File editor, an AppleScript Dictionary editor, an Image editor, a Data Model editor, and a few others. The editor that is used when you open a fi le is determined by the settings in the File Types tab of the Xcode Preferences (see Chapter 6). Each fi le type that Xcode understands is associated with an editor. This can be one of the editors built into Xcode, an external application, or the decision can be deferred to the Finder. Using an Alternate Editor Once At any time, you can open a fi le using an alternate Xcode editor. Right/Control+click the source item and choose an editor from the Open As menu. The menu contains the list of Xcode ’ s internal c23.indd 646c23.indd 646 1/22/10 1:28:41 PM1/22/10 1:28:41 PM Download at getcoolebook.com editors that are capable of editing that type of fi le. This is particularly useful when you need to edit or examine a fi le in a less structured way. For example, open a property list fi le ( Info.plist ) using the Plain Text editor if you want to edit the raw XML. The Open With Finder command, found in the same menu, opens the fi le just as if you had opened the fi le in the Finder. For Xcode source fi les, it ’ s very likely that this will be Xcode itself. To force a fi le to open in another application, use the Reveal In Finder command to locate the fi le. Drag the fi le to an application in the dock or open it using the Finder ’ s Open With command. Alternatively, switch to the other application and use its File ➪ Open command or drag a source item directly from the project window into the editor ’ s dock icon. Specifying the Default Editor Changing an editor choice in the preferences changes the default editor for that fi le type for all projects. For each fi le type, there are essentially four possibilities: One of Xcode ’ s built - in editors A specifi c external editor The default application the document is associated with in the operating system The default for the super - type In Figure 23 - 5, the default editor for AIFF audio fi les is being changed from its default — open it using the Finder, which would most likely open iTunes — to launch the Sound Studio audio editing application. ➤ ➤ ➤ ➤ FIGURE 23 - 5 Using an External Editor ❘ 647 c23.indd 647c23.indd 647 1/22/10 1:28:41 PM1/22/10 1:28:41 PM Download at getcoolebook.com 648 ❘ CHAPTER 23 CUSTOMIZING XCODE The choice of Xcode editors is always limited to the editors that understand that fi le type. A text.html fi le can be edited using the Source Code editor or the Plain Text editor; the RTF editor does not understand HTML and is not a choice. The text.rtf fi le type can be set to use the RTF editor, the Source Code editor, or the Plain Text editor. File types are arranged in a hierarchy. When a type is set to Default, it defers the choice to its enclosing supertype. The top - level types have pre - programmed choices based on what editors are available for that type. In general, if you set the editor for a supertype and set a subtype to Default, the subtypes will use the editor of the supertype. In the example shown in Figure 23 - 5, the editor for the audio.aiff type is being set to Sound Studio. If the editor for the audio supertype had been set instead, all of the audio subtypes ( audio.mp3 , audio.au , audio.aiff , and so on) would open using Sound Studio. Using an External Editor When External Editor is specifi ed, Xcode tells that application to open the fi le instead of opening it in a separate window. The selection of an external editor does not affect single - pane operations, such as simply selecting a source fi le in the project window. The editor pane in the project window, the class browser, the Project Find window, and others will continue to use Xcode ’ s internal editor to immediately display a fi le in the same window. Only double - clicking a source item or using the Open in Separate Editor command opens the fi le in its external editor. External editors are not synchronized to the changes made in Xcode. Whenever Xcode is reactivated, it checks to see if any fi les were altered. Xcode cannot detect changes made in an external program before they are saved. Get in the habit of saving all of your changes before switching back to Xcode. If it detects changes, Xcode rereads the fi le and updates its display. In the unfortunate situation where changes have also been made in both the Xcode editor and the external application, the dialog box shown in Figure 23 - 6 is presented. You can choose to keep the changes made in Xcode, ignoring the changes that were written to disk, or vice versa. Xcode does not have a merge function and cannot combine the changes made in two places. If you have inadvertently made important changes in both places, use the Keep Xcode Version choice. Reopen the fi le in the external editor, and then copy and paste the changes made there to the editor pane in Xcode. Save the fi le within Xcode to commit the combined changes. Another approach is to use Xcode ’ s File ➪ Save a Copy As (Shift+Option+Command+S) command to make a new fi le of the Xcode version, then use a utility like FileMerge to compare and combine the changes. Because of the hazard of editing source fi les in both the external editor and Xcode, I recommend using the Condensed layout or leaving the editing pane in the project window collapsed. This reduces the temptation to make a quick edit in a fi le that might be opened elsewhere. FIGURE 23 - 6 c23.indd 648c23.indd 648 1/22/10 1:28:41 PM1/22/10 1:28:41 PM Download at getcoolebook.com Supported External Editors Xcode provides full support for BBEdit, Text Wrangler, SubEthaEdit, Emacs, xemacs, and Interface Builder. Only those installed on your system will appear in the menu of external editors. You can also select any other application, but Xcode will only provide limited support for it. Full support means that Xcode communicates with the external editor and tells it to save fi les when appropriate. For example, when you build a project, you can have Xcode tell your external editor to save all of the unsaved fi les before compiling, just as it does for internally edited fi les. Similarly, closing a project saves all fi les in an external editor. External editors with limited support means once the fi le is open, Xcode has no more interaction with the application. It is your responsibility to save and close the fi le in the editor as needed. External editors do not use the fi le and line encodings, tab, or indent settings of the source item. Some editors, like BBEdit, either automatically detect the format or store that information in the resource fork of the fi le. Use the external editor to change the encoding. Then change the settings in the project ’ s source item to match. TEXT MACROS In the “ Text Macros ” section of Chapter 6, you learned how to insert text macros using the Edit ➪ Insert Text Macro menu and via Code Sense. These macros can be great timesavers when using common programming idioms. If you regularly use the text macros, you may fi nd that you want to customize the macros provided by Xcode or invent your own. This is the fi rst of the non - sanctioned Xcode customizations. At one time, Apple supported user - created text macro fi les and appeared to be moving toward formally documenting them. Since then, Apple has retreated and now states that custom text macros are not (offi cially) supported. Nevertheless, creating your own isn ’ t diffi cult and all currently available versions of Xcode will honor user - defi ned text macros. Apple has made a recent concession to its “ not supported ” position. Xcode 3.2 has an XCCodeSenseFormattingOptions expert setting that allows you to override text macro values using your user defaults. The “ Expert Preferences ” section, later in this chapter, explains how to set Xcode ’ s user defaults. The “ Sanctioned Text Macro Customization ” section describes what text macro properties you can redefi ne. But fi rst, it helps if you understand how text macro defi nitions interact with one another. Creating Text Macro Defi nitions Adding or altering text macros is accomplished by defi ning your own text macro defi nitions. Defi nitions are written using a simple C - like structure syntax and stored in plain text fi les with an extension of .xctxtmacro . You can create new defi nitions, or replace any of the existing defi nitions that come bundled with Xcode. When Xcode starts, it assembles all of the text macro defi nitions by searching two locations: the Xcode application bundle and the /Developer/Library/Xcode/Specifications folder. Xcode no longer looks in your home folder ’ s ~/Library/Application Support/Xcode/Specifications Text Macros ❘ 649 c23.indd 649c23.indd 649 1/22/10 1:28:42 PM1/22/10 1:28:42 PM Download at getcoolebook.com 650 ❘ CHAPTER 23 CUSTOMIZING XCODE folder, so it ’ s no longer possible to install per - user custom text macros. Xcode scans both of the locations and reads every .xctxtmacro fi le that it fi nds. All of the .xctxtmacro fi les are read and digested before reading the fi les in the next location. If you ’ ve created a custom text macro fi le and your macros don ’ t appear in Xcode, check the Console application. Xcode will record problems parsing an .xctxtmacro fi le in the system log. Every defi nition contains an Identifier property. This property is the unique identifi er for each defi nition. Defi nitions with a duplicate Identifier completely replace any previously read defi nition; Xcode essentially ignores any previously read defi nition with the same Identifier . Thus, defi nitions defi ned in your custom fi les can selectively override any defi nition found in the Xcode bundle. Macro Defi nition An .xctxtmacro fi le consists of a comma - separated list of defi nition blocks. The entire list is surrounded by parentheses, with each defi nition block contained between curly braces. Thus, the high - level structure of an .xctxtmacro fi le is: ( { definition }, { definition }, … ) A defi nition is an arbitrary collection of properties written as key/value pairs using the syntax key = value ; . The value can be any text, a list, or another block of properties. A text value can be “ naked ” if it doesn ’ t contain any special characters (such as whitespace) that would confuse the parser. If it does, it can be surrounded by quotes like a literal C string. Quoted strings can use the backslash to escape special characters. Xcode defi nes a number of keys that have special meaning, some of which are required. You are free to add your own keys and use them as values in other defi nitions. The following shows an example defi nition: { Identifier = c.printf; BasedOn = c; IsMenuItem = YES; Name = "Printf() Call"; TextString = "printf(\" < #message# > \");"; CompletionPrefix = printf; } The .xctxtmacro fi le also supports C ( /* … */ ) and C++ ( // … ) style comments. c23.indd 650c23.indd 650 1/22/10 1:28:42 PM1/22/10 1:28:42 PM Download at getcoolebook.com Text Macro Properties Each defi nition block must include an Identifier key. This key is used both to uniquely identify each defi nition and to refer to it in other defi nitions. By convention, it should be a reverse domain name that mirrors the hierarchy of the defi nition — this will make more sense when I explain about inheritance — and it should not contain any special characters that would require it to be quoted. Each Identifier is unique and a defi nition with a duplicate Identifier value will completely suppress any previously defi ned defi nition with the same Identifier . The remaining properties of a defi nition shape its purpose. You can use any combination of properties you wish, but only certain combinations make any sense. To help you, the text macros built into Xcode contain a set of macros that expand to prototype defi nitions for new text macros — yes, they ’ re macro macros. You can fi nd these in the Edit ➪ Insert Text Macro ➪ Text Macro Specifi cations menu. The properties recognized by Xcode ’ s text macro interpreter are listed in the following table: MACRO PROPERTY DESCRIPTION Identifier This is the unique identifi er for the defi nition, and is a required property. The Identifier is not inherited. Name This is the descriptive name of the defi nition. For menu items, this is the name that will appear in the menu. When using Code Sense, the completion list will include this text as a description of the macro. The Name property is not inherited. BasedOn This property is the Identifier of the defi nition that this defi nition inherits. Most properties in the BasedOn defi nition are inherited; the exceptions are noted. IsMenu If set to YES, this defi nition creates a submenu in the Edit ➪ Insert Text Macro menu. The Name defi nes the title of the menu. Submenu items are not macros and are solely for organizing text macros into groups. The IsMenu property is not inherited. IsMenuItem If set to YES, this text macro creates a menu item in the Edit ➪ Insert Text Macro menu. If the defi nition is BasedOn an IsMenu defi nition (directly or indirectly), it will appear in that submenu group. Otherwise, it will appear as a top-level item in the Edit ➪ Insert Text Macro menu. The IsMenuItem property is not inherited. TextString The body of the text macro. This property defi nes the characters that will be inserted when the text macro is inserted. It can contain placeholders, described later, and variable references. continues Text Macros ❘ 651 c23.indd 651c23.indd 651 1/22/10 1:28:53 PM1/22/10 1:28:53 PM Download at getcoolebook.com 652 ❘ CHAPTER 23 CUSTOMIZING XCODE MACRO PROPERTY DESCRIPTION CompletionPrefix This property is the “symbol” used to select the text macro using Code Sense. This is independent of the Name or TextString property of the text macro. For instance, a text macro that inserts a “do forever” loop could have a completion prefi x of “forever”. You could select this macro using code completion by typing as little as “fore”. The CompletionPrefix property is not inherited. IncludeContexts A comma-separated list of the contexts where the defi nition is enabled. The root context, xcode, would enable the defi nition in any Xcode editor pane. The more specifi c context, xcode.lang.c, would enable the defi nition only when Xcode is editing a C or C-like language. ExcludeContexts A comma-separated list of the contexts where the defi nition should be disabled. Used to refi ne the IncludeContexts by excluding sub- contexts. For example, if IncludeContexts was ( xcode.lang.c ) and ExcludeContexts was ( xcode.lang.c.comment, xcode. lang.c.string ), then the defi nition would be active in all C source contexts, except when you’re editing the text of a comment or in the middle of a literal string. OnlyAtBOL If set to YES, the macro will only appear as a Code Sense suggestion when the cursor position is at the beginning of a line. CycleList This property is a comma-separated list of defi nition identifi ers. This list is used to order multiple text macros that share a single menu item. This allows you to associate multiple variants of macro with a single menu item. The fi rst time you choose the menu item, the fi rst macro in the list is selected. If you immediately select the text macro menu item again, the fi rst macro is removed and replaced with the second macro in the list. The list is circular and will continue to substitute the di erent variants until you settle on the one you want. This property does not control the order in which text macros appear in the completion list — or cycled using Control+. — when using Code Sense. Only the fi rst defi nition should defi ne a CycleList. DefaultSettings This property is a block of properties that defi ne default property values for inherited defi nitions. Any defi nition that inherits from a defi nition containing a DefaultsSettings property will inherit all of the properties defi ned therein. Placeholders Including placeholders ( < #name# > ) in the TextString property makes it easy to jump immediately to the places in the macro that need to be replaced with valid code or other content. After a text macro is inserted, the fi rst placeholder is automatically selected. Text macros support a special form of placeholder that surrounds the name of the placeholder with exclamation marks: < #!name!# > . (continued) c23.indd 652c23.indd 652 1/22/10 1:28:54 PM1/22/10 1:28:54 PM Download at getcoolebook.com If text in the editor pane is selected when the text macro is inserted, this special placeholder is automatically replaced with the selected text. If no text is selected, or the macro was inserted using code completion, the special placeholder acts like any other placeholder. A text macro can only include one special placeholder. If your text macro does not contain a special placeholder, and the user has text selected when the macro is inserted, the macro text replaces the original text. Property References Defi nitions can also include any other property name you wish to invent. Property names, either defi ned or inherited, can be inserted into any value using the syntax $( key ) , where key is the name of the property. In addition to any property values defi ned, you also have access to any of the macros listed in the “ Template Macros ” section, later in this chapter. For example, the reference $(FULLUSERNAME) will be replaced with the long account name of the current user. The ability to defi ne arbitrary property values, refer to property values in other properties, and inherit property values creates a fl exible framework for designing modular text macro defi nitions. The following shows a simple example: ( { Identifier = james.main; TextString = "// main()\n// Written by $(FULLUSERNAME)\n$(MainDecl)\n{\n\t\n\treturn (0);\n}\n"; IsMenu = YES; Name = "James"; ExcludeContexts = ( "xcode.lang.string", "xcode.lang.character", "xcode.lang.comment", "xcode.lang.c.preprocessor" ); }, { Identifier = james.main.c; BasedOn = james.main; MainDecl = "int main( int argc, char** argv )"; IncludeContexts = ( "xcode.lang.c" ); OnlyAtBOL = YES; IsMenuItem = YES; Name = "main()"; CompletionPrefix = main; CycleList = ( james.main.c, james.main.java ); }, { Identifier = james.main.java; BasedOn = james.main; MainDecl = "public static int main( int argc, String[] argv )"; IncludeContexts = ( "xcode.lang.java" ); OnlyAtBOL = YES; Text Macros ❘ 653 continues c23.indd 653c23.indd 653 1/22/10 1:28:54 PM1/22/10 1:28:54 PM Download at getcoolebook.com 654 ❘ CHAPTER 23 CUSTOMIZING XCODE IsMenuItem = NO; Name = "main()"; CompletionPrefix = main; } ) In this example, the james.main defi nition creates the generic defi nition for a text macro that inserts an empty main() function. It also creates a submenu in the Edit ➪ Insert Text Macro menu named “ James. ” The TextString property refers to the (as yet undefi ned) MainDecl property. The two defi nitions that follow, james.main.c and james.main.java , defi ne actual text macros that appear in the text macro menu and code completion. Both inherit the TextString property defi ned in james.main (via the BasedOn property). The individual variants — one for C and the other for Java — defi ne the MainDecl property that will replace the $(MainDecl) reference when the TextString property is resolved. The end result is two macros that appear in the text macro menu and code completion as “ main() ” . When invoked while editing a C source fi le, it inserts a main() function using the declaration int main ( int argc, char ** argv ) . When inserted in a Java source fi le, it emits the same function but has a declaration of public static int main( int argc, String[] argv ) instead. You can fi nd more complex examples of inheritance and property references in the .xctxtmacro fi les supplied with Xcode. Use the following Terminal command to ferret out the text macro fi les that come bundled with Xcode: find /Developer -name '*.xctxtmacro' Open these fi les in Xcode, or any text editor, to get a feel for how text macros are structured and organized. The text macros in Xcode are both elaborate and sophisticated, and because text macros are not offi cially explained anywhere, these fi les and the comments they contain are the closest thing you ’ ll fi nd to documentation. Sanctioned Text Macro Customization The text macros built into Xcode make extensive use of inherited properties that allow you to globally customize their formatting. For example, the TextString property defi ned by Xcode ’ s try/ catch macro looks like this: TextString = "try$(BlockSeparator){\n\t < #!statements!# > \n}$(PostBlockSeparator) catch$(PreExpressionsSpacing)($(InExpressionsSpacing) < #exception# > $(InExpressionsSpacing))$(BlockSeparator){\n\t < #handler# > \n} $(PostBlockSeparator)finally$(BlockSeparator){\n\t < #statements# > \n}"; The reason the macro is so complex is because all of the macros included in Xcode use a number of variables to defi ne common formatting elements, such as the spacing before and after an expression. By overriding selected properties, you can redefi ne the formatting of every Xcode text macro with just a few lines. This used to be done by creating your own text macro defi nition fi les. But now that Apple has shied away from supporting per - user text macro defi nitions, one of the most common reasons to do so (continued) c23.indd 654c23.indd 654 1/22/10 1:28:54 PM1/22/10 1:28:54 PM Download at getcoolebook.com is also cut off. Apple has, instead, provided the same functionality via an expert preference. The “ Expert Preferences ” section explains how to defi ne these special settings. The expert preference setting that affects text macros is named XCCodeSenseFormattingOptions . The value is a dictionary — this is one setting that ’ s easier to edit using the Properties List Editor, rather than via the command line. It can contain values for any, or all, of the following text macro property values: PROPERTY DEFAULT DESCRIPTION BlockSeparator "" Whitespace after the parenthesized expression of an if, for, or while statement and its opening brace. PostBlockSeparator "\n" Whitespace after the closing brace of a block. FunctionBlockSeparator "\n" Whitespace after a method or function name and argument-list declarations and its body. PreExpressionsSpacing " " Whitespace between an if, for, and while keyword and the opening parenthesis. InFunctionArgsSpacing "" Whitespace inside a parenthesized function argument list (after the opening parenthesis and the closing parenthesis). InExpressionsSpacing "" Whitespace inside a parenthesized expression (after the opening parenthesis and the closing parenthesis). PreFunctionArgsSpacing "" Whitespace between a function name and the opening parenthesis. PreCommaSpacing "" Whitespace before a comma inside a function argument list. PostCommaSpacing " " Whitespace after a comma inside a function argument list. PreMethodTypeSpacing " " Whitespace before the parenthesized return type in an Objective-C method declaration. PreMethodDeclSpacing " " Whitespace between the parenthesized return type and the method name in an Objective-C method declaration. InMessageSpacing "" Whitespace inside an Objective-C message expression — after the opening bracket and before the closing bracket. continues Text Macros ❘ 655 c23.indd 655c23.indd 655 1/22/10 1:28:55 PM1/22/10 1:28:55 PM Download at getcoolebook.com [...]... example, if you want all code blocks inserted by Xcode text macros to place the opening curly brace on the next line of code, redefi ne the BlockSeparator property to "\n" The following command accomplishes this from the command line: defaults write com.apple .Xcode XCCodeSenseFormattingOptions -dict BlockSeparator '\n' This command creates a dictionary in the Xcode user properties with a single key/value... preferences file for the Xcode application This fi le is com.apple .Xcode. plist, located in your ~/Library/Preferences folder There are two simple ways of changing these settings However you alter them, remember that the Xcode application should not be running when you do Changing some values while Xcode is running may have unpredictable consequences It’s best to fi rst quit the Xcode application, make...656 ❘ CHAPTER 23 CUSTOMIZING XCODE (continued) PROPERTY DEFAULT DESCRIPTION PreColonSpacing "" Whitespace before a colon in an ObjectiveC method name or message expression PostColonSpacing "" Whitespace after a colon in an Objective-C method name or message expression MessageArgSpacing "" Whitespace... have unpredictable consequences It’s best to fi rst quit the Xcode application, make your changes, and then launch Xcode again The fi rst method is to use the defaults command from a Terminal window The syntax for setting a value in the Xcode preferences is as follows: defaults write com.apple .Xcode key -type value The write command tells the defaults command to set a value in the fi le The last three arguments... command for more options.) For example, the drag-and-drop delay used by Xcode s text editor can be adjusted by setting the value for the NSDragAndDropTextDelay key The command to set this value to 500 (milliseconds) is as follows: defaults write com.apple .Xcode NSDragAndDropTextDelay -integer 500 Download at getcoolebook.com c 23. indd 656 1/22/10 1:28:55 PM . to match. TEXT MACROS In the “ Text Macros ” section of Chapter 6, you learned how to insert text macros using the Edit ➪ Insert Text Macro menu and via Code Sense. These macros can be great. for new text macros — yes, they ’ re macro macros. You can fi nd these in the Edit ➪ Insert Text Macro ➪ Text Macro Specifi cations menu. The properties recognized by Xcode ’ s text macro interpreter. references. continues Text Macros ❘ 651 c 23. indd 651c 23. indd 651 1/22/10 1:28: 53 PM1/22/10 1:28: 53 PM Download at getcoolebook.com 652 ❘ CHAPTER 23 CUSTOMIZING XCODE MACRO PROPERTY DESCRIPTION CompletionPrefix