2 * Copyright (C) 2009, 2010, 2011, 2012 Google Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * * Redistributions in binary form must reproduce the above
11 * copyright notice, this list of conditions and the following disclaimer
12 * in the documentation and/or other materials provided with the
14 * * Neither the name of Google Inc. nor the names of its
15 * contributors may be used to endorse or promote products derived from
16 * this software without specific prior written permission.
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 #include "../platform/WebColor.h"
35 #include "../platform/WebString.h"
36 #include "../platform/WebVector.h"
37 #include "WebDragOperation.h"
38 #include "WebHistoryCommitType.h"
39 #include "WebHistoryItem.h"
40 #include "WebPageVisibilityState.h"
41 #include "WebWidget.h"
46 class WebAutofillClient;
47 class WebDevToolsAgent;
48 class WebDevToolsAgentClient;
52 class WebGraphicsContext3D;
53 class WebHitTestResult;
56 class WebPrerendererClient;
59 class WebSpellCheckClient;
61 class WebPasswordGeneratorClient;
63 struct WebActiveWheelFlingParameters;
64 struct WebMediaPlayerAction;
65 struct WebPluginAction;
68 struct WebWindowFeatures;
70 class WebView : public WebWidget {
72 BLINK_EXPORT static const double textSizeMultiplierRatio;
73 BLINK_EXPORT static const double minTextSizeMultiplier;
74 BLINK_EXPORT static const double maxTextSizeMultiplier;
75 BLINK_EXPORT static const float minPageScaleFactor;
76 BLINK_EXPORT static const float maxPageScaleFactor;
78 enum StyleInjectionTarget {
79 InjectStyleInAllFrames,
80 InjectStyleInTopFrameOnly
84 // Initialization ------------------------------------------------------
86 // Creates a WebView that is NOT yet initialized. You will need to
87 // call setMainFrame to finish the initialization. It is valid
88 // to pass a null client pointer.
89 BLINK_EXPORT static WebView* create(WebViewClient*);
91 // After creating a WebView, you should immediately call this method.
92 // You can optionally modify the settings before calling this method.
93 // This WebFrame will receive events for the main frame and must not
95 virtual void setMainFrame(WebFrame*) = 0;
97 // Initializes the various client interfaces.
98 virtual void setAutofillClient(WebAutofillClient*) = 0;
99 virtual void setDevToolsAgentClient(WebDevToolsAgentClient*) = 0;
100 virtual void setPrerendererClient(WebPrerendererClient*) = 0;
101 virtual void setSpellCheckClient(WebSpellCheckClient*) = 0;
102 virtual void setPasswordGeneratorClient(WebPasswordGeneratorClient*) = 0;
104 // Options -------------------------------------------------------------
106 // The returned pointer is valid for the lifetime of the WebView.
107 virtual WebSettings* settings() = 0;
109 // Corresponds to the encoding of the main frame. Setting the page
110 // encoding may cause the main frame to reload.
111 virtual WebString pageEncoding() const = 0;
112 virtual void setPageEncoding(const WebString&) = 0;
114 // Makes the WebView transparent. This is useful if you want to have
115 // some custom background rendered behind it.
116 virtual bool isTransparent() const = 0;
117 virtual void setIsTransparent(bool) = 0;
119 // Sets the base color used for this WebView's background. This is in effect
120 // the default background color used for pages with no background-color
121 // style in effect, or used as the alpha-blended basis for any pages with
122 // translucent background-color style. (For pages with opaque
123 // background-color style, this property is effectively ignored).
124 // Setting this takes effect for the currently loaded page, if any, and
125 // persists across subsequent navigations. Defaults to white prior to the
126 // first call to this method.
127 virtual void setBaseBackgroundColor(WebColor) = 0;
129 // Controls whether pressing Tab key advances focus to links.
130 virtual bool tabsToLinks() const = 0;
131 virtual void setTabsToLinks(bool) = 0;
133 // Method that controls whether pressing Tab key cycles through page
134 // elements or inserts a '\t' char in the focused text area.
135 virtual bool tabKeyCyclesThroughElements() const = 0;
136 virtual void setTabKeyCyclesThroughElements(bool) = 0;
138 // Controls the WebView's active state, which may affect the rendering
139 // of elements on the page (i.e., tinting of input elements).
140 virtual bool isActive() const = 0;
141 virtual void setIsActive(bool) = 0;
143 // Allows disabling domain relaxation.
144 virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0;
146 // Allows setting the state of the various bars exposed via BarProp
147 // properties on the window object. The size related fields of
148 // WebWindowFeatures are ignored.
149 virtual void setWindowFeatures(const WebWindowFeatures&) = 0;
151 // Marks the WebView as being opened by a DOM call. This is relevant
152 // for whether window.close() may be called.
153 virtual void setOpenedByDOM() = 0;
156 // Frames --------------------------------------------------------------
158 virtual WebFrame* mainFrame() = 0;
160 // Returns the frame identified by the given name. This method
161 // supports pseudo-names like _self, _top, and _blank. It traverses
162 // the entire frame tree containing this tree looking for a frame that
163 // matches the given name. If the optional relativeToFrame parameter
164 // is specified, then the search begins with the given frame and its
166 virtual WebFrame* findFrameByName(
167 const WebString& name, WebFrame* relativeToFrame = 0) = 0;
170 // Focus ---------------------------------------------------------------
172 virtual WebFrame* focusedFrame() = 0;
173 virtual void setFocusedFrame(WebFrame*) = 0;
175 // Focus the first (last if reverse is true) focusable node.
176 virtual void setInitialFocus(bool reverse) = 0;
178 // Clears the focused element (and selection if a text field is focused)
179 // to ensure that a text field on the page is not eating keystrokes we
181 virtual void clearFocusedElement() = 0;
183 // Scrolls the node currently in focus into |rect|, where |rect| is in
185 virtual void scrollFocusedNodeIntoRect(const WebRect&) { }
187 // Advance the focus of the WebView forward to the next element or to the
188 // previous element in the tab sequence (if reverse is true).
189 virtual void advanceFocus(bool reverse) { }
191 // Animate a scale into the specified find-in-page rect.
192 virtual void zoomToFindInPageRect(const WebRect&) = 0;
194 // Animate a scale into the specified rect where multiple targets were
195 // found from previous tap gesture.
196 // Returns false if it doesn't do any zooming.
197 virtual bool zoomToMultipleTargetsRect(const WebRect&) = 0;
200 // Zoom ----------------------------------------------------------------
202 // Returns the current zoom level. 0 is "original size", and each increment
203 // above or below represents zooming 20% larger or smaller to default limits
204 // of 300% and 50% of original size, respectively. Only plugins use
205 // non whole-numbers, since they might choose to have specific zoom level so
206 // that fixed-width content is fit-to-page-width, for example.
207 virtual double zoomLevel() = 0;
209 // Changes the zoom level to the specified level, clamping at the limits
210 // noted above, and returns the current zoom level after applying the
212 virtual double setZoomLevel(double) = 0;
214 // Updates the zoom limits for this view.
215 virtual void zoomLimitsChanged(double minimumZoomLevel,
216 double maximumZoomLevel) = 0;
218 // Helper functions to convert between zoom level and zoom factor. zoom
219 // factor is zoom percent / 100, so 300% = 3.0.
220 BLINK_EXPORT static double zoomLevelToZoomFactor(double zoomLevel);
221 BLINK_EXPORT static double zoomFactorToZoomLevel(double factor);
223 // Returns the current text zoom factor, where 1.0 is the normal size, > 1.0
224 // is scaled up and < 1.0 is scaled down.
225 virtual float textZoomFactor() = 0;
227 // Scales the text in the page by a factor of textZoomFactor.
228 // Note: this has no effect on plugins.
229 virtual float setTextZoomFactor(float) = 0;
231 // Sets the initial page scale to the given factor. This scale setting overrides
232 // page scale set in the page's viewport meta tag.
233 virtual void setInitialPageScaleOverride(float) = 0;
235 // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0
236 // is scaled up, < 1.0 is scaled down.
237 virtual float pageScaleFactor() const = 0;
239 // TODO: Obsolete, the origin parameter is ambiguous with two viewports. Remove
240 // once Chromium side users are removed.
241 // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y).
242 // setPageScaleFactor() magnifies and shrinks a page without affecting layout.
243 // On the other hand, zooming affects layout of the page.
244 virtual void setPageScaleFactor(float scaleFactor, const WebPoint& origin) = 0;
246 // TODO: Reevaluate if this is needed once all users are converted to using the
247 // virtual viewport pinch model.
248 // Temporary to keep old style pinch viewport working while we gradually bring up
249 // virtual viewport pinch.
250 virtual void setMainFrameScrollOffset(const WebPoint& origin) = 0;
252 // Scales the page without affecting layout by using the pinch-to-zoom viewport.
253 virtual void setPageScaleFactor(float) = 0;
255 // Sets the offset of the pinch-to-zoom viewport within the main frame, in
256 // partial CSS pixels. The offset will be clamped so the pinch viewport
257 // stays within the frame's bounds.
258 virtual void setPinchViewportOffset(const WebFloatPoint&) = 0;
260 // Gets the pinch viewport's current offset within the page's main frame,
261 // in partial CSS pixels.
262 virtual WebFloatPoint pinchViewportOffset() const = 0;
264 // PageScaleFactor will be force-clamped between minPageScale and maxPageScale
265 // (and these values will persist until setPageScaleFactorLimits is called
267 virtual void setPageScaleFactorLimits(float minPageScale, float maxPageScale) = 0;
269 virtual float minimumPageScaleFactor() const = 0;
270 virtual float maximumPageScaleFactor() const = 0;
272 // Reset any saved values for the scroll and scale state.
273 virtual void resetScrollAndScaleState() = 0;
275 // Prevent the web page from setting min/max scale via the viewport meta
276 // tag. This is an accessibility feature that lets folks zoom in to web
277 // pages even if the web page tries to block scaling.
278 virtual void setIgnoreViewportTagScaleLimits(bool) = 0;
280 // Returns the "preferred" contents size, defined as the preferred minimum width of the main document's contents
281 // and the minimum height required to display the main document without scrollbars.
282 // The returned size has the page zoom factor applied.
283 virtual WebSize contentsPreferredMinimumSize() = 0;
285 // The ratio of the current device's screen DPI to the target device's screen DPI.
286 virtual float deviceScaleFactor() const = 0;
288 // Sets the ratio as computed by computePageScaleConstraints.
289 virtual void setDeviceScaleFactor(float) = 0;
292 // Fixed Layout --------------------------------------------------------
294 // Locks main frame's layout size to specified size. Passing WebSize(0, 0)
296 virtual void setFixedLayoutSize(const WebSize&) = 0;
299 // Auto-Resize -----------------------------------------------------------
301 // In auto-resize mode, the view is automatically adjusted to fit the html
302 // content within the given bounds.
303 virtual void enableAutoResizeMode(
304 const WebSize& minSize,
305 const WebSize& maxSize) = 0;
307 // Turn off auto-resize.
308 virtual void disableAutoResizeMode() = 0;
310 // Media ---------------------------------------------------------------
312 // Performs the specified media player action on the node at the given location.
313 virtual void performMediaPlayerAction(
314 const WebMediaPlayerAction&, const WebPoint& location) = 0;
316 // Performs the specified plugin action on the node at the given location.
317 virtual void performPluginAction(
318 const WebPluginAction&, const WebPoint& location) = 0;
321 // Data exchange -------------------------------------------------------
323 // Do a hit test at given point and return the HitTestResult.
324 virtual WebHitTestResult hitTestResultAt(const WebPoint&) = 0;
326 // Copy to the clipboard the image located at a particular point in the
327 // WebView (if there is such an image)
328 virtual void copyImageAt(const WebPoint&) = 0;
330 // Save as the image located at a particular point in the
331 // WebView (if there is such an image)
332 virtual void saveImageAt(const WebPoint&) = 0;
334 // Notifies the WebView that a drag has terminated.
335 virtual void dragSourceEndedAt(
336 const WebPoint& clientPoint, const WebPoint& screenPoint,
337 WebDragOperation operation) = 0;
339 // Notfies the WebView that the system drag and drop operation has ended.
340 virtual void dragSourceSystemDragEnded() = 0;
342 // Callback methods when a drag-and-drop operation is trying to drop
343 // something on the WebView.
344 virtual WebDragOperation dragTargetDragEnter(
346 const WebPoint& clientPoint, const WebPoint& screenPoint,
347 WebDragOperationsMask operationsAllowed,
348 int keyModifiers) = 0;
349 virtual WebDragOperation dragTargetDragOver(
350 const WebPoint& clientPoint, const WebPoint& screenPoint,
351 WebDragOperationsMask operationsAllowed,
352 int keyModifiers) = 0;
353 virtual void dragTargetDragLeave() = 0;
354 virtual void dragTargetDrop(
355 const WebPoint& clientPoint, const WebPoint& screenPoint,
356 int keyModifiers) = 0;
358 // Retrieves a list of spelling markers.
359 virtual void spellingMarkers(WebVector<uint32_t>* markers) = 0;
362 // Support for resource loading initiated by plugins -------------------
364 // Returns next unused request identifier which is unique within the
366 virtual unsigned long createUniqueIdentifierForRequest() = 0;
369 // Developer tools -----------------------------------------------------
371 // Inspect a particular point in the WebView. (x = -1 || y = -1) is a
372 // special case, meaning inspect the current page and not a specific
374 virtual void inspectElementAt(const WebPoint&) = 0;
376 // Settings used by the inspector.
377 virtual WebString inspectorSettings() const = 0;
378 virtual void setInspectorSettings(const WebString&) = 0;
379 virtual bool inspectorSetting(const WebString& key,
380 WebString* value) const = 0;
381 virtual void setInspectorSetting(const WebString& key,
382 const WebString& value) = 0;
384 // Set an override of device scale factor passed from WebView to
385 // compositor. Pass zero to cancel override. This is used to implement
386 // device metrics emulation.
387 virtual void setCompositorDeviceScaleFactorOverride(float) = 0;
389 // Set offset and scale on the root composited layer. This is used
390 // to implement device metrics emulation.
391 virtual void setRootLayerTransform(const WebSize& offset, float scale) = 0;
393 // The embedder may optionally engage a WebDevToolsAgent. This may only
394 // be set once per WebView.
395 virtual WebDevToolsAgent* devToolsAgent() = 0;
398 // Accessibility -------------------------------------------------------
400 // Returns the accessibility object for this view.
401 virtual WebAXObject accessibilityObject() = 0;
404 // Context menu --------------------------------------------------------
406 virtual void performCustomContextMenuAction(unsigned action) = 0;
408 // Shows a context menu for the currently focused element.
409 virtual void showContextMenu() = 0;
412 // SmartClip support ---------------------------------------------------
414 virtual WebString getSmartClipData(WebRect) = 0;
417 // Popup menu ----------------------------------------------------------
419 // Sets whether select popup menus should be rendered by the browser.
420 BLINK_EXPORT static void setUseExternalPopupMenus(bool);
422 // Hides any popup (suggestions, selects...) that might be showing.
423 virtual void hidePopups() = 0;
426 // Visited link state --------------------------------------------------
428 // Tells all WebView instances to update the visited link state for the
430 BLINK_EXPORT static void updateVisitedLinkState(unsigned long long hash);
432 // Tells all WebView instances to update the visited state for all
434 BLINK_EXPORT static void resetVisitedLinkState();
437 // Custom colors -------------------------------------------------------
439 virtual void setSelectionColors(unsigned activeBackgroundColor,
440 unsigned activeForegroundColor,
441 unsigned inactiveBackgroundColor,
442 unsigned inactiveForegroundColor) = 0;
444 // Injected style ------------------------------------------------------
446 // Treats |sourceCode| as a CSS author style sheet and injects it into all Documents whose URLs match |patterns|,
447 // in the frames specified by the last argument.
448 BLINK_EXPORT static void injectStyleSheet(const WebString& sourceCode, const WebVector<WebString>& patterns, StyleInjectionTarget);
449 BLINK_EXPORT static void removeInjectedStyleSheets();
451 // Modal dialog support ------------------------------------------------
453 // Call these methods before and after running a nested, modal event loop
454 // to suspend script callbacks and resource loads.
455 BLINK_EXPORT static void willEnterModalLoop();
456 BLINK_EXPORT static void didExitModalLoop();
458 // Called to inform the WebView that a wheel fling animation was started externally (for instance
459 // by the compositor) but must be completed by the WebView.
460 virtual void transferActiveWheelFlingAnimation(const WebActiveWheelFlingParameters&) = 0;
462 // Cancels an active fling, returning true if a fling was active.
463 virtual bool endActiveFlingAnimation() = 0;
465 virtual void setShowPaintRects(bool) = 0;
466 virtual void setShowFPSCounter(bool) = 0;
467 virtual void setContinuousPaintingEnabled(bool) = 0;
468 virtual void setShowScrollBottleneckRects(bool) = 0;
470 // Compute the bounds of the root element of the current selection and fills
471 // the out-parameter on success. |bounds| coordinates will be relative to
472 // the contents window and will take into account the current scale level.
473 virtual void getSelectionRootBounds(WebRect& bounds) const = 0;
475 // Visibility -----------------------------------------------------------
477 // Sets the visibility of the WebView.
478 virtual void setVisibilityState(WebPageVisibilityState visibilityState,
479 bool isInitialState) { }
481 // PageOverlay ----------------------------------------------------------
483 // Adds/removes page overlay to this WebView. These functions change the
484 // graphical appearance of the WebView. WebPageOverlay paints the
485 // contents of the page overlay. It also provides an z-order number for
486 // the page overlay. The z-order number defines the paint order the page
487 // overlays. Page overlays with larger z-order number will be painted after
488 // page overlays with smaller z-order number. That is, they appear above
489 // the page overlays with smaller z-order number. If two page overlays have
490 // the same z-order number, the later added one will be on top.
491 virtual void addPageOverlay(WebPageOverlay*, int /*z-order*/) = 0;
492 virtual void removePageOverlay(WebPageOverlay*) = 0;
495 // Testing functionality for TestRunner ---------------------------------