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 WebFrame_h 32 #define WebFrame_h 33 34 #include "WebCanvas.h" 35 #include "WebURL.h" 36 37 struct NPObject; 38 39 #if WEBKIT_USING_V8 40 namespace v8 { 41 class Context; 42 template <class T> class Local; 43 } 44 #endif 45 46 namespace WebKit { 47 48 class WebAnimationController; 49 class WebData; 50 class WebDataSource; 51 class WebDocument; 52 class WebElement; 53 class WebFormElement; 54 class WebHistoryItem; 55 class WebInputElement; 56 class WebPasswordAutocompleteListener; 57 class WebRange; 58 class WebSecurityOrigin; 59 class WebString; 60 class WebURL; 61 class WebURLRequest; 62 class WebView; 63 struct WebConsoleMessage; 64 struct WebFindOptions; 65 struct WebRect; 66 struct WebScriptSource; 67 struct WebSize; 68 template <typename T> class WebVector; 69 70 class WebFrame { 71 public: 72 // Returns the number of live WebFrame objects, used for leak checking. 73 WEBKIT_API static int instanceCount(); 74 75 // The two functions below retrieve the WebFrame instances relating the 76 // currently executing JavaScript. Since JavaScript can make function 77 // calls across frames, though, we need to be more precise. 78 // 79 // For example, imagine that a JS function in frame A calls a function 80 // in frame B, which calls native code, which wants to know what the 81 // 'active' frame is. 82 // 83 // The 'entered context' is the context where execution first entered 84 // the script engine; the context that is at the bottom of the JS 85 // function stack. frameForEnteredContext() would return frame A in 86 // our example. 87 // 88 // The 'current context' is the context the JS engine is currently 89 // inside of; the context that is at the top of the JS function stack. 90 // frameForCurrentContext() would return frame B in our example. 91 WEBKIT_API static WebFrame* frameForEnteredContext(); 92 WEBKIT_API static WebFrame* frameForCurrentContext(); 93 94 // Returns the frame inside a given frame or iframe element. Returns 0 if 95 // the given element is not a frame, iframe or if the frame is empty. 96 WEBKIT_API static WebFrame* fromFrameOwnerElement(const WebElement&); 97 98 99 // Basic properties --------------------------------------------------- 100 101 // The name of this frame. 102 virtual WebString name() const = 0; 103 virtual void clearName() = 0; 104 105 // The url of the document loaded in this frame. This is equivalent to 106 // dataSource()->request().url(). 107 virtual WebURL url() const = 0; 108 109 // The url of the favicon (if any) specified by the document loaded in 110 // this frame. 111 virtual WebURL favIconURL() const = 0; 112 113 // The url of the OpenSearch Desription Document (if any) specified by 114 // the document loaded in this frame. 115 virtual WebURL openSearchDescriptionURL() const = 0; 116 117 // Return the frame's encoding. 118 virtual WebString encoding() const = 0; 119 120 121 // Geometry ----------------------------------------------------------- 122 123 // NOTE: These routines do not force page layout so their results may 124 // not be accurate if the page layout is out-of-date. 125 126 // The scroll offset from the top-left corner of the frame in pixels. 127 virtual WebSize scrollOffset() const = 0; 128 129 // The size of the contents area. 130 virtual WebSize contentsSize() const = 0; 131 132 // Returns the minimum preferred width of the content contained in the 133 // current document. 134 virtual int contentsPreferredWidth() const = 0; 135 136 // Returns the scroll height of the document element. This is 137 // equivalent to the DOM property of the same name, and is the minimum 138 // height required to display the document without scrollbars. 139 virtual int documentElementScrollHeight() const = 0; 140 141 // Returns true if the contents (minus scrollbars) has non-zero area. 142 virtual bool hasVisibleContent() const = 0; 143 144 145 // Hierarchy ---------------------------------------------------------- 146 147 // Returns the containing view. 148 virtual WebView* view() const = 0; 149 150 // Returns the frame that opened this frame or 0 if there is none. 151 virtual WebFrame* opener() const = 0; 152 153 // Returns the parent frame or 0 if this is a top-most frame. 154 virtual WebFrame* parent() const = 0; 155 156 // Returns the top-most frame in the hierarchy containing this frame. 157 virtual WebFrame* top() const = 0; 158 159 // Returns the first/last child frame. 160 virtual WebFrame* firstChild() const = 0; 161 virtual WebFrame* lastChild() const = 0; 162 163 // Returns the next/previous sibling frame. 164 virtual WebFrame* nextSibling() const = 0; 165 virtual WebFrame* previousSibling() const = 0; 166 167 // Returns the next/previous frame in "frame traversal order" 168 // optionally wrapping around. 169 virtual WebFrame* traverseNext(bool wrap) const = 0; 170 virtual WebFrame* traversePrevious(bool wrap) const = 0; 171 172 // Returns the child frame identified by the given name. 173 virtual WebFrame* findChildByName(const WebString& name) const = 0; 174 175 // Returns the child frame identified by the given xpath expression. 176 virtual WebFrame* findChildByExpression(const WebString& xpath) const = 0; 177 178 179 // Content ------------------------------------------------------------ 180 181 virtual WebDocument document() const = 0; 182 183 virtual void forms(WebVector<WebFormElement>&) const = 0; 184 185 virtual WebAnimationController* animationController() = 0; 186 187 188 // Scripting ---------------------------------------------------------- 189 190 // Returns the security origin of the current document. 191 virtual WebSecurityOrigin securityOrigin() const = 0; 192 193 // This grants the currently loaded document access to all security 194 // origins (including file URLs). Use with care. The access is 195 // revoked when a new document is loaded into this frame. 196 virtual void grantUniversalAccess() = 0; 197 198 // Returns a NPObject corresponding to this frame's DOMWindow. 199 virtual NPObject* windowObject() const = 0; 200 201 // Binds a NPObject as a property of this frame's DOMWindow. 202 virtual void bindToWindowObject(const WebString& name, NPObject*) = 0; 203 204 // Executes script in the context of the current page. 205 virtual void executeScript(const WebScriptSource&) = 0; 206 207 // Executes JavaScript in a new world associated with the web frame. 208 // The script gets its own global scope and its own prototypes for 209 // intrinsic JavaScript objects (String, Array, and so-on). It also 210 // gets its own wrappers for all DOM nodes and DOM constructors. 211 // extensionGroup is an embedder-provided specifier that controls which 212 // v8 extensions are loaded into the new context - see 213 // WebKit::registerExtension for the corresponding specifier. 214 virtual void executeScriptInIsolatedWorld( 215 int worldId, const WebScriptSource* sources, unsigned numSources, 216 int extensionGroup) = 0; 217 218 // Logs to the console associated with this frame. 219 virtual void addMessageToConsole(const WebConsoleMessage&) = 0; 220 221 // Calls window.gc() if it is defined. 222 virtual void collectGarbage() = 0; 223 224 #if WEBKIT_USING_V8 225 // Returns the V8 context for this frame, or an empty handle if there 226 // is none. 227 virtual v8::Local<v8::Context> mainWorldScriptContext() const = 0; 228 #endif 229 230 231 // Styling ------------------------------------------------------------- 232 233 // Insert the given text as a STYLE element at the beginning of the 234 // document. |elementId| can be empty, but if specified then it is used 235 // as the id for the newly inserted element (replacing an existing one 236 // with the same id, if any). 237 virtual bool insertStyleText(const WebString& styleText, 238 const WebString& elementId) = 0; 239 240 241 // Navigation ---------------------------------------------------------- 242 243 // Reload the current document. 244 virtual void reload() = 0; 245 246 // Load the given URL. 247 virtual void loadRequest(const WebURLRequest&) = 0; 248 249 // Load the given history state, corresponding to a back/forward 250 // navigation. 251 virtual void loadHistoryItem(const WebHistoryItem&) = 0; 252 253 // Loads the given data with specific mime type and optional text 254 // encoding. For HTML data, baseURL indicates the security origin of 255 // the document and is used to resolve links. If specified, 256 // unreachableURL is reported via WebDataSource::unreachableURL. If 257 // replace is false, then this data will be loaded as a normal 258 // navigation. Otherwise, the current history item will be replaced. 259 virtual void loadData(const WebData& data, 260 const WebString& mimeType, 261 const WebString& textEncoding, 262 const WebURL& baseURL, 263 const WebURL& unreachableURL = WebURL(), 264 bool replace = false) = 0; 265 266 // This method is short-hand for calling LoadData, where mime_type is 267 // "text/html" and text_encoding is "UTF-8". 268 virtual void loadHTMLString(const WebData& html, 269 const WebURL& baseURL, 270 const WebURL& unreachableURL = WebURL(), 271 bool replace = false) = 0; 272 273 // Returns true if the current frame is busy loading content. 274 virtual bool isLoading() const = 0; 275 276 // Stops any pending loads on the frame and its children. 277 virtual void stopLoading() = 0; 278 279 // Returns the data source that is currently loading. May be null. 280 virtual WebDataSource* provisionalDataSource() const = 0; 281 282 // Returns the data source that is currently loaded. 283 virtual WebDataSource* dataSource() const = 0; 284 285 // Returns the previous history item. Check WebHistoryItem::isNull() 286 // before using. 287 virtual WebHistoryItem previousHistoryItem() const = 0; 288 289 // Returns the current history item. Check WebHistoryItem::isNull() 290 // before using. 291 virtual WebHistoryItem currentHistoryItem() const = 0; 292 293 // View-source rendering mode. Set this before loading an URL to cause 294 // it to be rendered in view-source mode. 295 virtual void enableViewSourceMode(bool) = 0; 296 virtual bool isViewSourceModeEnabled() const = 0; 297 298 // Sets the referrer for the given request to be the specified URL or 299 // if that is null, then it sets the referrer to the referrer that the 300 // frame would use for subresources. NOTE: This method also filters 301 // out invalid referrers (e.g., it is invalid to send a HTTPS URL as 302 // the referrer for a HTTP request). 303 virtual void setReferrerForRequest(WebURLRequest&, const WebURL&) = 0; 304 305 // Called to associate the WebURLRequest with this frame. The request 306 // will be modified to inherit parameters that allow it to be loaded. 307 // This method ends up triggering WebFrameClient::willSendRequest. 308 virtual void dispatchWillSendRequest(WebURLRequest&) = 0; 309 310 // Called from within WebFrameClient::didReceiveDocumentData to commit 311 // data for the frame that will be used to construct the frame's 312 // document. 313 virtual void commitDocumentData(const char* data, size_t length) = 0; 314 315 // Returns the number of registered unload listeners. 316 virtual unsigned unloadListenerCount() const = 0; 317 318 // Returns true if a user gesture is currently being processed. 319 virtual bool isProcessingUserGesture() const = 0; 320 321 // Returns true if this frame is in the process of opening a new frame 322 // with a suppressed opener. 323 virtual bool willSuppressOpenerInNewFrame() const = 0; 324 325 326 // Editing ------------------------------------------------------------- 327 328 // Replaces the selection with the given text. 329 virtual void replaceSelection(const WebString& text) = 0; 330 331 virtual void insertText(const WebString& text) = 0; 332 333 virtual void setMarkedText(const WebString& text, unsigned location, unsigned length) = 0; 334 virtual void unmarkText() = 0; 335 virtual bool hasMarkedText() const = 0; 336 337 virtual WebRange markedRange() const = 0; 338 339 // Supports commands like Undo, Redo, Cut, Copy, Paste, SelectAll, 340 // Unselect, etc. See EditorCommand.cpp for the full list of supported 341 // commands. 342 virtual bool executeCommand(const WebString&) = 0; 343 virtual bool executeCommand(const WebString&, const WebString& value) = 0; 344 virtual bool isCommandEnabled(const WebString&) const = 0; 345 346 // Spell-checking support. 347 virtual void enableContinuousSpellChecking(bool) = 0; 348 virtual bool isContinuousSpellCheckingEnabled() const = 0; 349 350 351 // Selection ----------------------------------------------------------- 352 353 virtual bool hasSelection() const = 0; 354 355 virtual WebRange selectionRange() const = 0; 356 357 virtual WebString selectionAsText() const = 0; 358 virtual WebString selectionAsMarkup() const = 0; 359 360 // Expands the selection to a word around the caret and returns 361 // true. Does nothing and returns false if there is no caret or 362 // there is ranged selection. 363 virtual bool selectWordAroundCaret() = 0; 364 365 366 // Printing ------------------------------------------------------------ 367 368 // Reformats the WebFrame for printing. pageSize is the page size in 369 // pixels. Returns the number of pages that can be printed at the 370 // given page size. 371 virtual int printBegin(const WebSize& pageSize) = 0; 372 373 // Returns the page shrinking factor calculated by webkit (usually 374 // between 1/1.25 and 1/2). Returns 0 if the page number is invalid or 375 // not in printing mode. 376 virtual float getPrintPageShrink(int page) = 0; 377 378 // Prints one page, and returns the calculated page shrinking factor 379 // (usually between 1/1.25 and 1/2). Returns 0 if the page number is 380 // invalid or not in printing mode. 381 virtual float printPage(int pageToPrint, WebCanvas*) = 0; 382 383 // Reformats the WebFrame for screen display. 384 virtual void printEnd() = 0; 385 386 387 // Find-in-page -------------------------------------------------------- 388 389 // Searches a frame for a given string. 390 // 391 // If a match is found, this function will select it (scrolling down to 392 // make it visible if needed) and fill in selectionRect with the 393 // location of where the match was found (in window coordinates). 394 // 395 // If no match is found, this function clears all tickmarks and 396 // highlighting. 397 // 398 // Returns true if the search string was found, false otherwise. 399 virtual bool find(int identifier, 400 const WebString& searchText, 401 const WebFindOptions& options, 402 bool wrapWithinFrame, 403 WebRect* selectionRect) = 0; 404 405 // Notifies the frame that we are no longer interested in searching. 406 // This will abort any asynchronous scoping effort already under way 407 // (see the function scopeStringMatches for details) and erase all 408 // tick-marks and highlighting from the previous search. If 409 // clearSelection is true, it will also make sure the end state for the 410 // find operation does not leave a selection. This can occur when the 411 // user clears the search string but does not close the find box. 412 virtual void stopFinding(bool clearSelection) = 0; 413 414 // Counts how many times a particular string occurs within the frame. 415 // It also retrieves the location of the string and updates a vector in 416 // the frame so that tick-marks and highlighting can be drawn. This 417 // function does its work asynchronously, by running for a certain 418 // time-slice and then scheduling itself (co-operative multitasking) to 419 // be invoked later (repeating the process until all matches have been 420 // found). This allows multiple frames to be searched at the same time 421 // and provides a way to cancel at any time (see 422 // cancelPendingScopingEffort). The parameter searchText specifies 423 // what to look for and |reset| signals whether this is a brand new 424 // request or a continuation of the last scoping effort. 425 virtual void scopeStringMatches(int identifier, 426 const WebString& searchText, 427 const WebFindOptions& options, 428 bool reset) = 0; 429 430 // Cancels any outstanding requests for scoping string matches on a frame. 431 virtual void cancelPendingScopingEffort() = 0; 432 433 // This function is called on the main frame during the scoping effort 434 // to keep a running tally of the accumulated total match-count for all 435 // frames. After updating the count it will notify the WebViewClient 436 // about the new count. 437 virtual void increaseMatchCount(int count, int identifier) = 0; 438 439 // This function is called on the main frame to reset the total number 440 // of matches found during the scoping effort. 441 virtual void resetMatchCount() = 0; 442 443 444 // Password autocompletion --------------------------------------------- 445 446 // Registers a listener for the specified user name input element. The 447 // listener will receive notifications for blur and when autocomplete 448 // should be triggered. 449 // The WebFrame becomes the owner of the passed listener. 450 virtual void registerPasswordListener( 451 WebInputElement, 452 WebPasswordAutocompleteListener*) = 0; 453 454 455 // Utility ------------------------------------------------------------- 456 457 // Given a relative URL, returns an absolute URL by resolving the URL 458 // relative to the base URL of the frame's document. This uses the 459 // same algorithm that WebKit uses to resolve hyperlinks found in a 460 // HTML document. 461 // Deprecated. Use document().completeURL() instead. 462 virtual WebURL completeURL(const WebString&) const = 0; 463 464 // Returns the contents of this frame as a string. If the text is 465 // longer than maxChars, it will be clipped to that length. WARNING: 466 // This function may be slow depending on the number of characters 467 // retrieved and page complexity. For a typically sized page, expect 468 // it to take on the order of milliseconds. 469 // 470 // If there is room, subframe text will be recursively appended. Each 471 // frame will be separated by an empty line. 472 virtual WebString contentAsText(size_t maxChars) const = 0; 473 474 // Returns HTML text for the contents of this frame. This is generated 475 // from the DOM. 476 virtual WebString contentAsMarkup() const = 0; 477 478 // Returns a text representation of the render tree. This method is used 479 // to support layout tests. 480 virtual WebString renderTreeAsText() const = 0; 481 482 // Returns the counter value for the specified element. This method is 483 // used to support layout tests. 484 virtual WebString counterValueForElementById(const WebString& id) const = 0; 485 486 487 // Returns the number of page where the specified element will be put. 488 // This method is used to support layout tests. 489 virtual int pageNumberForElementById(const WebString& id, 490 float pageWidthInPixels, 491 float pageHeightInPixels) const = 0; 492 493 protected: 494 ~WebFrame() { } 495 }; 496 497 } // namespace WebKit 498 499 #endif 500