001/*
002 * Copyright (c) 2003 World Wide Web Consortium,
003 * (Massachusetts Institute of Technology, Institut National de
004 * Recherche en Informatique et en Automatique, Keio University). All
005 * Rights Reserved. This program is distributed under the W3C's Software
006 * Intellectual Property License. This program is distributed in the
007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009 * PURPOSE.
010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011 */
012
013package org.w3c.dom.html2;
014
015import org.w3c.dom.DOMException;
016
017/**
018 * The create* and delete* methods on the table allow authors to construct and
019 * modify tables. [<a href='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>] specifies that only one of each of the
020 * <code>CAPTION</code>, <code>THEAD</code>, and <code>TFOOT</code> elements
021 * may exist in a table. Therefore, if one exists, and the createTHead() or
022 * createTFoot() method is called, the method returns the existing THead or
023 * TFoot element. See the TABLE element definition in HTML 4.01.
024 * <p>See also the <a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>Document Object Model (DOM) Level 2 HTML Specification</a>.
025 */
026public interface HTMLTableElement extends HTMLElement {
027    /**
028     * Returns the table's <code>CAPTION</code>, or void if none exists.
029     * @version DOM Level 2
030     */
031    public HTMLTableCaptionElement getCaption();
032    /**
033     * Returns the table's <code>CAPTION</code>, or void if none exists.
034     * @exception DOMException
035     *    HIERARCHY_REQUEST_ERR: if the element is not a <code>CAPTION</code>.
036     * @version DOM Level 2
037     */
038    public void setCaption(HTMLTableCaptionElement caption)
039                          throws DOMException;
040
041    /**
042     * Returns the table's <code>THEAD</code>, or <code>null</code> if none
043     * exists.
044     * @version DOM Level 2
045     */
046    public HTMLTableSectionElement getTHead();
047    /**
048     * Returns the table's <code>THEAD</code>, or <code>null</code> if none
049     * exists.
050     * @exception DOMException
051     *    HIERARCHY_REQUEST_ERR: if the element is not a <code>THEAD</code>.
052     * @version DOM Level 2
053     */
054    public void setTHead(HTMLTableSectionElement tHead)
055                          throws DOMException;
056
057    /**
058     * Returns the table's <code>TFOOT</code>, or <code>null</code> if none
059     * exists.
060     * @version DOM Level 2
061     */
062    public HTMLTableSectionElement getTFoot();
063    /**
064     * Returns the table's <code>TFOOT</code>, or <code>null</code> if none
065     * exists.
066     * @exception DOMException
067     *    HIERARCHY_REQUEST_ERR: if the element is not a <code>TFOOT</code>.
068     * @version DOM Level 2
069     */
070    public void setTFoot(HTMLTableSectionElement tFoot)
071                          throws DOMException;
072
073    /**
074     * Returns a collection of all the rows in the table, including all in
075     * <code>THEAD</code>, <code>TFOOT</code>, all <code>TBODY</code>
076     * elements.
077     */
078    public HTMLCollection getRows();
079
080    /**
081     * Returns a collection of the table bodies (including implicit ones).
082     */
083    public HTMLCollection getTBodies();
084
085    /**
086     * Specifies the table's position with respect to the rest of the
087     * document. See the align attribute definition in HTML 4.01. This
088     * attribute is deprecated in HTML 4.01.
089     */
090    public String getAlign();
091    /**
092     * Specifies the table's position with respect to the rest of the
093     * document. See the align attribute definition in HTML 4.01. This
094     * attribute is deprecated in HTML 4.01.
095     */
096    public void setAlign(String align);
097
098    /**
099     * Cell background color. See the bgcolor attribute definition in HTML
100     * 4.01. This attribute is deprecated in HTML 4.01.
101     */
102    public String getBgColor();
103    /**
104     * Cell background color. See the bgcolor attribute definition in HTML
105     * 4.01. This attribute is deprecated in HTML 4.01.
106     */
107    public void setBgColor(String bgColor);
108
109    /**
110     * The width of the border around the table. See the border attribute
111     * definition in HTML 4.01.
112     */
113    public String getBorder();
114    /**
115     * The width of the border around the table. See the border attribute
116     * definition in HTML 4.01.
117     */
118    public void setBorder(String border);
119
120    /**
121     * Specifies the horizontal and vertical space between cell content and
122     * cell borders. See the cellpadding attribute definition in HTML 4.01.
123     */
124    public String getCellPadding();
125    /**
126     * Specifies the horizontal and vertical space between cell content and
127     * cell borders. See the cellpadding attribute definition in HTML 4.01.
128     */
129    public void setCellPadding(String cellPadding);
130
131    /**
132     * Specifies the horizontal and vertical separation between cells. See the
133     * cellspacing attribute definition in HTML 4.01.
134     */
135    public String getCellSpacing();
136    /**
137     * Specifies the horizontal and vertical separation between cells. See the
138     * cellspacing attribute definition in HTML 4.01.
139     */
140    public void setCellSpacing(String cellSpacing);
141
142    /**
143     * Specifies which external table borders to render. See the frame
144     * attribute definition in HTML 4.01.
145     */
146    public String getFrame();
147    /**
148     * Specifies which external table borders to render. See the frame
149     * attribute definition in HTML 4.01.
150     */
151    public void setFrame(String frame);
152
153    /**
154     * Specifies which internal table borders to render. See the rules
155     * attribute definition in HTML 4.01.
156     */
157    public String getRules();
158    /**
159     * Specifies which internal table borders to render. See the rules
160     * attribute definition in HTML 4.01.
161     */
162    public void setRules(String rules);
163
164    /**
165     * Description about the purpose or structure of a table. See the summary
166     * attribute definition in HTML 4.01.
167     */
168    public String getSummary();
169    /**
170     * Description about the purpose or structure of a table. See the summary
171     * attribute definition in HTML 4.01.
172     */
173    public void setSummary(String summary);
174
175    /**
176     * Specifies the desired table width. See the width attribute definition
177     * in HTML 4.01.
178     */
179    public String getWidth();
180    /**
181     * Specifies the desired table width. See the width attribute definition
182     * in HTML 4.01.
183     */
184    public void setWidth(String width);
185
186    /**
187     * Create a table header row or return an existing one.
188     * @return A new table header element (<code>THEAD</code>).
189     */
190    public HTMLElement createTHead();
191
192    /**
193     * Delete the header from the table, if one exists.
194     */
195    public void deleteTHead();
196
197    /**
198     * Create a table footer row or return an existing one.
199     * @return A footer element (<code>TFOOT</code>).
200     */
201    public HTMLElement createTFoot();
202
203    /**
204     * Delete the footer from the table, if one exists.
205     */
206    public void deleteTFoot();
207
208    /**
209     * Create a new table caption object or return an existing one.
210     * @return A <code>CAPTION</code> element.
211     */
212    public HTMLElement createCaption();
213
214    /**
215     * Delete the table caption, if one exists.
216     */
217    public void deleteCaption();
218
219    /**
220     * Insert a new empty row in the table. The new row is inserted
221     * immediately before and in the same section as the current
222     * <code>index</code>th row in the table. If <code>index</code> is -1 or
223     * equal to the number of rows, the new row is appended. In addition,
224     * when the table is empty the row is inserted into a <code>TBODY</code>
225     * which is created and inserted into the table.A table row cannot be
226     * empty according to [<a href='http://www.w3.org/TR/1999/REC-html401-19991224'>HTML 4.01</a>].
227     * @param index The row number where to insert a new row. This index
228     *   starts from 0 and is relative to the logical order (not document
229     *   order) of all the rows contained inside the table.
230     * @return The newly created row.
231     * @exception DOMException
232     *   INDEX_SIZE_ERR: Raised if the specified index is greater than the
233     *   number of rows or if the index is a negative number other than -1.
234     * @version DOM Level 2
235     */
236    public HTMLElement insertRow(int index)
237                                 throws DOMException;
238
239    /**
240     * Delete a table row.
241     * @param index The index of the row to be deleted. This index starts
242     *   from 0 and is relative to the logical order (not document order) of
243     *   all the rows contained inside the table. If the index is -1 the
244     *   last row in the table is deleted.
245     * @exception DOMException
246     *   INDEX_SIZE_ERR: Raised if the specified index is greater than or
247     *   equal to the number of rows or if the index is a negative number
248     *   other than -1.
249     * @version DOM Level 2
250     */
251    public void deleteRow(int index)
252                          throws DOMException;
253
254}