Members of the KDE Community are recommended to subscribe to the kde-community mailing list at https://mail.kde.org/mailman/listinfo/kde-community to allow them to participate in important discussions and receive other important announcements

Commit 9fd32dba authored by Fabian Riethmayer's avatar Fabian Riethmayer

Refactor pages about lists, list items and added picker pattern.

parent 9ae213f2
......@@ -17,7 +17,6 @@ Editing and manipulation
radiobutton
slider
spinbox
swipelistitem
tableview
textedit
togglebutton
......@@ -36,7 +35,6 @@ Selection
* :doc:`grid`
* :doc:`list`
* :doc:`radiobutton`
* :doc:`swipelistitem`
* :doc:`togglebutton`
* :doc:`tree`
......
......@@ -34,15 +34,6 @@ Is this the right control
year or days of a week)
- Usually the selected options are close to each other in the list
- Do *not* provide extended multiple selections with Shift+Click or
Ctrl+Click to select groups of contiguous or non-adjacent values,
respectively. Instead, use the
:doc:`dual-list pattern </patterns/content/duallist>` if multiple items
have to be selected, because it allows users to easily see which
items are selected at any point, without having to scroll through the
available options, and it can be used with only the mouse. (Once the
list view is being revised this guideline is subject of change.)
Behavior
~~~~~~~~
......@@ -51,8 +42,106 @@ Behavior
beginning of the list.
- Sort list items in a logical order. Make sure sorting fits
translation.
- For lists with more than one column, use headers and allow sorting.
Show these controls in the header.
On demand actions
^^^^^^^^^^^^^^^^^
List items can uses an :doc:`on-demand pattern </patterns/command/ondemand>` as
an alternative to always-visible controls. If the user often performs tasks on
single items of a list, you can add on-demand controls to the list item for
these.
.. image:: /img/Slide_to_reveal.jpg
:alt: Slide to reveal actions
:scale: 30 %
|desktopicon| Desktop
"""""""""""""""""""""
If only one action is available, most the time it's better to not use the
on-demand pattern and instead show the action right away.
.. raw:: html
<video src="https://cdn.kde.org/hig/video/20181031-1/Swipelistitem2.webm"
loop="true" playsinline="true" width="320" controls="true"
onended="this.play()" class="border"></video>
On-demand controls are shown when hovering over the item with the cursor.
A handle is shown to support devices with touch screens. Swiping the handle
right to left reveals the actions.
As soon as the user taps anywhere else or the pointer is no longer
hovering over the item, the handle is slid back.
|mobileicon| Mobile
"""""""""""""""""""
.. raw:: html
<video src="https://cdn.kde.org/hig/video/20181031-1/Swipelistitem1.webm"
loop="true" playsinline="true" width="320" controls="true"
onended="this.play()" class="border"></video>
On-demand controls are revealed by sliding a handle from right to left
to reveal them. As soon as the user taps anywhere else, the
handle is slid back.
Selection
^^^^^^^^^
List items can contain a checkbox to enable the selection of multiple items at
the same time. Clicking on the checkbox should not trigger an action, but only
change the selection. Place buttons below the list to perform actions on the
selected items.
If the selection is the only action a user can execute on the items, there is
no need for a checkbox. Change the background item color to toggle selection
state.
.. figure:: /img/PickerOverlay.png
:alt: Picker in Language KCM
:scale: 60%
Multiple selected items in a picker overlay.
- Do *not* provide extended multiple selections with Shift+Click or
Ctrl+Click to select groups of contiguous or non-adjacent values,
respectively. Instead, use the
:doc:`dual-list pattern </patterns/content/duallist>` or the
:doc:`picker pattern </patterns/content/picker>` if multiple items
have to be selected, because it allows users to easily see which
items are selected at any point, without having to scroll through the
available options, and it can be used with only the mouse.
Picker
^^^^^^
Lists can be used for the :doc:`picker pattern </patterns/content/picker>`.
Place a button below the list to add items to the list. To remove items from
the
list, either add an remove action on the item, or give the user the possibility
to select items and add a global remove button at the bottom of the list.
Ordering
^^^^^^^^
Allow drag and drop of items, if the the order of the items can be
changed by the user.
|desktopicon| Desktop
"""""""""""""""""""""
If you use a :doc:`dual-list pattern </patterns/content/duallist>` and want
to be able to re-order the items in the selected list you can add aditional up
and
down buttons.
.. figure:: /img/DualListOrdering.png
:scale: 50 %
:alt: Dual-list pattern with up and down buttons
Dual-list pattern with up and down buttons
Appearance
~~~~~~~~~~
......@@ -75,3 +164,182 @@ Appearance
- End each label with a colon. ":"
- Use :doc:`sentence style capitalization </style/writing/capitalization>`
for list view items.
|desktopicon| Desktop
^^^^^^^^^^^^^^^^^^^^^
.. figure:: /img/Listview6.png
:alt: Several different lists
:scale: 40 %
:figclass: border
List items with and without icons
List items can have a lot of different styles and sizes, but should always be
coherent in a list.
.. container:: flex
.. container::
.. figure:: /img/Listview3.png
:alt: Default padding of an item
:scale: 40 %
:figclass: border
Default padding of a SwipeListItem on desktop
Items have a padding of :doc:`Units.smallSpacing </layout/units>` on
the top and bottom and a padding of
:doc:`2 * Units.smallSpacing </layout/units>` on the left.
.. container::
.. figure:: /img/Listview4.png
:alt: Label is vertically centered
:scale: 40 %
:figclass: border
Label is vertically centered
Labels are vertically centered within the list item. If the list item
includes an icon, add a :doc:`2 * Units.smallSpacing </layout/units>`
margin between the icon and the label.
|mobileicon| Mobile
^^^^^^^^^^^^^^^^^^^
.. container:: flex
.. container::
.. figure:: /img/Listview1.png
:alt: Default padding of an item
:scale: 50 %
:figclass: border
Default padding of a SwipeListItem on mobile
Items have a padding of :doc:`Units.largeSpacing </layout/units>` on
the top and bottom and a padding of
:doc:`2 * Units.largeSpacing </layout/units>` on the left.
.. container::
.. figure:: /img/Listview2.png
:alt: Label is vertically centered
:scale: 50 %
:figclass: border
Label is vertically centered
Labels are vertically centered within the list item. If the list item
includes an icon, add a :doc:`2 * Units.largeSpacing </layout/units>`
margin between the icon and the label.
Selection
^^^^^^^^^
Checkboxes should be placed to the left of the item.
.. figure:: /img/Listview5.png
:alt: List items with checkboxes
:scale: 40 %
:figclass: border
List items with checkboxes for multi selection.
Add a :doc:`2 * Units.largeSpacing </layout/units>` margin between the checkbox
and the icon or the label.
If you change the background color to toggle selection state, use
Kirigami.Theme.highlightColor to indicate an active item.
Picker
^^^^^^
Place the button to add items to the bottom right of list.
.. figure:: /img/ListPicker.png
:alt: Picker
:scale: 40 %
:figclass: border
Add button at the bottom right of a list
For deselection you can either add a remove button for seleted icons next to
the add button or use an icon on the list item.
.. figure:: /img/ListPickerRemoveItem.png
:alt: Remove from a picker
:scale: 40 %
:figclass: border
Using an on-demand pattern to display a "Remove" icon.
Ordering
^^^^^^^^
Code
----
Kirigami
~~~~~~~~
.. code-block:: qml
...
ListView {
...
delegate: Kirigami.SwipeListItem {
id: lineItem
contentItem: Row {
spacing: lineItem.leftPadding
Item {
width: Kirigami.Units.iconSizes.medium
height: width
Image {
id: avatar
width: parent.width
height: width
source: "..."
visible: false
}
OpacityMask {
anchors.fill: avatar
source: avatar
maskSource: Rectangle {
height: avatar.width
width: height
radius: height / 2
}
}
}
Label {
anchors.verticalCenter: parent.verticalCenter
text: "..."
}
}
actions: [
Kirigami.Action {
text: i18n("&Make call")
iconName: "call-start"
},
Kirigami.Action {
text: i18n("&Write mail")
iconName: "mail-message"
}
]
}
...
}
...
Swipe list item
===============
.. container:: intend
|desktopicon| |mobileicon|
.. container:: available plasma qwidgets
|nbsp|
Purpose
-------
This uses an :doc:`on-demand pattern </patterns/command/ondemand>` as
alternative to always visible controls in lists. If the user
often performs tasks on single items of a list, add a handle on the side
the list item (next to the context drawer's edge, defined by a
system-wide configuration) which.
Example
-------
.. image:: /img/Slide_to_reveal.jpg
:alt: Slide to reveal actions
:scale: 30 %
Guidelines
----------
Is this the right control
~~~~~~~~~~~~~~~~~~~~~~~~~
- See :doc:`on-demand pattern </patterns/command/ondemand>` for
general recomendations.
- |desktopicon| If only one action is available, most the time it's better
to not use the on-demand pattern, but show the action right away.
Behavior
~~~~~~~~
|desktopicon| Desktop
"""""""""""""""""""""
.. image:: /img/desktop-listview.png
:alt: Hover to reveal
:scale: 60 %
On-demand controls are shown when hovering over the item with the cursor.
A handle is shown to support devices with touch screens. Swiping the handle
right to left reveals the actions.
As soon as the user taps anywhere else or the pointer is not any longer
hovering the item, the handle is slid back.
|mobileicon| Mobile
"""""""""""""""""""
.. raw:: html
<video src="https://cdn.kde.org/hig/video/20181031-1/Swipelistitem1.webm"
loop="true" playsinline="true" width="320" controls="true"
onended="this.play()" class="border"></video>
On-demand controls are revealed by sliding a handle from right to left
to reveal them. As soon as the user taps anywhere else, the
handle is slid back.
Appearance
~~~~~~~~~~
|desktopicon| Desktop
"""""""""""""""""""""
.. figure:: /img/Listview3.png
:alt: Default padding of an item
:scale: 60 %
:figclass: border
Default padding of a swipelistitem on desktop
Items have a padding of :doc:`Units.smallSpacing </layout/units>` on the top
and bottom and a padding of :doc:`2 * Units.smallSpacing </layout/units>` on
the left.
.. figure:: /img/Listview4.png
:alt: Label is vertically centered
:scale: 60 %
:figclass: border
Label is vertically centered
Labels are vertically centered within the list item. If the list item includes
an icon, add a :doc:`2 * Units.smallSpacing </layout/units>` margin between
the icon and the label.
|mobileicon| Mobile
"""""""""""""""""""
.. figure:: /img/Listview1.png
:alt: Default padding of an item
:scale: 60 %
:figclass: border
Default padding of a swipelistitem on mobile
Items have a padding of :doc:`Units.largeSpacing </layout/units>` on the top
and bottom and a padding of :doc:`2 * Units.largeSpacing </layout/units>` on
the left.
.. figure:: /img/Listview2.png
:alt: Label is vertically centered
:scale: 60 %
:figclass: border
Label is vertically centered
Labels are vertically centered within the list item. If the list item includes
an icon, add a :doc:`2 * Units.largeSpacing </layout/units>` margin between
the icon and the label.
Code
----
Kirigami
~~~~~~~~
.. code-block:: qml
...
ListView {
...
delegate: Kirigami.SwipeListItem {
id: lineItem
contentItem: Row {
spacing: lineItem.leftPadding
Item {
width: Kirigami.Units.iconSizes.medium
height: width
Image {
id: avatar
width: parent.width
height: width
source: "..."
visible: false
}
OpacityMask {
anchors.fill: avatar
source: avatar
maskSource: Rectangle {
height: avatar.width
width: height
radius: height / 2
}
}
}
Label {
anchors.verticalCenter: parent.verticalCenter
text: "..."
}
}
actions: [
Kirigami.Action {
text: i18n("&Make call")
iconName: "call-start"
},
Kirigami.Action {
text: i18n("&Write mail")
iconName: "mail-message"
}
]
}
...
}
...
......@@ -65,7 +65,6 @@ Selection
* :doc:`editing/grid`
* :doc:`editing/list`
* :doc:`editing/radiobutton`
* :doc:`editing/swipelistitem`
* :doc:`editing/togglebutton`
* :doc:`editing/tree`
......
source/img/Listview1.png

