textarea | NN 2 IE 3 DOM 1
The textarea object reflects the textarea element and is used as a form control. This object is the primary way of getting a user to enter multiple lines of text for submission to the server. Note that the innerHTML property is not available on the Macintosh version of Internet Explorer 4. Only a limited number of properties and methods shown below are available in early browsers that do not support addressing all HTML elements (prior to IE 4 and Netscape 6). IE 5 and later support the shared doScroll( ) method for this object.
HTML Equivalent
    <textarea>
Object Model Reference
    [window.]document.formName.elementName
    [window.]document.forms[i].elements[j]
    [window.]document.getElementById("elementID")
Object-Specific Properties
cols | dataFld | dataSrc | defaultValue | form
name | readOnly | rows | status | type
value | wrap |  |  |
Object-Specific Methods
createTextRange( ) | handleEvent[ ] | select( )
Object-Specific Event Handler Properties
Handler | NN | IE | DOM
onblur | 2 | 3 | n/a
onchange | 2 | 3 | n/a
onfocus | 2 | 3 | n/a
onkeydown | 4 | 4 | n/a
onkeypress | 4 | 4 | n/a
onkeyup | 4 | 4 | n/a
onscroll | n/a | 4 | n/a
onselect | 2 | 3 | n/a

accessKey | NN n/a IE 4 DOM 1
| Read/Write
This is single character key that either gives focus to an element (in some browsers) or activates a form control or link action. The browser and operating system determine if the user must press a modifier key (e.g., Ctrl, Alt, or Command) with the access key to activate the link. In Windows versions of IE 5 and later and Netscape 6, the Alt key is required and the key is not case-sensitive. For Macintosh versions of IE 5 and later and Netscape 6, the Ctrl modifier key is required to effect the action.
Although listed here as a widely shared property, that isn't strictly the case across all implementations. Netscape 6 (per the W3C DOM) recognizes this property only for the following elements: a, area, button, input, label, legend, and textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, object, select, span, table, and td (but removes label and legend). IE 5 adds every other renderable element, but with a caution. Except for input and other form-related elements, you must also assign a tabindex attribute or tabIndex property value to the IE 5 and later element (even if it's simply a value of zero for all) to let the accelerator key combination bring focus to the element. As of Version 7, Netscape does not alter UI behavior if a script changes the property's value.
Example
    document.links[3].accessKey = "n";
Value
Single alphanumeric (and punctuation) keyboard character.
Default
Empty string.

blur( ) | NN 2 IE 3 DOM 1
Removes focus from the current object, at which time the object's onblur event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the blur( ) method to blatantly focusable elements, such as text input and textarea elements. Assigning the attribute onfocus="this.blur( );" to a text input element, for instance, is a crude but effective backward-compatible way to largely disable a field for browsers that do not provide genuine element disabling.
Use blur( ) and focus( ) methods in moderation on the same page. You can inadvertently trigger endless loops of blurring and focusing if alert dialog boxes are involved along the way. Moreover, be aware that when you invoke the blur( ) method on one object, some other object (perhaps the window object) receives an onfocus event.
Parameters
None.
Returned Value
None.

