XcodeCapp Help

What is XcodeCapp?

One of Cappuccino’s greatest features is the ability to use Xcode 4 to create the user interface for your web applications. Xcode creates .xib files which then must be converted by the command line utility nib2cib to .cib files for use with Cappuccino. But beginning with Xcode 4, there is no way to directly create outlets and actions without editing Objective-C header files.

XcodeCapp-Cocoa acts as a bridge between Xcode and Cappuccino. It performs two main functions:

• Reads your source files when they are modified and automatically creates outlets and actions in the .xib file.
• Automatically converts .xib files to .cib files when the .xib file is modified.

Using XcodeCapp

XcodeCapp is very easy to use and requires very little user interaction. When you build Cappuccino with jake, it will create a symlink to the XcodeCapp application in your Applications folder. Launch XcodeCapp from there and the XcodeCapp icon will appear in your menu bar. Clicking on the icon will display the XcodeCapp menu:

¬

If this is the first time you have run XcodeCapp, or if you were not listening to a project when XcodeCapp was last quit, you need to choose a Cappuccino project. Select "Listen to Project…”, and a folder chooser will appear. Navigate to the root folder of your project — the one that contains index.html and Jakefile — and click Open.

Once you select a project, XcodeCapp will import your project and create a hidden folder called “.XcodeSupport” in the root project directory. This folder contains files built by XcodeCapp that it needs to perform its magic, so you should never directly modify those files. You will probably want to ignore this folder in your IDE and source code management system as well.

After XcodeCapp has imported a project, it will listen to changes in the following files anywhere in the project:

• *.xib – Interface Builder files
• *.j - Objective-J source
• .xcodecapp-ignore - specifies files XcodeCapp should ignore

Any time these files are modified, XcodeCapp will process the files and show a Growl notification when the processing is done.

Declaring Outlets and Actions

The most important function XcodeCapp performs is to create outlets and actions for use with Interface Builder. You create outlets by prefixing them in your source files with @outlet or IBOutlet. For example, in the class below, there are seven outlets defined:

¬

Similarly, you declare actions by declaring the return type of the method to be @action or IBAction. For example, the following method can serve as an action for a control:

¬

Editing XIBs

XcodeCapp creates an Xcode 4 project that allows you to edit your project’s xibs. To open the project, click on the XcodeCapp menu and select “Open Project in Xcode”.

¬

Once the Xcode project is open, you can edit your xibs with the interface builder. All of the outlets and actions you declared in your source will be available in interface builder for connection to views. For example, the InfoPanelController shown above would have these outlets in interface builder:

¬

Ignoring Files and Folders

To have XcodeCapp ignore files and folders, create a file in the root project directory named “.xcodecapp-ignore”, and enter one line for each pattern you would like to ignore. Patterns may use “*” as a wildcard to match zero or more characters (it is not a shell glob) and are matched against the absolute path of the file or folder, so in most cases your patterns should begin with “*”. To safely match a folder name, the pattern should be */<name>/*, where name is the name of the folder.

For example, to ignore the “Modules” directory and the xib file “foo.xib” in your project, enter these lines in .xcodecapp-ignore:

*/Modules/*
*/foo.xib

Note that in addition to whatever patterns you specify (if any), XcodeCapp always ignores the following patterns:

*/.git/*
*/.svn/*
*/.hg/*
*/Frameworks/*
*/.xCodeSupport/*
*/Build/*

Credits

XcodeCapp was originally written by Francisco Tolmasky.
The Cocoa port was written by Antoine Mercadal with contributions from Aparajita Fishman.
XcodeCapp (Cocoa) was originally built for the Archipel Project (archipelproject.org) and is now part of Cappuccino.