With this template you can add a new Time Picker component to your project. Time Picker allows the user to select the hour, minute and second from three lists the user can conveniently scroll. 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 Time 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 Time Picker wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Time 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 Time 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 Time Picker from scratch you can use the available template. The second function is more educative. The template implements fully working Time 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 Time 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 Time Picker component.

To create a new Time 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 Time Picker component from a template:

The new created Time 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 Time Picker component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Time 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 Time Picker component:

As long as the Time 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 Time 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 Time 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 Time Picker are only few following properties:

Property	Description
Hour	The property Hour stores the number of hours since midnight. The value is valid in range 0 .. 23.
Minute	The property Minute stores the number of minutes after the hour. The value is valid in range 0 .. 59.
OnChange	The property OnChange can refer to a slot method, which will receive a signal each time the user selects another time. Thereupon the method's logic will be executed. In the associated slot method you can evaluate the time picker properties Hour, Minute and Second.
Second	The property Second stores the number of seconds after the minute. The value is valid in range 0 .. 59.

Once added to the component, you can freely move the Time 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 Time Picker to appear behind other views you can reorder it explicitly.

The Time Picker is intended to allow the user to conveniently select a time value. When the user scrolls one of the three lists (hour, minute, second), the corresponding time component changes. This alternation is reflected in the Time Picker's properties Hour, Minute and Second. By evaluating these properties you can simply query the time 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 time value in 24-hour format. The property Hour stores the number of hours since midnight and is automatically limited to the range 0 .. 23. The property Minute stores the number of minutes after the hour in the range 0 .. 59. Similarly, the property Second stores the number of seconds after the minute, also in the range 0 .. 59. The following figure demonstrates the relations between the three properties and the visual appearance of the Time Picker:

While the user interacts with the Time Picker, the component sends signals to associated slot methods. Within the slot method your particular implementation can react and process the event. The Time Picker sends signals when the user has finished scrolling one of the three lists and a new time 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 Time 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 Time Picker appears as a white rectangle containing three scrollable lists displaying hours (0-23), minutes (0-59), and seconds (0-59). The lists can be scrolled by touch interaction, with a border rectangle highlighting the currently selected time value. Gradient shine effects at top and bottom indicate the scrollable nature of the lists. 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 Time Picker. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Time Picker to your particular needs:

Icon	Member	Description
	Hour	The property Hour stores the number of hours since midnight. The value is automatically limited to the range 0 .. 23.
	Minute	The property Minute stores the number of minutes after the hour. The value is automatically limited to the range 0 .. 59.
	Second	The property Second stores the number of seconds after the minute. The value is automatically limited to the range 0 .. 59.
	OnSetHour	The onset method belongs to the property Hour. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListHour list.
	OnGetHour	The onget method belongs to the property Hour. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the hour value from the current scroll position of the ListHour list.
	OnSetMinute	The onset method belongs to the property Minute. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListMinute list.
	OnGetMinute	The onget method belongs to the property Minute. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the minute value from the current scroll position of the ListMinute list.
	OnSetSecond	The onset method belongs to the property Second. Each time the value of the property is changed, the code implemented in the method is executed to update the scroll position of the ListSecond list.
	OnGetSecond	The onget method belongs to the property Second. Each time the value of the property is evaluated within an expression, the code implemented in the method calculates the second value from the current scroll position of the ListSecond 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 time value. Thereupon the method's logic will be executed. In the associated slot method you can evaluate the picker's properties Hour, Minute and Second.
	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 (TouchHandlerHour, TouchHandlerMinute, TouchHandlerSecond).
	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 notifies the owner component that a new time has been selected. This method is connected to all three touch handlers.
	OnLoadHourItem	This internal slot method is called by the ListHour vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the hour number with two-digit formatting.
	OnLoadMinuteItem	This internal slot method is called by the ListMinute vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the minute number with two-digit formatting.
	OnLoadSecondItem	This internal slot method is called by the ListSecond vertical list each time the list needs to load or update a displayed item. The method creates and configures a Text view displaying the second number with two-digit formatting.
	ListHour	This Vertical List displays 24 items (0-23) representing the hours. The list supports endless scrolling, meaning items wrap around when scrolling beyond the boundaries. The list is connected to TouchHandlerHour for scroll interaction.
	ListMinute	This Vertical List displays 60 items (0-59) representing the minutes. The list supports endless scrolling and is connected to TouchHandlerMinute for scroll interaction.
	ListSecond	This Vertical List displays 60 items (0-59) representing the seconds. The list supports endless scrolling and is connected to TouchHandlerSecond for scroll interaction.
	TouchHandlerHour	This Slide Touch Handler reacts to touch and drag events in the hour list area. It provides smooth scrolling with physics simulation (friction, snap-to-grid behavior) and invokes the associated slot methods: onStartSlide and onEndSlide.
	TouchHandlerMinute	This Slide Touch Handler reacts to touch and drag events in the minute list area. It provides smooth scrolling with physics simulation and invokes onStartSlide and onEndSlide.
	TouchHandlerSecond	This Slide Touch Handler reacts to touch and drag events in the second 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 Time Picker.
	BorderCurrent	This Border view highlights the currently selected time value. The border's color changes depending on whether the user is actively scrolling (sliding state).
	Separator1	This Text view displays the ":" separator between the hour and minute lists.
	Separator2	This Text view displays the ":" separator between the minute and second lists.
	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 Time Picker, the method updates the BorderCurrent view to reflect the picker's current state (especially the sliding state).
	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 Time 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 Time 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 TouchHandlerHour, TouchHandlerMinute or TouchHandlerSecond 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 Time 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 Time Picker or even remove the existing functionality if it is not needed in your case.

