nsITreeBoxObject

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

Further information about trees is given in the XUL Tutorial.

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

Attributes

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

• Tree Widget Changes (applies to Gecko 1.8.0 and later)
• XUL Tutorial:Tree Box
• Sorting and filtering a custom tree view
• XUL Tutorial:Tree View Details
• nsITreeView