Differential D12961 Diff 37192 source/layout/metrics.rst

Changeset View

Standalone View

View Options

source/layout/metrics.rst

1Metrics, placement & keylines 1​Metrics and placement
2============================= 2​=====================
3 3​
4Purpose 4​Purpose
5------- 5​-------
6 6​
7All controls have a default *height and width* to establish a harmonic 7​All controls have a default *height and width* to establish a harmonic
8overall picture. Nevertheless, size is used to direct users' attention. 8​overall picture. Nevertheless, size is used to direct users' attention.
9For instance, a list that captures most of screen’s space points to its 9​For instance, a list that captures most of screen’s space points to its
10central role in the current work flow. And, size can be used to indicate 10​central role in the current work flow. And, size can be used to indicate
11possible interactions. Smaller edits are probably constrained, for 11​possible interactions. Smaller edits are probably constrained, for
12instance. 12​instance.
13 13​
14Similar to size, the *space* between controls generates a visual 14​Similar to size, the *space* between controls generates a visual
15impression and supports layout. Space between controls indicates their 15​impression and supports layout. Space between controls indicates their
16relatedness. Objects with smaller distances are mentally associated 16​relatedness. Objects with smaller distances are mentally associated
17according to the Gestalt theory. *Whitespace* is an important element of 17​according to the Gestalt theory. *Whitespace* is an important element of
ngrahamUnsubmitted
Done

"whitespace" was fine, I think.

ngraham: "whitespace" was fine, I think.
18design which enables the objects in it to exist at all. The balance 18​design which enables the objects in it to exist at all. The balance
19between content and white spaces is key to *grouping*. 19​between content and whitespace is key to *grouping*.
ngrahamUnsubmitted
Done

"whitespaces" -> "whitespace"

ngraham: "whitespaces" -> "whitespace"
20 20​
21Please read :doc:`units` for more information which and how 21​Please read :doc:`units` for more information which and how
22different units as px, dpi independent pixels, units.smallSpacing, 22​different units such as px, dpi independent pixels, smallSpacing and
23units.largeSpacing are used. 23​largeSpacing are used.
ngrahamUnsubmitted
Done

"largeSpacing" -> "and largeSpacing"

ngraham: "largeSpacing" -> "and largeSpacing"
ngrahamUnsubmitted
Done

"units as" -> "units such as"

ngraham: "units as" -> "units such as"
24 24​
25Guidelines 25​Guidelines
26---------- 26​----------
27 27​
28Size 28​Size
29~~~~ 29​~~~~
30 30​
31- If the control appears in a dialog or utility window, consider making 31​- If the control appears in a dialog or utility window, consider making
32 the window and the control within it resizeable so that the user can 32​ the window and the control within it resizeable so that the user can
ngrahamUnsubmitted
Done

"resizeable" was fine IMHO, and "resize able" is just wrong. :)

ngraham: "resizeable" was fine IMHO, and "resize able" is just wrong. :)
33 choose how many items are visible at a time without scrolling. Each 33​ choose how many items are visible at a time without scrolling. Each
34 time the user opens this dialog, set its dimensions to those that the 34​ time the user opens this dialog, set its dimensions to those that the
35 user last resized it to. 35​ user last resized it to.
36- Size controls with a minimum of 36​- Size controls with a minimum of
37 37​
38 - Icon: 16x16px 38​ - Icon: 16x16px
39 - Buttons: 72 x 32px 39​ - Buttons: 72 x 32px
40 - Line edits, Drop-downs, Combo boxes: ≥80 x 32 px 40​ - Line edits, Drop-downs, Combo boxes: ≥80 x 32 px
41 - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per 41​ - Text edits: ≥80 x ≥36 px (text should not exceed 80 characters per
42 line) 42​ line)
43 - Check box, Radio button including label: ≥80 x 24 px 43​ - Check box, Radio button including label: ≥80 x 24 px
44 - Group boxes: ≥120 x ≥96 px 44​ - Group boxes: ≥120 x ≥96 px
45 - Tree view: ≥120 x ≥96 px 45​ - Tree view: ≥120 x ≥96 px
46 - List view: ≥80 px (per column) x ≥96 46​ - List view: ≥80 px (per column) x ≥96
47 47​
48- KDE seeks to support XGA (1024x768px) or WXGA (1280x768px) at least. 48​- KDE seeks to support XGA (1024x768px) or WXGA (1280x768px) at least.
49 49​
50 - Keep in mind that not everyone is provided with a high resolution 50​ - Keep in mind that not everyone is provided with a high resolution
51 display. 51​ display.
52 - Avoid to have a large number of controls visible at once, which in 52​ - Avoid to have a large number of controls visible at once, which in
53 turn requires a huge minimal size. 53​ turn requires a huge minimal size.
54 - Keep in mind that the available screen area typically also will be 54​ - Keep in mind that the available screen area typically also will be
55 shrunk by panels and the window titlebar. Also, user's font might 55​ shrunk by panels and the window titlebar. Also, user's font might
ngrahamUnsubmitted
Done

