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
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.
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