clientHeight, clientWidth | NN 7 IE 4 DOM n/a
| Read-only
Broadly speaking, these provide the height and width of the element's content, but with minor variations with respect to element padding among various operating system versions of IE and compatibility modes controlled by the DOCTYPE declaration. Not available for all element types in IE for Macintosh. For Netscape 7, values are zero except when an element's content overflows the viewable area, in which case the values reveal the dimensions of the viewable area (e.g., the browser window's content region for the document.body element). See the Section 9.2 at the beginning of this chapter for details.
Example
    var midHeight = document.body.clientHeight/2;
Value
Integer pixel value.
Default
0

clientLeft, clientTop | NN n/a IE 4 DOM n/a
| Read-only
Broadly speaking, these provide the left and top coordinates of the element's content within the box that includes the element's padding, but with minor variations among various operating system versions of IE. Not available for all element types in IE for Macintosh. See the Section 9.2 at the beginning of this chapter for details. More useful information for inline element positioning generally comes from the offsetLeft and offsetTop properties (including Netscape 6). For CSS-positioned elements (including changing an element's position), use style object properties, such as left and top, and (in IE only) pixelLeft and pixelTop.
Value
Integer pixel value.
Default
0

cols | NN 6 IE 4 DOM 1
| Read/Write
Specifies the width of the editable space of the textarea element. The value represents the number of monofont characters that are to be displayed within the width. When the font size can be influenced by style sheets, the actual width changes accordingly.
Example
    document.forms[0].comments.cols = 60;
Value
Integer.
Default
Varies with browser and operating system.

disabled | NN 6 IE 4 DOM 1
| Read/Write
Specifies whether the element is available for user interaction. When set to true, the element cannot receive focus or be modified by the user, and it typically appears grayed out on the page. This property is available for all HTML element objects in IE 5.5 for Windows and later. For IE 4 and IE 5, it applies only to form controls, while Netscape 6 and later recognize the property for form controls and the style element object. A disabled form control's name/value pair is not submitted with its form.
Example
    document.getElementById("myButton").disabled = true;
Value
Boolean value: true | false.
Default
false

dataFld | NN n/a IE 4 DOM n/a
| Read/Write
Used with IE data binding to associate a remote data source column name to a textarea object's value property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.
Example
    document.myForm.myTextArea.dataFld = "description";
Value
Case-sensitive identifier of the data source column.
Default
None.

dataSrc | NN n/a IE 4 DOM n/a
| Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.
Example
    document.myForm.myTextArea.dataSrc = "DBSRC3";
Value
Case-sensitive identifier of the data source.
Default
None.

defaultValue | NN 2 IE 3 DOM 1
| Read-only
Specifies the default text for the textarea element, as established by the text between the start and end tags in the page's source code.
Example
    var txtAObj = document.forms[0].myTextArea;
    if (txtAObj.value != txtAObj.defaultValue ) {
        ...
    }
Value
Any string value.
Default
None.

focus( ) | NN 2 IE 3 DOM 1
Gives focus from the current object, at which time the object's onfocus event fires. Note that the range of elements capable of focus and blur (both the event and method) is limited in all browsers except for more recent versions of IE (see the shared tabindex attribute in Chapter 8). Most reliably for backward compatibility, apply the focus( ) method to blatantly focusable elements, such as text input and textarea elements.
To give a text box focus and pre-select all the text in the box, use the sequence of focus( ) and select( ) methods on the element. If this sequence is to occur after windows change (such as after an alert dialog box closes), place the methods in a separate function, and invoke this function through the setTimeout( ) method following the alert( ) method for the dialog. This allows IE/Windows to sequence statement execution correctly.
Parameters
None.
Returned Value
None.

form | NN 2 IE 3 DOM 1a
| Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the select element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.
Example
    var theForm = evt.srcElement.form;
Value
form element object reference.
Default
None.

name | NN 2 IE 3 DOM 1
| Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a control be assigned a name attribute to allow the control's value to be submitted.
Example
    document.orderForm.myTextArea.name = "customerComment";
Value
Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.
Default
None.

readOnly | NN 6 IE 4 DOM 1
| Read/Write
Indicates whether the form element can be edited on the page by the user. A form control that has its readOnly property set to true may still be modified by scripts, even though the user may not alter the content.
Example
    document.forms[0].myTextArea.readOnly = "true";
Value
Boolean value: true | false.
Default
false

rows | NN 6 IE 4 DOM 1
| Read/Write
Specifies the height of the textarea element based on the number of lines of text that are to be displayed without scrolling. The value represents the number of monofont character lines that are to be displayed within the height before the scrollbar becomes active. When the font size can be influenced by style sheets, the actual height changes accordingly.
Example
    document.forms[0].comments.rows = 6;
Value
Integer.
Default
2 (IE/Windows); 1 (IE/Macintosh); -1 (Netscape 6, meaning that the attribute or property hasn't been set).

scrollHeight, scrollWidth | NN 7 IE 4 DOM n/a
| Read-only
Originally implemented in IE 4 for elements that either scrolled or influenced an element's scroll (body, button, caption, div, fieldset, legend, marquee, and textarea), these properties return the pixel dimensions of an element, including elements that are larger than the viewable area in the browser window. This is in contrast to the clientHeight and clientWidth properties for scrollable elements, which return dimensions of only visible portions of the element. IE for the Macintosh, however, interprets the intent of the scroll- properties differently, returning the dimensions of the visible portion.
Starting in IE 5 for Windows, all HTML elements have these properties, and the values for nonscrolling elements are the same as the offsetHeight and offsetWidth properties. Netscape 7 implements these properties for all elements, returning the height and width of the element, whether or not it's in view. The important point is that for key elements, such as the body, the properties mean different things and can disrupt cross-platform operation.
Example
    var midPoint = document.body.scrollHeight/2;
Value
Positive integer or zero.
Default
None.

scrollLeft, scrollTop | NN 7 IE 4 DOM n/a
| Read/Write
Provide the distance in pixels between the actual left or top edge of the element's physical content and the left or top edge of the visible portion of the content. Setting these properties allows you to use a script to adjust the scrolling of content within a scrollable container, such as text in a textarea element or an entire document in the browser window or frame. When the content is not scrolled, both values are zero. Setting the scrollTop property to 15 scrolls the document upward by 15 pixels in the window; the scrollLeft property is unaffected unless explicitly changed. The property values change as the user adjusts the scrollbars. This is important for some event-driven positioning tasks in IE for Windows because the coordinate system for event offset measurements are with respect to the visible area of a page in the browser window. You must add document.body scrolling factors to align event coordinates with body content positions (see the element dragging example in Chapter 6). Starting with IE 5 for Windows, the scrollLeft and scrollTop properties are available for all HTML element objects, but values for unscrollable elements are zero.
Example
    document.body.scrollTop = 40;
Value
Positive integer or zero.
Default
0

status | NN n/a IE 4 DOM n/a
| Read/Write
This is implemented in IE, but has no function for the textarea object.
Value
Boolean value: true | false; or null.
Default
null

tabIndex | NN 6 IE 4 DOM 1
| Read/Write
This is a number that indicates the sequence of this element within the tabbing order of all focusable elements in the document. Tabbing order follows a strict set of rules. Elements that have values other than zero assigned to their tabIndex properties are first in line when a user starts tabbing in a page. Focus starts with the element with the lowest tabIndex value and proceeds in order to the highest value, regardless of physical location on the page or in the document. If two elements have the same tabIndex values, the element that comes earlier in the document receives focus first. Next come all elements that either don't support the tabIndex property or have the value set to zero. These elements receive focus in the order in which they appear in the document.
The W3C DOM and Netscape 6 limit the tabIndex property to the following element objects: a, area, button, input, object, select, textarea. To this list, IE 4 adds applet, body, div, embed, isindex, marquee, span, table, and td. IE 5 adds every other renderable element. A negative value in IE (only) removes an element from tabbing order entirely.
Links and anchors cannot be tabbed to with the Mac version of IE 4, so the tabIndex property for a element objects is ignored in that version.
Example
    document.getElementById("link3").tabIndex = 6;
Value
Integer.
Default
0

type | NN 3 IE 4 DOM 1
| Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "textarea" while leaving other controls untouched).
Example
    if (document.forms[0].elements[3].type == "textarea") {
        ...
    }
Value
Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.
Default
textarea

value | NN 2 IE 3 DOM 1
| Read/Write
Specifies the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings.
Example
    var comment = document.forms[0].myTextArea.value;
Value
String.
Default
None.

wrap | NN n/a IE 4 DOM n/a
| Read/Write
Indicates whether the browser should wrap text in a textarea element and whether wrapped text should be submitted to the server with soft returns converted to hard carriage returns. A value of hard engages word-wrapping and converts soft returns to CR-LF characters in the value submitted to the server. A value of soft turns on word-wrapping, but does not include the CR-LF characters in the text submitted with the form. A value of off turns word-wrapping off.
Example
    document.forms[0].comments.wrap = "soft";
Value
One of the constant values (as a string): hard | off | soft.
Default
soft

createTextRange( ) | NN n/a IE 4(Win) DOM n/a
Creates a TextRange object from the content of the textarea object. See the TextRange object for details.
Returned Value
TextRange object.

handleEvent[ ] | NN |4| IE n/a DOM n/a
handleEvent(event) |
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.
Parameters
A Navigator 4 event object.
Returned Value
None.

select( ) | NN 2 IE 3 DOM 1
Selects all the text displayed in the form element. To position the insertion pointer in a specific location inside a textarea element in IE, see the TextRange object.
Parameters
None.
Returned Value
None.