Plasma

core/units.h
1 /*
2  SPDX-FileCopyrightText: 2013 Marco Martin <[email protected]>
3  SPDX-FileCopyrightText: 2014 Sebastian K├╝gler <[email protected]>
4 
5  SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #ifndef UNITS_H
9 #define UNITS_H
10 
11 #include <QObject>
12 #include <QQmlPropertyMap>
13 
14 #include <Plasma/Theme>
15 
16 #include <KConfigWatcher>
17 
18 class QQuickItem;
19 
20 class SharedAppFilter : public QObject
21 {
22  Q_OBJECT
23 public:
24  explicit SharedAppFilter(QObject *parent = nullptr);
25  ~SharedAppFilter() override;
26 
27 Q_SIGNALS:
28  void fontChanged();
29 
30 protected:
31  bool eventFilter(QObject *watched, QEvent *event) override;
32 };
33 
34 /**
35  * @class Units
36  * @short Expose sizes to QML
37  */
38 class Units : public QObject
39 {
40  Q_OBJECT
41 
42  /**
43  * The fundamental unit of space that should be used for sizes, expressed in pixels.
44  * Given the screen has an accurate DPI settings, it corresponds to the height of
45  * the font's boundingRect.
46  */
47  Q_PROPERTY(int gridUnit READ gridUnit NOTIFY gridUnitChanged)
48 
49  /**
50  * units.iconSizes provides access to platform-dependent icon sizing
51  *
52  * The icon sizes provided are normalized for different DPI, so icons
53  * will scale depending on the DPI.
54  *
55  * Icon sizes from KIconLoader, adjusted to devicePixelRatio:
56  * * small
57  * * smallMedium
58  * * medium
59  * * large
60  * * huge
61  * * enormous
62  * * desktop (DEPRECATED: use iconSizeHints instead)
63  *
64  */
65  // note the iconSizeChanged signal indicates that one (or more) of these icons have changed
66  // but the property map itself remains constant
68 
69  /**
70  * units.iconSizeHints provides access to user-configurable icon size hints,
71  * to be used where appropriate in the user interface.
72  *
73  * Conceptually, an icon size hint is a key that has one of the sizes from
74  * @iconSizes property as value.
75  *
76  * Currently available hints:
77  * * panel
78  * * desktop
79  */
80  // note the iconSizeHintsChanged signal indicates that one (or more) of these icons have changed
81  // but the property map itself remains constant
83 
84  // layout hints
85 
86  /**
87  * This property holds the amount of spacing that should be used between smaller UI elements,
88  * such as a small icon and a label in a button.
89  * Internally, this size depends on the size of the default font as rendered on the screen,
90  * so it takes user-configured font size and DPI into account.
91  */
92  Q_PROPERTY(int smallSpacing READ smallSpacing NOTIFY spacingChanged)
93 
94  /**
95  * This property holds the amount of spacing that should be used between medium UI elements,
96  * such as buttons and text fields in a toolbar.
97  * Internally, this size depends on the size of the default font as rendered on the screen,
98  * so it takes user-configured font size and DPI into account.
99  */
100  Q_PROPERTY(int mediumSpacing READ mediumSpacing NOTIFY spacingChanged)
101 
102  /**
103  * This property is functionally identical to gridUnit. To avoid confusion, it should not be used.
104  *
105  * TODO KF6: This should be changed to work like Kirigami::Units::largeSpacing.
106  */
107  Q_PROPERTY(int largeSpacing READ largeSpacing NOTIFY spacingChanged)
108 
109  /**
110  * The ratio between physical and device-independent pixels. This value does not depend on the \
111  * size of the configured font. If you want to take font sizes into account when scaling elements,
112  * use PlasmaCore.Theme.mSize(PlasmaCore.Theme.defaultFont), PlasmaCore.Units.smallSpacing and PlasmaCore.Units.largeSpacing.
113  * The devicePixelRatio follows the definition of "device independent pixel" by Microsoft.
114  */
115  Q_PROPERTY(qreal devicePixelRatio READ devicePixelRatio NOTIFY devicePixelRatioChanged)
116 
117  /**
118  * units.longDuration should be used for longer, screen-covering animations, for opening and
119  * closing of dialogs and other "not too small" animations
120  */
121  Q_PROPERTY(int longDuration READ longDuration NOTIFY durationChanged)
122 
123  /**
124  * units.shortDuration should be used for short animations, such as accentuating a UI event,
125  * hover events, etc..
126  */
127  Q_PROPERTY(int shortDuration READ shortDuration NOTIFY durationChanged)
128 
129  /**
130  * units.veryShortDuration should be used for elements that should animate near instantly,
131  * but should have a hint of smoothness
132  */
133  Q_PROPERTY(int veryShortDuration READ veryShortDuration NOTIFY durationChanged)
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 NOTIFY durationChanged)
140 
141  /**
142  * Time in milliseconds equivalent to the theoretical human moment, which can be used
143  * to determine whether how long to wait until the user should be informed of something,
144  * or can be used as the limit for how long something should wait before being
145  * automatically initiated.
146  *
147  * Some examples:
148  *
149  * - When the user types text in a search field, wait no longer than this duration after
150  * the user completes typing before starting the search
151  * - When loading data which would commonly arrive rapidly enough to not require interaction,
152  * wait this long before showing a spinner
153  *
154  * This might seem an arbitrary number, but given the psychological effect that three
155  * seconds seems to be what humans consider a moment (and in the case of waiting for
156  * something to happen, a moment is that time when you think "this is taking a bit long,
157  * isn't it?"), the idea is to postpone for just before such a conceptual moment. The reason
158  * for the two seconds, rather than three, is to function as a middle ground: Not long enough
159  * that the user would think that something has taken too long, for also not so fast as to
160  * happen too soon.
161  *
162  * See also
163  * https://www.psychologytoday.com/blog/all-about-addiction/201101/tick-tock-tick-hugs-and-life-in-3-second-intervals
164  * (the actual paper is hidden behind an academic paywall and consequently not readily
165  * available to us, so the source will have to be the blog entry above)
166  *
167  * @since 5.81
168  */
169  Q_PROPERTY(int humanMoment READ humanMoment CONSTANT)
170 
171 public:
172  /// @cond INTERNAL_DOCS
173 
174  ~Units() override;
175 
176  /**
177  * @return a reference to the global Units instance
178  * @since 5.31
179  */
180  static Units &instance();
181 
182  /**
183  * @return pixel value for a grid Unit. Depends on DPI and font size.
184  */
185  int gridUnit() const;
186 
187  /**
188  * @return The ratio between physical and device-independent pixels.
189  */
190  qreal devicePixelRatio() const;
191 
192  /**
193  * @return map with iconsizes, indexed by name
194  */
195  QQmlPropertyMap *iconSizes() const;
196 
197  /**
198  * @return map with user-configurable icon size hints, indexed by name
199  * @since 5.33
200  */
202 
203  /**
204  * @return Pixel value for large spacing between elements.
205  * @since 5.0
206  */
207  int smallSpacing() const;
208 
209  /**
210  * @return Pixel value for medium spacing between elements.
211  * @since 5.92
212  */
213  int mediumSpacing() const;
214 
215  /**
216  * @return Pixel value for large spacing between elements.
217  * @since 5.0
218  */
219  int largeSpacing() const;
220 
221  /**
222  * @return Duration for long animations, in milliseconds.
223  * @since 5.0
224  */
225  int longDuration() const;
226 
227  /**
228  * @return Duration for short animations, in milliseconds.
229  * @since 5.0
230  */
231  int shortDuration() const;
232 
233  /**
234  * @return Duration for very long animations, in milliseconds.
235  * @since 5.69
236  */
237  int veryLongDuration() const;
238 
239  /**
240  * @return Duration for instantaneous animations, in milliseconds.
241  * @since 5.78
242  */
243  int veryShortDuration() const;
244 
245  /**
246  * @return Duration for very long wait times
247  * @since 5.81
248  */
249  int humanMoment() const;
250  /// @endcond
251 
252  /**
253  * @return a size rounded to the nearest inferior standard icon size.
254  * sizes larger than iconSizes.huge, it will be returned unmodified
255  * @param int size the size we want to be rounded down
256  * @see iconSizes
257  */
258  Q_INVOKABLE static int roundToIconSize(int size);
259 
260 Q_SIGNALS:
261  void devicePixelRatioChanged();
262  void gridUnitChanged();
263  void iconSizesChanged();
264  void iconSizeHintsChanged();
265  void spacingChanged();
266  void durationChanged();
267 
268 private Q_SLOTS:
269  void iconLoaderSettingsChanged();
270  void updateSpacing();
271 
272 private:
273  Units(QObject *parent = nullptr);
274  Units(Units const &) = delete; // Copy construct
275  Units(Units &&) = delete; // Move construct
276  Units &operator=(Units const &) = delete; // Copy assign
277  Units &operator=(Units &&) = delete; // Move assign
278 
279  void updateDevicePixelRatio();
280  void updateAnimationSpeed();
281 
282  /**
283  * @return the best-looking icon scale for the given device pixel ratio
284  * Note that this function is only relevant when using Plasma scaling and
285  * when using Qt scaling, it always returns 1.
286  */
287  static qreal bestIconScaleForDevicePixelRatio(const qreal ratio);
288 
289  /**
290  * @return The dpi-adjusted size for a given icon size
291  */
292  int devicePixelIconSize(const int size) const;
293 
294  int m_gridUnit;
295  qreal m_devicePixelRatio;
296 
297  QQmlPropertyMap *m_iconSizes;
298  QQmlPropertyMap *m_iconSizeHints;
299  static SharedAppFilter *s_sharedAppFilter;
300 
301  int m_smallSpacing;
302  int m_mediumSpacing;
303  int m_largeSpacing;
304 
305  KConfigWatcher::Ptr m_animationSpeedWatcher;
306  int m_longDuration;
307 };
308 
309 #endif // UNITS_H
int gridUnit
The fundamental unit of space that should be used for sizes, expressed in pixels.
Definition: core/units.h:47
Q_OBJECTQ_OBJECT
Expose sizes to QML.
Definition: core/units.h:38
Q_PROPERTY(...)
int shortDuration
units.shortDuration should be used for short animations, such as accentuating a UI event,...
Definition: core/units.h:127
Q_SLOTSQ_SLOTS
int veryLongDuration
units.veryLongDuration should be used for specialty animations that benefit from being even longer th...
Definition: core/units.h:139
int longDuration
units.longDuration should be used for longer, screen-covering animations, for opening and closing of ...
Definition: core/units.h:121
static Q_INVOKABLE int roundToIconSize(int size)
Definition: core/units.cpp:139
int largeSpacing
This property is functionally identical to gridUnit.
Definition: core/units.h:107
virtual bool eventFilter(QObject *watched, QEvent *event)
int mediumSpacing
This property holds the amount of spacing that should be used between medium UI elements,...
Definition: core/units.h:100
qreal devicePixelRatio
The ratio between physical and device-independent pixels.
Definition: core/units.h:115
int smallSpacing
This property holds the amount of spacing that should be used between smaller UI elements,...
Definition: core/units.h:92
QQmlPropertyMap iconSizeHints
units.iconSizeHints provides access to user-configurable icon size hints, to be used where appropriat...
Definition: core/units.h:82
Q_INVOKABLEQ_INVOKABLE
Q_SIGNALSQ_SIGNALS
QQmlPropertyMap iconSizes
units.iconSizes provides access to platform-dependent icon sizing
Definition: core/units.h:67
int humanMoment
Time in milliseconds equivalent to the theoretical human moment, which can be used to determine wheth...
Definition: core/units.h:169
QObject * parent() const const
int veryShortDuration
units.veryShortDuration should be used for elements that should animate near instantly,...
Definition: core/units.h:133
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:15:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.