diff --git a/source/components/checkbox.rst b/source/components/checkbox.rst index 5b85aa6..2010412 100644 --- a/source/components/checkbox.rst +++ b/source/components/checkbox.rst @@ -1,205 +1,198 @@ Check box ========= Purpose ------- A *check box* is a control that permits the user to make multiple selections from a number of options. Check boxes 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'. Example ------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use check boxes for non-exclusive options that have clear alternatives. Mutually exclusive options should use a set of :doc:`radio buttons ` or a :doc:`combo box `. .. container:: flex .. container:: .. figure:: /img/Ambiguous_Opposite_Bad.qml.png :figclass: border :iconred:`BAD` |br| Do not use a check box if the opposite is ambiguous. .. container:: .. figure:: /img/Ambiguous_Opposite_Good.qml.png :figclass: border :noblefir:`GOOD` |br| Using two radio buttons removes the need to guess. - For more than five options, use either a :doc:`list view ` or the :doc:`dual-list pattern ` in case of multiple selections. - Do not use the selection to perform commands. .. container:: flex .. container:: .. figure:: /img/No_Command_2_Bad.qml.png :figclass: border :iconred:`BAD` |br| Do not use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border :noblefir:`GOOD` |br| Consider using a :doc:`push button ` instead. Behavior ~~~~~~~~ - Checking a check box should always "enable" an option or change the state of an option to "on". Checking a negative or disabling option is a double negative and causes confusion and errors. .. container:: flex .. container:: .. figure:: /img/Checkbox_Enable_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Checkbox_Enable_Good.qml.png :figclass: border :noblefir:`GOOD` - Use the mixed state only to indicate that an option is set for some, but not all, child objects. Mixed state must not be used to represent a third state. .. image:: /img/Checkbox_Mixed_State.qml.png :alt: Example for mixed state. - Users must not be able to set a mixed state directly. - Clicking a mixed state check box enables all child objects. - Do not use sliding switches in Desktop applications. They only offer good user interaction on touch screens, so they should only be used in applications for mobile devices. .. container:: flex .. container:: .. figure:: /img/Checkbox_Switch_Desktop.qml.png :iconred:`BAD` .. container:: .. figure:: /img/Checkbox_Switch_Mobile.qml.png :noblefir:`GOOD` Appearance ~~~~~~~~~~ If you are using qt widgets you should use one of Qt's Layout Classes like , that will take care of lay outing and spacing of your controls. - The text of a check box is on the right of its tick rectangle, which can make it difficult to avoid blank areas on the left side of the form. To keep the layout of the form balanced you can use one of the following approaches: - Group check boxes together in the widget column and add a label describing the group in the label column. .. image:: /img/Grouped_checkboxes.qml.png :alt: Grouped checkboxes - - - Make the check boxes span the two columns, but keep them at the - bottom of the form. Remark: This interferes with other layout - guidelines - - .. image:: /img/Two_column_checkboxes.qml.png - :alt: Checkboxes spanning two columns - - If all else fails, add a label describing the checkbox on the left side of the checkbox, then set the text of the checkbox to "Enabled", "On", or similar. .. image:: /img/Checkbox_separate_label.qml.png :alt: Using a separate title label for the checkbox. - When options are subordinate to a check box (e.g. Audio level can only be set if the Activate Audio option is selected), this relation should be visualized by indenting the sub-options. There are two options to do so: - When you are using a left-aligned check box, indent the sub-options by using a horizontal spacer of SizeType "Minimum". .. image:: /img/Suboption_spacer.qml.png :alt: Aligning sub-options with a horizontal spacer of SizeType "Minimum". - When you are using a check box that is placed right to its label, indent the sub-options in the same vertical axis as the check box. .. image:: /img/Suboption_right.qml.png :alt: Aligning sub-options with the same vertical axis as the checkbox itself.| - If activating a choice affects the appearance or the enabled state of other controls, place them next to the check box (group). - Align check boxes vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window. - If certain controls in a configuration dialog are only relevant if a certain check box is checked (i.e. they are dependent controls), disable them instead of hiding them if that check box is unchecked. - Do not separate check box and label. Clicking on both the box and the label should toggle the option. .. image:: /img/HIG_Checkbox5.png :alt: Separate check box and label - Do not add line breaks. If necessary place an additional label below the check box. .. container:: flex .. container:: .. figure:: /img/Checkbox_Alignment_Bad.qml.png :iconred:`BAD` .. container:: .. figure:: /img/Checkbox_Alignment_Good.qml.png :noblefir:`GOOD` - Label a group of check box with a descriptive caption to the top left of the group (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. -- Use :doc:`sentence style capitalization ` for check box items. +- Use :doc:`sentence style capitalization ` + for check box items. - Do not use ending punctuation (neither dot nor colon) for group label. diff --git a/source/components/radiobutton.rst b/source/components/radiobutton.rst index 0e5ab8c..d7438d6 100644 --- a/source/components/radiobutton.rst +++ b/source/components/radiobutton.rst @@ -1,178 +1,179 @@ Radio button ============ Purpose ------- *Radio buttons* offer the user a choice of two or more mutually exclusive options. Try to limit the number of radio buttons and radio button groups in a dialog. Offering a high number of radio buttons consumes screen space and adds to visual clutter. At the same time, showing all available options at once is an advantage if users are likely not to know possible alternatives. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use radio buttons for a few mutually exclusive options. If there are 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:: .. figure:: /img/Radiobutton_Many_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_Many_Good.qml.png :figclass: border :noblefir:`GOOD` - If there are only two options where one is the negation of the other (e.g. "apply" vs. "do not apply"), consider replacing the radio buttons by one :doc:`check box `. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Negation_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_Negation_Good.qml.png :figclass: border :noblefir:`GOOD` - Use radio buttons if the user should see the choices without further interaction. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Visible_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_Visible_Good.qml.png :figclass: border :noblefir:`GOOD` - Do not use a radio button to initiate an action. Consider using a :doc:`push button ` instead. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Command_Bad.qml.png :figclass: border :iconred:`BAD` |br| Do not use the selection to perform commands. .. container:: .. figure:: /img/No_Command_2_Good.qml.png :figclass: border :noblefir:`GOOD` |br| Consider using a :doc:`push button `. Behavior ~~~~~~~~ - Radio buttons are not dynamic; their content or labels should not change depending on the context. - Always have one radio button selected. .. container:: flex .. container:: .. figure:: /img/Radiobutton_Default_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_Default_Good.qml.png :figclass: border :noblefir:`GOOD` - Make the first item the default option. .. container:: flex .. container:: .. figure:: /img/Radiobutton_First_Bad.qml.png :figclass: border :iconred:`BAD` .. container:: .. figure:: /img/Radiobutton_First_Good.qml.png :figclass: border :noblefir:`GOOD` - 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 apply. Appearance ~~~~~~~~~~ -If you are using qt widgets you should use one of Qt's Layout Classes -like , that will take care of lay outing and spacing of your controls. +If you are using Qt widgets you should use one of +`Qt's Layout Classes `_, +which will take care of laying out 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". - 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 makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window. - If certain controls in a configuration dialog are only relevant if a 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. - - Do not separate radio button and label. Clicking on both the button and the label should toggle the option. - Do not add line breaks. If necessary place an additional label below the check box. - Label a group of radio buttons with a descriptive caption to the top left of the group (cf. :doc:`alignment `). - Create a buddy relation so access keys are assigned. -- Use :doc:`sentence style capitalization ` for radio buttons. +- Use :doc:`sentence style capitalization ` + for radio buttons. - Do not use ending punctuation (neither dot nor colon) for group label. diff --git a/source/img/Form_Align_YES_Mobile.qml.png b/source/img/Form_Align_YES_Mobile.qml.png new file mode 100644 index 0000000..c1dcbdf Binary files /dev/null and b/source/img/Form_Align_YES_Mobile.qml.png differ diff --git a/source/img/Radiobutton_Command_Bad.qml.png b/source/img/Radiobutton_Command_Bad.qml.png index be894ad..f2f0362 100644 Binary files a/source/img/Radiobutton_Command_Bad.qml.png and b/source/img/Radiobutton_Command_Bad.qml.png differ diff --git a/source/img/Radiobutton_Default_Bad.qml.png b/source/img/Radiobutton_Default_Bad.qml.png index 795eed1..76ce79d 100644 Binary files a/source/img/Radiobutton_Default_Bad.qml.png and b/source/img/Radiobutton_Default_Bad.qml.png differ diff --git a/source/img/Radiobutton_Default_Good.qml.png b/source/img/Radiobutton_Default_Good.qml.png index a898a9c..c4d354a 100644 Binary files a/source/img/Radiobutton_Default_Good.qml.png and b/source/img/Radiobutton_Default_Good.qml.png differ diff --git a/source/img/Radiobutton_First_Bad.qml.png b/source/img/Radiobutton_First_Bad.qml.png index 1504fc0..afbdbcf 100644 Binary files a/source/img/Radiobutton_First_Bad.qml.png and b/source/img/Radiobutton_First_Bad.qml.png differ diff --git a/source/img/Radiobutton_First_Good.qml.png b/source/img/Radiobutton_First_Good.qml.png index 733a272..7324157 100644 Binary files a/source/img/Radiobutton_First_Good.qml.png and b/source/img/Radiobutton_First_Good.qml.png differ diff --git a/source/img/Radiobutton_Many_Bad.qml.png b/source/img/Radiobutton_Many_Bad.qml.png index e6c8f1e..4add410 100644 Binary files a/source/img/Radiobutton_Many_Bad.qml.png and b/source/img/Radiobutton_Many_Bad.qml.png differ diff --git a/source/img/Radiobutton_Many_Good.qml.png b/source/img/Radiobutton_Many_Good.qml.png index b224867..53833ee 100644 Binary files a/source/img/Radiobutton_Many_Good.qml.png and b/source/img/Radiobutton_Many_Good.qml.png differ diff --git a/source/img/Radiobutton_Negation_Bad.qml.png b/source/img/Radiobutton_Negation_Bad.qml.png index bb67228..266d277 100644 Binary files a/source/img/Radiobutton_Negation_Bad.qml.png and b/source/img/Radiobutton_Negation_Bad.qml.png differ diff --git a/source/img/Radiobutton_Negation_Good.qml.png b/source/img/Radiobutton_Negation_Good.qml.png index ac5113d..2c41229 100644 Binary files a/source/img/Radiobutton_Negation_Good.qml.png and b/source/img/Radiobutton_Negation_Good.qml.png differ diff --git a/source/img/Radiobutton_Visible_Bad.qml.png b/source/img/Radiobutton_Visible_Bad.qml.png index 5a5ed5f..1c7d6be 100644 Binary files a/source/img/Radiobutton_Visible_Bad.qml.png and b/source/img/Radiobutton_Visible_Bad.qml.png differ diff --git a/source/img/Radiobutton_Visible_Good.qml.png b/source/img/Radiobutton_Visible_Good.qml.png index 0e5f2fd..6ebd431 100644 Binary files a/source/img/Radiobutton_Visible_Good.qml.png and b/source/img/Radiobutton_Visible_Good.qml.png differ diff --git a/source/img/SpacingPadding.qml.png b/source/img/SpacingPadding.qml.png new file mode 100644 index 0000000..95f9896 Binary files /dev/null and b/source/img/SpacingPadding.qml.png differ diff --git a/source/img/SpacingSeperate.qml.png b/source/img/SpacingSeperate.qml.png new file mode 100644 index 0000000..825812c Binary files /dev/null and b/source/img/SpacingSeperate.qml.png differ diff --git a/source/layout/alignment.rst b/source/layout/alignment.rst index 1452fab..63baed0 100644 --- a/source/layout/alignment.rst +++ b/source/layout/alignment.rst @@ -1,123 +1,131 @@ Alignment ========= Purpose ------- One of the most important aspects of presentation is *alignment* and *placement* of controls. Its theoretical foundation is based on Gestalt psychology. Human perception tends to order experience in a manner that is regular, orderly, symmetric, and simple. Visual impression is generated to an emergent whole based on several principles, called Gestalt laws. Two basic laws are: - Law of proximity: an assortment of objects that are close to each other are formed into a group - Law of similarity: objects will be perceptually grouped together if they are similar to each other Placement of controls should be carefully done according to Gestalt theory. Guidelines ---------- -Labels -~~~~~~ -- Align labels to the right and connected widgets to the left, making a - group of form widgets appear to be center aligned. In Qt5, using a - QFormLayout handles this correctly for you. +Labels on the left +~~~~~~~~~~~~~~~~~~ + +On |desktopicon| Desktop it is recomended to place the labels to the left +of the connected widgets. .. container:: flex .. container:: .. figure:: /img/Form_Align_KDE3.qml.png :scale: 80% :iconred:`BAD` |br| KDE3 form alignment .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% :noblefir:`GOOD` |br| Plasma 5 form alignment +- The labels that are to the left of their connected widgets should be right-aligned. + This makes the whole group of form widgets appear to be center-aligned. + In Qt5, using a QFormLayout handles this correctly for you. + Controls ~~~~~~~~ - Align groups of items vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window. - Align a group of widgets to the left. This makes use of space more efficiently. .. container:: flex .. container:: .. figure:: /img/Form_Align_OSX.qml.png :scale: 80% :iconred:`BAD` |br| OSX form alignment .. container:: .. figure:: /img/Form_Align_KDE5.qml.png :scale: 80% :noblefir:`GOOD` |br| Plasma 5 form alignment - Left align controls over multiple groups (in case of right-to-left languages mirror the alignment). The visual anchor facilitates scanning of content, and left-hand alignment fits as well forms that have been oversized individually. .. container:: flex .. container:: .. figure:: /img/Form_Align_NO.qml.png :scale: 80% :iconred:`BAD` |br| no alignment over controls .. container:: .. figure:: /img/Form_Align_YES.qml.png :scale: 80% :noblefir:`GOOD` |br| left aligned controls - Keep track on label size; avoid big differences in text length (even - after translation), that could result in much white space for + after translation), that could result in much whitespace for multiple aligned controls. .. figure:: /img/Form_Align_Long.qml.png :scale: 80% :iconred:`BAD` |br| Avoid very long captions -- In some cases it may be useful to visually separate groups of related - options within one group box to facilitate scanning of the dialog. In - that case, put a vertical, fixed-size spacer of 16px height between - the options. +Labels on top +~~~~~~~~~~~~~ -.. figure:: /img/Form_Align_Space.qml.png - :alt: Separating groups of related options with a vertical spacer. +For |mobileicon| mobile, or if only narrow space is available, it is +recomended to place the labels above the connected widgets. + +.. image:: /img/Form_Align_YES_Mobile.qml.png + :scale: 80% - Separating groups of related options with a vertical spacer. +- Labels and widgets align left +- Minimize label length. Avoid multi-line labels. Check boxes and Radio buttons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For more details on alignment of :doc:`radio buttons ` and :doc:`checkboxes ` see the detailed HIG pages. +For more details on alignment of +:doc:`radio buttons ` and +:doc:`checkboxes `, see the detailed HIG pages. diff --git a/source/layout/metrics.rst b/source/layout/metrics.rst index a7b0eca..4079a5c 100644 --- a/source/layout/metrics.rst +++ b/source/layout/metrics.rst @@ -1,123 +1,133 @@ -Metrics, placement & keylines -============================= +Metrics and placement +===================== Purpose ------- All controls have a default *height and width* to establish a harmonic overall picture. Nevertheless, size is used to direct users' attention. For instance, a list that captures most of screen’s space points to its central role in the current work flow. And, size can be used to indicate possible interactions. Smaller edits are probably constrained, for instance. Similar to size, the *space* between controls generates a visual impression and supports layout. Space between controls indicates their relatedness. Objects with smaller distances are mentally associated according to the Gestalt theory. *Whitespace* is an important element of design which enables the objects in it to exist at all. The balance -between content and white spaces is key to *grouping*. +between content and whitespace is key to *grouping*. Please read :doc:`units` for more information which and how -different units as px, dpi independent pixels, units.smallSpacing, -units.largeSpacing are used. +different units such as px, dpi independent pixels, smallSpacing and +largeSpacing are used. Guidelines ---------- Size ~~~~ - If the control appears in a dialog or utility window, consider making the window and the control within it resizeable so that the user can choose how many 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. - Size controls with a minimum of - Icon: 16x16px - Buttons: 72 x 32px - Line edits, Drop-downs, Combo boxes: ≥80 x 32 px - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per line) - Check box, Radio button including label: ≥80 x 24 px - Group boxes: ≥120 x ≥96 px - Tree view: ≥120 x ≥96 px - List view: ≥80 px (per column) x ≥96 - KDE seeks to support XGA (1024x768px) or WXGA (1280x768px) at least. - Keep in mind that not everyone is provided with a high resolution display. - Avoid to have a large number of controls visible at once, which in turn requires a huge minimal size. - Keep in mind that the available screen area typically also will be shrunk by panels and the window titlebar. Also, user's font might be bigger than yours (e.g. for accessibility reason). - You therefore should ideally preserve ~10% to catch those variables and try to not exceed 920x690px. Space ~~~~~ -qwidgets -^^^^^^^^ +Qt widgets +^^^^^^^^^^ -If you are using qwidgets you should use one of Qt's Layout Classes like -, that will take care of lay outing and spacing of your controls. +If you are using Qt widgets you should use one of +`Qt's Layout Classes `_, +which will take care of laying out and spacing of your controls. QML ^^^ -For consistency you should try to use plasmas units.smallSpacing and -units.largeSpacing for margins and paddings when ever possible. See -:doc:`units` for more details. +For consistency you should try to use Kirigami and Plasma's +smallSpacing and largeSpacing for margins and paddings whenever possible. +See :doc:`units` for more details. -.. hint:: - |designicon| For mockup and design you can use these values: - - units.smallSpacing = 4px - - units.largeSpacing = 18px - - units.gridUnit = 18px - - -Use Multiples of units.smallSpacing or units.largeSpacing, where more spacing is required. +Use multiples of smallSpacing or largeSpacing, where more spacing is required. .. figure:: /img/Margin.qml.png :alt: Use of base units Use of base units -Recomended minimum paddings -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Recommended minimum paddings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- A units.smallSpacing padding is the minimum recommended padding inside elements (buttons, drop boxes, text fields, etc.) -- An 2 * units.smallSpacing padding is the minimum recommended padding inside grouping frames (group boxes, tabs, etc.) +- A smallSpacing padding is the minimum recommended padding inside + elements (buttons, drop boxes, text fields, etc.) +- An 2 * smallSpacing padding is the minimum recommended padding + inside grouping frames (group boxes, tabs, etc.) - Use default spacing of - - related items within groups: 2 * units.smallSpacing - - label and item: units.smallSpacing - - related controls with same type (check boxes / radio buttons): units.smallSpacing - - related controls with different type (check box / button): units.smallSpacing - - unrelated controls: ≥ 2 * units.smallSpacing + - related items within groups: 2 * smallSpacing + - label and item: smallSpacing + - related controls with same type (check boxes / radio buttons): smallSpacing + - related controls with different type (check box / button): smallSpacing + - unrelated controls: ≥ 3 * smallSpacing -.. figure:: /img/Spacing_Padding.qml.png +.. figure:: /img/SpacingPadding.qml.png :alt: Sample spacing Sample spacing + +- In some cases it may be useful to visually separate groups of related + options within one group to facilitate scanning of the dialog. In + that case, put a vertical, fixed-size spacer of 18px height between + the options. + +.. figure:: /img/SpacingSeperate.qml.png + :alt: Separating groups of related options with a vertical spacer. + + Separating groups of related options with a vertical spacer. .. hint:: - |designicon| It oftens helps to use a soft grid of 18px (units.gridUnit), when creating mockups. But only use this as a visual hint, since plasma components and icon size are not multiple of the gridUnit, you wont be able to align everything to the grid. + |designicon| It often helps to use a soft grid of 18px (gridUnit), when creating + mockups. But only use this as a visual hint, since plasma components and icon + size are not multiples of the gridUnit, you won't be able to align everything to the + grid. Resize ~~~~~~ - Provide resizing for all primary and mode-less windows. - If form resizing is not provided disable border icons and adjust form style. - Define a minimum size for resizable forms. -- Make the content area scrollable if size is too small for all controls; do not scale controls. +- Make the content area scrollable if size is too small for all controls; + do not scale controls. .. figure:: /img/Resize.qml.png :alt: Give hints how to resize Give hints how to resize