QCalendarWidget Class
La clase QCalendarWidget ofrece un widget de calendario mensual que permite al usuario seleccionar una fecha. Más información...
| Encabezado: | #include <QCalendarWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredan: | QWidget |
Tipos públicos
| enum | HorizontalHeaderFormat { SingleLetterDayNames, ShortDayNames, LongDayNames, NoHorizontalHeader } |
| enum | SelectionMode { NoSelection, SingleSelection } |
| enum | VerticalHeaderFormat { ISOWeekNumbers, NoVerticalHeader } |
Propiedades
|
|
Funciones públicas
| QCalendarWidget(QWidget *parent = nullptr) | |
| virtual | ~QCalendarWidget() |
| QCalendar | calendar() const |
| void | clearMaximumDate() |
| void | clearMinimumDate() |
| int | dateEditAcceptDelay() const |
| QMap<QDate, QTextCharFormat> | dateTextFormat() const |
| QTextCharFormat | dateTextFormat(QDate date) const |
| Qt::DayOfWeek | firstDayOfWeek() const |
| QTextCharFormat | headerTextFormat() const |
| QCalendarWidget::HorizontalHeaderFormat | horizontalHeaderFormat() const |
| bool | isDateEditEnabled() const |
| bool | isGridVisible() const |
| bool | isNavigationBarVisible() const |
| QDate | maximumDate() const |
| QDate | minimumDate() const |
| int | monthShown() const |
| QDate | selectedDate() const |
| QCalendarWidget::SelectionMode | selectionMode() const |
| void | setCalendar(QCalendar c) |
| void | setDateEditAcceptDelay(int delay) |
| void | setDateEditEnabled(bool enable) |
| void | setDateTextFormat(QDate date, const QTextCharFormat &format) |
| void | setFirstDayOfWeek(Qt::DayOfWeek dayOfWeek) |
| void | setHeaderTextFormat(const QTextCharFormat &format) |
| void | setHorizontalHeaderFormat(QCalendarWidget::HorizontalHeaderFormat format) |
| void | setMaximumDate(QDate date) |
| void | setMinimumDate(QDate date) |
| void | setSelectionMode(QCalendarWidget::SelectionMode mode) |
| void | setVerticalHeaderFormat(QCalendarWidget::VerticalHeaderFormat format) |
| void | setWeekdayTextFormat(Qt::DayOfWeek dayOfWeek, const QTextCharFormat &format) |
| QCalendarWidget::VerticalHeaderFormat | verticalHeaderFormat() const |
| QTextCharFormat | weekdayTextFormat(Qt::DayOfWeek dayOfWeek) const |
| int | yearShown() const |
Funciones públicas reimplementadas
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Ranuras públicas
| void | setCurrentPage(int year, int month) |
| void | setDateRange(QDate min, QDate max) |
| void | setGridVisible(bool show) |
| void | setNavigationBarVisible(bool visible) |
| void | setSelectedDate(QDate date) |
| void | showNextMonth() |
| void | showNextYear() |
| void | showPreviousMonth() |
| void | showPreviousYear() |
| void | showSelectedDate() |
| void | showToday() |
Señales
| void | activated(QDate date) |
| void | clicked(QDate date) |
| void | currentPageChanged(int year, int month) |
| void | selectionChanged() |
Funciones protegidas
| virtual void | paintCell(QPainter *painter, const QRect &rect, QDate date) const |
| void | updateCell(QDate date) |
| void | updateCells() |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *watched, QEvent *event) override |
| virtual void | keyPressEvent(QKeyEvent *event) override |
| virtual void | mousePressEvent(QMouseEvent *event) override |
| virtual void | resizeEvent(QResizeEvent *event) override |
Descripción detallada

