ac1658140217eb154db0e3d0ce93c83314dda9c1
[WebKit-https.git] / Source / WebKit / chromium / public / WebWidget.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 WebWidget_h
32 #define WebWidget_h
33
34 #include "WebCompositionUnderline.h"
35 #include "WebTextDirection.h"
36 #include "WebTextInputInfo.h"
37 #include "platform/WebCanvas.h"
38 #include "platform/WebCommon.h"
39 #include "platform/WebRect.h"
40 #include "platform/WebSize.h"
41
42 #define WEBKIT_HAS_NEW_FULLSCREEN_API 1
43 #define WEBWIDGET_HAS_SETCOMPOSITORSURFACEREADY 1
44 #define WEBWIDGET_HAS_PAINT_OPTIONS 1
45
46 namespace WebKit {
47
48 class WebInputEvent;
49 class WebMouseEvent;
50 class WebString;
51 struct WebPoint;
52 struct WebRenderingStats;
53 template <typename T> class WebVector;
54
55 class WebWidget {
56 public:
57     // This method closes and deletes the WebWidget.
58     virtual void close() { }
59
60     // Returns the current size of the WebWidget.
61     virtual WebSize size() { return WebSize(); }
62
63     // Used to group a series of resize events. For example, if the user
64     // drags a resizer then willStartLiveResize will be called, followed by a
65     // sequence of resize events, ending with willEndLiveResize when the user
66     // lets go of the resizer.
67     virtual void willStartLiveResize() { }
68
69     // Called to resize the WebWidget.
70     virtual void resize(const WebSize&) { }
71
72     // Ends a group of resize events that was started with a call to
73     // willStartLiveResize.
74     virtual void willEndLiveResize() { }
75
76     // Called to notify the WebWidget of entering/exiting fullscreen mode. The
77     // resize method may be called between will{Enter,Exit}FullScreen and
78     // did{Enter,Exit}FullScreen.
79     virtual void willEnterFullScreen() { }
80     virtual void didEnterFullScreen() { }
81     virtual void willExitFullScreen() { }
82     virtual void didExitFullScreen() { }
83
84     // Called to update imperative animation state. This should be called before
85     // paint, although the client can rate-limit these calls.
86     //
87     // FIXME: remove this function entirely when inversion patches land.
88     virtual void animate(double ignored) { }
89
90     // Called to layout the WebWidget. This MUST be called before Paint,
91     // and it may result in calls to WebWidgetClient::didInvalidateRect.
92     virtual void layout() { }
93
94     enum PaintOptions {
95         // Attempt to fulfill the painting request by reading back from the
96         // compositor, assuming we're using a compositor to render.
97         ReadbackFromCompositorIfAvailable,
98
99         // Force the widget to rerender onto the canvas using software. This
100         // mode ignores 3d transforms and ignores GPU-resident content, such
101         // as video, canvas, and WebGL.
102         //
103         // Note: This option exists on OS(ANDROID) and will hopefully be
104         //       removed once the link disambiguation feature renders using
105         //       the compositor.
106         ForceSoftwareRenderingAndIgnoreGPUResidentContent,
107     };
108
109     // Called to paint the rectangular region within the WebWidget
110     // onto the specified canvas at (viewPort.x,viewPort.y). You MUST call
111     // Layout before calling this method. It is okay to call paint
112     // multiple times once layout has been called, assuming no other
113     // changes are made to the WebWidget (e.g., once events are
114     // processed, it should be assumed that another call to layout is
115     // warranted before painting again).
116     virtual void paint(WebCanvas*, const WebRect& viewPort, PaintOptions = ReadbackFromCompositorIfAvailable) { }
117
118     // In non-threaded compositing mode, triggers compositing of the current
119     // layers onto the screen. You MUST call Layout before calling this method,
120     // for the same reasons described in the paint method above
121     //
122     // In threaded compositing mode, indicates that the widget should update
123     // itself, for example due to window damage. The redraw will begin
124     // asynchronously and perform layout and animation internally. Do not call
125     // animate or layout in this case.
126     virtual void composite(bool finish) = 0;
127
128     // Indicates that the compositing surface associated with this WebWidget is
129     // ready to use.
130     virtual void setCompositorSurfaceReady() = 0;
131
132     // Temporary method for the embedder to notify the WebWidget that the widget
133     // has taken damage, e.g. due to a window expose. This method will be
134     // removed when the WebWidget inversion patch lands --- http://crbug.com/112837
135     virtual void setNeedsRedraw() { }
136
137     // Temporary method for the embedder to check for throttled input. When this
138     // is true, the WebWidget is indicating that it would prefer to not receive
139     // additional input events until
140     // WebWidgetClient::didBecomeReadyForAdditionalInput is called.
141     //
142     // This method will be removed when the WebWidget inversion patch lands ---
143     // http://crbug.com/112837
144     virtual bool isInputThrottled() const { return false; }
145
146     // Called to inform the WebWidget of a change in theme.
147     // Implementors that cache rendered copies of widgets need to re-render
148     // on receiving this message
149     virtual void themeChanged() { }
150
151     // Called to inform the WebWidget of an input event. Returns true if
152     // the event has been processed, false otherwise.
153     virtual bool handleInputEvent(const WebInputEvent&) { return false; }
154
155     // Called to inform the WebWidget that mouse capture was lost.
156     virtual void mouseCaptureLost() { }
157
158     // Called to inform the WebWidget that it has gained or lost keyboard focus.
159     virtual void setFocus(bool) { }
160
161     // Called to inform the WebWidget of a new composition text.
162     // If selectionStart and selectionEnd has the same value, then it indicates
163     // the input caret position. If the text is empty, then the existing
164     // composition text will be cancelled.
165     // Returns true if the composition text was set successfully.
166     virtual bool setComposition(
167         const WebString& text,
168         const WebVector<WebCompositionUnderline>& underlines,
169         int selectionStart,
170         int selectionEnd) { return false; }
171
172     // Called to inform the WebWidget to confirm an ongoing composition.
173     // This method is same as confirmComposition(WebString());
174     // Returns true if there is an ongoing composition.
175     virtual bool confirmComposition() { return false; }
176
177     // Called to inform the WebWidget to confirm an ongoing composition with a
178     // new composition text. If the text is empty then the current composition
179     // text is confirmed. If there is no ongoing composition, then deletes the
180     // current selection and inserts the text. This method has no effect if
181     // there is no ongoing composition and the text is empty.
182     // Returns true if there is an ongoing composition or the text is inserted.
183     virtual bool confirmComposition(const WebString& text) { return false; }
184
185     // Fetches the character range of the current composition, also called the
186     // "marked range." Returns true and fills the out-paramters on success;
187     // returns false on failure.
188     virtual bool compositionRange(size_t* location, size_t* length) { return false; }
189
190     // Returns information about the current text input of this WebWidget.
191     virtual WebTextInputInfo textInputInfo() { return WebTextInputInfo(); }
192
193     // Returns the current text input type of this WebWidget.
194     // FIXME: Remove this method. It's redundant with textInputInfo().
195     virtual WebTextInputType textInputType() { return WebTextInputTypeNone; }
196
197     // Returns the start and end bounds of the current selection.
198     // If the selection range is empty, it returns the caret bounds.
199     virtual bool selectionBounds(WebRect& start, WebRect& end) const { return false; }
200
201     // Returns the text direction at the start and end bounds of the current selection.
202     // If the selection range is empty, it returns false.
203     virtual bool selectionTextDirection(WebTextDirection& start, WebTextDirection& end) const { return false; }
204
205     // Fetch the current selection range of this WebWidget. If there is no
206     // selection, it will output a 0-length range with the location at the
207     // caret. Returns true and fills the out-paramters on success; returns false
208     // on failure.
209     virtual bool caretOrSelectionRange(size_t* location, size_t* length) { return false; }
210
211     // Changes the text direction of the selected input node.
212     virtual void setTextDirection(WebTextDirection) { }
213
214     // Returns true if the WebWidget uses GPU accelerated compositing
215     // to render its contents.
216     virtual bool isAcceleratedCompositingActive() const { return false; }
217
218     // Calling WebWidgetClient::requestPointerLock() will result in one
219     // return call to didAcquirePointerLock() or didNotAcquirePointerLock().
220     virtual void didAcquirePointerLock() { }
221     virtual void didNotAcquirePointerLock() { }
222
223     // Pointer lock was held, but has been lost. This may be due to a
224     // request via WebWidgetClient::requestPointerUnlock(), or for other
225     // reasons such as the user exiting lock, window focus changing, etc.
226     virtual void didLosePointerLock() { }
227
228     // Informs the WebWidget that the resizer rect changed. Happens for example
229     // on mac, when a widget appears below the WebWidget without changing the
230     // WebWidget's size (WebWidget::resize() automatically checks the resizer
231     // rect.)
232     virtual void didChangeWindowResizerRect() { }
233
234     // Instrumentation method that marks beginning of frame update that includes
235     // things like animate()/layout()/paint()/composite().
236     virtual void instrumentBeginFrame() { }
237     // Cancels the effect of instrumentBeginFrame() in case there were no events
238     // following the call to instrumentBeginFrame().
239     virtual void instrumentCancelFrame() { }
240
241     // Fills in a WebRenderingStats struct containing information about rendering, e.g. count of frames rendered, time spent painting.
242     // This call is relatively expensive in threaded compositing mode, as it blocks on the compositor thread.
243     // It is safe to call in software mode, but will only give stats for rendering done in compositing mode.
244     virtual void renderingStats(WebRenderingStats&) const { }
245
246     // The page background color. Can be used for filling in areas without
247     // content.
248     virtual WebColor backgroundColor() const { return 0xFFFFFFFF; /* SK_ColorWHITE */ }
249
250 protected:
251     ~WebWidget() { }
252 };
253
254 } // namespace WebKit
255
256 #endif