KCoreAddons

formats.h
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
13class Formats : public QObject
14{
16
17public:
18 /**
19 * Converts size from bytes to the appropriate string representation
20 */
21 Q_INVOKABLE QString formatByteSize(double size, int precision = 1) const;
22
23 /**
24 * Given a number of milliseconds, converts that to a string containing
25 * the localized equivalent, e.g. 1:23:45
26 */
27 Q_INVOKABLE QString formatDuration(quint64 msecs, KFormat::DurationFormatOptions options = KFormat::DefaultDuration) const;
28
29 Q_DECLARE_FLAGS(DurationFormatOptions, KFormat::DurationFormatOption)
30
31 /**
32 * This overload exists so it can be called from QML, which does
33 * not support calling Q_INVOKABLEs with Q_ENUMS from different classes
34 *
35 * This is mentioned in the docs and also in https://bugreports.qt.io/browse/QTBUG-20639
36 * Until that bug is fixed, we'll need this
37 */
38 Q_INVOKABLE QString formatDuration(quint64 msecs, int options) const;
39
40 /**
41 * Given a number of milliseconds, converts that to a string containing
42 * the localized equivalent to the requested decimal places.
43 *
44 * e.g. given formatDuration(60000), returns "1.0 minutes"
45 */
46 Q_INVOKABLE QString formatDecimalDuration(quint64 msecs, int decimalPlaces = 2) const;
47
48 /**
49 * Given a number of milliseconds, converts that to a spell-out string containing
50 * the localized equivalent.
51 *
52 * e.g. given formatSpelloutDuration(60001) returns "1 minute"
53 * given formatSpelloutDuration(62005) returns "1 minute and 2 seconds"
54 * given formatSpelloutDuration(90060000) returns "1 day and 1 hour"
55 *
56 * Units not interesting to the user, for example seconds or minutes when the first
57 * unit is day, are not returned because they are irrelevant. The same applies for
58 * seconds when the first unit is hour.
59 *
60 */
61 Q_INVOKABLE QString formatSpelloutDuration(quint64 msecs) const;
62
63 /**
64 * Returns a string formatted to a relative date style.
65 *
66 * If the date falls within one week before or after the current date
67 * then a relative date string will be returned, such as:
68 * * Yesterday
69 * * Today
70 * * Tomorrow
71 * * Last Tuesday
72 * * Next Wednesday
73 *
74 * If the date falls outside this period then the format is used
75 */
76 Q_INVOKABLE QString formatRelativeDate(const QDate &date, QLocale::FormatType format) const;
77
78 /**
79 * Returns a string formatted to a relative datetime style.
80 *
81 * If the dateTime falls within one week before or after the current date
82 * then a relative date string will be returned, such as:
83 * * Yesterday, 3:00pm
84 * * Today, 3:00pm
85 * * Tomorrow, 3:00pm
86 * * Last Tuesday, 3:00pm
87 * * Next Wednesday, 3:00pm
88 *
89 * If the datetime falls outside this period then the format is used
90 */
91 Q_INVOKABLE QString formatRelativeDateTime(const QDateTime &dateTime, QLocale::FormatType format) const;
92
93private:
94 const KFormat m_format;
95};
96
97#endif
KFormat provides support for formatting numbers and datetimes in formats that are not supported by QL...
Definition kformat.h:59
DurationFormatOption
Format flags for formatDuration()
Definition kformat.h:183
@ DefaultDuration
Default formatting in localized 1:23:45 format.
Definition kformat.h:184
Q_INVOKABLEQ_INVOKABLE
Q_OBJECTQ_OBJECT
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 7 2024 12:01:00 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.