WIDGET_BROWSER
The WIDGET_BROWSER function is used to create a web browser widget. The browser supports a wide variety of content, from HTML5 to JavaScript, video, and WebGL. Multiple browsers can be created within the same widget application.
The browser widget is supported on Windows and Linux.
Creating a browser is as simple as:
wParent = WIDGET_BASE()
url = "http://www.google.com"
wBrowser = WIDGET_BROWSER(wParent, VALUE=url, XSIZE=900, YSIZE=600)
WIDGET_CONTROL, wParent, /REALIZE
The browser will generate events when the address changes, the title or status changes, frames start and stop loading, etc.
For a detailed example of the browser widget combining IDL widgets, JavaScript, and a Google table, compile and run browser_ex.pro located in the examples/widget_browser directory of your IDL installation.
Syntax
Result = WIDGET_BROWSER( Parent [, /ALIGN_BOTTOM] [, /ALIGN_CENTER] [, /ALIGN_LEFT] [, /ALIGN_RIGHT] [, /ALIGN_TOP] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FUNC_GET_VALUE=string] [, KILL_NOTIFY=string] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=value] [, SCR_YSIZE=value] [, /SENSITIVE] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=string] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] )
Return Value
The returned value of this function is the widget ID of the newly-created widget.
Arguments
Parent
The widget ID of the parent widget for the new browser widget.
Keywords
ALIGN_BOTTOM
Set this keyword to position the widget at the bottom edge of the parent. To take effect, the parent should be a ROW base.
ALIGN_CENTER
Set this keyword to position the widget at the center of the parent. If the parent was created with the COLUMN keyword then the widget will be centered horizontally. If the parent was created with the ROW keyword then the widget will be centered vertically.
ALIGN_LEFT
Set this keyword to position the widget at the left edge of the parent. To take effect, the parent should be a COLUMN base.
ALIGN_RIGHT
Set this keyword to position the widget at the right edge of the parent. To take effect, the parent should be a COLUMN base.
ALIGN_TOP
Set this keyword to position the widget at the bottom edge of the parent. To take effect, the parent should be a ROW base.
EVENT_FUNC
A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from the widget.
EVENT_PRO
A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from the widget.
FUNC_GET_VALUE
A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user.
KILL_NOTIFY
Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to an empty string.
The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget.
NOTIFY_REALIZE
Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to an empty string.
The callback routine is called with the widget identifier as its only argument.
PRO_SET_VALUE
A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. See the SET_VALUE keyword on WIDGET_CONTROL for more information.
SCR_XSIZE
Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword.
SCR_YSIZE
Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword.
SENSITIVE
Set this keyword to control the initial sensitivity state of the widget.
Set this keyword to 1 to allow the widget to receive user input and generate events (this is the default value). If this keyword is set to 0 then the widget does not receive user input despite having a normal appearance.
After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword on WIDGET_CONTROL.
UNAME
Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
UNITS
Set this keyword to specify the units used when supplying measurements or position values. Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. This keyword does not change the units used in a widget event structure or in most of the fields of the geometry structure returned by WIDGET_INFO.
UVALUE
The "user value" to be assigned to the widget.
Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created.
If UVALUE is not present, the user value is undefined.
VALUE
Set this keyword to a scalar string containing the initial URL or raw HTML contents for the widget.
XOFFSET
The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming.
XSIZE
The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. By default, browser widgets are 640 pixels wide by 400 pixels high.
YOFFSET
The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming.
YSIZE
The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. By default, browser widgets are 640 pixels wide by 400 pixels high.
Keywords to WIDGET_CONTROL
A number of WIDGET_CONTROL keywords affect the behavior of browser widgets. In addition to those keywords that affect all widgets, the following are particularly useful: BROWSER_CANCEL_ALL_DOWNLOADS, BROWSER_CANCEL_DOWNLOAD, BROWSER_CANCEL_PAGE, BROWSER_GO_BACK, BROWSER_GO_FORWARD, BROWSER_NOTIFY, and BROWSER_RELOAD.
Keywords to WIDGET_INFO
A number of WIDGET_INFO keywords return information that applies specifically to browser widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: BROWSER_CAN_GO_BACK, BROWSER_CAN_GO_FORWARD, BROWSER_GET_PAGE_SOURCE.
Widget Events
The browser widget returns events with three different event structures:
{WIDGET_BROWSER, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, VALUE:""}
{WIDGET_BROWSER_DOWNLOAD, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, VALUE:"", URL:"", IDENTIFIER:""}
{WIDGET_BROWSER_ERROR, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, VALUE:"", ERROR_CODE:0L, ERROR_TEXT:""}
{WIDGET_BROWSER_CONSOLE, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, VALUE:"", SOURCE:"", LINE:0}
All three event structures have the following fields:
- ID: the widget identifier of the browser generating the event.
- TOP: the widget ID of the top level widget containing ID.
- HANDLER: the widget ID of the widget associated with the handler routine.
- TYPE: an integer giving the browser event type.
All of the events are detailed in the following table:
| Type | Meaning | Description |
|---|---|---|
|
0 |
BeforePopup |
Sent when the browser requests a new browser popup or tab. The VALUE is the requested URL. |
|
1 |
LoadStart |
Sent when the browser starts loading a new frame (may be sent multiple times if there are several frames). The VALUE is the new URL. |
|
2 |
LoadEnd |
Sent when the browser finishes loading a new frame (may be sent multiple times if there are several frames). The VALUE is the URL. |
|
3 |
LoadError |
Sends a {WIDGET_BROWSER_LOAD_ERROR} event when the browser has an error loading a new frame (may be sent multiple times if there are several frames). The VALUE is the URL. The fields ERROR_CODE and ERROR_TEXT give details about the error. |
|
4 |
AddressChange |
Sent once whenever the browser changes to a new URL. The VALUE is the new URL. |
|
5 |
TitleChange |
Sent when the browser title changes (may be sent twice, once on load start, once on load end). The VALUE is the new title. |
|
6 |
StatusMessage |
Sent when the browser updates its status message (usually when you hover over a link). The VALUE is the status message. |
|
7 |
FaviconChange |
Sent when the favicon URL changes. The value is the URL of the favicon file. |
|
8 |
ConsoleMessage |
Sends a {WIDGET_BROWSER_CONSOLE_MESSAGE} event when the browser logs a message to the console. The VALUE, SOURCE and LINE fields give the details of the message. |
| 9 | Notify |
Sent when the browser sends a JavaScript notification event to IDL. The VALUE is the notification message. |
| 10 | OnDownloadBegin | Sent when the browser starts downloading a file. The VALUE is the full filepath being downloaded, URL is the source of the download, and IDENTIFIER is a unique integer identifying the download – can be used to match start to end events.. |
| 11 | OnDownloadEnd | Set when a download is either completed or canceled. No differentiation is currently made. See OnDownloadBegin for the event description. |
Sending messages to JavaScript
In your IDL code, you can send messages to JavaScript using the BROWSER_NOTIFY keyword on WIDGET_CONTROL:
Widget_Control, wBrowser, BROWSER_NOTIFY=string
Note: a scalar string must be used. A convenient way of converting IDL data to a string is to use IDL's JSON_SERIALIZE function.
JavaScript Events
In your JavaScript code, you can send messages to IDL or receive messages from IDL.
To enable IDL JavaScript Events, you need to include the "idl-1.0.0.js" script, a copy of which can be found in the examples/widget_browser directory of your IDL installation:
<script type="text/javascript" src="idl-1.0.0.js"></script>
To send a message from JavaScript to IDL:
IDL.notifyIDL(string);
To receive messages from IDL, you need to register an event listener:
IDL.addEventListener(myListener);
where myListener is a function that accepts an "event" parameter. The event parameter will contain a property called "detail" that contains the message from IDL.
Example
<html>
<body>
<script type="text/javascript" src="idl-1.0.0.js"></script>
<script type="text/javascript">
IDL.addEventListener(function(event){
alert("Message from IDL: " + event.detail);
});
IDL.notifyIDL("Hello from JavaScript");
</script>
</body>
</html>
Browser Widget Implementation Details
The browser widget is implemented using the Chromium Embedded Framework (CEF), which is an open source framework for embedding a web browser engine based on the Chromium core. Given this, the browser has the rendering capabilities of Chrome, which means it can display a wide variety of content such as HTML5, JavaScript, video and WebGL.
Each IDL browser widget will run one or more idl_browser processes to do the rendering and GPU processing. As with Chrome, these extra processes protect the main process (IDL) from crashes and allow IDL to run without interruption.
Note: The version of Chromium that IDL uses may not be the most recent release of Chrome. When using the browser widget in your own applications, the browser may not have the most up-to-date security features of the latest release of Chrome. If you are developing an application for other users, they may have different versions of Chromium, depending upon their IDL version.
Version History
|
8.7.2 |
Introduced |