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;
62 struct WebActiveWheelFlingParameters;
63 struct WebMediaPlayerAction;
64 struct WebPluginAction;
67 struct WebWindowFeatures;
69 class WebView : public WebWidget {
71 BLINK_EXPORT static const double textSizeMultiplierRatio;
72 BLINK_EXPORT static const double minTextSizeMultiplier;
73 BLINK_EXPORT static const double maxTextSizeMultiplier;
74 BLINK_EXPORT static const float minPageScaleFactor;
75 BLINK_EXPORT static const float maxPageScaleFactor;
77 enum StyleInjectionTarget {
78 InjectStyleInAllFrames,
79 InjectStyleInTopFrameOnly
83 // Initialization ------------------------------------------------------
85 // Creates a WebView that is NOT yet initialized. You will need to
86 // call setMainFrame to finish the initialization. It is valid
87 // to pass a null client pointer.
88 BLINK_EXPORT static WebView* create(WebViewClient*);
90 // After creating a WebView, you should immediately call this method.
91 // You can optionally modify the settings before calling this method.
92 // This WebFrame will receive events for the main frame and must not
94 virtual void setMainFrame(WebFrame*) = 0;
96 // Initializes the various client interfaces.
97 virtual void setAutofillClient(WebAutofillClient*) = 0;
98 virtual void setDevToolsAgentClient(WebDevToolsAgentClient*) = 0;
99 virtual void setPrerendererClient(WebPrerendererClient*) = 0;
100 virtual void setSpellCheckClient(WebSpellCheckClient*) = 0;
102 // Options -------------------------------------------------------------
104 // The returned pointer is valid for the lifetime of the WebView.
105 virtual WebSettings* settings() = 0;
107 // Corresponds to the encoding of the main frame. Setting the page
108 // encoding may cause the main frame to reload.
109 virtual WebString pageEncoding() const = 0;
110 virtual void setPageEncoding(const WebString&) = 0;
112 // Makes the WebView transparent. This is useful if you want to have
113 // some custom background rendered behind it.
114 virtual bool isTransparent() const = 0;
115 virtual void setIsTransparent(bool) = 0;
117 // Sets the base color used for this WebView's background. This is in effect
118 // the default background color used for pages with no background-color
119 // style in effect, or used as the alpha-blended basis for any pages with
120 // translucent background-color style. (For pages with opaque
121 // background-color style, this property is effectively ignored).
122 // Setting this takes effect for the currently loaded page, if any, and
123 // persists across subsequent navigations. Defaults to white prior to the
124 // first call to this method.
125 virtual void setBaseBackgroundColor(WebColor) = 0;
127 // Controls whether pressing Tab key advances focus to links.
128 virtual bool tabsToLinks() const = 0;
129 virtual void setTabsToLinks(bool) = 0;
131 // Method that controls whether pressing Tab key cycles through page
132 // elements or inserts a '\t' char in the focused text area.
133 virtual bool tabKeyCyclesThroughElements() const = 0;
134 virtual void setTabKeyCyclesThroughElements(bool) = 0;
136 // Controls the WebView's active state, which may affect the rendering
137 // of elements on the page (i.e., tinting of input elements).
138 virtual bool isActive() const = 0;
139 virtual void setIsActive(bool) = 0;
141 // Allows disabling domain relaxation.
142 virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0;
144 // Allows setting the state of the various bars exposed via BarProp
145 // properties on the window object. The size related fields of
146 // WebWindowFeatures are ignored.
147 virtual void setWindowFeatures(const WebWindowFeatures&) = 0;
149 // Marks the WebView as being opened by a DOM call. This is relevant
150 // for whether window.close() may be called.
151 virtual void setOpenedByDOM() = 0;
154 // Frames --------------------------------------------------------------
156 virtual WebFrame* mainFrame() = 0;
158 // Returns the frame identified by the given name. This method
159 // supports pseudo-names like _self, _top, and _blank. It traverses
160 // the entire frame tree containing this tree looking for a frame that
161 // matches the given name. If the optional relativeToFrame parameter
162 // is specified, then the search begins with the given frame and its
164 virtual WebFrame* findFrameByName(
165 const WebString& name, WebFrame* relativeToFrame = 0) = 0;
168 // Focus ---------------------------------------------------------------
170 virtual WebFrame* focusedFrame() = 0;
171 virtual void setFocusedFrame(WebFrame*) = 0;
173 // Focus the first (last if reverse is true) focusable node.
174 virtual void setInitialFocus(bool reverse) = 0;
176 // Clears the focused element (and selection if a text field is focused)
177 // to ensure that a text field on the page is not eating keystrokes we
179 virtual void clearFocusedElement() = 0;
181 // Scrolls the node currently in focus into |rect|, where |rect| is in
183 virtual void scrollFocusedNodeIntoRect(const WebRect&) { }
185 // Advance the focus of the WebView forward to the next element or to the
186 // previous element in the tab sequence (if reverse is true).
187 virtual void advanceFocus(bool reverse) { }
189 // Animate a scale into the specified find-in-page rect.
190 virtual void zoomToFindInPageRect(const WebRect&) = 0;
192 // Animate a scale into the specified rect where multiple targets were
193 // found from previous tap gesture.
194 // Returns false if it doesn't do any zooming.
195 virtual bool zoomToMultipleTargetsRect(const WebRect&) = 0;
198 // Zoom ----------------------------------------------------------------
200 // Returns the current zoom level. 0 is "original size", and each increment
201 // above or below represents zooming 20% larger or smaller to default limits
202 // of 300% and 50% of original size, respectively. Only plugins use
203 // non whole-numbers, since they might choose to have specific zoom level so
204 // that fixed-width content is fit-to-page-width, for example.
205 virtual double zoomLevel() = 0;
207 // Changes the zoom level to the specified level, clamping at the limits
208 // noted above, and returns the current zoom level after applying the
210 virtual double setZoomLevel(double) = 0;
212 // Updates the zoom limits for this view.
213 virtual void zoomLimitsChanged(double minimumZoomLevel,
214 double maximumZoomLevel) = 0;
216 // Helper functions to convert between zoom level and zoom factor. zoom
217 // factor is zoom percent / 100, so 300% = 3.0.
218 BLINK_EXPORT static double zoomLevelToZoomFactor(double zoomLevel);
219 BLINK_EXPORT static double zoomFactorToZoomLevel(double factor);
221 // Returns the current text zoom factor, where 1.0 is the normal size, > 1.0
222 // is scaled up and < 1.0 is scaled down.
223 virtual float textZoomFactor() = 0;
225 // Scales the text in the page by a factor of textZoomFactor.
226 // Note: this has no effect on plugins.
227 virtual float setTextZoomFactor(float) = 0;
229 // Sets the initial page scale to the given factor. This scale setting overrides
230 // page scale set in the page's viewport meta tag.
231 virtual void setInitialPageScaleOverride(float) = 0;
233 // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0
234 // is scaled up, < 1.0 is scaled down.
235 virtual float pageScaleFactor() const = 0;
237 // TODO: Obsolete, the origin parameter is ambiguous with two viewports. Remove
238 // once Chromium side users are removed.
239 // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y).
240 // setPageScaleFactor() magnifies and shrinks a page without affecting layout.
241 // On the other hand, zooming affects layout of the page.
242 virtual void setPageScaleFactor(float scaleFactor, const WebPoint& origin) = 0;
244 // TODO: Reevaluate if this is needed once all users are converted to using the
245 // virtual viewport pinch model.
246 // Temporary to keep old style pinch viewport working while we gradually bring up
247 // virtual viewport pinch.
248 virtual void setMainFrameScrollOffset(const WebPoint& origin) = 0;
250 // Scales the page without affecting layout by using the pinch-to-zoom viewport.
251 virtual void setPageScaleFactor(float) = 0;
253 // Sets the offset of the pinch-to-zoom viewport within the main frame, in
254 // partial CSS pixels. The offset will be clamped so the pinch viewport
255 // stays within the frame's bounds.
256 virtual void setPinchViewportOffset(const WebFloatPoint&) = 0;
258 // Gets the pinch viewport's current offset within the page's main frame,
259 // in partial CSS pixels.
260 virtual WebFloatPoint pinchViewportOffset() const = 0;
262 // PageScaleFactor will be force-clamped between minPageScale and maxPageScale
263 // (and these values will persist until setPageScaleFactorLimits is called
265 virtual void setPageScaleFactorLimits(float minPageScale, float maxPageScale) = 0;
267 virtual float minimumPageScaleFactor() const = 0;
268 virtual float maximumPageScaleFactor() const = 0;
270 // Reset any saved values for the scroll and scale state.
271 virtual void resetScrollAndScaleState() = 0;
273 // Prevent the web page from setting min/max scale via the viewport meta
274 // tag. This is an accessibility feature that lets folks zoom in to web
275 // pages even if the web page tries to block scaling.
276 virtual void setIgnoreViewportTagScaleLimits(bool) = 0;
278 // Returns the "preferred" contents size, defined as the preferred minimum width of the main document's contents
279 // and the minimum height required to display the main document without scrollbars.
280 // The returned size has the page zoom factor applied.
281 virtual WebSize contentsPreferredMinimumSize() = 0;
283 // The ratio of the current device's screen DPI to the target device's screen DPI.
284 virtual float deviceScaleFactor() const = 0;
286 // Sets the ratio as computed by computePageScaleConstraints.
287 virtual void setDeviceScaleFactor(float) = 0;
290 // Fixed Layout --------------------------------------------------------
292 // Locks main frame's layout size to specified size. Passing WebSize(0, 0)
294 virtual void setFixedLayoutSize(const WebSize&) = 0;
297 // Auto-Resize -----------------------------------------------------------
299 // In auto-resize mode, the view is automatically adjusted to fit the html
300 // content within the given bounds.
301 virtual void enableAutoResizeMode(
302 const WebSize& minSize,
303 const WebSize& maxSize) = 0;
305 // Turn off auto-resize.
306 virtual void disableAutoResizeMode() = 0;
308 // Media ---------------------------------------------------------------
310 // Performs the specified media player action on the node at the given location.
311 virtual void performMediaPlayerAction(
312 const WebMediaPlayerAction&, const WebPoint& location) = 0;
314 // Performs the specified plugin action on the node at the given location.
315 virtual void performPluginAction(
316 const WebPluginAction&, const WebPoint& location) = 0;
319 // Data exchange -------------------------------------------------------
321 // Do a hit test at given point and return the HitTestResult.
322 virtual WebHitTestResult hitTestResultAt(const WebPoint&) = 0;
324 // Copy to the clipboard the image located at a particular point in the
325 // WebView (if there is such an image)
326 virtual void copyImageAt(const WebPoint&) = 0;
328 // Save as the image located at a particular point in the
329 // WebView (if there is such an image)
330 virtual void saveImageAt(const WebPoint&) = 0;
332 // Notifies the WebView that a drag has terminated.
333 virtual void dragSourceEndedAt(
334 const WebPoint& clientPoint, const WebPoint& screenPoint,
335 WebDragOperation operation) = 0;
337 // Notfies the WebView that the system drag and drop operation has ended.
338 virtual void dragSourceSystemDragEnded() = 0;
340 // Callback methods when a drag-and-drop operation is trying to drop
341 // something on the WebView.
342 virtual WebDragOperation dragTargetDragEnter(
344 const WebPoint& clientPoint, const WebPoint& screenPoint,
345 WebDragOperationsMask operationsAllowed,
346 int keyModifiers) = 0;
347 virtual WebDragOperation dragTargetDragOver(
348 const WebPoint& clientPoint, const WebPoint& screenPoint,
349 WebDragOperationsMask operationsAllowed,
350 int keyModifiers) = 0;
351 virtual void dragTargetDragLeave() = 0;
352 virtual void dragTargetDrop(
353 const WebPoint& clientPoint, const WebPoint& screenPoint,
354 int keyModifiers) = 0;
356 // Retrieves a list of spelling markers.
357 virtual void spellingMarkers(WebVector<uint32_t>* markers) = 0;
360 // Support for resource loading initiated by plugins -------------------
362 // Returns next unused request identifier which is unique within the
364 virtual unsigned long createUniqueIdentifierForRequest() = 0;
367 // Developer tools -----------------------------------------------------
369 // Inspect a particular point in the WebView. (x = -1 || y = -1) is a
370 // special case, meaning inspect the current page and not a specific
372 virtual void inspectElementAt(const WebPoint&) = 0;
374 // FIXME: These are deprecated. Remove them.
375 virtual WebString inspectorSettingsDeprecated() const { return WebString(); };
376 virtual void setInspectorSettings(const WebString&) { };
377 virtual bool inspectorSettingDeprecated(const WebString& key, WebString* value) const { return false; };
378 virtual void setInspectorSetting(const WebString& key, const WebString& value) { };
380 // Set an override of device scale factor passed from WebView to
381 // compositor. Pass zero to cancel override. This is used to implement
382 // device metrics emulation.
383 virtual void setCompositorDeviceScaleFactorOverride(float) = 0;
385 // Set offset and scale on the root composited layer. This is used
386 // to implement device metrics emulation.
387 virtual void setRootLayerTransform(const WebSize& offset, float scale) = 0;
389 // The embedder may optionally engage a WebDevToolsAgent. This may only
390 // be set once per WebView.
391 virtual WebDevToolsAgent* devToolsAgent() = 0;
394 // Accessibility -------------------------------------------------------
396 // Returns the accessibility object for this view.
397 virtual WebAXObject accessibilityObject() = 0;
400 // Context menu --------------------------------------------------------
402 virtual void performCustomContextMenuAction(unsigned action) = 0;
404 // Shows a context menu for the currently focused element.
405 virtual void showContextMenu() = 0;
408 // SmartClip support ---------------------------------------------------
409 virtual void extractSmartClipData(WebRect initRect, WebString& text, WebString& html, WebRect& resultRect) = 0;
412 // Popup menu ----------------------------------------------------------
414 // Sets whether select popup menus should be rendered by the browser.
415 BLINK_EXPORT static void setUseExternalPopupMenus(bool);
417 // Hides any popup (suggestions, selects...) that might be showing.
418 virtual void hidePopups() = 0;
421 // Visited link state --------------------------------------------------
423 // Tells all WebView instances to update the visited link state for the
425 BLINK_EXPORT static void updateVisitedLinkState(unsigned long long hash);
427 // Tells all WebView instances to update the visited state for all
429 BLINK_EXPORT static void resetVisitedLinkState();
432 // Custom colors -------------------------------------------------------
434 virtual void setSelectionColors(unsigned activeBackgroundColor,
435 unsigned activeForegroundColor,
436 unsigned inactiveBackgroundColor,
437 unsigned inactiveForegroundColor) = 0;
439 // Injected style ------------------------------------------------------
441 // Treats |sourceCode| as a CSS author style sheet and injects it into all Documents whose URLs match |patterns|,
442 // in the frames specified by the last argument.
443 BLINK_EXPORT static void injectStyleSheet(const WebString& sourceCode, const WebVector<WebString>& patterns, StyleInjectionTarget);
444 BLINK_EXPORT static void removeInjectedStyleSheets();
446 // Modal dialog support ------------------------------------------------
448 // Call these methods before and after running a nested, modal event loop
449 // to suspend script callbacks and resource loads.
450 BLINK_EXPORT static void willEnterModalLoop();
451 BLINK_EXPORT static void didExitModalLoop();
453 // Called to inform the WebView that a wheel fling animation was started externally (for instance
454 // by the compositor) but must be completed by the WebView.
455 virtual void transferActiveWheelFlingAnimation(const WebActiveWheelFlingParameters&) = 0;
457 // Cancels an active fling, returning true if a fling was active.
458 virtual bool endActiveFlingAnimation() = 0;
460 virtual void setShowPaintRects(bool) = 0;
461 virtual void setShowFPSCounter(bool) = 0;
462 virtual void setContinuousPaintingEnabled(bool) = 0;
463 virtual void setShowScrollBottleneckRects(bool) = 0;
465 // Compute the bounds of the root element of the current selection and fills
466 // the out-parameter on success. |bounds| coordinates will be relative to
467 // the contents window and will take into account the current scale level.
468 virtual void getSelectionRootBounds(WebRect& bounds) const = 0;
470 // Visibility -----------------------------------------------------------
472 // Sets the visibility of the WebView.
473 virtual void setVisibilityState(WebPageVisibilityState visibilityState,
474 bool isInitialState) { }
476 // PageOverlay ----------------------------------------------------------
478 // Adds/removes page overlay to this WebView. These functions change the
479 // graphical appearance of the WebView. WebPageOverlay paints the
480 // contents of the page overlay. It also provides an z-order number for
481 // the page overlay. The z-order number defines the paint order the page
482 // overlays. Page overlays with larger z-order number will be painted after
483 // page overlays with smaller z-order number. That is, they appear above
484 // the page overlays with smaller z-order number. If two page overlays have
485 // the same z-order number, the later added one will be on top.
486 virtual void addPageOverlay(WebPageOverlay*, int /*z-order*/) = 0;
487 virtual void removePageOverlay(WebPageOverlay*) = 0;
490 // i18n -----------------------------------------------------------------
492 // Inform the WebView that the accept languages have changed.
493 // If the WebView wants to get the accept languages value, it will have
494 // to call the WebViewClient::acceptLanguages().
495 virtual void acceptLanguagesChanged() = 0;
497 // Testing functionality for TestRunner ---------------------------------