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