Package com.esri.arcgisruntime.ogc.kml

Class KmlNode

  • Direct Known Subclasses:
    KmlContainer, KmlGroundOverlay, KmlNetworkLink, KmlPhotoOverlay, KmlPlacemark, KmlScreenOverlay, KmlTour
    public abstract class KmlNode
extends Object
    A single node within a KML document.

    A KmlNode corresponds to the KML concept of a Feature. It is an abstract type that describes common properties that are common to all KML Features, such as: name, description, visibility, and view point etc.

    The following table maps KML Feature Types to ArcGIS Runtime types:

    KML Feature Types
    KML Feature Type Runtime Type Notes
    Container KmlContainer Abstract type. Contains properties common to KmlDocument and KmlFolder.
    Document KmlDocument
    Folder KmlFolder
    Placemark KmlPlacemark
    OverlayN/AProperties can be found on individual overlay subtypes instead.
    GroundOverlay KmlGroundOverlay
    ScreenOverlayKmlScreenOverlay
    PhotoOverlay KmlPhotoOverlay
    NetworkLinkKmlNetworkLink

    Examining individual nodes may be useful for: viewing attributes of the KML data, seeing the organization/structure within the KmlDataset, toggling visibility of KML features, and navigating to specific KML features.

    It should be noted that a typical KML document will have multiple levels of nested KML nodes. Therefore to accurately traverse through all of the KML node information in a KmlDataset, it is recommended to recursively test all KmlNodes to see if they contain additional child KmlNodes.

    Since:
    100.4.0

    • Method Detail

      • getName

        public String getName()
        Gets the name of the KML node.
        Returns:
        the name of the KML node
        Since:
        100.4.0

      • setName

        public void setName​(String name)
        Sets the name of the KML node.
        Parameters:
        name - the name of the KML node
        Since:
        100.6.0

      • getDescription

        public String getDescription()
        Gets the description of the KML node.
        Returns:
        the description of the KML node
        Since:
        100.4.0

      • setDescription

        public void setDescription​(String description)
        Sets the description of the KML node.
        Parameters:
        description - the description of the KML node
        Since:
        100.6.0

      • getBalloonContent

        public String getBalloonContent()
        Gets the balloon popup content for this KML node as a string containing HTML.
        Returns:
        a string containing HTML to be displayed in a balloon popup for the KML node
        Since:
        100.4.0

      • getBalloonBackgroundColor

        public int getBalloonBackgroundColor()
        Gets the color to be used when this node's balloon popup is displayed.

        This color can be used for the UI that presents the balloon contents, such as the border and background colors. The default color is white (0xFFFFFFFF).

        Returns:
        the color in an integer 0xAARRGGBB format
        Since:
        100.4.0

      • isVisible

        public boolean isVisible()
        Gets the visibility of the KML node.

        In order for a node to be visible, all of its ancestors must also be visible. Changing the visibility of one node may affect visibility of other nodes in the dataset hierarchy, such as child nodes.

        Returns:
        true if the KML node is visible, false otherwise
        Since:
        100.4.0

      • setVisible

        public void setVisible​(boolean visible)
        Sets the visibility of the KML node.

        It will hide or show the KML node on the connected GeoView. The visibility also affects the visibility of child nodes.

        Parameters:
        visible - true to set the KML node visible, false otherwise
        Since:
        100.4.0

      • isHighlighted

        public boolean isHighlighted()
        Controls whether the default style or an alternate 'highlighted' style (if present) is used for rendering the node.

        This is unrelated to the concept of selection in ArcGIS Runtime.

        Returns:
        true if the KML node is highlighted, false otherwise
        Since:
        100.4.0

      • setHighlighted

        public void setHighlighted​(boolean highlighted)
        Controls whether the default style or an alternate 'highlighted' style (if present) is used for rendering the node.

        This is unrelated to the concept of selection in ArcGIS Runtime.

        Parameters:
        highlighted - true to set the KML node to be highlighted, false otherwise
        Since:
        100.4.0

      • getExtent

        public Envelope getExtent()
        Gets the bounding extent for the KML node.

        All coordinates in KML are expressed in latitude and longitude (using decimal degrees) and are in the WGS84 geographic coordinate system.

        Returns:
        the extent for the KML node
        Since:
        100.4.0

      • getSnippet

        public String getSnippet()
        Gets the KML node's snippet.

        Snippets can be defined for KML nodes as an additional short description for UI display. If no snippet is specified, you can take the first few lines of the description. The maximum number of lines to display is specified by the getSnippetMaxLines() property.

        Returns:
        the KML node's snippet
        Since:
        100.4.0

      • setSnippet

        public void setSnippet​(String snippet)
        Sets the KML node's snippet.

        Snippets can be defined for KML nodes as an additional short description for UI display. If no snippet is specified, you can take the first few lines of the description. The maximum number of lines to display is specified by the getSnippetMaxLines() property.

        Parameters:
        snippet - the KML node's snippet
        Since:
        100.6.0

      • getSnippetMaxLines

        public long getSnippetMaxLines()
        Gets the maximum number of lines of snippet to be shown in the UI.

        If no snippet is specified, you can create a short snippet by taking the first few lines of the description.

        Returns:
        number of lines of snippet to be shown in the UI
        Since:
        100.4.0

      • setSnippetMaxLines

        public void setSnippetMaxLines​(int maxLines)
        Sets the maximum number of lines of snippet to be shown in the UI.
        Parameters:
        maxLines - number of lines of snippet to be shown in the UI
        Since:
        100.6.0

      • getParentNode

        public KmlNode getParentNode()
        Gets the KML node's parent. Can be null if this is a root node.
        Returns:
        the KML node's parent
        Since:
        100.4.0

      • getTimeExtent

        public TimeExtent getTimeExtent()
        Gets the KML node's time extent.

        Represents the TimeExtent equivalent of a KML node's TimeStamp or TimeSpan. A KmlContainer node such as KmlDocument or KmlFolder may have its own TimeExtent independent of its child nodes. All KML TimeStamps and TimeSpans specified in a KML/KMZ file are converted to their UTC TimeExtent equivalents. 

        
 Examples:

 Kml TimeStamp       | TimeExtent.getStartTime()   | TimeExtent.getEndTime()
 ------------------- | --------------------------- | -------------------------
 2021                | 2021-01-01T00:00:00         | 2021-12-31T23:59:59
 2021-01             | 2021-01-01T00:00:00         | 2021-01-31T23:59:59
 2021-01-01          | 2021-01-01T00:00:00         | 2021-01-01T23:59:59
 2021-01-01T12:34:56 | 2021-01-01T12:34:56         | 2021-01-01T12:34:56

 Kml TimeSpan           | TimeExtent.getStartTime()  | TimeExtent.getEndTime()
 ---------------------- | ---------------------------| --------------------------
 2021         - 2022    | 2021-01-01T00:00:00        | 2022-12-31T23:59:59
 2021-01      - 2021-02 | 2021-01-01T00:00:00        | 2021-02-28T23:59:59
 No beginning - 2021    | Infinite start time        | 2021-12-31T23:59:59
 2021         - No end  | 2021-01-01T00:00:00        | Infinite end time
        Returns:
        the KML node's time extent, or null if none
        Since:
        100.11.0
        See Also:
        TimeExtent

      • setTimeExtent

        public void setTimeExtent​(TimeExtent timeExtent)
        Sets the KML node's time extent.

        Represents the TimeExtent equivalent of a KML node's TimeStamp or TimeSpan. A KmlContainer node such as KmlDocument or KmlFolder may have its own TimeExtent independent of its child nodes. All KML TimeStamps and TimeSpans specified in a KML/KMZ file are converted to their UTC TimeExtent equivalents. Examples: 

        
 Kml TimeStamp       | TimeExtent.getStartTime()   | TimeExtent.getEndTime()
 ------------------- | --------------------------- | -------------------------
 2021                | 2021-01-01T00:00:00         | 2021-12-31T23:59:59
 2021-01             | 2021-01-01T00:00:00         | 2021-01-31T23:59:59
 2021-01-01          | 2021-01-01T00:00:00         | 2021-01-01T23:59:59
 2021-01-01T12:34:56 | 2021-01-01T12:34:56         | 2021-01-01T12:34:56

 Kml TimeSpan           | TimeExtent.getStartTime() | TimeExtent.getEndTime()
 ---------------------- | ---------------------------| --------------------------
 2021         - 2022    | 2021-01-01T00:00:00        | 2022-12-31T23:59:59
 2021-01      - 2021-02 | 2021-01-01T00:00:00        | 2021-02-28T23:59:59
 No beginning - 2021    | Infinite start time        | 2021-12-31T23:59:59
 2021         - No end  | 2021-01-01T00:00:00        | Infinite end time.
        Parameters:
        timeExtent - the KML node's time extent
        Since:
        100.11.0
        See Also:
        TimeExtent

      • getViewpoint

        public KmlViewpoint getViewpoint()
        Gets the KML node's viewpoint or null if no Camera or LookAt is specified for the node.

        The KML view point is the specified vantage point for looking at the node. This can be used to show a particular node in the view (for example, if a user selected it in a table of contents).

        KML viewpoints can be converted to Runtime viewpoints for use with a GeoView. See the guide documentation and samples for details.

        Returns:
        the KML node's view point
        Since:
        100.4.0

      • setViewpoint

        public void setViewpoint​(KmlViewpoint viewpoint)
        Sets the viewpoint of the KML node.
        Parameters:
        viewpoint - a KmlViewpoint
        Since:
        100.6.0

      • getUxIcon

        public byte[] getUxIcon()
        Gets the icon of a KML node.

        Use this icon to represent the KML node in the UI. Use addIconUpdatedEventListener(IconUpdatedListener) to listen for changes to the icon.

        Returns:
        the UX icon of a KML node
        Since:
        100.4.0

      • getUxIconColor

        public int getUxIconColor()
        Gets the color mask used to tint the KML node's image buffer.

        Pixels in the image are multiplied by this color channel-by-channel.

        When no icon is specified (getUxIcon() is null), you can use the icon color to draw a placeholder image in the UI (for example, the legend). Note that Runtime does not pre-tint the getUxIcon(); it is the application's responsibility to tint the image before displaying it.

        Returns:
        the color in an integer 0xAARRGGBB format
        Since:
        100.4.0

      • getUxIconId

        public int getUxIconId()
        Returns the ID of the node's icon.
        Returns:
        the icon ID
        Since:
        100.4.0

      • setId

        public void setId​(String id)
        Sets the ID of the KML node.
        Parameters:
        id - the ID of the KML node
        Since:
        100.6.0

      • getId

        public String getId()
        Gets the ID of the KML node.
        Returns:
        the ID of the KML node
        Since:
        100.6.0

      • getRefreshStatus

        public KmlNode.RefreshStatus getRefreshStatus()
        Gets the current refresh status. Use the node refresh status to update the node's properties and update application UI.
        • KmlNode.RefreshStatus.IN_PROGRESS - Invalidate the node and its children. Applications may wish to show an appropriate UI cue such as a spinning wheel on top of the node's table of contents icon to indicate in progress status and to restrict user interaction with the node.
        • KmlNode.RefreshStatus.COMPLETED - Read and update the node's properties and its children.
        • KmlNode.RefreshStatus.FAILED - Application may call getRefreshError() to get the reason for failure. Also, applications may wish to show an appropriate UI cue such as a red X with the node's table of contents icon to indicate the failed status.
        Returns:
        the refresh status
        Since:
        100.4.0

      • getRefreshError

        public ArcGISRuntimeException getRefreshError()
        Returns the most recent error that was encountered when the KML node transitioned to the KmlNode.RefreshStatus.FAILED state.
        Returns:
        the most recent error that was encountered when the KML node transitioned to the RefreshStatus.FAILED state
        Since:
        100.4.0

      • addIconUpdatedEventListener

        public void addIconUpdatedEventListener​(IconUpdatedListener listener)
        Adds a listener to listen for the icon updates.
        Parameters:
        listener - the listener
        Throws:
        IllegalArgumentException - if listener is null
        Since:
        100.4.0

      • removeIconUpdatedEventListener

        public boolean removeIconUpdatedEventListener​(IconUpdatedListener listener)
        Removes an icon updated listener.
        Parameters:
        listener - the listener to remove
        Returns:
        true if successful, false otherwise
        Since:
        100.4.0

      • addRefreshStatusChangedListener

        public void addRefreshStatusChangedListener​(RefreshStatusChangedListener listener)
        Adds a listener to listen for refresh status change events.
        Parameters:
        listener - the listener
        Throws:
        IllegalArgumentException - if listener is null
        Since:
        100.4.0

      • removeRefreshStatusChangedListener

        public boolean removeRefreshStatusChangedListener​(RefreshStatusChangedListener listener)
        Removes a refresh status change listener.
        Parameters:
        listener - the listener to remove
        Returns:
        true if successful, false otherwise
        Since:
        100.4.0

      • saveAsAsync

        public ListenableFuture<Void> saveAsAsync​(String filepath)
        Asynchronously saves the KML node and any referenced local files into a zipped KMZ archive(.kmz).

        The node will be saved to a KMZ file to ensure that any referenced files are available locally when sharing the file with others.

        If this method is called on a leaf node (e.g. KmlPlacemark, KmlGroundOverlay, etc), only that node and its referenced files will be saved. If this method is called on container node (e.g. KmlDocument, KmlFolder), the node and all of its children and referenced files will be saved. If this method is called on a KMLNetworkLink, the link will be saved but the children will not. This is because the children will simply be refetched when the saved KMLNetworkLink is loaded.

        Saving referenced files will differ based on the type of reference. For HTTP paths, the path will be saved as is but the referenced file will not be zipped into the archive, as it will simply be refetched when the new KMZ is loaded. For relative paths, the path will be saved as is and the referenced file will be zipped relative to the root of the KMZ file. For absolute paths, the path will be converted to a relative path, and the referenced file will be zipped into a files folder at the root of the KMZ file. For example, C:/icons/some_icon.png would be converted to files/some_icon.png and stored at that location in the KMZ file.

        The filename supports unicode characters as well as nested directories. It must be non-empty and there must not be an existing file located there. An ArcGIS runtime exception will be thrown if the file path doesn't end with the extension KMZ. Saving a node to a KMZ file requires an ArcGIS Runtime 'Standard' license level.

        Parameters:
        filepath - a file path with the extension (.kmz) to which the node should be saved
        Returns:
        a ListenableFuture to execute the operation asynchronously. Add a listener to the Future to know when the saving is done.
        Throws:
        IllegalArgumentException - if filepath is null or empty
        Since:
        100.6.0

      • setHighlightStyle

        public void setHighlightStyle​(KmlStyle highlightStyle)
        Sets the KML node's highlight style.

        The style is used when the KML node has been highlighted or selected.

        Parameters:
        highlightStyle - a KmlStyle
        Since:
        100.6.0
        See Also:
        getHighlightStyle()

      • setStyle

        public void setStyle​(KmlStyle kmlStyle)
        Sets the KML node's style.
        Parameters:
        kmlStyle - a KmlStyle
        Since:
        100.6.0
        See Also:
        getStyle()

      • getStyle

        public KmlStyle getStyle()
        Gets the KML node's style.
        Returns:
        a KmlStyle
        Since:
        100.6.0
        See Also:
        setStyle(KmlStyle)

      • setAddress

        public void setAddress​(String address)
        Sets the address of the KML node.

        The address represents an unstructured address such as a street, city, state address, and/or a postal code.

        Parameters:
        address - a string value representing an address
        Since:
        100.7.0
        See Also:
        getAddress()

      • getAddress

        public String getAddress()
        Gets the address of the KML node.
        Returns:
        a string value representing an address
        Since:
        100.7.0
        See Also:
        setAddress(String)