For example, open a property list fi le Info.plist using the Plain Text editor if you want to edit the raw XML.. For each fi le type, there are essentially four possibilities: One of X
Trang 1646 ❘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
Trang 2editors 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
Trang 3648 ❘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
Trang 4Supported 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
Trang 5650 ❘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
“ 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
Trang 6Text 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:
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
Trang 7652 ❘CHAPTER 23 CUSTOMIZING XCODE
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 diff 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)
Trang 8If 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
Trang 9654 ❘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)
Trang 10is 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:
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