SDK Multiplataforma en C logo
EspañolEnglish
SDK Multiplataforma en C

DateView

❮ Anterior
Siguiente ❯

#Cabecera

#include <gui/dateview.h>


#Funciones

DateView*dateview_create (void)
voiddateview_OnSelect (...)
voiddateview_font (...)
voiddateview_first_wday (...)
voiddateview_month_names (...)
voiddateview_wday_names (...)
voiddateview_now (...)
voiddateview_select (...)
Datedateview_selected (...)

Los DateView son controles que muestran un calendario donde el usuario puede seleccionar una fecha (Figura 1), (Figura 2), (Figura 3). A diferencia de otros controles, no utiliza ningún componente nativo, sino que se dibuja íntegramente por NAppGUI, por lo que su aspecto y comportamiento son idénticos en todas las plataformas. Los colores se obtienen del tema del sistema, por lo que se adapta automáticamente al Soporte de temas (Dark Mode). En ¡Hola DateView! tienes un ejemplo de uso.

Captura de varios controles DateView en Windows.
Figura 1: Controles DateView en Windows.
Captura de varios controles DateView en macOS.
Figura 2: Controles DateView en macOS.
Captura de varios controles DateView en Linux.
Figura 3: Controles DateView en Linux.
  • Se puede vincular con campos int32_t (días transcurridos desde el 1 de enero de 1970) de una estructura GUI Data binding.

#1. Anatomía del calendario

El control se compone de tres partes: una cabecera con el mes y el año actual y cuatro botones de navegación, una fila con las iniciales de los días de la semana y una cuadrícula con los días. La cuadrícula siempre muestra semanas completas, tantas como quepan en el espacio disponible, sin celdas en blanco. Los días que no pertenecen al mes de la cabecera se dibujan con un color atenuado.

  • El mes que aparece en la cabecera es el que tiene más días en las primeras filas visibles (hasta seis). Al desplazar el calendario semana a semana, la cabecera cambiará cuando el mes siguiente (o anterior) pase a ser mayoritario.
  • El día de hoy se dibuja en negrita.
  • El día seleccionado se resalta con el color de selección del sistema.
  • Cuando el control tiene el foco del teclado, un rectángulo de foco indica el día seleccionado (o el de hoy, si no hay selección).

Cuando se selecciona una fecha, se navega a otro mes o cambia el tamaño del control, el calendario se recoloca para mostrar el mes completo desde su primera semana. Si no hay espacio suficiente para mostrar el mes entero, se prioriza el día seleccionado (o el que tiene el foco), que aparecerá en la última fila visible.


#2. Navegación con ratón y teclado

Con el ratón, podremos hacer clic en un día para seleccionarlo, utilizar los botones de la cabecera para avanzar o retroceder un mes o un año y la rueda para desplazar el calendario semana a semana. Ni los botones ni la rueda cambian la selección, solo desplazan la vista. Los botones de la cabecera no reciben el foco del teclado. Con el teclado, al igual que en ListBox o TableView, las teclas mueven directamente la selección, desplazando el calendario cuando sea necesario (Tabla 1).

Tabla 1: Teclado en un DateView.
Tecla Acción
[LEFT]/[RIGHT] Día anterior/siguiente. Al llegar al borde de la semana, continúa en la semana anterior/siguiente.
[UP]/[DOWN] Semana anterior/siguiente.
[HOME]/[END] Primer/último día de la semana.
[PAGEUP]/[PAGEDOWN] Mes anterior/siguiente.
[SHIFT]+[PAGEUP]/[PAGEDOWN] Año anterior/siguiente.

Al cambiar de mes o de año con el teclado, se mantiene el día del mes siempre que sea posible. Por ejemplo, desde el 31 de enero se pasa al 28 (o 29) de febrero.


#3. Configuración regional

Por defecto, el calendario toma de la configuración regional del usuario el primer día de la semana, los nombres de los meses y las iniciales de los días Tiempo. Cualquiera de estos valores se puede sustituir por otros propios, por ejemplo, para que coincidan con el idioma de la aplicación en lugar del idioma del sistema Internacionalización (i18n). Traducciones.

Listado 1: Calendario con nombres propios.
1
2
3
4
5
6
7
static const char_t *i_MONTHS[12] = {"Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio", "Julio", "Agosto", "Septiembre", "Octubre", "Noviembre", "Diciembre"};
static const char_t *i_WDAYS[7] = {"D", "L", "M", "X", "J", "V", "S"};

