With this template you can add a new Date Picker component to your project. Date Picker allows the user to select the day, month and year from three lists the user can conveniently scroll. The special case of leap year is handled automatically. Each time the user interacts with the picker, the component sends signals to associated slot methods where your particular implementation is executed.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Date Picker you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Date Picker wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Date Pickers created by the template are working widgets. If desired, they can already be used as they are. The following figure demonstrates the default appearance of the Date Picker created by using the here described component template:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Date Picker from scratch you can use the available template. The second function is more educative. The template implements fully working Date Picker component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Date Picker component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Date Picker component.

To create a new Date Picker component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Date Picker component from a template:

The new created Date Picker component appears accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Date Picker component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Date Picker class in-place within some superior GUI component. At the runtime, the superior GUI component takes care of the correct initialization and the displaying of all embedded components, so they appear similarly as you have composed them at the design time.

The following are the typical steps to create a new instance of an already existing Date Picker component:

As long as the Date Picker is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Date Picker are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Date Picker component descends from the Mosaic class Core::Group. Consequently, most of the properties listed in the above screenshot are inherited from this base class. Particular to the Date Picker are only few following properties:

Property	Description
Day	The property Day stores the day of the month. The valid value lies in range 1 .. 31 depending on the actually selected month.
Month	The property Month stores the month of the year. The valid value lies in the range 1 .. 12.
OnChange	The property OnChange can refer to a slot method, which will receive a signal each time the user selects another date. Thereupon the method's logic will be executed. In the associated slot method you can evaluate the date picker properties Day, Month and Year.
Year	The property Year stores the year. The value is valid in range 1900 .. 2100.

Once added to the component, you can freely move the Date Picker instance, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the component also by directly modifying its property Bounds. If you want the Date Picker to appear behind other views you can reorder it explicitly.

The Date Picker is intended to allow the user to conveniently select a date value. When the user scrolls one of the three lists (day, month, year), the corresponding date component changes. This alternation is reflected in the Date Picker's properties Day, Month and Year. By evaluating these properties you can simply query the date value which is actually set in the affected picker. Accordingly, when you modify these properties, the affected picker will implicitly update the position of its lists. For example:

The three properties work together to represent a complete date value. The property Day stores the day of the month and is automatically limited to the valid range depending on the selected month (28-31 days). The property Month stores the month of the year in the range 1 .. 12 (January = 1, February = 2, ..., December = 12). The property Year stores the year in the range 1900 .. 2100. The following figure demonstrates the relations between the three properties and the visual appearance of the Date Picker:

The Date Picker automatically handles the special case of different month lengths and leap years. When you change the month or year, the picker automatically adjusts the Day property if necessary. For example, if the current date is January 31 and you change the month to February, the day will automatically be adjusted to either 28 or 29 depending on whether it's a leap year.

While the user interacts with the Date Picker, the component sends signals to associated slot methods. Within the slot method your particular implementation can react and process the event. The Date Picker sends signals when the user has finished scrolling one of the three lists and a new date value has been selected.

The slot methods are connected to the picker by simply storing them in the for this purpose available property OnChange. The slot method connected to this property is signaled when the user has finished the interaction with any of the three lists. You can initialize the property OnChange with already existing slot methods or you add a new one and implement it as desired. The following steps describe how to do this:

When you start the Prototyper now, you can interact with the picker. Thereupon the picker will trigger the associated slot method.

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Date Picker component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Date Picker appears as a white rectangle containing three scrollable lists displaying days (1-31), months (Jan-Dec), and years (1900-2100). The lists can be scrolled by touch interaction, with a border rectangle highlighting the currently selected date value. Gradient shine effects at top and bottom indicate the scrollable nature of the lists. The month list displays abbreviated month names (Jan, Feb, Mar, etc.). Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details.

This default functionality is implemented by following members belonging to the Date Picker. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Date Picker to your particular needs:

