display/BrailleInputEvent.java

/*
 * Copyright (C) 2012 Google Inc.
 *
 * 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.googlecode.eyesfree.braille.display;

import android.os.Parcel;
import android.os.Parcelable;
import android.util.SparseArray;

import java.util.HashMap;

/**
 * An input event, originating from a braille display.
 *
 * An event contains a command that is a high-level representation of the
 * key or key combination that was pressed on the display such as a
 * navigation key or braille keyboard combination.  For some commands, there is
 * also an integer argument that contains additional information.
 */
public class BrailleInputEvent implements Parcelable {

    // Movement commands.

    /** Keyboard command: Used when there is no actual command. */
    public static final int CMD_NONE = -1;

    /** Keyboard command: Navigate upwards. */
    public static final int CMD_NAV_LINE_PREVIOUS = 1;
    /** Keyboard command: Navigate downwards. */
    public static final int CMD_NAV_LINE_NEXT = 2;
    /** Keyboard command: Navigate left one item. */
    public static final int CMD_NAV_ITEM_PREVIOUS = 3;
    /** Keyboard command: Navigate right one item. */
    public static final int CMD_NAV_ITEM_NEXT = 4;
    /** Keyboard command: Navigate one display window to the left. */
    public static final int CMD_NAV_PAN_LEFT = 5;
    /** Keyboard command: Navigate one display window to the right. */
    public static final int CMD_NAV_PAN_RIGHT = 6;
    /** Keyboard command: Navigate to the top or beginning. */
    public static final int CMD_NAV_TOP = 7;
    /** Keyboard command: Navigate to the bottom or end. */
    public static final int CMD_NAV_BOTTOM = 8;

    // Activation commands.

    /** Keyboard command: Activate the currently selected/focused item. */
    public static final int CMD_ACTIVATE_CURRENT = 20;

    // Scrolling.

    /** Keyboard command: Scroll backward. */
    public static final int CMD_SCROLL_BACKWARD = 30;
    /** Keyboard command: Scroll forward. */
    public static final int CMD_SCROLL_FORWARD = 31;

    // Selection commands.

    /** Keyboard command: Set the start ot the selection. */
    public static final int CMD_SELECTION_START = 40;
    /** Keyboard command: Set the end of the selection. */
    public static final int CMD_SELECTION_END = 41;
    /** Keyboard command: Select all content of the current field. */
    public static final int CMD_SELECTION_SELECT_ALL = 42;
    /** Keyboard command: Cut the content of the selection. */
    public static final int CMD_SELECTION_CUT = 43;
    /** Keyboard command: Copy the current selection. */
    public static final int CMD_SELECTION_COPY = 44;
    /**
     * Keyboard command: Paste the content of the clipboard at the current
     * insertion point.
     */
    public static final int CMD_SELECTION_PASTE = 45;

    /**
     * Keyboard command: Primary routing key pressed, typically
     * used to move the insertion point or click/tap on the item
     * under the key.
     * The argument is the zero-based position, relative to the first cell
     * on the display, of the cell that is closed to the key that
     * was pressed.
     */
    public static final int CMD_ROUTE = 50;

    // Braille keyboard input.

    /**
     * Keyboard command: A key combination was pressed on the braille
     * keyboard.
     * The argument contains the dots that were pressed as a bitmask.
     */
    public static final int CMD_BRAILLE_KEY = 60;

    // Editing keys.

    /** Keyboard command: Enter key. */
    public static final int CMD_KEY_ENTER = 70;
    /** Keyboard command: Delete backward. */
    public static final int CMD_KEY_DEL = 71;
    /** Keyboard command: Delete forward. */
    public static final int CMD_KEY_FORWARD_DEL = 72;

    // Glboal navigation keys.

    /** Keyboard command: Back button. */
    public static final int CMD_GLOBAL_BACK = 90;
    /** Keyboard command: Home button. */
    public static final int CMD_GLOBAL_HOME = 91;
    /** Keyboard command: Recent apps button. */
    public static final int CMD_GLOBAL_RECENTS = 92;
    /** Keyboard command: Show notificaitons. */
    public static final int CMD_GLOBAL_NOTIFICATIONS = 93;

    // Miscelanous commands.

    /** Keyboard command: Invoke keyboard help. */
    public static final int CMD_HELP = 100;

    // Meanings of the argument to a command.

    /** This command doesn't have an argument. */
    public static final int ARGUMENT_NONE = 0;
    /**
     * The lower order bits of the arguemnt to this command represent braille
     * dots.  Dot 1 is represented by the rightmost bit and so on until dot 8,
     * which is represented by bit 7, counted from the right.
     */
    public static final int ARGUMENT_DOTS = 1;
    /**
     * The argument represents a 0-based position on the display counted from
     * the leftmost cell.
     */
    public static final int ARGUMENT_POSITION = 2;

