d8e83b57ea
* Add UI Guidelines to SDK docs * Add UI Guidelines to SDK docs * Fixing build errors * optimize PNGs * add UI guidelines landing page placeholder * IJ SDK Docs <-> UI guidelines crosslinks updated * split_button.md: remove reference to removed setting * use <ui-path> * use MD instead of <note> * use %gh-ic% links * drop_down.md: fix <control> * code samples: fix most obvious issues * remove obsolete `_defaults.md` * ijs.tree: UI cleanup * Delete "under construction" pages * Fix headers * Add link-summary * Remove invalid links * Delete unused files * Remove ''@2x' from image file names * Use Markdown syntax for some images and tables * Rename non-unique files to unique * Remove alpha in images where content is unreadable * align quotation marks * Controls: cleanup/fixes, add code links, edit * tooltip.md: fix HTML * misc fixes * typography.md: fix table contents * typography.md: fix table header * UI guidelines landing page + TOC fixes * remove unused icons_list.md * Normalize image paths * validation_errors.md: Fix broken tab * "correct"/"incorrect" labels styling * Resize images to 50% * button.topic: fixes * grammar, spelling, minor edits * remove ' ' * fix 99px * cleanup * UI_kit.md: minor * Fix "MRK058: Large image in paragraph rendered as a block element by default." * button.topic: Add img[alt] * mnemonics.md: Update "Contact Us" link to the IJSDK YouTrack * split_button.md: Use ui-path * UI landing: add feedback snippet * Improve code snippets formatting and naming * Fix code samples * Fix code samples * Add Kotlin variants for code samples * Add icons_list.md * crosslinks * Change external link to https://intellij-icons.jetbrains.design/ * icons list -> https://intellij-icons.jetbrains.design * Hide info about reducing split button to simple action button (now it is available through the registry only) * reformat * icons_style.md: Images in new line --------- Co-authored-by: marianna.kononenko <marianna.kononenko@jetbrains.com> Co-authored-by: Yann Cébron <yann.cebron@jetbrains.com>
4.2 KiB
Text Area
UI guidelines on using text areas.
Implementation: JBTextArea
A text area allows users to enter or edit multi-line text.
{width=300}
When to use
Use a text area if input is unconstrained and long, or if the newline character is a valid value. Example: commit message or code snippets.
Do not use a text area if:
- Input consists of several words. Use an input field instead.
- There is not enough space for a text area, or if input is normally short but can occasionally be long or multi-line. Use an expandable input field instead.
- Values are added one by one. Use a table instead.
- Text is read-only. Use a description text instead.
How to use
Label
Follow the rules for the input field.
A label is required for all empty text areas. If a text area is prefilled, and it’s clear from the context what data it contains, a label can be omitted. For example, the following text area is used to preview file and code templates:
{width=584}
If a new file template is added and the text area is empty, the label is required.
Do not put units on the right of the text area.
Do not use a group header instead of the text area label. The horizontal line is redundant here. Use context help to explain the field behavior.
Incorrect
{width=598}
Correct
{width=598}
Placeholder, prefilled values and field focus
Follow the rules for the input field: placeholder, prefilled value, field focus.
History
If the previous user input should be saved, use ⌥↑ and ⌥↓ on macOS and Alt+Up/Down on Windows and Linux to navigate through the history. If history is available, add a note at the bottom of the input field:
{width=400}
Save the current value, so that the user can return to it while navigating through the history.
Validation
If the user types an invalid value, highlight the text area with red and show an error message in a tooltip. For more details, see Validation errors.
{width=306}
Size and placement
Recommended sizes:
{width=492}
This is the default size, it can be changed if the dialog is resized.
Height. The minimum text area height is 3 lines ~55px, so the user understands that it’s multi-line. The maximum height is not limited and should be appropriate for the most common values.
Width. The minimum text area width is 270px. It’s inconvenient to use a narrower field due to frequent line breaks. The maximum width is 80 symbols ~600px, otherwise, it’s hard to read the text.
Size the text area to display an integral number of lines of text:
| Incorrect | Correct |
|---|---|
 |
 |
Do not resize a text area on input. It will change the position of other controls and they can become hardly discoverable.
If the text is long and does not fit the text area, add scrollbar.
For placement, follow the rules for the input field.
Style
Use the same colors as for the input field.
Do not highlight a text area on selection, only if a validation error occurs.
History
Background: dialog default theme color
Font: Windows, IntelliJ — default, macOS 2px smaller than default