TextArea and TextField User Experience Documentation

Author: Karen Stanley

1. Introduction

This document specifies all the behaviors of the Single-Style, Multi-Line TextBox control (sometimes referred to in this document as the Multi-Line TextBox or simply the TextBox control) necessary for the control to be complete and delightful to use. This document is not meant to define the APIs or architecture. The goal of the specification is to ensure that we can deliver and validate UI components that are consistent, usable, appealing and sufficiently customizable to succeed in today's market. 

2. Single-Style, Multi-Line TextBox Overview

A Multi-Line TextBox is a rectangular space where users can type multiple lines of text. The Multi-Line TextBox described is designed to display text in a Single-Style (font, font size, font style).

An example of a Single-Style, Multi-Line TextBox is shown below in the enabled state.

NOTE: ALL GRAPICS IN THIS DOCUMENT ARE NOT FINAL. Final graphics will be provided in the visual design specification for each platform.


Figure 1: Desktop Enabled Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)


This control is used when users will likely want to to enter more text than is typically entered into a slingle line text input control. For example, a TextBox control may be used to allow users to enter descriptions, messages, code or lists.

Word Wrap* can be enabled so that words wrap to the next line when it reaches the edge of the text area.  Word Wrap is useful in situations where the text area is intended to contains prose. In other situations, such as when the TextBox is intended to contain information for which exact line breaks are important, such as code or poetry, it is more useful to turn off word wrap.

* Word Wrap may also be referred to as "Line Break" or "Line Wrap". (Not all languages wrap on a word boundary when breaking is expected on a long line. However, this will be the default, at least for English-speaking languages, though appropriate default breaks should be made for each language.)

Possible options for input include typing, pasting, or selecting characters, depending on the platform on which users are working. Some platforms may also allow cutting and copying from the TextBox control.

One may also know this control by the name: Multi-Line Text Area or Multi-Line Text Field.

Horizontal Scrolling:
If word wrap is not enabled and the entered text is or becomes wider than the width of the TextBox control a horizontal scroll bar should automatically be displayed by default so users can scroll the width of the text. Figure 2 shows a Single-Style, Multi-Line TextBox control with both horizontal and vertical scroll bars.

Vertical Scrolling:
Whether word wrap is enabled or not, if the entered text is or becomes longer than the height (extends beyond the bottom) of the TextBox, a vertical scrollbar should automatically be displayed by default so users can scroll the length of the text. . Figure 2 shows a Single-Style, Multi-Line TextBox control with both horizontal and vertical scroll bars.



Figure 2: Desktop Enabled Single-Style, Multi-Line TextBox control with both vertical and horizontal scroll bars (NOT FINAL GRAPHICS)

3. Single-Style, Multi-Line TextBox: Desktop

3.1 Desktop - Introduction

The desktop allows for robust interactions with the Single-Style, Multi-Line TextBox control including expected desktop abilities suchs as typing, swiping text to select it with a mouse, cutting and copying to the clipboard, and pasting. 

3.2 Desktop - Visual Design

Desktop Single-Style, Multi-Line TextBox images in the UE spec are NOT FINAL GRAPHICS.

3.3 Desktop - Detailed Behaviors

Detailed behaviors associated with the Single-Style, Multi-Line TextBox in its three possible states (Enabled, Focused, and Disabled) are described below.

Enabled:

 
Figure 3: Desktop Enabled Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)


When the Single-Style, Multi-Line TextBox is enabled, it is displayed as an empty box when no text has been input, or displays any text that has already been entered. Scroll bars are displayed if needed and allowed (e.g. not turned off by an attribute setting - see 3.5 Desktop - Attributes below.)

The control is ready to receive focus.


Focused:

 
Figure 4: Desktop Focused Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)


When the Single-Style, Multi-Line TextBox receives focus, by being tabbed to or clicked in, its border is shown highlighted. When tabbing to the control or clicking in it when there is no existing text, the I-beam cursor is placed within the control, at the top left. When tabbing into a TextBox control that already contains text, the I-beam cursor is positioned within the text where it was last positioned when the control last had focus. When clicking into a TextBox control that already contains text, the I-beam cursor is inserted into the existing text where clicked. 


Behaviors when in Focused State:

