Source code

Revision control

Other Tools

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
void getCellIndexes(in Element aCellElement,
244
out long aRowIndex, out long aColumnIndex);
245
246
/**
247
* getTableSize() computes number of rows and columns.
248
* Note that this depends on layout information. Therefore, all pending
249
* layout should've been flushed before calling this.
250
*
251
* @param aTableOrElementInTable If a <table> element, this computes number
252
* of rows and columns of it.
253
* If another element and in a <table>, this
254
* computes number of rows and columns of
255
* the nearest ancestor <table> element.
256
* If element is not in <table> element,
257
* throwing an exception.
258
* If null, this looks for nearest ancestor
259
* <table> element containing anchor of
260
* Selection. If found, computes the number
261
* of rows and columns of the <table>.
262
* Otherwise, throwing an exception.
263
* @param aRowCount Number of *actual* row count.
264
* I.e., rowspan does NOT increase this value.
265
* @param aColumnCount Number of column count.
266
* I.e., if colspan is specified with bigger
267
* number than actual, the value is used
268
* as this.
269
*/
270
void getTableSize(in Element aTableOrElementInTable,
271
out long aRowCount, out long aColCount);
272
273
/**
274
* getCellAt() returns a <td> or <th> element in a <table> if there is a
275
* cell at the indexes.
276
*
277
* @param aTableElement If not null, must be a <table> element.
278
* If null, looks for the nearest ancestor <table>
279
* to look for a cell.
280
* @param aRowIndex Row index of the cell.
281
* @param aColumnIndex Column index of the cell.
282
* @return Returns a <td> or <th> element if there is.
283
* Otherwise, returns null without throwing
284
* exception.
285
* If aTableElement is not null and not a <table>
286
* element, throwing an exception.
287
* If aTableElement is null and anchor of Selection
288
* is not in any <table> element, throwing an
289
* exception.
290
*/
291
Element getCellAt(in Element aTableElement,
292
in long aRowIndex, in long aColumnIndex);
293
294
/**
295
* Get cell element and its various information from <table> element and
296
* indexes in it. If aTableElement is null, this looks for an ancestor
297
* <table> element of anchor of Selection. If there is no <table> element
298
* at that point, this throws exception. Note that this requires layout
299
* information. So, you need to flush the layout after changing the DOM
300
* tree.
301
* If there is no cell element at the indexes, this throws exception.
302
* XXX Perhaps, this is wrong behavior, this should return null without
303
* exception since the caller cannot distinguish whether the exception
304
* is caused by "not found" or other unexpected situation.
305
*
306
* @param aTableElement A <table> element. If this is null, this
307
* uses ancestor of anchor of Selection.
308
* @param aRowIndex Row index in aTableElement. Starting from 0.
309
* @param aColumnIndex Column index in aTableElement. Starting from
310
* 0.
311
* @param aCellElement [OUT] The cell element at the indexes.
312
* @param aStartRowIndex [OUT] First row index which contains
313
* aCellElement. E.g., if the cell's rowspan is
314
* not 1, this returns its first row index.
315
* I.e., this can be smaller than aRowIndex.
316
* @param aStartColumnIndex [OUT] First column index which contains the
317
* aCellElement. E.g., if the cell's colspan is
318
* larger than 1, this returns its first column
319
* index. I.e., this can be smaller than
320
* aColumIndex.
321
* @param aRowSpan [OUT] rowspan attribute value in most cases.
322
* If the specified value is invalid, this
323
* returns 1. Only when the document is written
324
* in HTML5 or later, this can be 0.
325
* @param aColSpan [OUT] colspan attribute value in most cases.
326
* If the specified value is invalid, this
327
* returns 1.
328
* @param aEffectiveRowSpan [OUT] Effective rowspan value at aRowIndex.
329
* This is same as:
330
* aRowSpan - (aRowIndex - aStartRowIndex)
331
* @param aEffectiveColSpan [OUT] Effective colspan value at aColumnIndex.
332
* This is same as:
333
* aColSpan - (aColumnIndex - aStartColumnIndex)
334
* @param aIsSelected [OUT] Returns true if aCellElement or its
335
* <tr> or <table> element is selected.
336
* Otherwise, e.g., aCellElement just contains
337
* selection range, returns false.
338
*/
339
void getCellDataAt(in Element aTableElement,
340
in long aRowIndex, in long aColumnIndex,
341
out Element aCellElement,
342
out long aStartRowIndex, out long aStartColumnIndex,
343
out long aRowSpan, out long aColSpan,
344
out long aEffectiveRowSpan, out long aEffectiveColSpan,
345
out boolean aIsSelected);
346
347
/**
348
* getFirstRow() returns first <tr> element in a <table> element.
349
*
350
* @param aTableOrElementInTable If a <table> element, returns its first
351
* <tr> element.
352
* If another element, looks for nearest
353
* ancestor <table> element first. Then,
354
* return its first <tr> element.
355
* @return <tr> element in the <table> element.
356
* If <table> element is not found, this
357
* throws an exception.
358
* If there is a <table> element but it
359
* does not have <tr> elements, returns
360
* null without throwing exception.
361
* Note that this may return anonymous <tr>
362
* element if <table> has one or more cells
363
* but <tr> element is not in the source.
364
*/
365
Element getFirstRow(in Element aTableElement);
366
367
/** Preferred direction to search for neighboring cell
368
* when trying to locate a cell to place caret in after
369
* a table editing action.
370
* Used for aDirection param in SetSelectionAfterTableEdit
371
*/
372
373
/**
374
* getSelectedOrParentTableElement() returns a <td>, <th>, <tr> or <table>.
375
* If first selection range selects a <td> or <th>, returns it. aTagName
376
* is set to "td" even if the result is a <th> and aCount is set to
377
* Selection.rangeCount.
378
* If first selection range does not select <td> nor <th>, but selection
379
* anchor refers <table>, returns it. aTagName is set to "table" and
380
* aCount is set to 1.
381
* If first selection range does not select <td> nor <th>, but selection
382
* anchor refers <tr>, returns it. aTagName is set to "tr" and aCount is
383
* set to 1.
384
* If first selection range does not select <td> nor <th>, but selection
385
* anchor refers <td> (not include <th>!), returns it. aTagName is set to
386
* "td" and aCount is set to 0.
387
* Otherwise, if container of selection anchor is in a <td> or <th>,
388
* returns it. aTagName is set to "td" but aCount is set to 0.
389
* Otherwise, returns null, aTagName is set to empty string and aCount is
390
* set to 0. I.e., does not throw exception even if a cell is not found.
391
* NOTE: Calling this resets internal counter of getFirstSelectedCell()
392
* and getNextSelectedCell(). I.e., getNextSelectedCell() will
393
* return second selected cell element.
394
*/
395
Element getSelectedOrParentTableElement(out AString aTagName,
396
out long aCount);
397
398
/** Generally used after GetSelectedOrParentTableElement
399
* to test if selected cells are complete rows or columns
400
*
401
* @param aElement Any table or cell element or any element
402
* inside a table
403
* Used to get enclosing table.
404
* If null, selection's anchorNode is used
405
*
406
* @return
407
* 0 aCellElement was not a cell
408
* (returned result = NS_ERROR_FAILURE)
409
* TableSelectionMode::Cell There are 1 or more cells selected but
410
* complete rows or columns are not selected
411
* TableSelectionMode::Row All cells are in 1 or more rows
412
* and in each row, all cells selected
413
* Note: This is the value if all rows
414
* (thus all cells) are selected
415
* TableSelectionMode::Column All cells are in 1 or more columns
416
* and in each column, all cells are selected
417
*/
418
uint32_t getSelectedCellsType(in Element aElement);
419
420
/**
421
* getFirstSelectedCell() returns a <td> or <th> element if first range of
422
* Selection selects only one table cell element (i.e., startContainer and
423
* endContainer are same <tr> element and startOffset + 1 equals endOffset).
424
* If first range of Selection does not select a table cell element, this
425
* returns null. However, if Selection has no range, this throws an
426
* exception.
427
*
428
* @param aFirstRangeOfSelection [OUT] Returns the first range of Selection
429
* only when this returns a <td> or <th>
430
* element. Otherwise, returns null.
431
* @return A <td> or <th> element if first range of
432
* Selection selects only one table cell
433
* element.
434
*/
435
Element getFirstSelectedCell(out Range aFirstRangeOfSelection);
436
437
/**
438
* getFirstSelectedCellInTable() returns a cell element, its row index and
439
* its column index if first range of Selection selects a cell. Note that
440
* that "selects a cell" means that the range container is a <tr> element
441
* and endOffset is startOffset + 1. So, even if first range of Selection
442
* is in a cell element, this treats the range does not select a cell.
443
* NOTE: Calling this resets internal counter of getFirstSelectedCell()
444
* and getNextSelectedCell(). I.e., getNextSelectedCell() will
445
* return second selected cell element.
446
*
447
* @param aRowIndex [OUT} Returns row index of the found cell. If not
448
* found, returns 0.
449
* @param aColumnIndex [OUT] Returns column index of the found cell. If
450
* not found, returns 0.
451
* @return The cell element which is selected by the first
452
* range of Selection. Even if this is not found,
453
* this returns null, not throwing exception.
454
*/
455
Element getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
456
457
/**
458
* getNextSelectedCell() is a stateful method to retrieve selected table
459
* cell elements which are selected by 2nd or later ranges of Selection.
460
* When you call getFirstSelectedCell(), it resets internal counter of
461
* this method. Then, following calls of getNextSelectedCell() scans the
462
* remaining ranges of Selection. If a range selects a <td> or <th>
463
* element, returns the cell element. If a range selects an element but
464
* neither <td> nor <th> element, this ignores the range. If a range is
465
* in a text node, returns null without throwing exception, but stops
466
* scanning the remaining ranges even you call this again.
467
* Note that this may cross <table> boundaries since this method just
468
* scans all ranges of Selection. Therefore, returning cells which
469
* belong to different <table> elements.
470
*
471
* @param aNextSelectedCellRange [OUT] Returns null if this method returns
472
* null. Otherwise, i.e., found a range which
473
* selects a <td> or <th> element, returns the
474
* range.
475
* @return A <td> or <th> element if one of remaining
476
* ranges selects a <td> or <th> element unless
477
* this does not meet a range in a text node.
478
*/
479
Element getNextSelectedCell(out Range aNextSelectedCellRange);
480
};