// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Braille display access private API.
namespace brailleDisplayPrivate {
  // Braille display keyboard command.
  enum KeyCommand {
    line_up,
    line_down,
    pan_left,
    pan_right,
    top,
    bottom,
    routing,
    secondary_routing,
    dots,
    chord,
    standard_key
  };

  // A keyboard event.  This is not a standard keyboard event because
  // braille display keyboards look significantly different from standard
  // keyboards.
  dictionary KeyEvent {
    KeyCommand command;
    // 0-based display position for commands that involve a routing key.
    long? displayPosition;
    // Braille dot keys that were pressed, stored in the low-order bits.
    // Dot 1 is stored in bit 0, dot2 in bit 1, etc.
    long? brailleDots;
    // DOM keyboard event code.  This is present when command is standard_key
    // and the braille display event represents a non-alphanumeric key such
    // as an arrow key or function key.
    // The value is as defined by the |code| property in
    // http://www.w3.org/TR/uievents/#keyboard-event-interface
    DOMString? standardKeyCode;
    // DOM keyboard event character value.  This is present if the
    // braille key event corresponds to a character.
    DOMString? standardKeyChar;
    // Whether the space key was pressed.
    boolean? spaceKey;
    // Whether the alt key was pressed.
    boolean? altKey;
    // Whether the shift key was pressed.
    boolean? shiftKey;
    // Whether the ctrl key was pressed.
    boolean? ctrlKey;
  };

  // The current braille display state.
  dictionary DisplayState {
    // Whether a braille display is currently available.
    boolean available;
    // Number of rows of braille cells on the currently connected display.
    long? textRowCount;
    // Number of columns of braille cells on the currently connected display.
    long? textColumnCount;
  };

  callback DisplayStateCallback = void(DisplayState result);

  interface Functions {
    // Gets the current display state.
    static void getDisplayState(DisplayStateCallback callback);
    // Write the given dot patterns to the display.  The buffer contains one
    // byte for each braille cell on the display, starting from the leftmost
    // cell. Each byte contains a bit pattern indicating which dots should be
    // raised in the corresponding cell with the low-order bit representing
    // dot 1 and so on until bit 7 which corresponds to dot 8.  If the number
    // of bytes in the buffer is not equal to the display size, the buffer
    // will either be clipped or padded with blank cells on the right. The
    // buffer is a 2D array compressed into 1D. The |columns| and |rows|
    // parameters give the original 2D dimensions of the buffer. To access
    // an element cells[r][c], simply access cells[r * columns + c].
    static void writeDots(ArrayBuffer cells, long columns, long rows);

    // Updates the single user-preferred braille device with the given bluetooth
    // device address and starts or restarts the Brltty daemon.
    static void updateBluetoothBrailleDisplayAddress(DOMString address);
  };

  interface Events {
    // Fired when a braille display is connected or disconnected.
    static void onDisplayStateChanged(DisplayState state);
    // Fired when an input event is received from the display.
    static void onKeyEvent(KeyEvent event);
  };
};