elemental.html

Interface SelectElement

All Superinterfaces:

Element, ElementTraversal, EventTarget, Node, NodeSelector

All Known Implementing Classes:

JsSelectElement

public interface SelectElement
extends Element

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).

Field Summary

Fields inherited from interface elemental.dom.Element

ALLOW_KEYBOARD_INPUT

Fields inherited from interface elemental.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Element element, Element before) Adds an element to the collection of option elements for this select element.
boolean	checkValidity()
FormElement	getForm() The form that this element is associated with.
NodeList	getLabels() A list of label elements associated with this select element.
int	getLength() The number of <option> elements in this select element.
String	getName() Reflects the name HTML attribute, containing the name of this control used by servers and DOM search functions.
HTMLOptionsCollection	getOptions() The set of <option> elements contained by this element.
int	getSelectedIndex() The index of the first selected <option> element.
HTMLCollection	getSelectedOptions() The set of options that are selected.
int	getSize() Reflects the size HTML attribute, which contains the number of visible items in the control.
String	getType() The form control's type.
String	getValidationMessage() A localized message that describes the validation constraints that the control does not satisfy (if any).
ValidityState	getValidity() The validity states that this control is in.
String	getValue() The value of this form control, that is, of the first selected option.
boolean	isAutofocus() 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.
boolean	isDisabled() Reflects the disabled HTML attribute, which indicates whether the control is disabled.
boolean	isMultiple() Reflects the multiple HTML attribute, whichindicates whether multiple items can be selected.
boolean	isRequired() Reflects the required HTML attribute, which indicates whether the user is required to select a value before submitting the form.
boolean	isWillValidate() Indicates whether the button is a candidate for constraint validation.
Node	item(int index)
Node	namedItem(String name)
void	remove(int index) Removes the element at the specified index from the options collection for this select element.
void	remove(OptionElement option) Removes the element at the specified index from the options collection for this select element.
void	setAutofocus(boolean arg)
void	setCustomValidity(String error) HTML5 only.
void	setDisabled(boolean arg)
void	setLength(int arg)
void	setMultiple(boolean arg)
void	setName(String arg)
void	setRequired(boolean arg)
void	setSelectedIndex(int arg)
void	setSize(int arg)
void	setValue(String arg)

Methods inherited from interface elemental.dom.Element

blur, click, focus, getAccessKey, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getBoundingClientRect, getChildElementCount, getChildren, getClassList, getClassName, getClientHeight, getClientLeft, getClientRects, getClientTop, getClientWidth, getContentEditable, getDataset, getDir, getElementsByClassName, getElementsByTagName, getElementsByTagNameNS, getFirstElementChild, getId, getInnerHTML, getInnerText, getLang, getLastElementChild, getNextElementSibling, getOffsetHeight, getOffsetLeft, getOffsetParent, getOffsetTop, getOffsetWidth, getOnabort, getOnbeforecopy, getOnbeforecut, getOnbeforepaste, getOnblur, getOnchange, getOnclick, getOncontextmenu, getOncopy, getOncut, getOndblclick, getOndrag, getOndragend, getOndragenter, getOndragleave, getOndragover, getOndragstart, getOndrop, getOnerror, getOnfocus, getOninput, getOninvalid, getOnkeydown, getOnkeypress, getOnkeyup, getOnload, getOnmousedown, getOnmousemove, getOnmouseout, getOnmouseover, getOnmouseup, getOnmousewheel, getOnpaste, getOnreset, getOnscroll, getOnsearch, getOnselect, getOnselectstart, getOnsubmit, getOntouchcancel, getOntouchend, getOntouchmove, getOntouchstart, getOnwebkitfullscreenchange, getOnwebkitfullscreenerror, getOuterHTML, getOuterText, getPreviousElementSibling, getScrollHeight, getScrollLeft, getScrollTop, getScrollWidth, getStyle, getTabIndex, getTagName, getTitle, getWebkitdropzone, getWebkitRegionOverflow, hasAttribute, hasAttributeNS, insertAdjacentElement, insertAdjacentHTML, insertAdjacentText, isContentEditable, isDraggable, isHidden, isSpellcheck, isTranslate, querySelector, querySelectorAll, removeAttribute, removeAttributeNode, removeAttributeNS, scrollByLines, scrollByPages, scrollIntoView, scrollIntoView, scrollIntoViewIfNeeded, scrollIntoViewIfNeeded, setAccessKey, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setClassName, setContentEditable, setDir, setDraggable, setHidden, setId, setInnerHTML, setInnerText, setLang, setOnabort, setOnbeforecopy, setOnbeforecut, setOnbeforepaste, setOnblur, setOnchange, setOnclick, setOncontextmenu, setOncopy, setOncut, setOndblclick, setOndrag, setOndragend, setOndragenter, setOndragleave, setOndragover, setOndragstart, setOndrop, setOnerror, setOnfocus, setOninput, setOninvalid, setOnkeydown, setOnkeypress, setOnkeyup, setOnload, setOnmousedown, setOnmousemove, setOnmouseout, setOnmouseover, setOnmouseup, setOnmousewheel, setOnpaste, setOnreset, setOnscroll, setOnsearch, setOnselect, setOnselectstart, setOnsubmit, setOntouchcancel, setOntouchend, setOntouchmove, setOntouchstart, setOnwebkitfullscreenchange, setOnwebkitfullscreenerror, setOuterHTML, setOuterText, setScrollLeft, setScrollTop, setSpellcheck, setTabIndex, setTitle, setTranslate, setWebkitdropzone, webkitMatchesSelector, webkitRequestFullscreen, webkitRequestFullScreen

