class:: WebView
summary:: Web page display and browser
categories:: GUI>Views

DESCRIPTION::

WebView displays web pages and provides all the standard browsing functionality.

Since the Qt WebEngine dependency is hefty and difficult to install on some systems, it is possible for sclang to have been built without WebView support (using the CMake flag code:: -DSC_USE_QTWEBENGINE=OFF :: at compile). If so, attempting to invoke this class will throw an error.

CLASSMETHODS::

PRIVATE:: key

METHOD:: clearCache

  Clears the cache for all browser instances.

METHOD:: setUrlHandler

    Set or clear a function to handle a specific URL prefix (e.g. mail://)

    Argument:: prefix
        URL prefix. For mail:///, use the string "mail" (do not append "://")

    Argument:: function
        Function to execute when any WebView loads a URL with this prefix. First argument is the URL.


INSTANCEMETHODS::

SUBSECTION:: Navigation

METHOD:: url
    Gets the current URL, or navigates to a new one. This is equivalent to entering a URL in a browser's URL box.

METHOD:: navigate
    Navigate to a url. This is equivalent to clicking a link on a page - after a navigate call, back will return you to the previous page.

METHOD:: back
    Navigates to the previous page in history.

METHOD:: forward
    Navigates to the next page in history.

METHOD:: findText
    Finds and selects the next instance of given text on the current page. When the given text changes, the search starts anew.

    Argument::
        The text to find; a String.
    Argument::
        Whether to search in reverse direction; a Boolean.
    Argument::
        A function, called when the operation is finished. If the text was found this function is passed code::true::, otherwise code::false::.

METHOD:: triggerPageAction
    Trigger an action on the current page. Possible actions include: reload, select all, copy, undo, redo (see link::Classes/QWebPageAction::)

    Argument::
        A QWebPageAction.
    Argument::
        A Boolean to enable or disable the action (applies to only some actions).

SUBSECTION:: Data

METHOD:: setHtml
    Set the HTML displayed in the view.

    Argument::
        A String.
    Argument::
        A url. The browser will interpret this to be the current page location.

METHOD:: setContent
    Set the raw content of a web view. This can be used to display binary data such as image / movie files.

    Argument::
        An Int8Array containing data.
    Argument::
        A mime type, of the form e.g. "image/jpeg"
    Argument::
        A url. The browser will interpret this to be the current page location.

METHOD:: setAttribute
    Set a QWebAttribute for the view. Attributes can affect behavior such as caching, auto-loading images, file url access, etc.

    Argument::
        A QWebAttribute.
    Argument::
        A Boolean.

METHOD:: testAttribute
    Check the enablement state of a QWebAttribute.

    Argument::
        A QWebAttribute.
    Returns::
        A Boolean.

METHOD:: resetAttribute
    Reset the enablement state of a QWebAttribute.

    Argument::
        A QWebAttribute.

METHOD:: toPlainText
    Convert the page to plain text.
    Argument::
        A callback function. Called with the resulting plain text string when the operation is finished.

METHOD:: toHtml
    Fetch the HTML of the current page.
    Argument::
        A callback function. Called with the resulting HTML string when the operation is finished.

METHOD:: title
    The title of the current page.
    Returns:: A String.

METHOD:: requestedUrl
    The requested url for the current page.
    Returns:: A String.

METHOD:: selectedText
    The currently selected text.
    Returns:: A String.

SUBSECTION:: Behavior and appearance

METHOD:: audioMuted
    Get or set audio mute setting for the view;
    Argument::
        A Boolean.

METHOD:: contentsSize
    Get the size of the current content.
    Returns::
        A Point

METHOD:: scrollPosition
    Get or sets the scroll position of the current page.
    Returns::
        A Point

METHOD:: hasSelection
    Returns whether the page has a text selection.
    Returns::
        A Boolean.

METHOD:: enterInterpretsSelection
    Whether pressing Ctrl+Return or Ctrl+Enter while some text is selected should evaluate the selection as SuperCollider code.
    Argument::
        A Boolean.

METHOD:: setFontFamily
    Sets a specific font family to be used in place of a CSS-specified generic font family.
    Argument::
        The CSS generic font family to assign a font to; one of link::Classes/QWebFontFamily::
    Argument::
        A font family name to be assigned to the generic family; a String.

METHOD:: zoom
    Gets or sets the zoom level on a page.
    Argument::
        A Number, where 1.0 is the default zoom.

METHOD:: editable
    Get or set whether the entire web page is editable.
    Argument::
        A Boolean.

METHOD:: pageBackgroundColor
    Get or set the default background color of web pages.
    Argument::
        A Color.

SUBSECTION:: Actions

METHOD:: onAudioMutedChanged
    Sets the object to be evaluated when the mute setting of the view has changed.

METHOD:: onRecentlyAudibleChanged
    Sets the object to be evaluated when the page has started or stopped playing audio.

METHOD:: onContentsSizeChanged
    Sets the object to be evaluated when the contents size of the view has changed

METHOD:: onScrollPositionChanged
    Sets the object to be evaluated when the scroll position on a page has changed.

METHOD:: onSelectionChanged
    Sets the object to be evaluated when the text selection on a page has changed.

METHOD:: onJavaScriptMsg
    Sets the object to be evaluated when a javascript console message is posted.

METHOD:: onLinkHovered
    Sets the object to be evaluated when a the mouse rolls over a link.

METHOD:: onTitleChanged
    Sets the object to be evaluated when the title of the displayed page changes.

METHOD:: onUrlChanged
    Sets the object to be evaluated when the url of the displayed page changes.

METHOD:: onLoadProgress
    Sets the object to be evaluated with load progress updates.

METHOD:: onLoadStarted
    Sets the object to be evaluated when a page load begins.

METHOD:: onLoadFinished
    Sets the object to be evaluated when a page has loaded successfully, passing the view as the argument.

METHOD:: onLoadFailed
    Sets the object to be evaluated when a page has failed to load, passing the view as the argument.

METHOD:: overrideNavigation
    When true, page navigation requests will not be handled. Use in combination with onLinkActivated to provide custom navigation behavior.

METHOD:: onLinkActivated
    Sets the object to be evaluated when the user triggers a link. Arguments are: a URL, a QWebPageNavigationType, a bool (page is opening in current view).

    When this is set to other than nil, WebView will stop handling clicked links altogether. Setting this to nil will restore WebView link handling again.
    Note: for specialty behavior when clicking on links, it is much better to use setUrlHandler in most cases.

METHOD:: onReloadTriggered
    Sets the object to be evaluated whenever a page reload is requested, passing the view and the URL to be reloaded (as String) as the arguments.

SUBSECTION:: JavaScript

METHOD:: runJavaScript
    Evaluates the given JavaScript code in the context of the current page.
    Argument::
        A String.
    Argument::
        A function to be called when execution is complete, with the result as first argument.
        NOTE:: javascript code can correctly return Numbers, Strings and Arrays, but it can't currently pass javascript Objects to sclang. It is possible however to use JSON serialization to acheive this: ::
        CODE::
// passing a nested object from javascript to sclang:
WebView().runJavaScript("JSON.stringify({a: [1,2,3], b: {ba: 1, bb: 'yeah'}})"){ |res| res.parseJSON.postln }
::

EXAMPLES::
CODE::
// A simple web browser
(
var browser, webview, reloadStop, prev, next, urlBox, go;

webview = WebView()
	.minSize_(300@200);
reloadStop = Button()
	.states_([["※"], ["◙"]])
	.fixedSize_(36@28);
prev = Button()
	.states_([["⇦"]])
	.fixedSize_(36@28);
next = Button()
	.states_([["⇨"]])
	.fixedSize_(36@28);
urlBox = TextField()
	.minWidth_(100);
go = Button()
	.states_([["⌘"]])
	.fixedSize_(36@28);

reloadStop.action = {
	|v|
	if (v.value == 1) {
		webview.reload(true);
	} {
		webview.stop;
	}
};

prev.action = { webview.back };
next.action = { webview.forward };
urlBox.action = { webview.url = urlBox.string };
go.action = { webview.url = urlBox.string };

webview.onUrlChanged = {
	|view, url|
	urlBox.string = url;
};

webview.onLoadStarted = {
	reloadStop.value = 1;
	urlBox.background = Color.grey(0.4);
};

webview.onLoadFinished = {
	reloadStop.value = 0;
	urlBox.background = Color.grey(0.2);
};

webview.onLoadFailed = {
	reloadStop.value = 0;
	urlBox.background = Color.red(1, 0.2);
};

browser = View(bounds:900@700).layout_(VLayout(
	HLayout(
		prev, reloadStop, next,
		urlBox,
		go
	),
	webview
));

browser.front;

urlBox.valueAction = "http://supercollider.github.io/"
)
::