6.1-roHtmlWidget

Object creation: Like other widgets, an roHtmlWidget is created with an roRectangle, which specifies the size and positioning of the widget on the screen.

CreateObject("roHtmlWidget", rect As roRectangle)

ifHtmlWidget

GetFailureReason() As String

Gives more information when a member function returns False.

Hide() As Boolean

Hides the widget.

Show() As Boolean

Shows the widget.

SetRectangle(r As roRectangle) As Boolean

Changes the size and positioning of the widget rectangle using the passed roRectangle object.

SetURL(URL As String) As Boolean

Displays content from the specified URL.

When using SetUrl to retrieve content from local storage, you do not need to specify the full file path: SetUrl("file:///example.html"). 

If the content is located somewhere other than the current storage device, you can specify it within the string itself. For example, you can use the following syntax to retrieve content from a storage device inserted into the USB port when the current device is an SD card: SetUrl(" file:///USB1:/example.html ").   

MapFilesFromAssetPool(asset_pool As roAssetPool, asset_collection As roAssetCollection, pool_prefix As String, uri_prefix As String) As Boolean

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, as long as you use the following: an roAssetPool object containing some assets, an roAssetCollection object identifying them, 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.

SetZoomLevel(scale_factor as Float) As Boolean

Adjusts the scale factor for the displayed page (the default equals 1.0).

EnableSecurity(enable As Dynamic) As Boolean

Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc. This method accepts either a Boolean argument or an associative array, which can contain the following parameters:

• websecurity: A Boolean parameter that enables or disables Chromium security checks. This parameter is identical to passing a Boolean argument to the method itself.
• camera_enabled: A Boolean parameter that allows or disallows webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.

EnableMouseEvents() As Boolean

Enables response to button presses if True. Setting this method to False (the default) disables this feature.

SetPortrait(portrait_mode As Boolean) As Boolean

Sets the widget orientation to portrait if True. If this method is False (the default), the widget is oriented as a landscape.

SetTransform(transform As String) As Boolean

Sets the screen orientation of the widget. This method accepts the following strings:

• "identity": There is no transform (i.e. the widget is oriented as landscape). This is the default setting.
• "rot90": The widget is rotated to portrait at 90 degrees.
• "rot270": The widget is rotated to portrait at 270 degrees.

SetAlpha(alpha As Integer) As Boolean

Sets the overall alpha level for the widget (the default equals 255).

EnableScrollbars(scrollbars As Boolean) As Boolean

Enables automatic scrollbars for content that does not fit into the viewport if True. Setting this method to False (the default) disables this feature.

AddFont(filename As String) As Boolean

Makes a font available for text rendering. The AddFont() method can be used to supply additional or custom typefaces for the HTML rendering engine. These should be supplied in the form of TTF files, and the filename should be passed as the argument to AddFont().

SetHWZDefault(default As String) As Void

Sets the default HWZ mode for HTML video. Normally, HWZ must be enabled in each <video> tag, but passing "on" to this string enables HWZ for all <video> elements. This method can also accept a semicolon-separated list of HWZ parameters:

• on/off: Enables or disables HWZ mode.
• z-index: Sets the default z-ordering for <video> elements. A positive integer places the video in front of all graphics; a negative integer places the video behind all graphics; and a zero value disables HWZ mode completely. You can customize the z-ordering of individual video elements with respect to each other by inserting the "z-index" parameter into the <video> tag.
• transform: Sets the default rotation for <video> elements. HWZ mode must be enabled for transforms to work.
  • identity: No transformation (default behavior)
  • rot90: 90 degree clockwise rotation
  • rot180: 180 degree rotation
  • rot270: 270 degree clockwise rotation
  • mirror: Horizontal mirror transformation
  • mirror_rot90: Mirrored 90 degree clockwise rotation
  • mirror_rot180: Mirrored 180 degree clockwise rotation
  • mirror_rot270: Mirrored 270 degree clockwise rotation
