Skip to main content
Samsung Developer Program

Integrating AirButton

AirButton provides dynamic button enhancement to your UI elements (any view, which may or may not be a button). AirButton is hidden, and does not affect its associated view action, until the user hovers their S-Pen over the view. AirButton items are then displayed vertically (list AirButton) or horizontally (menu AirButton) with their position and action as specified by your app. Each AirButton item can display static text, a static image, or dynamic content populated by DefaultAdapters. When your users click on an AirButton item, your app is notified of the user selection in order to process it.

For details about the AirButton API, see AirButton API Structure.

AirButton Requirements

To enable AirButtons, the user device must be a Samsung Note device, which your app can determine by using the following code. 

Example Code: Checking Device Support of AirButton
import android.widget.Toast; 
import com.samsung.android.sdk.look.Slook; 

Slook slook = new Slook(); 
if(!slook.isFeatureEnabled(Slook.AIRBUTTON)) { 
    Toast.makeText(this, "This model doesn't support AirButton", 
        Toast.LENGTH_LONG).show(); 
}

AirButton User Experience

Your app can assign AirButtons to any view, for example, UI buttons, or non-active UI elements. Until a user invokes AirButton features, the view's UI element behaves normally, for example, tapping a UI button invokes its onClick event.  

Types of AirButtons

There are 2 types of AirButton layouts:

  • List AirButtons are vertically oriented.
  • Menu AirButtons are horizontally oriented. 

There are 3 types of AirButton content:

  • Text AirButton items display Unicode character strings.
  • Image AirButton items display bitmap image files.
  • Recipient AirButton items that receive their text or image content from Android objects.

There are 3 ways to provide AirButton item content:

  • Specifying static content for an individual item.
  • Populating static content for one or more items via an array.
  • Dynamically populating the content for one or more items via an Android default adapter.

AirButton Display

  • A user initiates a view's AirButton using their S-Pen by either:
    • Hovering outside and then moving the hover icon inside the view. The hover icon changes from the default hover icon to the AirButton hover icon.
    • Hovering inside the view. The AirButton hover icon is displayed.
  • AirButton items are displayed:
    • When a Pen event occurs while the user hovers their S-Pen over an AirButton view.
      Layout and content of items are controlled by your app:
    • The position of AirButton items relative to their view and each other is controlled by your app:
      • Button action is controlled by your app (such as item bounce effect and AirButton icon animation):
      • The number of items displayed is controlled by the following factors:
        • The maximum is controlled by the device screen size and orientation, and the position of the AirButton.
        • Only entire items are displayed in their index order (0, 1, 2, ...).
        • When their is not enough screen to display another item, that item and all higher-index numbered items are not displayed.
          List items that are not displayed are not available to the user for selection.

AirButtons must be hidden when the device is being re-oriented, or AirButton menus can be displayed at incorrect locations.

If your CustomView inherits from a ViewGroup, then you can use WritingBuddy directly. If not, add a framework for the exterior and use WritingBuddy from a FrameLayout.

AirButton UI Actions

  • When a user hovers over an AirButton view:
    • The maximum number of AirButton options will be displayed.
    • As the user hovers over another option, it is enlarged.
  • When a user selects an AirButton item by tapping it:
    • A user-select call is issued with the index number of the selected item.
    • The AirButton items disappear.

Setting Up AirButtons

Users can open an optimized menu for various contexts by pressing the side button in S-Pen.

Setting Up AirButtons with Static Content

Your app can create list or menu AirButtons that contain text, image, or recipient items with static content that is specified for each item or populated by an array. Your app can create list or menu AirButtons that contain text, image, or recipient items with content dynamically populated via an Android default adapter.  

