Commit 8fdf3bd0 authored by Carl Schwan's avatar Carl Schwan 🚴
Browse files

Finish fixing component editing

parent a14fe688
......@@ -25,42 +25,15 @@ groups:
key: editing
description: >
Editing and Manipulation considers the behaviors that result in persistent
changes to user’s stored information.
changes to user’s stored information. Behaviors in this layer can often be
recognized by the following traits: they result in persistent, stored changes;
they require an implicit or explicit save operation; and they typically require
validation of the input data.
subgroups:
- name: Selection
key: selection
- name: Unconstrained Input
key: unconstrined
key: unconstrained
- name: Constrained Input
key: constrained
---
Editing and Manipulation
------------------------
Editing and Manipulation considers the behaviors that result in
persistent changes to user's stored information.
### Selection
- `editing/card`
- `editing/checkbox`
- `editing/combobox`
- `editing/dropdown`
- `editing/grid`
- `editing/list`
- `editing/radiobutton`
- `editing/togglebutton`
- `editing/tree`
### Unconstrained Input
- `editing/lineedit`
- `editing/tableview`
- `editing/textedit`
### Constrained Input
- `editing/date`
- `editing/slider`
- `editing/spinbox`
---
title: User Assistance
---
===============
::: {.toctree maxdepth="1" titlesonly="" hidden=""}
emblem inline message progress statusbar tooltip aboutview
:::
User assistance
---------------
......@@ -14,19 +9,3 @@ 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
- `emblem`
- `inline`
- `message`
- `progress`
- `statusbar`
### Help
- `tooltip`
### Information
- `aboutview`
---
title: Editing and Manipulation
---
========================
::: {.toctree maxdepth="1" titlesonly="" hidden=""}
card checkbox combobox date dropdown grid lineedit list radiobutton
slider spinbox tableview textedit togglebutton tree
:::
Editing and Manipulation considers the behaviors that result in
persistent changes to user's stored information. Behaviors in this layer
can often be recognized by the following traits: they result in
persistent, stored changes; they require an implicit or explicit save
operation; and they typically require validation of the input data.
Selection
---------
- `card`
- `checkbox`
- `combobox`
- `dropdown`
- `grid`
- `list`
- `radiobutton`
- `togglebutton`
- `tree`
Unconstrained Input
-------------------
- `lineedit`
- `tableview`
- `textedit`
Constrained Input
-----------------
- `date`
- `slider`
- `spinbox`
---
title: Date and Time Picker
weight: 3
weight: 13
group: editing
subgroup: constrained
---
......
---
title: Radio Button
weight: 8
group: editing
subgroup: selection
---
============
Purpose
-------
......@@ -22,68 +24,52 @@ Guidelines
more than five options (or if there is not enough space to arrange
four or five options), use a combo box or list instead.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t use radio buttons
for more than five options.](/hig/Radiobutton_Many_Bad.qml.png){.border
.dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Use a combobox
instead.](/hig/Radiobutton_Many_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_Many_Bad.qml.png" >}}
Don't use radio buttons for more than five options.
{{< /dont >}}
{{< do src="/hig/Radiobutton_Many_Good.qml.png" >}}
Use a combobox instead.
{{< /do >}}
{{< /compare >}}
- If there are only two options where one is the negation of the other
(e.g. \"apply\" vs. \"don\'t apply\"), consider replacing the radio
(e.g. "apply" vs. "don't apply"), consider replacing the radio
buttons by one `checkbox <checkbox>`.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t use radio buttons
for do/don\'t
operations.](/hig/Radiobutton_Negation_Bad.qml.png){.border .dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Use a checkbox
instead.](/hig/Radiobutton_Negation_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_Negation_Bad.qml.png" >}}
Don't use radio buttons for do/don't operations.
{{< /dont >}}
{{< do src="/hig/Radiobutton_Negation_Good.qml.png" >}}
Use a checkbox instead.
{{< /do >}}
{{< /compare >}}
- Use radio buttons if the user should see the choices without further
interaction.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t hide choices that
the user should see from the start in
comboboxes.](/hig/Radiobutton_Visible_Bad.qml.png){.border .dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Use radio buttons
instead.](/hig/Radiobutton_Visible_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_Visible_Bad.qml.png" >}}
Don't hide choices that the user should see from the start in comboboxes.
{{< /dont >}}
{{< do src="/hig/Radiobutton_Visible_Good.qml.png" >}}
Use radio buttons instead.
{{< /do >}}
{{< /compare >}}
- Don\'t use a radio button to initiate an action. Consider using a
- Don't use a radio button to initiate an action. Consider using a
`push button <../navigation/pushbutton>`{.interpreted-text
role="doc"} instead.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t use the selection to
perform commands.](/hig/Radiobutton_Command_Bad.qml.png){.border .dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Consider using a
`push button <../navigation/pushbutton>`{.interpreted-text
role="doc"}.](/hig/No_Command_2_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_Command_Bad.qml.png" >}}
Don't use the selection to perform commands.
{{< /dont >}}
{{< do src="/hig/No_Command_2_Good.qml.png" >}}
Consider using a [push button](../../navigation/pushbutton).
{{< /do >}}
{{< /compare >}}
### Behavior
......@@ -91,33 +77,26 @@ role="doc"}.](/hig/No_Command_2_Good.qml.png){.border .do}
change depending on the context.
- Always have one radio button selected.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t forget a default
option.](/hig/Radiobutton_Default_Bad.qml.png){.border .dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Set a default
option.](/hig/Radiobutton_Default_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_Default_Bad.qml.png" >}}
Don't forget a default option.
{{< /dont >}}
{{< do src="/hig/Radiobutton_Default_Good.qml.png" >}}
Set a default option.
{{< /do >}}
{{< /compare >}}
- Make the first item the default option.
::: {.container .flex}
::: {.container}
![`Don't.`{.interpreted-text role="iconred"} Don\'t have an option
besides the first as the
default.](/hig/Radiobutton_First_Bad.qml.png){.border .dont}
:::
::: {.container}
![`Do.`{.interpreted-text role="noblefir"} Set the first option as
default. Reorder your items if
necessary.](/hig/Radiobutton_First_Good.qml.png){.border .do}
:::
:::
{{< compare >}}
{{< dont src="/hig/Radiobutton_First_Bad.qml.png" >}}
Don't have an option besides the first as the default.
{{< /dont >}}
{{< do src="/hig/Radiobutton_First_Good.qml.png" >}}
Set the first option as default. Reorder your items if
necessary.
{{< /do >}}
{{< /compare >}}
- When using a radio button and none of the options is a valid choice,
add another option to reflect this choice, such as None or Does not
......@@ -125,13 +104,13 @@ necessary.](/hig/Radiobutton_First_Good.qml.png){.border .do}
### Appearance
If you are using Qt widgets you should use one of [Qt\'s Layout
If you are using Qt widgets you should use one of [Qt's Layout
Classes](http://doc.qt.io/qt-5/layout.html), which will take care of the
layout and spacing of your controls.
- When options are subordinate to a radio box, this relation should be
visualized by indenting the sub-options by using a horizontal spacer
of SizeType \"Minimum\".
of SizeType "Minimum".
- If activating a choice affects the appearance or the enabled state
of other controls, place them next to the radio button (group).
- Align radio buttons vertically rather than horizontally, as this
......@@ -141,18 +120,18 @@ layout and spacing of your controls.
certain radio button is toggled on (i.e. they are dependent
controls), disable them instead of hiding them if that radio button
is toggled off.
- Don\'t separate radio button and label. Clicking on both the button
- Don't separate radio button and label. Clicking on both the button
and the label should toggle the option.
- Don\'t add line breaks. If necessary place an additional label below
- Don't add line breaks. If necessary place an additional label below
the checkbox.
- Label a group of radio buttons with a descriptive caption to the top
left of the group (cf.
`alignment </layout/alignment>`).
[alignment](/hig/layout/alignment)).
- Create a buddy relation so access keys are assigned.
- Use
`sentence style capitalization </style/writing/capitalization>`{.interpreted-text
role="doc"} for radio buttons.
- Don\'t use ending punctuation (neither dot nor colon) for group
[sentence style capitalization](/hig/style/writing/capitalization)
for radio buttons.
- Don't use ending punctuation (neither dot nor colon) for group
label.
Code
......@@ -160,10 +139,8 @@ Code
### Kirigami
> - [QML:
> RadioButton](https://doc.qt.io/qt-5/qml-qtquick-controls-radiobutton.html)
- QML: [RadioButton](https://doc.qt.io/qt-5/qml-qtquick-controls-radiobutton.html)
### Plasma components
> - `Plasma RadioButton <RadioButton>`{.interpreted-text
> role="plasmaapi"}
- [Plasma RadioButton](docs:plasma;org::kde::plasma::components::RadioButton)
---
title: Slider
weight: 14
group: editing
subgroup: constrained
---
======
Purpose
-------
......@@ -29,13 +31,13 @@ Guidelines
- Use a slider when it is useful for the user to control the rate of
change of the value in real time.
- If the value is open-ended on one or both ends, consider using a
`Spin Box <spinbox>` instead.
[Spin Box](../spinbox) instead.
### Behavior
- Try to give immediate feedback while the user makes a selection.
- Size the control so that a user can easily set the desired value.
- Don\'t use a non-linear scale, e.g. logarithmic.
- Don't use a non-linear scale, e.g. logarithmic.
### Appearance
......@@ -63,8 +65,8 @@ eg screen size, symbol-size
checkmarks. Checkmark have a height of 4 px or 8 if you want to
emphasize them.
- Min/max labels are optional. Label min/max with real values, eg
\'640x480\' and \'5120×2880\' in case of screen resolution.
- Label the range of values; use checkmark and value label; don\'t
'640x480' and '5120×2880' in case of screen resolution.
- Label the range of values; use checkmark and value label; don't
label every checkmark.
#### Slider with many steps
......@@ -73,9 +75,9 @@ eg volume control, mouse speed, brightness
![Exact value is not important](/hig/Slider.Volume.qml.png)
- Don\'t show checkmarks if the exact value is not important
- Don\'t show min/max label if the values don\'t give the user
additional information, (eg. don\'t label them 0%, 100% when
- Don't show checkmarks if the exact value is not important
- Don't show min/max label if the values don't give the user
additional information, (eg. don't label them 0%, 100% when
obvious)
- If the exact value might be important to the user offer an input
field instead of the current value label
......@@ -107,9 +109,8 @@ Code
### Kirigami
> - [QML:
> Slider](https://doc.qt.io/qt-5/qml-qtquick-controls-slider.html)
- QML: [Slider](https://doc.qt.io/qt-5/qml-qtquick-controls-slider.html)
### Plasma Components
> - `Plasma Slider <Slider>`{.interpreted-text role="plasmaapi"}
- [Plasma Slider](../Slider)
---
title: Spin Box
group: editing
subgroup: constrained
weight: 15
---
========
![Control that accepts a range of values.](/hig/Spinbox1.png)
......@@ -27,11 +29,11 @@ Guidelines
iterations of some action, or a time-out value.
- If the range is fixed at both ends, or the numerical values are
arbitrary (for example, a volume control), use a
`Slider <slider>` control instead.
[Slider](../slider) control instead.
- For cases where the values are constrained at both ends and there
large ranges of integers (more than about 20) or floating-point
values that require precise control, consider providing both a
`Slider and Spin Box <slider>`. This
[Slider and Spin Box](../slider). This
allows the user to quickly set or fine-tune the setting more easily
than they could with the slider control alone.
......@@ -50,11 +52,11 @@ Guidelines
- Label the spin box with a text label to its left, using sentence
capitalization.
- Always append a suffix with the value\'s unit to the right.
- Always append a suffix with the value's unit to the right.
- Provide an access key in the label that allows the user to give
focus directly to the spin box.
- Right-justify the contents of spin boxes, unless the convention in
the user\'s locale demands otherwise. This is useful in windows
the user's locale demands otherwise. This is useful in windows
where the user might want to compare two numerical values in the
same column of controls. In this case, ensure the right edges of the
relevant controls are also aligned.
......@@ -64,9 +66,8 @@ Code
### Kirigami
> - [QML:
> SpinBox](https://doc.qt.io/qt-5/qml-qtquick-controls2-spinbox.html)
- QML: [SpinBox](https://doc.qt.io/qt-5/qml-qtquick-controls2-spinbox.html)
### Plasma Components
> - `Plasma SpinBox <SpinBox>`{.interpreted-text role="plasmaapi"}
- [Plasma SpinBox](../SpinBox)
---
title: Table View
weight: 11
group: editing
subgroup: unconstrained
---
==========
Purpose
-------
......@@ -29,9 +31,9 @@ Guidelines
- Use a table to arrange data in two dimensions.
- Use a table for a concise layout with inline editing feature.
- Don\'t use a table for read-only data. In this case use a simple
`list view <list>` or a
`tree view <tree>` with multiple
- Don't use a table for read-only data. In this case use a simple
[list view](../list) or a
[tree view](../tree) with multiple
columns.
### Behavior
......@@ -46,11 +48,11 @@ Guidelines
receives focus as a whole. By pressing arrow-down key the next row
is focused; respectively arrow-up for previous row. The arrow-left
or arrow-right key navigates to adjacent columns if available.
Don\'t change tab key navigation to allow users to switch to other
Don't change tab key navigation to allow users to switch to other
controls.
- Use the appropriate control for constrained input. Show the
control's UI (e.g. arrow for
`drop-down list <dropdown>`) not until
[drop-down list](../dropdown)) not until
the cell is in edit mode.
- Distinguish editable cells from those that are read-only.
- Allow tables to be extended by users in both directions.
......@@ -62,5 +64,5 @@ Guidelines
- Avoid horizontal scrollbars. Size the table to a reasonable width.
- Use fixed column header.
- Label the table with a descriptive caption to the top left (cf.
`/layout/alignment`).
[Alignment](../layout/alignment)).
- Create a buddy relation so access keys are assigned.
---
title: Text Edit
weight: 12
group: editing
subgroup: unconstrained
---
=========
![Control to enter multiple lines of text.](/hig/Textedit1.png)
......@@ -20,20 +22,20 @@ Guidelines
- Use text edits for input of unconstrained text with more than one
line.
- Don\'t use a text edit for input of a few words. Use a
`line edit <lineedit>` to enter single
- Don't use a text edit for input of a few words. Use a
[line edit](./lineedit) to enter single
lines of text.
### Behavior
- Don\'t make users scroll unnecessarily; size text boxes to eliminate
- Don't make users scroll unnecessarily; size text boxes to eliminate
the need for scrolling.
- Don\'t put horizontal scroll bars on multi-line text boxes.
- Don't put horizontal scroll bars on multi-line text boxes.
### Appearance
- When disabling the text edit, also disable any associated labels and
buttons.
- Label every text edit with a descriptive caption to the top left
(cf. `alignment </layout/alignment>`).
(cf. [alignment](/hig/layout/alignment)).
- Create a buddy relation so access keys are assigned.
---
title: Toggle Button
weight: 8
group: editing
subgroup: selection
---
=============
![Control to show a change of state.](/hig/Togglebutton1.png)
......@@ -9,9 +11,9 @@ Purpose
-------
Toggle buttons look similar to regular buttons, but are used to show or
change a state rather than initiate an action. A toggle button\'s two
states, set and unset, are shown by its appearing \"pushed in\" or
\"popped out\" respectively.
change a state rather than initiate an action. A toggle button's two
states, set and unset, are shown by its appearing "pushed in" or
"popped out" respectively.
Toggle buttons are a valid option to indicate a state with the advance
of using an icon. Compared to the related radio button or checkbox they
......@@ -26,9 +28,9 @@ Guidelines
- Use a toggle button to indicate a state if no other control apply,
i.e. in case of the
`toolbar <../navigation/toolbar>`.
- Prefer `radio buttons <radiobutton>`
or `checkboxes <checkbox>` outside the
[toolbar](../../navigation/toolbar).
- Prefer [radio buttons](../radiobutton)
or [checkboxes](../checkbox) outside the
toolbar.
### Behavior
......@@ -36,8 +38,8 @@ Guidelines
- Group toggle buttons in case of multiple selection.
- Separate toggle buttons from other controls, so they are not
mistaken for push buttons.
- Don\'t use a toggle button to initiate an action.
- Don\'t change the label according the button state.
- Don't use a toggle button to initiate an action.
- Don't change the label according the button state.
### Appearance
......
---
title: Tree View
weight: 9
group: editing
subgroup: selection
---
=========
Purpose
-------
......@@ -33,9 +35,8 @@ Guidelines
Balance discoverability with a predictable user model that minimizes
confusion.
- Consider breaking down the hierarchical data. For example, into a
selection by a `drop-down list <dropdown>`{.interpreted-text
role="doc"} with an associated `list view <list>`{.interpreted-text
role="doc"}.
selection by a [drop-down list](../dropdown) with an associated
[list view](../list).
### Behavior
......@@ -68,8 +69,7 @@ Guidelines
- For checkboxes, use the mixed state to indicate that an option is
set for some, but not all, child objects. Users should not be able
to set a mixed state directly (cf.
`checkboxes <checkbox>`).
to set a mixed state directly (cf. [checkboxes](../checkbox)).
- Clicking a mixed state checkbox selects all child objects and the
parent checkbox.
......@@ -86,10 +86,9 @@ Guidelines
- Make controls large enough that it can show at least eight list
items at a time without scrolling.
- Label the tree view with a descriptive caption to the top left (cf.
`alignment </layout/alignment>`).
[alignment](../layout/alignment)).
- Create a buddy relation so access keys are assigned.
- Make use of punctuation (Except for dot \".\" or colon \":\") for a