1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1998
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Dave Hyatt <hyatt@mozilla.org> (Original Author)
24 * Ben Goodger <ben@netscape.com>
25 * Jan Varga <varga@ku.sk>
26 * Nate Nielsen <nielsen@memberwebs.com>
27 *
28 * Alternatively, the contents of this file may be used under the terms of
29 * either of the GNU General Public License Version 2 or later (the "GPL"),
30 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
31 * in which case the provisions of the GPL or the LGPL are applicable instead
32 * of those above. If you wish to allow use of your version of this file only
33 * under the terms of either the GPL or the LGPL, and not to allow others to
34 * use your version of this file under the terms of the MPL, indicate your
35 * decision by deleting the provisions above and replace them with the notice
36 * and other provisions required by the GPL or the LGPL. If you do not delete
37 * the provisions above, a recipient may use your version of this file under
38 * the terms of any one of the MPL, the GPL or the LGPL.
39 *
40 * ***** END LICENSE BLOCK ***** */
41
42 #include "nsISupports.idl"
43 #include "domstubs.idl"
44
45 interface nsITreeView;
46 interface nsITreeSelection;
47 interface nsITreeColumn;
48 interface nsITreeColumns;
49
50 [scriptable, uuid(a264f607-9d90-469e-b770-1ae7284fde05)]
51 interface nsITreeBoxObject : nsISupports
52 {
53 /**
54 * Obtain the columns.
55 */
56 readonly attribute nsITreeColumns columns;
57
58 /**
59 * The view that backs the tree and that supplies it with its data.
60 * It is dynamically settable, either using a view attribute on the
61 * tree tag or by setting this attribute to a new value.
62 */
63 attribute nsITreeView view;
64
65 /**
66 * Whether or not we are currently focused.
67 */
68 attribute boolean focused;
69
70 /**
71 * Obtain the treebody content node
72 */
73 readonly attribute nsIDOMElement treeBody;
74
75 /**
76 * Obtain the height of a row.
77 */
78 readonly attribute long rowHeight;
79
80 /**
81 * Obtain the width of a row.
82 */
83 readonly attribute long rowWidth;
84
85 /**
86 * Get the pixel position of the horizontal scrollbar.
87 */
88 readonly attribute long horizontalPosition;
89
90 /**
91 * Get the index of the first visible row.
92 */
93 long getFirstVisibleRow();
94
95 /**
96 * Get the index of the last visible row.
97 */
98 long getLastVisibleRow();
99
100 /**
101 * Gets the number of possible visible rows.
102 */
103 long getPageLength();
104
105 /**
106 * Ensures that a row at a given index is visible.
107 */
108 void ensureRowIsVisible(in long index);
109
110 /**
111 * Ensures that a given cell in the tree is visible.
112 */
113 void ensureCellIsVisible(in long row, in nsITreeColumn col);
114
115 /**
116 * Scrolls such that the row at index is at the top of the visible view.
117 */
118 void scrollToRow(in long index);
119
120 /**
121 * Scroll the tree up or down by numLines lines. Positive
122 * values move down in the tree. Prevents scrolling off the
123 * end of the tree.
124 */
125 void scrollByLines(in long numLines);
126
127 /**
128 * Scroll the tree up or down by numPages pages. A page
129 * is considered to be the amount displayed by the tree.
130 * Positive values move down in the tree. Prevents scrolling
131 * off the end of the tree.
132 */
133 void scrollByPages(in long numPages);
134
135 /**
136 * Scrolls such that a given cell is visible (if possible)
137 * at the top left corner of the visible view.
138 */
139 void scrollToCell(in long row, in nsITreeColumn col);
140
141 /**
142 * Scrolls horizontally so that the specified column is
143 * at the left of the view (if possible).
144 */
145 void scrollToColumn(in nsITreeColumn col);
146
147 /**
148 * Scroll to a specific horizontal pixel position.
149 */
150 void scrollToHorizontalPosition(in long horizontalPosition);
151
152 /**
153 * Invalidation methods for fine-grained painting control.
154 */
155 void invalidate();
156 void invalidateColumn(in nsITreeColumn col);
157 void invalidateRow(in long index);
158 void invalidateCell(in long row, in nsITreeColumn col);
159 void invalidateRange(in long startIndex, in long endIndex);
160 void invalidateColumnRange(in long startIndex, in long endIndex,
161 in nsITreeColumn col);
162
163 /**
164 * A hit test that can tell you what row the mouse is over.
165 * returns -1 for invalid mouse coordinates.
166 *
167 * The coordinate system is the client coordinate system for the
168 * document this boxObject lives in, and the units are CSS pixels.
169 */
170 long getRowAt(in long x, in long y);
171
172 /**
173 * A hit test that can tell you what cell the mouse is over. Row is the row index
174 * hit, returns -1 for invalid mouse coordinates. ColID is the column hit.
175 * ChildElt is the pseudoelement hit: this can have values of
176 * "cell", "twisty", "image", and "text".
177 *
178 * The coordinate system is the client coordinate system for the
179 * document this boxObject lives in, and the units are CSS pixels.
180 */
181 void getCellAt(in long x, in long y, out long row, out nsITreeColumn col, out ACString childElt);
182
183 /**
184 * Find the coordinates of an element within a specific cell.
185 */
186 void getCoordsForCellItem(in long row, in nsITreeColumn col, in ACString element,
187 out long x, out long y, out long width, out long height);
188
189 /**
190 * Determine if the text of a cell is being cropped or not.
191 */
192 boolean isCellCropped(in long row, in nsITreeColumn col);
193
194 /**
195 * The view is responsible for calling these notification methods when
196 * rows are added or removed. Index is the position at which the new
197 * rows were added or at which rows were removed. For
198 * non-contiguous additions/removals, this method should be called multiple times.
199 */
200 void rowCountChanged(in long index, in long count);
201
202 /**
203 * Notify the tree that the view is about to perform a batch
204 * update, that is, add, remove or invalidate several rows at once.
205 * This must be followed by calling endUpdateBatch(), otherwise the tree
206 * will get out of sync.
207 */
208 void beginUpdateBatch();
209
210 /**
211 * Notify the tree that the view has completed a batch update.
212 */
213 void endUpdateBatch();
214
215 /**
216 * Called on a theme switch to flush out the tree's style and image caches.
217 */
218 void clearStyleAndImageCaches();
219 };