MauiKit Controls

handy.h
1/*
2 * Copyright 2018 Camilo Higuita <milo.h@aol.com>
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Library General Public License as
6 * published by the Free Software Foundation; either version 2, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20#pragma once
21#include <QObject>
22#include <QQmlEngine>
23
24#include <QVariantMap>
25
26namespace MauiMan
27{
28 class FormFactorManager;
29 class AccessibilityManager;
30}
31
32/**
33 * @brief The Handy class.
34 *
35 * Contains useful static methods to be used in the MauiKit application.
36 *
37 * @note This class is exposed as the singleton type `Handy` to the QML engine.
38 *
39 */
40class Handy : public QObject
41{
43 QML_ELEMENT
44 QML_SINGLETON
45 Q_DISABLE_COPY(Handy)
46
47 /**
48 * Whether the host platform is set as mobile. Either by the `QT_QUICK_CONTROLS_MOBILE` environment variable on, or from the MauiMan form factor mode to mobile.
49 */
50 Q_PROPERTY(bool isMobile READ isMobile NOTIFY isMobileChanged)
51
52 /**
53 * Whether the target device has a touch screen
54 */
55 Q_PROPERTY(bool isTouch READ isTouch NOTIFY isTouchChanged)
56
57 /**
58 * Whether the target device has a physical mouse attached
59 */
60 Q_PROPERTY(bool hasMouse READ hasMouse NOTIFY hasMouseChanged)
61
62 /**
63 * Whether the target device has a physical keyboard attached
64 */
65 Q_PROPERTY(bool hasKeyboard READ hasKeyboard NOTIFY hasKeyboardChanged)
66
67 /**
68 * Whether the current press input has been received from a touch screen
69 */
70 Q_PROPERTY(bool hasTransientTouchInput READ hasTransientTouchInput NOTIFY hasTransientTouchInputChanged)
71
72 /**
73 * Whether the host platform is an Android device
74 */
75 Q_PROPERTY(bool isAndroid READ isAndroid CONSTANT FINAL)
76
77 /**
78 * Whether the host platform is a GNU/Linux distribution
79 */
80 Q_PROPERTY(bool isLinux READ isLinux CONSTANT FINAL)
81
82 /**
83 * Whether the host platform is running Windows OS
84 */
85 Q_PROPERTY(bool isWindows READ isWindows CONSTANT FINAL)
86
87 /**
88 * Whether the host platform is running MacOS
89 */
90 Q_PROPERTY(bool isMac READ isMac CONSTANT FINAL)
91
92 /**
93 * Whether the host platform is running IOS
94 */
95 Q_PROPERTY(bool isIOS READ isIOS CONSTANT FINAL)
96
97 /**
98 * Whether the system preference is to open/trigger items with a single click
99 * @note This preference is taken from MauiMan global preference.
100 */
101 Q_PROPERTY(bool singleClick MEMBER m_singleClick NOTIFY singleClickChanged)
102
103 /**
104 * The current preferred from factor the user has selected.
105 * @note This preference can be set using MauiMan, and it is exposed to the end user via the Maui Settings.
106 *
107 * This property allows the user to manually pick between a mobile, tablet or desktop mode. This can be consumed by the applications to position elements in a fitting manner.
108 */
109 Q_PROPERTY(FFactor formFactor READ formFactor NOTIFY formFactorChanged)
110
111public:
112 Handy(QObject *parent = nullptr);
113
114 /**
115 * @brief The different form factor options.
116 */
118 {
119 /**
120 * Desktop form factor assumes there is a physical mouse and keyboard, and the screen area is wide and spacious.
121 */
123
124 /**
125 * Tablet form factor assumes a hand held device with touch screen, maybe there is a physical keyboard attached. The screen area is spacious enough still, not as wide as a desktop or as narrow as a mobile phone.
126 */
128
129 /**
130 * Mobile form factor mode assumes a phone is the target device. A small touch screen and not mouse or keyboard attached.
131 */
132 Phone
133 }; Q_ENUM(FFactor)
134
135 /**
136 * @private
137 */
138 static Handy *qmlAttachedProperties(QObject *object);
139
140 /**
141 * @private
142 */
143 static Handy *instance();
144
145 /**
146 * @private
147 */
148 static QObject * qmlInstance(QQmlEngine *engine, QJSEngine *scriptEngine) {
149 Q_UNUSED(engine);
150 Q_UNUSED(scriptEngine);
151
152 return Handy::instance();
153 }
154
155 void setTransientTouchInput(bool touch);
156 bool hasTransientTouchInput() const;
157
158protected:
159
160 /**
161 * @private
162 */
163 bool eventFilter(QObject *watched, QEvent *event) override;
164
165private:
166
167 MauiMan::FormFactorManager *m_formFactor;
168 MauiMan::AccessibilityManager *m_accessibility;
169
170 FFactor m_ffactor = FFactor::Desktop;
171 bool m_isTouch = false;
172 bool m_singleClick = true;
173 bool m_mobile = 1;
174 bool m_hasTransientTouchInput = 1;
175
176public Q_SLOTS:
177
178 /**
179 * @brief Returns the major version of the current OS
180 *
181 * This function is static.
182 * @return Major OS version number
183 */
184 static int version();
185
186 /**
187 * @brief Returns a key-value map containing basic information about the current user
188 *
189 * The pairs keys for the information returned are:
190 * - name
191 *
192 * @return with user info map
193 */
194 static QVariantMap userInfo();
195
196 /**
197 * @brief Returns the text contained in the clipboard
198 * @return text string
199 */
200 static QString getClipboardText();
201
202 /**
203 * @brief Retrieves the data in the clipboard into a key-value map.
204 * The possible keys available are [only if there is any metadata]:
205 * - text
206 * - urls
207 * - image
208 * - cut
209 *
210 * @note This can invoked from QML and the data extracted as `Handy.getClipboard().text` for example.
211 */
212 static QVariantMap getClipboard();
213
214 /**
215 * @brief Copies a text string to the clipboard
216 * @param text text to be copied to the clipboard
217 * @return whether the operation was successful
218 */
219 static bool copyTextToClipboard(const QString &text);
220
221 /**
222 * @brief Adds a key-value map to the clipboard.
223 * Possible keys can be:
224 * - text
225 * - urls
226 * - image
227 *
228 * There can be more than one.
229 * @param value the data
230 * @param cut whether to add the metadata information necessary for it to be read as a cut operation by third party.
231 * @return whether the operation was successful
232 */
233 static bool copyToClipboard(const QVariantMap &value, const bool &cut = false);
234
235 bool hasKeyboard();
236
237 bool hasMouse();
238
239 static bool isAndroid();
240
241 static bool isWindows();
242
243 static bool isMac();
244
245 static bool isLinux();
246
247 static bool isIOS();
248
249 bool isMobile() const;
250
251 bool isTouch();
252
253 FFactor formFactor();
254
255 /**
256 * @brief Format a size value to the a readable locale size format.
257 * @param size the size value in bits
258 * @return Formatted into a readable string using the preferred locale settings.
259 */
260 static QString formatSize(quint64 size);
261
262 /**
263 * @brief Format a milliseconds value to a readable format
264 * @param value milliseconds
265 * @return readable formatted value
266 */
267 static QString formatTime(const qint64 &value);
268
269 /**
270 * @brief Given a date string, its original format and an intended format, return a readable string
271 * @param dateStr date string
272 * @param format Intended format, by default `"dd/MM/yyyy"`
273 * @param initFormat the original date format. This is optional and by default it will try to be auto determined.
274 * @return
275 */
276 static QString formatDate(const QString &dateStr, const QString &format = QString("dd/MM/yyyy"), const QString &initFormat = QString());
277
279
280 void singleClickChanged();
281 void hasKeyboardChanged();
282 void hasMouseChanged();
283 void isMobileChanged();
284 void hasTransientTouchInputChanged();
285 void formFactorChanged();
286 void isTouchChanged();
287};
288
The Handy class.
Definition handy.h:41
FFactor formFactor
The current preferred from factor the user has selected.
Definition handy.h:109
bool isTouch
Whether the target device has a touch screen.
Definition handy.h:55
static int version()
Returns the major version of the current OS.
Definition handy.cpp:267
QML_SINGLETONbool isMobile
Whether the host platform is set as mobile.
Definition handy.h:50
static QVariantMap getClipboard()
Retrieves the data in the clipboard into a key-value map.
Definition handy.cpp:191
static QString formatTime(const qint64 &value)
Format a milliseconds value to a readable format.
Definition handy.cpp:322
FFactor
The different form factor options.
Definition handy.h:118
@ Phone
Mobile form factor mode assumes a phone is the target device.
Definition handy.h:132
@ Desktop
Desktop form factor assumes there is a physical mouse and keyboard, and the screen area is wide and s...
Definition handy.h:122
@ Tablet
Tablet form factor assumes a hand held device with touch screen, maybe there is a physical keyboard a...
Definition handy.h:127
bool isLinux
Whether the host platform is a GNU/Linux distribution.
Definition handy.h:80
bool isMac
Whether the host platform is running MacOS.
Definition handy.h:90
bool hasMouse
Whether the target device has a physical mouse attached.
Definition handy.h:60
bool isWindows
Whether the host platform is running Windows OS.
Definition handy.h:85
static QString getClipboardText()
Returns the text contained in the clipboard.
Definition handy.cpp:176
bool singleClick
Whether the system preference is to open/trigger items with a single click.
Definition handy.h:101
bool hasKeyboard
Whether the target device has a physical keyboard attached.
Definition handy.h:65
static bool copyToClipboard(const QVariantMap &value, const bool &cut=false)
Adds a key-value map to the clipboard.
Definition handy.cpp:226
bool isIOS
Whether the host platform is running IOS.
Definition handy.h:95
static QString formatDate(const QString &dateStr, const QString &format=QString("dd/MM/yyyy"), const QString &initFormat=QString())
Given a date string, its original format and an intended format, return a readable string.
Definition handy.cpp:314
static QVariantMap userInfo()
Returns a key-value map containing basic information about the current user.
Definition handy.cpp:167
bool hasTransientTouchInput
Whether the current press input has been received from a touch screen.
Definition handy.h:70
bool isAndroid
Whether the host platform is an Android device.
Definition handy.h:75
static bool copyTextToClipboard(const QString &text)
Copies a text string to the clipboard.
Definition handy.cpp:257
static QString formatSize(quint64 size)
Format a size value to the a readable locale size format.
Definition handy.cpp:308
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
virtual bool event(QEvent *e)
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 12:00:22 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.