| // Copyright 2012 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ |
| #define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ |
| |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| #include <memory> |
| #include <optional> |
| #include <string> |
| #include <vector> |
| |
| #include "base/functional/callback_forward.h" |
| #include "base/functional/callback_helpers.h" |
| #include "base/functional/function_ref.h" |
| #include "base/location.h" |
| #include "base/memory/raw_ptr.h" |
| #include "base/memory/safety_checks.h" |
| #include "base/memory/scoped_refptr.h" |
| #include "base/memory/weak_ptr.h" |
| #include "base/process/kill.h" |
| #include "base/supports_user_data.h" |
| #include "base/time/time.h" |
| #include "build/build_config.h" |
| #include "cc/input/browser_controls_state.h" |
| #include "content/common/content_export.h" |
| #include "content/public/browser/invalidate_type.h" |
| #include "content/public/browser/mhtml_generation_result.h" |
| #include "content/public/browser/navigation_controller.h" |
| #include "content/public/browser/page.h" |
| #include "content/public/browser/page_navigator.h" |
| #include "content/public/browser/preloading.h" |
| #include "content/public/browser/preloading_trigger_type.h" |
| #include "content/public/browser/prerender_handle.h" |
| #include "content/public/browser/save_page_type.h" |
| #include "content/public/browser/visibility.h" |
| #include "content/public/common/stop_find_action.h" |
| #include "services/network/public/mojom/web_sandbox_flags.mojom-shared.h" |
| #include "third_party/blink/public/mojom/favicon/favicon_url.mojom-forward.h" |
| #include "third_party/blink/public/mojom/frame/find_in_page.mojom-forward.h" |
| #include "third_party/blink/public/mojom/frame/remote_frame.mojom-forward.h" |
| #include "third_party/blink/public/mojom/input/pointer_lock_result.mojom.h" |
| #include "third_party/blink/public/mojom/media/capture_handle_config.mojom-forward.h" |
| #include "third_party/blink/public/mojom/mediastream/media_stream.mojom-forward.h" |
| #include "third_party/blink/public/mojom/picture_in_picture_window_options/picture_in_picture_window_options.mojom.h" |
| #include "third_party/perfetto/include/perfetto/tracing/traced_value_forward.h" |
| #include "third_party/skia/include/core/SkColor.h" |
| #include "ui/accessibility/ax_mode.h" |
| #include "ui/accessibility/ax_node.h" |
| #include "ui/accessibility/platform/inspect/ax_api_type.h" |
| #include "ui/base/cursor/mojom/cursor_type.mojom-shared.h" |
| #include "ui/color/color_provider_key.h" |
| #include "ui/display/types/display_constants.h" |
| #include "ui/gfx/geometry/rect.h" |
| #include "ui/gfx/geometry/size.h" |
| #include "ui/gfx/native_widget_types.h" |
| #include "url/gurl.h" |
| |
| #if BUILDFLAG(IS_ANDROID) |
| #include "base/android/scoped_java_ref.h" |
| #endif |
| |
| namespace base { |
| class FilePath; |
| } // namespace base |
| |
| namespace blink { |
| namespace web_pref { |
| struct WebPreferences; |
| } |
| class WebInputEvent; |
| struct UserAgentOverride; |
| struct RendererPreferences; |
| } // namespace blink |
| |
| namespace device { |
| namespace mojom { |
| class WakeLockContext; |
| } |
| } |
| |
| namespace net { |
| struct LoadStateWithParam; |
| } |
| |
| namespace service_manager { |
| class InterfaceProvider; |
| } |
| |
| namespace ui { |
| struct AXPropertyFilter; |
| struct AXTreeUpdate; |
| class ColorProvider; |
| class ColorProviderSource; |
| } |
| |
| namespace content { |
| |
| class BackForwardTransitionAnimationManager; |
| class BrowserContext; |
| class BrowserPluginGuestDelegate; |
| class RenderFrameHost; |
| class RenderViewHost; |
| class RenderWidgetHostView; |
| class ScreenOrientationDelegate; |
| class SiteInstance; |
| class WebContentsDelegate; |
| class WebUI; |
| struct DropData; |
| struct MHTMLGenerationParams; |
| class PreloadingAttempt; |
| |
| // WebContents is the core class in content/. A WebContents renders web content |
| // (usually HTML) in a rectangular area. |
| // |
| // Instantiating one is simple: |
| // std::unique_ptr<content::WebContents> web_contents( |
| // content::WebContents::Create( |
| // content::WebContents::CreateParams(browser_context))); |
| // gfx::NativeView view = web_contents->GetNativeView(); |
| // // |view| is an HWND, NSView*, etc.; insert it into the view hierarchy |
| // // wherever it needs to go. |
| // |
| // That's it; go to your kitchen, grab a scone, and chill. WebContents will do |
| // all the multi-process stuff behind the scenes. More details are at |
| // https://www.chromium.org/developers/design-documents/multi-process-architecture |
| // . |
| // |
| // The owner of `std::unique_ptr<content::WebContents> web_contents` is |
| // responsible for ensuring that `web_contents` are destroyed (e.g. closed) |
| // *before* the corresponding `browser_context` is destroyed. |
| // |
| // Each WebContents has a `NavigationController`, which can be obtained from |
| // `GetController()`, and is used to load URLs into the WebContents, navigate |
| // it backwards/forwards, etc. |
| // See navigation_controller.h for more details. |
| class WebContents : public PageNavigator, |
| public base::SupportsUserData { |
| // Do not remove this macro! |
| // The macro is maintained by the memory safety team. |
| ADVANCED_MEMORY_SAFETY_CHECKS(); |
| |
| public: |
| struct CONTENT_EXPORT CreateParams { |
| explicit CreateParams( |
| BrowserContext* context, |
| base::Location creator_location = base::Location::Current()); |
| CreateParams(BrowserContext* context, |
| scoped_refptr<SiteInstance> site, |
| base::Location creator_location = base::Location::Current()); |
| CreateParams(const CreateParams& other); |
| ~CreateParams(); |
| |
| raw_ptr<BrowserContext> browser_context; |
| |
| // Specifying a SiteInstance here is optional. It can be set to avoid an |
| // extra process swap if the first navigation is expected to require a |
| // privileged process. |
| scoped_refptr<SiteInstance> site_instance; |
| |
| // The process id of the frame initiating the open. |
| int opener_render_process_id = content::ChildProcessHost::kInvalidUniqueID; |
| |
| // The routing id of the frame initiating the open. |
| int opener_render_frame_id = MSG_ROUTING_NONE; |
| |
| // If the opener is suppressed, then the new WebContents doesn't hold a |
| // reference to its opener. |
| bool opener_suppressed = false; |
| |
| // Indicates whether this WebContents was created by another window. |
| // This is used when determining whether the WebContents is allowed to be |
| // closed via window.close(). This may be true even with a null |opener| |
| // (e.g., for blocked popups), or when the window is opened with "noopener". |
| bool opened_by_another_window = false; |
| |
| // The name of the top-level frame of the new window. It is non-empty |
| // when creating a named window (e.g. <a target="foo"> or |
| // window.open('', 'bar')). |
| std::string main_frame_name; |
| |
| // New window starts from the initial empty document. When created by an |
| // opener, the latter can request an initial navigation attempt to be made. |
| // This is the url specified in: `window.open(initial_popup_url, ...)`. |
| // This is empty otherwise. |
| GURL initial_popup_url; |
| |
| // True if the contents should be initially hidden. |
| bool initially_hidden = false; |
| |
| // If non-null then this WebContents will be hosted by a BrowserPlugin. |
| raw_ptr<BrowserPluginGuestDelegate> guest_delegate = nullptr; |
| |
| // Used to specify the location context which display the new view should |
| // belong. This can be unset if not needed. |
| gfx::NativeView context = gfx::NativeView(); |
| |
| // Used to specify that the new WebContents creation is driven by the |
| // renderer process. In this case, the renderer-side objects, such as |
| // RenderFrame, have already been created on the renderer side, and |
| // WebContents construction should take this into account. |
| bool renderer_initiated_creation = false; |
| |
| // Used to specify how far WebContents::Create can initialize a renderer |
| // process. |
| // |
| // This is useful in two scenarios: |
| // - Conserving resources - e.g. tab discarding and session restore do not |
| // want to use an actual renderer process before the WebContents are |
| // loaded or reloaded. This can be accomplished via kNoRendererProcess. |
| // - Avoiding the latency of the first navigation |
| // - kInitializeAndWarmupRendererProcess is most aggressive in avoiding |
| // the latency, but may be incompatible with scenarios that require |
| // manipulating the freshly created WebContents prior to initializing |
| // renderer-side objects (e.g. in scenarios like |
| // WebContentsImpl::CreateNewWindow which needs to copy the |
| // SessionStorageNamespace) |
| // - kOkayToHaveRendererProcess is the default latency-conserving mode. |
| // In this mode a spare, pre-spawned RenderProcessHost may be claimed |
| // by the newly created WebContents, but no renderer-side objects will |
| // be initialized from within WebContents::Create method. |
| // |
| // Note that the pre-created renderer process may not be used if the first |
| // navigation requires a dedicated or privileged process, such as a WebUI. |
| // This can be avoided by ensuring that |site_instance| matches the first |
| // navigation's destination. |
| enum RendererInitializationState { |
| // Creation of WebContents should not spawn a new OS process and should |
| // not reuse a RenderProcessHost that might be associated with an existing |
| // OS process (as in the case of SpareRenderProcessHostManager). |
| kNoRendererProcess, |
| |
| // Created WebContents may or may not be associated with an actual OS |
| // process. |
| kOkayToHaveRendererProcess, |
| |
| // Ensures that the created WebContents are backed by an OS process which |
| // has an initialized `blink::WebView`. |
| // |
| // TODO(lukasza): https://crbug.com/848366: Remove |
| // kInitializeAndWarmupRendererProcess value - warming up the renderer by |
| // initializing the `blink::WebView` is redundant with the warm-up that |
| // can be |
| // achieved by either 1) warming up the spare renderer before creating |
| // WebContents and/or 2) speculative RenderFrameHost used internally |
| // during a navigation. |
| kInitializeAndWarmupRendererProcess, |
| } desired_renderer_state = kOkayToHaveRendererProcess; |
| |
| // Sandboxing flags set on the new WebContents. |
| network::mojom::WebSandboxFlags starting_sandbox_flags = |
| network::mojom::WebSandboxFlags::kNone; |
| |
| // Value used to set the last time the WebContents was made active, this is |
| // the value that'll be returned by GetLastActiveTime(). If this is left |
| // default initialized then the value is not passed on to the WebContents |
| // and GetLastActiveTime() will return the WebContents' creation time. |
| base::TimeTicks last_active_time; |
| |
| // Code location responsible for creating the CreateParams. This is used |
| // mostly for debugging (e.g. to help attribute specific scenarios or |
| // invariant violations to a particular flavor of WebContents). |
| base::Location creator_location; |
| |
| #if BUILDFLAG(IS_ANDROID) |
| // Same as `creator_location`, for WebContents created via Java. This |
| // java.lang.Throwable contains the entire |
| // WebContentsCreator.createWebContents() stack trace. |
| base::android::ScopedJavaGlobalRef<jthrowable> java_creator_location; |
| #endif // BUILDFLAG(IS_ANDROID) |
| |
| // Enables contents to hold wake locks, for example, to keep the screen on |
| // while playing video. |
| bool enable_wake_locks = true; |
| |
| // Options specific to WebContents created for picture-in-picture windows. |
| std::optional<blink::mojom::PictureInPictureWindowOptions> |
| picture_in_picture_options; |
| |
| // Enable preview mode that shows a page with a capability restriction |
| // for previewing the page. |
| bool preview_mode = false; |
| }; |
| |
| // Token that causes input to be blocked on this WebContents for at least as |
| // long as it exists. |
| class CONTENT_EXPORT ScopedIgnoreInputEvents { |
| public: |
| ~ScopedIgnoreInputEvents(); |
| |
| ScopedIgnoreInputEvents(ScopedIgnoreInputEvents&&); |
| ScopedIgnoreInputEvents& operator=(ScopedIgnoreInputEvents&&); |
| |
| private: |
| friend class WebContentsImpl; |
| explicit ScopedIgnoreInputEvents(base::OnceClosure on_destruction_cb); |
| |
| base::ScopedClosureRunner on_destruction_cb_; |
| }; |
| |
| // Creates a new WebContents. |
| // |
| // The caller is responsible for ensuring that the returned WebContents is |
| // destroyed (e.g. closed) *before* the BrowserContext associated with |
| // `params` is destroyed. It is a security bug if WebContents haven't been |
| // destroyed when the destructor of BrowserContext starts running. It is not |
| // necessarily a bug if WebContents haven't been destroyed when |
| // BrowserContext::NotifyWillBeDestroyed starts running. |
| // |
| // Best practices for managing the lifetime of `WebContents` and |
| // `BrowserContext` will vary across different //content embedders. For |
| // example, for information specific to the //chrome layer, please see the |
| // "Managing lifetime of a Profile" section in |
| // //chrome/browser/profiles/README.md. |
| CONTENT_EXPORT static std::unique_ptr<WebContents> Create( |
| const CreateParams& params); |
| |
| // Similar to Create() above but should be used when you need to prepopulate |
| // the SessionStorageNamespaceMap of the WebContents. This can happen if |
| // you duplicate a WebContents, try to reconstitute it from a saved state, |
| // or when you create a new WebContents based on another one (eg., when |
| // servicing a window.open() call). |
| // |
| // You do not want to call this. If you think you do, make sure you completely |
| // understand when SessionStorageNamespace objects should be cloned, why |
| // they should not be shared by multiple WebContents, and what bad things |
| // can happen if you share the object. |
| CONTENT_EXPORT static std::unique_ptr<WebContents> CreateWithSessionStorage( |
| const CreateParams& params, |
| const SessionStorageNamespaceMap& session_storage_namespace_map); |
| |
| // Returns the WebContents that owns the RenderViewHost. |
| // |
| // WARNING: `rvh` may belong to a prerendered page, a page in the back/forward |
| // cache, or a pending deletion page, so it might be inappropriate for it to |
| // to trigger changes to the WebContents. See also the below comments for |
| // FromRenderFrameHost(). |
| CONTENT_EXPORT static WebContents* FromRenderViewHost(RenderViewHost* rvh); |
| |
| // Returns the WebContents for the RenderFrameHost. It is unsafe to call this |
| // function with an invalid (e.g. destructed) `rfh`. |
| // |
| // WARNING: It might be inappropriate for `rfh` to trigger changes to the |
| // WebContents, so be careful when calling this. Some cases to be aware of |
| // are: |
| // * Pages/documents which are not active are not observable by the user |
| // and therefore should not show UI elements (e.g., a colour picker). These |
| // features should use `rfh->IsActive()` to determine whether `rfh` is |
| // active. See the comments there for more information. |
| // * Pages/documents which are not primary generally should not update |
| // per-WebContents state (e.g., theme colour). Use |
| // `rfh->GetPage().IsPrimary()` to check for primary. Fenced frames are |
| // one case where a RenderFrameHost can be active but not primary. |
| CONTENT_EXPORT static WebContents* FromRenderFrameHost(RenderFrameHost* rfh); |
| |
| // Returns the WebContents associated with the |frame_tree_node_id|. This may |
| // return nullptr if the RenderFrameHost is shutting down. |
| CONTENT_EXPORT static WebContents* FromFrameTreeNodeId( |
| int frame_tree_node_id); |
| |
| // A callback that returns a pointer to a WebContents. The callback can |
| // always be used, but it may return nullptr: if the info used to |
| // instantiate the callback can no longer be used to return a WebContents, |
| // nullptr will be returned instead. |
| // The callback should only run on the UI thread and it should always be |
| // non-null. |
| // Most uses of Getter and OnceGetter can likely be safety replaced with |
| // base::WeakPtr<WebContents>. |
| using Getter = base::RepeatingCallback<WebContents*(void)>; |
| // Use this variant for instances that will only run the callback a single |
| // time. |
| using OnceGetter = base::OnceCallback<WebContents*(void)>; |
| |
| // Sets delegate for platform specific screen orientation functionality. |
| CONTENT_EXPORT static void SetScreenOrientationDelegate( |
| ScreenOrientationDelegate* delegate); |
| |
| ~WebContents() override = default; |
| |
| // Intrinsic tab state ------------------------------------------------------- |
| |
| // Gets/Sets the delegate. |
| virtual WebContentsDelegate* GetDelegate() = 0; |
| virtual void SetDelegate(WebContentsDelegate* delegate) = 0; |
| |
| // Gets the NavigationController for primary frame tree of this WebContents. |
| // See comments on NavigationController for more details. |
| virtual NavigationController& GetController() = 0; |
| |
| // Returns the user browser context associated with this WebContents (via the |
| // NavigationController). |
| virtual content::BrowserContext* GetBrowserContext() = 0; |
| |
| // Returns a weak pointer. |
| virtual base::WeakPtr<WebContents> GetWeakPtr() = 0; |
| |
| // Gets the URL that is currently being displayed, if there is one. |
| // This method is deprecated. DO NOT USE! Pick either |GetVisibleURL| or |
| // |GetLastCommittedURL| as appropriate. |
| virtual const GURL& GetURL() = 0; |
| |
| // Gets the virtual URL currently being displayed in the URL bar, if there is |
| // one. This URL might be a pending navigation that hasn't committed yet, so |
| // it is not guaranteed to match the current page in this WebContents. |
| virtual const GURL& GetVisibleURL() = 0; |
| |
| // Gets the virtual URL of the last committed page in this WebContents. |
| // Virtual URLs are meant to be displayed to the user (e.g., they include the |
| // "view-source:" prefix for view source URLs, unlike NavigationEntry::GetURL |
| // and NavigationHandle::GetURL). The last committed page is the current |
| // security context and the content that is actually displayed within the tab. |
| // See also GetVisibleURL above, which may differ from this URL. Note that |
| // this might return an empty GURL if no navigation has committed in the |
| // WebContents' main frame. |
| virtual const GURL& GetLastCommittedURL() = 0; |
| |
| // Returns the primary main frame for the currently active page. Always |
| // non-null except during WebContents destruction. This WebContents may |
| // have additional main frames for prerendered pages, bfcached pages, etc. |
| // See docs/frame_trees.md for more details. |
| virtual const RenderFrameHost* GetPrimaryMainFrame() const = 0; |
| virtual RenderFrameHost* GetPrimaryMainFrame() = 0; |
| |
| // Returns the current page in the primary frame tree of this WebContents. |
| // If this WebContents is associated with an omnibox, usually the URL of the |
| // main document of this page will be displayed in it. |
| // |
| // Primary page can change as a result of a navigation, both to a new page |
| // (navigation loading a new main document) and an existing one (when |
| // restoring the page from back/forward cache or activating a prerendering |
| // page). This change can be observed using |
| // WebContentsObserver::PrimaryPageChanged, see the comments there for more |
| // details. |
| // |
| // The primary page's lifetime corresponds to its main document's lifetime |
| // and may differ from a RenderFrameHost's lifetime (for cross-document same |
| // RenderFrameHost navigations). |
| // |
| // Apart from the primary page, additional pages might be associated with this |
| // WebContents: |
| // - Pending commit pages (which will become primary after-and-if the ongoing |
| // main frame navigation successfully commits). |
| // - Pending deletion pages (pages the user has navigated from, but which are |
| // still alive as they are running unload handlers in background). |
| // - Pages in back/forward cache (which can be navigated to later). |
| // - Prerendered pages (pages which are loading in the background in |
| // anticipation of user navigating to them). |
| // |
| // Given the existence of multiple pages, in many cases (especially when |
| // handling IPCs from the renderer process), calling GetPrimaryPage would not |
| // be appropriate as it might return a wrong page. If the code already has a |
| // reference to RenderFrameHost or a Page (e.g. each IPC from the renderer |
| // process should be associated with a particular RenderFrameHost), it should |
| // be used instead of getting the primary page from the WebContents. |
| // See docs/frame_trees.md for more details. |
| virtual Page& GetPrimaryPage() = 0; |
| |
| // Returns the focused frame for the primary page or an inner page thereof. |
| // Might be nullptr if nothing is focused. |
| virtual RenderFrameHost* GetFocusedFrame() = 0; |
| |
| // Returns true if |frame_tree_node_id| refers to a frame in a prerendered |
| // page. |
| // TODO(1196715, 1232528): This will be extended to also return true if it is |
| // in an inner page of a prerendered page. |
| virtual bool IsPrerenderedFrame(int frame_tree_node_id) = 0; |
| |
| // NOTE: This is generally unsafe to use. A frame's RenderFrameHost may |
| // change over its lifetime, such as during cross-process navigation (and |
| // thus privilege change). Use RenderFrameHost::FromID instead wherever |
| // possible. |
| // |
| // Given a FrameTreeNode ID that belongs to this WebContents, returns the |
| // current RenderFrameHost regardless of which FrameTree it is in. |
| // |
| // See RenderFrameHost::GetFrameTreeNodeId for documentation on this ID. |
| virtual RenderFrameHost* UnsafeFindFrameByFrameTreeNodeId( |
| int frame_tree_node_id) = 0; |
| |
| // Calls |on_frame| for every RenderFrameHost in this WebContents. Note that |
| // this includes RenderFrameHosts that are not descended from the primary main |
| // frame (e.g. bfcached pages and prerendered pages). The order of traversal |
| // for RenderFrameHosts within a page is consistent with |
| // |RenderFrameHost::ForEachRenderFrameHost|'s order, however no order is |
| // guaranteed between pages. |
| // For callers only interested in the primary page, |
| // |GetMainFrame()->ForEachRenderFrameHost()| can be used. |
| // See |RenderFrameHost::ForEachRenderFrameHost| for details. |
| using FrameIterationAction = RenderFrameHost::FrameIterationAction; |
| virtual void ForEachRenderFrameHostWithAction( |
| base::FunctionRef<FrameIterationAction(RenderFrameHost*)> on_frame) = 0; |
| virtual void ForEachRenderFrameHost( |
| base::FunctionRef<void(RenderFrameHost*)> on_frame) = 0; |
| |
| // Gets the current RenderViewHost for this tab. |
| virtual RenderViewHost* GetRenderViewHost() = 0; |
| |
| // Returns the currently active RenderWidgetHostView. This may change over |
| // time and can be nullptr (during setup and teardown). |
| virtual RenderWidgetHostView* GetRenderWidgetHostView() = 0; |
| |
| // Returns the outermost RenderWidgetHostView. This will return the platform |
| // specific RenderWidgetHostView (as opposed to |
| // RenderWidgetHostViewChildFrame), which can be used to create context |
| // menus. |
| virtual RenderWidgetHostView* GetTopLevelRenderWidgetHostView() = 0; |
| |
| // Request a one-time snapshot of the accessibility tree without changing |
| // the accessibility mode. See RenderFrame::AXTreeSnapshotter for |
| // definitions of |ax_mode|, |max_nodes|, and |timeout|. |
| using AXTreeSnapshotCallback = |
| base::OnceCallback<void(const ui::AXTreeUpdate&)>; |
| virtual void RequestAXTreeSnapshot(AXTreeSnapshotCallback callback, |
| ui::AXMode ax_mode, |
| size_t max_nodes, |
| base::TimeDelta timeout) = 0; |
| |
| // Causes the current page to be closed, including running its onunload event |
| // handler. |
| virtual void ClosePage() = 0; |
| |
| // Returns the theme color for the underlying content as set by the |
| // theme-color meta tag if any. |
| virtual std::optional<SkColor> GetThemeColor() = 0; |
| |
| // Returns the background color for the underlying content as set by CSS if |
| // any. |
| virtual std::optional<SkColor> GetBackgroundColor() = 0; |
| |
| // Sets the renderer-side default background color of the page. This is used |
| // when the page has not loaded enough to know a background color or if the |
| // page does not set a background color. |
| // Pass in nullopt to reset back to the default. |
| // Note there are situations where the base background color is not used, such |
| // as fullscreen. |
| // Note currently this is sent directly to the renderer, so does not interact |
| // directly with `RenderWidgetHostView::SetBackgroundColor`. There is pending |
| // refactor to remove `RenderWidgetHostView::SetBackgroundColor` and merge its |
| // functionality here, which will be more consistent and simpler to |
| // understand. |
| virtual void SetPageBaseBackgroundColor(std::optional<SkColor> color) = 0; |
| |
| // Sets the ColorProviderSource for the WebContents. The WebContents will |
| // maintain an observation of `source` until a new source is set or the |
| // current source is destroyed. WebContents will receive updates when the |
| // source's ColorProvider changes. |
| virtual void SetColorProviderSource(ui::ColorProviderSource* source) = 0; |
| |
| // Returns the ColorProvider instance for this WebContents object. This will |
| // always return a valid ColorProvider instance. |
| virtual const ui::ColorProvider& GetColorProvider() const = 0; |
| |
| // Gets the color mode for the ColorProvider associated with this WebContents. |
| virtual ui::ColorProviderKey::ColorMode GetColorMode() const = 0; |
| |
| // Returns the committed WebUI if one exists. |
| virtual WebUI* GetWebUI() = 0; |
| |
| // Sets the user-agent that may be used for navigations in this WebContents. |
| // The user-agent is *only* used when |
| // NavigationEntry::SetIsOverridingUserAgent(true) is used (the value of |
| // is-overriding-user-agent may be specified in LoadURLParams). If |
| // |override_in_new_tabs| is true, and the first navigation in the tab is |
| // renderer initiated, then is-overriding-user-agent is set to true for the |
| // NavigationEntry. See SetRendererInitiatedUserAgentOverrideOption() for |
| // details on how renderer initiated navigations are configured. |
| // |
| // If nonempty, |ua_override|'s value must not contain '\0', '\r', or '\n' (in |
| // other words, it must be a valid HTTP header value). |
| virtual void SetUserAgentOverride(const blink::UserAgentOverride& ua_override, |
| bool override_in_new_tabs) = 0; |
| |
| // Configures the value of is-overriding-user-agent for renderer initiated |
| // navigations. The default is UA_OVERRIDE_INHERIT. This value does not apply |
| // to the first renderer initiated navigation if the tab has no navigations. |
| // See SetUserAgentOverride() for details on that. |
| virtual void SetRendererInitiatedUserAgentOverrideOption( |
| NavigationController::UserAgentOverrideOption option) = 0; |
| |
| virtual const blink::UserAgentOverride& GetUserAgentOverride() = 0; |
| |
| // Updates all renderers to start sending subresource notifications since a |
| // certificate error or HTTP exception has been allowed by the user. |
| virtual void SetAlwaysSendSubresourceNotifications() = 0; |
| virtual bool GetSendSubresourceNotification() = 0; |
| |
| // Returns true only if the WebContentsObserver accessibility mode is |
| // enabled. |
| virtual bool IsWebContentsOnlyAccessibilityModeForTesting() = 0; |
| |
| // Returns true only if complete accessibility mode is on, meaning there's |
| // both renderer accessibility, and a native browser accessibility tree. |
| virtual bool IsFullAccessibilityModeForTesting() = 0; |
| |
| virtual ui::AXMode GetAccessibilityMode() = 0; |
| |
| // Forces a reset of accessibility state in the instance's renderers. |
| // Observers will receive a new accessibility tree. |
| virtual void ResetAccessibility() = 0; |
| |
| // Returns a pointer to the root node of the live accessibility tree for the |
| // main frame, if accessibility is turned on. Otherwise, returns nullptr. |
| virtual ui::AXNode* GetAccessibilityRootNode() = 0; |
| |
| virtual std::string DumpAccessibilityTree( |
| bool internal, |
| std::vector<ui::AXPropertyFilter> property_filters) = 0; |
| |
| virtual std::string DumpAccessibilityTree( |
| ui::AXApiType::Type api_type, |
| std::vector<ui::AXPropertyFilter> property_filters) = 0; |
| |
| // A callback that takes a string which contains accessibility event |
| // information. |
| using AccessibilityEventCallback = |
| base::RepeatingCallback<void(const std::string&)>; |
| |
| // Starts or stops recording accessibility events. |start_recording| is true |
| // when recording should start and false when recording should stop. |
| // |callback| is an optional function which is called when an accessibility |
| // event is received while accessibility events are being recorded. When |
| // |start_recording| is true, it is expected that |callback| has a value; when |
| // |start_recording| is false, it is expected that |callback| does not. |
| virtual void RecordAccessibilityEvents( |
| bool start_recording, |
| std::optional<AccessibilityEventCallback> callback) = 0; |
| |
| virtual void RecordAccessibilityEvents( |
| ui::AXApiType::Type api_type, |
| bool start_recording, |
| std::optional<AccessibilityEventCallback> callback) = 0; |
| // Tab navigation state ------------------------------------------------------ |
| |
| // Returns the current navigation properties, which if a navigation is |
| // pending may be provisional (e.g., the navigation could result in a |
| // download, in which case the URL would revert to what it was previously). |
| virtual const std::u16string& GetTitle() = 0; |
| |
| // Saves the given title to the navigation entry and does associated work. It |
| // will update history and the view with the new title, and also synthesize |
| // titles for file URLs that have none. Thus |entry| must have a URL set. |
| virtual void UpdateTitleForEntry(NavigationEntry* entry, |
| const std::u16string& title) = 0; |
| |
| // Returns app title of the current navigation entry. The apptitle is |
| // an alternative title text that can be used by app windows. |
| // See |
| // https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/DocumentSubtitle/explainer.md |
| virtual const std::u16string& GetAppTitle() = 0; |
| |
| // Returns the SiteInstance associated with the current page. |
| virtual SiteInstance* GetSiteInstance() = 0; |
| |
| // Returns whether this WebContents is loading a resource. |
| virtual bool IsLoading() = 0; |
| |
| // Returns the current load progress. |
| virtual double GetLoadProgress() = 0; |
| |
| // Returns whether a navigation is currently in progress that should show |
| // loading UI if such UI exists (progress bar, loading spinner, stop button, |
| // etc.) True for different-document navigations and the navigation API's |
| // intercept(). This being true implies that IsLoading() is also true. |
| virtual bool ShouldShowLoadingUI() = 0; |
| |
| // Returns whether the current primary main document has reached and finished |
| // executing its onload() handler. Corresponds to |
| // WebContentsObserver::DocumentOnLoadCompletedInPrimaryMainFrame() and see |
| // comments there for more details. |
| virtual bool IsDocumentOnLoadCompletedInPrimaryMainFrame() = 0; |
| |
| // Returns whether this WebContents is waiting for a first-response for the |
| // main resource of the page. |
| virtual bool IsWaitingForResponse() = 0; |
| |
| // Returns whether this WebContents's primary frame tree node is navigating, |
| // i.e. it has an associated NavigationRequest. |
| virtual bool HasUncommittedNavigationInPrimaryMainFrame() = 0; |
| |
| // Returns the current load state and the URL associated with it. |
| // The load state is only updated while IsLoading() is true. |
| virtual const net::LoadStateWithParam& GetLoadState() = 0; |
| virtual const std::u16string& GetLoadStateHost() = 0; |
| |
| // Returns the upload progress. |
| virtual uint64_t GetUploadSize() = 0; |
| virtual uint64_t GetUploadPosition() = 0; |
| |
| // Returns the character encoding of the page. |
| virtual const std::string& GetEncoding() = 0; |
| |
| // Indicates that the tab was previously discarded. |
| // wasDiscarded is exposed on Document after discard, see: |
| // https://github.com/WICG/web-lifecycle |
| // When a tab is discarded, WebContents sets was_discarded on its |
| // root FrameTreeNode. |
| // In addition, when a child frame is created, this bit is passed on from |
| // parent to child. |
| // When a navigation request is created, was_discarded is passed on to the |
| // request and reset to false in FrameTreeNode. |
| virtual bool WasDiscarded() = 0; |
| virtual void SetWasDiscarded(bool was_discarded) = 0; |
| |
| // Notifies observers that this WebContents is about to be discarded, and |
| // replaced with `new_contents`. See the comment on |
| // WebContentsObserver::AboutToBeDiscarded. |
| virtual void AboutToBeDiscarded(WebContents* new_contents) = 0; |
| |
| // Internal state ------------------------------------------------------------ |
| |
| // Indicates whether the WebContents is being captured (e.g., for screenshots, |
| // or mirroring video and/or audio). Each IncrementCapturerCount() call must |
| // be balanced with a corresponding DecrementCapturerCount() call. |
| // |
| // Both internal-to-content and embedders must increment the capturer count |
| // while capturing to ensure "hidden rendering" optimizations are disabled. |
| // For example, renderers will be configured to produce compositor frames |
| // regardless of their "backgrounded" or on-screen occlusion state. |
| // |
| // Embedders can detect whether a WebContents is being captured (see |
| // IsBeingCaptured() below) and use this, for example, to provide an |
| // alternative user interface. So, developers should be careful to understand |
| // the side-effects from using or changing these APIs, both upstream and |
| // downstream of this API layer. |
| // |
| // Callers must hold onto the returned base::ScopedClosureRunner until they |
| // are done capturing. |
| // |
| // |capture_size| is only used in the case of mirroring (i.e., screen capture |
| // video); otherwise, an empty gfx::Size should be provided. This specifies |
| // the capturer's target video resolution, but can be empty to mean |
| // "unspecified." This becomes a temporary override to GetPreferredSize(), |
| // allowing embedders to size the WebContents on-screen views for optimal |
| // capture quality. |
| // |
| // |stay_hidden| affects the page visibility state of the renderers (i.e., a |
| // web page can be made aware of whether it is actually user-visible). If |
| // true, the show/hide state of the WebContents will be passed to the |
| // renderers, like normal. If false, the renderers will always be told they |
| // are user-visible while being captured. |
| // |
| // |stay_awake| will cause a WakeLock to be held which prevents system sleep. |
| // |
| // |is_activity| means the capture will cause the last active time to be |
| // updated. |
| [[nodiscard]] virtual base::ScopedClosureRunner IncrementCapturerCount( |
| const gfx::Size& capture_size, |
| bool stay_hidden, |
| bool stay_awake, |
| bool is_activity = true) = 0; |
| |
| // Getter for the capture handle, which allows a captured application to |
| // opt-in to exposing information to its capturer(s). |
| virtual const blink::mojom::CaptureHandleConfig& GetCaptureHandleConfig() = 0; |
| |
| // Returns true if audio/screenshot/video is being captured by the embedder, |
| // as indicated by calls to IncrementCapturerCount(). |
| virtual bool IsBeingCaptured() = 0; |
| |
| // Returns true if audio/screenshot/video is being captured by the embedder |
| // and renderers are being told they are always user-visible, as indicated by |
| // calls to IncrementCapturerCount(). |
| virtual bool IsBeingVisiblyCaptured() = 0; |
| |
| // Indicates/Sets whether all audio output from this WebContents is muted. |
| // This does not affect audio capture, just local/system output. |
| virtual bool IsAudioMuted() = 0; |
| virtual void SetAudioMuted(bool mute) = 0; |
| |
| // Returns true if the audio is currently audible. |
| virtual bool IsCurrentlyAudible() = 0; |
| |
| // Indicates whether any frame in the WebContents is connected to a Bluetooth |
| // Device. |
| virtual bool IsConnectedToBluetoothDevice() = 0; |
| |
| // Indicates whether any frame in the WebContents is scanning for Bluetooth |
| // devices. |
| virtual bool IsScanningForBluetoothDevices() = 0; |
| |
| // Indicates whether any frame in the WebContents is connected to a serial |
| // port. |
| virtual bool IsConnectedToSerialPort() = 0; |
| |
| // Indicates whether any frame in the WebContents is connected to a HID |
| // device. |
| virtual bool IsConnectedToHidDevice() = 0; |
| |
| // Indicates whether any frame in the WebContents is connected to a USB |
| // device. |
| virtual bool IsConnectedToUsbDevice() = 0; |
| |
| // Indicates whether any frame in the WebContents has File System Access |
| // handles. |
| virtual bool HasFileSystemAccessHandles() = 0; |
| |
| // Indicates whether a video is in Picture-in-Picture for |this|. |
| virtual bool HasPictureInPictureVideo() = 0; |
| |
| // Indicates whether a document is in Picture-in-Picture for |this|. |
| virtual bool HasPictureInPictureDocument() = 0; |
| |
| // Indicates whether this tab should be considered crashed. This becomes false |
| // again when the renderer process is recreated after a crash in order to |
| // recreate the main frame. |
| virtual bool IsCrashed() = 0; |
| |
| virtual base::TerminationStatus GetCrashedStatus() = 0; |
| virtual int GetCrashedErrorCode() = 0; |
| |
| // Whether the tab is in the process of being destroyed. |
| virtual bool IsBeingDestroyed() = 0; |
| |
| // Convenience method for notifying the delegate of a navigation state |
| // change. |
| virtual void NotifyNavigationStateChanged(InvalidateTypes changed_flags) = 0; |
| |
| // Notifies the WebContents that audio state has changed. The contents is |
| // aware of all of its potential sources of audio and needs to poll them |
| // directly to determine its aggregate audio state. |
| virtual void OnAudioStateChanged() = 0; |
| |
| // Get/Set the last time that the WebContents was made active (either when it |
| // was created or shown with WasShown()). |
| virtual base::TimeTicks GetLastActiveTime() = 0; |
| |
| // Invoked when the WebContents becomes shown/hidden. A hidden WebContents |
| // isn't painted on the screen. |
| virtual void WasShown() = 0; |
| virtual void WasHidden() = 0; |
| |
| // Invoked when the WebContents becomes occluded. An occluded WebContents |
| // isn't painted on the screen, except in a window switching feature (e.g. |
| // Alt-Tab). |
| virtual void WasOccluded() = 0; |
| |
| // Returns the visibility of the WebContents' view. |
| virtual Visibility GetVisibility() = 0; |
| |
| // Sets the visibility of the WebContents' view and notifies the WebContents |
| // observers about Visibility change. Call UpdateWebContentsVisibility instead |
| // of WasShown() if you are setting Visibility to VISIBLE for the first time. |
| // TODO(crbug.com/40911760): Make updating Visibility more robust. |
| virtual void UpdateWebContentsVisibility(Visibility visibility) = 0; |
| |
| // This function checks *all* frames in this WebContents (not just the main |
| // frame) and returns true if at least one frame has either a beforeunload or |
| // an unload/pagehide/visibilitychange handler. |
| // |
| // The value of this may change over time. For example, if true and the |
| // beforeunload listener is executed and allows the user to exit, then this |
| // returns false. |
| virtual bool NeedToFireBeforeUnloadOrUnloadEvents() = 0; |
| |
| // Runs the beforeunload handler for the main frame and all its subframes. |
| // See also ClosePage in RenderViewHostImpl, which runs the unload handler. |
| // If |auto_cancel| is true, and the beforeunload handler returns a non-empty |
| // string (indicating the page wants to present a confirmation dialog), then |
| // the beforeunload operation will automatically return with |proceed=false| |
| // and no dialog will be shown to the user. This is used to interrupt a |
| // potential discard without causing the dialog to appear. |
| virtual void DispatchBeforeUnload(bool auto_cancel) = 0; |
| |
| // Attaches |inner_web_contents| to the container frame |render_frame_host|, |
| // which must be in a FrameTree for this WebContents. This outer WebContents |
| // takes ownership of |inner_web_contents|. |
| // Note: |render_frame_host| will be swapped out and destroyed during the |
| // process. Generally a frame same-process with its parent is the right choice |
| // but ideally it should be "about:blank" to avoid problems with beforeunload. |
| // To ensure sane usage of this API users first should call the async API |
| // RenderFrameHost::PrepareForInnerWebContentsAttach first. |
| // Note: If |is_full_page| is true, focus will be given to the inner |
| // WebContents. |
| virtual void AttachInnerWebContents( |
| std::unique_ptr<WebContents> inner_web_contents, |
| RenderFrameHost* render_frame_host, |
| mojo::PendingAssociatedRemote<blink::mojom::RemoteFrame> remote_frame, |
| mojo::PendingAssociatedReceiver<blink::mojom::RemoteFrameHost> |
| remote_frame_host_receiver, |
| bool is_full_page) = 0; |
| |
| // Returns whether this WebContents is an inner WebContents for a guest. |
| // Important: please avoid using this in new callsites, and use |
| // GetOuterWebContents instead. |
| virtual bool IsInnerWebContentsForGuest() = 0; |
| |
| // Returns the outer WebContents frame, the same frame that this WebContents |
| // was attached in AttachToOuterWebContentsFrame(). |
| virtual RenderFrameHost* GetOuterWebContentsFrame() = 0; |
| |
| // Returns the outer WebContents of this WebContents if any. |
| // Otherwise, return nullptr. |
| virtual WebContents* GetOuterWebContents() = 0; |
| |
| // Returns the root WebContents of the WebContents tree. Always returns |
| // non-null value. |
| virtual WebContents* GetOutermostWebContents() = 0; |
| |
| // Returns a vector to the inner WebContents within this WebContents. |
| virtual std::vector<WebContents*> GetInnerWebContents() = 0; |
| |
| // Returns the user-visible WebContents that is responsible for the UI |
| // activity in the provided WebContents. For example, this delegate may be |
| // aware that the contents is embedded in some other contents, or hosts |
| // background activity on behalf of a user-visible tab which should be used to |
| // display dialogs and similar affordances to the user. |
| // |
| // This may be distinct from the outer web contents (for example, the |
| // responsible contents may logically "own" a contents but not currently embed |
| // it for rendering). |
| // |
| // Always returns a non-null value. |
| // |
| // TODO(crbug.com/40939539): Consider replacing this with |
| // GuestViewBase::GetTopLevelWebContents, since that is now the only case |
| // where this would return a contents other than |this|. |
| virtual WebContents* GetResponsibleWebContents() = 0; |
| |
| // Invoked when visible security state changes. |
| virtual void DidChangeVisibleSecurityState() = 0; |
| |
| // Sends the current preferences to all renderer processes for the current |
| // page. |
| virtual void SyncRendererPrefs() = 0; |
| |
| // Commands ------------------------------------------------------------------ |
| |
| // Stop any pending navigation. |
| virtual void Stop() = 0; |
| |
| // Freezes or unfreezes the current page. A frozen page runs as few tasks as |
| // possible. This cannot be called when the page is visible. If the page is |
| // made visible after this is called, it is automatically unfrozen. |
| virtual void SetPageFrozen(bool frozen) = 0; |
| |
| // Creates a new WebContents with the same state as this one. The returned |
| // heap-allocated pointer is owned by the caller. |
| virtual std::unique_ptr<WebContents> Clone() = 0; |
| |
| // Reloads the focused frame. |
| virtual void ReloadFocusedFrame() = 0; |
| |
| // Editing commands ---------------------------------------------------------- |
| |
| virtual void Undo() = 0; |
| virtual void Redo() = 0; |
| virtual void Cut() = 0; |
| virtual void Copy() = 0; |
| virtual void CopyToFindPboard() = 0; |
| virtual void CenterSelection() = 0; |
| virtual void Paste() = 0; |
| virtual void PasteAndMatchStyle() = 0; |
| virtual void Delete() = 0; |
| virtual void SelectAll() = 0; |
| virtual void CollapseSelection() = 0; |
| virtual void ScrollToTopOfDocument() = 0; |
| virtual void ScrollToBottomOfDocument() = 0; |
| |
| // Adjust the selection starting and ending points in the focused frame 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. |
| virtual void AdjustSelectionByCharacterOffset(int start_adjust, |
| int end_adjust, |
| bool show_selection_menu) = 0; |
| |
| // Replaces the currently selected word or a word around the cursor. |
| virtual void Replace(const std::u16string& word) = 0; |
| |
| // Replaces the misspelling in the current selection. |
| virtual void ReplaceMisspelling(const std::u16string& word) = 0; |
| |
| // Let the renderer know that the menu has been closed. |
| virtual void NotifyContextMenuClosed(const GURL& link_followed) = 0; |
| |
| // Executes custom context menu action that was provided from Blink. |
| virtual void ExecuteCustomContextMenuCommand(int action, |
| const GURL& link_followed) = 0; |
| |
| // Views and focus ----------------------------------------------------------- |
| |
| // Returns the native widget that contains the contents of the tab. |
| virtual gfx::NativeView GetNativeView() = 0; |
| |
| // Returns the native widget with the main content of the tab (i.e. the main |
| // render view host, though there may be many popups in the tab as children of |
| // the container). |
| virtual gfx::NativeView GetContentNativeView() = 0; |
| |
| // Returns the outermost native view. This will be used as the parent for |
| // dialog boxes. |
| virtual gfx::NativeWindow GetTopLevelNativeWindow() = 0; |
| |
| // Computes the rectangle for the native widget that contains the contents of |
| // the tab in the screen coordinate system. |
| virtual gfx::Rect GetContainerBounds() = 0; |
| |
| // Get the bounds of the View in the global screen position. |
| virtual gfx::Rect GetViewBounds() = 0; |
| |
| // Resize a WebContents to |new_bounds|. |
| virtual void Resize(const gfx::Rect& new_bounds) = 0; |
| |
| // Get the size of a WebContents. |
| virtual gfx::Size GetSize() = 0; |
| |
| // Returns the current drop data, if any. |
| virtual DropData* GetDropData() = 0; |
| |
| // Sets focus to the native widget for this tab. |
| virtual void Focus() = 0; |
| |
| // Sets focus to the appropriate element when the WebContents is shown the |
| // first time. |
| virtual void SetInitialFocus() = 0; |
| |
| // Stores the currently focused view. |
| virtual void StoreFocus() = 0; |
| |
| // Restores focus to the last focus view. If StoreFocus has not yet been |
| // invoked, SetInitialFocus is invoked. |
| virtual void RestoreFocus() = 0; |
| |
| // Focuses the first (last if |reverse| is true) element in the page. |
| // Invoked when this tab is getting the focus through tab traversal (|reverse| |
| // is true when using Shift-Tab). |
| virtual void FocusThroughTabTraversal(bool reverse) = 0; |
| |
| // Misc state & callbacks ---------------------------------------------------- |
| |
| // Check whether we can do the saving page operation this page given its MIME |
| // type. |
| virtual bool IsSavable() = 0; |
| |
| // Prepare for saving the current web page to disk. |
| virtual void OnSavePage() = 0; |
| |
| // Save page with the main HTML file path, the directory for saving resources, |
| // and the save type: HTML only or complete web page. Returns true if the |
| // saving process has been initiated successfully. |
| virtual bool SavePage(const base::FilePath& main_file, |
| const base::FilePath& dir_path, |
| SavePageType save_type) = 0; |
| |
| // Saves the given frame's URL to the local filesystem. If `rfh` is provided, |
| // the saving is performed in its context. For example, the associated |
| // navigation isolation info will be used for making the network request. |
| virtual void SaveFrame(const GURL& url, |
| const Referrer& referrer, |
| RenderFrameHost* rfh) = 0; |
| |
| // Saves the given frame's URL to the local filesystem. The headers, if |
| // provided, is used to make a request to the URL rather than using cache. |
| // Format of |headers| is a new line separated list of key value pairs: |
| // "<key1>: <value1>\r\n<key2>: <value2>". The saving is performed in the |
| // context of `rfh`. For example, the associated navigation isolation info |
| // will be used for making the network request. If `is_subresource` is true, |
| // the URL is assumed to correspond to a subresource loaded in the frame, |
| // as opposed to the main (generally, document) resource. |
| virtual void SaveFrameWithHeaders(const GURL& url, |
| const Referrer& referrer, |
| const std::string& headers, |
| const std::u16string& suggested_filename, |
| RenderFrameHost* rfh, |
| bool is_subresource) = 0; |
| |
| // Generate an MHTML representation of the current page conforming to the |
| // settings provided by |params| and returning final status information via |
| // the callback. See MHTMLGenerationParams for details on generation settings. |
| // A resulting |file_size| of -1 represents a failure. Any other value |
| // represents the size of the successfully generated file. |
| // |
| // TODO(https://crbug.com/915966): GenerateMHTML will eventually be removed |
| // and GenerateMHTMLWithResult will be renamed to GenerateMHTML to replace it. |
| // Both GenerateMHTML and GenerateMHTMLWithResult perform the same operation. |
| // however, GenerateMHTMLWithResult provides a struct as output, that contains |
| // the file size and more. |
| virtual void GenerateMHTML( |
| const MHTMLGenerationParams& params, |
| base::OnceCallback<void(int64_t /* file_size */)> callback) = 0; |
| virtual void GenerateMHTMLWithResult( |
| const MHTMLGenerationParams& params, |
| MHTMLGenerationResult::GenerateMHTMLCallback callback) = 0; |
| |
| // Returns the MIME type bound to the primary page contents after a primary |
| // page navigation. |
| virtual const std::string& GetContentsMimeType() = 0; |
| |
| // Returns the settings which get passed to the renderer. |
| virtual blink::RendererPreferences* GetMutableRendererPrefs() = 0; |
| |
| // Tells the tab to close now. The tab will take care not to close until it's |
| // out of nested run loops. |
| virtual void Close() = 0; |
| |
| // Indicates if this tab was explicitly closed by the user (control-w, close |
| // tab menu item...). This is false for actions that indirectly close the tab, |
| // such as closing the window. The setter is maintained by TabStripModel, and |
| // the getter only useful from within TAB_CLOSED notification |
| virtual void SetClosedByUserGesture(bool value) = 0; |
| virtual bool GetClosedByUserGesture() = 0; |
| |
| // Gets the minimum/maximum zoom percent. |
| virtual int GetMinimumZoomPercent() = 0; |
| virtual int GetMaximumZoomPercent() = 0; |
| |
| // Set the renderer's page scale to the given factor. |
| virtual void SetPageScale(float page_scale_factor) = 0; |
| |
| // Gets the preferred size of the contents. |
| virtual gfx::Size GetPreferredSize() = 0; |
| |
| // Called when the response to a pending pointer lock request has arrived. |
| // Returns true if |allowed| is true and the mouse has been successfully |
| // locked. |
| virtual bool GotResponseToPointerLockRequest( |
| blink::mojom::PointerLockResult result) = 0; |
| |
| // Wrapper around GotResponseToPointerLockRequest to fit into |
| // ChromeWebViewPermissionHelperDelegate's structure. |
| virtual void GotPointerLockPermissionResponse(bool allowed) = 0; |
| |
| // Drop the mouse lock if it is currently locked, or reject an |
| // outstanding request if it is pending. |
| virtual void DropPointerLockForTesting() = 0; |
| |
| // Called when the response to a keyboard mouse lock request has arrived. |
| // Returns false if the request is no longer valid, otherwise true. |
| virtual bool GotResponseToKeyboardLockRequest(bool allowed) = 0; |
| |
| #if BUILDFLAG(IS_ANDROID) || BUILDFLAG(IS_APPLE) |
| // Called when the user has selected a color in the color chooser. |
| virtual void DidChooseColorInColorChooser(SkColor color) = 0; |
| |
| // Called when the color chooser has ended. |
| virtual void DidEndColorChooser() = 0; |
| #endif |
| |
| // Returns true if the location bar should be focused by default rather than |
| // the page contents. The view calls this function when the tab is focused |
| // to see what it should do. |
| virtual bool FocusLocationBarByDefault() = 0; |
| |
| // Does this have an opener (corresponding to window.opener in JavaScript) |
| // associated with it? |
| virtual bool HasOpener() = 0; |
| |
| // Returns the opener if HasOpener() is true, or nullptr otherwise. |
| virtual RenderFrameHost* GetOpener() = 0; |
| |
| // Returns true if this WebContents was opened by another WebContents, even |
| // if the opener was suppressed. In contrast to HasOpener/GetOpener, the |
| // "original opener chain" doesn't reflect window.opener which can be |
| // suppressed or updated. The "original opener" is the main frame of the |
| // actual opener of this frame. This traces the all the way back, so if the |
| // original opener was closed (deleted or severed due to COOP), but _it_ had |
| // an original opener, this will return the original opener's original opener, |
| // etc. |
| virtual bool HasLiveOriginalOpenerChain() = 0; |
| |
| // Returns the "original opener WebContents" if HasLiveOriginalOpenerChain() |
| // is true, or nullptr otherwise. See the comment for |
| // `HasLiveOriginalOpenerChain()` for more details. |
| virtual WebContents* GetFirstWebContentsInLiveOriginalOpenerChain() = 0; |
| |
| // Returns the WakeLockContext accociated with this WebContents. |
| virtual device::mojom::WakeLockContext* GetWakeLockContext() = 0; |
| |
| // |http_status_code| can be 0 e.g. for data: URLs. |
| // |bitmaps| will be empty on download failure. |
| // |sizes| are the sizes in pixels of the bitmaps before they were resized due |
| // to the max bitmap size passed to DownloadImage(). Each entry in the bitmaps |
| // vector corresponds to an entry in the sizes vector (both vector sizes are |
| // guaranteed to be equal). If a bitmap was resized, there should be a single |
| // returned bitmap. |
| using ImageDownloadCallback = |
| base::OnceCallback<void(int id, |
| int http_status_code, |
| const GURL& image_url, |
| const std::vector<SkBitmap>& bitmaps, |
| const std::vector<gfx::Size>& sizes)>; |
| |
| // Sends a request to download the given image |url| and returns the unique |
| // id of the download request. When the download is finished, |callback| will |
| // be called with the bitmaps received from the renderer. |
| // If |is_favicon| is true, the cookies are not sent and not accepted during |
| // download. |
| // If there are no bitmap results <= |max_bitmap_size|, the smallest bitmap |
| // is resized to |max_bitmap_size| and is the only result. |
| // A |max_bitmap_size| of 0 means unlimited. |
| // For vector images, |preferred_size| will serve as a viewport into which |
| // the image will be rendered. This would usually be the dimensions of the |
| // rectangle where the bitmap will be rendered. If |preferred_size| is empty, |
| // any existing intrinsic dimensions of the image will be used. If |
| // |max_bitmap_size| is non-zero it will also impose an upper bound on the |
| // longest edge of |preferred_size| (|preferred_size| will be scaled down). |
| // If |bypass_cache| is true, |url| is requested from the server even if it |
| // is present in the browser cache. |
| virtual int DownloadImage(const GURL& url, |
| bool is_favicon, |
| const gfx::Size& preferred_size, |
| uint32_t max_bitmap_size, |
| bool bypass_cache, |
| ImageDownloadCallback callback) = 0; |
| |
| // Same as DownloadImage(), but uses the ImageDownloader from the specified |
| // frame instead of the main frame. |
| virtual int DownloadImageInFrame( |
| const GlobalRenderFrameHostId& initiator_frame_routing_id, |
| const GURL& url, |
| bool is_favicon, |
| const gfx::Size& preferred_size, |
| uint32_t max_bitmap_size, |
| bool bypass_cache, |
| ImageDownloadCallback callback) = 0; |
| |
| // Finds text on a page. |search_text| should not be empty. |skip_delay| |
| // indicates that the find request should be sent to the renderer immediately |
| // instead of waiting for privacy/performance mitigations. |
| virtual void Find(int request_id, |
| const std::u16string& search_text, |
| blink::mojom::FindOptionsPtr options, |
| bool skip_delay = false) = 0; |
| |
| // Notifies the renderer that the user has closed the FindInPage window |
| // (and what action to take regarding the selection). |
| virtual void StopFinding(StopFindAction action) = 0; |
| |
| // Returns true if audio has been audible from the WebContents since the last |
| // navigation. |
| virtual bool WasEverAudible() = 0; |
| |
| // Returns whether the renderer is in fullscreen mode. |
| virtual bool IsFullscreen() = 0; |
| |
| // Returns a copy of the current WebPreferences associated with this |
| // WebContents. If it does not exist, this will create one and send the newly |
| // computed value to all renderers. |
| // Note that this will not trigger a recomputation of WebPreferences if it |
| // already exists - this will return the last computed/set value of |
| // WebPreferences. If we want to guarantee that the value reflects the current |
| // state of the WebContents, NotifyPreferencesChanged() should be called |
| // before calling this. |
| virtual const blink::web_pref::WebPreferences& |
| GetOrCreateWebPreferences() = 0; |
| |
| // Notify this WebContents that the preferences have changed, so it needs to |
| // recompute the current WebPreferences based on the current state of the |
| // WebContents, etc. This will send an IPC to all the renderer processes |
| // associated with this WebContents. |
| // Note that this will do this by creating a new WebPreferences with default |
| // values, then recomputing some of the attributes based on current states. |
| // This means if there's any value previously set through SetWebPreferences |
| // which does not have special recomputation logic in either |
| // WebContentsImpl::ComputeWebPreferences or |
| // ContentBrowserClient::OverrideWebkitPrefs, it will return back to its |
| // default value whenever this function is called. |
| virtual void NotifyPreferencesChanged() = 0; |
| |
| // Sets the WebPreferences to |prefs|. This will send an IPC to all the |
| // renderer processes associated with this WebContents. |
| // Note that this is different from NotifyPreferencesChanged, which recomputes |
| // the WebPreferences based on the current state of things. Instead, we're |
| // setting this to a specific value. This also means that if we trigger a |
| // recomputation of WebPreferences after this, the WebPreferences value will |
| // be overridden. if there's any value previously set through |
| // SetWebPreferences which does not have special recomputation logic in either |
| // WebContentsImpl::ComputeWebPreferences or |
| // ContentBrowserClient::OverrideWebkitPrefs, it will return back to its |
| // default value, which might be different from the value we set it to here. |
| // If you want to use this function outside of tests, consider adding |
| // recomputation logic in either of those functions. |
| // TODO(rakina): Try to make values set through this function stick even after |
| // recomputations. |
| virtual void SetWebPreferences( |
| const blink::web_pref::WebPreferences& prefs) = 0; |
| |
| // Passes current web preferences to all renderer in this WebContents after |
| // possibly recomputing them as follows: all "fast" preferences (those not |
| // requiring slow platform/device polling) are recomputed unconditionally; the |
| // remaining "slow" ones are recomputed only if they have not been computed |
| // before. |
| // |
| // This method must be called if any state that affects web preferences has |
| // changed so that it can be recomputed and sent to the renderer. |
| virtual void OnWebPreferencesChanged() = 0; |
| |
| // Requests the renderer to exit fullscreen. |
| // |will_cause_resize| indicates whether the fullscreen change causes a |
| // view resize. e.g. This will be false when going from tab fullscreen to |
| // browser fullscreen. |
| virtual void ExitFullscreen(bool will_cause_resize) = 0; |
| |
| // The WebContents is trying to take some action that would cause user |
| // confusion if taken while in fullscreen. If this WebContents or any outer |
| // WebContents is in fullscreen, drop it. |
| // |
| // Returns a ScopedClosureRunner, and for the lifetime of that closure, this |
| // (and other related) WebContentses will not enter fullscreen. If the action |
| // should cause a one-time dropping of fullscreen (e.g. a UI element not |
| // attached to the WebContents), invoke RunAndReset() on the returned |
| // base::ScopedClosureRunner to release the fullscreen block immediately. |
| // Otherwise, if the action should cause fullscreen to be prohibited for a |
| // span of time (e.g. a UI element attached to the WebContents), keep the |
| // closure alive for that duration. |
| // |
| // If |display_id| is valid, only WebContentses on that specific screen will |
| // exit fullscreen; the scoped prohibition will still apply to all displays. |
| // This supports sites using cross-screen window placement capabilities to |
| // retain fullscreen and open or place a window on another screen. |
| [[nodiscard]] virtual base::ScopedClosureRunner ForSecurityDropFullscreen( |
| int64_t display_id = display::kInvalidDisplayId) = 0; |
| |
| // Unblocks requests from renderer for a newly created window. This is |
| // used in showCreatedWindow() or sometimes later in cases where |
| // delegate->ShouldResumeRequestsForCreatedWindow() indicated the requests |
| // should not yet be resumed. Then the client is responsible for calling this |
| // as soon as they are ready. |
| virtual void ResumeLoadingCreatedWebContents() = 0; |
| |
| // Sets whether the WebContents is for overlaying content on a page. |
| virtual void SetIsOverlayContent(bool is_overlay_content) = 0; |
| |
| virtual int GetCurrentlyPlayingVideoCount() = 0; |
| |
| virtual std::optional<gfx::Size> GetFullscreenVideoSize() = 0; |
| |
| // Tells the renderer to clear the focused element (if any). |
| virtual void ClearFocusedElement() = 0; |
| |
| // Returns true if the current focused element is editable. |
| virtual bool IsFocusedElementEditable() = 0; |
| |
| // Returns true if a context menu is showing on the page. |
| virtual bool IsShowingContextMenu() = 0; |
| |
| // Tells the WebContents whether the context menu is showing. |
| virtual void SetShowingContextMenu(bool showing) = 0; |
| |
| #if BUILDFLAG(IS_ANDROID) |
| CONTENT_EXPORT static WebContents* FromJavaWebContents( |
| const base::android::JavaRef<jobject>& jweb_contents_android); |
| virtual base::android::ScopedJavaLocalRef<jobject> GetJavaWebContents() = 0; |
| |
| // Returns the value from CreateParams::java_creator_location. |
| virtual base::android::ScopedJavaLocalRef<jthrowable> |
| GetJavaCreatorLocation() = 0; |
| |
| // Selects and zooms to the find result nearest to the point (x,y) defined in |
| // find-in-page coordinates. |
| virtual void ActivateNearestFindResult(float x, float y) = 0; |
| |
| // Requests the rects of the current find matches from the renderer |
| // process. |current_version| is the version of find rects that the caller |
| // already knows about. This version will be compared to the current find |
| // rects version in the renderer process (which is updated whenever the rects |
| // change), to see which new rect data will need to be sent back. |
| // |
| // TODO(paulmeyer): This process will change slightly once multi-process |
| // find-in-page is implemented. This comment should be updated at that time. |
| virtual void RequestFindMatchRects(int current_version) = 0; |
| |
| // Returns an InterfaceProvider for Java-implemented interfaces that are |
| // scoped to this WebContents. This provides access to interfaces implemented |
| // in Java in the browser process to C++ code in the browser process. |
| virtual service_manager::InterfaceProvider* GetJavaInterfaces() = 0; |
| #endif // BUILDFLAG(IS_ANDROID) |
| |
| // Returns true if the WebContents has completed its first meaningful paint |
| // since the last navigation. |
| virtual bool CompletedFirstVisuallyNonEmptyPaint() = 0; |
| |
| // TODO(crbug.com/41379215): This is a simple mitigation to validate |
| // that an action that requires a user gesture actually has one in the |
| // trustworthy browser process, rather than relying on the untrustworthy |
| // renderer. This should be eventually merged into and accounted for in the |
| // user activation work: crbug.com/848778 |
| virtual bool HasRecentInteraction() = 0; |
| |
| // Causes the WebContents to ignore input events for at least as long as the |
| // token exists. In the event of multiple calls, input events will be ignored |
| // until all tokens have been destroyed. |
| // If WebInputEventAuditCallback is given, it can audits WebInputEvent based |
| // input events and ignore only events that the callback returns false for the |
| // event. Other kind of events, such as focus event or ui::Events will be |
| // always ignored without asking the callback. The given callback will be |
| // invoked only while the returned ScopedIgnoreInputEvents alives. |
| using WebInputEventAuditCallback = |
| base::RepeatingCallback<bool(const blink::WebInputEvent&)>; |
| [[nodiscard]] virtual ScopedIgnoreInputEvents IgnoreInputEvents( |
| std::optional<WebInputEventAuditCallback> audit_callback) = 0; |
| |
| // Returns the group id for all audio streams that correspond to a single |
| // WebContents. This can be used to determine if a AudioOutputStream was |
| // created from a renderer that originated from this WebContents. |
| virtual base::UnguessableToken GetAudioGroupId() = 0; |
| |
| // Returns the raw list of favicon candidates as reported to observers via |
| // WebContentsObserver::DidUpdateFaviconURL() since the last navigation start. |
| // Consider using FaviconDriver in components/favicon if possible for more |
| // reliable favicon-related state. |
| virtual const std::vector<blink::mojom::FaviconURLPtr>& GetFaviconURLs() = 0; |
| |
| // Intended for desktop PWAs with manifest entry of window-controls-overlay, |
| // This sends the available title bar area bounds to the renderer process. |
| virtual void UpdateWindowControlsOverlay(const gfx::Rect& bounding_rect) = 0; |
| |
| // Returns the Window Control Overlay rectangle. Only applies to an |
| // outermost main frame's widget. Other widgets always returns an empty rect. |
| virtual gfx::Rect GetWindowsControlsOverlayRect() const = 0; |
| |
| // Whether the WebContents has an active player that is effectively |
| // fullscreen. That means that the video is either fullscreen or it is the |
| // content of a fullscreen page (in other words, a fullscreen video with |
| // custom controls). |
| virtual bool HasActiveEffectivelyFullscreenVideo() = 0; |
| |
| // Serialise this object into a trace. |
| virtual void WriteIntoTrace(perfetto::TracedValue context) = 0; |
| |
| // Returns the value from CreateParams::creator_location. |
| virtual const base::Location& GetCreatorLocation() = 0; |
| |
| // Returns the parameters associated with PictureInPicture WebContents |
| virtual const std::optional<blink::mojom::PictureInPictureWindowOptions>& |
| GetPictureInPictureOptions() const = 0; |
| |
| // Hide or show the browser controls for the given WebContents, based on |
| // allowed states, desired state and whether the transition should be animated |
| // or not. |
| virtual void UpdateBrowserControlsState(cc::BrowserControlsState constraints, |
| cc::BrowserControlsState current, |
| bool animate) = 0; |
| |
| // Transmits data to V8CrowdsourcedCompileHintsConsumer in the renderer. The |
| // data is a model describing which JavaScript functions on the page should be |
| // eagerly parsed & compiled by the JS engine. |
| virtual void SetV8CompileHints(base::ReadOnlySharedMemoryRegion data) = 0; |
| |
| // Sets the last time a tab switch made this WebContents visible. |
| // `start_time` is the timestamp of the input event that triggered the tab |
| // switch. `destination_is_loaded` is true when |
| // ResourceCoordinatorTabHelper::IsLoaded() is true for the new tab contents. |
| // These will be used to record metrics with the latency between the input |
| // event and the time when the WebContents is painted. |
| virtual void SetTabSwitchStartTime(base::TimeTicks start_time, |
| bool destination_is_loaded) = 0; |
| |
| // Checks if the WebContents host pages in preview mode. |
| virtual bool IsInPreviewMode() const = 0; |
| |
| // Called before ActivatePreviewPage() to prepare the activation. This will |
| // end the preview mode and IsInPreviewMode() will start returning false after |
| // the call. This allows embedders to run preparation steps on the activating |
| // WebContents (e.g. attach TabHelpers) before activating the page shown by |
| // the WebContents through ActivatePreviewPage(). |
| virtual void WillActivatePreviewPage() = 0; |
| |
| // Activates the primary page that is shown in preview mode. This will relax |
| // capability restriction in the browser process, and notify the renderer to |
| // process the prerendering activation algorithm. |
| // This all processes happens asynchronously, and |
| // `WebContentsDelegate::DidActivatePreviewedPage` will be called once it's |
| // done. |
| virtual void ActivatePreviewPage() = 0; |
| |
| // Starts an embedder triggered (browser-initiated) prerendering page and |
| // returns the unique_ptr<PrerenderHandle>, which cancels prerendering on its |
| // destruction. If the prerendering failed to start (e.g. if prerendering is |
| // disabled, failure happened or because this URL is already being |
| // prerendered), this function returns a nullptr. |
| // PreloadingAttempt helps us to log various metrics associated with |
| // particular prerendering attempt. `url_match_predicate` allows embedders to |
| // define their own predicates for matching same-origin URLs during |
| // prerendering activation; it would be useful if embedders want Prerender2 to |
| // ignore some parameter mismatches. Note that if the mismatched prerender URL |
| // will be activated due to the predicate returning true, the last committed |
| // URL in the prerendered RenderFrameHost will be activated. |
| // `prerender_navigation_handle_callback` allows embedders to attach their own |
| // NavigationHandleUserData when prerender starts, and the user data can be |
| // used for identifying the types of embedder for metrics logging. |
| virtual std::unique_ptr<PrerenderHandle> StartPrerendering( |
| const GURL& prerendering_url, |
| PreloadingTriggerType trigger_type, |
| const std::string& embedder_histogram_suffix, |
| ui::PageTransition page_transition, |
| PreloadingHoldbackStatus holdback_status_override, |
| PreloadingAttempt* preloading_attempt, |
| base::RepeatingCallback<bool(const GURL&)> url_match_predicate, |
| base::RepeatingCallback<void(NavigationHandle&)> |
| prerender_navigation_handle_callback) = 0; |
| |
| // May be called when the embedder believes that it is likely that the user |
| // will perform a back navigation due to the trigger indicated by `predictor` |
| // (e.g. they're hovering over a back button). `disposition` indicates where |
| // the navigation is predicted to happen (which could differ from where the |
| // navigation actually happens). |
| virtual void BackNavigationLikely(PreloadingPredictor predictor, |
| WindowOpenDisposition disposition) = 0; |
| |
| // Returns a scope object that needs to be owned by caller in order to |
| // disallow custom cursors. Custom cursors whose width or height are larger |
| // than `max_dimension_dips` are diallowed in this web contents for as long as |
| // any of the returned `ScopedClosureRunner` objects is alive. |
| [[nodiscard]] virtual base::ScopedClosureRunner |
| CreateDisallowCustomCursorScope(int max_dimension_dips = 0) = 0; |
| |
| // Enables overscroll history navigation. |
| virtual void SetOverscrollNavigationEnabled(bool enabled) = 0; |
| |
| // Tag `WebContents` with its owner. Used purely for debugging purposes so it |
| // does not need to be exhaustive or perfectly correct. |
| // TODO(crbug.com/40062641): Remove after bug is fixed. |
| virtual void SetOwnerLocationForDebug( |
| std::optional<base::Location> owner_location) = 0; |
| |
| // Sends the attribution support state to all renderer processes for the |
| // current page. |
| virtual void UpdateAttributionSupportRenderer() = 0; |
| |
| // Return all currently streaming devices of `type` via `callback`. |
| virtual void GetMediaCaptureRawDeviceIdsOpened( |
| blink::mojom::MediaStreamType type, |
| base::OnceCallback<void(std::vector<std::string>)> callback) = 0; |
| |
| // Returns an animation manager that displays a preview of the history page |
| // during a session history navigation gesture. Only non-null if |
| // `features::kBackForwardTransitions` is enabled for the supported platform. |
| virtual BackForwardTransitionAnimationManager* |
| GetBackForwardTransitionAnimationManager() = 0; |
| |
| private: |
| // This interface should only be implemented inside content. |
| friend class WebContentsImpl; |
| WebContents() = default; |
| }; |
| |
| } // namespace content |
| |
| #endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ |