browser-pane

browser-pane Class

Summary

Embeds a pane that can display HTML. Implemented only on Microsoft Windows and Cocoa.

Package

capi

Superclasses

Initargs

`:before-navigate-callback`
	A function that is called before navigating, or `nil`.
`:navigate-complete-callback`
	A function that is called when navigation completes, or `nil`.
`:new-window-callback`
	A function that is called before opening a new window, or `nil`.
`:status-text-change-callback`
	A function that is called when there is a new status text or `nil`.
`:document-complete-callback`
	A function that is called when a document is complete, or `nil`.
`:title-change-callback`
	A function that is called when the title changes, or `nil`.
`:update-commands-callback`
	A function that is called when the enabled status of commands related to the pane may need to change, or `nil`.
`:internet-explorer-callback`
	Microsoft Windows specific: A function that is whenever there is an event from the underlying IWebBrowser2, or `nil`.
`:navigate-error-callback`
	A function that is called when the pane fails to navigate, or `nil`.
`:progress-callback`
`:debug`	A boolean specifying whether debugging mode is on or not.
`:url`	A string specifying the initial URL.

Accessors

browser-pane-navigate-complete-callback
browser-pane-new-window-callback
browser-pane-status-text-change-callback
browser-pane-document-complete-callback
browser-pane-title-change-callback
browser-pane-update-commands-callback
browser-pane-internet-explorer-callback
browser-pane-before-navigate-callback
browser-pane-navigate-error-callback
browser-pane-debug

Readers

browser-pane-url
browser-pane-successful-p
browser-pane-title

Description

An instance of the class browser-pane is a pane that embeds a pane that can display HTML. Navigation in the pane happens either by the user clicking on hyperlinks, or by the application using browser-pane-navigate. The various callbacks gives the program information on what happens in the window and can be used to control (for example, to block or redirect pages).

browser-pane is implemented only on Microsoft Windows (where it embeds an IWebBrowser2) and Cocoa (where it uses WebKit).

The initarg :url specifies the initial URL. After being created, the pane automatically navigates to this URL.

When before-navigate-callback is non-nil, it is called before any navigation (whether programmatic or by the user), and gives the application control over whether to perform the navigation. The callback must have this signature:

before-navigate-callback pane url &key sub-frame-p frame-name &allow-other-keys => do-it

pane is the pane that navigates, and url is a string to which it wants to navigate. sub-frame-p is true when the navigation is for a sub-frame inside the current URL, otherwise sub-frame-p is nil. frame-name is either nil or the name of a sub-frame when the navigation is to a sub-frame.

If before-navigate-callback returns nil, the navigation is canceled.

Note: To perform a redirection, just call browser-pane-navigate to the required URL, and return nil from before-navigate-callback.

If new-window-callback is non-nil, it is called before the pane tries to open a new window. It must have this signature:

new-window-callback pane url &key context flags &allow-other-keys => do-it-p

pane is the pane that wants to open a new window, and url is a string containing the URL that the new window will navigate to. context is a string containing the URL of the page from which the request comes.

flags is implementation-specific flags. On Cocoa flags is always 0. On Microsoft Windows flags contains bits from the NWMF enumeration.

If new-window-callback returns nil, the opening of the new window is canceled. If new-window-callback returns t or is not supplied, it launches a browser using the OS settings.

On Microsoft Windows, new-window-callback is invoked from the "NewWindow3" event (or "NewWindow2" for old versions) of the sink of the underlying IWebBrowser2. If not canceled, the pane opens a new normal Internet Explorer window.

If document-complete-callback is non-nil, it is called when the new document in the pane is complete. It must be a function with signature:

document-complete-callback pane url title =>

url is the loaded URL, and may be nil in the case of failure. title is a string that is associated with the URL url (or the previous URL if the latest call failed).

document-complete-callback is called when, as far as the system is concerned, all the data for the URL has been loaded and is displayed in the pane. There is only one call to document-complete-callback for each navigation of the pane.

If navigate-complete-callback is non-nil, it is called whenever a navigation completes. navigate-complete-callback can be called several times for each navigation of the pane. It must be a function with the signature:

navigate-complete-callback pane url sub-frame-p =>

pane is the pane that is navigated. url is a string to which it navigated, unless the navigation failed, in which case url is nil. sub-frame-p is true when the navigation was in a sub-frame.

Notes: For most purposes the document-complete-callback is more useful than navigate-complete-callback. When navigate-complete-callback gets a nil url, the value of the URL in the pane (that is, what the accessor browser-pane-url returns) is still set to the actual URL. The success flag (which you can read with browser-pane-successful-p) is set to nil.

url can be non-nil even if there was an error in the navigation, if the server supplied another URL. In this case, on Microsoft Windows only, the success flag is set to :redirected. You can read it with browser-pane-successful-p.

