item Method (IHTMLElementCollection)

item Method

IHTMLElementCollection::item Method

Retrieves a form object or an object from an elements collection.

Syntax

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

Parameters

name
[in] VARIANT of type VT_I4 or VT_BSTR that specifies the object or collection to retrieve. If this parameter is an integer, it is the zero-based index of the object. If this parameter is a string, all objects with matching name or id properties are retrieved, and a collection is returned if more than one match is made.
index
[in] VARIANT of type VT_I4 that specifies the zero-based index of the object to retrieve when a collection is returned.
pdisp
[out, retval] The address of a pointer that receives an IDispatch interface for the object or collection if successful, or NULL otherwise.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Note This method indexes collections by the name or id property of the object; this is a known standards-compliance issue. For interoperability with other browsers, do not reference an object by name using this method.
Internet Explorer 8 and later. In IE8 mode, the index parameter is not used. For more information, see Defining Document Compatibility.
Call QueryInterface on the IDispatch interface pointer retrieved to pdisp to obtain the correct interface for the object or collection.
This function returns S_OK even if the element is not found. You should check the value of the pdisp (IDispatch) pointer returned by this call. If the value of the pointer is NULL, the element was not found and the call was not successful.

Examples

The following example shows how to use the IHTMLSelectElement::length property and item method to iterate through the option objects within a select object.

HRESULT GetOptions(IHTMLSelectElement *ppvSelect, BSTR *pszOptText, long *plItems)
{
    IDispatch *ppvdispOption;
    IHTMLOptionElement *ppvOption;
    HRESULT hResult;

    // Obtain the number of option objects in the select object.
    ppvSelect->get_length(plItems);
 
    for (long i=0;i<*plItems;i++){

        // Get an IDispatch interface for the next option.
        _variant_t index = i;
        hResult = ppvSelect->item( index, index, &ppvdispOption );
        if FAILED(hResult) return(hResult);

        // Query for the IHTMLOptionElement interface.
        hResult = ppvdispOption->QueryInterface( IID_IHTMLOptionElement, 
                                                 (void **) &ppvOption);
        ppvdispOption->Release();
        if FAILED(hResult) return(hResult);

        // Add the option text to a list box.
        hResult = ppvOption->get_text(&(pszOptText[i]));
        ppvOption->Release();
        if FAILED(hResult) return(hResult);
    }
    return S_OK;
}

Tags

: Add a tag

Community Content

Add new content

Annotations

A clarification of the sample code

FredRing ... unuseddisplayname | Edit | Show History

In practical application the name and index arguments will almost never be the same value. To look up an HTML element by name you are likely to need a modification to the sample code like this:

_variant_t name = "NameOfElement";  // or zero-based index in the IHTMLElementCollection
_variant_t index = 0l;
hResult = ppvSelect->item( name, index, &ppvdispOption );
if FAILED(hResult) return(hResult);

This assumes each element on the document has a unique name - a likely scenario. But if you have more than one element with the same name this might not be the right solution for you. In that case the index is "the zero-based index of the object to retrieve when a collection is returned." So keep this in mind if you don't get back the element you were looking for as there might be more than one with the same name.