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.
5 #ifndef CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_
6 #define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_
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"
36 class JavaScriptDialogManager;
39 class SessionStorageNamespace;
41 class WebContentsImpl;
42 struct ColorSuggestion;
43 struct ContextMenuParams;
45 struct FileChooserParams;
46 struct NativeWebKeyboardEvent;
58 class WebGestureEvent;
60 struct WebWindowFeatures;
67 // Objects implement this interface to get notified about changes in the
68 // WebContents and to provide necessary functionality.
69 class CONTENT_EXPORT WebContentsDelegate {
71 WebContentsDelegate();
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.
77 // A NULL source indicates the current tab (callers should probably use
78 // OpenURL() for these cases which does it for you).
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);
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) {}
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
98 virtual void AddNewContents(WebContents* source,
99 WebContents* new_contents,
100 WindowOpenDisposition disposition,
101 const gfx::Rect& initial_pos,
103 bool* was_blocked) {}
105 // Selects the specified contents, bringing its container to the front.
106 virtual void ActivateContents(WebContents* contents) {}
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) {}
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) {}
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
123 virtual void LoadProgressChanged(WebContents* source,
126 // Request the delegate to close this web contents, and do whatever cleanup
128 virtual void CloseContents(WebContents* source) {}
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) {}
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) {}
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;
142 // Notification that the target URL has changed.
143 virtual void UpdateTargetURL(WebContents* source,
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,
154 // Request the delegate to change the zoom level of the current tab.
155 virtual void ContentsZoomChange(bool zoom_in) {}
157 // Called to determine if the WebContents can be overscrolled with touch/wheel
159 virtual bool CanOverscrollContent() const;
161 // Callback that allows vertical overscroll activies to be communicated to the
163 virtual void OverscrollUpdate(int delta_y) {}
165 // Return the rect where to display the resize corner, if any, otherwise
167 virtual gfx::Rect GetRootWindowResizerRect() const;
169 // Invoked prior to showing before unload handler confirmation dialog.
170 virtual void WillRunBeforeUnloadConfirm() {}
172 // Returns true if javascript dialogs and unload alerts are suppressed.
174 virtual bool ShouldSuppressDialogs();
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);
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,
186 const base::string16& message,
188 const base::string16& source_id);
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,
197 bool* proceed_to_fire_unload);
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);
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
208 virtual void SetFocusToLocationBar(bool select_all) {}
210 // Returns whether the page should be focused when transitioning from crashed
211 // to live. Default is true.
212 virtual bool ShouldFocusPageAfterCrash();
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,
220 // Invoked when the page loses mouse capture.
221 virtual void LostCapture() {}
223 // Notification that |contents| has gained focus.
224 virtual void WebContentsFocused(WebContents* contents) {}
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,
230 const std::string& request_method,
231 const base::Callback<void(bool)>& callback);
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;
238 // Returns true if the context menu operation was handled by the delegate.
239 virtual bool HandleContextMenu(const content::ContextMenuParams& params);
241 // Opens source view for given WebContents that is navigated to the given
243 virtual void ViewSourceForTab(WebContents* source, const GURL& page_url);
245 // Opens source view for the given subframe.
246 virtual void ViewSourceForFrame(WebContents* source,
248 const PageState& page_state);
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);
258 // Allows delegates to handle unhandled keyboard messages coming back from
260 virtual void HandleKeyboardEvent(WebContents* source,
261 const NativeWebKeyboardEvent& event) {}
263 virtual void HandleMouseDown() {}
264 virtual void HandleMouseUp() {}
266 // Handles activation resulting from a pointer event (e.g. when mouse is
267 // pressed, or a touch-gesture begins).
268 virtual void HandlePointerActivate() {}
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(
277 const blink::WebGestureEvent& event);
279 virtual void HandleGestureBegin() {}
280 virtual void HandleGestureEnd() {}
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);
289 // Render view drag n drop ended.
290 virtual void DragEnded() {}
292 // Shows the repost form confirmation dialog box.
293 virtual void ShowRepostFormWarningDialog(WebContents* source) {}
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);
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
304 virtual bool ShouldCreateWebContents(
305 WebContents* web_contents,
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);
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) {}
321 // Notification that the tab is hung.
322 virtual void RendererUnresponsive(WebContents* source) {}
324 // Notification that the tab is no longer hung.
325 virtual void RendererResponsive(WebContents* source) {}
327 // Notification that a worker associated with this tab has crashed.
328 virtual void WorkerCrashed(WebContents* source) {}
330 // Invoked when a main fram navigation occurs.
331 virtual void DidNavigateMainFramePostCommit(WebContents* source) {}
333 // Invoked when navigating to a pending entry. When invoked the
334 // NavigationController has configured its pending entry, but it has not yet
336 virtual void DidNavigateToPendingEntry(WebContents* source) {}
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();
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,
349 const std::vector<ColorSuggestion>& suggestions);
351 // Called when a file selection is to be done.
352 virtual void RunFileChooser(WebContents* web_contents,
353 const FileChooserParams& params) {}
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
358 virtual void EnumerateDirectory(WebContents* web_contents,
360 const base::FilePath& path) {}
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;
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;
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
377 virtual void RegisterProtocolHandler(WebContents* web_contents,
378 const std::string& protocol,
380 const base::string16& title,
381 bool user_gesture) {}
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,
388 int number_of_matches,
389 const gfx::Rect& selection_rect,
390 int active_match_ordinal,
391 bool final_update) {}
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,
398 const std::vector<gfx::RectF>& rects,
399 const gfx::RectF& active_rect) {}
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) {}
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) {}
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) {}
416 // Requests to lock the mouse. Once the request is approved or rejected,
417 // GotResponseToLockMouseRequest() will be called on the requesting tab
419 virtual void RequestToLockMouse(WebContents* web_contents,
421 bool last_unlocked_by_target) {}
423 // Notification that the page has lost the mouse lock.
424 virtual void LostMouseLock() {}
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);
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,
442 const base::FilePath& plugin_path,
443 const base::Callback<void(bool)>& callback);
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
450 virtual gfx::Size GetSizeForNewRenderView(WebContents* web_contents) const;
452 // Notification that validation of a form displayed by the |web_contents|
453 // has failed. There can only be one message per |web_contents| at a time.
454 virtual void ShowValidationMessage(WebContents* web_contents,
455 const gfx::Rect& anchor_in_root_view,
456 const base::string16& main_text,
457 const base::string16& sub_text) {}
459 // Notification that the delegate should hide any showing form validation
461 virtual void HideValidationMessage(WebContents* web_contents) {}
463 // Notification that the form element that triggered the validation failure
465 virtual void MoveValidationMessage(WebContents* web_contents,
466 const gfx::Rect& anchor_in_root_view) {}
468 // Returns true if the WebContents is never visible.
469 virtual bool IsNeverVisible(WebContents* web_contents);
472 virtual ~WebContentsDelegate();
475 friend class WebContentsImpl;
477 // Called when |this| becomes the WebContentsDelegate for |source|.
478 void Attach(WebContents* source);
480 // Called when |this| is no longer the WebContentsDelegate for |source|.
481 void Detach(WebContents* source);
483 // The WebContents that this is currently a delegate for.
484 std::set<WebContents*> attached_contents_;
487 } // namespace content
489 #endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_