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 013 package org.w3c.dom.html2; 014 015 import org.w3c.dom.DOMException; 016 017 /** 018 * The select element allows the selection of an option. The contained options 019 * can be directly accessed through the select element as a collection. See 020 * the SELECT element definition in HTML 4.01. 021 * <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>. 022 */ 023 public interface HTMLSelectElement extends HTMLElement { 024 /** 025 * The type of this form control. This is the string "select-multiple" 026 * when the multiple attribute is <code>true</code> and the string 027 * "select-one" when <code>false</code>. 028 */ 029 public String getType(); 030 031 /** 032 * The ordinal index of the selected option, starting from 0. The value -1 033 * is returned if no element is selected. If multiple options are 034 * selected, the index of the first selected option is returned. 035 */ 036 public int getSelectedIndex(); 037 /** 038 * The ordinal index of the selected option, starting from 0. The value -1 039 * is returned if no element is selected. If multiple options are 040 * selected, the index of the first selected option is returned. 041 */ 042 public void setSelectedIndex(int selectedIndex); 043 044 /** 045 * The current form control value (i.e. the value of the currently 046 * selected option), if multiple options are selected this is the value 047 * of the first selected option. 048 */ 049 public String getValue(); 050 /** 051 * The current form control value (i.e. the value of the currently 052 * selected option), if multiple options are selected this is the value 053 * of the first selected option. 054 */ 055 public void setValue(String value); 056 057 /** 058 * The number of options in this <code>SELECT</code>. 059 * @version DOM Level 2 060 */ 061 public int getLength(); 062 /** 063 * The number of options in this <code>SELECT</code>. 064 * @exception DOMException 065 * NOT_SUPPORTED_ERR: if setting the length is not allowed by the 066 * implementation. 067 * @version DOM Level 2 068 */ 069 public void setLength(int length) 070 throws DOMException; 071 072 /** 073 * Returns the <code>FORM</code> element containing this control. Returns 074 * <code>null</code> if this control is not within the context of a 075 * form. 076 */ 077 public HTMLFormElement getForm(); 078 079 /** 080 * The collection of <code>OPTION</code> elements contained by this 081 * element. 082 * @version DOM Level 2 083 */ 084 public HTMLOptionsCollection getOptions(); 085 086 /** 087 * The control is unavailable in this context. See the disabled attribute 088 * definition in HTML 4.01. 089 */ 090 public boolean getDisabled(); 091 /** 092 * The control is unavailable in this context. See the disabled attribute 093 * definition in HTML 4.01. 094 */ 095 public void setDisabled(boolean disabled); 096 097 /** 098 * If true, multiple <code>OPTION</code> elements may be selected in this 099 * <code>SELECT</code>. See the multiple attribute definition in HTML 100 * 4.01. 101 */ 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 */ 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 */ 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 */ 119 public void setName(String name); 120 121 /** 122 * Number of visible rows. See the size attribute definition in HTML 4.01. 123 */ 124 public int getSize(); 125 /** 126 * Number of visible rows. See the size attribute definition in HTML 4.01. 127 */ 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 */ 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 */ 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 */ 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 */ 167 public void remove(int index); 168 169 /** 170 * Removes keyboard focus from this element. 171 */ 172 public void blur(); 173 174 /** 175 * Gives keyboard focus to this element. 176 */ 177 public void focus(); 178 179 }