elemental.html.SelectElement Maven / Gradle / Ivy
/*
* Copyright 2012 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package elemental.html;
import elemental.dom.Node;
import elemental.dom.Element;
import elemental.dom.NodeList;
import elemental.events.*;
import elemental.util.*;
import elemental.dom.*;
import elemental.html.*;
import elemental.css.*;
import elemental.stylesheets.*;
import java.util.Date;
/**
* DOM select elements share all of the properties and methods of other HTML elements described in the element
section. They also have the specialized interface HTMLSelectElement (or
HTML 4 HTMLSelectElement).
*/
public interface SelectElement extends Element {
/**
* Reflects the
autofocus
HTML attribute, which indicates whether the control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form-associated element in a document can have this attribute specified.
HTML5
Requires Gecko 2.0
*/
boolean isAutofocus();
void setAutofocus(boolean arg);
/**
* Reflects the
disabled
HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks.
*/
boolean isDisabled();
void setDisabled(boolean arg);
/**
* The form that this element is associated with. If this element is a descendant of a form element, then this attribute is the ID of that form element. If the element is not a descendant of a form element, then: -
HTML5 The attribute can be the ID of any form element in the same document.
-
HTML 4 The attribute is null.
Read only.
*/
FormElement getForm();
/**
* A list of label elements associated with this select element.
*/
NodeList getLabels();
/**
* The number of <option>
elements in this select element.
*/
int getLength();
void setLength(int arg);
/**
* Reflects the
multiple
HTML attribute, whichindicates whether multiple items can be selected.
*/
boolean isMultiple();
void setMultiple(boolean arg);
/**
* Reflects the
name
HTML attribute, containing the name of this control used by servers and DOM search functions.
*/
String getName();
void setName(String arg);
/**
* The set of <option>
elements contained by this element. Read only.
*/
HTMLOptionsCollection getOptions();
/**
* Reflects the
required
HTML attribute, which indicates whether the user is required to select a value before submitting the form.
HTML5
Requires Gecko 2.0
*/
boolean isRequired();
void setRequired(boolean arg);
/**
* The index of the first selected <option>
element.
*/
int getSelectedIndex();
void setSelectedIndex(int arg);
/**
* The set of options that are selected.
HTML5
*/
HTMLCollection getSelectedOptions();
/**
* Reflects the
size
HTML attribute, which contains the number of visible items in the control. The default is 1,
HTML5 unless multiple is true, in which case it is 4.
*/
int getSize();
void setSize(int arg);
/**
* The form control's type. When multiple is true, it returns select-multiple; otherwise, it returns select-one.Read only.
*/
String getType();
/**
* A localized message that describes the validation constraints that the control does not satisfy (if any). This attribute is the empty string if the control is not a candidate for constraint validation (willValidate is false), or it satisfies its constraints.Read only.
HTML5
Requires Gecko 2.0
*/
String getValidationMessage();
/**
* The validity states that this control is in. Read only.
HTML5
Requires Gecko 2.0
*/
ValidityState getValidity();
/**
* The value of this form control, that is, of the first selected option.
*/
String getValue();
void setValue(String arg);
/**
* Indicates whether the button is a candidate for constraint validation. It is false if any conditions bar it from constraint validation. Read only.
HTML5
Requires Gecko 2.0
*/
boolean isWillValidate();
/**
* Adds an element to the collection of option elements for this select element.
Parameters
element- An item to add to the collection of options.
before
Optional from Gecko 7.0
- An item (or
HTML5 index of an item) that the new item should be inserted before. If this parameter is
null (or the index does not exist), the new element is appended to the end of the collection.
Examples
Creating Elements from Scratch
var sel = document.createElement("select");
var opt1 = document.createElement("option");
var opt2 = document.createElement("option");
opt1.value = "1";
opt1.text = "Option: Value 1";
opt2.value = "2";
opt2.text = "Option: Value 2";
sel.add(opt1, null);
sel.add(opt2, null);
/*
Produces the following, conceptually:
<select>
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
</select>
*/
From
HTML5 and Gecko 7.0 the before parameter is optional. So the following is accepted.
...
sel.add(opt1);
sel.add(opt2);
...
Append to an Existing Collection
var sel = document.getElementById("existingList");
var opt = document.createElement("option");
opt.value = "3";
opt.text = "Option: Value 3";
sel.add(opt, null);
/*
Takes the existing following select object:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
</select>
And changes it to:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
<option value="3">Option: Value 3</option>
</select>
*/
From
HTML5 and Gecko 7.0 the before parameter is optional. So the following is accepted.
...
sel.add(opt);
...
Inserting to an Existing Collection
var sel = document.getElementById("existingList");
var opt = document.createElement("option");
opt.value = "3";
opt.text = "Option: Value 3";
sel.add(opt, sel.options[1]);
/*
Takes the existing following select object:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
</select>
And changes it to:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="3">Option: Value 3</option>
<option value="2">Option: Value 2</option>
</select>
*/
Obsolete since Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2)
*/
void add(Element element, Element before);
/**
* HTML5 Checks whether the element has any constraints and whether it satisfies them. If the element fails its constraints, the browser fires a cancelable invalid event at the element (and returns false).
Return value
A false value if the select element is a candidate for constraint evaluation and it does not satisfy its constraints. Returns true if the element is not constrained, or if it satisfies its constraints.
Obsolete since Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2)
*/
boolean checkValidity();
/**
* HTML5 Gets an item from the options collection for this select element. You can also access an item by specifying the index in array-style brackets or parentheses, without calling this method explicitly.
Parameters
index- The zero-based index into the collection of the option to get.
Return value
The node at the specified index, or null if such a node does not exist in the collection.
*/
Node item(int index);
/**
* HTML5 Gets the item in the options collection with the specified name. The name string can match either the id or the name attribute of an option node. You can also access an item by specifying the name in array-style brackets or parentheses, without calling this method explicitly.
Parameters
name- The name of the option to get.
Return value
- A node, if there is exactly one match.
null if there are no matches.- A
NodeList
in tree order of nodes whose name or id attributes match the specified name.
*/
Node namedItem(String name);
/**
* Removes the element at the specified index from the options collection for this select element.
Parameters
index- The zero-based index of the option element to remove from the collection.
Example
var sel = document.getElementById("existingList");
sel.remove(1);
/*
Takes the existing following select object:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
<option value="3">Option: Value 3</option>
</select>
And changes it to:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="3">Option: Value 3</option>
</select>
*/
*/
void remove(int index);
/**
* Removes the element at the specified index from the options collection for this select element.
Parameters
index- The zero-based index of the option element to remove from the collection.
Example
var sel = document.getElementById("existingList");
sel.remove(1);
/*
Takes the existing following select object:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="2">Option: Value 2</option>
<option value="3">Option: Value 3</option>
</select>
And changes it to:
<select id="existingList" name="existingList">
<option value="1">Option: Value 1</option>
<option value="3">Option: Value 3</option>
</select>
*/
*/
void remove(OptionElement option);
/**
* HTML5 only. Sets the custom validity message for the selection element to the specified message. Use the empty string to indicate that the element does not have a custom validity error.
Parameters
error- The string to use for the custom validity message.
*/
void setCustomValidity(String error);
}