gov.nasa.worldwind.util.webview
Class WindowsWebView

java.lang.Object
  gov.nasa.worldwind.avlist.AVListImpl
      gov.nasa.worldwind.WWObjectImpl
          gov.nasa.worldwind.util.webview.AbstractWebView
              gov.nasa.worldwind.util.webview.WindowsWebView

All Implemented Interfaces:

AVList, Disposable, MessageListener, WebView, WWObject, PropertyChangeListener, EventListener

public class WindowsWebView
extends AbstractWebView

WebView implementation for Windows. This implementation uses the Window's native web browser control and the MSHTML library to render a web page and create an OpenGL texture from the web browser window.

Limits on the number of WebViews that can be created

WindowsWebView creates a hidden native window. Creating the native window can fail if the process runs out of Windows user object handles. Other GUI elements in an application also consume these handles, so it is difficult to put a firm limit on how many WebViews can be created. An application that creates only WebViews and no other windows can create about 1500 WebViews before running out of handles. See MSDN for more information on User Objects and operating system limits.

Nested Class Summary

protected class

WindowsWebView.WindowsWebViewTexture

Field Summary

protected Color	backgroundColor
protected boolean	disposed Flag to the indicate that the WebView has been disposed.
protected static AtomicInteger	instances Count of the number of active (non-disposed) WebView instances.
protected long	observerPtr The address of the native NotificationAdapter object.
protected static long	webViewMessageLoop Identifier for the message loop in native code.
protected static Thread	webViewUI Thread to run web view message loop.
protected static Object	webViewUILock Lock to protect creation of the web view message loop thread.
protected long	webViewWindowPtr The address of the native WindowsWebView object.

Fields inherited from class gov.nasa.worldwind.util.webview.AbstractWebView

active, frameSize, textureRep

Constructor Summary

WindowsWebView(Dimension frameSize)
Create a new WebView.

Method Summary

protected MouseEvent	convertToWindows(MouseEvent e) Converts the specified mouse event's screen point from WebView coordinates to Windows coordinates, and returns a new event who's screen point is in Windows coordinates, with the origin at the upper left corner of the WebView window.
protected WWTexture	createTextureRepresentation(DrawContext dc) Create a texture representation of the WebView.
void	dispose() Disposes of any internal resources allocated by the object.
protected void	doSetFrameSize(Dimension size)
protected void	ensureMessageLoopRunning() Ensure that the message loop thread is running.
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.
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.
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.
protected void	handleWebViewCreationError() This method is called by the constructor if an exception is thrown creating the WebView.
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	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.
protected void	stopMessageLoopIfNoInstances() Terminate the message loop thread if there are no active (non-disposed) WebView instances.

Methods inherited from class gov.nasa.worldwind.util.webview.AbstractWebView

finalize, getFrameSize, getTextureRepresentation, isActive, propertyChange, setFrameSize

Methods inherited from class gov.nasa.worldwind.WWObjectImpl

onMessage

Methods inherited from class gov.nasa.worldwind.avlist.AVListImpl

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getBooleanValue, getBooleanValue, getChangeSupport, getDoubleValue, getDoubleValue, getEntries, getIntegerValue, getIntegerValue, getLongValue, getLongValue, getRestorableStateForAVPair, getStringValue, getStringValue, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Field Detail

backgroundColor

protected Color backgroundColor

disposed

protected boolean disposed

Flag to the indicate that the WebView has been disposed.

instances

protected static AtomicInteger instances

Count of the number of active (non-disposed) WebView instances. The WebView UI thread is started when a WebView is created (if it's not already running), and terminated when there are no active instances.

observerPtr

protected long observerPtr

The address of the native NotificationAdapter object. Initialized during construction.

webViewMessageLoop

protected static long webViewMessageLoop

Identifier for the message loop in native code.

webViewUI

protected static Thread webViewUI

Thread to run web view message loop. At most one message loop thread is running at any time, and it is shared by all WebView instances.

webViewUILock

protected static final Object webViewUILock

Lock to protect creation of the web view message loop thread.

webViewWindowPtr

protected long webViewWindowPtr

The address of the native WindowsWebView object. Initialized during construction.

Constructor Detail

WindowsWebView

public WindowsWebView(Dimension frameSize)

Create a new WebView.

Parameters:

frameSize - The size of the WebView rectangle.

Throws:

UnsupportedOperationException - if this class is instantiated on a non-Windows operating system.

WWRuntimeException - if creating the native web browser window fails for any reason. For example, because the process has run out of User Object handles (see documentation above).

Method Detail

convertToWindows

protected MouseEvent convertToWindows(MouseEvent e)

Converts the specified mouse event's screen point from WebView coordinates to Windows coordinates, and returns a new event who's screen point is in Windows coordinates, with the origin at the upper left corner of the WebView window.

Parameters:

e - The event to convert.

Returns:

A new mouse event in the Windows coordinate system.

createTextureRepresentation

protected WWTexture createTextureRepresentation(DrawContext dc)

Create a texture representation of the WebView.

Specified by:

createTextureRepresentation in class AbstractWebView

Parameters:

dc - draw context.

Returns:

A texture representation of the WebView contents.

dispose

public void dispose()

Disposes of any internal resources allocated by the object.

doSetFrameSize

protected void doSetFrameSize(Dimension size)

Specified by:

doSetFrameSize in class AbstractWebView

ensureMessageLoopRunning

protected void ensureMessageLoopRunning()

Ensure that the message loop thread is running. This method simply returns if the thread is already running. It creates a new thread if the message thread is not running. This method does not return until the message loop is initialized and ready for use.

getBackgroundColor

public 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

public 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 WebView.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:

WebView.getMinContentSize()

getContentURL

public 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.

getLinks

public 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

public 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.

goBack

public void goBack()

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

goForward

public void goForward()

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

handleWebViewCreationError

protected void handleWebViewCreationError()

This method is called by the constructor if an exception is thrown creating the WebView. It gives the WebView a change to cleanup static state that may have been set during the failed WebView construction.

sendEvent

public 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 WebView.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:

WebView.setActive(boolean)

setActive

public void setActive(boolean active)

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

Overridden to apply the active state to the native WebView.

Specified by:

setActive in interface WebView

Overrides:

setActive in class AbstractWebView

Parameters:

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

See Also:

WebView.sendEvent(java.awt.event.InputEvent)

setBackgroundColor

public 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.

setHTMLString

public 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

public 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

public 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

public void setMinContentSize(Dimension size)

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

Parameters:

size - Minimum size of the WebView content area.

stopMessageLoopIfNoInstances

protected void stopMessageLoopIfNoInstances()

Terminate the message loop thread if there are no active (non-disposed) WebView instances. Has no effect if there are active instances.