nsITreeBoxObject

The nsITreeBoxObject interface contains information about the size and layout of a tree.

Further information about trees is given in the XUL Tutorial.

Please add a summary to this article.
Last changed in Gecko 1.9 (Firefox 3)

Inherits from: nsISupports

To get the treeBoxObject for a tree:

let boxobject = tree.boxObject;
boxobject.queryInterface("Components.interfaces.nsITreeBoxObject");

Or simply:

let boxobject = tree.treeBoxObject;

Method Overview

long getFirstVisibleRow();
long getLastVisibleRow();
long getPageLength();
void ensureRowIsVisible(in long index);
void ensureCellIsVisible(in long row, in nsITreeColumn col);
void scrollToRow(in long index);
void scrollByLines(in long numLines);
void scrollByPages(in long numPages);
void scrollToCell(in long row, in nsITreeColumn col);
void scrollToColumn(in nsITreeColumn col);
void scrollToHorizontalPosition(in long horizontalPosition);
void invalidate();
void invalidateColumn(in nsITreeColumn col);
void invalidateRow(in long index);
void invalidateCell(in long row, in nsITreeColumn col);
void invalidateRange(in long startIndex, in long endIndex);
void invalidateColumnRange(in long startIndex, in long endIndex, in nsITreeColumn col);
long getRowAt(in long x, in long y);
void getCellAt(in long x, in long y, out long row, out nsITreeColumn col, out ACString childElt);
void getCoordsForCellItem(in long row, in nsITreeColumn col, in ACString element, out long x, out long y, out long width, out long height);
boolean isCellCropped(in long row, in nsITreeColumn col);
void rowCountChanged(in long index, in long count);
void beginUpdateBatch();
void endUpdateBatch();
void clearStyleAndImageCaches();

Attributes

Attribute Type Description
columns nsITreeColumns Readonly: Obtain the columns.
view nsITreeView The view that backs the tree and that supplies it with its data. It is dynamically settable, either using a view attribute on the tree tag or by setting this attribute to a new value.
focused boolean Whether or not we are currently focused.
treeBody nsIDOMElement Readonly: Obtain the treebody content node. This is a node that corresponds to the treechildren tag.
rowHeight long Readonly: Obtain the height of a row.
rowWidth long Readonly: Obtain the width of a row.
horizontalPosition long Readonly: Get the pixel position of the horizontal scrollbar.
selectionRegion nsIScriptableRegion Readonly: Return the region for the visible parts of the selection, in device pixels.

Methods

getFirstVisibleRow()

Get the index of the first visible row.

 long getFirstVisibleRow();

getLastVisibleRow()

Get the index of the last visible row.

 long getLastVisibleRow();

getPageLength()

Gets the number of possible visible rows.

 long getPageLength();

ensureRowIsVisible()

Ensures that a row at a given index is visible.

 void ensureRowIsVisible(in long index);
Parameters
index
The index of the row

ensureCellIsVisible()

Ensures that a given cell in the tree is visible.

 void ensureCellIsVisible(in long row, in nsITreeColumn col);
Parameters
index
The index of the row to check
col
The nsITreeColumn to check

scrollToRow()

Scrolls such that the row at index is at the top of the visible view.

 void scrollToRow(in long index);
Parameters
index
The index of the row

scrollByLines()

Scroll the tree up or down by numLines lines.

 void scrollByLines(in long numLines);
Parameters
numlines
The number of lines to scroll. Positive values move down in the tree. Prevents scrolling off the end of the tree.

scrollByPages()

Scroll the tree up or down by numPages pages. A page is considered to be the amount displayed by the tree. This method prevents scrolling off the end of the tree.

 void scrollByPages(in long numPages);
Parameters
numPages
The number of pages to scroll. Positive values move down in the tree.

scrollToCell()

Scrolls such that a given cell is visible (if possible) at the top left corner of the visible view.

 void scrollToCell(in long row, in nsITreeColumn col);
Parameters
row
The cell's row index
col
The nsITreeColumn of the cell

scrollToColumn()

Scrolls horizontally so that the specified column is at the left of the view (if possible).

 void scrollToColumn(in nsITreeColumn col);
Parameters
col
The nsITreeColumn to scroll to

scrollToHorizontalPosition()

Scroll to a specific horizontal pixel position.

 void scrollToHorizontalPosition(in long horizontalPosition);
Parameters
horizontalPosition
The number of pixels to scroll

invalidate()

invalidateColumn()

invalidateRow()

invalidateCell()

invalidateRange()

invalidateColumnRange()

Invalidation methods for fine-grained painting control.

  void invalidate();
  void invalidateColumn(in nsITreeColumn col);
  void invalidateRow(in long index);
  void invalidateCell(in long row, in nsITreeColumn col);
  void invalidateRange(in long startIndex, in long endIndex);
  void invalidateColumnRange(in long startIndex, in long endIndex,
                             in nsITreeColumn col);

getRowAt()

A hit test that can tell you what row the mouse is over. Returns -1 for invalid mouse coordinates. The coordinate system is the client coordinate system for the document this boxObject lives in, and the units are CSS pixels.

 long getRowAt(in long x, in long y);
Parameters
x
The x coordinate
y
The y coordinate

getCellAt()

A hit test that can tell you what cell the mouse is over. Returns -1 for invalid mouse coordinates. The coordinate system is the client coordinate system for the document this boxObject lives in, and the units are CSS pixels.

 void getCellAt(in long x, in long y, out long row, out nsITreeColumn col, out ACString childElt);
Parameters
x
The x coordinate
y
The y coordinate
Returns
row
The row index at the coordinates
col
The nsITreeColumn hit.
ChildElt
The pseudoelement hit: this can have values of "cell", "twisty", "image", and "text".

getCoordsForCellItem()

Find the coordinates of an element within a specific cell.

 void getCoordsForCellItem(in long row, in nsITreeColumn col, in ACString element,
                            out long x, out long y, out long width, out long height);
Parameters
row
The index of the row
col
The nsITreeColumn
element
The pseudoelement. This can have values of "cell", "twisty", "image", and "text".
Returns
x
The x coordinate
col
The y coordinate.
width
The width of the element
height
The height of the element

isCellCropped()

Determine if the text of a cell is being cropped or not.

 boolean isCellCropped(in long row, in nsITreeColumn col);
Parameters
row
The index of the row
col
The nsITreeColumn

rowCountChanged()

Notify the tree that the number of rows changed. The view is responsible for calling this notification method when rows are added or removed. For non-contiguous additions/removals, this method should be called multiple times.

 void rowCountChanged(in long index, in long count);
Parameters
index
the position at which the new rows were added or at which rows were removed.
count
the number of rows added or removed. Use negative values for removed rows.
Example

You deleted the row with index rowIndex. Inform the tree about this change by calling

rowCountChanged(rowIndex+1, -1);

beginUpdateBatch()

Notify the tree that the view is about to perform a batch update, that is, add, remove or invalidate several rows at once. This must be followed by calling endUpdateBatch(), otherwise the tree will get out of sync.

 void beginUpdateBatch();

endUpdateBatch()

Notify the tree that the view has completed a batch update.

 void endUpdateBatch();

clearStyleAndImageCaches()

Called on a theme switch to flush out the tree's style and image caches.

 void clearStyleAndImageCaches();

Other references