mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 01:07:49 +08:00
556 lines
25 KiB
XML
556 lines
25 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
||
<!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="button" title="Button">
|
||
|
||
<link-summary>UI guidelines on using buttons.</link-summary>
|
||
|
||
<tldr>
|
||
<p>
|
||
<control>Implementation</control>:
|
||
<a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html">JButton</a>
|
||
</p>
|
||
</tldr>
|
||
<img src="button_example.png" alt="Cancel and Save buttons" width="706"/>
|
||
<chapter title="When to use" id="when-to-use">
|
||
<p>Use a button to invoke an immediate action:</p>
|
||
<img src="when_to_use_button.png" alt="When to use a button" width="706"/>
|
||
</chapter>
|
||
<chapter title="When not to use" id="when-not-to-use">
|
||
<table style="none" border="false">
|
||
<tr>
|
||
<td width="50%"><img src="link_instead_of_button.png" alt="Using links instead of buttons" width="378"/></td>
|
||
<td><p>Use a link instead if:</p>
|
||
<list>
|
||
<li><p>The action takes the user to another page of the same dialog or an external source like
|
||
documentation.</p>
|
||
<note>Exception: the <control>Next</control> and <control>Previous</control> buttons in wizard navigation.</note>
|
||
</li>
|
||
<li>
|
||
The command is a secondary action that isn't related to the primary purpose of the window,
|
||
and the space is constrained.
|
||
</li>
|
||
</list>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><img src="toolbar_button.png" alt="Using toolbar buttons instead of buttons" width="378"/></td>
|
||
<td><p>Use a <a href="toolbar.md">toolbar button</a> instead if there are several buttons related to a table or list.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><img src="split_button.png" alt="Using split buttons instead of buttons" width="378"/></td>
|
||
<td><p>Use a <a href="split_button.md">split button</a> instead if:</p>
|
||
<list>
|
||
<li>There are more than two related actions, but the space is limited and/or packed.</li>
|
||
<li>The action isn't common and is dangerous, for example, can destroy user data and cannot be easily
|
||
undone.
|
||
</li>
|
||
</list>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%">
|
||
<img src="built-in_button.png" alt="Using built-in buttons instead of buttons" width="378"/>
|
||
</td>
|
||
<td><p>Use a <a href="built_in_button.md">built-in button</a> instead if it's related to an input field, combo box,
|
||
search field.</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
|
||
<chapter title="How to use" id="how-to-use">
|
||
<p>The label displays the action the button performs.</p>
|
||
<chapter title="Use title capitalization" id="use-title-capitalization">
|
||
<p>Use <a href="capitalization.md">title capitalization</a> for button labels.</p>
|
||
</chapter>
|
||
<chapter title="Use imperative verbs" id="use-imperative-verbs">
|
||
<p>Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.</p>
|
||
<note><p>Exceptions: standard buttons like <control>OK</control>, <control>Back</control>/<control>Forward</control>,
|
||
<control>Previous</control>/<control>Next</control>, <control>Yes</control>/<control>No</control>, <control>Agree</control>,
|
||
<control>Options</control>, <control>Settings</control>, <control>Details</control>.
|
||
</p></note>
|
||
</chapter>
|
||
<chapter title="Be specific" id="be-specific">
|
||
<p>The button should answer the question in the title, so the user can skip the description. Prefer specific
|
||
labels over
|
||
generic ones:</p>
|
||
<table style="none" border="false">
|
||
<tr>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="369650" style="bold">Correct</format>
|
||
</p>
|
||
</td>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="E55765" style="bold">Incorrect</format>
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><img src="default_button_save.png" alt="A correct button with a clear 'Save' label" width="378"/></td>
|
||
<td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/></td>
|
||
</tr>
|
||
</table>
|
||
<note>
|
||
Exception: the <control>Cancel</control> button if it's clear what action is being canceled.
|
||
For example, use
|
||
<control>Cancel</control> instead of <control>Don’t Create</control>.
|
||
</note>
|
||
<p>Do not
|
||
use the word
|
||
<control>Now</control> in labels because buttons always trigger an immediate action:
|
||
</p>
|
||
<table style="none" border="false">
|
||
<tr>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="369650" style="bold">Correct</format>
|
||
</p>
|
||
</td>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="E55765" style="bold">Incorrect</format>
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<img src="check_for_updates.png" alt="A button with 'Check for Updates' label" width="378"/>
|
||
</td>
|
||
<td><img src="check_now_button.png" alt="A button with 'Check Now' label" width="378"/></td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
<chapter title="Be short and clear" id="short_and_clear">
|
||
<p>The label should be short, not more than five words. If it’s not obvious what element the button is related
|
||
to, add more
|
||
words to make it clear. Prefer clear labels to short ones:</p>
|
||
<table style="none" border="false">
|
||
<tr>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="369650" style="bold">Correct</format>
|
||
</p>
|
||
</td>
|
||
<td width="50%">
|
||
<p>
|
||
<format color="DarkOrange" style="bold">Acceptable</format>
|
||
</p>
|
||
</td>
|
||
|
||
</tr>
|
||
<tr>
|
||
<td><img src="active_edit_action.png"
|
||
alt="A button with the 'Edit Action Icon...' label"
|
||
width="378"/></td>
|
||
<td><img src="active_edit.png" alt="A button with 'Edit' label" width="378"/></td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
<chapter title="Ellipsis" id="ellipsis">
|
||
<list>
|
||
<li>Add an ellipsis if additional actions such as adding more info or confirming the action are required.
|
||
</li>
|
||
<li>Don't add an ellipsis if another window is opened, but no more input from the user is required. For example,
|
||
<control>About</control>, <control>Details</control>.</li>
|
||
</list>
|
||
<img src="buttons_with_ellipsis.png" alt="Buttons with ellipsis" width="706"/>
|
||
</chapter>
|
||
</chapter>
|
||
<!-- <chapter title="Icons" id="icons">
|
||
<p>Don't add an icon to the button. The main purpose of an icon is to quickly find a
|
||
familiar action in a packed toolbar or menu. Usually, no more than three buttons
|
||
are placed nearby, their labels can be scanned quickly, and icons aren't required.
|
||
</p>
|
||
</chapter>-->
|
||
|
||
<chapter title="Button states" id="button-states">
|
||
<chapter title="Default" id="default">
|
||
|
||
<img src="default_button.png" alt="Default button on macOS and Windows" width="706"/>
|
||
<list>
|
||
<li>The default button confirms the main purpose of a dialog. It is triggered by pressing
|
||
<shortcut>Enter</shortcut>
|
||
or
|
||
<shortcut>Ctrl+Enter</shortcut>
|
||
on Windows/Linux and
|
||
<shortcut>Enter</shortcut>
|
||
or
|
||
<shortcut>Cmd+Enter</shortcut>
|
||
on macOS.
|
||
<note>Exception: if the focus is on an element that uses the
|
||
<shortcut>Enter</shortcut>
|
||
key, for example, a text area, the default button is triggered only by
|
||
<shortcut>Ctrl+Enter</shortcut>
|
||
on Windows/Linux and
|
||
<shortcut>Cmd+Enter</shortcut>
|
||
on macOS.</note>
|
||
</li>
|
||
<li>The default button should always be present in a dialog. Only one button in a dialog can be the default
|
||
one.
|
||
</li>
|
||
<li>If an action is dangerous, for example, it can lead to data loss, provide an easy way to undo the command.</li>
|
||
<li>If it's not possible to undo the action, make a secondary button the default one:
|
||
<img src="merge_dialog.png"
|
||
alt="A dialog with secondary and primary buttons"
|
||
width="706"/>
|
||
</li>
|
||
</list>
|
||
</chapter>
|
||
|
||
|
||
<chapter title="Focused" id="focused">
|
||
<img src="focused_button.png" alt="'Cancel' button in a focused state" width="706"/>
|
||
<p>All buttons can get focus, even on macOS if the
|
||
<control>Full Keyboard Access</control>
|
||
option is disabled in Preferences > Keyboard >
|
||
Shortcuts.
|
||
A focused button behavior varies on macOS/Linux and Windows.
|
||
</p>
|
||
|
||
<tabs>
|
||
<tab title="macOS">
|
||
<list>
|
||
<li>
|
||
<p>A focused button is invoked by pressing
|
||
<shortcut>Space</shortcut>. Focused and default buttons are
|
||
<b>independent</b>,
|
||
so when
|
||
the focus moves from one button to another, the default button does not change.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Make the second most popular button in the dialog focused.It’s recommended to have one default and one focused button, so that most of the actions can be
|
||
triggered using
|
||
the keyboard.
|
||
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>It’s recommended to have one default and one focused button, so that most of the actions can be
|
||
triggered using
|
||
the keyboard.</p>
|
||
<p>
|
||
<format color="369650" style="bold">Correct</format>
|
||
<img src="open_project_dialog.png"
|
||
width="706"
|
||
alt="A dialog with buttons: 'New Window' (focused), 'Cancel', and 'This Window' (default)."
|
||
style="block"/>
|
||
|
||
</p>
|
||
<p>
|
||
<format color="E55765" style="bold">Incorrect</format>
|
||
</p>
|
||
<img
|
||
src="open_project_dialog_incorrect.png"
|
||
alt="A dialog with buttons: 'New Window', 'Cancel', and 'This Window' (default and focused)."
|
||
width="706"/>
|
||
|
||
</li>
|
||
</list>
|
||
</tab>
|
||
<tab title="Windows, Linux">
|
||
<list>
|
||
<li>The focused button is triggered by pressing
|
||
<shortcut>Enter</shortcut>
|
||
or
|
||
<shortcut>Space</shortcut>
|
||
. If a non-default
|
||
button gets focus, the default button is invoked using
|
||
<shortcut>Ctrl+Enter</shortcut>.
|
||
<!-- TODO <img src="open_project_dialog_win.png"
|
||
alt="A Windows dialog with buttons: 'This Window' (default), 'New Window' (focused), and 'Cancel'."
|
||
width="672"/>-->
|
||
<p>On pressing the
|
||
<shortcut>Tab</shortcut>
|
||
key, the
|
||
<control>New Window</control>
|
||
button gets the focus and is triggered with
|
||
<shortcut>Enter</shortcut>
|
||
or
|
||
<shortcut>Space</shortcut>
|
||
.
|
||
The original
|
||
<control>This Window</control>
|
||
button is triggered with
|
||
<shortcut>Ctrl+Enter</shortcut>.</p>
|
||
<p>
|
||
If the focus moves to the control that’s not a button, the original default button is triggered by
|
||
<shortcut>Enter</shortcut>.</p>
|
||
</li>
|
||
</list>
|
||
</tab>
|
||
</tabs>
|
||
</chapter>
|
||
|
||
|
||
<chapter title="Disabled" id="disabled">
|
||
<img src="disabled_button.png"
|
||
alt="Disabled button"
|
||
width="706"/>
|
||
<p>Disable a button if:</p>
|
||
<list>
|
||
<li>It’s an
|
||
<a anchor="apply">Apply</a>
|
||
button and no changes have been made in this dialog.
|
||
</li>
|
||
<li>The control to which the button is related is disabled.</li>
|
||
<li>Not all required fields in the dialog are filled.
|
||
</li>
|
||
</list>
|
||
<p>Other <a anchor="standard-buttons">standard buttons</a> are described below. They can be regular or default buttons.</p>
|
||
</chapter>
|
||
|
||
|
||
<chapter title="Hover" id="hover">
|
||
|
||
<p>On hovering over a button, show a tooltip with the shortcut and the action name if it can be clarified.
|
||
For more details,
|
||
see <a href="context_help.md">Context help</a>.</p>
|
||
<table style="none" column-width="fixed" border="false">
|
||
<tr>
|
||
<td width="378">
|
||
<img src="hovered_button.png" alt="Hovered buttons" width="378"/>
|
||
|
||
</td>
|
||
<td width="378">
|
||
<p>If the action is clear, show the shortcut only.
|
||
</p>
|
||
<p>
|
||
If the action can be clarified, show the action name and the shortcut.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
</chapter>
|
||
<chapter title="Standard buttons" id="standard-buttons">
|
||
<chapter title="Apply" id="apply">
|
||
<table style="none" column-width="fixed" border="false">
|
||
<tr>
|
||
<td width="378">
|
||
<img src="apply.png" alt="Hovered buttons" width="378"/>
|
||
|
||
</td>
|
||
<td width="378">
|
||
<p>Use the <control>Apply</control> button in dialogs with many settings that affect how data is displayed. The
|
||
<control>Apply</control> button
|
||
allows you to
|
||
save and preview the effect of the selected options and continue changing the settings, for example,
|
||
change a scheme in
|
||
settings.</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
<chapter title="Cancel" id="cancel">
|
||
<table style="none" border="false" column-width="fixed">
|
||
<tr>
|
||
<td width="378">
|
||
<img src="cancel.png" alt="Hovered buttons" width="378"/>
|
||
|
||
</td>
|
||
<td width="378">
|
||
<p>The
|
||
<control>Cancel</control>
|
||
button reverts the app to the state before the dialog was invoked, and works as an equivalent to the
|
||
<shortcut>
|
||
Esc
|
||
</shortcut>
|
||
key on Windows and Linux, and
|
||
<shortcut>Esc</shortcut>
|
||
or
|
||
<shortcut>Cmd+Period</shortcut>
|
||
on macOS.
|
||
If a confirmation button is present in a dialog, for example,
|
||
<control>OK</control>
|
||
or
|
||
<control>Save</control>
|
||
, it’s recommended to have a button that cancels the
|
||
dialog, for example,
|
||
<control>Cancel</control>
|
||
,
|
||
<control>Continue Editing</control>
|
||
, and so on.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
</chapter>
|
||
|
||
<chapter title="Close">
|
||
<table style="none" column-width="fixed" border="false">
|
||
<tr>
|
||
<td width="378">
|
||
<img src="close.png" alt="Hovered buttons" width="378"/>
|
||
|
||
</td>
|
||
<td width="378">
|
||
<p>Use the
|
||
<control>Close</control>
|
||
label only if nothing can be changed in the dialog and there is no confirmation button, for example, in
|
||
the
|
||
<ui-path>Help | My Productivity</ui-path>
|
||
dialog.
|
||
In all other cases, use the
|
||
<control>Cancel</control>
|
||
button.
|
||
</p>
|
||
<p>Do not
|
||
add an icon to the button. The main purpose of an icon is to quickly find a familiar action in a packed
|
||
toolbar or menu. Usually, no more than 3 buttons are placed nearby, their labels can be scanned quickly,
|
||
and icons are not required.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
<chapter title="Help" id="help">
|
||
<table style="none" border="false" column-width="fixed">
|
||
<tr>
|
||
<td width="378">
|
||
<img src="help.png" alt="Hovered buttons" width="378"/>
|
||
|
||
</td>
|
||
<td width="378">
|
||
<p>The help button appears in the bottom-left corner of a dialog and shows help in a tooltip on hover, or
|
||
opens a help
|
||
dialog when clicking it. For more details, see <a href="context_help.md">Context help</a>.</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</chapter>
|
||
</chapter>
|
||
<!-- <chapter title="Sizes and placement" id="sizes-and-placement">
|
||
<p>The button width accommodates the length of the label plus standard indents 14px, but not less than the
|
||
72px.</p>
|
||
<img src="button_sizes.png" alt="Example buttons with incorrect and correct sizes and indents" width="491"/>
|
||
<p>The button height is fixed, so the label is always a single line.</p>
|
||
<p>To lay out the button that depends on other control, e.g., input field, follow the rules
|
||
for <a href="layout.md" anchor="dependent-controls">dependent controls</a>. Otherwise, follow
|
||
the rules for <a href="layout.md" anchor="independent-controls">independent controls</a>.</p>
|
||
<!–
|
||
<table>
|
||
<col width="140px">
|
||
<col width="200px">
|
||
<col width="300px">
|
||
<tr>
|
||
<td> </td>
|
||
<td> macOS, Darcula </td>
|
||
<td> Windows </td>
|
||
</tr>
|
||
<tr>
|
||
<td> <p style="color: #999999; margin-top: 10px;"> Several buttons </p></td>
|
||
<td> <img src="button_size_1.png" style="margin: -5px 0 0 0"></td>
|
||
<td> <img src="button_size_2.png" style="margin: -5px 0 0 0"></td>
|
||
</tr>
|
||
</table>
|
||
<table>
|
||
<col width="140px">
|
||
<tr>
|
||
<td> <p style="color: #999999; margin-top: 10px;"> Button on the right </p></td>
|
||
<td> <img src="button_size_3.png" style="margin: -5px 0 0 0"></td>
|
||
</tr>
|
||
<tr>
|
||
<td> </td>
|
||
<td> <img src="button_size_4.png" style="margin: -5px 0 0 0"></td>
|
||
</tr>
|
||
<tr>
|
||
<td> </td>
|
||
</tr>
|
||
<tr>
|
||
<td> <p style="color: #999999; margin-top: -5px;"> Button under </p></td>
|
||
<td> <img src="button_size_5.png" style="margin: -5px 0 0 0"></td>
|
||
</tr>
|
||
</table>
|
||
–>
|
||
<!–
|
||
### Colors
|
||
|
||
<table>
|
||
<col width="50%">
|
||
<th> Regular button </td>
|
||
<tr>
|
||
<td> Text </td>
|
||
<td> Button.foreground </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Background </td>
|
||
<td> Button.startBackground<br/>
|
||
Button.endBackground
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td> Border </td>
|
||
<td> Button.startBorderColor <br/>
|
||
Button.endBorderColor
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td> Inner focused border </td>
|
||
<td> Button.focusedBorderColor </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Outer wider focus border </td>
|
||
<td> Component.focusColor </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Shadow </td>
|
||
<td> Button.shadowColor </td>
|
||
</tr>
|
||
<th> Default button </td>
|
||
<tr>
|
||
<td> Text </td>
|
||
<td> Button.default.foreground </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Background </td>
|
||
<td> Button.default.startBackground<br/>
|
||
Button.default.endBackground
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td> Border </td>
|
||
<td> Button.default.startBorderColor <br/>
|
||
Button.default.endBorderColor
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td> Inner focused border </td>
|
||
<td> Button.default.focusedBorderColor </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Outer wider focus border </td>
|
||
<td> IntelliJ: Component.focusColor <br/>
|
||
Darcula: Button.default.focusColor</td>
|
||
</tr>
|
||
<tr>
|
||
<td> Shadow </td>
|
||
<td> Button.default.shadowColor </td>
|
||
</tr>
|
||
<th> Disabled button </td>
|
||
<tr>
|
||
<td> Text </td>
|
||
<td> Button.disabledText </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Background </td>
|
||
<td> Button.background (same as Panel.background) </td>
|
||
</tr>
|
||
<tr>
|
||
<td> Border </td>
|
||
<td> Button.disabledBorderColor </td>
|
||
</tr>
|
||
</table>
|
||
–>
|
||
</chapter>-->
|
||
|
||
</topic>
|