dom/chrome-webidl/TreeView.webidl

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