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

KDE's Doxygen guidelines are available online.