El widget se inicializa con el mes y el año actuales, pero QCalendarWidget proporciona varias ranuras públicas para cambiar el año y el mes que se muestran.
Por defecto, se selecciona la fecha de hoy, y el usuario puede seleccionar una fecha tanto con el ratón como con el teclado. La fecha seleccionada actualmente se puede recuperar mediante la función ` selectedDate()`. Es posible restringir la selección del usuario a un intervalo de fechas determinado configurando las propiedades ` minimumDate ` y ` maximumDate `. Alternativamente, ambas propiedades se pueden configurar de una sola vez mediante la ranura de conveniencia ` setDateRange()`. Establece la propiedad ` selectionMode ` en ` NoSelection ` para impedir que el usuario seleccione ninguna fecha. Ten en cuenta que también se puede seleccionar una fecha mediante programación utilizando la ranura ` setSelectedDate()`.
El mes y el año que se muestran actualmente se pueden recuperar mediante las funciones ` monthShown()` y ` yearShown()`, respectivamente.
Un widget de calendario recién creado utiliza nombres abreviados de los días, y tanto los sábados como los domingos aparecen marcados en rojo. La cuadrícula del calendario no es visible. Se muestran los números de semana, y el día de la primera columna es el primer día de la semana según la configuración regional del calendario.
La notación de los días se puede cambiar a abreviaturas de una sola letra («M» para «lunes») estableciendo la propiedad horizontalHeaderFormat en QCalendarWidget::SingleLetterDayNames. Si se establece la misma propiedad en QCalendarWidget::LongDayNames, el encabezado mostrará los nombres completos de los días. Los números de semana se pueden eliminar estableciendo la propiedad « verticalHeaderFormat » en « QCalendarWidget::NoVerticalHeader ». La cuadrícula del calendario se puede activar estableciendo la propiedad « gridVisible » en «true» mediante la función « setGridVisible()»:
|
|
Por último, el día de la primera columna se puede modificar mediante la función setFirstDayOfWeek().
La clase `QCalendarWidget` también proporciona tres señales: ` selectionChanged()`, ` activated()` y ` currentPageChanged()`, que permiten responder a la interacción del usuario.
La visualización de los encabezados, los días de la semana o los días concretos se puede personalizar en gran medida configurando los valores de ` QTextCharFormat` para un día concreto de la semana, una fecha especial o para la visualización de los encabezados.
El widget de calendario solo utiliza un subconjunto de las propiedades de QTextCharFormat. Actualmente, se utilizan las propiedades de primer plano, fondo y fuente para determinar la visualización de las celdas individuales del widget.
Véase también QDate, QDateEdit y QTextCharFormat.
Documentación sobre tipos de miembros
enum QCalendarWidget::HorizontalHeaderFormat
Este tipo de enumeración define los distintos formatos que puede mostrar el encabezado horizontal.
| Constante | Valor | Descripción |
|---|---|---|
QCalendarWidget::SingleLetterDayNames | 1 | El encabezado muestra una abreviatura de una sola letra para los nombres de los días (por ejemplo, «M» para lunes). |
QCalendarWidget::ShortDayNames | 2 | El encabezado muestra una abreviatura corta de los nombres de los días (p. ej., «Mon» para lunes). |
QCalendarWidget::LongDayNames | 3 | El encabezado muestra los nombres completos de los días (p. ej., lunes). |
QCalendarWidget::NoHorizontalHeader | 0 | El encabezado está oculto. |
Véase también horizontalHeaderFormat() y VerticalHeaderFormat.
enum QCalendarWidget::SelectionMode
Esta enumeración describe los tipos de selección que se ofrecen al usuario para elegir fechas en el calendario.
| Constante | Valor | Descripción |
|---|---|---|
QCalendarWidget::NoSelection | 0 | No se pueden seleccionar fechas. |
QCalendarWidget::SingleSelection | 1 | Se pueden seleccionar fechas individuales. |
Véase también selectionMode.
enum QCalendarWidget::VerticalHeaderFormat
Este tipo de enumeración define los distintos formatos que puede mostrar el encabezado vertical.
| Constante | Valor | Descripción |
|---|---|---|
QCalendarWidget::ISOWeekNumbers | 1 | El encabezado muestra los números de semana ISO tal y como se describen en QDate::weekNumber(). |
QCalendarWidget::NoVerticalHeader | 0 | El encabezado está oculto. |
Véase también verticalHeaderFormat() y HorizontalHeaderFormat.
Documentación de la propiedad
dateEditAcceptDelay : int
Esta propiedad indica el tiempo que permanece visible un campo de edición de fecha inactivo antes de que se acepte su contenido
Si el widget de calendario tiene activada la opción « date edit is enabled », esta propiedad especifica el tiempo (en milisegundos) que el campo de edición de fecha permanece abierto tras la última entrada del usuario. Una vez transcurrido este tiempo, se acepta la fecha especificada en el campo de edición y se cierra la ventana emergente.
Por defecto, el retraso está definido en 1500 milisegundos (1,5 segundos).
Funciones de acceso:
| int | dateEditAcceptDelay() const |
| void | setDateEditAcceptDelay(int delay) |
dateEditEnabled : bool
Esta propiedad indica si la ventana emergente de edición de fecha está habilitada
Si esta propiedad está activada, al pulsar una tecla que no sea de modificador se abrirá una ventana emergente de edición de fecha si el widget de calendario tiene el foco, lo que permite al usuario especificar una fecha en el formato establecido por la configuración regional actual.
Por defecto, esta propiedad está activada.
La ventana emergente de edición de fecha tiene un aspecto más sencillo que QDateEdit, pero permite al usuario desplazarse entre los campos con las teclas de cursor izquierda y derecha, aumentar o disminuir los valores de cada campo con las teclas de cursor arriba y abajo, e introducir valores directamente con las teclas numéricas.
Funciones de acceso:
| bool | isDateEditEnabled() const |
| void | setDateEditEnabled(bool enable) |
Véase también QCalendarWidget::dateEditAcceptDelay.
firstDayOfWeek : Qt::DayOfWeek
Esta propiedad contiene un valor que identifica el día que se muestra en la primera columna.
Por defecto, el día que aparece en la primera columna es el primer día de la semana según la configuración regional del calendario.
Funciones de acceso:
| Qt::DayOfWeek | firstDayOfWeek() const |
| void | setFirstDayOfWeek(Qt::DayOfWeek dayOfWeek) |
gridVisible : bool
Esta propiedad determina si se muestra la cuadrícula de la tabla.
![]() |
|
El valor por defecto es «false».
Funciones de acceso:
| bool | isGridVisible() const |
| void | setGridVisible(bool show) |
horizontalHeaderFormat : HorizontalHeaderFormat
Esta propiedad define el formato del encabezado horizontal.
El valor por defecto es « QCalendarWidget::ShortDayNames ».
Funciones de acceso:
| QCalendarWidget::HorizontalHeaderFormat | horizontalHeaderFormat() const |
| void | setHorizontalHeaderFormat(QCalendarWidget::HorizontalHeaderFormat format) |
maximumDate : QDate
Esta propiedad contiene la fecha máxima del intervalo de fechas especificado actualmente.
El usuario no podrá seleccionar una fecha posterior a la fecha máxima establecida actualmente.
|
|
Al establecer una fecha máxima, las propiedades « minimumDate » y « selectedDate » se ajustan si el intervalo de selección deja de ser válido. Si la fecha proporcionada no es un objeto « QDate » válido, la función «setMaximumDate()» no realiza ninguna acción.
La fecha máxima por defecto es el 31 de diciembre del año 9999 d. C. Se puede restablecer este valor por defecto llamando a clearMaximumDate() (a partir de Qt 6.6).
Funciones de acceso:
| QDate | maximumDate() const |
| void | setMaximumDate(QDate date) |
| void | clearMaximumDate() |
Véase también setDateRange().
minimumDate : QDate
Esta propiedad contiene la fecha mínima del intervalo de fechas especificado actualmente.
El usuario no podrá seleccionar una fecha anterior a la fecha mínima establecida actualmente.
|
|
Al establecer una fecha mínima, las propiedades ` maximumDate ` y ` selectedDate ` se ajustan si el intervalo de selección deja de ser válido. Si la fecha proporcionada no es un objeto ` QDate ` válido, la función `setMinimumDate()` no realiza ninguna acción.
La fecha mínima por defecto es el 25 de noviembre del 4714 a. C. Se puede restablecer este valor por defecto llamando a clearMinimumDate() (a partir de Qt 6.6).
Funciones de acceso:
| QDate | minimumDate() const |
| void | setMinimumDate(QDate date) |
| void | clearMinimumDate() |
Véase también ` setDateRange()`.
navigationBarVisible : bool
Esta propiedad se mantiene independientemente de si la barra de navegación está visible o no
Cuando esta propiedad tiene el valor « true » (valor predeterminado), los controles de «mes siguiente», «mes anterior», «selección de mes» y «selección de año» se muestran en la parte superior.
Cuando la propiedad se establece en «false», estos controles se ocultan.
Funciones de acceso:
| bool | isNavigationBarVisible() const |
| void | setNavigationBarVisible(bool visible) |
selectedDate : QDate
Esta propiedad contiene la fecha seleccionada actualmente.
La fecha seleccionada debe estar dentro del intervalo de fechas especificado por las propiedades « minimumDate » y « maximumDate ». De forma predeterminada, la fecha seleccionada es la fecha actual.
Funciones de Access:
| QDate | selectedDate() const |
| void | setSelectedDate(QDate date) |
Véase también setDateRange().
selectionMode : SelectionMode
Esta propiedad indica el tipo de selección que el usuario puede realizar en el calendario
Cuando esta propiedad se establece en « SingleSelection », el usuario puede seleccionar una fecha dentro del intervalo permitido entre la fecha mínima y la máxima, ya sea con el ratón o con el teclado.
Cuando la propiedad se establece en « NoSelection », el usuario no podrá seleccionar fechas, aunque estas sí podrán seleccionarse mediante programación. Ten en cuenta que la fecha seleccionada cuando la propiedad se establece en « NoSelection » seguirá siendo la fecha seleccionada en el calendario.
El valor predeterminado es « SingleSelection ».
Funciones de acceso:
| QCalendarWidget::SelectionMode | selectionMode() const |
| void | setSelectionMode(QCalendarWidget::SelectionMode mode) |
verticalHeaderFormat : VerticalHeaderFormat
Esta propiedad define el formato del encabezado vertical.
El valor por defecto es QCalendarWidget::ISOWeekNumber.
Funciones de acceso:
| QCalendarWidget::VerticalHeaderFormat | verticalHeaderFormat() const |
| void | setVerticalHeaderFormat(QCalendarWidget::VerticalHeaderFormat format) |
Documentación de las funciones miembro
[explicit] QCalendarWidget::QCalendarWidget(QWidget *parent = nullptr)
Crea un widget de calendario con el objeto ` parent` proporcionado.
El widget se inicializa con el mes y el año actuales, y la fecha seleccionada actualmente es la de hoy.
Véase también setCurrentPage().
[virtual noexcept] QCalendarWidget::~QCalendarWidget()
Elimina el widget del calendario.
[signal] void QCalendarWidget::activated(QDate date)
Esta señal se emite cada vez que el usuario pulsa la tecla «Return» o «Enter», o hace doble clic en un « date » del widget del calendario.
QCalendar QCalendarWidget::calendar() const
Indica el sistema de calendario que utiliza este widget.
Véase también setCalendar().
[signal] void QCalendarWidget::clicked(QDate date)
Esta señal se emite al hacer clic con el ratón. La fecha en la que se hizo clic se especifica mediante ` date`. La señal solo se emite cuando se hace clic en una fecha válida; es decir, las fechas no deben estar fuera de los rangos ` minimumDate()` y ` maximumDate()`. Si el modo de selección es ` NoSelection`, esta señal no se emitirá.
[signal] void QCalendarWidget::currentPageChanged(int year, int month)
Esta señal se emite cuando cambia el mes que se muestra actualmente. Se pasan como parámetros los nuevos valores de « year » y « month ».
Véase también setCurrentPage().
QMap<QDate, QTextCharFormat> QCalendarWidget::dateTextFormat() const
Devuelve un objeto ` QMap ` desde ` QDate ` hasta ` QTextCharFormat `, que muestra todas las fechas que utilizan un formato especial que altera su visualización.
Véase también setDateTextFormat().
QTextCharFormat QCalendarWidget::dateTextFormat(QDate date) const
Devuelve un objeto ` QTextCharFormat ` para ` date`. El formato `char` puede estar vacío si la fecha no se representa de forma especial.
[override virtual protected] bool QCalendarWidget::event(QEvent *event)
Reimplementa: ` QWidget::event(QEvent *event)`.
[override virtual protected] bool QCalendarWidget::eventFilter(QObject *watched, QEvent *event)
Reimplementa: ` QObject::eventFilter` (`QObject *watched, QEvent *event`).
QTextCharFormat QCalendarWidget::headerTextFormat() const
Devuelve el formato de texto «char» para mostrar el encabezado.
Véase también setHeaderTextFormat().
[override virtual protected] void QCalendarWidget::keyPressEvent(QKeyEvent *event)
Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.
[override virtual] QSize QCalendarWidget::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.
int QCalendarWidget::monthShown() const
Devuelve el mes que se muestra actualmente. Los meses se numeran del 1 al 12.
Véase también yearShown() y setCurrentPage().
[override virtual protected] void QCalendarWidget::mousePressEvent(QMouseEvent *event)
Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.
[virtual protected] void QCalendarWidget::paintCell(QPainter *painter, const QRect &rect, QDate date) const
Pinta la celda especificada por el valor dado en « date », utilizando los valores dados en « painter » y « rect ».
[override virtual protected] void QCalendarWidget::resizeEvent(QResizeEvent *event)
Reimplementa: ` QWidget::resizeEvent(QResizeEvent *event)`.
[signal] void QCalendarWidget::selectionChanged()
Esta señal se emite cuando se modifica la fecha seleccionada actualmente.
El usuario puede cambiar la fecha seleccionada actualmente con el ratón o el teclado, o bien el programador puede hacerlo mediante la función setSelectedDate().
Véase también selectedDate().
void QCalendarWidget::setCalendar(QCalendar c)
Establece c como el sistema de calendario que utilizará este widget.
El widget puede utilizar cualquier sistema de calendario compatible. Por defecto, utiliza el calendario gregoriano.
Véase también calendar().
[slot] void QCalendarWidget::setCurrentPage(int year, int month)
Muestra el mes y el año ( month ) de la fecha ( year ) indicada sin modificar la fecha seleccionada. Utiliza la función setSelectedDate() para modificar la fecha seleccionada.
El mes y el año que se muestran actualmente se pueden obtener utilizando las funciones monthShown() y yearShown(), respectivamente.
Véanse también yearShown(), monthShown(), showPreviousMonth(), showNextMonth(), showPreviousYear() y showNextYear().
[slot] void QCalendarWidget::setDateRange(QDate min, QDate max)
Define un intervalo de fechas mediante la configuración de las propiedades « minimumDate » y « maximumDate ».
El intervalo de fechas restringe la selección del usuario, es decir, el usuario solo puede seleccionar fechas dentro del intervalo especificado. Ten en cuenta que
QCalendarWidget *calendar;
calendar->setDateRange(min, max);es análogo a
QCalendarWidget *calendar;
calendar->setMinimumDate(min);
calendar->setMaximumDate(max);Si alguno de los parámetros min o max no es un objeto válido de tipo « QDate », esta función no realiza ninguna acción.
Véase también setMinimumDate() y setMaximumDate().
void QCalendarWidget::setDateTextFormat(QDate date, const QTextCharFormat &format)
Establece el formato utilizado para mostrar el « date » indicado según lo especificado en « format ».
Si date es nulo, se borran todos los formatos de fecha.
Véase también dateTextFormat().
void QCalendarWidget::setHeaderTextFormat(const QTextCharFormat &format)
Establece el formato de caracteres de texto para mostrar el encabezado en format. Si además se establece un formato de texto para los días de la semana, los colores de primer plano y de fondo de este formato tendrán prioridad sobre el formato del encabezado. El resto de la información de formato seguirá estando determinada por el formato del encabezado.
Véase también headerTextFormat().
void QCalendarWidget::setWeekdayTextFormat(Qt::DayOfWeek dayOfWeek, const QTextCharFormat &format)
Establece el formato de caracteres de texto para la visualización del día de la semana dayOfWeek a format. Este formato tendrá prioridad sobre el formato de los encabezados en lo que respecta al color de primer plano y de fondo. El resto de la información de formato de texto se toma del formato de los encabezados.
Véase también weekdayTextFormat() y setHeaderTextFormat().
[slot] void QCalendarWidget::showNextMonth()
Muestra el mes siguiente en relación con el mes que se está visualizando actualmente. Ten en cuenta que la fecha seleccionada no cambia.
Véase también showPreviousMonth(), setCurrentPage() y setSelectedDate().
[slot] void QCalendarWidget::showNextYear()
Muestra el mes del año siguiente que se está visualizando actualmente, en relación con el año que se está visualizando actualmente. Ten en cuenta que la fecha seleccionada no cambia.
Véanse también showPreviousYear(), setCurrentPage() y setSelectedDate().
[slot] void QCalendarWidget::showPreviousMonth()
Muestra el mes anterior en relación con el mes que se está visualizando actualmente. Ten en cuenta que la fecha seleccionada no cambia.
Véanse también showNextMonth(), setCurrentPage() y setSelectedDate().
[slot] void QCalendarWidget::showPreviousYear()
Muestra el mes del año anterior que se muestra actualmente en relación con el año que se muestra actualmente. Ten en cuenta que la fecha seleccionada no cambia.
Véase también showNextYear(), setCurrentPage() y setSelectedDate().
[slot] void QCalendarWidget::showSelectedDate()
Muestra el mes de la fecha seleccionada.
Véase también selectedDate() y setCurrentPage().
[slot] void QCalendarWidget::showToday()
Muestra el mes de la fecha de hoy.
Véase también selectedDate() y setCurrentPage().
[override virtual] QSize QCalendarWidget::sizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.
[protected] void QCalendarWidget::updateCell(QDate date)
Actualiza la celda especificada por el date proporcionado, a menos que las actualizaciones estén desactivadas o que la celda esté oculta.
Véase también updateCells(), yearShown() y monthShown().
[protected] void QCalendarWidget::updateCells()
Actualiza todas las celdas visibles, a menos que las actualizaciones estén desactivadas.
Véase también updateCell().
QTextCharFormat QCalendarWidget::weekdayTextFormat(Qt::DayOfWeek dayOfWeek) const
Devuelve el formato de carácter de texto para mostrar el día de la semana dayOfWeek.
Véase también setWeekdayTextFormat() y headerTextFormat().
int QCalendarWidget::yearShown() const
Devuelve el año del mes que se muestra actualmente. Los meses se numeran del 1 al 12.
Véase también monthShown() y setCurrentPage().
© 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.


