MessageCore::DateFormatter Class

class MessageCore::DateFormatter

A class for abstracting date formatting. More...

Header: #include <MessageCore/DateFormatter>
CMake: find_package(KPim6MessageCore REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::MessageCore)

Public Types

enum FormatType { CTime, Localized, Fancy, Custom }

Public Functions

DateFormatter(MessageCore::DateFormatter::FormatType ftype = DateFormatter::Fancy)
~DateFormatter()
QString customFormat() const
QString dateString(const QDateTime &dtime, const QString &lang = QString(), bool shortFormat = true) const
MessageCore::DateFormatter::FormatType format() const
void invalidateReferenceDate() const
void setCustomFormat(const QString &format)
void setFormat(MessageCore::DateFormatter::FormatType ftype)

Static Public Members

QString formatCurrentDate(MessageCore::DateFormatter::FormatType ftype, const QString &data = QString(), bool shortFormat = true)
QString formatDate(MessageCore::DateFormatter::FormatType ftype, const QDateTime &t, const QString &data = QString(), bool shortFormat = true)

Detailed Description

This class deals with different kinds of date display formats. The formats supported include: - @b fancy "Today 02:08:35" - @b ctime as with the ctime function, eg. "Sun Mar 31 02:08:35 2002" - @b localized according to the control center setting, eg. "2002-03-31 02:08" - @b custom "whatever you like"

Note: If a long-lived instance of this class is kept, its owner is responsible for calling `invalidateReferenceDate()` on date changes. This ensures that the `Fancy` formatter has an up-to-date notion of "Today", "Yesterday" etc.

Member Type Documentation

enum DateFormatter::FormatType

The different types of date formats.

Member Function Documentation

[explicit] DateFormatter::DateFormatter(MessageCore::DateFormatter::FormatType ftype = DateFormatter::Fancy)

Constructs a date formatter with a default #FormatType.

ftype is the default #FormatType to use.

[noexcept] DateFormatter::~DateFormatter()

Destroys the date formatter.

QString DateFormatter::customFormat() const

Returns the custom format string.

See also setCustomFormat().

QString DateFormatter::dateString(const QDateTime &dtime, const QString &lang = QString(), bool shortFormat = true) const

Constructs a formatted date string from QDateTime dtime.

dtime is the QDateTime to use for formatting. lang is the language, only used if #FormatType is #Localized. shortFormat if true, create the short version of the date string, only used if #FormatType is #Localized.

Returns a QString containing the formatted date.

MessageCore::DateFormatter::FormatType DateFormatter::format() const

Returns the #FormatType currently set.

See also setFormat().

[static] QString DateFormatter::formatCurrentDate(MessageCore::DateFormatter::FormatType ftype, const QString &data = QString(), bool shortFormat = true)

Convenience function, same as formatDate() but returns the current time formatted.

ftype is the #FormatType to use. data is either the format when #FormatType is Custom, or language when #FormatType is #Localized. shortFormat if true, create the short version of the date string, only used if #FormatType is #Localized.

Returns a QString containing the formatted date.

[static] QString DateFormatter::formatDate(MessageCore::DateFormatter::FormatType ftype, const QDateTime &t, const QString &data = QString(), bool shortFormat = true)

Convenience function dateString

ftype is the #FormatType to use. t is the time to use for formatting. data is either the format when #FormatType is Custom, or language when #FormatType is #Localized. shortFormat if true, create the short version of the date string, only used if #FormatType is #Localized.

Returns a QString containing the formatted date.

void DateFormatter::invalidateReferenceDate() const

Invalidates the cached reference date used by the `Fancy` formatter to determine the meaning of "Today", "Yesterday" etc.

void DateFormatter::setCustomFormat(const QString &format)

Sets the custom format for date to string conversions to format. This method accepts the same arguments as QDateTime::toString(), but also supports the "Z" expression which is substituted with the RFC2822 (Section 3.3) style numeric timezone (-0500).

format is a QString containing the custom format.

See also QDateTime::toString() and customFormat().

void DateFormatter::setFormat(MessageCore::DateFormatter::FormatType ftype)

Sets the date format to ftype.

ftype is the #FormatType.

See also format().