/// <summary>
/// Gets or sets the Url to the KML document.
/// </summary>
/// <remarks>
/// <para>
/// Accessing a KmlLayer is unique in that ArcGIS Server is not required to view geographic information. Since
/// the KmlLayer is based upon a KML or KMZ file, all that is required is a web server to host the KML/KMZ file.
/// <b>NOTE:</b> ArcGIS Server has the ability to host geographic web services created in ArcMap as native
/// KML/KMZ files.
/// </para>
/// <para>
/// Developers who wish to test the KmlLayer functionality using KML/KMZ files locally on their
/// development machine have the followings options:
/// </para>
/// <para>
/// <b>Option #1:</b> Developers can place the KML/KMZ file in the ClientBin directory of the test web site that
/// is generated when creating a Silverlight application using Visual Studios built in web server (i.e. the directory
/// that has the path: ..\[APPLICATION_NAME].Web\ClientBin). This option is the easiest method for testing KML/KMZ files
/// when there is no web browser security issues because all of the KML/KMZ functionality is self contained. See the
/// code example in this document for one common workflow example for Option #1.
/// </para>
/// <para>
/// <b>NOTE:</b> If the KML/KMZ file has hyperlinks (i.e. they begin with http://) to resources (such as other KML/KMZ
/// files) to locations outside of your local network, <b>IT WILL BE REQUIRED</b> to use Option #2 for local
/// testing of KML/KMZ files. Some common KML tags (or nested sub-tags) that can use external hyperlinks outside
/// of your local network include the following: <href>, <Style>, <Icon>, <IconStyle>,
/// <StyleMap>, <NetworkLink>, and <styleUrl>. Additionally, if you get a Security Exception
/// or unhandled exception 4004 errors in Visual Studio during your Silverlight application debugging, you will
/// most likely need to use Option #2 instead.
/// </para>
/// <para>
/// <b>Option #2:</b> If the developer has installed a web server on the same computer as Visual Studio (for example:
/// Internet Information Server (IIS)), then they can place the KML/KMZ file in an application directory of their
/// local web server (i.e. http://localhost). Using this option has the additional requirements of:
/// </para>
/// <list type="bullet">
/// <item>Setting up the correct MIME type on the web server to handle KML/KMZ files</item>
/// <item>Adding a crossdomain.xml file to the root of the web server</item>
/// <item>Making use of a proxy to avoid Security Exception error messages</item>
/// </list>
/// <para> See the code example in the
/// <see cref="ESRI.ArcGIS.Client.Toolkit.DataSources.KmlLayer.ProxyUrl">KmlLayer.ProxyUrl</see> Property
/// for one common workflow example of Option #2.
/// </para>
/// </remarks>
/// <example>
/// <para>
/// The following steps show one example of how a developer could test a simple KML file (with no external
/// hyperlink dependencies) using Visual Studio’s built-in web server (Cassini):
/// </para>
/// <list type="bullet">
/// <item>Launch Visual Studio 2010</item>
/// <item>Choose <b>File</b> | <b>New Project</b> from the Visual Studio menus.</item>
/// <item>
/// In the <b>New Project</b> dialog, expand .NET Language of your choice (Visual Basic shown in this
/// example), click on the <b>Silverlight Template</b>, choose <b>Silverlight Application</b>, and specify the
/// following information in the textboxes:
/// <list type="bullet">
/// <item>Name: <b>SilverlightApplication1</b></item>
/// <item>Location: <b>C:\KML_Test\</b></item>
/// <item>Solution name: <b>SilverlightApplication1</b></item>
/// </list>
/// See the following screen shot:<br/>
/// <img border="0" alt="Choosing a Silverlight Application in Visual Studio." src="C:\ArcGIS\dotNET\API SDK\Main\ArcGISSilverlightSDK\LibraryReference\images\Client.Toolkit.DataSources.Url.VS_KML_Test_1.png"/>
/// </item>
/// <item>
/// In the <b>New Silverlight Application</b> dialog, accept the defaults (make sure the <b>Host the Silverlight
/// application in a new Web site</b> is checked). This will use the Visual Studio built-in web server (Cassini) for
/// launching your Silverlight application (see the following screen shot):<br/>
/// <img border="0" alt="Accepting the defaults in the New Silverlight Application dialog." src="C:\ArcGIS\dotNET\API SDK\Main\ArcGISSilverlightSDK\LibraryReference\images\Client.Toolkit.DataSources.Url.VS_KML_Test_2.png"/>
/// </item>
/// <item>Drag an ESRI Silverlight API <b>Map Control</b> onto the <b>MainPage.xaml</b> design surface.</item>
/// <item>Add the following additional Reference to the Visual Studio Project: <b>ESRI.ArcGIS.Client.Toolkit.DataSources</b>.</item>
/// <item>Replace the XAML code in the <b>MainPage.xaml</b> with the following:
/// <code title="Example XAML1" description="" lang="XAML">
/// <UserControl x:Class="SilverlightApplication1.MainPage"
/// xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
/// xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
/// xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
/// xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
/// mc:Ignorable="d"
/// d:DesignHeight="300" d:DesignWidth="400"
/// xmlns:esri="http://schemas.esri.com/arcgis/client/2009">
///
/// <Grid x:Name="LayoutRoot" Background="White">
/// <esri:Map Background="White" HorizontalAlignment="Left" Name="Map1" VerticalAlignment="Top"
/// WrapAround="True" Height="276" Width="376" Margin="12,12,0,0">
/// <esri:Map.Layers>
/// <esri:LayerCollection>
/// <esri:ArcGISTiledMapServiceLayer
/// Url="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" />
/// <esri:KmlLayer Url="Test.kml"/>
/// </esri:LayerCollection>
/// </esri:Map.Layers>
/// </esri:Map>
/// </Grid>
/// </UserControl>
/// </code>
/// </item>
/// <item>
/// Choose <b>Build</b> | <b>Build Solution</b> from the Visual Studio menus (you should not have any
/// compiler Errors/Warnings).
/// </item>
/// <item>
/// Using the text editor application, <b>Notepad</b>, copy the following KML syntax and save the file as
/// <b>C:\KML_Test\SilverlightApplication1\SilverlightApplication1.Web\ClientBin\Test.kml</b> (this is
/// the same location as where the <b>SilverlightApplication1.xap</b> file gets created when the Visual
/// Studio Project gets built).
/// <code title="Example XAML2" description="" lang="XAML">
/// <?xml version="1.0" encoding="UTF-8"?>
/// <kml xmlns="http://www.opengis.net/kml/2.2">
/// <Document>
/// <name>Simple Placemark KML</name>
/// <visibility>1</visibility>
/// <open>1</open>
/// <Placemark>
/// <name>Simple placemark</name>
/// <visibility>true</visibility>
/// <open>0</open>
/// <Point>
/// <coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
/// </Point>
/// </Placemark>
/// </Document>
/// </kml>
/// </code>
/// </item>
/// <item>
/// Use <b>Windows Explorer</b> to confirm you have a the
/// <b>C:\KML_TEST\SilverlightApplication1\SilverlightApplication1.Web\ClientBin\Test.kml</b> file created (see the
/// following screen shot):<br/>
/// <img border="0" alt="Location of the .kml file on disk." src="C:\ArcGIS\dotNET\API SDK\Main\ArcGISSilverlightSDK\LibraryReference\images\Client.Toolkit.DataSources.Url.VS_KML_Test_4.png"/>
/// </item>
/// <item>
/// Hit <b>F5</b> (or click the Start Debugging button) in Visual Studio to launch the Silverlight application in
/// Internet Explorer. You should get an image that appears like the following screenshot (a single red point in San
/// Francisco):<br/>
/// <img border="0" alt="Displaying the KML in a Map Control." src="C:\ArcGIS\dotNET\API SDK\Main\ArcGISSilverlightSDK\LibraryReference\images\Client.Toolkit.DataSources.Url.VS_KML_Test_3.png"/>
/// </item>
/// </list>
/// </example>
/// <seealso cref="SetSource"/>
#endif
#if !SILVERLIGHT
/// <summary>
/// Gets or sets the Url to the KML document.
/// </summary>
/// <remarks>
/// <para>
/// Accessing a KmlLayer is unique in that ArcGIS Server is not required to view geographic information. Since
/// the KmlLayer is based upon a KML or KMZ file, all that is required is a web server to host the KML/KMZ file.
/// <b>NOTE:</b> ArcGIS Server has the ability to host geographic web services created in ArcMap as native
/// KML/KMZ files.
/// </para>
/// <para>
/// Developers who wish to test the KmlLayer functionality using KML/KMZ files locally on their
/// development machine have the followings options:
/// </para>
/// <para>
/// <b>Option #1:</b> Developers can place a KML/KMZ file anywhere on the local hard drive and provide the file
/// path as the KmlLayer.Url (example: Url="C:\TEST_KML_FILES\Test.kml").
/// </para>
/// <para>
/// <b>Option #2:</b> If the developer has installed a web server on the same computer as Visual Studio (for
/// example: Internet Information Server (IIS)), then they can place the KML/KMZ file in an application
/// directory of their local web server (i.e. http://localhost). Using this option has the additional requirements of:
/// </para>
/// <list type="bullet">
/// <item>Setting up the correct MIME type on the web server to handle KML/KMZ files</item>
/// <item>Adding a crossdomain.xml file to the root of the web server</item>
/// <item>Making use of a proxy to avoid Security Exception error messages</item>
/// </list>
/// <para>
/// <b>NOTE:</b> WPF does not use proxies so the use of KmlLayer.ProxyUrl is not necessary (even though the local KML
/// file may have resource links (i.e. http://) to locations outside of the local network).
/// </para>
/// </remarks>
/// <seealso cref="SetSource"/>
#endif
#if WINDOWS_PHONE
/// <summary>
/// Gets or sets the Url to the KML document.
/// </summary>
/// <remarks>
/// <para>
/// Accessing a KmlLayer is unique in that ArcGIS Server is not required to view geographic information. Since
/// the KmlLayer is based upon a KML or KMZ file, all that is required is a web server to host the KML/KMZ file.
/// <b>NOTE:</b> ArcGIS Server has the ability to host geographic web services created in ArcMap as native
/// KML/KMZ files.
/// </para>
/// <para>
/// Developers who wish to test the KmlLayer functionality using KML/KMZ files locally on their
/// development machine have the followings options:
/// </para>
/// <para>
/// <b>Option #1:</b> If the developer has installed a web server on the same computer as Visual Studio (for
/// example: Internet Information Server (IIS)), then they can place the KML/KMZ file in an application directory
/// of their local web server (i.e. http://localhost). Using this option has the additional requirements of:
/// </para>
/// <list type="bullet">
/// <item>Setting up the correct MIME type on the web server to handle KML/KMZ files</item>
/// <item>Adding a crossdomain.xml file to the root of the web server</item>
/// <item>Making use of a proxy to avoid Security Exception error messages</item>
/// </list>
/// <para>
/// <b>NOTE:</b> Windows Phone does not use proxies so the use of KmlLayer.ProxyUrl is not necessary (even though
/// the local KML file may have resource links (i.e. http://) to locations outside of the local network).
/// </para>
/// </remarks>
/// <seealso cref="SetSource"/>
#endif
#region Constructors
/// <summary>
/// Initializes a new instance of the <see cref="KmlLayer"/> class.
/// </summary>
public KmlLayer()
{
ChildLayers = new LayerCollection();
_isLoading = false;
_isLoaded = false;
NeedRefreshOnRegion = false;
_context = new KmlLayerContext { Images = new Dictionary<string,ImageBrush>()};
PropertyChanged += KmlLayer_PropertyChanged;
}
void RefreshOnRegion(Envelope region)
{
if (NeedRefreshOnRegion && IsInRegion(Map, region))
{
// refresh the KML layer
_context = new KmlLayerContext { Images = new Dictionary<string, ImageBrush>() }; // reset the context
_isLoading = true;
NeedRefreshOnRegion = false;
if (Url != null)
DownloadContent(Url);
}
}
/// <summary>
/// Sets the KML stream source.
/// </summary>
/// <param name="stream">A stream to a KML or KMZ file.</param>
/// <remarks>
/// Use this method if you need to load KML from a local file or
/// file stream.
/// </remarks>
public void SetSource(Stream stream)
{
_url = null;
_context = new KmlLayerContext { Images = new Dictionary<string, ImageBrush>() }; // reset the context
SetSourceInternal(stream);
if (IsInitialized) // else wait for Initialize to parse the stream
{
IsInitialized = false; // will raise again Initialized event
if (ChildLayers.Any())
ChildLayers.Clear();
Name = null;
Refresh();
}
}
/// <summary>
/// If the region matches the map extent, download the URL immediately
/// else set the flag NeedRefreshOnRegion for further refresh
/// </summary>
/// <param name="region">The region.</param>
private void ConditionalRefresh(Envelope region)
{
if (IsInRegion(Map, region))
{
// Download the url
_context = new KmlLayerContext { Images = new Dictionary<string, ImageBrush>() }; // reset the context
_isLoading = true;
NeedRefreshOnRegion = false;
if (Url != null)
DownloadContent(Url);
}
else
{
// Delay refresh until the map fits the KML region
NeedRefreshOnRegion = true;
if (ChildLayers.Any())
ChildLayers.Clear();
if (!IsInitialized)
base.Initialize(); // call Initialize though else could wait indefinitively for it
}
}
/// <summary>
/// Refreshes the KML layer by downloading and parsing the KML document.
/// </summary>
public void Refresh()
{
if (_isLoading)
return; // refresh already on the way
_isLoaded = false;
if (!Visible) // delay the refresh until the layer is visible
{
if (!IsInitialized)
base.Initialize(); // call Initialize though else could wait indefinitively for it
return;
}
InitializationFailure = null;
if (Url != null)
{
// Download again the url
_context = new KmlLayerContext { Images = new Dictionary<string, ImageBrush>() }; // reset the context
_isLoading = true;
DownloadContent(Url);
}
else if (_context != null && _context.Element != null)
{
// SetSource may have been called
_isLoading = true;
ParseKmlDocument();
}
else
{
InitializationFailure = new ArgumentException(Properties.Resources.Generic_UrlNotSet, "Url");
ChildLayers.Clear();
if (!IsInitialized)
base.Initialize();
}
}