--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/WebKit/chromium/public/WebFrame.h Fri Sep 17 09:02:29 2010 +0300
@@ -0,0 +1,540 @@
+/*
+ * Copyright (C) 2009 Google Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ * * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef WebFrame_h
+#define WebFrame_h
+
+#include "WebCanvas.h"
+#include "WebURL.h"
+
+struct NPObject;
+
+#if WEBKIT_USING_V8
+namespace v8 {
+class Context;
+class Value;
+template <class T> class Handle;
+template <class T> class Local;
+}
+#endif
+
+namespace WebKit {
+
+class WebAnimationController;
+class WebData;
+class WebDataSource;
+class WebDocument;
+class WebElement;
+class WebFormElement;
+class WebHistoryItem;
+class WebInputElement;
+class WebPasswordAutocompleteListener;
+class WebRange;
+class WebSecurityOrigin;
+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 number of live WebFrame objects, used for leak checking.
+ WEBKIT_API static int instanceCount();
+
+ // 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();
+
+ // Returns the frame inside a given frame or iframe element. Returns 0 if
+ // the given element is not a frame, iframe or if the frame is empty.
+ WEBKIT_API static WebFrame* fromFrameOwnerElement(const WebElement&);
+
+
+ // Basic properties ---------------------------------------------------
+
+ // The name of this frame.
+ virtual WebString name() const = 0;
+
+ // Sets the name of this frame. For child frames (frames that are not a
+ // top-most frame) the actual name may have a suffix appended to make the
+ // frame name unique within the hierarchy.
+ virtual void setName(const WebString&) = 0;
+
+ // The url of the document loaded in this frame. This is equivalent to
+ // dataSource()->request().url().
+ virtual WebURL url() const = 0;
+
+ // The url of the favicon (if any) specified by the document loaded in
+ // this frame.
+ 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() const = 0;
+
+ // Return the frame's encoding.
+ virtual WebString encoding() const = 0;
+
+
+ // Geometry -----------------------------------------------------------
+
+ // NOTE: These routines do not force page layout so their results may
+ // not be accurate if the page layout is out-of-date.
+
+ // If set to false, do not draw scrollbars on this frame's view.
+ virtual void setCanHaveScrollbars(bool) = 0;
+
+ // The scroll offset from the top-left corner of the frame in pixels.
+ virtual WebSize scrollOffset() const = 0;
+
+ // The size of the contents area.
+ virtual WebSize contentsSize() const = 0;
+
+ // Returns the minimum preferred width of the content contained in the
+ // current document.
+ virtual int contentsPreferredWidth() const = 0;
+
+ // Returns the scroll height of the document element. This is
+ // equivalent to the DOM property of the same name, and is the minimum
+ // height required to display the document without scrollbars.
+ virtual int documentElementScrollHeight() const = 0;
+
+ // Returns true if the contents (minus scrollbars) has non-zero area.
+ virtual bool hasVisibleContent() const = 0;
+
+
+ // Hierarchy ----------------------------------------------------------
+
+ // Returns the containing view.
+ 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 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() const = 0;
+
+ // Returns the first/last child frame.
+ virtual WebFrame* firstChild() const = 0;
+ virtual WebFrame* lastChild() const = 0;
+
+ // Returns the next/previous sibling frame.
+ 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) const = 0;
+ virtual WebFrame* traversePrevious(bool wrap) const = 0;
+
+ // Returns the child frame identified by the given name.
+ virtual WebFrame* findChildByName(const WebString& name) const = 0;
+
+ // Returns the child frame identified by the given xpath expression.
+ virtual WebFrame* findChildByExpression(const WebString& xpath) const = 0;
+
+
+ // Content ------------------------------------------------------------
+
+ virtual WebDocument document() const = 0;
+
+ virtual void forms(WebVector<WebFormElement>&) const = 0;
+
+ virtual WebAnimationController* animationController() = 0;
+
+
+ // Scripting ----------------------------------------------------------
+
+ // Returns the security origin of the current document.
+ virtual WebSecurityOrigin 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() const = 0;
+
+ // Binds a NPObject as a property of this frame's DOMWindow.
+ virtual void bindToWindowObject(const WebString& name, NPObject*) = 0;
+
+ // Executes script in the context of the current page.
+ virtual void executeScript(const WebScriptSource&) = 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 executeScriptInIsolatedWorld(
+ int worldId, const WebScriptSource* sources, 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
+ // Executes script in the context of the current page and returns the value
+ // that the script evaluated to.
+ virtual v8::Handle<v8::Value> executeScriptAndReturnValue(
+ const WebScriptSource&) = 0;
+
+ // 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 -------------------------------------------------------------
+
+ // Insert the given text as a STYLE element at the beginning of the
+ // document. |elementId| can be empty, but if specified then it is used
+ // as the id for the newly inserted element (replacing an existing one
+ // with the same id, if any).
+ virtual bool insertStyleText(const WebString& styleText,
+ const WebString& elementId) = 0;
+
+
+ // Navigation ----------------------------------------------------------
+
+ // Reload the current document.
+ // True |ignoreCache| explicitly bypasses caches.
+ // False |ignoreCache| revalidates any existing cache entries.
+ virtual void reload(bool ignoreCache = false) = 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,
+ const WebURL& baseURL,
+ 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;
+
+ // 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() const = 0;
+
+ // Returns the data source that is currently loaded.
+ virtual WebDataSource* dataSource() const = 0;
+
+ // Returns the previous history item. Check WebHistoryItem::isNull()
+ // before using.
+ virtual WebHistoryItem previousHistoryItem() const = 0;
+
+ // Returns the current history item. Check WebHistoryItem::isNull()
+ // before using.
+ 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() const = 0;
+
+ // Sets the referrer for the given request to be the specified URL or
+ // if that is null, then it sets the referrer to the referrer that the
+ // frame would use for subresources. NOTE: This method also filters
+ // out invalid referrers (e.g., it is invalid to send a HTTPS URL as
+ // the referrer for a HTTP request).
+ virtual void setReferrerForRequest(WebURLRequest&, const WebURL&) = 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;
+
+ // 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;
+
+ // Returns the number of registered unload listeners.
+ virtual unsigned unloadListenerCount() const = 0;
+
+ // Returns true if a user gesture is currently being processed.
+ virtual bool isProcessingUserGesture() const = 0;
+
+ // Returns true if this frame is in the process of opening a new frame
+ // with a suppressed opener.
+ virtual bool willSuppressOpenerInNewFrame() const = 0;
+
+
+ // Editing -------------------------------------------------------------
+
+ // 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;
+
+ // Supports commands like Undo, Redo, Cut, Copy, Paste, SelectAll,
+ // Unselect, etc. See EditorCommand.cpp for the full list of supported
+ // commands.
+ 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() const = 0;
+
+
+ // Selection -----------------------------------------------------------
+
+ virtual bool hasSelection() const = 0;
+
+ virtual WebRange selectionRange() const = 0;
+
+ virtual WebString selectionAsText() const = 0;
+ virtual WebString selectionAsMarkup() const = 0;
+
+ // Expands the selection to a word around the caret and returns
+ // true. Does nothing and returns false if there is no caret or
+ // there is ranged selection.
+ virtual bool selectWordAroundCaret() = 0;
+
+
+ // Printing ------------------------------------------------------------
+
+ // Reformats the WebFrame for printing. pageSize is the page size in
+ // points (a point in 1/72 of an inch). printerDPI is the user selected,
+ // DPI for the printer. Returns the number of pages that
+ // can be printed at the given page size. The out param useBrowserOverlays
+ // specifies whether the browser process should use its overlays (header,
+ // footer, margins etc) or whether the renderer controls this.
+ virtual int printBegin(const WebSize& pageSize, int printerDPI = 72,
+ bool* useBrowserOverlays = 0) = 0;
+
+ // Returns the page shrinking factor calculated by webkit (usually
+ // between 1/1.25 and 1/2). Returns 0 if the page number is invalid or
+ // not in printing mode.
+ virtual float getPrintPageShrink(int page) = 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, WebCanvas*) = 0;
+
+ // Reformats the WebFrame for screen display.
+ virtual void printEnd() = 0;
+
+ // CSS3 Paged Media ----------------------------------------------------
+
+ // Returns true if page box (margin boxes and page borders) is visible.
+ virtual bool isPageBoxVisible(int pageIndex) = 0;
+
+ // Returns the preferred page size and margins in pixels, assuming 96
+ // pixels per inch. pageSize, marginTop, marginRight, marginBottom,
+ // marginLeft must be initialized to the default values that are used if
+ // auto is specified.
+ virtual void pageSizeAndMarginsInPixels(int pageIndex,
+ WebSize& pageSize,
+ int& marginTop,
+ int& marginRight,
+ int& marginBottom,
+ int& marginLeft) = 0;
+
+ // Find-in-page --------------------------------------------------------
+
+ // 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;
+
+ // This function is called on the main frame to reset the total number
+ // of matches found during the scoping effort.
+ virtual void resetMatchCount() = 0;
+
+
+ // Password autocompletion ---------------------------------------------
+
+ // Registers a listener for the specified user name input element. The
+ // listener will receive notifications for blur and when autocomplete
+ // should be triggered.
+ // An element can have only one listener. If a listener already exists,
+ // this method returns false and does not add the new one.
+ // Either way, the WebFrame becomes the owner of the passed listener.
+ virtual bool registerPasswordListener(
+ WebInputElement,
+ WebPasswordAutocompleteListener*) = 0;
+
+ // Dispatches an Autocompletion notification to registered listener if one
+ // exists that is registered against the WebInputElement specified.
+ virtual void notifiyPasswordListenerOfAutocomplete(
+ const WebInputElement&) = 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;
+
+ // Returns a text representation of the render tree. This method is used
+ // to support layout tests.
+ virtual WebString renderTreeAsText() const = 0;
+
+ // Returns the counter value for the specified element. This method is
+ // used to support layout tests.
+ virtual WebString counterValueForElementById(const WebString& id) const = 0;
+
+
+ // Returns the number of page where the specified element will be put.
+ // This method is used to support layout tests.
+ virtual int pageNumberForElementById(const WebString& id,
+ float pageWidthInPixels,
+ float pageHeightInPixels) const = 0;
+
+ // Returns the bounds rect for current selection. If selection is performed
+ // on transformed text, the rect will still bound the selection but will
+ // not be transformed itself. If no selection is present, the rect will be
+ // empty ((0,0), (0,0)).
+ virtual WebRect selectionBoundsRect() const = 0;
+
+protected:
+ ~WebFrame() { }
+};
+
+} // namespace WebKit
+
+#endif