1/* 2 * Copyright (C) 2009, 2010, 2011, 2012 Google Inc. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are 6 * met: 7 * 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 13 * distribution. 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. 17 * 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. 29 */ 30 31#ifndef WebView_h 32#define WebView_h 33 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" 40 41namespace WebKit { 42 43class WebAccessibilityObject; 44class WebAutofillClient; 45class WebDevToolsAgent; 46class WebDevToolsAgentClient; 47class WebDragData; 48class WebFrame; 49class WebFrameClient; 50class WebGraphicsContext3D; 51class WebHitTestResult; 52class WebNode; 53class WebPageOverlay; 54class WebPermissionClient; 55class WebPrerendererClient; 56class WebRange; 57class WebSettings; 58class WebSpellCheckClient; 59class WebString; 60class WebPasswordGeneratorClient; 61class WebValidationMessageClient; 62class WebViewBenchmarkSupport; 63class WebViewClient; 64struct WebActiveWheelFlingParameters; 65struct WebMediaPlayerAction; 66struct WebPluginAction; 67struct WebPoint; 68struct WebWindowFeatures; 69 70class WebView : public WebWidget { 71public: 72 WEBKIT_EXPORT static const double textSizeMultiplierRatio; 73 WEBKIT_EXPORT static const double minTextSizeMultiplier; 74 WEBKIT_EXPORT static const double maxTextSizeMultiplier; 75 WEBKIT_EXPORT static const float minPageScaleFactor; 76 WEBKIT_EXPORT static const float maxPageScaleFactor; 77 78 // Controls which frames user content is injected into. 79 enum UserContentInjectIn { 80 UserContentInjectInAllFrames, 81 UserContentInjectInTopFrameOnly 82 }; 83 84 // Controls which documents user styles are injected into. 85 enum UserStyleInjectionTime { 86 UserStyleInjectInExistingDocuments, 87 UserStyleInjectInSubsequentDocuments 88 }; 89 90 91 // Initialization ------------------------------------------------------ 92 93 // Creates a WebView that is NOT yet initialized. You will need to 94 // call initializeMainFrame to finish the initialization. It is valid 95 // to pass null client pointers. 96 WEBKIT_EXPORT static WebView* create(WebViewClient*); 97 98 // After creating a WebView, you should immediately call this method. 99 // You can optionally modify the settings before calling this method. 100 // The WebFrameClient will receive events for the main frame and any 101 // child frames. It is valid to pass a null WebFrameClient pointer. 102 virtual void initializeMainFrame(WebFrameClient*) = 0; 103 104 virtual void initializeHelperPluginFrame(WebFrameClient*) = 0; 105 106 // Initializes the various client interfaces. 107 virtual void setAutofillClient(WebAutofillClient*) = 0; 108 virtual void setDevToolsAgentClient(WebDevToolsAgentClient*) = 0; 109 virtual void setPermissionClient(WebPermissionClient*) = 0; 110 virtual void setPrerendererClient(WebPrerendererClient*) = 0; 111 virtual void setSpellCheckClient(WebSpellCheckClient*) = 0; 112 virtual void setValidationMessageClient(WebValidationMessageClient*) = 0; 113 virtual void setPasswordGeneratorClient(WebPasswordGeneratorClient*) = 0; 114 115 // Options ------------------------------------------------------------- 116 117 // The returned pointer is valid for the lifetime of the WebView. 118 virtual WebSettings* settings() = 0; 119 120 // Corresponds to the encoding of the main frame. Setting the page 121 // encoding may cause the main frame to reload. 122 virtual WebString pageEncoding() const = 0; 123 virtual void setPageEncoding(const WebString&) = 0; 124 125 // Makes the WebView transparent. This is useful if you want to have 126 // some custom background rendered behind it. 127 virtual bool isTransparent() const = 0; 128 virtual void setIsTransparent(bool) = 0; 129 130 // Sets the base color used for this WebView's background. This is in effect 131 // the default background color used for pages with no background-color 132 // style in effect, or used as the alpha-blended basis for any pages with 133 // translucent background-color style. (For pages with opaque 134 // background-color style, this property is effectively ignored). 135 // Setting this takes effect for the currently loaded page, if any, and 136 // persists across subsequent navigations. Defaults to white prior to the 137 // first call to this method. 138 virtual void setBaseBackgroundColor(WebColor) = 0; 139 140 // Controls whether pressing Tab key advances focus to links. 141 virtual bool tabsToLinks() const = 0; 142 virtual void setTabsToLinks(bool) = 0; 143 144 // Method that controls whether pressing Tab key cycles through page 145 // elements or inserts a '\t' char in the focused text area. 146 virtual bool tabKeyCyclesThroughElements() const = 0; 147 virtual void setTabKeyCyclesThroughElements(bool) = 0; 148 149 // Controls the WebView's active state, which may affect the rendering 150 // of elements on the page (i.e., tinting of input elements). 151 virtual bool isActive() const = 0; 152 virtual void setIsActive(bool) = 0; 153 154 // Allows disabling domain relaxation. 155 virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0; 156 157 // Allows setting the state of the various bars exposed via BarProp 158 // properties on the window object. The size related fields of 159 // WebWindowFeatures are ignored. 160 virtual void setWindowFeatures(const WebWindowFeatures&) = 0; 161 162 163 // Closing ------------------------------------------------------------- 164 165 // Runs beforeunload handlers for the current page, returning false if 166 // any handler suppressed unloading. 167 virtual bool dispatchBeforeUnloadEvent() = 0; 168 169 // Runs unload handlers for the current page. 170 virtual void dispatchUnloadEvent() = 0; 171 172 173 // Frames -------------------------------------------------------------- 174 175 virtual WebFrame* mainFrame() = 0; 176 177 // Returns the frame identified by the given name. This method 178 // supports pseudo-names like _self, _top, and _blank. It traverses 179 // the entire frame tree containing this tree looking for a frame that 180 // matches the given name. If the optional relativeToFrame parameter 181 // is specified, then the search begins with the given frame and its 182 // children. 183 virtual WebFrame* findFrameByName( 184 const WebString& name, WebFrame* relativeToFrame = 0) = 0; 185 186 187 // Focus --------------------------------------------------------------- 188 189 virtual WebFrame* focusedFrame() = 0; 190 virtual void setFocusedFrame(WebFrame*) = 0; 191 192 // Focus the first (last if reverse is true) focusable node. 193 virtual void setInitialFocus(bool reverse) = 0; 194 195 // Clears the focused node (and selection if a text field is focused) 196 // to ensure that a text field on the page is not eating keystrokes we 197 // send it. 198 virtual void clearFocusedNode() = 0; 199 200 // Scrolls the node currently in focus into view. 201 virtual void scrollFocusedNodeIntoView() = 0; 202 203 // Scrolls the node currently in focus into |rect|, where |rect| is in 204 // window space. 205 virtual void scrollFocusedNodeIntoRect(const WebRect&) { } 206 207 // Advance the focus of the WebView forward to the next element or to the 208 // previous element in the tab sequence (if reverse is true). 209 virtual void advanceFocus(bool reverse) { } 210 211 // Animate a scale into the specified find-in-page rect. 212 virtual void zoomToFindInPageRect(const WebRect&) = 0; 213 214 // Animate a scale into the specified rect where multiple targets were 215 // found from previous tap gesture. 216 // Returns false if it doesn't do any zooming. 217 virtual bool zoomToMultipleTargetsRect(const WebRect&) = 0; 218 219 220 // Zoom ---------------------------------------------------------------- 221 222 // Returns the current zoom level. 0 is "original size", and each increment 223 // above or below represents zooming 20% larger or smaller to default limits 224 // of 300% and 50% of original size, respectively. Only plugins use 225 // non whole-numbers, since they might choose to have specific zoom level so 226 // that fixed-width content is fit-to-page-width, for example. 227 virtual double zoomLevel() = 0; 228 229 // Changes the zoom level to the specified level, clamping at the limits 230 // noted above, and returns the current zoom level after applying the 231 // change. 232 virtual double setZoomLevel(double) = 0; 233 234 // FIXME: Deprecated, delete once Chromium side is updated. 235 virtual double setZoomLevel(bool textOnly, double zoomLevel) = 0; 236 237 // Updates the zoom limits for this view. 238 virtual void zoomLimitsChanged(double minimumZoomLevel, 239 double maximumZoomLevel) = 0; 240 241 // Helper functions to convert between zoom level and zoom factor. zoom 242 // factor is zoom percent / 100, so 300% = 3.0. 243 WEBKIT_EXPORT static double zoomLevelToZoomFactor(double zoomLevel); 244 WEBKIT_EXPORT static double zoomFactorToZoomLevel(double factor); 245 246 // Returns the current text zoom factor, where 1.0 is the normal size, > 1.0 247 // is scaled up and < 1.0 is scaled down. 248 virtual float textZoomFactor() = 0; 249 250 // Scales the text in the page by a factor of textZoomFactor. 251 // Note: this has no effect on plugins. 252 virtual float setTextZoomFactor(float) = 0; 253 254 // Sets the initial page scale to the given factor. This scale setting overrides 255 // page scale set in the page's viewport meta tag. 256 virtual void setInitialPageScaleOverride(float) = 0; 257 258 // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0 259 // is scaled up, < 1.0 is scaled down. 260 virtual float pageScaleFactor() const = 0; 261 262 // Scales the page and the scroll offset by a given factor, while ensuring 263 // that the new scroll position does not go beyond the edge of the page. 264 virtual void setPageScaleFactorPreservingScrollOffset(float) = 0; 265 266 // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y). 267 // setPageScaleFactor() magnifies and shrinks a page without affecting layout. 268 // On the other hand, zooming affects layout of the page. 269 virtual void setPageScaleFactor(float scaleFactor, const WebPoint& origin) = 0; 270 271 // PageScaleFactor will be force-clamped between minPageScale and maxPageScale 272 // (and these values will persist until setPageScaleFactorLimits is called 273 // again). 274 virtual void setPageScaleFactorLimits(float minPageScale, float maxPageScale) = 0; 275 276 virtual float minimumPageScaleFactor() const = 0; 277 virtual float maximumPageScaleFactor() const = 0; 278 279 // Save the WebView's current scroll and scale state. Each call to this function 280 // overwrites the previously saved scroll and scale state. 281 virtual void saveScrollAndScaleState() = 0; 282 283 // Restore the previously saved scroll and scale state. After restoring the 284 // state, this function deletes any saved scroll and scale state. 285 virtual void restoreScrollAndScaleState() = 0; 286 287 // Reset any saved values for the scroll and scale state. 288 virtual void resetScrollAndScaleState() = 0; 289 290 // Prevent the web page from setting min/max scale via the viewport meta 291 // tag. This is an accessibility feature that lets folks zoom in to web 292 // pages even if the web page tries to block scaling. 293 virtual void setIgnoreViewportTagScaleLimits(bool) = 0; 294 295 // Returns the "preferred" contents size, defined as the preferred minimum width of the main document's contents 296 // and the minimum height required to display the main document without scrollbars. 297 // The returned size has the page zoom factor applied. 298 virtual WebSize contentsPreferredMinimumSize() = 0; 299 300 // The ratio of the current device's screen DPI to the target device's screen DPI. 301 virtual float deviceScaleFactor() const = 0; 302 303 // Sets the ratio as computed by computePageScaleConstraints. 304 virtual void setDeviceScaleFactor(float) = 0; 305 306 307 // Fixed Layout -------------------------------------------------------- 308 309 // In fixed layout mode, the layout of the page is independent of the 310 // view port size, given by WebWidget::size(). 311 312 virtual bool isFixedLayoutModeEnabled() const = 0; 313 virtual void enableFixedLayoutMode(bool enable) = 0; 314 315 virtual WebSize fixedLayoutSize() const = 0; 316 virtual void setFixedLayoutSize(const WebSize&) = 0; 317 318 319 // Auto-Resize ----------------------------------------------------------- 320 321 // In auto-resize mode, the view is automatically adjusted to fit the html 322 // content within the given bounds. 323 virtual void enableAutoResizeMode( 324 const WebSize& minSize, 325 const WebSize& maxSize) = 0; 326 327 // Turn off auto-resize. 328 virtual void disableAutoResizeMode() = 0; 329 330 // Media --------------------------------------------------------------- 331 332 // Performs the specified media player action on the node at the given location. 333 virtual void performMediaPlayerAction( 334 const WebMediaPlayerAction&, const WebPoint& location) = 0; 335 336 // Performs the specified plugin action on the node at the given location. 337 virtual void performPluginAction( 338 const WebPluginAction&, const WebPoint& location) = 0; 339 340 341 // Data exchange ------------------------------------------------------- 342 343 // Do a hit test at given point and return the HitTestResult. 344 virtual WebHitTestResult hitTestResultAt(const WebPoint&) = 0; 345 346 // Copy to the clipboard the image located at a particular point in the 347 // WebView (if there is such an image) 348 virtual void copyImageAt(const WebPoint&) = 0; 349 350 // Notifies the WebView that a drag has terminated. 351 virtual void dragSourceEndedAt( 352 const WebPoint& clientPoint, const WebPoint& screenPoint, 353 WebDragOperation operation) = 0; 354 355 // Notifies the WebView that a drag is going on. 356 virtual void dragSourceMovedTo( 357 const WebPoint& clientPoint, const WebPoint& screenPoint, 358 WebDragOperation operation) = 0; 359 360 // Notfies the WebView that the system drag and drop operation has ended. 361 virtual void dragSourceSystemDragEnded() = 0; 362 363 // Callback methods when a drag-and-drop operation is trying to drop 364 // something on the WebView. 365 virtual WebDragOperation dragTargetDragEnter( 366 const WebDragData&, 367 const WebPoint& clientPoint, const WebPoint& screenPoint, 368 WebDragOperationsMask operationsAllowed, 369 int keyModifiers) = 0; 370 virtual WebDragOperation dragTargetDragOver( 371 const WebPoint& clientPoint, const WebPoint& screenPoint, 372 WebDragOperationsMask operationsAllowed, 373 int keyModifiers) = 0; 374 virtual void dragTargetDragLeave() = 0; 375 virtual void dragTargetDrop( 376 const WebPoint& clientPoint, const WebPoint& screenPoint, 377 int keyModifiers) = 0; 378 379 // Retrieves a list of spelling markers. 380 virtual void spellingMarkers(WebVector<uint32_t>* markers) = 0; 381 382 383 // Support for resource loading initiated by plugins ------------------- 384 385 // Returns next unused request identifier which is unique within the 386 // parent Page. 387 virtual unsigned long createUniqueIdentifierForRequest() = 0; 388 389 390 // Developer tools ----------------------------------------------------- 391 392 // Inspect a particular point in the WebView. (x = -1 || y = -1) is a 393 // special case, meaning inspect the current page and not a specific 394 // point. 395 virtual void inspectElementAt(const WebPoint&) = 0; 396 397 // Settings used by the inspector. 398 virtual WebString inspectorSettings() const = 0; 399 virtual void setInspectorSettings(const WebString&) = 0; 400 virtual bool inspectorSetting(const WebString& key, 401 WebString* value) const = 0; 402 virtual void setInspectorSetting(const WebString& key, 403 const WebString& value) = 0; 404 405 // The embedder may optionally engage a WebDevToolsAgent. This may only 406 // be set once per WebView. 407 virtual WebDevToolsAgent* devToolsAgent() = 0; 408 409 410 // Accessibility ------------------------------------------------------- 411 412 // Returns the accessibility object for this view. 413 virtual WebAccessibilityObject accessibilityObject() = 0; 414 415 416 // Autofill ----------------------------------------------------------- 417 418 // Notifies the WebView that Autofill suggestions are available for a node. 419 // |itemIDs| is a vector of IDs for the menu items. A positive itemID is a 420 // unique ID for the Autofill entries. Other MenuItemIDs are defined in 421 // WebAutofillClient.h 422 virtual void applyAutofillSuggestions( 423 const WebNode&, 424 const WebVector<WebString>& names, 425 const WebVector<WebString>& labels, 426 const WebVector<WebString>& icons, 427 const WebVector<int>& itemIDs, 428 int separatorIndex = -1) = 0; 429 430 // Hides any popup (suggestions, selects...) that might be showing. 431 virtual void hidePopups() = 0; 432 433 virtual void selectAutofillSuggestionAtIndex(unsigned listIndex) = 0; 434 435 436 // Context menu -------------------------------------------------------- 437 438 virtual void performCustomContextMenuAction(unsigned action) = 0; 439 440 // Shows a context menu for the currently focused element. 441 virtual void showContextMenu() = 0; 442 443 444 // Popup menu ---------------------------------------------------------- 445 446 // Sets whether select popup menus should be rendered by the browser. 447 WEBKIT_EXPORT static void setUseExternalPopupMenus(bool); 448 449 450 // Visited link state -------------------------------------------------- 451 452 // Tells all WebView instances to update the visited link state for the 453 // specified hash. 454 WEBKIT_EXPORT static void updateVisitedLinkState(unsigned long long hash); 455 456 // Tells all WebView instances to update the visited state for all 457 // their links. 458 WEBKIT_EXPORT static void resetVisitedLinkState(); 459 460 461 // Custom colors ------------------------------------------------------- 462 463 virtual void setScrollbarColors(unsigned inactiveColor, 464 unsigned activeColor, 465 unsigned trackColor) = 0; 466 467 virtual void setSelectionColors(unsigned activeBackgroundColor, 468 unsigned activeForegroundColor, 469 unsigned inactiveBackgroundColor, 470 unsigned inactiveForegroundColor) = 0; 471 472 // User scripts -------------------------------------------------------- 473 WEBKIT_EXPORT static void addUserStyleSheet(const WebString& sourceCode, 474 const WebVector<WebString>& patterns, 475 UserContentInjectIn injectIn, 476 UserStyleInjectionTime injectionTime = UserStyleInjectInSubsequentDocuments); 477 WEBKIT_EXPORT static void removeAllUserContent(); 478 479 // Modal dialog support ------------------------------------------------ 480 481 // Call these methods before and after running a nested, modal event loop 482 // to suspend script callbacks and resource loads. 483 WEBKIT_EXPORT static void willEnterModalLoop(); 484 WEBKIT_EXPORT static void didExitModalLoop(); 485 486 // Called to inform the WebView that a wheel fling animation was started externally (for instance 487 // by the compositor) but must be completed by the WebView. 488 virtual void transferActiveWheelFlingAnimation(const WebActiveWheelFlingParameters&) = 0; 489 490 virtual bool setEditableSelectionOffsets(int start, int end) = 0; 491 virtual bool setCompositionFromExistingText(int compositionStart, int compositionEnd, const WebVector<WebCompositionUnderline>& underlines) = 0; 492 virtual void extendSelectionAndDelete(int before, int after) = 0; 493 494 virtual bool isSelectionEditable() const = 0; 495 496 virtual void setShowPaintRects(bool) = 0; 497 virtual void setShowFPSCounter(bool) = 0; 498 virtual void setContinuousPaintingEnabled(bool) = 0; 499 virtual void setShowScrollBottleneckRects(bool) = 0; 500 501 // Benchmarking support ------------------------------------------------- 502 503 virtual WebViewBenchmarkSupport* benchmarkSupport() { return 0; } 504 505 // Visibility ----------------------------------------------------------- 506 507 // Sets the visibility of the WebView. 508 virtual void setVisibilityState(WebPageVisibilityState visibilityState, 509 bool isInitialState) { } 510 511 // PageOverlay ---------------------------------------------------------- 512 513 // Adds/removes page overlay to this WebView. These functions change the 514 // graphical appearance of the WebView. WebPageOverlay paints the 515 // contents of the page overlay. It also provides an z-order number for 516 // the page overlay. The z-order number defines the paint order the page 517 // overlays. Page overlays with larger z-order number will be painted after 518 // page overlays with smaller z-order number. That is, they appear above 519 // the page overlays with smaller z-order number. If two page overlays have 520 // the same z-order number, the later added one will be on top. 521 virtual void addPageOverlay(WebPageOverlay*, int /*z-order*/) = 0; 522 virtual void removePageOverlay(WebPageOverlay*) = 0; 523 524 // Testing functionality for TestRunner --------------------------------- 525 526protected: 527 ~WebView() {} 528}; 529 530} // namespace WebKit 531 532#endif 533