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 "WebPageVisibilityState.h"
39 #include "WebWidget.h"
44 class WebAutofillClient;
45 class WebDevToolsAgent;
46 class WebDevToolsAgentClient;
51 class WebGraphicsContext3D;
52 class WebHelperPlugin;
53 class WebHitTestResult;
56 class WebPrerendererClient;
59 class WebSpellCheckClient;
61 class WebPasswordGeneratorClient;
63 struct WebActiveWheelFlingParameters;
64 struct WebMediaPlayerAction;
65 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;
101 virtual void setPasswordGeneratorClient(WebPasswordGeneratorClient*) = 0;
103 // Options -------------------------------------------------------------
105 // The returned pointer is valid for the lifetime of the WebView.
106 virtual WebSettings* settings() = 0;
108 // Corresponds to the encoding of the main frame. Setting the page
109 // encoding may cause the main frame to reload.
110 virtual WebString pageEncoding() const = 0;
111 virtual void setPageEncoding(const WebString&) = 0;
113 // Makes the WebView transparent. This is useful if you want to have
114 // some custom background rendered behind it.
115 virtual bool isTransparent() const = 0;
116 virtual void setIsTransparent(bool) = 0;
118 // Sets the base color used for this WebView's background. This is in effect
119 // the default background color used for pages with no background-color
120 // style in effect, or used as the alpha-blended basis for any pages with
121 // translucent background-color style. (For pages with opaque
122 // background-color style, this property is effectively ignored).
123 // Setting this takes effect for the currently loaded page, if any, and
124 // persists across subsequent navigations. Defaults to white prior to the
125 // first call to this method.
126 virtual void setBaseBackgroundColor(WebColor) = 0;
128 // Controls whether pressing Tab key advances focus to links.
129 virtual bool tabsToLinks() const = 0;
130 virtual void setTabsToLinks(bool) = 0;
132 // Method that controls whether pressing Tab key cycles through page
133 // elements or inserts a '\t' char in the focused text area.
134 virtual bool tabKeyCyclesThroughElements() const = 0;
135 virtual void setTabKeyCyclesThroughElements(bool) = 0;
137 // Controls the WebView's active state, which may affect the rendering
138 // of elements on the page (i.e., tinting of input elements).
139 virtual bool isActive() const = 0;
140 virtual void setIsActive(bool) = 0;
142 // Allows disabling domain relaxation.
143 virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0;
145 // Allows setting the state of the various bars exposed via BarProp
146 // properties on the window object. The size related fields of
147 // WebWindowFeatures are ignored.
148 virtual void setWindowFeatures(const WebWindowFeatures&) = 0;
151 // Closing -------------------------------------------------------------
153 // Runs beforeunload handlers for the current page, returning false if
154 // any handler suppressed unloading.
155 virtual bool dispatchBeforeUnloadEvent() = 0;
157 // Runs unload handlers for the current page.
158 virtual void dispatchUnloadEvent() = 0;
161 // Frames --------------------------------------------------------------
163 virtual WebFrame* mainFrame() = 0;
165 // Returns the frame identified by the given name. This method
166 // supports pseudo-names like _self, _top, and _blank. It traverses
167 // the entire frame tree containing this tree looking for a frame that
168 // matches the given name. If the optional relativeToFrame parameter
169 // is specified, then the search begins with the given frame and its
171 virtual WebFrame* findFrameByName(
172 const WebString& name, WebFrame* relativeToFrame = 0) = 0;
175 // Focus ---------------------------------------------------------------
177 virtual WebFrame* focusedFrame() = 0;
178 virtual void setFocusedFrame(WebFrame*) = 0;
180 // Focus the first (last if reverse is true) focusable node.
181 virtual void setInitialFocus(bool reverse) = 0;
183 // Clears the focused node (and selection if a text field is focused)
184 // to ensure that a text field on the page is not eating keystrokes we
186 virtual void clearFocusedNode() = 0;
188 // Scrolls the node currently in focus into view.
189 virtual void scrollFocusedNodeIntoView() = 0;
191 // Scrolls the node currently in focus into |rect|, where |rect| is in
193 virtual void scrollFocusedNodeIntoRect(const WebRect&) { }
195 // Advance the focus of the WebView forward to the next element or to the
196 // previous element in the tab sequence (if reverse is true).
197 virtual void advanceFocus(bool reverse) { }
199 // Animate a scale into the specified find-in-page rect.
200 virtual void zoomToFindInPageRect(const WebRect&) = 0;
202 // Animate a scale into the specified rect where multiple targets were
203 // found from previous tap gesture.
204 // Returns false if it doesn't do any zooming.
205 virtual bool zoomToMultipleTargetsRect(const WebRect&) = 0;
208 // Zoom ----------------------------------------------------------------
210 // Returns the current zoom level. 0 is "original size", and each increment
211 // above or below represents zooming 20% larger or smaller to default limits
212 // of 300% and 50% of original size, respectively. Only plugins use
213 // non whole-numbers, since they might choose to have specific zoom level so
214 // that fixed-width content is fit-to-page-width, for example.
215 virtual double zoomLevel() = 0;
217 // Changes the zoom level to the specified level, clamping at the limits
218 // noted above, and returns the current zoom level after applying the
220 virtual double setZoomLevel(double) = 0;
222 // Updates the zoom limits for this view.
223 virtual void zoomLimitsChanged(double minimumZoomLevel,
224 double maximumZoomLevel) = 0;
226 // Helper functions to convert between zoom level and zoom factor. zoom
227 // factor is zoom percent / 100, so 300% = 3.0.
228 BLINK_EXPORT static double zoomLevelToZoomFactor(double zoomLevel);
229 BLINK_EXPORT static double zoomFactorToZoomLevel(double factor);
231 // Returns the current text zoom factor, where 1.0 is the normal size, > 1.0
232 // is scaled up and < 1.0 is scaled down.
233 virtual float textZoomFactor() = 0;
235 // Scales the text in the page by a factor of textZoomFactor.
236 // Note: this has no effect on plugins.
237 virtual float setTextZoomFactor(float) = 0;
239 // Sets the initial page scale to the given factor. This scale setting overrides
240 // page scale set in the page's viewport meta tag.
241 virtual void setInitialPageScaleOverride(float) = 0;
243 // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0
244 // is scaled up, < 1.0 is scaled down.
245 virtual float pageScaleFactor() const = 0;
247 // Scales the page and the scroll offset by a given factor, while ensuring
248 // that the new scroll position does not go beyond the edge of the page.
249 virtual void setPageScaleFactorPreservingScrollOffset(float) = 0;
251 // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y).
252 // setPageScaleFactor() magnifies and shrinks a page without affecting layout.
253 // On the other hand, zooming affects layout of the page.
254 virtual void setPageScaleFactor(float scaleFactor, const WebPoint& origin) = 0;
256 // PageScaleFactor will be force-clamped between minPageScale and maxPageScale
257 // (and these values will persist until setPageScaleFactorLimits is called
259 virtual void setPageScaleFactorLimits(float minPageScale, float maxPageScale) = 0;
261 virtual float minimumPageScaleFactor() const = 0;
262 virtual float maximumPageScaleFactor() const = 0;
264 // Save the WebView's current scroll and scale state. Each call to this function
265 // overwrites the previously saved scroll and scale state.
266 virtual void saveScrollAndScaleState() = 0;
268 // Restore the previously saved scroll and scale state. After restoring the
269 // state, this function deletes any saved scroll and scale state.
270 virtual void restoreScrollAndScaleState() = 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 // Creates a Helper Plugin of |pluginType| for |hostDocument|. Caller owns
317 // the returned object, and must call closeAndDeleteSoon() to free the Plugin.
318 virtual WebHelperPlugin* createHelperPlugin(
319 const WebString& pluginType, const WebDocument& hostDocument) = 0;
321 // Performs the specified plugin action on the node at the given location.
322 virtual void performPluginAction(
323 const WebPluginAction&, const WebPoint& location) = 0;
326 // Data exchange -------------------------------------------------------
328 // Do a hit test at given point and return the HitTestResult.
329 virtual WebHitTestResult hitTestResultAt(const WebPoint&) = 0;
331 // Copy to the clipboard the image located at a particular point in the
332 // WebView (if there is such an image)
333 virtual void copyImageAt(const WebPoint&) = 0;
335 // Notifies the WebView that a drag has terminated.
336 virtual void dragSourceEndedAt(
337 const WebPoint& clientPoint, const WebPoint& screenPoint,
338 WebDragOperation operation) = 0;
340 // Notifies the WebView that a drag is going on.
341 virtual void dragSourceMovedTo(
342 const WebPoint& clientPoint, const WebPoint& screenPoint,
343 WebDragOperation operation) = 0;
345 // Notfies the WebView that the system drag and drop operation has ended.
346 virtual void dragSourceSystemDragEnded() = 0;
348 // Callback methods when a drag-and-drop operation is trying to drop
349 // something on the WebView.
350 virtual WebDragOperation dragTargetDragEnter(
352 const WebPoint& clientPoint, const WebPoint& screenPoint,
353 WebDragOperationsMask operationsAllowed,
354 int keyModifiers) = 0;
355 virtual WebDragOperation dragTargetDragOver(
356 const WebPoint& clientPoint, const WebPoint& screenPoint,
357 WebDragOperationsMask operationsAllowed,
358 int keyModifiers) = 0;
359 virtual void dragTargetDragLeave() = 0;
360 virtual void dragTargetDrop(
361 const WebPoint& clientPoint, const WebPoint& screenPoint,
362 int keyModifiers) = 0;
364 // Retrieves a list of spelling markers.
365 virtual void spellingMarkers(WebVector<uint32_t>* markers) = 0;
368 // Support for resource loading initiated by plugins -------------------
370 // Returns next unused request identifier which is unique within the
372 virtual unsigned long createUniqueIdentifierForRequest() = 0;
375 // Developer tools -----------------------------------------------------
377 // Inspect a particular point in the WebView. (x = -1 || y = -1) is a
378 // special case, meaning inspect the current page and not a specific
380 virtual void inspectElementAt(const WebPoint&) = 0;
382 // Settings used by the inspector.
383 virtual WebString inspectorSettings() const = 0;
384 virtual void setInspectorSettings(const WebString&) = 0;
385 virtual bool inspectorSetting(const WebString& key,
386 WebString* value) const = 0;
387 virtual void setInspectorSetting(const WebString& key,
388 const WebString& value) = 0;
390 // Set an override of device scale factor passed from WebView to
391 // compositor. Pass zero to cancel override. This is used to implement
392 // device metrics emulation.
393 virtual void setCompositorDeviceScaleFactorOverride(float) = 0;
395 // Set offset and scale on the root composited layer. This is used
396 // to implement device metrics emulation.
397 virtual void setRootLayerTransform(const WebSize& offset, float scale) = 0;
399 // The embedder may optionally engage a WebDevToolsAgent. This may only
400 // be set once per WebView.
401 virtual WebDevToolsAgent* devToolsAgent() = 0;
404 // Accessibility -------------------------------------------------------
406 // Returns the accessibility object for this view.
407 virtual WebAXObject accessibilityObject() = 0;
410 // Context menu --------------------------------------------------------
412 virtual void performCustomContextMenuAction(unsigned action) = 0;
414 // Shows a context menu for the currently focused element.
415 virtual void showContextMenu() = 0;
418 // SmartClip support ---------------------------------------------------
420 virtual WebString getSmartClipData(WebRect) = 0;
423 // Popup menu ----------------------------------------------------------
425 // Sets whether select popup menus should be rendered by the browser.
426 BLINK_EXPORT static void setUseExternalPopupMenus(bool);
428 // Hides any popup (suggestions, selects...) that might be showing.
429 virtual void hidePopups() = 0;
432 // Visited link state --------------------------------------------------
434 // Tells all WebView instances to update the visited link state for the
436 BLINK_EXPORT static void updateVisitedLinkState(unsigned long long hash);
438 // Tells all WebView instances to update the visited state for all
440 BLINK_EXPORT static void resetVisitedLinkState();
443 // Custom colors -------------------------------------------------------
445 virtual void setSelectionColors(unsigned activeBackgroundColor,
446 unsigned activeForegroundColor,
447 unsigned inactiveBackgroundColor,
448 unsigned inactiveForegroundColor) = 0;
450 // Injected style ------------------------------------------------------
452 // Treats |sourceCode| as a CSS author style sheet and injects it into all Documents whose URLs match |patterns|,
453 // in the frames specified by the last argument.
454 BLINK_EXPORT static void injectStyleSheet(const WebString& sourceCode, const WebVector<WebString>& patterns, StyleInjectionTarget);
455 BLINK_EXPORT static void removeInjectedStyleSheets();
457 // Modal dialog support ------------------------------------------------
459 // Call these methods before and after running a nested, modal event loop
460 // to suspend script callbacks and resource loads.
461 BLINK_EXPORT static void willEnterModalLoop();
462 BLINK_EXPORT static void didExitModalLoop();
464 // Called to inform the WebView that a wheel fling animation was started externally (for instance
465 // by the compositor) but must be completed by the WebView.
466 virtual void transferActiveWheelFlingAnimation(const WebActiveWheelFlingParameters&) = 0;
468 // Cancels an active fling, returning true if a fling was active.
469 virtual bool endActiveFlingAnimation() = 0;
471 virtual bool setEditableSelectionOffsets(int start, int end) = 0;
472 virtual bool setCompositionFromExistingText(int compositionStart, int compositionEnd, const WebVector<WebCompositionUnderline>& underlines) = 0;
473 virtual void extendSelectionAndDelete(int before, int after) = 0;
475 virtual bool isSelectionEditable() const = 0;
477 virtual void setShowPaintRects(bool) = 0;
478 virtual void setShowFPSCounter(bool) = 0;
479 virtual void setContinuousPaintingEnabled(bool) = 0;
480 virtual void setShowScrollBottleneckRects(bool) = 0;
482 // Visibility -----------------------------------------------------------
484 // Sets the visibility of the WebView.
485 virtual void setVisibilityState(WebPageVisibilityState visibilityState,
486 bool isInitialState) { }
488 // PageOverlay ----------------------------------------------------------
490 // Adds/removes page overlay to this WebView. These functions change the
491 // graphical appearance of the WebView. WebPageOverlay paints the
492 // contents of the page overlay. It also provides an z-order number for
493 // the page overlay. The z-order number defines the paint order the page
494 // overlays. Page overlays with larger z-order number will be painted after
495 // page overlays with smaller z-order number. That is, they appear above
496 // the page overlays with smaller z-order number. If two page overlays have
497 // the same z-order number, the later added one will be on top.
498 virtual void addPageOverlay(WebPageOverlay*, int /*z-order*/) = 0;
499 virtual void removePageOverlay(WebPageOverlay*) = 0;
501 // Testing functionality for TestRunner ---------------------------------