SeaMonkey:Toolkit Transition:PrefwindowPanes:HowTo

The architecture patch in bug 394522 paved the way for migrating SeaMonkey's old XPFE preference panels to toolkit's <prefpane>s. See SeaMonkey:Toolkit_Transition:PrefwindowPanes for migration coordination (who's doing what?).

PrefWindow v5 (XPFE) vs. v6 ("new toolkit")

The main difference between the two prefwindow versions is the way preference panels are handled: while v5 loaded each panel into one iframe (thus reloading the panel each time you change the panel!), v6 uses a lazy overlay mechanism: a pane is only loaded if it's needed and then only once. It's overlayed over the main preference window by courtesy of document.loadOverlay.

This change in behaviour has some important consequences:

• Any pref panel is loaded only once, hence its potential Startup() method doesn't need to care for reentrancy or persisting data over panel changes.
• Any <script>s in a panel's XUL will be loaded into the main preference window (not into the panel!), hence their globals and methods are likely to clash!

How to migrate a preference panel

To ease the migration, both v5 and v6 preference windows will be accessible during the transition:

• Edit → Preferences... opens the new prefwindow main window preferences.xul.
• Edit → (Legacy Prefwindow...) opens the old XPFE pref.xul.

1. Tree items

Edit /suite/common/pref/preferences.xul (or the respective overlay) and set the following attributes on the respective <treeitem>:

<treeitem id="securityItem"
          prefpane="security_pane"
          label="&security.label;"
          url="chrome://communicator/content/pref/pref-security.xul">

• The id attribute should adhere to the "xxxItem" meme.
• The prefpane attribute should adhere to the "xxx_pane" meme. This will be the id of the preference panel to be reached by this <treeitem>.
• Keep the label of the old panel.
• Set the url attribute to the chrome URI of the panel to be reached by this <treeitem>.