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 "WebString.h"

    36 #include "WebVector.h"

    37 #include "WebWidget.h"

    38 

    39 namespace WebKit {

    40 

    41 class WebAccessibilityObject;

    42 class WebDevToolsAgent;

    43 class WebDevToolsAgentClient;

    44 class WebDragData;

    45 class WebFrame;

    46 class WebFrameClient;

    47 class WebGLES2Context;

    48 class WebNode;

    49 class WebSettings;

    50 class WebString;

    51 class WebViewClient;

    52 struct WebMediaPlayerAction;

    53 struct WebPoint;

    54 

    55 class WebView : public WebWidget {

    56 public:

    57     // Controls the time that user scripts injected into the document run.

    58     enum UserScriptInjectAt {

    59         UserScriptInjectAtDocumentStart,

    60         UserScriptInjectAtDocumentEnd

    61     };

    62 

    63     // Controls which frames user content is injected into.

    64     enum UserContentInjectIn {

    65         UserContentInjectInAllFrames,

    66         UserContentInjectInTopFrameOnly

    67     };

    68 

    69     // Initialization ------------------------------------------------------

    70 

    71     // Creates a WebView that is NOT yet initialized.  You will need to

    72     // call initializeMainFrame to finish the initialization.  It is valid

    73     // to pass null WebViewClient and WebDevToolsAgentClient pointers.

    74     WEBKIT_API static WebView* create(WebViewClient*, WebDevToolsAgentClient*);

    75 

    76     // After creating a WebView, you should immediately call this method.

    77     // You can optionally modify the settings before calling this method.

    78     // The WebFrameClient will receive events for the main frame and any

    79     // child frames.  It is valid to pass a null WebFrameClient pointer.

    80     virtual void initializeMainFrame(WebFrameClient*) = 0;

    81 

    82 

    83     // Options -------------------------------------------------------------

    84 

    85     // The returned pointer is valid for the lifetime of the WebView.

    86     virtual WebSettings* settings() = 0;

    87 

    88     // Corresponds to the encoding of the main frame.  Setting the page

    89     // encoding may cause the main frame to reload.

    90     virtual WebString pageEncoding() const = 0;

    91     virtual void setPageEncoding(const WebString&) = 0;

    92 

    93     // Makes the WebView transparent.  This is useful if you want to have

    94     // some custom background rendered behind it.

    95     virtual bool isTransparent() const = 0;

    96     virtual void setIsTransparent(bool) = 0;

    97 

    98     // Controls whether pressing Tab key advances focus to links.

    99     virtual bool tabsToLinks() const = 0;

   100     virtual void setTabsToLinks(bool) = 0;

   101 

   102     // Method that controls whether pressing Tab key cycles through page

   103     // elements or inserts a '\t' char in the focused text area.

   104     virtual bool tabKeyCyclesThroughElements() const = 0;

   105     virtual void setTabKeyCyclesThroughElements(bool) = 0;

   106 

   107     // Controls the WebView's active state, which may affect the rendering

   108     // of elements on the page (i.e., tinting of input elements).

   109     virtual bool isActive() const = 0;

   110     virtual void setIsActive(bool) = 0;

   111 

   112 

   113     // Closing -------------------------------------------------------------

   114 

   115     // Runs beforeunload handlers for the current page, returning false if

   116     // any handler suppressed unloading.

   117     virtual bool dispatchBeforeUnloadEvent() = 0;

   118 

   119     // Runs unload handlers for the current page.

   120     virtual void dispatchUnloadEvent() = 0;

   121 

   122 

   123     // Frames --------------------------------------------------------------

   124 

   125     virtual WebFrame* mainFrame() = 0;

   126 

   127     // Returns the frame identified by the given name.  This method

   128     // supports pseudo-names like _self, _top, and _blank.  It traverses

   129     // the entire frame tree containing this tree looking for a frame that

   130     // matches the given name.  If the optional relativeToFrame parameter

   131     // is specified, then the search begins with the given frame and its

   132     // children.

   133     virtual WebFrame* findFrameByName(

   134         const WebString& name, WebFrame* relativeToFrame = 0) = 0;

   135 

   136 

   137     // Focus ---------------------------------------------------------------

   138 

   139     virtual WebFrame* focusedFrame() = 0;

   140     virtual void setFocusedFrame(WebFrame*) = 0;

   141 

   142     // Focus the first (last if reverse is true) focusable node.

   143     virtual void setInitialFocus(bool reverse) = 0;

   144 

   145     // Clears the focused node (and selection if a text field is focused)

   146     // to ensure that a text field on the page is not eating keystrokes we

   147     // send it.

   148     virtual void clearFocusedNode() = 0;

   149 

   150 

   151     // Zoom ----------------------------------------------------------------

   152 

   153     // Returns the current zoom level.  0 is "original size", and each increment

   154     // above or below represents zooming 20% larger or smaller to limits of 300%

   155     // and 50% of original size, respectively.

   156     virtual int zoomLevel() = 0;

   157 

   158     // Changes the zoom level to the specified level, clamping at the limits

   159     // noted above, and returns the current zoom level after applying the

   160     // change.

   161     //

   162     // If |textOnly| is set, only the text will be zoomed; otherwise the entire

   163     // page will be zoomed. You can only have either text zoom or full page zoom

   164     // at one time.  Changing the mode while the page is zoomed will have odd

   165     // effects.

   166     virtual int setZoomLevel(bool textOnly, int zoomLevel) = 0;

   167 

   168 

   169     // Media ---------------------------------------------------------------

   170 

   171     // Performs the specified action on the node at the given location.

   172     virtual void performMediaPlayerAction(

   173         const WebMediaPlayerAction&, const WebPoint& location) = 0;

   174 

   175 

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

   177 

   178     // Copy to the clipboard the image located at a particular point in the

   179     // WebView (if there is such an image)

   180     virtual void copyImageAt(const WebPoint&) = 0;

   181 

   182     // Notifies the WebView that a drag has terminated.

   183     virtual void dragSourceEndedAt(

   184         const WebPoint& clientPoint, const WebPoint& screenPoint,

   185         WebDragOperation operation) = 0;

   186 

   187     // Notifies the WebView that a drag is going on.

   188     virtual void dragSourceMovedTo(

   189         const WebPoint& clientPoint, const WebPoint& screenPoint,

   190         WebDragOperation operation) = 0;

   191 

   192     // Notfies the WebView that the system drag and drop operation has ended.

   193     virtual void dragSourceSystemDragEnded() = 0;

   194 

   195     // Callback methods when a drag-and-drop operation is trying to drop

   196     // something on the WebView.

   197     virtual WebDragOperation dragTargetDragEnter(

   198         const WebDragData&, int identity,

   199         const WebPoint& clientPoint, const WebPoint& screenPoint,

   200         WebDragOperationsMask operationsAllowed) = 0;

   201     virtual WebDragOperation dragTargetDragOver(

   202         const WebPoint& clientPoint, const WebPoint& screenPoint,

   203         WebDragOperationsMask operationsAllowed) = 0;

   204     virtual void dragTargetDragLeave() = 0;

   205     virtual void dragTargetDrop(

   206         const WebPoint& clientPoint, const WebPoint& screenPoint) = 0;

   207 

   208     virtual int dragIdentity() = 0;

   209 

   210     // Helper method for drag and drop target operations: override the

   211     // default drop effect with either a "copy" (accept true) or "none"

   212     // (accept false) effect.  Return true on success.

   213     virtual bool setDropEffect(bool accept) = 0;

   214 

   215 

   216     // Support for resource loading initiated by plugins -------------------

   217 

   218     // Returns next unused request identifier which is unique within the

   219     // parent Page.

   220     virtual unsigned long createUniqueIdentifierForRequest() = 0;

   221 

   222 

   223     // Developer tools -----------------------------------------------------

   224 

   225     // Inspect a particular point in the WebView.  (x = -1 || y = -1) is a

   226     // special case, meaning inspect the current page and not a specific

   227     // point.

   228     virtual void inspectElementAt(const WebPoint&) = 0;

   229 

   230     // Settings used by the inspector.

   231     virtual WebString inspectorSettings() const = 0;

   232     virtual void setInspectorSettings(const WebString&) = 0;

   233     virtual bool inspectorSetting(const WebString& key,

   234                                   WebString* value) const = 0;

   235     virtual void setInspectorSetting(const WebString& key,

   236                                      const WebString& value) = 0;

   237 

   238     // The embedder may optionally engage a WebDevToolsAgent.  This may only

   239     // be set once per WebView.

   240     virtual WebDevToolsAgent* devToolsAgent() = 0;

   241 

   242 

   243     // Accessibility -------------------------------------------------------

   244 

   245     // Returns the accessibility object for this view.

   246     virtual WebAccessibilityObject accessibilityObject() = 0;

   247 

   248 

   249     // AutoFill  -----------------------------------------------------------

   250 

   251     // DEPRECATED.

   252     virtual void applyAutoFillSuggestions(

   253         const WebNode&,

   254         const WebVector<WebString>& names,

   255         const WebVector<WebString>& labels,

   256         int separatorIndex) = 0;

   257 

   258     // Notifies the WebView that AutoFill suggestions are available for a node.

   259     // |uniqueIDs| is a vector of IDs that represent the unique ID of each

   260     // AutoFill profile in the suggestions popup.

   261     virtual void applyAutoFillSuggestions(

   262         const WebNode&,

   263         const WebVector<WebString>& names,

   264         const WebVector<WebString>& labels,

   265         const WebVector<int>& uniqueIDs,

   266         int separatorIndex) = 0;

   267 

   268     // Notifies the WebView that Autocomplete suggestions are available for a

   269     // node.

   270     // DEPRECATED: merging with applyAutoFillSuggestions.

   271     virtual void applyAutocompleteSuggestions(

   272         const WebNode&,

   273         const WebVector<WebString>& suggestions,

   274         int defaultSuggestionIndex) = 0;

   275 

   276     // Hides any popup (suggestions, selects...) that might be showing.

   277     virtual void hidePopups() = 0;

   278 

   279 

   280     // Context menu --------------------------------------------------------

   281 

   282     virtual void performCustomContextMenuAction(unsigned action) = 0;

   283 

   284 

   285     // Visited link state --------------------------------------------------

   286 

   287     // Tells all WebView instances to update the visited link state for the

   288     // specified hash.

   289     WEBKIT_API static void updateVisitedLinkState(unsigned long long hash);

   290 

   291     // Tells all WebView instances to update the visited state for all

   292     // their links.

   293     WEBKIT_API static void resetVisitedLinkState();

   294 

   295 

   296     // Custom colors -------------------------------------------------------

   297 

   298     virtual void setScrollbarColors(unsigned inactiveColor,

   299                                     unsigned activeColor,

   300                                     unsigned trackColor) = 0;

   301 

   302     virtual void setSelectionColors(unsigned activeBackgroundColor,

   303                                     unsigned activeForegroundColor,

   304                                     unsigned inactiveBackgroundColor,

   305                                     unsigned inactiveForegroundColor) = 0;

   306 

   307     // User scripts --------------------------------------------------------

   308     // FIXME: These two methods are DEPRECATED. Remove once Chromium has been rolled.

   309     virtual void addUserScript(const WebString& sourceCode, bool runAtStart)

   310     {

   311         addUserScript(sourceCode, WebVector<WebString>(),

   312                       runAtStart ? UserScriptInjectAtDocumentStart : UserScriptInjectAtDocumentEnd,

   313                       UserContentInjectInAllFrames);

   314     }

   315     virtual void addUserStyleSheet(const WebString& sourceCode)

   316     {

   317         addUserStyleSheet(sourceCode, WebVector<WebString>(), UserContentInjectInAllFrames);

   318     }

   319 

   320     WEBKIT_API static void addUserScript(const WebString& sourceCode,

   321                                          const WebVector<WebString>& patterns,

   322                                          UserScriptInjectAt injectAt,

   323                                          UserContentInjectIn injectIn);

   324     WEBKIT_API static void addUserStyleSheet(const WebString& sourceCode,

   325                                              const WebVector<WebString>& patterns,

   326                                              UserContentInjectIn injectIn);

   327     WEBKIT_API static void removeAllUserContent();

   328 

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

   330 

   331     // Call these methods before and after running a nested, modal event loop

   332     // to suspend script callbacks and resource loads.

   333     WEBKIT_API static void willEnterModalLoop();

   334     WEBKIT_API static void didExitModalLoop();

   335 

   336     // GPU acceleration support --------------------------------------------

   337 

   338     // Returns the GLES2Context associated with this WebView. One will be

   339     // created if it doesn't already exist.

   340     virtual WebGLES2Context* gles2Context() = 0;

   341 

   342 protected:

   343     ~WebView() {}

   344 };

   345 

   346 } // namespace WebKit

   347 

   348 #endif