32.1 KB | W: | H:

source/img/Listview1.png

601 KB | W: | H:

source/img/Listview1.png
source/img/Listview1.png
source/img/Listview1.png
source/img/Listview1.png
  • 2-up
  • Swipe
  • Onion skin
source/img/Listview2.png

30.2 KB | W: | H:

source/img/Listview2.png

752 KB | W: | H:

source/img/Listview2.png
source/img/Listview2.png
source/img/Listview2.png
source/img/Listview2.png
  • 2-up
  • Swipe
  • Onion skin
source/img/Listview3.png

63.1 KB | W: | H:

source/img/Listview3.png

63.1 KB | W: | H:

source/img/Listview3.png
source/img/Listview3.png
source/img/Listview3.png
source/img/Listview3.png
  • 2-up
  • Swipe
  • Onion skin
source/img/Listview4.png

62.1 KB | W: | H:

source/img/Listview4.png

62.1 KB | W: | H:

source/img/Listview4.png
source/img/Listview4.png
source/img/Listview4.png
source/img/Listview4.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -63,4 +63,4 @@ to reveal them. As soon as the user taps anywhere else, the
handle is slid back.
For futher guidelines see :doc:`swipe list item </components/editing/swipelistitem>`.
For futher guidelines see :doc:`list item </components/editing/list>`.
Dual-list
=========
.. image:: /img/TwoLists.png
:alt: twoLists.png
.. image:: /img/DualListOrdering.png
:alt: Dual-list pattern
Multiple selection in lists with more than a few items might become
difficult because selected as well as available items are not visible at
once. As an alternative approach, the *dual-list pattern* (also known as
list builder, or paired lists) was introduced. It consists of two
standard list boxes with the option to move items from one list to the
other and back. Dual-lists are useful for extended multiple selection in
general, especially for huge sets of items or in case of elaborate
selections. The trade-off is the rather large amount of space that is
needed to show two adjoining lists.
Multiple selection in :doc:`lists </components/editing/list>` with more than a
few items might become difficult because selected as well as available items are
not visible at once. As an alternative approach, the *dual-list pattern* (also
known as list builder, or paired lists) was introduced. It consists of two
standard :doc:`list </components/editing/list>` boxes with the option to move
items from one :doc:`list </components/editing/list>` to the other and back.
Dual-lists are useful for extended multiple selection in general, especially for
huge sets of items or in case of elaborate selections. The trade-off is the
rather large amount of space that is needed to show two adjoining lists.
When to use
-----------
- Use a dual-list pattern for multiple selection and in case of large
lists.
- Use a dual-list pattern for multiple selection and in case of
:doc:`large lists </components/editing/list>`.
- In case of limited screen real estate, consider changing the workflow
into repeated selections of smaller lists or by applying a hierarchy
to the data.
......@@ -39,8 +39,8 @@ How to use
(rather than move) the item from the available pool of items to the
list of current items.
- If the list of current items can be reordered, place up/down buttons
to the right of the list of current items. Only enable the up/down
buttons when an item is selected and can be moved.
in between the two lists, above and below the left and right buttons. Only
enable the up/down buttons when an item is selected and can be moved.
- Do not have blank list items; use meta-options, (e.g. "None") instead.
- Place options that represent general options (e.g. "All", "None") at the
beginning of the list.
......
......@@ -10,6 +10,7 @@ Content patterns
form
iconandtext
help
picker
settings
viewingediting
......@@ -17,5 +18,6 @@ Content patterns
- :doc:`form`
- :doc:`iconandtext`
- :doc:`help`
- :doc:`picker`
- :doc:`settings`
- :doc:`viewingediting`
Picker
======
Pickers implement a pattern to select multiple items from a list of available
choices. The main component only displays the selected items, and more items
can be added by choosing them from a list or grid in a dialog or overlay.
In compairison to dual lists, they work well on desktop and mobile.
Example
-------
.. figure:: /img/LanguagePicker.png
:alt: Picker in Language KCM
:scale: 60%
Use of a picker to select aditional languages.
When to use
-----------
- Use a picker for multiple selection and in case of large lists.
- Don't use it if both selected and unselected items need to be visible at
once. Use a dual list instead.
- Do not use a picker to show data primarily.
- If selection state needs to change often, think about using a list with
checkboxes or similar instead.
How to use
----------
.. figure:: /img/PickerOverlay.png
:alt: Using an overlay
:scale: 60%
Using an overlay to pick aditional items.
- Use a :doc:`grid </components/editing/grid>` or a
:doc:`list </components/editing/list>` to display the selected elemets.
- Open list of additional items to choose in a overlay sheet or a dialog
- Allow the user to select multiple items at once.
- Use either an on-demand control or display an button to allow the user
to deselect items.
- If the list of selected items can be reordered, place up/down buttons
to the right of the list of current items. Only enable the up/down
buttons when an item is selected and can be moved.
- Do not have blank list items; use meta-options, (e.g. "None") instead.
- Place options that represent general options (e.g. "All", "None") at the
beginning of the list.
- Sort list items in a logical order. Alphabetical sorting should be able
to change when the text is translated.
- If the lists or grids appears in a dialog, consider making the window and
the lists or grids within it resizeable so that the user can choose how
many list items are visible at a time without scrolling.
- Use :doc:`sentence style capitalization </style/writing/capitalization>`
for items.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment