Resources | Resources |



Enabling viewport rubber banding

Viewport rubber banding is a feature that causes the content of a viewport to snap to a particular offset position when it is scrolled and released by the user. The sameple code shown in this topic is from c_viewportrubberbanding_1.0.0.

By default, the feature is disabled in the viewport touch controller. For backward compatibility reasons, the viewport will not initially scroll and pan its content when touched, instead, it will attempt to pass touch events to its child widget (the widget it decorates), if the child can handle the event.

After the application has created a root container, enabled touch support, and provided the root container with a canvas, it can enable viewport rubber banding as follows:

  1. Enable viewport consumption of touch events.
  2. Ensure the widget decorated by the viewport does not attempt to handle all touch events.
  3. Enable rubber banding on the viewport touch controller.
  4. Set appropriate snap offsets.

On receipt of the EVT_APP_START event, a viewport is created, which decorates an XY container widget (the strip). The strip contains a row of colored XY containers (blocks). Each block contains a button widget. This allows the user to scroll the content of the viewport with a touchscreen pointer, while allowing descendants of the viewport (the buttons) to handle touch events when required.

Note: The buttons in this example perform only their default (up/down) behavior.

As the viewport is smaller than its child widget, the user is able to scroll the strip of colored blocks through the viewport, using a touchscreen pointer. Because rubber banding is enabled, the viewport will continue to scroll the strip to the nearest snap offset when the user removes the pointer from the screen, rather than allowing it to come to rest at any arbitrary position.

Event handling

The applet handles EVT_APP_START, EVT_APP_STOP, and EVT_APP_RESUME events. Touchscreen pointer events received by the applet are handled by the viewport touch controller and the button widget touch controller (no special handling is required by the applet itself).

Example - Create a viewport and enable rubber banding

For the viewport touch controller to respond to touch events, the viewport must be set to consume them. This allows the user to scroll the contents of the viewport.

// Make the viewport consume touch events so it can handle
// scrolling of the strip
nErr = IWidget_AddFlags(pViewportWgt, VWF_CONSUMETOUCHEVENTS);

Rubber banding must be enabled on the viewport touch controller. It must also be provided with appropriate snap offsets.

// Get the viewport's touch controller
if (AEE_SUCCESS == nErr) nErr = IWidget_GetTouchController(pViewportWgt, &pViewportTC);

if (AEE_SUCCESS == nErr && pViewportTC) {
   // Enable rubberbanding in the touch controller
   nErr = IController_EnableRubberBand(pViewportTC, TRUE);

   // Set the rubberbanding snap offsets
   if (AEE_SUCCESS == nErr) nErr = IController_SetHorizontalSnapOffsets
   (pViewportTC, pMe->m_nSnapOffsets, NUM_BLOCKS);


The strip of blocks viewed through the viewport must pass touch events to its descendants when necessary. This allows the buttons, which are children of the children of the strip, to function; however, the viewport touch controller must respond to touch events outside the children to support scrolling of its contents.

nErr = IWidget_SetTouchMode(pStripWgt, AEEWIDGET_TOUCH_MODE_CHILD);
// Make the block pass touch events to its child
nErr = IWidget_SetTouchMode(pBlockWgt, AEEWIDGET_TOUCH_MODE_CHILD);