Kirigami2

units.h
1 /*
2  * SPDX-FileCopyrightText: 2021 Jonah BrĂ¼chert <[email protected]>
3  * SPDX-FileCopyrightText: 2015 Marco Martin <[email protected]>
4  *
5  * SPDX-License-Identifier: LGPL-2.0-or-later
6  */
7 
8 #pragma once
9 
10 #include <QObject>
11 #include <memory>
12 
13 #include "kirigami2_export.h"
14 
15 class QQmlEngine;
16 
17 namespace Kirigami {
18 class Units;
19 class UnitsPrivate;
20 
21 /**
22  * @class IconSizes units.h <Kirigami/Units>
23  *
24  * Provides access to platform-dependent icon sizing
25  */
26 class KIRIGAMI2_EXPORT IconSizes : public QObject
27 {
28  Q_OBJECT
29 
30  Q_PROPERTY(int sizeForLabels READ sizeForLabels NOTIFY sizeForLabelsChanged)
31  Q_PROPERTY(int small READ small NOTIFY smallChanged)
32  Q_PROPERTY(int smallMedium READ smallMedium NOTIFY smallMediumChanged)
33  Q_PROPERTY(int medium READ medium NOTIFY mediumChanged)
34  Q_PROPERTY(int large READ large NOTIFY largeChanged)
35  Q_PROPERTY(int huge READ huge NOTIFY hugeChanged)
36  Q_PROPERTY(int enormous READ enormous NOTIFY enormousChanged)
37 
38 public:
39  IconSizes(Units *units);
40 
41  int sizeForLabels() const;
42  int small() const;
43  int smallMedium() const;
44  int medium() const;
45  int large() const;
46  int huge() const;
47  int enormous() const;
48 
49  Q_INVOKABLE int roundedIconSize(int size) const;
50 
51 private:
52  float iconScaleFactor() const;
53 
54  Units *m_units;
55 
56 Q_SIGNALS:
57  void sizeForLabelsChanged();
58  void smallChanged();
59  void smallMediumChanged();
60  void mediumChanged();
61  void largeChanged();
62  void hugeChanged();
63  void enormousChanged();
64 };
65 
66 /**
67  * @class Units units.h <Kirigami/Units>
68  *
69  * A set of values to define semantically sizes and durations.
70  */
71 class KIRIGAMI2_EXPORT Units : public QObject
72 {
73  Q_OBJECT
74 
75  friend class IconSizes;
76 
77  /**
78  * The fundamental unit of space that should be used for sizes, expressed in pixels.
79  * Given the screen has an accurate DPI settings, it corresponds to the height of
80  * the font's boundingRect.
81  */
82  Q_PROPERTY(int gridUnit READ gridUnit WRITE setGridUnit NOTIFY gridUnitChanged)
83 
84  /**
85  * units.iconSizes provides access to platform-dependent icon sizing
86  *
87  * The icon sizes provided are normalized for different DPI, so icons
88  * will scale depending on the DPI.
89  *
90  * * sizeForLabels (the largest icon size that fits within fontMetrics.height) @since 5.80 @since org.kde.kirigami 2.16
91  * * small
92  * * smallMedium
93  * * medium
94  * * large
95  * * huge
96  * * enormous
97  */
98  Q_PROPERTY(IconSizes *iconSizes READ iconSizes CONSTANT)
99 
100  /**
101  * This property holds the amount of spacing that should be used between smaller UI elements,
102  * such as a small icon and a label in a button.
103  * Internally, this size depends on the size of the default font as rendered on the screen,
104  * so it takes user-configured font size and DPI into account.
105  */
106  Q_PROPERTY(int smallSpacing READ smallSpacing WRITE setSmallSpacing NOTIFY smallSpacingChanged)
107 
108  /**
109  * This property holds the amount of spacing that should be used between medium UI elements,
110  * such as buttons and text fields in a toolbar.
111  * Internally, this size depends on the size of the default font as rendered on the screen,
112  * so it takes user-configured font size and DPI into account.
113  */
114  Q_PROPERTY(int mediumSpacing READ mediumSpacing WRITE setMediumSpacing NOTIFY mediumSpacingChanged)
115 
116  /**
117  * This property holds the amount of spacing that should be used between bigger UI elements,
118  * such as a large icon and a heading in a card.
119  * Internally, this size depends on the size of the default font as rendered on the screen,
120  * so it takes user-configured font size and DPI into account.
121  */
122  Q_PROPERTY(int largeSpacing READ largeSpacing WRITE setLargeSpacing NOTIFY largeSpacingChanged)
123 
124  /**
125  * The ratio between physical and device-independent pixels. This value does not depend on the \
126  * size of the configured font. If you want to take font sizes into account when scaling elements,
127  * use theme.mSize(theme.defaultFont), units.smallSpacing and units.largeSpacing.
128  * The devicePixelRatio follows the definition of "device independent pixel" by Microsoft.
129  *
130  * @deprecated since 5.86. When using Qt's high DPI scaling, all sizes are
131  * considered to be device-independent pixels, so this will simply return 1.
132  */
133  Q_PROPERTY(qreal devicePixelRatio READ devicePixelRatio NOTIFY devicePixelRatioChanged)
134 
135  /**
136  * units.veryLongDuration should be used for specialty animations that benefit
137  * from being even longer than longDuration.
138  */
139  Q_PROPERTY(int veryLongDuration READ veryLongDuration WRITE setVeryLongDuration NOTIFY veryLongDurationChanged)
140 
141  /**
142  * units.longDuration should be used for longer, screen-covering animations, for opening and
143  * closing of dialogs and other "not too small" animations
144  */
145  Q_PROPERTY(int longDuration READ longDuration WRITE setLongDuration NOTIFY longDurationChanged)
146 
147  /**
148  * units.shortDuration should be used for short animations, such as accentuating a UI event,
149  * hover events, etc..
150  */
151  Q_PROPERTY(int shortDuration READ shortDuration WRITE setShortDuration NOTIFY shortDurationChanged)
152 
153  /**
154  * units.veryShortDuration should be used for elements that should have a hint of smoothness,
155  * but otherwise animate near instantly.
156  */
157  Q_PROPERTY(int veryShortDuration READ veryShortDuration WRITE setVeryShortDuration NOTIFY veryShortDurationChanged)
158 
159  /**
160  * Time in milliseconds equivalent to the theoretical human moment, which can be used
161  * to determine whether how long to wait until the user should be informed of something,
162  * or can be used as the limit for how long something should wait before being
163  * automatically initiated.
164  *
165  * Some examples:
166  *
167  * - When the user types text in a search field, wait no longer than this duration after
168  * the user completes typing before starting the search
169  * - When loading data which would commonly arrive rapidly enough to not require interaction,
170  * wait this long before showing a spinner
171  *
172  * This might seem an arbitrary number, but given the psychological effect that three
173  * seconds seems to be what humans consider a moment (and in the case of waiting for
174  * something to happen, a moment is that time when you think "this is taking a bit long,
175  * isn't it?"), the idea is to postpone for just before such a conceptual moment. The reason
176  * for the two seconds, rather than three, is to function as a middle ground: Not long enough
177  * that the user would think that something has taken too long, for also not so fast as to
178  * happen too soon.
179  *
180  * See also
181  * https://www.psychologytoday.com/blog/all-about-addiction/201101/tick-tock-tick-hugs-and-life-in-3-second-intervals
182  * (the actual paper is hidden behind an academic paywall and consequently not readily
183  * available to us, so the source will have to be the blog entry above)
184  *
185  * \note This should __not__ be used as an animation duration, as it is deliberately not scaled according
186  * to the animation settings. This is specifically for determining when something has taken too long and
187  * the user should expect some kind of feedback. See veryShortDuration, shortDuration, longDuration, and
188  * veryLongDuration for animation duration choices.
189  *
190  * @since 5.81
191  * @since org.kde.kirigami 2.16
192  */
193  Q_PROPERTY(int humanMoment READ humanMoment WRITE setHumanMoment NOTIFY humanMomentChanged)
194 
195  /**
196  * time in ms by which the display of tooltips will be delayed.
197  *
198  * @sa ToolTip.delay property
199  */
200  Q_PROPERTY(int toolTipDelay READ toolTipDelay WRITE setToolTipDelay NOTIFY toolTipDelayChanged)
201 
202 #if KIRIGAMI2_ENABLE_DEPRECATED_SINCE(5, 86)
203  /**
204  * How much the mouse scroll wheel scrolls, expressed in lines of text.
205  * Note: this is strictly for classical mouse wheels, touchpads 2 figer scrolling won't be affected
206  */
207  Q_PROPERTY(int wheelScrollLines READ wheelScrollLines NOTIFY wheelScrollLinesChanged)
208 #endif
209 
210 #if KIRIGAMI2_ENABLE_DEPRECATED_SINCE(5, 86)
211  /**
212  * metrics used by the default font
213  *
214  * @deprecated since 5.86.0, Create your own TextMetrics object if needed.
215  * For the roundedIconSize function, use Units.iconSizes.roundedIconSize instead
216  */
217  Q_PROPERTY(QObject *fontMetrics READ fontMetrics CONSTANT)
218 #endif
219 
220 public:
221  explicit Units(QObject *parent = nullptr);
222  ~Units() override;
223 
224  int gridUnit() const;
225  void setGridUnit(int size);
226 
227  int smallSpacing() const;
228  void setSmallSpacing(int size);
229 
230  int mediumSpacing() const;
231  void setMediumSpacing(int size);
232 
233  int largeSpacing() const;
234  void setLargeSpacing(int size);
235 
236 #if KIRIGAMI2_ENABLE_DEPRECATED_SINCE(5, 86)
237  // TODO KF6 remove
238  KIRIGAMI2_DEPRECATED_VERSION(5, 86, "When using Qt scaling, this would return a value of 1")
239  qreal devicePixelRatio() const;
240 #endif
241 
242  int veryLongDuration() const;
243  void setVeryLongDuration(int duration);
244 
245  int longDuration() const;
246  void setLongDuration(int duration);
247 
248  int shortDuration() const;
249  void setShortDuration(int duration);
250 
251  int veryShortDuration() const;
252  void setVeryShortDuration(int duration);
253 
254  int humanMoment() const;
255  void setHumanMoment(int duration);
256 
257  int toolTipDelay() const;
258  void setToolTipDelay(int delay);
259 
260 #if KIRIGAMI2_ENABLE_DEPRECATED_SINCE(5, 86)
261  // TODO KF6 remove
262  KIRIGAMI2_DEPRECATED_VERSION(5, 86, "Use Qt.styleHints.wheelScrollLines instead")
263  int wheelScrollLines() const;
264  void setWheelScrollLines(int lines);
265 #endif
266 
267  IconSizes *iconSizes() const;
268 
269 Q_SIGNALS:
270  void gridUnitChanged();
271  void smallSpacingChanged();
272  void mediumSpacingChanged();
273  void largeSpacingChanged();
274  void devicePixelRatioChanged();
275  void veryLongDurationChanged();
276  void longDurationChanged();
277  void shortDurationChanged();
278  void veryShortDurationChanged();
279  void humanMomentChanged();
280  void toolTipDelayChanged();
281  void wheelScrollLinesChanged();
282 
283 private:
284 #if KIRIGAMI2_ENABLE_DEPRECATED_SINCE(5, 86)
285  QObject *fontMetrics() const;
286 #endif
287 
288  std::unique_ptr<UnitsPrivate> d;
289 };
290 
291 }
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat May 28 2022 04:29:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.