third_party/blink/public/mojom/frame/find_in_page.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 blink.mojom;

import "ui/gfx/geometry/mojo/geometry.mojom";

interface FindInPage {
  // If |options.find_next| is false, this is a "Start Find" call.
  // It starts a new find-in-page session with id |request_id|.
  // If |options.find_next| is true, this is a "Find Next" call.
  // It asks the active/highlighted match for session with id |request_id|
  // to be moved either forward if |options.forward| is true, or backwards
  // if |options.forward| is false.
  Find(int32 request_id, string search_text, FindOptions options);

  // Notifies the frame that we are no longer interested in searching. This
  // will abort any asynchronous scoping effort already under way and erase
  // all tick-marks and highlighting from the previous search.  It will also
  // follow the specified StopFindAction.
  StopFinding(StopFindAction action);

  // Notify the frame that it is no longer the active frame in the
  // current find session, and so it should clear its active find match
  // (and no longer highlight it with special coloring).
  ClearActiveFindMatch();

  // Request the distance to the nearest find result in a frame from |point|
  // defined in fractions of the content document's width and height.
  GetNearestFindResult(gfx.mojom.PointF point) => (float distance);

  // Activates a find result nearest to |point|, which is in fractions of the
  // content document's width and height. This function will call either the
  // SetActiveMatch or SetNumberOfMatches on the FindInPageClient for this
  // FindInPage instance.
  // TODO(rakina): Find a way to remove |request_id|
  ActivateNearestFindResult(int32 request_id, gfx.mojom.PointF point);

  // Sets the client for this FindInPage instance. Should be called before
  // calling ActivateNearestFindResult.
  // TODO(rakina): Remove the need for this?
  SetClient(FindInPageClient client);

  // Returns the bounding boxes of the find-in-page match markers from the
  // frame. The bounding boxes are returned in find-in-page coordinates.
  //
  // Return values:
  // |version| will contain the current version number of the renderer's find
  // match list (incremented whenever they change), which should be passed in
  // the next call to FindMatchRects.
  //
  // |rects| will either contain a list of the enclosing rects of all matches
  // found by the most recent Find operation, or will be empty if |version| is
  // not greater than the |current_version| in the FindMatchRects call (hence
  // your locally cached rects should still be valid). The rect coords will be
  // custom normalized fractions of the document size. The rects will be sorted
  // by frame traversal order starting in the main frame, then by DOM order.
  //
  // |active_rect| will contain the bounding box of the active find-in-page
  // match marker, in similarly normalized coords (or an empty rect if there
  // isn't one).
  FindMatchRects(int32 current_version) =>
                (int32 version, array<gfx.mojom.RectF> rects,
                gfx.mojom.RectF active_match_rect);
};

// Per-frame client of FindInPage.
interface FindInPageClient {
  // Sets the number of matches of the frame to |number_of_matches|.
  // If |final_update| is kFinalUpdate, there will be no more update to the
  // number of matches or active match for this frame.
  SetNumberOfMatches(int32 request_id, uint32 number_of_matches,
                     FindMatchUpdateType update_type);

  // Sets the current active match rect and ordinal.
  // If |final_update| is kFinalUpdate, there will be no more update to the
  // number of matches or active match for this frame.
  SetActiveMatch(int32 request_id, gfx.mojom.Rect active_match_rect,
                 int32 active_match_ordinal,
                 FindMatchUpdateType update_type);
};

// This enum defines what actions the renderer should take next when
// the user has completed a find-in-page;
enum StopFindAction {
  // No selection will be left.
  kStopFindActionClearSelection,
  // The active match will remain selected.
  kStopFindActionKeepSelection,
  // The active match selection will be activated.
  kStopFindActionActivateSelection
};

// Type of updates for FindInPageClient::SetNumberOfMatches
enum FindMatchUpdateType {
  kFinalUpdate,
  kMoreUpdatesComing
};

struct FindOptions {
 // Whether to search forward or backward within the page.
  bool forward;

  // Whether search should be case-sensitive.
  bool match_case;

  // Whether this operation is the first request or a follow-up.
  bool find_next;

  // Force a re-search of the frame: typically used when forcing a re-search
  // after the frame navigates.
  bool force;

  // Signifies whether we should force text scoping to happen immediately
  // or not. Only used for testing purposes.
  bool run_synchronously_for_testing;
};