Cross-platform C SDK logo
EspañolEnglish
Cross-platform C SDK

DateView

❮ Back
Next ❯

#Header

#include <gui/dateview.h>


#Functions

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

DateView are controls that display a calendar where the user can select a date (Figure 1), (Figure 2), (Figure 3). Unlike other controls, it does not use any native component, but is drawn entirely by NAppGUI, so its look and behavior are identical on all platforms. Colors are taken from the system theme, so it automatically adapts to Theme support (Dark Mode). In Hello DateView! you have an example of use.

Screenshot of several DateView controls in Windows.
Figure 1: DateView controls in Windows.
Screenshot of several DateView controls in macOS.
Figure 2: DateView controls in macOS.
Screenshot of several DateView controls in Linux.
Figure 3: DateView controls in Linux.
  • It can be bound to int32_t fields (days elapsed since January 1, 1970) of a structure GUI Data binding.

#1. Calendar anatomy

The control consists of three parts: a header with the current month and year and four navigation buttons, a row with the initials of the weekdays and a grid with the days. The grid always shows complete weeks, as many as fit in the available space, with no blank cells. Days that do not belong to the header month are drawn with a dimmed color.

  • The month shown in the header is the one with the most days in the first visible rows (up to six). When scrolling the calendar week by week, the header will change when the next (or previous) month becomes the majority.
  • Today is drawn in bold.
  • The selected day is highlighted with the system selection color.
  • When the control has the keyboard focus, a focus rectangle indicates the selected day (or today, if there is no selection).

When a date is selected, another month is navigated to or the control size changes, the calendar is repositioned to show the complete month from its first week. If there is not enough space to show the whole month, priority is given to the selected day (or the one with the focus), which will appear in the last visible row.


#2. Mouse and keyboard navigation

With the mouse, we can click on a day to select it, use the header buttons to move forward or backward one month or one year, and the wheel to scroll the calendar week by week. Neither the buttons nor the wheel change the selection, they only scroll the view. The header buttons do not receive the keyboard focus. With the keyboard, as in ListBox or TableView, the keys move the selection directly, scrolling the calendar when necessary (Table 1).

Table 1: Keyboard in a DateView.
Key Action
[LEFT]/[RIGHT] Previous/next day. When reaching the edge of the week, it continues in the previous/next week.
[UP]/[DOWN] Previous/next week.
[HOME]/[END] First/last day of the week.
[PAGEUP]/[PAGEDOWN] Previous/next month.
[SHIFT]+[PAGEUP]/[PAGEDOWN] Previous/next year.

When changing month or year with the keyboard, the day of the month is kept whenever possible. For example, from January 31 it moves to February 28 (or 29).


#3. Regional settings

By default, the calendar takes the first day of the week, the month names and the weekday initials from the user's regional settings Time. Any of these values can be replaced by custom ones, for example, to match the application language instead of the system language Internationalization (i18n). Translations.

Listing 1: Calendar with custom names.
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. Calendar size

  • Use dateview_font to change the font and, with it, the size of the control.

The Natural sizing of the control is the one needed to show a complete month (six weeks). It is calculated from the font and the month names, so it may vary slightly between languages. Each cell is large enough to show a two-digit number in bold. If the header, with the longest month name, does not fit in the width of seven cells, the cells will be widened.

  • If the control expands, more weeks will be shown and the grid will be centered horizontally.
  • If the control shrinks, fewer weeks will be shown. With very little space, the weekday row and the header will be hidden, leaving at least one row of days.
❮ Back
Next ❯

#dateview_create ()

Create a new calendar.

DateView*
dateview_create(void);

Return

The newly created DateView.


#dateview_OnSelect ()

Set a handler for the selection of a date.

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

The DateView.

listener

Callback function that will be called when the user selects a date.

Remarks

The event is launched when a day is selected with the mouse or keyboard, but not when calling dateview_select. See GUI Events.


#dateview_font ()

Set the calendar font.

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

The DateView.

font

The font.

Remarks

Font styles (bold, italic, underline, etc.) are ignored. The control uses the normal font for the days and a bold version of it for the header and today.


#dateview_first_wday ()

Set the first day of the week.

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

The DateView.

wday

The weekday that will appear in the first column.

Remarks

By default, the value of btime_first_wday.


#dateview_month_names ()

Set the month names.

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

The DateView.

names

Array with the 12 names in UTF-8, starting with January. NULL to restore the names from the regional settings.

Remarks

By default, the names of btime_month_name.


#dateview_wday_names ()

Set the weekday names.

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

The DateView.

names

Array with the 7 names in UTF-8, starting with Sunday (ekSUNDAY), regardless of the first day of the week. NULL to restore the names from the regional settings.

Remarks

By default, the uppercase initial of btime_wday_name is used. Names set with this function are displayed as is, without trimming.


#dateview_now ()

Set today's date.

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

The DateView.

date

The date that will be highlighted as today. Only the year, month and day are taken into account.

Remarks

By default, the system date at the moment the control is created. The control does not update today's date automatically, for example, when midnight passes. If no date is selected, the calendar is repositioned to show this day.


#dateview_select ()

Select a date.

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

The DateView.

date

The date to select. Only the year, month and day are taken into account. kDATE_NULL to clear the selection.

Remarks

The calendar is repositioned to show the selected date. This function does not launch the dateview_OnSelect event.


#dateview_selected ()

Get the selected date.

Date
dateview_selected(const DateView *view);
view

The DateView.

Return

The selected date or kDATE_NULL if there is none.

❮ Back
Next ❯