defineSetter method

Article
05/02/2017

Obsolete. Do not use.

Allows developers to create new or override existing Document Object Model (DOM) properties and functions using functionality implemented by a custom Microsoft JScript function. The custom function is used to set the value of a property or a function.

Syntax

HRESULT retVal = object.defineSetter(propname, pdispHandler);

Parameters

propname [in]
Type: BSTR

Name of the property or function to be modified.
pdispHandler [in]
Type: IDispatch

Name of the JScript function that provides the new functionality.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The name of the method is preceded and followed by two underscore characters (__).

The IHTMLDOMConstructor::DefineSetter method can be used to override DOM properties, DOM functions, and expandos. You cannot use IHTMLDOMConstructor::DefineSetter to override JScript objects or functions.

When defined for built-in properties or functions, IHTMLDOMConstructor::DefineSetter overrides the built-in property or function. When referring to functions that support arguments, include required arguments in the call to IHTMLDOMConstructor::DefineSetter.

Use the delete operator to delete custom properties or functions created using IHTMLDOMConstructor::DefineSetter and to restore overridden properties or functions to their original functionality.

To cache (save) a function to be overriden with IHTMLDOMConstructor::DefineSetter, assign the function to a variable before overriding it. To invoke behavior cached to a variable, use the apply method or the call method.

The IHTMLDOMConstructor::DefineSetter is only supported in IE8 Standards mode. For more information, see Defining Document Compatibility.

Warning This feature is not yet standardized and the current implementation is based on similar features in other web browsers. Should the final standard specify an alternate implementation, the current implementation may change.

Examples

This example shows how to create a write only property, a property that cannot be read.

try
{
  document.__defineSetter__("writeOnlyProp", function(value)
  {
    alert("write only: " + value);
  }
} catch(e)
  { alert( "setter not supported: " + e.message); }

// Displays "to-write" in IE8 and "undefined"
// in earlier versions.
document.writeOnlyProp = "to-write";
alert( document.readOnlyProp );