I think "titlebar" is a technical term here, so it doesn't need the space in the middle.

ngraham: I think "titlebar" is a technical term here, so it doesn't need the space in the middle.
56 be bigger than yours (e.g. for accessibility reason). 56​ be bigger than yours (e.g. for accessibility reason).
57 - You therefore should ideally preserve ~10% to catch those 57​ - You therefore should ideally preserve ~10% to catch those
58 variables and try to not exceed 920x690px. 58​ variables and try to not exceed 920x690px.
59 59​
60Space 60​Space
61~~~~~ 61​~~~~~
62 62​
63qwidgets 63​Qt widgets
64^^^^^^^^ 64​^^^^^^^^^^
65 65​
66If you are using qwidgets you should use one of Qt's Layout Classes like 66​If you are using Qt widgets you should use one of
67, that will take care of lay outing and spacing of your controls. 67​`Qt's Layout Classes <http://doc.qt.io/qt-5/layout.html>`_,
68​which will take care of laying out and spacing of your controls.
ngrahamUnsubmitted
Not Done

Maybe specifically recommend QFormLayout again here?

ngraham: Maybe specifically recommend `QFormLayout` again here?
fabianrAuthorUnsubmitted
Not Done

To me the content on the page is too much focused on form layout anyways. These should be more general guidelines for spacings and paddings. So I would rather not change that here, but in a next step add more general examples to the page and probably create a content pattern for forms.

fabianr: To me the content on the page is too much focused on form layout anyways. These should be more…
ngrahamUnsubmitted
Done

"that will" -> "which will"

ngraham: "that will" -> "which will"
68 69​
69QML 70​QML
70^^^ 71​^^^
71 72​
72For consistency you should try to use plasmas units.smallSpacing and 73​For consistency you should try to use Kirigami and Plasma's
73units.largeSpacing for margins and paddings when ever possible. See 74​smallSpacing and largeSpacing for margins and paddings whenever possible.
ngrahamUnsubmitted
Done

"when ever" -> "whenever"

ngraham: "when ever" -> "whenever"
74:doc:`units` for more details. 75​See :doc:`units` for more details.
ngrahamUnsubmitted
Done

"Kirigami and Plasma's"

Or even

"smallspacing and largespacing from Kirigami or Plasma"

ngraham: "Kirigami and Plasma's" Or even "smallspacing and largespacing from Kirigami or Plasma"
75 76​
76.. hint:: 77​Use multiples of smallSpacing or largeSpacing, where more spacing is required.
ngrahamUnsubmitted
Done

No need to capitalize "Multiples"

