Add BrailleBack.
git-svn-id: https://eyes-free.googlecode.com/svn/trunk/braille/client/src/com/googlecode/eyesfree/braille@781 584082c0-ab3a-11dd-9ddb-6f86aeb5eef6
diff --git a/display/BrailleDisplayProperties.aidl b/display/BrailleDisplayProperties.aidl
new file mode 100644
index 0000000..5a7f410
--- /dev/null
+++ b/display/BrailleDisplayProperties.aidl
@@ -0,0 +1,19 @@
+/*
+ * 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;
+
+parcelable BrailleDisplayProperties;
diff --git a/display/BrailleDisplayProperties.java b/display/BrailleDisplayProperties.java
new file mode 100644
index 0000000..f61bad0
--- /dev/null
+++ b/display/BrailleDisplayProperties.java
@@ -0,0 +1,102 @@
+/*
+ * 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;
+
+/**
+ * Properties of a braille display such as dimensions and keyboard
+ * configuration.
+ */
+public class BrailleDisplayProperties implements Parcelable {
+ private final int mNumTextCells;
+ private final int mNumStatusCells;
+ private final BrailleKeyBinding[] mKeyBindings;
+
+ public BrailleDisplayProperties(int numTextCells, int numStatusCells,
+ BrailleKeyBinding[] keyBindings) {
+ mNumTextCells = numTextCells;
+ mNumStatusCells = numStatusCells;
+ mKeyBindings = keyBindings;
+ }
+
+ /**
+ * Returns the number of cells on the main display intended for display of
+ * text or other content.
+ */
+ public int getNumTextCells() {
+ return mNumTextCells;
+ }
+
+ /**
+ * Returns the number of status cells that are separated from the main
+ * display. This value will be {@code 0} for displays without any separate
+ * status cells.
+ */
+ public int getNumStatusCells() {
+ return mNumStatusCells;
+ }
+
+ /**
+ * Returns the list of key bindings for this display.
+ */
+ public BrailleKeyBinding[] getKeyBindings() {
+ return mKeyBindings;
+ }
+
+ @Override
+ public String toString() {
+ return String.format(
+ "BrailleDisplayProperties [numTextCells: %d, numStatusCells: %d, "
+ + "keyBindings: %d]",
+ mNumTextCells, mNumStatusCells, mKeyBindings.length);
+ }
+
+ // For Parcelable support.
+
+ public static final Parcelable.Creator<BrailleDisplayProperties> CREATOR =
+ new Parcelable.Creator<BrailleDisplayProperties>() {
+ @Override
+ public BrailleDisplayProperties createFromParcel(Parcel in) {
+ return new BrailleDisplayProperties(in);
+ }
+
+ @Override
+ public BrailleDisplayProperties[] newArray(int size) {
+ return new BrailleDisplayProperties[size];
+ }
+ };
+
+ @Override
+ public int describeContents() {
+ return 0;
+ }
+
+ @Override
+ public void writeToParcel(Parcel out, int flags) {
+ out.writeInt(mNumTextCells);
+ out.writeInt(mNumStatusCells);
+ out.writeTypedArray(mKeyBindings, flags);
+ }
+
+ private BrailleDisplayProperties(Parcel in) {
+ mNumTextCells = in.readInt();
+ mNumStatusCells = in.readInt();
+ mKeyBindings = in.createTypedArray(BrailleKeyBinding.CREATOR);
+ }
+}
diff --git a/display/BrailleInputEvent.aidl b/display/BrailleInputEvent.aidl
new file mode 100644
index 0000000..f64c080
--- /dev/null
+++ b/display/BrailleInputEvent.aidl
@@ -0,0 +1,19 @@
+/*
+ * 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;
+
+parcelable BrailleInputEvent;
diff --git a/display/BrailleInputEvent.java b/display/BrailleInputEvent.java
new file mode 100644
index 0000000..1c2ffb4
--- /dev/null
+++ b/display/BrailleInputEvent.java
@@ -0,0 +1,300 @@
+/*
+ * 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();
+ }
+}
diff --git a/display/BrailleKeyBinding.java b/display/BrailleKeyBinding.java
new file mode 100644
index 0000000..92b58d0
--- /dev/null
+++ b/display/BrailleKeyBinding.java
@@ -0,0 +1,100 @@
+/*
+ * 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;
+
+/**
+ * Represents a binding between a combination of braille device keys and a
+ * command as declared in {@link BrailleInputEvent}.
+ */
+public class BrailleKeyBinding implements Parcelable {
+ private int mCommand;
+ private String[] mKeyNames;
+
+ public BrailleKeyBinding() {
+ }
+
+ public BrailleKeyBinding(int command, String[] keyNames) {
+ mCommand = command;
+ mKeyNames = keyNames;
+ }
+
+ /**
+ * Sets the command for this binding.
+ */
+ public BrailleKeyBinding setCommand(int command) {
+ mCommand = command;
+ return this;
+ }
+
+ /**
+ * Sets the key names for this binding.
+ */
+ public BrailleKeyBinding setKeyNames(String[] keyNames) {
+ mKeyNames = keyNames;
+ return this;
+ }
+
+ /**
+ * Returns the command for this key binding.
+ * @see {@link BrailleInputEvent}.
+ */
+ public int getCommand() {
+ return mCommand;
+ }
+
+ /**
+ * Returns the list of device-specific keys that, when pressed
+ * at the same time, will yield the command of this key binding.
+ */
+ public String[] getKeyNames() {
+ return mKeyNames;
+ }
+
+ // For Parcelable support.
+
+ public static final Parcelable.Creator<BrailleKeyBinding> CREATOR =
+ new Parcelable.Creator<BrailleKeyBinding>() {
+ @Override
+ public BrailleKeyBinding createFromParcel(Parcel in) {
+ return new BrailleKeyBinding(in);
+ }
+
+ @Override
+ public BrailleKeyBinding[] newArray(int size) {
+ return new BrailleKeyBinding[size];
+ }
+ };
+
+ @Override
+ public int describeContents() {
+ return 0;
+ }
+
+ @Override
+ public void writeToParcel(Parcel out, int flags) {
+ out.writeInt(mCommand);
+ out.writeStringArray(mKeyNames);
+ }
+
+ private BrailleKeyBinding(Parcel in) {
+ mCommand = in.readInt();
+ mKeyNames = in.createStringArray();
+ }
+}
diff --git a/display/Display.java b/display/Display.java
new file mode 100644
index 0000000..54a57a2
--- /dev/null
+++ b/display/Display.java
@@ -0,0 +1,321 @@
+/*
+ * 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.Message;
+import android.content.ComponentName;
+import android.content.Context;
+import android.content.Intent;
+import android.content.ServiceConnection;
+import android.os.Handler;
+import android.os.IBinder;
+import android.os.RemoteException;
+import android.util.Log;
+
+/**
+ * A client for the braille display service.
+ */
+public class Display {
+ private static final String LOG_TAG = Display.class.getSimpleName();
+ /** Service name used for connecting to the service. */
+ public static final String ACTION_DISPLAY_SERVICE =
+ "com.googlecode.eyesfree.braille.service.ACTION_DISPLAY_SERVICE";
+
+ /** Initial value, which is never reported to the listener. */
+ private static final int STATE_UNKNOWN = -2;
+ public static final int STATE_ERROR = -1;
+ public static final int STATE_NOT_CONNECTED = 0;
+ public static final int STATE_CONNECTED = 1;
+
+ private final OnConnectionStateChangeListener
+ mConnectionStateChangeListener;
+ private final Context mContext;
+ private final DisplayHandler mHandler;
+ private volatile OnInputEventListener mInputEventListener;
+ private static final Intent mServiceIntent =
+ new Intent(ACTION_DISPLAY_SERVICE);
+ private Connection mConnection;
+ private int currentConnectionState = STATE_UNKNOWN;
+ private BrailleDisplayProperties mDisplayProperties;
+ private ServiceCallback mServiceCallback = new ServiceCallback();
+ /**
+ * Delay before the first rebind attempt on bind error or service
+ * disconnect.
+ */
+ private static final int REBIND_DELAY_MILLIS = 500;
+ private static final int MAX_REBIND_ATTEMPTS = 5;
+ private int mNumFailedBinds = 0;
+
+ /**
+ * A callback interface to get informed about connection state changes.
+ */
+ public interface OnConnectionStateChangeListener {
+ void onConnectionStateChanged(int state);
+ }
+
+ /**
+ * A callback interface for input from the braille display.
+ */
+ public interface OnInputEventListener {
+ void onInputEvent(BrailleInputEvent inputEvent);
+ }
+
+ /**
+ * Constructs an instance and connects to the braille display service.
+ * The current thread must have an {@link android.os.Looper} associated
+ * with it. Callbacks from this object will all be executed on the
+ * current thread. Connection state will be reported to {@code listener).
+ */
+ public Display(Context context, OnConnectionStateChangeListener listener) {
+ this(context, listener, null);
+ }
+
+ /**
+ * Constructs an instance and connects to the braille display service.
+ * Callbacks from this object will all be executed on the thread
+ * associated with {@code handler}. If {@code handler} is {@code null},
+ * the current thread must have an {@link android.os.Looper} associated
+ * with it, which will then be used to execute callbacks. Connection
+ * state will be reported to {@code listener).
+ */
+ public Display(Context context, OnConnectionStateChangeListener listener,
+ Handler handler) {
+ mContext = context;
+ mConnectionStateChangeListener = listener;
+ if (handler == null) {
+ mHandler = new DisplayHandler();
+ } else {
+ mHandler = new DisplayHandler(handler);
+ }
+
+ doBindService();
+ }
+
+ /**
+ * Sets a {@code listener} for input events. {@code listener} can be
+ * {@code null} to remove a previously set listener.
+ */
+ public void setOnInputEventListener(OnInputEventListener listener) {
+ mInputEventListener = listener;
+ }
+
+ /**
+ * Returns the display properties, or {@code null} if not connected
+ * to a display.
+ */
+ public BrailleDisplayProperties getDisplayProperties() {
+ return mDisplayProperties;
+ }
+
+ /**
+ * Displays a given dots configuration on the braille display.
+ * @param patterns Dots configuration to be displayed.
+ */
+ public void displayDots(byte[] patterns) {
+ IBrailleService localService = getBrailleService();
+ if (localService != null) {
+ try {
+ localService.displayDots(patterns);
+ } catch (RemoteException ex) {
+ Log.e(LOG_TAG, "Error in displayDots", ex);
+ }
+ } else {
+ Log.v(LOG_TAG, "Error in displayDots: service not connected");
+ }
+ }
+
+ /**
+ * Unbinds from the braille display service and deallocates any
+ * resources. This method should be called when the braille display
+ * is no longer in use by this client.
+ */
+ public void shutdown() {
+ doUnbindService();
+ }
+
+ // NOTE: The methods in this class will be executed in the main
+ // application thread.
+ private class Connection implements ServiceConnection {
+ private volatile IBrailleService mService;
+
+ @Override
+ public void onServiceConnected(ComponentName className,
+ IBinder binder) {
+ Log.i(LOG_TAG, "Connected to braille service");
+ IBrailleService localService =
+ IBrailleService.Stub.asInterface(binder);
+ try {
+ localService.registerCallback(mServiceCallback);
+ mService = localService;
+ synchronized (mHandler) {
+ mNumFailedBinds = 0;
+ }
+ } catch (RemoteException e) {
+ // In this case the service has crashed before we could even do
+ // anything with it.
+ Log.e(LOG_TAG, "Failed to register callback on service", e);
+ // We should get a disconnected call and the rebind
+ // and failure reporting happens in that handler.
+ }
+ }
+
+ @Override
+ public void onServiceDisconnected(ComponentName className) {
+ mService = null;
+ Log.e(LOG_TAG, "Disconnected from braille service");
+ // Report display disconnected for now, this will turn into a
+ // connected state or error state depending on how the retrying
+ // goes.
+ mHandler.reportConnectionState(STATE_NOT_CONNECTED, null);
+ mHandler.scheduleRebind();
+ }
+ }
+
+ // NOTE: The methods of this class will be executed in the IPC
+ // thread pool and not on the main application thread.
+ private class ServiceCallback extends IBrailleServiceCallback.Stub {
+ @Override
+ public void onDisplayConnected(
+ BrailleDisplayProperties displayProperties) {
+ mHandler.reportConnectionState(STATE_CONNECTED, displayProperties);
+ }
+
+ @Override
+ public void onDisplayDisconnected() {
+ mHandler.reportConnectionState(STATE_NOT_CONNECTED, null);
+ }
+
+ @Override
+ public void onInput(BrailleInputEvent inputEvent) {
+ mHandler.reportInputEvent(inputEvent);
+ }
+ }
+
+ private void doBindService() {
+ Connection localConnection = new Connection();
+ if (!mContext.bindService(mServiceIntent, localConnection,
+ Context.BIND_AUTO_CREATE)) {
+ Log.e(LOG_TAG, "Failed to bind Service");
+ mHandler.scheduleRebind();
+ return;
+ }
+ mConnection = localConnection;
+ Log.i(LOG_TAG, "Bound to braille service");
+ }
+
+ private void doUnbindService() {
+ IBrailleService localService = getBrailleService();
+ if (localService != null) {
+ try {
+ localService.unregisterCallback(mServiceCallback);
+ } catch (RemoteException e) {
+ // Nothing to do if the service can't be reached.
+ }
+ }
+ if (mConnection != null) {
+ mContext.unbindService(mConnection);
+ mConnection = null;
+ }
+ }
+
+ private IBrailleService getBrailleService() {
+ Connection localConnection = mConnection;
+ if (localConnection != null) {
+ return localConnection.mService;
+ }
+ return null;
+ }
+
+ private class DisplayHandler extends Handler {
+ private static final int MSG_REPORT_CONNECTION_STATE = 1;
+ private static final int MSG_REPORT_INPUT_EVENT = 2;
+ private static final int MSG_REBIND_SERVICE = 3;
+
+ public DisplayHandler() {
+ }
+
+ public DisplayHandler(Handler handler) {
+ super(handler.getLooper());
+ }
+
+ public void reportConnectionState(final int newState,
+ final BrailleDisplayProperties displayProperties) {
+ obtainMessage(MSG_REPORT_CONNECTION_STATE, newState, 0,
+ displayProperties)
+ .sendToTarget();
+ }
+
+ public void reportInputEvent(BrailleInputEvent event) {
+ obtainMessage(MSG_REPORT_INPUT_EVENT, event).sendToTarget();
+ }
+
+ public void scheduleRebind() {
+ synchronized (this) {
+ if (mNumFailedBinds < MAX_REBIND_ATTEMPTS) {
+ int delay = REBIND_DELAY_MILLIS << mNumFailedBinds;
+ sendEmptyMessageDelayed(MSG_REBIND_SERVICE, delay);
+ ++mNumFailedBinds;
+ Log.w(LOG_TAG, String.format(
+ "Will rebind to braille service in %d ms.", delay));
+ } else {
+ reportConnectionState(STATE_ERROR, null);
+ }
+ }
+ }
+
+ @Override
+ public void handleMessage(Message msg) {
+ switch (msg.what) {
+ case MSG_REPORT_CONNECTION_STATE:
+ handleReportConnectionState(msg.arg1,
+ (BrailleDisplayProperties) msg.obj);
+ break;
+ case MSG_REPORT_INPUT_EVENT:
+ handleReportInputEvent((BrailleInputEvent) msg.obj);
+ break;
+ case MSG_REBIND_SERVICE:
+ handleRebindService();
+ break;
+ }
+ }
+
+ private void handleReportConnectionState(int newState,
+ BrailleDisplayProperties displayProperties) {
+ mDisplayProperties = displayProperties;
+ if (newState != currentConnectionState
+ && mConnectionStateChangeListener != null) {
+ mConnectionStateChangeListener.onConnectionStateChanged(
+ newState);
+ }
+ currentConnectionState = newState;
+ }
+
+ private void handleReportInputEvent(BrailleInputEvent event) {
+ OnInputEventListener localListener = mInputEventListener;
+ if (localListener != null) {
+ localListener.onInputEvent(event);
+ }
+ }
+
+ private void handleRebindService() {
+ if (mConnection != null) {
+ doUnbindService();
+ }
+ doBindService();
+ }
+ }
+}
diff --git a/display/IBrailleService.aidl b/display/IBrailleService.aidl
new file mode 100644
index 0000000..2b478bb
--- /dev/null
+++ b/display/IBrailleService.aidl
@@ -0,0 +1,43 @@
+/*
+ * 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 com.googlecode.eyesfree.braille.display.IBrailleServiceCallback;
+
+/**
+ * Interface for clients to talk to the braille display service.
+ */
+interface IBrailleService {
+ /**
+ * Register a callback for the {@code callingApp} which will receive
+ * certain braille display related events.
+ */
+ boolean registerCallback(in IBrailleServiceCallback callback);
+
+ /**
+ * Unregister a previously registered callback for the {@code callingApp}.
+ */
+ oneway void unregisterCallback(in IBrailleServiceCallback callback);
+
+ /**
+ * Updates the main cells of the connected braille display
+ * with a given dot {@code pattern}.
+ *
+ * @return {@code true} on success and {@code false} otherwise.
+ */
+ void displayDots(in byte[] patterns);
+}
diff --git a/display/IBrailleServiceCallback.aidl b/display/IBrailleServiceCallback.aidl
new file mode 100644
index 0000000..545d1ad
--- /dev/null
+++ b/display/IBrailleServiceCallback.aidl
@@ -0,0 +1,30 @@
+/*
+ * 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 com.googlecode.eyesfree.braille.display.BrailleDisplayProperties;
+import com.googlecode.eyesfree.braille.display.BrailleInputEvent;
+
+/**
+ * Callback interface that a braille display client can expose to
+ * get information about various braille display events.
+ */
+interface IBrailleServiceCallback {
+ void onDisplayConnected(in BrailleDisplayProperties displayProperties);
+ void onDisplayDisconnected();
+ void onInput(in BrailleInputEvent inputEvent);
+}
diff --git a/translate/BrailleTranslator.java b/translate/BrailleTranslator.java
new file mode 100644
index 0000000..e7ee9cb
--- /dev/null
+++ b/translate/BrailleTranslator.java
@@ -0,0 +1,35 @@
+/*
+ * 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.translate;
+
+/**
+ * Translates from text to braille and the other way according to a
+ * particular translation table.
+ */
+public interface BrailleTranslator {
+ /**
+ * Translates a string into the corresponding dot patterns and returns the
+ * resulting byte array. Returns {@code null} on error.
+ */
+ byte[] translate(String text);
+
+ /**
+ * Translates the braille {@code cells} into the corresponding text, which
+ * is returned. Returns {@code null} on error.
+ */
+ String backTranslate(byte[] cells);
+}
diff --git a/translate/ITranslatorService.aidl b/translate/ITranslatorService.aidl
new file mode 100644
index 0000000..1ccab87
--- /dev/null
+++ b/translate/ITranslatorService.aidl
@@ -0,0 +1,47 @@
+/*
+ * 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.translate;
+
+import com.googlecode.eyesfree.braille.translate.ITranslatorServiceCallback;
+
+interface ITranslatorService {
+ /**
+ * Sets a callback to be called when the service is ready to translate.
+ * Using any of the other methods in this interface before the
+ * callback is called with a successful status will return
+ * failure.
+ */
+ void setCallback(ITranslatorServiceCallback callback);
+
+ /**
+ * Makes sure that the given table string is valid and that the
+ * table compiles.
+ */
+ boolean checkTable(String tableName);
+
+ /**
+ * Translates text into braille according to the give tableName.
+ * Returns null on fatal translation errors.
+ */
+ byte[] translate(String text, String tableName);
+
+ /**
+ * Translates braille cells into text according to the given table
+ * name. Returns null on fatal translation errors.
+ */
+ String backTranslate(in byte[] cells, String tableName);
+}
diff --git a/translate/ITranslatorServiceCallback.aidl b/translate/ITranslatorServiceCallback.aidl
new file mode 100644
index 0000000..91c74cb
--- /dev/null
+++ b/translate/ITranslatorServiceCallback.aidl
@@ -0,0 +1,21 @@
+/*
+ * 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.translate;
+
+oneway interface ITranslatorServiceCallback {
+ void onInit(int status);
+}
diff --git a/translate/TranslatorManager.java b/translate/TranslatorManager.java
new file mode 100644
index 0000000..841a041
--- /dev/null
+++ b/translate/TranslatorManager.java
@@ -0,0 +1,278 @@
+/*
+ * 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.translate;
+
+import android.content.ComponentName;
+import android.content.Context;
+import android.content.Intent;
+import android.content.ServiceConnection;
+import android.os.Handler;
+import android.os.IBinder;
+import android.os.Message;
+import android.os.RemoteException;
+import android.util.Log;
+
+/**
+ * Client-side interface to the central braille translator service.
+ *
+ * This class can be used to retrieve {@link BrailleTranslator} instances for
+ * performing translation between text and braille cells.
+ *
+ * Typically, an instance of this class is created at application
+ * initialization time and destroyed using the {@link destroy()} method when
+ * the application is about to be destroyed. It is recommended that the
+ * instance is destroyed and recreated if braille translation is not going to
+ * be need for a long period of time.
+ *
+ * Threading:<br>
+ * The object must be destroyed on the same thread it was created.
+ * Other methods may be called from any thread.
+ */
+public class TranslatorManager {
+ private static final String LOG_TAG =
+ TranslatorManager.class.getSimpleName();
+ private static final String ACTION_TRANSLATOR_SERVICE =
+ "com.googlecode.eyesfree.braille.service.ACTION_TRANSLATOR_SERVICE";
+ private static final Intent mServiceIntent =
+ new Intent(ACTION_TRANSLATOR_SERVICE);
+ /**
+ * Delay before the first rebind attempt on bind error or service
+ * disconnect.
+ */
+ private static final int REBIND_DELAY_MILLIS = 500;
+ private static final int MAX_REBIND_ATTEMPTS = 5;
+ public static final int ERROR = -1;
+ public static final int SUCCESS = 0;
+
+ /**
+ * A callback interface to get notified when the translation
+ * manager is ready to be used, or an error occurred during
+ * initialization.
+ */
+ public interface OnInitListener {
+ /**
+ * Called exactly once when it has been determined that the
+ * translation service is either ready to be used ({@code SUCCESS})
+ * or the service is not available {@code ERROR}.
+ */
+ public void onInit(int status);
+ }
+
+ private final Context mContext;
+ private final TranslatorManagerHandler mHandler =
+ new TranslatorManagerHandler();
+ private final ServiceCallback mServiceCallback = new ServiceCallback();
+
+ private OnInitListener mOnInitListener;
+ private Connection mConnection;
+ private int mNumFailedBinds = 0;
+
+ /**
+ * Constructs an instance. {@code context} is used to bind to the
+ * translator service. The other methods of this class should not be
+ * called (they will fail) until {@code onInitListener.onInit()}
+ * is called.
+ */
+ public TranslatorManager(Context context, OnInitListener onInitListener) {
+ mContext = context;
+ mOnInitListener = onInitListener;
+ doBindService();
+ }
+
+ /**
+ * Destroys this instance, deallocating any global resources it is using.
+ * Any {@link BrailleTranslator} objects that were created using this
+ * object are invalid after this call.
+ */
+ public void destroy() {
+ doUnbindService();
+ mHandler.destroy();
+ }
+
+ /**
+ * Returns a new {@link BrailleTranslator} for the translation
+ * table specified by {@code tableName}.
+ */
+ // TODO: Document how to discover valid table names.
+ public BrailleTranslator getTranslator(String tableName) {
+ ITranslatorService localService = getTranslatorService();
+ if (localService != null) {
+ try {
+ if (localService.checkTable(tableName)) {
+ return new BrailleTranslatorImpl(tableName);
+ }
+ } catch (RemoteException ex) {
+ Log.e(LOG_TAG, "Error in getTranslator", ex);
+ }
+ }
+ return null;
+ }
+
+ private void doBindService() {
+ Connection localConnection = new Connection();
+ if (!mContext.bindService(mServiceIntent, localConnection,
+ Context.BIND_AUTO_CREATE)) {
+ Log.e(LOG_TAG, "Failed to bind to service");
+ mHandler.scheduleRebind();
+ return;
+ }
+ mConnection = localConnection;
+ Log.i(LOG_TAG, "Bound to translator service");
+ }
+
+ private void doUnbindService() {
+ if (mConnection != null) {
+ mContext.unbindService(mConnection);
+ mConnection = null;
+ }
+ }
+
+ private ITranslatorService getTranslatorService() {
+ Connection localConnection = mConnection;
+ if (localConnection != null) {
+ return localConnection.mService;
+ }
+ return null;
+ }
+
+ private class Connection implements ServiceConnection {
+ // Read in application threads, written in main thread.
+ private volatile ITranslatorService mService;
+
+ @Override
+ public void onServiceConnected(ComponentName className,
+ IBinder binder) {
+ Log.i(LOG_TAG, "Connected to translation service");
+ ITranslatorService localService =
+ ITranslatorService.Stub.asInterface(binder);
+ try {
+ localService.setCallback(mServiceCallback);
+ mService = localService;
+ synchronized (mHandler) {
+ mNumFailedBinds = 0;
+ }
+ } catch (RemoteException ex) {
+ // Service went away, rely on disconnect handler to
+ // schedule a rebind.
+ Log.e(LOG_TAG, "Error when setting callback", ex);
+ }
+ }
+
+ @Override
+ public void onServiceDisconnected(ComponentName className) {
+ Log.e(LOG_TAG, "Disconnected from translator service");
+ mService = null;
+ // Retry by rebinding, and finally call the onInit if aplicable.
+ mHandler.scheduleRebind();
+ }
+ }
+
+ private class BrailleTranslatorImpl implements BrailleTranslator {
+ private final String mTable;
+
+ public BrailleTranslatorImpl(String table) {
+ mTable = table;
+ }
+
+ @Override
+ public byte[] translate(String text) {
+ ITranslatorService localService = getTranslatorService();
+ if (localService != null) {
+ try {
+ return localService.translate(text, mTable);
+ } catch (RemoteException ex) {
+ Log.e(LOG_TAG, "Error in translate", ex);
+ }
+ }
+ return null;
+ }
+
+ @Override
+ public String backTranslate(byte[] cells) {
+ ITranslatorService localService = getTranslatorService();
+ if (localService != null) {
+ try {
+ return localService.backTranslate(cells, mTable);
+ } catch (RemoteException ex) {
+ Log.e(LOG_TAG, "Error in backTranslate", ex);
+ }
+ }
+ return null;
+ }
+ }
+
+ private class ServiceCallback extends ITranslatorServiceCallback.Stub {
+ @Override
+ public void onInit(int status) {
+ mHandler.onInit(status);
+ }
+ }
+
+ private class TranslatorManagerHandler extends Handler {
+ private static final int MSG_ON_INIT = 1;
+ private static final int MSG_REBIND_SERVICE = 2;
+
+ public void onInit(int status) {
+ obtainMessage(MSG_ON_INIT, status, 0).sendToTarget();
+ }
+
+ public void destroy() {
+ mOnInitListener = null;
+ // Cacnel outstanding messages, most importantly
+ // scheduled rebinds.
+ removeCallbacksAndMessages(null);
+ }
+
+ public void scheduleRebind() {
+ synchronized (this) {
+ if (mNumFailedBinds < MAX_REBIND_ATTEMPTS) {
+ int delay = REBIND_DELAY_MILLIS << mNumFailedBinds;
+ sendEmptyMessageDelayed(MSG_REBIND_SERVICE, delay);
+ ++mNumFailedBinds;
+ } else {
+ onInit(ERROR);
+ }
+ }
+ }
+
+ @Override
+ public void handleMessage(Message msg) {
+ switch (msg.what) {
+ case MSG_ON_INIT:
+ handleOnInit(msg.arg1);
+ break;
+ case MSG_REBIND_SERVICE:
+ handleRebindService();
+ break;
+ }
+ }
+
+ private void handleOnInit(int status) {
+ if (mOnInitListener != null) {
+ mOnInitListener.onInit(status);
+ mOnInitListener = null;
+ }
+ }
+
+ private void handleRebindService() {
+ if (mConnection != null) {
+ doUnbindService();
+ }
+ doBindService();
+ }
+ }
+}
