Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 460 insertions, 0 deletions

diff --git a/editor/nsITableEditor.idl b/editor/nsITableEditor.idl
new file mode 100644
index 0000000000..cf5e3bf8b0
--- /dev/null
+++ b/editor/nsITableEditor.idl
@@ -0,0 +1,460 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+
+#include "nsISupports.idl"
+
+webidl Element;
+webidl Node;
+webidl Range;
+
+[scriptable, builtinclass, uuid(4805e684-49b9-11d3-9ce4-ed60bd6cb5bc)]
+interface nsITableEditor : nsISupports
+{
+  const short eNoSearch = 0;
+  const short ePreviousColumn = 1;
+  const short ePreviousRow = 2;
+
+  /**
+   * insertTableCell() inserts <td> elements before or after a cell element
+   * containing first selection range.  I.e., if the cell spans columns and
+   * aInsertPosition is true, new columns will be inserted after the
+   * right-most column which contains the cell.  Note that this simply
+   * inserts <td> elements, i.e., colspan and rowspan around the cell
+   * containing selection are not modified.  So, for example, adding a cell
+   * to rectangular table changes non-rectangular table.  And if a cell
+   * containing selection is at left of row-spanning cell, it may be moved to
+   * right side of the row-spanning cell after inserting some cell elements
+   * before it.  Similarly, colspan won't be adjusted for keeping table
+   * rectangle.
+   * If first selection range is not in table cell element, this does nothing
+   * without exception.
+   *
+   * @param aNumberOfCellssToInsert     Number of cells to insert.
+   * @param aInsertAfterSelectedCell    true if new cells should be inserted
+   *                                    before current cell.  Otherwise, will
+   *                                    be inserted after the cell.
+   */
+  [can_run_script]
+  void insertTableCell(in long aNumberOfColumnsToInsert,
+                       in boolean aInsertAfterSelectedCell);
+
+  /**
+   * insertTableColumn() inserts columns before or after a cell element
+   * containing first selection range.  I.e., if the cell spans columns and
+   * aInsertAfterSelectedCell is tre, new columns will be inserted after the
+   * right-most column which contains the cell.  If first selection range is
+   * not in table cell element, this does nothing without exception.
+   *
+   * @param aNumberOfColumnsToInsert    Number of columns to insert.
+   * @param aInsertAfterSelectedCell    true if new columns will be inserted
+   *                                    before current cell.  Otherwise, will
+   *                                    be inserted after the cell.
+   */
+  [can_run_script]
+  void insertTableColumn(in long aNumberOfColumnsToInsert,
+                         in boolean aInsertAfterSelectedCell);
+
+  /*
+   * insertTableRow() inserts <tr> elements before or after a <td> element
+   * containing first selection range.  I.e., if the cell spans rows and
+   * aInsertAfterSelectedCell is true, new rows will be inserted after the
+   * bottom-most row which contains the cell.  If first selection range is
+   * not in table cell element, this does nothing without exception.
+   *
+   * @param aNumberOfRowsToInsert       Number of rows to insert.
+   * @param aInsertAfterSelectedCell    true if new rows will be inserted
+   *                                    before current cell.  Otherwise, will
+   *                                    be inserted after the cell.
+   */
+  [can_run_script]
+  void insertTableRow(in long aNumberOfRowsToInsert,
+                      in boolean aInsertAfterSelectedCell);
+
+  /** Delete table methods
+    * Delete starting at the selected cell or the
+    *  cell (or table) enclosing the selection anchor
+    * The selection is collapsed and is left in the
+    *  cell at the same row,col location as
+    *  the previous selection anchor, if possible,
+    *  else in the closest neighboring cell
+    *
+    * @param aNumber    Number of items to insert/delete
+    */
+  [can_run_script]
+  void deleteTable();
+
+  /**
+   * deleteTableCellContents() removes any contents in cell elements.  If two
+   * or more cell elements are selected, this removes all selected cells'
+   * contents.  Otherwise, this removes contents of a cell which contains
+   * first selection range.  This does nothing without exception if selection
+   * is not in cell element.
+   */
+  [can_run_script]
+  void deleteTableCellContents();
+
+  /**
+   * deleteTableCell() removes table cell elements.  If two or more cell
+   * elements are selected, this removes all selected cell elements.
+   * Otherwise, this removes some cell elements starting from selected cell
+   * element or a cell containing first selection range.  When this removes
+   * last cell element in <tr> or <table>, this removes the <tr> or the
+   * <table> too.  Note that when removing a cell causes number of its row
+   * becomes less than the others, this method does NOT fill the place with
+   * rowspan nor colspan.  This does nothing without exception if selection is
+   * not in cell element.
+   *
+   * @param aNumberOfCellsToDelete  Number of cells to remove.  This is ignored
+   *                                if 2 or more cells are selected.
+   */
+  [can_run_script]
+  void deleteTableCell(in long aNumberOfCellsToDelete);
+
+  /**
+   * deleteTableColumn() removes cell elements which belong to same columns
+   * of selected cell elements.
+   * If only one cell element is selected or first selection range is
+   * in a cell, removes cell elements which belong to same column.
+   * If 2 or more cell elements are selected, removes cell elements which
+   * belong to any of all selected columns.  In this case,
+   * aNumberOfColumnsToDelete is ignored.
+   * If there is no selection ranges, throws exception.
+   * If selection is not in a cell element, just does nothing without
+   * throwing exception.
+   * WARNING: This does not remove <col> nor <colgroup> elements.
+   *
+   * @param aNumberOfColumnsToDelete    Number of columns to remove.  This is
+   *                                    ignored if 2 ore more cells are
+   *                                    selected.
+   */
+  [can_run_script]
+  void deleteTableColumn(in long aNumberOfColumnsToDelete);
+
+  /**
+   * deleteTableRow() removes <tr> elements.
+   * If only one cell element is selected or first selection range is
+   * in a cell, removes <tr> elements starting from a <tr> element
+   * containing the selected cell or first selection range.
+   * If 2 or more cell elements are selected, all <tr> elements
+   * which contains selected cell(s).  In this case, aNumberOfRowsToDelete
+   * is ignored.
+   * If there is no selection ranges, throws exception.
+   * If selection is not in a cell element, just does nothing without
+   * throwing exception.
+   *
+   * @param aNumberOfRowsToDelete   Number of rows to remove.  This is ignored
+   *                                if 2 or more cells are selected.
+   */
+  [can_run_script]
+  void deleteTableRow(in long aNumberOfRowsToDelete);
+
+  /** Table Selection methods
+    * Selecting a row or column actually
+    * selects all cells (not TR in the case of rows)
+    */
+  [can_run_script]
+  void selectTableCell();
+
+  [can_run_script]
+  void selectTableRow();
+  [can_run_script]
+  void selectTableColumn();
+  [can_run_script]
+  void selectTable();
+  [can_run_script]
+  void selectAllTableCells();
+
+  /** Create a new TD or TH element, the opposite type of the supplied aSourceCell
+    *   1. Copy all attributes from aSourceCell to the new cell
+    *   2. Move all contents of aSourceCell to the new cell
+    *   3. Replace aSourceCell in the table with the new cell
+    *
+    *  @param aSourceCell   The cell to be replaced
+    *  @return              The new cell that replaces aSourceCell
+    */
+  [can_run_script]
+  Element switchTableCellHeaderType(in Element aSourceCell);
+
+  /** Merges contents of all selected cells
+    * for selected cells that are adjacent,
+    * this will result in a larger cell with appropriate
+    * rowspan and colspan, and original cells are deleted
+    * The resulting cell is in the location of the
+    *   cell at the upper-left corner of the adjacent
+    *   block of selected cells
+    *
+    * @param aMergeNonContiguousContents:
+    *       If true:
+    *         Non-contiguous cells are not deleted,
+    *         but their contents are still moved
+    *         to the upper-left cell
+    *       If false: contiguous cells are ignored
+    *
+    * If there are no selected cells,
+    *   and selection or caret is in a cell,
+    *   that cell and the one to the right
+    *   are merged
+    */
+  [can_run_script]
+  void joinTableCells(in boolean aMergeNonContiguousContents);
+
+  /** Split a cell that has rowspan and/or colspan > 0
+    *   into cells such that all new cells have
+    *   rowspan = 1 and colspan = 1
+    *  All of the contents are not touched --
+    *   they will appear to be in the upper-left cell
+    */
+  [can_run_script]
+  void splitTableCell();
+
+  /** Scan through all rows and add cells as needed so
+    *   all locations in the cellmap are occupied.
+    *   Used after inserting single cells or pasting
+    *   a collection of cells that extend past the
+    *   previous size of the table
+    * If aTable is null, it uses table enclosing the selection anchor
+    * This doesn't doesn't change the selection,
+    *   thus it can be used to fixup all tables
+    *   in a page independent of the selection
+    */
+  [can_run_script]
+  void normalizeTable(in Element aTable);
+
+  /**
+   * getCellIndexes() computes row index and column index of a table cell.
+   * Note that this depends on layout information.  Therefore, all pending
+   * layout should've been flushed before calling this.
+   *
+   * @param aCellElement        If not null, this computes indexes of the cell.
+   *                            If null, this computes indexes of a cell which
+   *                            contains anchor of Selection.
+   * @param aRowIndex           Must be an object, whose .value will be set
+   *                            to row index of the cell.  0 is the first row.
+   *                            If rowspan is set to 2 or more, the start
+   *                            row index is used.
+   * @param aColumnIndex        Must be an object, whose .value will be set
+   *                            to column index of the cell.  0 is the first
+   *                            column.  If colspan is set to 2 or more, the
+   *                            start column index is used.
+   */
+  [can_run_script]
+  void getCellIndexes(in Element aCellElement,
+                      out long aRowIndex, out long aColumnIndex);
+
+  /**
+   * getTableSize() computes number of rows and columns.
+   * Note that this depends on layout information.  Therefore, all pending
+   * layout should've been flushed before calling this.
+   *
+   * @param aTableOrElementInTable  If a <table> element, this computes number
+   *                                of rows and columns of it.
+   *                                If another element and in a <table>, this
+   *                                computes number of rows and columns of
+   *                                the nearest ancestor <table> element.
+   *                                If element is not in <table> element,
+   *                                throwing an exception.
+   *                                If null, this looks for nearest ancestor
+   *                                <table> element containing anchor of
+   *                                Selection.  If found, computes the number
+   *                                of rows and columns of the <table>.
+   *                                Otherwise, throwing an exception.
+   * @param aRowCount               Number of *actual* row count.
+   *                                I.e., rowspan does NOT increase this value.
+   * @param aColumnCount            Number of column count.
+   *                                I.e., if colspan is specified with bigger
+   *                                number than actual, the value is used
+   *                                as this.
+   */
+  [can_run_script]
+  void getTableSize(in Element aTableOrElementInTable,
+                    out long aRowCount, out long aColCount);
+
+  /**
+   * getCellAt() returns a <td> or <th> element in a <table> if there is a
+   * cell at the indexes.
+   *
+   * @param aTableElement       If not null, must be a <table> element.
+   *                            If null, looks for the nearest ancestor <table>
+   *                            to look for a cell.
+   * @param aRowIndex           Row index of the cell.
+   * @param aColumnIndex        Column index of the cell.
+   * @return                    Returns a <td> or <th> element if there is.
+   *                            Otherwise, returns null without throwing
+   *                            exception.
+   *                            If aTableElement is not null and not a <table>
+   *                            element, throwing an exception.
+   *                            If aTableElement is null and anchor of Selection
+   *                            is not in any <table> element, throwing an
+   *                            exception.
+   */
+  [can_run_script]
+  Element getCellAt(in Element aTableElement,
+                    in long aRowIndex, in long aColumnIndex);
+
+  /**
+   * Get cell element and its various information from <table> element and
+   * indexes in it.  If aTableElement is null, this looks for an ancestor
+   * <table> element of anchor of Selection.  If there is no <table> element
+   * at that point, this throws exception.  Note that this requires layout
+   * information.  So, you need to flush the layout after changing the DOM
+   * tree.
+   * If there is no cell element at the indexes, this throws exception.
+   * XXX Perhaps, this is wrong behavior, this should return null without
+   *     exception since the caller cannot distinguish whether the exception
+   *     is caused by "not found" or other unexpected situation.
+   *
+   * @param aTableElement       A <table> element.  If this is null, this
+   *                            uses ancestor of anchor of Selection.
+   * @param aRowIndex           Row index in aTableElement.  Starting from 0.
+   * @param aColumnIndex        Column index in aTableElement.  Starting from
+   *                            0.
+   * @param aCellElement        [OUT] The cell element at the indexes.
+   * @param aStartRowIndex      [OUT] First row index which contains
+   *                            aCellElement.  E.g., if the cell's rowspan is
+   *                            not 1, this returns its first row index.
+   *                            I.e., this can be smaller than aRowIndex.
+   * @param aStartColumnIndex   [OUT] First column index which contains the
+   *                            aCellElement.  E.g., if the cell's colspan is
+   *                            larger than 1, this returns its first column
+   *                            index.  I.e., this can be smaller than
+   *                            aColumIndex.
+   * @param aRowSpan            [OUT] rowspan attribute value in most cases.
+   *                            If the specified value is invalid, this
+   *                            returns 1.  Only when the document is written
+   *                            in HTML5 or later, this can be 0.
+   * @param aColSpan            [OUT] colspan attribute value in most cases.
+   *                            If the specified value is invalid, this
+   *                            returns 1.
+   * @param aEffectiveRowSpan   [OUT] Effective rowspan value at aRowIndex.
+   *                            This is same as:
+   *                              aRowSpan - (aRowIndex - aStartRowIndex)
+   * @param aEffectiveColSpan   [OUT] Effective colspan value at aColumnIndex.
+   *                            This is same as:
+   *                              aColSpan - (aColumnIndex - aStartColumnIndex)
+   * @param aIsSelected         [OUT] Returns true if aCellElement or its
+   *                            <tr> or <table> element is selected.
+   *                            Otherwise, e.g., aCellElement just contains
+   *                            selection range, returns false.
+   */
+  [can_run_script]
+  void getCellDataAt(in Element aTableElement,
+                     in long aRowIndex, in long aColumnIndex,
+                     out Element aCellElement,
+                     out long aStartRowIndex, out long aStartColumnIndex,
+                     out long aRowSpan, out long aColSpan,
+                     out long aEffectiveRowSpan, out long aEffectiveColSpan,
+                     out boolean aIsSelected);
+
+  /**
+   * getFirstRow() returns first <tr> element in a <table> element.
+   *
+   * @param aTableOrElementInTable  If a <table> element, returns its first
+   *                                <tr> element.
+   *                                If another element, looks for nearest
+   *                                ancestor <table> element first.  Then,
+   *                                return its first <tr> element.
+   * @return                        <tr> element in the <table> element.
+   *                                If <table> element is not found, this
+   *                                throws an exception.
+   *                                If there is a <table> element but it
+   *                                does not have <tr> elements, returns
+   *                                null without throwing exception.
+   *                                Note that this may return anonymous <tr>
+   *                                element if <table> has one or more cells
+   *                                but <tr> element is not in the source.
+   */
+  [can_run_script]
+  Element getFirstRow(in Element aTableElement);
+
+  /** Preferred direction to search for neighboring cell
+    * when trying to locate a cell to place caret in after
+    * a table editing action.
+    * Used for aDirection param in SetSelectionAfterTableEdit
+    */
+
+  /**
+   * getSelectedOrParentTableElement() returns a <td>, <th>, <tr> or <table>.
+   * If first selection range selects a <td> or <th>, returns it.  aTagName
+   * is set to "td" even if the result is a <th> and aCount is set to
+   * Selection.rangeCount.
+   * If first selection range does not select <td> nor <th>, but selection
+   * anchor refers <table>, returns it.  aTagName is set to "table" and
+   * aCount is set to 1.
+   * If first selection range does not select <td> nor <th>, but selection
+   * anchor refers <tr>, returns it.  aTagName is set to "tr" and aCount is
+   * set to 1.
+   * If first selection range does not select <td> nor <th>, but selection
+   * anchor refers <td> (not include <th>!), returns it.  aTagName is set to
+   * "td" and aCount is set to 0.
+   * Otherwise, if container of selection anchor is in a <td> or <th>,
+   * returns it.  aTagName is set to "td" but aCount is set to 0.
+   * Otherwise, returns null, aTagName is set to empty string and aCount is
+   * set to 0.  I.e., does not throw exception even if a cell is not found.
+   * NOTE: Calling this resets internal counter of getFirstSelectedCell()
+   *       and getNextSelectedCell().  I.e., getNextSelectedCell() will
+   *       return second selected cell element.
+   */
+  [can_run_script]
+  Element getSelectedOrParentTableElement(out AString aTagName,
+                                          out long aCount);
+
+  /** Generally used after GetSelectedOrParentTableElement
+    *   to test if selected cells are complete rows or columns
+    *
+    * @param aElement           Any table or cell element or any element
+    *                           inside a table
+    *                           Used to get enclosing table.
+    *                           If null, selection's anchorNode is used
+    *
+    * @return
+    *     0                        aCellElement was not a cell
+    *                              (returned result = NS_ERROR_FAILURE)
+    *     TableSelectionMode::Cell     There are 1 or more cells selected but
+    *                              complete rows or columns are not selected
+    *     TableSelectionMode::Row      All cells are in 1 or more rows
+    *                              and in each row, all cells selected
+    *                              Note: This is the value if all rows
+    *                              (thus all cells) are selected
+    *     TableSelectionMode::Column   All cells are in 1 or more columns
+    *                              and in each column, all cells are selected
+    */
+  [can_run_script]
+  uint32_t getSelectedCellsType(in Element aElement);
+
+  /**
+   * getFirstSelectedCellInTable() returns a cell element, its row index and
+   * its column index if first range of Selection selects a cell.  Note that
+   * that "selects a cell" means that the range container is a <tr> element
+   * and endOffset is startOffset + 1.  So, even if first range of Selection
+   * is in a cell element, this treats the range does not select a cell.
+   * NOTE: Calling this resets internal counter of getFirstSelectedCell()
+   *       and getNextSelectedCell().  I.e., getNextSelectedCell() will
+   *       return second selected cell element.
+   *
+   * @param aRowIndex    [OUT} Returns row index of the found cell.  If not
+   *                     found, returns 0.
+   * @param aColumnIndex [OUT] Returns column index of the found cell.  If
+   *                     not found, returns 0.
+   * @return             The cell element which is selected by the first
+   *                     range of Selection.  Even if this is not found,
+   *                     this returns null, not throwing exception.
+   */
+  [can_run_script]
+  Element getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
+
+  /**
+   * getSelectedCells() returns an array of `<td>` and `<th>` elements which
+   * are selected in **any** `<table>` elements (i.e., some cells may be
+   * in different `<table>` element).
+   * If first range does not select a table cell element, this returns empty
+   * array because editor considers that selection is not in table cell
+   * selection mode.
+   * If second or later ranges do not select only a table cell element, this
+   * ignores the ranges.
+   */
+  [can_run_script]
+  Array<Element> getSelectedCells();
+};