IHTMLSelectElement

IHTMLSelectElement


This interface provides access to the properties and methods of the SELECT element.

IHTMLSelectElement Methods
put_size   get_size   put_multiple  
get_multiple   put_name   get_name  
get_options   put_onchange   get_onchange  
put_selectedIndex   get_selectedIndex   get_type  
put_value   get_value   put_disabled  
get_disabled   get_form   add  
remove   put_length   get_length  
get__newEnum   item   tags  

IHTMLSelectElement::put_size

HRESULT put_size(
   long v 
);

Specifies the number of rows in the list box.

v
Value specifying the number of rows.

See also get_size

IHTMLSelectElement::get_size

HRESULT get_size(
    long *p 
);

Retrieves the number of rows in the list box.

p
Address of a variable that receives the number of rows.

See also put_size

IHTMLSelectElement::put_multiple

HRESULT put_multiple(
    VARIANT_BOOL v 
);

Specifies whether multiple items in the list can be selected.

v
Multiple-items flag. If TRUE, multiple items can be selected; if FALSE, they cannot.

The default value for this property is FALSE.

See also get_multiple

IHTMLSelectElement::get_multiple

HRESULT get_multiple(
    VARIANT_BOOL *p 
);

Determines whether multiple items in the list can be selected.

p
Address of a variable that receives TRUE if multiple items can be selected, or FALSE if not.

The default value for this property is FALSE.

See also put_multiple

IHTMLSelectElement::put_name

HRESULT put_name(
    BSTR v 
);

Sets the name of the control, bookmark, or application.

v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name

IHTMLSelectElement::get_name

HRESULT get_name(
    BSTR *p 
);

Retrieves the name of the control, bookmark, or application.

p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

IHTMLSelectElement::get_options

HRESULT get_options( 
    IDispatch **p 
);

Retrieves an interface pointer for a collection of OPTION elements in a SELECT object.

p
Address of a variable that receives the interface pointer.

IHTMLSelectElement::put_onchange

HRESULT put_onchange( 
    VARIANT v 
);

Sets the inline script associated with the onchange event on the SELECT element. This occurs when the contents of the object have changed.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

v
VARIANT structure that contains the script to be set.

See also get_onchange

IHTMLSelectElement::get_onchange

HRESULT get_onchange(
    VARIANT *p 
);

Retrieves the inline script associated with the onchange event on the SELECT element. This occurs when the contents of the object have changed.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

p
Address of a VARIANT structure that contains the script.

See also put_onchange

IHTMLSelectElement::put_selectedIndex

HRESULT put_selectedIndex(
    long v 
);

Selects an item in the list box or drop-down list associated with the select object.

v
Value specifying the zero-based index of the item to select.

Options in a select object are indexed in the order in which they are defined, starting with an index of 0. You can set the selectedIndex property at any time. The display of the select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value.

In general, the selectedIndex property is more useful for select objects that are created without the multiple attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the select object.

The selected property of the select object's options array is more useful for select objects that are created with the multiple attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

See also get_selectedIndex

IHTMLSelectElement::get_selectedIndex

HRESULT get_selectedIndex(
    long *p 
);

Retreives the index of the selected item in the list box or drop-down list associated with the select object.

p
Address of a variable that receives the index of the selected item.

Options in a select object are indexed in the order in which they are defined, starting with an index of 0. You can set the selectedIndex property at any time. The display of the select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value.

In general, the selectedIndex property is more useful for select objects that are created without the multiple attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the select object.

The selected property of the select object's options array is more useful for select objects that are created with the multiple attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

See also put_selectedIndex

IHTMLSelectElement::get_type

HRESULT get_type(
    BSTR *p 
);

Retrieves the type of intrinsic control represented by the given element object.

p
Address of a string variable that receives the type. The possible values depend on the element, as listed in the following table.
Element Possible value Description
INPUT checkbox Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file A file upload element.
hidden No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the FORM, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT select-multiple Specifies a multiple-select list box.
select-one Specifies a single-select list box.
TEXTAREA textarea Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.

IHTMLSelectElement::put_value

HRESULT put_value(
    BSTR v 
);

Sets the value of the object.

v
String specifying the value.

See also get_value

IHTMLSelectElement::get_value

HRESULT get_value(
    BSTR *p 
);

Retrieves the value of the object.

p
Address of a variable that receives the value.

See also put_value

IHTMLSelectElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v 
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled

IHTMLSelectElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p 
);

Determines whether the control is enabled or disabled.

p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

IHTMLSelectElement::get_form

HRESULT get_form(
    IHTMLFormElement **p 
);

Retrieves a reference to the form the element is embedded on.

p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement

IHTMLSelectElement::add

HRESULT add(
    IHTMLElement *element,
    VARIANT before 
);

Adds an OPTION element to a SELECT block.

element
Interface pointer to the OPTION element to add.
before
Zero-based index specifying the position of the OPTION element within the SELECT block.

See also remove

IHTMLSelectElement::remove

HRESULT remove(
    long index 
);

Removes the given element from the SELECT block.

index
Zero-based index of the item to remove.

See also add

IHTMLSelectElement::put_length

HRESULT put_length(
    long v 
);

Sets the number of elements in the SELECT block.

v
Value specifying the number of elements.

See also get_length

IHTMLSelectElement::get_length

HRESULT get_length(
    long *p 
);

Retrieves the number of elements in the SELECT block.

p
Address of a variable that receives the number of elements.

See also put_length

IHTMLSelectElement::get__newEnum

HRESULT get__newEnum(
    IUnknown **p 
);

Retrieves an enumerator interface which can be used to iterate through the options collection of the select element.

p
Address of a variable that receives the enumerator interface pointer.

IHTMLSelectElement::item

HRESULT item(
    VARIANT name,
    VARIANT index,
    IDispatch **pdisp 
);

Retrieves an interface pointer for an element in a SELECT block.

name
Number or string specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter contains a string, the method returns a collection of elements, where the value of the NAME or ID= property for each element is equal to the string.
index
Number specifying the position of an element to retrieve. This parameter is used when name is a string. The method uses the string to construct a collection of all elements that have a NAME or ID= equal to the string, then retrieves from this collection the element at the position specified by index.
pdisp
Address of a variable that receives an interface pointer to the element object.

IHTMLSelectElement::tags

HRESULT tags(
    VARIANT tagName,
    IDispatch **pdisp 
);

Retrieves a collection of all elements in the given collection that have the given HTML tag name.

tagName
String specifying the tag name.
pdisp
Address of a variable that receives an interface pointer to the collection.

This method returns an empty collection if no elements having the given name are found. Use the length property on the collection to determine the number of elements it contains.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.