content/common/input/input_handler.mojom

// 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 content.mojom;

import "content/common/input/synchronous_compositor.mojom";
import "content/common/native_types.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "services/ws/public/mojom/ime/ime.mojom";
import "third_party/blink/public/web/selection_menu_behavior.mojom";
import "ui/events/mojo/event.mojom";
import "ui/events/mojo/event_constants.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";
import "ui/gfx/range/mojo/range.mojom";
import "ui/latency/mojo/latency_info.mojom";


// These structs are purposely duplicated from ui/events/mojom/event.mojom.
// They map WebInputEvent <-> WebInputEvent across mojo.
// We have to work at unifying them. The current problem is that the browser
// uses WebInputEvents inside the render widget host and input router. Once
// we move these to ui::Event's then we can get rid of these duplicated
// mojom structs. Ideally the browser would use ui::Event up until we
// pass the events into the renderer and just use a StructTraits to perform
// conversion from ui::mojom::Event --> blink::WebInputEvent.
struct KeyData {
  int32 dom_key;
  int32 dom_code;
  int32 windows_key_code;
  int32 native_key_code;
  bool is_system_key;
  bool is_browser_shortcut;
  mojo_base.mojom.String16 text;
  mojo_base.mojom.String16 unmodified_text;
};

struct PointerData {
  int32 pointer_id;
  float force;
  int32 tilt_x;
  int32 tilt_y;
  float tangential_pressure;
  int32 twist;
  Button button;
  PointerType pointer_type;
  int32 movement_x;
  int32 movement_y;
  gfx.mojom.PointF widget_position;
  gfx.mojom.PointF screen_position;
  MouseData? mouse_data;
};

struct WheelData {
  float delta_x;
  float delta_y;
  float wheel_ticks_x;
  float wheel_ticks_y;
  float acceleration_ratio_x;
  float acceleration_ratio_y;
  int32 resending_plugin_id;
  uint8 phase;
  uint8 momentum_phase;
  bool scroll_by_page;
  bool has_precise_scrolling_deltas;
  Cancelability cancelable;
  uint8 event_action;
};

struct MouseData {
  int32 click_count;
  WheelData? wheel_data;
};

struct ScrollUpdate {
  float velocity_x;
  float velocity_y;
  bool previous_update_in_sequence_prevented;
};

struct ScrollData {
  float delta_x;
  float delta_y;
  ScrollUnits delta_units;
  bool target_viewport;
  InertialPhaseState inertial_phase;
  bool synthetic;
  int32 pointer_count;
  ScrollUpdate? update_details;
};

struct PinchData {
  float scale;
};

struct FlingData {
  float velocity_x;
  float velocity_y;
  bool target_viewport;
  bool prevent_boosting;
};

struct TapData {
  int32 tap_count;
};

struct GestureData {
  gfx.mojom.PointF screen_position;
  gfx.mojom.PointF widget_position;
  GestureDevice source_device;
  bool is_source_touch_event_set_non_blocking;
  PointerType primary_pointer_type;
  int32 unique_touch_event_id;
  int32 resending_plugin_id;
  gfx.mojom.Size? contact_size;
  ScrollData? scroll_data;
  PinchData? pinch_data;
  TapData? tap_data;
  FlingData? fling_data;
};

struct TouchPoint {
  TouchState state;
  float radius_x;
  float radius_y;
  float rotation_angle;
  PointerData pointer_data;
};

struct TouchData {
  Cancelability cancelable;
  bool moved_beyond_slop_region;
  bool touch_start_or_first_move;
  bool hovering;
  uint32 unique_touch_event_id;
  array<TouchPoint> touches;
};

struct Event {
  EventType type;
  int32 modifiers;
  mojo_base.mojom.TimeTicks timestamp;
  ui.mojom.LatencyInfo latency;
  KeyData? key_data;
  PointerData? pointer_data;
  GestureData? gesture_data;
  TouchData? touch_data;
};

struct TouchActionOptional {
  TouchAction touch_action;
};

// Interface exposed by the browser to the renderer. The messages
// contained in here are state changes that the renderer has taken
// that the browser must be aware of.
interface WidgetInputHandlerHost {
  // When the renderer's main thread computes the touch action, send this to the
  // browser.
  SetTouchActionFromMain(TouchAction touch_action);

