diff options
Diffstat (limited to 'src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc')
| -rw-r--r-- | src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc | 1962 |
1 files changed, 1962 insertions, 0 deletions
diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc new file mode 100644 index 000000000..a63ac9c6f --- /dev/null +++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc @@ -0,0 +1,1962 @@ +/* + Copyright (C) 2008, 2009, 2012 Nokia Corporation and/or its subsidiary(-ies) + Copyright (C) 2007 Staikos Computing Services Inc. + Copyright (C) 2007 Apple Inc. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +// The documentation in this file was imported from QtWebKit and is thus constrained +// by its LGPL license. Documentation written from scratch for new methods should be +// placed inline in the code as usual. + +/*! + \class QWebPage + \since 4.4 + \brief The QWebPage class provides an object to view and edit web documents. + + \inmodule QtWebKit + + QWebPage holds a main frame responsible for web content, settings, the history + of navigated links and actions. This class can be used, together with QWebFrame, + to provide functionality like QWebView in a widget-less environment. + + QWebPage's API is very similar to QWebView, as you are still provided with + common functions like action() (known as + \l{QWebView::pageAction()}{pageAction}() in QWebView), triggerAction(), + findText() and settings(). More QWebView-like functions can be found in the + main frame of QWebPage, obtained via the mainFrame() function. For example, + the \l{QWebFrame::load()}{load}(), \l{QWebFrame::setUrl()}{setUrl}() and + \l{QWebFrame::setHtml()}{setHtml}() functions for QWebPage can be accessed + using QWebFrame. + + The loadStarted() signal is emitted when the page begins to load.The + loadProgress() signal, on the other hand, is emitted whenever an element + of the web page completes loading, such as an embedded image, a script, + etc. Finally, the loadFinished() signal is emitted when the page contents + are loaded completely, independent of script execution or page rendering. + Its argument, either true or false, indicates whether or not the load + operation succeeded. + + \section1 Using QWebPage in a Widget-less Environment + + Before you begin painting a QWebPage object, you need to set the size of + the viewport by calling setViewportSize(). Then, you invoke the main + frame's render function (QWebFrame::render()). An example of this + is shown in the code snippet below. + + Suppose we have a \c Thumbnail class as follows: + + \snippet webkitsnippets/webpage/main.cpp 0 + + The \c Thumbnail's constructor takes in a \a url. We connect our QWebPage + object's \l{QWebPage::}{loadFinished()} signal to our private slot, + \c render(). + + \snippet webkitsnippets/webpage/main.cpp 1 + + The \c render() function shows how we can paint a thumbnail using a + QWebPage object. + + \snippet webkitsnippets/webpage/main.cpp 2 + + We begin by setting the \l{QWebPage::viewportSize()}{viewportSize} and + then we instantiate a QImage object, \c image, with the same size as our + \l{QWebPage::viewportSize()}{viewportSize}. This image is then sent + as a parameter to \c painter. Next, we render the contents of the main + frame and its subframes into \c painter. Finally, we save the scaled image. + + \sa QWebFrame +*/ + +/*! + \fn QMenu *QWebPage::createStandardContextMenu() + \since 4.5 + This function creates the standard context menu which is shown when + the user clicks on the web page with the right mouse button. It is + called from the default contextMenuEvent() handler. The popup menu's + ownership is transferred to the caller. + */ + +/*! + \property QWebPage::palette + \brief the page's palette + + The base brush of the palette is used to draw the background of the main frame. + + By default, this property contains the application's default palette. +*/ + +/*! + \fn QVariant QWebPage::inputMethodQuery(Qt::InputMethodQuery property) const + This method is used by the input method to query a set of properties of the page + to be able to support complex input method operations as support for surrounding + text and reconversions. + + \a property specifies which property is queried. + + \sa QWidget::inputMethodEvent(), QInputMethodEvent, QInputContext +*/ + +/*! + \enum QWebPage::FindFlag + + This enum describes the options available to the findText() function. The options + can be OR-ed together from the following list: + + \value FindBackward Searches backwards instead of forwards. + \value FindCaseSensitively By default findText() works case insensitive. Specifying this option + changes the behavior to a case sensitive find operation. + \value FindWrapsAroundDocument Makes findText() restart from the beginning of the document if the end + was reached and the text was not found. + \value HighlightAllOccurrences Highlights all existing occurrences of a specific string. + (This value was introduced in 4.6.) + \value FindAtWordBeginningsOnly Searches for the sub-string only at the beginnings of words. + (This value was introduced in 5.2.) + \value TreatMedialCapitalAsWordBeginning Treats a capital letter occurring anywhere in the middle of a word + as the beginning of a new word. + (This value was introduced in 5.2.) + \value FindBeginsInSelection Begin searching inside the text selection first. + (This value was introduced in 5.2.) +*/ + +/*! + \enum QWebPage::LinkDelegationPolicy + + This enum defines the delegation policies a webpage can have when activating links and emitting + the linkClicked() signal. + + \value DontDelegateLinks No links are delegated. Instead, QWebPage tries to handle them all. + \value DelegateExternalLinks When activating links that point to documents not stored on the + local filesystem or an equivalent - such as the Qt resource system - then linkClicked() is emitted. + \value DelegateAllLinks Whenever a link is activated the linkClicked() signal is emitted. + + \sa QWebPage::linkDelegationPolicy +*/ + +/*! + \enum QWebPage::NavigationType + + This enum describes the types of navigation available when browsing through hyperlinked + documents. + + \value NavigationTypeLinkClicked The user clicked on a link or pressed return on a focused link. + \value NavigationTypeFormSubmitted The user activated a submit button for an HTML form. + \value NavigationTypeBackOrForward Navigation to a previously shown document in the back or forward history is requested. + \value NavigationTypeReload The user activated the reload action. + \value NavigationTypeFormResubmitted An HTML form was submitted a second time. + \value NavigationTypeOther A navigation to another document using a method not listed above. + + \sa acceptNavigationRequest() +*/ + +/*! + \enum QWebPage::WebAction + + This enum describes the types of action which can be performed on the web page. + + Actions only have an effect when they are applicable. The availability of + actions can be be determined by checking \l{QAction::}{isEnabled()} on the + action returned by action(). + + One method of enabling the text editing, cursor movement, and text selection actions + is by setting \l contentEditable to true. + + \value NoWebAction No action is triggered. + \value OpenLink Open the current link. + \value OpenLinkInNewWindow Open the current link in a new window. + \value OpenLinkInThisWindow Open the current link without opening a new window. Used on links that would default to opening in another frame or a new window. (Added in Qt 5.0) + \value OpenFrameInNewWindow Replicate the current frame in a new window. + \value DownloadLinkToDisk Download the current link to the disk. + \value CopyLinkToClipboard Copy the current link to the clipboard. + \value OpenImageInNewWindow Open the highlighted image in a new window. + \value DownloadImageToDisk Download the highlighted image to the disk. + \value CopyImageToClipboard Copy the highlighted image to the clipboard. (Added in Qt 4.8) + \value CopyImageUrlToClipboard Copy the highlighted image's URL to the clipboard. + \value Back Navigate back in the history of navigated links. + \value Forward Navigate forward in the history of navigated links. + \value Stop Stop loading the current page. + \value StopScheduledPageRefresh Stop all pending page refresh/redirect requests. (Added in Qt 4.7) + \value Reload Reload the current page. + \value ReloadAndBypassCache Reload the current page, but do not use any local cache. (Added in Qt 4.6) + \value Cut Cut the content currently selected into the clipboard. + \value Copy Copy the content currently selected into the clipboard. + \value Paste Paste content from the clipboard. + \value Undo Undo the last editing action. + \value Redo Redo the last editing action. + \value MoveToNextChar Move the cursor to the next character. + \value MoveToPreviousChar Move the cursor to the previous character. + \value MoveToNextWord Move the cursor to the next word. + \value MoveToPreviousWord Move the cursor to the previous word. + \value MoveToNextLine Move the cursor to the next line. + \value MoveToPreviousLine Move the cursor to the previous line. + \value MoveToStartOfLine Move the cursor to the start of the line. + \value MoveToEndOfLine Move the cursor to the end of the line. + \value MoveToStartOfBlock Move the cursor to the start of the block. + \value MoveToEndOfBlock Move the cursor to the end of the block. + \value MoveToStartOfDocument Move the cursor to the start of the document. + \value MoveToEndOfDocument Move the cursor to the end of the document. + \value SelectNextChar Select to the next character. + \value SelectPreviousChar Select to the previous character. + \value SelectNextWord Select to the next word. + \value SelectPreviousWord Select to the previous word. + \value SelectNextLine Select to the next line. + \value SelectPreviousLine Select to the previous line. + \value SelectStartOfLine Select to the start of the line. + \value SelectEndOfLine Select to the end of the line. + \value SelectStartOfBlock Select to the start of the block. + \value SelectEndOfBlock Select to the end of the block. + \value SelectStartOfDocument Select to the start of the document. + \value SelectEndOfDocument Select to the end of the document. + \value DeleteStartOfWord Delete to the start of the word. + \value DeleteEndOfWord Delete to the end of the word. + \value SetTextDirectionDefault Set the text direction to the default direction. + \value SetTextDirectionLeftToRight Set the text direction to left-to-right. + \value SetTextDirectionRightToLeft Set the text direction to right-to-left. + \value ToggleBold Toggle the formatting between bold and normal weight. + \value ToggleItalic Toggle the formatting between italic and normal style. + \value ToggleUnderline Toggle underlining. + \value InspectElement Show the Web Inspector with the currently highlighted HTML element. + \value InsertParagraphSeparator Insert a new paragraph. + \value InsertLineSeparator Insert a new line. + \value SelectAll Selects all content. + \value PasteAndMatchStyle Paste content from the clipboard with current style. (Added in Qt 4.6) + \value RemoveFormat Removes formatting and style. (Added in Qt 4.6) + \value ToggleStrikethrough Toggle the formatting between strikethrough and normal style. (Added in Qt 4.6) + \value ToggleSubscript Toggle the formatting between subscript and baseline. (Added in Qt 4.6) + \value ToggleSuperscript Toggle the formatting between supercript and baseline. (Added in Qt 4.6) + \value InsertUnorderedList Toggles the selection between an ordered list and a normal block. (Added in Qt 4.6) + \value InsertOrderedList Toggles the selection between an ordered list and a normal block. (Added in Qt 4.6) + \value Indent Increases the indentation of the currently selected format block by one increment. (Added in Qt 4.6) + \value Outdent Decreases the indentation of the currently selected format block by one increment. (Added in Qt 4.6) + \value AlignCenter Applies center alignment to content. (Added in Qt 4.6) + \value AlignJustified Applies full justification to content. (Added in Qt 4.6) + \value AlignLeft Applies left justification to content. (Added in Qt 4.6) + \value AlignRight Applies right justification to content. (Added in Qt 4.6) + + \omitvalue WebActionCount + +*/ + +/*! + \enum QWebPage::WebWindowType + + This enum describes the types of window that can be created by the createWindow() function. + + \value WebBrowserWindow The window is a regular web browser window. + \value WebModalDialog The window acts as modal dialog. +*/ + +/*! + \class QWebPage::ViewportAttributes + \since 4.7 + \brief The QWebPage::ViewportAttributes class describes hints that can be applied to a viewport. + + QWebPage::ViewportAttributes provides a description of a viewport, such as viewport geometry, + initial scale factor with limits, plus information about whether a user should be able + to scale the contents in the viewport or not, ie. by zooming. + + ViewportAttributes can be set by a web author using the viewport meta tag extension, documented + at \l{http://developer.apple.com/safari/library/documentation/appleapplications/reference/safariwebcontent/usingtheviewport/usingtheviewport.html}{Safari Reference Library: Using the Viewport Meta Tag}. + + All values might not be set, as such when dealing with the hints, the developer needs to + check whether the values are valid. Negative values denote an invalid qreal value. + + \inmodule QtWebKit +*/ + +/*! + \fn QWebPage::ViewportAttributes::ViewportAttributes() + Constructs an empty QWebPage::ViewportAttributes. +*/ + +/*! + \fn QWebPage::ViewportAttributes::ViewportAttributes(const QWebPage::ViewportAttributes& other) + Constructs a QWebPage::ViewportAttributes which is a copy from \a other . +*/ + +/*! + \fn QWebPage::ViewportAttributes::~ViewportAttributes() + Destroys the QWebPage::ViewportAttributes. +*/ + +/*! + \fn QWebPage::ViewportAttributes& QWebPage::ViewportAttributes::operator=(const QWebPage::ViewportAttributes& other) + Assigns the given QWebPage::ViewportAttributes to this viewport hints and returns a + reference to this. +*/ + +/*! \fn inline bool QWebPage::ViewportAttributes::isValid() const + Returns whether this is a valid ViewportAttributes or not. + + An invalid ViewportAttributes will have an empty QSize, negative values for scale factors and + true for the boolean isUserScalable. +*/ + +/*! \fn inline QSize QWebPage::ViewportAttributes::size() const + Returns the size of the viewport. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::initialScaleFactor() const + Returns the initial scale of the viewport as a multiplier. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::minimumScaleFactor() const + Returns the minimum scale value of the viewport as a multiplier. +*/ + +/*! \fn inline qreal QWebPage::ViewportAttributes::maximumScaleFactor() const + Returns the maximum scale value of the viewport as a multiplier. +*/ + +/*! \fn inline bool QWebPage::ViewportAttributes::isUserScalable() const + Determines whether or not the scale can be modified by the user. +*/ + +/*! + \fn QWebPage::QWebPage(QObject *parent) + Constructs an empty QWebPage with parent \a parent. +*/ + +/*! + \fn QWebPage::~QWebPage() + Destroys the web page. +*/ + +/*! + \fn QWebFrame *QWebPage::mainFrame() const + Returns the main frame of the page. + + The main frame provides access to the hierarchy of sub-frames and is also needed if you + want to explicitly render a web page into a given painter. + + \sa currentFrame() +*/ + +/*! + \fn QWebFrame *QWebPage::currentFrame() const + Returns the frame currently active. + + \sa mainFrame(), frameCreated() +*/ + +/*! + \fn QWebFrame* QWebPage::frameAt(const QPoint& pos) const + \since 4.6 + + Returns the frame at the given point \a pos, or 0 if there is no frame at + that position. + + \sa mainFrame(), currentFrame() +*/ + +/*! + \fn QWebHistory *QWebPage::history() const + Returns a pointer to the view's history of navigated web pages. +*/ + +/*! + \fn void QWebPage::setView(QWidget* view) + Sets the \a view that is associated with the web page. + + \sa view() +*/ + +/*! + \fn QWidget *QWebPage::view() const + Returns the view widget that is associated with the web page. + + \sa setView() +*/ + +/*! + \fn void QWebPage::javaScriptConsoleMessage(const QString& message, int lineNumber, const QString& sourceID) + This function is called whenever a JavaScript program tries to print a \a message to the web browser's console. + + For example in case of evaluation errors the source URL may be provided in \a sourceID as well as the \a lineNumber. + + The default implementation prints nothing. +*/ + +/*! + \fn void QWebPage::javaScriptAlert(QWebFrame *frame, const QString& msg) + This function is called whenever a JavaScript program running inside \a frame calls the alert() function with + the message \a msg. + + The default implementation shows the message, \a msg, with QMessageBox::information. +*/ + +/*! + \fn bool QWebPage::javaScriptConfirm(QWebFrame *frame, const QString& msg) + This function is called whenever a JavaScript program running inside \a frame calls the confirm() function + with the message, \a msg. Returns true if the user confirms the message; otherwise returns false. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Ok and QMessageBox::Cancel buttons. +*/ + +/*! + \fn bool QWebPage::javaScriptPrompt(QWebFrame *frame, const QString& msg, const QString& defaultValue, QString* result) + This function is called whenever a JavaScript program running inside \a frame tries to prompt the user for input. + The program may provide an optional message, \a msg, as well as a default value for the input in \a defaultValue. + + If the prompt was cancelled by the user the implementation should return false; otherwise the + result should be written to \a result and true should be returned. If the prompt was not cancelled by the + user, the implementation should return true and the result string must not be null. + + The default implementation uses QInputDialog::getText(). +*/ + +/*! + \fn bool QWebPage::shouldInterruptJavaScript() + \since 4.6 + This function is called when a JavaScript program is running for a long period of time. + + If the user wanted to stop the JavaScript the implementation should return true; otherwise false. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Yes and QMessageBox::No buttons. +*/ + +/*! + \fn QWebPage *QWebPage::createWindow(WebWindowType type) + This function is called whenever WebKit wants to create a new window of the given \a type, for + example when a JavaScript program requests to open a document in a new window. + + If the new window can be created, the new window's QWebPage is returned; otherwise a null pointer is returned. + + If the view associated with the web page is a QWebView object, then the default implementation forwards + the request to QWebView's createWindow() function; otherwise it returns a null pointer. + + If \a type is WebModalDialog, the application must call setWindowModality(Qt::ApplicationModal) on the new window. + + \note In the cases when the window creation is being triggered by JavaScript, apart from + reimplementing this method application must also set the JavaScriptCanOpenWindows attribute + of QWebSettings to true in order for it to get called. + + \sa acceptNavigationRequest(), QWebView::createWindow() +*/ + +/*! + \fn QObject *QWebPage::createPlugin(const QString &classid, const QUrl &url, const QStringList ¶mNames, const QStringList ¶mValues) + This function is called whenever WebKit encounters a HTML object element with type "application/x-qt-plugin". It is + called regardless of the value of QWebSettings::PluginsEnabled. The \a classid, \a url, \a paramNames and \a paramValues + correspond to the HTML object element attributes and child elements to configure the embeddable object. +*/ + +/*! + \fn QStringList QWebPage::supportedContentTypes() const + Returns the list of all content types supported by QWebPage. +*/ + +/*! + \fn bool QWebPage::supportsContentType(const QString& mimeType) const + Returns true if QWebPage can handle the given \a mimeType; otherwise, returns false. +*/ + +/*! + \fn void QWebPage::triggerAction(WebAction action, bool) + This function can be called to trigger the specified \a action. + It is also called by Qt WebKit if the user triggers the action, for example + through a context menu item. + + If \a action is a checkable action then \a checked specified whether the action + is toggled or not. + + \sa action() +*/ + +/*! + \fn void QWebPage::setViewportSize(const QSize &size) const + \property QWebPage::viewportSize + \brief the size of the viewport + + The size affects for example the visibility of scrollbars + if the document is larger than the viewport. + + By default, for a newly-created Web page, this property contains a size with + zero width and height. + + \sa QWebFrame::render(), preferredContentsSize +*/ + +/*! + \fn QWebPage::ViewportAttributes QWebPage::viewportAttributesForSize(const QSize& availableSize) const + Computes the optimal viewport configuration given the \a availableSize, when + user interface components are disregarded. + + The configuration is also dependent on the device screen size which is obtained + automatically. For testing purposes the size can be overridden by setting two + environment variables QTWEBKIT_DEVICE_WIDTH and QTWEBKIT_DEVICE_HEIGHT, which + both needs to be set. + + The ViewportAttributes includes a pixel density ratio, which will also be exposed to + the web author though the -webkit-pixel-ratio media feature. This is the ratio + between 1 density-independent pixel (DPI) and physical pixels. + + A density-independent pixel is equivalent to one physical pixel on a 160 DPI screen, + so on our platform assumes that as the baseline density. + + The conversion of DIP units to screen pixels is quite simple: + + pixels = DIPs * (density / 160). + + Thus, on a 240 DPI screen, 1 DIPs would equal 1.5 physical pixels. + + An invalid instance will be returned in the case an empty size is passed to the + method. + + \note The density is automatically obtained from the DPI of the screen where the page + is being shown, but as many X11 servers are reporting wrong DPI, it is possible to + override it using QX11Info::setAppDpiY(). +*/ + +/*! + \fn void QWebPage::setPreferredContentsSize(const QSize& size) const + \property QWebPage::preferredContentsSize + \since 4.6 + \brief a custom size used for laying out the page contents. + + By default all pages are laid out using the viewport of the page as the base. + + As pages mostly are designed for desktop usage, they often do not layout properly + on small devices as the contents require a certain view width. For this reason + it is common to use a different layout size and then scale the contents to fit + within the actual view. + + If this property is set to a valid size, this size is used for all layout needs + instead of the size of the viewport. + + Setting an invalid size, makes the page fall back to using the viewport size for layout. + + \sa viewportSize +*/ + +/* + \fn void QWebPage::setActualVisibleContentRect(const QRect& rect) const + This function is to be called after any (animated) scroll/pan has ended, in the case the application handles the + scrolling/panning of the web contents. This is commonly used in combination with tiling where is it common for + the application to pan the actual view, which then resizes itself to the size of the contents. + + \note Calling this function makes WebKit stop trying to calculate the visibleContentRect. To turn that on + again, call this method with an empty rect. + + \sa QGraphicsWebView::resizesToContents, QWebSettings::TiledBackingStoreEnabled +*/ + +/*! + \fn bool QWebPage::acceptNavigationRequest(QWebFrame *frame, const QNetworkRequest &request, QWebPage::NavigationType type) + + This function is called whenever WebKit requests to navigate \a frame to the resource specified by \a request by means of + the specified navigation type \a type. + + If \a frame is a null pointer then navigation to a new window is requested. If the request is + accepted createWindow() will be called. + + The default implementation interprets the page's linkDelegationPolicy and emits linkClicked accordingly or returns true + to let QWebPage handle the navigation itself. + + \sa createWindow() +*/ + +/*! + \fn bool QWebPage::hasSelection() const + \property QWebPage::hasSelection + \brief whether this page contains selected content or not. + + \sa selectionChanged() +*/ + +/*! + \fn QString QWebPage::selectedText() const + \property QWebPage::selectedText + \brief the text currently selected + + By default, this property contains an empty string. + + \sa selectionChanged(), selectedHtml() +*/ + +/*! + \fn QString QWebPage::selectedHtml() const + \since 4.8 + \property QWebPage::selectedHtml + \brief the HTML currently selected + + By default, this property contains an empty string. + + \sa selectionChanged(), selectedText() +*/ + +/*! + \fn QAction *QWebPage::action(WebAction action) const + Returns a QAction for the specified WebAction \a action. + + The action is owned by the QWebPage but you can customize the look by + changing its properties. + + QWebPage also takes care of implementing the action, so that upon + triggering the corresponding action is performed on the page. + + \sa triggerAction() +*/ + +/*! + \fn bool QWebPage::isModified() const + \property QWebPage::modified + \brief whether the page contains unsubmitted form data, or the contents have been changed. + + By default, this property is false. + + \sa contentsChanged(), contentEditable, undoStack() +*/ + +/*! + \fn QUndoStack *QWebPage::undoStack() const + Returns a pointer to the undo stack used for editable content. + + \sa modified +*/ + +/*! + \fn bool QWebPage::focusNextPrevChild(bool next) + Similar to QWidget::focusNextPrevChild() it focuses the next focusable web element + if \a next is true; otherwise the previous element is focused. + + Returns true if it can find a new focusable element, or false if it can't. +*/ + +/*! + \fn void QWebPage::setContentEditable(bool editable) + \property QWebPage::contentEditable + \brief whether the content in this QWebPage is editable or not + \since 4.5 + + If this property is enabled the contents of the page can be edited by the user through a visible + cursor. If disabled (the default) only HTML elements in the web page with their + \c{contenteditable} attribute set are editable. + + \sa modified, contentsChanged(), WebAction +*/ + +/*! + \fn void QWebPage::setForwardUnsupportedContent(bool forward) + \property QWebPage::forwardUnsupportedContent + \brief whether QWebPage should forward unsupported content + + If enabled, the unsupportedContent() signal is emitted with a network reply that + can be used to read the content. + + If disabled, the download of such content is aborted immediately. + + By default unsupported content is not forwarded. +*/ + +/*! + \fn void QWebPage::setLinkDelegationPolicy(LinkDelegationPolicy policy) + \property QWebPage::linkDelegationPolicy + \brief how QWebPage should delegate the handling of links through the + linkClicked() signal + + The default is to delegate no links. +*/ + +/*! + \fn bool QWebPage::swallowContextMenuEvent(QContextMenuEvent *event) + Filters the context menu event, \a event, through handlers for scrollbars and + custom event handlers in the web page. Returns true if the event was handled; + otherwise false. + + A web page may swallow a context menu event through a custom event handler, allowing for context + menus to be implemented in HTML/JavaScript. This is used by \l{http://maps.google.com/}{Google + Maps}, for example. +*/ + +/*! + \fn void QWebPage::updatePositionDependentActions(const QPoint &pos) + Updates the page's actions depending on the position \a pos. For example if \a pos is over an image + element the CopyImageToClipboard action is enabled. +*/ + +/*! + \enum QWebPage::Extension + + This enum describes the types of extensions that the page can support. Before using these extensions, you + should verify that the extension is supported by calling supportsExtension(). + + \value ChooseMultipleFilesExtension Whether the web page supports multiple file selection. + This extension is invoked when the web content requests one or more file names, for example + as a result of the user clicking on a "file upload" button in a HTML form where multiple + file selection is allowed. + + \value ErrorPageExtension Whether the web page can provide an error page when loading fails. + (introduced in Qt 4.6) + + \sa ChooseMultipleFilesExtensionOption, ChooseMultipleFilesExtensionReturn, ErrorPageExtensionOption, ErrorPageExtensionReturn +*/ + +/*! + \enum QWebPage::ErrorDomain + \since 4.6 + + This enum describes the domain of an ErrorPageExtensionOption object (i.e. the layer in which the error occurred). + + \value QtNetwork The error occurred in the QtNetwork layer; the error code is of type QNetworkReply::NetworkError. + \value Http The error occurred in the HTTP layer; the error code is a HTTP status code (see QNetworkRequest::HttpStatusCodeAttribute). + \value WebKit The error is an internal WebKit error. +*/ + +/*! + \class QWebPage::ExtensionOption + \since 4.4 + \brief The ExtensionOption class provides an extended input argument to QWebPage's extension support. + + \inmodule QtWebKit + + \sa QWebPage::extension(), QWebPage::ExtensionReturn +*/ + +/*! + \class QWebPage::ExtensionReturn + \since 4.4 + \brief The ExtensionReturn class provides an output result from a QWebPage's extension. + + \inmodule QtWebKit + + \sa QWebPage::extension(), QWebPage::ExtensionOption +*/ + +/*! + \class QWebPage::ErrorPageExtensionOption + \since 4.6 + \brief The ErrorPageExtensionOption class describes the option + for the error page extension. + + \inmodule QtWebKit + + The ErrorPageExtensionOption class holds the \a url for which an error occurred as well as + the associated \a frame. + + The error itself is reported by an error \a domain, the \a error code as well as \a errorString. + + \sa QWebPage::extension(), QWebPage::ErrorPageExtensionReturn +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::url + \brief the url for which an error occurred +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::frame + \brief the frame associated with the error +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::domain + \brief the domain that reported the error +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::error + \brief the error code. Interpretation of the value depends on the \a domain + \sa QWebPage::ErrorDomain +*/ + +/*! + \variable QWebPage::ErrorPageExtensionOption::errorString + \brief a string that describes the error +*/ + +/*! + \class QWebPage::ErrorPageExtensionReturn + \since 4.6 + \brief The ErrorPageExtensionReturn describes the error page, which will be shown for the + frame for which the error occurred. + + \inmodule QtWebKit + + The ErrorPageExtensionReturn class holds the data needed for creating an error page. Some are + optional such as \a contentType, which defaults to "text/html", as well as the \a encoding, which + is assumed to be UTF-8 if not indicated otherwise. + + The error page is stored in the \a content byte array, as HTML content. In order to convert a + QString to a byte array, the QString::toUtf8() method can be used. + + External objects such as stylesheets or images referenced in the HTML are located relative to + \a baseUrl. + + \sa QWebPage::extension(), QWebPage::ErrorPageExtensionOption, QString::toUtf8() +*/ + +/*! + \fn QWebPage::ErrorPageExtensionReturn::ErrorPageExtensionReturn() + + Constructs a new error page object. +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::contentType + \brief the error page's content type +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::encoding + \brief the error page encoding +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::baseUrl + \brief the base url + + External objects such as stylesheets or images referenced in the HTML are located relative to this url. +*/ + +/*! + \variable QWebPage::ErrorPageExtensionReturn::content + \brief the HTML content of the error page +*/ + +/*! + \class QWebPage::ChooseMultipleFilesExtensionOption + \since 4.5 + \brief The ChooseMultipleFilesExtensionOption class describes the option + for the multiple files selection extension. + + \inmodule QtWebKit + + The ChooseMultipleFilesExtensionOption class holds the frame originating the request + and the suggested filenames which might be provided. + + \sa QWebPage::extension(), QWebPage::chooseFile(), QWebPage::ChooseMultipleFilesExtensionReturn +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionOption::parentFrame + \brief The frame in which the request originated +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionOption::suggestedFileNames + \brief The suggested filenames +*/ + +/*! + \variable QWebPage::ChooseMultipleFilesExtensionReturn::fileNames + \brief The selected filenames +*/ + +/*! + \class QWebPage::ChooseMultipleFilesExtensionReturn + \since 4.5 + \brief The ChooseMultipleFilesExtensionReturn describes the return value + for the multiple files selection extension. + + \inmodule QtWebKit + + The ChooseMultipleFilesExtensionReturn class holds the filenames selected by the user + when the extension is invoked. + + \sa QWebPage::extension(), QWebPage::ChooseMultipleFilesExtensionOption +*/ + +/*! + \fn bool QWebPage::extension(Extension extension, const ExtensionOption *option, ExtensionReturn *output) + This virtual function can be reimplemented in a QWebPage subclass to provide support for extensions. The \a option + argument is provided as input to the extension; the output results can be stored in \a output. + + The behavior of this function is determined by \a extension. The \a option + and \a output values are typically casted to the corresponding types (for + example, ChooseMultipleFilesExtensionOption and + ChooseMultipleFilesExtensionReturn for ChooseMultipleFilesExtension). + + You can call supportsExtension() to check if an extension is supported by the page. + + Returns true if the extension was called successfully; otherwise returns false. + + \sa supportsExtension(), Extension +*/ + +/*! + \fn bool QWebPage::supportsExtension(Extension extension) const + This virtual function returns true if the web page supports \a extension; otherwise false is returned. + + \sa extension() +*/ + +/*! + \fn bool QWebPage::findText(const QString &subString, FindFlags options) + Finds the specified string, \a subString, in the page, using the given \a options. + + If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences + that exist in the page. All subsequent calls will extend the highlight, rather than + replace it, with occurrences of the new string. + + If the HighlightAllOccurrences flag is not passed, the function will select an occurrence + and all subsequent calls will replace the current occurrence with the next one. + + To clear the selection, just pass an empty string. + + Returns true if \a subString was found; otherwise returns false. +*/ + +/*! + \fn QWebSettings *QWebPage::settings() const + Returns a pointer to the page's settings object. + + \sa QWebSettings::globalSettings() +*/ + +/*! + \fn QString QWebPage::chooseFile(QWebFrame *parentFrame, const QString& suggestedFile) + This function is called when the web content requests a file name, for example + as a result of the user clicking on a "file upload" button in a HTML form. + + A suggested filename may be provided in \a suggestedFile. The frame originating the + request is provided as \a parentFrame. + + \sa ChooseMultipleFilesExtension +*/ + +/*! + \fn void QWebPage::setNetworkAccessManager(QNetworkAccessManager *manager) + Sets the QNetworkAccessManager \a manager responsible for serving network requests for this + QWebPage. + + \note It is currently not supported to change the network access manager after the + QWebPage has used it. The results of doing this are undefined. + + \sa networkAccessManager() +*/ + +/*! + \fn QNetworkAccessManager *QWebPage::networkAccessManager() const + Returns the QNetworkAccessManager that is responsible for serving network + requests for this QWebPage. + + \sa setNetworkAccessManager() +*/ + +/*! + \fn void QWebPage::setPluginFactory(QWebPluginFactory *factory) + Sets the QWebPluginFactory \a factory responsible for creating plugins embedded into this + QWebPage. + + Note: The plugin factory is only used if the QWebSettings::PluginsEnabled attribute is enabled. + + \sa pluginFactory() +*/ + +/*! + \fn QWebPluginFactory *QWebPage::pluginFactory() const + Returns the QWebPluginFactory that is responsible for creating plugins embedded into + this QWebPage. If no plugin factory is installed a null pointer is returned. + + \sa setPluginFactory() +*/ + +/*! + \fn QString QWebPage::userAgentForUrl(const QUrl&) const + This function is called when a user agent for HTTP requests is needed. You can reimplement this + function to dynamically return different user agents for different URLs, based on the \a url parameter. + + The default implementation returns the following value: + + "Mozilla/5.0 (%Platform%%Security%%Subplatform%) AppleWebKit/%WebKitVersion% (KHTML, like Gecko) %AppVersion Safari/%WebKitVersion%" + + In this string the following values are replaced at run-time: + \list + \li %Platform% expands to the windowing system followed by "; " if it is not Windows (e.g. "X11; "). + \li %Security% expands to "N; " if SSL is disabled. + \li %Subplatform% expands to the operating system version (e.g. "Windows NT 6.1" or "Intel Mac OS X 10.5"). + \li %WebKitVersion% is the version of WebKit the application was compiled against. + \li %AppVersion% expands to QCoreApplication::applicationName()/QCoreApplication::applicationVersion() if they're set; otherwise defaulting to Qt and the current Qt version. + \endlist +*/ + +/*! + \fn quint64 QWebPage::totalBytes() const + Returns the total number of bytes that were received from the network to render the current page, + including extra content such as embedded images. + + \sa bytesReceived() +*/ + +/*! + \fn quint64 QWebPage::bytesReceived() const + Returns the number of bytes that were received from the network to render the current page. + + \sa totalBytes(), loadProgress() +*/ + +/*! + \fn void QWebPage::setVisibilityState(VisibilityState state) + \property QWebPage::visibilityState + \brief the page's visibility state + + This property should be changed by Qt applications who want to notify the JavaScript application + that the visibility state has changed (e.g. by reimplementing QWidget::setVisible). + The visibility state will be updated with the \a state parameter value only if it's different from the previous set. + Then, HTML DOM Document Object attributes 'hidden' and 'visibilityState' + will be updated to the correct value and a 'visiblitychange' event will be fired. + More information about this HTML5 API can be found at \l{http://www.w3.org/TR/page-visibility/}{W3C Recommendation: Page Visibility}. + + By default, this property is set to VisibilityStateVisible. +*/ + +/*! + \since 4.8 + \fn void QWebPage::viewportChangeRequested() + + Page authors can provide the supplied values by using the viewport meta tag. More information + about this can be found at \l{http://developer.apple.com/safari/library/documentation/appleapplications/reference/safariwebcontent/usingtheviewport/usingtheviewport.html}{Safari Reference Library: Using the Viewport Meta Tag}. + + \sa QWebPage::ViewportAttributes, setPreferredContentsSize(), QGraphicsWebView::setScale() +*/ + +/*! + \fn void QWebPage::loadStarted() + + This signal is emitted when a page starts loading content. + + \sa loadFinished() +*/ + +/*! + \fn void QWebPage::loadProgress(int progress) + + This signal is emitted when the global progress status changes. + The current value is provided by \a progress and scales from 0 to 100, + which is the default range of QProgressBar. + It accumulates changes from all the child frames. + + \sa bytesReceived() +*/ + +/*! + \fn void QWebPage::loadFinished(bool ok) + + This signal is emitted when the page finishes loading content. This signal + is independent of script execution or page rendering. + \a ok will indicate whether the load was successful or any error occurred. + + \sa loadStarted(), ErrorPageExtension +*/ + +/*! + \fn void QWebPage::linkHovered(const QString &link, const QString &title, const QString &textContent) + + This signal is emitted when the mouse hovers over a link. + + \a link contains the link url. + \a title is the link element's title, if it is specified in the markup. + \a textContent provides text within the link element, e.g., text inside an HTML anchor tag. + + When the mouse leaves the link element the signal is emitted with empty parameters. + + \sa linkClicked() +*/ + +/*! + \fn void QWebPage::statusBarMessage(const QString& text) + + This signal is emitted when the statusbar \a text is changed by the page. +*/ + +/*! + \fn void QWebPage::frameCreated(QWebFrame *frame) + + This signal is emitted whenever the page creates a new \a frame. + + \sa currentFrame() +*/ + +/*! + \fn void QWebPage::selectionChanged() + + This signal is emitted whenever the selection changes, either interactively + or programmatically (e.g. by calling triggerAction() with a selection action). + + \sa selectedText() +*/ + +/*! + \fn void QWebPage::contentsChanged() + \since 4.5 + + This signal is emitted whenever the text in form elements changes + as well as other editable content. + + \sa contentEditable, modified, QWebFrame::toHtml(), QWebFrame::toPlainText() +*/ + +/*! + \fn void QWebPage::geometryChangeRequested(const QRect& geom) + + This signal is emitted whenever the document wants to change the position and size of the + page to \a geom. This can happen for example through JavaScript. +*/ + +/*! + \fn void QWebPage::repaintRequested(const QRect& dirtyRect) + + This signal is emitted whenever this QWebPage should be updated. It's useful + when rendering a QWebPage without a QWebView or QGraphicsWebView. + \a dirtyRect contains the area that needs to be updated. To paint the QWebPage get + the mainFrame() and call the render(QPainter*, const QRegion&) method with the + \a dirtyRect as the second parameter. + + \sa mainFrame() + \sa view() +*/ + +/*! + \fn void QWebPage::scrollRequested(int dx, int dy, const QRect& rectToScroll) + + This signal is emitted whenever the content given by \a rectToScroll needs + to be scrolled \a dx and \a dy downwards and no view was set. + + \sa view() +*/ + +/*! + \fn void QWebPage::windowCloseRequested() + + This signal is emitted whenever the page requests the web browser window to be closed, + for example through the JavaScript \c{window.close()} call. +*/ + +/*! + \fn void QWebPage::printRequested(QWebFrame *frame) + + This signal is emitted whenever the page requests the web browser to print \a frame, + for example through the JavaScript \c{window.print()} call. + + \sa QWebFrame::print(), QPrintPreviewDialog +*/ + +/*! + \fn void QWebPage::unsupportedContent(QNetworkReply *reply) + + This signal is emitted when WebKit cannot handle a link the user navigated to or a + web server's response includes a "Content-Disposition" header with the 'attachment' + directive. If "Content-Disposition" is present in \a reply, the web server is indicating + that the client should prompt the user to save the content regardless of content-type. + See RFC 2616 sections 19.5.1 for details about Content-Disposition. + + At signal emission time the meta-data of the QNetworkReply \a reply is available. + + \note The receiving slot is responsible for deleting the QNetworkReply \a reply. + + \note This signal is only emitted if the forwardUnsupportedContent property is set to true. + + \sa downloadRequested() +*/ + +/*! + \fn void QWebPage::downloadRequested(const QNetworkRequest &request) + + This signal is emitted when the user decides to download a link. The url of + the link as well as additional meta-information is contained in \a request. + + \sa unsupportedContent() +*/ + +/*! + \fn void QWebPage::microFocusChanged() + + This signal is emitted when for example the position of the cursor in an editable form + element changes. It is used to inform input methods about the new on-screen position where + the user is able to enter text. This signal is usually connected to the + QWidget::updateMicroFocus() slot. +*/ + +/*! + \fn void QWebPage::linkClicked(const QUrl &url) + + This signal is emitted whenever the user clicks on a link and the page's linkDelegationPolicy + property is set to delegate the link handling for the specified \a url. + + By default no links are delegated and are handled by QWebPage instead. + + \note This signal possibly won't be emitted for clicked links which use + JavaScript to trigger navigation. + + \sa linkHovered() +*/ + +/*! + \fn void QWebPage::toolBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the toolbar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::statusBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the statusbar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::menuBarVisibilityChangeRequested(bool visible) + + This signal is emitted whenever the visibility of the menubar in a web browser + window that hosts QWebPage should be changed to \a visible. +*/ + +/*! + \fn void QWebPage::databaseQuotaExceeded(QWebFrame* frame, QString databaseName); + \since 4.5 + + This signal is emitted whenever the web site shown in \a frame is asking to store data + to the database \a databaseName and the quota allocated to that web site is exceeded. + + \sa QWebDatabase +*/ +/*! + \fn void QWebPage::applicationCacheQuotaExceeded(QWebSecurityOrigin* origin, quint64 defaultOriginQuota, quint64 totalSpaceNeeded); + + This signal is emitted whenever the web site is asking to store data to the application cache + database databaseName and the quota allocated to that web site is exceeded. + +*/ + +/*! + \since 4.5 + \fn void QWebPage::saveFrameStateRequested(QWebFrame* frame, QWebHistoryItem* item); + + This signal is emitted shortly before the history of navigated pages + in \a frame is changed, for example when navigating back in the history. + + The provided QWebHistoryItem, \a item, holds the history entry of the frame before + the change. + + A potential use-case for this signal is to store custom data in + the QWebHistoryItem associated to the frame, using QWebHistoryItem::setUserData(). +*/ + +/*! + \since 4.5 + \fn void QWebPage::restoreFrameStateRequested(QWebFrame* frame); + + This signal is emitted when the load of \a frame is finished and the application may now update its state accordingly. +*/ + +/*! + \class QWebFrame + \since 4.4 + \brief The QWebFrame class represents a frame in a web page. + + \inmodule QtWebKit + + QWebFrame represents a frame inside a web page. Each QWebPage + object contains at least one frame, the main frame, obtained using + QWebPage::mainFrame(). Additional frames will be created for HTML + \c{<frame>} or \c{<iframe>} elements. + + A frame can be loaded using load() or setUrl(). Alternatively, if you have + the HTML content readily available, you can use setHtml() instead. + + The page() function returns a pointer to the web page object. See + \l{QWebView}{Elements of QWebView} for an explanation of how web + frames are related to a web page and web view. + + The QWebFrame class also offers methods to retrieve both the URL currently + loaded by the frame (see url()) as well as the URL originally requested + to be loaded (see requestedUrl()). These methods make possible the retrieval + of the URL before and after a DNS resolution or a redirection occurs during + the load process. The requestedUrl() also matches to the URL added to the + frame history (\l{QWebHistory}) if load is successful. + + The title of an HTML frame can be accessed with the title() property. + Additionally, a frame may also specify an icon, which can be accessed + using the icon() property. If the title or the icon changes, the + corresponding titleChanged() and iconChanged() signals will be emitted. + The zoomFactor() property can be used to change the overall size + of the content displayed in the frame. + + QWebFrame objects are created and controlled by the web page. You + can connect to the web page's \l{QWebPage::}{frameCreated()} signal + to be notified when a new frame is created. + + There are multiple ways to programmatically examine the contents of a frame. + The hitTestContent() function can be used to find elements by coordinate. + For access to the underlying DOM tree, there is documentElement(), + findAllElements() and findFirstElement(). + + A QWebFrame can be printed onto a QPrinter using the print() function. + This function is marked as a slot and can be conveniently connected to + \l{QPrintPreviewDialog}'s \l{QPrintPreviewDialog::}{paintRequested()} + signal. + + \sa QWebPage +*/ + +/*! + \enum QWebFrame::RenderLayer + + This enum describes the layers available for rendering using \l{QWebFrame::}{render()}. + The layers can be OR-ed together from the following list: + + \value ContentsLayer The web content of the frame + \value ScrollBarLayer The scrollbars of the frame + \value PanIconLayer The icon used when panning the frame + + \value AllLayers Includes all the above layers +*/ + +/*! + \fn void QWebFrame::addToJavaScriptWindowObject(const QString &name, QObject *object, ValueOwnership own) + + Make \a object available under \a name from within the frame's JavaScript + context. The \a object will be inserted as a child of the frame's window + object. + + Qt properties will be exposed as JavaScript properties and slots as + JavaScript methods. + The interaction between C++ and JavaScript is explained in the documentation of the \l{The Qt WebKit Bridge}{Qt WebKit bridge}. + + If you want to ensure that your QObjects remain accessible after loading a + new URL, you should add them in a slot connected to the + javaScriptWindowObjectCleared() signal. + + If Javascript is not enabled for this page, then this method does nothing. + + The ownership of \a object is specified using \a own. +*/ + +/*! + \fn QString QWebFrame::toHtml() const + Returns the frame's content as HTML, enclosed in HTML and BODY tags. + + \sa setHtml(), toPlainText() +*/ + +/*! + \fn QString QWebFrame::toPlainText() const + Returns the content of this frame converted to plain text, completely + stripped of all HTML formatting. + + \sa toHtml() +*/ + +/*! + \fn QString QWebFrame::title() const + \property QWebFrame::title + \brief the title of the frame as defined by the HTML <title> element + + \sa titleChanged() +*/ + +/*! + \fn QMultiMap<QString, QString> QWebFrame::metaData() const + \since 4.5 + \brief Returns the meta data in this frame as a QMultiMap + + The meta data consists of the name and content attributes of the + of the \c{<meta>} tags in the HTML document. + + For example: + + \code + <html> + <head> + <meta name="description" content="This document is a tutorial about Qt development"> + <meta name="keywords" content="Qt, WebKit, Programming"> + </head> + ... + </html> + \endcode + + Given the above HTML code the metaData() function will return a map with two entries: + \table + \header \li Key + \li Value + \row \li "description" + \li "This document is a tutorial about Qt development" + \row \li "keywords" + \li "Qt, WebKit, Programming" + \endtable + + This function returns a multi map to support multiple meta tags with the same attribute name. +*/ + +/*! + \fn void QWebFrame::setUrl(const QUrl &url) + \property QWebFrame::url + \brief the url of the frame currently viewed + + Setting this property clears the view and loads the URL. + + By default, this property contains an empty, invalid URL. + + \sa urlChanged() +*/ + +/*! + \fn QUrl QWebFrame::requestedUrl() const + \since 4.6 + \property QWebFrame::requestedUrl + + The URL requested to loaded by the frame currently viewed. The URL may differ from + the one returned by url() if a DNS resolution or a redirection occurs. + + \sa url(), setUrl() +*/ + +/*! + \fn QUrl QWebFrame::baseUrl() const + \since 4.6 + \property QWebFrame::baseUrl + \brief the base URL of the frame, can be used to resolve relative URLs + \since 4.6 +*/ + +/*! + \fn QIcon QWebFrame::icon() const + \property QWebFrame::icon + \brief the icon associated with this frame + + \sa iconChanged(), QWebSettings::iconForUrl() +*/ + +/*! + \fn QString QWebFrame::frameName() const + The name of this frame as defined by the parent frame. +*/ + +/*! + \fn QWebPage *QWebFrame::page() const + The web page that contains this frame. + + \sa pageChanged() +*/ + +/*! + \fn void QWebFrame::load(const QUrl &url) + Loads \a url into this frame. + + \note The view remains the same until enough data has arrived to display the new \a url. + + \sa setUrl(), setHtml(), setContent() +*/ + +/*! + \fn void QWebFrame::load(const QNetworkRequest &req, QNetworkAccessManager::Operation operation, const QByteArray &body) + Loads a network request, \a req, into this frame, using the method specified in \a + operation. + + \a body is optional and is only used for POST operations. + + \note The view remains the same until enough data has arrived to display the new content. + + \sa setUrl() +*/ + +/*! + \fn void QWebFrame::setHtml(const QString &html, const QUrl &baseUrl) + Sets the content of this frame to \a html. \a baseUrl is optional and used to resolve relative + URLs in the document, such as referenced images or stylesheets. + + The \a html is loaded immediately; external objects are loaded asynchronously. + + If a script in the \a html runs longer than the default script timeout (currently 10 seconds), + for example due to being blocked by a modal JavaScript alert dialog, this method will return + as soon as possible after the timeout and any subsequent \a html will be loaded asynchronously. + + When using this method WebKit assumes that external resources such as JavaScript programs or style + sheets are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external + script can be specified through the charset attribute of the HTML script tag. It is also possible + for the encoding to be specified by web server. + + This is a convenience function equivalent to setContent(html, "text/html", baseUrl). + + \note This method will not affect session or global history for the frame. + + \warning This function works only for HTML, for other mime types (i.e. XHTML, SVG) + setContent() should be used instead. + + \sa toHtml(), setContent(), load() +*/ + +/*! + \fn void QWebFrame::setContent(const QByteArray &data, const QString &mimeType, const QUrl &baseUrl) + Sets the content of this frame to the specified content \a data. If the \a mimeType argument + is empty it is currently assumed that the content is HTML but in future versions we may introduce + auto-detection. + + External objects referenced in the content are located relative to \a baseUrl. + + The \a data is loaded immediately; external objects are loaded asynchronously. + + \note This method will not affect session or global history for the frame. + + \sa toHtml(), setHtml() +*/ + +/*! + \fn QWebFrame *QWebFrame::parentFrame() const + Returns the parent frame of this frame, or 0 if the frame is the web pages + main frame. + + This is equivalent to qobject_cast<QWebFrame*>(frame->parent()). + + \sa childFrames() +*/ + +/*! + \fn QList<QWebFrame*> QWebFrame::childFrames() const + Returns a list of all frames that are direct children of this frame. + + \sa parentFrame() +*/ + +/*! + \fn Qt::ScrollBarPolicy QWebFrame::scrollBarPolicy(Qt::Orientation orientation) const + Returns the scrollbar policy for the scrollbar defined by \a orientation. +*/ + +/*! + \fn void QWebFrame::setScrollBarPolicy(Qt::Orientation orientation, Qt::ScrollBarPolicy policy) + Sets the scrollbar policy for the scrollbar defined by \a orientation to \a policy. +*/ + +/*! + \fn void QWebFrame::setScrollBarValue(Qt::Orientation orientation, int value) + Sets the current \a value for the scrollbar with orientation \a orientation. + + The scrollbar forces the \a value to be within the legal range: minimum <= value <= maximum. + + Changing the value also updates the thumb position. + + \sa scrollBarMinimum(), scrollBarMaximum() +*/ + +/*! + \fn int QWebFrame::scrollBarValue(Qt::Orientation orientation) const + Returns the current value for the scrollbar with orientation \a orientation, or 0 + if no scrollbar is found for \a orientation. + + \sa scrollBarMinimum(), scrollBarMaximum() +*/ + +/*! + \fn int QWebFrame::scrollBarMaximum(Qt::Orientation orientation) const + Returns the maximum value for the scrollbar with orientation \a orientation, or 0 + if no scrollbar is found for \a orientation. + + \sa scrollBarMinimum() +*/ + +/*! + \fn int QWebFrame::scrollBarMinimum(Qt::Orientation orientation) const + Returns the minimum value for the scrollbar with orientation \a orientation. + + The minimum value is always 0. + + \sa scrollBarMaximum() +*/ + +/*! + \fn QRect QWebFrame::scrollBarGeometry(Qt::Orientation orientation) const + \since 4.6 + Returns the geometry for the scrollbar with orientation \a orientation. + + If the scrollbar does not exist an empty rect is returned. +*/ + +/*! + \fn void QWebFrame::scroll(int dx, int dy) + \since 4.5 + Scrolls the frame \a dx pixels to the right and \a dy pixels downward. Both + \a dx and \a dy may be negative. + + \sa QWebFrame::scrollPosition +*/ + +/*! + \fn QPoint QWebFrame::scrollPosition() const + \property QWebFrame::scrollPosition + \since 4.5 + \brief the position the frame is currently scrolled to. +*/ + +/*! + \fn void QWebFrame::scrollToAnchor(const QString& anchor) + \since 4.7 + Scrolls the frame to the given \a anchor name. +*/ + +/*! + \fn void QWebFrame::render(QPainter* painter, RenderLayers layer, const QRegion& clip) + \since 4.6 + Render the \a layer of the frame using \a painter clipping to \a clip. + + \sa print() +*/ + +/*! + \fn void QWebFrame::render(QPainter* painter, const QRegion& clip) + Render the frame into \a painter clipping to \a clip. +*/ + +/*! + \property QWebFrame::textSizeMultiplier + \brief the scaling factor for all text in the frame + \obsolete + + Use setZoomFactor instead, in combination with the ZoomTextOnly attribute in + QWebSettings. + + \note Setting this property also enables the ZoomTextOnly attribute in + QWebSettings. +*/ + +/*! + \fn void QWebFrame::setTextSizeMultiplier(qreal factor) + Sets the value of the multiplier used to scale the text in a Web frame to + the \a factor specified. +*/ + +/*! + \fn qreal QWebFrame::textSizeMultiplier() const + Returns the value of the multiplier used to scale the text in a Web frame. +*/ + +/*! + \fn void QWebFrame::setZoomFactor(qreal factor) + \property QWebFrame::zoomFactor + \since 4.5 + \brief the zoom factor for the frame +*/ + +/*! + \fn bool QWebFrame::hasFocus() const + \property QWebFrame::focus + \since 4.6 + + Returns true if this frame has keyboard input focus; otherwise, returns false. +*/ + +/*! + \fn void QWebFrame::setFocus() + \since 4.6 + + Gives keyboard input focus to this frame. +*/ + +/*! + \fn QPoint QWebFrame::pos() const + Returns the position of the frame relative to it's parent frame. +*/ + +/*! + \fn QRect QWebFrame::geometry() const + Return the geometry of the frame relative to it's parent frame. +*/ + +/*! + \fn QSize QWebFrame::contentsSize() const + \property QWebFrame::contentsSize + \brief the size of the contents in this frame + + \sa contentsSizeChanged() +*/ + +/*! + \fn QWebElement QWebFrame::documentElement() const + \since 4.6 + + Returns the document element of this frame. + + The document element provides access to the entire structured + content of the frame. +*/ + +/*! + \fn QWebElementCollection QWebFrame::findAllElements(const QString &selectorQuery) const + \since 4.6 + Returns a new list of elements matching the given CSS selector \a selectorQuery. + If there are no matching elements, an empty list is returned. + + \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is + used for the query. + + \sa QWebElement::findAll() +*/ + +/*! + \fn QWebElement QWebFrame::findFirstElement(const QString &selectorQuery) const + \since 4.6 + Returns the first element in the frame's document that matches the + given CSS selector \a selectorQuery. If there is no matching element, a + null element is returned. + + \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{Standard CSS2 selector} syntax is + used for the query. + + \sa QWebElement::findFirst() +*/ + +/*! + \fn QWebHitTestResult QWebFrame::hitTestContent(const QPoint &pos) const + Performs a hit test on the frame contents at the given position \a pos and returns the hit test result. +*/ + +/*! + \fn void QWebFrame::print(QPrinter *printer) const + Prints the frame to the given \a printer. + + \sa render() +*/ + +/*! + \fn QVariant QWebFrame::evaluateJavaScript(const QString& scriptSource) + Evaluates the JavaScript defined by \a scriptSource using this frame as context + and returns the result of the last executed statement. + + \sa addToJavaScriptWindowObject(), javaScriptWindowObjectCleared() +*/ + +/*! + \fn QWebSecurityOrigin QWebFrame::securityOrigin() const + \since 4.5 + + Returns the frame's security origin. +*/ + +/*! + \fn void QWebFrame::javaScriptWindowObjectCleared() + + This signal is emitted whenever the global window object of the JavaScript + environment is cleared, e.g., before starting a new load. + + If you intend to add QObjects to a QWebFrame using + addToJavaScriptWindowObject(), you should add them in a slot connected + to this signal. This ensures that your objects remain accessible when + loading new URLs. +*/ + +/*! + \fn void QWebFrame::provisionalLoad() + \internal +*/ + +/*! + \fn void QWebFrame::titleChanged(const QString &title) + + This signal is emitted whenever the title of the frame changes. + The \a title string specifies the new title. + + \sa title() +*/ + +/*! + \fn void QWebFrame::urlChanged(const QUrl &url) + + This signal is emitted with the URL of the frame when the frame's title is + received. The new URL is specified by \a url. + + \sa url() +*/ + +/*! + \fn void QWebFrame::initialLayoutCompleted() + + This signal is emitted when the frame is laid out the first time. + This is the first time you will see contents displayed on the frame. + + \note A frame can be laid out multiple times. +*/ + +/*! + \fn void QWebFrame::iconChanged() + + This signal is emitted when the icon ("favicon") associated with the frame + has been loaded. + + \sa icon() +*/ + +/*! + \fn void QWebFrame::contentsSizeChanged(const QSize &size) + \since 4.6 + + This signal is emitted when the frame's contents size changes + to \a size. + + \sa contentsSize() +*/ + +/*! + \fn void QWebFrame::loadStarted() + \since 4.6 + + This signal is emitted when a new load of this frame is started. + + \sa loadFinished() +*/ + +/*! + \fn void QWebFrame::loadFinished(bool ok) + \since 4.6 + + This signal is emitted when a load of this frame is finished. + \a ok will indicate whether the load was successful or any error occurred. + + \sa loadStarted() +*/ + +/*! + \fn void QWebFrame::pageChanged() + \since 4.7 + + This signal is emitted when this frame has been moved to a different QWebPage. + + \sa page() +*/ + +/*! + \class QWebHitTestResult + \since 4.4 + \brief The QWebHitTestResult class provides information about the web + page content after a hit test. + + \inmodule QtWebKit + + QWebHitTestResult is returned by QWebFrame::hitTestContent() to provide + information about the content of the web page at the specified position. +*/ + +/*! + \fn QWebHitTestResult::QWebHitTestResult() + Constructs a null hit test result. +*/ + +/*! + \fn QWebHitTestResult::QWebHitTestResult(const QWebHitTestResult &other) + Constructs a hit test result from \a other. +*/ + +/*! + \fn QWebHitTestResult &QWebHitTestResult::operator=(const QWebHitTestResult &other) + Assigns the \a other hit test result to this. +*/ + +/*! + \fn QWebHitTestResult::~QWebHitTestResult() + Destructor. +*/ + +/*! + \fn bool QWebHitTestResult::isNull() const + Returns true if the hit test result is null; otherwise returns false. +*/ + +/*! + \fn QPoint QWebHitTestResult::pos() const + Returns the position where the hit test occurred in the coordinates of frame containing the element hit. + + \sa frame() +*/ + +/*! + \fn QRect QWebHitTestResult::boundingRect() const + \since 4.5 + Returns the bounding rect of the element. +*/ + +/*! + \fn QWebElement QWebHitTestResult::enclosingBlockElement() const + \since 4.6 + Returns the block element that encloses the element hit. + + A block element is an element that is rendered using the + CSS "block" style. This includes for example text + paragraphs. +*/ + +/*! + \fn QString QWebHitTestResult::title() const + Returns the title of the nearest enclosing HTML element. +*/ + +/*! + \fn QString QWebHitTestResult::linkText() const + Returns the text of the link. +*/ + +/*! + \fn QUrl QWebHitTestResult::linkUrl() const + Returns the url to which the link points to. +*/ + +/*! + \fn QUrl QWebHitTestResult::linkTitle() const + Returns the title of the link. +*/ + +/*! + \fn QWebElement QWebHitTestResult::linkElement() const + \since 4.6 + Returns the element that represents the link. + + \sa linkTargetFrame() +*/ + +/*! + \fn QWebFrame *QWebHitTestResult::linkTargetFrame() const + Returns the frame that will load the link if it is activated. + + \sa linkElement() +*/ + +/*! + \fn QString QWebHitTestResult::alternateText() const + Returns the alternate text of the element. This corresponds to the HTML alt attribute. +*/ + +/*! + \fn QUrl QWebHitTestResult::imageUrl() const + Returns the url of the image. +*/ + +/*! + \fn QPixmap QWebHitTestResult::pixmap() const + Returns a QPixmap containing the image. A null pixmap is returned if the + element being tested is not an image. +*/ + +/*! + \fn bool QWebHitTestResult::isContentEditable() const + Returns true if the content is editable by the user; otherwise returns false. +*/ + +/*! + \fn bool QWebHitTestResult::isContentSelected() const + Returns true if the content tested is part of the selection; otherwise returns false. +*/ + +/*! + \fn QWebElement QWebHitTestResult::element() const + \since 4.6 + Returns the underlying DOM element as QWebElement. +*/ + +/*! + \fn QWebFrame *QWebHitTestResult::frame() const + Returns the frame of the element hit. +*/ |