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