Icon	Member	Description
	Day	The property Day stores the day of the month. The value is automatically limited to the range 1 .. 31 depending on the selected month and year.
	Month	The property Month stores the month of the year. The value is automatically limited to the range 1 .. 12.
	Year	The property Year stores the year. The value is automatically limited to the range 1900 .. 2100.
	OnSetDay	The onset method belongs to the property Day. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListDay list. The method also ensures the day value is valid for the currently selected month.
	OnGetDay	The onget method belongs to the property Day. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the day value from the current scroll position of the ListDay list.
	OnSetMonth	The onset method belongs to the property Month. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListMonth list. The method also adjusts the number of days in the ListDay and ensures the day value remains valid.
	OnGetMonth	The onget method belongs to the property Month. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the month value from the current scroll position of the ListMonth list.
	OnSetYear	The onset method belongs to the property Year. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListYear list. The method also adjusts the number of days in the ListDay to handle February in leap years.
	OnGetYear	The onget method belongs to the property Year. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the year value from the current scroll position of the ListYear list.
	OnChange	The property OnChange can refer to a slot method, which will receive a signal when the user has finished scrolling and selected a new date value. Thereupon the method's logic will be executed. In the associated slot method you can evaluate the picker's properties Day, Month and Year.
	onStartSlide	This internal slot method is called when the user begins touching and dragging one of the three lists. This method is connected to all three touch handlers (TouchHandlerDay, TouchHandlerMonth, TouchHandlerYear).
	onEndSlide	This internal slot method is called when the user releases the touch screen after scrolling one of the lists and the slide animation has finished. The method adjusts the day value if necessary (to handle month length changes) and notifies the owner component that a new date has been selected. This method is connected to all three touch handlers.
	OnLoadDayItem	This internal slot method is called by the ListDay vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the day number with two-digit formatting (01, 02, ..., 31).
	OnLoadMonthItem	This internal slot method is called by the ListMonth vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the abbreviated month name (Jan, Feb, Mar, etc.).
	OnLoadYearItem	This internal slot method is called by the ListYear vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the four-digit year (1900, 1901, ..., 2100).
	ListDay	This Vertical List displays items (1-31) representing the days. The number of items is dynamically adjusted based on the selected month and year. The list supports endless scrolling, meaning items wrap around when scrolling beyond the boundaries. The list is connected to TouchHandlerDay for scroll interaction.
	ListMonth	This Vertical List displays 12 items (Jan-Dec) representing the months. The list supports endless scrolling and is connected to TouchHandlerMonth for scroll interaction.
	ListYear	This Vertical List displays 200 items (1900-2100) representing the years. The list supports endless scrolling and is connected to TouchHandlerYear for scroll interaction.
	TouchHandlerDay	This Slide Touch Handler reacts to touch and drag events in the day list area. It provides smooth scrolling with physics simulation (friction, snap-to-grid behavior) and invokes the associated slot methods: onStartSlide and onEndSlide.
	TouchHandlerMonth	This Slide Touch Handler reacts to touch and drag events in the month list area. It provides smooth scrolling with physics simulation and invokes onStartSlide and onEndSlide.
	TouchHandlerYear	This Slide Touch Handler reacts to touch and drag events in the year list area. It provides smooth scrolling with physics simulation and invokes onStartSlide and onEndSlide.
	Background	This Filled Rectangle view displays the white background of the Date Picker.
	BorderCurrent	This Border view highlights the currently selected date value. The border's color changes depending on whether the user is actively scrolling (sliding state).
	ShineAtTop	This Filled Rectangle view creates a gradient shine effect at the top of the picker to indicate scrollable content above.
	ShineAtBottom	This Filled Rectangle view creates a gradient shine effect at the bottom of the picker to indicate scrollable content below.
	UpdateViewState	This method is invoked automatically after the state of the component has been changed. In case of the Date Picker, the method updates the BorderCurrent view to reflect the picker's current state (especially the sliding state).
	getDaysInMonth	This utility method calculates the number of days in a given month and year. The method takes care of leap years and returns the correct number of days (28, 29, 30, or 31) depending on the month and whether it's a leap year.
	enabled	This variable stores the current state of the picker. It is true if the picker is allowed to handle user inputs (the component is enabled). See also Control the Enabled state of nested components. If the picker is actually disabled, the variable is consequently false.
	selected	This variable stores the current state of the picker. It is true if the picker is actually focused for keyboard inputs (more precisely, the picker is selected within its owner component).
	sliding	This variable stores the current state of the picker. It is true if the user is actively scrolling one of the three lists (the user is interacting with the picker).

