Your Search Results

    nsITreeView

    This interface is used by the tree widget to get information about what and how to display a tree widget.
    Inherits from: nsISupports Last changed in Gecko 22 (Firefox 22 / Thunderbird 22 / SeaMonkey 2.19)

    Implementing a nsITreeView in lieu of DOM methods for tree creation can improve performance dramatically, and removes the need to make changes to the tree manually when changes to the database occur.

    Further information about creating treeviews is given in the XUL Tutorial.

    Method overview

    boolean canDrop(in long index, in long orientation, in nsIDOMDataTransfer dataTransfer);
    boolean canDropBeforeAfter(in long index, in boolean before); Obsolete since Gecko 1.8
    boolean canDropOn(in long index); Obsolete since Gecko 1.8
    void cycleCell(in long row, in nsITreeColumn col);
    void cycleHeader(in nsITreeColumn col);
    void drop(in long row, in long orientation, in nsIDOMDataTransfer dataTransfer);
    AString getCellProperties(in long row, in nsITreeColumn col, in nsISupportsArray properties Obsolete since Gecko 22);
    AString getCellText(in long row, in nsITreeColumn col);
    AString getCellValue(in long row, in nsITreeColumn col);
    AString getColumnProperties(in nsITreeColumn col, in nsISupportsArray properties Obsolete since Gecko 22);
    AString getImageSrc(in long row, in nsITreeColumn col);
    long getLevel(in long index);
    long getParentIndex(in long rowIndex);
    long getProgressMode(in long row, in nsITreeColumn col);
    AString getRowProperties(in long index, in nsISupportsArray properties Obsolete since Gecko 22);
    boolean hasNextSibling(in long rowIndex, in long afterIndex);
    boolean isContainer(in long index);
    boolean isContainerEmpty(in long index);
    boolean isContainerOpen(in long index);
    boolean isEditable(in long row, in nsITreeColumn col);
    boolean isSelectable(in long row, in nsITreeColumn col);
    boolean isSeparator(in long index);
    boolean isSorted();
    void performAction(in wstring action);
    void performActionOnCell(in wstring action, in long row, in nsITreeColumn col);
    void performActionOnRow(in wstring action, in long row);
    void selectionChanged();
    void setCellText(in long row, in nsITreeColumn col, in AString value);
    void setCellValue(in long row, in nsITreeColumn col, in AString value);
    void setTree(in nsITreeBoxObject tree);
    void toggleOpenState(in long index);

    Attributes

    Attribute Type Description
    rowCount long The total number of rows in the tree (including the offscreen rows). Read only.
    selection nsITreeSelection The selection for this view.

    Constants

    Constant Value Description
    PROGRESS_NORMAL 1 Renamed from progressNormal in Gecko 1.8
    PROGRESS_UNDETERMINED 2 Renamed from progressUndetermined in Gecko 1.8
    PROGRESS_NONE 3 Renamed from progressNone in Gecko 1.8
    DROP_BEFORE -1
    DROP_ON 0
    DROP_AFTER 1
    inDropBefore 0 Obsolete since Gecko 1.8
    inDropOn 1 Obsolete since Gecko 1.8
    inDropAfter 2 Obsolete since Gecko 1.8

    Methods

    Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    canDrop()

    Methods used by the drag feedback code to determine if a drag is allowable at the current location. To get the behavior where drops are only allowed on items, such as the mailNews folder pane, always return false when the orientation is not DROP_ON.

    Note: DROP_ON will only be passed to canDrop() if the item is a container; see isContainer().
    boolean canDrop(
      in long index,
      in long orientation,
      in nsIDOMDataTransfer dataTransfer
    );
    
    Parameters
    index
    The index of the row.
    orientation
    The position around the given row. Defined in constants.
    dataTransfer
    This parameter, added in Gecko 1.9.2, provides the data being dragged, so that it can be examined to determine if a drop is possible.
    Return value

    true if a drop is allowed at the current location; otherwise false.

    Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    canDropBeforeAfter()

    Method used by the drag feedback code to determine if a drag is allowable at the current location. To get the behavior where drops are only allowed on items, such as the mailNews folder pane, always return false from canDropBeforeAfter().

    boolean canDropBeforeAfter(
      in long index,
      in boolean before
    );
    
    Parameters
    index
    The index of the item.
    before
    true to test drop before. false to test drop after.
    Return value

    true if a drop event can occur. Otherwise false.

    Obsolete since Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    canDropOn()

    Method used by the drag feedback code to determine if a drag is allowable at the current location. To get the behavior where drops are only allowed on items, such as the mailNews folder pane, always return false from canDropBeforeAfter().

    boolean canDropOn(
      in long index
    );
    
    Parameters
    index
    The index of the item.
    Return value

    true if a drop event can occur. Otherwise false.

    cycleCell()

    Called on the view when a cell in a non-selectable cycling column (for example, unread/flag/and so on.) is clicked.

    void cycleCell(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The row of the cell.
    col
    The column of the cell.

    cycleHeader()

    Called on the view when a header is clicked.

    void cycleHeader(
      in nsITreeColumn col
    );
    
    Parameters
    col
    The column to cycle.

    drop()

    Called when the user drops something on this view. The orientation paramater specifies before/on/after the given row.

    void drop(
      in long row,
      in long orientation,
      in nsIDOMDataTransfer dataTransfer
    );
    
    Parameters
    row
    The index of the row.
    orientation
    The position around the given row. Defined in constants.
    dataTransfer
    This parameter, added in Gecko 1.9.2, provides the data that has been dropped.

    getCellProperties()

    An atomized list of properties for a given cell. Each property, x, that the view gives back will cause the CSS ::moz-tree-cell-*(x) pseudoelement to be matched on the treechildren element.

    See getRowProperties() for an example.

    AString getCellProperties(
      in long row,
      in nsITreeColumn col,
      in nsISupportsArray properties
    );
    
    Parameters
    row
    The index of the row.
    col
    The current column.
    properties
    An array of the cell's current properties. Obsolete since Gecko 22
    Return value

    A string of space-separated property names. Requires Gecko 22

    getCellText()

    The text for a given cell. If a column consists only of an image, then the empty string is returned.

    AString getCellText(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The index of the row.
    col
    The column of the cell. (Note that this is not the column index.)
    Return value

    The text of the cell.

    getCellValue()

    The value for a given cell. This method is only called for columns of type other than text.

    AString getCellValue(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The index of the row.
    col
    The column of the cell. (Note that this is not the column index.)
    Return value

    The value of the cell.

    getColumnProperties()

    Called to get properties to paint a column background. For shading the sort column, and so on. Each property, x, that the view gives back will cause the CSS  ::moz-tree-column(x) to be matched on the treechildren element.

    See getRowProperties() for an example.

    void getColumnProperties(
      in nsITreeColumn col,
      in nsISupportsArray properties
    );
    
    Parameters
    col
    The current column.
    properties
    An array of the column's current properties. Obsolete since Gecko 22
    Return value

    A string of space-separated property names. Requires Gecko 22

    getImageSrc()

    The image path for a given cell. For defining an icon for a cell. If the empty string is returned, the ::moz-tree-image pseudoelement will be used.

    AString getImageSrc(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The index of the row.
    col
    The index of the column.
    Return value

    The image path of the cell.

    getLevel()

    The level is an integer value that represents the level of indentation. It is multiplied by the width specified in the ::moz-tree-indentation pseudoelement to compute the exact indentation.

    long getLevel(
      in long index
    );
    
    Parameters
    index
    The index of the item.
    Return value

    The level of indentation.

    getParentIndex()

    Methods used by the tree to draw thread lines in the tree. getParentIndex is used to obtain the index of a parent row. If there is no parent row, getParentIndex returns -1.

    long getParentIndex(
      in long rowIndex
    );
    
    Parameters
    rowIndex
    The index of the row whose parent should be found.
    Return value

    The row index of the parent row.

    getProgressMode()

    The progress mode for a given cell. This method is only called for columns of type progressmeter. See the constants section for possible modes.

    long getProgressMode(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The index of the row.
    col
    The index of the column.
    Return value

    The progress mode for the cell.

    getRowProperties()

    An atomized list of properties for a given row. Each property, x, that the view gives back will cause the CSS ::moz-tree-row(x) pseudoelement to be matched on the treechildren element.

    void getRowProperties(
      in long index,
      in nsISupportsArray properties
    );
    
    Parameters
    index
    The index of the row.
    properties
    An array of the row's current properties. Obsolete since Gecko 22
    Return value

    A string of space-separated property names. Requires Gecko 22

    Example

    Your function will not be provided with a properties array. (This is one way of detecting the version at run-time). Simply return a string of space-separated property names. For example:

    getRowProperties: function(index) {
      return "dummy";
    }
    

    Obsolete since Gecko 22 (Firefox 22 / Thunderbird 22 / SeaMonkey 2.19)
    This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

    To add properties for a particular row, you must use the nsIAtomService to create an nsIAtom string, which can then be appended to the array to alter the style (see also Styling a Tree)

    getRowProperties: function(index, properties) {
      var atomService = Components.classes["@mozilla.org/atom-service;1"].getService(Components.interfaces.nsIAtomService);
      var atom = atomService.getAtom("dummy");
      properties.AppendElement(atom);
    }
    

    hasNextSibling()

    Used to determine if the row at rowIndex has a nextSibling that occurs after the index specified by afterIndex. Code that is forced to march down the view looking at levels can optimize the march by starting at afterIndex+1.

    boolean hasNextSibling(
      in long rowIndex,
      in long afterIndex
    );
    
    Parameters
    rowIndex
    The index of the item.
    afterIndex
    The index of the item to find siblings after.
    Return value

    true if the row has a next sibling. Otherwise false

    isContainer()

    Whether the row has the potential to hold other rows within it. This does not determine whether a twisty is actually drawn; that's left up to isContainerEmpty. For very simple tree views, such as those without multi-level data, you might want to consider using something simpler than a tree view, such as a listbox.

    For tree views with multi-level data, it's advisable to distinguish between a row which is an empty container (i.e., a row with the potential to hold children but that currently has none), and a non-empty container (i.e., a row that positively does currently have children). The tree frame code that handles drag and drop, for example, uses this method to determine how to interpret the drop position.

    Note: nsITreeView implementations must be prepared to handle a call to toggleOpenState for any row index which returns true for a call to isContainer, even if isContainerEmpty returns true.

    boolean isContainer(
      in long index
    );
    
    Parameters
    index
    The index of the row being asked about.
    Return value

    true if the row is a container. Otherwise false.

    isContainerEmpty()

    One of the methods that can be used to test whether or not a twisty should be drawn, and if so, whether an open or closed twisty should be used.

    boolean isContainerEmpty(
      in long index
    );
    
    Parameters
    index
    The index of the item being asked about.
    Return value

    true if the item is an empty container. Otherwise false.

    isContainerOpen()

    One of the methods that can be used to test whether or not a twisty should be drawn, and if so, whether an open or closed twisty should be used.

    boolean isContainerOpen(
      in long index
    );
    
    Parameters
    index
    The index of the item being asked about.
    Return value

    true if the item is an open container. Otherwise false.

    isEditable()

    Called to ask the view if the cell contents are editable. A value of true will result in the tree popping up a text field when the user tries to inline edit the cell.

    boolean isEditable(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The row of the cell.
    col
    The column of the cell.

    Requires Gecko 1.9 (Firefox 3)

    isSelectable()

    Called to ask the view if the cell is selectable. This method is only called if the selection type is cell or text.

    boolean isSelectable(
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    row
    The row of the cell.
    col
    The column of the cell.
    Return value

    true if the cell is selectable. Otherwise false.

    isSeparator()

    Used to determine if the row at index is a separator. A value of true will result in the tree drawing a horizontal separator. The tree uses the ::moz-tree-separator pseudoelement to draw the separator.

    boolean isSeparator(
      in long index
    );
    
    Parameters
    index
    The index of the item being asked about.

    true if the row is a separator. Otherwise false.

    isSorted()

    Specifies if there is currently a sort on any column. Used mostly by dragdrop to affect drop feedback.

    boolean isSorted();
    
    Parameters

    None.

    true if the column is sorted. Otherwise false.

    performAction()

    A command API that can be used to invoke commands on the selection. The tree will automatically invoke this method when certain keys are pressed. For example, when the DEL key is pressed, performAction will be called with the delete string.

    void performAction(
      in wstring action
    );
    
    Parameters
    action
    The action to perform.

    performActionOnCell()

    A command API that can be used to invoke commands on a specific cell.

    void performActionOnCell(
      in wstring action,
      in long row,
      in nsITreeColumn col
    );
    
    Parameters
    action
    The action to perform.
    row
    The row of the cell.
    col
    The column of the cell.

    performActionOnRow()

    A command API that can be used to invoke commands on a specific row.

    void performActionOnRow(
      in wstring action,
      in long row
    );
    
    Parameters
    action
    The action to perform.
    row
    The row of the cell.

    selectionChanged()

    Should be called from a XUL onselect handler whenever the selection changes.

    void selectionChanged();
    
    Parameters

    None.

    setCellText()

    setCellText is called when the contents of the cell have been edited by the user.

    void setCellText(
      in long row,
      in nsITreeColumn col,
      in AString value
    );
    
    Parameters
    row
    The row of the cell.
    col
    The column of the cell.
    value
    The text to change the cell to.

    Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    setCellValue()

    setCellValue is called when the value of the cell has been set by the user. This method is only called for columns of type other than text.

    void setCellValue(
      in long row,
      in nsITreeColumn col,
      in AString value
    );
    
    Parameters
    row
    The row of the cell.
    col
    The column of the cell.
    value
    The value to change the cell to.

    setTree()

    Called when setting or clearing the view on the tree to link the view to or disconnect the front end box object.

    void setTree(
      in nsITreeBoxObject tree
    );
    
    Parameters
    tree
    The nsITreeBoxObject to attach this view to, or null if the view is being removed from the tree.

    toggleOpenState()

    Called on the view when an item is opened or closed, e.g., by clicking the twisty, keyboard access, et cetera.

    Note: As of this writing (Gecko 2.0), custom nsITreeView implementations must be prepared to handle a call to toggleOpenState for any row index which returns true for a call to isContainer, regardless of whether the container is empty.

    void toggleOpenState(
      in long index
    );
    
    Parameters
    index
    The index of the row to toggle.

    See also

    When working with tree views, the tree box object may also be useful

    Document Tags and Contributors

    Contributors to this page: Sheppy
    Last updated by: Sheppy,