The information below describes some of the standard text editing behaviors on a Windows operating system. Keyboard manipulations may differ on other Operating Systems.

Inputting Text:
Users may type or paste text into the control. Text is displayed as it is entered.

If Word Wrap is On:
If Word Wrap is turned on, when the user types beyond the width of the TextBox control, the text wraps to the next line. If the user types beyond the bottom of the TextBox control a vertical scroll bar will automatically be displayed by default on the right side of the TextBox control. Users may manipulate the scroll bar to move the text vertically to get the desired text into the viewable area of the TextBox control.

If Word Wrap is Off:
If Word Wrap is turned off, when the user types beyond the width of the TextBox, a horizontal scroll bar is automatically displayed by default and is adjusted such that what the user is typing is always visible.The user must manually input a carriage return (Enter key) to move to the next line. If the user types beyond the bottom of the TextBox control, a vertical scroll bar will automatically be displayed by default on the right side of the TextBox control. Users may manipulate the scroll bar to move the text both vertically and horizontally to get the desired text into the viewable area of the TextBox control.

Other Attributes That Could Be In Effect:
Developers should have the ability to indicate that a TextBox should never have scroll bars. This can be done with the Show Scroll Bars* attribute. In this case, regardless of whether Word Wrap is turned On or Off, scroll bars will never appear.

In addition, developers should be able to indicate that input is restricted to the size of the TextBox control. They can do this with the Fit Width* and Fit Height* attributes.

* Indicates that these are attributes of the Scroll View control.

Viewing Text:
Users can always see what is displayed in the visible area of the TextBox control. Users can use the arrow keys to scroll text up, down, left, and right when the text's width or height exceeds the size of the TextBox. Using the arrow keys also moves the position of the I-beam cursor. Users may also use shortcut keys to move within the text. See 3.4 Desktop - Keyboard Support for more information.

See the JavaFX Scroll View Control UE Specification for details about using the scroll bars to view the text.



Selecting Text:
Users can select text using the mouse or keyboard. Using the mouse, the user right-mouse clicks, holds, and drags left or right until the desired text is selected. Then releases the right-mouse button. Using the keyboard the user can position the i-beam cursor within the text using arrow keys and press and hold the shift key while then using arrow keys to select the desired text. Shortcuts also exist such as pressing and holding shift and then pressing the End or Home key to select to the end or beginning of the line respectively. See 3.4 Desktop - Keyboard Support for more information.

Once text is selected, it may be further manipulated. For example, it may be cut or copied to the clipboard, deleted, or replaced.



Deleting Text:
Once text is displayed, users may delete it or replace it. To delete text users can hit the backspace key to delete individual characters one at at time, deleting the character to the left of the i-beam cursor or they can press the Del key to delete the character to the right of the I-beam cursor. Users may also select the text to be deleted and then press the backspace key to delete it. See 3.4 Desktop - Keyboard Support for more information.



Replacing Text:
To replace text, users may select it as described above and then either type or paste. The selected text is replaced by the typed or pasted text.



Completing the Input or Editing of Text:
When users are done entering/editing text, they typically indicate this by leaving the control. They can leave the control by either tabbing out of the control or clicking outside of the control. At this point, the control is returned to the calling application which determines what to do next (e.g. change the TextBox control from the focused state to the enabled state, place focus on another control, and possibly perform an action).



Disabled:


Figure 5: Desktop Disabled Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)

In the disabled state, the Single-Style, Multi-Line TextBox is "grayed out" (shown in a disabled appearance - visual details are governed by the visual design specification being used) to indicate that is cannot receive input. Any input already entered is displayed using the disabled appearance. The control does not accept focus when tabbed to (it is basically skipped) or clicked on. Scrollbars are displayed in the disabled state if they had been displayed before the control became disabled. This is so that when the control becomes enabled, if scrollbars are necessary, the control size and display of the text will not be affected just by the state change.

States:
The following table identifies the applicable states pertaining to the Single-Style, Multi-Line TextBox control.

3.4 Desktop - Keyboard Support

3.4.1 Windows Keyboard Support

The table below shows keyboard operations applicable to the TextBox control. It also includes some frequent mouse actions (at the top), but does not cover using the scroll bars. See the JavaFX Scroll View Control UE Specification for details about using the scroll bars to view the text.

