## 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)`