Chapter 3. Wheel

Summary

_static_/{GAMA_devGuide} wheel_component.png

The Wheel Component is a widget for selecting an item using the dial. It is a view that shows items in a circle scrolling. Let's use the Wheel Component when you need to support wheel style UX like turning the dial and previewing items. The component is useful to show the main menu, the option menu and the selecting menu more visually in applications.

GAMA Wheel Component has the following features:

  • You may configure as you wish such as the item and background images configuration, widget size and position setting, and so on.

  • It handles user's subtle touch input and supports a smooth and realistic flicking motion. The range of touch input can be set as well.

  • Supports a variety of event-handling when selecting each item.

  • It is fully compatible with other Android widgets.

You may download a showcase with full-functionality of the Wheel Component in Android Market. In this section, you'll write a sample code that adds a wheel to the activity of Android.

Elements of Wheel Component

Items

A list of the images shown through the Wheel Component. It is rotated based on the center of the Wheel.

Background image

It is used when it is rotated with the items of the wheel or decorated the Wheel itself.

Creating Your First Application with GAMA Wheel Component

If you link the Wheel Component to your project on the Eclipse IDE, You can import the Wheel.

 import com.digitalaria.gama.wheel.Wheel;

Wheel component is composed of Android FrameLayout. As you know, the Wheel can be described on the layout XML file. So let's define them in main.xml file:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >

    <TextView
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Hello, GAMA!" />
    
    <com.digitalaria.gama.wheel.Wheel
        android:id="@+id/wheel"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center_horizontal"/>

</LinearLayout>

Like other components, default data has to be set for the operation. The setting data will be delivered to the Wheel component. And if one sets the diameter of Wheel, items will be located around the circle.

A typical use of this component in an activity would be the following:

private Wheel wheel;
private Resources res; 
private int[] icons = { 
 R.drawable.icon00, R.drawable.icon01, R.drawable.icon02, 
 R.drawable.icon03, R.drawable.icon04, R.drawable.icon05, 
 R.drawable.icon06, R.drawable.icon07, R.drawable.icon08, 
 R.drawable.icon09, R.drawable.icon10, R.drawable.icon11 };
    
private void init() {
  res = getApplicationContext().getResources();
  wheel = (Wheel) findViewById(R.id.wheel);

  // set the image what items will be in wheel.
  wheel.setItems(getDrawableFromData(icons)); 

  // set the diameter of Wheel.
  wheel.setWheelDiameter(400); 
}

// This function is a helper for drawable data.
private Drawable[] getDrawableFromData(int[] data) {
  Drawable[] ret = new Drawable[data.length];
  for (int i = 0; i < data.length; i++) {
    ret[i] = res.getDrawable(data[i]);
  }
  return ret;
}

The result of this code is like below.

_static_/{GAMA_devGuide} wheel_result.png

Also, we will need a background image of Wheel, current selected item and if items will be rotated. The variety of other functions for the Wheel is provided through the Wheel component API. For more information about this component, please refer to the Wheel Component API and the GAMA developers Forum.

Download