- Loading...
Page History
...
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.
...
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)
...
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:
...
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.
...
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.
...
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
...
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.
...
Overview
Content Tools