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 (more here) 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).
  • All hint text should be left-aligned with the left edge of the widget for which the text provides a hint.

• 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.

• For Camino icon logos on sheets, use the general guideline of 20 px around the outside margins, and 10 px between the logo and the sheet's text. However, this case can vary widely with context, so adapt until it looks good.

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

Error creating thumbnail: Unable to save thumbnail to destination

Error creating thumbnail: Unable to save thumbnail to destination

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.

• Use only one space following a period (between sentences).

• 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.
  • E.g., "Single Window Mode" is a fragment, but "Links from other applications" is part of a sentence that is completed by the text of the three radio button options

• Use "me" and "my" in preference text, and "you" and "your" in hint text (although it is better to avoid using these in many cases)
  • E.g., "Always use my fonts" and "Ask me which to use"
  • E.g., "History remembers web pages you have visited on the Internet." and "The cache keeps copies of frequently visited web pages on your hard disk."

• 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, Bookmarks Manager, Downloads window

  See also the cb.o style guide (currently existing only in prototype form).

IB Considerations

Until further notice, all nib work should be done only in Interface Builder 2.5.x (preferably under Mac OS X 10.4, as a number of features do not work properly in IB 2.5.6 under Mac OS X 10.5, but it can be run under in a pinch).

• Be sure you do not break the focus and tab cycle (both normal and Full Keyboard Access) when adding or changing controls in nibs. Verify that all controls are included in the tab chain (forwards and backward) with Full Keyboard Access on.

• 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 in IB3, NSMatrixes have two extra pixels of padding on their left side, so the 8px spacing between a label and the NSMatrix becomes 6px according to IB. The placement is identical and auto-guides will snap the NSMatrix to the proper place, so simply be aware of the difference in measuring method.

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.
• The top of the tab view (buttons) should be 12px from the bottom of the titlebar.