2 * Copyright (C) 2009 Google Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
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
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.
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.
34 #include "WebCanvas.h"
35 #include "WebFileSystem.h"
36 #include "WebIconURL.h"
39 #include "WebURLLoaderOptions.h"
47 template <class T> class Handle;
48 template <class T> class Local;
54 class WebAnimationController;
61 class WebInputElement;
64 class WebSecurityOrigin;
70 struct WebConsoleMessage;
71 struct WebFindOptions;
74 struct WebScriptSource;
76 struct WebURLLoaderOptions;
78 template <typename T> class WebVector;
82 // Returns the number of live WebFrame objects, used for leak checking.
83 WEBKIT_EXPORT static int instanceCount();
85 // The two functions below retrieve the WebFrame instances relating the
86 // currently executing JavaScript. Since JavaScript can make function
87 // calls across frames, though, we need to be more precise.
89 // For example, imagine that a JS function in frame A calls a function
90 // in frame B, which calls native code, which wants to know what the
93 // The 'entered context' is the context where execution first entered
94 // the script engine; the context that is at the bottom of the JS
95 // function stack. frameForEnteredContext() would return frame A in
98 // The 'current context' is the context the JS engine is currently
99 // inside of; the context that is at the top of the JS function stack.
100 // frameForCurrentContext() would return frame B in our example.
101 WEBKIT_EXPORT static WebFrame* frameForEnteredContext();
102 WEBKIT_EXPORT static WebFrame* frameForCurrentContext();
105 // Returns the frame corresponding to the given context. This can return 0
106 // if the context is detached from the frame, or if the context doesn't
107 // correspond to a frame (e.g., workers).
108 WEBKIT_EXPORT static WebFrame* frameForContext(v8::Handle<v8::Context>);
111 // Returns the frame inside a given frame or iframe element. Returns 0 if
112 // the given element is not a frame, iframe or if the frame is empty.
113 WEBKIT_EXPORT static WebFrame* fromFrameOwnerElement(const WebElement&);
116 // Basic properties ---------------------------------------------------
118 // The name of this frame.
119 virtual WebString name() const = 0;
121 // Sets the name of this frame. For child frames (frames that are not a
122 // top-most frame) the actual name may have a suffix appended to make the
123 // frame name unique within the hierarchy.
124 virtual void setName(const WebString&) = 0;
126 // A globally unique identifier for this frame.
127 virtual long long identifier() const = 0;
129 // The urls of the given combination types of favicon (if any) specified by
130 // the document loaded in this frame. The iconTypes is a bit-mask of
131 // WebIconURL::Type values, used to select from the available set of icon
133 virtual WebVector<WebIconURL> iconURLs(int iconTypes) const = 0;
136 // Geometry -----------------------------------------------------------
138 // NOTE: These routines do not force page layout so their results may
139 // not be accurate if the page layout is out-of-date.
141 // If set to false, do not draw scrollbars on this frame's view.
142 virtual void setCanHaveScrollbars(bool) = 0;
144 // The scroll offset from the top-left corner of the frame in pixels.
145 virtual WebSize scrollOffset() const = 0;
146 virtual void setScrollOffset(const WebSize&) = 0;
148 // The minimum and maxium scroll positions in pixels.
149 virtual WebSize minimumScrollOffset() const = 0;
150 virtual WebSize maximumScrollOffset() const = 0;
152 // The size of the contents area.
153 virtual WebSize contentsSize() const = 0;
155 // Returns the minimum preferred width of the content contained in the
157 virtual int contentsPreferredWidth() const = 0;
159 // Returns the scroll height of the document element. This is
160 // equivalent to the DOM property of the same name, and is the minimum
161 // height required to display the document without scrollbars.
162 virtual int documentElementScrollHeight() const = 0;
164 // Returns true if the contents (minus scrollbars) has non-zero area.
165 virtual bool hasVisibleContent() const = 0;
167 virtual bool hasHorizontalScrollbar() const = 0;
168 virtual bool hasVerticalScrollbar() const = 0;
171 // Hierarchy ----------------------------------------------------------
173 // Returns the containing view.
174 virtual WebView* view() const = 0;
176 // Returns the frame that opened this frame or 0 if there is none.
177 virtual WebFrame* opener() const = 0;
179 // Reset the frame that opened this frame to 0.
180 // This is executed between layout tests runs
181 virtual void clearOpener() = 0;
183 // Returns the parent frame or 0 if this is a top-most frame.
184 virtual WebFrame* parent() const = 0;
186 // Returns the top-most frame in the hierarchy containing this frame.
187 virtual WebFrame* top() const = 0;
189 // Returns the first/last child frame.
190 virtual WebFrame* firstChild() const = 0;
191 virtual WebFrame* lastChild() const = 0;
193 // Returns the next/previous sibling frame.
194 virtual WebFrame* nextSibling() const = 0;
195 virtual WebFrame* previousSibling() const = 0;
197 // Returns the next/previous frame in "frame traversal order"
198 // optionally wrapping around.
199 virtual WebFrame* traverseNext(bool wrap) const = 0;
200 virtual WebFrame* traversePrevious(bool wrap) const = 0;
202 // Returns the child frame identified by the given name.
203 virtual WebFrame* findChildByName(const WebString& name) const = 0;
205 // Returns the child frame identified by the given xpath expression.
206 virtual WebFrame* findChildByExpression(const WebString& xpath) const = 0;
209 // Content ------------------------------------------------------------
211 virtual WebDocument document() const = 0;
213 virtual WebAnimationController* animationController() = 0;
215 virtual WebPerformance performance() const = 0;
218 // Scripting ----------------------------------------------------------
220 // Returns a NPObject corresponding to this frame's DOMWindow.
221 virtual NPObject* windowObject() const = 0;
223 // Binds a NPObject as a property of this frame's DOMWindow.
224 virtual void bindToWindowObject(const WebString& name, NPObject*) = 0;
226 // Executes script in the context of the current page.
227 virtual void executeScript(const WebScriptSource&) = 0;
229 // Executes JavaScript in a new world associated with the web frame.
230 // The script gets its own global scope and its own prototypes for
231 // intrinsic JavaScript objects (String, Array, and so-on). It also
232 // gets its own wrappers for all DOM nodes and DOM constructors.
233 // extensionGroup is an embedder-provided specifier that controls which
234 // v8 extensions are loaded into the new context - see
235 // WebKit::registerExtension for the corresponding specifier.
236 virtual void executeScriptInIsolatedWorld(
237 int worldID, const WebScriptSource* sources, unsigned numSources,
238 int extensionGroup) = 0;
240 // Associates an isolated world (see above for description) with a security
241 // origin. XMLHttpRequest instances used in that world will be considered
242 // to come from that origin, not the frame's.
243 virtual void setIsolatedWorldSecurityOrigin(
244 int worldID, const WebSecurityOrigin&) = 0;
246 // Logs to the console associated with this frame.
247 virtual void addMessageToConsole(const WebConsoleMessage&) = 0;
249 // Calls window.gc() if it is defined.
250 virtual void collectGarbage() = 0;
252 // Check if the scripting URL represents a mixed content condition relative
254 virtual bool checkIfRunInsecureContent(const WebURL&) const = 0;
257 // Executes script in the context of the current page and returns the value
258 // that the script evaluated to.
259 virtual v8::Handle<v8::Value> executeScriptAndReturnValue(
260 const WebScriptSource&) = 0;
262 // Returns the V8 context for this frame, or an empty handle if there
264 virtual v8::Local<v8::Context> mainWorldScriptContext() const = 0;
266 // Creates an instance of file system object.
267 virtual v8::Handle<v8::Value> createFileSystem(WebFileSystem::Type,
268 const WebString& name,
269 const WebString& rootURL) = 0;
270 // Creates an instance of file or directory entry object.
271 virtual v8::Handle<v8::Value> createFileEntry(WebFileSystem::Type,
272 const WebString& fileSystemName,
273 const WebString& fileSystemRootURL,
274 const WebString& filePath,
275 bool isDirectory) = 0;
279 // Navigation ----------------------------------------------------------
281 // Reload the current document.
282 // True |ignoreCache| explicitly bypasses caches.
283 // False |ignoreCache| revalidates any existing cache entries.
284 virtual void reload(bool ignoreCache = false) = 0;
286 // Load the given URL.
287 virtual void loadRequest(const WebURLRequest&) = 0;
289 // Load the given history state, corresponding to a back/forward
291 virtual void loadHistoryItem(const WebHistoryItem&) = 0;
293 // Loads the given data with specific mime type and optional text
294 // encoding. For HTML data, baseURL indicates the security origin of
295 // the document and is used to resolve links. If specified,
296 // unreachableURL is reported via WebDataSource::unreachableURL. If
297 // replace is false, then this data will be loaded as a normal
298 // navigation. Otherwise, the current history item will be replaced.
299 virtual void loadData(const WebData& data,
300 const WebString& mimeType,
301 const WebString& textEncoding,
302 const WebURL& baseURL,
303 const WebURL& unreachableURL = WebURL(),
304 bool replace = false) = 0;
306 // This method is short-hand for calling LoadData, where mime_type is
307 // "text/html" and text_encoding is "UTF-8".
308 virtual void loadHTMLString(const WebData& html,
309 const WebURL& baseURL,
310 const WebURL& unreachableURL = WebURL(),
311 bool replace = false) = 0;
313 // Returns true if the current frame is busy loading content.
314 virtual bool isLoading() const = 0;
316 // Stops any pending loads on the frame and its children.
317 virtual void stopLoading() = 0;
319 // Returns the data source that is currently loading. May be null.
320 virtual WebDataSource* provisionalDataSource() const = 0;
322 // Returns the data source that is currently loaded.
323 virtual WebDataSource* dataSource() const = 0;
325 // Returns the previous history item. Check WebHistoryItem::isNull()
327 virtual WebHistoryItem previousHistoryItem() const = 0;
329 // Returns the current history item. Check WebHistoryItem::isNull()
331 virtual WebHistoryItem currentHistoryItem() const = 0;
333 // View-source rendering mode. Set this before loading an URL to cause
334 // it to be rendered in view-source mode.
335 virtual void enableViewSourceMode(bool) = 0;
336 virtual bool isViewSourceModeEnabled() const = 0;
338 // Sets the referrer for the given request to be the specified URL or
339 // if that is null, then it sets the referrer to the referrer that the
340 // frame would use for subresources. NOTE: This method also filters
341 // out invalid referrers (e.g., it is invalid to send a HTTPS URL as
342 // the referrer for a HTTP request).
343 virtual void setReferrerForRequest(WebURLRequest&, const WebURL&) = 0;
345 // Called to associate the WebURLRequest with this frame. The request
346 // will be modified to inherit parameters that allow it to be loaded.
347 // This method ends up triggering WebFrameClient::willSendRequest.
348 // DEPRECATED: Please use createAssociatedURLLoader instead.
349 virtual void dispatchWillSendRequest(WebURLRequest&) = 0;
351 // Returns a WebURLLoader that is associated with this frame. The loader
352 // will, for example, be cancelled when WebFrame::stopLoading is called.
353 // FIXME: stopLoading does not yet cancel an associated loader!!
354 virtual WebURLLoader* createAssociatedURLLoader(const WebURLLoaderOptions& = WebURLLoaderOptions()) = 0;
356 // Called from within WebFrameClient::didReceiveDocumentData to commit
357 // data for the frame that will be used to construct the frame's
359 virtual void commitDocumentData(const char* data, size_t length) = 0;
361 // Returns the number of registered unload listeners.
362 virtual unsigned unloadListenerCount() const = 0;
364 // Returns true if a user gesture is currently being processed.
365 virtual bool isProcessingUserGesture() const = 0;
367 // Returns true if this frame is in the process of opening a new frame
368 // with a suppressed opener.
369 virtual bool willSuppressOpenerInNewFrame() const = 0;
372 // Editing -------------------------------------------------------------
374 // Replaces the selection with the given text.
375 virtual void replaceSelection(const WebString& text) = 0;
377 virtual void insertText(const WebString& text) = 0;
379 virtual void setMarkedText(const WebString& text, unsigned location, unsigned length) = 0;
380 virtual void unmarkText() = 0;
381 virtual bool hasMarkedText() const = 0;
383 virtual WebRange markedRange() const = 0;
385 // Returns the frame rectangle in window coordinate space of the given text
387 virtual bool firstRectForCharacterRange(unsigned location, unsigned length, WebRect&) const = 0;
389 // Returns the index of a character in the Frame's text stream at the given
390 // point. The point is in the window coordinate space. Will return
391 // WTF::notFound if the point is invalid.
392 virtual size_t characterIndexForPoint(const WebPoint&) const = 0;
394 // Supports commands like Undo, Redo, Cut, Copy, Paste, SelectAll,
395 // Unselect, etc. See EditorCommand.cpp for the full list of supported
397 virtual bool executeCommand(const WebString&, const WebNode& = WebNode()) = 0;
398 virtual bool executeCommand(const WebString&, const WebString& value) = 0;
399 virtual bool isCommandEnabled(const WebString&) const = 0;
401 // Spell-checking support.
402 virtual void enableContinuousSpellChecking(bool) = 0;
403 virtual bool isContinuousSpellCheckingEnabled() const = 0;
406 // Selection -----------------------------------------------------------
408 virtual bool hasSelection() const = 0;
410 virtual WebRange selectionRange() const = 0;
412 virtual WebString selectionAsText() const = 0;
413 virtual WebString selectionAsMarkup() const = 0;
415 // Expands the selection to a word around the caret and returns
416 // true. Does nothing and returns false if there is no caret or
417 // there is ranged selection.
418 virtual bool selectWordAroundCaret() = 0;
420 virtual void selectRange(const WebPoint& start, const WebPoint& end) = 0;
423 // Printing ------------------------------------------------------------
425 // Reformats the WebFrame for printing. pageSize is the page size in
426 // points (a point in 1/72 of an inch). If |constrainToNode| node is
427 // specified, then only the given node is printed (for now only plugins are
428 // supported), instead of the entire frame. printerDPI is the user
429 // selected, DPI for the printer. Returns the number of pages that can be
430 // printed at the given page size. The out param useBrowserOverlays
431 // specifies whether the browser process should use its overlays (header,
432 // footer, margins etc) or whether the renderer controls this.
433 virtual int printBegin(const WebSize& pageSize,
434 const WebNode& constrainToNode = WebNode(),
436 bool* useBrowserOverlays = 0) = 0;
438 // Returns the page shrinking factor calculated by webkit (usually
439 // between 1/1.25 and 1/2). Returns 0 if the page number is invalid or
440 // not in printing mode.
441 virtual float getPrintPageShrink(int page) = 0;
443 // Prints one page, and returns the calculated page shrinking factor
444 // (usually between 1/1.25 and 1/2). Returns 0 if the page number is
445 // invalid or not in printing mode.
446 virtual float printPage(int pageToPrint, WebCanvas*) = 0;
448 // Reformats the WebFrame for screen display.
449 virtual void printEnd() = 0;
451 // CSS3 Paged Media ----------------------------------------------------
453 // Returns true if page box (margin boxes and page borders) is visible.
454 virtual bool isPageBoxVisible(int pageIndex) = 0;
456 // Returns the preferred page size and margins in pixels, assuming 96
457 // pixels per inch. pageSize, marginTop, marginRight, marginBottom,
458 // marginLeft must be initialized to the default values that are used if
459 // auto is specified.
460 virtual void pageSizeAndMarginsInPixels(int pageIndex,
465 int& marginLeft) = 0;
467 // Find-in-page --------------------------------------------------------
469 // Searches a frame for a given string.
471 // If a match is found, this function will select it (scrolling down to
472 // make it visible if needed) and fill in selectionRect with the
473 // location of where the match was found (in window coordinates).
475 // If no match is found, this function clears all tickmarks and
478 // Returns true if the search string was found, false otherwise.
479 virtual bool find(int identifier,
480 const WebString& searchText,
481 const WebFindOptions& options,
482 bool wrapWithinFrame,
483 WebRect* selectionRect) = 0;
485 // Notifies the frame that we are no longer interested in searching.
486 // This will abort any asynchronous scoping effort already under way
487 // (see the function scopeStringMatches for details) and erase all
488 // tick-marks and highlighting from the previous search. If
489 // clearSelection is true, it will also make sure the end state for the
490 // find operation does not leave a selection. This can occur when the
491 // user clears the search string but does not close the find box.
492 virtual void stopFinding(bool clearSelection) = 0;
494 // Counts how many times a particular string occurs within the frame.
495 // It also retrieves the location of the string and updates a vector in
496 // the frame so that tick-marks and highlighting can be drawn. This
497 // function does its work asynchronously, by running for a certain
498 // time-slice and then scheduling itself (co-operative multitasking) to
499 // be invoked later (repeating the process until all matches have been
500 // found). This allows multiple frames to be searched at the same time
501 // and provides a way to cancel at any time (see
502 // cancelPendingScopingEffort). The parameter searchText specifies
503 // what to look for and |reset| signals whether this is a brand new
504 // request or a continuation of the last scoping effort.
505 virtual void scopeStringMatches(int identifier,
506 const WebString& searchText,
507 const WebFindOptions& options,
510 // Cancels any outstanding requests for scoping string matches on a frame.
511 virtual void cancelPendingScopingEffort() = 0;
513 // This function is called on the main frame during the scoping effort
514 // to keep a running tally of the accumulated total match-count for all
515 // frames. After updating the count it will notify the WebViewClient
516 // about the new count.
517 virtual void increaseMatchCount(int count, int identifier) = 0;
519 // This function is called on the main frame to reset the total number
520 // of matches found during the scoping effort.
521 virtual void resetMatchCount() = 0;
524 // Utility -------------------------------------------------------------
526 // Returns the contents of this frame as a string. If the text is
527 // longer than maxChars, it will be clipped to that length. WARNING:
528 // This function may be slow depending on the number of characters
529 // retrieved and page complexity. For a typically sized page, expect
530 // it to take on the order of milliseconds.
532 // If there is room, subframe text will be recursively appended. Each
533 // frame will be separated by an empty line.
534 virtual WebString contentAsText(size_t maxChars) const = 0;
536 // Returns HTML text for the contents of this frame. This is generated
538 virtual WebString contentAsMarkup() const = 0;
540 // Returns a text representation of the render tree. This method is used
541 // to support layout tests.
542 virtual WebString renderTreeAsText(bool showDebugInfo = false) const = 0;
544 // Returns the counter value for the specified element. This method is
545 // used to support layout tests.
546 virtual WebString counterValueForElementById(const WebString& id) const = 0;
548 // Calls markerTextForListItem() defined in WebCore/rendering/RenderTreeAsText.h.
549 virtual WebString markerTextForListItem(const WebElement&) const = 0;
551 // Returns the number of page where the specified element will be put.
552 // This method is used to support layout tests.
553 virtual int pageNumberForElementById(const WebString& id,
554 float pageWidthInPixels,
555 float pageHeightInPixels) const = 0;
557 // Returns the bounds rect for current selection. If selection is performed
558 // on transformed text, the rect will still bound the selection but will
559 // not be transformed itself. If no selection is present, the rect will be
560 // empty ((0,0), (0,0)).
561 virtual WebRect selectionBoundsRect() const = 0;
563 // Only for testing purpose:
564 // Returns true if selection.anchorNode has a marker on range from |from| with |length|.
565 virtual bool selectionStartHasSpellingMarkerFor(int from, int length) const = 0;
567 // Pauses and samples an SVG animation. Returns false if there's no svg
568 // animation to pause. This is only for testing.
569 virtual bool pauseSVGAnimation(const WebString& animationId,
571 const WebString& elementId) = 0;
573 // Dumps the layer tree, used by the accelerated compositor, in
574 // text form. This is used only by layout tests.
575 virtual WebString layerTreeAsText(bool showDebugInfo = false) const = 0;
581 } // namespace WebKit