// Copyright 2017 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.

module ash.mojom;

import "ash/public/interfaces/accessibility_controller_enums.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "ui/accessibility/ax_enums.mojom";
import "ui/events/mojo/event.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";

// Allows a client to implement Select-to-Speak.
// TODO(katie): Consider combining DispatchMouseEvent and DispatchKeyEvent
// into a single DispatchEvent function.
interface SelectToSpeakEventHandlerDelegate {
  // Sends a KeyEvent to the Select-to-Speak extension in Chrome. The event
  // is cast to a key event with a type CHECK.
  DispatchKeyEvent(ui.mojom.Event event);

  // Sends a MouseEvent to the Select-to-Speak extension in Chrome. The event
  // is cast to a mouse event with a type CHECK.
  DispatchMouseEvent(ui.mojom.Event event);
};

// Allows a client to implement Switch Access.
interface SwitchAccessEventHandlerDelegate {
  // Sends a KeyEvent to the Switch Access extension in Chrome. The event
  // is cast to a key event with a type CHECK.
  DispatchKeyEvent(ui.mojom.Event event);
};

// Interface for ash client (e.g. Chrome) to control and query accessibility
// features.
interface AccessibilityController {
  // Sets the client interface.
  SetClient(AccessibilityControllerClient client);

  // Starts or stops darkening the screen (e.g. to allow chrome a11y extensions
  // to darken the screen).
  SetDarkenScreen(bool darken);

  // Called when braille display state is changed.
  BrailleDisplayStateChanged(bool connected);

  // Sets the focus highlight rect using |bounds_in_screen|. Called when focus
  // changed in page and a11y focus highlight feature is enabled.
  SetFocusHighlightRect(gfx.mojom.Rect bounds_in_screen);

  // Sets the text input caret bounds used to draw the caret highlight effect.
  // For effciency, only sent when the caret highlight feature is enabled.
  // Setting off-screen or empty bounds suppresses the highlight.
  SetCaretBounds(gfx.mojom.Rect bounds_in_screen);

  // Sets whether the accessibility panel should always be visible, regardless
  // of whether the window is fullscreen.
  SetAccessibilityPanelAlwaysVisible(bool always_visible);

  // Sets the bounds for the accessibility panel. Overrides current
  // configuration (i.e. fullscreen, full-width).
  SetAccessibilityPanelBounds(gfx.mojom.Rect bounds,
                              AccessibilityPanelState state);

  // Sets the current Select-to-Speak state. This should be used by the Select-
  // to-Speak extension to inform ash of its updated state.
  SetSelectToSpeakState(SelectToSpeakState state);

  // Set the delegate used by the Select-to-Speak event handler.
  SetSelectToSpeakEventHandlerDelegate(
      SelectToSpeakEventHandlerDelegate delegate);

  // Sets the key codes that Switch Access should capture.
  SetSwitchAccessKeysToCapture(array<int32> keys_to_capture);

  // Set the delegate used by the Switch Access event handler.
  SetSwitchAccessEventHandlerDelegate(
      SwitchAccessEventHandlerDelegate delegate);

  // Starts or stops dictation. Records metrics for toggling via SwitchAccess.
  ToggleDictationFromSource(DictationToggleSource source);

  // Tells the Switch Access Event Handler whether to forward all key events to
  // the Switch Access extension.
  ForwardKeyEventsToSwitchAccess(bool should_forward);

  // Retrieves a string description of the current battery status.
  GetBatteryDescription()
    => (mojo_base.mojom.String16 battery_description);
};

// Interface for ash to request accessibility service from its client (e.g.
// Chrome).
interface AccessibilityControllerClient {
  // Triggers an accessibility alert to give the user feedback.
  TriggerAccessibilityAlert(AccessibilityAlert alert);

  // Plays an earcon. Earcons are brief and distinctive sounds that indicate
  // that their mapped event has occurred. The |sound_key| enums can be found in
  // chromeos/audio/chromeos_sounds.h. This method exists because the browser
  // owns all media playback.
  PlayEarcon(int32 sound_key);

  // Initiates play of shutdown sound and returns sound duration. This method
  // exists because the browser owns all media playback.
  PlayShutdownSound() => (mojo_base.mojom.TimeDelta sound_duration);

  // Forwards an accessibility gesture from the touch exploration controller to
  // ChromeVox.
  HandleAccessibilityGesture(ax.mojom.Gesture gesture);

  // Starts or stops dictation (type what you speak).
  // Returns the new dictation state after the toggle.
  ToggleDictation() => (bool dictation_on);

  // Cancels all current and queued speech immediately.
  SilenceSpokenFeedback();

  // Called when we first detect two fingers are held down, which can be used to
  // toggle spoken feedback on some touch-only devices.
  OnTwoFingerTouchStart();

  // Called when the user is no longer holding down two fingers (including
  // releasing one, holding down three, or moving them).
  OnTwoFingerTouchStop();

  // Whether or not to enable toggling spoken feedback via holding down two
  // fingers on the screen.
  ShouldToggleSpokenFeedbackViaTouch() => (bool should_toggle);

  // Plays tick sound indicating spoken feedback will be toggled after
  // countdown.
  PlaySpokenFeedbackToggleCountdown(int32 tick_count);

  // Requests the Select-to-Speak extension to change its state. This lets users
  // do the same things in tablet mode as with a keyboard. Specifically, if
  // Select-to-Speak is not speaking, move to capturing state; if
  // Select-to-Speak is speaking, cancel speaking and move to inactive state.
  RequestSelectToSpeakStateChange();
};