diff options
Diffstat (limited to 'webkit/api/public/WebFrame.h')
| -rw-r--r-- | webkit/api/public/WebFrame.h | 278 |
1 files changed, 219 insertions, 59 deletions
diff --git a/webkit/api/public/WebFrame.h b/webkit/api/public/WebFrame.h index acb8dff..954c379 100644 --- a/webkit/api/public/WebFrame.h +++ b/webkit/api/public/WebFrame.h @@ -31,47 +31,73 @@ #ifndef WebFrame_h #define WebFrame_h -#error "This header file is still a work in progress; do not include!" - -#include "WebCommon.h" +#include "WebCanvas.h" +#include "WebURL.h" +class WebView; // FIXME: Move into the WebKit namespace. struct NPObject; +#if WEBKIT_USING_V8 +namespace v8 { + class Context; + template <class T> class Local; +} +#endif + namespace WebKit { class WebData; class WebDataSource; + class WebForm; class WebHistoryItem; + class WebRange; class WebString; class WebURL; class WebURLRequest; - class WebView; + struct WebConsoleMessage; + struct WebFindOptions; + struct WebRect; + struct WebScriptSource; + struct WebSize; + template <typename T> class WebVector; class WebFrame { public: - // Returns the frame that is currently executing script or 0 if there - // is none. - WEBKIT_API static WebFrame* activeFrame(); + // The two functions below retrieve the WebFrame instances relating the + // currently executing JavaScript. Since JavaScript can make function + // calls across frames, though, we need to be more precise. + // + // For example, imagine that a JS function in frame A calls a function + // in frame B, which calls native code, which wants to know what the + // 'active' frame is. + // + // The 'entered context' is the context where execution first entered + // the script engine; the context that is at the bottom of the JS + // function stack. frameForEnteredContext() would return frame A in + // our example. + // + // The 'current context' is the context the JS engine is currently + // inside of; the context that is at the top of the JS function stack. + // frameForCurrentContext() would return frame B in our example. + WEBKIT_API static WebFrame* frameForEnteredContext(); + WEBKIT_API static WebFrame* frameForCurrentContext(); // Basic properties --------------------------------------------------- // The name of this frame. - virtual WebString name() = 0; + virtual WebString name() const = 0; // The url of the document loaded in this frame. This is equivalent to // dataSource()->request().url(). - virtual WebURL url() = 0; + virtual WebURL url() const = 0; // The url of the favicon (if any) specified by the document loaded in // this frame. - virtual WebURL favIconURL() = 0; + virtual WebURL favIconURL() const = 0; // The url of the OpenSearch Desription Document (if any) specified by // the document loaded in this frame. - virtual WebURL openSearchDescriptionURL() = 0; - - // Returns the security origin of the current document. - virtual WebString securityOrigin() = 0; + virtual WebURL openSearchDescriptionURL() const = 0; // Geometry ----------------------------------------------------------- @@ -80,57 +106,70 @@ namespace WebKit { // not be accurate if the page layout is out-of-date. // The scroll offset from the top-left corner of the frame in pixels. - virtual WebSize scrollOffset() = 0; + virtual WebSize scrollOffset() const = 0; // The size of the contents area. - virtual WebSize contentsSize() = 0; + virtual WebSize contentsSize() const = 0; // Returns the minimum preferred width of the content contained in the // current document. - virtual int contentsPreferredWidth() = 0; + virtual int contentsPreferredWidth() const = 0; // Returns true if the contents (minus scrollbars) has non-zero area. - virtual bool hasVisibleContent() = 0; + virtual bool hasVisibleContent() const = 0; // Hierarchy ---------------------------------------------------------- // Returns the containing view. - virtual WebView* view() = 0; + virtual WebView* view() const = 0; + + // Returns the frame that opened this frame or 0 if there is none. + virtual WebFrame* opener() const = 0; - // Returns the parent frame. - virtual WebFrame* parent() = 0; + // Returns the parent frame or 0 if this is a top-most frame. + virtual WebFrame* parent() const = 0; // Returns the top-most frame in the hierarchy containing this frame. - virtual WebFrame* top() = 0; + virtual WebFrame* top() const = 0; // Returns the first/last child frame. - virtual WebFrame* firstChild() = 0; - virtual WebFrame* lastChild() = 0; + virtual WebFrame* firstChild() const = 0; + virtual WebFrame* lastChild() const = 0; // Returns the next/previous sibling frame. - virtual WebFrame* nextSibling() = 0; - virtual WebFrame* previousSibling() = 0; + virtual WebFrame* nextSibling() const = 0; + virtual WebFrame* previousSibling() const = 0; // Returns the next/previous frame in "frame traversal order" // optionally wrapping around. - virtual WebFrame* traverseNext(bool wrap) = 0; - virtual WebFrame* traversePrevious(bool wrap) = 0; + virtual WebFrame* traverseNext(bool wrap) const = 0; + virtual WebFrame* traversePrevious(bool wrap) const = 0; // Returns the child frame identified by the given name. - virtual WebFrame* findChildByName(const WebString& name) = 0; + virtual WebFrame* findChildByName(const WebString& name) const = 0; // Returns the child frame identified by the given xpath expression. - virtual WebFrame* findChildByExpression(const WebString& xpath) = 0; + virtual WebFrame* findChildByExpression(const WebString& xpath) const = 0; + + + // Content ------------------------------------------------------------ + + virtual void forms(WebVector<WebForm>&) const = 0; // Scripting ---------------------------------------------------------- - // Calls window.gc() if it is defined. - virtual void collectGarbage() = 0; + // Returns the security origin of the current document. + virtual WebString securityOrigin() const = 0; + + // This grants the currently loaded document access to all security + // origins (including file URLs). Use with care. The access is + // revoked when a new document is loaded into this frame. + virtual void grantUniversalAccess() = 0; // Returns a NPObject corresponding to this frame's DOMWindow. - virtual NPObject* windowObject() = 0; + virtual NPObject* windowObject() const = 0; // Binds a NPObject as a property of this frame's DOMWindow. virtual void bindToWindowObject(const WebString& name, NPObject*) = 0; @@ -141,20 +180,37 @@ namespace WebKit { // Executes script in a new context associated with the frame. The // script gets its own global scope and its own prototypes for // intrinsic JS objects (String, Array, and so-on). It shares the - // wrappers for all DOM nodes and DOM constructors. + // wrappers for all DOM nodes and DOM constructors. extensionGroup is + // an embedder-provided specifier that controls which v8 extensions are + // loaded into the new context - see WebKit::registerExtension for the + // corresponding specifier. virtual void executeScriptInNewContext(const WebScriptSource* sources, - unsigned numSources) = 0; + unsigned numSources, + int extensionGroup) = 0; // Executes JavaScript in a new world associated with the web frame. // The script gets its own global scope and its own prototypes for // intrinsic JavaScript objects (String, Array, and so-on). It also // gets its own wrappers for all DOM nodes and DOM constructors. + // extensionGroup is an embedder-provided specifier that controls which + // v8 extensions are loaded into the new context - see + // WebKit::registerExtension for the corresponding specifier. virtual void executeScriptInNewWorld(const WebScriptSource* sources, - unsigned numSources) = 0; + unsigned numSources, + int extensionGroup) = 0; // Logs to the console associated with this frame. virtual void addMessageToConsole(const WebConsoleMessage&) = 0; + // Calls window.gc() if it is defined. + virtual void collectGarbage() = 0; + +#if WEBKIT_USING_V8 + // Returns the V8 context for this frame, or an empty handle if there + // is none. + virtual v8::Local<v8::Context> mainWorldScriptContext() const = 0; +#endif + // Styling ------------------------------------------------------------- @@ -165,12 +221,22 @@ namespace WebKit { // Navigation ---------------------------------------------------------- + // Reload the current document. virtual void reload() = 0; + // Load the given URL. virtual void loadRequest(const WebURLRequest&) = 0; + // Load the given history state, corresponding to a back/forward + // navigation. virtual void loadHistoryItem(const WebHistoryItem&) = 0; + // Loads the given data with specific mime type and optional text + // encoding. For HTML data, baseURL indicates the security origin of + // the document and is used to resolve links. If specified, + // unreachableURL is reported via WebDataSource::unreachableURL. If + // replace is false, then this data will be loaded as a normal + // navigation. Otherwise, the current history item will be replaced. virtual void loadData(const WebData& data, const WebString& mimeType, const WebString& textEncoding, @@ -178,43 +244,50 @@ namespace WebKit { const WebURL& unreachableURL = WebURL(), bool replace = false) = 0; + // This method is short-hand for calling LoadData, where mime_type is + // "text/html" and text_encoding is "UTF-8". virtual void loadHTMLString(const WebData& html, const WebURL& baseURL, const WebURL& unreachableURL = WebURL(), bool replace = false) = 0; - virtual bool isLoading() = 0; + // Returns true if the current frame is busy loading content. + virtual bool isLoading() const = 0; // Stops any pending loads on the frame and its children. virtual void stopLoading() = 0; // Returns the data source that is currently loading. May be null. - virtual WebDataSource* provisionalDataSource() = 0; + virtual WebDataSource* provisionalDataSource() const = 0; // Returns the data source that is currently loaded. - virtual WebDataSource* dataSource() = 0; + virtual WebDataSource* dataSource() const = 0; // Returns the previous history item. Check WebHistoryItem::isNull() // before using. - virtual WebHistoryItem previousHistoryItem() = 0; + virtual WebHistoryItem previousHistoryItem() const = 0; // Returns the current history item. Check WebHistoryItem::isNull() // before using. - virtual WebHistoryItem currentHistoryItem() = 0; + virtual WebHistoryItem currentHistoryItem() const = 0; // View-source rendering mode. Set this before loading an URL to cause // it to be rendered in view-source mode. virtual void enableViewSourceMode(bool) = 0; - virtual bool isViewSourceModeEnabled() = 0; + virtual bool isViewSourceModeEnabled() const = 0; + // Called to associate the WebURLRequest with this frame. The request + // will be modified to inherit parameters that allow it to be loaded. + // This method ends up triggering WebFrameClient::willSendRequest. + virtual void dispatchWillSendRequest(WebURLRequest&) = 0; - // App-cache ----------------------------------------------------------- - - virtual void selectAppCacheWithoutManifest() = 0; - virtual void selectAppCacheWithManifest(const WebURL& manifest) = 0; + // Called from within WebFrameClient::didReceiveDocumentData to commit + // data for the frame that will be used to construct the frame's + // document. + virtual void commitDocumentData(const char* data, size_t length) = 0; - // Will be null if an app cache has not been selected. - virtual WebAppCacheContext* appCacheContext() = 0; + // Returns the number of registered unload listeners. + virtual unsigned unloadListenerCount() const = 0; // Editing ------------------------------------------------------------- @@ -222,23 +295,34 @@ namespace WebKit { // Replaces the selection with the given text. virtual void replaceSelection(const WebString& text) = 0; + virtual void insertText(const WebString& text) = 0; + + virtual void setMarkedText(const WebString& text, unsigned location, unsigned length) = 0; + virtual void unmarkText() = 0; + virtual bool hasMarkedText() const = 0; + + virtual WebRange markedRange() const = 0; + // See EditorCommand.cpp for the list of supported commands. - virtual void executeCommand(const WebString&) = 0; - virtual void executeCommand(const WebString&, const WebString& value) = 0; - virtual bool isCommandEnabled(const WebString&); + virtual bool executeCommand(const WebString&) = 0; + virtual bool executeCommand(const WebString&, const WebString& value) = 0; + virtual bool isCommandEnabled(const WebString&) const = 0; // Spell-checking support. virtual void enableContinuousSpellChecking(bool) = 0; - virtual bool isContinuousSpellCheckingEnabled() = 0; + virtual bool isContinuousSpellCheckingEnabled() const = 0; // Selection ----------------------------------------------------------- virtual void selectAll() = 0; - virtual void selectNone() = 0; + virtual void clearSelection() = 0; + virtual bool hasSelection() const = 0; + + virtual WebRange selectionRange() const = 0; - virtual WebString selectionAsText() = 0; - virtual WebString selectionAsHTML() = 0; + virtual WebString selectionAsText() const = 0; + virtual WebString selectionAsMarkup() const = 0; // Printing ------------------------------------------------------------ @@ -246,20 +330,96 @@ namespace WebKit { // Reformats the WebFrame for printing. pageSize is the page size in // pixels. Returns the number of pages that can be printed at the // given page size. - virtual int printBegin(const WebSize& pageSize); + virtual int printBegin(const WebSize& pageSize) = 0; // Prints one page, and returns the calculated page shrinking factor // (usually between 1/1.25 and 1/2). Returns 0 if the page number is // invalid or not in printing mode. - virtual float printPage(int pageToPrint, const WebCanvas&); + virtual float printPage(int pageToPrint, WebCanvas*) = 0; // Reformats the WebFrame for screen display. - virtual void printEnd(); + virtual void printEnd() = 0; // Find-in-page -------------------------------------------------------- - // FIXME + // Searches a frame for a given string. + // + // If a match is found, this function will select it (scrolling down to + // make it visible if needed) and fill in selectionRect with the + // location of where the match was found (in window coordinates). + // + // If no match is found, this function clears all tickmarks and + // highlighting. + // + // Returns true if the search string was found, false otherwise. + virtual bool find(int identifier, + const WebString& searchText, + const WebFindOptions& options, + bool wrapWithinFrame, + WebRect* selectionRect) = 0; + + // Notifies the frame that we are no longer interested in searching. + // This will abort any asynchronous scoping effort already under way + // (see the function scopeStringMatches for details) and erase all + // tick-marks and highlighting from the previous search. If + // clearSelection is true, it will also make sure the end state for the + // find operation does not leave a selection. This can occur when the + // user clears the search string but does not close the find box. + virtual void stopFinding(bool clearSelection) = 0; + + // Counts how many times a particular string occurs within the frame. + // It also retrieves the location of the string and updates a vector in + // the frame so that tick-marks and highlighting can be drawn. This + // function does its work asynchronously, by running for a certain + // time-slice and then scheduling itself (co-operative multitasking) to + // be invoked later (repeating the process until all matches have been + // found). This allows multiple frames to be searched at the same time + // and provides a way to cancel at any time (see + // cancelPendingScopingEffort). The parameter searchText specifies + // what to look for and |reset| signals whether this is a brand new + // request or a continuation of the last scoping effort. + virtual void scopeStringMatches(int identifier, + const WebString& searchText, + const WebFindOptions& options, + bool reset) = 0; + + // Cancels any outstanding requests for scoping string matches on a frame. + virtual void cancelPendingScopingEffort() = 0; + + // This function is called on the main frame during the scoping effort + // to keep a running tally of the accumulated total match-count for all + // frames. After updating the count it will notify the WebViewClient + // about the new count. + virtual void increaseMatchCount(int count, int identifier) = 0; + + // Notifies the WebViewClient about a new selection rect. This will + // result in the browser getting notified. For more information see + // WebViewClient. + virtual void reportFindInPageSelection(const WebRect& selectionRect, + int activeMatchOrdinal, + int identifier) = 0; + + // This function is called on the main frame to reset the total number + // of matches found during the scoping effort. + virtual void resetMatchCount() = 0; + + + // Utility ------------------------------------------------------------- + + // Returns the contents of this frame as a string. If the text is + // longer than maxChars, it will be clipped to that length. WARNING: + // This function may be slow depending on the number of characters + // retrieved and page complexity. For a typically sized page, expect + // it to take on the order of milliseconds. + // + // If there is room, subframe text will be recursively appended. Each + // frame will be separated by an empty line. + virtual WebString contentAsText(size_t maxChars) const = 0; + + // Returns HTML text for the contents of this frame. This is generated + // from the DOM. + virtual WebString contentAsMarkup() const = 0; }; } // namespace WebKit |