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