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.
State Name | Description |
Enabled | Control is displayed. Any existing input is displayed. Scroll bars are displayed if needed and allowed (e.g. not turned off by an attribute setting - see 3.5 Desktop - Attributes below..) |
Focused | Control is highlighted, I-beam cursor is positioned appropriately, and the control is ready for input. |
Disabled | Control cannot accept input or be navigated to. |
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.
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 | Focused state. | No change. |
Backspace | Focused state. | Deletes the character to the left of the I-beam cursor. |
Del | Focused state. | Deletes the character to the right of the I-beam cursor. |
Ctrl+C | Focused state. | Copies any selected text to the clipboard. |
Ctrl+V | Focused state. | Pastes the current clipboard contentsinto 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. |
Ctrl+Tab | Focused state. | Moves focus to the next focusable control. |
Ctrl+Shift+Tab | Focused state. | Moves focus to the previous focusable control. |
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. | Extends selection to the beginning of the line the I-beam cursor is currently in. |
Shift+End | Focused state. | Extends selection to the end of the line the I-beam cursor is currently in. |
Ctrl+Home | Focused state. | Moves the I-beam cursor to the very beginning of the entered text. |
Ctrl+End | Focused state. | Moves the I-beam cursor to the very end of the entered text. |
Ctrl+Shift+Home | Focused state. | Extends selection to the very beginning of the text. |
Ctrl+Shift+End | Focused state. | Extends selection to the very end of the 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. |
Ctrl+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. |
Ctrl+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 down one information pane. |
Shift+PgDn | Focused state. | Extends selection down one information pane. |
Ctrl+Shift+PgUp | Focused state. | Extends selection to the left one information pane |
Ctrl+Shift+PgDn | Focused state. | Extends selection to the right one information pane |
Ctrl+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. |
|
Ctrl+Left Arrow | Focused state. | Moves the I-beam cursor to the beginning of previous word. If the I-beam cursor is in the middle of a word, the I-beam cursor moves to the beginning of the word. |
Ctrl+Right Arrow | Focused state. | Moves the I-beam cursor to the beginning of next word. |
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. |
Ctrl+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. |
Ctrl+Shift Right Arrow | Focused state. | Extend selection the the beginning of the next word. |
any alphanumeric keys and special character keys | Single-Style, Multi-Line TextBox is in 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. |
Ctrl+Up Arrow | 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. | |
Ctrl+Down Arrow | Move the caret to the beginning of the next paragraph. | |
Ctrl+Shift+Up Arrow | Extends selection to the beginning of the current line/paragraph. | |
Ctrl+Shift+Down Arrow | Extends selection to the end of the current line/paragraph. | |
Ctrl+Backspace | Deletes the word to the left of the I-beam cursor. | |
Ctrl+Delete | Deletes the word to the right of the I-beam cursor. |
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. |
|
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. |
|
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:
Attribute Name | Description | Default | Valid Values |
Not for 1.3* Word Wrap * For 1.3, Word Wrap behavior is always ON. | This attribute allows developers to indicate whether text should wrap when the user types beyond the width of the TextBox control. Word Wrap wraps on word boundaries. (The default line breaking (in Swing stack) behavior is based on the Unicode's line breaking algorithm (http://www.unicode.org/reports/tr14/) so hyphenation etc. should already be taken care of for each language.) | Boolean True | Boolean True or False |
Lines | This attribute allows the developer to set the number of lines of the TextBox. This value multiplied by the Text Input control's Height value, determines the height of the TextBox control. | Default number of lines is five. | Positive Integer |
Show Scroll Bars* | 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. | As Needed | Positive Integer |
Fit Width* | When the developer sets this attribute to True, the width of the entered text is limited to the available width of the TextBox control. A vertical scroll bar appears as needed. (A horizontal scrollbar will never be displayed.) | Boolean False | Boolean True or False |
Fit Height* | When the developer sets this attribute to True, the height of the entered text is limited to the available height of the TextBox control. A horizontal scroll bar appears as needed. (A vertical scrollbar will never be displayed.) | Boolean False | Boolean True or False |
* Indicates that these are attributes of the Scroll View control. |
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.
State Name | Description | |
Enabled | Control is displayed. Any existing input is displayed. Scroll bars are displayed if needed and allowed (e.g. not turned off by an attribute setting - see 4.5 Touch - Attributes below..) | |
Focused | Control is highlighted. I-beam cursor is positioned appropriately, and the control is ready for input. | |
Disabled | Control cannot accept input or be navigated to. |
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.
Key | Initial State | Result |
Enter/Return | Focused state | The on-screen keyboard is dismissed. (Another means to dismiss the keyboard would be to click an icon on the bottom bar or on another component in an (native) application, which doesn't allow text input.) Control is returned to the calling application. State becomes focused (non-interactive) until the calling application changes focus. Entered text remains displayed in the control |
<- (backspace) | Focused State | Deletes the character to the left of the I-beam cursor in the Single-Style, Multi-Line TextBox control. |
Spacebar | Focused state | Enters a space character into the TextBox control. |
CAPS LOCK (if available on the on-screen keyboard)) | Focused state | 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. If ever supported, this key turns on CAPS LOCK. The on-Screen keyboard should display some visual indicator that CAPS LOCK is "on". The Single-Style, Multi-Line TextBox control itself will not provide any indication of CAPS LOCK being on. CAPS LOCK makes it such that the shift characters on the keyboard are input into the Single-Style, Multi-Line TextBox control (e.g. any alphabetic character selected is entered as a capital letter) until this key is tapped again, turning it off (and removing the visual cue from the keyboard). |
any alphanumeric keys and special characters | Focused state | Enters these characters into the TextBox control. |
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:
Attribute Name | Description | Default | Valid Values |
Not for 1.3* Word Wrap * For 1.3, Word Wrap behavior is always ON. | This attribute allows developers to indicate whether text should wrap when the user types beyond the width of the TextBox control. Word Wrap wraps on word boundaries by default. (The default line breaking (in Swing stack) behavior is based on the Unicode's line breaking algorithm (http://www.unicode.org/reports/tr14/) so hyphenation etc. should already be taken care of for each language.) | Boolean True | Boolean True or False |
Lines | This attribute allows the developer to set the number of lines of the TextBox. This value multiplied by the Text Input control's Height value, determines the height of the TextBox control. | Default number of lines is three. | Positive Integer |
Show Scroll Bars* | 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. | As Needed | Positive Integer |
Fit Width* | When the developer sets this attribute to True, the width of the entered text is limited to the available width of the TextBox control. A vertical scroll bar appears as needed. (A horizontal scrollbar will never be displayed.) | Boolean False | Boolean True or False |
Fit Height* | When the developer sets this attribute to True, the height of the entered text is limited to the available height of the TextBox control. A horizontal scroll bar appears as needed. (A vertical scrollbar will never be displayed.) | Boolean False | Boolean True or False |
* Indicates that these are attributes of the Scroll View control. |