nsITableEditor.idl (22268B)
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 neighboring 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 [can_run_script] 162 void selectTableRow(); 163 [can_run_script] 164 void selectTableColumn(); 165 [can_run_script] 166 void selectTable(); 167 [can_run_script] 168 void selectAllTableCells(); 169 170 /** Create a new TD or TH element, the opposite type of the supplied aSourceCell 171 * 1. Copy all attributes from aSourceCell to the new cell 172 * 2. Move all contents of aSourceCell to the new cell 173 * 3. Replace aSourceCell in the table with the new cell 174 * 175 * @param aSourceCell The cell to be replaced 176 * @return The new cell that replaces aSourceCell 177 */ 178 [can_run_script] 179 Element switchTableCellHeaderType(in Element aSourceCell); 180 181 /** Merges contents of all selected cells 182 * for selected cells that are adjacent, 183 * this will result in a larger cell with appropriate 184 * rowspan and colspan, and original cells are deleted 185 * The resulting cell is in the location of the 186 * cell at the upper-left corner of the adjacent 187 * block of selected cells 188 * 189 * @param aMergeNonContiguousContents: 190 * If true: 191 * Non-contiguous cells are not deleted, 192 * but their contents are still moved 193 * to the upper-left cell 194 * If false: contiguous cells are ignored 195 * 196 * If there are no selected cells, 197 * and selection or caret is in a cell, 198 * that cell and the one to the right 199 * are merged 200 */ 201 [can_run_script] 202 void joinTableCells(in boolean aMergeNonContiguousContents); 203 204 /** Split a cell that has rowspan and/or colspan > 0 205 * into cells such that all new cells have 206 * rowspan = 1 and colspan = 1 207 * All of the contents are not touched -- 208 * they will appear to be in the upper-left cell 209 */ 210 [can_run_script] 211 void splitTableCell(); 212 213 /** Scan through all rows and add cells as needed so 214 * all locations in the cellmap are occupied. 215 * Used after inserting single cells or pasting 216 * a collection of cells that extend past the 217 * previous size of the table 218 * If aTable is null, it uses table enclosing the selection anchor 219 * This doesn't doesn't change the selection, 220 * thus it can be used to fixup all tables 221 * in a page independent of the selection 222 */ 223 [can_run_script] 224 void normalizeTable(in Element aTable); 225 226 /** 227 * getCellIndexes() computes row index and column index of a table cell. 228 * Note that this depends on layout information. Therefore, all pending 229 * layout should've been flushed before calling this. 230 * 231 * @param aCellElement If not null, this computes indexes of the cell. 232 * If null, this computes indexes of a cell which 233 * contains anchor of Selection. 234 * @param aRowIndex Must be an object, whose .value will be set 235 * to row index of the cell. 0 is the first row. 236 * If rowspan is set to 2 or more, the start 237 * row index is used. 238 * @param aColumnIndex Must be an object, whose .value will be set 239 * to column index of the cell. 0 is the first 240 * column. If colspan is set to 2 or more, the 241 * start column index is used. 242 */ 243 [can_run_script] 244 void getCellIndexes(in Element aCellElement, 245 out long aRowIndex, out long aColumnIndex); 246 247 /** 248 * getTableSize() computes number of rows and columns. 249 * Note that this depends on layout information. Therefore, all pending 250 * layout should've been flushed before calling this. 251 * 252 * @param aTableOrElementInTable If a <table> element, this computes number 253 * of rows and columns of it. 254 * If another element and in a <table>, this 255 * computes number of rows and columns of 256 * the nearest ancestor <table> element. 257 * If element is not in <table> element, 258 * throwing an exception. 259 * If null, this looks for nearest ancestor 260 * <table> element containing anchor of 261 * Selection. If found, computes the number 262 * of rows and columns of the <table>. 263 * Otherwise, throwing an exception. 264 * @param aRowCount Number of *actual* row count. 265 * I.e., rowspan does NOT increase this value. 266 * @param aColumnCount Number of column count. 267 * I.e., if colspan is specified with bigger 268 * number than actual, the value is used 269 * as this. 270 */ 271 [can_run_script] 272 void getTableSize(in Element aTableOrElementInTable, 273 out long aRowCount, out long aColCount); 274 275 /** 276 * getCellAt() returns a <td> or <th> element in a <table> if there is a 277 * cell at the indexes. 278 * 279 * @param aTableElement If not null, must be a <table> element. 280 * If null, looks for the nearest ancestor <table> 281 * to look for a cell. 282 * @param aRowIndex Row index of the cell. 283 * @param aColumnIndex Column index of the cell. 284 * @return Returns a <td> or <th> element if there is. 285 * Otherwise, returns null without throwing 286 * exception. 287 * If aTableElement is not null and not a <table> 288 * element, throwing an exception. 289 * If aTableElement is null and anchor of Selection 290 * is not in any <table> element, throwing an 291 * exception. 292 */ 293 [can_run_script] 294 Element getCellAt(in Element aTableElement, 295 in long aRowIndex, in long aColumnIndex); 296 297 /** 298 * Get cell element and its various information from <table> element and 299 * indexes in it. If aTableElement is null, this looks for an ancestor 300 * <table> element of anchor of Selection. If there is no <table> element 301 * at that point, this throws exception. Note that this requires layout 302 * information. So, you need to flush the layout after changing the DOM 303 * tree. 304 * If there is no cell element at the indexes, this throws exception. 305 * XXX Perhaps, this is wrong behavior, this should return null without 306 * exception since the caller cannot distinguish whether the exception 307 * is caused by "not found" or other unexpected situation. 308 * 309 * @param aTableElement A <table> element. If this is null, this 310 * uses ancestor of anchor of Selection. 311 * @param aRowIndex Row index in aTableElement. Starting from 0. 312 * @param aColumnIndex Column index in aTableElement. Starting from 313 * 0. 314 * @param aCellElement [OUT] The cell element at the indexes. 315 * @param aStartRowIndex [OUT] First row index which contains 316 * aCellElement. E.g., if the cell's rowspan is 317 * not 1, this returns its first row index. 318 * I.e., this can be smaller than aRowIndex. 319 * @param aStartColumnIndex [OUT] First column index which contains the 320 * aCellElement. E.g., if the cell's colspan is 321 * larger than 1, this returns its first column 322 * index. I.e., this can be smaller than 323 * aColumIndex. 324 * @param aRowSpan [OUT] rowspan attribute value in most cases. 325 * If the specified value is invalid, this 326 * returns 1. Only when the document is written 327 * in HTML5 or later, this can be 0. 328 * @param aColSpan [OUT] colspan attribute value in most cases. 329 * If the specified value is invalid, this 330 * returns 1. 331 * @param aEffectiveRowSpan [OUT] Effective rowspan value at aRowIndex. 332 * This is same as: 333 * aRowSpan - (aRowIndex - aStartRowIndex) 334 * @param aEffectiveColSpan [OUT] Effective colspan value at aColumnIndex. 335 * This is same as: 336 * aColSpan - (aColumnIndex - aStartColumnIndex) 337 * @param aIsSelected [OUT] Returns true if aCellElement or its 338 * <tr> or <table> element is selected. 339 * Otherwise, e.g., aCellElement just contains 340 * selection range, returns false. 341 */ 342 [can_run_script] 343 void getCellDataAt(in Element aTableElement, 344 in long aRowIndex, in long aColumnIndex, 345 out Element aCellElement, 346 out long aStartRowIndex, out long aStartColumnIndex, 347 out long aRowSpan, out long aColSpan, 348 out long aEffectiveRowSpan, out long aEffectiveColSpan, 349 out boolean aIsSelected); 350 351 /** 352 * getFirstRow() returns first <tr> element in a <table> element. 353 * 354 * @param aTableOrElementInTable If a <table> element, returns its first 355 * <tr> element. 356 * If another element, looks for nearest 357 * ancestor <table> element first. Then, 358 * return its first <tr> element. 359 * @return <tr> element in the <table> element. 360 * If <table> element is not found, this 361 * throws an exception. 362 * If there is a <table> element but it 363 * does not have <tr> elements, returns 364 * null without throwing exception. 365 * Note that this may return anonymous <tr> 366 * element if <table> has one or more cells 367 * but <tr> element is not in the source. 368 */ 369 [can_run_script] 370 Element getFirstRow(in Element aTableElement); 371 372 /** Preferred direction to search for neighboring cell 373 * when trying to locate a cell to place caret in after 374 * a table editing action. 375 * Used for aDirection param in SetSelectionAfterTableEdit 376 */ 377 378 /** 379 * getSelectedOrParentTableElement() returns a <td>, <th>, <tr> or <table>. 380 * If first selection range selects a <td> or <th>, returns it. aTagName 381 * is set to "td" even if the result is a <th> and aCount is set to 382 * Selection.rangeCount. 383 * If first selection range does not select <td> nor <th>, but selection 384 * anchor refers <table>, returns it. aTagName is set to "table" and 385 * aCount is set to 1. 386 * If first selection range does not select <td> nor <th>, but selection 387 * anchor refers <tr>, returns it. aTagName is set to "tr" and aCount is 388 * set to 1. 389 * If first selection range does not select <td> nor <th>, but selection 390 * anchor refers <td> (not include <th>!), returns it. aTagName is set to 391 * "td" and aCount is set to 0. 392 * Otherwise, if container of selection anchor is in a <td> or <th>, 393 * returns it. aTagName is set to "td" but aCount is set to 0. 394 * Otherwise, returns null, aTagName is set to empty string and aCount is 395 * set to 0. I.e., does not throw exception even if a cell is not found. 396 * NOTE: Calling this resets internal counter of getFirstSelectedCell() 397 * and getNextSelectedCell(). I.e., getNextSelectedCell() will 398 * return second selected cell element. 399 */ 400 [can_run_script] 401 Element getSelectedOrParentTableElement(out AString aTagName, 402 out long aCount); 403 404 /** Generally used after GetSelectedOrParentTableElement 405 * to test if selected cells are complete rows or columns 406 * 407 * @param aElement Any table or cell element or any element 408 * inside a table 409 * Used to get enclosing table. 410 * If null, selection's anchorNode is used 411 * 412 * @return 413 * 0 aCellElement was not a cell 414 * (returned result = NS_ERROR_FAILURE) 415 * TableSelectionMode::Cell There are 1 or more cells selected but 416 * complete rows or columns are not selected 417 * TableSelectionMode::Row All cells are in 1 or more rows 418 * and in each row, all cells selected 419 * Note: This is the value if all rows 420 * (thus all cells) are selected 421 * TableSelectionMode::Column All cells are in 1 or more columns 422 * and in each column, all cells are selected 423 */ 424 [can_run_script] 425 uint32_t getSelectedCellsType(in Element aElement); 426 427 /** 428 * getFirstSelectedCellInTable() returns a cell element, its row index and 429 * its column index if first range of Selection selects a cell. Note that 430 * that "selects a cell" means that the range container is a <tr> element 431 * and endOffset is startOffset + 1. So, even if first range of Selection 432 * is in a cell element, this treats the range does not select a cell. 433 * NOTE: Calling this resets internal counter of getFirstSelectedCell() 434 * and getNextSelectedCell(). I.e., getNextSelectedCell() will 435 * return second selected cell element. 436 * 437 * @param aRowIndex [OUT} Returns row index of the found cell. If not 438 * found, returns 0. 439 * @param aColumnIndex [OUT] Returns column index of the found cell. If 440 * not found, returns 0. 441 * @return The cell element which is selected by the first 442 * range of Selection. Even if this is not found, 443 * this returns null, not throwing exception. 444 */ 445 [can_run_script] 446 Element getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex); 447 448 /** 449 * getSelectedCells() returns an array of `<td>` and `<th>` elements which 450 * are selected in **any** `<table>` elements (i.e., some cells may be 451 * in different `<table>` element). 452 * If first range does not select a table cell element, this returns empty 453 * array because editor considers that selection is not in table cell 454 * selection mode. 455 * If second or later ranges do not select only a table cell element, this 456 * ignores the ranges. 457 */ 458 [can_run_script] 459 Array<Element> getSelectedCells(); 460 };