diff --git a/images/ui/inline_help_text/inline_text_brackets_correct.png b/images/ui/inline_help_text/inline_text_brackets_correct.png new file mode 100644 index 000000000..43b58ad5a Binary files /dev/null and b/images/ui/inline_help_text/inline_text_brackets_correct.png differ diff --git a/images/ui/inline_help_text/inline_text_brackets_correct_dark.png b/images/ui/inline_help_text/inline_text_brackets_correct_dark.png new file mode 100644 index 000000000..4d31d487f Binary files /dev/null and b/images/ui/inline_help_text/inline_text_brackets_correct_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_brackets_incorrect.png b/images/ui/inline_help_text/inline_text_brackets_incorrect.png new file mode 100644 index 000000000..db55834ed Binary files /dev/null and b/images/ui/inline_help_text/inline_text_brackets_incorrect.png differ diff --git a/images/ui/inline_help_text/inline_text_brackets_incorrect_dark.png b/images/ui/inline_help_text/inline_text_brackets_incorrect_dark.png new file mode 100644 index 000000000..1e14d9b7e Binary files /dev/null and b/images/ui/inline_help_text/inline_text_brackets_incorrect_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_external_link.png b/images/ui/inline_help_text/inline_text_external_link.png new file mode 100644 index 000000000..9a274a867 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_external_link.png differ diff --git a/images/ui/inline_help_text/inline_text_external_link_dark.png b/images/ui/inline_help_text/inline_text_external_link_dark.png new file mode 100644 index 000000000..3df0d65ff Binary files /dev/null and b/images/ui/inline_help_text/inline_text_external_link_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_formatting_correct.png b/images/ui/inline_help_text/inline_text_formatting_correct.png new file mode 100644 index 000000000..96c914900 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_formatting_correct.png differ diff --git a/images/ui/inline_help_text/inline_text_formatting_correct_dark.png b/images/ui/inline_help_text/inline_text_formatting_correct_dark.png new file mode 100644 index 000000000..cd83e4957 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_formatting_correct_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_formatting_incorrect.png b/images/ui/inline_help_text/inline_text_formatting_incorrect.png new file mode 100644 index 000000000..441aa47ba Binary files /dev/null and b/images/ui/inline_help_text/inline_text_formatting_incorrect.png differ diff --git a/images/ui/inline_help_text/inline_text_formatting_incorrect_dark.png b/images/ui/inline_help_text/inline_text_formatting_incorrect_dark.png new file mode 100644 index 000000000..5b57d5b16 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_formatting_incorrect_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_group.png b/images/ui/inline_help_text/inline_text_group.png new file mode 100644 index 000000000..a337398b5 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_group.png differ diff --git a/images/ui/inline_help_text/inline_text_group_dark.png b/images/ui/inline_help_text/inline_text_group_dark.png new file mode 100644 index 000000000..d24ef351f Binary files /dev/null and b/images/ui/inline_help_text/inline_text_group_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_height.png b/images/ui/inline_help_text/inline_text_height.png new file mode 100644 index 000000000..2aadd429e Binary files /dev/null and b/images/ui/inline_help_text/inline_text_height.png differ diff --git a/images/ui/inline_help_text/inline_text_height_dark.png b/images/ui/inline_help_text/inline_text_height_dark.png new file mode 100644 index 000000000..1cdefb2f3 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_height_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_internal_link.png b/images/ui/inline_help_text/inline_text_internal_link.png new file mode 100644 index 000000000..d6119910f Binary files /dev/null and b/images/ui/inline_help_text/inline_text_internal_link.png differ diff --git a/images/ui/inline_help_text/inline_text_internal_link_dark.png b/images/ui/inline_help_text/inline_text_internal_link_dark.png new file mode 100644 index 000000000..572ddc150 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_internal_link_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_legal.png b/images/ui/inline_help_text/inline_text_legal.png new file mode 100644 index 000000000..c6670165a Binary files /dev/null and b/images/ui/inline_help_text/inline_text_legal.png differ diff --git a/images/ui/inline_help_text/inline_text_legal_dark.png b/images/ui/inline_help_text/inline_text_legal_dark.png new file mode 100644 index 000000000..cb079b7a9 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_legal_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom.png b/images/ui/inline_help_text/inline_text_on_the_bottom.png new file mode 100644 index 000000000..c55ce3bb9 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom_dark.png b/images/ui/inline_help_text/inline_text_on_the_bottom_dark.png new file mode 100644 index 000000000..b6eb45804 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail.png b/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail.png new file mode 100644 index 000000000..f8b6f0bb1 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail_dark.png b/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail_dark.png new file mode 100644 index 000000000..efdc9fa69 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom_master_detail_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom_tree.png b/images/ui/inline_help_text/inline_text_on_the_bottom_tree.png new file mode 100644 index 000000000..f8b6f0bb1 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom_tree.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_bottom_tree_dark.png b/images/ui/inline_help_text/inline_text_on_the_bottom_tree_dark.png new file mode 100644 index 000000000..efdc9fa69 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_bottom_tree_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_button.png b/images/ui/inline_help_text/inline_text_on_the_right_button.png new file mode 100644 index 000000000..20c6822b4 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_button.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_button_dark.png b/images/ui/inline_help_text/inline_text_on_the_right_button_dark.png new file mode 100644 index 000000000..8b7bb35b8 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_button_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_checkbox.png b/images/ui/inline_help_text/inline_text_on_the_right_checkbox.png new file mode 100644 index 000000000..40d53c3ce Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_checkbox.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_checkbox_dark.png b/images/ui/inline_help_text/inline_text_on_the_right_checkbox_dark.png new file mode 100644 index 000000000..7db2ba02b Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_checkbox_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_input_field.png b/images/ui/inline_help_text/inline_text_on_the_right_input_field.png new file mode 100644 index 000000000..fed5968bd Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_input_field.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_input_field_dark.png b/images/ui/inline_help_text/inline_text_on_the_right_input_field_dark.png new file mode 100644 index 000000000..9216913fd Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_input_field_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_tree.png b/images/ui/inline_help_text/inline_text_on_the_right_tree.png new file mode 100644 index 000000000..fb124db4f Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_tree.png differ diff --git a/images/ui/inline_help_text/inline_text_on_the_right_tree_dark.png b/images/ui/inline_help_text/inline_text_on_the_right_tree_dark.png new file mode 100644 index 000000000..5d1e818f3 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_on_the_right_tree_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_repetition_correct.png b/images/ui/inline_help_text/inline_text_repetition_correct.png new file mode 100644 index 000000000..196b64bfa Binary files /dev/null and b/images/ui/inline_help_text/inline_text_repetition_correct.png differ diff --git a/images/ui/inline_help_text/inline_text_repetition_correct_dark.png b/images/ui/inline_help_text/inline_text_repetition_correct_dark.png new file mode 100644 index 000000000..fcba44165 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_repetition_correct_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_repetition_incorrect.png b/images/ui/inline_help_text/inline_text_repetition_incorrect.png new file mode 100644 index 000000000..2590b7f4e Binary files /dev/null and b/images/ui/inline_help_text/inline_text_repetition_incorrect.png differ diff --git a/images/ui/inline_help_text/inline_text_repetition_incorrect_dark.png b/images/ui/inline_help_text/inline_text_repetition_incorrect_dark.png new file mode 100644 index 000000000..59228b97a Binary files /dev/null and b/images/ui/inline_help_text/inline_text_repetition_incorrect_dark.png differ diff --git a/images/ui/inline_help_text/inline_text_under_table.png b/images/ui/inline_help_text/inline_text_under_table.png new file mode 100644 index 000000000..94c150818 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_under_table.png differ diff --git a/images/ui/inline_help_text/inline_text_under_table_dark.png b/images/ui/inline_help_text/inline_text_under_table_dark.png new file mode 100644 index 000000000..7159eb6e3 Binary files /dev/null and b/images/ui/inline_help_text/inline_text_under_table_dark.png differ diff --git a/images/ui/inline_help_text/tooltip_list.png b/images/ui/inline_help_text/tooltip_list.png new file mode 100644 index 000000000..c61106a05 Binary files /dev/null and b/images/ui/inline_help_text/tooltip_list.png differ diff --git a/images/ui/inline_help_text/tooltip_list_dark.png b/images/ui/inline_help_text/tooltip_list_dark.png new file mode 100644 index 000000000..03789a190 Binary files /dev/null and b/images/ui/inline_help_text/tooltip_list_dark.png differ diff --git a/topics/ui/controls/inline_help_text.md b/topics/ui/controls/inline_help_text.md index c8191a839..07d1c10dd 100644 --- a/topics/ui/controls/inline_help_text.md +++ b/topics/ui/controls/inline_help_text.md @@ -4,27 +4,26 @@ UI guidelines on using inline help texts. -Inline help text provides useful information about a setting. +Inline help texts provide useful information about settings: -![](01_header_pic.png){width=304} +Inline help text -## When to use + +