  // The whitelisted touch action and the associated unique touch event id
  // for a new touch point sent by the compositor. The unique touch event id is
  // only needed to verify that the whitelisted touch action is being associated
  // with the correct touch event. The input event ack state is needed when
  // the touchstart message was not sent to the renderer and the touch
  // actions need to be reset and the touch ack timeout needs to be started.
  SetWhiteListedTouchAction(TouchAction touch_action,
                            uint32 unique_touch_event_id,
                            InputEventAckState state);

  // Sent by the compositor when input scroll events are dropped due to bounds
  // restrictions on the root scroll offset.
  DidOverscroll(DidOverscrollParams params);

  // Sent by the compositor when a GSB has started scrolling the viewport.
  DidStartScrollingViewport();

  // Required for cancelling an ongoing input method composition.
  ImeCancelComposition();

  // Sends the character bounds after every composition change
  // to always have correct bound info.
  ImeCompositionRangeChanged(gfx.mojom.Range range,
                             array<gfx.mojom.Rect> bounds);

  // Updates the mouse capture state of this widget. While capture is enabled,
  // all mouse events, including those that don't hittest to this widget, will
  // be targeted to this widget. This enables Blink to behave correctly when
  // a scrollbar is being dragged, or text is being drag-highlighted, even
  // when the mouse passes across different RenderWidget areas.
  SetMouseCapture(bool capture);
};

// Interface exposed by the renderer to the browser. This class represents
// an input interface for an associated Widget object. See FrameInputHandler
// for an interface at the frame level.
interface WidgetInputHandler {
  // Tells widget focus has been changed.
  SetFocus(bool focused);

  // Tells widget mouse capture has been lost.
  MouseCaptureLost();

  // This message notifies the renderer that the next key event is bound to one
  // or more pre-defined edit commands. If the next key event is not handled
  // by webkit, the specified edit commands shall be executed against current
  // focused frame.
  // Parameters
  // * edit_commands (see chrome/common/edit_command_types.h)
  //   Contains one or more edit commands.
  // See third_party/WebKit/Source/WebCore/editing/EditorCommand.cpp for
  // detailed definition of webkit edit commands.
  //
  // This message must be sent just before sending a key event.

  SetEditCommandsForNextKeyEvent(array<content.mojom.EditCommand> commands);

  // Sends the cursor visibility state to the render widget.
  CursorVisibilityChanged(bool visible);

  // This message sends a string being composed with an input method.
  ImeSetComposition(mojo_base.mojom.String16 text,
                    array<ws.mojom.ImeTextSpan> ime_text_spans,
                    gfx.mojom.Range range, int32 start, int32 end);

  // This message deletes the current composition, inserts specified text, and
  // moves the cursor.
  ImeCommitText(mojo_base.mojom.String16 text,
                array<ws.mojom.ImeTextSpan> ime_text_spans,
                gfx.mojom.Range range, int32 relative_cursor_position) => ();

  // This message inserts the ongoing composition.
  ImeFinishComposingText(bool keep_selection);

  // Request from browser to update text input state.
  RequestTextInputStateUpdate();

  // Request from browser to update the cursor and composition information which
  // will be sent through ImeCompositionRangeChanged. Setting
  // |immediate_request| to true  will lead to an immediate update. If
  // |monitor_updates| is set to true then changes to text selection or regular
  // updates in each compositor frame (when there is a change in composition
  // info) will lead to updates being sent to the browser.
  RequestCompositionUpdates(bool immediate_request, bool monitor_request);

  // Sends an input event to the render widget. The browser should use this
  // API if it wants to know about the result of the rendering handling
  // the event. The callback may be delayed based on the event running on
  // the main thread so DispatchNonBlockingEvent is always preferred if
  // you don't require notification.
  DispatchEvent(Event event)
      => (InputEventAckSource source, ui.mojom.LatencyInfo updated_latency,
         InputEventAckState state, DidOverscrollParams? overscroll,
         TouchActionOptional? touch_action);

  // Sends a non-blocking input event to the render widget. The behaviour
  // of this API is the same as DispatchEvent just that there is no callback
  // after the event is processed.
  DispatchNonBlockingEvent(Event event);

