button control
Qt Quick Control provides a series of button-like controls.
| Abstract base type that provides common functionality for buttons |
|
| Buttons you can click to execute commands or answer questions |
|
| Check button that can be turned on or off |
|
| Check button triggered when pressed long enough |
|
| Dedicated radio button that can be turned on or off |
|
| A button control with rounded corners that can be clicked by the user. |
|
| Button that can be turned on or off |
|
| Buttons that look like a toolbar |
Each type of button has its specific use case. The following sections provide guidance on selecting the appropriate type of button based on your use case.
button control
Is a clickable control that initiates an action or opens or closes a pop-up window. Buttons usually have text labels but can also contain icons.
Buttons are a very appropriate control when an action needs to be performed in a pop-up window or dialog box. The most common examples are Apply, Cancel, Save, Close, and Help.
suggestion:
- The button's text should be a predicate that describes the action, or a noun that matches the title of the popup that will open.
- Don't use buttons to set state. More suitable for that.
- Use the default font unless your UI guidelines specify otherwise.
- If the text is localized, consider the impact that longer text will have on the layout.
See also and
checkbox control
Used to build a multi-select option list. Any number of options may be selected, including none, but the options should not be mutually exclusive.
Use a single option to represent a yes/no choice, such as when you must accept a terms of service agreement in a form.
For single yes/no options, switches can also be used. If the selection involves an option, it is better to use . If it involves an action to be performed, it is recommended to toggle it.
When options can be grouped, partial selection can be used to represent the entire group. Use this checkbox when the user selects some (but not all) children in the group.
The three available check statuses are: Checked, Partially Checked, and Unchecked.
Checkable options are usually listed vertically.
suggestion:
- The checkbox label should be a statement with a check mark that is true, and a statement that lacks a check mark that is false.
- Checkbox labels should not contain negative statements.
- Use the default font unless UI guidelines specify otherwise.
- If the text is localized, consider the impact that longer text will have on the layout.
See
Delay button control
is a button that contains a delay before triggering the action. This delay prevents accidental presses.
suggestion:
- Used in touch user interfaces.
- Used for operations that must be triggered with care.
See also and
radio button control
Used to select only one option from a set of options. Selecting an option automatically deselects the previously selected option.
If you only have two mutually exclusive options, combine them into a checkbox or switch.
suggestion:
- Limit label text to one line.
- Make sure sensible default options are selected.
- List options vertically.
- If the text is localized, consider the impact that longer text will have on the layout.
- Use the default font unless UI guidelines specify otherwise.
- Like, don't make the list too big.
- To avoid confusion, do not place two sets of radio buttons side by side.
Specific uses of button controls:
An abstract base type that provides common functionality for buttons. More. . .
| Import Statement: | import QtQuick.Controls 2.15 |
| Since: | Qt 5.7 |
| Inherits: | |
| Inherited By: | Button, CheckBox, DelayButton, ItemDelegate, MenuBarItem, MenuItem, RadioButton, Switch, and TabButton |
performance
- action : Action
- autoExclusive : bool
- autoRepeat : bool
- autoRepeatDelay : int
- autoRepeatInterval : int
- checkable : bool
- checked : bool
- display : enumeration
- down : bool
- icon
- icon.cache : bool
- icon.color : color
- icon.height : int
- icon.name : string
- icon.source : url
- icon.width : int
- implicitIndicatorHeight : real
- implicitIndicatorWidth : real
- indicator : Item
- pressX : real
- pressY : real
- pressed : bool
- text : string
Signal
- canceled()
- clicked()
- doubleClicked()
- pressAndHold()
- pressed()
- released()
- toggled()
method
- void toggle()
Detailed description
Abstract buttons provide an interface for controls with button-like behavior; for example, buttons and checkable controls such as radio buttons and check boxes. As an abstract control, it has no delegate implementations, leaving them to the types derived from it.
See also and.
properties document
| action : Action |
This property holds the button action.
This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).
See also .
| autoExclusive : bool |
This property holds whether automatic exclusivity is enabled.
If automatic exclusivity is enabled, checkable buttons that belong to the same parent behave as if they are the same . Only one button can be checked at any time; selecting another button automatically unchecks the previously selected button.
Note: This property has no effect on the button it belongs to.
And it is automatically exclusive by default.
| autoRepeat : bool |
This property holds whether the button is repeated or not, and emits a signal when the button is pressed and held.
If this property is set to , no signal will be emitted.true
The default value is .false
The initial delay and repeat interval are defined by and in milliseconds.
| autoRepeatDelay : int |
This property holds the initial delay in milliseconds for auto-repeat. The default value is ms.300
This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).
See also and.
| autoRepeatInterval : int |
This property holds the auto-repeat interval in milliseconds. The default value is ms.100
This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).
See also and.
| checkable : bool |
This property holds whether the button is checkable.
Toggles between checked (on) and unchecked (off) when the user clicks the checkable button or presses the spacebar while the button has active focus.
Set to force this property to be.truetrue
The default value is .false
See also .
| checked : bool |
This property holds whether the button is selected or not.
See also .
| display : enumeration |
This property determines how and appears in the button.
| show | result |
|---|---|
AbstractButton.IconOnly |
|
AbstractButton.TextOnly |
|
AbstractButton.TextBesideIcon |
|
AbstractButton.TextUnderIcon |
|
This property was introduced in QtQuick.Controls 2.3 (Qt 5.10).
See also and.
| down : bool |
This property holds whether the button is visually closed.
The value this property will follow unless explicitly set. To return to the default value, set this property to .undefined
See also .
This property group has been added to . Controls 2.3.
| name | describe |
|---|---|
| name | This property holds the name of the icon to use. Icons will be loaded from the platform theme. If the icon is found in the theme, it will always be used; even if it is also set. If this icon is not found, it will be used instead. For more information about theme icons, see . |
| source | This property holds the name of the icon to use. The icon will load as a regular image. If set to and referencing a valid theme icon, it will always be used instead of this property. |
| width | This property holds the width of the icon. The icon will never be wider than this value, but will shrink when necessary. |
| high | This property holds the height of the icon. The icon's height will never exceed this value, but will shrink when necessary. |
| color | This property holds the color of the icon. 图标使用指定的颜色着色，除非颜色设置为 。 |
| 缓存 | 此属性指定是否应缓存图标。 默认值为 true。 此属性已在 中介绍。控件 2.13. |
另请参见 、 和 。
| [read-only]implicitIndicatorHeight : real |
此属性保存隐式指示器高度。
该值等于 。indicator ? indicator.implicitHeight : 0
这通常与 和 一起使用来计算 。
此属性在 QtQuick.Controls 2.5 （Qt 5.12） 中引入。
另请参阅。
| [read-only]implicitIndicatorWidth : real |
此属性保存隐式指示器宽度。
该值等于 。indicator ? indicator.implicitWidth : 0
这通常与 和 一起使用来计算 。
此属性在 QtQuick.Controls 2.5 （Qt 5.12） 中引入。
另请参阅。
| indicator : Item |
此属性保存指示器项。
| [read-only]pressX : real |
此属性保存上次按下的 x 坐标。
注意： 该值在触摸移动时更新，但在触摸释放后保持不变。
此属性在 QtQuick.Controls 2.4 （Qt 5.11） 中引入。
另请参阅。
| [read-only]pressY : real |
此属性保存上次按下的 y 坐标。
注意： 该值在触摸移动时更新，但在触摸释放后保持不变。
此属性在 QtQuick.Controls 2.4 （Qt 5.11） 中引入。
另请参阅。
| [read-only]pressed : bool |
此属性保存按钮是否被物理按下。按钮可以通过触摸或按键事件按下。
另请参阅。
| text : string |
This property holds a textual description of the button.
Note: The text is used for accessibility purposes, so it makes sense to set a textual description even if the content item is an image.
See also icon, display, and contentItem.
signal documentation
| canceled() |
This signal is emitted when the button loses mouse grip when pressed, or when it would emit a signal but the mouse cursor is not within the button.
NOTE: The corresponding handler is.onCanceled
| clicked() |
This signal is emitted when the user interactively clicks a button via touch, mouse, or keyboard.
NOTE: The corresponding handler is.onClicked
| doubleClicked() |
This signal is emitted when the user interactively double-clicks the button via touch or mouse.
NOTE: The corresponding handler is.onDoubleClicked
| pressAndHold() |
This signal is emitted when the user interactively presses and holds the button via touch or mouse. It will not be emitted when enabled.
NOTE: The corresponding handler is.onPressAndHold
| pressed() |
This signal is emitted when the user interactively presses a button via touch, mouse, or keyboard.
NOTE: The corresponding handler is.onPressed
| released() |
This signal is emitted when the user releases the button interactively via touch, mouse, or keyboard.
NOTE: The corresponding handler is.onReleased
| toggled() |
This signal is emitted when the user interactively toggles an inspectable button via touch, mouse, or keyboard.
NOTE: The corresponding handler is.onToggled
This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).