\brief The HbDateTimePicker class provides a widget that has multiple vertical tumblers 

    for selecting a date, time, or date and time by flick, drag and tap gestures.

    The number of tumblers depends on the display format. The default constructor creates

    a widget for selecting a date by internally setting the display format to the default 

    locale's short date format. Other constructors enable you to create a widget

    for selecting a time or date and time by passing a QTime or QDateTime variable as an 

    argument. Internally these constructors set the display format to the default locale's

    short time or date and time format, respectively.

    Use setDisplayFormat() to set the display format. Be aware that changing the display format 

    can change the widget from one for selecting the date to one for selecting the time, for 

    example.

    Looping is enabled in the tumblers. The general appearance of the widget depends on the 

    theme that is in use.

    <TABLE border="0">

    <TR><TD>\image html hbdatetimepicker_date.png "Display format: d.MMMM"</TD>

    <TD></TD>

    <TD>\image html hbdatetimepicker_time.png "Display format: h.m.AP"</TD></TR>

    </TABLE>

    You can set the range of values available in the tumblers by defining minimum and maximum 

    values or using convenience range functions. If you change the range, if necessary 

    the widget changes the displayed values so that they are within the new range. Users 

    cannot select a value outside the range. One effect of this is that if you set, 

    for example, an afternoon time range, users cannot scroll to the AM value when the 

    display format includes an AM/PM tumbler. The date range is currently independent of the 

    time range.

    You can use setInterval() to define the increments for the minute tumbler. This is 

    useful when you want users to be able to set the time in 15 minute increments, for example.

    The number of rows displayed depends on how much space is available. To change the number 

    of rows shown when the widget is is in a layout, for example, use 

    QGraphicsLayoutItem::setPreferredHeight() to increase the space available. The widget then

    increases the number of rows to occupy the available space. 

    %HbDateTimePicker emits a dateChanged(), timeChanged() or dateTimeChanged() signal when 

    the user selects a new value. The selected date, time, or date and time value is passed

    in a QDate, QTime, or QDateTime argument. 

    \section _usecases_hbdatetimepicker Using HbDateTimePicker

    The following example demonstrates creating a widget for selecting a date:

    \code

    // Use the default constructor to create a widget for selecting a date.

    HbDateTimePicker *datePicker = new HbDateTimePicker();

    // Set the minumum and maximum dates to display.

    datePicker->setMinimumDate(QDate::currentDate());

    datePicker->setMaximumDate(QDate::currentDate().addDays(365));

    // Specify the display format.

    datePicker->setDisplayFormat("dd.MMMM.yyyy");

    \endcode

    The following example demonstrates connecting the dateChanged() signal to a slot

    on an object, \a d, of a class (not shown). This has a \c setMeetingDate() function 

    that takes a QDate argument.

    \code

    QObject::connect(datePicker, SIGNAL(dateChanged(const QDate&)),

                     d, SLOT(setMeetingDate(const QDate&)));

    \endcode

    The following example demonstrates creating a widget for selecting a time:

    \code

    // Create a widget for selecting a time.

    HbDateTimePicker *timePicker = new HbDateTimePicker(QTime());

    // Set the minimum and maximum times using the convenience range method.

    timePicker->setTimeRange(QTime::currentTime(),

                             QTime::currentTime().addSecs(10*60*60));

    // Set the time interval to be 15 minutes.

    timePicker->setInterval(QDateTimeEdit::MinuteSection, 15);

    // Specify the display format.

    timePicker->setDisplayFormat("hh:mm.ap");

    \endcode

    The following example demonstrates creating a widget for selecting a date and time:

    \code

    // Create a widget for selecting a date and time.

    HbDateTimePicker *dateTimePicker =

            new HbDateTimePicker(QDateTime::currentDateTime());

    // Specify the display format.

    dateTimePicker->setDisplayFormat("dd.MM.yyyy.hh.mm.ap");

    \endcode

    The properties that hold the minimum and maximum values take a QDate, QTime 

    or QDateTime object as an argument. DocML does not directly support properties that

    use QDate, QTime or QDateTime as a parameter. This means that when you add an \b %HbDateTimePicker 

    widget in Application Designer, you must pass the date, time and date and time to these

    properties as a string in a valid ISO 8601 extended format. For example, YYYY-MM-DD for dates, 

    hh:mm:ss for times, and YYYY-MM-DDTHH:MM:SS for combined dates and times. 

    Here is an example of the \c maximumTime property defined in DocML:

    \code

    <widget name="t:dtp" type="HbDateTimePicker">

        <!-- 'maximumTime' is a QTime property of HbDateTimePicker. -->

        <string name ="displayFormat" value="hh:mm:ss" />

        <string name="maximumTime" value="08:30:00" />

    </widget>

    \endcode

    \section _methodgroups_HbDateTimePicker Function groups

    \li \b Range: setDateRange(), setTimeRange(), setDateTimeRange()

    \li \b Minimum \b value: setMinimumDate(), setMinimumTime(), setMinimumDateTime()

    \li \b Maximum \b value: setMaximumDate(), setMaximumTime(), setMaximumDateTime()

    \li \b Time \b interval: setInterval()

    \sa HbDateTimeEdit, HbTumbleView, HbExtendedLocale

    \fn void HbDateTimePicker::dateChanged(const QDate &date);

    This signal is emitted when there is a change in the day, month or year selected.

    The new date is passed in \a date.

    \fn void HbDateTimePicker::timeChanged(const QTime &time);

    This signal is emitted when there is a change in the hour, minute, second, or AM/PM

    selected. The new time is passed in \a time.

    \fn void HbDateTimePicker::dateTimeChanged(const QDateTime &datetime);

    This signal is emitted when there is a change in the value selected in any of the

    tumblers in a date and time picker. The new date and time are passed in \a dateTime.

    Constructs an %HbDateTimePicker object with the locale's default short date display format 

    and with parent \a parent.

    Constructs an %HbDateTimePicker object with the locale's default short date and time 

    display format and with parent \a parent.

    Constructs an %HbDateTimePicker object with the locale's default short date 

    display format and with parent \a parent.

    Constructs an %HbDateTimePicker object with the locale's default time 

    display format and with parent \a parent.

    The default mode is date and time. If another mode is required, set the mDateTimeMode 

    variable explicitly in the constructor of the class derived from HbDateTimePicker. This 

    does not set the default date and time value. 

    \sa setDateTime(), setTime(), setDate()

    Returns the current display format as a QString value.

    Sets the display format using a suitable combination of the following expressions 

    in QString format.

    These expressions may be used for the date:

    <TR><TD><b><b>Expression </b></TD><TD><b>Output</b> </TD></b></TR>

    <TR><TD> d </TD><TD> The day as a number without a leading zero (1 to 31).</TD></TR>

    <TR><TD> dd </TD><TD> The day as a number with a leading zero (01 to 31). </TD></TR>

    <TR><TD> ddd </TD><TD>The abbreviated localized day name (such as <i>Mon</i> to <i>Sun</i>).

            Uses QDate::shortDayName().</TD></TR>

    <TR><TD> dddd </TD><TD>The long localized day name (such as <i>Monday</i> to <i>Sunday</i>).

            Uses QDate::longDayName().</TD></TR>

    <TR><TD> M </TD><TD> The month as a number without a leading zero (1 to 12).</TD></TR>

    <TR><TD> MM </TD><TD> The month as a number with a leading zero (01 to 12).</TD></TR>

    <TR><TD> MMM </TD><TD>The abbreviated localized month name (such as <i>Jan</i> to <i>Dec</i>).

            Uses QDate::shortMonthName().</TD></TR>

    <TR><TD> MMMM </TD><TD>The long localized month name (such as <i>January</i> to <i>December</i>).

            Uses QDate::longMonthName().</TD></TR>

    <TR><TD> yy </TD><TD>The year as a two digit number (00 to 99).</TD></TR>

    <TR><TD> yyyy </TD><TD>The year as a four digit number. If the year is negative,

            a minus sign is prepended.</TD></TR>

    </TABLE>

    These expressions may be used for the time:

    <TABLE>

    <TR><TD><b><b>Expression </b></TD><TD><b>Output</b> </TD></b></TR>

    <TR><TD> h </TD><TD>The hour without a leading zero (0 to 23 or 1 to 12).</TD></TR>

    <TR><TD> hh </TD><TD>The hour with a leading zero (00 to 23 or 01 to 12). </TD></TR>

    <TR><TD>H	</TD><TD>The hour without a leading zero (0 to 23, even with AM/PM display).</TD></TR>

    <TR><TD>HH	</TD><TD>The hour with a leading zero (00 to 23, even with AM/PM display).</TD></TR>

    <TR><TD> m </TD><TD>The minute without a leading zero (0 to 59).</TD></TR>

    <TR><TD> mm </TD><TD>The minute with a leading zero (00 to 59).</TD></TR>

    <TR><TD> s </TD><TD>The second without a leading zero (0 to 59).</TD></TR>

    <TR><TD> ss </TD><TD>The second with a leading zero (00 to 59).</TD></TR>

    <TR><TD>AP or A	</TD><TD>Displays AM and PM.</i></TD></TR>

    <TR><TD>ap or a	</TD><TD>Displays am and pm.</TD></TR>

    \note Currently you must include separators in the format; for example, 'dd.mm.yy'. 

    Returns the currently selected date in QDate format.

    \note DocML does not directly support properties that use QDate as a parameter. For these 

    properties, pass the date as a string in a valid ISO 8601 extended format,

    such as YYYY-MM-DD.

    \sa setDate()

    Sets the current date to \a date.

    \param date The date in QDate format.

    \sa date()

    Returns the minimum date in QDate format.

    \note DocML does not directly support properties that use QDate as a parameter. For these 

    properties, pass the date as a string in a valid ISO 8601 extended format, such as YYYY-MM-DD.

    \sa setMinimumDate()

    Sets the minimum date to \a date. 

    \param date The minimum date in QDate format.

    \sa minimumDate(), setDateRange()

    Returns the maximum date in QDate format.

    \note DocML does not directly support properties that use QDate as a parameter. For these 

    properties, pass the date as a string in a valid ISO 8601 extended format, such as YYYY-MM-DD.

    \sa setMaximumDate()

    Sets the maximum date to \a date. 

    \param date The maximum date in QDate format.

    \sa maximumDate(), setDateRange()

    Sets the minimum and maximum dates.

    \param minDate The minimum date in QDate format.

    \param maxDate The maximum date in QDate format.

    \sa setMinimumDate(), setMaximumDate()

    Returns the currently selected date and time in QDateTime format.

    \note DocML does not directly support properties that use QDate, QTime or QDateTime as a 

    parameter. For these properties, pass the date, time or date and time as a string in a 

    valid ISO 8601 extended format. For example, YYYY-MM-DD for dates and YYYY-MM-DDTHH:MM:SS

    for combined dates and times.

    \sa setDateTime()

    Sets the current date and time.

    \param datetime The date and time in QDateTime format.

    \sa dateTime()

    Returns the minimum date and time in QDateTime format.

    \note DocML does not directly support properties that use QDate, QTime or QDateTime as a 

    parameter. For these properties, pass the date, time or date and time as a string in a 

    valid ISO 8601 extended format. For example, YYYY-MM-DD for dates and YYYY-MM-DDTHH:MM:SS