gov.nasa.worldwind.util.webview

Interface WebView

All Superinterfaces:

AVList, Disposable

All Known Implementing Classes:

AbstractWebView, MacWebView, WindowsWebView

public interface WebView
extends AVList, Disposable

WebView provides an interface for loading web content, laying out and rendering the content as an OpenGL texture, and interacting with the rendered content. This functionality is divided into four main tasks:

• Loading web content into a WebView's frame.
• Sending input events to the WebView's frame.
• Receiving information about links in the WebView's frame.
• Receiving a rendered representation of the WebView's frame.

A WebView is configured by specifying its text content and the size of the WebView's frame. The text may be an HTML document, an HTML fragment, simple text, null, or another text format supported by the implementation. The size of the WebView's frame is specified in pixels, and may not exceed an implementation-defined maximum. Most implementations define the maximum value to be 4096 - the maximum texture size on most platforms.

The user can interact with the WebView using the mouse and keyboard. The application must send input events to the WebView's frame because WebView is not associated with any windowing system. Input events are received and processed in an implementation-defined manner. Applications can suppress WebView navigation by drawing the link rectangles during the picking phase, and consuming link clicked SelectEvents before they are sent to the WebView.

The WebView provides a representation of itself as an OpenGL texture. On machines that support non-power-of-two sized textures, this texture has dimensions equal to the WebView's frame size. Otherwise, the texture's dimensions are the smallest power-of-two that captures the WebView's frame size. The WebView's texture representation is standard two-dimensional OpenGL texture that may be mapped onto any OpenGL primitive using texture coordinates.

When the WebView's texture representation changes as a result of an internal event it fires a property change event with the key AVKey.REPAINT. This can happen from web content loading, user interaction, or from a programmatic change such as JavaScript.

Method Summary

Modifier and Type	Method and Description
Color	getBackgroundColor() Indicates the current WebView background color.
Dimension	getContentSize() Returns the size in pixels of this WebView's current content.
URL	getContentURL() Returns the URL of this WebView's current content, or null if the current content is the HTML string specified by setHTMLString.
Dimension	getFrameSize() Returns the size in pixels of this WebView's frame.
Iterable<AVList>	getLinks() Returns an iterable of AVList elements describing this WebView's visible links.
Dimension	getMinContentSize() Returns the minimum size in pixels of this WebView's content area.
WWTexture	getTextureRepresentation(DrawContext dc) Returns a layed out and rendered representation of the WebView's content as a WWTexture.
void	goBack() Navigate the WebView to the previous page in the browsing history.
void	goForward() Navigate the WebView to the next page in the browsing history.
boolean	isActive() Indicates whether or not this WebView is active.
void	sendEvent(InputEvent event) Sends the specified input event to the WebView.
void	setActive(boolean active) Called when this WebView is activated or deactivated.
void	setBackgroundColor(Color color) Specifies a background color for the WebView.
void	setFrameSize(Dimension size) Specifies the size in pixels of this WebView's frame.
void	setHTMLString(String htmlString) Specifies this WebView's HTML content as a string.
void	setHTMLString(String htmlString, URL baseURL) Specifies this WebView's HTML content as a string.
void	setHTMLString(String htmlString, WebResourceResolver resourceResolver) Specifies this WebView's HTML content as a string.
void	setMinContentSize(Dimension size) Specifies the minimum size in pixels of this WebView content area.

Methods inherited from interface gov.nasa.worldwind.avlist.AVList

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getEntries, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from interface gov.nasa.worldwind.Disposable

dispose

Method Detail

getBackgroundColor

Color getBackgroundColor()

Indicates the current WebView background color. Implementations are not required to support setting the background color.

Returns:

the color applied to the WebView background, or null if no color has been set.

getContentSize

Dimension getContentSize()

Returns the size in pixels of this WebView's current content. This returns null if the size of this WebView's current content is unknown, either because it has not finished loading or because its size cannot be determined. This WebView attempts to determine its current content's size each time an HTML frame is loaded and its layout is performed. If the content is plain text or has no HTML frames, this WebView determines its content size after the text is loaded.

The returned size changes as this WebView navigates to new content or navigates within its history, and always reflects the size of the current content. The returned size is limited by this WebView's minimum content size. See getMinContentSize() for more information on how the minimum content size is used.

Returns:

the size of this WebView's content limited by the minContentSize, or null if this WebView's content size is unknown.

See Also:

getMinContentSize()

getContentURL

URL getContentURL()

Returns the URL of this WebView's current content, or null if the current content is the HTML string specified by setHTMLString. The returned URL changes as this WebView navigates to new content or navigates within its history, and always reflects the URL of the current content.

Returns:

the URL of this WebView's current content, or null if the current content is the HTML string specified by setHTMLString.

getFrameSize

Dimension getFrameSize()

Returns the size in pixels of this WebView's frame. This returns null if this WebView's frame size is unspecified.

Returns:

the size of this WebView's frame in pixels, or null if it's unspecified.

See Also:

setFrameSize(java.awt.Dimension)

getLinks

Iterable<AVList> getLinks()

Returns an iterable of AVList elements describing this WebView's visible links. The returned iterable has no elements if this WebView has no links, or if none of the links are currently in the WebView's visible area. Each AVList describes the parameters for one link as follows:

• AVKey.URL - a String containing the link's destination.
• AVKey.MIME_TYPE - a String mime type describing the content type of the link's destination.
• AVKey.TARGET - the link's target frame, one of the following: _blank, _self, _parent, _top. See the W3C documentation on frame target names.
• AVKey.BOUNDS - a java.awt.Rectangle representing the link's bounding rectangle.
• AVKey.RECTANGLES - an array of one or more java.awt.Rectangle instances representing the link's separate pickable rectangles.

