Documentation

Installation

Copy ODCompletionDictionary.pbplugin to

and restart Xcode. After successful installation Completion Dictionary logs its version number to the Console whenever the plugin gets loaded into Xcode.

Upgrading from previous versions

Completion Dictionary 4.0 stores its configuration data in a new location. You therefore have to move and rename an existing configuration file from ~/Library/KeyBindings/CompletionKeyBinding.dict to ~/Library/Application Support/Completion Dictionary/Configuration.plist

Further, the completion method selector has changed from completeUsingDictionary: to completionDictionaryExpandMacro:, so you have to update your key bindings as described in the following section.

Customizing the completion shortcut

By default the Edit > Completion Dictionary > Expand Macro command can be invoked with Control-Escape. You may customize this shortcut in Xcode's Key Bindings preferences.

Unfortunately, Xcode doesn't let you bind the Escape key (without any modifiers) to a menu command, which would be a very convenient shortcut though. However, it is possible to establish this binding by editing the appropriate key binding file manually.

When using the default Key Binding Set

If you haven't yet created a custom "Key Binding Set" in Xcode's Key Bindings preferences, you can establish the key binding in

This file must contain at least the following lines:

When using a custom Key Binding Set

If you are using a custom key binding set, Xcode ignores the settings in PBKeyBinding.dict. Therefore you must edit your custom key bindings file instead, which can be found at

Open this file in Property List Editor, select Edit > Show Strings as Unicode and add a key binding to the "text" dictionary where the key is \U001B and the selector is completionDictionaryExpandMacro:.

Configuration

Choose Edit > Completion Dictionary > Edit Macros or type Command-Option-comma to open the macro editor. You will see a set of pre-installed example macros, ready to be used immediately. You can add your own macros by entering several abbreviation-macro pairs, e.g:

Placeholders

A macro may contain one or more placeholders for variable names, arguments and other program-specific information. A placeholder is delimited by <# and #> and can be inserted conveniently by choosing an item from the "Insert Placeholder" pull down menu.

• Simple Placeholder: The placeholder is selected when the macro is expanded, so you can replace it with your own code. If the macro contains multiple placeholders, the first placeholder is selected and you can cycle through the placeholders by either choosing Edit > Select Next Placeholder or typing Control-slash.
• Query Placeholder: When a placeholder's label is preceded with a question mark, expanding the macro will raise a panel asking you to enter replacement values for each query placeholder. If the macro contains multiple, equally labeled placeholders, their replacement value will be requested only once, and all these placeholders will be replaced with the same value. If a placeholder's label starts with a capital letter, the entered value's initial character will be converted to uppercase. See the "set" macro for an example how to use this kind of case conversion.
• Query Placeholder with Default Value: A query placeholder may specify an optional default value. If the macro contains multiple, equally labeled placeholders, the default value must only be specified in one of the placeholders.
• Clipboard Contents: This placeholder is replaced with the contents of the Clipboard.
• C Type Delimiter: Inserts a space character unless the preceding character is an asterisk (indicating a C pointer type). See the "enum" macro for an example how to use this placeholder.

Restoring the default configuration

Completion Dictionary includes a comprehensive set of default macros, illustrating lots of the plugin's capabilities. They provide a good starting point for your own macro definitions. If you wish to restore the default configuration at a later point, you just have to remove (or rename) your custom configuration file at

and restart Xcode.

The default configuration includes macros for C, Objective-C and HTML. Here are just a few noteworthy macros:

• acc - Inserts Objective-C accessor methods. Prompts for variable name and type. Illustrates the usage of query placeholders and automatic case conversion.
• enum - Inserts an Objective-C enumeration code snippet. Illustrates the usage of query placeholders with default values and the "C Type Delimiter" placeholder.
• oi, ok - Expand to objectAtIndex: and objectForKey:. Macros like these save a lot of time when typing such common code fragments.
• \ - Entering NSString constants has never been faster…
• ( - Illustrates the usage of the "Clipboard Contents" placeholder.
• div - Inserts an HTML div-tag. Prompts for the "class" property.
• t - Inserts an arbitrary HTML tag. Prompts for the tag's name.

Usage

Once you've configured the dictionary you can use it as follows: Type the abbreviation and press the completion shortcut (Control-Escape by default). If the abbreviation is found in the dictionary, the corresponding macro is inserted, otherwise Xcode's built-in code completion is invoked. If the completion doesn't deliver the desired results, you can undo this operation with Command-Z.

If the macro contains any placeholder the first placeholder will be selected, so you can replace it with your own code right away. If there's more than one placeholder you can cycle through the placeholders by either choosing Edit > Select Next Placeholder or typing Control-slash.

If the macro contains any query placeholder, a panel will appear, allowing you to fill out the requested fields. Note that you can navigate through the fields using the up/down arrow keys. Once you've completed your input you can confirm with Return or dismiss this panel by pressing Escape.