ash/public/interfaces/keyboard_controller.mojom

// Copyright 2018 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/keyboard_config.mojom";
import "ash/public/interfaces/keyboard_controller_types.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";

enum HideReason {
  // Hide requested by an explicit user action.
  kUser,

  // Hide requested due to a system event (e.g. because it would interfere with
  // a menu or other on screen UI).
  kSystem,
};

interface KeyboardControllerObserver {
  // Called when a keyboard enable flag changes.
  OnKeyboardEnableFlagsChanged(array<keyboard.mojom.KeyboardEnableFlag> flags);

  // Called when the keyboard is enabled or disabled. If ReloadKeyboard() is
  // called or other code enables the keyboard while already enabled, this will
  // be called twice, once when the keyboard is disabled and again when it is
  // re-enabled.
  OnKeyboardEnabledChanged(bool is_enabled);

  // Called when the virtual keyboard configuration changes.
  OnKeyboardConfigChanged(keyboard.mojom.KeyboardConfig config);

  // Called when the visibility of the virtual keyboard changes, e.g. an input
  // field is focused or blurred, or the user hides the keyboard.
  OnKeyboardVisibilityChanged(bool visible);

  // Called when the keyboard bounds change. |screen_bounds| is in screen
  // coordinates.
  OnKeyboardVisibleBoundsChanged(gfx.mojom.Rect screen_bounds);

  // Called when the keyboard occluded bounds change. |screen_bounds| is in
  // screen coordinates.
  OnKeyboardOccludedBoundsChanged(gfx.mojom.Rect screen_bounds);

  // Signals a request to load the keyboard contents. If the contents are
  // already loaded, requests a reload. Once the contents have loaded,
  // KeyboardController.KeyboardContentsLoaded is expected to be called by the
  // client implementation.
  OnLoadKeyboardContentsRequested();

  // Called when the UI has been destroyed so that the client can reset the
  // embedded contents and handle.
  OnKeyboardUIDestroyed();
};

interface KeyboardController {
  // Informs the controller that the keyboard contents have loaded.
  KeyboardContentsLoaded(gfx.mojom.Size size);

  // Retrieves the current keyboard configuration.
  GetKeyboardConfig() => (keyboard.mojom.KeyboardConfig config);

  // Sets the current keyboard configuration.
  SetKeyboardConfig(keyboard.mojom.KeyboardConfig config);

  // Returns whether the virtual keyboard has been enabled.
  IsKeyboardEnabled() => (bool enabled);

  // Sets the provided keyboard enable flag. If the computed enabled state
  // changes, enables or disables the keyboard to match the new state.
  SetEnableFlag(keyboard.mojom.KeyboardEnableFlag flag);

  // Clears the provided keyboard enable flag. If the computed enabled state
  // changes, enables or disables the keyboard to match the new state.
  ClearEnableFlag(keyboard.mojom.KeyboardEnableFlag flag);

  // Gets the current set of keyboard enable flags.
  GetEnableFlags() => (array<keyboard.mojom.KeyboardEnableFlag> flags);

  // Reloads the virtual keyboard if it is enabled and the URL has changed, e.g.
  // the focus has switched from one type of field to another.
  ReloadKeyboardIfNeeded();

  // Rebuilds (disables and re-enables) the virtual keyboard if it is enabled.
  // This is used to force a reload of the virtual keyboard when preferences or
  // other configuration that affects loading the keyboard may have changed.
  RebuildKeyboardIfEnabled();

  // Returns whether the virtual keyboard is visible.
  IsKeyboardVisible() => (bool visible);

  // Shows the virtual keyboard on the current display if it is enabled.
  ShowKeyboard();

  // Hides the virtual keyboard if it is visible.
  HideKeyboard(HideReason reason);

  // Sets the keyboard container type. If non empty, |target_bounds| provides
  // the container size. Returns whether the transition succeeded once the
  // container type changes (or fails to change).
  SetContainerType(keyboard.mojom.ContainerType container_type,
                   gfx.mojom.Rect? target_bounds) => (bool result);

  // If |locked| is true, the keyboard remains visible even when no window has
  // input focus.
  SetKeyboardLocked(bool locked);

  // Sets the regions of the keyboard window that occlude whatever is behind it.
  SetOccludedBounds(array<gfx.mojom.Rect> bounds);

  // Sets the regions of the keyboard window where events should be handled.
  SetHitTestBounds(array<gfx.mojom.Rect> bounds);

  // Sets the region of the keyboard window that can be used as a drag handle.
  SetDraggableArea(gfx.mojom.Rect bounds);

  // Adds a KeyboardControllerObserver.
  AddObserver(associated KeyboardControllerObserver observer);
};