New Layout: WebWidget

The WebWidget API allows application developers to reuse the functionality of the NGLayout html layout and rendering engine. The API is divided into two main interfaces, IWebWidget which is responsible for the actual layout/rendering of documents, and IWebWidgetState which maintains state and preferences shared among multiple IWebWidgets. an IWebWidget plus some added chrome could produce a web browser, and there could be multiple browsers running on a single machine, each using the shared services provided by a single IWebWidgetState. In addition, there are IWebWidgetListener and IWebWidgetStateListener interfaces to allow implementors to receive event notifications.

It is assumed that implementors will provide a DOM (Document Object Model). A DOM document can be obtained from IWebWidget. The DOM API is not specified in this API.

This API is hopefully a refinement of the combination of Microsoft's WebBrowserControl (aka Trident) and Sun's Hot Java Browser Components plus Navigator 4.0 functionality added in. Sun's API defines an Authenticator Bean for talking to secure servers, but its functionality is not included in this API.

Major Components

WebWidgetAPI
This interface specifies functionality for the parsing, layout, and rendering of html documents. An Instance of this interface would likely service a single instance of a web browser application and would interact heavily with a IWebWidgetState for user preferences and state. The major activities of an instance can be monitored by implementing the IWebWidgetListener interface. Below is a summary of the methods.


addWebWidgetListener	add a listener to receive events
find	search the current page for a text string
getDoc	get the current DOM document
getDocURL	get the current page as a URL
getDocSource	get the hmtl associated with the current page
getDocTitle	get the title of the current page. This is a convience method.
getErrorMessage	get the last error message
getFrames	get a list of framesets in the current page This is a convience method.
getLoadingProgress	get the loading status of the current page
getSelection	get the current user selection
getStatusMessage	get the text of the current status message
goBack	go to the previous page if any
goForward	go to the next page if any
loadDoc	start loading a new page
print	submit a print job comprising the current page
reloadDoc	reload the current page, optionally ignoring the cache
removeWebWidgetListener	remove a listener
setStatusMessage	change the text of the status message
stopLoadingDoc	stop loading and/or laying out the current page

IWebWidgetListener

This interface allows other classes to receive events that IWebWidget generates. For simplicty, there is a single interface for all events, and a refinement would be to have multiple listeners (e.g. loading, mouse activiy) instead. Below is a summary of the methods.


error	called after an error occurs
loadRequest	called before a page is going to be loaded; the caller can cancel the request
loadBegin	called after loadRequest and when a page starts loading
loadComplete	called after a page completes loading, was stopped, or failed
loadProgress	called after the status of a page load changes
mouseDownAnchor	called when the mouse is pressed over an anchor
mouseOverAnchor	called when the mouse moves over an anchor
selectionChange	called after the selection changes
statusTextChange	called after the status text changes
titleChange	called after the title of a page changes, possibly before it's available through the DOM

IWebWidgetState

This interface provides the bookeeping of system and user properties, preferences, history, bookmarks, etc. An instance of this interface would likely service one or more instances of IWebWidget. The major activity of an IWebWidgetState can be monitored by implementing the IWebWidgetStateListener interface. Below is a summary of the methods.


addWebWidgetStateListener	add a listener to receive events
clearCache	clear the memory and/or disk cache
getSystemProperties	get the system wide properties governing user interface appearance, history parameters, etc
getUserCookies	get the cookies for a user
getUserBookmarks	get the bookmarks for a user
getUserHistory	get the history of visited URLs for a user
getUserProperties	get the user properties; initially a user's properties are the same as the system properties
removeWebWidgetStateListener	remove a listener
setSystemProperties	set the system wide properties governing user interface appearance, history parameters, etc
setUserCookies	set the cookies for a user
setUserBookmarks	set the bookmarks for a user
setUserHistory	set the history of visited URLs for a user; this can also be used to clear the history
setUserProperties	set the user properties

Below is a summary of the properties which can be accessed and/or set on a IWebWidgetState.


altTextColor	the color for alternate text
backgroundColor	the backstop background color
backstopOverride	if true the backstop colors, fonts, etc override those specified in the document
cacheFolder	the location of the disk cache
cacheResynch	the frequency at which the cache is compared to the network for a given page
cacheSizeDisk	the size in KB of the disk cache
cacheSizeMemory	the size in KB of the memory cache
characterSet	the character set to be used
cursorColor	the color of the cursor
cookieAcceptance	specifies which cookies to accept (all, none, those from originating server)
cookieWarning	if true, warn before accepting a cookie
delayAppletLoading	if true an applet will not be loaded until an image in its place is clicked
enableAnimation	if true, animated gifs will be operational
enableAutoInstall	if true, enable automatic updates to the browser
enableBackgroundImages	if true background images will be displayed
enableImages	if true images will be loaded
enableJava	if true, enable the java subsystem (and applets)
enableJavascript	if true, enable the javascript subsystem
enableStyleSheets	if true, enable CSS style sheets
historyExpiration	history entries are expunged after this many hours
proxyExclusions	list of domain prefixes to exclude from proxies
ftpProxyHost	the hostname of the ftp proxy if any
ftpProxyPort	the port number of the ftp proxy
gohperProxyHost	the hostname of the gohper proxy if any
gopherProxyPort	the port number of the gohper proxy
headingFont	the backstop font to use for headings
headingFontSizes	the backstop font sizes to user for headings
homePage	the URL string of the home page
httpProxyHost	the hostname of the http proxy if any
httpProxyPort	the port number of the http proxy
lastVistedPage	the URL string of the last visited page
linkColors	the colors of visited and unvisted links
linkUnderline	if true links will be underlined
searchPage	the URL string of the default search page
securityProxyHost	the hostname of the Security proxy if any
securityProxyPort	the port number of the Security proxy
socksProxyHost	the hostname of the Socks proxy if any
socksProxyPort	the port number of the Socks proxy
startPage	the page from which to start a session (blank, home, last visited)
textColor	the backstop text color to use for paragraphs
textFont	the backstop font to use for paragraphs
textFontSize	the backstop font size to use for paragraphs
waisProxyHost	the hostname of the WAIS proxy if any
waisProxyPort	the hostname of the WAIS proxy if any

IWebWidgetStateListener

This interface allows other classes to receive events that IWebWidgetState generates. For simplicity, all of the events are handled by a single interface, and a possible refinement would be to have multiple interfaces (e.g. properties, bookmarks) instead. Below is a summary of the methods.


userBookmarkChange	called after a change has been made to a user's bookmarks
userHistoryChange	called after a change has been made to a user's history
userPropertyChange	called after a change has been made to a user's properties