To create a text, image, or recipient list AirButton, or a menu AirButton:

  1. Create a list AirButton object that targets a parent view (SlookAirButton(UI_TYPE_LIST)).
  2. Specify the listener to manage user selection of AirButton items (setItemSelectListener).
  3. Specify the location, action, and animation icon of the AirButton.
  4. Create an AirButton adapter object and populate it with AirButton items:
    1. Create an object with a specific list of items (SlookAirButtonAdapter(itemList))
      or without items (SlookAirButtonAdapter()).
    2. Manage the AirButton items: 
      1. Specify the text of the toast popup displayed when the list is empty (setEmptyText).
      2. Manage the number and order of items: 
  • Insert 1 item at the end of the AirButton list (addItem()).
  • Insert 1 or more items in their listed order at the end of the AirButton list (addItem(itemList)).
  • Insert 1 item at the specific position in the AirButton list (insertItem).
  • Delete a specific item (removeItem).
  • Update a specific item (updateItem).
  1. For each list item, manage its content:
  • For each text list AirButton:
    • Create an AirButton item object and specify its parent view data (AirButtonItem(view, data)).
    • Update its parent view data (set(view, data)).
  • For an image list AirButton:
    • Create an AirButton item object by either:
      • Specifying its image file, descriptive text, and data (AirButtonItem(image, description, data)).
      • Specifying its image file, first- and second-level descriptive text, and data (AirButtonItem(image, description, subDescription, data)).
    • Update its image file, descriptive text, and data (set(image, description, data)).
    • Update its image file, first- and second-level descriptive text, and data (set(image, description, subDescription, data)).
  • For a recipient list AirButton:
    • Create an AirButton item object and specify its parent view data (AirButtonItem(view, data)).
    • Update its its parent view data (set(view, data)).
  1. Register the listener to manage processing user-selected AirButton list items:
    1. For each list item, specify what action(s) will initiate a user-select callback for the item, and the content of the callback (onItemSelected).
Example Code: To create a text list AirButton
public SlookAirButton createTextListWidgetFromView(View v) { 
    /* Create AirButton instance with UI_TYPE_LIST */ 
    SlookAirButton airButtonWidget = new SlookAirButton(v, getAdapterStringList(), 
    SlookAirButton.UI_TYPE_LIST); 
    /* Set item select listener */
    airButtonWidget.setItemSelectListener(mCallback); 
    /* Set position */ 
    airButtonWidget.setPosition(0, 50); 

    return airButtonWidget; 
} 

/* Create adapter for text string */ 
public SlookAirButtonAdapter getAdapterStringList() { 
    ArrayList<AirButtonItem> stringList = new ArrayList<AirButtonItem>(); 
    stringList.add(newAirButtonItem(null, "/* text string */", null)); 
    ... 

    return new SlookAirButtonAdapter(stringList); 
}
Example Code:  To create an image list AirButton
public SlookAirButton createImageListWidgetFromView(View v) { 
    /* Instantian a list AirButton object. */ 
    SlookAirButton airButtonWidget = new SlookAirButton(v, getAdapterImageList(), 
        SlookAirButton.UI_TYPE_LIST); 
    /* Set the item select listener. */
    airButtonWidget.setItemSelectListener(mCallback); 
    /* Set gravity. */ 
    airButtonWidget.setGravity(SlookAirButton.GRAVITY_LEFT); 
    /* Set direction. */ 
    airButtonWidget.setDirection(SlookAirButton.DIRECTION_UPPER); 
    /* Set position. */ 
    airButtonWidget.setPosition(0, -50); 

    return airButtonWidget; 
} 

/* Create an adapter for the AirButton image items. */ 
public SlookAirButtonAdapter getAdapterImageList() { 
    ArrayList<AirButtonItem> itemList = new ArrayList<AirButtonItem>(); 
    itemList.add(new AirButtonItem(getResources().getDrawable(/* image */), null, 
        null)); 
    ...

    ​return new SlookAirButtonAdapter(itemList); 
}
Code Example:  To create a recipient list AirButton
public SlookAirButton createRecipientListWidgetFromView(View v) { 
    /* Create AirButton instance with UI_TYPE_LIST */ 
    SlookAirButton airButtonWidget = new SlookAirButton(v, 
        getAdapterRecipientList(), SlookAirButton.UI_TYPE_LIST); 
    /* Set direction */ 
    airButtonWidget.setDirection(SlookAirButton.DIRECTION_LOWER); 
    /* Set item select listener */ 
    airButtonWidget.setItemSelectListener(mCallback); 

    return airButtonWidget; 
} 

/* Create adapter for recipient list */ 
public SlookAirButtonAdapter getAdapterRecipientList() { 
    ArrayList<AirButtonItem> itemList = new ArrayList<AirButtonItem>(); 
    itemList.add(new AirButtonItem(getResources() 
        .getDrawable(R.drawable.recipient), "Alexander Hamilton", null)); 
    itemList.add(new AirButtonItem(/* image */, /* text */, null)); 
    . . . 

    return new SlookAirButtonAdapter(itemList); 
}

