Development:Editing Nibs

These guidelines are not meant to replace the Apple Human Interface Guidelines. Rather, they extend upon them, and document Camino-specific deviations.

Positioning and Margins

• Follow the general guidelines in the Aqua Human Interface Guidelines about positioning controls and center-equalization, with exceptions as noted below.

• Standard distances between elements are standardized at 8 px (10 px on either side of a drop-down menu) for related items in a "section" and 17 px between sections (despite what the HIG say - see screenshot).

• Two buttons next to each other should be 12 px apart, and dangerous buttons should be at least 24 px from safe buttons (as the HIG dictate).

• Buttons on dialog sheets go 20 px below the last element on the sheet.

• It's important that all prefPane windows have a width of 595 px (since they will be forced to that dimension in the actual prefs window). You should set the minimum width to 595px and the minimum height to the actual height of the prefPane.

• The top, bottom, and side margins are all 20 px.

• Keep the following template in mind (from discussion over Bug 308942).

Error creating thumbnail: Unable to save thumbnail to destination

Despite the image above, all hint text should be left-aligned with the left edge of the widget for which the text provides a hint.

Naming Conventions

• Application names in nibs should be capitalized.

• Any quotations should use curly quote characters.

• Omit the comma before the last item in a series.

• Capitalize pref names that are sentences like sentences (aside from also capitalizing the first word in the "option" part of the sentence), and capitalize all words in pref names that are fragments.

• As per the HIG, buttons which have further actions receive an ellipsis ("…"). Many times this means that the ellipsis should follow buttons which open sheets, but not buttons which open windows. Use the real elipsis character (opt-; on a US keyboard), not three periods.

• Refer to button names elsewhere within the text with curly quotes.

• website, web pages, Internet, URL, Location bar, pop-up, plug-in, auto-fill, text field.

  See also the cb.o style guide

IB Considerations

• Be sure you do not break the focus and tab cycle (both normal and Full Keyboard Access) when adding or changing controls in nibs.

• Make sure the initialFirstResponder is correctly set to the first element which should have focus (even though Bug 327203 currently blocks this in prefPanes).

• In sheets, let initialFirstResponder be the closest to a "Cancel" button. That is, set initialFirstResponder to a button that "bails out" of the sheet, but has no destructive behavior.

• Be sure that all items bounding boxes resemble the actual size of the item it encloses as closely as possible, especially vertically for text.

N.B. In the “Great prefPane Correction of 2006”, we discovered a number of layout/display differences between 10.3 and 10.4, so it is imperative that those modifying nibs make sure that the nib is tested on both 10.3 and 10.4 as long as we support 10.3 to prevent breakage.

For instance, hint text that is left-aligned with the left edge of the widget for which the text provides a hint on 10.4 will be indented 3px to the right on 10.3, and, much more seriously, bounding boxes that are sized very tightly to the text on 10.4 will often be 2-3px too small on 10.3, leading to odd/broken wrapping or the disappearance of words altogether!

In these two cases, we take the alignment of the hint text on 10.4 as canonical, since it does not "break" anything on 10.3, but for the bounding box sizes, we take the appearance on 10.3 to be canonical to prevent breakage.

Another known aberration is that NSMatrixes appear to begin one pixel lower on 10.3 than on 10.4. Since this is "non-breaking" behavior, 10.4's measurement is canonically correct here.

Also on 10.3, NSTextFields are measured differently; the layout rectangle line is 3px inside the text field instead of on the edge. Items aligned properly on 10.4 using the edges will "appear" 3px too far apart using the measuring functions on 10.3. Since this is merely a measuring variation (the items actually appear in the correct locations on 10.3 and 10.4), we take the 10.4 measurement as canonical.

Special Notes on the Appearance prefPane

Simply put, this prefPane is evil and buggy.

• Always save with the Colors tab active, or cmd-w will not work in the Fonts tab in real life.