summaryrefslogtreecommitdiffstats
path: root/editor/nsITableEditor.idl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
commit6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch)
treea68f146d7fa01f0134297619fbe7e33db084e0aa /editor/nsITableEditor.idl
parentInitial commit. (diff)
downloadthunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.tar.xz
thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.zip
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--editor/nsITableEditor.idl460
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();
+};