Methods inherited from interface elemental.dom.Node

addEventListener, addEventListener, appendChild, cloneNode, compareDocumentPosition, contains, dispatchEvent, getAttributes, getBaseURI, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentElement, getParentNode, getPrefix, getPreviousSibling, getTextContent, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, removeEventListener, removeEventListener, replaceChild, setNodeValue, setPrefix, setTextContent

Method Detail

isAutofocus

boolean isAutofocus()

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

setAutofocus

void setAutofocus(boolean arg)

isDisabled

boolean isDisabled()

Reflects the disabled HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks.

setDisabled

void setDisabled(boolean arg)

getForm

FormElement getForm()

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.

getLabels

NodeList getLabels()

A list of label elements associated with this select element.

getLength

int getLength()

The number of <option> elements in this select element.

setLength

void setLength(int arg)

isMultiple

boolean isMultiple()

Reflects the multiple HTML attribute, whichindicates whether multiple items can be selected.

setMultiple

void setMultiple(boolean arg)

getName

String getName()

Reflects the name HTML attribute, containing the name of this control used by servers and DOM search functions.

setName

void setName(String arg)

getOptions

HTMLOptionsCollection getOptions()

The set of <option> elements contained by this element. Read only.

isRequired

boolean isRequired()

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

setRequired

void setRequired(boolean arg)

getSelectedIndex

int getSelectedIndex()

The index of the first selected <option> element.

setSelectedIndex

void setSelectedIndex(int arg)

getSelectedOptions

HTMLCollection getSelectedOptions()

The set of options that are selected. HTML5

getSize

int getSize()

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.

setSize

void setSize(int arg)

getType

String getType()

The form control's type. When multiple is true, it returns select-multiple; otherwise, it returns select-one.Read only.

getValidationMessage

String getValidationMessage()

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

getValidity

ValidityState getValidity()

The validity states that this control is in. Read only. HTML5 Requires Gecko 2.0

getValue

String getValue()

The value of this form control, that is, of the first selected option.

setValue

void setValue(String arg)

isWillValidate

boolean isWillValidate()

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

add

void add(Element element,
       Element before)

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)

checkValidity

boolean checkValidity()

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)

item

Node item(int index)

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.

namedItem

Node namedItem(String name)

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.

remove

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>
/

remove

void remove(OptionElement option)

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>
/

setCustomValidity

void setCustomValidity(String error)

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.