If navigate-error-callback is non-nil, it is called when navigation fails for some reason. It should have this signature:

navigate-error-callback pane url &key http-code error-symbol implementation-error-code message frame-name sub-frame-p fatal &allow-other-keys => cancel

pane is the navigating pane, and url is the URL that got the error.

If the failure is server-side failure, then http-code contains the http-code in the response of the server, otherwise (that is, when it failed to connect to a server) it is nil.

error-symbol is a keyword uniquely identifying the error. For an http error it is of the form :HTTP_STATUS*, and for requests with bad syntax error-symbol is :bad-request.

On Microsoft Windows implementation-error-code is the code in the "NavigateError" event. If http-code is non-nil then implementation-error-code and http-code will be the same. On Cocoa implementation-error-code will be the same as http-code in the case of server-side failure, otherwise it is one of the NSURLError* constants.

fatal is a boolean. A true value means that nothing is going to be displayed in the pane to tell the user about the error.

message is a message saying what the error is. sub-frame-p is t when the navigation is for a sub-frame, otherwise nil. frame-name is the name of the frame.

The return value cancel of navigate-error-callback should be one of nil, t, or :stop, with these interpretations:

`nil`	On Microsoft Windows this means displaying either the substitution page from the server if there is one, or displaying automatically generated (by the underlying IWebBrowser2) error page.
`t`	Cancel. On Microsoft Windows this means not displaying the automatically generated error page, but displaying server substitution if there is any.
`:stop`	Stop the navigation immediately.

Note that the effect of the returned value cancel is only on the specific navigation, so it possible for a sub-frame to be stopped, while the main page and maybe other sub-frames complete.

On Cocoa there is no automatically generated error page, so the return value of cancel nil means the same as t, and both display whatever the server returned.

Note: To redirect on error, navigate-error-callback should just call browser-pane-navigate with the new page and return :stop.

If title-change-callback is non-nil, it is called when the title of the pane should change. It should have this signature:

title-change-callback pane new-title

new-title is a string, which the application should use as the title of the pane.

Note: In most cases, using the title argument of the document-complete-callback is more useful.

If status-text-change-callback is non-nil, it is called when the status text of the pane should change. It has this signature:

status-text-change-callback pane new-status-text

new-status-text is a string, which the application should use as the status text for the pane.

If update-commands-callback is non-nil, it is called when other panes (typically buttons or menu items) that are used to perform commands on the pane need to update. The callback has this signature:

update-commands-callback pane what enabled-p

Currently what can be one of:

`:forward`	Other panes that are used to go forward in the pane should be enabled or disabled.
`:backward`	Other panes that are used to go backward in the pane should be enabled or disabled.

Additionally on Microsoft Windows only, what can be:

`t`	Other panes that may try to anything with the pane may need updating. Note that this callback is called quite often with `what` = `t`, so make sure it usually does not do much work in this case.

enabled-p specifies whether the other panes should be enabled or disabled.

On Windows only, if internet-explorer-callback is non-nil, it is called for each event for the pane. It has the signature:

internet-explorer-callback pane event-name args

event-name is a string specifying the event. args is a vector containing the arguments in order. The callback is called before any code that is used to implement the callbacks, which is called afterwards with the same argument vector. That means that the callback should not set anything in the vector, except when debugging.

internet-explorer-callback is intended to add functionality that is not given by the callbacks, and for debugging (but see also :debug). If you need more control, you probably want to define your pane directly: for the basics see:

(example-edit-file "com/ole/html-viewer")

debug specifies that the pane should be in debugging mode. Currently, on Microsoft Windows this means that it prints each event and the arguments that it receives. Whenever an event is sent to the sink associated with the embedded browser, the method name (which is the same as the event name in this case) and the argument are printed to mp:*background-standard-output*. On Cocoa it prints some diagnostics to mp:*background-standard-output*.

browse-pane-url returns the current url of the pane. Initially the value is the keyword :url, but once the browser completed navigation to some URL it is changed to this. Note that the url changes even if the navigation was not successful, as long as it was not stopped or canceled and there was no substitution page.

browse-pane-title returns the title of the current document. Note that during navigation browse-pane-title and browse-pane-url may not be synchronized. They are synchronized when document-complete-callback is called, until the next before-navigate-callback call.

browser-pane-successful-p tests whether the navigation to the current URL completed successfully, returning nil for failure and t for success. On Microsoft Windows only it can also return :substituted, which means that the server returned an error but also supplied a substitution page. On Cocoa, browser-pane-successful-p returns only t or nil.

Notes

browser-pane and related APIs are implemented on Microsoft Windows and Cocoa only. You can test whether it is available by browser-pane-available-p.