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