Developer

API Reference

AEECLSID_ButtonTC

Brew Release
Brew MP 1.0.2
See Also
AEECLSID_ButtonWidget Border Support Events Border Decoration Events Widget Events AEEEvent Model Events StepEvent
Description

ButtonTC is an implementation of IController that can be used by Button Widget to handle BREW pointer events. It is used as the default touch controller for Button Widget if AEECLSID_OEMButtonTC is not concrete.
When the default button touch controller receives a pointer down event, it begins to track the movement of the pointer and puts the button into a depressed (selected) state. If the pointer ever leaves the bounding rectangle of the button, it will revert to the 'natural' state until the pointer returns to the button's confines or the press is released (at which point the button will no longer capture touch events until it is once again pressed). If the user releases the press within the confines of the button, it will count it as a button press which will return the button to its natural state and send a EVT_MDL_WIDGETELM_CLICK event out through the view model.
Early capture release based on timeout and radius threshold release criteria - This feature is used in tandem with other decorators or containers that support release criteria. It allows the button to tentatively take capture and if it does not understand the gesture that the user is performing (such as panning or flick), 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 ButtonTC. An application can enable early capture release using IController_SetRadiusThresholdReleaseCriteria().
ButtonTC 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, ButtonTC will release capture if button does not receive EVT_POINTER_UP within the timeout period specified by the timeout release criteria.

Events:


Event                   Description
----------              ----------------------------------------------------------------------------
EVT_POINTER_DOWN        Enables capture mode (tracks moves that go outside the extent of the widget)
                        and puts the attached widget into the pressed (selected) state.

EVT_POINTER_MOVE
EVT_POINTER_STATE_MOVE  Tracks the movement of the pointer.  If the pointer strays outside the
                        bounding rectangle, it resets the widget to the natural (unselected) state
                        and re-presses it if the pointer then returns to the button.

EVT_POINTER_UP          If the pointer remains in the button's extent, restores the button to the
                        natural (unselected) state and sends a click event to the attached viewmodel.

EVT_WDG_SETPROPERTY     The Button Touch Controller handler responds to this event by attempting to
                        set the property identified by the 'wParam' parameter.  The following properties
                        may be set by the ButtonTC Event Handler.
                        PROP_VIEWMODEL
                        PROP_EX
                        PROPEX_WIDGETTC_PRESSED
                           IWidget_SetProperty
                           IWidget_SetPropertyEx

Properties:


Property                      Description
--------                      ------------------------------------------------------------
PROP_VIEWMODEL                Property to set the view model associated with the Button Touch
                              Controller.
                                  IWidget_SetViewModel

PROP_EX                       Property used to specify an extended property.
                                  IWidget_GetPropertyEx
                                  IWidget_SetPropertyEx

PROPEX_WIDGETTC_PRESSED       This property is used to simulate a pointer up or down on the widget.

APIs supported: IController_SetRadiusThresholdReleaseCriteria IController_GetRadiusThresholdReleaseCriteria IController_SetTimeoutReleaseCriteria IController_GetTimeoutReleaseCriteria
Instantiaion
The Button Touch Controller is instantiated by passing AEECLSID_ButtonTC into ISHELL_CreateInstance
Cleanup
The ButtonTC is reference-counted. When you are done with your reference to the buttonTC, you should Release that reference. Any controller specific cleanup will be handled for you when all references are released
Default Interface Name
Other Interfaces
  • Follow