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 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
Overlay N/A Properties can be found on individual overlay subtypes instead. GroundOverlay KmlGroundOverlay
ScreenOverlay KmlScreenOverlay
PhotoOverlay KmlPhotoOverlay
NetworkLink KmlNetworkLink
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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
KmlNode.RefreshStatus
KML node refresh statuses.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addIconUpdatedEventListener(IconUpdatedListener listener)
Adds a listener to listen for the icon updates.void
addRefreshStatusChangedListener(RefreshStatusChangedListener listener)
Adds a listener to listen for refresh status change events.String
getAddress()
Gets the address of the KML node.int
getBalloonBackgroundColor()
Gets the color to be used when this node's balloon popup is displayed.String
getBalloonContent()
Gets the balloon popup content for this KML node as a string containing HTML.String
getDescription()
Gets the description of the KML node.Envelope
getExtent()
Gets the bounding extent for the KML node.KmlStyle
getHighlightStyle()
Gets the KML node's highlight style.String
getId()
Gets the ID of the KML node.String
getName()
Gets the name of the KML node.KmlNode
getParentNode()
Gets the KML node's parent.ArcGISRuntimeException
getRefreshError()
Returns the most recent error that was encountered when the KML node transitioned to theKmlNode.RefreshStatus.FAILED
state.KmlNode.RefreshStatus
getRefreshStatus()
Gets the current refresh status.String
getSnippet()
Gets the KML node's snippet.long
getSnippetMaxLines()
Gets the maximum number of lines of snippet to be shown in the UI.KmlStyle
getStyle()
Gets the KML node's style.TimeExtent
getTimeExtent()
Gets the KML node's time extent.byte[]
getUxIcon()
Gets the icon of a KML node.int
getUxIconColor()
Gets the color mask used to tint the KML node's image buffer.int
getUxIconId()
Returns the ID of the node's icon.KmlViewpoint
getViewpoint()
Gets the KML node's viewpoint ornull
if no Camera or LookAt is specified for the node.boolean
isHighlighted()
Controls whether the default style or an alternate 'highlighted' style (if present) is used for rendering the node.boolean
isVisible()
Gets the visibility of the KML node.boolean
removeIconUpdatedEventListener(IconUpdatedListener listener)
Removes an icon updated listener.boolean
removeRefreshStatusChangedListener(RefreshStatusChangedListener listener)
Removes a refresh status change listener.ListenableFuture<Void>
saveAsAsync(String filepath)
Asynchronously saves the KML node and any referenced local files into a zipped KMZ archive(.kmz).void
setAddress(String address)
Sets the address of the KML node.void
setDescription(String description)
Sets the description of the KML node.void
setHighlighted(boolean highlighted)
Controls whether the default style or an alternate 'highlighted' style (if present) is used for rendering the node.void
setHighlightStyle(KmlStyle highlightStyle)
Sets the KML node's highlight style.void
setId(String id)
Sets the ID of the KML node.void
setName(String name)
Sets the name of the KML node.void
setSnippet(String snippet)
Sets the KML node's snippet.void
setSnippetMaxLines(int maxLines)
Sets the maximum number of lines of snippet to be shown in the UI.void
setStyle(KmlStyle kmlStyle)
Sets the KML node's style.void
setTimeExtent(TimeExtent timeExtent)
Sets the KML node's time extent.void
setViewpoint(KmlViewpoint viewpoint)
Sets the viewpoint of the KML node.void
setVisible(boolean visible)
Sets the visibility of the KML node.
-
-
-
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 benull
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. AKmlContainer
node such asKmlDocument
orKmlFolder
may have its ownTimeExtent
independent of its child nodes. All KML TimeStamps and TimeSpans specified in a KML/KMZ file are converted to their UTCTimeExtent
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. AKmlContainer
node such asKmlDocument
orKmlFolder
may have its ownTimeExtent
independent of its child nodes. All KML TimeStamps and TimeSpans specified in a KML/KMZ file are converted to their UTCTimeExtent
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 ornull
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 thegetUxIcon()
; 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 callgetRefreshError()
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 theKmlNode.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 tofiles/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()
-
getHighlightStyle
public KmlStyle getHighlightStyle()
Gets the KML node's highlight style.- Returns:
- a KmlStyle
- Since:
- 100.6.0
- See Also:
setHighlightStyle(KmlStyle)
-
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)
-
-