calpa.html
Interface CalHTMLObserver

All Known Implementing Classes:

DefaultCalHTMLObserver

public abstract interface CalHTMLObserver

A class implementing this interface can be passed to a CalHTMLPane at construction time and will thereafter receive notification of events which have occured within the Pane. A CalHTMLPane always has one, and only one, attached CalHTMLObserver.

If a CalHTMLObserver is not passed to the Pane during construction, a DefaultCalHTMLObserver will be used. DefaultCalHTMLObserver implements all the methods of this interface as null-ops, allowing the programmer to extend the class and only implement those methods of interest.

Note that the same CalHTMLObserver may be used with several CalHTMLPanes.

See Also:

CalHTMLPane

Method Summary

void	formSubmitUpdate(CalHTMLPane pane, java.net.URL docBaseURL, int method, java.lang.String action, java.lang.String data) Notification that a form submission has been initiated.
void	historyUpdate(CalHTMLPane pane, int position) Notification of a change in position within the Pane's document history.
void	linkActivatedUpdate(CalHTMLPane pane, java.net.URL url, java.lang.String targetFrame, java.lang.String jname) Notification that a hyperlink has been activated via the keyboard or mouse.
void	linkFocusedUpdate(CalHTMLPane pane, java.net.URL url) Notification that a hyperlink has received or lost keyboard/mouse focus.
void	showNewFrameRequest(CalHTMLPane pane, java.lang.String targetFrame, java.net.URL url) Notification for a new CalHTMLPane to be created with the specified top-level frame name and showing the specified document.
void	statusUpdate(CalHTMLPane pane, int status, java.net.URL url, int value, java.lang.String message) Gives general notifications of events or errors which are occuring within the Pane.

Method Detail

linkActivatedUpdate

public void linkActivatedUpdate(CalHTMLPane pane,
                                java.net.URL url,
                                java.lang.String targetFrame,
                                java.lang.String jname)

Notification that a hyperlink has been activated via the keyboard or mouse. If the jname argument is null the link will be automatically followed by the calling Pane, unless the URL protocol is 'mailto', which the Pane cannot currently handle. If the jname argument is not null the pane will not attempt to follow the link, allowing it to be handled here.

Parameters:

pane - the CalHTMLPane which has called this method

url - the URL of the link that has been activated

targetFrame - the name of the frame where the contents of the URL are to be displayed

jname - A name given to the link so it can be handled outside the calling Pane

linkFocusedUpdate

public void linkFocusedUpdate(CalHTMLPane pane,
                              java.net.URL url)

Notification that a hyperlink has received or lost keyboard/mouse focus. This method is called when there has been a change in focus. If the URL sent is not null then a new link has now received focus. If the URL is null then a link which previously had focus has now lost it, and no link is currently focused.

This method can be used, for example, to update a status display which shows the currently focused link on the user's screen.

Parameters:

pane - the CalHTMLPane which has called this method

url - the URL of the focused link, or null if no link has the focus

statusUpdate

public void statusUpdate(CalHTMLPane pane,
                         int status,
                         java.net.URL url,
                         int value,
                         java.lang.String message)

Gives general notifications of events or errors which are occuring within the Pane. Apart from the DOC_LENGTH status argument listed below, the value argument sent will be the nesting level of the frame initiating this call. A nesting of 0 indicates the Pane's top level frame has made the call. Often you will only be interested in calls from the top level frame. For example, if a frameset document is loading you may get the DOC_LOADED status call several times, but the one that really counts is the frame 0 call, and this is never sent until all sub-frames have finished loading.

The current status arguments sent to this method are:

• CalCons.PRE_CONNECT
  The Pane is attempting to connect to the given URL to receive data.
• CalCons.PARSE_FAILED
  The Pane was unable to connect to the given URL or was unable to parse the content. Most likely this will be due to an incorrectly specified URL. The message argument may contain further details of the reason for failure.