Menu AirButtons

Note: Note 4 and Note Edge do not support ‘Menu List’(UI_TYPE_MENU) AirButton.

See sample APK (3. Air Button > 1. Simple > Menu, 3. Air Button > 3.SurfaceView, 3. Air Button > 4. SurfaceView-Manual)

For Note 4 and Note Edge, opening the 'Menu List'(UI_TYPE_MENU) was changed from pressing the 'sidekey' to 'hovering' to improve usability.

To create a legacy menu list as a submenu for AirButton:

  1. Create an AirButton instance with type UI_TYPE_MENU.
  2. Set the direction for the AirButtoninstance.List (DIRECTION_AUTO, DIRECTION_LEFT or DIRECTION_RIGHT) .
    CAUTION: DIRECTION_UPPER and DIRECTION_LOWER are not supported, and result in an exception being thrown.
  3. Create an adapter for menu list.
Code Example
public class MainActivity extends Activity { 
    public SlookAirButton createMenuWidgetFromView(View v) { 
    /* Create AirButton instance using UI_TYPE_MENU. */ 
        SlookAirButton airButtonWidget = new SlookAirButton(v, 
            getAdapterMenuList(), SlookAirButton.UI_TYPE_MENU); 
    /* Set direction */ 
        airButtonWidget.setDirection(SlookAirButton.DIRECTION_RIGHT); 

        return airButtonWidget; 
    } 

    /* Create adapter for menu list*/
    public SlookAirButtonAdapter getAdapterMenuList() { 
        ArrayList<AirButtonItem> itemList = new ArrayList<AirButtonItem>(); 
        itemList.add(new AirButtonItem(mContext.getResources().getDrawable( 
            R.drawable.ic_menu_add), "Add", null)); 
        itemList.add(new AirButtonItem(mContext.getResources().getDrawable( 
            R.drawable.ic_menu_archive), "Help", null)); 
        itemList.add(new AirButtonItem(mContext.getResources().getDrawable( 
            R.drawable.ic_menu_edit), "Edit", null)); 
        itemList.add(new AirButtonItem(mContext.getResources().getDrawable( 
            R.drawable.ic_menu_help), "Help", null)); 

        return new SlookAirButtonAdapter(itemList); 
    } 
}

Setting Up DefaultAdaptor AirButtons

Your app can include an Android default adapter (either Look-provided or your own) into a recipient list AirButton in order to dynamically generate AirButton items.

The Look package provides 2 default adapters:

  • SlookAirButtonFrequentContactAdapter to present AirButton items of frequently accessed contacts. 
  • SlookAirButtonRecentMediaAdapter, to configure AirButton to display recently played media files.

SlookAirButtonFrequentContactAdapter

The Look package provides a default adapter, SlookAirButtonFrequentContactAdapter, to configure AirButton to display frequently accessed contacts. 

To use the default adapter, add the following permission in your Android manifest file.

Code Example:  
<manifest> 
    <uses-permission android:name="android.permission.READ_CONTACTS" /> 
<application>

The sample code below shows how to use SlookAirButtonFrequentContactAdapter.  The arg2 parameter is a bundle type value that contains the display name, data, URI, and thumbnail image.

Code Example
public SlookAirButton createRecipientListWidgetFromView(View v) { 
    Bundle option = new Bundle(); 
    option.putString("MIME_TYPE", "vnd.android.cursor.item/phone_v2"); 
    SlookAirButton airButtonWidget = new SlookAirButton(v, 
        new SlookAirButtonFrequentContactAdapter(v, null), 
            SlookAirButton.UI_TYPE_LIST); 
    airButtonWidget.setDirection(SlookAirButton.DIRECTION_UPPER); 
    airButtonWidget.setItemSelectListener(new ItemSelectListener() { 

        public void onItemSelected(View arg0, int arg1, Object arg2) { 

            Bundle bundle = (Bundle) arg2; 
            String name = bundle 
                .getString(SlookAirButtonFrequentContactAdapter 
                    .DISPLAY_NAME); 
            String data = bundle 
                .getString(SlookAirButtonFrequentContactAdapter.DATA); 

            Toast.makeText(AirButtonDefaultActivity.this, 
                name + ":" + data, Toast.LENGTH_SHORT).show(); 
        }
    }); 

    return airButtonWidget; 
}

