Setting Up the Viewport

Setting Up the Viewport

A viewport is a container for a document. A viewport is not a graphical component, but contains references to a pilot that can render the content type of the document and to the graphical container into which the pilot renders the content.

Viewports can be composite in nature and contain references to other viewports. For example, a viewport containing the HTML 4 pilot is often a composite viewport that contains references to other viewports for rendering other content types, such as applets, MathML equations, SVG diagrams, or even other HTML documents (when a FRAMESET is specified).

A ViewportCallback can be registered with a viewport to receive notifications that a viewport container needs to be created or destroyed, such as when a new HTML document window is opened or closed. It also provides an API for displaying GUI toolkit-independent dialogs in cases where that is the desired behavior of the application.

This line provides the StormBase with a ViewportCallback:
stormBase.setViewportCallback(new MyCallback( ));
 
For an example ViewportCallback class implementation, see Step 1 - Basics of the tutorial.

Accessing a Pilot

After content is rendered in a viewport, you can access the pilot object that does the rendering.

To access a pilot in a viewport with a given name, add code similar to the following:
Viewport view = base.findViewportByName(viewportName);

if (view!=null) /* found a valid viewport */

Pilot p = view.getPilot( );

if (p==null) /* no pilot in the viewport */
 
Note: Avoid storing references to viewports for long periods of time, as a viewport object can be replaced by another viewport object with the same name during viewport configuration. Instead, storing viewport names is recommended.

Next, cast the pilot object into its actual pilot class subtype. For example, you can cast the HTML 4 pilot to ice.pilots.html4.ThePilot. Then you can use public methods of the pilot as shown in the following example:
if (p instanceof ice.pilots.html4.ThePilot)

// Get DOM Document object from HTML 4 pilot

org.w3c.dom.Document doc = 
((ice.pilots.html4.ThePilot)p).getDocument( );
 
See the example files Domdemo.java and Domdemo3.java for more information on accessing a pilot, casting the pilot into a specific pilot, and accessing the methods. These examples are described in DOM Usage Examples.