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   /**
  21    * insertTableCell() inserts <td> elements before or after a cell element
  22    * containing first selection range.  I.e., if the cell spans columns and
  23    * aInsertPosition is true, new columns will be inserted after the
  24    * right-most column which contains the cell.  Note that this simply
  25    * inserts <td> elements, i.e., colspan and rowspan around the cell
  26    * containing selection are not modified.  So, for example, adding a cell
  27    * to rectangular table changes non-rectangular table.  And if a cell
  28    * containing selection is at left of row-spanning cell, it may be moved to
  29    * right side of the row-spanning cell after inserting some cell elements
  30    * before it.  Similarly, colspan won't be adjusted for keeping table
  31    * rectangle.
  32    * If first selection range is not in table cell element, this does nothing
  33    * without exception.
  34    *
  35    * @param aNumberOfCellssToInsert     Number of cells to insert.
  36    * @param aInsertAfterSelectedCell    true if new cells should be inserted
  37    *                                    before current cell.  Otherwise, will
  38    *                                    be inserted after the cell.
  39    */
  40   [can_run_script]
  41   void insertTableCell(in long aNumberOfColumnsToInsert,
  42                        in boolean aInsertAfterSelectedCell);
  43
  44   /**
  45    * insertTableColumn() inserts columns before or after a cell element
  46    * containing first selection range.  I.e., if the cell spans columns and
  47    * aInsertAfterSelectedCell is tre, new columns will be inserted after the
  48    * right-most column which contains the cell.  If first selection range is
  49    * not in table cell element, this does nothing without exception.
  50    *
  51    * @param aNumberOfColumnsToInsert    Number of columns to insert.
  52    * @param aInsertAfterSelectedCell    true if new columns will be inserted
  53    *                                    before current cell.  Otherwise, will
  54    *                                    be inserted after the cell.
  55    */
  56   [can_run_script]
  57   void insertTableColumn(in long aNumberOfColumnsToInsert,
  58                          in boolean aInsertAfterSelectedCell);
  59
  60   /*
  61    * insertTableRow() inserts <tr> elements before or after a <td> element
  62    * containing first selection range.  I.e., if the cell spans rows and
  63    * aInsertAfterSelectedCell is true, new rows will be inserted after the
  64    * bottom-most row which contains the cell.  If first selection range is
  65    * not in table cell element, this does nothing without exception.
  66    *
  67    * @param aNumberOfRowsToInsert       Number of rows to insert.
  68    * @param aInsertAfterSelectedCell    true if new rows will be inserted
  69    *                                    before current cell.  Otherwise, will
  70    *                                    be inserted after the cell.
  71    */
  72   [can_run_script]
  73   void insertTableRow(in long aNumberOfRowsToInsert,
  74                       in boolean aInsertAfterSelectedCell);
  75
  76   /** Delete table methods
  77     * Delete starting at the selected cell or the
  78     *  cell (or table) enclosing the selection anchor
  79     * The selection is collapsed and is left in the
  80     *  cell at the same row,col location as
  81     *  the previous selection anchor, if possible,
  82     *  else in the closest neigboring cell
  83     *
  84     * @param aNumber    Number of items to insert/delete
  85     */
  86   [can_run_script]
  87   void deleteTable();
  88
  89   /**
  90    * deleteTableCellContents() removes any contents in cell elements.  If two
  91    * or more cell elements are selected, this removes all selected cells'
  92    * contents.  Otherwise, this removes contents of a cell which contains
  93    * first selection range.  This does nothing without exception if selection
  94    * is not in cell element.
  95    */
  96   [can_run_script]
  97   void deleteTableCellContents();
  98
  99   /**
 100    * deleteTableCell() removes table cell elements.  If two or more cell
 101    * elements are selected, this removes all selected cell elements.
 102    * Otherwise, this removes some cell elements starting from selected cell
 103    * element or a cell containing first selection range.  When this removes
 104    * last cell element in <tr> or <table>, this removes the <tr> or the
 105    * <table> too.  Note that when removing a cell causes number of its row
 106    * becomes less than the others, this method does NOT fill the place with
 107    * rowspan nor colspan.  This does nothing without exception if selection is
 108    * not in cell element.
 109    *
 110    * @param aNumberOfCellsToDelete  Number of cells to remove.  This is ignored
 111    *                                if 2 or more cells are selected.
 112    */
 113   [can_run_script]
 114   void deleteTableCell(in long aNumberOfCellsToDelete);
 115
 116   /**
 117    * deleteTableColumn() removes cell elements which belong to same columns
 118    * of selected cell elements.
 119    * If only one cell element is selected or first selection range is
 120    * in a cell, removes cell elements which belong to same column.
 121    * If 2 or more cell elements are selected, removes cell elements which
 122    * belong to any of all selected columns.  In this case,
 123    * aNumberOfColumnsToDelete is ignored.
 124    * If there is no selection ranges, throws exception.
 125    * If selection is not in a cell element, just does nothing without
 126    * throwing exception.
 127    * WARNING: This does not remove <col> nor <colgroup> elements.
 128    *
 129    * @param aNumberOfColumnsToDelete    Number of columns to remove.  This is
 130    *                                    ignored if 2 ore more cells are
 131    *                                    selected.
 132    */
 133   [can_run_script]
 134   void deleteTableColumn(in long aNumberOfColumnsToDelete);
 135
 136   /**
 137    * deleteTableRow() removes <tr> elements.
 138    * If only one cell element is selected or first selection range is
 139    * in a cell, removes <tr> elements starting from a <tr> element
 140    * containing the selected cell or first selection range.
 141    * If 2 or more cell elements are selected, all <tr> elements
 142    * which contains selected cell(s).  In this case, aNumberOfRowsToDelete
 143    * is ignored.
 144    * If there is no selection ranges, throws exception.
 145    * If selection is not in a cell element, just does nothing without
 146    * throwing exception.
 147    *
 148    * @param aNumberOfRowsToDelete   Number of rows to remove.  This is ignored
 149    *                                if 2 or more cells are selected.
 150    */
 151   [can_run_script]
 152   void deleteTableRow(in long aNumberOfRowsToDelete);
 153
 154   /** Table Selection methods
 155     * Selecting a row or column actually
 156     * selects all cells (not TR in the case of rows)
 157     */
 158   [can_run_script]
 159   void selectTableCell();
 160
 161   /** Select a rectangular block of cells:
 162     *  all cells falling within the row/column index of aStartCell
 163     *  to through the row/column index of the aEndCell
 164     *  aStartCell can be any location relative to aEndCell,
 165     *   as long as they are in the same table
 166     *  @param aStartCell  starting cell in block
 167     *  @param aEndCell    ending cell in block
 168     */
 169   [can_run_script]
 170   void selectBlockOfCells(in Element aStartCell,
 171                           in Element aEndCell);
 172
 173   [can_run_script]
 174   void selectTableRow();
 175   [can_run_script]
 176   void selectTableColumn();
 177   [can_run_script]
 178   void selectTable();
 179   [can_run_script]
 180   void selectAllTableCells();
 181
 182   /** Create a new TD or TH element, the opposite type of the supplied aSourceCell
 183     *   1. Copy all attributes from aSourceCell to the new cell
 184     *   2. Move all contents of aSourceCell to the new cell
 185     *   3. Replace aSourceCell in the table with the new cell
 186     *
 187     *  @param aSourceCell   The cell to be replaced
 188     *  @return              The new cell that replaces aSourceCell
 189     */
 190   [can_run_script]
 191   Element switchTableCellHeaderType(in Element aSourceCell);
 192
 193   /** Merges contents of all selected cells
 194     * for selected cells that are adjacent,
 195     * this will result in a larger cell with appropriate
 196     * rowspan and colspan, and original cells are deleted
 197     * The resulting cell is in the location of the
 198     *   cell at the upper-left corner of the adjacent
 199     *   block of selected cells
 200     *
 201     * @param aMergeNonContiguousContents:
 202     *       If true:
 203     *         Non-contiguous cells are not deleted,
 204     *         but their contents are still moved
 205     *         to the upper-left cell
 206     *       If false: contiguous cells are ignored
 207     *
 208     * If there are no selected cells,
 209     *   and selection or caret is in a cell,
 210     *   that cell and the one to the right
 211     *   are merged
 212     */
 213   [can_run_script]
 214   void joinTableCells(in boolean aMergeNonContiguousContents);
 215
 216   /** Split a cell that has rowspan and/or colspan > 0
 217     *   into cells such that all new cells have
 218     *   rowspan = 1 and colspan = 1
 219     *  All of the contents are not touched --
 220     *   they will appear to be in the upper-left cell
 221     */
 222   [can_run_script]
 223   void splitTableCell();
 224
 225   /** Scan through all rows and add cells as needed so
 226     *   all locations in the cellmap are occupied.
 227     *   Used after inserting single cells or pasting
 228     *   a collection of cells that extend past the
 229     *   previous size of the table
 230     * If aTable is null, it uses table enclosing the selection anchor
 231     * This doesn't doesn't change the selection,
 232     *   thus it can be used to fixup all tables
 233     *   in a page independent of the selection
 234     */
 235   [can_run_script]
 236   void normalizeTable(in Element aTable);
 237
 238   /**
 239    * getCellIndexes() computes row index and column index of a table cell.
 240    * Note that this depends on layout information.  Therefore, all pending
 241    * layout should've been flushed before calling this.
 242    *
 243    * @param aCellElement        If not null, this computes indexes of the cell.
 244    *                            If null, this computes indexes of a cell which
 245    *                            contains anchor of Selection.
 246    * @param aRowIndex           Must be an object, whose .value will be set
 247    *                            to row index of the cell.  0 is the first row.
 248    *                            If rowspan is set to 2 or more, the start
 249    *                            row index is used.
 250    * @param aColumnIndex        Must be an object, whose .value will be set
 251    *                            to column index of the cell.  0 is the first
 252    *                            column.  If colspan is set to 2 or more, the
 253    *                            start column index is used.
 254    */
 255   void getCellIndexes(in Element aCellElement,
 256                       out long aRowIndex, out long aColumnIndex);
 257
 258   /**
 259    * getTableSize() computes number of rows and columns.
 260    * Note that this depends on layout information.  Therefore, all pending
 261    * layout should've been flushed before calling this.
 262    *
 263    * @param aTableOrElementInTable  If a <table> element, this computes number
 264    *                                of rows and columns of it.
 265    *                                If another element and in a <table>, this
 266    *                                computes number of rows and columns of
 267    *                                the nearest ancestor <table> element.
 268    *                                If element is not in <table> element,
 269    *                                throwing an exception.
 270    *                                If null, this looks for nearest ancestor
 271    *                                <table> element containing anchor of
 272    *                                Selection.  If found, computes the number
 273    *                                of rows and columns of the <table>.
 274    *                                Otherwise, throwing an exception.
 275    * @param aRowCount               Number of *actual* row count.
 276    *                                I.e., rowspan does NOT increase this value.
 277    * @param aColumnCount            Number of column count.
 278    *                                I.e., if colspan is specified with bigger
 279    *                                number than actual, the value is used
 280    *                                as this.
 281    */
 282   void getTableSize(in Element aTableOrElementInTable,
 283                     out long aRowCount, out long aColCount);
 284
 285   /**
 286    * getCellAt() returns a <td> or <th> element in a <table> if there is a
 287    * cell at the indexes.
 288    *
 289    * @param aTableElement       If not null, must be a <table> element.
 290    *                            If null, looks for the nearest ancestor <table>
 291    *                            to look for a cell.
 292    * @param aRowIndex           Row index of the cell.
 293    * @param aColumnIndex        Column index of the cell.
 294    * @return                    Returns a <td> or <th> element if there is.
 295    *                            Otherwise, returns null without throwing
 296    *                            exception.
 297    *                            If aTableElement is not null and not a <table>
 298    *                            element, throwing an exception.
 299    *                            If aTableElement is null and anchor of Selection
 300    *                            is not in any <table> element, throwing an
 301    *                            exception.
 302    */
 303   Element getCellAt(in Element aTableElement,
 304                     in long aRowIndex, in long aColumnIndex);
 305
 306   /**
 307    * Get cell element and its various information from <table> element and
 308    * indexes in it.  If aTableElement is null, this looks for an ancestor
 309    * <table> element of anchor of Selection.  If there is no <table> element
 310    * at that point, this throws exception.  Note that this requires layout
 311    * information.  So, you need to flush the layout after changing the DOM
 312    * tree.
 313    * If there is no cell element at the indexes, this throws exception.
 314    * XXX Perhaps, this is wrong behavior, this should return null without
 315    *     exception since the caller cannot distinguish whether the exception
 316    *     is caused by "not found" or other unexpected situation.
 317    *
 318    * @param aTableElement       A <table> element.  If this is null, this
 319    *                            uses ancestor of anchor of Selection.
 320    * @param aRowIndex           Row index in aTableElement.  Starting from 0.
 321    * @param aColumnIndex        Column index in aTableElement.  Starting from
 322    *                            0.
 323    * @param aCellElement        [OUT] The cell element at the indexes.
 324    * @param aStartRowIndex      [OUT] First row index which contains
 325    *                            aCellElement.  E.g., if the cell's rowspan is
 326    *                            not 1, this returns its first row index.
 327    *                            I.e., this can be smaller than aRowIndex.
 328    * @param aStartColumnIndex   [OUT] First column index which contains the
 329    *                            aCellElement.  E.g., if the cell's colspan is
 330    *                            larger than 1, this returns its first column
 331    *                            index.  I.e., this can be smaller than
 332    *                            aColumIndex.
 333    * @param aRowSpan            [OUT] rowspan attribute value in most cases.
 334    *                            If the specified value is invalid, this
 335    *                            returns 1.  Only when the document is written
 336    *                            in HTML5 or later, this can be 0.
 337    * @param aColSpan            [OUT] colspan attribute value in most cases.
 338    *                            If the specified value is invalid, this
 339    *                            returns 1.
 340    * @param aEffectiveRowSpan   [OUT] Effective rowspan value at aRowIndex.
 341    *                            This is same as:
 342    *                              aRowSpan - (aRowIndex - aStartRowIndex)
 343    * @param aEffectiveColSpan   [OUT] Effective colspan value at aColumnIndex.
 344    *                            This is same as:
 345    *                              aColSpan - (aColumnIndex - aStartColumnIndex)
 346    * @param aIsSelected         [OUT] Returns true if aCellElement or its
 347    *                            <tr> or <table> element is selected.
 348    *                            Otherwise, e.g., aCellElement just contains
 349    *                            selection range, returns false.
 350    */
 351   void getCellDataAt(in Element aTableElement,
 352                      in long aRowIndex, in long aColumnIndex,
 353                      out Element aCellElement,
 354                      out long aStartRowIndex, out long aStartColumnIndex,
 355                      out long aRowSpan, out long aColSpan,
 356                      out long aEffectiveRowSpan, out long aEffectiveColSpan,
 357                      out boolean aIsSelected);
 358
 359   /**
 360    * getFirstRow() returns first <tr> element in a <table> element.
 361    *
 362    * @param aTableOrElementInTable  If a <table> element, returns its first
 363    *                                <tr> element.
 364    *                                If another element, looks for nearest
 365    *                                ancestor <table> element first.  Then,
 366    *                                return its first <tr> element.
 367    * @return                        <tr> element in the <table> element.
 368    *                                If <table> element is not found, this
 369    *                                throws an exception.
 370    *                                If there is a <table> element but it
 371    *                                does not have <tr> elements, returns
 372    *                                null without throwing exception.
 373    *                                Note that this may return anonymous <tr>
 374    *                                element if <table> has one or more cells
 375    *                                but <tr> element is not in the source.
 376    */
 377   Element getFirstRow(in Element aTableElement);
 378
 379   /** Preferred direction to search for neighboring cell
 380     * when trying to locate a cell to place caret in after
 381     * a table editing action.
 382     * Used for aDirection param in SetSelectionAfterTableEdit
 383     */
 384
 385   /**
 386    * getSelectedOrParentTableElement() returns a <td>, <th>, <tr> or <table>.
 387    * If first selection range selects a <td> or <th>, returns it.  aTagName
 388    * is set to "td" even if the result is a <th> and aCount is set to
 389    * Selection.rangeCount.
 390    * If first selection range does not select <td> nor <th>, but selection
 391    * anchor refers <table>, returns it.  aTagName is set to "table" and
 392    * aCount is set to 1.
 393    * If first selection range does not select <td> nor <th>, but selection
 394    * anchor refers <tr>, returns it.  aTagName is set to "tr" and aCount is
 395    * set to 1.
 396    * If first selection range does not select <td> nor <th>, but selection
 397    * anchor refers <td> (not include <th>!), returns it.  aTagName is set to
 398    * "td" and aCount is set to 0.
 399    * Otherwise, if container of selection anchor is in a <td> or <th>,
 400    * returns it.  aTagName is set to "td" but aCount is set to 0.
 401    * Otherwise, returns null, aTagName is set to empty string and aCount is
 402    * set to 0.  I.e., does not throw exception even if a cell is not found.
 403    * NOTE: Calling this resets internal counter of getFirstSelectedCell()
 404    *       and getNextSelectedCell().  I.e., getNextSelectedCell() will
 405    *       return second selected cell element.
 406    */
 407   Element getSelectedOrParentTableElement(out AString aTagName,
 408                                           out long aCount);
 409
 410   /** Generally used after GetSelectedOrParentTableElement
 411     *   to test if selected cells are complete rows or columns
 412     *
 413     * @param aElement           Any table or cell element or any element
 414     *                           inside a table
 415     *                           Used to get enclosing table.
 416     *                           If null, selection's anchorNode is used
 417     *
 418     * @return
 419     *     0                        aCellElement was not a cell
 420     *                              (returned result = NS_ERROR_FAILURE)
 421     *     TableSelection::Cell     There are 1 or more cells selected but
 422     *                              complete rows or columns are not selected
 423     *     TableSelection::Row      All cells are in 1 or more rows
 424     *                              and in each row, all cells selected
 425     *                              Note: This is the value if all rows
 426     *                              (thus all cells) are selected
 427     *     TableSelection::Column   All cells are in 1 or more columns
 428     *                              and in each column, all cells are selected
 429     */
 430   uint32_t getSelectedCellsType(in Element aElement);
 431
 432   /**
 433    * getFirstSelectedCell() returns a <td> or <th> element if first range of
 434    * Selection selects only one table cell element (i.e., startContainer and
 435    * endContainer are same <tr> element and startOffset + 1 equals endOffset).
 436    * If first range of Selection does not select a table cell element, this
 437    * returns null.  However, if Selection has no range, this throws an
 438    * exception.
 439    *
 440    * @param aFirstRangeOfSelection [OUT] Returns the first range of Selection
 441    *                               only when this returns a <td> or <th>
 442    *                               element.  Otherwise, returns null.
 443    * @return                       A <td> or <th> element if first range of
 444    *                               Selection selects only one table cell
 445    *                               element.
 446    */
 447   Element getFirstSelectedCell(out Range aFirstRangeOfSelection);
 448
 449   /**
 450    * getFirstSelectedCellInTable() returns a cell element, its row index and
 451    * its column index if first range of Selection selects a cell.  Note that
 452    * that "selects a cell" means that the range container is a <tr> element
 453    * and endOffset is startOffset + 1.  So, even if first range of Selection
 454    * is in a cell element, this treats the range does not select a cell.
 455    * NOTE: Calling this resets internal counter of getFirstSelectedCell()
 456    *       and getNextSelectedCell().  I.e., getNextSelectedCell() will
 457    *       return second selected cell element.
 458    *
 459    * @param aRowIndex    [OUT} Returns row index of the found cell.  If not
 460    *                     found, returns 0.
 461    * @param aColumnIndex [OUT] Returns column index of the found cell.  If
 462    *                     not found, returns 0.
 463    * @return             The cell element which is selected by the first
 464    *                     range of Selection.  Even if this is not found,
 465    *                     this returns null, not throwing exception.
 466    */
 467   Element getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
 468
 469   /**
 470    * getNextSelectedCell() is a stateful method to retrieve selected table
 471    * cell elements which are selected by 2nd or later ranges of Selection.
 472    * When you call getFirstSelectedCell(), it resets internal counter of
 473    * this method.  Then, following calls of getNextSelectedCell() scans the
 474    * remaining ranges of Selection.  If a range selects a <td> or <th>
 475    * element, returns the cell element.  If a range selects an element but
 476    * neither <td> nor <th> element, this ignores the range.  If a range is
 477    * in a text node, returns null without throwing exception, but stops
 478    * scanning the remaining ranges even you call this again.
 479    * Note that this may cross <table> boundaries since this method just
 480    * scans all ranges of Selection.  Therefore, returning cells which
 481    * belong to different <table> elements.
 482    *
 483    * @param aNextSelectedCellRange [OUT] Returns null if this method returns
 484    *                               null.  Otherwise, i.e., found a range which
 485    *                               selects a <td> or <th> element, returns the
 486    *                               range.
 487    * @return                       A <td> or <th> element if one of remaining
 488    *                               ranges selects a <td> or <th> element unless
 489    *                               this does not meet a range in a text node.
 490    */
 491   Element getNextSelectedCell(out Range aNextSelectedCellRange);
 492 };