During the lifecycle of HTMLComponent there are many events that the developer can respond to. Developers should implement the HTMLCallback interface and set it to the HTMLComponent.
The html package provides a default implementation of the HTMLCallback named DefaultHTMLCallback. This implementation does not do too much, but it does demonstrate how to implement the interface methods without harming HTMLComponent tasks (as there are several potential pitfalls). The methods are parsingError, pageStatusChanged, titleUpdated, linkClicked, getLinkProperties, and auto complete.
This method is called whenever the internal parser encounters an error during the document's parsing. This can occur while processing the main HTML document or its referenced CSS files.
You must return a boolean value denoting whether to continue the document processing despite the error (true) or to stop processing (false).
Detailed information on the error can be found in the parameters the method passes, especially errorId which holds the error code (one of the ERROR_* constants).
This method notifies of changes in the page loading lifecycle. pageStatusChanged can help you display status information to the user or to delay to certain statuses for certain flows.
A new HTMLComponent starts as STATUS_NONE. Shortly after a page URL is set it becomes STATUS_REQUESTED. After a successful connection to the input stream it changes to STATUS_CONNECTED. When the page is displayed (and this can be before images have been completely loaded), the status changes to STATUS_DISPLAYED, and finally after all resources have been fully loaded the status becomes STATUS_COMPLETED.
If an error is encountered during the page loading, for example an unrecoverable parsing error, then the status is STATUS_ERROR. If the page loading was cancelled, the status becomes STATUS_CANCELLED.
A useful event that is called after the document's title has been extracted from the TITLE tag of the HTML document.
Called whenever a link is clicked to allow alternative or additional handling. Usually, when a link is clicked, the link is simply followed through, but in some cases you might want to take additional actions. For example, some updates to the UI outside the HTMLComponent.
The return value should be true if the regular link processing should proceed, and false if it should not.
This method is used to support Visited and Forbidden links.
Visited Links: Most browsers mark visited links in different colors. HTMLComponent does not have any info on which links have been visited before, but getLinkProperties can help hook it to any implementation that tracks links, returning LINK_VISITED for visited links. (See LWUITBrowser for an example.)
Forbidden Links: Sometimes you may want to disallow the use of some links. A common use case may be restricting the user from accessing links outside a defined domain. Another may be blocking content types that HTMLComponent can not render. When getLinkProperties is called, the implementation can look at the URL and determine whether it returns LINK_REGULAR which enables the link, or LINK_FORBIDDEN which disables it.
The fieldSubmitted and getAutoComplete methods support an auto complete implementation.
fieldSubmitted is called whenever a field in an HTML form is submitted. In return, the implementation should return the actual field value to send to the form. This can be used to perform some content filtering, if needed. When none is needed, the value should be returned as is. However, you get the chance to store the field value along with its name, the form URL, etc.
Data collected with fieldSubmitted can be used to populate form fields with getAutoComplete, which is called while constructing forms to obtain values for the various fields. Returning null simply means that users must fill out the form themselves. You can also supply another value that is appropriate for the form's specific field — for example, from a repository of stored values as recorded by fieldSubmitted.