En esta página

Ejemplo de plugin de backend para calendario

QCalendar Ejemplo que ilustra los calendarios personalizados proporcionados por el usuario.

Widget de calendario que muestra octubre de 1582 con el intervalo de transición del calendario juliano al gregoriano

Introducción

Existen numerosos sistemas de calendario diferentes en uso en todo el mundo. Qt ofrece compatibilidad integrada con algunos de ellos (véase System), pero no puede proporcionar compatibilidad general debido a su gran número. Se pueden añadir sistemas de calendario adicionales implementando un QCalendarBackend personalizado, que es una API privada.

Este ejemplo muestra cómo escribir un backend de calendario personalizado y cómo utilizar la API de complementos de bajo nivel para ampliar una aplicación con calendarios seleccionables por el usuario. Muchos países pasaron del calendario juliano al gregoriano en algún momento de su historia, y este backend de calendario personalizado implementará el calendario correspondiente a modo de ejemplo. El backend personalizado se compila en un complemento y la aplicación principal lo carga en tiempo de ejecución. La fecha exacta de la transición, que varía según las regiones, se proporciona al complemento como una cadena de caracteres y puede ser determinada por el usuario.

Backend del calendario

La clase del backend del calendario debe heredar de ` QCalendarBackend ` e implementar sus funciones virtuales puras de forma « thread-safe ». También puede sobrescribir otras funciones virtuales según sea necesario.

Ejemplo de implementación

Este ejemplo hereda de la clase ya existente ` QRomanCalendar`, que a su vez hereda de ` QCalendarBackend ` e implementa algunas de sus funciones virtuales. Resulta constructivo hacerlo así porque el calendario de transición comparte, tanto con el calendario juliano como con el gregoriano, elementos proporcionados por el calendario romano.

A continuación se muestra la declaración de la clase ` JulianGregorianCalendar`:

class JulianGregorianCalendar : public QRomanCalendar
{
public:
    JulianGregorianCalendar(QDate endJulian, QAnyStringView name);
    QString name() const override;
    int daysInMonth(int month, int year = QCalendar::Unspecified) const override;
    bool isLeapYear(int year) const override;
    bool dateToJulianDay(int year, int month, int day, qint64 *jd) const override;
    QCalendar::YearMonthDay julianDayToDate(qint64 jd) const override;
private:
    static inline const QCalendar julian = QCalendar(QCalendar::System::Julian);
    static inline const QCalendar gregorian = QCalendar(QCalendar::System::Gregorian);
    QCalendar::YearMonthDay m_julianUntil;
    QCalendar::YearMonthDay m_gregorianSince;
    QString m_name;
};

El objeto ` QDate ` pasado al constructor —` endJulian `— es la fecha del último día del calendario juliano. El calendario calculará automáticamente el desfase para un año determinado; por ejemplo, en 1582 se omitieron 10 días, pero en 1700 hubo que omitir 12 días. El backend del calendario está registrado con el nombre « name » y se puede crear una instancia del calendario utilizando ese nombre. La clase solo sobrescribe las funciones en las que los dos calendarios que combina difieren del calendario romano de referencia. Cuenta con instancias de los calendarios juliano y gregoriano a las que estas funciones pueden delegar.

Conversiones de días julianos

dateToJulianDay(int year, int month, int day, qint64 *jd) calcula el número de día juliano correspondiente a las fechas especificadas year, month y day. Devuelve true y establece jd si existe dicha fecha en este calendario; de lo contrario, devuelve false.

bool JulianGregorianCalendar::dateToJulianDay(int year, int month, int day, qint64 *jd) const
{
    if (year == m_julianUntil.year && month == m_julianUntil.month) {
        if (m_julianUntil.day < day && day < m_gregorianSince.day) {
            // Requested date is in the gap skipped over by the transition.
            *jd = 0;
            return false;
        }
    }
    QDate givenDate = gregorian.dateFromParts(year, month, day);
    QDate julianUntil = julian.dateFromParts(m_julianUntil);
    if (givenDate > julianUntil) {
        *jd = givenDate.toJulianDay();
        return true;
    }
    *jd = julian.dateFromParts(year, month, day).toJulianDay();
    return true;
}

