c77f452d0f6c2d0cdf494d4538e8508c70649dc4
[WebKit-https.git] / Source / WebKit / chromium / public / WebView.h
1 /*
2  * Copyright (C) 2009 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 "WebDragOperation.h"
35 #include "WebPageVisibilityState.h"
36 #include "WebString.h"
37 #include "WebVector.h"
38 #include "WebWidget.h"
39
40 namespace WebKit {
41
42 class WebAccessibilityObject;
43 class WebAutofillClient;
44 class WebDevToolsAgent;
45 class WebDevToolsAgentClient;
46 class WebDragData;
47 class WebFrame;
48 class WebFrameClient;
49 class WebGraphicsContext3D;
50 class WebNode;
51 class WebPermissionClient;
52 class WebSettings;
53 class WebSpellCheckClient;
54 class WebString;
55 class WebViewClient;
56 struct WebMediaPlayerAction;
57 struct WebPoint;
58
59 class WebView : public WebWidget {
60 public:
61     WEBKIT_EXPORT static const double textSizeMultiplierRatio;
62     WEBKIT_EXPORT static const double minTextSizeMultiplier;
63     WEBKIT_EXPORT static const double maxTextSizeMultiplier;
64
65     // Controls the time that user scripts injected into the document run.
66     enum UserScriptInjectAt {
67         UserScriptInjectAtDocumentStart,
68         UserScriptInjectAtDocumentEnd
69     };
70
71     // Controls which frames user content is injected into.
72     enum UserContentInjectIn {
73         UserContentInjectInAllFrames,
74         UserContentInjectInTopFrameOnly
75     };
76
77     // Controls which documents user styles are injected into.
78     enum UserStyleInjectionTime {
79         UserStyleInjectInExistingDocuments,
80         UserStyleInjectInSubsequentDocuments
81     };
82
83
84     // Initialization ------------------------------------------------------
85
86     // Creates a WebView that is NOT yet initialized.  You will need to
87     // call initializeMainFrame to finish the initialization.  It is valid
88     // to pass null client pointers.
89     WEBKIT_EXPORT static WebView* create(WebViewClient*);
90
91     // After creating a WebView, you should immediately call this method.
92     // You can optionally modify the settings before calling this method.
93     // The WebFrameClient will receive events for the main frame and any
94     // child frames.  It is valid to pass a null WebFrameClient pointer.
95     virtual void initializeMainFrame(WebFrameClient*) = 0;
96
97     // Initializes the various client interfaces.
98     virtual void setAutofillClient(WebAutofillClient*) = 0;
99     virtual void setDevToolsAgentClient(WebDevToolsAgentClient*) = 0;
100     virtual void setPermissionClient(WebPermissionClient*) = 0;
101     virtual void setSpellCheckClient(WebSpellCheckClient*) = 0;
102
103
104     // Options -------------------------------------------------------------
105
106     // The returned pointer is valid for the lifetime of the WebView.
107     virtual WebSettings* settings() = 0;
108
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;
113
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;
118
119     // Controls whether pressing Tab key advances focus to links.
120     virtual bool tabsToLinks() const = 0;
121     virtual void setTabsToLinks(bool) = 0;
122
123     // Method that controls whether pressing Tab key cycles through page
124     // elements or inserts a '\t' char in the focused text area.
125     virtual bool tabKeyCyclesThroughElements() const = 0;
126     virtual void setTabKeyCyclesThroughElements(bool) = 0;
127
128     // Controls the WebView's active state, which may affect the rendering
129     // of elements on the page (i.e., tinting of input elements).
130     virtual bool isActive() const = 0;
131     virtual void setIsActive(bool) = 0;
132
133     // Allows disabling domain relaxation.
134     virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0;
135
136
137     // Closing -------------------------------------------------------------
138
139     // Runs beforeunload handlers for the current page, returning false if
140     // any handler suppressed unloading.
141     virtual bool dispatchBeforeUnloadEvent() = 0;
142
143     // Runs unload handlers for the current page.
144     virtual void dispatchUnloadEvent() = 0;
145
146
147     // Frames --------------------------------------------------------------
148
149     virtual WebFrame* mainFrame() = 0;
150
151     // Returns the frame identified by the given name.  This method
152     // supports pseudo-names like _self, _top, and _blank.  It traverses
153     // the entire frame tree containing this tree looking for a frame that
154     // matches the given name.  If the optional relativeToFrame parameter
155     // is specified, then the search begins with the given frame and its
156     // children.
157     virtual WebFrame* findFrameByName(
158         const WebString& name, WebFrame* relativeToFrame = 0) = 0;
159
160
161     // Focus ---------------------------------------------------------------
162
163     virtual WebFrame* focusedFrame() = 0;
164     virtual void setFocusedFrame(WebFrame*) = 0;
165
166     // Focus the first (last if reverse is true) focusable node.
167     virtual void setInitialFocus(bool reverse) = 0;
168
169     // Clears the focused node (and selection if a text field is focused)
170     // to ensure that a text field on the page is not eating keystrokes we
171     // send it.
172     virtual void clearFocusedNode() = 0;
173
174     // Scrolls the node currently in focus into view.
175     virtual void scrollFocusedNodeIntoView() = 0;
176
177     // Scrolls the node currently in focus into |rect|, where |rect| is in
178     // window space.
179     virtual void scrollFocusedNodeIntoRect(const WebRect&) { }
180
181
182     // Zoom ----------------------------------------------------------------
183
184     // Returns the current zoom level.  0 is "original size", and each increment
185     // above or below represents zooming 20% larger or smaller to default limits
186     // of 300% and 50% of original size, respectively.  Only plugins use
187     // non whole-numbers, since they might choose to have specific zoom level so
188     // that fixed-width content is fit-to-page-width, for example.
189     virtual double zoomLevel() = 0;
190
191     // Changes the zoom level to the specified level, clamping at the limits
192     // noted above, and returns the current zoom level after applying the
193     // change.
194     //
195     // If |textOnly| is set, only the text will be zoomed; otherwise the entire
196     // page will be zoomed. You can only have either text zoom or full page zoom
197     // at one time.  Changing the mode while the page is zoomed will have odd
198     // effects.
199     virtual double setZoomLevel(bool textOnly, double zoomLevel) = 0;
200
201     // Updates the zoom limits for this view.
202     virtual void zoomLimitsChanged(double minimumZoomLevel,
203                                    double maximumZoomLevel) = 0;
204
205     // Helper functions to convert between zoom level and zoom factor.  zoom
206     // factor is zoom percent / 100, so 300% = 3.0.
207     WEBKIT_EXPORT static double zoomLevelToZoomFactor(double zoomLevel);
208     WEBKIT_EXPORT static double zoomFactorToZoomLevel(double factor);
209
210     // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0
211     // is scaled up, < 1.0 is scaled down.
212     virtual float pageScaleFactor() const = 0;
213
214     // FIXME: Delete this once Chromium side has been updated.
215     virtual void scalePage(float scaleFactor, const WebPoint& origin) = 0;
216
217     // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y).
218     // setPageScaleFactor() magnifies and shrinks a page without affecting layout.
219     // On the other hand, zooming affects layout of the page.
220     virtual void setPageScaleFactor(float scaleFactor, const WebPoint& origin) = 0;
221
222     // The ratio of the current device's screen DPI to the target device's screen DPI.
223     virtual float deviceScaleFactor() const = 0;
224
225     // Sets the ratio as computed by computeViewportAttributes.
226     virtual void setDeviceScaleFactor(float) = 0;
227
228
229     // Fixed Layout --------------------------------------------------------
230
231     // In fixed layout mode, the layout of the page is independent of the
232     // view port size, given by WebWidget::size().
233
234     virtual bool isFixedLayoutModeEnabled() const = 0;
235     virtual void enableFixedLayoutMode(bool enable) = 0;
236
237     virtual WebSize fixedLayoutSize() const = 0;
238     virtual void setFixedLayoutSize(const WebSize&) = 0;
239
240
241     // Media ---------------------------------------------------------------
242
243     // Performs the specified action on the node at the given location.
244     virtual void performMediaPlayerAction(
245         const WebMediaPlayerAction&, const WebPoint& location) = 0;
246
247
248     // Data exchange -------------------------------------------------------
249
250     // Copy to the clipboard the image located at a particular point in the
251     // WebView (if there is such an image)
252     virtual void copyImageAt(const WebPoint&) = 0;
253
254     // Notifies the WebView that a drag has terminated.
255     virtual void dragSourceEndedAt(
256         const WebPoint& clientPoint, const WebPoint& screenPoint,
257         WebDragOperation operation) = 0;
258
259     // Notifies the WebView that a drag is going on.
260     virtual void dragSourceMovedTo(
261         const WebPoint& clientPoint, const WebPoint& screenPoint,
262         WebDragOperation operation) = 0;
263
264     // Notfies the WebView that the system drag and drop operation has ended.
265     virtual void dragSourceSystemDragEnded() = 0;
266
267     // Callback methods when a drag-and-drop operation is trying to drop
268     // something on the WebView.
269     virtual WebDragOperation dragTargetDragEnter(
270         const WebDragData&,
271         const WebPoint& clientPoint, const WebPoint& screenPoint,
272         WebDragOperationsMask operationsAllowed) = 0;
273     virtual WebDragOperation dragTargetDragOver(
274         const WebPoint& clientPoint, const WebPoint& screenPoint,
275         WebDragOperationsMask operationsAllowed) = 0;
276     virtual void dragTargetDragLeave() = 0;
277     virtual void dragTargetDrop(
278         const WebPoint& clientPoint, const WebPoint& screenPoint) = 0;
279
280
281     // Support for resource loading initiated by plugins -------------------
282
283     // Returns next unused request identifier which is unique within the
284     // parent Page.
285     virtual unsigned long createUniqueIdentifierForRequest() = 0;
286
287
288     // Developer tools -----------------------------------------------------
289
290     // Inspect a particular point in the WebView.  (x = -1 || y = -1) is a
291     // special case, meaning inspect the current page and not a specific
292     // point.
293     virtual void inspectElementAt(const WebPoint&) = 0;
294
295     // Settings used by the inspector.
296     virtual WebString inspectorSettings() const = 0;
297     virtual void setInspectorSettings(const WebString&) = 0;
298     virtual bool inspectorSetting(const WebString& key,
299                                   WebString* value) const = 0;
300     virtual void setInspectorSetting(const WebString& key,
301                                      const WebString& value) = 0;
302
303     // The embedder may optionally engage a WebDevToolsAgent.  This may only
304     // be set once per WebView.
305     virtual WebDevToolsAgent* devToolsAgent() = 0;
306
307
308     // Accessibility -------------------------------------------------------
309
310     // Returns the accessibility object for this view.
311     virtual WebAccessibilityObject accessibilityObject() = 0;
312
313
314     // Autofill  -----------------------------------------------------------
315
316     // Notifies the WebView that Autofill suggestions are available for a node.
317     // |uniqueIDs| is a vector of IDs that represent the unique ID of each
318     // Autofill profile in the suggestions popup. If a unique ID is 0, then the
319     // corresponding suggestion comes from Autocomplete rather than Autofill.
320     // If a unique ID is negative, then the corresponding "suggestion" is
321     // actually a user-facing warning, e.g. explaining why Autofill is
322     // unavailable for the current form.
323     virtual void applyAutofillSuggestions(
324         const WebNode&,
325         const WebVector<WebString>& names,
326         const WebVector<WebString>& labels,
327         const WebVector<WebString>& icons,
328         const WebVector<int>& uniqueIDs,
329         int separatorIndex) = 0;
330
331     // Hides any popup (suggestions, selects...) that might be showing.
332     virtual void hidePopups() = 0;
333
334
335     // Context menu --------------------------------------------------------
336
337     virtual void performCustomContextMenuAction(unsigned action) = 0;
338
339
340     // Popup menu ----------------------------------------------------------
341
342     // Sets whether select popup menus should be rendered by the browser.
343     WEBKIT_EXPORT static void setUseExternalPopupMenus(bool);
344
345
346     // Visited link state --------------------------------------------------
347
348     // Tells all WebView instances to update the visited link state for the
349     // specified hash.
350     WEBKIT_EXPORT static void updateVisitedLinkState(unsigned long long hash);
351
352     // Tells all WebView instances to update the visited state for all
353     // their links.
354     WEBKIT_EXPORT static void resetVisitedLinkState();
355
356
357     // Custom colors -------------------------------------------------------
358
359     virtual void setScrollbarColors(unsigned inactiveColor,
360                                     unsigned activeColor,
361                                     unsigned trackColor) = 0;
362
363     virtual void setSelectionColors(unsigned activeBackgroundColor,
364                                     unsigned activeForegroundColor,
365                                     unsigned inactiveBackgroundColor,
366                                     unsigned inactiveForegroundColor) = 0;
367
368     // User scripts --------------------------------------------------------
369     WEBKIT_EXPORT static void addUserScript(const WebString& sourceCode,
370                                             const WebVector<WebString>& patterns,
371                                             UserScriptInjectAt injectAt,
372                                             UserContentInjectIn injectIn);
373     WEBKIT_EXPORT static void addUserStyleSheet(const WebString& sourceCode,
374                                                 const WebVector<WebString>& patterns,
375                                                 UserContentInjectIn injectIn,
376                                                 UserStyleInjectionTime injectionTime = UserStyleInjectInSubsequentDocuments);
377     WEBKIT_EXPORT static void removeAllUserContent();
378
379     // Modal dialog support ------------------------------------------------
380
381     // Call these methods before and after running a nested, modal event loop
382     // to suspend script callbacks and resource loads.
383     WEBKIT_EXPORT static void willEnterModalLoop();
384     WEBKIT_EXPORT static void didExitModalLoop();
385
386     // GPU acceleration support --------------------------------------------
387
388     // Returns the (on-screen) WebGraphicsContext3D associated with
389     // this WebView. One will be created if it doesn't already exist.
390     // This is used to set up sharing between this context (which is
391     // that used by the compositor) and contexts for WebGL and other
392     // APIs.
393     virtual WebGraphicsContext3D* graphicsContext3D() = 0;
394
395     // Visibility -----------------------------------------------------------
396
397     // Sets the visibility of the WebView.
398     virtual void setVisibilityState(WebPageVisibilityState visibilityState,
399                                     bool isInitialState) { }
400
401
402     // Fullscreen -----------------------------------------------------------
403
404     virtual void exitFullscreen() = 0;
405
406     // Testing functionality for LayoutTestController -----------------------
407
408     // Simulates a compositor lost context.
409     virtual void loseCompositorContext(int numTimes) = 0;
410
411
412 protected:
413     ~WebView() {}
414 };
415
416 } // namespace WebKit
417
418 #endif