Follow the rules for context help.

+ -Follow the rules for [context help](context_help.md). + + +Show no more than five lines of help text to not clutter the screen. +Text width is limited to 70 characters. -## How to use +![](inline_text_height.png){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. +![](inline_text_legal.png){width=706} -![](02_text_size.png){width=380} - -Show more than 5 lines only when a text cannot be shortened for legal purposes. - -![](03_text_size_long.png){width=396} - -

Implementation

+ ```kotlin panel { @@ -46,52 +45,95 @@ panel { } } ``` + + + 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. -![](04_link_external.png){width=366 style=block} -*External link* + + + + + +
+ Internal link + Internal link + + External link + External link +
+ -![](04_link_internal.png){width=345 style=block} -*Local link* + -Text style formatting: +- Avoid text highlighting. Usually, the help text is short, and no highlighting in bold or italics is needed: + + + + + +
+ Correct + Avoid highlighting: correct + + Incorrect + Avoid highlighting: incorrect +
-* 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 `` tags is not needed.) - ![](inline_text_no_styling.png){width=364} +[//]: # ( ![](inline_text_parameter_styling.png){width=213}) -* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `` tags is not needed. +- Avoid using brackets in control labels and place this information in the inline text instead: + + + + + +
+ Correct + Avoid brackets: correct + + Incorrect + Avoid brackets: incorrect +
+ - ![](inline_text_parameter_styling.png){width=213} + -Avoid using brackets. +- Make help text [short and descriptive](writing_short.md). -![](05_no_brackets.png){width=362} +- Do not repeat the setting name in the help text: -### Writing guidelines + + + + + +
+ Correct + Avoid brackets: correct + + Incorrect + Avoid brackets: incorrect +
+ + -Make help text [short and descriptive](writing_short.md). + -Do not repeat the setting name in the help text. - -![](06_inline_text_dont_repeat_setting.png){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: + +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. -![](07_right_inputs.png){width=433} +Input fields with inline texts on the right + ```kotlin panel { row("Plugin update policy:") { @@ -104,8 +146,32 @@ panel { } } ``` + -![](08_right_checkboxes.png){width=438} +* In other cases, place the help text under the UI controls: + +Input filed with inline text on the bottom + + + +```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. + + +Checkboxes with inline texts on the right + ```kotlin panel { @@ -119,32 +185,21 @@ panel { } } ``` + + -![](09_right_button.png){width=309} + + Button with inline texts on the right + + -Otherwise, place the help text under the UI control. - -![](10_under_field.png){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 + If the help text applies to a whole list, tree, or table, place it below the control. -![](11_under_table.png){width=531} +Inline text under the table + + ```kotlin @@ -163,31 +218,33 @@ panel { }.resizableRow() } ``` + -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: -![](12_tree_inline_help_text.png){width=422} +Inline text under the table * If the text is longer than 10 words: -

For a list or tree in the master part, place the text into the detail part.

+For a list or tree in the master part, place the text into the detail part. -![](13_master-detail_help_text.png){width=673} +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: -![](05_question_icon_tree.png){width=390} +Inline text on the bottom of the master detail layout -### Group of controls + + + If the help text applies to several UI controls, place it at the bottom of the group. -![](14_under_group.png){width=430} +Inline text for a group of controls -

Implementation

+ 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 { } } ``` + + + +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. + -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.