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>
6.1 KiB
Inline Help Text
UI guidelines on using inline help texts.
Inline help text provides useful information about a setting.
{width=304}
When to use
Follow the rules for context help.
How to use
Text length and formatting
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=380}
Show more than 5 lines only when a text cannot be shortened for legal purposes.
{width=396}
Implementation
panel {
row {
checkBox("Send usage statistics when using EAP versions")
.comment("""
<p>Help JetBrains improve its products by sending anonymous
data about features and plugins used, hardware and software
configuration, statistics on types of files, number of files
per project, etc.</p>
<br/>
<p>Please note that this will not include personal data or
any sensitive information, such as source code, file names,
etc. The data sent complies with the
<a href=\"https://www.jetbrains.com\">
JetBrains Privacy Policy</a></p>
""".trimIndent()
)
}
}
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
{width=345 style=block}
Local link
Text style formatting:
-
Avoid text highlighting. Usually, the help text is short and no bold or italics are needed.
{width=364} -
Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in
<html></html>tags is not needed.
{width=213}
Avoid using brackets.
{width=362}
Writing guidelines
Make help text short and descriptive.
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:
- 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}
panel {
row("Plugin update policy:") {
comboBox(listOf("Default", "Non default"))
comment("Ignore by Maven 3+")
}
row("Thread count:") {
textField()
comment("-T option")
}
}
{width=438}
panel {
row {
checkBox("Build project automatically")
comment("Works while not running / debugging")
}
row {
checkBox("Compile independent modules in parallel")
comment("May require larger heap size")
}
}
{width=309}
Otherwise, place the help text under the UI control.
{width=484}
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 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.
{width=531}
import javax.swing.JTable
panel {
row {
cell(createTable()) // Actual table creation
.align(Align.FILL)
.comment("""
<Project> is content roots of all modules,
all immediate descendants<br/>of the projects base
directory, and .idea directory contents
""".trimIndent()
)
}.resizableRow()
}
If it 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.
{width=422}
- If the text is longer than 10 words:
For a list or tree in the master part, place the text into the detail part.
{width=673}
If the case with the master-detail layout above does not apply, use the help tooltip with the question mark icon.
{width=390}
Group of controls
If the help text applies to several UI controls, place it at the bottom of the group.
{width=430}
Implementation
Use Panel.group() as the border for panels that need title and possibly the gray line on the right of the title:
panel {
group("Build and Run") {
row("Build and run with:") {
comboBox(listOf("IntelliJ IDEA", "Gradle"))
}
row("Run tests with:") {
comboBox(listOf("IntelliJ IDEA", "Gradle"))
}
row {
comment("""
<p>By default IntelliJ IDEA uses Gradle to build the project
and run the tasks.</p>
<p>In a pure Java/Kotlin project, building and running
by means of IDE might be faster, thanks to optimizations.
Note, that the IDE doesn't support all Gradle plugins and
the project might not be built correctly with some of them.</p>
""".trimIndent()
)
}
}
group("Gradle") {
row("Use Gradle from:") {
comboBox(gradleModel)
}
}
}
You can find more examples by invoking the Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase action (available in internal mode) and clicking the View source links on specific pages.