/*
 * Copyright 2014-2016 Canonical Ltd.
 *
 * This file is part of webbrowser-app.
 *
 * webbrowser-app is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 3.
 *
 * webbrowser-app 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*!
    \qmltype WebView
    \inqmlmodule Morph.Web 0.1
    \ingroup morph
    \brief A webview that can be used to render web content in an application.

    Here is a very simple example of how to use a WebView to render a web page:
    \qml
        import QtQuick 2.4
        import Morph.Web 0.1

        WebView {
            url: "http://ubuntu.com"
        }
    \endqml

    The \c WebView component defaults to using a \l {SharedWebContext}
    {shared \c WebContext} that is shared across all \c WebView instances
    in a given application.

    \sa SharedWebContext
 */

/*!
    \qmlproperty url WebView::url

    The URL of the current page.
 */

/*!
    \qmlproperty string WebView::title

    The title of the current page.
 */

/*!
    \qmlproperty url WebView::icon

    The URL of the favicon of the current page.
 */

/*!
    \qmlproperty bool WebView::canGoBack
    \deprecated

    Whether the navigation history has a previous entry to navigate back.
    This is now deprecated.
    Use WebView::navigationHistory::canGoBack instead.

    \sa goBack, canGoForward
 */

/*!
    \qmlproperty bool WebView::canGoForward
    \deprecated

    Whether the navigation history has a next entry to navigate forward.
    This is now deprecated.
    Use WebView::navigationHistory::canGoForward instead.

    \sa goForward, canGoBack
 */

/*!
    \qmlproperty bool WebView::incognito

    Whether the WebView is being used in private browsing mode,
    where no data is persisted across sessions.
 */

/*!
    \qmlproperty bool WebView::loading

    Whether the current page is loading.

    \sa loadProgress, stop, reload
 */

/*!
    \qmlproperty bool WebView::fullscreen

    Whether the current page requested fullscreen display.
 */

/*!
    \qmlproperty int WebView::loadProgress

    The load progress of the current page
    (as a integer value between 0 and 100).

    \sa loading
 */

/*!
    \qmlproperty component WebView::alertDialog

    The QML component that will be instantiated to display
    a JavaScript alert dialog.

    \sa confirmDialog, promptDialog, beforeUnloadDialog
 */

/*!
    \qmlproperty component WebView::confirmDialog

    The QML component that will be instantiated to display
    a JavaScript confirmation dialog.

    \sa alertDialog, promptDialog, beforeUnloadDialog
 */

/*!
    \qmlproperty component WebView::promptDialog

    The QML component that will be instantiated to display
    a JavaScript prompt dialog.

    \sa alertDialog, confirmDialog, beforeUnloadDialog
 */

/*!
    \qmlproperty component WebView::beforeUnloadDialog

    The QML component that will be instantiated to display
    a JavaScript confirmation when the user initiates a navigation away from
    the current page, if the page has defined an \c onBeforeUnload handler.

    \sa alertDialog, confirmDialog, promptDialog
 */

/*!
    \qmlproperty component WebView::filePicker

    The QML component that will be instantiated to let the user select files
    when the user clicks an \c {<input type="file">} element
    on the current page.
 */

/*!
    \qmlproperty WebContext WebView::context

    The web context associated to this WebView.
    By default a \l {SharedWebContext} {shared context} is used which should
    fit most use cases, do not override unless you really need a finer control
    over the context.
 */

/*!
    \qmlproperty list WebView::navigationHistory

    The navigation history (back/forward entries) stored as a list model
    with a \c currentIndex property. Each entry exposes the URL and title of
    the corresponding page, as well as a timestamp of when it was visited.
 */

/*!
    \qmlproperty ActionList WebView::contextualActions

    A list of actions that the user will be presented with when invoking a
    context menu (by way of a right click on desktop, or a long press on a
    touch-enabled device, on an image or a hyperlink).
    By default the list is empty, and no menu is shown.
    User-defined actions can access the \l {contextModel} {context model}.

    Example of user-defined actions:
    \code
        import Lomiri.Components 1.3
        import Morph.Web 0.1

        WebView {
            contextualActions: ActionList {
                Action {
                    text: i18n.tr("Open link in browser")
                    enabled: contextModel && contextModel.linkUrl.toString()
                    onTriggered: Qt.openUrlExternally(contextModel.linkUrl)
                }
            }
        }
    \endcode

    \sa contextModel
 */

/*!
    \deprecated
    \qmlproperty QtObject WebView::contextualData

    This property is deprecated, use the \l {contextModel} property instead.

    An object that holds the contextual data associated with the current context
    menu. User-defined \l {contextualActions} {contextual actions} can use this
    data to process it when triggered.

    It has the following properties:
    \list
        \li href (url): the full URI of the hyperlink, if any
        \li title (string): the title of the hyperlink, if any
        \li img (url): the full URI of the image
    \endlist

    Note that in the case of an image enclosed inside a hyperlink, both \c href
    and \c img will be available, allowing a user-defined contextual action to
    operate on both elements.

    \sa contextualActions, contextModel
 */

/*!
    \qmlproperty QtObject WebView::contextModel

    An object that holds the contextual data associated with the current context
    menu, as well as methods to interact with this data. User-defined
    \l {contextualActions} {contextual actions} can use this data to process it
    when triggered.

    It has the following properties:
    \list
        \li linkUrl (url): the full URI of the hyperlink, if any
        \li srcUrl (url): the full URI of the image/media, if any
        \li mediaType (int): the type of media (one of Oxide.WebView.MediaTypeNone,
            Oxide.WebView.MediaTypeImage, Oxide.WebView.MediaTypeCanvas,
            Oxide.WebView.MediaTypeAudio, Oxide.WebView.MediaTypeVideo)
        \li isEditable (bool): whether the current element is editable
        \li editFlags (int): for editable elements, an OR-combined list of flags that
            define the current editing capabilities (Oxide.WebView.UndoCapability,
            Oxide.WebView.RedoCapability, Oxide.WebView.CutCapability,
            Oxide.WebView.CopyCapability, Oxide.WebView.PasteCapability,
            Oxide.WebView.EraseCapability, Oxide.WebView.SelectAllCapability)
    \endlist

    It has the following methods:
    \list
        \li saveLink(): initiates a download request for the resource pointed
            to by the hyperlink, if any
        \li saveMedia(): initiates a download request for the media
            (image, canvas, audio, video), if any
    \endlist

    When there is no active context menu, \c contextModel is null.

    \sa contextualActions
 */

/*!
    \qmlmethod void WebView::goBack()
    \deprecated

    Go back one entry in the navigation history.
    This is now deprecated.
    Use WebView::navigationHistory::goBack instead.

    \sa canGoBack, goForward
 */

/*!
    \qmlmethod void WebView::goForward()
    \deprecated

    Go forward one entry in the navigation history.
    This is now deprecated.
    Use WebView::navigationHistory::goForward instead.

    \sa canGoForward, goBack
 */

/*!
    \qmlmethod void WebView::stop()

    Stop loading the current page.
    Does nothing if there is no page currently loading.

    \sa reload, loading
 */

/*!
    \qmlmethod void WebView::reload()

    Reload the current page.

    \sa stop
 */

/*!
    \qmlmethod void WebView::loadHtml(string html, url baseUrl)

    Load HTML content from memory instead of loading it from a URL.
    The \c baseUrl argument is used to resolve relative URLs in the provided
    content.
 */