julianDayToDate(qint64 jd) calcula el año, el mes y el día en este calendario a partir del número de día juliano dado, jd. Si el día dado queda fuera del ámbito de este calendario, el valor de retorno para isValid() es false. En este ejemplo, si la fecha dada se encuentra en el intervalo omitido por la transición del calendario juliano al gregoriano, queda fuera del ámbito.

QCalendar::YearMonthDay JulianGregorianCalendar::julianDayToDate(qint64 jd) const
{
    const qint64 jdForChange = julian.dateFromParts(m_julianUntil).toJulianDay();
    if (jdForChange < jd) {
        QCalendar gregorian(QCalendar::System::Gregorian);
        QDate date = QDate::fromJulianDay(jd);
        return gregorian.partsFromDate(date);
    } else if (jd <= jdForChange) {
        QCalendar julian(QCalendar::System::Julian);
        QDate date = QDate::fromJulianDay(jd);
        return julian.partsFromDate(date);
    }
    return QCalendar::YearMonthDay(QCalendar::Unspecified, QCalendar::Unspecified,
                                   QCalendar::Unspecified);
}
Compatibilidad con configuraciones regionales

En general, un calendario puede tener su propia denominación de los meses del año y los días de la semana. Estas denominaciones deben estar debidamente adaptadas a la configuración regional para que resulten comprensibles para todos los usuarios. Por defecto, la clase base del backend se encarga de los nombres de los días de la semana, lo cual es totalmente suficiente para estos calendarios de transición entre el juliano y el gregoriano.

Aunque un backend puede anular directamente los métodos de denominación de los meses, la versión de la clase base de estos se puede personalizar implementando localeMonthData() y localeMonthIndexData() para proporcionar tablas de nombres de meses localizados. Dado que los calendarios juliano y gregoriano utilizan la misma nomenclatura de meses, heredan esa personalización de una clase base común, QRomanCalendar. Esto también significa que el calendario personalizado puede utilizar los mismos nombres, de nuevo heredando de esa clase base. De este modo queda resuelta la localización.

Complemento

Las aplicaciones Qt pueden ampliarse mediante complementos. Para ello, la aplicación debe detectar y cargar los complementos utilizando QPluginLoader.

Cómo escribir un complemento

Para escribir un complemento, lo primero que hay que hacer es crear una clase virtual pura que defina la interfaz entre el complemento y la aplicación.

En este ejemplo se ha utilizado la siguiente interfaz:

class RequestedCalendarInterface
{
public:
    RequestedCalendarInterface() = default;
    virtual QCalendar::SystemId loadCalendar(QAnyStringView requested) = 0;
    virtual ~RequestedCalendarInterface() = default;
};

y registrarla en el sistema de metaobjetos de Qt:

#define RequestedCalendarInterface_iid \
"org.qt-project.Qt.Examples.CalendarBackend.RequestedCalendarInterface/1.0"
Q_DECLARE_INTERFACE(RequestedCalendarInterface, RequestedCalendarInterface_iid)

Q_DECLARE_INTERFACELa macro () se utiliza para asociar el « ClassName » (en este caso: RequestedCalendarInterface) con el « Identifier » definido (en este caso: RequestedCalendarInterface_iid). La interfaz « Identifier » debe ser única. Esta interfaz puede ser implementada por complementos que carguen otros calendarios, interpretando el parámetro de cadena de « loadCalendar() » de diversas formas. No se limita al complemento concreto que se va a implementar utilizando esta interfaz, por lo que tiene un nombre genérico, y no uno específico para este backend en particular.

A continuación, se crea una clase de complemento que hereda de « QObject » y de la interfaz.

class JulianGregorianPlugin : public QObject, public RequestedCalendarInterface
{
    Q_OBJECT
    Q_INTERFACES(RequestedCalendarInterface)
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples."
                          "CalendarBackend."
                          "RequestedCalendarInterface/1.0")
public:
    JulianGregorianPlugin();
    QCalendar::SystemId loadCalendar(QAnyStringView request) override;
    ~JulianGregorianPlugin();
};

