UX-2323 Update existing UI Guidelines: Inline text
marianna.kononenko
BIN
images/ui/inline_help_text/inline_text_brackets_correct.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/inline_help_text/inline_text_brackets_correct_dark.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/inline_help_text/inline_text_brackets_incorrect.png
Normal file
|
After Width: | Height: | Size: 8.6 KiB |
|
After Width: | Height: | Size: 8.1 KiB |
BIN
images/ui/inline_help_text/inline_text_external_link.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/inline_help_text/inline_text_external_link_dark.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/inline_help_text/inline_text_formatting_correct.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/inline_help_text/inline_text_formatting_incorrect.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/inline_help_text/inline_text_group.png
Normal file
|
After Width: | Height: | Size: 53 KiB |
BIN
images/ui/inline_help_text/inline_text_group_dark.png
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
images/ui/inline_help_text/inline_text_height.png
Normal file
|
After Width: | Height: | Size: 28 KiB |
BIN
images/ui/inline_help_text/inline_text_height_dark.png
Normal file
|
After Width: | Height: | Size: 27 KiB |
BIN
images/ui/inline_help_text/inline_text_internal_link.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/inline_help_text/inline_text_internal_link_dark.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
BIN
images/ui/inline_help_text/inline_text_legal.png
Normal file
|
After Width: | Height: | Size: 57 KiB |
BIN
images/ui/inline_help_text/inline_text_legal_dark.png
Normal file
|
After Width: | Height: | Size: 55 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom_dark.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 51 KiB |
|
After Width: | Height: | Size: 49 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_bottom_tree.png
Normal file
|
After Width: | Height: | Size: 51 KiB |
|
After Width: | Height: | Size: 49 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_button.png
Normal file
|
After Width: | Height: | Size: 9.9 KiB |
|
After Width: | Height: | Size: 10 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_checkbox.png
Normal file
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/inline_help_text/inline_text_on_the_right_tree.png
Normal file
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 30 KiB |
BIN
images/ui/inline_help_text/inline_text_repetition_correct.png
Normal file
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/inline_help_text/inline_text_repetition_incorrect.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/inline_help_text/inline_text_under_table.png
Normal file
|
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/inline_help_text/inline_text_under_table_dark.png
Normal file
|
After Width: | Height: | Size: 25 KiB |
BIN
images/ui/inline_help_text/tooltip_list.png
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
images/ui/inline_help_text/tooltip_list_dark.png
Normal file
|
After Width: | Height: | Size: 56 KiB |
@ -4,27 +4,26 @@
|
||||
|
||||
<link-summary>UI guidelines on using inline help texts.</link-summary>
|
||||
|
||||
Inline help text provides useful information about a setting.
|
||||
Inline help texts provide useful information about settings:
|
||||
|
||||
{width=304}
|
||||
<img src="context_help_inline_text.png" width="706" alt="Inline help text"/>
|
||||
|
||||
## When to use
|
||||
<chapter title="When to use" id="when-to-use">
|
||||
<p>Follow the rules for <a href="context_help.md">context help</a>.</p>
|
||||
</chapter>
|
||||
|
||||
Follow the rules for [context help](context_help.md).
|
||||
<chapter title="How to use" id="how_to_use">
|
||||
<chapter title="Text length" id="text_length">
|
||||
Show no more than five lines of help text to not clutter the screen.
|
||||
Text width is limited to 70 characters.
|
||||
|
||||
## How to use
|
||||
{width=706}
|
||||
|
||||
### Text length and formatting
|
||||
Show more than five lines only when a text cannot be shortened for legal purposes.
|
||||
|
||||
Show no more than 5 lines of help text not to clutter the screen. Note that the text width is limited to 70 characters.
|
||||
{width=706}
|
||||
|
||||
{width=380}
|
||||
|
||||
Show more than 5 lines only when a text cannot be shortened for legal purposes.
|
||||
|
||||
{width=396}
|
||||
|
||||
<p>Implementation</p>
|
||||
<chapter title="Implementation" id="implementation_legal" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
@ -46,52 +45,95 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
</chapter>
|
||||
<chapter title="Links" id="links">
|
||||
Provide a link to the corresponding help article or to a place in the IDE where the related settings can be found.
|
||||
Place the link at the end of the text where possible so that it does not disrupt reading.
|
||||
|
||||
{width=366 style=block}
|
||||
*External link*
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<control>Internal link</control>
|
||||
<img src="inline_text_internal_link.png" alt="Internal link"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<control>External link</control>
|
||||
<img src="inline_text_external_link.png" alt="External link"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
|
||||
{width=345 style=block}
|
||||
*Local link*
|
||||
<chapter title="Text style formatting" id="text_style_formatting">
|
||||
|
||||
Text style formatting:
|
||||
- Avoid text highlighting. Usually, the help text is short, and no highlighting in bold or italics is needed:
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_formatting_correct.png" alt="Avoid highlighting: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_formatting_incorrect.png" alt="Avoid highlighting: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
* Avoid text highlighting. Usually, the help text is short and no bold or italics are needed.
|
||||
[//]: # (* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `<html></html>` tags is not needed.)
|
||||
|
||||
{width=364}
|
||||
[//]: # ( {width=213})
|
||||
|
||||
* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `<html></html>` tags is not needed.
|
||||
- Avoid using brackets in control labels and place this information in the inline text instead:
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_brackets_correct.png" alt="Avoid brackets: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_brackets_incorrect.png" alt="Avoid brackets: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
|
||||
{width=213}
|
||||
<chapter title="Writing guidelines" id="writing_guidelines">
|
||||
|
||||
Avoid using brackets.
|
||||
- Make help text [short and descriptive](writing_short.md).
|
||||
|
||||
{width=362}
|
||||
- Do not repeat the setting name in the help text:
|
||||
|
||||
### Writing guidelines
|
||||
<table style="none" border="false" column-width="fixed">
|
||||
<tr>
|
||||
<td width="378">
|
||||
<format color="369650" style="bold">Correct</format>
|
||||
<img src="inline_text_repetition_correct.png" alt="Avoid brackets: correct"/>
|
||||
</td>
|
||||
<td width="378">
|
||||
<format color="E55765" style="bold">Incorrect</format>
|
||||
<img src="inline_text_repetition_incorrect.png" alt="Avoid brackets: incorrect"/>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
Make help text [short and descriptive](writing_short.md).
|
||||
<chapter title="Placement" id="placement">
|
||||
|
||||
Do not repeat the setting name in the help text.
|
||||
|
||||
{width=481}
|
||||
|
||||
## Placement
|
||||
|
||||
### Labeled input, button, checkbox, or radio button
|
||||
|
||||
Labeled inputs are fields, combo boxes, or text areas.
|
||||
|
||||
Place the help text to the right of a labeled input, checkbox, or radio button if all the following applies:
|
||||
<chapter title="Labeled inputs, checkboxes, radio buttons, and buttons" id="small_ui_controls">
|
||||
|
||||
Place the help text to the right of labeled inputs (fields, combo boxes, or text areas), checkboxes, buttons, or radio buttons if all the following applies:
|
||||
* The space to the right is empty.
|
||||
* The help text has 1–5 words, not counting articles and prepositions.
|
||||
* The control label has 1–5 words.
|
||||
|
||||
{width=433}
|
||||
<img src="inline_text_on_the_right_input_field.png" width="706" alt="Input fields with inline texts on the right"/>
|
||||
|
||||
<chapter title="Implementation" id="labeled_input_inline_text_implementation" collapsible="true" default-state="collapsed">
|
||||
```kotlin
|
||||
panel {
|
||||
row("Plugin update policy:") {
|
||||
@ -104,8 +146,32 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
{width=438}
|
||||
* In other cases, place the help text under the UI controls:
|
||||
|
||||
<img src="inline_text_on_the_bottom.png" width="706" alt="Input filed with inline text on the bottom"/>
|
||||
|
||||
<chapter title="Implementation" id="implementation_under_input_filed" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
row("Default directory:") {
|
||||
textFieldWithBrowseButton()
|
||||
.comment(
|
||||
"Preselected in Open and New | Project dialogs"
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
If there is no space under the UI control, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon for labeled inputs, checkboxes, and radio buttons.
|
||||
For buttons, use the help tooltip without the icon.
|
||||
|
||||
<chapter title="Checkboxes" id="checkboxes">
|
||||
<img src="inline_text_on_the_right_checkbox.png" width="706" alt="Checkboxes with inline texts on the right"/>
|
||||
<chapter collapsible="true" default-state="collapsed" title="Implementation">
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
@ -119,32 +185,21 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
{width=309}
|
||||
<chapter title="Buttons" id="buttons">
|
||||
<img src="inline_text_on_the_right_button.png" width="706" alt="Button with inline texts on the right"/>
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
Otherwise, place the help text under the UI control.
|
||||
|
||||
{width=484}
|
||||
|
||||
```kotlin
|
||||
panel {
|
||||
row("Default directory:") {
|
||||
textFieldWithBrowseButton()
|
||||
.comment(
|
||||
"Preselected in \"Open ...\" and \"New | Project\" dialogs"
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If there is no space under the UI control, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon for labeled inputs, checkboxes, and radio buttons.
|
||||
For buttons, use the help tooltip without the icon.
|
||||
|
||||
### List, tree or table
|
||||
<chapter title="Trees, lists, and tables" id="trees_lists_tables">
|
||||
|
||||
If the help text applies to a whole list, tree, or table, place it below the control.
|
||||
|
||||
{width=531}
|
||||
<img src="inline_text_under_table.png" width="706" alt="Inline text under the table"/>
|
||||
|
||||
<chapter title="Implementation" id="implementation_table" collapsible="true" default-state="collapsed">
|
||||
|
||||
```kotlin
|
||||
|
||||
@ -163,31 +218,33 @@ panel {
|
||||
}.resizableRow()
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
|
||||
If it applies to a single list, tree or table item:
|
||||
If the help text applies to a single list, tree, or table item:
|
||||
|
||||
* If the help text has 1–10 words, place it to the right of the item.
|
||||
*
|
||||
* If the help text has 1–10 words, place it to the right of the item:
|
||||
|
||||
{width=422}
|
||||
<img src="inline_text_on_the_right_tree.png" width="706" alt="Inline text under the table"/>
|
||||
|
||||
* If the text is longer than 10 words:
|
||||
|
||||
<p>For a list or tree in the master part, place the text into the detail part.</p>
|
||||
For a list or tree in the master part, place the text into the detail part.
|
||||
|
||||
{width=673}
|
||||
<img src="inline_text_on_the_bottom_master_detail.png" width="706" alt="Inline text on the bottom of the master detail layout"/>
|
||||
|
||||
If the case with the master-detail layout above does not apply, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon.
|
||||
For other cases, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon:
|
||||
|
||||
{width=390}
|
||||
<img src="tooltip_list.png" width="706" alt="Inline text on the bottom of the master detail layout"/>
|
||||
|
||||
### Group of controls
|
||||
</chapter>
|
||||
|
||||
<chapter title="Group of controls" id="group_of_controls">
|
||||
|
||||
If the help text applies to several UI controls, place it at the bottom of the group.
|
||||
|
||||
{width=430}
|
||||
<img src="inline_text_group.png" width="706" alt="Inline text for a group of controls"/>
|
||||
|
||||
<p>Implementation</p>
|
||||
<chapter title="Implementation" id="implementation_group" collapsible="true" default-state="collapsed">
|
||||
|
||||
Use [`Panel.group()`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Panel.kt) as the border for panels that need title and possibly the gray line on the right of the title:
|
||||
|
||||
@ -219,5 +276,9 @@ panel {
|
||||
}
|
||||
}
|
||||
```
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
||||
You can find more examples by invoking the **Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase** action (available in [internal mode](enabling_internal.md) and clicking the **View source** links on specific pages.
|
||||
</chapter>
|
||||
|
||||
You can find more examples by invoking the <ui-path>Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase</ui-path> action (available in [internal mode](enabling_internal.md)) and clicking the <control>View source</control> links on specific pages.
|
||||
|
||||