ListTC is an implementation of IController that can be used by a List Widget to handle BREW pointer events. It is used as the default touch contorller for List Widget if AEECLSID_OEMListTC is not concrete.
The default list touch controller performs numerous operations based on the current state of the pointer. When it receives a EVT_POINTER_DOWN, the list immediately switches focus to the widget under the pointer. The behavior of the controller then varies based on whether or not LWF_LIVESCROLL has been set. If Live Scroll has not been enabled, the focus will follow the pointer as it moves up and down across the items. If Live Scroll has been enabled, the item clicked on will follow the pointer as it moves across the screen. This gives the impression that the user is physically "dragging" the item (and the surrounding items) across the list.
Alternatively, if Live Scroll has been enabled, the user can move the pointer quickly and then release which will start a flick. A flick is essentially an acceleration-based way of moving through the list. The faster the user moves his pointer across the screen and releases, the faster and farther the list will scroll. The flick is calculated as follows: on receiving this event, it queries the TouchObserver to get information like velocity, distance traveled and angle of pointer movements. ListTC calculates the distance that it needs to travel before coming to a stop. It also calculates acceleration, and total time needed to stop the list.
Distance = (widget's extent (height for list/grid or width for pick widget) * distance traveled) / item size Acceleration = - square(velocity of pointer move) / 2 * Distance Time = (- Velocity of pointer move) / Acceleration
Finally if a doubleclick is detected (measured by the second EVT_POINTER_DOWN), the touch controller will both select the widget under the pointer and notify any listener's of the handled widget's ViewModel that a double click has occured.
Additionally, List TC supports rubberbanding and early capture release as optional features.
Rubberbanding in vertical list and horizontal pick list - When an item is partially visible in the list as a result of scrolling, a list can be configured to "snap" or "rubber band" so an item is evenly aligned with one side of the list. Rubberbanding is disabled by default in ListTC. An application can enable or disable rubberbanding by using IController_EnableRubberBand(). Rubberbanding is not supported in Grid mode.
Early capture release based on threshold release criteria - This feature is used in tandem with other decorators or containers that support threshold release criteria. It allows the list to tentatively take capture and if it does not understand the gesture that the user is performing (such as panning left on a vertical list), it will release the capture in the belief that the gesture was meant for one of its ancestor widgets. Early capture release is disabled by default in ListTC. An application can enable early capture release using IController_SetHorizontalThresholdReleaseCriteria() for vertical list, grid and IController_SetVerticalThresholdReleaseCriteria() for pick list.
ListTC also supports early capture release based on timeout release criteria. An application can disable or enable early capture release using IController_SetTimeoutReleaseCriteria(). When timeout release criteria is enabled, ListTC will release capture if list does not start live scroll or click within the timeout period specified by the timeout release criteria.
Property Description -------- ------------------------------------------------------------ PROPEX_MIN_LIVESCROLL_DIST: This extended property is used to set or retrieve minimum distance which should be covered by EVT_POINTER_MOVE events before the list starts scrolling with respect to EVT_POINTER_MOVE events. PROPEX_MAX_LLM_ANGLE_RANGE: This extended property is used to set or retrieve the correction angle which is used to determine the direction on flick. For example, if 90 degrees angle is considered vertical movement and angle specified by PROPEX_MAX_LLM_ANGLE_RANGE is 10 degrees. Then any angle between the range of 70 to 110 degrees will be considered vertical move. PROPEX_FLICK_STEPTIME: This extended property is used to set or retrieve flick step time, scroll events are sent to the list widget after this step time. PROPEX_ITEMSELECTION_TIMEOUT: This extended property is used to set or retrieve the timer value which is used for item selection, In live scroll mode, item is selection after the expiration of this timer, which is set when the widget gets EVT_POINTER_UP. PROPEX_SETTINGS_OBJECT: This extended property is used to set or retrieve the ISettings object attached to touch controller.
APIs supported: IController_SetMinLiveScrollDist IController_GetMinLiveScrollDist IController_SetFlickStepTime IController_GetFlickStepTime IController_SetMaxLLMAngleRange IController_GetMaxLLMAngleRange IController_SetItemSelectionTimeout IController_GetItemSelectionTimeout IController_SetSettings IController_EnableRubberBand IController_IsRubberBandEnabled IController_SetVerticalThresholdReleaseCriteria IController_GetVerticalThresholdReleaseCriteria IController_SetHorizontalThresholdReleaseCriteria IController_GetHorizontalThresholdReleaseCriteria IController_SetTimeoutReleaseCriteria IController_GetTimeoutReleaseCriteria
The List Touch Controller is instantiated by passing AEECLSID_ListTC into ISHELL_CreateInstance.
The ListTC is reference-counted. When you are done with your reference to the ListTC, you should Release that reference. Any controller-specific cleanup will be handled for you when all references are released.