Q_PLUGIN_METADATASe utilizan () y Q_INTERFACES() para declarar los metadatos que también se declararon en la clase de interfaz y para indicar a Qt qué interfaz implementa la clase.

Este complemento crea una instancia y registra un backend de calendario personalizado que, a su vez, puede ser utilizado por la aplicación para crear una instancia de ` QCalendar ` en cualquier momento.

Los complementos de Qt se almacenan en una única biblioteca compartida (una DLL) y se utiliza QPluginLoader para detectar y cargar dinámicamente el archivo del complemento (para más información, consulta «Cómo crear complementos de Qt»).

Carga del complemento

QPluginLoader comprueba si la versión de Qt del complemento es la misma que la de la aplicación y proporciona acceso directo a un complemento de Qt.

A continuación se muestra el uso de ` QPluginLoader ` en el ejemplo:

    QPluginLoader loader;
    loader.setFileName("../plugin/calendarPlugin");
    loader.load();
    if (!loader.isLoaded())
        return 1;
    auto *myplugin = qobject_cast<RequestedCalendarInterface*>(loader.instance());

En primer lugar, hay que inicializar una instancia de un objeto ` QPluginLoader `. A continuación, hay que especificar qué complemento se va a cargar pasando el nombre de un archivo DLL a ` setFileName()`. Después, mediante ` load()`, se carga dinámicamente el archivo del complemento. Por último, una llamada a qobject_cast() comprueba si un complemento implementa una interfaz determinada. qobject_cast() utiliza instance() para acceder al componente raíz del complemento. Si el complemento se ha cargado correctamente, sus funciones deberían estar disponibles.

Instanciación del backend

En este ejemplo solo hay una función en el complemento. ` loadCalendar() ` se encarga de registrar el backend de calendario personalizado en ` QCalendarRegistry ` con la fecha de transición y los nombres indicados.

QCalendar::SystemId JulianGregorianPlugin::loadCalendar(QAnyStringView request)
{
    Q_ASSERT(!request.isEmpty());
    QStringList names = request.toString().split(u';');
    if (names.size() < 1)
        return {};
    QString dateString = names.takeFirst();
    auto date = QDate::fromString(dateString, u"yyyy-MM-dd",
                                  QCalendar(QCalendar::System::Julian));
    if (!date.isValid())
        return {};
    QString primary = names.isEmpty() ?
            QString::fromStdU16String(u"Julian until ") + dateString : names[0];
    auto backend = new JulianGregorianCalendar(date, primary);
    names.emplaceFront(backend->name());
    auto cid = backend->registerCustomBackend(names);
    return cid;
}

JulianGregorianPlugin::~JulianGregorianPlugin()
{
}

El usuario proporciona el argumento de cadena para ` loadCalendar() ` a través de los argumentos de la línea de comandos. A continuación, se extrae la fecha de transición del calendario juliano al gregoriano dividiendo la cadena proporcionada. Tras la validación, se crea un objeto de backend personalizado. El backend debe registrarse antes de poder utilizarse en QCalendar, mediante el método registerCustomBackend(). Una vez registrado el backend, se puede instanciar un QCalendar con el SystemId o el name correspondiente.

A continuación se muestra el uso de ` loadCalendar ` en ` main`:

   const auto cid = myplugin->loadCalendar(args.at(0));
    if (!cid.isValid()) {
        qWarning() << "Invalid ID";
        parser.showHelp(1);
    }
    const QCalendar calendar(cid);
Ampliación de QCalendarWidget

Al crear una instancia de ` QCalendar ` con un calendario específico como backend, es posible proporcionar ese backend a ` QCalendarWidget ` y visualizarlo.

    QCalendarWidget widget;
    widget.setCalendar(calendar);
    widget.show();
    QCalendar::YearMonthDay when = { 1582, 10, 4 };
    QCalendar julian = QCalendar(QCalendar::System::Julian);
    auto got = QDate::fromString(args.at(0).left(10), u"yyyy-MM-dd", julian);
    if (got.isValid())
        when = julian.partsFromDate(got);
    widget.setCurrentPage(when.year, when.month);

Proyecto de ejemplo en code.qt.io

Véase también QCalendarWidget, QCalendar, QDate, QLocale, QtPlugin y QPluginLoader.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.