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