Cocoa interfaces are typically created using Xcode's Interface Builder. This program produces XIB files, which are XML representations of a user interface. Despite being XML, the files are fairly opaque and should not generally be edited manually, and they often do not merge cleanly via source control. The format and content of the XIB file will be different depending on the OS version and devtools (Xcode) version that is used to edit them. If you edit files with consistent versions, the diffs remain marginally readable. Because of this, Chromium has a policy that requires all XIBs to saved with a specific developer setup.
All XIBs must be saved using:
Xcode: 4.4.x - 5.0.x
Mac OS X: 10.8.x
Editing a XIB File
Prior to Xcode 4, Interface Builder was a standalone program that could be used to edit XIBs independently of the Xcode program. In Xcode 4 however, Interface Builder is now just an IDE component, not a separate program. The chrome.xcodeproj is humongous and brings Xcode to its knees, making it unideal for editing XIB files. To make things easier, Chromium has a special Xcode project just for editing XIB files.
To edit a XIB:
- Run the /src/build/mac/edit_xibs.sh script.
- Open the resulting .xcodeproj file in Xcode 4.
- Make any necessary user interface changes.
- If you are adding any new custom classes, follow the directions below.
script will execute GYP
using the Xcode generator for
. That script's output will print the path to the Xcode project that you should use for editing a XIB file.
chrome_nibs.gyp file contains a fake target for use in Xcode. It lists explicitly all the source files on which the XIBs (listed in
chrome_nibs.gypi) depend. For example, all NSWindowController and NSViewController class files are listed in the sources list for the fake Xcode project. This is because Xcode uses the class files to create connections between the user interface in the XIB and the methods and variables to which the elements are bound.
Any custom NSView, NSWindow, NSWindowController, or NSViewController class files should be listed in chrome_nibs.gyp. This will allow you to create new IBOutlets and new IBActions for classes, as well as allowing Xcode to maintain existing connections.
When it comes time to prepare your changelist
, you should list explicitly the XIB changes you have made. This allows your reviewer to know what was done, and to, if necessary, repeat the steps if the change were to be merged or re-done. Example:
[Mac] Add a help center link to the foobar dialog.
* Make the window 20px taller.
* Add a new NSButton configured with a HyperlinkButtonCell.
* Set the springs on the button to lock to lower-left corner.
* Connect the button to |-goToHelpCenter:|.
TEST=(1) Open the foobar dialog.
(2) Click on the "What does this mean?" link.
(3) A new tab opens for the help center article.
Adding a XIB File
Before adding a new XIB file, consider your user interface. As discussed above, XIB files carry a maintenance burden that defining an interface in code does not. But some interfaces are indeed easier to lay out graphically, and if your new UI would be easier done in Interface Builder, then proceed. If, however, your interface is simple and can be easily done in code, please do write it that way.
To add a new XIB file:
- Open Xcode 4 independently of a project.
- Go to File > New > File… and select a new OS X > User Interface. Select the template appropriate for your needs (likely either a Window or a View).
- Save the file in
/src/chrome/app/nibs/ with an appropriate name for your interface (note that XIB files use InterCapsNaming.xib).
/src/chrome/chrome_nibs.gypi and put your newly created XIB file in either the
mac_untranslated_xibs list, depending on if you're going to use the XIB-based localization process.
- Edit /src/chrome/chrome_nibs.gyp (not the .gypi) and add the associated class files for your new XIB. This may be a NSViewController or NSWindowController, as well as any custom NSView, NSControl, or NSWindow subclasses.
- Run the /src/build/mac/edit_xibs.sh script to generate the Xcode project used to edit XIB files (see above).
- Open the .xcodeproj file and edit your user interface. Xcode will now be able to connect the UI components of the XIB to the class files, allowing you to Control-Drag (see the Xcode documentation) between the UI and code to connect IBOutlets and IBActions.