ViewportTC is an implementation of IController that can be used by a Viewport Widget to handle BREW pointer events. It is used as the default touch controller for Viewport Widget if AEECLSID_OEMViewportTC is not concrete.
The default viewport touch controller performs numerous operations based on the current state of the pointer. When it receives an EVT_POINTER_DOWN, the viewport will perform one of two actions: It will first check the viewport's child to see if the child can take the touch event; if the child does not want the touch event, it will then begin live scrolling the viewport. In this mode, the viewport view will essentially track the user's finger as it moves across the screen, giving the impression that the user is physically "dragging" the viewport around the widget that it is viewing.
If-- based on the pointer down-- the viewport has entered Live Scroll mode, the Viewport can be flicked if the user moves the pointer quickly across the screen and then 'releases' (i.e. a EVT_POINTER_UP is received). 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 viewport will scroll. The flick is calculated as follows: upon receiving the EVT_POINTER_UP event, it will query the TouchObserver (AEECLSID_TouchObserver) to get information such as velocity, distance travelled, and angle of pointer movements. It then uses this information to calculate the distance the viewport should scroll, the deceleration of the scroll, and the amount of time that the viewport will be scrolling.
Viewport TC will also start live scrolling if its child chooses to release its capture during a pointer sequence based on the threshold release criteria.
Viewport TC supports various other features like rubberbanding and early capture release.
When viewport content that is panning or flicking is released between two discrete snap offsets, the content will slide to the closest snap offset. This effect of "sliding to the closest snap offset" is referred as rubberbanding. One example of when this is useful is a photo album viewer; when a user drags a photo (live scroll) and release touch when two partial images are visible the viewport will automatically slide one of the images to be fully visible (assuming the snap offsets are set correctly).
Rubberbanding is disabled by default in ViewportTC. An application can enable or disable rubberbanding by using IController_EnableRubberBand() and set snap offsets by using IController_SetVerticalSnapOffsets(), IController_SetHorizontalSnapOffsets(). Please note that viewport will not rubberband if snap offsets are not set.
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 viewport to tentatively take capture and if it does not understand the gesture that the user is performing (such as panning left on a vertical viewport), 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 ViewportTC. An application can enable early capture release using IController_SetHorizontalThresholdReleaseCriteria() for vertical viewport and IController_SetVerticalThresholdReleaseCriteria() for horizontal viewport.
ViewportTC 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, ViewportTC will release capture if viewport does not start live scroll within the timeout period specified by the timeout release criteria.
Please note that, due to backwards compatibility, the Viewport will not initially send touch events to the ViewportTC, instead choosing to always attempt to pass the touch events down to the child widget of the Viewport Widget. In order to change this functionality, you should send VWF_CONSUMETOUCHEVENTS to the Viewport Widget. Additionally, please take into consideration that the Viewport Touch Controller will attempt to pass pointer down events to its child widget if the child says that it can handle the event. By default, all widgets start in AEEWIDGET_TOUCH_MODE_ALWAYS: meaning that the Viewport TC will always pass the touch event to the child. This will result in the Viewport never attempting to Live Scroll or Flick. This behavior is included in order to allow for a better user experience when the Viewport is wrapping a container that includes clickable elements such as slider bars and buttons. If your application always wants the touches to be interpreted as part of a Live Scroll or Flick, just set the Touch Mode to AEEWIDGET_TOUCH_MODE_NEVER using IWidget_SetTouchMode.
APIs supported: IController_SetMinLiveScrollDist IController_GetMinLiveScrollDist IController_SetFlickStepTime IController_GetFlickStepTime IController_SetMaxLLMAngleRange IController_GetMaxLLMAngleRange IController_SetSettings IController_EnableRubberBand IController_IsRubberBandEnabled IController_SetVerticalSnapOffsets IController_SetHorizontalSnapOffsets IController_SetVerticalThresholdReleaseCriteria IController_GetVerticalThresholdReleaseCriteria IController_SetHorizontalThresholdReleaseCriteria IController_GetHorizontalThresholdReleaseCriteria IController_SetTimeoutReleaseCriteria IController_GetTimeoutReleaseCriteria
The Viewport Touch Controller is instanciated by passing AEECLSID_ViewportTC into ISHELL_CreateInstance. It is also created automatically by the Viewport Widget when touch is enabled and an OEM Viewport TC class could not be found.
The ViewportTC is reference-counted. When you are done with your reference to the ViewportTC, you should Release that reference. Any controller-specific cleanup will be handled for you when all references are released.