web_contents_delegate.h revision f2477e01787aa58f445919b809d89e252beef54f
1// Copyright (c) 2012 The Chromium Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5#ifndef CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_ 6#define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_ 7 8#include <set> 9#include <string> 10 11#include "base/basictypes.h" 12#include "base/callback.h" 13#include "base/strings/string16.h" 14#include "content/common/content_export.h" 15#include "content/public/browser/navigation_type.h" 16#include "content/public/common/media_stream_request.h" 17#include "content/public/common/page_transition_types.h" 18#include "content/public/common/window_container_type.h" 19#include "third_party/WebKit/public/web/WebDragOperation.h" 20#include "third_party/skia/include/core/SkColor.h" 21#include "ui/base/window_open_disposition.h" 22#include "ui/gfx/native_widget_types.h" 23#include "ui/gfx/rect_f.h" 24 25class GURL; 26 27namespace base { 28class FilePath; 29class ListValue; 30} 31 32namespace content { 33class BrowserContext; 34class ColorChooser; 35class DownloadItem; 36class JavaScriptDialogManager; 37class PageState; 38class RenderViewHost; 39class SessionStorageNamespace; 40class WebContents; 41class WebContentsImpl; 42struct ContextMenuParams; 43struct DropData; 44struct FileChooserParams; 45struct NativeWebKeyboardEvent; 46struct Referrer; 47struct SSLStatus; 48} 49 50namespace gfx { 51class Point; 52class Rect; 53class Size; 54} 55 56namespace blink { 57class WebLayer; 58struct WebWindowFeatures; 59} 60 61namespace content { 62 63struct OpenURLParams; 64 65// Objects implement this interface to get notified about changes in the 66// WebContents and to provide necessary functionality. 67class CONTENT_EXPORT WebContentsDelegate { 68 public: 69 WebContentsDelegate(); 70 71 // Opens a new URL inside the passed in WebContents (if source is 0 open 72 // in the current front-most tab), unless |disposition| indicates the url 73 // should be opened in a new tab or window. 74 // 75 // A NULL source indicates the current tab (callers should probably use 76 // OpenURL() for these cases which does it for you). 77 78 // Returns the WebContents the URL is opened in, or NULL if the URL wasn't 79 // opened immediately. 80 virtual WebContents* OpenURLFromTab(WebContents* source, 81 const OpenURLParams& params); 82 83 // Called to inform the delegate that the WebContents's navigation state 84 // changed. The |changed_flags| indicates the parts of the navigation state 85 // that have been updated, and is any combination of the 86 // |WebContents::InvalidateTypes| bits. 87 virtual void NavigationStateChanged(const WebContents* source, 88 unsigned changed_flags) {} 89 90 // Adds the navigation request headers to |headers|. Use 91 // net::HttpUtil::AppendHeaderIfMissing to build the set of headers. 92 virtual void AddNavigationHeaders(const GURL& url, std::string* headers) {} 93 94 // Creates a new tab with the already-created WebContents 'new_contents'. 95 // The window for the added contents should be reparented correctly when this 96 // method returns. If |disposition| is NEW_POPUP, |initial_pos| should hold 97 // the initial position. If |was_blocked| is non-NULL, then |*was_blocked| 98 // will be set to true if the popup gets blocked, and left unchanged 99 // otherwise. 100 virtual void AddNewContents(WebContents* source, 101 WebContents* new_contents, 102 WindowOpenDisposition disposition, 103 const gfx::Rect& initial_pos, 104 bool user_gesture, 105 bool* was_blocked) {} 106 107 // Selects the specified contents, bringing its container to the front. 108 virtual void ActivateContents(WebContents* contents) {} 109 110 // Deactivates the specified contents by deactivating its container and 111 // potentialy moving it to the back of the Z order. 112 virtual void DeactivateContents(WebContents* contents) {} 113 114 // Notifies the delegate that this contents is starting or is done loading 115 // some resource. The delegate should use this notification to represent 116 // loading feedback. See WebContents::IsLoading() 117 virtual void LoadingStateChanged(WebContents* source) {} 118 119 // Notifies the delegate that the page has made some progress loading. 120 // |progress| is a value between 0.0 (nothing loaded) to 1.0 (page fully 121 // loaded). 122 virtual void LoadProgressChanged(WebContents* source, 123 double progress) {} 124 125 // Request the delegate to close this web contents, and do whatever cleanup 126 // it needs to do. 127 virtual void CloseContents(WebContents* source) {} 128 129 // Informs the delegate that the underlying RenderViewHost has been swapped 130 // out so it can perform any cleanup necessary. 131 virtual void SwappedOut(WebContents* source) {} 132 133 // Request the delegate to move this WebContents to the specified position 134 // in screen coordinates. 135 virtual void MoveContents(WebContents* source, const gfx::Rect& pos) {} 136 137 // Called to determine if the WebContents is contained in a popup window 138 // or a panel window. 139 virtual bool IsPopupOrPanel(const WebContents* source) const; 140 141 // Notification that the target URL has changed. 142 virtual void UpdateTargetURL(WebContents* source, 143 int32 page_id, 144 const GURL& url) {} 145 146 // Notification that there was a mouse event, along with the absolute 147 // coordinates of the mouse pointer and whether it was a normal motion event 148 // (otherwise, the pointer left the contents area). 149 virtual void ContentsMouseEvent(WebContents* source, 150 const gfx::Point& location, 151 bool motion) {} 152 153 // Request the delegate to change the zoom level of the current tab. 154 virtual void ContentsZoomChange(bool zoom_in) {} 155 156 // Called to determine if the WebContents can be overscrolled with touch/wheel 157 // gestures. 158 virtual bool CanOverscrollContent() const; 159 160 // Callback that allows vertical overscroll activies to be communicated to the 161 // delegate. 162 virtual void OverscrollUpdate(int delta_y) {} 163 164 // Check whether this contents is permitted to load data URLs in WebUI mode. 165 // This is normally disallowed for security. 166 virtual bool CanLoadDataURLsInWebUI() const; 167 168 // Return the rect where to display the resize corner, if any, otherwise 169 // an empty rect. 170 virtual gfx::Rect GetRootWindowResizerRect() const; 171 172 // Invoked prior to showing before unload handler confirmation dialog. 173 virtual void WillRunBeforeUnloadConfirm() {} 174 175 // Returns true if javascript dialogs and unload alerts are suppressed. 176 // Default is false. 177 virtual bool ShouldSuppressDialogs(); 178 179 // Add a message to the console. Returning true indicates that the delegate 180 // handled the message. If false is returned the default logging mechanism 181 // will be used for the message. 182 virtual bool AddMessageToConsole(WebContents* source, 183 int32 level, 184 const string16& message, 185 int32 line_no, 186 const string16& source_id); 187 188 // Tells us that we've finished firing this tab's beforeunload event. 189 // The proceed bool tells us whether the user chose to proceed closing the 190 // tab. Returns true if the tab can continue on firing its unload event. 191 // If we're closing the entire browser, then we'll want to delay firing 192 // unload events until all the beforeunload events have fired. 193 virtual void BeforeUnloadFired(WebContents* tab, 194 bool proceed, 195 bool* proceed_to_fire_unload); 196 197 // Returns true if the location bar should be focused by default rather than 198 // the page contents. NOTE: this is only used if WebContents can't determine 199 // for itself whether the location bar should be focused by default. For a 200 // complete check, you should use WebContents::FocusLocationBarByDefault(). 201 virtual bool ShouldFocusLocationBarByDefault(WebContents* source); 202 203 // Sets focus to the location bar or some other place that is appropriate. 204 // This is called when the tab wants to encourage user input, like for the 205 // new tab page. 206 virtual void SetFocusToLocationBar(bool select_all) {} 207 208 // Returns whether the page should be focused when transitioning from crashed 209 // to live. Default is true. 210 virtual bool ShouldFocusPageAfterCrash(); 211 212 // Called when a popup select is about to be displayed. The delegate can use 213 // this to disable inactive rendering for the frame in the window the select 214 // is opened within if necessary. 215 virtual void RenderWidgetShowing() {} 216 217 // This is called when WebKit tells us that it is done tabbing through 218 // controls on the page. Provides a way for WebContentsDelegates to handle 219 // this. Returns true if the delegate successfully handled it. 220 virtual bool TakeFocus(WebContents* source, 221 bool reverse); 222 223 // Invoked when the page loses mouse capture. 224 virtual void LostCapture() {} 225 226 // Notification that |contents| has gained focus. 227 virtual void WebContentsFocused(WebContents* contents) {} 228 229 // Asks the delegate if the given tab can download. 230 // Invoking the |callback| synchronously is OK. 231 virtual void CanDownload(RenderViewHost* render_view_host, 232 int request_id, 233 const std::string& request_method, 234 const base::Callback<void(bool)>& callback); 235 236 // Return much extra vertical space should be allotted to the 237 // render view widget during various animations (e.g. infobar closing). 238 // This is used to make painting look smoother. 239 virtual int GetExtraRenderViewHeight() const; 240 241 // Returns true if the context menu operation was handled by the delegate. 242 virtual bool HandleContextMenu(const content::ContextMenuParams& params); 243 244 // Opens source view for given WebContents that is navigated to the given 245 // page url. 246 virtual void ViewSourceForTab(WebContents* source, const GURL& page_url); 247 248 // Opens source view for the given subframe. 249 virtual void ViewSourceForFrame(WebContents* source, 250 const GURL& url, 251 const PageState& page_state); 252 253 // Allows delegates to handle keyboard events before sending to the renderer. 254 // Returns true if the |event| was handled. Otherwise, if the |event| would be 255 // handled in HandleKeyboardEvent() method as a normal keyboard shortcut, 256 // |*is_keyboard_shortcut| should be set to true. 257 virtual bool PreHandleKeyboardEvent(WebContents* source, 258 const NativeWebKeyboardEvent& event, 259 bool* is_keyboard_shortcut); 260 261 // Allows delegates to handle unhandled keyboard messages coming back from 262 // the renderer. 263 virtual void HandleKeyboardEvent(WebContents* source, 264 const NativeWebKeyboardEvent& event) {} 265 266 virtual void HandleMouseDown() {} 267 virtual void HandleMouseUp() {} 268 269 // Handles activation resulting from a pointer event (e.g. when mouse is 270 // pressed, or a touch-gesture begins). 271 virtual void HandlePointerActivate() {} 272 273 virtual void HandleGestureBegin() {} 274 virtual void HandleGestureEnd() {} 275 276 // Called when an external drag event enters the web contents window. Return 277 // true to allow dragging and dropping on the web contents window or false to 278 // cancel the operation. This method is used by Chromium Embedded Framework. 279 virtual bool CanDragEnter(WebContents* source, 280 const DropData& data, 281 blink::WebDragOperationsMask operations_allowed); 282 283 // Render view drag n drop ended. 284 virtual void DragEnded() {} 285 286 // Shows the repost form confirmation dialog box. 287 virtual void ShowRepostFormWarningDialog(WebContents* source) {} 288 289 // Allows delegate to override navigation to the history entries. 290 // Returns true to allow WebContents to continue with the default processing. 291 virtual bool OnGoToEntryOffset(int offset); 292 293 // Allows delegate to control whether a WebContents will be created. Returns 294 // true to allow the creation. Default is to allow it. In cases where the 295 // delegate handles the creation/navigation itself, it will use |target_url|. 296 virtual bool ShouldCreateWebContents( 297 WebContents* web_contents, 298 int route_id, 299 WindowContainerType window_container_type, 300 const string16& frame_name, 301 const GURL& target_url, 302 const std::string& partition_id, 303 SessionStorageNamespace* session_storage_namespace); 304 305 // Notifies the delegate about the creation of a new WebContents. This 306 // typically happens when popups are created. 307 virtual void WebContentsCreated(WebContents* source_contents, 308 int64 source_frame_id, 309 const string16& frame_name, 310 const GURL& target_url, 311 WebContents* new_contents) {} 312 313 // Notification that the tab is hung. 314 virtual void RendererUnresponsive(WebContents* source) {} 315 316 // Notification that the tab is no longer hung. 317 virtual void RendererResponsive(WebContents* source) {} 318 319 // Notification that a worker associated with this tab has crashed. 320 virtual void WorkerCrashed(WebContents* source) {} 321 322 // Invoked when a main fram navigation occurs. 323 virtual void DidNavigateMainFramePostCommit(WebContents* source) {} 324 325 // Invoked when navigating to a pending entry. When invoked the 326 // NavigationController has configured its pending entry, but it has not yet 327 // been committed. 328 virtual void DidNavigateToPendingEntry(WebContents* source) {} 329 330 // Returns a pointer to a service to manage JavaScript dialogs. May return 331 // NULL in which case dialogs aren't shown. 332 virtual JavaScriptDialogManager* GetJavaScriptDialogManager(); 333 334 // Called when color chooser should open. Returns the opened color chooser. 335 // Ownership of the returned pointer is transferred to the caller. 336 virtual ColorChooser* OpenColorChooser(WebContents* web_contents, 337 SkColor color); 338 339 // Called when a file selection is to be done. 340 virtual void RunFileChooser(WebContents* web_contents, 341 const FileChooserParams& params) {} 342 343 // Request to enumerate a directory. This is equivalent to running the file 344 // chooser in directory-enumeration mode and having the user select the given 345 // directory. 346 virtual void EnumerateDirectory(WebContents* web_contents, 347 int request_id, 348 const base::FilePath& path) {} 349 350 // Returns true if the delegate will embed a WebContents-owned fullscreen 351 // render widget. In this case, the delegate may access the widget by calling 352 // WebContents::GetFullscreenRenderWidgetHostView(). If false is returned, 353 // WebContents will be responsible for showing the fullscreen widget. 354 virtual bool EmbedsFullscreenWidget() const; 355 356 // Called when the renderer puts a tab into or out of fullscreen mode. 357 virtual void ToggleFullscreenModeForTab(WebContents* web_contents, 358 bool enter_fullscreen) {} 359 virtual bool IsFullscreenForTabOrPending( 360 const WebContents* web_contents) const; 361 362 // Called when a Javascript out of memory notification is received. 363 virtual void JSOutOfMemory(WebContents* web_contents) {} 364 365 // Register a new handler for URL requests with the given scheme. 366 // |user_gesture| is true if the registration is made in the context of a user 367 // gesture. 368 virtual void RegisterProtocolHandler(WebContents* web_contents, 369 const std::string& protocol, 370 const GURL& url, 371 const string16& title, 372 bool user_gesture) {} 373 374 // Result of string search in the page. This includes the number of matches 375 // found and the selection rect (in screen coordinates) for the string found. 376 // If |final_update| is false, it indicates that more results follow. 377 virtual void FindReply(WebContents* web_contents, 378 int request_id, 379 int number_of_matches, 380 const gfx::Rect& selection_rect, 381 int active_match_ordinal, 382 bool final_update) {} 383 384#if defined(OS_ANDROID) 385 // Provides the rects of the current find-in-page matches. 386 // Sent as a reply to RequestFindMatchRects. 387 virtual void FindMatchRectsReply(WebContents* web_contents, 388 int version, 389 const std::vector<gfx::RectF>& rects, 390 const gfx::RectF& active_rect) {} 391 392 // Request permission to access protected media identifier. The callback will 393 // tell whether it's allowed. 394 virtual void RequestProtectedMediaIdentifierPermission( 395 const WebContents* web_contents, 396 const GURL& frame_url, 397 const base::Callback<void(bool)>& callback) {} 398#endif 399 400 // Invoked when the preferred size of the contents has been changed. 401 virtual void UpdatePreferredSize(WebContents* web_contents, 402 const gfx::Size& pref_size) {} 403 404 // Invoked when the contents auto-resized and the container should match it. 405 virtual void ResizeDueToAutoResize(WebContents* web_contents, 406 const gfx::Size& new_size) {} 407 408 // Notification message from HTML UI. 409 virtual void WebUISend(WebContents* web_contents, 410 const GURL& source_url, 411 const std::string& name, 412 const base::ListValue& args) {} 413 414 // Requests to lock the mouse. Once the request is approved or rejected, 415 // GotResponseToLockMouseRequest() will be called on the requesting tab 416 // contents. 417 virtual void RequestToLockMouse(WebContents* web_contents, 418 bool user_gesture, 419 bool last_unlocked_by_target) {} 420 421 // Notification that the page has lost the mouse lock. 422 virtual void LostMouseLock() {} 423 424 // Asks permission to use the camera and/or microphone. If permission is 425 // granted, a call should be made to |callback| with the devices. If the 426 // request is denied, a call should be made to |callback| with an empty list 427 // of devices. |request| has the details of the request (e.g. which of audio 428 // and/or video devices are requested, and lists of available devices). 429 virtual void RequestMediaAccessPermission( 430 WebContents* web_contents, 431 const MediaStreamRequest& request, 432 const MediaResponseCallback& callback); 433 434 // Requests permission to access the PPAPI broker. The delegate should return 435 // true and call the passed in |callback| with the result, or return false 436 // to indicate that it does not support asking for permission. 437 virtual bool RequestPpapiBrokerPermission( 438 WebContents* web_contents, 439 const GURL& url, 440 const base::FilePath& plugin_path, 441 const base::Callback<void(bool)>& callback); 442 443 // Returns the size for the new render view created for the pending entry in 444 // |web_contents|; if there's no size, returns an empty size. 445 // This is optional for implementations of WebContentsDelegate; if the 446 // delegate doesn't provide a size, the current WebContentsView's size will be 447 // used. 448 virtual gfx::Size GetSizeForNewRenderView( 449 const WebContents* web_contents) const; 450 451 protected: 452 virtual ~WebContentsDelegate(); 453 454 private: 455 friend class WebContentsImpl; 456 457 // Called when |this| becomes the WebContentsDelegate for |source|. 458 void Attach(WebContents* source); 459 460 // Called when |this| is no longer the WebContentsDelegate for |source|. 461 void Detach(WebContents* source); 462 463 // The WebContents that this is currently a delegate for. 464 std::set<WebContents*> attached_contents_; 465}; 466 467} // namespace content 468 469#endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_ 470