Getting input

Controls

KDE apps mostly use standard input controls such as buttons, menus, checkboxes, text fields, and sliders. There are some rules to keep in mind beyond the basics:

• Use a flat ToolButton on a toolbar in a header or footer position, or in a Contextual Toolview—anywhere users expect to encounter UI elements that look like toolbars.
• Use a regular raised Button in the main content area, including settings pages and when overlaid on top of content items including list and grid items. In these contexts, the raised outline helps them to be be visibly recognizable as buttons.
• Use a RoundButton for covering up part of the content area not already covered by any kind of opaque or semi-transparent background. These kinds of buttons never have text, so choose an icon that conveys the button's action perfectly.
• Use a Switch for “Instant apply” settings or state switchers that take effect immediately. Otherwise use a CheckBox.
• Use RadioButtons for sets of 3 or fewer mutually-exclusive options with short text where space is plentiful. If there will be 10 or fewer items, use a ComboBox. Otherwise use a list view. Arrange items in a logical order; if none exists, alphabetical is a good default.
• Use a Slider for bounded input where fast manipulation is more important than precision. Use a SpinBox for precise control of numerical values. If both numerical precision and speed of interaction are important, then use a Slider with a SpinBox trailing it.

Text input

Only ask for input using a text field when it's not possible to use a control that automatically validates input. For this reason, you must validate the input text yourself.

When the current text is invalid, indicate this using a Kirigami.InlineMessage and disable the ability to confirm or send the input.

If possible, implement an auto-complete feature to help the user enter valid input.

If possible, use one of the pre-made Kirigami text fields:

• Use Kirigami.ActionTextField when you need to add inline actions in the trailing position (e.g. a clear button).
• Use Kirigami.SearchField to implement a search field.
• Use Kirigami.PasswordField to display password prompts.

Dialogs

Only show a dialog when the normal workflow must be interrupted for one of two reasons:

• When the user must make an immediate decision before the app can continue working normally.
• To display progress information about a task that must complete before the app can continue working normally.

For all other purposes, don't use a dialog; request input or display information inline in a non-modal fashion.

For opening and saving files, use QtQuick.Dialogs.FileDialog with the fileMode set appropriately. Don't implement a custom file-choosing UI.

For getting other kinds of input, use one of the Kirigami Dialog types:

• Use Kirigami.PromptDialog for a “do it/don't do it” type of choice.
• Use Kirigami.PromptDialog with a QtQuick.Controls.TextField inside it to get text input from the user.
• Use Kirigami.MenuDialog to let the user choose from among a set of actions.

Don't display more than one dialog at a time. Never use a dialog to create more dialogs.

Signaling interactivity

Standard Breeze styling for controls signals interactivity primary through hover effects—typically by changing the background or outline color. Keep these guidelines in mind:

• Use standard controls as much as possible to automatically inherit this style of visual interactivity.
• When custom controls must be used, prefer to override the contentItem property of standard controls so that only the content is custom, and the interactivity and styling of the background effect are preserved.
• If even that is not possible, re-implement interactivity signaling using hover effects.
• Only use the pointing finger cursor to signal interactivity for a clickable URL.
• Only use underlined web-style links for clickable URLs, never for internal navigation within your app.