diff --git a/source/components/editing/index.rst b/source/components/editing/index.rst index cfca402..f3bbbe7 100644 --- a/source/components/editing/index.rst +++ b/source/components/editing/index.rst @@ -1,54 +1,52 @@ Editing and manipulation ======================== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: card checkbox combobox date dropdown grid lineedit list radiobutton slider spinbox - swipelistitem 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 ~~~~~~~~~ * :doc:`card` * :doc:`checkbox` * :doc:`combobox` * :doc:`dropdown` * :doc:`grid` * :doc:`list` * :doc:`radiobutton` -* :doc:`swipelistitem` * :doc:`togglebutton` * :doc:`tree` Unconstrained input ~~~~~~~~~~~~~~~~~~~ * :doc:`lineedit` * :doc:`tableview` * :doc:`textedit` Constrained input ~~~~~~~~~~~~~~~~~ * :doc:`date` * :doc:`slider` * :doc:`spinbox` diff --git a/source/components/editing/list.rst b/source/components/editing/list.rst index abb4ad6..dc4de07 100644 --- a/source/components/editing/list.rst +++ b/source/components/editing/list.rst @@ -1,77 +1,345 @@ List View ========= Purpose ------- A *list view* offers orientation, organization, and allows navigation without the need for more controls. Additionally, a list view may be used for single selection (users select one item from a list of mutually exclusive values) or multiple selections (selections in combination with the Shift key or Control key). However, because there is no common visual clue whether a list box’ mode is single or multiple and since other controls are more efficient for single selection, a list box should be used for single selection only. .. image:: /img/ListView.png :alt: ListView.png Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Prefer a list view to show items that belong together and in case there is enough space. - Use the list view for selection when it is easy for users to know which items are selected at any given time, for one or more of these reasons: - There are no more than twice the number of options then are visible at a time - The options are well-known and familiar (for example months of a 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 ` 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 ~~~~~~~~ - 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. 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 ` 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 + + + +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 + + + +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 ` or the + :doc:`picker pattern ` 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 `. +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 ` 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 ~~~~~~~~~~ - Alternate row color (use theme settings). Use different keys (e.g. page up/down) when more lists should be accessible. - Show at least four list view items at any time without the need for scrolling. - Make windows and the list within a dialog or utility window resizeable so that users can choose how many list items are visible at a time without scrolling. Make these windows remember last used dimensions. - If selections affect the appearance or control states, place these controls next to the list view. - Disable controls in a dialog if not in use rather than hide, or remove them from the list (i.e. they are dependent controls), - Label the list view with a descriptive caption to the top left (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. - End each label with a colon. ":" - Use :doc:`sentence style 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 ` on + the top and bottom and a padding of + :doc:`2 * Units.smallSpacing ` 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 ` + 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 ` on + the top and bottom and a padding of + :doc:`2 * Units.largeSpacing ` 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 ` + 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 ` 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" + } + ] + } + + ... + } + ... diff --git a/source/components/editing/swipelistitem.rst b/source/components/editing/swipelistitem.rst deleted file mode 100644 index 60f325a..0000000 --- a/source/components/editing/swipelistitem.rst +++ /dev/null @@ -1,180 +0,0 @@ -Swipe list item -=============== - -.. container:: intend - - |desktopicon| |mobileicon| - -.. container:: available plasma qwidgets - - |nbsp| - -Purpose -------- - -This uses an :doc:`on-demand pattern ` 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 ` 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 - - - -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 ` on the top -and bottom and a padding of :doc:`2 * Units.smallSpacing ` 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 ` 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 ` on the top -and bottom and a padding of :doc:`2 * Units.largeSpacing ` 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 ` 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" - } - ] - } - - ... - } - ... diff --git a/source/components/index.rst b/source/components/index.rst index 0a4619d..2ed53ca 100644 --- a/source/components/index.rst +++ b/source/components/index.rst @@ -1,83 +1,82 @@ Components ========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: formating/index navigation/index assistance/index editing/index Formating --------- * :doc:`formating/groupbox` * :doc:`formating/splitter` Navigation ---------- * :doc:`navigation/actionbutton` * :doc:`navigation/commandlink` * :doc:`navigation/contextdrawer` * :doc:`navigation/contextmenu` * :doc:`navigation/dialog` * :doc:`navigation/globaldrawer` * :doc:`navigation/menubar` * :doc:`navigation/pushbutton` * :doc:`navigation/tab` * :doc:`navigation/toolbar` 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 ~~~~~~~~~~~~ * :doc:`assistance/emblem` * :doc:`assistance/inline` * :doc:`assistance/message` * :doc:`assistance/progress` * :doc:`assistance/statusbar` Help ~~~~ * :doc:`assistance/tooltip` Editing and manipulation ------------------------ Editing and Manipulation considers the behaviors that result in persistent changes to user’s stored information. Selection ~~~~~~~~~ * :doc:`editing/card` * :doc:`editing/checkbox` * :doc:`editing/combobox` * :doc:`editing/dropdown` * :doc:`editing/grid` * :doc:`editing/list` * :doc:`editing/radiobutton` -* :doc:`editing/swipelistitem` * :doc:`editing/togglebutton` * :doc:`editing/tree` Unconstrained input ~~~~~~~~~~~~~~~~~~~ * :doc:`editing/lineedit` * :doc:`editing/tableview` * :doc:`editing/textedit` Constrained input ~~~~~~~~~~~~~~~~~ * :doc:`editing/date` * :doc:`editing/slider` * :doc:`editing/spinbox` diff --git a/source/img/DualListOrdering.png b/source/img/DualListOrdering.png new file mode 100644 index 0000000..5166075 Binary files /dev/null and b/source/img/DualListOrdering.png differ diff --git a/source/img/LanguagePicker.png b/source/img/LanguagePicker.png new file mode 100644 index 0000000..ddb8565 Binary files /dev/null and b/source/img/LanguagePicker.png differ diff --git a/source/img/ListPicker.png b/source/img/ListPicker.png new file mode 100644 index 0000000..74d130b Binary files /dev/null and b/source/img/ListPicker.png differ diff --git a/source/img/ListPickerRemoveItem.png b/source/img/ListPickerRemoveItem.png new file mode 100644 index 0000000..5555a5e Binary files /dev/null and b/source/img/ListPickerRemoveItem.png differ diff --git a/source/img/Listview1.png b/source/img/Listview1.png index 8cee248..dd32667 100644 Binary files a/source/img/Listview1.png and b/source/img/Listview1.png differ diff --git a/source/img/Listview2.png b/source/img/Listview2.png index 3224eec..f763a9a 100644 Binary files a/source/img/Listview2.png and b/source/img/Listview2.png differ diff --git a/source/img/Listview3.png b/source/img/Listview3.png index 0138599..b4cb5d7 100644 Binary files a/source/img/Listview3.png and b/source/img/Listview3.png differ diff --git a/source/img/Listview4.png b/source/img/Listview4.png index cf2a5cc..5cc52e0 100644 Binary files a/source/img/Listview4.png and b/source/img/Listview4.png differ diff --git a/source/img/Listview5.png b/source/img/Listview5.png new file mode 100644 index 0000000..aa8740c Binary files /dev/null and b/source/img/Listview5.png differ diff --git a/source/img/Listview6.png b/source/img/Listview6.png new file mode 100644 index 0000000..0244bbc Binary files /dev/null and b/source/img/Listview6.png differ diff --git a/source/img/PickerOverlay.png b/source/img/PickerOverlay.png new file mode 100644 index 0000000..32a0bfc Binary files /dev/null and b/source/img/PickerOverlay.png differ diff --git a/source/patterns/command/ondemand.rst b/source/patterns/command/ondemand.rst index f1d8a84..dd324d9 100644 --- a/source/patterns/command/ondemand.rst +++ b/source/patterns/command/ondemand.rst @@ -1,66 +1,66 @@ On-Demand controls ================== .. container:: intend |desktopicon| |mobileicon| .. container:: flex .. container:: .. image:: /img/Slide_to_reveal.jpg :alt: 240px :scale: 25 % .. container:: .. image:: /img/Dolphin_hover.png :alt: 240px :scale: 80 % When to use ----------- Use on-demand controls for actions which directly relate to an element in a list or a grid, so they can be executed without selecting the element first (for example deleting or replying to an email right from the list). How to use ---------- - Do not use on-demand controls as the only means to execute an action, they are only shortcuts. - Do not use more than five (ideally not more than three) actions in on-demand controls. If you need more actions, choose a different :doc:`command pattern `. - Only use on-demand controls, if the actions are the same for each item. - Since the actions don't have a label, don't use the on-demand pattern, if the actions are not clearly identifiable. .. caution:: Especially if only one action is available, it is often better to show the action directly or have the action as default on the item. Behavior --------- |desktopicon| Desktop ~~~~~~~~~~~~~~~~~~~~~ On-demand controls are shown when hovering over the item with the cursor. A handle can be added to enable touch screen support. As soon as the user taps anywhere else or the pointer is not any longer hovering the item, the on-demand controls are hiden again. |mobileicon| Mobile ~~~~~~~~~~~~~~~~~~~ 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. -For futher guidelines see :doc:`swipe list item `. +For futher guidelines see :doc:`list item `. diff --git a/source/patterns/content/duallist.rst b/source/patterns/content/duallist.rst index 2d99f72..76e58cc 100644 --- a/source/patterns/content/duallist.rst +++ b/source/patterns/content/duallist.rst @@ -1,67 +1,67 @@ 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 ` 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 ` boxes with the option to move +items from one :doc:`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 `. - 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. - Do not use a dual-list to show data primarily. How to use ---------- - Label both lists view with a descriptive caption to the top. End each list label with a colon. - Use the left list to contain all available options. The right list should hold all currently active or in use items. - Ensure that the list boxes are of equal height and width. - Place move/remove buttons (right and left arrows) centered and in between the two lists. Disable a button if the list it is pointing away from is empty. - If an instance of one item can be repeated (such as a spacer), copy (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. - Sort list items in a logical order. Alphabetical sorting should be able to change when the text is translated. Implementation -------------- - Allow the user to drag-and-drop items between lists, or re-order items within a list (if applicable) - Double clicking on an item should add it to or remove it from the current list, respectively. - Allow multiple selection of items within one list. - Make both list controls large enough that it can show at least four items at a time without scrolling. - If the lists appears in a dialog or utility window, consider making the window and the lists within it resizeable so that the user can choose how many list items are visible at a time without scrolling. Each time the user opens this dialog, set its dimensions to those that the user last resized it to. - Create a buddy relation so access keys are assigned. - Use :doc:`sentence style capitalization ` for list view items. diff --git a/source/patterns/content/index.rst b/source/patterns/content/index.rst index 36c41c2..f544149 100644 --- a/source/patterns/content/index.rst +++ b/source/patterns/content/index.rst @@ -1,21 +1,23 @@ Content patterns ================ .. toctree:: :maxdepth: 1 :titlesonly: :hidden: duallist form iconandtext help + picker settings viewingediting - :doc:`duallist` - :doc:`form` - :doc:`iconandtext` - :doc:`help` +- :doc:`picker` - :doc:`settings` - :doc:`viewingediting` diff --git a/source/patterns/content/picker.rst b/source/patterns/content/picker.rst new file mode 100644 index 0000000..da4caa5 --- /dev/null +++ b/source/patterns/content/picker.rst @@ -0,0 +1,58 @@ +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 ` or a + :doc:`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 ` + for items.