2009-11-27 Yury Semikhatsky <yurys@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     // Change the text zoom level.  It will make the zoom level 20% larger
139     // or smaller.  If textOnly is set, the text size will be changed.
140     // When unset, the entire page's zoom factor will be changed.
141     //
142     // You can only have either text zoom or full page zoom at one time.
143     // Changing the mode will change things in weird ways.  Generally the
144     // app should only support text zoom or full page zoom, and not both.
145     //
146     // zoomDefault will reset both full page and text zoom.
147     virtual void zoomIn(bool textOnly) = 0;
148     virtual void zoomOut(bool textOnly) = 0;
149     virtual void zoomDefault() = 0;
150
151
152     // Media ---------------------------------------------------------------
153
154     // Performs the specified action on the node at the given location.
155     virtual void performMediaPlayerAction(
156         const WebMediaPlayerAction&, const WebPoint& location) = 0;
157
158
159     // Data exchange -------------------------------------------------------
160
161     // Copy to the clipboard the image located at a particular point in the
162     // WebView (if there is such an image)
163     virtual void copyImageAt(const WebPoint&) = 0;
164
165     // Notifies the WebView that a drag has terminated.
166     virtual void dragSourceEndedAt(
167         const WebPoint& clientPoint, const WebPoint& screenPoint,
168         WebDragOperation operation) = 0;
169
170     // Notfies the WebView that the system drag and drop operation has ended.
171     virtual void dragSourceSystemDragEnded() = 0;
172
173     // Callback methods when a drag-and-drop operation is trying to drop
174     // something on the WebView.
175     virtual WebDragOperation dragTargetDragEnter(
176         const WebDragData&, int identity,
177         const WebPoint& clientPoint, const WebPoint& screenPoint,
178         WebDragOperationsMask operationsAllowed) = 0;
179     virtual WebDragOperation dragTargetDragOver(
180         const WebPoint& clientPoint, const WebPoint& screenPoint,
181         WebDragOperationsMask operationsAllowed) = 0;
182     virtual void dragTargetDragLeave() = 0;
183     virtual void dragTargetDrop(
184         const WebPoint& clientPoint, const WebPoint& screenPoint) = 0;
185
186     virtual int dragIdentity() = 0;
187
188     // Helper method for drag and drop target operations: override the
189     // default drop effect with either a "copy" (accept true) or "none"
190     // (accept false) effect.  Return true on success.
191     virtual bool setDropEffect(bool accept) = 0;
192
193
194     // Support for resource loading initiated by plugins -------------------
195
196     // Returns next unused request identifier which is unique within the
197     // parent Page.
198     virtual unsigned long createUniqueIdentifierForRequest() = 0;
199
200
201     // Developer tools -----------------------------------------------------
202
203     // Inspect a particular point in the WebView.  (x = -1 || y = -1) is a
204     // special case, meaning inspect the current page and not a specific
205     // point.
206     virtual void inspectElementAt(const WebPoint&) = 0;
207
208     // Settings used by the inspector.
209     virtual WebString inspectorSettings() const = 0;
210     virtual void setInspectorSettings(const WebString&) = 0;
211
212     // The embedder may optionally engage a WebDevToolsAgent.  This may only
213     // be set once per WebView.
214     virtual WebDevToolsAgent* devToolsAgent() = 0;
215     virtual void setDevToolsAgent(WebDevToolsAgent*) = 0;
216
217
218     // Accessibility -------------------------------------------------------
219
220     // Returns the accessibility object for this view.
221     virtual WebAccessibilityObject accessibilityObject() = 0;
222
223
224     // Autofill ------------------------------------------------------------
225
226     // Notifies the WebView that autofill suggestions are available for a node.
227     virtual void applyAutofillSuggestions(
228         const WebNode&,
229         const WebVector<WebString>& suggestions,
230         int defaultSuggestionIndex) = 0;
231
232     // Hides the autofill popup if any are showing.
233     virtual void hideAutofillPopup() = 0;
234
235
236     // Visited link state --------------------------------------------------
237
238     // Tells all WebView instances to update the visited link state for the
239     // specified hash.
240     WEBKIT_API static void updateVisitedLinkState(unsigned long long hash);
241
242     // Tells all WebView instances to update the visited state for all
243     // their links.
244     WEBKIT_API static void resetVisitedLinkState();
245
246
247 protected:
248     ~WebView() {}
249 };
250
251 } // namespace WebKit
252
253 #endif