Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
nsITableEditor Interface Reference

import "nsITableEditor.idl";

Inheritance diagram for nsITableEditor:
Inheritance graph
[legend]
Collaboration diagram for nsITableEditor:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void insertTableCell (in long aNumber, in boolean aAfter)
 Insert table methods Insert relative to the selected cell or the cell enclosing the selection anchor The selection is collapsed and is left in the new cell at the same row,col location as the original anchor cell.
void insertTableColumn (in long aNumber, in boolean aAfter)
void insertTableRow (in long aNumber, in boolean aAfter)
void deleteTable ()
 Delete table methods Delete starting at the selected cell or the cell (or table) enclosing the selection anchor The selection is collapsed and is left in the cell at the same row,col location as the previous selection anchor, if possible, else in the closest neigboring cell.
void deleteTableCellContents ()
 Delete just the cell contents This is what should happen when Delete key is used for selected cells, to minimize upsetting the table layout.
void deleteTableCell (in long aNumber)
 Delete cell elements as well as contents.
void deleteTableColumn (in long aNumber)
void deleteTableRow (in long aNumber)
void selectTableCell ()
 Table Selection methods Selecting a row or column actually selects all cells (not TR in the case of rows)
void selectBlockOfCells (in nsIDOMElement aStartCell, in nsIDOMElement aEndCell)
 Select a rectangular block of cells: all cells falling within the row/column index of aStartCell to through the row/column index of the aEndCell aStartCell can be any location relative to aEndCell, as long as they are in the same table.
void selectTableRow ()
void selectTableColumn ()
void selectTable ()
void selectAllTableCells ()
nsIDOMElement switchTableCellHeaderType (in nsIDOMElement aSourceCell)
 Create a new TD or TH element, the opposite type of the supplied aSourceCell.
void joinTableCells (in boolean aMergeNonContiguousContents)
 Merges contents of all selected cells for selected cells that are adjacent, this will result in a larger cell with appropriate rowspan and colspan, and original cells are deleted The resulting cell is in the location of the cell at the upper-left corner of the adjacent block of selected cells.
void splitTableCell ()
 Split a cell that has rowspan and/or colspan > 0 into cells such that all new cells have rowspan = 1 and colspan = 1 All of the contents are not touched -- they will appear to be in the upper-left cell.
void normalizeTable (in nsIDOMElement aTable)
 Scan through all rows and add cells as needed so all locations in the cellmap are occupied.
void getCellIndexes (in nsIDOMElement aCell, out long aRowIndex, out long aColIndex)
 Get the row an column index from the layout's cellmap If aCell is null, it will try to find enclosing table of selection anchor.
void getTableSize (in nsIDOMElement aTable, out long aRowCount, out long aColCount)
 Get the number of rows and columns in a table from the layout's cellmap If aTable is null, it will try to find enclosing table of selection ancho Note that all rows in table will not have this many because of ROWSPAN effects or if table is not "rectangular" (has short rows)
nsIDOMElement getCellAt (in nsIDOMElement aTable, in long aRowIndex, in long aColIndex)
 Get a cell element at cellmap grid coordinates A cell that spans across multiple cellmap locations will be returned multiple times, once for each location it occupies.
void getCellDataAt (in nsIDOMElement aTable, in long aRowIndex, in long aColIndex, out nsIDOMElement aCell, out long aStartRowIndex, out long aStartColIndex, out long aRowSpan, out long aColSpan, out long aActualRowSpan, out long aActualColSpan, out boolean aIsSelected)
 Get a cell at cellmap grid coordinates and associated data A cell that spans across multiple cellmap locations will be returned multiple times, once for each location it occupies Examine the returned aStartRowIndex and aStartColIndex to see if it is in the same layout column or layout row: A "layout row" is all cells sharing the same top edge A "layout column" is all cells sharing the same left edge This is important to determine what to do when inserting or deleting a column or row.
nsIDOMNode getFirstRow (in nsIDOMElement aTableElement)
 Get the first row element in a table.
nsIDOMNode getNextRow (in nsIDOMNode aTableElement)
 Get the next row element starting the search from aTableElement.
void setSelectionAfterTableEdit (in nsIDOMElement aTable, in long aRow, in long aCol, in long aDirection, in boolean aSelected)
 Preferred direction to search for neighboring cell when trying to locate a cell to place caret in after a table editing action.
nsIDOMElement getSelectedOrParentTableElement (out AString aTagName, out long aCount)
 Examine the current selection and find a selected TABLE, TD or TH, or TR element.
PRUint32 getSelectedCellsType (in nsIDOMElement aElement)
 Generally used after GetSelectedOrParentTableElement to test if selected cells are complete rows or columns.
nsIDOMElement getFirstSelectedCell (out nsIDOMRange aRange)
 Get first selected element from first selection range.