The link rectangles are in the WebView's local coordinate system, and are clipped to the WebView's visible area. The WebView's coordinate system has its origin in the lower left corner with the X-axis pointing right and the Y-axis pointing up. Multi-line links are represented as one AVList with multiple pickable rectangles.

Returns:

an Iterable of AVList parameters describing this WebView's visible links.

getMinContentSize

Dimension getMinContentSize()

Returns the minimum size in pixels of this WebView's content area.

HTML content can expand to fit its frame, so it is impossible to determine the size of content without laying out the content in a frame of some size. The minimum content size determines the size of the frame used to compute the content layout and size. If the content is simple text, the text will wrap to the minimum content width.

Returns:

The minimum size of the WebView content area.

getTextureRepresentation

WWTexture getTextureRepresentation(DrawContext dc)

Returns a layed out and rendered representation of the WebView's content as a WWTexture. The texture's image source is the WebView, and its dimensions are large enough to capture the WebView's frame size (see setFrameSize(java.awt.Dimension).

On machines that support non-power-of-two sized textures, the texture's dimensions are always equal to the WebView's frame size. Otherwise, the texture's dimensions are the smallest power-of-two that captures the WebView's frame size.

Parameters:

dc - The draw context the WebView is associated with.

Returns:

a rendered representation of the WebView's frame as a WWTexture.

goBack

void goBack()

Navigate the WebView to the previous page in the browsing history. Has no effect if there is no previous page.

goForward

void goForward()

Navigate the WebView to the next page in the browsing history. Has no effect if there is no next page.

isActive

boolean isActive()

Indicates whether or not this WebView is active. The WebView only receives input events when it is active.

Returns:

true if this WebView is active, false if not.

sendEvent

void sendEvent(InputEvent event)

Sends the specified input event to the WebView. Which events the WebView's responds to and how it responds is implementation-defined. Typical implementations respond to KeyEvent, MouseEvent, and MouseWheelEvent.

The screen coordinates for a MouseEvent must be transformed into the WebView's local coordinate system, which has its origin in the lower left corner with the X-axis pointing right and the Y-axis pointing up.

This does nothing if the specified event is null.

Users of the WebView must call setActive(boolean) before sending input events to the WebView. The WebView can be activated and deactivated any number of times. For example, a controller might call setActive(true) when the mouse enters the WebView texture, and call setActive(false) when the mouse exits the texture.

Parameters:

event - the event to send.

See Also:

setActive(boolean)

setActive

void setActive(boolean active)

Called when this WebView is activated or deactivated. The WebView only receives input events when it is active.

Parameters:

active - true if this WebView is being activated. false if this WebView is being deactivated.

See Also:

sendEvent(java.awt.event.InputEvent)

setBackgroundColor

void setBackgroundColor(Color color)

Specifies a background color for the WebView. Implementations are not required to support setting the background color. Implementations that do not support setting the background color may simply ignore attempts to set the color.

Parameters:

color - Color to apply to the background.

setFrameSize

void setFrameSize(Dimension size)

Specifies the size in pixels of this WebView's frame.

Parameters:

size - the size of this WebView's frame in pixels.

Throws:

IllegalArgumentException - if size is null, if the width or height are less than one, or if the width or height exceed the implementation-defined maximum.

setHTMLString

void setHTMLString(String htmlString)

Specifies this WebView's HTML content as a string. The specified htmlString may be one of the following:

• HTML document
• HTML fragment
• Simple text
• null

The WebView displays nothing if htmlString is null or empty. If the htmlString contains relative paths, they are not resolved and are interpreted as unresolved references.

If the application sends input events to the WebView, the user may navigate away from the specified HTML content by interacting with links or buttons in the content.

Parameters:

htmlString - the WebView's HTML text content, or null to display an empty WebView.

setHTMLString

void setHTMLString(String htmlString,
                   URL baseURL)

Specifies this WebView's HTML content as a string. The specified htmlString may be one of the following:

• HTML document
• HTML fragment
• Simple text
• null

The WebView displays nothing if htmlString is null or empty. The baseURL is used to resolve relative paths in the specified htmlString. If the baseURL is null, relative paths are not resolved and are interpreted as unresolved references.

If the application sends input events to the WebView, the user may navigate away from the specified HTML content by interacting with links or buttons in the content. Once the user navigates away from the content specified here, the htmlString and baseURL are no longer used.

Parameters:

htmlString - the WebView's HTML text content, or null to display an empty WebView.

baseURL - the URL used to resolve relative paths in the htmlString, or null to indicate that relative paths should be interpreted as unresolved references.

setHTMLString

void setHTMLString(String htmlString,
                   WebResourceResolver resourceResolver)

Specifies this WebView's HTML content as a string. The specified htmlString may be one of the following:

• HTML document
• HTML fragment
• Simple text
• null

The WebView displays nothing if htmlString is null or empty. The WebResourceResolver is used to resolve relative paths in the specified htmlString. If the WebResourceResolver is null, relative paths are not resolved and are interpreted as unresolved references.

If the application sends input events to the WebView, the user may navigate away from the specified HTML content by interacting with links or buttons in the content. Once the user navigates away from the content specified here, the htmlString and resourceResolver are no longer used.

Parameters:

htmlString - the WebView's HTML text content, or null to display an empty WebView.

resourceResolver - the WebResourceResolver used to resolve relative paths in the htmlString, or null to indicate that relative paths should be interpreted as unresolved references.

setMinContentSize

void setMinContentSize(Dimension size)

Specifies the minimum size in pixels of this WebView content area. See getMinContentSize() for more information on how this value is interpreted.

Parameters:

size - Minimum size of the WebView content area.