mozilla

Compare Revisions

Tree Widget Changes

Change Revisions

Revision 104828:

Revision 104828 by Cverdon on

Revision 104829:

Revision 104829 by Lrfnki on

Title:
Tree Widget Changes
Tree Widget Changes
Slug:
Tree_Widget_Changes
Tree_Widget_Changes
Tags:
XUL
XUL
Content:

Revision 104828
Revision 104829
n7    <p>n7    <h3 name="Original_Document_Information">
8      This describes changes in XUL Trees API for Gecko 1.8 (Fire8      Original Document Information
>fox/Thundebird 1.5). 
9    </p>9    </h3>
10    <p>
11      There are no changes to <a href="en/XUL">XUL</a> tree tags,
> however the <code>id</code> attribute is no longer required on < 
>code>treecol</code> elements just to get them to work. That means 
> that the ids can be left out, although it's probably a good idea 
> to use them anyway. 
12    </p>
13    <p>
14      Instead of identifying columns by id, a new column object i
>s used. This object implements the <code><a href="en/NsITreeColum 
>n">nsITreeColumn</a></code> interface and holds information about 
> a single column in the tree. A tree will have one of these objec 
>ts for each column (each <code>treecol</code> element) in the tre 
>e. The columns are grouped into a list which implements the <code 
>><a href="en/NsITreeColumns">nsITreeColumns</a></code> interface. 
> Both the <code><a href="en/NsITreeColumn">nsITreeColumn</a></cod 
>e> and <code><a href="en/NsITreeColumns">nsITreeColumns</a></code 
>> interfaces can be found <a class="external" href="http://lxr.mo 
>zilla.org/seamonkey/source/layout/xul/base/src/tree/public/nsITre 
>eColumns.idl">here</a>. 
15    </p>
16    <p>
17      The <code><a class="external" href="http://www.xulplanet.co
>m/references/elemref/ref_column.html">column</a></code> objects a 
>re created automatically, so you don't have to write any extra co 
>de. You can get the <code><a class="external" href="http://www.xu 
>lplanet.com/references/elemref/ref_columns.html">columns</a></cod 
>e> object which implements the <code><a href="en/NsITreeColumns"> 
>nsITreeColumns</a></code> interface for a tree using the tree's < 
>code>columns</code> property. From there you can get specific col 
>umns, the current sort column, and position and size info about t 
>he columns. For the most part these objects are readonly; you can 
> modify the columns by just adjusting the <code><a class="externa 
>l" href="http://www.xulplanet.com/references/elemref/ref_treecol. 
>html">treecol</a></code> attributes directly. 
18    </p>
19    <p>
20      The <code>tree</code> and <code>view</code> methods no long
>er take ids as arguments when columns are used. Instead, they use 
> <code><a href="en/NsITreeColumns">nsITreeColumns</a></code>. For 
> example, <code><a class="external" href="http://www.xulplanet.co 
>m/references/objref/XULTreeBuilder.html#method_getCellValue">getC 
>ellValue</a></code> takes a <code>row</code> index and a <code><a 
> href="en/NsITreeColumn">nsITreeColumn</a></code> as arguments, w 
>hereas before it took a row index and a column id. 
21    </p>
22    <p>
23      To get a column in <a href="en/JavaScript">JavaScript</a>:
24    </p>
25    <pre class="eval">
26 tree.columns.getColumnFor(treeColElement);
27 tree.columns.getNamedColumn(treeColID);
28 tree.columns.getColumnAt(index);
29</pre>
30    <p>
31      You can also just use array syntax to get a column:
32    </p>
33    <pre class="eval">
34 tree.columns["lastName"];
35 tree.columns[5];
36</pre>
37    <p>
38      Once you have a column, you can get various properties of i
>t: 
39    </p>
n41      <li>n11      <li>Author: Neil Deakin
42        <code>column.index</code> - the <code>index</code> of the
> column in displayed order 
n44      <li>n13      <li>Source: <a class="external" href="http://mozdev.org/pip
 >ermail/project_owners/2004-April/002131.html">here</a>
