A layer that can visualize KML data. More...
| Header: | #include <KmlLayer.h> |
| Since: | Esri::ArcGISRuntime 100.4 |
| Inherits: | Esri::ArcGISRuntime::Layer and Esri::ArcGISRuntime::TimeAware |
Public Functions
| KmlLayer(Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr) | |
| KmlLayer(Esri::ArcGISRuntime::KmlDataset *dataset, QObject *parent = nullptr) | |
| virtual | ~KmlLayer() override |
| Esri::ArcGISRuntime::KmlDataset * | dataset() const |
Reimplemented Public Functions
| virtual Esri::ArcGISRuntime::TimeExtent | fullTimeExtent() const override |
| virtual bool | isSupportsTimeFiltering() const override |
| virtual bool | isTimeFilteringEnabled() const override |
| virtual void | setTimeFilteringEnabled(bool timeFilteringEnabled) override |
| virtual void | setTimeOffset(const Esri::ArcGISRuntime::TimeValue &timeOffset) override |
| virtual Esri::ArcGISRuntime::TimeValue | timeInterval() const override |
| virtual Esri::ArcGISRuntime::TimeValue | timeOffset() const override |
Signals
| void | fullTimeExtentChanged() |
Detailed Description
Keyhole Markup Language (KML) is a specification for working with geographic content. KML files can contain 2D and 3D content, as well as links to content from the network. You can read .kml and .kmz files from disk or the network and create, edit, and save a KML layer via the KmlDataset.
Functional characteristics
KML represents features as a tree of nodes, including network links, folders, and place marks. Like ArcGIS features, place marks are defined with point, line, or polygon geometry. KML geometry, however, is always based on the WGS84 coordinate system. KML can also have attributes, but unlike ArcGIS feature services, a KML document does not use a schema to define a standard set of fields. This API supports version 2.2 of the KML Standard, defined by the Open Geospatial Consortium (OGC).
Unique features of KML include network links and screen overlays. Network links are useful for retrieving network content on a specified interval, which is useful for keeping a live map up to date. Network links can also be used to split a large KML file into multiple per-region KML files, with each being loaded only when the region is in view. Screen overlays can be used to show content, such as branding or a legend, on top of the view. Screen overlay content does not scroll with the map or react to user interaction.
All coordinates are expressed in latitude and longitude (using decimal degrees), and are based on the SpatialReference::wgs84 geographic coordinate system. Altitude is always expressed in meters. The geographic features can contain attribute information and various styles can be specified to render them. Ground overlays allow images to be displayed for specific geographic objects or draped onto the map itself. Screen overlays allow fixing images to the GeoView, and may be used for compasses, logos, legends, etc. Network links give the ability to reference remote .kml or .kmz files, and refresh them periodically.
Loading the KmlLayer also loads its underlying KmlDataset, creating one if you didn't supply one through a constructor. The structure of a KML document can be examined through KmlDataset::rootNodes after the KmlDataset has successfully loaded. Missing or inaccessible .kml and .kmz files would cause loading to fail. Missing resources referenced by the KML document (such as images or files referenced via a network link will not prevent the layer from loading.
Performance characteristics
KML files can vary significantly in the features they use, including 3D models, network links, and refresh intervals. Not all features are supported in 2D and 3D. For example, 3D models only appear when the KML layer is shown in a scene. Many KML files consist solely of a pointer to another KML file and a refresh interval. For example, the National Weather Service distributes forecast maps in the United States this way.
Relevant samples:
- Display KML: Display KML from a URL, portal item, or local KML file.
- Display KML network links: Display a file with a KML network link, including displaying any network link control messages at launch.
- Edit KML ground overlay: Edit the values of a KML ground overlay.
- Identify KML features: Show a callout with formatted content for a KML feature.
- List KML contents: List the contents of a KML file.
See also Layer and KmlDataset.
Member Function Documentation
[explicit] KmlLayer::KmlLayer (Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr)
Creates a new KML layer object from a portal item.
- item - A PortalItem.
- parent - The optional parent QObject.
See also Layer::item.
[explicit] KmlLayer::KmlLayer (Esri::ArcGISRuntime::KmlDataset *dataset, QObject *parent = nullptr)
Creates a KML layer.
- dataset - The KML dataset.
- parent - The optional parent QObject.
KML layers are read-only and do not allow authoring or editing.
[override virtual] KmlLayer::~KmlLayer ()
Destructor.
Esri::ArcGISRuntime::KmlDataset *KmlLayer::dataset() const
Returns the KML dataset for this layer.
The KML dataset is the authoritative source for the layer's KML data. The KML dataset should be used when access to the tree of KML nodes is needed (for example to build a legend or toggle node visibility).
[override virtual] Esri::ArcGISRuntime::TimeExtent KmlLayer::fullTimeExtent () const
Reimplements: TimeAware::fullTimeExtent() const.
Returns the full time extent of the layer.
If the layer, such as an ArcGISMapImageLayer, has sublayers with different time extents, fullTimeExtent is a union of its sublayer's time extents.
[signal] void KmlLayer::fullTimeExtentChanged ()
Signal emitted when the fullTimeExtent changes for this layer.
See also TimeAware.
[override virtual] bool KmlLayer::isSupportsTimeFiltering () const
Reimplements: TimeAware::isSupportsTimeFiltering() const.
Returns whether the layer supports filtering its contents by time values.
[override virtual] bool KmlLayer::isTimeFilteringEnabled () const
Reimplements: TimeAware::isTimeFilteringEnabled() const.
Returns true if the layer filters data based on its GeoView::timeExtent, false otherwise.
This is only applicable if the layer's isSupportsTimeFiltering value is true. If the GeoView::timeExtent value is empty, no time filtering is applied and all content is rendered.
[override virtual] void KmlLayer::setTimeFilteringEnabled (bool timeFilteringEnabled )
Reimplements: TimeAware::setTimeFilteringEnabled(bool timeFilteringEnabled).
Sets the timeFilteringEnabled to timeFilteringEnabled.
See also isTimeFilteringEnabled.
[override virtual] void KmlLayer::setTimeOffset (const Esri::ArcGISRuntime::TimeValue &timeOffset )
Reimplements: TimeAware::setTimeOffset(const Esri::ArcGISRuntime::TimeValue &timeOffset).
Sets the timeOffset to timeOffset.
See also timeOffset.
[override virtual] Esri::ArcGISRuntime::TimeValue KmlLayer::timeInterval () const
Reimplements: TimeAware::timeInterval() const.
Returns the suggested time slider step size for this time aware layer.
You can use this information to set the step size for a time slider control. The value is empty if no time interval is suggested. The author of the layer's data typically configures this property if the data has been collected on a regular basis. For example, the daily position of a hurricane.
[override virtual] Esri::ArcGISRuntime::TimeValue KmlLayer::timeOffset () const
Reimplements: TimeAware::timeOffset() const.
Returns the amount of time by which the temporal values of this layer's data points are offset when displaying it in a GeoView.
The time offset is subtracted from the time extent set on the layer's GeoView. This is useful if you want to overlay data in multiple layers that lies within different temporal extents. For example, if you want to compare data in one layer for a certain year with data in the same layer from the subsequent year, you can create two layers that reference the same data's service endpoint but set the TimeValue in one of the layers to be one year.
See also setTimeOffset().