editor/nsITableEditor.idl

   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
   7 #include "nsISupports.idl"
   8
   9 webidl Element;
  10 webidl Node;
  11 webidl Range;
  12
  13 [scriptable, builtinclass, uuid(4805e684-49b9-11d3-9ce4-ed60bd6cb5bc)]
  14 interface nsITableEditor : nsISupports
  15 {
  16   const short eNoSearch = 0;
  17   const short ePreviousColumn = 1;
  18   const short ePreviousRow = 2;
  19
  20   /* ------------ Table editing Methods -------------- */
  21
  22   /** Insert table methods
  23     * Insert relative to the selected cell or the
  24     *  cell enclosing the selection anchor
  25     * The selection is collapsed and is left in the new cell
  26     *  at the same row,col location as the original anchor cell
  27     *
  28     * @param aNumber    Number of items to insert
  29     * @param aAfter     If TRUE, insert after the current cell,
  30     *                     else insert before current cell
  31     */
  32   void insertTableCell(in long  aNumber, in boolean aAfter);
  33   void insertTableColumn(in long  aNumber, in boolean aAfter);
  34   void insertTableRow(in long  aNumber, in boolean aAfter);
  35
  36   /** Delete table methods
  37     * Delete starting at the selected cell or the
  38     *  cell (or table) enclosing the selection anchor
  39     * The selection is collapsed and is left in the
  40     *  cell at the same row,col location as
  41     *  the previous selection anchor, if possible,
  42     *  else in the closest neigboring cell
  43     *
  44     * @param aNumber    Number of items to insert/delete
  45     */
  46   void deleteTable();
  47
  48   /** Delete just the cell contents
  49     * This is what should happen when Delete key is used
  50     *   for selected cells, to minimize upsetting the table layout
  51     */
  52   void deleteTableCellContents();
  53
  54   /** Delete cell elements as well as contents
  55     * @param aNumber   Number of contiguous cells, rows, or columns
  56     *
  57     * When there are more than 1 selected cells, aNumber is ignored.
  58     * For Delete Rows or Columns, the complete columns or rows are
  59     *  determined by the selected cells. E.g., to delete 2 complete rows,
  60     *  user simply selects a cell in each, and they don't
  61     *  have to be contiguous.
  62     */
  63   void deleteTableCell(in long  aNumber);
  64   void deleteTableColumn(in long  aNumber);
  65   void deleteTableRow(in long  aNumber);
  66
  67   /** Table Selection methods
  68     * Selecting a row or column actually
  69     * selects all cells (not TR in the case of rows)
  70     */
  71   void selectTableCell();
  72
  73   /** Select a rectangular block of cells:
  74     *  all cells falling within the row/column index of aStartCell
  75     *  to through the row/column index of the aEndCell
  76     *  aStartCell can be any location relative to aEndCell,
  77     *   as long as they are in the same table
  78     *  @param aStartCell  starting cell in block
  79     *  @param aEndCell    ending cell in block
  80     */
  81   void selectBlockOfCells(in Element aStartCell,
  82                           in Element aEndCell);
  83
  84   void selectTableRow();
  85   void selectTableColumn();
  86   void selectTable();
  87   void selectAllTableCells();
  88
  89   /** Create a new TD or TH element, the opposite type of the supplied aSourceCell
  90     *   1. Copy all attributes from aSourceCell to the new cell
  91     *   2. Move all contents of aSourceCell to the new cell
  92     *   3. Replace aSourceCell in the table with the new cell
  93     *
  94     *  @param aSourceCell   The cell to be replaced
  95     *  @return              The new cell that replaces aSourceCell
  96     */
  97   Element switchTableCellHeaderType(in Element aSourceCell);
  98
  99   /** Merges contents of all selected cells
 100     * for selected cells that are adjacent,
 101     * this will result in a larger cell with appropriate
 102     * rowspan and colspan, and original cells are deleted
 103     * The resulting cell is in the location of the
 104     *   cell at the upper-left corner of the adjacent
 105     *   block of selected cells
 106     *
 107     * @param aMergeNonContiguousContents:
 108     *       If true:
 109     *         Non-contiguous cells are not deleted,
 110     *         but their contents are still moved
 111     *         to the upper-left cell
 112     *       If false: contiguous cells are ignored
 113     *
 114     * If there are no selected cells,
 115     *   and selection or caret is in a cell,
 116     *   that cell and the one to the right
 117     *   are merged
 118     */
 119   void joinTableCells(in boolean aMergeNonContiguousContents);
 120
 121   /** Split a cell that has rowspan and/or colspan > 0
 122     *   into cells such that all new cells have
 123     *   rowspan = 1 and colspan = 1
 124     *  All of the contents are not touched --
 125     *   they will appear to be in the upper-left cell
 126     */
 127   void splitTableCell();
 128
 129   /** Scan through all rows and add cells as needed so
 130     *   all locations in the cellmap are occupied.
 131     *   Used after inserting single cells or pasting
 132     *   a collection of cells that extend past the
 133     *   previous size of the table
 134     * If aTable is null, it uses table enclosing the selection anchor
 135     * This doesn't doesn't change the selection,
 136     *   thus it can be used to fixup all tables
 137     *   in a page independent of the selection
 138     */
 139   void normalizeTable(in Element aTable);
 140
 141   /** Get the row an column index from the layout's cellmap
 142     * If aCell is null, it will try to find enclosing table of selection anchor
 143     *
 144     */
 145   void getCellIndexes(in Element aCell,
 146                       out long aRowIndex, out long aColIndex);
 147
 148   /** Get the number of rows and columns in a table from the layout's cellmap
 149     * If aTable is null, it will try to find enclosing table of selection ancho
 150     * Note that all rows in table will not have this many because of
 151     * ROWSPAN effects or if table is not "rectangular" (has short rows)
 152     */
 153   void getTableSize(in Element aTable,
 154                     out long aRowCount, out long aColCount);
 155
 156   /** Get a cell element at cellmap grid coordinates
 157     * A cell that spans across multiple cellmap locations will
 158     *   be returned multiple times, once for each location it occupies
 159     *
 160     * @param aTable                   A table in the document
 161     * @param aRowIndex, aColIndex     The 0-based cellmap indexes
 162     *
 163     * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 164     *  passes NS_SUCCEEDED macro)
 165     *
 166     *   You can scan for all cells in a row or column
 167     *   by iterating through the appropriate indexes
 168     *   until the returned aCell is null
 169     */
 170   Element getCellAt(in Element aTable,
 171                     in long aRowIndex, in long aColIndex);
 172
 173   /** Get a cell at cellmap grid coordinates and associated data
 174     * A cell that spans across multiple cellmap locations will
 175     *   be returned multiple times, once for each location it occupies
 176     * Examine the returned aStartRowIndex and aStartColIndex to see
 177     *   if it is in the same layout column or layout row:
 178     *   A "layout row" is all cells sharing the same top edge
 179     *   A "layout column" is all cells sharing the same left edge
 180     *   This is important to determine what to do when inserting or deleting a column or row
 181     *
 182     *  @param aTable                   A table in the document
 183     *  @param aRowIndex, aColIndex     The 0-based cellmap indexes
 184     * returns values:
 185     *  @param aCell                    The cell at this cellmap location
 186     *  @param aStartRowIndex           The row index where cell starts
 187     *  @param aStartColIndex           The col index where cell starts
 188     *  @param aRowSpan                 May be 0 (to span down entire table) or number of cells spanned
 189     *  @param aColSpan                 May be 0 (to span across entire table) or number of cells spanned
 190     *  @param aActualRowSpan           The actual number of cellmap locations (rows) spanned by the cell
 191     *  @param aActualColSpan           The actual number of cellmap locations (columns) spanned by the cell
 192     *  @param aIsSelected
 193     *  @param
 194     *
 195     * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 196     *  passes NS_SUCCEEDED macro)
 197     */
 198   void getCellDataAt(in Element aTable,
 199                      in long  aRowIndex, in long  aColIndex,
 200                      out Element aCell,
 201                      out long  aStartRowIndex, out long  aStartColIndex,
 202                      out long  aRowSpan, out long  aColSpan,
 203                      out long  aActualRowSpan, out long  aActualColSpan,
 204                      out boolean aIsSelected);
 205
 206   /** Get the first row element in a table
 207     *
 208     * @return            The row at the requested index
 209     *                    Returns null if there are no rows in table
 210     * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 211     *  passes NS_SUCCEEDED macro)
 212     */
 213   Node getFirstRow(in Element aTableElement);
 214
 215   /** Get the next row element starting the search from aTableElement
 216     *
 217     * @param aTableElement Any TR or child-of-TR element in the document
 218     *
 219     * @return            The row to start search from
 220     *                    and the row returned from the search
 221     *                    Returns null if there isn't another row
 222     * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 223     *  passes NS_SUCCEEDED macro)
 224     */
 225   Node getNextRow(in Node aTableElement);
 226
 227   /** Preferred direction to search for neighboring cell
 228     * when trying to locate a cell to place caret in after
 229     * a table editing action.
 230     * Used for aDirection param in SetSelectionAfterTableEdit
 231     */
 232
 233   /** Examine the current selection and find
 234     *   a selected TABLE, TD or TH, or TR element.
 235     *   or return the parent TD or TH if selection is inside a table cell
 236     *   Returns null if no table element is found.
 237     *
 238     * @param aTagName         The tagname of returned element
 239     *                         Note that "td" will be returned if name
 240     *                         is actually "th"
 241     * @param aCount           How many table elements were selected
 242     *                         This tells us if we have multiple cells selected
 243     *                           (0 if element is a parent cell of selection)
 244     * @return                 The table element (table, row, or first selected cell)
 245     *
 246     */
 247   Element getSelectedOrParentTableElement(out AString aTagName, out long aCount);
 248
 249   /** Generally used after GetSelectedOrParentTableElement
 250     *   to test if selected cells are complete rows or columns
 251     *
 252     * @param aElement           Any table or cell element or any element
 253     *                           inside a table
 254     *                           Used to get enclosing table.
 255     *                           If null, selection's anchorNode is used
 256     *
 257     * @return
 258     *     0                        aCellElement was not a cell
 259     *                              (returned result = NS_ERROR_FAILURE)
 260     *     TableSelection::Cell     There are 1 or more cells selected but
 261     *                              complete rows or columns are not selected
 262     *     TableSelection::Row      All cells are in 1 or more rows
 263     *                              and in each row, all cells selected
 264     *                              Note: This is the value if all rows
 265     *                              (thus all cells) are selected
 266     *     TableSelection::Column   All cells are in 1 or more columns
 267     *                              and in each column, all cells are selected
 268     */
 269   uint32_t getSelectedCellsType(in Element aElement);
 270
 271   /** Get first selected element from first selection range.
 272     *   (If multiple cells were selected this is the first in the order they were selected)
 273     * Assumes cell-selection model where each cell
 274     * is in a separate range (selection parent node is table row)
 275     * @param aCell     [OUT] Selected cell or null if ranges don't contain
 276     *                  cell selections
 277     * @param aRange    [OUT] Optional: if not null, return the selection range
 278     *                     associated with the cell
 279     * Returns the DOM cell element
 280     *   (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 281     *    passes NS_SUCCEEDED macro)
 282     */
 283   Element getFirstSelectedCell(out Range aRange);
 284
 285   /** Get first selected element in the table
 286     *   This is the upper-left-most selected cell in table,
 287     *   ignoring the order that the user selected them (order in the selection ranges)
 288     * Assumes cell-selection model where each cell
 289     * is in a separate range (selection parent node is table row)
 290     * @param aCell       Selected cell or null if ranges don't contain
 291     *                    cell selections
 292     * @param aRowIndex   Optional: if not null, return row index of 1st cell
 293     * @param aColIndex   Optional: if not null, return column index of 1st cell
 294     *
 295     * Returns the DOM cell element
 296     *   (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 297     *    passes NS_SUCCEEDED macro)
 298     */
 299   Element getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
 300
 301   /** Get next selected cell element from first selection range.
 302     * Assumes cell-selection model where each cell
 303     * is in a separate range (selection parent node is table row)
 304     * Always call GetFirstSelectedCell() to initialize stored index of "next" cell
 305     * @param aCell     Selected cell or null if no more selected cells
 306     *                     or ranges don't contain cell selections
 307     * @param aRange    Optional: if not null, return the selection range
 308     *                     associated with the cell
 309     *
 310     * Returns the DOM cell element
 311     *   (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
 312     *    passes NS_SUCCEEDED macro)
 313     */
 314   Element getNextSelectedCell(out Range aRange);
 315 };