3.4.2 MAC Keyboard Support

Below is a table of MAC keyboard symbols and their meanings. This table was excerpted (and then slightly modified) from the following site:
MAC Central, author Dan Rodney. See this site for more MAC keyboard information.

Symbol	Key on Keyboard	Symbol	Key on Keyboard
	Command/Apple key (like Control on a PC)		Delete (Backspace)
	Option (like Alt on a PC)		Escape
	Shift		Page Up
	Control (Control-click = Right-click)		Page Down
	Tab		Home
	Return		End
	Enter (on Number Pad)		Arrow Keys
			Delete

The table below shows keyboard operations applicable to the TextBox control. It also includes some frequent mouse actions (at the top), but does not cover using the scroll bars. See the JavaFX Scroll View Control UE Specification for details about using the scroll bars to view the text.

TextField

Key	Initial State	Result
Mouse button 1(Left Mouse button)	Enabled state.	Control is put in focused state.
Mouse button 2 (right mouse button	Enabled or focused state.	Puts control in focused state, if not already, and if a context menu is associated with this control, it is displayed.
Mouse button 1 + drag	Enabled or focused state.	Puts control in focused state, if not already, and selects text from beginning of drag to end.
Mouse button 1, double click	Enabled or focused state.	Puts control in focused state, if not already, and selects current word.
Mouse button 2, tripple click	Enabled or focused state.	Puts control in focused state, if not already, and selects current line. If text is wrapped, it selects the whole paragraph.
Esc	Enabled or focused state.	No change.
Delete	Focused state.	Deletes the character to the left of the I-beam cursor.
Delete	Focused state.	Deletes the character to the right of the I-beam cursor.
Command+C	Focused state.	Copies any selected text to the clipboard.
Command+V	Focused state.	Pastes the current clipboard contents into the TextBox control, if the content's format is applicable (e.g. text).
Shift+Tab	Focused state.	Moves focus to the previous focusable control.
Tab	Focused state	Moves focus to the next focusable control.
Command+Tab or Command+Shift+Tab	Focused state.	Displays toolbar of opened application icons.
Home	Focused state.	Moves I-beam cursor to the beginning of the line the I-beam cursor is currently in.
End	Focused state.	Moves I-beam cursor to the beginning of the line the I-beam cursor is currently in.
Shift+Home	Focused state.	Extend selection to beginning of text
Shift+End	Focused state.	Extend selection to end of text
Command+Home	Focused state.	Moves the I-beam cursor to the very beginning of the entered text.
Command+End	Focused state.	Moves the I-beam cursor to the very end of the entered text.
Command+Shift+Home	Focused state.	Select to beginning of text
Command+Shift+End	Focused state.	Select to end of text
PgUp	Focused state.	Moves up one information pane. An information pane is defined as 1 fewer lines than the number of lines in in the TextBox control's height. This allows for one line of overlap (for example, when paging up, the bottom line becomes the top-most viewable line before PgUp was pressed). I-beam cursor should remain in the same relative position though the text changes.
PgDn	Focused state.	Moves down one information pane. An information pane is defined as 1 fewer lines than the number of lines in in the TextBox control's height. This allows for one line of overlap (for example, when paging down, the top line becomes the bottom-most viewable line before PgDn was pressed). I-beam cursor should remain in the same relative position though the text changes.
Command+PgUp	Focused state.	In a tabbed dialog or a browser with multiple open tabs, this typically moves to the previous tab. In a non-tabbed situation, this typically does nothing.
Command+PgDn	Focused state.	In a tabbed dialog or a browser with multiple open tabs, this typically moves to the next tab. In a non-tabbed situation, this typically does nothing.
Shift+PgUp	Focused state.	Extends selection up one information pane.
Shift+PgDn	Focused state.	Extends selection down one information pane.
Command+Shift+PgUp	Focused state.	Extends selection to the left one information pane
Command+Shift+PgDn	Focused state.	Extends selection to the right one information pane
Command+A	Focused state.	Selects all.
Enter/return	Focused state.	Inserts a line break in the text being entered.
Spacebar	Focused state.	Enters a space character as part of the entered text.
Left, Right, Up, Down arrow keys	Single-Style, Multi-Line TextBox is in Focused state.	If nothing has been entered in field, all arrow keys result in no change. Up and Down arrow keys move the I-beam cursor up or down one line if control height is multiple lines tall. If text has been entered Left and Right arrow keys move the I-beam cursor left and right among the entered text characters. The Left arrow key results in no change when the cursor is positioned to the left of the very first entered character. The Right arrow key results in no change when the cursor is positioned to the right of the very last entered character.
Option+Left Arrow	Focused state.	Move the caret to the beginning of the previous word. If the caret is in the middle of a word, move the caret to the beginning of the word.
Option+Right Arrow	Focused state.	This key combination moves the caret to the end of the next word. If the caret is in the middle of a word, move the caret to the end of the word.
Command+Left Arrow	Focused state.	Moves the I-beam cursor to the beginning of current line.
Command+Right Arrow	Focused state.	Moves the I-beam cursor to the end of current line.
Shift+Up Arrow	Focused state.	Extends selection up one line.
Shift+Down Arrow	Focused state.	Extends selection up one line.
Shift+Left Arrow	Focused state.	Extends selection left one character.
Shift+Right Arrow	Focused state.	Extends selection right one character.
Option+Shift+Left Arrow	Focused state.	Extend selection to the beginning of the previous word. If the caret is in the middle of a word, extend selection to the beginning of the word.
Option+Shift+Right Arrow	Focused state.	This key combination extends selection to the end of the next word. If the caret is in the middle of a word, extend selection to the end of the word.
any alphanumeric keys and special character keys	Focused state.	Enters these characters into the TextBox control.
Shift+any alphanumeric keys and special character keys	Focused state.	The shift character on the alphanumeric/special character key is input into the TextBox control.
CAPS LOCK+any alphanumeric keys and special character keys	Focused state.	If CAPS LOCK key is on, the shift characters on the keyboard are input into the TextBox control (e.g. any alphabetic character keys pressed are entered as capital letters) until this key is selected again, turning it off.
Command+Up Arrow		Moves the I-beam cursor to the beginning of the current line/paragraph.
Command+Down Arrow		Moves the I-beam cursor to the end of the current line/paragraph.
Command+Shift+Up Arrow		Extends selection to the beginning of the current line/paragraph.
Command+Shift+Down Arrow		Extends selection to the end of the current line/paragraph.
Command+Shift+Left Arrow		Extends selection to beginning of text
Command+Shift+Right Arrow		Extends selection to end of text
Command+Backspace		Deletes the line to the left of the I-beam cursor.
Command+Delete		Deletes the line to the right of the I-beam cursor.

TextArea

Key	Initial State	Result
Mouse button 1(Left Mouse button)	Enabled state.	Control is put in focused state.
Mouse button 2 (right mouse button	Enabled or focused state.	Puts control in focused state, if not already, and if a context menu is associated with this control, it is displayed.
Mouse button 1 + drag	Enabled or focused state.	Puts control in focused state, if not already, and selects text from beginning of drag to end.
Mouse button 1, double click	Enabled or focused state.	Puts control in focused state, if not already, and selects current word.
Mouse button 2, tripple click	Enabled or focused state.	Puts control in focused state, if not already, and selects current line. If text is wrapped, it selects the whole paragraph.
Esc	Enabled or focused state.	No change.
Delete	Focused state.	Deletes the character to the left of the I-beam cursor.
Delete	Focused state.	Deletes the character to the right of the I-beam cursor.
Command+C	Focused state.	Copies any selected text to the clipboard.
Command+V	Focused state.	Pastes the current clipboard contents into the TextBox control, if the content's format is applicable (e.g. text).
Tab	Focused state.	Inserts a Tab into the text of the TextBox control. In case of read-only text box (which is different from disabled), pressing Tab should tab out of a text box.
Shift-Tab	Focused state.	Moves focus to the previous focusable control.
Control+F7	Focused state.	Moves focus to the next focusable control.
Command+Tab or Command+Shift+Tab	Focused state.	Displays toolbar of opened application icons.
Home	Focused state.	Moves I-beam cursor to the beginning of the line the I-beam cursor is currently in.
End	Focused state.	Moves I-beam cursor to the beginning of the line the I-beam cursor is currently in.
Shift+Home	Focused state.	Extend selection to beginning of text
Shift+End	Focused state.	Extend selection to end of text
Command+Home	Focused state.	Move cursor to beginning of text
Command+End	Focused state.	Move cursor to end of text
Command+Shift+Home	Focused state.	Select to beginning of text
Command+Shift+End	Focused state.	Select to end of text
PgUp	Focused state.	Moves up one information pane. An information pane is defined as 1 fewer lines than the number of lines in in the TextBox control's height. This allows for one line of overlap (for example, when paging up, the bottom line becomes the top-most viewable line before PgUp was pressed). I-beam cursor should remain in the same relative position though the text changes.
PgDn	Focused state.	Moves down one information pane. An information pane is defined as 1 fewer lines than the number of lines in in the TextBox control's height. This allows for one line of overlap (for example, when paging down, the top line becomes the bottom-most viewable line before PgDn was pressed). I-beam cursor should remain in the same relative position though the text changes.
Command+PgUp	Focused state.	In a tabbed dialog or a browser with multiple open tabs, this typically moves to the previous tab. In a non-tabbed situation, this typically does nothing.
Command+PgDn	Focused state.	In a tabbed dialog or a browser with multiple open tabs, this typically moves to the next tab. In a non-tabbed situation, this typically does nothing.
Shift+PgUp	Focused state.	Extends selection up one information pane.
Shift+PgDn	Focused state.	Extends selection down one information pane.
Command+Shift+PgUp	Focused state.	Extends selection to the left one information pane
Command+Shift+PgDn	Focused state.	Extends selection to the right one information pane
Command+A	Focused state.	Selects all.
Enter/return	Focused state.	Inserts a line break in the text being entered.
Spacebar	Focused state.	Enters a space character as part of the entered text.
Left, Right, Up, Down arrow keys	Single-Style, Multi-Line TextBox is in Focused state.	If nothing has been entered in field, all arrow keys result in no change. Up and Down arrow keys move the I-beam cursor up or down one line if control height is multiple lines tall. If text has been entered Left and Right arrow keys move the I-beam cursor left and right among the entered text characters. The Left arrow key results in no change when the cursor is positioned to the left of the very first entered character. The Right arrow key results in no change when the cursor is positioned to the right of the very last entered character.
Option+Left Arrow	Focused state.	Moves the I-beam cursor to the beginning of current word.
Option+Right Arrow	Focused state.	Moves the I-beam cursor to the end of current word.
Command+Left Arrow	Focused state.	Moves the I-beam cursor to the beginning of current line.
Command+Right Arrow	Focused state.	Moves the I-beam cursor to the end of current line.
Shift+Up Arrow	Focused state.	Extends selection up one line.
Shift+Down Arrow	Focused state.	Extends selection up one line.
Shift+Left Arrow	Focused state.	Extends selection left one character.
Shift+Right Arrow	Focused state.	Extends selection right one character.
Option+Shift+Left Arrow	Focused state.	Extend selection to the beginning of the previous word. If the caret is in the middle of a word, extend selection to the beginning of the word.
Option+Shift+Right Arrow	Focused state.	This key combination extends selection to the end of the next word. If the caret is in the middle of a word, extend selection to the end of the word.
any alphanumeric keys and special character keys	Focused state.	Enters these characters into the TextBox control.
Shift+any alphanumeric keys and special character keys	Focused state.	The shift character on the alphanumeric/special character key is input into the TextBox control.
CAPS LOCK+any alphanumeric keys and special character keys	Focused state.	If CAPS LOCK key is on, the shift characters on the keyboard are input into the TextBox control (e.g. any alphabetic character keys pressed are entered as capital letters) until this key is selected again, turning it off.
Command+Up Arrow	Focused state.	Moves the I-beam cursor to the beginning of the current line/paragraph.
Command+Down Arrow	Focused state.	Moves the I-beam cursor to the end of the current line/paragraph.
Command+Shift+Up Arrow	Focused state.	Extend selection to beginning of text
Command+Shift+Down Arrow	Focused state.	Extend selection to end of text
Command+Shift+Left Arrow	Focused state.	Extend selection to beginning of line
Command+Shift+Right Arrow	Focused state.	Extend selection to end of line
Option+Up Arrow	Focused state.	Move the caret to the beginning of the previous paragraph. If the caret is in the middle of a paragraph, move the caret to the beginning of the paragraph.
Option+Down Arrow	Focused state.	Move the caret to the beginning of the next paragraph.
Option+Shift+Up Arrow	Focused state.	Extend selection to the beginning of the current paragraph.
Option+Shift+Down Arrow	Focused state.	Extend selection to the end of the current paragraph.
Command+Backspace		Deletes the line to the left of the I-beam cursor.
Command+Delete		Deletes the line to the right of the I-beam cursor.

3.4.3 Linux Keyboard Support

Linux keyboard behaviors are the same as for Windows keyboard behaviors.

3.5 Desktop - Attributes

Below is a table identifying the attributes required by the Single-Style, Multi-Line TextBox control.

Note that the Single-Style, Multi-Line TextBox will inherit attributes of the Text Input (TextBox) control including:

• TextBox width
• TextBox height
• vertical position with respect to parent
• horizontal position with respect to parent
• font details (e.g. font, size, style, color - as available for the text field control)
• shadow text (which displays initial "prompt" (or hint) information in the field)

Particular to Single-Style, Multi-Line TextBox will be the following:   

4 Single-Style, Multi-Line TextBox: Touch

4.1 Touch - Introduction

The Touch platform introduces some additional considerations not seen on the desktop:

• Interaction is conducted on a touch device which will be much smaller than any desktop.
• Touch allows for direct manipulation (finger touch/gestures) of content and objects, which may be considered more natural than using an input device such as a keyboard or mouse or hardware keypad.
• Some touch devices may allow the use of a stylus as well as finger touch, while others may not. A stylus introduces different gesture considerations.
• Text input involves an on-screen keyboard that typically toggles between displaying alphanumeric characters and a number pad.
  
  

4.2 Touch - Visual Design

The Touch Single-Style, Multi-Line TextBox images in the UE spec are NOT FINAL GRAPHICS.

4.3 Touch - Detailed Behaviors

Below is a description of the behaviors and interactions pertaining to the Single-Style, Multi-Line TextBox on the Touch platform.

Note that this specification assumes the invocation and use of an on-screen keyboard for text input.

Applicable states are similar to the Desktop: Enabled, Focused and Disabled.

Detailed behaviors associated with the Single-Style, Multi-Line TextBox in its three possible states are described below.


Enabled:

 
 Figure 6: Touch Enabled Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)

When the Single-Style, Multi-Line TextBox is enabled, it is displayed as an empty box when no text has been input, or displays any text that has already been entered. Scroll bars are displayed if needed and allowed (e.g. not turned off by an attribute setting - see 3.5 Desktop - Attributes below.)

The control is ready to receive focus.

Focused:

Figure 7: Touch Focused Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)

