2009-12-07 Evan Martin <evan@chromium.org>
[WebKit-https.git] / 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 "WebWidget.h"
36
37 namespace WebKit {
38
39 class WebAccessibilityObject;
40 class WebDevToolsAgent;
41 class WebDragData;
42 class WebFrame;
43 class WebFrameClient;
44 class WebNode;
45 class WebSettings;
46 class WebString;
47 class WebViewClient;
48 struct WebMediaPlayerAction;
49 struct WebPoint;
50 template <typename T> class WebVector;
51
52 class WebView : public WebWidget {
53 public:
54     // Initialization ------------------------------------------------------
55
56     // Creates a WebView that is NOT yet initialized.  You will need to
57     // call initializeMainFrame to finish the initialization.  It is valid
58     // to pass a null WebViewClient pointer.
59     WEBKIT_API static WebView* create(WebViewClient*);
60
61     // After creating a WebView, you should immediately call this method.
62     // You can optionally modify the settings before calling this method.
63     // The WebFrameClient will receive events for the main frame and any
64     // child frames.  It is valid to pass a null WebFrameClient pointer.
65     virtual void initializeMainFrame(WebFrameClient*) = 0;
66
67
68     // Options -------------------------------------------------------------
69
70     // The returned pointer is valid for the lifetime of the WebView.
71     virtual WebSettings* settings() = 0;
72
73     // Corresponds to the encoding of the main frame.  Setting the page
74     // encoding may cause the main frame to reload.
75     virtual WebString pageEncoding() const = 0;
76     virtual void setPageEncoding(const WebString&) = 0;
77
78     // Makes the WebView transparent.  This is useful if you want to have
79     // some custom background rendered behind it.
80     virtual bool isTransparent() const = 0;
81     virtual void setIsTransparent(bool) = 0;
82
83     // Controls whether pressing Tab key advances focus to links.
84     virtual bool tabsToLinks() const = 0;
85     virtual void setTabsToLinks(bool) = 0;
86
87     // Method that controls whether pressing Tab key cycles through page
88     // elements or inserts a '\t' char in the focused text area.
89     virtual bool tabKeyCyclesThroughElements() const = 0;
90     virtual void setTabKeyCyclesThroughElements(bool) = 0;
91
92     // Controls the WebView's active state, which may affect the rendering
93     // of elements on the page (i.e., tinting of input elements).
94     virtual bool isActive() const = 0;
95     virtual void setIsActive(bool) = 0;
96
97
98     // Closing -------------------------------------------------------------
99
100     // Runs beforeunload handlers for the current page, returning false if
101     // any handler suppressed unloading.
102     virtual bool dispatchBeforeUnloadEvent() = 0;
103
104     // Runs unload handlers for the current page.
105     virtual void dispatchUnloadEvent() = 0;
106
107
108     // Frames --------------------------------------------------------------
109
110     virtual WebFrame* mainFrame() = 0;
111
112     // Returns the frame identified by the given name.  This method
113     // supports pseudo-names like _self, _top, and _blank.  It traverses
114     // the entire frame tree containing this tree looking for a frame that
115     // matches the given name.  If the optional relativeToFrame parameter
116     // is specified, then the search begins with the given frame and its
117     // children.
118     virtual WebFrame* findFrameByName(
119         const WebString& name, WebFrame* relativeToFrame = 0) = 0;
120
121
122     // Focus ---------------------------------------------------------------
123
124     virtual WebFrame* focusedFrame() = 0;
125     virtual void setFocusedFrame(WebFrame*) = 0;
126
127     // Focus the first (last if reverse is true) focusable node.
128     virtual void setInitialFocus(bool reverse) = 0;
129
130     // Clears the focused node (and selection if a text field is focused)
131     // to ensure that a text field on the page is not eating keystrokes we
132     // send it.
133     virtual void clearFocusedNode() = 0;
134
135
136     // Zoom ----------------------------------------------------------------
137
138     // Returns the current zoom level.  0 is "original size", and each increment
139     // above or below represents zooming 20% larger or smaller to limits of 300%
140     // and 50% of original size, respectively.
141     virtual int zoomLevel() = 0;
142
143     // Changes the zoom level to the specified level, clamping at the limits
144     // noted above, and returns the current zoom level after applying the
145     // change.
146     //
147     // If |textOnly| is set, only the text will be zoomed; otherwise the entire
148     // page will be zoomed. You can only have either text zoom or full page zoom
149     // at one time.  Changing the mode while the page is zoomed will have odd
150     // effects.
151     virtual int setZoomLevel(bool textOnly, int zoomLevel) = 0;
152
153
154     // Media ---------------------------------------------------------------
155
156     // Performs the specified action on the node at the given location.
157     virtual void performMediaPlayerAction(
158         const WebMediaPlayerAction&, const WebPoint& location) = 0;
159
160
161     // Data exchange -------------------------------------------------------
162
163     // Copy to the clipboard the image located at a particular point in the
164     // WebView (if there is such an image)
165     virtual void copyImageAt(const WebPoint&) = 0;
166
167     // Notifies the WebView that a drag has terminated.
168     virtual void dragSourceEndedAt(
169         const WebPoint& clientPoint, const WebPoint& screenPoint,
170         WebDragOperation operation) = 0;
171
172     // Notfies the WebView that the system drag and drop operation has ended.
173     virtual void dragSourceSystemDragEnded() = 0;
174
175     // Callback methods when a drag-and-drop operation is trying to drop
176     // something on the WebView.
177     virtual WebDragOperation dragTargetDragEnter(
178         const WebDragData&, int identity,
179         const WebPoint& clientPoint, const WebPoint& screenPoint,
180         WebDragOperationsMask operationsAllowed) = 0;
181     virtual WebDragOperation dragTargetDragOver(
182         const WebPoint& clientPoint, const WebPoint& screenPoint,
183         WebDragOperationsMask operationsAllowed) = 0;
184     virtual void dragTargetDragLeave() = 0;
185     virtual void dragTargetDrop(
186         const WebPoint& clientPoint, const WebPoint& screenPoint) = 0;
187
188     virtual int dragIdentity() = 0;
189
190     // Helper method for drag and drop target operations: override the
191     // default drop effect with either a "copy" (accept true) or "none"
192     // (accept false) effect.  Return true on success.
193     virtual bool setDropEffect(bool accept) = 0;
194
195
196     // Support for resource loading initiated by plugins -------------------
197
198     // Returns next unused request identifier which is unique within the
199     // parent Page.
200     virtual unsigned long createUniqueIdentifierForRequest() = 0;
201
202
203     // Developer tools -----------------------------------------------------
204
205     // Inspect a particular point in the WebView.  (x = -1 || y = -1) is a
206     // special case, meaning inspect the current page and not a specific
207     // point.
208     virtual void inspectElementAt(const WebPoint&) = 0;
209
210     // Settings used by the inspector.
211     virtual WebString inspectorSettings() const = 0;
212     virtual void setInspectorSettings(const WebString&) = 0;
213
214     // The embedder may optionally engage a WebDevToolsAgent.  This may only
215     // be set once per WebView.
216     virtual WebDevToolsAgent* devToolsAgent() = 0;
217     virtual void setDevToolsAgent(WebDevToolsAgent*) = 0;
218
219
220     // Accessibility -------------------------------------------------------
221
222     // Returns the accessibility object for this view.
223     virtual WebAccessibilityObject accessibilityObject() = 0;
224
225
226     // Autofill ------------------------------------------------------------
227
228     // Notifies the WebView that autofill suggestions are available for a node.
229     virtual void applyAutofillSuggestions(
230         const WebNode&,
231         const WebVector<WebString>& suggestions,
232         int defaultSuggestionIndex) = 0;
233
234     // Hides the autofill popup if any are showing.
235     virtual void hideAutofillPopup() = 0;
236
237
238     // Visited link state --------------------------------------------------
239
240     // Tells all WebView instances to update the visited link state for the
241     // specified hash.
242     WEBKIT_API static void updateVisitedLinkState(unsigned long long hash);
243
244     // Tells all WebView instances to update the visited state for all
245     // their links.
246     WEBKIT_API static void resetVisitedLinkState();
247
248     // Scrollbar colors ----------------------------------------------------
249     virtual void setScrollbarColors(unsigned inactiveColor,
250                                     unsigned activeColor,
251                                     unsigned trackColor) = 0;
252
253 protected:
254     ~WebView() {}
255 };
256
257 } // namespace WebKit
258
259 #endif