nsIDOMElement getFirstSelectedCellInTable (out long aRowIndex, out long aColIndex)
 Get first selected element in the table This is the upper-left-most selected cell in table, ignoring the order that the user selected them (order in the selection ranges) Assumes cell-selection model where each cell is in a separate range (selection parent node is table row)
nsIDOMElement getNextSelectedCell (out nsIDOMRange aRange)
 Get next selected cell element from first selection range.

Public Attributes

const short eNoSearch = 0
const short ePreviousColumn = 1
const short ePreviousRow = 2

Detailed Description

Definition at line 47 of file nsITableEditor.idl.


Member Function Documentation

Delete table methods Delete starting at the selected cell or the cell (or table) enclosing the selection anchor The selection is collapsed and is left in the cell at the same row,col location as the previous selection anchor, if possible, else in the closest neigboring cell.

Parameters:
aNumberNumber of items to insert/delete

Delete cell elements as well as contents.

Parameters:
aNumberNumber of contiguous cells, rows, or columns

When there are more than 1 selected cells, aNumber is ignored. For Delete Rows or Columns, the complete columns or rows are determined by the selected cells. E.g., to delete 2 complete rows, user simply selects a cell in each, and they don't have to be contiguous.

Delete just the cell contents This is what should happen when Delete key is used for selected cells, to minimize upsetting the table layout.

nsIDOMElement nsITableEditor::getCellAt ( in nsIDOMElement  aTable,
in long  aRowIndex,
in long  aColIndex 
)

Get a cell element at cellmap grid coordinates A cell that spans across multiple cellmap locations will be returned multiple times, once for each location it occupies.

Parameters:
aTableA table in the document
aRowIndex,aColIndexThe 0-based cellmap indexes