When the TextBox receives focus, by being tapped (with finger or stylus), it is shown highlighted. The I-beam cursor blinks at the next input location. When the field receives focus, a keyboard also typically appears. 


Behaviors when in Focused State:


Inputting Text:

As users tap the keys on the keyboard there is visual feedback on the characters (varies by platform) and there is also input into the TextBox control. Tapped (selected) characters are displayed in the TextBox control. 

Here is an example using a keyboard with multiple characters available per touch button:


Figure 8: Mobile Touch Focused Single-Style, Multi-Line TextBox control with on-screen keyboard (NOT FINAL GRAPHICS)


Other examples layouts of mobile touch keyboards are shown below:

Figure 9: Example showing three possible on-screen keyboard layouts

Use of Scrollbars on Touch Devices:
The scroll bar will be operable (similar to using pointing devices on the desktop) if stylus interaction is supported. If only finger touch interaction is supported, scrollbars are only displayed to provide content size and position information. See the JavaFX Scroll View Control UE Specification for information about scrolling content on the Touch platform. 


If Word Wrap is On:
If Word Wrap is turned on, when the user taps characters beyond the width of the TextBox control, the text wraps to the next line, breaking at whole words by default. If the user enters text beyond the bottom of the TextBox control a vertical scroll bar will automatically be displayed on the right side of the TextBox control. 

