// Copyright 2016 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 ws.mojom;

import "mojo/public/mojom/base/text_direction.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "ui/base/ime/mojo/ime_types.mojom";
import "ui/events/mojo/event.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";
import "ui/gfx/range/mojo/range.mojom";
import "ui/platform_window/mojo/text_input_state.mojom";

// Specifies where to display the candidate window.
enum CandidateWindowPosition {
  // Candidate window follows the cursor.
  kCursor,

  // Candidate window is locked to the beginning of the composition.
  kComposition
};

struct CandidateWindowProperties {
  // Number of candidates to display per page.
  int32 page_size;

  // Should candidate window be rendered vertical or horizontal.
  bool vertical;

  // Text that is shown at the bottom of the candidate window.
  string auxiliary_text;

  // True to display auxiliary text, false to hide it.
  bool auxiliary_text_visible;

  // Position and visibility of cursor in the candidate window.
  int32 cursor_position;
  bool cursor_visible;

  // Where to display the candidate window.
  CandidateWindowPosition window_position;
};

// Represents a candidate window entry.
struct CandidateWindowEntry {
  // Value of the candidate.
  mojo_base.mojom.String16 value;

  // Short string displayed next to the candidate, often the shortcut key or
  // index.
  mojo_base.mojom.String16 label;

  // Additional text describing the candidate.
  mojo_base.mojom.String16 annotation;

  // The usage or detailed description of the candidate.
  mojo_base.mojom.String16 description_title;
  mojo_base.mojom.String16 description_body;
};

// Represents the text input state of a client.
struct TextInputState {
  ui.mojom.TextInputType text_input_type;
  ui.mojom.TextInputMode text_input_mode;
  mojo_base.mojom.TextDirection text_direction;
  int32 text_input_flags;  // A bitfield of ui::TextInputFlags.
};

// Cached input context information so that RemoteTextInputClient could support
// synchronous getters.
struct TextInputClientData {
  gfx.mojom.Range? text_range;
  mojo_base.mojom.String16? text;
  bool has_composition_text;
  gfx.mojom.Range? composition_text_range;
  gfx.mojom.Range? editable_selection_range;
  // Contains a boolean indicating the enabled state of each of the
  // ui::TextEditCommands, where the index is the command. For example,
  // edit_command_enabled[TextCommand::DELETE_BACKWARD] gives the enabled
  // state of TextCommand::DELETE_BACKWARD.
  array<bool>? edit_command_enabled;
};

// Detailed data of an IME session.
struct SessionDetails {
  // State of the text input client.
  TextInputState state;

  // Caret bounds of the text input client.
  gfx.mojom.Rect caret_bounds;

  // Data of the text input client.
  TextInputClientData data;

  // How the text input client was focused.
  ui.mojom.FocusReason focus_reason;

  // ukm::SourceId for identifying the text input client.
  int64 client_source_for_metrics;

  // Whether the text entered into this text input client should be used to
  // improve IME suggestions.
  bool should_do_learning;
};

// A service which provides the IMEDriver interface is responsible for doing
// the composition logic. After starting a session, it receives events from
// the client via the InputMethod interface, and sends composition events to
// the client via the TextInputClient.
interface IMEDriver {
  StartSession(InputMethod& input_method_request,
               TextInputClient client,
               SessionDetails details);
};

// An IME driver register should register itself to Mus using the IMERegistrar
// interface.
interface IMERegistrar {
  RegisterDriver(IMEDriver driver);
};

// A client sends updates to the IME driver using the InputMethod interface.
// This interface is provided by IME drivers, and also by Mus as a lightweight
// proxy between IME drivers and clients.
interface InputMethod {
  // Called when the text input state of client is changed.
  OnTextInputStateChanged(TextInputState text_input_state);

  // Client sends |caret_bounds| in focused window coordinates,
  // Mus translates it to global coordinates and sends it to IME app.
  OnCaretBoundsChanged(gfx.mojom.Rect caret_bounds);

  // Update the cached text input client data.
  OnTextInputClientDataChanged(TextInputClientData data);

  // Called to process a key event. The callback function will be called to
  // notify the client if the event was handled or not. A handled event may
  // generate zero or more composition events which will be sent to the client
  // using the "input method result" functions of TextInputClient interface.
  ProcessKeyEvent(ui.mojom.Event key_event) => (bool handled);

  CancelComposition();

  // Plumbs requests to show the virtual keyboard.
  ShowVirtualKeyboardIfEnabled();
};

// IME drivers send updates to clients using the TextInputClient interface.
interface TextInputClient {
  // Functions corresponding to "input method result" functions of
  // ui::TextInputClient. See comments for InputMethod::ProcessKeyEvent() for
  // when these are called.

  // Sets composition text and attributes. See comments for
  // ui::TextInputClient::SetCompositionText() for more details.
  SetCompositionText(ui.mojom.CompositionText composition);

  // Converts current composition text into final content.
  ConfirmCompositionText();

  // Removes current composition text.
  ClearCompositionText();

  // Inserts a given text at the insertion point. Current composition text or
  // selection will be removed. This method should never be called when the
  // current text input type is TEXT_INPUT_TYPE_NONE.
  InsertText(mojo_base.mojom.String16 text);

  // Inserts a single character at the insertion point. Unlike InsertText(),
  // the character is not processed. See ui::TextInputClient::InsertChar()
  // for more details.
  InsertChar(ui.mojom.Event event);

  // Dispatch a key event after minimal processing by the IME. The results of
  // the callback indicated whether the event was handled, and whether any
  // further processing should be performed. That is, if |stopped_propagation|
  // is true, IME does no further processing.
  DispatchKeyEventPostIME(ui.mojom.Event event) => (
      bool handled,
      bool stopped_propagation);

  // Ensure the caret is not in |rect|.  |rect| is in dip screen coordinates
  // and may extend beyond the bounds of this TextInputClient.
  EnsureCaretNotInRect(gfx.mojom.Rect rect);

  // Selects the given UTF-16 based character range. Current composition text
  // will be confirmed before selecting the range.
  SetEditableSelectionRange(gfx.mojom.Range range);

  // Deletes contents in the given UTF-16 based character range. Current
  // composition text will be confirmed before deleting the range.
  DeleteRange(gfx.mojom.Range range);

  // Called whenever current keyboard layout or input method is changed.
  OnInputMethodChanged();

  // Called whenever the user requests to change the text direction and layout
  // alignment of the current text box.
  ChangeTextDirectionAndLayoutAlignment(
      mojo_base.mojom.TextDirection direction);

  // Deletes the current selection plus the specified number of characters
  // before and after the selection or caret.
  ExtendSelectionAndDelete(uint32 before, uint32 after);

  // TODO(moshayedi): Add functions corresponding to ui::TextInputClient for:
  // - Input context information
  // - Document content operations
  // - Miscellaneous functions
  // crbug.com/631527.
};