During its lifetime, the Date Picker will assume different states as direct effect of user interactions and as result of other superior state alternations within the GUI application. To track its current state the Date Picker manages the above mentioned state variables: enabled, selected and sliding. The variables are evaluated and updated within the implementation of the method UpdateViewState. This method evaluates the common component states (Enabled and Selected) and verifies whether the user is actually interacting with one of the picker's three lists via touch screen (the user is sliding). At the end of the method the estimated states are stored in the state variables:

For example, the local variable isSliding will become true if the user is actually touching and dragging within the area of any of the picker's three lists (the variable Sliding of the TouchHandlerDay, TouchHandlerMonth or TouchHandlerYear is true). Being in this state, the picker should assume an appearance indicating that the user is actively interacting with it.

When common component states (Enabled or Selected) have changed, the method UpdateViewState is invoked automatically. You don't need to worry about it. Any other state alternations need to explicitly request an invocation of the UpdateViewState method. This is especially true for state alternations caused by touch handlers. In the Date Picker, the slot methods onStartSlide and onEndSlide explicitly request the invocation:

Depending on your design expectations the default state management may require adaptations. Generally, you are free to modify the method UpdateViewState, add further state variables to your Date Picker or even remove the existing functionality if it is not needed in your case.

Originally, if not yet modified, the Date Picker appears as a white rectangle with three scrollable lists, a border highlighting the selected value, and gradient shine effects at top and bottom. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the picker to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Date Picker template contains per default the views Background, BorderCurrent, ShineAtTop and ShineAtBottom. If desired, you can modify the views. For example, you can display them with other colors depending on the actual state of the picker. For this purpose you change the implementation of the above explained method UpdateViewState responsible for tracking the state alternations within the Date Picker.

When you open the method UpdateViewState you will see that it does not only update the state variables but also updates the view BorderCurrent existing within the component. Accordingly, depending on whether the user is actively sliding, the border color changes. By simply modifying this implementation you change the appearance. For example, you change the border color to blue when the user actively interacts with the picker:

You can also modify other properties of the existing views. For example, you could change the visibility, opacity, or even the size of views depending on the picker's state. You might want to hide the shine effects when the picker is disabled:

If not needed, you can delete the per default existing views Background, BorderCurrent, ShineAtTop and ShineAtBottom. Doing this, please don't forget to also remove all references to the deleted views from the implementation of the UpdateViewState method. Otherwise you will get error messages next time the Composer contents is reloaded. To avoid this error message we recommend to perform the steps in following order:

You can add further views to your Date Picker. For example, you can add a Text view to display a caption in the upper area of the picker. This caption could label the purpose of the date selection, such as "Birth Date", "Expiry Date", or "Appointment Date". Or you add an Image view to display an icon representing the date picker's function. The appearance of the views (e.g. colors) can be fixed, predetermined at the design time. Or it can change according to the actual state of the picker. For example, if the user is actually scrolling a list, the caption text color can change or an icon can appear highlighted. Following steps explain the workflow:

Also possible, you can replace the existing views by other views. For example, in the original version, the Date Picker displays month names as text. To make the component more sophisticated, you could replace the here used Text views by e.g. Image views displaying custom month graphics or icons. For this purpose:

The Date Picker uses three Vertical List objects to display the selectable date values: ListDay with a variable number of items (28-31 depending on month), ListMonth with 12 items (Jan-Dec), and ListYear with 200 items (1900-2100). Each list is responsible for displaying its corresponding date component and supporting scrolling interaction.

The lists are configured with several important properties:

Property	Description
NoOfItems	Specifies the total number of items in the list. For ListDay this is dynamically adjusted between 28 and 31 depending on the selected month and year. For ListMonth this is 12, and for ListYear this is 200 (years 1900-2100).
ItemHeight	Specifies the height in pixels of each item. The default value is 30 pixels.
ItemClass	Specifies what the items are. In its original version, all lists are configured to use Text views as items.
Endless	When true, the list supports infinite scrolling. Scrolling beyond the last item (e.g., past December) automatically wraps to the first item (January).
SlideHandler	References the associated Slide Touch Handler that controls the scrolling interaction for this list.
OnLoadItem	References the slot method that will be called each time the list needs to load or update a visible item.
ScrollOffset	The current scroll position in pixels. Negative values scroll the list downward, positive values scroll upward. This property is synchronized with the corresponding Day, Month, or Year property.

