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