DateView *view = dateview_create();
dateview_first_wday(view, ekMONDAY);
dateview_month_names(view, i_MONTHS);
dateview_wday_names(view, i_WDAYS);

#4. Tamaño del calendario

  • Utiliza dateview_font para cambiar la fuente y, con ella, el tamaño del control.

El Dimensionado natural del control es el necesario para mostrar un mes completo (seis semanas). Se calcula a partir de la fuente y de los nombres de los meses, por lo que puede variar ligeramente entre idiomas. Cada celda tiene el tamaño suficiente para mostrar un número de dos cifras en negrita. Si la cabecera, con el nombre de mes más largo, no cabe en el ancho de siete celdas, estas se ensancharán.

  • Si el control se expande, se mostrarán más semanas y la cuadrícula se centrará horizontalmente.
  • Si el control se reduce, se mostrarán menos semanas. Con muy poco espacio se ocultarán la fila de los días de la semana y la cabecera, quedando como mínimo una fila de días.
❮ Anterior
Siguiente ❯

#dateview_create ()

Crea un nuevo calendario.

DateView*
dateview_create(void);

Retorna

El DateView recién creado.


#dateview_OnSelect ()

Establece un manejador para la selección de una fecha.

void
dateview_OnSelect(DateView *view,
                  Listener *listener);
1
2
3
4
5
6
7
static void i_OnSelect(App *app, Event *e)
{
    const EvDate *p = event_params(e, EvDate);
    do_something_onselect(app, &p->date);
}
...
dateview_OnSelect(view, listener(app, i_OnSelect, App));
view

El DateView.

listener

Función callback que se llamará cuando el usuario seleccione una fecha.

Observaciones

El evento se lanza al seleccionar un día con el ratón o con el teclado, pero no al llamar a dateview_select. Ver Eventos GUI.


#dateview_font ()

Establece la fuente del calendario.

void
dateview_font(DateView *view,
              const Font *font);
view

El DateView.

font

La fuente.

Observaciones

Se ignoran los estilos de la fuente (negrita, cursiva, subrayado, etc.). El control utiliza la fuente normal para los días y una versión en negrita de la misma para la cabecera y el día de hoy.


#dateview_first_wday ()

Establece el primer día de la semana.

void
dateview_first_wday(DateView *view,
                    const week_day_t wday);
view

El DateView.

wday

El día de la semana que aparecerá en la primera columna.

Observaciones

Por defecto, el valor de btime_first_wday.


#dateview_month_names ()

Establece los nombres de los meses.

void
dateview_month_names(DateView *view,
                     const char_t **names);
view

El DateView.

names

Array con los 12 nombres en UTF-8, comenzando por enero. NULL para restaurar los nombres de la configuración regional.

Observaciones

Por defecto, los nombres de btime_month_name.


#dateview_wday_names ()

Establece los nombres de los días de la semana.

void
dateview_wday_names(DateView *view,
                    const char_t **names);
view

El DateView.

names

Array con los 7 nombres en UTF-8, comenzando por el domingo (ekSUNDAY), independientemente del primer día de la semana. NULL para restaurar los nombres de la configuración regional.

Observaciones

Por defecto, se utiliza la inicial en mayúscula de btime_wday_name. Los nombres establecidos con esta función se muestran tal cual, sin recortar.


#dateview_now ()

Establece la fecha de hoy.

void
dateview_now(DateView *view,
             const Date *date);
view

El DateView.

date

La fecha que se resaltará como día de hoy. Solo se tienen en cuenta el año, el mes y el día.

Observaciones

Por defecto, la fecha del sistema en el momento de crear el control. El control no actualiza la fecha de hoy automáticamente, por ejemplo, al pasar la medianoche. Si no hay ninguna fecha seleccionada, el calendario se recoloca para mostrar este día.


#dateview_select ()

Selecciona una fecha.

void
dateview_select(DateView *view,
                const Date *date);
view

El DateView.

date

La fecha a seleccionar. Solo se tienen en cuenta el año, el mes y el día. kDATE_NULL para eliminar la selección.

Observaciones

El calendario se recoloca para mostrar la fecha seleccionada. Esta función no lanza el evento dateview_OnSelect.


#dateview_selected ()

Obtiene la fecha seleccionada.

Date
dateview_selected(const DateView *view);
view

El DateView.

Retorna

La fecha seleccionada o kDATE_NULL si no hay ninguna.

❮ Anterior
Siguiente ❯