Resources | Resources |



Setting release criteria on widgets

Setting release criteria on widgets is a way to enhance user touch interactions. By using release critieria, an application can allow users to interact with more than one widget with a single touch.

For example, in an email application in which the default view is a list of email titles sorted by date, the user can touch an email to open it, and can also pan and/or flick the list vertically to view older or newer emails. When the user first touches or flicks an email, the application assumes that the user wishes to open the email. Control of the pointer stream then passes to the button representing the individual email item. By setting up a release criteria on the email item button, the application specifies that if the user moves a finger more than 15 pixels vertically, the button will release the pointer string back to its parent list container, allowing the user to perform the list scrolling action.

Some other interactions in which an application could use release criteria are

  • A list of buttons in which the user can press/pan over the buttons
  • A keyboard in which the user presses an "a," and it is released so that the keyboard can pick up the user's press on the "s."
  • A global scroll action in which the user does a horizontal flick to change applications
  • A timer on a critical button that allows an inexperienced user to escape from an action they cannot undo.

This example describes the process for setting release criteria on widgets. It does not provide an example of creating your own release criteria, which requires a custom touch controller. See Creating a Custom Touch Controller in on the Brew MP website. The example code is this topic is from c_releasecriteria_app.

To set up release criteria for a widget, an application needs to do the following:

  1. Create the widget on which you want to set release criteria.
  2. Get the touch controller of the widget in one of two ways:
    • Enable touch on that widget and retrieve the created touch controller.
    • Create a custom touch controller and set that on the widget. For more information on creating a custom touch controller, see Creating a Custom Touch Controller in on the Brew MP website.
  3. Set the required release criteria.

Each step is described in greater detail in the sections below.

Create the widget on which release criteria will be set

Create a button widget by calling IEnv_CreateInstance() or ISHELL_CreateInstance().

Note: An application can also create a button widget using a custom function that wraps ISHELL.

IDecorator  *pidButton = NULL;    
IWidget     *piwButton = NULL;    
IController *picButton = NULL;    
ERR_TRY(ISHELL_CreateInstance(me->piShell, AEECLSID_CButtonWidget,(void**)&pidButton));    
ERR_TRY(IDecorator_QueryInterface(pidButton, AEEIID_IWidget, (void**)&piwButton));    

Get the touch controller of the widget

Retrieve the touch controller of the widget. Make sure the widget has been touch-enabled, because widgets only create their default touch controllers after touch has been enabled on them.

ERR_TRY( IWidget_EnableTouch(piwButton) );    
ERR_TRY( IWidget_GetTouchController(piwButton, &picButton) );    

Note: You can create your own touch controller and attach it to the widget. See Creating a Custom Touch Controller in on the Brew MP website.

ERR_TRY(IWidget_SetTouchController(piwButton, picButton));    

Set the required release criteria

Set the necessary release criteria on the object, such as the timeout, radius, or horizontal or vertical threshold.

releaseCriteria.bEnable    = TRUE;    
releaseCriteria.nThreshold = thresholdValue;    
ERR_TRY( IController_SetTimeoutReleaseCriteria(picButton, releaseCriteria) );