The Tor Browser / file comparison

comparison: editor/idl/nsITableEditor.idl

editor/idl/nsITableEditor.idl

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:3a006ddcc1d2
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 interface nsIDOMNode;
10 interface nsIDOMElement;
11 interface nsIDOMRange;
12
13 [scriptable, uuid(4805e684-49b9-11d3-9ce4-ed60bd6cb5bc)]
14
15 interface nsITableEditor : nsISupports
16 {
17 const short eNoSearch = 0;
18 const short ePreviousColumn = 1;
19 const short ePreviousRow = 2;
20
21 /* ------------ Table editing Methods -------------- */
22
23 /** Insert table methods
24 * Insert relative to the selected cell or the
25 * cell enclosing the selection anchor
26 * The selection is collapsed and is left in the new cell
27 * at the same row,col location as the original anchor cell
28 *
29 * @param aNumber Number of items to insert
30 * @param aAfter If TRUE, insert after the current cell,
31 * else insert before current cell
32 */
33 void insertTableCell(in long aNumber, in boolean aAfter);
34 void insertTableColumn(in long aNumber, in boolean aAfter);
35 void insertTableRow(in long aNumber, in boolean aAfter);
36
37 /** Delete table methods
38 * Delete starting at the selected cell or the
39 * cell (or table) enclosing the selection anchor
40 * The selection is collapsed and is left in the
41 * cell at the same row,col location as
42 * the previous selection anchor, if possible,
43 * else in the closest neigboring cell
44 *
45 * @param aNumber Number of items to insert/delete
46 */
47 void deleteTable();
48
49 /** Delete just the cell contents
50 * This is what should happen when Delete key is used
51 * for selected cells, to minimize upsetting the table layout
52 */
53 void deleteTableCellContents();
54
55 /** Delete cell elements as well as contents
56 * @param aNumber Number of contiguous cells, rows, or columns
57 *
58 * When there are more than 1 selected cells, aNumber is ignored.
59 * For Delete Rows or Columns, the complete columns or rows are
60 * determined by the selected cells. E.g., to delete 2 complete rows,
61 * user simply selects a cell in each, and they don't
62 * have to be contiguous.
63 */
64 void deleteTableCell(in long aNumber);
65 void deleteTableColumn(in long aNumber);
66 void deleteTableRow(in long aNumber);
67
68 /** Table Selection methods
69 * Selecting a row or column actually
70 * selects all cells (not TR in the case of rows)
71 */
72 void selectTableCell();
73
74 /** Select a rectangular block of cells:
75 * all cells falling within the row/column index of aStartCell
76 * to through the row/column index of the aEndCell
77 * aStartCell can be any location relative to aEndCell,
78 * as long as they are in the same table
79 * @param aStartCell starting cell in block
80 * @param aEndCell ending cell in block
81 */
82 void selectBlockOfCells(in nsIDOMElement aStartCell,
83 in nsIDOMElement aEndCell);
84
85 void selectTableRow();
86 void selectTableColumn();
87 void selectTable();
88 void selectAllTableCells();
89
90 /** Create a new TD or TH element, the opposite type of the supplied aSourceCell
91 * 1. Copy all attributes from aSourceCell to the new cell
92 * 2. Move all contents of aSourceCell to the new cell
93 * 3. Replace aSourceCell in the table with the new cell
94 *
95 * @param aSourceCell The cell to be replaced
96 * @return The new cell that replaces aSourceCell
97 */
98 nsIDOMElement switchTableCellHeaderType(in nsIDOMElement aSourceCell);
99
100 /** Merges contents of all selected cells
101 * for selected cells that are adjacent,
102 * this will result in a larger cell with appropriate
103 * rowspan and colspan, and original cells are deleted
104 * The resulting cell is in the location of the
105 * cell at the upper-left corner of the adjacent
106 * block of selected cells
107 *
108 * @param aMergeNonContiguousContents:
109 * If true:
110 * Non-contiguous cells are not deleted,
111 * but their contents are still moved
112 * to the upper-left cell
113 * If false: contiguous cells are ignored
114 *
115 * If there are no selected cells,
116 * and selection or caret is in a cell,
117 * that cell and the one to the right
118 * are merged
119 */
120 void joinTableCells(in boolean aMergeNonContiguousContents);
121
122 /** Split a cell that has rowspan and/or colspan > 0
123 * into cells such that all new cells have
124 * rowspan = 1 and colspan = 1
125 * All of the contents are not touched --
126 * they will appear to be in the upper-left cell
127 */
128 void splitTableCell();
129
130 /** Scan through all rows and add cells as needed so
131 * all locations in the cellmap are occupied.
132 * Used after inserting single cells or pasting
133 * a collection of cells that extend past the
134 * previous size of the table
135 * If aTable is null, it uses table enclosing the selection anchor
136 * This doesn't doesn't change the selection,
137 * thus it can be used to fixup all tables
138 * in a page independent of the selection
139 */
140 void normalizeTable(in nsIDOMElement aTable);
141
142 /** Get the row an column index from the layout's cellmap
143 * If aCell is null, it will try to find enclosing table of selection anchor
144 *
145 */
146 void getCellIndexes(in nsIDOMElement aCell,
147 out long aRowIndex, out long aColIndex);
148
149 /** Get the number of rows and columns in a table from the layout's cellmap
150 * If aTable is null, it will try to find enclosing table of selection ancho
151 * Note that all rows in table will not have this many because of
152 * ROWSPAN effects or if table is not "rectangular" (has short rows)
153 */
154 void getTableSize(in nsIDOMElement aTable,
155 out long aRowCount, out long aColCount);
156
157 /** Get a cell element at cellmap grid coordinates
158 * A cell that spans across multiple cellmap locations will
159 * be returned multiple times, once for each location it occupies
160 *
161 * @param aTable A table in the document
162 * @param aRowIndex, aColIndex The 0-based cellmap indexes
163 *
164 * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
165 * passes NS_SUCCEEDED macro)
166 *
167 * You can scan for all cells in a row or column
168 * by iterating through the appropriate indexes
169 * until the returned aCell is null
170 */
171 nsIDOMElement getCellAt(in nsIDOMElement aTable,
172 in long aRowIndex, in long aColIndex);
173
174 /** Get a cell at cellmap grid coordinates and associated data
175 * A cell that spans across multiple cellmap locations will
176 * be returned multiple times, once for each location it occupies
177 * Examine the returned aStartRowIndex and aStartColIndex to see
178 * if it is in the same layout column or layout row:
179 * A "layout row" is all cells sharing the same top edge
180 * A "layout column" is all cells sharing the same left edge
181 * This is important to determine what to do when inserting or deleting a column or row
182 *
183 * @param aTable A table in the document
184 * @param aRowIndex, aColIndex The 0-based cellmap indexes
185 * returns values:
186 * @param aCell The cell at this cellmap location
187 * @param aStartRowIndex The row index where cell starts
188 * @param aStartColIndex The col index where cell starts
189 * @param aRowSpan May be 0 (to span down entire table) or number of cells spanned
190 * @param aColSpan May be 0 (to span across entire table) or number of cells spanned
191 * @param aActualRowSpan The actual number of cellmap locations (rows) spanned by the cell
192 * @param aActualColSpan The actual number of cellmap locations (columns) spanned by the cell
193 * @param aIsSelected
194 * @param
195 *
196 * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
197 * passes NS_SUCCEEDED macro)
198 */
199 void getCellDataAt(in nsIDOMElement aTable,
200 in long aRowIndex, in long aColIndex,
201 out nsIDOMElement aCell,
202 out long aStartRowIndex, out long aStartColIndex,
203 out long aRowSpan, out long aColSpan,
204 out long aActualRowSpan, out long aActualColSpan,
205 out boolean aIsSelected);
206
207 /** Get the first row element in a table
208 *
209 * @return The row at the requested index
210 * Returns null if there are no rows in table
211 * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
212 * passes NS_SUCCEEDED macro)
213 */
214 nsIDOMNode getFirstRow(in nsIDOMElement aTableElement);
215
216 /** Get the next row element starting the search from aTableElement
217 *
218 * @param aTableElement Any TR or child-of-TR element in the document
219 *
220 * @return The row to start search from
221 * and the row returned from the search
222 * Returns null if there isn't another row
223 * (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
224 * passes NS_SUCCEEDED macro)
225 */
226 nsIDOMNode getNextRow(in nsIDOMNode aTableElement);
227
228 /** Preferred direction to search for neighboring cell
229 * when trying to locate a cell to place caret in after
230 * a table editing action.
231 * Used for aDirection param in SetSelectionAfterTableEdit
232 */
233
234 /** Reset a selected cell or collapsed selection (the caret) after table editing
235 *
236 * @param aTable A table in the document
237 * @param aRow The row ...
238 * @param aCol ... and column defining the cell
239 * where we will try to place the caret
240 * @param aSelected If true, we select the whole cell instead of setting caret
241 * @param aDirection If cell at (aCol, aRow) is not found,
242 * search for previous cell in the same
243 * column (aPreviousColumn) or row (ePreviousRow)
244 * or don't search for another cell (aNoSearch)
245 * If no cell is found, caret is place just before table;
246 * and if that fails, at beginning of document.
247 * Thus we generally don't worry about the return value
248 * and can use the nsSetSelectionAfterTableEdit stack-based
249 * object to insure we reset the caret in a table-editing method.
250 */
251 void setSelectionAfterTableEdit(in nsIDOMElement aTable,
252 in long aRow, in long aCol,
253 in long aDirection, in boolean aSelected);
254
255 /** Examine the current selection and find
256 * a selected TABLE, TD or TH, or TR element.
257 * or return the parent TD or TH if selection is inside a table cell
258 * Returns null if no table element is found.
259 *
260 * @param aTagName The tagname of returned element
261 * Note that "td" will be returned if name
262 * is actually "th"
263 * @param aCount How many table elements were selected
264 * This tells us if we have multiple cells selected
265 * (0 if element is a parent cell of selection)
266 * @return The table element (table, row, or first selected cell)
267 *
268 */
269 nsIDOMElement getSelectedOrParentTableElement(out AString aTagName, out long aCount);
270
271 /** Generally used after GetSelectedOrParentTableElement
272 * to test if selected cells are complete rows or columns
273 *
274 * @param aElement Any table or cell element or any element
275 * inside a table
276 * Used to get enclosing table.
277 * If null, selection's anchorNode is used
278 *
279 * @return
280 * 0 aCellElement was not a cell
281 * (returned result = NS_ERROR_FAILURE)
282 * TABLESELECTION_CELL There are 1 or more cells selected but
283 * complete rows or columns are not selected
284 * TABLESELECTION_ROW All cells are in 1 or more rows
285 * and in each row, all cells selected
286 * Note: This is the value if all rows
287 * (thus all cells) are selected
288 * TABLESELECTION_COLUMN All cells are in 1 or more columns
289 * and in each column, all cells are selected
290 */
291 uint32_t getSelectedCellsType(in nsIDOMElement aElement);
292
293 /** Get first selected element from first selection range.
294 * (If multiple cells were selected this is the first in the order they were selected)
295 * Assumes cell-selection model where each cell
296 * is in a separate range (selection parent node is table row)
297 * @param aCell [OUT] Selected cell or null if ranges don't contain
298 * cell selections
299 * @param aRange [OUT] Optional: if not null, return the selection range
300 * associated with the cell
301 * Returns the DOM cell element
302 * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
303 * passes NS_SUCCEEDED macro)
304 */
305 nsIDOMElement getFirstSelectedCell(out nsIDOMRange aRange);
306
307 /** Get first selected element in the table
308 * This is the upper-left-most selected cell in table,
309 * ignoring the order that the user selected them (order in the selection ranges)
310 * Assumes cell-selection model where each cell
311 * is in a separate range (selection parent node is table row)
312 * @param aCell Selected cell or null if ranges don't contain
313 * cell selections
314 * @param aRowIndex Optional: if not null, return row index of 1st cell
315 * @param aColIndex Optional: if not null, return column index of 1st cell
316 *
317 * Returns the DOM cell element
318 * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
319 * passes NS_SUCCEEDED macro)
320 */
321 nsIDOMElement getFirstSelectedCellInTable(out long aRowIndex, out long aColIndex);
322
323 /** Get next selected cell element from first selection range.
324 * Assumes cell-selection model where each cell
325 * is in a separate range (selection parent node is table row)
326 * Always call GetFirstSelectedCell() to initialize stored index of "next" cell
327 * @param aCell Selected cell or null if no more selected cells
328 * or ranges don't contain cell selections
329 * @param aRange Optional: if not null, return the selection range
330 * associated with the cell
331 *
332 * Returns the DOM cell element
333 * (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
334 * passes NS_SUCCEEDED macro)
335 */
336 nsIDOMElement getNextSelectedCell(out nsIDOMRange aRange);
337 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial