Package gov.nasa.worldwindx.examples.util

Class BalloonController

  • All Implemented Interfaces:
    SelectListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener, java.util.EventListener
    public class BalloonController
extends java.awt.event.MouseAdapter
implements SelectListener
    Controller to display a Balloon and handle balloon events. The controller does the following:
    • Display a balloon when an object is selected
    • Handle URL selection events in balloons
    • Resize BrowserBalloons
    • Handle close, back, and forward events in BrowserBalloon

    Displaying a balloon for a selected object

    When a object is clicked, the controller looks for a Balloon attached to the object. The controller includes special logic for handling balloons attached to KML features.

    KML Features

    The KMLAbstractFeature is attached to the top PickedObject under AVKey.CONTEXT. The controller looks for the balloon in the KMLAbstractFeature under key AVKey.BALLOON.

    Other objects

    If the top object is an instance of AVList, the controller looks for a Balloon under AVKey.BALLOON.

    URL events

    The controller looks for a value under AVKey.URL attached to either the top PickedObject. If the URL refers to a KML or KMZ document, the document is loaded into a new layer. If the link includes a reference to a KML feature, controller will animate the view to that feature and/or open the feature balloon.

    If the link should open in a new window (determined by an AVKey.TARGET of "_blank"), the controller will launch the system web browser and navigate to the link. Otherwise it will allow the BrowserBalloon to navigate to the link.

    Consuming a SelectEvent in the BalloonController will prevent the balloon from taking action on that event. For example, a BrowserBalloon will navigate in place when a link is clicked, but it will not if the balloon controller consumes the left press and left click select events. This allows the balloon controller to override the default action for certain URLs.

    BrowserBalloon control events

    AbstractBrowserBalloon identifies its controls by attaching a value to the PickedObject's AVList under AVKey.ACTION. The controller reads this value and performs the appropriate action. The possible actions are AVKey.RESIZE, AVKey.BACK, AVKey.FORWARD, and AVKey.CLOSE.

    • Field Detail

      • lastSelectedObject

        protected java.lang.Object lastSelectedObject

      • balloon

        protected Balloon balloon

      • balloonOffset

        protected int balloonOffset
        Vertical offset, in pixels, between the balloon and the point that the leader shape points to.

      • retrievalTimeout

        protected long retrievalTimeout
        Timeout to use when requesting remote documents. If the document does not load within this many milliseconds the controller will stop trying and report an error.

      • retrievalPollInterval

        protected long retrievalPollInterval
        Interval between periodic checks for completion of asynchronous document retrieval (in milliseconds).

      • resizeController

        protected BalloonResizeController resizeController
        A resize controller is created when the mouse enters a resize control on the balloon. The controller is destroyed when the mouse exits the resize control.

    • Constructor Detail

      • BalloonController

        public BalloonController​(WorldWindow wwd)
        Create a new balloon controller.
        Parameters:
        wwd - WorldWindow to attach to.

    • Method Detail

      • getBalloonOffset

        public int getBalloonOffset()
        Indicates the vertical distance, in pixels, between the balloon and the point that the leader points to.
        Returns:
        Vertical offset, in pixels.

      • setBalloonOffset

        public void setBalloonOffset​(int balloonOffset)
        Sets the vertical distance, in pixels, between the balloon and the point that the leader points to.
        Parameters:
        balloonOffset - Vertical offset, in pixels.

      • mouseClicked

        public void mouseClicked​(java.awt.event.MouseEvent e)
        Handle a mouse click. If the top picked object has a balloon attached to it the balloon will be made visible. A balloon may be attached to a KML feature, or to any picked object though AVKey.BALLOON.
        Specified by:
        mouseClicked in interface java.awt.event.MouseListener
        Overrides:
        mouseClicked in class java.awt.event.MouseAdapter
        Parameters:
        e - Mouse event

      • mouseMoved

        public void mouseMoved​(java.awt.event.MouseEvent e)
        Specified by:
        mouseMoved in interface java.awt.event.MouseMotionListener
        Overrides:
        mouseMoved in class java.awt.event.MouseAdapter

      • isResizeControl

        protected boolean isResizeControl​(PickedObject po)

      • getUrl

        protected java.lang.String getUrl​(PickedObject pickedObject)
        Get the URL attached to a PickedObject. This method looks for a URL attached to the PickedObject under AVKey.URL.
        Parameters:
        pickedObject - PickedObject to inspect. May not be null.
        Returns:
        The URL attached to the PickedObject, or null if there is no URL.

      • getContext

        protected KMLAbstractFeature getContext​(PickedObject pickedObject)
        Get the KML feature that is the context of a picked object. The context is associated with either the PickedObject or the user object under the key AVKey.CONTEXT.
        Parameters:
        pickedObject - PickedObject to inspect for context. May not be null.
        Returns:
        The KML feature associated with the picked object, or null if no KML feature is found.

      • onBalloonAction

        protected void onBalloonAction​(gov.nasa.worldwind.render.AbstractBrowserBalloon browserBalloon,
                               java.lang.String action)
        Called when a AbstractBrowserBalloon control is activated (Close, Back, or Forward).
        Parameters:
        browserBalloon - Balloon involved in action.
        action - Identifier for the action that occurred.

      • createResizeController

        protected void createResizeController​(Balloon balloon)
        Create a resize controller and attach it to the WorldWindow. Has no effect if there is already an active resize controller.
        Parameters:
        balloon - Balloon to resize.

      • destroyResizeController

        protected void destroyResizeController​(SelectEvent event)
        Destroy the active resize controller.
        Parameters:
        event - Event that triggered the controller to be destroyed.

      • onLinkActivated

        protected void onLinkActivated​(SelectEvent event,
                               java.lang.String url)
        Called when a URL in a balloon is activated. This method handles links to KML documents, features in KML documents, and links that target a new browser window.

        The possible cases are:

        KML/KMZ document - Load the document in a new layer.
        Feature in KML/KMZ document - Load the document, navigate to the feature and/or open feature balloon.
        Feature in currently open KML/KMZ document - Navigate to the feature and/or open feature balloon.
        HTML document, target current window - No action, let the BrowserBalloon navigate to the URL.
        HTML document, target new window - Launch the system web browser and navigate to the URL.

        If the URL matches one of the cases defined above, the SelectEvent will be marked as consumed. Marking the event as consumed prevents BrowserBalloon from handling the event. However, the controller will only take action on the event if the event is a link activation trigger.

        For example, if a left click event (a link activation event) occurs on a link to a KML document, the event will be marked as consumed and the document will be opened. If a left press event (not a link activation event) occurs with the same URL, the event will be consumed but the document will not be opened (if the press is followed by a click, the click will cause the document to be opened). Consuming the left press prevents the balloon from processing the event.

        Parameters:
        event - SelectEvent for the URL activation. If the event is a link activation trigger the controller will take action on the event (by opening a KML document, etc). If the event is not a link activation trigger, but the URL is a URL that the balloon controller would normally handle, the event is consumed to prevent the balloon itself from trying to handle the event, but no further action is taken.
        url - URL that was activated.
        See Also:
        isLinkActivationTrigger(gov.nasa.worldwind.event.SelectEvent)

      • isLinkActivationTrigger

        protected boolean isLinkActivationTrigger​(SelectEvent event)
        Determines if a SelectEvent is an event that activates a hyperlink.
        Parameters:
        event - Event to test. May not be null.
        Returns:
        true if the event actives hyperlinks. This implementation returns true for left click events.

      • openInNewBrowser

        protected void openInNewBrowser​(SelectEvent event,
                                java.lang.String url)
        Open a URL in a new web browser. Launch the system web browser and navigate to the URL.
        Parameters:
        event - SelectEvent that triggered navigation. The event is consumed if URL can be parsed.
        url - URL to open.

      • onFeatureLinkActivated

        protected boolean onFeatureLinkActivated​(KMLRoot doc,
                                         java.lang.String linkFragment,
                                         SelectEvent event)
        Called when a link to a KML feature is activated.
        Parameters:
        doc - Document to search for the feature.
        linkFragment - Reference to the feature. The fragment may contain a display directive. For example "#myPlacemark", or "#myPlacemark;balloon".
        event - The select event that activated the link. This event will be consumed if a KML feature is found that matches the link fragment. However, the controller only moves to the feature or opens a balloon if the event is a link activation event, or null. Other events are consumed to prevent the balloon from handling events for a link that the controller wants handle. This parameter may be null.
        Returns:
        True if a feature matching the reference was found and some action was taken.

      • doFeatureLinkActivated

        protected void doFeatureLinkActivated​(KMLAbstractFeature feature,
                                      java.lang.String directive)
        Handle activation of a KML feature link. Depending on the display directive, this method will either move the view to the feature, open the balloon for the feature, or both. See the KML specification for details on links to features in the KML description balloon.
        Parameters:
        feature - Feature to navigate to.
        directive - Display directive, one of FLY_TO, BALLOON, or BALLOON_FLY_TO.

      • isKmlUrl

        protected boolean isKmlUrl​(java.lang.String url,
                           java.lang.String contentType)
        Does a URL refer to a KML or KMZ document?
        Parameters:
        url - URL to test.
        contentType - Mime type of the URL content. May be null.
        Returns:
        Return true if the URL refers to a file with a ".kml" or ".kmz" extension, or if the contentType is the KML or KMZ mime type.

      • moveToFeature

        protected void moveToFeature​(KMLAbstractFeature feature)
        Move the view to look at a KML feature. The view will be adjusted to look at the bounding sector that contains all of the feature's points.
        Parameters:
        feature - Feature to look at.

      • showBalloon

        public void showBalloon​(KMLAbstractFeature feature)
        Show a balloon for a KML feature. The balloon will be positioned over the feature on the globe. If the feature does not have a balloon, a balloon may be created. canShowBalloon determines if a balloon will be created.
        Parameters:
        feature - KML feature for which to show a balloon.

      • canShowBalloon

        public boolean canShowBalloon​(KMLAbstractFeature feature)
        Determines whether or not a balloon must be created for a KML feature. A balloon is created for any feature with a balloon style or a non-empty description. No balloon is created for a feature with no balloon style and no description.
        Parameters:
        feature - KML feature to test.
        Returns:
        true if a balloon must be created for the feature. Otherwise false.

      • isBalloonTrigger

        protected boolean isBalloonTrigger​(java.awt.event.MouseEvent e)
        Inspect a mouse event to see if it should make a balloon visible.
        Parameters:
        e - Event to inspect.
        Returns:
        true if the event is a balloon trigger. This implementation returns true if the event is a left click.

      • getBalloon

        protected Balloon getBalloon​(PickedObject pickedObject)
        Get the balloon attached to a PickedObject. If the PickedObject represents a KML feature, then the balloon will be retrieved from the feature. Otherwise, the balloon will be retrieved from the user object's field AVKey.BALLOON.

        If a KML feature is picked, and the feature does not have a balloon, a new balloon may be created and attached to the feature. canShowBalloon determines if a balloon will be created for the feature.

        Parameters:
        pickedObject - PickedObject to inspect. May not be null.
        Returns:
        The balloon attached to the picked object, or null if there is no balloon. Returns null if pickedObject is null.

      • createBalloon

        protected Balloon createBalloon​(KMLAbstractFeature feature)
        Create a balloon for a KML feature and attach the balloon to the feature. The type of balloon created depends on the type of feature and the result of isUseBrowserBalloon(). If the feature is attached to a point on the globe, this method creates a GlobeBalloon. If the feature is attached to the screen, a ScreenBalloon is created. If isUseBrowserBalloon() returns true, the balloon will be a descendant of AbstractBrowserBalloon. Otherwise it will be a descendant of AbstractAnnotationBalloon.
        Parameters:
        feature - Feature to create balloon for.
        Returns:
        New balloon. May return null if the feature should not have a balloon.

      • configureBalloon

        protected void configureBalloon​(Balloon balloon,
                                KMLAbstractFeature feature)
        Configure a new balloon for a KML feature.
        Parameters:
        balloon - Balloon to configure.
        feature - Feature that owns the Balloon.

      • getAttachmentMode

        protected java.lang.String getAttachmentMode​(KMLAbstractFeature feature)
        Get the attachment mode of a KML feature: AVKey.GLOBE or AVKey.SCREEN. Some features, such as a PointPlacemark, are attached to a point on the globe. Others, such as a ScreenImage, are attached to the screen.
        Parameters:
        feature - KML feature to test.
        Returns:
        AVKey.GLOBE if the feature is attached to a geographic location. Otherwise AVKey.SCREEN. Container features (Document and Folder) are considered screen features.

      • isUseBrowserBalloon

        protected boolean isUseBrowserBalloon()
        Indicates if the controller will create Balloons of type AbstractBrowserBalloon. BrowserBalloons are used on platforms that support them (currently Windows and Mac). AbstractAnnotationBalloon is used on other platforms.
        Returns:
        true if the controller will create BrowserBalloons.

      • showBalloon

        protected void showBalloon​(Balloon balloon,
                           java.lang.Object balloonObject,
                           java.awt.Point point)
        Show a balloon at a screen point.
        Parameters:
        balloon - Balloon to make visible.
        balloonObject - The picked object that owns the balloon. May be null.
        point - Point where mouse was clicked.

      • showBalloon

        protected void showBalloon​(Balloon balloon,
                           Position position)
        Show a balloon at a globe position.
        Parameters:
        balloon - Balloon to make visible.
        position - Position on the globe to locate the balloon. If the balloon is attached to the screen, it will be position at the screen point currently over this position.

      • mustAdjustPosition

        protected boolean mustAdjustPosition​(Balloon balloon)
        Determines if a balloon position must be adjusted to make the balloon visible in the viewport.
        Parameters:
        balloon - Balloon to inspect.
        Returns:
        true if the balloon position must be adjusted to make the balloon visible.

      • adjustPosition

        protected void adjustPosition​(Balloon balloon,
                              java.awt.Point screenPoint)
        Adjust the position of a balloon so that the entire balloon is visible on screen.
        Parameters:
        balloon - Balloon to adjust the position of.
        screenPoint - Screen point to which the balloon leader points.

      • hideBalloon

        protected void hideBalloon()
        Hide the active balloon. Does nothing if there is no active balloon.

      • getBalloonPosition

        protected Position getBalloonPosition​(java.lang.Object topObject,
                                      java.awt.Point pickPoint)
        Get the position of the balloon for a picked object with an attached balloon. If the top object is an instance of Locatable, this method returns the position of the Locatable. If the object is an instance of AbstractShape, the method performs an intersection calculation between a ray through the pick point and the shape. If neither of the previous conditions are true, or if the object is null, this method returns the intersection position of a ray through the pick point and the globe.
        Parameters:
        topObject - Object that was picked. May be null.
        pickPoint - The point at which the mouse event occurred.
        Returns:
        Position at which to place the balloon, or null if a position cannot be determined.

      • getBalloonAltitudeMode

        protected int getBalloonAltitudeMode​(java.lang.Object balloonObject)
        Get the appropriate altitude mode for a GlobeBalloon, depending on the object that has been selected. If the balloon object is an instance of PointPlacemark, this implementation returns the altitude mode of the placemark. Otherwise it returns WorldWind.ABSOLUTE.
        Parameters:
        balloonObject - The object that the balloon is attached to.
        Returns:
        The altitude mode that should be applied to the balloon, one of WorldWind.ABSOLUTE, WorldWind.CLAMP_TO_GROUND, or WorldWind.RELATIVE_TO_GROUND.

      • computeIntersection

        protected Position computeIntersection​(AbstractShape shape,
                                       java.awt.Point screenPoint)
        Compute the intersection of a line through a screen point and a shape.
        Parameters:
        shape - Shape with which to compute intersection.
        screenPoint - Compute the intersection of a line through this screen point and the shape.
        Returns:
        The intersection position, or null if there is no intersection, or if the computation is interrupted.

      • getBalloonPositionForPlacemark

        protected Position getBalloonPositionForPlacemark​(KMLPlacemark placemark)
        Get the position of the balloon for a KML placemark. For a point placemark, this method returns the placemark point. For all other placemarks, this method returns the centroid of the sector that bounds all of the points in the placemark. Note that the centroid of the sector may not actually fall on the visible area of the shape.
        Parameters:
        placemark - Placemark for which to find a balloon position.
        Returns:
        Position for the balloon, or null if a position cannot be determined.
        See Also:
        getBalloonPosition(gov.nasa.worldwind.ogc.kml.KMLAbstractFeature)

      • getBalloonPositionForGroundOverlay

        protected Position getBalloonPositionForGroundOverlay​(KMLGroundOverlay overlay)
        Get the position of the balloon for a KML GroundOverlay. This method returns the centroid of the sector that bounds all of the points in the overlay.
        Parameters:
        overlay - Ground overlay for which to find a balloon position.
        Returns:
        Position for the balloon, or null if a position cannot be determined.
        See Also:
        getBalloonPosition(gov.nasa.worldwind.ogc.kml.KMLAbstractFeature)

      • getBalloonPosition

        protected Position getBalloonPosition​(java.util.List<? extends Position> positions)
        Get the position of the balloon for a list of positions that bound a feature. This method returns a position at the centroid of the sector that bounds all of the points in the list, and at the maximum altitude of the points in the list.
        Parameters:
        positions - List of positions to find a balloon position.
        Returns:
        Position for the balloon, or null if a position cannot be determined.

      • getBalloonPointForScreenOverlay

        protected java.awt.Point getBalloonPointForScreenOverlay​(KMLScreenOverlay overlay)
        Get the screen point for a balloon for a ScreenOverlay.
        Parameters:
        overlay - ScreenOverlay for which to find a balloon position.
        Returns:
        Point for the balloon, or null if a point cannot be determined.
        See Also:
        getBalloonPoint(gov.nasa.worldwind.ogc.kml.KMLAbstractFeature)

      • findMaxAltitude

        protected double findMaxAltitude​(java.util.List<? extends Position> positions)
        Get the maximum altitude in a list of positions.
        Parameters:
        positions - List of positions to search for max altitude.
        Returns:
        The maximum elevation in the list of positions. Returns -Double.MAX_VALUE if positions is empty.

      • findOpenKmlDocument

        protected KMLRoot findOpenKmlDocument​(java.lang.String url)
        Search for a KML document that has already been opened. This method looks in the session cache for a parsed KMLRoot.
        Parameters:
        url - URL of the KML document.
        Returns:
        KMLRoot for an already-parsed document, or null if the document was not found in the cache.

      • onDocumentLoaded

        protected void onDocumentLoaded​(java.lang.String url,
                                KMLRoot document,
                                java.lang.String featureRef)
        Called when a KML document has been loaded. This implementation creates a new layer and adds the new document to the layer.
        Parameters:
        url - URL of the document that has been loaded.
        document - Parsed document.
        featureRef - Reference to a feature that must be activated (fly to or open balloon).

      • onDocumentFailed

        protected void onDocumentFailed​(java.lang.String url,
                                java.lang.Exception e)
        Called when a KML file fails to load due to a network timeout or parsing error. This implementation simply logs a warning.
        Parameters:
        url - URL of the document that failed to load.
        e - Exception that caused the failure.

      • addDocumentLayer

        protected void addDocumentLayer​(KMLRoot document)
        Adds the specified document to this controller's WorldWindow as a new Layer.

        This expects the kmlRoot's AVKey.DISPLAY_NAME field to contain a display name suitable for use as a layer name.

        Parameters:
        document - the KML document to add a Layer for.