• CalCons.CONNECTED
  The Pane has established a connection to the given URL and is receiving any content.
• CalCons.DOC_LENGTH
  The size of the content at the given URL is known and is contained in the value argument.
• CalCons.TITLE
  The title of the document for the given URL is known and is contained in the message argument. Only the title of a document in the Pane's top level frame will be sent to this method. If the document has no name, the message will be null, unless the document is a Frameset document in which case the message "Frameset" will be sent.
• CalCons.PARSE_FAILED_POST_CONNECT
  An exception has been thrown during parsing of the data from the URL. This will most likely be an IOException such as a server time-out.
• CalCons.WAITING_FOR_IMAGES
  The document has been parsed but formatting cannot be completed because the document contains images of unspecified size. The parsing thread is waiting for image updates to give it the information it needs to format and display the document.
• CalCons.DOC_LOADED
  All text and image data has been received, parsed and the document structure determined.

Parameters:

pane - the CalHTMLPane which has called this method

status - the status code of the update

url - a URL related to the status code

value - a value related to the status code

message - a message related to the status code

formSubmitUpdate

public void formSubmitUpdate(CalHTMLPane pane,
                             java.net.URL docBaseURL,
                             int method,
                             java.lang.String action,
                             java.lang.String data)

Notification that a form submission has been initiated. Whether the Pane handles the submission directly depends on whether handleFormSubmission is enabled or disabled by the CalHTMLPreferences object controlling the Pane.

The method argument will be either CalCons.V_GET, CalCons.V_POST, or CalCons.V_JFORM
If the argument is V_JFORM then the Pane will take no action, irrespective of whether handleFormSubmission is enabled. This allows the programmer to treat this method as a pseudo actionListener for controls placed within documents.

The data argument sent to this method is an x-www-form-urlencoded concatenated string of the form results gathered from successful form controls.

Parameters:

pane - the CalHTMLPane which has called this method

docBaseURL - the URL of the document containing the form, possibly modified by the <BASE> tag

method - a code for the form method - GET, POST or JFORM

action - the value of the action attribute (if any) specified in the FORM tag

data - the concatenated, encoded form results

See Also:

CalHTMLPreferences.setHandleFormSubmission(boolean)

historyUpdate

public void historyUpdate(CalHTMLPane pane,
                          int position)

Notification of a change in position within the Pane's document history. This method's primary purpose is to allow the programmer to enable/disable controls which navigate the Pane's history. Note that it is possible for the Pane to be simultaneously at the top and bottom of its history (when the Pane has only shown a single document for example). It's easiest to show how you might use this method with some simple pseudo-code:

if (position == CalCons.AT_HISTORY_MIDDLE) {
//...enable both the 'back' and 'forward' buttons
} else {
if ((position & CalCons.AT_HISTORY_TOP) > 0) {
//...disable the 'forward' button
} else {
//...enable the 'forward' button
}
if ((position & CalCons.AT_HISTORY_BOTTOM) > 0) {
//...disable the 'back' button
} else {
//...enable the 'back' button
}
}

Parameters:

pane - the CalHTMLPane which has called this method

position - a value denoting the current position within the Pane's history

showNewFrameRequest

public void showNewFrameRequest(CalHTMLPane pane,
                                java.lang.String targetFrame,
                                java.net.URL url)

Notification for a new CalHTMLPane to be created with the specified top-level frame name and showing the specified document.

This method will be only be called if handleNewFrames is disabled in the CalHTMLPreferences object controlling the Pane. The need for a new frame occurs when an HTML anchor or other tag specifies that a URL should be displayed in a frame which has a name unknown to the Pane, or when the reserved HTML name "_blank" is specified.

Parameters:

pane - the CalHTMLPane which has called this method

targetFrame - the name to be given to the top-level frame of the new Pane, or null if no name has been specified

url - the URL of the document to be displayed in the new Pane

See Also:

CalHTMLPreferences.setHandleNewFrames(boolean)