  // Forces input to be flushed and resolves the callback only once the input
  // has been fully processed, meaning its effects are visible to the full
  // system. In practice, this will force a redraw and wait until the new
  // CompositorFrame (containing all changes caused by prior input) has been
  // displayed.
  WaitForInputProcessed() => ();

  // Attach the synchronous compositor interface. This method only
  // should be called for Android WebView.
  AttachSynchronousCompositor(
      SynchronousCompositorControlHost control_host,
      associated SynchronousCompositorHost host,
      associated SynchronousCompositor& compositor_request);
};

// This interface provides the input actions associated with the RenderFrame.
// Other input actions may also be dispatched via the WidgetInputHandler
// interface. If frame input actions are dispatched the WidgetInputHandler
// should be fetched via the associated interface request so that input calls
// remain in order. See https://goo.gl/x4ee8A for more details.
interface FrameInputHandler {
  // Sets the text composition to be between the given start and end offsets in
  // the currently focused editable field.
  SetCompositionFromExistingText(
      int32 start, int32 end, array<ws.mojom.ImeTextSpan> ime_text_spans);

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

  // Deletes text before and after the current cursor position, excluding the
  // selection. The lengths are supplied in Java chars (UTF-16 Code Unit),
  // not in code points or in glyphs.
  DeleteSurroundingText(int32 before, int32 after);

  // Deletes text before and after the current cursor position, excluding the
  // selection. The lengths are supplied in code points, not in Java chars
  // (UTF-16 Code Unit) or in glyphs. Does nothing if there are one or more
  // invalid surrogate pairs in the requested range
  DeleteSurroundingTextInCodePoints(int32 before, int32 after);

  // Selects between the given start and end offsets in the currently focused
  // editable field.
  SetEditableSelectionOffsets(int32 start, int32 end);

  // Message payload is the name/value of a WebCore edit command to execute.
  ExecuteEditCommand(string command, mojo_base.mojom.String16? value);

  // These messages are typically generated from context menus and request the
  // renderer to apply the specified operation to the current selection.
  Undo();
  Redo();
  Cut();
  Copy();
  CopyToFindPboard();
  Paste();
  PasteAndMatchStyle();
  Delete();
  SelectAll();
  CollapseSelection();

  // Replaces the selected region or a word around the cursor with the
  // specified string.
  Replace(mojo_base.mojom.String16 word);

  // Replaces the misspelling in the selected region with the specified string.
  ReplaceMisspelling(mojo_base.mojom.String16 word);

  // Requests the renderer to select the region between two points.
  // Expects a SelectRange_ACK message when finished.
  SelectRange(gfx.mojom.Point base, gfx.mojom.Point extent);

  // Sent by the browser to ask the renderer to adjust the selection start and
  // end points by the given amounts. A negative amount moves the selection
  // towards the beginning of the document, a positive amount moves the
  // selection towards the end of the document. Will send show selection menu
  // event when needed.
  AdjustSelectionByCharacterOffset(
      int32 start, int32 end, blink.mojom.SelectionMenuBehavior behavior);

  // Requests the renderer to select word around caret.
  // Expects ack with new selection information when finished. |start_adjust|
  // and |end_adjust| are the start and end offset difference between the
  // current selection and the previous selection (which is a caret).
  [EnableIf=is_android]
  SelectWordAroundCaret()
      => (bool did_select, int32 start_adjust, int32 end_adjust);

  // Requests the renderer to move the selection extent point to a new position.
  // Expects a MoveRangeSelectionExtent_ACK message when finished.
  MoveRangeSelectionExtent(gfx.mojom.Point extent);

  // Tells the renderer to scroll the currently focused node into rect only if
  // the currently focused node is a Text node (textfield, text area or content
  // editable divs).
  ScrollFocusedEditableNodeIntoRect(gfx.mojom.Rect rect);

  // Requests the renderer to move the caret selection toward the point.
  MoveCaret(gfx.mojom.Point point);

  // Return an associated WidgetInputHandler interface so that input
  // messages to the widget associated with this frame can be sent
  // serially.
  GetWidgetInputHandler(associated WidgetInputHandler& interface_request,
                        WidgetInputHandlerHost host);
};