(in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

You can scan for all cells in a row or column by iterating through the appropriate indexes until the returned aCell is null

void nsITableEditor::getCellDataAt ( in nsIDOMElement  aTable,
in long  aRowIndex,
in long  aColIndex,
out nsIDOMElement  aCell,
out long  aStartRowIndex,
out long  aStartColIndex,
out long  aRowSpan,
out long  aColSpan,
out long  aActualRowSpan,
out long  aActualColSpan,
out boolean  aIsSelected 
)

Get a cell at cellmap grid coordinates and associated data A cell that spans across multiple cellmap locations will be returned multiple times, once for each location it occupies Examine the returned aStartRowIndex and aStartColIndex to see if it is in the same layout column or layout row: A "layout row" is all cells sharing the same top edge A "layout column" is all cells sharing the same left edge This is important to determine what to do when inserting or deleting a column or row.

Parameters:
aTableA table in the document
aRowIndex,aColIndexThe 0-based cellmap indexes returns values:
aCellThe cell at this cellmap location
aStartRowIndexThe row index where cell starts
aStartColIndexThe col index where cell starts
aRowSpanMay be 0 (to span down entire table) or number of cells spanned
aColSpanMay be 0 (to span across entire table) or number of cells spanned
aActualRowSpanThe actual number of cellmap locations (rows) spanned by the cell
aActualColSpanThe actual number of cellmap locations (columns) spanned by the cell
aIsSelected
(inC++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)
void nsITableEditor::getCellIndexes ( in nsIDOMElement  aCell,
out long  aRowIndex,
out long  aColIndex 
)

Get the row an column index from the layout's cellmap If aCell is null, it will try to find enclosing table of selection anchor.

 

Get the first row element in a table.

Returns:
The row at the requested index Returns null if there are no rows in table (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

Get first selected element from first selection range.

(If multiple cells were selected this is the first in the order they were selected) Assumes cell-selection model where each cell is in a separate range (selection parent node is table row)

Parameters:
aCell[OUT] Selected cell or null if ranges don't contain cell selections
aRange[OUT] Optional: if not null, return the selection range associated with the cell Returns the DOM cell element (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

Get first selected element in the table This is the upper-left-most selected cell in table, ignoring the order that the user selected them (order in the selection ranges) Assumes cell-selection model where each cell is in a separate range (selection parent node is table row)

Parameters:
aCellSelected cell or null if ranges don't contain cell selections
aRowIndexOptional: if not null, return row index of 1st cell
aColIndexOptional: if not null, return column index of 1st cell

Returns the DOM cell element (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

Get the next row element starting the search from aTableElement.

Parameters:
aTableElementAny TR or child-of-TR element in the document
Returns:
The row to start search from and the row returned from the search Returns null if there isn't another row (in C++ returns: NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

Get next selected cell element from first selection range.

Assumes cell-selection model where each cell is in a separate range (selection parent node is table row) Always call GetFirstSelectedCell() to initialize stored index of "next" cell

Parameters:
aCellSelected cell or null if no more selected cells or ranges don't contain cell selections
aRangeOptional: if not null, return the selection range associated with the cell

Returns the DOM cell element (in C++: returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found passes NS_SUCCEEDED macro)

Generally used after GetSelectedOrParentTableElement to test if selected cells are complete rows or columns.

Parameters:
aElementAny table or cell element or any element inside a table Used to get enclosing table. If null, selection's anchorNode is used
Returns:
0 aCellElement was not a cell (returned result = NS_ERROR_FAILURE) TABLESELECTION_CELL There are 1 or more cells selected but complete rows or columns are not selected TABLESELECTION_ROW All cells are in 1 or more rows and in each row, all cells selected Note: This is the value if all rows (thus all cells) are selected TABLESELECTION_COLUMN All cells are in 1 or more columns and in each column, all cells are selected

Examine the current selection and find a selected TABLE, TD or TH, or TR element.

or return the parent TD or TH if selection is inside a table cell Returns null if no table element is found.

Parameters:
aTagNameThe tagname of returned element Note that "td" will be returned if name is actually "th"
aCountHow many table elements were selected This tells us if we have multiple cells selected (0 if element is a parent cell of selection)
Returns:
The table element (table, row, or first selected cell)
void nsITableEditor::getTableSize ( in nsIDOMElement  aTable,
out long  aRowCount,
out long  aColCount 
)

Get the number of rows and columns in a table from the layout's cellmap If aTable is null, it will try to find enclosing table of selection ancho Note that all rows in table will not have this many because of ROWSPAN effects or if table is not "rectangular" (has short rows)

Insert table methods Insert relative to the selected cell or the cell enclosing the selection anchor The selection is collapsed and is left in the new cell at the same row,col location as the original anchor cell.

Parameters:
aNumberNumber of items to insert
aAfterIf TRUE, insert after the current cell, else insert before current cell
void nsITableEditor::insertTableRow ( in long  aNumber,
in boolean  aAfter 
)
void nsITableEditor::joinTableCells ( in boolean  aMergeNonContiguousContents)

Merges contents of all selected cells for selected cells that are adjacent, this will result in a larger cell with appropriate rowspan and colspan, and original cells are deleted The resulting cell is in the location of the cell at the upper-left corner of the adjacent block of selected cells.

Parameters:
aMergeNonContiguousContents,:If true: Non-contiguous cells are not deleted, but their contents are still moved to the upper-left cell If false: contiguous cells are ignored

If there are no selected cells, and selection or caret is in a cell, that cell and the one to the right are merged

Scan through all rows and add cells as needed so all locations in the cellmap are occupied.

Used after inserting single cells or pasting a collection of cells that extend past the previous size of the table If aTable is null, it uses table enclosing the selection anchor This doesn't doesn't change the selection, thus it can be used to fixup all tables in a page independant of the selection

Select a rectangular block of cells: all cells falling within the row/column index of aStartCell to through the row/column index of the aEndCell aStartCell can be any location relative to aEndCell, as long as they are in the same table.

Parameters:
aStartCellstarting cell in block
aEndCellending cell in block

Table Selection methods Selecting a row or column actually selects all cells (not TR in the case of rows)

void nsITableEditor::setSelectionAfterTableEdit ( in nsIDOMElement  aTable,
in long  aRow,
in long  aCol,
in long  aDirection,
in boolean  aSelected 
)

Preferred direction to search for neighboring cell when trying to locate a cell to place caret in after a table editing action.

Used for aDirection param in SetSelectionAfterTableEdit Reset a selected cell or collapsed selection (the caret) after table editing

Parameters:
aTableA table in the document
aRowThe row ...
aCol... and column defining the cell where we will try to place the caret
aSelectedIf true, we select the whole cell instead of setting caret
aDirectionIf cell at (aCol, aRow) is not found, search for previous cell in the same column (aPreviousColumn) or row (ePreviousRow) or don't search for another cell (aNoSearch) If no cell is found, caret is place just before table; and if that fails, at beginning of document. Thus we generally don't worry about the return value and can use the nsSetSelectionAfterTableEdit stack-based object to insure we reset the caret in a table-editing method.

Split a cell that has rowspan and/or colspan > 0 into cells such that all new cells have rowspan = 1 and colspan = 1 All of the contents are not touched -- they will appear to be in the upper-left cell.

Create a new TD or TH element, the opposite type of the supplied aSourceCell.

  1. Copy all attributes from aSourceCell to the new cell
  2. Move all contents of aSourceCell to the new cell
  3. Replace aSourceCell in the table with the new cell
Parameters:
aSourceCellThe cell to be replaced
Returns:
The new cell that replaces aSourceCell

Member Data Documentation

Definition at line 49 of file nsITableEditor.idl.

Definition at line 50 of file nsITableEditor.idl.

Definition at line 51 of file nsITableEditor.idl.


The documentation for this interface was generated from the following file: