Working with Property Change Events

Property change events notify your application of state changes within viewports. Your application can register a listener with the StormBase object to receive the events from specific viewports.

If not otherwise specified, the source is the ice.storm.Viewport, the oldValue is null, and the newValue is a String.

The most common events, as used by the HTML 4 pilot, are shown in the following table. Events specific to other pilots are described in the relevant sections in Pilots.


Event	Values	Definition
contentLoading	request, connect, begin, end, error, stop	Indicates the status of the content loading process after the pilot is loaded. The application can listen to this event to get notification when the content loading is complete. For the HTML 4 pilot, the value `end' means the DOM is built. All events except `stop' and `error' have an ice.storm.ContentLoader as oldValue. The ContentLoader objects can be queried for the java.net.URL, which is the requested location that has been loaded. The `error' event sends an Exception object. For an example, see Working with Headers.
contentLoadingProgress	String	Indicates how much of the document has been loaded. It consists of a string in three parts, separated by spaces. The first substring is the name of the file that is being loaded. The second is the number of bytes read so far, and the third is the total number of bytes, or the size of the document. If the total size is unknown, the third substring is "-1". When an HTML document is loaded, this event will have an ice.pilots.html4.ProgressDetail as its oldValue.
contentRendering	begin, end, finished	Multiple threads are used to load content. Each thread fires both `begin' and `end' events for contentRendering. The `finished' event is sent when all the threads are finished rendering. For example, to determine the time at which HTML 4 content is fully loaded and displayed, the application should first listen to the contentLoading event. After it receives contentLoading, end, it should wait until it gets contentRendering, finished, followed by an oustandingImages, 0 event. This means the layout of all the loaded content is complete. For non-HTML content, it is enough to wait for the contentLoading, end event.
contentSelection	defined, cleared	The event contentSelection, defined is fired by a viewport when a content selection range has been defined in the viewport (that is, text or images have been selected). The event contentSelection, cleared is fired by a viewport when a previously defined content selection range has been cleared (that is, text or images have been unselected).
history	modified	Indicates that history has been modified. For example, when this event is received you could call the canGoBack( ) and canGoForward( ) ice.storm.HistoryManager methods to determine whether back/forward controls should be enabled. For more information, see Adding Navigation.
location	String	Indicates that the location (URL) of the content that a viewport is displaying has changed. This is useful for updating location fields in the browser. The value is a string showing the URL of the currently displayed document.
nameChange	String	Fired when the setViewportName method is called to change the name of the viewport. The oldValue is the old viewport name and the newValue is the new viewport name.
outstandingImages	String	Specifies the number of images left to load and display. Due to the multi-threaded, asynchronous nature of the content loading process, it is possible for more than one outstandingImages=0 event to be generated during the loading of a single document. This could happen, for example, if an image has been completely loaded before the entire HTML document has been parsed, because another image tag may be encountered after all the previous images have been loaded. The event is fired when an image starts to load, at intervals as the image is loading, after contentRendering, finished is fired, and when an image is loaded. The URL is supplied as the oldValue in the last case only. Otherwise, oldValue is null.
pilotLoading	begin, end, error	This is useful for detecting when a pilot of a specific type has been loaded so that configuration changes can be made or event listeners can be registered with the pilot. For an example of registering event listeners with the HTML 4 pilot, see Step 5 - DOM Events of the tutorial.
statusLine	String	Fired when there is information to display on the status line. The value is a string containing the new text to be displayed on the status line.
title	String	Fired when there is an updated title for a viewport. The value is a string containing the title of the new document. This is useful for displaying the title of a document on the window title bar of the application, for example.
viewport	ready, childrenReady, activated, deactivated	ready or childrenReady is fired when the top-level viewport or child viewports are ready to be used. activated or deactivated is fired when a viewport's state changes.

Property Constants

The ice.util.PropertyConstants class contains the string constants for all the property change events. Use these constants when referring to the values of property change events.

For an example of using PropertyConstants in a PropertyChangeEvent listener, see Step 2 - Property Change Events of the tutorial.

Determining When Rendering Is Complete

In some situations an application may need to know when content is loaded and rendered. You can use the PropertyChangeEvent callback to determine this.

For basic cases using the HTML 4 pilot, such as on a page with no frames or other embedded content types (applets, for example), you can determine when rendering is complete by listening for the CONTENT_RENDERING=FINISHED event followed by an OUTSTANDING_IMAGES=0 event.

Note, however, that dynamic changes to the page can occur (with JavaScript, for example) after you receive notification that the page has completed, and this does not take into account the time required to paint the rendered page to the screen.

On a page that contains multiple frames or other embedded pilots, the process is more complex. In these cases, you need to track the rendering status of the top-level Viewport and all its descendants. For framesets, you need to track the rendering status of a collection of Viewports, each bound to an HTML 4 pilot.

For other pilots, it is usually sufficient to wait only for the contentLoading, end event, which signals that all of the content has been loaded. However, some other pilots provide additional PropertyChangeEvent types that are useful in determining when the pilot has completed loading and displaying its content. For more information, see the specific pilot in Pilots.