ON THIS PAGE |
This object embeds the Chromium HTML rendering engine, which can be rendered at full screen or as a widget. You can display multiple roHtmlWidget instances at the same time.
Use the roKeyStore object to provide client certificates for websites. Use the roVirtualMemory object to set up a virtual memory repository for Chromium. |
The roHtmlWidget object is initialized with an roRectangle object, which specifies the size and positioning of the widget on the screen, and an optional associative array, which defines properties for the widget.
CreateObject("roHtmlWidget", rect As roRectangle, properties As roAssociativeArray) |
The properties of an roHtmlWidget instance can be set with an associative array at initialization or with equivalent methods after initialization. Because many roHtmlWidget properties cannot be changed without reloading the page (and can produce unpredictable results if changed while the page is running), we recommend setting properties at initialization when possible, rather than using the equivalent methods.
Defining initialization properties for an roHtmlWidget instance disables some methods for that instance (e.g. |
The associative array passed during initialization can have the following parameters:
Enables Node.js® on the widget. This value is false
by default.
Reloading a page which has Node.js enabled can be classified as an undefined behavior. The recommended method for restarting a Node instance is to destroy and rebuild the roHtmlWidget |
Enables focus for mouse/touchscreen events. This value is true
by default.
Enables mouse/touchscreen events. This value is false
by default.
Enables automatic scrollbars for content that does not fit into the viewport. This value is false
by default.
The browser defaults to desktop-style scrollbars, but they can be configured for mobile style as well.
Enables pinch-to-zoom functionality. This value is false
by default.
This setting has been deprecated. As of OS8, GPU rasterization is enabled by default and setting this property has no effect. |
Enables GPU rasterization for HTML graphics. By default, the decision to use GPU rasterization is based on internal Chromium logic.
This setting has been deprecated. As of OS8, Canvas acceleration is enabled by default and can be disabled by setting this flag to |
Enables 2D canvas acceleration. This will improve the framerate of most HTML pages that use 2D animations, but can cause out-of-memory issues with pages that use a large number of off-screen canvas surfaces.
Enables JavaScript on the widget. This value is true
by default.
Enables BrightScript-JavaScript objects. This value is false
by default.
In OS 8.2.55.4 and later, html widgets that are loaded from HTTP/HTTPS protocols do not share the same local storage database (html widgets that are loaded via file protocol act as they did in previous releases). These flags allow you to change the default behavior of widgets loaded through HTTP/HTTPS from "unshared" to "shared", or to change the default behavior of widgets with locally loaded files to "unshared" from "shared":
Allows html widgets loaded via HTTP/HTTPS protocol to share local storage if they are loaded from the same domain.
Prevents html widgets loaded via FILE protocol from sharing storage.
Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the roRectangle containing the widget are not affected by rotation). The following values are accepted:
"identity"
: There is no transform (i.e. the widget content is oriented as landscape). This is the default setting."rot90"
: The widget content is rotated to portrait at 90 degrees (clockwise)."rot270"
: The widget content is rotated to portrait at 270 degrees (counter-clockwise).Modifies the default user-agent string for the roHtmlWidget instance.
The URL to use for display. See the
SetUrl()
entry below for more information on using URIs to access files from local storage.
Specifies the language to load the web page in.
Applies the specified user stylesheet to pages in the widget. The parameter is a URI specifying any file:
resource in the storage. The stylesheet can also be specified as inline data.
Specifies the default HWZ behavior. This value is off
by default. To enable it, set it to on
.
Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage class.
Sets the total size (in bytes) allotted to all local storage applications (including IndexedDB). A BrightScript integer is only guaranteed to be able to represent a count of bytes up to 2GB so avoid using integers when calculating the size: Use float or double instead since they can represent values over 2GB (string can also be used but is not recommended). If the storage path is specified without a storage quota, Chromium defaults to reserving 1GB plus 10% of the total size of the storage device.
Configures the message port to which the roHtmlWidget instance will send events. When using initialization parameters, the port
parameter should be used instead of the SetPort()
method to ensure the script can catch load-started
, load-finished
, and load-error
events.
Specifies a list of font files that can be accessed by the webpage. Font files are specified as an array of string filenames. Supported font types include TrueType Font files (.ttf) and Web Open Font files (.woff, .woff2).
Configures the PCM audio output for the HTML widget. Outputs are specified as an array of strings, each string being the name of an output. (See roAudioOutput documentation for a list of acceptable names.)
Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
Configures multi-channel audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
Configures the Chromium Inspector for the widget.
[string] ip_addr
: The Inspector IP address. This value is useful if the player is assigned more than one IP address (i.e. there are multiple network interfaces) and you wish to limit the Inspector server to one. The default value is "0.0.0.0"
, which allows the Inspector to accept connections using either IP address.
[int] port
: The port for the Inspector server.
Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc.
[Boolean] websecurity
: Enables Chromium security checks for cross-origin requests. [Boolean] camera_enabled
: Enables webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.[Boolean] insecure_https_enabled
: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts (insecure HTTPS is disabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments and should only be used for testing.With BOS 8.2 and later (Chromium69 and later), several new CORS checks have been added: security_params.websecurity
or enableSecurity(false)
do not disable all these checks. Use the following registry setting instead:
registry write html disable-web-security 1
This flag will take effect on all roHtmlWidget
instances, as opposed to previous flags which are only effective on the instance they are called on.
The |
Specifies JavaScript code to inject at different initialization points (JavaScript code can also be injected during runtime using the InjectJavaScript()
method). The associative array can contain three parameters (described below). Each parameter value is an array of associative arrays, each containing a single key/value pair. The array must contain a source
key. The source
value is a string that can contain any of the following: pure JavaScript code, a path to a JavaScript file, or a base64-encoded string (i.e. beginning with data:text/javascript;charset=utf-8;base64,
). Mutliple source
keys can be included, but the load order will be unpredictable. The array can also contain the optional world
key, which can be assigned one of the following values: "application"
, "user"
, or "main"
(see this page for more details); if the world
parameter is not included in the array, "application"
is selected by default.
document_creation
: The script will run as soon as the document is created. This behavior is not suitable for any DOM operation.document_ready
: The script will run as soon as the DOM is ready. This behavior is equivalent to the DOMContentLoaded
event firing in JavaScript. deferred
: The script will run when the page load finishes.
config = { javascript_injection: { document_creation: [{source: "0.js" }], document_ready: [{source: "1a.js" }, {source: "1b.js" }], deferred: [{source: "2.js" }] }, url: "..." } |
Allows the roHtmlWidget instance to access one or more asset pools. If a file exists in multiple specified asset pools, the asset pool with the lowest index in the array has precedence. Each array entry is an associative array containing information about an asset pool:
[roAssetPool] pool
: An asset pool containing files [roAssetCollection] collection
: A manifest identifying the files in the pool[string] uri_prefix
: The URI prefix of the webpage resources to retrieve from the pool
[string] pool_prefix
: The pool prefix that will replace the URI prefix when looking up the resource in the poolGives more information when a member function returns false
.
Hides the widget.
Shows the widget.
Raises the html widget above all other graphical elements on screen (including other html widgets).
Lowers the html widget below all graphical elements on screen.
Changes the size and positioning of the widget rectangle using the passed roRectangle object.
Displays content from the specified URL. When using this method to retrieve content from local storage, specify the file location as follows: "file:/<drive>:/<directory>/<filename>"
. For example, an index.html file in the "Content" folder on the SD card can be selected with the string "file:/SD:/Content/index.html"
. You can also omit the drive specification to select the currently active drive (i.e. whichever drive the current autorun as loaded from).
Tells Chromium to use the specified username and password when retrieving the given URL.
Sets the mapping between the URL space and the pool files. HTML content that has been deployed via BrightAuthor will typically reside in the pool and have encrypted SHA1-based filenames. A mapping mechanism is required to allow any relative URIs contained in the HTML content to continue working and to locate the appropriate resources in their respective pool locations.
You can use this method to bind part of the resource URI space onto pool locations. This method accepts the following arguments: an roAssetPool object containing assets, an roAssetCollection object identifying the assets, and two semi-arbitrary strings (URI_PREFIX and POOL_PREFIX).
Any URI in the form "file:/[URI_PREFIX][RESOURCE_ID]"
will be rewritten into the form "[POOL_PREFIX][RESOURCE_ID]"
. It will then be located in the pool as if that name had been passed to the roAssetPoolFiles.GetPoolFilePath() method. This binding occurs for every instance of roHtmlWidget, so different mappings can be used for different bundles of content.
Adjusts the scale factor for the displayed page (the default equals 1.0).
Enables or disables pinch-to-zoom functionality, which is disabled by default.
Deprecated. Use security_params
in initialization parameters instead.
Deprecated. Use mouse_enabled
in initialization parameters instead.
Deprecated. Use transform
in initialization parameters instead.
Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the roRectangle containing the widget are not affected by rotation). This method accepts the following strings:
"identity"
: There is no transform (i.e. the widget content is oriented as landscape). This is the default setting."rot90"
: The widget content is rotated to portrait at 90 degrees (clockwise)."rot270"
: The widget content is rotated to portrait at 270 degrees (counter-clockwise).The JavaScript |
Sets the overall alpha level for the widget (the default equals 255).
Deprecated. Use scrollbar_enabled
in initialization parameters instead.
Deprecated. Use fonts
in initialization parameters instead.
Deprecated. Use pcm_audio_outputs
in initialization parameters instead.
Deprecated. Use compressed_audio_outputs
in initialization parameters instead.
Deprecated. Use multi_channel_audio_outputs
in initialization parameters instead.
Deprecated. Use hwz_default
in initialization parameters instead.
Sets default playback settings for <video>
elements in the widget. Available parameters are identical to the roVideoPlayer.PlayFile() method. Default settings will be overwritten by parameters specified in individual <video>
elements.
Deprecated. As of OS8, GPU rasterization is enabled by default and calling this method has no effect.
Deprecated. Use canvas_2d_acceleration_enabled
in initialization parameters instead.
Deprecated. Use user_stylesheet
in initialization parameters instead.
Discards any resources that Chromium has cached in memory.
Configures the HTML storage path. This method takes effect when a new roHtmlWidget instance is created; it doesn't apply to the roHtmlWidget instance on which it is called.
As of OS8, the |
Configures the HTML storage path. See the SetLocalStorageDir()
entry above for details.
This method takes effect when a new roHtmlWidget instance is created; it doesn't apply to the roHtmlWidget instance on which it is called.
Configures the HTML storage path. See the SetLocalStorageDir()
entry above for details.
This method takes effect when a new roHtmlWidget instance is created; it doesn't apply to the roHtmlWidget instance on which it is called.
Sets the total size (in bytes) for all persistent HTML storage on the player. This method can accept a string, double, or integer. A number literal can only represent byte numbers up to 2GB; use a string to specify larger amounts. If the storage path is specified without a storage quota, Chromium defaults to reserving 1GB plus 10% of the total size of the storage device.
This method takes effect when a new roHtmlWidget instance is created; it doesn't apply to the roHtmlWidget instance on which it is called.
As of OS8, the |
Sets the total size (in bytes) for all persistent HTML storage on the player. See the SetLocalStorageQuota()
entry above for details.
This method takes effect when a new roHtmlWidget instance is created; it doesn't apply to the roHtmlWidget instance on which it is called.
Sets the maximum size (in bytes) for the application cache. Changing the storage size of the application cache will clear the cache and rebuild the cache storage. Depending on database-specific attributes, you will only be able to set the size in units that are equal to the page size of the database, which is established at creation. These storage units will occur only in the following increments: 512, 1024, 2048, 4096, 8192, 16384, 32768.
Deprecated. Use javascript_enabled
in initialization parameters instead.
Deprecated. If javascript_enabled
is set to true
in the initialization parameters, JavaScript objects are enabled for all sites.
Posts a collection of key:value pairs to the BSMessagePort JavaScript class (see the JavaScript Objects for BrightScript tech note for more details). This method does not support passing nested associative arrays.
Immediately injects a user script into the JavaScript engine. The passed string can contain any of the following: pure JavaScript code, a path to a JavaScript file, or a base64-encoded string (i.e. beginning with data:text/javascript;charset=utf-8;base64,
).
This method can be used to simulate the bind_ready
option:
if type(event) = "roHtmlWidgetEvent" then if event.GetData().reason = "load-finished" then h.InjectJavascript("fillPasswordFields()") end if end if |
Changing the DOM is only possible at |
Deprecated. Use inspector_server
in initialization parameters instead.
Deprecated. Use user_agent
in initialization parameters instead.
Returns the currently active user-agent string for the roHtmlWidget instance.
Deprecated. Use user_agent
in initialization parameters instead.
Sets the name or address of the proxy server that the roHtmlWidget instance will use to make HTTP requests. This method takes effect immediately. It does not affect network operations performed by other components in the firmware. The string can be used to specify either the proxy URL or the location of a .pac proxy file:
The following are examples of valid location formats for .pac files:
|
Exempts the specified hosts from the proxy configuration on the roHtmlWidget instance. The passed array should consist of one or more hostnames. The player will attempt to reach the specified hosts directly rather than using the proxy that has been specified with the SetProxy()
method. For example, the hostname "example.com" would exempt "example.com", "example.com:80", and "www.example.com" from the proxy setting.
Allows the user to set up one or more proxies. If proxy pac files are included, this method must be used to specify authentication parameters.
Accept any dialog request with the given string, if there is any such request.
Reject any dialog request.
Posts messages of type roHtmlWidgetEvent to the attached message port.
Sets the user data that will be returned when events are raised.
Returns the user data that has previously been set via SetUserData()
. It will return Invalid if no data has been set.
If the properties of an roHtmlWidget object are configured at initialization, most ifHtmlWidget methods will be disabled. However, the following methods are still functional:
Hide()
Show()
EnablePinchToZoom()
FlushCachedResources()
SetUserAgent()
GetUserAgent()
SetUserAgentSuffix()
PostJSMessages()
The following examples show how to use either an associative array or object methods to configure an roHtmlWidget instance using local storage to cache the files.
Note that these techniques are mutually exclusive.
x = 0 y = 0 width = 1920 height = 1080 url = "http://www.brightsign.biz" rect = CreateObject("roRectangle", x, y, width, height) config = { url: url, mouse_enabled: true, storage_path: "/local/", } html = CreateObject("roHtmlWidget", rect, config) html.Show() |
x = 0 y = 0 width = 1920 height = 1080 url = "http://www.brightsign.biz" rect = CreateObject("roRectangle", x, y, width, height) html = CreateObject("roHtmlWidget", rect) html.SetUrl(url) html.EnableMouseEvents(true) html.SetLocalStorageDir("/local/") html.Show() |