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 virtual void LoadingStateChanged(WebContents* source) {}
117 // Notifies the delegate that the page has made some progress loading.
118 // |progress| is a value between 0.0 (nothing loaded) to 1.0 (page fully
120 virtual void LoadProgressChanged(WebContents* source,
123 // Request the delegate to close this web contents, and do whatever cleanup
125 virtual void CloseContents(WebContents* source) {}
127 // Informs the delegate that the underlying RenderViewHost has been swapped
128 // out so it can perform any cleanup necessary.
129 virtual void SwappedOut(WebContents* source) {}
131 // Request the delegate to move this WebContents to the specified position
132 // in screen coordinates.
133 virtual void MoveContents(WebContents* source, const gfx::Rect& pos) {}
135 // Called to determine if the WebContents is contained in a popup window
136 // or a panel window.
137 virtual bool IsPopupOrPanel(const WebContents* source) const;
139 // Notification that the target URL has changed.
140 virtual void UpdateTargetURL(WebContents* source,
144 // Notification that there was a mouse event, along with the absolute
145 // coordinates of the mouse pointer and whether it was a normal motion event
146 // (otherwise, the pointer left the contents area).
147 virtual void ContentsMouseEvent(WebContents* source,
148 const gfx::Point& location,
151 // Request the delegate to change the zoom level of the current tab.
152 virtual void ContentsZoomChange(bool zoom_in) {}
154 // Called to determine if the WebContents can be overscrolled with touch/wheel
156 virtual bool CanOverscrollContent() const;
158 // Callback that allows vertical overscroll activies to be communicated to the
160 virtual void OverscrollUpdate(int delta_y) {}
162 // Return the rect where to display the resize corner, if any, otherwise
164 virtual gfx::Rect GetRootWindowResizerRect() const;
166 // Invoked prior to showing before unload handler confirmation dialog.
167 virtual void WillRunBeforeUnloadConfirm() {}
169 // Returns true if javascript dialogs and unload alerts are suppressed.
171 virtual bool ShouldSuppressDialogs();
173 // Add a message to the console. Returning true indicates that the delegate
174 // handled the message. If false is returned the default logging mechanism
175 // will be used for the message.
176 virtual bool AddMessageToConsole(WebContents* source,
178 const base::string16& message,
180 const base::string16& source_id);
182 // Tells us that we've finished firing this tab's beforeunload event.
183 // The proceed bool tells us whether the user chose to proceed closing the
184 // tab. Returns true if the tab can continue on firing its unload event.
185 // If we're closing the entire browser, then we'll want to delay firing
186 // unload events until all the beforeunload events have fired.
187 virtual void BeforeUnloadFired(WebContents* tab,
189 bool* proceed_to_fire_unload);
191 // Returns true if the location bar should be focused by default rather than
192 // the page contents. NOTE: this is only used if WebContents can't determine
193 // for itself whether the location bar should be focused by default. For a
194 // complete check, you should use WebContents::FocusLocationBarByDefault().
195 virtual bool ShouldFocusLocationBarByDefault(WebContents* source);
197 // Sets focus to the location bar or some other place that is appropriate.
198 // This is called when the tab wants to encourage user input, like for the
200 virtual void SetFocusToLocationBar(bool select_all) {}
202 // Returns whether the page should be focused when transitioning from crashed
203 // to live. Default is true.
204 virtual bool ShouldFocusPageAfterCrash();
206 // This is called when WebKit tells us that it is done tabbing through
207 // controls on the page. Provides a way for WebContentsDelegates to handle
208 // this. Returns true if the delegate successfully handled it.
209 virtual bool TakeFocus(WebContents* source,
212 // Invoked when the page loses mouse capture.
213 virtual void LostCapture() {}
215 // Notification that |contents| has gained focus.
216 virtual void WebContentsFocused(WebContents* contents) {}
218 // Asks the delegate if the given tab can download.
219 // Invoking the |callback| synchronously is OK.
220 virtual void CanDownload(RenderViewHost* render_view_host,
222 const std::string& request_method,
223 const base::Callback<void(bool)>& callback);
225 // Return much extra vertical space should be allotted to the
226 // render view widget during various animations (e.g. infobar closing).
227 // This is used to make painting look smoother.
228 virtual int GetExtraRenderViewHeight() const;
230 // Returns true if the context menu operation was handled by the delegate.
231 virtual bool HandleContextMenu(const content::ContextMenuParams& params);
233 // Opens source view for given WebContents that is navigated to the given
235 virtual void ViewSourceForTab(WebContents* source, const GURL& page_url);
237 // Opens source view for the given subframe.
238 virtual void ViewSourceForFrame(WebContents* source,
240 const PageState& page_state);
242 // Allows delegates to handle keyboard events before sending to the renderer.
243 // Returns true if the |event| was handled. Otherwise, if the |event| would be
244 // handled in HandleKeyboardEvent() method as a normal keyboard shortcut,
245 // |*is_keyboard_shortcut| should be set to true.
246 virtual bool PreHandleKeyboardEvent(WebContents* source,
247 const NativeWebKeyboardEvent& event,
248 bool* is_keyboard_shortcut);
250 // Allows delegates to handle unhandled keyboard messages coming back from
252 virtual void HandleKeyboardEvent(WebContents* source,
253 const NativeWebKeyboardEvent& event) {}
255 virtual void HandleMouseDown() {}
256 virtual void HandleMouseUp() {}
258 // Handles activation resulting from a pointer event (e.g. when mouse is
259 // pressed, or a touch-gesture begins).
260 virtual void HandlePointerActivate() {}
262 // Allows delegates to handle gesture events before sending to the renderer.
263 // Returns true if the |event| was handled and thus shouldn't be processed
264 // by the renderer's event handler. Note that the touch events that create
265 // the gesture are always passed to the renderer since the gesture is created
266 // and dispatched after the touches return without being "preventDefault()"ed.
267 virtual bool PreHandleGestureEvent(
269 const blink::WebGestureEvent& event);
271 virtual void HandleGestureBegin() {}
272 virtual void HandleGestureEnd() {}
274 // Called when an external drag event enters the web contents window. Return
275 // true to allow dragging and dropping on the web contents window or false to
276 // cancel the operation. This method is used by Chromium Embedded Framework.
277 virtual bool CanDragEnter(WebContents* source,
278 const DropData& data,
279 blink::WebDragOperationsMask operations_allowed);
281 // Render view drag n drop ended.
282 virtual void DragEnded() {}
284 // Shows the repost form confirmation dialog box.
285 virtual void ShowRepostFormWarningDialog(WebContents* source) {}
287 // Allows delegate to override navigation to the history entries.
288 // Returns true to allow WebContents to continue with the default processing.
289 virtual bool OnGoToEntryOffset(int offset);
291 // Allows delegate to control whether a WebContents will be created. Returns
292 // true to allow the creation. Default is to allow it. In cases where the
293 // delegate handles the creation/navigation itself, it will use |target_url|.
294 // The embedder has to synchronously adopt |route_id| or else the view will
296 virtual bool ShouldCreateWebContents(
297 WebContents* web_contents,
299 WindowContainerType window_container_type,
300 const base::string16& frame_name,
301 const GURL& target_url,
302 const std::string& partition_id,
303 SessionStorageNamespace* session_storage_namespace);
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 base::string16& frame_name,
310 const GURL& target_url,
311 WebContents* new_contents) {}
313 // Notification that the tab is hung.
314 virtual void RendererUnresponsive(WebContents* source) {}
316 // Notification that the tab is no longer hung.
317 virtual void RendererResponsive(WebContents* source) {}
319 // Notification that a worker associated with this tab has crashed.
320 virtual void WorkerCrashed(WebContents* source) {}
322 // Invoked when a main fram navigation occurs.
323 virtual void DidNavigateMainFramePostCommit(WebContents* source) {}
325 // Invoked when navigating to a pending entry. When invoked the
326 // NavigationController has configured its pending entry, but it has not yet
328 virtual void DidNavigateToPendingEntry(WebContents* source) {}
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();
334 // Called when color chooser should open. Returns the opened color chooser.
335 // Returns NULL if we failed to open the color chooser (e.g. when there is a
336 // ColorChooserDialog already open on Windows). Ownership of the returned
337 // pointer is transferred to the caller.
338 virtual ColorChooser* OpenColorChooser(
339 WebContents* web_contents,
341 const std::vector<ColorSuggestion>& suggestions);
343 // Called when a file selection is to be done.
344 virtual void RunFileChooser(WebContents* web_contents,
345 const FileChooserParams& params) {}
347 // Request to enumerate a directory. This is equivalent to running the file
348 // chooser in directory-enumeration mode and having the user select the given
350 virtual void EnumerateDirectory(WebContents* web_contents,
352 const base::FilePath& path) {}
354 // Returns true if the delegate will embed a WebContents-owned fullscreen
355 // render widget. In this case, the delegate may access the widget by calling
356 // WebContents::GetFullscreenRenderWidgetHostView(). If false is returned,
357 // WebContents will be responsible for showing the fullscreen widget.
358 virtual bool EmbedsFullscreenWidget() const;
360 // Called when the renderer puts a tab into or out of fullscreen mode.
361 virtual void ToggleFullscreenModeForTab(WebContents* web_contents,
362 bool enter_fullscreen) {}
363 virtual bool IsFullscreenForTabOrPending(
364 const WebContents* web_contents) const;
366 // Called when a Javascript out of memory notification is received.
367 virtual void JSOutOfMemory(WebContents* web_contents) {}
369 // Register a new handler for URL requests with the given scheme.
370 // |user_gesture| is true if the registration is made in the context of a user
372 virtual void RegisterProtocolHandler(WebContents* web_contents,
373 const std::string& protocol,
375 const base::string16& title,
376 bool user_gesture) {}
378 // Result of string search in the page. This includes the number of matches
379 // found and the selection rect (in screen coordinates) for the string found.
380 // If |final_update| is false, it indicates that more results follow.
381 virtual void FindReply(WebContents* web_contents,
383 int number_of_matches,
384 const gfx::Rect& selection_rect,
385 int active_match_ordinal,
386 bool final_update) {}
388 #if defined(OS_ANDROID)
389 // Provides the rects of the current find-in-page matches.
390 // Sent as a reply to RequestFindMatchRects.
391 virtual void FindMatchRectsReply(WebContents* web_contents,
393 const std::vector<gfx::RectF>& rects,
394 const gfx::RectF& active_rect) {}
397 // Invoked when the preferred size of the contents has been changed.
398 virtual void UpdatePreferredSize(WebContents* web_contents,
399 const gfx::Size& pref_size) {}
401 // Invoked when the contents auto-resized and the container should match it.
402 virtual void ResizeDueToAutoResize(WebContents* web_contents,
403 const gfx::Size& new_size) {}
405 // Notification message from HTML UI.
406 virtual void WebUISend(WebContents* web_contents,
407 const GURL& source_url,
408 const std::string& name,
409 const base::ListValue& args) {}
411 // Requests to lock the mouse. Once the request is approved or rejected,
412 // GotResponseToLockMouseRequest() will be called on the requesting tab
414 virtual void RequestToLockMouse(WebContents* web_contents,
416 bool last_unlocked_by_target) {}
418 // Notification that the page has lost the mouse lock.
419 virtual void LostMouseLock() {}
421 // Asks permission to use the camera and/or microphone. If permission is
422 // granted, a call should be made to |callback| with the devices. If the
423 // request is denied, a call should be made to |callback| with an empty list
424 // of devices. |request| has the details of the request (e.g. which of audio
425 // and/or video devices are requested, and lists of available devices).
426 virtual void RequestMediaAccessPermission(
427 WebContents* web_contents,
428 const MediaStreamRequest& request,
429 const MediaResponseCallback& callback);
431 // Requests permission to access the PPAPI broker. The delegate should return
432 // true and call the passed in |callback| with the result, or return false
433 // to indicate that it does not support asking for permission.
434 virtual bool RequestPpapiBrokerPermission(
435 WebContents* web_contents,
437 const base::FilePath& plugin_path,
438 const base::Callback<void(bool)>& callback);
440 // Returns the size for the new render view created for the pending entry in
441 // |web_contents|; if there's no size, returns an empty size.
442 // This is optional for implementations of WebContentsDelegate; if the
443 // delegate doesn't provide a size, the current WebContentsView's size will be
445 virtual gfx::Size GetSizeForNewRenderView(
446 const WebContents* web_contents) const;
448 // Notification that validation of a form displayed by the |web_contents|
449 // has failed. There can only be one message per |web_contents| at a time.
450 virtual void ShowValidationMessage(WebContents* web_contents,
451 const gfx::Rect& anchor_in_root_view,
452 const base::string16& main_text,
453 const base::string16& sub_text) {}
455 // Notification that the delegate should hide any showing form validation
457 virtual void HideValidationMessage(WebContents* web_contents) {}
459 // Notification that the form element that triggered the validation failure
461 virtual void MoveValidationMessage(WebContents* web_contents,
462 const gfx::Rect& anchor_in_root_view) {}
465 virtual ~WebContentsDelegate();
468 friend class WebContentsImpl;
470 // Called when |this| becomes the WebContentsDelegate for |source|.
471 void Attach(WebContents* source);
473 // Called when |this| is no longer the WebContentsDelegate for |source|.
474 void Detach(WebContents* source);
476 // The WebContents that this is currently a delegate for.
477 std::set<WebContents*> attached_contents_;
480 } // namespace content
482 #endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_DELEGATE_H_