    private static final SparseArray<String> CMD_NAMES =
            new SparseArray<String>();
    private static final HashMap<String, Integer> NAMES_TO_CMDS
            = new HashMap<String, Integer>();
    static {
        CMD_NAMES.append(CMD_NAV_LINE_PREVIOUS, "CMD_NAV_LINE_PREVIOUS");
        CMD_NAMES.append(CMD_NAV_LINE_NEXT, "CMD_NAV_LINE_NEXT");
        CMD_NAMES.append(CMD_NAV_ITEM_PREVIOUS, "CMD_NAV_ITEM_PREVIOUS");
        CMD_NAMES.append(CMD_NAV_ITEM_NEXT, "CMD_NAV_ITEM_NEXT");
        CMD_NAMES.append(CMD_NAV_PAN_LEFT, "CMD_NAV_PAN_LEFT");
        CMD_NAMES.append(CMD_NAV_PAN_RIGHT, "CMD_NAV_PAN_RIGHT");
        CMD_NAMES.append(CMD_NAV_TOP, "CMD_NAV_TOP");
        CMD_NAMES.append(CMD_NAV_BOTTOM, "CMD_NAV_BOTTOM");
        CMD_NAMES.append(CMD_ACTIVATE_CURRENT, "CMD_ACTIVATE_CURRENT");
        CMD_NAMES.append(CMD_SCROLL_BACKWARD, "CMD_SCROLL_BACKWARD");
        CMD_NAMES.append(CMD_SCROLL_FORWARD, "CMD_SCROLL_FORWARD");
        CMD_NAMES.append(CMD_SELECTION_START, "CMD_SELECTION_START");
        CMD_NAMES.append(CMD_SELECTION_END, "CMD_SELECTION_END");
        CMD_NAMES.append(CMD_SELECTION_SELECT_ALL, "CMD_SELECTION_SELECT_ALL");
        CMD_NAMES.append(CMD_SELECTION_CUT, "CMD_SELECTION_CUT");
        CMD_NAMES.append(CMD_SELECTION_COPY, "CMD_SELECTION_COPY");
        CMD_NAMES.append(CMD_SELECTION_PASTE, "CMD_SELECTION_PASTE");
        CMD_NAMES.append(CMD_ROUTE, "CMD_ROUTE");
        CMD_NAMES.append(CMD_BRAILLE_KEY, "CMD_BRAILLE_KEY");
        CMD_NAMES.append(CMD_KEY_ENTER, "CMD_KEY_ENTER");
        CMD_NAMES.append(CMD_KEY_DEL, "CMD_KEY_DEL");
        CMD_NAMES.append(CMD_KEY_FORWARD_DEL, "CMD_KEY_FORWARD_DEL");
        CMD_NAMES.append(CMD_GLOBAL_BACK, "CMD_GLOBAL_BACK");
        CMD_NAMES.append(CMD_GLOBAL_HOME, "CMD_GLOBAL_HOME");
        CMD_NAMES.append(CMD_GLOBAL_RECENTS, "CMD_GLOBAL_RECENTS");
        CMD_NAMES.append(CMD_GLOBAL_NOTIFICATIONS, "CMD_GLOBAL_NOTIFICATIONS");
        CMD_NAMES.append(CMD_HELP, "CMD_HELP");
        for (int i = 0; i < CMD_NAMES.size(); ++i) {
            NAMES_TO_CMDS.put(CMD_NAMES.valueAt(i),
                    CMD_NAMES.keyAt(i));
        }
    }

    private final int mCommand;
    private final int mArgument;
    private final long mEventTime;

    public BrailleInputEvent(int command, int argument, long eventTime) {
        mCommand = command;
        mArgument = argument;
        mEventTime = eventTime;
    }

    /**
     * Returns the keyboard command that this event represents.
     */
    public int getCommand() {
        return mCommand;
    }

    /**
     * Returns the command-specific argument of the event, or zero if the
     * command doesn't have an argument.  See the individual command constants
     * for more details.
     */
    public int getArgument() {
        return mArgument;
    }

    /**
     * Returns the approximate time when this event happened as
     * returned by {@link android.os.SystemClock#uptimeMillis}.
     */
    public long getEventTime() {
        return mEventTime;
    }

    /**
     * Returns a string representation of {@code command}, or the string
     * {@code (unknown)} if the command is unknown.
     */
    public static String commandToString(int command) {
        String ret = CMD_NAMES.get(command);
        return ret != null ? ret : "(unknown)";
    }

    /**
     * Returns the command corresponding to {@code commandName}, or
     * {@link #CMD_NONE} if the name doesn't match any existing command.
     */
    public static int stringToCommand(String commandName) {
        Integer command = NAMES_TO_CMDS.get(commandName);
        if (command == null) {
            return CMD_NONE;
        }
        return command;
    }

    /**
     * Returns the type of argument for the given {@code command}.
     */
    public static int argumentType(int command) {
        switch (command) {
            case CMD_SELECTION_START:
            case CMD_SELECTION_END:
            case CMD_ROUTE:
                return ARGUMENT_POSITION;
            case CMD_BRAILLE_KEY:
                return ARGUMENT_DOTS;
            default:
                return ARGUMENT_NONE;
        }
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append("BrailleInputEvent {");
        sb.append("amd=");
        sb.append(commandToString(mCommand));
        sb.append(", arg=");
        sb.append(mArgument);
        sb.append("}");
        return sb.toString();
    }

    // For Parcelable support.

    public static final Parcelable.Creator<BrailleInputEvent> CREATOR =
        new Parcelable.Creator<BrailleInputEvent>() {
            @Override
            public BrailleInputEvent createFromParcel(Parcel in) {
                return new BrailleInputEvent(in);
            }

            @Override
            public BrailleInputEvent[] newArray(int size) {
                return new BrailleInputEvent[size];
            }
        };

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel out, int flags) {
        out.writeInt(mCommand);
        out.writeInt(mArgument);
        out.writeLong(mEventTime);
    }

    private BrailleInputEvent(Parcel in) {
        mCommand = in.readInt();
        mArgument = in.readInt();
        mEventTime = in.readLong();
    }
}