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

import "services/network/public/mojom/network_param.mojom";
import "ui/accessibility/mojom/ax_tree_id.mojom";
import "ui/base/mojom/window_open_disposition.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "url/mojom/url.mojom";

// Parameters used to configure the behavior of |NavigableContents.Navigate|.
struct NavigateParams {
  // Indicates that upon successful navigation, the session history should be
  // cleared, resulting in the navigated page being the first and only entry in
  // the session's history.
  bool should_clear_session_history = false;
};

// The primary interface an application uses to drive a top-level, navigable
// content object. Typically this would correspond to e.g. a browser tab, but
// it is not strictly necessary that the contents have any graphical presence
// within the client application.
interface NavigableContents {
  // Initiates a navigation to |url|.
  Navigate(url.mojom.Url url, NavigateParams params);

  // Attempts to navigate the web contents back in its history stack. The
  // supplied |callback| is run to indicate success/failure of the attempt. The
  // navigation attempt will fail if the history stack is empty.
  GoBack() => (bool success);

  // Creates a visual representation of the navigated contents, which is
  // maintained by the Content Service. Responds with a |embed_token| which can
  // be given to Mus in order to authorize embedding of that visual
  // representation within the client application's own window tree.
  CreateView() => (mojo_base.mojom.UnguessableToken embed_token);

  // Attempts to transfer global input focus to the navigated contents if they
  // have an active visual representation.
  Focus();

  // Similar to above but for use specifically when UI traversal is being done
  // via Tab-key cycling.
  FocusThroughTabTraversal(bool reverse);
};

// A client interface used by the Content Service to push contents-scoped events
// back to the application.
interface NavigableContentsClient {
  // Requests that the client relinquish focus from the content area's view.
  ClearViewFocus();

  // Notifies the client that a navigation has finished.
  DidFinishNavigation(url.mojom.Url url,
                      bool is_main_frame,
                      bool is_error_page,
                      network.mojom.HttpResponseHeaders? response_headers);

  // Notifies the client that the NavigableContents has stopped loading
  // resources pertaining to a prior navigation request.
  DidStopLoading();

  // Indicates that the navigated contents changed in such a way as to elicit
  // automatic resizing of the containing view. Only fired if
  // |NavigableContentsParams.enable_view_auto_resize| was set to |true| when
  // creating the corresponding NavigableContents. The client may use this as a
  // signal to, e.g., resize a UI element containing the content view.
  DidAutoResizeView(gfx.mojom.Size new_size);

  // Notifies the client that a navigation was attempted by the contents (e.g.
  // by user gesture or script behavior), but it was suppressed because
  // |NavigableContentsParams.suppress_navigations| was set to |true| when the
  // NavigableContents was created. See that flag's documentation for details
  // regarding which types of navigations it can affect.
  DidSuppressNavigation(url.mojom.Url url,
                        ui.mojom.WindowOpenDisposition disposition,
                        bool from_user_gesture);

  // Informs the client of the ID of the content area's accessibility tree
  // whenever it changes.
  UpdateContentAXTree(ax.mojom.AXTreeID id);
};