Class with infos needed to be able to refresh and reparse a KML layer
        /// <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: &lt;href&gt;, &lt;Style&gt;, &lt;Icon&gt;, &lt;IconStyle&gt;, 
        /// &lt;StyleMap&gt;, &lt;NetworkLink&gt;, and &lt;styleUrl&gt;. 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">
        /// &lt;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"&gt;
        /// 
        ///   &lt;Grid x:Name="LayoutRoot" Background="White"&gt;
        ///     &lt;esri:Map Background="White" HorizontalAlignment="Left" Name="Map1" VerticalAlignment="Top"
        ///           WrapAround="True" Height="276" Width="376" Margin="12,12,0,0"&gt;
        ///       &lt;esri:Map.Layers&gt;
        ///         &lt;esri:LayerCollection&gt;
        ///           &lt;esri:ArcGISTiledMapServiceLayer 
        ///                 Url="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" /&gt;
        ///           &lt;esri:KmlLayer Url="Test.kml"/&gt;
        ///         &lt;/esri:LayerCollection&gt;
        ///       &lt;/esri:Map.Layers&gt;
        ///     &lt;/esri:Map&gt;
        ///   &lt;/Grid&gt;
        /// &lt;/UserControl&gt;
        /// </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">
        /// &lt;?xml version="1.0" encoding="UTF-8"?&gt;
        /// &lt;kml xmlns="http://www.opengis.net/kml/2.2"&gt;
        ///   &lt;Document&gt;
        ///     &lt;name&gt;Simple Placemark KML&lt;/name&gt;
        ///     &lt;visibility&gt;1&lt;/visibility&gt;
        ///     &lt;open&gt;1&lt;/open&gt;
        ///     &lt;Placemark&gt;
        ///       &lt;name&gt;Simple placemark&lt;/name&gt;
        ///       &lt;visibility&gt;true&lt;/visibility&gt;
        ///       &lt;open&gt;0&lt;/open&gt;
        ///       &lt;Point&gt;
        ///         &lt;coordinates&gt;-122.0822035425683,37.42228990140251,0&lt;/coordinates&gt;
        ///       &lt;/Point&gt;
        ///     &lt;/Placemark&gt;
        ///   &lt;/Document&gt;
        /// &lt;/kml&gt;
        /// </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();
			}
		}