← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/editor/idl/nsITableEditor.idl

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

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