getOwnPropertyDescriptor Method (Windows Scripting - JScript)

Returns the property definition of a Document Object Model (DOM) property.

Syntax

Object.getOwnPropertyDescriptor(object, propertyname)

Arguments

• object
  Required. The existing DOM object that contains the property.

• propertyname
  Required. A string that contains the name of the property.

Return Value

A JScript object that contains a descriptor that describes the property of the DOM object. The definition can be for a data property or an accessor property.

Remarks

You can use the getOwnPropertyDescriptor method to obtain the property definition of a DOM property. The method returns a descriptor object that describes attributes of the property. The attributes of the descriptor object determine whether the property is an accessor property or a data property.

The defineProperty Method (Windows Scripting - JScript) is used to add an accessor property or data property to an existing DOM object.

Accessor Properties

An accessor property calls a user-provided function every time that the property value is set or retrieved. The descriptor object for an accessor property contains a get attribute, a set attribute, or both.

In the accessor property descriptor, the enumerable attribute can be set to false, or it can be unspecified. The configurable property can be set to true, or it can be unspecified. Those attributes are reserved for future use.

When a get accessor is not specified and an attempt is made to access the property value, the value undefined is returned. When a set accessor is not specified and an attempt is made to assign a value to the accessor property, nothing occurs.

Data Properties

A data property is a property that can store and retrieve a value. The descriptor object for a data property contains a value attribute, a writable attribute, or both.

In the data property descriptor, the writable attribute, the enumerable attribute, and the configurable property can each be set to true, or they can be unspecified.

In the following example, the getOwnPropertyDescriptor method is used to obtain the definition of an accessor property of a DOM object.

function AddAccessorProperty()
    {
    var obj = window.document;

    // Create the descriptor for the new accessor property.
    var descriptor =
        {
        set: function (x)
            {
            println("in property set accessor");
            this.newaccpropvalue = x;
            },
        get: function ()
            {
            println("in property get accessor");
            return this.newaccpropvalue;
            },
        enumerable: false,
        configurable: true
        };

    // Display the descriptor's properties.
    ShowProperties (descriptor, "accessor descriptor");

    // Add the new data property to the window.document object.
    Object.defineProperty (obj, "NewAccessorProperty", descriptor);

    // Set the property value.
    println ("<i>Setting and getting accessor property value</i>");

    obj.NewAccessorProperty = 42;
    println ("Property value: " + obj.NewAccessorProperty);
    println ("");

    // Get the descriptor from the object's property.
    var descfromprop = Object.getOwnPropertyDescriptor(obj, "NewAccessorProperty");

    // Display the descriptor's properties.
    ShowProperties (descfromprop, "descfromprop accessor descriptor");
    }

function ShowProperties(objwithproperties, description)
    {
    println ("<i>properties in " + description + "</i>");
    for (var prop in objwithproperties)
        {
        println(prop + ': ' + objwithproperties[prop]);
        }
    println ("");
    }

function println(s)
    {
    document.write(s + '<br>');
    }

In the following example, the getOwnPropertyDescriptor method is used to obtain the definition of a data property of a DOM object. The ShowProperties() and println() support functions are in the previous example.

function AddDataProperty()
    {
    var obj = window.document;

    // Create the descriptor for the new data property.
    var descriptor =
    {
      value: 101,
      writable: true,
      enumerable: true,
      configurable: true
    };
 
    // Display the descriptor's properties.
    ShowProperties (descriptor, "descriptor");

    // Add the new data property to the window.document object.
    Object.defineProperty (obj, "NewDataProperty", descriptor);

    // Display the properties of the window.document object,
    // which now includes the NewDataProperty property.
    ShowProperties (obj, "window.document object");

    // Display the property value.
    // Output: 101
    println ("Initial value: " + obj.NewDataProperty);

    // Modify and display the property value.
    // This is allowed if the descriptor's writable value is true.
    obj.NewDataProperty = 45;
    println ("Modified value: " + obj.NewDataProperty);
    println ("");

    // Get the descriptor from the object's property.
    var descfromprop = Object.getOwnPropertyDescriptor(obj, "NewDataProperty");

    // Display the descriptor's properties.
    ShowProperties (descfromprop, "descfromprop descriptor");
    }

Requirements

Version 5.8

Change History

See Also

defineProperty Method (Windows Scripting - JScript)
Broken link. The 'expie20081007a' GUID is not correct.