1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/editor/idl/nsITableEditor.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,337 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIDOMNode;
1.13 +interface nsIDOMElement;
1.14 +interface nsIDOMRange;
1.15 +
1.16 +[scriptable, uuid(4805e684-49b9-11d3-9ce4-ed60bd6cb5bc)]
1.17 +
1.18 +interface nsITableEditor : nsISupports
1.19 +{
1.20 + const short eNoSearch = 0;
1.21 + const short ePreviousColumn = 1;
1.22 + const short ePreviousRow = 2;
1.23 +
1.24 + /* ------------ Table editing Methods -------------- */
1.25 +
1.26 + /** Insert table methods
1.27 + * Insert relative to the selected cell or the
1.28 + * cell enclosing the selection anchor
1.29 + * The selection is collapsed and is left in the new cell
1.30 + * at the same row,col location as the original anchor cell
1.31 + *
1.32 + * @param aNumber Number of items to insert
1.33 + * @param aAfter If TRUE, insert after the current cell,
1.34 + * else insert before current cell
1.35 + */
1.36 + void insertTableCell(in long aNumber, in boolean aAfter);
1.37 + void insertTableColumn(in long aNumber, in boolean aAfter);
1.38 + void insertTableRow(in long aNumber, in boolean aAfter);
1.39 +
1.40 + /** Delete table methods
1.41 + * Delete starting at the selected cell or the
1.42 + * cell (or table) enclosing the selection anchor
1.43 + * The selection is collapsed and is left in the
1.44 + * cell at the same row,col location as
1.45 + * the previous selection anchor, if possible,
1.46 + * else in the closest neigboring cell
1.47 + *
1.48 + * @param aNumber Number of items to insert/delete
1.49 + */
1.50 + void deleteTable();
1.51 +
1.52 + /** Delete just the cell contents
1.53 + * This is what should happen when Delete key is used
1.54 + * for selected cells, to minimize upsetting the table layout
1.55 + */
1.56 + void deleteTableCellContents();
1.57 +
1.58 + /** Delete cell elements as well as contents
1.59 + * @param aNumber Number of contiguous cells, rows, or columns
1.60 + *
1.61 + * When there are more than 1 selected cells, aNumber is ignored.
1.62 + * For Delete Rows or Columns, the complete columns or rows are
1.63 + * determined by the selected cells. E.g., to delete 2 complete rows,
1.64 + * user simply selects a cell in each, and they don't
1.65 + * have to be contiguous.
1.66 + */
1.67 + void deleteTableCell(in long aNumber);
1.68 + void deleteTableColumn(in long aNumber);
1.69 + void deleteTableRow(in long aNumber);
1.70 +
1.71 + /** Table Selection methods
1.72 + * Selecting a row or column actually
1.73 + * selects all cells (not TR in the case of rows)
1.74 + */
1.75 + void selectTableCell();
1.76 +
1.77 + /** Select a rectangular block of cells:
1.78 + * all cells falling within the row/column index of aStartCell
1.79 + * to through the row/column index of the aEndCell
1.80 + * aStartCell can be any location relative to aEndCell,
1.81 + * as long as they are in the same table
1.82 + * @param aStartCell starting cell in block
1.83 + * @param aEndCell ending cell in block
1.84 + */
1.85 + void selectBlockOfCells(in nsIDOMElement aStartCell,
1.86 + in nsIDOMElement aEndCell);
1.87 +
1.88 + void selectTableRow();
1.89 + void selectTableColumn();
1.90 + void selectTable();
1.91 + void selectAllTableCells();
1.92 +
1.93 + /** Create a new TD or TH element, the opposite type of the supplied aSourceCell
1.94 + * 1. Copy all attributes from aSourceCell to the new cell
1.95 + * 2. Move all contents of aSourceCell to the new cell
1.96 + * 3. Replace aSourceCell in the table with the new cell
1.97 + *
1.98 + * @param aSourceCell The cell to be replaced
1.99 + * @return The new cell that replaces aSourceCell
1.100 + */
1.101 + nsIDOMElement switchTableCellHeaderType(in nsIDOMElement aSourceCell);
1.102 +
1.103 + /** Merges contents of all selected cells
1.104 + * for selected cells that are adjacent,
1.105 + * this will result in a larger cell with appropriate
1.106 + * rowspan and colspan, and original cells are deleted
1.107 + * The resulting cell is in the location of the
1.108 + * cell at the upper-left corner of the adjacent
1.109 + * block of selected cells
1.110 + *
1.111 + * @param aMergeNonContiguousContents:
1.112 + * If true:
1.113 + * Non-contiguous cells are not deleted,
1.114 + * but their contents are still moved
1.115 + * to the upper-left cell
1.116 + * If false: contiguous cells are ignored
1.117 + *
1.118 + * If there are no selected cells,
1.119 + * and selection or caret is in a cell,
1.120 + * that cell and the one to the right
1.121 + * are merged
1.122 + */
1.123 + void joinTableCells(in boolean aMergeNonContiguousContents);
1.124 +
1.125 + /** Split a cell that has rowspan and/or colspan > 0
1.126 + * into cells such that all new cells have
1.127 + * rowspan = 1 and colspan = 1
1.128 + * All of the contents are not touched --
1.129 + * they will appear to be in the upper-left cell
1.130 + */
1.131 + void splitTableCell();
1.132 +
1.133 + /** Scan through all rows and add cells as needed so
1.134 + * all locations in the cellmap are occupied.
1.135 + * Used after inserting single cells or pasting
1.136 + * a collection of cells that extend past the
1.137 + * previous size of the table
1.138 + * If aTable is null, it uses table enclosing the selection anchor
1.139 + * This doesn't doesn't change the selection,
1.140 + * thus it can be used to fixup all tables
1.141 + * in a page independent of the selection
1.142 + */
1.143 + void normalizeTable(in nsIDOMElement aTable);
1.144 +
1.145 + /** Get the row an column index from the layout's cellmap
1.146 + * If aCell is null, it will try to find enclosing table of selection anchor
1.147 + *
1.148 + */
1.149 + void getCellIndexes(in nsIDOMElement aCell,
1.150 + out long aRowIndex, out long aColIndex);
1.151 +
1.152 + /** Get the number of rows and columns in a table from the layout's cellmap
1.153 + * If aTable is null, it will try to find enclosing table of selection ancho
1.154 + * Note that all rows in table will not have this many because of
1.155 + * ROWSPAN effects or if table is not "rectangular" (has short rows)
1.156 + */
1.157 + void getTableSize(in nsIDOMElement aTable,
1.158 + out long aRowCount, out long aColCount);
1.159 +
1.160 + /** Get a cell element at cellmap grid coordinates
1.161 + * A cell that spans across multiple cellmap locations will
1.162 + * be returned multiple times, once for each location it occupies
1.163 + *
1.164 + * @param aTable A table in the document
1.165 + * @param aRowIndex, aColIndex The 0-based cellmap indexes
1.166 + *
1.167 + * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.168 + * passes NS_SUCCEEDED macro)
1.169 + *
1.170 + * You can scan for all cells in a row or column
1.171 + * by iterating through the appropriate indexes
1.172 + * until the returned aCell is null
1.173 + */
1.174 + nsIDOMElement getCellAt(in nsIDOMElement aTable,
1.175 + in long aRowIndex, in long aColIndex);
1.176 +
1.177 + /** Get a cell at cellmap grid coordinates and associated data
1.178 + * A cell that spans across multiple cellmap locations will
1.179 + * be returned multiple times, once for each location it occupies
1.180 + * Examine the returned aStartRowIndex and aStartColIndex to see
1.181 + * if it is in the same layout column or layout row:
1.182 + * A "layout row" is all cells sharing the same top edge
1.183 + * A "layout column" is all cells sharing the same left edge
1.184 + * This is important to determine what to do when inserting or deleting a column or row
1.185 + *
1.186 + * @param aTable A table in the document
1.187 + * @param aRowIndex, aColIndex The 0-based cellmap indexes
1.188 + * returns values:
1.189 + * @param aCell The cell at this cellmap location
1.190 + * @param aStartRowIndex The row index where cell starts
1.191 + * @param aStartColIndex The col index where cell starts
1.192 + * @param aRowSpan May be 0 (to span down entire table) or number of cells spanned
1.193 + * @param aColSpan May be 0 (to span across entire table) or number of cells spanned
1.194 + * @param aActualRowSpan The actual number of cellmap locations (rows) spanned by the cell
1.195 + * @param aActualColSpan The actual number of cellmap locations (columns) spanned by the cell
1.196 + * @param aIsSelected
1.197 + * @param
1.198 + *
1.199 + * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.200 + * passes NS_SUCCEEDED macro)
1.201 + */
1.202 + void getCellDataAt(in nsIDOMElement aTable,
1.203 + in long aRowIndex, in long aColIndex,
1.204 + out nsIDOMElement aCell,
1.205 + out long aStartRowIndex, out long aStartColIndex,
1.206 + out long aRowSpan, out long aColSpan,
1.207 + out long aActualRowSpan, out long aActualColSpan,
1.208 + out boolean aIsSelected);
1.209 +
1.210 + /** Get the first row element in a table
1.211 + *
1.212 + * @return The row at the requested index
1.213 + * Returns null if there are no rows in table
1.214 + * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.215 + * passes NS_SUCCEEDED macro)
1.216 + */
1.217 + nsIDOMNode getFirstRow(in nsIDOMElement aTableElement);
1.218 +
1.219 + /** Get the next row element starting the search from aTableElement
1.220 + *
1.221 + * @param aTableElement Any TR or child-of-TR element in the document
1.222 + *
1.223 + * @return The row to start search from
1.224 + * and the row returned from the search
1.225 + * Returns null if there isn't another row
1.226 + * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.227 + * passes NS_SUCCEEDED macro)
1.228 + */
1.229 + nsIDOMNode getNextRow(in nsIDOMNode aTableElement);
1.230 +
1.231 + /** Preferred direction to search for neighboring cell
1.232 + * when trying to locate a cell to place caret in after
1.233 + * a table editing action.
1.234 + * Used for aDirection param in SetSelectionAfterTableEdit
1.235 + */
1.236 +
1.237 + /** Reset a selected cell or collapsed selection (the caret) after table editing
1.238 + *
1.239 + * @param aTable A table in the document
1.240 + * @param aRow The row ...
1.241 + * @param aCol ... and column defining the cell
1.242 + * where we will try to place the caret
1.243 + * @param aSelected If true, we select the whole cell instead of setting caret
1.244 + * @param aDirection If cell at (aCol, aRow) is not found,
1.245 + * search for previous cell in the same
1.246 + * column (aPreviousColumn) or row (ePreviousRow)
1.247 + * or don't search for another cell (aNoSearch)
1.248 + * If no cell is found, caret is place just before table;
1.249 + * and if that fails, at beginning of document.
1.250 + * Thus we generally don't worry about the return value
1.251 + * and can use the nsSetSelectionAfterTableEdit stack-based
1.252 + * object to insure we reset the caret in a table-editing method.
1.253 + */
1.254 + void setSelectionAfterTableEdit(in nsIDOMElement aTable,
1.255 + in long aRow, in long aCol,
1.256 + in long aDirection, in boolean aSelected);
1.257 +
1.258 + /** Examine the current selection and find
1.259 + * a selected TABLE, TD or TH, or TR element.
1.260 + * or return the parent TD or TH if selection is inside a table cell
1.261 + * Returns null if no table element is found.
1.262 + *
1.263 + * @param aTagName The tagname of returned element
1.264 + * Note that "td" will be returned if name
1.265 + * is actually "th"
1.266 + * @param aCount How many table elements were selected
1.267 + * This tells us if we have multiple cells selected
1.268 + * (0 if element is a parent cell of selection)
1.269 + * @return The table element (table, row, or first selected cell)
1.270 + *
1.271 + */
1.272 + nsIDOMElement getSelectedOrParentTableElement(out AString aTagName, out long aCount);
1.273 +
1.274 + /** Generally used after GetSelectedOrParentTableElement
1.275 + * to test if selected cells are complete rows or columns
1.276 + *
1.277 + * @param aElement Any table or cell element or any element
1.278 + * inside a table
1.279 + * Used to get enclosing table.
1.280 + * If null, selection's anchorNode is used
1.281 + *
1.282 + * @return
1.283 + * 0 aCellElement was not a cell
1.284 + * (returned result = NS_ERROR_FAILURE)
1.285 + * TABLESELECTION_CELL There are 1 or more cells selected but
1.286 + * complete rows or columns are not selected
1.287 + * TABLESELECTION_ROW All cells are in 1 or more rows
1.288 + * and in each row, all cells selected
1.289 + * Note: This is the value if all rows
1.290 + * (thus all cells) are selected
1.291 + * TABLESELECTION_COLUMN All cells are in 1 or more columns
1.292 + * and in each column, all cells are selected
1.293 + */
1.294 + uint32_t getSelectedCellsType(in nsIDOMElement aElement);
1.295 +
1.296 + /** Get first selected element from first selection range.
1.297 + * (If multiple cells were selected this is the first in the order they were selected)
1.298 + * Assumes cell-selection model where each cell
1.299 + * is in a separate range (selection parent node is table row)
1.300 + * @param aCell [OUT] Selected cell or null if ranges don't contain
1.301 + * cell selections
1.302 + * @param aRange [OUT] Optional: if not null, return the selection range
1.303 + * associated with the cell
1.304 + * Returns the DOM cell element
1.305 + * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.306 + * passes NS_SUCCEEDED macro)
1.307 + */
1.308 + nsIDOMElement getFirstSelectedCell(out nsIDOMRange aRange);
1.309 +
1.310 + /** Get first selected element in the table
1.311 + * This is the upper-left-most selected cell in table,
1.312 + * ignoring the order that the user selected them (order in the selection ranges)
1.313 + * Assumes cell-selection model where each cell
1.314 + * is in a separate range (selection parent node is table row)
1.315 + * @param aCell Selected cell or null if ranges don't contain
1.316 + * cell selections
1.317 + * @param aRowIndex Optional: if not null, return row index of 1st cell
1.318 + * @param aColIndex Optional: if not null, return column index of 1st cell
1.319 + *
1.320 + * Returns the DOM cell element
1.321 + * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.322 + * passes NS_SUCCEEDED macro)
1.323 + */
1.324 + nsIDOMElement getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
1.325 +
1.326 + /** Get next selected cell element from first selection range.
1.327 + * Assumes cell-selection model where each cell
1.328 + * is in a separate range (selection parent node is table row)
1.329 + * Always call GetFirstSelectedCell() to initialize stored index of "next" cell
1.330 + * @param aCell Selected cell or null if no more selected cells
1.331 + * or ranges don't contain cell selections
1.332 + * @param aRange Optional: if not null, return the selection range
1.333 + * associated with the cell
1.334 + *
1.335 + * Returns the DOM cell element
1.336 + * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.337 + * passes NS_SUCCEEDED macro)
1.338 + */
1.339 + nsIDOMElement getNextSelectedCell(out nsIDOMRange aRange);
1.340 +};