If Word Wrap is Off:
If Word Wrap is turned off, when the user taps characters beyond the width of the TextBox, the a horizontal scroll bar is automatically displayed and is adjusted such that the characters that are tapped are always visible. The user must manually select a carriage return (Enter key) to move to the next line. If the user taps characters beyond the bottom of the TextBox control, a vertical scroll bar will automatically be displayed on the right side of the TextBox control.

Not for 1.3 on Touch:

• Cut, Copy, and Paste are not for 1.3 on Touch: Because the clipboard is not supported on touch devices in the 1.3 release, Cut and Copy to the clipboard and the Paste operation cannot be supported. 
• Not for Touch: CAPS LOCK is not supported because there is currently no way for the control to know that CAPS LOCK has been engaged on the on-screen keyboard.

Other Attributes That Could Be In Effect:
Developers should have the ability to indicate that a TextBox should never have scroll bars. This can be done with the Show Scroll Bars* attribute. In this case, regardless of whether Word Wrap is turned On or Off, scroll bars will never appear.

In addition, developers should be able to indicate that input is restricted to the size of the TextBox control. They can do this with the Fit Width* and Fit Height* attributes.

* Indicates that these are attributes of the Scroll View control.

Viewing Text:
Users can always see what is displayed in the visible area of the TextBox control. Users can use finger or stylus gestures, as supported, to move the text around in the TextBox control to view the desired text. See the JavaFX Scroll View Control UE Specification for information about scrolling content on the Touch platform. 



