User:Callek/Prefwindow API Variants

From MozillaWiki
Jump to: navigation, search

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

Pros and Cons

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

Annotated --Neil
  • Relies on ordering of <prefpane>'s in the <prefwindow> (as does default toolkit)
  • Flat XUL structure to represent tree hierarchy.
  • Hardcoded with one nesting level maximum, (this can change)
  • Easily co-mingles with toolkit prefwindow users.
    Pro: conceptually simpler
    Con: less flexible
  • Internally uses nsITreeView for tree generation.
    Con: suspect implementation
  • Overrides _makePaneButton of parent (toolkit) binding.
    Pro: supports addPane
    Con: less maintainable
  • 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.
    Con: should use <radiogroup onselect>

Latest Patch


Mnyromyr's Variant

Example Use

In Mnyromyr's implementation, he adds <preftree> and <preftreeitem> elements which serve the purpose of defining the hierarchical 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.

If no <preftree> element is given, all panes will be listed as top-level panes; if a <preftree> is present, only those panes are accessible that are referenced by a <preftreeitem>!

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

Pros and Cons

Annotated --Neil
  • Obvious tree hierarchy structure, prohibiting circular references
    Pro
  • No complex custom content tree view implementation necessary
    Pro
  • Inaccessible <prefpane>'s if not explicitly referenced by a <preftreeitem>
    Con
  • Adds two more elements to xul, which are only used in SeaMonkey
    Con
  • Actual tree hierarchy is structurally a tree (XSLT would have been even easier, but does not work in XBL)
    Pro
  • Internal implementation uses a Tree Walker and recursive function calls
    Con: unreadable code

Latest Patch