ngraham: No need to capitalize "Multiples"
77 |designicon| For mockup and design you can use these values: ​
78 - units.smallSpacing = 4px ​
79 - units.largeSpacing = 18px ​
80 - units.gridUnit = 18px ​
81 ​
82 ​
83Use Multiples of units.smallSpacing or units.largeSpacing, where more spacing is required. ​
84 78​
85.. figure:: /img/Margin.qml.png 79​.. figure:: /img/Margin.qml.png
86 :alt: Use of base units 80​ :alt: Use of base units
87 81​
88 Use of base units 82​ Use of base units
89 83​
90Recomended minimum paddings 84​Recommended minimum paddings
91~~~~~~~~~~~~~~~~~~~~~~~~~~~ 85​~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 86​
93- A units.smallSpacing padding is the minimum recommended padding inside elements (buttons, drop boxes, text fields, etc.) 87​- A smallSpacing padding is the minimum recommended padding inside
94- An 2 * units.smallSpacing padding is the minimum recommended padding inside grouping frames (group boxes, tabs, etc.) 88​ elements (buttons, drop boxes, text fields, etc.)
89​- An 2 * smallSpacing padding is the minimum recommended padding
90​ inside grouping frames (group boxes, tabs, etc.)
95- Use default spacing of 91​- Use default spacing of
96 92​
97 - related items within groups: 2 * units.smallSpacing 93​ - related items within groups: 2 * smallSpacing
98 - label and item: units.smallSpacing 94​ - label and item: smallSpacing
99 - related controls with same type (check boxes / radio buttons): units.smallSpacing 95​ - related controls with same type (check boxes / radio buttons): smallSpacing
100 - related controls with different type (check box / button): units.smallSpacing 96​ - related controls with different type (check box / button): smallSpacing
101 - unrelated controls: ≥ 2 * units.smallSpacing 97​ - unrelated controls: ≥ 3 * smallSpacing
102 98​
103.. figure:: /img/Spacing_Padding.qml.png 99​.. figure:: /img/SpacingPadding.qml.png
104 :alt: Sample spacing 100​ :alt: Sample spacing
105 101​
106 Sample spacing 102​ Sample spacing
107 103​
104​- In some cases it may be useful to visually separate groups of related
105​ options within one group to facilitate scanning of the dialog. In
ngrahamUnsubmitted
Done

Let's not use the term "group box" here, as that could seem to imply that we're advocating the use of group boxes, which I believe we're trying to move away from.

ngraham: Let's not use the term "group box" here, as that could seem to imply that we're advocating the…
106​ that case, put a vertical, fixed-size spacer of 18px height between
ngrahamUnsubmitted
Not Done

Per discussion below, let's increase this to 18px. A few more pixels makes a huge difference!

ngraham: Per discussion below, let's increase this to 18px. A few more pixels makes a huge difference!
107​ the options.
108​
109​.. figure:: /img/SpacingSeperate.qml.png
110​ :alt: Separating groups of related options with a vertical spacer.
111​
112​ Separating groups of related options with a vertical spacer.
113​
108 114​
109.. hint:: 115​.. hint::
110 |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. 116​ |designicon| It often helps to use a soft grid of 18px (gridUnit), when creating
117​ mockups. But only use this as a visual hint, since plasma components and icon
ngrahamUnsubmitted
Done

"mock ups" -> "mockups"

ngraham: "mock ups" -> "mockups"
118​ size are not multiples of the gridUnit, you won't be able to align everything to the
ngrahamUnsubmitted
Done

"multiple" -> "multiples"

"gridUnit, you wont" -> "gridUnit, and you won't"

ngraham: "multiple" -> "multiples" "gridUnit, you wont" -> "gridUnit, and you won't"
119​ grid.
111 120​
112Resize 121​Resize
113~~~~~~ 122​~~~~~~
114 123​
115- Provide resizing for all primary and mode-less windows. 124​- Provide resizing for all primary and mode-less windows.
116- If form resizing is not provided disable border icons and adjust form style. 125​- If form resizing is not provided disable border icons and adjust form style.
117- Define a minimum size for resizable forms. 126​- Define a minimum size for resizable forms.
118- Make the content area scrollable if size is too small for all controls; do not scale controls. 127​- Make the content area scrollable if size is too small for all controls;
128​ do not scale controls.
ngrahamUnsubmitted
Done

"re sizable" -> "resizable"

ngraham: "re sizable" -> "resizable"
ngrahamUnsubmitted
Done

"scroll able" -> "scrollable"

ngraham: "scroll able" -> "scrollable"
119 129​
120.. figure:: /img/Resize.qml.png 130​.. figure:: /img/Resize.qml.png
121 :alt: Give hints how to resize 131​ :alt: Give hints how to resize
122 132​
123 Give hints how to resize 133​ Give hints how to resize