/*
    Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
    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 QWebEnginePage
    \since 4.4
    \brief The QWebEnginePage class provides an object to view and edit web documents.

    \inmodule QtWebEngine

    QWebEnginePage holds a main frame responsible for web content, settings, the history
    of navigated links and actions. This class can be used to provide functionality like
    QWebEngineView in a widget-less environment.

    QWebEnginePage's API is very similar to QWebEngineView, as you are still provided with
    common functions like action() (known as
    \l{QWebEngineView::pageAction()}{pageAction}() in QWebEngineView), triggerAction(),
    findText() and settings().


    A page can be loaded using load() or setUrl(). Alternatively, if you have
    the HTML content readily available, you can use setHtml() instead.

    The QWebEnginePage class also offers methods to retrieve both the URL currently
    loaded by its main 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
    page history (\l{QWebEngineHistory}) if load is successful.

    The title of an HTML page can be accessed with the title() property.
    Additionally, a page 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 page.

    There are multiple ways to programmatically examine the contents of a page.
    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 QWebEnginePage 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.

    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 QWebEnginePage in a Widget-less Environment

    Before you begin painting a QWebEnginePage object, you need to set the size of
    the viewport by calling setViewportSize(). Then, you invoke the main
    frame's render function (QWebEnginePage::render()). An example of this
    is shown in the code snippet below.

    Suppose we have a \c Thumbnail class as follows:

    \snippet snippets/webpage/main.cpp 0

    The \c Thumbnail's constructor takes in a \a url. We connect our QWebEnginePage
    object's \l{QWebEnginePage::}{loadFinished()} signal to our private slot,
    \c render().

    \snippet snippets/webpage/main.cpp 1

    The \c render() function shows how we can paint a thumbnail using a
    QWebEnginePage object.

    \snippet snippets/webpage/main.cpp 2

    We begin by setting the \l{QWebEnginePage::viewportSize()}{viewportSize} and
    then we instantiate a QImage object, \c image, with the same size as our
    \l{QWebEnginePage::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.
*/

/*!
    \fn QMenu *QWebEnginePage::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.
 */

/*!
    \fn QVariant QWebEnginePage::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 QWebEnginePage::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.
*/

/*!
    \enum QWebEnginePage::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().

    \value NoWebAction No action is triggered.
    \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 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 SelectAll Selects all content.
    \value PasteAndMatchStyle Paste content from the clipboard with current style. (Added in Qt 4.6)

    \omitvalue WebActionCount

*/

/*!
    \enum QWebEnginePage::WebWindowType

    This enum describes the types of window that can be created by the createWindow() function.

    \value WebBrowserWindow The page should be opened in a complete web browser window.
    \value WebBrowserTab The page should be opened as a web browser tab.
    \value WebDialog The page should be opened in a window without decoration.
*/

/*!
    \fn QWebEnginePage::QWebEnginePage(QObject *parent)
    Constructs an empty QWebEnginePage with parent \a parent.
*/

/*!
    \fn QWebEnginePage::~QWebEnginePage()
    Destroys the web page.
*/

/*!
    \fn QWebEngineHistory *QWebEnginePage::history() const
    Returns a pointer to the view's history of navigated web pages.
*/

/*!
    \fn void QWebEnginePage::setView(QWidget* view)
    Sets the \a view that is associated with the web page.

    \sa view()
*/

/*!
    \fn QWidget *QWebEnginePage::view() const
    Returns the view widget that is associated with the web page.

    \sa setView()
*/

/*!
    \fn void QWebEnginePage::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 QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString& msg)
    This function is called whenever a JavaScript program running in a frame affiliated with \a securityOrigin calls the alert() function with
    the message \a msg.

    The default implementation shows the message, \a msg, with QMessageBox::information.
*/

/*!
    \fn bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString& msg)
    This function is called whenever a JavaScript program running in a frame affiliated with \a securityOrigin 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 QWebEnginePage::javaScriptPrompt(const QUrl &securityOrigin, const QString& msg, const QString& defaultValue, QString* result)
    This function is called whenever a JavaScript program running in a frame affiliated with \a securityOrigin 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 QWebEnginePage *QWebEnginePage::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 QWebEnginePage is returned; otherwise a null pointer is returned.

    If the view associated with the web page is a QWebEngineView object, then the default implementation forwards
    the request to QWebEngineView'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 QWebEngineSettings to true in order for it to get called.

    \sa QWebEngineView::createWindow()
*/

/*!
    \fn void QWebEnginePage::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()
*/

/*!
    \property QWebEnginePage::hasSelection
    \brief whether this page contains selected content or not.

    \sa selectionChanged()
*/

/*!
    \property QWebEnginePage::selectedText
    \brief the text currently selected

    By default, this property contains an empty string.

    \sa selectionChanged()
*/

/*!
    \fn QAction *QWebEnginePage::action(WebAction action) const
    Returns a QAction for the specified WebAction \a action.

    The action is owned by the QWebEnginePage but you can customize the look by
    changing its properties.

    QWebEnginePage also takes care of implementing the action, so that upon
    triggering the corresponding action is performed on the page.

    \sa triggerAction()
*/

/*!
    \fn bool QWebEnginePage::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 QString QWebEnginePage::chooseFile(QWebEngineFrame *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 QWebEnginePage::loadStarted()

    This signal is emitted when a page starts loading content.

    \sa loadFinished()
*/

/*!
    \fn void QWebEnginePage::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 QWebEnginePage::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 QWebEnginePage::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 QWebEnginePage::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 QWebEnginePage::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 QString QWebEnginePage::toHtml() const
    Returns the frame's content as HTML, enclosed in HTML and BODY tags.

    \sa setHtml(), toPlainText()
*/

/*!
    \fn QString QWebEnginePage::toPlainText() const
    Returns the content of this frame converted to plain text, completely
    stripped of all HTML formatting.

    \sa toHtml()
*/

/*!
    \property QWebEnginePage::title
    \brief the title of the frame as defined by the HTML <title> element

    \sa titleChanged()
*/

/*!
    \property QWebEnginePage::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()
*/

/*!
    \since 4.6
    \property QWebEnginePage::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 void QWebEnginePage::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 QWebEnginePage::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 QWebEnginePage::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()
*/

/*!
    \property QWebEnginePage::zoomFactor
    \since 4.5
    \brief the zoom factor for the frame
*/

/*!
    \fn QVariant QWebEnginePage::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 void QWebEnginePage::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 QWebEnginePage::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()
*/