The WebBrowser (WebView2) is available in Build 2797 and later.
To work with WebBrowser that uses the Microsoft Edge WebView2, pay attention to the following.
Starting from Version 2022 R2, the PowerBuilder WebBrowser control has upgraded the underlying web platform from Chromium Embedded Framework (CEF) to Microsoft Edge WebView2.
The WebBrowser control now:
-
Supports browsing web page that contains JavaScript
-
Supports accessing web page that requires basic or digest authentication
The WebBrowser control will automatically display a login window for the user to enter the user name and password for authentication. If the authentication fails, this window will display again until the authentication is successful or the authentication operation is cancelled.
-
Supports browsing HTML and HTML5 pages
-
Supports browsing a PDF file online
-
Supports browsing local files (including htm, gif, jpg, jpeg, png, swf, txt, c, cpp, pdf, etc.) and does not support browsing the Microsoft Office file including docx, xlsx etc. or any file that cannot be opened by Google Chrome.
-
Supports browsing videos in most common non-proprietary formats. Proprietary formats such as MPEG-4 ASP, H.264, and H.265 formats are not supported.
-
Supports accessing microphone or camera on the device
-
Supports playing flash (with the flash plug-in installed by the user)
-
Supports browsing web pages that support multiple languages
-
Supports printing web pages as PDFs and responding to the print events
-
Supports the various HTTPS protocols
-
Supports the right-mouse context menus
-
Supports web page zoom in/out
-
Supports responding to the error event from the server certificate
-
Supports dynamically configuring the file download location
-
Supports responding to the keyboard actions (such as F5)
And:
-
Does not support callback of the popup window
-
Does not support cookie manipulation interface
-
Does not support request irrelevant to the browser
-
Does not support receiving focus when the user tabs among controls within a window
-
Does not support searching within the web page
-
Does not support drag & drop in the web page
-
Does not support Google Developer tools
-
Does not support loading the local file from different origins via file:/// (you will have to use http or https)
-
Does not support Google authentication (because Google does not allow OAuth requests to Google via embedded browsers)
For a complete list of properties/functions/events of the WebBrowser control, refer to the section called “WebBrowser control” in Objects and Controls.
Use WebBrowserSet and WebBrowserGet to configure the global settings for the WebBrowser control.
-
RuntimeMode -- The distribution mode of WebView2 Runtime.
-
FixedVersionRuntimePath -- The path of WebView2 Runtime Fixed Version.
-
DownloadPath -- The default download path.
-
allow-file-access-from-files -- Whether to allow access to the local files (XML etc.).
-
UserDataFolder -- The folder that stores user data. Both the relative path and absolute path are supported.
-
Language -- The language of WebBrowser control to be set.
-
UserAgent -- The User-Agent request header that contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.
Note
These settings such as RuntimeMode, FixedVersionRuntimePath, allow-file-access-from-files, UserDataFolder, Language, and UserAgent must be set before the WebBrowser control is initialized. You can set them in the application Open event.
If you have run the application (that includes the WebBrowser control) from PowerBuilder IDE, you may need to restart PowerBuilder IDE before the program can successfully initialize the WebBrowser control again.
Note
For code examples of using the WebBrowser control in the PowerBuilder application, refer to the Example Graph App included in the product or https://github.com/Appeon/PowerBuilder-Graph-Example.
You can define PowerBuilder user events for WebBrowser and then trigger the event in JavaScript.
The PowerBuilder user event to be registered should be defined as follows.
event type string eventName(string as_arg);
User events can be defined with one string-type parameter and string-type return value (code example) or no parameters.
User events must be registered by RegisterEvent function before it can be triggered in JavaScript.
After a PowerBuilder user event is registered successfully, it can be triggered by JavaScript on Web in the following ways (assuming the name of the registered event is TestPBEvent)
-
Syntax 1: trigger the user event synchronously and return a string
webBrowser.TestPBEvent ('The event is synchronously triggered by JavaScript') -
Syntax 2: trigger the user event asynchronously and return a JavaScript Promise object.
webBrowser.asyncfun.prototype.TestPBEvent ('The event is asynchronously triggered by JavaScript')
Note
In the registered PowerBuilder user event, only the asynchronous function EvaluateJavascriptAsync can be called; and calling any synchronous function such as EvaluateJavascriptSync will result in a process deadlock.
In the registered PowerBuilder user event, it is not allowed to call any other WebBrowser functions.
When the WebBrowser control (using Microsoft Edge WebView2) is used in your PowerBuilder application, you need to distribute the WebView2 Runtime with your application. WebView2 Runtime supports two distribution modes: Evergreen Runtime and Fixed Version; which means, you can choose to either distribute the automatically updated evergreen runtime, or distribute a fixed version of the runtime.
Which distribution mode to use
To distribute the automatically updated evergreen runtime, persistent Internet connection is required at the client, so that the Evergreen Runtime can be automatically installed and updated. The Evergreen Runtime distribution mode ensures that WebView2 Runtime is taking advantage of the latest features and security updates. In Windows 11 or later, the Evergreen Runtime is included as part of the Windows operating system; and it is updated automatically (when Internet connection is available). In Windows 10 or earlier, the Evergreen Runtime should be first installed using an online bootstrapper or an offline installer and then it will get updated automatically when Internet connection is available.
To distribute a fixed version of the runtime, the develop will need to download and install the latest available version of the Fixed Version to the specified location so that it can be automatically packaged and installed with the PowerBuilder application. The Fixed Version installed on the client will not be automatically updated; the developer can stay with the existing version or periodically update the version that is packaged and installed with the PowerBuilder application.
For more information about the pros and cons of each distribution mode, refer to this page.
How to configure the distribution mode
To configure how to distribute the WebView2 Runtime with the application, use one of the following ways:
-
Method #1: Configure the distribution mode in the PowerBuilder IDE.
-
Method #2: Configure the distribution mode in the application script.
Method #1: Configure the WebView2 Runtime distribution mode in the PowerBuilder IDE
In the Application painter, click Additional Properties on the General tab page in the Properties view; and then in the Application properties dialog box that displays, select the WebBrowser tab.
-
Always use the Evergreen Runtime at the client
This option is selected by default. When this option is selected, the Evergreen Runtime that is installed and updated with Windows will be used. If the client has no Evergreen Runtime installed, the client will be prompted to install the Evergreen Runtime from the URL which is specified in the "WebView2 Runtime Download URL" field.
-
Always use the Fixed Version at the client
When this option is selected, the Fixed Version must be packaged with your PowerBuilder application and then installed to the client.
You will need to download and install a version of the WebView2 Runtime (from this website) to the location specified in the "WebView2 Runtime Fixed Version" group, so that it will be automatically packaged and installed with the PowerBuilder application.
-
Use the Evergreen Runtime by default; if it does not exist, use the Fixed Version
The Evergreen WebView2 Runtime will be used by default, but if it does not exist, the Fixed Version Runtime will be used.
Method #2: Configure the WebView2 Runtime distribution mode in the application script
In the application Open event, call the WebBrowserSet function to set the distribution mode:
long ll_Ret
ll_Ret = WebBrowserSet ("RuntimeMode", 0) //0: Evergreen Runtime, 1: Fixed Version, 2: First Evergreen, then Fixed Version
The precedence order in the development environment
The WebView2 Runtime distribution mode takes effect in the following precedence order:
-
The runtime mode specified in the application script.
-
The runtime mode selected in the PowerBuilder IDE.
When WebView2 Runtime Fixed Version is selected, the application will search for the runtime in the following precedence order:
-
The path specified in FixedVersionRuntimePath of the WebBrowserSet function.
-
The directory where the application executable file is located.
-
The PowerBuilder Runtime corresponding to the build number selected in the PowerBuilder IDE > Tools menu > System Options dialog.
The precedence order in the production environment
The WebView2 Runtime distribution mode takes effect in the following precedence order:
-
The runtime mode specified in the application script.
-
The runtime mode selected in the PowerBuilder IDE.
When WebView2 Runtime Fixed Version is selected, the application will search for the runtime in the following precedence order:
-
The path specified in FixedVersionRuntimePath of the WebBrowserSet function.
-
The directory where the application executable file is located.
-
The PowerBuilder Runtime directory specified in the configuration file (executable-name.xml).
-
The PowerBuilder Runtime directory stored in the system registry.
-
The PowerBuilder Runtime directory specified in the PATH environment variable (if any)
If the WebBrowser control is used in the application, the developer needs to select the "WebBrowser Support" option in the PowerBuilder Runtime Packager to automatically package the WebBrowser runtime files into the PowerBuilder runtime installer.
If the developer wants to manually distribute the PowerBuilder runtime files, s/he must go to the PowerBuilder Runtime location and get the runtime files required for the WebBrowser support according to the WebView2 distribution mode:
-
For WebView2 Evergreen Runtime, pbwebbrowser.dll and webbrowserapi.tlb are required.
-
For WebView2 Runtime Fixed Version, pbwebbrowser.dll, webbrowserapi.tlb, and "PBWebView2" folder are required.
The "PBWebView2" folder contains the files of the Fixed Version that was installed by the developer.
The WebBrowser (CEF) is available in Build 2779 and earlier.
To work with WebBrowser that uses the Chromium Embedded Framework (CEF), pay attention to the following.
The WebBrowser control uses the Chromium Embedded Framework (CEF), an open source framework used in many applications to provide web browsing functionality. Therefore, the WebBrowser control can be used to create a Web browser that can execute JavaScript and communicate between the Web page and the PowerBuilder client.
The WebBrowser control:
-
Supports browsing web page that contains JavaScript
-
Supports accessing web page that requires basic or digest authentication
The WebBrowser control will automatically display a login window for the user to enter the user name and password for authentication. If the authentication fails, this window will display again until the authentication is successful or the authentication operation is cancelled.
-
Supports browsing HTML and HTML5 pages
-
Supports browsing a PDF file online
-
Supports browsing local files (including htm, gif, jpg, jpeg, png, swf, txt, c, cpp, pdf, etc.) and does not support browsing the Microsoft Office file including docx, xlsx etc. or any file that cannot be opened by Google Chrome.
-
Supports browsing videos at common formats in web page (MPEG-4 ASP, H.264, and H.265 formats are unsupported)
-
Supports accessing microphone or camera on the device
-
Supports playing flash (with the flash plug-in installed by the user)
-
Supports browsing web pages that support multiple languages
-
Supports printing web pages as PDFs and responding to the print events
-
Supports the various HTTPS protocols
-
Supports the right-mouse context menus
-
Supports web page zoom in/out
-
Supports responding to the error event from the server certificate
-
Supports dynamically configuring the file download location and proxy settings
And does not support:
-
callback of the popup window
-
cookie manipulation interface
-
request irrelevant to the browser
-
responding to the keyboard actions (such as F5)
-
receiving focus when the user tabs among controls within a window
-
searching within the web page
-
drag & drop in the web page
-
Google Developer tools
-
loading the local file from different origins via file:/// (you will have to use http or https)
For a complete list of properties/functions/events of the WebBrowser control, refer to the section called “WebBrowser control” in Objects and Controls.
Use the global functions WebBrowserSet and WebBrowserGet to configure the path, user agent and proxy settings for the WebBrowser control.
Path settings:
-
CachePath -- The folder that stores the web page cache, cookies etc.
-
UserDataPath -- The folder that stores the user data dictionary.
-
DownloadPath -- The default download path.
User agent settings:
-
UserAgent -- The User-Agent request header that contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.
Proxy settings:
-
ProxyAuto -- Whether to use auto proxy detection. WebBrowser supports auto proxy detection, PAC (proxy auto configuration) file setting, and manual proxy settings. The priority order of the settings is: auto proxy detection > PAC file setting > manual proxy settings. By default the IE proxy is used.
-
ProxyPacUrl -- The URL of the server where the PAC file is located.
-
ProxyAddress -- The address of the proxy server.
-
ProxyPort -- The port of the proxy server.
-
ProxyUser -- The user name that will be authenticated by the proxy server.
-
ProxyPassword -- The password that will be authenticated by the proxy server.
Local file access:
-
allow-file-access-from-files -- Whether to allow access to the local files (XML etc.).
-
enable-media-stream -- Whether to allow access to the microphone or camera.
You can define PowerBuilder user events for WebBrowser and then trigger the event in JavaScript. User events must be defined with only one string-type parameter and string-type return value (code example).
EventName (string parameter)
User events must be registered by RegisterEvent function before it can be triggered in JavaScript.
It is not allowed to call any other WebBrowser functions in the user event.
If the WebBrowser control is used in the application, the developer needs to select the "WebBrowser Support" option in the PowerBuilder Runtime Packager to package the WebBrowser components (and the "pbcef" folder) into the PowerBuilder runtime installer.
This new WebBrowser control has the following advantages over the Microsoft Web Browser OLE control:
-
Supports HTML5
-
Provides more control on download
-
Able to set the default URL
-
Shorter dot notation to access functions or properties
This new WebBrowser control has the following disadvantages compared to the Microsoft Web Browser OLE control:
-
Fewer options on the right-click popup menu
-
Does not support the web page document interface
-
Unable to get the current URL through properties or functions
For differences on properties/functions/events of WebBrowser control vs. Microsoft Web Browser OLE control, refer to the section called “WebBrowser control” in Objects and Controls.
In PowerBuilder WebBrowser control, the underlying web platform has been upgraded from CEF to WebView2. Some functions supported by WebView2 are different from those of CEF.
-
If an error occurs during the execution of JavaScript codes, the WebView2 event returns null but CEF event returns specific error message.
-
In the ResourceRedirect event, the request headers are obtained in the headers argument in WebView2 while the response headers are obtained in CEF.
-
The differences in return values between WebView2 and CEF are listed in the following table.
WebView2
CEF
Unsupported type
Returns null.
Result:{"type":"null","value":null}Returns undefined type and value.
Result:{"type":"undefined","value":"undefined"}Unsupported functions
Returns object.
Result:{"type":"object","value":{}}Returns function.
Result:{"type":"function","value":"unsupport"DateTime type
Not supported. Returns object.
Result:{"type":"object","value":{}}Supported. Returns datetime.
Result:{"type":"datetime","value":"2022-06-30 16:41:15.859"}Integer type boundary value
Returns double.
Result:{"type":"double","value":2147483648.0}Returns integer.
Result:{"type":"integer","value":-2147483648}Array
Returns JSON with two-level structure.
Result:{"type":"array","value":[1,2,3,4]}Returns JSON with three-level structure.
Result:{"type":"array","value":[{"type":"integer","value":1},{"type":"integer","value":2},{"type":"integer","value":3},{"type":"integer","value":4}]}Nan, Infinity and -Infinity
Not supported. Returns null.
Supported.
