gov.nasa.worldwind.util.webview.WebView Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of worldwind-pcm Show documentation
worldwind-pcm
The newest version!
/*
 * Copyright (C) 2012 United States Government as represented by the Administrator of the
 * National Aeronautics and Space Administration.
 * All Rights Reserved.
 */
package gov.nasa.worldwind.util.webview;

import gov.nasa.worldwind.Disposable;
import gov.nasa.worldwind.avlist.AVList;
import gov.nasa.worldwind.render.*;

import java.awt.*;
import java.awt.event.*;
import java.net.URL;

/**
 * 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 {@link gov.nasa.worldwind.avlist.AVKey#REPAINT}. This can happen from web content loading, user
 * interaction, or from a programmatic change such as JavaScript.
 *
 * @author dcollins
 * @version $Id: WebView.java 1171 2013-02-11 21:45:02Z dcollins $
 */
public interface WebView extends AVList, Disposable
{
    /**
     * 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.
     *
     * @param htmlString the WebView's HTML text content, or null to display an empty
     *                   WebView.
     */
    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. 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.
     *
     * @param htmlString the WebView's HTML text content, or null to display an empty
     *                   WebView.
     * @param baseURL    the URL used to resolve relative paths in the htmlString, or
     *                   null to indicate that relative paths should be interpreted as unresolved
     *                   references.
     */
    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
     * 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.
     *
     * @param htmlString       the WebView's HTML text content, or null to display an empty
     *                         WebView.
     * @param resourceResolver the WebResourceResolver used to resolve relative paths in the
     *                         htmlString, or null to indicate that relative paths should be
     *                         interpreted as unresolved references.
     */
    void setHTMLString(String htmlString, WebResourceResolver resourceResolver);

    /**
     * Returns the size in pixels of this WebView's frame. This returns null if this WebView's frame size
     * is unspecified.
     *
     * @return the size of this WebView's frame in pixels, or null if it's unspecified.
     *
     * @see #setFrameSize(java.awt.Dimension)
     */
    Dimension getFrameSize();

    /**
     * Specifies the size in pixels of this WebView's frame.
     *
     * @param 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.
     */
    void setFrameSize(Dimension size);

    /**
     * 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 {@link #getMinContentSize()} for more information on how the minimum content size is used.
     *
     * @return the size of this WebView's content limited by the {@code minContentSize}, or null if this
     *         WebView's content size is unknown.
     *
     * @see #getMinContentSize()
     */
    Dimension getContentSize();

    /**
     * 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.
     *
     * @return The minimum size of the WebView content area.
     */
    Dimension getMinContentSize();

    /**
     * Specifies the minimum size in pixels of this WebView content area. See {@link #getMinContentSize()} for more
     * information on how this value is interpreted.
     *
     * @param size Minimum size of the WebView content area.
     */
    void setMinContentSize(Dimension size);

    /**
     * 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.
     *
     * @return the URL of this WebView's current content, or null if the current content is the HTML string
     *         specified by setHTMLString.
     */
    URL getContentURL();

    /**
     * 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.
     *
     * @return an Iterable of AVList parameters describing this WebView's visible
     *         links.
     */
    Iterable getLinks();

    /**
     * Returns a layed out and rendered representation of the WebView's content as a {@link
     * gov.nasa.worldwind.render.WWTexture}. The texture's image source is the WebView, and its dimensions are large
     * enough to capture the WebView's frame size (see {@link #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.
     *
     * @param dc The draw context the WebView is associated with.
     *
     * @return a rendered representation of the WebView's frame as a WWTexture.
     */
    WWTexture getTextureRepresentation(DrawContext dc);

    /**
     * Called when this WebView is activated or deactivated. The WebView only receives input events when it is active.
     *
     * @param active true if this WebView is being activated. false if this WebView is being
     *               deactivated.
     *
     * @see #sendEvent
     */
    void setActive(boolean active);

    /**
     * Indicates whether or not this WebView is active. The WebView only receives input events when it is active.
     *
     * @return true if this WebView is active, false if not.
     */
    boolean isActive();

    /**
     * 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 {@link java.awt.event.KeyEvent}, {@link
     * java.awt.event.MouseEvent}, and {@link java.awt.event.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 {@link #setActive} 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.
     *
     * @param event the event to send.
     *
     * @see #setActive
     */
    void sendEvent(InputEvent event);

    /** Navigate the WebView to the previous page in the browsing history. Has no effect if there is no previous page. */
    void goBack();

    /** Navigate the WebView to the next page in the browsing history. Has no effect if there is no next page. */
    void goForward();

    /**
     * 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.
     *
     * @param color Color to apply to the background.
     */
    void setBackgroundColor(Color color);

    /**
     * Indicates the current WebView background color. Implementations are not required to support setting the
     * background color.
     *
     * @return the color applied to the WebView background, or null if no color has been set.
     */
    Color getBackgroundColor();
}