• fade: Sets the fading behavior for <video> elements.
  • auto: Videos transition without fade effects. This is the default behavior.
  • always : When a video ends, the video window will go black. The new video will then fade in.
• luma-key/cr-key/cb-key: Enables luma and/or chroma keying for <video> elements. HWZ mode must be enabled for luma/chroma keying to work.

 html.SetHWZDefault("on; transform:rot90; luma-key:#ff0020;")

ForceGpuRasterization(enable As Boolean) As Boolean

Enables GPU rasterization for HTML graphics. This method will take effect for subsequent page loads only. If Chromium determines that a page is not compatible, it will refuse to enable GPU rasterization for that page.

SetUserStylesheet(URI As String) As Boolean

Applies the specified user stylesheet to the page(s) loaded in the widget. The parameter can be a URI specifying any file: resource in the storage. The stylesheet can also be specified as inline data in the following form:

"data:text/css;charset=utf-8;base64,<base64 encoded data>"

This method will fail if you specify the inline data in any other order or if you use any data format other than base64.

SetAppCacheDir(file_path As String) As Boolean

Sets the directory to use for storing the application cache (which services <html manifest="example.appcache"> tags). The file path is passed to the method as a string (e.g. "SD:/appcache").

SetAppCacheSize(maximum As Integer) As Boolean

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.

FlushCachedResources() As Boolean

Discards any resources that Chromium has cached in memory.

SetLocalStorageDir(file_path As String) As Boolean

Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage class.

SetLocalStorageQuota(maximum As Integer) As Boolean

Sets the total size (in bytes) allotted to all local storage applications. The default total size is 5MB.

SetWebDatabaseDir(file_path As String) As Boolean

Specifies the directory that should be used for web database applications (e.g. "SD:/webdb"). This method must be called before using web database applications such as Web SQL or IndexedDB.

SetWebDatabaseQuota(maximum As Integer) As Boolean

Sets the total size (in bytes) allotted to all web database applications. The default total size is 5MB.

EnableJavaScript(enable As Boolean) As Boolean
 

AllowJavaScriptURLs(url_collection As roAssociativeArray)

Allows the specified JavaScript BrightScript classes to be used by the specified URLs (all BrightScript classes in JavaScript are disabled by default). This method accepts an associative array that maps JavaScript BrightScript classes to the URL(s) that are allowed to use them.

• An all key indicates that all classes are authorized for the associated URL(s).
• An asterisk "*" value indicates that all URLs are authorized for the associated BrightScript class.
• A "local" value indicates that all local pages are authorized for the associated BrightScript class.

The following will enable all BrightScript classes for all URLs:

html.AllowJavaScriptUrls({ all: "*" })

The following will enable all BrightScript classes for local pages and the BrightSign homepage:

html.AllowJavaScriptUrls({ all: ["local", "http://www.brightsign.biz"]})

PostJSMessage(data As roAssociativeArray) As Boolean

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.

StartInspectorServer(port As Integer) As Boolean

Enables the JavaScript console, which allows you to debug JavaScript applications while a webpage is running. To access the console, navigate to the player IP address at the specified port number. See this page for documentation relating to the JavaScript console.

SetUserAgent(user_agent As String) As Boolean

Changes the default user-agent string reported by the rendering engine.

The following is an example of a default user-agent string sent by a BrightSign player:

BrightSign/4.7.85.2-8-g1a6e6f6-td-debug (XD1230) Mozilla/5.0 (compatible; Linux mips) AppleWebKit/537.4 (KHTML, like Gecko)
Chromium/18.0.1025.168 Chrome/18.0.1025.168 Safari/537.4

SetPort(port As roMessagePort)

Posts messages of type roHtmlWidgetEvent to the attached message port.

ifUserData

SetUserData(user_data As Object)

Sets the user data that will be returned when events are raised.

GetUserData() As Object

Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.