- Direct Known Subclasses:
KmlContainer
,KmlGroundOverlay
,KmlNetworkLink
,KmlPhotoOverlay
,KmlPlacemark
,KmlScreenOverlay
,KmlTour
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 Type | API 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
-
Property Summary
TypePropertyDescriptionThe color to be used when this node's balloon popup is displayed.The color mask used to tint the KML node's image buffer. -
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds a listener to listen for the icon updates.void
Adds a listener to listen for refresh status change events.The color to be used when this node's balloon popup is displayed.Gets the address of the KML node.Gets the value of theballoonBackgroundColor
property.Gets the balloon popup content for this KML node as a string containing HTML.Gets the description of the KML node.Gets the bounding extent for the KML node.Gets the KML node's highlight style.getId()
Gets the ID of the KML node.getName()
Gets the name of the KML node.Gets the KML node's parent.Returns the most recent error that was encountered when the KML node transitioned to theKmlNode.RefreshStatus.FAILED
state.Gets the current refresh status.Gets the KML node's snippet.long
Gets the maximum number of lines of snippet to be shown in the UI.getStyle()
Gets the KML node's style.Gets the KML node's time extent.byte[]
Gets the icon of a KML node.Gets the value of theuxIconColor
property.int
Returns the ID of the node's icon.Gets the KML node's viewpoint ornull
if no Camera or LookAt is specified for the node.boolean
Controls whether the default style or an alternate 'highlighted' style (if present) is used for rendering the node.boolean
Gets the visibility of the KML node.boolean
Removes an icon updated listener.boolean
Removes a refresh status change listener.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
Sets the ID of the KML node.void
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
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.The color mask used to tint the KML node's image buffer.
-
Property Details
-
balloonBackgroundColor
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
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
Gets the name of the KML node.- Returns:
- the name of the KML node
- Since:
- 100.4.0
-
setName
Sets the name of the KML node.- Parameters:
name
- the name of the KML node- Since:
- 100.6.0
-
getDescription
Gets the description of the KML node.- Returns:
- the description of the KML node
- Since:
- 100.4.0
-
setDescription
Sets the description of the KML node.- Parameters:
description
- the description of the KML node- Since:
- 100.6.0
-
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
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
Gets the value of theballoonBackgroundColor
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
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
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
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
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
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
-
setTimeExtent
Sets the KML node's time extent.- Parameters:
timeExtent
- the KML node's time extent. May be null.- Since:
- 100.11.0
-
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 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
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
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
Gets the value of theuxIconColor
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
Sets the ID of the KML node.- Parameters:
id
- the ID of the KML node- Since:
- 100.6.0
-
getId
Gets the ID of the KML node.- Returns:
- the ID of the KML node
- Since:
- 100.6.0
-
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
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
Adds a listener to listen for the icon updates.- Parameters:
listener
- the listener- Throws:
IllegalArgumentException
- if listener is null- Since:
- 100.4.0
-
removeIconUpdatedEventListener
Removes an icon updated listener.- Parameters:
listener
- the listener to remove- Returns:
- true if successful, false otherwise
- Since:
- 100.4.0
-
addRefreshStatusChangedListener
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
Removes a refresh status change listener.- Parameters:
listener
- the listener to remove- Returns:
- true if successful, false otherwise
- Since:
- 100.4.0
-
saveAsAsync
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 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
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
Gets the KML node's highlight style.- Returns:
- a KmlStyle
- Since:
- 100.6.0
- See Also:
-
setStyle
Sets the KML node's style.- Parameters:
kmlStyle
- a KmlStyle- Since:
- 100.6.0
- See Also:
-
getStyle
Gets the KML node's style.- Returns:
- a KmlStyle
- Since:
- 100.6.0
- See Also:
-
setAddress
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
Gets the address of the KML node.- Returns:
- a string value representing an address
- Since:
- 100.7.0
- See Also:
-