xref: /development/samples/Support4Demos/src/com/example/android/supportv4/widget/ExploreByTouchHelperActivity.java

/*
 * Copyright (C) 2013 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.android.supportv4.widget;

import android.annotation.TargetApi;
import android.app.Activity;
import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Paint.Align;
import android.graphics.Paint.Style;
import android.graphics.Rect;
import android.graphics.RectF;
import android.os.Build;
import android.os.Bundle;
import android.support.v4.view.ViewCompat;
import android.support.v4.view.accessibility.AccessibilityNodeInfoCompat;
import android.support.v4.view.accessibility.AccessibilityNodeProviderCompat;
import android.support.v4.widget.ExploreByTouchHelper;
import android.util.AttributeSet;
import android.view.MotionEvent;
import android.view.View;
import android.view.accessibility.AccessibilityEvent;
import com.example.android.supportv4.R;

import java.util.ArrayList;
import java.util.List;

/**
 * This example shows how to use the {@link ExploreByTouchHelper} class in the
 * Android support library to add accessibility support to a custom view that
 * represents multiple logical items.
 * <p>
 * The {@link ExploreByTouchHelper} class wraps
 * {@link AccessibilityNodeProviderCompat} and simplifies exposing information
 * about a custom view's logical structure to accessibility services.
 * <p>
 * The custom view in this example is responsible for:
 * <ul>
 * <li>Creating a helper class that extends {@link ExploreByTouchHelper}
 * <li>Setting the helper as the accessibility delegate using
 * {@link ViewCompat#setAccessibilityDelegate}
 * <li>Dispatching hover events to the helper in {@link View#dispatchHoverEvent}
 * </ul>
 * <p>
 * The helper class implementation in this example is responsible for:
 * <ul>
 * <li>Mapping hover event coordinates to logical items
 * <li>Exposing information about logical items to accessibility services
 * <li>Handling accessibility actions
 * <ul>
 */
