Merge branch 'checkbox-eldar'
# Conflicts: # topics/ui/controls/radio_button.md
eldar-jetbrains
2
ijs.tree
@ -465,7 +465,7 @@
|
|||||||
<toc-element topic="built_in_button.md"/>
|
<toc-element topic="built_in_button.md"/>
|
||||||
<toc-element topic="split_button.md"/>
|
<toc-element topic="split_button.md"/>
|
||||||
</toc-element>
|
</toc-element>
|
||||||
<toc-element topic="checkbox.md"/>
|
<toc-element topic="checkbox.topic"/>
|
||||||
<toc-element topic="combo_box.md"/>
|
<toc-element topic="combo_box.md"/>
|
||||||
<toc-element topic="context_help.md">
|
<toc-element topic="context_help.md">
|
||||||
<toc-element topic="inline_help_text.md"/>
|
<toc-element topic="inline_help_text.md"/>
|
||||||
|
|||||||
BIN
images/ui/checkbox/checkbox.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_dark.png
Normal file
|
After Width: | Height: | Size: 10 KiB |
BIN
images/ui/checkbox/checkbox_download_status.png
Normal file
|
After Width: | Height: | Size: 20 KiB |
BIN
images/ui/checkbox/checkbox_download_status_dark.png
Normal file
|
After Width: | Height: | Size: 21 KiB |
BIN
images/ui/checkbox/checkbox_label_long_correct.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/checkbox/checkbox_label_long_correct_dark.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/checkbox/checkbox_label_long_incorrect.png
Normal file
|
After Width: | Height: | Size: 26 KiB |
BIN
images/ui/checkbox/checkbox_label_long_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 26 KiB |
BIN
images/ui/checkbox/checkbox_label_right_correct.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_label_right_correct_dark.png
Normal file
|
After Width: | Height: | Size: 5.5 KiB |
BIN
images/ui/checkbox/checkbox_label_right_incorrect.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_label_right_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 5.5 KiB |
BIN
images/ui/checkbox/checkbox_three_state.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/checkbox/checkbox_three_state_dark.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1_correct.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1_correct_dark.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1_dark.png
Normal file
|
After Width: | Height: | Size: 15 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1_incorrect.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_1_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2-1.png
Normal file
|
After Width: | Height: | Size: 10 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2.png
Normal file
|
After Width: | Height: | Size: 10 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2_correct.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2_correct_dark.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2_dark.png
Normal file
|
After Width: | Height: | Size: 10 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2_incorrect.png
Normal file
|
After Width: | Height: | Size: 5.4 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_2_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 5.2 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_3-1.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_3.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_when_not_to_use_3_dark.png
Normal file
|
After Width: | Height: | Size: 11 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use.png
Normal file
|
After Width: | Height: | Size: 17 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_1.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_1_dark.png
Normal file
|
After Width: | Height: | Size: 5.5 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_2.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_2_dark.png
Normal file
|
After Width: | Height: | Size: 13 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_3.png
Normal file
|
After Width: | Height: | Size: 14 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_3_dark.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/checkbox/checkbox_when_to_use_dark.png
Normal file
|
After Width: | Height: | Size: 16 KiB |
BIN
images/ui/checkbox/checkbox_writing_1_correct.png
Normal file
|
After Width: | Height: | Size: 6.3 KiB |
BIN
images/ui/checkbox/checkbox_writing_1_correct_dark.png
Normal file
|
After Width: | Height: | Size: 6.1 KiB |
BIN
images/ui/checkbox/checkbox_writing_1_incorrect.png
Normal file
|
After Width: | Height: | Size: 6.4 KiB |
BIN
images/ui/checkbox/checkbox_writing_1_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 6.1 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_correct-1.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_correct.png
Normal file
|
After Width: | Height: | Size: 5.9 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_correct_dark.png
Normal file
|
After Width: | Height: | Size: 5.6 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_incorrect-1.png
Normal file
|
After Width: | Height: | Size: 6.2 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_incorrect.png
Normal file
|
After Width: | Height: | Size: 6.0 KiB |
BIN
images/ui/checkbox/checkbox_writing_2_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_writing_3_correct.png
Normal file
|
After Width: | Height: | Size: 9.7 KiB |
BIN
images/ui/checkbox/checkbox_writing_3_correct_dark.png
Normal file
|
After Width: | Height: | Size: 9.4 KiB |
BIN
images/ui/checkbox/checkbox_writing_3_incorrect.png
Normal file
|
After Width: | Height: | Size: 9.9 KiB |
BIN
images/ui/checkbox/checkbox_writing_3_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 9.7 KiB |
BIN
images/ui/checkbox/checkbox_writing_4_correct.png
Normal file
|
After Width: | Height: | Size: 5.9 KiB |
BIN
images/ui/checkbox/checkbox_writing_4_correct_dark.png
Normal file
|
After Width: | Height: | Size: 5.7 KiB |
BIN
images/ui/checkbox/checkbox_writing_4_incorrect.png
Normal file
|
After Width: | Height: | Size: 6.5 KiB |
BIN
images/ui/checkbox/checkbox_writing_4_incorrect_dark.png
Normal file
|
After Width: | Height: | Size: 6.2 KiB |
@ -22,7 +22,7 @@
|
|||||||
<td>An icon placed inside an input control.</td>
|
<td>An icon placed inside an input control.</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><a href="checkbox.md"></a></td>
|
<td><a href="checkbox.topic"></a></td>
|
||||||
<td>Use checkboxes for yes/no choices or for selecting several items in a group.
|
<td>Use checkboxes for yes/no choices or for selecting several items in a group.
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|||||||
@ -1,192 +0,0 @@
|
|||||||
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
||||||
|
|
||||||
# Checkbox
|
|
||||||
|
|
||||||
<link-summary>UI guidelines on using checkboxes.</link-summary>
|
|
||||||
|
|
||||||
<tldr>
|
|
||||||
|
|
||||||
**Implementation:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html), [`JBCheckBox`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java)
|
|
||||||
|
|
||||||
</tldr>
|
|
||||||
|
|
||||||
{width=166}
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
Use checkboxes for yes/no choices or for selecting several items in a group.
|
|
||||||
|
|
||||||
Do **not** use checkboxes if:
|
|
||||||
|
|
||||||
* Only one option in a group can be selected. Use a [radio button group](radio_button.md) instead.
|
|
||||||
* The behavior in the "off" state is unclear from the checkbox label. Use two radio buttons instead and label them accordingly.
|
|
||||||
{width=365}
|
|
||||||
* With the checkbox, it is unclear how the setting works if it’s unchecked. With radio buttons, both states are labeled clearly.*
|
|
||||||
|
|
||||||
## How to use
|
|
||||||
|
|
||||||
### Label
|
|
||||||
|
|
||||||
A label accompanies each checkbox and is placed next to it.
|
|
||||||
|
|
||||||
{width=161}
|
|
||||||
|
|
||||||
If a label is long, split it into two lines. Use HTML formatting for that.
|
|
||||||
|
|
||||||
{width=331}
|
|
||||||
|
|
||||||
<tabs group="languages">
|
|
||||||
<tab title="Kotlin UI DSL" group-key="kotlin">
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
checkBox(
|
|
||||||
"""<html>Insert selected suggestion by pressing space, dot,<br/>
|
|
||||||
or other context-dependent keys</html>""")
|
|
||||||
```
|
|
||||||
|
|
||||||
</tab>
|
|
||||||
<tab title="Java" group-key="java">
|
|
||||||
|
|
||||||
```java
|
|
||||||
new JCheckBox(
|
|
||||||
"<html>Insert selected suggestion by pressing space, dot,<br/>" +
|
|
||||||
"or other context-dependent keys</html>");
|
|
||||||
```
|
|
||||||
|
|
||||||
</tab>
|
|
||||||
</tabs>
|
|
||||||
|
|
||||||
Avoid labels that take more than two lines. See recommendations on writing concise labels below.
|
|
||||||
|
|
||||||
If a checkbox appears in a table, place the label into the column header and do not repeat it on every row.
|
|
||||||
|
|
||||||
{width=347}
|
|
||||||
|
|
||||||
**Implementation**: Checkboxes are rendered in tables with [`BooleanTableCellRenderer`](%gh-ic%/platform/core-ui/src/ui/BooleanTableCellRenderer.java)
|
|
||||||
and edited with `DefaultCellEditor(JCheckBox)` implementation.
|
|
||||||
For any column that should be rendered as a checkbox, set both a renderer and editor for consistency.
|
|
||||||
The type of data in the correspondent column of the `Table` model should either be `Boolean` or `String` containing `true` or `false`.
|
|
||||||
|
|
||||||
```java
|
|
||||||
TableColumn column = table.getColumnModel().getColumn(COLUMN_INDEX);
|
|
||||||
column.setCellEditor(JBTable.createBooleanEditor());
|
|
||||||
column.setCellRenderer(new BooleanTableCellRender());
|
|
||||||
```
|
|
||||||
|
|
||||||
### Writing guidelines
|
|
||||||
|
|
||||||
Use sentence-style capitalization.
|
|
||||||
|
|
||||||
Do not use ending punctuation.
|
|
||||||
|
|
||||||
Use the imperative form of verbs.
|
|
||||||
|
|
||||||
{width=350}
|
|
||||||
|
|
||||||
Do not use negation in labels as it complicates understanding.
|
|
||||||
**Exception**: "Do not show again" checkbox.
|
|
||||||
|
|
||||||
{width=224}
|
|
||||||
|
|
||||||
Make labels short and intelligible — see [Writing short and clear](writing_short.md).
|
|
||||||
|
|
||||||
### Three-state checkbox
|
|
||||||
|
|
||||||
In a group of options, use the parent checkbox to show the status of its children.
|
|
||||||
|
|
||||||
{width=542}
|
|
||||||
|
|
||||||
*The parent checkbox in checked, indeterminate and unchecked states*
|
|
||||||
**Implementation**: The three-state checkbox is represented by the [`ThreeStateCheckBox`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/ThreeStateCheckBox.java)
|
|
||||||
class which represents its state with the `ThreeStateCheckBox.State` enum containing `SELECTED, NOT_SELECTED, DONT_CARE` states.
|
|
||||||
|
|
||||||
When the user clicks an indeterminate checkbox for the first time, the whole group becomes checked. The second click unchecks the whole group.
|
|
||||||
|
|
||||||
An indeterminate checkbox can also show the download status. An example with a remote repository:
|
|
||||||
|
|
||||||
{width=358}
|
|
||||||
|
|
||||||
*Repositories "tools-base" and "contrib" are being loaded. When loading is finished, the indeterminate checkbox will be replaced with the checked checkbox if there are commits, or an unchecked checkbox if there are no commits.*
|
|
||||||
|
|
||||||
**Implementation**: In a table, the three-state checkbox is represented by [`ThreeStateCheckBoxRenderer`](%gh-ic%/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/table/ThreeStateCheckBoxRenderer.java)
|
|
||||||
that provides both `TableCellRenderer` and `TableEditor`.
|
|
||||||
It accepts `Boolean` type in the column being supplied by the `TableModel` and becomes `DONT_CARE` when the value in the cell is null.
|
|
||||||
Otherwise, it becomes `SELECTED` for `Boolean.TRUE`, and `NOT_SELECTED` for `Boolean.FALSE`.
|
|
||||||
|
|
||||||
## Placement
|
|
||||||
|
|
||||||
If a checkbox depends on another control, e.g., an input field, follow the rules for [dependent controls](layout.md#dependent-controls). Otherwise, follow the rules for [independent controls](layout.md#independent-controls).
|
|
||||||
|
|
||||||
<!--
|
|
||||||
### Colors
|
|
||||||
<p> The color keys can be used only in a UI theme plugin. </p>
|
|
||||||
|
|
||||||
<table>
|
|
||||||
<col width="50%">
|
|
||||||
<tr>
|
|
||||||
<td> Unchecked background </td>
|
|
||||||
<td> Checkbox.Background.Default <br/>
|
|
||||||
Checkbox.Background.Default.Dark </td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Checked background </td>
|
|
||||||
<td> Checkbox.Background.Selected <br/>
|
|
||||||
Checkbox.Background.Selected.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Disabled background </td>
|
|
||||||
<td> Checkbox.Background.Disabled <br/>
|
|
||||||
Checkbox.Background.Disabled.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Unchecked border </td>
|
|
||||||
<td> Checkbox.Border.Default <br/>
|
|
||||||
Checkbox.Border.Default.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Checked border </td>
|
|
||||||
<td> Checkbox.Border.Selected <br/>
|
|
||||||
Checkbox.Border.Selected.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Disabled border </td>
|
|
||||||
<td> Checkbox.Border.Disabled <br/>
|
|
||||||
Checkbox.Border.Disabled.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Focused inner 1px border for unchecked state </td>
|
|
||||||
<td> Checkbox.Focus.Thin.Default <br/>
|
|
||||||
Checkbox.Focus.Thin.Default.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Focused inner 1px border for checked state </td>
|
|
||||||
<td> Checkbox.Focus.Thin.Selected <br/>
|
|
||||||
Checkbox.Focus.Thin.Selected.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Focused outer 2px border </td>
|
|
||||||
<td> Checkbox.Focus.Wide <br/>
|
|
||||||
Checkbox.Focus.Wide.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Checkmark fill </td>
|
|
||||||
<td> Checkbox.Foreground.Selected <br/>
|
|
||||||
Checkbox.Foreground.Selected.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td> Disabled checkmark fill </td>
|
|
||||||
<td> Checkbox.Foreground.Disabled <br/>
|
|
||||||
Checkbox.Foreground.Disabled.Dark
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
-->
|
|
||||||
209
topics/ui/controls/checkbox.topic
Normal file
@ -0,0 +1,209 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
|
||||||
|
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
|
||||||
|
id="checkbox" title="Checkbox">
|
||||||
|
|
||||||
|
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
||||||
|
<title>
|
||||||
|
Checkbox
|
||||||
|
</title>
|
||||||
|
<link-summary>UI guidelines on using checkboxes.</link-summary>
|
||||||
|
<tldr>
|
||||||
|
<p>
|
||||||
|
<control>Implementation:</control>
|
||||||
|
<a href="https://docs.oracle.com/javase/8/docs/api/javax/swing/JCheckBox.html"><code>JCheckBox</code></a>,
|
||||||
|
<a href="%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java"><code>JBCheckBox</code></a>
|
||||||
|
</p>
|
||||||
|
</tldr>
|
||||||
|
<img src="checkbox.png" alt="A preview of checkboxes in different states" width="706"/>
|
||||||
|
<chapter title="When to use" id="when-to-use">
|
||||||
|
<p>Use checkboxes for yes/no choices or for selecting several items in a group:</p>
|
||||||
|
<img src="checkbox_when_to_use.png" alt="An example of a checkbox group with two selected options" width="706"/>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="When not to use" id="when-not-to-use">
|
||||||
|
<p>If only one option in a group can be selected, use <a href="radio_button.md">radio button</a>:</p>
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="378">
|
||||||
|
<format style="bold" color="E55765">Incorrect</format>
|
||||||
|
<img src="checkbox_when_not_to_use_1_incorrect.png" alt="A radio button group with only one selected option possible"/>
|
||||||
|
</td>
|
||||||
|
<td width="378">
|
||||||
|
<format style="bold" color="369650">Correct</format>
|
||||||
|
<img src="checkbox_when_not_to_use_1_correct.png" alt="Two radio buttons with clear labels"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<p>If the behavior in the "off" state is unclear from the checkbox label, use two <a href="radio_button.md">radio buttons</a> instead
|
||||||
|
and label them accordingly:</p>
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="378">
|
||||||
|
<format style="bold" color="E55765">Incorrect</format>
|
||||||
|
<img src="checkbox_when_not_to_use_2_incorrect.png" alt="A radio button group with only one selected option possible"/>
|
||||||
|
</td>
|
||||||
|
<td width="378">
|
||||||
|
<format style="bold" color="369650">Correct</format>
|
||||||
|
<img src="checkbox_when_not_to_use_2_correct.png" alt="Two radio buttons with clear labels"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="How to use" id="how-to-use">
|
||||||
|
<chapter title="Label on the right" id="label-on-the-right">
|
||||||
|
<p>A label accompanies each checkbox and is placed on the right side.</p>
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="378">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_label_right_correct.png"
|
||||||
|
alt="A correct checkbox with the label on the right"/>
|
||||||
|
</td>
|
||||||
|
<td width="378">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_label_right_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the label on the left"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="Long labels" id="long-labeles">
|
||||||
|
<p>If a label is long, split it into two lines. Use HTML formatting for that. Avoid labels that take more than two lines. See recommendations on <a anchor="writing-guidelines">writing concise labels</a> below.</p>
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="378">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_label_long_correct.png"
|
||||||
|
alt="A correct checkbox with the label on the right"/>
|
||||||
|
</td>
|
||||||
|
<td width="378">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_label_long_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the label on the left"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<chapter title="Implementation" collapsible="true" id="implementation-of-long-labels">
|
||||||
|
<tabs group="languages">
|
||||||
|
<tab title="Kotlin UI DSL" group-key="kotlin">
|
||||||
|
<code-block lang="kotlin">
|
||||||
|
checkBox(
|
||||||
|
"""<html>Insert selected suggestion by pressing space, dot,<br/>
|
||||||
|
or other context-dependent keys</html>""")
|
||||||
|
</code-block>
|
||||||
|
</tab>
|
||||||
|
<tab title="Java" group-key="java">
|
||||||
|
<code-block lang="java">
|
||||||
|
new JCheckBox(
|
||||||
|
"<html>Insert selected suggestion by pressing space, dot,<br/>" +
|
||||||
|
"or other context-dependent keys</html>");
|
||||||
|
</code-block>
|
||||||
|
</tab>
|
||||||
|
</tabs>
|
||||||
|
</chapter>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="Checkboxes in a table">
|
||||||
|
<p>If a checkbox appears in a table, place the label into the column header and do not repeat it on every
|
||||||
|
row:</p>
|
||||||
|
<img src="checkbox_when_to_use_3.png"
|
||||||
|
alt="A table with checkboxes where the label is placed into the column header" width="706"/>
|
||||||
|
<chapter title="Implementation" collapsible="true" id="checkbox-table-implementation">
|
||||||
|
Checkboxes are rendered in tables with <a
|
||||||
|
href="%gh-ic%/platform/core-ui/src/ui/BooleanTableCellRenderer.java"><code>BooleanTableCellRenderer</code></a>
|
||||||
|
and edited with <code>DefaultCellEditor(JCheckBox)</code> implementation.
|
||||||
|
For any column that should be rendered as a checkbox, set both a renderer and editor for consistency.
|
||||||
|
The type of data in the correspondent column of the <code>Table</code> model should either be <code>Boolean</code>
|
||||||
|
or <code>String</code> containing <code>true</code> or <code>false</code>.
|
||||||
|
<code-block lang="java">
|
||||||
|
TableColumn column = table.getColumnModel().getColumn(COLUMN_INDEX);
|
||||||
|
column.setCellEditor(JBTable.createBooleanEditor());
|
||||||
|
column.setCellRenderer(new BooleanTableCellRender());
|
||||||
|
</code-block>
|
||||||
|
</chapter>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="Three-state checkbox" id="three-state-checkbox">
|
||||||
|
<chapter title="Status of children">
|
||||||
|
<p>In a group of options, use the parent checkbox to show the status of its children. The state of the parent checkbox can be checked, indeterminate or unchecked. When a user clicks an indeterminate checkbox for the first time, the whole group becomes checked. The second click unchecks the whole group.
|
||||||
|
</p>
|
||||||
|
<img src="checkbox_three_state.png"
|
||||||
|
alt="Different states for a parent checkbox: checked, indeterminate, and unchecked" width="706"/>
|
||||||
|
<chapter title="Implementation" collapsible="true">
|
||||||
|
The three-state checkbox is represented by the <a
|
||||||
|
href="%gh-ic%/platform/util/ui/src/com/intellij/util/ui/ThreeStateCheckBox.java"><code>ThreeStateCheckBox</code></a>
|
||||||
|
class which represents its state with the <code>ThreeStateCheckBox.State</code> enum containing <code>SELECTED,
|
||||||
|
NOT_SELECTED, DONT_CARE</code> states.</chapter>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="Download status">
|
||||||
|
<p>An indeterminate checkbox can also show the download status. In the example below, a remote repository with Repositories "tools-base" and "contrib" are being loaded. When loading is finished, the indeterminate checkbox will be replaced with the checked checkbox if there are commits, or an unchecked checkbox if there are no commits.</p>
|
||||||
|
<img src="checkbox_download_status.png" alt="Indeterminate checkboxes showing download status" width="706"/>
|
||||||
|
<chapter title="Implementation" collapsible="true">
|
||||||
|
<p>In a table, the three-state checkbox is represented by <a href="%gh-ic%/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/table/ThreeStateCheckBoxRenderer.java"><code>ThreeStateCheckBoxRenderer</code></a>
|
||||||
|
that provides both <code>TableCellRenderer</code> and <code>TableEditor</code>.
|
||||||
|
It accepts <code>Boolean</code> type in the column being supplied by the <code>TableModel</code> and
|
||||||
|
becomes <code>DONT_CARE</code> when the value in the cell is null.
|
||||||
|
Otherwise, it becomes <code>SELECTED</code> for <code>Boolean.TRUE</code>, and <code>NOT_SELECTED</code>
|
||||||
|
for <code>Boolean.FALSE</code>.</p>
|
||||||
|
</chapter>
|
||||||
|
</chapter>
|
||||||
|
</chapter>
|
||||||
|
</chapter>
|
||||||
|
<chapter title="Writing guidelines" id="writing-guidelines">
|
||||||
|
Use sentence-style capitalization:
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_writing_1_correct.png"
|
||||||
|
alt="A correct checkbox with the imperative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_writing_1_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the declarative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
Do not use ending punctuation:
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_writing_2_correct.png"
|
||||||
|
alt="A correct checkbox with the imperative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_writing_2_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the declarative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
Use the imperative form of verbs:
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_writing_3_correct.png"
|
||||||
|
alt="A correct checkbox with the imperative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_writing_3_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the declarative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
Do not use negation in labels as it complicates understanding:
|
||||||
|
<table style="none" border="false">
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="369650" style="bold">Correct</format><img src="checkbox_writing_4_correct.png"
|
||||||
|
alt="A correct checkbox with the imperative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
<format color="E55765" style="bold">Incorrect</format><img src="checkbox_writing_4_incorrect.png"
|
||||||
|
alt="An incorrect checkbox with the declarative form of the verb" width="378"/>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
<note>Exception: <control>Do not show again</control> checkbox.</note>
|
||||||
|
|
||||||
|
Make labels short and intelligible. See <a href="writing_short.md">Writing short and clear</a>.
|
||||||
|
</chapter>
|
||||||
|
<chapter title="How to layout" id="how-to-layout">
|
||||||
|
<p>
|
||||||
|
Follow the guidelines for <a href="layout.md" anchor="checkboxes-and-radio-buttons">checkboxes and radio buttons</a> layout.
|
||||||
|
</p>
|
||||||
|
</chapter>
|
||||||
|
</topic>
|
||||||
@ -55,7 +55,7 @@ If the setting is in a tree or menu, use the toggle button label to specify wher
|
|||||||
{width=676 style=block}
|
{width=676 style=block}
|
||||||
*The same setting in search results; separate the first menu level with a vertical bar, and separate others with a colon*
|
*The same setting in search results; separate the first menu level with a vertical bar, and separate others with a colon*
|
||||||
|
|
||||||
Refer to [checkbox](checkbox.md) for writing checkbox labels and menu labels.
|
Refer to [checkbox](checkbox.topic) for writing checkbox labels and menu labels.
|
||||||
|
|
||||||
[//]: # (TODO: and [menu](menu_list.md))
|
[//]: # (TODO: and [menu](menu_list.md))
|
||||||
|
|
||||||
|
|||||||