SeaMonkey:Toolkit Transition:PrefwindowPanes:HowTo

From MozillaWiki
Jump to navigation Jump to search

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.
  • In v6, nsWidgetStateManager.js and nsPrefWindow.js are obsolete and replaced by several bindings in preferences.xml.
  • 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!

And preference panels are called "panes" in v6.

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>.
Retrieved from "https://wiki.mozilla.org/index.php?title=SeaMonkey:Toolkit_Transition:PrefwindowPanes:HowTo&oldid=72209"