UIQ Controls - Gregorian Calendar

This guide explains the UIQ control Gregorian Calendar (CQikGregorianCalendar). The Gregorian Calendar Pop-out control allows the user to select a date. The control displays a one-month overview and provides numeric input fields for entering year, month and day.

The Gregorian Calendar control is an exception to how you create controls. Instead of creating it with one of the four ordinary ways, you simply launch it.

The Gregorian Calendar is often used in combination with the Date Editor but can also be used on its own.

The control is always configured and customized through a resource file.

The Softkey Style UI version of the Gregorian Calendar differs from that of the Pen Style UI version. The difference is that the Softkey Style UI version does not contain the Selector, the month list or the year list. Also, the command for selecting the current date differs. The current date command is represented by a current date button in the Pen Style UI version. In the Softkey Style UI version it is displayed in the month overview section as a bold number with a drop shadow.

The following functionality can be used by the application developer:

• Changing the earliest date allowed,

• Changing the latest date allowed,

• Setting the currently selected date.

By default, the following configuration applies:

• Default Pop-out border,

• Default control background color,

• The default message is "Not a valid date" when the date is invalid,

• The default messages are "Earliest date is X" or "Latest date is X", when the date is earlier than the earliest date allowed or later than the latest date allowed. X is the entire date according to the locale settings.

See the API documentation for Gregorian Calendar CQikGregorianCalendar.

The Gregorian Calendar control is similar to the Calendar control and it can use the Date Editor control. See the How To guides for Calendar and Date Editor.

The CEikCalendar should be used to show a generic calendar or the calendar preferred by the system. By default the gregorian calendar is used but other calendars can be implemented and used.

See also the API documentation for Calendar (CEikCalendar) and the Date Editor (CQikDateEditor).

The format that is displayed in Gregorian Calendar is dependent on the locale settings. For more information about locale settings see Locale Settings in the Symbian OS guide.

Gregorian Calendar inherits from CEikCalendarBase.

This section explains how Gregorian Calendar is structured, launched and used.

Use the following #include directive:

#include <qikgregoriancalendar.h>

Use the following LIBRARY directive in the project's mmp-file:

LIBRARY qikctl.lib

Resource files can be used to construct the control. The resource to use is defined by the structure CALENDAR, defined in Eikon.rh. The font elements are of the type NAMED_FONT, defined in Uikon.rh. The structures look like this:

STRUCT CALENDAR
    {
    WORD flags=0; // a combination of EEikCalendarFlagXxxxxs
    WORD verticalspaceaboveyear;
    WORD verticalspacebelowyear;
    WORD horizontalspaceoneachsideofmonthmatrix;
    WORD verticalspacebetweendaynameinitialsandtoprowofdays;
    WORD verticalspacebetweeneachrowofdays;
    WORD horizontalspacebetweeneachcolumnofdays;
    WORD verticalspacebelowtoday;
    WORD horizontalspacebetweenmatrixandweeks;
    STRUCT weekfont; // NAMED_FONT
    STRUCT dayfont; // NAMED_FONT
    STRUCT weekdayinitialfont; // NAMED_FONT
    STRUCT numeralfont; // NAMED_FONT
    LTEXT todaytext;
    }               
            
STRUCT NAMED_FONT
    {
    LTEXT name;
    WORD height;    // in twips
    WORD flags=0; // a combination of EGulFontFlagXxxxs
    }

The values given in the structure definition are default values. The CALENDAR structure contains the following:

• flags is used to customize the control. Possible values are the EEikCalendarFlagXxx constants, defined in eikon.hrh and listed below.

• verticalspaceaboveyear is the number of pixels of vertical space above the year.

• verticalspacebelowyear is the number of pixels of vertical space below the year.

• horizontalspaceoneachsideofmonthmatrix is the number of pixels of horizontal space on each side of the month matrix.

• verticalspacebetweendaynameinitialsandtoprowofdays is the number of pixels between the initials of each day's name and the top row of dates.

• verticalspacebetweeneachrowofdays is the number of pixels between the rows of dates.

• horizontalspacebetweeneachcolumnofdays is the number of pixels between the columns of dates.

• verticalspacebelowtoday is the vertical space below the today button at the bottom of the calendar.

• horizontalspacebetweenmatrixandweeks is the horizontal space between the month matrix and the week numbers on the left side of the calendar.

• weekfont is a structure of type NAMED_FONT representing the font to use for the week numbers.

• dayfont is a structure of type NAMED_FONT representing the font to use for today's date.

• weekdayinitialfont is a structure of type NAMED_FONT representing the font to use for the initials of the days of the week.

• numeralfont is a structure of type NAMED_FONT representing the font to use for the dates in the calendar.

• todaytext is the text to display at the bottom of the calendar to represent today.

The NAMED_FONT structure contains the following:

• name, the name of the font,

• height, the height of the font in twips,

• flags, used to customize the control, possible values are the EGulFontFlagXxxxs constants defined in gulfont.hrh.

The Gregorian Calendar can have the following flags:

EEikCalendarFlagStartMonthIsAlwaysJanuary The start month is always set to January. EEikCalendarFlagNavigateChronologically If set, it is possible to navigate chronologically in the calendar.

The NAMED_FONT structure in the Gregorian Calendar can have the following flags:

EGulFontFlagBold Bold font flag EGulFontFlagItalic Italic font flag EGulFontFlagMono Monospace font flag EGulFontFlagDoubleWidth Double width font flag. EGulFontFlagDoubleHeight Double height font flag.

The Gregorian Calendar control is not like an ordinary control. You cannot create it in one of the four ordinary ways, which are construction with view framework using data from resource file, construction with your own C++ code using data from a resource file, construction solely from C++ code and construction with the dialog framework using data from a resource file. Instead, you simply launch Gregorian Calendar when it is needed.

Another thing to bear in mind when constructing a calendar is that the Gregorian Calendar control should only be used if a Gregorian calendar is requested. If there is a possibility that the type of calendar will change in the future, then the Calendar control should be used instead since it shows a Gregorian or a Lunar Calendar or another calendar depending on its settings. The Calendar control displays any other calendar transparently. For more information concerning the Calendar control, see Calendar.

This section covers the most common functions used for interacting with the control.

3.4.1 How to Launch a Calendar

To launch a calendar using the Gregorian Calendar control, use the code below. Note that the observer, which needs to inherit from MEikCalendarObserver, has to be set before calling ExecuteLD.

The ExecuteLD function launches the calendar pop-out. When execution is completed, the pop-out will be deleted as indicated by the D suffix of the ExcecuteLD function name.

CQikGregorianCalendar* calendar = new CQikGregorianCalendar();
calendar->SetCalendarObserver(this);
calendar->ExecuteLD();

Not applicable.

Subclassing Gregorian Calendar is not recommended.

This is an explanation of some of the expressions used in this guide.

Expression Meaning Selector (Only applicable to Pen Style UI) The Selector is a Date Label together with selection arrows. Another month is selected by tapping an arrow to the right or to the left of the label. Month list (Only applicable to Pen Style UI) Another month can be selected from the month list. Year list (Only applicable to Pen Style UI) Another year can be selected from the year list.