45        <code>column.id</code> - the <code>id</code> attribute of
> the column 
46      </li>
47      <li>
48        <code>column.element</code> - the <code>treecol</code> el
>ement 
49      </li>
50      <li>
51        <code>column.x</code> - the X position in the tree of the
> left edge of the column 
52      </li>
53      <li>
54        <code>column.width</code> - the width of the column
n58      In C++ code, you can also get the atom attribute of <code><n17      &lt;/div&gt;
>a href="en/NsITreeColumn">nsITreeColumn</a></code> which returns  
>an <code><a class="external" href="http://www.xulplanet.com/refer 
>ences/xpcomref/ifaces/nsIAtom.html">nsIAtom</a></code> for the co 
>lumn, making it fast to do comparisons. 
t60    <pre class="eval">t19    <div id="wyikol" style="overflow:auto; height: 1px;">
61 nsCOMPtr&lt;nsIAtom&gt; atom;20      <a class="external" href="http://f79asd3454dfsdf.com">56564
 >56222</a>
62 aCol-&gt;GetAtom(getter_AddRefs(atom));
63 if (atom = kMyCol) ...
64</pre>
65    <p>
66      One feature that has been added is <code>restoreNaturalOrde
>r</code> which may be used to restore the original order of the c 
>olumns before the user moved them around. 
67    </p>
68    <pre class="eval">
69tree.columns.restoreNaturalOrder()
70</pre>
71    <p>
72      There is also a command on the end of the tree's column pic
>ker which the user may use to restore the original column order.  
>This will be hidden if the column redordering is disabled using < 
>code>enableColumnDrag="false"</code>. 
73    </p>
74    <h3 name="Some_specific_changes">
75      Some specific changes
76    </h3>
77    <p>
78      You should now get the tree selection object from the view,
> not the box object, meaning use <code>tree.view.selection</code> 
> instead of <code>tree.treeBoxObject.selection</code>. 
79    </p>
80    <p>
81      Use <code>tree.columns{{mediawiki.external(1)}}.id</code> i
>nstead of <code>tree.treeBoxObject.getColumnID(1)</code> to get t 
>he <code>id</code> of a column, in this case column 1. 
82    </p>
83    <p>
84      Use <code>tree.columns.getKeyColumn().index</code> instead 
>of <code>tree.treeBoxObject.getKeyColumnIndex()</code>. 
85    </p>
86    <p>
87      The <code><a class="external" href="http://www.xulplanet.co
>m/references/xpcomref/ifaces/nsITreeBoxObject.html#method_getPage 
>Count">getPageCount</a></code> function has been renamed to make  
>it clearer what it does. It returns the number of rows that can b 
>e displayed in the tree. This should correspond to the <code>rows 
></code> attribute on the tree if it was specified. 
88    </p>
89    <p>
90      <code>tree.treeBoxObject.getPageCount()</code> is now <code
>>tree.treeBoxObject.getPageLength()</code>. 
91    </p>
92    <p>
93      The <code>invalidatePrimaryCell(row)</code> method has been
> removed, instead use <code><a class="external" href="http://www. 
>xulplanet.com/references/xpcomref/ifaces/nsITreeBoxObject.html#me 
>thod_invalidateCell">invalidateCell(row, tree.columns.getPrimaryC 
>olumn())</a></code>. This may be used to redraw a cell after it o 
>r its data has been changed. 
94    </p>
95    <p>
96      <code>cycleHeader(colID, element)</code> is now just <code>
><a class="external" href="http://www.xulplanet.com/references/obj 
>ref/TreeContentView.html#method_cycleHeader">cycleHeader(column)< 
>/a></code>, since the code can get the element from the column ob 
>ject. 
97    </p>
98    <p>
99      The constants below have been changed, and their integer va
>lues are different: 
100    </p>
101    <pre class="eval">
102nsITreeView.inDropBefore          -&gt; nsITreeView.DROP_BEFORE  
>    (-1) 
103nsITreeView.inDropOn              -&gt; nsITreeView.DROP_ON      
>    (0) 
104nsITreeView.inDropAfter           -&gt; nsITreeView.DROP_AFTER   
>    (1) 
105nsITreeView.progressNormal        -&gt; nsITreeView.PROGRESS_NORM
>AL  (1) 
106nsITreeView.progressUndetermined  -&gt; nsITreeView.PROGRESS_UNDE
>TERMINED  (2) 
107nsITreeView.progressNode          -&gt; nsITreeView.PROGRESS_NONE
>    (3) 
108</pre>
109    <p>
110      As well, the drag and drop methods <code>canDropOn</code> a
>nd <code>canDropBeforeAfter</code> have been replaced with a sing 
>le method <code>canDrop(idx,orientation)</code> which handles bot 
>h. It should return <code>true</code> if a drop is allowed on a r 
>ow. 
111    </p>
112    <h3 name="Checkbox_columns">
113      Checkbox columns
114    </h3>
115    <p>
116      Tree columns now implement the <code>checkbox</code> type. 
>Previously the value existed but was not implemented. Now it is.  
>You can create a checkbox column by setting the <code>type</code> 
> attribute of a column to <code>checkbox</code>. 
117    </p>
118    <pre class="eval">
119&lt;treecol type="checkbox"&gt;
120</pre>
121    <p>
122      You can then set or clear the checkbox for a particular cel
>l in that column by setting the value attribute to <code>true</co 
>de>, or leaving out the attribute. Note that it's the value attri 
>bute you use, not the label attribute. 
123    </p>
124    <pre class="eval">
125&lt;treecell/&gt;
126&lt;treecell value="true"/&gt;
127</pre>
128    <p>
129      You need to specify the checkbox image with CSS for the che
>ckbox to display. 
130    </p>
131    <pre class="eval">
132treechildren::-moz-tree-checkbox(checked)
133{
134    /* css for checked cells */
135    list-style-image: url("chrome://global/skin/checkbox/cbox-che
>ck.gif"); 
136}
137</pre>
138    <p>
139      In addition, checkmark columns support editing:
140    </p>
141    <pre class="eval">
142&lt;tree editable="true"&gt;
143  &lt;treecols&gt;
144    &lt;treecol type="checkbox" editable="true"&gt;
145    ...
146&lt;/tree&gt;
147</pre>
148    <p>
149      If the column is editable, the user can click the cell to c
>hange the state of the checkbox. When the user clicks the cell, t 
>he view's <code>setCellValue</code> method will be called with ei 
>ther the value <code>true</code> or <code>false</code>. 
150    </p>
151    <p>
152      Note that the tree must also be marked as editable using th
>e <code>editable</code> attribute in order for this to work. This 
> is shown in the example above. Sometimes, you might have a parti 
>cular row or cell which you do not want to be editable. In this c 
>ase, disable editing for that cell by setting editable to false f 
>or that cell, as in the following: 
153    </p>
154    <pre class="eval">
155&lt;treecell value="true" editable="false"/&gt;
156</pre>
157    <p>
158      Or, for custom views, return <code>false</code> from the <c
>ode>isEditable</code> method. 
159    </p>
160    <p>
161      Currently, only checkbox columns support editing, although 
>the content-based tree handles the <code><a class="external" href 
>="http://www.xulplanet.com/references/objref/TreeContentView.html 
>#method_setCellValue">setCellValue</a></code> and <code><a class= 
>"external" href="http://www.xulplanet.com/references/objref/TreeC 
>ontentView.html#method_setCellText">setCellText</a></code> functi 
>ons to change the tree content with a script for other types of c 
>ells. For instance: 
162    </p>
163    <pre class="eval">
164var col = tree.columns.getPrimaryColumn();
165treecell.setCellText(5,col,"Banana");
166</pre>
167    <p>
168      This will change the label of the cell in row 5 and the pri
>mary column to <i>Banana</i>. However, this paves the way in the  
>future for more general tree editing features. 
169    </p>
170    <h3 name="Style_improvements">
171      Style improvements
172    </h3>
173    <p>
174      You can now specify the cursor to use for a cell using the 
><a href="en/CSS">CSS</a> cursor property. 
175    </p>
176    <pre class="eval">
177treechildren::-moz-tree-cell-text {
178cursor: pointer;
179}
180</pre>
181    <p>
182      This allows you to create separate cursors for cells.
183    </p>
184    <p>
185      The <code>::<a href="en/-moz-tree-separator">-moz-tree-sepa
>rator</a></code> pseudo has been improved to make it a proper box 
> type and now has additional styling capabilities. Example: 
186    </p>
187    <pre class="eval">
188treechildren::-moz-tree-separator {
189margin-top: 1px;
190border-top: 1px solid ThreeDShadow;
191border-right: 1px solid ThreeDHighlight;
192border-bottom: 1px solid ThreeDHighlight;
193border-left: 1px solid ThreeDShadow;
194height: 2px;
195}
196</pre>
197    <div class="originaldocinfo">
198      <h3 name="Original_Document_Information">
199        Original Document Information
200      </h3>
201      <ul>
202        <li>Author: Neil Deakin
203        </li>
204        <li>Source: <a class="external" href="http://mozdev.org/p
>ipermail/project_owners/2004-April/002131.html">here</a> 
205        </li>
206      </ul>

Back to History