The vertical list component manages items dynamically. Only the items that are actually visible on screen are created and displayed. As the user scrolls, items that leave the visible area are recycled and reused for newly appearing items. This approach ensures efficient memory usage regardless of the total number of items in the list.

Each time a list needs to display an item, it calls the corresponding slot method: OnLoadDayItem, OnLoadMonthItem, or OnLoadYearItem. These slot methods are responsible for configuring the view that represents the item. The default implementation uses a Text view for each item. For example, the following is the implementation of the OnLoadDayItem method:

Important aspects of the item loading process:

The implementation of OnLoadMonthItem is different because it displays month names instead of numbers. It uses a switch statement to select the appropriate month name from the Mosaic resources:

The OnLoadYearItem method is similar to OnLoadDayItem, but it offsets the item number by 1900 to display years in the range 1900-2100:

The Date Picker's three properties Day, Month and Year are directly synchronized with the scroll positions of the three vertical lists ListDay, ListMonth and ListYear. The calculation between scroll position and date value is performed in the onget and onset methods of these properties.

Each onget method calculates the date value from the list's current scroll position. For example, the onget method for the Day property:

This calculation performs following operations:

The Month property calculation is similar, but months are numbered 1-12:

The Year property calculation includes an offset to the base year 1900:

The three properties Day, Month, and Year are automatically limited to their valid ranges. The limiting is performed in the onset methods before the value is stored. However, the Date Picker includes special logic to handle varying month lengths and leap years.

Conversely, each onset method updates the list's scroll position when the property is modified programmatically. For example, the onset method for the Month property:

This implementation demonstrates the leap year and month length handling. After updating the month, the method:

The onset Year method includes similar logic to handle leap years:

The utility method getDaysInMonth() encapsulates the leap year logic:

This method creates a temporary Core::Time object for the first day of the specified month and year, then queries its DaysInMonth property. The Core::Time class automatically handles leap year calculation according to the Gregorian calendar rules.

Finally, the onEndSlide slot method includes additional logic to ensure date validity after user interaction:

This ensures that when the user scrolls the month or year while the day is set to 31, and the new month has fewer days, the day is automatically adjusted to the last valid day of that month.

The Date Picker is an interactive component controlled via touch screen or mouse device. For this purpose the template contains three Slide Touch Handler objects named TouchHandlerDay, TouchHandlerMonth and TouchHandlerYear. Each touch handler covers the area of its corresponding list. To these handlers are associated two slot methods: onStartSlide and onEndSlide. These methods are invoked at the beginning of the slide interaction (start) and when the slide animation has finished (end):

The slide touch handlers provide smooth scrolling with physics simulation. The user can drag a finger up or down within any of the three list areas, and the list will scroll accordingly. When the user releases the finger, the list continues scrolling with simulated inertia (deceleration) until it snaps to the nearest item position. This behavior is controlled by two important properties:

The slot methods take care of three tasks. First, they request an invocation of the UpdateViewState method when the user begins or ends interaction with the picker, allowing the visual appearance to reflect the current state. Second, the onEndSlide method adjusts the day value and the number of items in the day list to handle month length changes. Third, it sends a signal to the slot method stored in the property OnChange to notify the owner component that a new date has been selected.

The method onStartSlide is invoked when the user begins touching and dragging any of the three lists:

The method onEndSlide is invoked when the slide animation has finished. This occurs after the user has released the touch and the list has coasted to its final position:

Please note that the onEndSlide method checks whether all three touch handlers have finished sliding before performing the day adjustment and sending the signal. This ensures that the owner component receives only one notification even when the user has scrolled multiple lists in quick succession. The day adjustment is particularly important when the user changes from a month with 31 days to one with fewer days - the picker automatically adjusts to the last valid day of the new month.

This is also essential on target devices supporting multi-touch displays. On such devices the user can interact with all three lists simultaneously, by using three fingers (see also Touch screen inputs).

Usually you will not need to edit the implementation of these methods. They correspond already to whatever typical date pickers do. Nevertheless, you are free to change this default functionality if you want some particular behavior to be implemented in your picker. For example, you could modify the friction or snap behavior by adjusting the properties of the touch handlers:

