Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Touch controller classes

Touch controller classes are implementations of IController that can be used by their corresponding widgets to handle pointer events provided to the widget by Brew MP.

Button

ButtonTC is an implementation of IController that can be used by button widget to handle Brew MP pointer events. It is used as the default touch controller for button widget if AEECLSID_COEMButtonTC is not found.

The button touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CButtonTC ClassID.

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 leaves the bounding rectangle of the button, it reverts to the unpressed state until the pointer returns to the button's confines or the user lifts the finger (at which point the button does not capture touch events until it is pressed again). If the user lifts the finger within the confines of the button, it counts it as a button press which returns the button to its natural state and sends an EVT_MDL_WIDGETELM_CLICK event through the view model.

Check and Radio

CheckTC and RadioTC are implementations of IController that are used by check widget and radio widget to handle Brew MP pointer events. These are the default touch controllers for these widgets if AEECLSID_COEMCheckTC is not found.

The default touch controllers for check and radio widgets are very simple. When a controller receives a pointer down followed by a pointer up within the extent of the bounding rectangle of the check or radio widget, it either toggles the value model of the widget (in the case of the check widget) or sets the value model to true (in the case of the radio button widget). The pointer may be moved throughout the widget canvas as long as the pointer up occurs within the confines of the same widget that received the pointer down.

Container

ContainerTC is an implementation of IController that can be used by any container to handle pointer events provided to the widgets by Brew MP.

ContainerTC handles Brew MP pointer events for any type of container and responds by:

  • Moving focus between the children. On EVT_POINTER_DOWN, ContainerTC checks if the event is for a child that does not currently have focus. If that is the case, it asks the child widget if it can take focus (using EVT_WDG_CANTAKEFOCUS) and moves focus to this child widget, if it can take focus. (This results in an EVT_MDL_FOCUS_CHANGE view model event).

  • Localizing all events and passing them to the child widgets. ContainerTC processes all EVT_POINTER_XXX events. After it determines the child widget to which the event needs to be sent, it localizes the event in the child widget's co-ordinate system and passes it to that widget.

Note that the above ContainerTC behavior is implemented by containers themselves by default; containers do not need any explicit controller. A new instance of the ContainerTC class object can be created by calling ISHELL_CreateInstance() and with the AEECLSID_CContainerTC ClassID.

DateTime

DateTimeTC is an implementation of IController that is used by the date and time widgets to handle Brew MP pointer events. It is used as the default touch controller for these widgets if AEECLSID_COEMDateTimeTC is not found.

The default touch controller for date and time widgets performs two actions:

  • When a pointer down event occurs on a date/time field, the focus is changed to that field.
  • If the DTWF_SHOWARROWS flag has been applied to the date/time widget, and the pointer is held down on an arrow, the value of the field in the date/time widget is incremented or decremented. If the pointer is continuously held down on the arrow, the increment or decrement continues repeatedly following a specified delay (the amount of time between the first and second repeat) and repeat rate (the amount of time between any successive repeats).

The Date Time Touch Controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CDateTimeTC ClassID.

Generic

GenericTC is an implementation of IController that can be used by widgets that do not have a default touch controller. These widgets can use GenericTC to handle pointer events and receive gesture notifications for single tap, double tap, and tap and hold. For example, an image widget could use GenericTC to detect a tap and change its border color to indicate that it has been selected.

GenericTC performs the following actions:

  • Sends double tap notification on EVT_POINTER_DOWN, if a double tap is detected.
  • Sends single tap notification on EVT_POINTER_UP, if a tap is detected.
  • Sends tap and hold notification, if a tap and hold gesture is detected.

The Generic Touch Controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CGenericTC ClassID.

Grid container

GridContainerTC is an implementation of IController that can be used by grid container to handle pointer events provided to the widget by Brew MP. GridContainerTC is an extension to ContainerTC that adds notifications when pointer events occur.

GridContainerTC performs the following actions:

  • Moving focus
  • Localizing events for its children
  • Sending view model notifications about pointer events.

    On first occurrence of EVT_POINTER_DOWN, GridContainerTC uses the view model to notify with WECLTYPE_CLICK. If a second EVT_POINTER_DOWN happens at the same time, and click count in the event is 2, then grid container notifies with WECLTYPE_DOUBLECLICK.

    An application can add a listener to the grid container's view model and listen for EVT_MDL_WIDGETELEM_CLICK to know when an item was tapped or double-tapped.

To create a grid container touch controller object, call ISHELL_CreateInstance() with the AEECLSID_CGridContainerTC ClassID.

List

ListTC is an implementation of IController that can be used by a list widget to handle Brew MP pointer events. It is used as the default touch controller for list widget if AEECLSID_COEMListTC is not found.

