WebView.h 16.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
/*
 * Copyright (C) 2009 Google Inc. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *     * Neither the name of Google Inc. nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef WebView_h
#define WebView_h

#include "WebDragOperation.h"
35
#include "WebPageVisibilityState.h"
36 37
#include "WebString.h"
#include "WebVector.h"
38 39 40 41 42
#include "WebWidget.h"

namespace WebKit {

class WebAccessibilityObject;
43
class WebAutofillClient;
44
class WebDevToolsAgent;
45
class WebDevToolsAgentClient;
46 47 48
class WebDragData;
class WebFrame;
class WebFrameClient;
49
class WebGraphicsContext3D;
50
class WebNode;
51
class WebPermissionClient;
52
class WebSettings;
53
class WebSpellCheckClient;
54 55 56 57 58 59 60
class WebString;
class WebViewClient;
struct WebMediaPlayerAction;
struct WebPoint;

class WebView : public WebWidget {
public:
61 62 63
    WEBKIT_EXPORT static const double textSizeMultiplierRatio;
    WEBKIT_EXPORT static const double minTextSizeMultiplier;
    WEBKIT_EXPORT static const double maxTextSizeMultiplier;
64

65 66 67 68 69 70 71 72 73 74 75
    // Controls the time that user scripts injected into the document run.
    enum UserScriptInjectAt {
        UserScriptInjectAtDocumentStart,
        UserScriptInjectAtDocumentEnd
    };

    // Controls which frames user content is injected into.
    enum UserContentInjectIn {
        UserContentInjectInAllFrames,
        UserContentInjectInTopFrameOnly
    };
76

77 78 79 80 81
    // Controls which documents user styles are injected into.
    enum UserStyleInjectionTime {
        UserStyleInjectInExistingDocuments,
        UserStyleInjectInSubsequentDocuments
    };
82

83

84 85 86 87
    // Initialization ------------------------------------------------------

    // Creates a WebView that is NOT yet initialized.  You will need to
    // call initializeMainFrame to finish the initialization.  It is valid
88
    // to pass null client pointers.
89
    WEBKIT_EXPORT static WebView* create(WebViewClient*);
90 91 92 93 94 95 96

    // After creating a WebView, you should immediately call this method.
    // You can optionally modify the settings before calling this method.
    // The WebFrameClient will receive events for the main frame and any
    // child frames.  It is valid to pass a null WebFrameClient pointer.
    virtual void initializeMainFrame(WebFrameClient*) = 0;

97
    // Initializes the various client interfaces.
98
    virtual void setAutofillClient(WebAutofillClient*) = 0;
99 100
    virtual void setDevToolsAgentClient(WebDevToolsAgentClient*) = 0;
    virtual void setPermissionClient(WebPermissionClient*) = 0;
101 102
    virtual void setSpellCheckClient(WebSpellCheckClient*) = 0;

103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132

    // Options -------------------------------------------------------------

    // The returned pointer is valid for the lifetime of the WebView.
    virtual WebSettings* settings() = 0;

    // Corresponds to the encoding of the main frame.  Setting the page
    // encoding may cause the main frame to reload.
    virtual WebString pageEncoding() const = 0;
    virtual void setPageEncoding(const WebString&) = 0;

    // Makes the WebView transparent.  This is useful if you want to have
    // some custom background rendered behind it.
    virtual bool isTransparent() const = 0;
    virtual void setIsTransparent(bool) = 0;

    // Controls whether pressing Tab key advances focus to links.
    virtual bool tabsToLinks() const = 0;
    virtual void setTabsToLinks(bool) = 0;

    // Method that controls whether pressing Tab key cycles through page
    // elements or inserts a '\t' char in the focused text area.
    virtual bool tabKeyCyclesThroughElements() const = 0;
    virtual void setTabKeyCyclesThroughElements(bool) = 0;

    // Controls the WebView's active state, which may affect the rendering
    // of elements on the page (i.e., tinting of input elements).
    virtual bool isActive() const = 0;
    virtual void setIsActive(bool) = 0;

133
    // Allows disabling domain relaxation.
134
    virtual void setDomainRelaxationForbidden(bool, const WebString& scheme) = 0;
135

136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173

    // Closing -------------------------------------------------------------

    // Runs beforeunload handlers for the current page, returning false if
    // any handler suppressed unloading.
    virtual bool dispatchBeforeUnloadEvent() = 0;

    // Runs unload handlers for the current page.
    virtual void dispatchUnloadEvent() = 0;


    // Frames --------------------------------------------------------------

    virtual WebFrame* mainFrame() = 0;

    // Returns the frame identified by the given name.  This method
    // supports pseudo-names like _self, _top, and _blank.  It traverses
    // the entire frame tree containing this tree looking for a frame that
    // matches the given name.  If the optional relativeToFrame parameter
    // is specified, then the search begins with the given frame and its
    // children.
    virtual WebFrame* findFrameByName(
        const WebString& name, WebFrame* relativeToFrame = 0) = 0;


    // Focus ---------------------------------------------------------------

    virtual WebFrame* focusedFrame() = 0;
    virtual void setFocusedFrame(WebFrame*) = 0;

    // Focus the first (last if reverse is true) focusable node.
    virtual void setInitialFocus(bool reverse) = 0;

    // Clears the focused node (and selection if a text field is focused)
    // to ensure that a text field on the page is not eating keystrokes we
    // send it.
    virtual void clearFocusedNode() = 0;

174 175 176
    // Scrolls the node currently in focus into view.
    virtual void scrollFocusedNodeIntoView() = 0;

177
    // Scrolls the node currently in focus into |rect|, where |rect| is in
178 179
    // window space.
    virtual void scrollFocusedNodeIntoRect(const WebRect&) { }
180

181 182 183

    // Zoom ----------------------------------------------------------------

184
    // Returns the current zoom level.  0 is "original size", and each increment
185 186 187 188
    // above or below represents zooming 20% larger or smaller to default limits
    // of 300% and 50% of original size, respectively.  Only plugins use
    // non whole-numbers, since they might choose to have specific zoom level so
    // that fixed-width content is fit-to-page-width, for example.
189
    virtual double zoomLevel() = 0;
190 191 192 193 194 195 196 197 198

    // Changes the zoom level to the specified level, clamping at the limits
    // noted above, and returns the current zoom level after applying the
    // change.
    //
    // If |textOnly| is set, only the text will be zoomed; otherwise the entire
    // page will be zoomed. You can only have either text zoom or full page zoom
    // at one time.  Changing the mode while the page is zoomed will have odd
    // effects.
199
    virtual double setZoomLevel(bool textOnly, double zoomLevel) = 0;
200 201

    // Updates the zoom limits for this view.
202 203
    virtual void zoomLimitsChanged(double minimumZoomLevel,
                                   double maximumZoomLevel) = 0;
204 205 206

    // Helper functions to convert between zoom level and zoom factor.  zoom
    // factor is zoom percent / 100, so 300% = 3.0.
207 208
    WEBKIT_EXPORT static double zoomLevelToZoomFactor(double zoomLevel);
    WEBKIT_EXPORT static double zoomFactorToZoomLevel(double factor);
209

210 211 212 213
    // Gets the scale factor of the page, where 1.0 is the normal size, > 1.0
    // is scaled up, < 1.0 is scaled down.
    virtual float pageScaleFactor() const = 0;

214 215 216 217 218
    // Scales a page by a factor of scaleFactor and then sets a scroll position to (x, y).
    // scalePage() magnifies and shrinks a page without affecting layout.
    // On the other hand, zooming affects layout of the page.
    virtual void scalePage(float scaleFactor, WebPoint origin) = 0;

219

220 221 222 223 224 225 226 227 228 229 230 231
    // Fixed Layout --------------------------------------------------------

    // In fixed layout mode, the layout of the page is independent of the
    // view port size, given by WebWidget::size().

    virtual bool isFixedLayoutModeEnabled() const = 0;
    virtual void enableFixedLayoutMode(bool enable) = 0;

    virtual WebSize fixedLayoutSize() const = 0;
    virtual void setFixedLayoutSize(const WebSize&) = 0;


232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
    // Media ---------------------------------------------------------------

    // Performs the specified action on the node at the given location.
    virtual void performMediaPlayerAction(
        const WebMediaPlayerAction&, const WebPoint& location) = 0;


    // Data exchange -------------------------------------------------------

    // Copy to the clipboard the image located at a particular point in the
    // WebView (if there is such an image)
    virtual void copyImageAt(const WebPoint&) = 0;

    // Notifies the WebView that a drag has terminated.
    virtual void dragSourceEndedAt(
        const WebPoint& clientPoint, const WebPoint& screenPoint,
        WebDragOperation operation) = 0;

250 251 252 253 254
    // Notifies the WebView that a drag is going on.
    virtual void dragSourceMovedTo(
        const WebPoint& clientPoint, const WebPoint& screenPoint,
        WebDragOperation operation) = 0;

255 256 257 258 259
    // Notfies the WebView that the system drag and drop operation has ended.
    virtual void dragSourceSystemDragEnded() = 0;

    // Callback methods when a drag-and-drop operation is trying to drop
    // something on the WebView.
260 261 262 263
    virtual WebDragOperation dragTargetDragEnter(
        const WebDragData&,
        const WebPoint& clientPoint, const WebPoint& screenPoint,
        WebDragOperationsMask operationsAllowed) = 0;
264 265 266 267 268 269 270 271
    virtual WebDragOperation dragTargetDragOver(
        const WebPoint& clientPoint, const WebPoint& screenPoint,
        WebDragOperationsMask operationsAllowed) = 0;
    virtual void dragTargetDragLeave() = 0;
    virtual void dragTargetDrop(
        const WebPoint& clientPoint, const WebPoint& screenPoint) = 0;


272 273 274 275 276 277 278
    // Support for resource loading initiated by plugins -------------------

    // Returns next unused request identifier which is unique within the
    // parent Page.
    virtual unsigned long createUniqueIdentifierForRequest() = 0;


279 280 281 282 283 284 285 286 287 288
    // Developer tools -----------------------------------------------------

    // Inspect a particular point in the WebView.  (x = -1 || y = -1) is a
    // special case, meaning inspect the current page and not a specific
    // point.
    virtual void inspectElementAt(const WebPoint&) = 0;

    // Settings used by the inspector.
    virtual WebString inspectorSettings() const = 0;
    virtual void setInspectorSettings(const WebString&) = 0;
289 290 291 292
    virtual bool inspectorSetting(const WebString& key,
                                  WebString* value) const = 0;
    virtual void setInspectorSetting(const WebString& key,
                                     const WebString& value) = 0;
293 294 295 296 297 298 299 300 301 302 303 304

    // The embedder may optionally engage a WebDevToolsAgent.  This may only
    // be set once per WebView.
    virtual WebDevToolsAgent* devToolsAgent() = 0;


    // Accessibility -------------------------------------------------------

    // Returns the accessibility object for this view.
    virtual WebAccessibilityObject accessibilityObject() = 0;


305
    // Autofill  -----------------------------------------------------------
306

307
    // Notifies the WebView that Autofill suggestions are available for a node.
308
    // |uniqueIDs| is a vector of IDs that represent the unique ID of each
309 310
    // Autofill profile in the suggestions popup. If a unique ID is 0, then the
    // corresponding suggestion comes from Autocomplete rather than Autofill.
311
    // If a unique ID is negative, then the corresponding "suggestion" is
312
    // actually a user-facing warning, e.g. explaining why Autofill is
313
    // unavailable for the current form.
314
    virtual void applyAutofillSuggestions(
315 316 317
        const WebNode&,
        const WebVector<WebString>& names,
        const WebVector<WebString>& labels,
318
        const WebVector<WebString>& icons,
319
        const WebVector<int>& uniqueIDs,
320
        int separatorIndex) = 0;
321

322 323
    // Hides any popup (suggestions, selects...) that might be showing.
    virtual void hidePopups() = 0;
324 325


326 327 328 329 330
    // Context menu --------------------------------------------------------

    virtual void performCustomContextMenuAction(unsigned action) = 0;


331 332 333
    // Popup menu ----------------------------------------------------------

    // Sets whether select popup menus should be rendered by the browser.
334
    WEBKIT_EXPORT static void setUseExternalPopupMenus(bool);
335 336


337 338 339 340
    // Visited link state --------------------------------------------------

    // Tells all WebView instances to update the visited link state for the
    // specified hash.
341
    WEBKIT_EXPORT static void updateVisitedLinkState(unsigned long long hash);
342 343 344

    // Tells all WebView instances to update the visited state for all
    // their links.
345
    WEBKIT_EXPORT static void resetVisitedLinkState();
346

347

348
    // Custom colors -------------------------------------------------------
349

350 351 352
    virtual void setScrollbarColors(unsigned inactiveColor,
                                    unsigned activeColor,
                                    unsigned trackColor) = 0;
353

354 355 356 357 358
    virtual void setSelectionColors(unsigned activeBackgroundColor,
                                    unsigned activeForegroundColor,
                                    unsigned inactiveBackgroundColor,
                                    unsigned inactiveForegroundColor) = 0;

359
    // User scripts --------------------------------------------------------
360 361 362 363 364 365 366 367 368
    WEBKIT_EXPORT static void addUserScript(const WebString& sourceCode,
                                            const WebVector<WebString>& patterns,
                                            UserScriptInjectAt injectAt,
                                            UserContentInjectIn injectIn);
    WEBKIT_EXPORT static void addUserStyleSheet(const WebString& sourceCode,
                                                const WebVector<WebString>& patterns,
                                                UserContentInjectIn injectIn,
                                                UserStyleInjectionTime injectionTime = UserStyleInjectInSubsequentDocuments);
    WEBKIT_EXPORT static void removeAllUserContent();
369 370 371 372 373

    // Modal dialog support ------------------------------------------------

    // Call these methods before and after running a nested, modal event loop
    // to suspend script callbacks and resource loads.
374 375
    WEBKIT_EXPORT static void willEnterModalLoop();
    WEBKIT_EXPORT static void didExitModalLoop();
376

377 378
    // GPU acceleration support --------------------------------------------

379 380 381 382 383 384 385
    // Returns the (on-screen) WebGraphicsContext3D associated with
    // this WebView. One will be created if it doesn't already exist.
    // This is used to set up sharing between this context (which is
    // that used by the compositor) and contexts for WebGL and other
    // APIs.
    virtual WebGraphicsContext3D* graphicsContext3D() = 0;

386 387 388 389 390 391
    // Visibility -----------------------------------------------------------

    // Sets the visibility of the WebView.
    virtual void setVisibilityState(WebPageVisibilityState visibilityState,
                                    bool isInitialState) { }

392 393 394 395 396

    // Fullscreen -----------------------------------------------------------

    virtual void exitFullscreen() = 0;

397 398 399
    // Testing functionality for LayoutTestController -----------------------

    // Simulates a compositor lost context.
400
    virtual void loseCompositorContext(int numTimes) = 0;
401

402

403 404 405 406 407 408 409
protected:
    ~WebView() {}
};

} // namespace WebKit

#endif