Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.ogc.kml

Class KmlNode

java.lang.Object
com.esri.arcgisruntime.ogc.kml.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 the API types:

KML Feature Types
KML Feature Type API 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

  • Property Details

    • balloonBackgroundColor

      public ReadOnlyObjectProperty<Color> balloonBackgroundColorProperty
      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 Color.WHITE.

      Since:
      200.0.0
      See Also:

    • uxIconColor

      public ReadOnlyObjectProperty<Color> uxIconColorProperty
      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 UX icon is specified, you can use this color to draw a placeholder for use in the UI (for example, a legend). Note that it does not pre-tint the getUxIcon(); it is the application's responsibility to tint the image before displaying it.

      Since:
      200.0.0
      See Also:

  • Method Details

    • 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

    • balloonBackgroundColorProperty

      public ReadOnlyObjectProperty<Color> balloonBackgroundColorProperty()
      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 Color.WHITE.

      Returns:
      the balloonBackgroundColor property
      Since:
      200.0.0
      See Also:

    • getBalloonBackgroundColor

      public Color getBalloonBackgroundColor()
      Gets the value of the balloonBackgroundColor property.
      Property description:
      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 Color.WHITE.

      Returns:
      the value of the balloonBackgroundColor property
      Since:
      200.0.0
      See Also:

    • 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 this API.

      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 this API.

      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

    • setTimeExtent

      public void setTimeExtent(TimeExtent timeExtent)
      Sets the KML node's time extent.
      Parameters:
      timeExtent - the KML node's time extent. May be null.
      Since:
      100.11.0

    • 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 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

    • uxIconColorProperty

      public ReadOnlyObjectProperty<Color> uxIconColorProperty()
      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 UX icon is specified, you can use this color to draw a placeholder for use in the UI (for example, a legend). Note that it does not pre-tint the getUxIcon(); it is the application's responsibility to tint the image before displaying it.

      Returns:
      the uxIconColor property
      Since:
      200.0.0
      See Also:

    • getUxIconColor

      public Color getUxIconColor()
      Gets the value of the uxIconColor property.
      Property description:
      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 UX icon is specified, you can use this color to draw a placeholder for use in the UI (for example, a legend). Note that it does not pre-tint the getUxIcon(); it is the application's responsibility to tint the image before displaying it.

      Returns:
      the value of the uxIconColor property
      Since:
      200.0.0
      See Also:

    • 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 a '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

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

    • setStyle

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

    • getStyle

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

    • 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

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