1/*
2 SPDX-FileCopyrightText: 2014 Bhushan Shah <bhush94@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7#ifndef FORMATS_H
8#define FORMATS_H
9
10#include <KFormat>
11#include <QObject>
12#include <QQmlEngine>
13
14namespace FormatTypes
15{
16Q_NAMESPACE
17QML_NAMED_ELEMENT(FormatTypes)
18QML_FOREIGN_NAMESPACE(KFormat)
19}
20
21/*!
22 * \qmltype Format
23 * \inqmlmodule org.kde.coreaddons
24 *
25 * \brief Provides support for formatting numbers and datetimes in
26 * formats that are not supported by QLocale.
27 *
28 * \sa KFormat
29 */
30class Formats : public QObject
31{
32 Q_OBJECT
33 QML_NAMED_ELEMENT(Format)
34 QML_SINGLETON
35
36public:
37 /*!
38 * \qmlmethod string Format::formatByteSize(double size, int precision = 1)
39 *
40 * Converts \a size from bytes to the appropriate string representation
41 */
42 Q_INVOKABLE QString formatByteSize(double size, int precision = 1) const;
43
44 /*!
45 * \qmlmethod string Format::formatDuration(int msecs, KFormat::DurationFormatOptions options = KFormat::DefaultDuration)
46 *
47 * Given a number of milliseconds, converts that to a string containing
48 * the localized equivalent, e.g. 1:23:45
49 */
50 Q_INVOKABLE QString formatDuration(quint64 msecs, KFormat::DurationFormatOptions options = KFormat::DefaultDuration) const;
51
52 /*!
53 * \qmlmethod string Format::formatDecimalDuration(int msecs, int decimalPlaces = 2)
54 *
55 * Given a number of milliseconds, converts that to a string containing
56 * the localized equivalent to the requested decimal places.
57 *
58 * e.g. given formatDuration(60000), returns "1.0 minutes"
59 */
60 Q_INVOKABLE QString formatDecimalDuration(quint64 msecs, int decimalPlaces = 2) const;
61
62 /*!
63 * \qmlmethod string Format::formatSpelloutDuration(int msecs)
64 *
65 * Given a number of milliseconds, converts that to a spell-out string containing
66 * the localized equivalent.
67 *
68 * e.g. given formatSpelloutDuration(60001) returns "1 minute"
69 * given formatSpelloutDuration(62005) returns "1 minute and 2 seconds"
70 * given formatSpelloutDuration(90060000) returns "1 day and 1 hour"
71 *
72 * Units not interesting to the user, for example seconds or minutes when the first
73 * unit is day, are not returned because they are irrelevant. The same applies for
74 * seconds when the first unit is hour.
75 *
76 */
77 Q_INVOKABLE QString formatSpelloutDuration(quint64 msecs) const;
78
79 /*!
80 * \qmlmethod string Format::formatRelativeDate(date date, format)
81 *
82 * Returns a string formatted to a relative date style.
83 *
84 * If the date falls within one week before or after the current date
85 * then a relative date string will be returned, such as:
86 * \list
87 * \li Yesterday
88 * \li Today
89 * \li Tomorrow
90 * \li Last Tuesday
91 * \li Next Wednesday
92 * \endlist
93 * If the date falls outside this period then the format is used
94 */
95 Q_INVOKABLE QString formatRelativeDate(const QDate &date, QLocale::FormatType format) const;
96
97 /*!
98 * \qmlmethod string Format::formatRelativeDate(QDateTime date, format)
99 *
100 * Returns a string formatted to a relative datetime style.
101 *
102 * If the dateTime falls within one week before or after the current date
103 * then a relative date string will be returned, such as:
104 * \list
105 * \li Yesterday, 3:00pm
106 * \li Today, 3:00pm
107 * \li Tomorrow, 3:00pm
108 * \li Last Tuesday, 3:00pm
109 * \li Next Wednesday, 3:00pm
110 * \endlist
111 *
112 * If the datetime falls outside this period then the format is used
113 */
114 Q_INVOKABLE QString formatRelativeDateTime(const QDateTime &dateTime, QLocale::FormatType format) const;
115
116 /*!
117 * \qmlmethod string Format::formatTime(var object, string propertyName, int format, int options)
118 *
119 * Applies time formatting to the QDateTime value found in the property \a propertyName in object \a object.
120 * This indirection is necessary to avoid the QDateTime value to ever be exposed to QML's JS runtime,
121 * which would destroy its timezone information.
122 * The formatting itself is done via KFormat::formatTime, see that for \a format and \a options.
123 *
124 * \since 6.16
125 */
126 Q_INVOKABLE [[nodiscard]] QString formatTime(const QVariant &obj,
127 const QString &propertyName,
128 QLocale::FormatType format = QLocale::ShortFormat,
129 KFormat::TimeFormatOptions options = KFormat::DoNotAddTimeZone) const;
130
131 /*!
132 * \qmlmethod string Format::formatDistance(real distance, enumeration options)
133 *
134 * Formats a distance value given in meters in appropriate units for
135 * displaying.
136 *
137 * Unless explicitly forced to metric units this uses units approrpiate for
138 * the current locale.
139 */
140 Q_INVOKABLE [[nodiscard]] QString formatDistance(double distance, KFormat::DistanceFormatOptions options = KFormat::LocaleDistanceUnits) const;
141
142private:
143 const KFormat m_format;
144};
145
146#endif
147

source code of kcoreaddons/src/qml/formats.h