public class ExploreByTouchHelperActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.explore_by_touch_helper);

        final CustomView customView = (CustomView) findViewById(R.id.custom_view);

        // Adds an item at the top-left quarter of the custom view.
        customView.addItem(getString(R.string.sample_item_a), 0, 0, 0.5f, 0.5f);

        // Adds an item at the bottom-right quarter of the custom view.
        customView.addItem(getString(R.string.sample_item_b), 0.5f, 0.5f, 1, 1);
    }

    /**
     * Simple custom view that draws rectangular items to the screen. Each item
     * has a checked state that may be toggled by tapping on the item.
     */
    public static class CustomView extends View {
        private static final int NO_ITEM = -1;

        private final Paint mPaint = new Paint();
        private final Rect mTempBounds = new Rect();
        private final List<CustomItem> mItems = new ArrayList<CustomItem>();
        private CustomViewTouchHelper mTouchHelper;

        public CustomView(Context context, AttributeSet attrs) {
            super(context, attrs);

            // Set up accessibility helper class.
            mTouchHelper = new CustomViewTouchHelper(this);
            ViewCompat.setAccessibilityDelegate(this, mTouchHelper);
        }

        @TargetApi(Build.VERSION_CODES.ICE_CREAM_SANDWICH)
        @Override
        public boolean dispatchHoverEvent(MotionEvent event) {
            // Always attempt to dispatch hover events to accessibility first.
            if (mTouchHelper.dispatchHoverEvent(event)) {
                return true;
            }

            return super.dispatchHoverEvent(event);
        }

        @Override
        public boolean onTouchEvent(MotionEvent event) {
            switch (event.getAction()) {
                case MotionEvent.ACTION_DOWN:
                    return true;
                case MotionEvent.ACTION_UP:
                    final int itemIndex = getItemIndexUnder(event.getX(), event.getY());
                    if (itemIndex >= 0) {
                        onItemClicked(itemIndex);
                    }
                    return true;
            }

            return super.onTouchEvent(event);
        }

        /**
         * Adds an item to the custom view. The item is positioned relative to
         * the custom view bounds and its descriptions is drawn at its center.
         *
         * @param description The item's description.
         * @param top Top coordinate as a fraction of the parent height, range
         *            is [0,1].
         * @param left Left coordinate as a fraction of the parent width, range
         *            is [0,1].
         * @param bottom Bottom coordinate as a fraction of the parent height,
         *            range is [0,1].
         * @param right Right coordinate as a fraction of the parent width,
         *            range is [0,1].
         */
        public void addItem(String description, float top, float left, float bottom, float right) {
            final CustomItem item = new CustomItem();
            item.bounds = new RectF(top, left, bottom, right);
            item.description = description;
            item.checked = false;
            mItems.add(item);
        }

        @Override
        protected void onDraw(Canvas canvas) {
            super.onDraw(canvas);

            final Paint paint = mPaint;
            final Rect bounds = mTempBounds;
            final int height = getHeight();
            final int width = getWidth();

            for (CustomItem item : mItems) {
                paint.setColor(item.checked ? Color.RED : Color.BLUE);
                paint.setStyle(Style.FILL);
                scaleRectF(item.bounds, bounds, width, height);
                canvas.drawRect(bounds, paint);
                paint.setColor(Color.WHITE);
                paint.setTextAlign(Align.CENTER);
                canvas.drawText(item.description, bounds.centerX(), bounds.centerY(), paint);
            }
        }

        protected boolean onItemClicked(int index) {
            final CustomItem item = getItem(index);
            if (item == null) {
                return false;
            }

            item.checked = !item.checked;
            invalidate();

            // Since the item's checked state is exposed to accessibility
            // services through its AccessibilityNodeInfo, we need to invalidate
            // the item's virtual view. At some point in the future, the
            // framework will obtain an updated version of the virtual view.
            mTouchHelper.invalidateVirtualView(index);

            // We also need to let the framework know what type of event
            // happened. Accessibility services may use this event to provide
            // appropriate feedback to the user.
            mTouchHelper.sendEventForVirtualView(index, AccessibilityEvent.TYPE_VIEW_CLICKED);

            return true;
        }

        protected int getItemIndexUnder(float x, float y) {
            final float scaledX = (x / getWidth());
            final float scaledY = (y / getHeight());
            final int n = mItems.size();

            for (int i = 0; i < n; i++) {
                final CustomItem item = mItems.get(i);
                if (item.bounds.contains(scaledX, scaledY)) {
                    return i;
                }
            }

            return NO_ITEM;
        }

        protected CustomItem getItem(int index) {
            if ((index < 0) || (index >= mItems.size())) {
                return null;
            }

            return mItems.get(index);
        }

        protected static void scaleRectF(RectF in, Rect out, int width, int height) {
            out.top = (int) (in.top * height);
            out.bottom = (int) (in.bottom * height);
            out.left = (int) (in.left * width);
            out.right = (int) (in.right * width);
        }

        private class CustomViewTouchHelper extends ExploreByTouchHelper {
            private final Rect mTempRect = new Rect();

            public CustomViewTouchHelper(View forView) {
                super(forView);
            }

            @Override
            protected int getVirtualViewAt(float x, float y) {
                // We also perform hit detection in onTouchEvent(), and we can
                // reuse that logic here. This will ensure consistency whether
                // accessibility is on or off.
                final int index = getItemIndexUnder(x, y);
                if (index == NO_ITEM) {
                    return ExploreByTouchHelper.INVALID_ID;
                }

                return index;
            }

            @Override
            protected void getVisibleVirtualViews(List<Integer> virtualViewIds) {
                // Since every item should be visible, and since we're mapping
                // directly from item index to virtual view id, we can just add
                // every available index in the item list.
                final int n = mItems.size();
                for (int i = 0; i < n; i++) {
                    virtualViewIds.add(i);
                }
            }

            @Override
            protected void onPopulateEventForVirtualView(
                    int virtualViewId, AccessibilityEvent event) {
                final CustomItem item = getItem(virtualViewId);
                if (item == null) {
                    throw new IllegalArgumentException("Invalid virtual view id");
                }

                // The event must be populated with text, either using
                // getText().add() or setContentDescription(). Since the item's
                // description is displayed visually, we'll add it to the event
                // text. If it was only used for accessibility, we would use
                // setContentDescription().
                event.getText().add(item.description);
            }

            @Override
            protected void onPopulateNodeForVirtualView(
                    int virtualViewId, AccessibilityNodeInfoCompat node) {
                final CustomItem item = getItem(virtualViewId);
                if (item == null) {
                    throw new IllegalArgumentException("Invalid virtual view id");
                }

                // Node and event text and content descriptions are usually
                // identical, so we'll use the exact same string as before.
                node.setText(item.description);

                // Reported bounds should be consistent with those used to draw
                // the item in onDraw(). They should also be consistent with the
                // hit detection performed in getVirtualViewAt() and
                // onTouchEvent().
                final Rect bounds = mTempRect;
                final int height = getHeight();
                final int width = getWidth();
                scaleRectF(item.bounds, bounds, width, height);
                node.setBoundsInParent(bounds);

                // Since the user can tap an item, add the CLICK action. We'll
                // need to handle this later in onPerformActionForVirtualView.
                node.addAction(AccessibilityNodeInfoCompat.ACTION_CLICK);

                // This item has a checked state.
                node.setCheckable(true);
                node.setChecked(item.checked);
            }

            @Override
            protected boolean onPerformActionForVirtualView(
                    int virtualViewId, int action, Bundle arguments) {
                switch (action) {
                    case AccessibilityNodeInfoCompat.ACTION_CLICK:
                        // Click handling should be consistent with
                        // onTouchEvent(). This ensures that the view works the
                        // same whether accessibility is turned on or off.
                        return onItemClicked(virtualViewId);
                }

                return false;
            }

        }

        public static class CustomItem {
            private String description;
            private RectF bounds;
            private boolean checked;
        }
    }
}