1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6// invalid widl
7// interface nsITreeSelection;
8
9[NoInterfaceObject]
10interface TreeView
11{
12  /**
13   * The total number of rows in the tree (including the offscreen rows).
14   */
15  readonly attribute long rowCount;
16
17  /**
18   * The selection for this view.
19   */
20  [SetterThrows]
21  attribute nsITreeSelection? selection;
22
23  /**
24   * A whitespace delimited list of properties.  For each property X the view
25   * gives back will cause the pseudoclasses  ::-moz-tree-cell(x),
26   * ::-moz-tree-row(x), ::-moz-tree-twisty(x), ::-moz-tree-image(x),
27   * ::-moz-tree-cell-text(x).  to be matched on the pseudoelement
28   * ::moz-tree-row.
29   */
30  [Throws]
31  DOMString getRowProperties(long row);
32
33  /**
34   * A whitespace delimited list of properties for a given cell.  Each
35   * property, x, that the view gives back will cause the pseudoclasses
36   *  ::-moz-tree-cell(x), ::-moz-tree-row(x), ::-moz-tree-twisty(x),
37   *  ::-moz-tree-image(x), ::-moz-tree-cell-text(x). to be matched on the
38   *  cell.
39   */
40  [Throws]
41  DOMString getCellProperties(long row, TreeColumn column);
42
43  /**
44   * Called to get properties to paint a column background.  For shading the sort
45   * column, etc.
46   */
47  DOMString getColumnProperties(TreeColumn column);
48
49  /**
50   * Methods that can be used to test whether or not a twisty should be drawn,
51   * and if so, whether an open or closed twisty should be used.
52   */
53  [Throws]
54  boolean isContainer(long row);
55  [Throws]
56  boolean isContainerOpen(long row);
57  [Throws]
58  boolean isContainerEmpty(long row);
59
60  /**
61   * isSeparator is used to determine if the row is a separator.
62   * A value of true will result in the tree drawing a horizontal separator.
63   * The tree uses the ::moz-tree-separator pseudoclass to draw the separator.
64   */
65  [Throws]
66  boolean isSeparator(long row);
67
68  /**
69   * Specifies if there is currently a sort on any column. Used mostly by dragdrop
70   * to affect drop feedback.
71   */
72  boolean isSorted();
73
74  const short DROP_BEFORE = -1;
75  const short DROP_ON = 0;
76  const short DROP_AFTER = 1;
77  /**
78   * Methods used by the drag feedback code to determine if a drag is allowable at
79   * the current location. To get the behavior where drops are only allowed on
80   * items, such as the mailNews folder pane, always return false when
81   * the orientation is not DROP_ON.
82   */
83  [Throws]
84  boolean canDrop(long row, long orientation, DataTransfer? dataTransfer);
85
86  /**
87   * Called when the user drops something on this view. The |orientation| param
88   * specifies before/on/after the given |row|.
89   */
90  [Throws]
91  undefined drop(long row, long orientation, DataTransfer? dataTransfer);
92
93  /**
94   * Methods used by the tree to draw thread lines in the tree.
95   * getParentIndex is used to obtain the index of a parent row.
96   * If there is no parent row, getParentIndex returns -1.
97   */
98  [Throws]
99  long getParentIndex(long row);
100
101  /**
102   * hasNextSibling is used to determine if the row at rowIndex has a nextSibling
103   * that occurs *after* the index specified by afterIndex.  Code that is forced
104   * to march down the view looking at levels can optimize the march by starting
105   * at afterIndex+1.
106   */
107  [Throws]
108  boolean hasNextSibling(long row, long afterIndex);
109
110  /**
111   * The level is an integer value that represents
112   * the level of indentation.  It is multiplied by the width specified in the
113   * :moz-tree-indentation pseudoelement to compute the exact indendation.
114   */
115  [Throws]
116  long getLevel(long row);
117
118  /**
119   * The image path for a given cell. For defining an icon for a cell.
120   * If the empty string is returned, the :moz-tree-image pseudoelement
121   * will be used.
122   */
123  [Throws]
124  DOMString getImageSrc(long row, TreeColumn column);
125
126  /**
127   * The value for a given cell. This method is only called for columns
128   * of type other than |text|.
129   */
130  [Throws]
131  DOMString getCellValue(long row, TreeColumn column);
132
133  /**
134   * The text for a given cell.  If a column consists only of an image, then
135   * the empty string is returned.
136   */
137  [Throws]
138  DOMString getCellText(long row, TreeColumn column);
139
140  /**
141   * Called during initialization to link the view to the front end box object.
142   */
143  [Throws]
144  undefined setTree(TreeBoxObject? tree);
145
146  /**
147   * Called on the view when an item is opened or closed.
148   */
149  [Throws]
150  undefined toggleOpenState(long row);
151
152  /**
153   * Called on the view when a header is clicked.
154   */
155  [Throws]
156  undefined cycleHeader(TreeColumn column);
157
158  /**
159   * Should be called from a XUL onselect handler whenever the selection changes.
160   */
161  undefined selectionChanged();
162
163  /**
164   * Called on the view when a cell in a non-selectable cycling column (e.g., unread/flag/etc.) is clicked.
165   */
166  undefined cycleCell(long row, TreeColumn column);
167
168  /**
169   * isEditable is called to ask the view if the cell contents are editable.
170   * A value of true will result in the tree popping up a text field when
171   * the user tries to inline edit the cell.
172   */
173  [Throws]
174  boolean isEditable(long row, TreeColumn column);
175
176  /**
177   * isSelectable is called to ask the view if the cell is selectable.
178   * This method is only called if the selection style is |cell| or |text|.
179   * XXXvarga shouldn't this be called isCellSelectable?
180   */
181  [Throws]
182  boolean isSelectable(long row, TreeColumn column);
183
184  /**
185   * setCellValue is called when the value of the cell has been set by the user.
186   * This method is only called for columns of type other than |text|.
187   */
188  [Throws]
189  undefined setCellValue(long row, TreeColumn column, DOMString value);
190
191  /**
192   * setCellText is called when the contents of the cell have been edited by the user.
193   */
194  [Throws]
195  undefined setCellText(long row, TreeColumn column, DOMString value);
196
197  /**
198   * A command API that can be used to invoke commands on the selection.  The tree
199   * will automatically invoke this method when certain keys are pressed.  For example,
200   * when the DEL key is pressed, performAction will be called with the "delete" string.
201   */
202  undefined performAction(DOMString action);
203
204  /**
205   * A command API that can be used to invoke commands on a specific row.
206   */
207  undefined performActionOnRow(DOMString action, long row);
208
209  /**
210   * A command API that can be used to invoke commands on a specific cell.
211   */
212  undefined performActionOnCell(DOMString action, long row, TreeColumn column);
213};
214