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