Browser

Exact behavior depends on operating system - see below

Description

The APLX Browser control implements a web browser, as a control which you can place on windows which you create. You can use it to display HTML Help files in your application, or to display pages from web sites accessed over the internet (Note: Under Linux, this is only partially implemented, as described below).

To use the Browser control, you create a window in the normal way, and place the Browser control on it. (If you want the Browser to fill the whole window, use the align property with a value of ¯1). You tell the control to fetch an HTML page (either from the local disk, or from the internet) by using the Load method. The user can then click on hyperlinks to load further pages, as in a normal web browser.

Browser properties

Key properties of the Browser control include:

status: (Read-only) Returns a three-element boolean vector. The first is 1 if the control is busy fetching a page, 0 if it is not busy. The second is 1 if the Back method can be called (i.e. there is a previous page in the history list), else 0. The third is 1 if the Forward method can be called (i.e. there is a subsequent page in the history list).

text: (Read-only) Returns a character vector (with embedded carriage returns), containing the current text as displayed in the control, with the HTML tags stripped out.

contents: (Read-only) Returns a character vector (with embedded carriage returns), containing the raw HTML text of the page currently displayed in the control.

caption or title: (Read-only) Returns a character vector containing the title of the page currently displayed in the control.

url: (Read-only) Returns a character vector containing the URL (Uniform Resource Location) of the page currently displayed in the control. This is not necessarily the same as the page which has been requested using the Load method or clicked-on by the user, because the request may have been redirected to a different location.

offline: If the offline property is set to 1, the Browser object will access only local files and cached copies of pages. The default is 0, meaning that the Browser will connect via the Internet to access web pages where necessary. Note: This property is ignored under MacOS.

Browser methods

Key methods of the Browser control include:

Load: The Load method takes a single parameter, which is the URL of the web page you want to display. It can be an internet address (such as 'http://www.bbc.co.uk/news'), or a local file address (such as 'file://C:\Program Files\MicroAPL\APLX\help\HTML\ch.htm'). You can also just specify a local file name without the 'file://' prefix. It is important to note that the actual loading of the page happens asynchronously, i.e. the Load method may return before the page has been retrieved from the internet. You can use the status property to determine whether the page is still being loaded.

Back: This method takes no arguments. It causes the Browser to go back one page in the history of previously-displayed web pages. It does nothing if there is no previous page. (You can test for this by reading the status property).

Forward: This method takes no arguments. It causes the Browser to go forward one page in the history of previously-displayed web pages. It does nothing if there is no subsequent page. (You can test for this by reading the status property).

Copy: This method takes no arguments. It causes the Browser to copy any selected text to the Clipboard.

Print: This method takes no arguments. It causes the Browser to print the currently-displayed page on the currently-selected printer. Note: The Print method is not implemented under Linux.

Stop: This method takes no arguments. If a page is loading, this method will abort the fetch.

Refresh: This method takes no arguments. It causes the current page to be reloaded from the internet or from disk, as appropriate.

Browser events

The Browser control can trigger the following callbacks:

onReady: This event occurs when a page has been successfully loaded and displayed.

onError: This event occurs when an error occurs retrieving a page.

Platform-dependent notes

Under Windows, the APLX Browser control is a wrapper for the Internet Explorer ActiveX Control. This means that, to use the Browser control, you must have Microsoft Internet Explorer installed. Note that, as well as using the properties and methods documented for the APLX Browser control itself, you can also directly access the Internet Explorer properties and methods (with names preceded by 'x' or 'X' respectively). See Microsoft's documentation on Reusing the Web Browser Control for more details on programming the browser directly.

Under Linux, the APLX Browser control is built-in to APLX, but its functionality is very restricted. It uses a limited HTML rendering engine which can handle simple HTML pages, but which does not have any scripting, plug-in, form-filling or encryption capability. Unrecognised HTML elements are ignored. In addition, the control implements only a small subset of the HTTP protocol. This means that many web pages will not display or operate correctly. The Print method is not supported. However, the Browser control is still very useful for adding HTML help to an application, and for certain accessing web pages which you know can be displayed reasonably well using only the simpler HTML elements. (The same underlying control is used to display the APLX Help pages under Linux).

Under MacOS X, the APLX Browser control is a wrapper for Apple's Safari HTML display engine. This is available under MacOS 10.2 and later only. Because of limitations in the Safari control, it may not operate correctly if the window contains Edit fields and other input controls.

Under MacOS 9, the APLX Browser control is not available.

Example

     ∇DEMO_Browser;DEMO
[1]   ⍝ Sample function demonstrating use of the Browser object
[2]   DEMO←'⎕' ⎕NEW 'Window' ⋄ DEMO.scale←5 ⋄ DEMO.size←470 800
[3]   DEMO.Web.New 'Browser' ⋄ DEMO.Web.align←¯1
[4]   ⍝
[5]   ⍝ Add a callback so window title changes when a new page is loaded
[6]   DEMO.Web.onReady←"DEMO.title←DEMO.Web.title"
[7]   ⍝
[8]   ⍝ Display a page from the MicroAPL web site
[9]   DEMO.Web.Load 'http://www.microapl.co.uk/apl'
[10]  ⍝
[11]  ⍝ Process events until the window is closed
[12]  0 0⍴⎕WE DEMO
     ∇

Properties

align anchors aquaadjust autodraw caption children class color contents data doublebuffered dragsource droptarget enabled events extent handle maxsize methods minsize name offline opened order pointer properties scale self size sourceformats status tabstop targetformats text tie units url verbs visible where winptr

Methods

Back Click Clienttoscreen Close Copy Create Delete Draw Focus Forward Hide Load New Open Paint Print Refresh Resize Screentoclient Send Set Show Stop Trigger

Callbacks

onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onError onFocus onHide onKeyDown onKeyPress onKeyUp onMouseDown onMouseMove onMouseUp onOpen onReady onSend onShow onUnFocus