The default list touch controller performs numerous operations based on the current state of the pointer. When it receives 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 follows the pointer as it moves up and down across the items. If live scroll has been enabled, the item tapped follows 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.

The list touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CListTC ClassID.

Root

RootTC is an implementation of IController that can be used by root container to handle pointer events provided to the container by Brew MP. RootTC queries touch observer to detect single tap occurrence on pointer down event and double tap occurrence on pointer up event and updates the pointer event string provided to the container by Brew MP with the single or double tap information.

Capture mode changes how the RootTC routes certain pointer events. A widget can call IWIDGET_SetCapture() to set capture mode to TRUE, which means the widget receives pointer events, regardless of the coordinates, until an EVT_POINTER_UP event is received, all fingers are off the screen in multitouch mode, or the widget releases capture mode. Only one widget can have capture at a time, even in multi-touch mode.

If a widget has set capture mode, RootTC sends EVT_POINTER_UP, EVT_POINTER_MOVE, and EVT_POINTER_STALEMOVE events directly to the capture widget. In multitouch mode, all EVT_POINTER_DOWN events after the first one are also sent to the capture widget. If no capture widget exists, all events are sent to the container touch controller.

The Root Touch Controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CRootTC ClassID.

Scroll

ScrollTC is an implementation of IController that can be used by the scrollbar widget and scrollindicator widget to handle pointer events provided to the widget by Brew MP.

ScrollTC sends the EVT_WDG_SCROLL event to the widget it decorates, with different wParam and dwParam values based on the location of the pointer event. It is the child widget's responsibility to change its view to correspond to the scroll event. For more information on the wParam and dwParam values, see AEECLSID_CScrollTC in the http://developer.brewmp.com/reference/api-all.

If an application needs to customize scrolling behavior, it should set a custom handler on the child widget and the custom handler should handle the EVT_WDG_SCROLL event.

The scroll touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CScrollTC ClassID.

Slider

SliderTC is an implementation of IController that can be used by slider widget to handle pointer events provided to the widget by Brew MP.

When the SliderTC receives an EVT_POINTER_DOWN event, it initiates a drag if the pointer event occurred on the slider handle. If the event occurred on the slider-bar, SliderTC sends EVT_WDG_SCROLL to the slider widget, which handles the scrolling of the slider handle.

The default scroll delay and scroll rate can be modified by calling on the following functions:

  • IController_SetScrollRepDelay()
  • IController_GetScrollRepDelay()
  • IController_SetScrollRepRate()
  • IController_GetScrollRepRate()

The slider touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CSliderTC ClassID.

Softkey

SoftkeyTC is an implementation of IController that can be used by the softkey widget to handle pointer events provided to the widget by Brew MP. SoftkeyTC handles Brew MP pointer events for a softkey widget and responds by listening to EVT_POINTER_DOWN and sending view model notification with WECLTYPE_CLICK.

The softkey touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CSoftkeyTC ClassID.

Tab

TabTC is an implementation of IController that can be used by the tab widget to handle pointer events provided to the widget by Brew MP. When the TabTC receives a pointer down event, it moves the focus to the appropriate tab. If the pointer down occurs on a tab, it moves the focus to that tab. If the tab widget has arrows for navigation, and the pointer down occurs on an arrow, the focus is moved to the previous or next tab, depending on the arrow selected. If the pointer event occurs inside the tab content, the event is passed to the appropriate child widget.

The tab widget touch controller is instantiated by calling ISHELL_CreateInstance() with the AEECLSID_CTabTC ClassID.

Viewport

ViewportTC is an implementation of IController that can be used by a viewport widget to handle Brew MP pointer events. It is used as the default touch controller for the viewport widget if AEECLSID_COEMViewportTC is not found.

To provide backward compatibility, the viewport widget by default does not send touch events to the ViewportTC. Instead, it passes touch events to its child widget. To change this functionality, an application can set the VWF_CONSUMETOUCHEVENTS flag for the viewport widget.

In addition, ViewportTC will pass pointer down events to its child widget if the child says that it can handle the event. By default, all widgets have a default touch mode of AEEWIDGET_TOUCH_MODE_ALWAYS, meaning that the ViewportTC always passes touch events to the child. This will result in the Viewport never attempting to live scroll or flick, which provides a better user experience when a viewport is wrapping a container that includes clickable elements such as slider bars and buttons. If an application always wants touch events to be interpreted as part of a live scroll or flick, it can set the child widget's touch mode to AEEWIDGET_TOUCH_MODE_NEVER by calling IWidget_SetTouchMode().

The viewport touch controller is instantiated by calling ISHELL_CreateInstance()with the AEECLSID_CViewportTC ClassID.