Skip to content
AtlasOSFramework API
Browse the docs

AtlasFormat

A singleton that formats sizes, speeds, percentages, numbers, durations and dates alike in every Atlas app and in the user's language.

Since 1.4.0

AtlasFormat shows sizes, speeds, percentages, numbers, durations and dates one way, so every Atlas app spells them alike. Every function takes an optional last locale argument ("de_DE", "en"); without one it uses the application's QLocale.

Example

Column {
    Label { text: AtlasFormat.bytes(file.size) }                  // "1.5 MiB"
    Label { text: AtlasFormat.percent(progress) }                 // "42%"
    Label { text: AtlasFormat.duration(remaining) }               // "1 h 5 min"
    Label { text: AtlasFormat.date(modified, "relative") }        // "5 minutes ago"
}

Note

The unit and wording strings belong to Atlas.Ui and are translated with its catalogue. A translation follows the application's language, not the locale argument: that one only decides digits, separators and date formats.

A value that is not a number (NaN, infinity), or a date that is invalid, gives "", never "NaN". A negative size or duration keeps its sign. An unknown duration or date style is treated as the default one.

Methods

Each method can be called with fewer arguments; the later ones take the defaults named below.

Signature Description
bytes(double n): QString Formats a byte count with IEC units: "0 B", "512 B", "1.5 KiB", "3.2 GiB". precision is 0 to 10 (default 1); other values are clamped.
bytes(double n, int precision): QString Same, with the extra argument set.
bytes(double n, int precision, QString locale): QString Same, with the extra argument set.
bytesPerSecond(double n): QString Like bytes, as a speed: "1.5 MiB/s". precision is clamped to 0 to 10 the same way.
bytesPerSecond(double n, int precision): QString Same, with the extra argument set.
bytesPerSecond(double n, int precision, QString locale): QString Same, with the extra argument set.
date(QDateTime d): QString Formats a date. style is "short" (default), "long", "dateTime", "time", "atTime" ("today at 14:05") or "relative" ("just now", "3 hours ago", "yesterday", "in 5 minutes"; a date a week or more away shows its short form). atTime gives "yesterday at 14:05" for the previous day and "the short date, then "at" and the time" for any other day. atTime and relative compare with now (default: the current time). An invalid date gives "".
date(QDateTime d, QString style): QString Same, with the extra argument set.
date(QDateTime d, QString style, QString locale): QString Same, with the extra argument set.
date(QDateTime d, QString style, QString locale, QDateTime now): QString Same, with the extra argument set.
duration(double seconds): QString Formats a number of seconds. style is "short" (default; "1 h 5 min"), "long" ("1 hour 5 minutes") or "clock" ("1:05:09", "05:09"). The largest non-zero unit is shown, plus the next one only when it is not zero, in both short and long: 3605 s gives "1 h" and 65 s gives "1 min 5 s". The input is clamped. A negative duration keeps its sign.
duration(double seconds, QString style): QString Same, with the extra argument set.
duration(double seconds, QString style, QString locale): QString Same, with the extra argument set.
number(double n): QString Formats a number grouped by the locale. precision -1 (default; any negative value) is the shortest exact form, up to 6 decimals; otherwise 0 to 10, clamped.
number(double n, int precision): QString Same, with the extra argument set.
number(double n, int precision, QString locale): QString Same, with the extra argument set.
percent(double fraction): QString Formats a fraction as a percentage: 0.423 gives "42%" (en) or "42 %" (de). precision defaults to 0 and is clamped to 0 to 10.
percent(double fraction, int precision): QString Same, with the extra argument set.
percent(double fraction, int precision, QString locale): QString Same, with the extra argument set.