1 /* 2 * Copyright (c) 2003 World Wide Web Consortium, 3 * (Massachusetts Institute of Technology, Institut National de 4 * Recherche en Informatique et en Automatique, Keio University). All 5 * Rights Reserved. This program is distributed under the W3C's Software 6 * Intellectual Property License. This program is distributed in the 7 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 8 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 9 * PURPOSE. 10 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 11 */ 12 13 package org.w3c.dom.html2; 14 15 import org.w3c.dom.DOMException; 16 17 /** 18 * The select element allows the selection of an option. The contained options 19 * can be directly accessed through the select element as a collection. See 20 * the SELECT element definition in HTML 4.01. 21 * <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>. 22 */ 23 public interface HTMLSelectElement extends HTMLElement { 24 /** 25 * The type of this form control. This is the string "select-multiple" 26 * when the multiple attribute is <code>true</code> and the string 27 * "select-one" when <code>false</code>. 28 */ getType()29 public String getType(); 30 31 /** 32 * The ordinal index of the selected option, starting from 0. The value -1 33 * is returned if no element is selected. If multiple options are 34 * selected, the index of the first selected option is returned. 35 */ getSelectedIndex()36 public int getSelectedIndex(); 37 /** 38 * The ordinal index of the selected option, starting from 0. The value -1 39 * is returned if no element is selected. If multiple options are 40 * selected, the index of the first selected option is returned. 41 */ setSelectedIndex(int selectedIndex)42 public void setSelectedIndex(int selectedIndex); 43 44 /** 45 * The current form control value (i.e. the value of the currently 46 * selected option), if multiple options are selected this is the value 47 * of the first selected option. 48 */ getValue()49 public String getValue(); 50 /** 51 * The current form control value (i.e. the value of the currently 52 * selected option), if multiple options are selected this is the value 53 * of the first selected option. 54 */ setValue(String value)55 public void setValue(String value); 56 57 /** 58 * The number of options in this <code>SELECT</code>. 59 * @version DOM Level 2 60 */ getLength()61 public int getLength(); 62 /** 63 * The number of options in this <code>SELECT</code>. 64 * @exception DOMException 65 * NOT_SUPPORTED_ERR: if setting the length is not allowed by the 66 * implementation. 67 * @version DOM Level 2 68 */ setLength(int length)69 public void setLength(int length) 70 throws DOMException; 71 72 /** 73 * Returns the <code>FORM</code> element containing this control. Returns 74 * <code>null</code> if this control is not within the context of a 75 * form. 76 */ getForm()77 public HTMLFormElement getForm(); 78 79 /** 80 * The collection of <code>OPTION</code> elements contained by this 81 * element. 82 * @version DOM Level 2 83 */ getOptions()84 public HTMLOptionsCollection getOptions(); 85 86 /** 87 * The control is unavailable in this context. See the disabled attribute 88 * definition in HTML 4.01. 89 */ getDisabled()90 public boolean getDisabled(); 91 /** 92 * The control is unavailable in this context. See the disabled attribute 93 * definition in HTML 4.01. 94 */ setDisabled(boolean disabled)95 public void setDisabled(boolean disabled); 96 97 /** 98 * If true, multiple <code>OPTION</code> elements may be selected in this 99 * <code>SELECT</code>. See the multiple attribute definition in HTML 100 * 4.01. 101 */ getMultiple()102 public boolean getMultiple(); 103 /** 104 * If true, multiple <code>OPTION</code> elements may be selected in this 105 * <code>SELECT</code>. See the multiple attribute definition in HTML 106 * 4.01. 107 */ setMultiple(boolean multiple)108 public void setMultiple(boolean multiple); 109 110 /** 111 * Form control or object name when submitted with a form. See the name 112 * attribute definition in HTML 4.01. 113 */ getName()114 public String getName(); 115 /** 116 * Form control or object name when submitted with a form. See the name 117 * attribute definition in HTML 4.01. 118 */ setName(String name)119 public void setName(String name); 120 121 /** 122 * Number of visible rows. See the size attribute definition in HTML 4.01. 123 */ getSize()124 public int getSize(); 125 /** 126 * Number of visible rows. See the size attribute definition in HTML 4.01. 127 */ setSize(int size)128 public void setSize(int size); 129 130 /** 131 * Index that represents the element's position in the tabbing order. See 132 * the tabindex attribute definition in HTML 4.01. 133 */ getTabIndex()134 public int getTabIndex(); 135 /** 136 * Index that represents the element's position in the tabbing order. See 137 * the tabindex attribute definition in HTML 4.01. 138 */ setTabIndex(int tabIndex)139 public void setTabIndex(int tabIndex); 140 141 /** 142 * Add a new element to the collection of <code>OPTION</code> elements for 143 * this <code>SELECT</code>. This method is the equivalent of the 144 * <code>appendChild</code> method of the <code>Node</code> interface if 145 * the <code>before</code> parameter is <code>null</code>. It is 146 * equivalent to the <code>insertBefore</code> method on the parent of 147 * <code>before</code> in all other cases. This method may have no 148 * effect if the new element is not an <code>OPTION</code> or an 149 * <code>OPTGROUP</code>. 150 * @param element The element to add. 151 * @param before The element to insert before, or <code>null</code> for 152 * the tail of the list. 153 * @exception DOMException 154 * NOT_FOUND_ERR: Raised if <code>before</code> is not a descendant of 155 * the <code>SELECT</code> element. 156 */ add(HTMLElement element, HTMLElement before)157 public void add(HTMLElement element, 158 HTMLElement before) 159 throws DOMException; 160 161 /** 162 * Remove an element from the collection of <code>OPTION</code> elements 163 * for this <code>SELECT</code>. Does nothing if no element has the 164 * given index. 165 * @param index The index of the item to remove, starting from 0. 166 */ remove(int index)167 public void remove(int index); 168 169 /** 170 * Removes keyboard focus from this element. 171 */ blur()172 public void blur(); 173 174 /** 175 * Gives keyboard focus to this element. 176 */ focus()177 public void focus(); 178 179 } 180