If your device does not contain any touch screen nor mouse, the per default existing touch handlers and their associated slot methods are unnecessary ballast. You could remove them and implement keyboard-based control instead. In practice this could be achieved by adding three Key Press Handlers. One handler to toggle the selection between the three lists (e.g. Tab key), and the second and third handler to react to Up/Down or Plus/Minus keys and adjust accordingly the scroll position in the currently selected list.

The default implementation of the Date Picker displays each date value with a height of 30 pixels and uses standard black text on white background. The month list displays abbreviated month names. If your design requires different dimensions or appearance, you can customize these aspects.

To change the height of items in the lists, you need to modify two related properties:

The SnapNext property must always match the ItemHeight to ensure that after scrolling, the lists align properly with complete items visible.

To change the visual appearance of day and year items (fonts, colors, alignment), you modify the implementation of the OnLoadDayItem and OnLoadYearItem slot methods:

You can customize various aspects:

You can also make the appearance conditional based on the item number. For example, to highlight the first day of each month:

The month list has a special implementation because it displays text names instead of numbers. To customize the month names, you modify the OnLoadMonthItem slot method:

For example, to use full month names:

Or to display month numbers instead of names:

More sophisticated customizations are possible by changing the ItemClass property of the lists to use custom view classes instead of simple Views::Text. This would allow you to display the items with other views. For example, if your application case requires the items to appear with some fancy design, you can provide a bitmap resource containing month icons or symbols as small color rich images (frames inside a multi-frame bitmap resource). Then adapt the property ItemClass of the month list to be Views::Image and adapt the implementation of the slot method as shown below:

The initial size of the Date Picker is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Date Picker component will have by default. If desired, you can adjust the Canvas area and change this default size accordingly. This could be for example the case when you plan to create a larger Date Picker with more spacing or additional elements like a caption. For this purpose you click and drag the edges of the surrounding border (see also Resize the Canvas area). Once the size is changed, you can then adapt (move, resize) the views and lists existing within the component:

The resulting size of the Date Picker is by default fixed. When you resize a picker instance, the content of the picker remains with the original size. This is because the picker uses texts with fixed predetermined height. Nevertheless, if your application case requires the pickers to be flexible in size, you will need to:

When you configure all views and touch handler with following layout setting, the views will adjust their position and size proportionally to changes of the picker's own size:

If you add other decorative views or want to adjust the positions of the lists, you can similarly configure their Layout properties. However, be careful when modifying the positions of the three lists and their associated touch handlers - they must remain synchronized (each touch handler must cover its corresponding list area).

When creating your own Date Picker component you should ensure that instances of the picker can be configured to control all the features implemented in it. For example, if you have enhanced the picker to display a caption text, you should allow this caption to be specified individually for each picker instance. In this way several picker instances can exist at the same time, each displaying another caption like "Birth Date", "Expiry Date", or "Event Date".

To control the features in your picker you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the caption text to display in the picker. When the value of the property changes, the picker can react to it and update its appearance accordingly. The properties reflect thus the settings within your picker. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, a picker where caption and icon can be configured will require two properties: one for the caption text and one for the icon bitmap. In its original version, the Date Picker contains already four properties Day, Month, Year and OnChange. They allow the picker instance to configure its current date value or to receive notifications when the user selects a new date. In order to enhance this interface by your own properties, following steps are necessary:

That is all. Now when you deal with instances of the Date Picker component, you can evaluate and modify the properties similarly to how you access variables. Especially, when the picker instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window:

If desired, the properties can also be modified at the runtime of your application. The picker caption, for example, can be adapted to provide useful information for the user concerning the date selection purpose. For this purpose you access and modify the affected property directly within Chora code:

In the section Adapt the appearance of the component you learned how state alternations within the Date Picker are processed and how views existing in the component are updated in order to reflect the actual state. Accordingly, when the user starts scrolling a list (begins the sliding interaction), the picker can appear with a modified appearance. When the user releases and the sliding animation finishes, the picker restores its normal appearance. The default implementation performs such appearance updates instantly, just in the moment when the respective interaction took place.

If desired, you can modify the Date Picker to update its appearance with animations. For example, instead of instantly switching the BorderCurrent color between the sliding and non-sliding states, the picker can smoothly fade the color. Or you can animate the opacity of decorative views. For this purpose you use the Animation Effects. With an Animation Effect you can animate a property of a view existing in the picker. Following are the steps how to do this: