Commit a14fe688 authored by Carl Schwan's avatar Carl Schwan 🚴
Browse files

Improve HIG components

parent a4ccb4db
......@@ -8,53 +8,33 @@ groups:
key: formating
- name: "Navigation"
key: navigation
- name: "Packaging"
key: "packaging"
- name: "Application Extensions"
key: "applications"
- name: "User Assistance"
key: assistance
description: >
User Assistance guidance considers interface elements that inform users
of the application's activity and status, as well as elements dedicated
to user education. This includes online help, error alerts, and status alerts.
subgroups:
- name: "Notifications"
key: notifications
- name: "Help"
key: help
- name: "Information"
key: information
- name: "Editing and Manipulation"
key: editing
description: >
Editing and Manipulation considers the behaviors that result in persistent
changes to user’s stored information.
subgroups:
- name: Selection
key: selection
- name: Unconstrained Input
key: unconstrined
- name: Constrained Input
key: constrained
---
Formating
---------
- `formating/groupbox`
- `formating/splitter`
Navigation
----------
- `navigation/actionbutton`
- `navigation/commandlink`
- `navigation/contextdrawer`
- `navigation/contextmenu`
- `navigation/dialog`
- `navigation/globaldrawer`
- `navigation/menubar`
- `navigation/pushbutton`
- `navigation/tab`
- `navigation/toolbar`
- `navigation/scrim`
User Assistance
---------------
User Assistance guidance considers interface elements that inform users
of the application's activity and status, as well as elements dedicated
to user education. This includes online help, error alerts, and status
alerts.
### Notification
- `assistance/emblem`
- `assistance/inline`
- `assistance/message`
- `assistance/progress`
- `assistance/statusbar`
### Help
- `assistance/tooltip`
Editing and Manipulation
------------------------
......
---
title: About Application
group: assistance
subgroup: information
weight: 10
---
=================
Every application should have a view that contains basic information
about the application. This includes a short description of the
......@@ -17,30 +19,32 @@ QML/Kirigami
------------
Kirigami apps should use the
`Kirigami.AboutPage <AboutPage>`{.interpreted-text role="kirigamiapi"}
component. It consumes the data set by `KAboutData`{.interpreted-text
role="kcoreaddonsapi"}. It should cover all existing pages and must have
[Kirigami.AboutPage](docs:kirigami2;AboutPage)
component. It consumes the data set by [KAboutData](docs:kcoreaddons;KAboutData).
It should cover all existing pages and must have
a way to close it again. This can be achieved by using the
`pageStack.layers <PageRow>`{.interpreted-text role="kirigamiapi"}
[pageStack.layers](docs:kirigami2;PageRow)
mechanism. It should not be possible to open the AboutPage more than
once. :
Component {
id: aboutPage
Kirigami.AboutPage {
aboutData: theAboutData
}
```qml
Component {
id: aboutPage
Kirigami.AboutPage {
aboutData: theAboutData
}
Kirigami.Action {
text: i18n("About MyApplication")
iconName: "help-about"
onTriggered: {
if (window.pageStack.layers.depth < 2) {
window.pageStack.layers.push(aboutPage)
}
}
Kirigami.Action {
text: i18n("About MyApplication")
iconName: "help-about"
onTriggered: {
if (window.pageStack.layers.depth < 2) {
window.pageStack.layers.push(aboutPage)
}
}
}
```
Usage example
......
---
title: Emblem
group: assistance
subgroup: notifications
weight: 1
---
======
Purpose
-------
......@@ -27,8 +29,8 @@ Guidelines
elements in a file manager, system tray, task manager, dock, image
view, etc. Emblems should not be applied to textual content.
- Use emblems to display that an icon or image has some unusual status
associated with it, or that there are unread notifications. Don\'t
use emblems to display an element\'s normal, common, or typical
associated with it, or that there are unread notifications. Don't
use emblems to display an element's normal, common, or typical
status. For example, an emblem could indicate that a folder is
read-only or is a symlink, or that a disk is unmounted or encrypted.
An emblem should not be used to indicate that a folder is read-write
......@@ -38,7 +40,7 @@ Guidelines
placed in other corners in a clockwise order.
- Emblems that indicate unread notifications should be located in the
top-right corner.
- Use the minimum number of emblems and don\'t overwhelm the icon
- Use the minimum number of emblems and don't overwhelm the icon
itself. Three is usually too many.
Appearance
......@@ -46,7 +48,7 @@ Appearance
An emblem that indicates unread notifications should take the form of a
light-colored number inside a blue circle. The circle can become
\"pill-shaped\" if the number is very large.
"pill-shaped" if the number is very large.
![Notification emblem](/hig/emblem-notification-small.png)
......@@ -54,4 +56,4 @@ light-colored number inside a blue circle. The circle can become
number](/hig/emblem-notification-large.png)
For symbolic icon emblems, see
`/style/icons/monochrome/emblem`.
[Emblem icons](/hig/style/icons/monochrome/emblem).
---
title: Inline Message
group: assistance
subgroup: notifications
weight: 2
---
==============
::: {.container .intend}
:::
Purpose
-------
......@@ -28,27 +27,23 @@ Guidelines
- Use inline messages in cases of non-critical problems that user can
solve.
- Use `negative feedback`{.interpreted-text role="iconred"} (aka
error) as a secondary indicator of failure, e.g. if a
transaction was not completed successfully.
- Use negative feedback (aka error) as a secondary indicator of
failure, e.g. if a transaction was not completed successfully.
- Show the information on a warning level in case of relevant
information that does not concern the current workflow, e.g.
No Internet connection available.
- Use `positive feedback`{.interpreted-text role="noblefir"} to
notify about user-initiated processes, e.g. to indicate
completion of background tasks.
- Use `opportunistic interaction`{.interpreted-text
role="plasmablue"} (aka notification) to acknowledge the user
about options that he or she might be interested in, e.g.
\"Remember password?\"
- Use positive feedback to notify about user-initiated processes,
e.g. to indicate completion of background tasks.
- Use opportunistic interaction (aka notification) to acknowledge
the user about options that he or she might be interested in, e.g.
"Remember password?"
- Display the information immediately.
- When users dismiss the inline message, don\'t display any other UI
- When users dismiss the inline message, don't display any other UI
or start any other side effect.
- Don\'t add controls to the inline message other than action buttons
- Don't add controls to the inline message other than action buttons
for opportunistic interaction.
- Consider to show a
`notification </platform/notification>`{.interpreted-text
role="doc"} if information does not concern the current workflow.
- Consider to show a [notification](/hig/platform/notification)
if information does not concern the current workflow.
Is this the right control? / Behavior
-------------------------------------
......@@ -59,7 +54,7 @@ The inline message should be used as a secondary indicator of failure:
the first indicator is for instance that the action the user expected to
happen did not happen.
Example: User fills a form, clicks \"Submit\".
Example: User fills a form, clicks "Submit".
- Expected feedback: form closes
- First indicator of failure: form stays there
......@@ -71,12 +66,12 @@ placed close to its context. In the case of a form, it should appear on
top of the form entries.
An inline message should get inserted in the existing layout. Space
should not be reserved for it, otherwise it becomes \"dead space\",
should not be reserved for it, otherwise it becomes "dead space",
ignored by the user. An inline message should also not appear as an
overlay to prevent blocking access to elements the user needs to
interact with to fix the failure.
When used for negative feedback, don\'t offer a close button. The
When used for negative feedback, don't offer a close button. The
message panel only closes when the problem it informs about (e.g. the
error) is fixed.
......@@ -88,7 +83,7 @@ results of an action.
Examples of acceptable uses:
- Confirm success of \"critical\" transactions
- Confirm success of "critical" transactions
- Indicate completion of background tasks
Example of wrong uses:
......@@ -107,7 +102,7 @@ Example use cases:
- A browser can propose remembering a recently entered password
- A music collection can propose ripping a CD which just got inserted
- A chat application may notify the user a \"special friend\" just
- A chat application may notify the user a "special friend" just
connected
Appearance
......@@ -115,7 +110,7 @@ Appearance
A basic inline messages consists of an icon and text. It can contain an
optional close button and
`buttons <../navigation/pushbutton>`.
[buttons](../../navigation/pushbutton).
![Inline message with a custom icon and a close
button.](/hig/Message1.png)
......@@ -132,14 +127,10 @@ Code
### Kirigami
> - `Kirigami: InlineMessage <InlineMessage>`{.interpreted-text
> role="kirigamiapi"}
>
> ::: {.literalinclude language="qml"}
> /../../examples/kirigami/InlineMessage.qml
> :::
- Kirigami: [InlineMessage](docs:kirigami2;InlineMessage)
{{< readfile file="/content/hig/examples/kirigami/InlineMessage.qml" highlight="qml" >}}
### Qt Widgets
> - `QtWidgets: KMessageWidget <KMessageWidget>`{.interpreted-text
> role="kwidgetsaddonsapi"}
- QtWidgets: [KMessageWidget](docs:kwidgetsaddons;KMessageWidget)
---
title: Modal Message Dialog
group: assistance
subgroup: notifications
weight: 3
---
====================
Purpose
-------
......@@ -9,7 +11,7 @@ Purpose
If the processing has reached an unexpected or potentially dangerous
condition, the user must make a decision. The correct presentation for
this kind of disruptive question is a modal message dialog: a secondary
window that interrupts user\'s current activity and blocks interaction
window that interrupts user's current activity and blocks interaction
until the user decides how to proceed.
Use modal message dialogs sparingly. Users will learn to reflexively
......@@ -32,7 +34,7 @@ Guidelines
### Behavior
- Dialogs should be modal, and block user interaction with the rest of
the application until a choice has been made. Don\'t block the
the application until a choice has been made. Don't block the
entire user interface for the whole system, though.
- Create specific, actionable, user-centered error messages. Users
should either perform an action or change their behavior as a
......@@ -49,12 +51,12 @@ Guidelines
how to solve the problem.
- Phrase your messages clearly, in non-technical terms. Avoid obscure
error codes.
- Avoid wording that terrifies the user (\"killed\", \"fatal\",
\"illegal\") or blames them for their behavior. Be polite.
- Avoid wording that terrifies the user ("killed", "fatal",
"illegal") or blames them for their behavior. Be polite.
- Buttons should clearly indicate the available options using action
verbs (\"Delete\", \"Rename\", \"Close\", \"Accept\", etc.) and
verbs ("Delete", "Rename", "Close", "Accept", etc.) and
allow the user to make an informed decision even if they have not
read the message text. Never use \"Yes\" and \"No\" as button
read the message text. Never use "Yes" and "No" as button
titles.
- Follow the general guidelines for
`dialogs <../navigation/dialog>`.
[dialogs](../../navigation/dialog).
---
title: Progress Indicator
group: assistance
subgroup: notifications
---
==================
Purpose
-------
If a foreground task lasts longer than expected or when calculation
takes some time, the system should provide some feedback on the task\'s
takes some time, the system should provide some feedback on the task's
progress. Users are aware of response times of over one second and
shorter. Consequently, operations that take two seconds or longer to
complete should be considered to be lengthy and need of some type of
......@@ -37,15 +38,15 @@ Guidelines
- Clearly indicate real progress -- and lack of progress. The progress
bar must advance if progress is being made and not advance if no
progress is being made.
- Show progress by steps in respect to context. For instance, don\'t
- Show progress by steps in respect to context. For instance, don't
inform about the number of files that have been downloaded but
rather the total size in bytes.
- Provide additional progress information, but only if users can do
something with it, e.g. cancel the processing, relate an error to a
particular processing step, etc. Don\'t provide unnecessary details.
- Don\'t use progress bars if the time needed to complete the task
particular processing step, etc. Don't provide unnecessary details.
- Don't use progress bars if the time needed to complete the task
cannot be estimated, as well not per waiting bar (aka marquee
style). In that case, if the task will likely take only a few
seconds, use a spinner. If it takes longer, move the task to the
background.
- Don\'t combine a progress bar with a busy pointer.
- Don't combine a progress bar with a busy pointer.
---
title: Status Bars
group: assistance
subgroup: notifications
---
===========
Purpose
-------
A status bar is an area at the bottom of a primary window that displays
information about the current window\'s state, background tasks, or
information about the current window's state, background tasks, or
other contextual information.
KDE applications should not use a conventional status bar by default in
......@@ -20,24 +21,21 @@ Guidelines
- Omit the status bar in the main window to maximize vertical space
for content.
- Don\'t show meaningless information like \'Ready\'.
- Use a floating panel or `tooltips <tooltip>`{.interpreted-text
role="doc"} for short-term status information like full length
text of links.
- Don't show meaningless information like 'Ready'.
- Use a floating panel or [tooltips](../tooltip) for short-term
status information like full length text of links.
- Move controls to the toolbar.
- If you cannot find good replacements for status bar functions,
please ask the usability team for support.
- Don\'t display a status bar in secondary or internal windows.
- Don't display a status bar in secondary or internal windows.
- If a status bar is really necessary in your application consider to
use a `toolbar <../navigation/toolbar>`{.interpreted-text
role="doc"} with all customization features.
use a [toolbar](../../navigation/toolbar) with all customization features.
### Behavior
- Don\'t use the status bars or any kind of replacement for crucial
- Don't use the status bars or any kind of replacement for crucial
information. Users should never have to know what is in the status
bar.
- Don\'t use the status bar or any kind of replacement to display
advisory messages in place of standard
`tooltips <tooltip>`.
- Keep the status information plain; e.g. don\'t add icons.
- Don't use the status bar or any kind of replacement to display
advisory messages in place of standard [tooltips](../tooltip).
- Keep the status information plain; e.g. don't add icons.
---
title: Tooltip
group: assistance
subgroup: help
---
=======
Purpose
-------
......@@ -32,9 +33,9 @@ Guidelines
values.
- Tooltips for a disabled control should include information regarding
the disabled state of the control. Include this information even if
the control is enabled. For instance: \'Go to the next unread
message\' in the case of enabled controls and \'Go to the next
unread message (No unread messages left)\' when disabled.
the control is enabled. For instance: 'Go to the next unread
message' in the case of enabled controls and 'Go to the next
unread message (No unread messages left)' when disabled.
- Consider adding small informational buttons for touch screen use.
### Appearance
......@@ -47,7 +48,7 @@ Guidelines
- supplemental: important information should be communicated using
self-explanatory control labels or in-place supplemental text
- static: tips should not change from one instance to the next
- Don\'t use icons and formattings for tips of unlabeled controls.
- Don't use icons and formattings for tips of unlabeled controls.
- Use tool-tips with icons and formatting
- if tips describe comprehensive functions,
- when content is lengthy and formatting improves readability
......@@ -58,11 +59,9 @@ Code
### Kirigami
> - `Kirigami: ApplicationWindow <ApplicationWindow>`{.interpreted-text
> role="kirigamiapi"}
> - [QML:
> MenuBar](https://doc.qt.io/qt-5/qml-qtquick-controls-menubar.html)
- Kirigami: [ApplicationWindow](docs:kirigami2;ApplicationWindow)
- QML: [MenuBar](https://doc.qt.io/qt-5/qml-qtquick-controls-menubar.html)
### Plasma components
> - `Plasma ToolTip <ToolTip>`{.interpreted-text role="plasmaapi"}
- [Plasma ToolTip](docs:plasma;ToolTip)
---
title: Card
group: editing
subgroup: selection
weight: 1
---
====
Purpose
-------
......@@ -15,15 +17,15 @@ Guidelines
### Is this the right control?
- Don\'t use a card to display long texts.
- Don't use a card to display long texts.
- Cards can be used to display items with different content types,
e.g. images text, videos.
- Don\'t use cards for content that should be directly comparable, use
- Don't use cards for content that should be directly comparable, use
a table view or a grid view for that.
- If you would show more than 20 cards at a time, or if the user would
have to scroll for more than three screen heights to see all of
them, consider using a list instead.
- Don\'t use cards with text input elements.
- Don't use cards with text input elements.
- If your cards consist of just one image a grid with overlay actions
might be more suitable.
......@@ -33,15 +35,13 @@ Guidelines
Cards are responsive. They resize to fit into the available space.
```{=html}
<video autoplay controls src="https://cdn.kde.org/hig/video/20180620-1/CardLayout1.webm" loop="true" playsinline="true" width="536" onended="this.play()" class="border"></video>
```
It is recommended that you adjust the number of cards displayed next to
each other depending on the available space.
```{=html}
<video autoplay controls src="https://cdn.kde.org/hig/video/20180620-1/CardLayout2.webm" loop="true" playsinline="true" width="536" onended="this.play()" class="border"></video>
```
#### Mobile
- Cards only resize to orientation changes.
......@@ -52,7 +52,7 @@ each other depending on the available space.
It is recomended that you use the standard card layout for consistency,
but cards can have a lot of different layouts.
> ![](/hig/Card6.qml.png)
![](/hig/Card6.qml.png)
The only common requirement is the container around it. While cards can
have a lot of different layouts, each should focus only on one bit of
......@@ -80,14 +80,9 @@ Code
### Kirigami
> - `Kirigami: Card <Card>`{.interpreted-text role="kirigamiapi"}
> - `Kirigami: CardsGridView <CardsGridView>`{.interpreted-text
> role="kirigamiapi"}
> - `Kirigami: CardsLayout <CardsLayout>`{.interpreted-text
> role="kirigamiapi"}
> - `Kirigami: CardsListView <CardsListView>`{.interpreted-text
> role="kirigamiapi"}
::: {.literalinclude language="qml"}
/../../examples/kirigami/Card.qml
:::
- Kirigami: [Card](docs:kirigami2;Card)
- Kirigami: [CardsGridView](docs:kirigami2;CardsGridView)
- Kirigami: [CardsLayout](docs:kirigami2;CardsLayout)
- Kirigami: [CardsListView](docs:kirigami2;CardsListView)
{{< readfile file="/content/hig/examples/kirigami/Card.qml" highlight="qml" >}}
---
title: Checkbox
weight: 2
group: editing
subgroup: selection
---
========
Purpose
-------
......@@ -9,8 +11,8 @@ Purpose
A checkbox is a control that permits the user to make multiple
selections from a number of options. Checkboxes are used to toggle an
option on or off, or to select or deselect an item. Users make a
decision between two clearly opposite choices, e.g. \'on vs. off\',
\'apply vs. don\'t apply\', \'show vs. hide\'.
decision between two clearly opposite choices, e.g. 'on vs. off',
'apply vs. don't apply', 'show vs. hide'.
Guidelines
----------
......@@ -19,59 +21,45 @@ Guidelines
- Use checkboxes for non-exclusive options that have clear
alternatives. Mutually exclusive options should use a set of
`radio buttons <radiobutton>` or a
`combo box <combobox>`.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t use a checkbox if
the opposite is ambiguous.](/hig/Ambiguous_Opposite_Bad.qml.png){.border
.dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Use two radio buttons to
remove the need to guess.](/hig/Ambiguous_Opposite_Good.qml.png){.border
.do}
:::
:::
[radio buttons](../radiobutton) or a [combo box](../combobox).
{{< compare >}}
{{< dont src="/hig/Ambiguous_Opposite_Bad.qml.png" >}}
Don't use a checkbox if the opposite is ambiguous.
{{< /dont >}}
{{< do src="/hig/Ambiguous_Opposite_Good.qml.png" >}}
Use two radio buttons to remove the need to guess.
{{< /do >}}
{{< /compare >}}
- For more than five options, use either a
`list view <list>` or the
`dual-list pattern </patterns/content/duallist>`{.interpreted-text
role="doc"} in case of multiple selections.
- Don\'t use the selection to perform commands.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t use the selection to
perform commands.](/hig/No_Command_2_Bad.qml.png){.border .dont}
:::