SlookAirButtonRecentMediaAdapter

The Look package offers a default adapter, SlookAirButtonRecentMediaAdapter, to configure AirButton to display recently played media files.

The sample code below shows how to use SlookAirButtonRecentMediaAdapter:

  • The second parameter for the adapter is a bundle type value that contains a Boolean value, true or false, for IMAGE_TYPE, VIDEO_TYPE, and AUDIO_TYPE. For example, Bundle.putBoolean(IMAGE_TYPE, true).
  • Cast the arg2 parameter to URI.

Only UI_TYPE is available for this default adapter, and it is used as a parameter for the SlookAirButton constructor.

Code Example
public SlookAirButton createImageListWidgetFromView(View v) {
    SlookAirButton airButtonWidget = new SlookAirButton(v, 
        new SlookAirButtonRecentMediaAdapter(v, null), 
            SlookAirButton.UI_TYPE_LIST); 
    airButtonWidget.setItemSelectListener(new ItemSelectListener() { 

        public void onItemSelected(View arg0, int arg1, Object arg2) { 
            Uri uri = (Uri) arg2; 
            Toast.makeText(AirButtonDefaultActivity.this, uri.toString(), 
                Toast.LENGTH_SHORT).show(); 
        } 
    }); 

    airButtonWidget.setGravity(SlookAirButton.GRAVITY_LEFT); 
    airButtonWidget.setDirection(SlookAirButton.DIRECTION_UPPER); 
    airButtonWidget.setPosition(0, -50); 

    return airButtonWidget; 
}

Hello AirButton

Hello AirButton is a sample application that: creates an AirButton instance and creates a text menu as a submenu.

To create a sample application:

Add the following layout to your activity_main.xml file:

Code Example
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android:layout_width="match_parent" 
android:layout_height="match_parent" 
android:orientation="vertical"> 

<Button 
android:id="@+id/button1" 
android:layout_width="match_parent" 
android:layout_height="wrap_content" 
android:layout_marginTop="100dip"
android:text="AirButton"/> 
</ LinearLayout>
package com.example.airbutton; 

import java.util.ArrayList; 

import android.app.Activity; 
import android.content.Context; 
import android.os.Bundle; 
import android.view.Menu; 
import android.view.View; 
import android.widget.Button; 
import android.widget.Toast; 

import com.samsung.android.sdk.look.airbutton.SlookAirButton; 
import com.samsung.android.sdk.look.airbutton.SlookAirButton.ItemSelectListener; 
import com.samsung.android.sdk.look.airbutton.SlookAirButtonAdapter; 
import com.samsung.android.sdk.look.airbutton.SlookAirButtonAdapter.AirButtonItem; 

public class MainActivity extends Activity { 
    private Context vContext = null; 
    private Button vBtnText = null; 

    @Override 
    protected void onCreate(Bundle savedInstanceState) { 
        super.onCreate(savedInstanceState); 
        vContext = this; 

        setContentView(R.layout.activity_main); 
        vBtnText = (Button) findViewById(R.id.button1); 
        createTextListWidgetFromView(vBtnText); 
    } 

    private ItemSelectListener vCallback = new ItemSelectListener() { 
        @Override 
        public void onItemSelected(View v, int itemIndex, Object data) { 
            Toast.makeText(vContext, "Item index = " + itemIndex, 
                Toast.LENGTH_SHORT).show(); 
        } 
    }; 

    public SlookAirButton createTextListWidgetFromView(View v) { 
        SlookAirButton airButtonWidget = new SlookAirButton(v, 
            getAdapterStringList(), SlookAirButton.UI_TYPE_LIST); 
        airButtonWidget.setItemSelectListener(vCallback); 
        airButtonWidget.setPosition(0, 0); 

        return airButtonWidget; 
    } 

    public SlookAirButtonAdapter getAdapterStringList() { 
        ArrayList<AirButtonItem> stringList = new ArrayList<AirButtonItem>(); 
        stringList.add(new AirButtonItem(null, "1st Text Menu", null)); 
        stringList.add(new AirButtonItem(null, "2nd Text Menu", null)); 
        stringList.add(new AirButtonItem(null, "3rd Text Menu", null));

        return new SlookAirButtonAdapter(stringList); 
    } 
}
  • Was this article helpful?