Deleting Text:
To correct an incorrect selection, the user chooses the keyboard key that allows deletion of the input to the left of the I-beam cursor. In the above on-screen keyboard example, this would be the '<--' (backspace) key.



Replacing Text:
To replace text, users must delete the undesired text (as described above) and then tap the desired characters on-the onscreen keyboard as described in Inputting Text above.



Completing the Input or Editing of Text:
When the user has finished entering text, the Enter (or whatever button the keyboard provides to indicate "finished") button can be tapped. This dismisses the keyboard. (Another means to dismiss the keyboard would be to click an icon on the bottom bar or on another component in a (native) application, which doesn't allow text input.) At this point, all application control is returned to the calling application which would then be responsible for determining what action to take next. The TextBox would remain in focused (non-interactive) state until the calling application moves the focus. The entered text would remain displayed in the control. 
 

Disabled:

 
 Figure 10: Touch Disabled Single-Style, Multi-Line TextBox control (NOT FINAL GRAPHICS)

In the disabled state, the Single-Style, Multi-Line TextBox is "grayed out" (shown in a disabled appearance - visual details are governed by the visual design specification being used) to indicate that is cannot receive input. Any input already entered is displayed using the disabled appearance. The control does not accept focus when tapped and cannot otherwise be navigated to. Scrollbars are displayed in the disabled state if they had been displayed before the control became disabled. This is so that when the control becomes enabled, if scrollbars are necessary, the control size and display of the text will not be affected just by the state change.


States:
The following table identifies the applicable states pertaining to the Single-Style, Multi-Line TextBox control.

4.4 Touch - On-Screen Keyboard Support

This section describes keys & key behavior when using an on-screen keyboard. The keys identified here are considered to be common across keyboards, though keyboard keys and layout tend to vary.

On-Screen Keyboard Notes: 
  - Tapping a key once selects the left-most primary (large) item displayed on a key with multiple items.
  - Tapping two times in quick succession selects the item to the right of the left-most item; three times moves to the right of that.
  - Tapping Shift and then another key selects the secondary (smaller - and usually a top) item on the key.
  - Tapping the '123' item toggles the on-screen keyboard to a numeric keyboard.

4.5 Touch - Attributes

Below is a table identifying the attributes required by the Single-Style, Multi-Line TextBox control on the Touch platform.

Note that the Single-Style, Multi-Line TextBox will inherit attributes of the TextBox control including:

• TextBox width
• TextBox height
• vertical position with respect to parent
• horizontal position with respect to parent
• font details (e.g. font, size, style, color - as available for the text field control)
• shadow text (which displays initial "prompt" (or hint) information in the field)

Particular to Single-Style, Multi-Line TextBox will be the following: