API Documentation
Documentation for developing SailfishOS applicationsDatePicker QML Type
A calendar grid for selecting a date More...
| Import Statement: | import Sailfish.Silica 1.0 |
Properties
- cellHeight : real
- cellWidth : real
- date : date
- dateText : string
- day : int
- daysVisible : bool
- delegate : Component
- leftMargin : real
- modelComponent : Component
- month : int
- monthYearVisible : bool
- rightMargin : real
- viewMoving : bool
- weeksVisible : bool
- year : int
Signals
- updateModel(variant modelObject, variant fromDate, variant toDate, int primaryMonth)
Methods
- showMonth(int month, int year)
Detailed Description
The DatePicker type enables the user to select a date from a calendar grid.
The currently selected date can be set through the date property. Additionally, the individual year, month and day values of the date can be accessed through the read-only year, month and day properties.
Here is a simple date picker with its date set to midday of November 23, 2012:
import QtQuick 2.2
import Sailfish.Silica 1.0
DatePicker {
date: new Date(2012, 10, 23, 12, 0, 0) // 10 = November, JavaScript date objects have 0-based month
}If the date property is not set, it defaults to the local date.
When the user selects a date, the date, year, month and day properties are updated to reflect the selected date.
For convenience, the DatePickerDialog type presents a date picker within a dialog. If you simply need to request a date value from the user, you may find it useful to present a DatePickerDialog rather than inserting a DatePicker item into your user interface.
Using a custom date picker delegate
The standard date picker display shows each day in the calendar grid and colors the text depending on whether the day is the currently selected day, whether the day is within the currently displayed month, and so on. This display can be customized by changing the delegate used to display each day in a grid.
For example, the following date picker uses a custom delegate to display all days in orange:
import QtQuick 2.2
import Sailfish.Silica 1.0
DatePicker {
id: datePicker
delegate: MouseArea {
width: datePicker.cellWidth
height: datePicker.cellHeight
onClicked: datePicker.date = new Date(year, month-1, day, 12, 0, 0) // set the selected date
Label {
anchors.centerIn: parent
text: day
color: "orange"
font.pixelSize: month === primaryMonth ? Theme.fontSizeMedium : Theme.fontSizeExtraSmall
}
}
}Note the reference to the "day", "year", "month" and "primaryMonth" model roles. Unless a custom modelComponent has been set, the date picker uses the default model, which provides various roles for the date represented by each model index. See delegate for details.
Using a custom date picker model
In addition to specifying a custom delegate, a date picker may also specify a custom model that will be used as the model for each calendar grid. This is done by specifying a model component with the modelComponent property. The model component will be instantiated for each calendar grid that is created in the date picker view, and the updateModel() signal is emitted whenever a model instance needs to be updated with a new range of dates to be displayed. This allows for the use of more complex custom delegates that require additional data from the model.
For example, the following date picker specifies a custom model that adds a "holiday" role along with the standard date model roles, and then references this role from the delegate so that Christmas Day, Boxing Day and New Year's Day are shown in bold white text:
import QtQuick 2.2
import Sailfish.Silica 1.0
DatePicker {
id: datePicker
function getModelData(dateObject, primaryMonth) {
var y = dateObject.getFullYear()
var m = dateObject.getMonth() + 1
var d = dateObject.getDate()
var data = {'year': y, 'month': m, 'day': d,
'primaryMonth': primaryMonth,
'holiday': (m === 1 && d === 1) || (m === 12 && (d === 25 || d === 26))}
return data
}
modelComponent: Component {
ListModel { }
}
onUpdateModel: {
var i = 0
var dateObject = new Date(fromDate)
while (dateObject < toDate) {
if (i < modelObject.count) {
modelObject.set(i, getModelData(dateObject, primaryMonth))
} else {
modelObject.append(getModelData(dateObject, primaryMonth))
}
dateObject.setDate(dateObject.getDate() + 1)
i++
}
}
delegate: MouseArea {
width: datePicker.cellWidth
height: datePicker.cellHeight
onClicked: datePicker.date = new Date(year, month-1, day, 12, 0, 0)
Label {
anchors.centerIn: parent
text: day
color: holiday? "white" : "orange"
font.bold: holiday
font.pixelSize: month === primaryMonth ? Theme.fontSizeMedium : Theme.fontSizeExtraSmall
}
}
}See also DatePickerDialog and TimePicker.
Property Documentation
This property provides the width of a date cell. It is sized to ensure all days of the week are visible within the width of the DatePicker.
Custom delegates must be sized to cellWidth x cellHeight.
See also cellHeight.
date : date |
The currently selected date, as a JavaScript date object. This defaults to the current local date.
When setting this value, note that JavaScript date objects have 0-based month values and thus are in the range 0-11, unlike the month property which is 1-12. Additionally, due to the use of QDateTime Daylight Savings Time calculations, dates before 1970-01-01 and after 2037-12-31 may be one day off if the date object is not created with appropriate time information.
So, for example, the code below sets the date correctly with a month in the range 0-11 and a time of midday:
DatePicker {
date: new Date(2000, 9, 26, 12, 0, 0) // 9 = October, so this refers to midday on October 26, 2000
Component.onCompleted: console.log(month) // prints "10" as DatePicker::month property is 1-12
}Reports the currently selected date as a formatted date string in the system short date format.
Reports the day of the currently selected date, as a number in the range 1-31.
This property holds whether the days of week are displayed above the date grid. The default value is false.
Specifies a custom delegate to use for the calendar grid display. The delegate is instantiated for each date within a calendar grid. See Using a custom date picker delegate for an example.
If the modelComponent is not set, this delegate can use the default date picker model, which provides the following roles:
- day - the day (1-31) represented by the model index
- month - the month (1-12) represented by the model index
- year - the year (a four-digit number) represented by the model index
- primaryMonth - the main month represented by this particular calendar grid (see updateModel() for more details)
The delegate must use the cellWidth and cellHeight as its width and height.
See also modelComponent.
The margins between the left and right edges of the date picker and its contents. The default value is Theme.horizontalPageMargin.
Specifies a custom model to use for each calendar grid in the date picker. This can be used together with a custom delegate to provide additional model roles that can be referenced by the delegate. See Using a custom date picker model for an example.
This model component is instantiated for each calendar grid created by the date picker, and updateModel() is emitted when a calendar grid changes its displayed month and thus requires an instance of the model to be filled or updated with a new range of dates.
If this modelComponent is specified but a custom delegate is not set, it should provide the default model roles (listed in the delegate documentation) so that the default delegate is able to access these roles as expected.
Reports the month of the currently selected date, as a number in the range 1-12.
This property holds whether the month and year are displayed to the left of the date grid. The default value is true.
The margins between the left and right edges of the date picker and its contents. The default value is Theme.horizontalPageMargin.
This property holds whether the week numbers are always visible. If true, a column of week numbers is shown to the left of the date grid. If false, the column is hidden to the left of the date grid, but can be exposed by dragging the view to the right.
weeksVisible defaults to true on larger screens (e.g. tablet) and false on smaller screens (e.g. phone).
Reports the year of the currently selected date, as a four-digit number.
Signal Documentation
Emitted when modelComponent is set and an instance of this custom model needs to be populated or updated with a new range of dates. This occurs whenever the date picker changes its displayed months.
The arguments are:
- modelObject - the model instance to be updated. This is an instance of the specified modelComponent.
- fromDate - the first date to be added to the model
- toDate - the last date to be added to the model
- primaryMonth - the main month displayed by this particular calendar grid. The date picker displays six weeks of dates for each month, so the fromDate and toDate values will usually fall outside the start and end dates of the month. The primaryMonth is useful for enabling the delegate to render dates differently if they fall outside of this month.
See Using a custom date picker model for an example.
Method Documentation
Changes the currently displayed month in the date picker to be the specified month of the specified year.
This action also updates the month and year of the currently selected date accordingly, though the day will remain the same. (If the previously selected day is not valid for the new month, the day will be set to the last day of the month.)