Originally, if not yet modified, the Time Picker appears as a white rectangle with three scrollable lists, two colon separators, 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 Time Picker template contains per default the views Background, BorderCurrent, Separator1, Separator2, 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 Time 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, Separator1, Separator2, 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 Time 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 time selection, such as "Alarm Time" or "Departure Time". Or you add an Image view to display an icon representing the time 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 Time Picker displays colon separators as text. To make the component more sophisticated, you could replace the here used Text views by e.g. Image views displaying custom separator graphics. For this purpose:

The Time Picker uses three Vertical List objects to display the selectable time values: ListHour with 24 items (0-23), ListMinute with 60 items (0-59), and ListSecond with 60 items (0-59). Each list is responsible for displaying its corresponding time 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 ListHour this is 24, for ListMinute and ListSecond this is 60.
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 23 hours) automatically wraps to the first item (0 hours).
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 Hour, Minute, or Second 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: OnLoadHourItem, OnLoadMinuteItem, or OnLoadSecondItem. 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 OnLoadHourItem method:

Important aspects of the item loading process:

The implementations of OnLoadMinuteItem and OnLoadSecondItem are identical to OnLoadHourItem, except they work with their respective lists (ListMinute and ListSecond).

The Time Picker's three properties Hour, Minute and Second are directly synchronized with the scroll positions of the three vertical lists ListHour, ListMinute and ListSecond. The calculation between scroll position and time value is performed in the onget and onset methods of these properties.

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

This calculation performs following operations:

The three properties Hour, Minute, and Second are automatically limited to their valid ranges: Hour is limited to 0 .. 23, while Minute and Second are limited to 0 .. 59. This limiting is performed in the onset methods before the value is stored.

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

This calculation reverses the operations performed in the onget method:

The following figure illustrates how the scroll position relates to the displayed time value:

This calculation approach allows the Time Picker to provide smooth, endless scrolling while maintaining accurate time values. The endless scrolling means that when you scroll past 23 hours, it automatically continues with 0 hours, and vice versa. Similarly, minutes and seconds wrap at 59.

The Time Picker is an interactive component controlled via touch screen or mouse device. For this purpose the template contains three Slide Touch Handler objects named TouchHandlerHour, TouchHandlerMinute and TouchHandlerSecond. 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 two 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 sends a signal to the slot method stored in the property OnChange to notify the owner component that a new time 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 sending the signal. This ensures that the owner component receives only one notification even when the user has scrolled multiple lists in quick succession. This is in particulary essential on target devices supporting multi-touch displays. On such devices the user can interact with all three lists simultanously, 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 time 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 Time Picker displays each time value with a height of 30 pixels and uses standard black text on white background. 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 items (fonts, colors, alignment), you modify the implementation of the OnLoadHourItem, OnLoadMinuteItem, and OnLoadSecondItem slot methods:

You can customize various aspects:

You can also make the appearance conditional based on the item number. For example, to highlight midnight (0) and noon (12) in the hour list:

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 the values 00 .. 59 as small color rich images (frames inside a multi-frame bitmap resource). The adapt the property ItemClass of all three lists to be Views::Image and adapt the implementation of the slot methods as shown below:

The initial size of the Time Picker is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Time 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 Time 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 Time 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 Time 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 "Alarm Time", "Departure Time", or "Meeting Time".

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 Time Picker contains already four properties Hour, Minute, Second and OnChange. They allow the picker instance to configure its current time value or to receive notifications when the user selects a new time. 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 Time 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 time 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 Time 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 Time 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: