User:Callek/Prefwindow API Variants

With the choice to create a SeaMonkey version of <prefwindow> comes the option of two variants. This document will attempt to describe both variants as well as provide pro's and con's of each.

Callek's Variant

Example Use

In Callek's Version, the only exposed difference is the presence of a parentpane attribute on the <prefpane> XUL element.

<prefwindow>
  <prefpane id="Foo" label="Foo" src="..."/>
  <prefpane id="Bar" label="Bar" src="..."/>
  <prefpane id="FooBaz" label="Baz" parentpane="Foo" src="..."/>
  <prefpane id="FooNoo" label="Noo" parentpane="Foo" src="..."/>
  <prefpane id="FooBoo" label="Boo" parentpane="Foo" src="..."/>
  <prefpane id="Goo" label="Goo" src="..."/>
  <prefpane id="GooGag" label="Gag" parentpane="Goo" src="..."/>
</prefwindow>

Example UI Mockup

===============================================
| Category:  |                                =
|------------|   Lorem ipsum dolor sit amet,  =
|[-] Foo     | consectetuer adipiscing elit.  =
|  |- Baz    | Vestibulum mi. Nulla tempor    =
|  |- Noo    | velit et enim. In fermentum.   =
|  \- Boo    | Etiam quis odio eget nisi      =
|  Bar       | egestas gravida. Donec nisi    =
|[+] Goo     | nisl, eleifend eu, pulvinar    =
|            | a, porttitor eu, elit. Morbi   =
|            | non velit quis magna eleifend  =
|            | posuere. Praesent.             =
|            |                                =
===============================================

Pro's and Con's

We will leave the reader to decide what is a pro or a con of the implementation

• Hardcoded with one nesting level maximum, (this can change)
• Internally uses nsITreeView for tree generation.
• Overrides _makePaneButton of parent (toolkit) binding.
• Flat XUL structure to represent tree hierarchy.
• Easily co-mingles with toolkit prefwindow users.
• Internally registers for an attributeChanged Event for the paneDeck. (un-registers on destruction); in order to be sure to map tree-selection to pane-selected reliably.
• Relies on ordering of <prefpane>'s in the <prefwindow> (as does default toolkit)

Latest Patch

• Attachment # 229434 of bug 342087

Mnyromyr's Variant

Example Use

In Mnyromyr's implementation, he adds <preftree> and <preftreeitem> elements. Which serve the purpose of defining the structure of the tree. The preftreeitem's themselves point to the pane via the pane's id in a prefpane attribute. The <preftreeitem> element will look first on itself for a label attribute to use as the treeitem's label; if there is no label set on itself, it will look on the referenced <prefpane> element for a label.

In the absense of a <preftree> element all panes will be listed as top-level panes. While if <preftree> is present, and <prefpane>'s not referenced by <preftreeitem>'s will effectively be innaccessible.

<prefwindow>
  <preftree>
    <preftreeitem id="prefItemFoo" label="Foo" prefpane="Foo">
      <preftreeitem id="prefItemFooBaz" label="Baz" prefpane="FooBaz"/>
      <preftreeitem id="prefItemFooNoo" label="Baz" prefpane="FooNoo"/>
      <preftreeitem id="prefItemFooBoo" prefpane="FooBoo"/>
    </preftreeitem>
    <preftreeitem id="prefItemBar" label="Bar" prefpane="Bar"/>
    <preftreeitem id="prefItemGoo" prefpane="Goo">
      <preftreeitem id="prefItemGooGag" label="Gag" prefpane="GooGag"/>
    </preftreeitem>
  </preftree>

  <prefpane id="Foo" label="Foo" src="..."/>
  <prefpane id="Bar" label="Bar" src="..."/>
  <prefpane id="FooBaz" label="Baz" src="..."/>
  <prefpane id="FooNoo" label="Noo" src="..."/>
  <prefpane id="FooBoo" label="Boo" src="..."/>
  <prefpane id="Goo" label="Goo" src="..."/>
  <prefpane id="GooGag" label="Gag" src="..."/>
</prefwindow>

Example UI Mockup

===============================================
| Category:  |                                =
|------------|   Lorem ipsum dolor sit amet,  =
|[-] Foo     | consectetuer adipiscing elit.  =
|  |- Baz    | Vestibulum mi. Nulla tempor    =
|  |- Noo    | velit et enim. In fermentum.   =
|  \- Boo    | Etiam quis odio eget nisi      =
|  Bar       | egestas gravida. Donec nisi    =
|[+] Goo     | nisl, eleifend eu, pulvinar    =
|            | a, porttitor eu, elit. Morbi   =
|            | non velit quis magna eleifend  =
|            | posuere. Praesent.             =
|            |                                =
===============================================

Pro's and Con's

• Inaccessible <prefpane>'s if not referenced by a <preftreeitem>
• Adds two more elements to xul, which are only used in SeaMonkey.
• Complexity of creating a tree.
• Actual tree hierarchy is structurally a tree.
• Internal Implementation uses a Tree Walker.

Latest Patch

• Attachment # 230663 of bug 342087