/*
         * A function to handle the click event after the user clicks 'Add'
         */
        private void btnAdd_Click(object sender, EventArgs e)
        {
            // disable the button immediately
            this.btnAdd.Enabled = false;

            // create a download progress dialog and show it
            Dialogs.Processing.ProgressDialog downloadProgress = new Processing.ProgressDialog();
            downloadProgress.Show(this);

            // attempt to add the selected map to the user ArcGIS instance
            log.Debug("Attempting to create a new feature class and add it to the map.");
            try
            {
                // get the key out of the key/value pair object
                log.Debug("Fetching the user selected MapId from the DataGridView.");
                string MapId = ((MapsEngine.DataModel.gme.Map) this.dataGridGlobeDirectory.SelectedRows[0].DataBoundItem).id;
                log.Debug("MapId: " + MapId);

                // create a new empty Feature Class to hold the Google Maps Engine catalog results
                log.Debug("Creating a new empty feature class to hold the Google Maps Enigne catalog results");
                IFeatureClass fc = Extension.Data.GeodatabaseUtilities.createGoogleMapsEngineCatalogFeatureClass(ref log, ref ext);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(false, "Preparing to download map '" + MapId + "'.", 1, 0);

                // create a new reference to the Google Maps API.
                log.Debug("Creating a new instance of the Google Maps Engine API object.");
                MapsEngine.API.GoogleMapsEngineAPI api = new MapsEngine.API.GoogleMapsEngineAPI(ref log);

                // create a new map object to be defined by the API or MapRoot
                log.Debug("Creating a new empty Map object.");
                MapsEngine.DataModel.gme.Map map;

                // query Google Maps Engine for the layers within this map
                log.Debug("Fetching the Google Maps Engine layers for this map.");
                map = api.getMapById(ext.getToken(), MapId);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(false, "Building local geodatabase for map '" + MapId + "'.", 1, 0);

                // create a new Feature Class Management object
                Data.GoogleMapsEngineFeatureClassManagement fcMngmt = new Data.GoogleMapsEngineFeatureClassManagement(api);

                // populate a feature for every Google Maps Engine Map
                log.Debug("Populate the feature class with the specific MapId");
                fcMngmt.populateFCWithGoogleMapsEngineMap(ref fc, ref map);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(true, "Adding '" + MapId + "' layer to your map.", 1, 1);

                // add the new feature class to the map (auto selecting type "map")
                ext.addFeatureClassToMapAsLayer(ref fc, Properties.Resources.GeodatabaseUtilities_schema_LayerName
                                                , "" + Properties.Resources.GeodatabaseUtilities_schema_AssetType_Name + " = 'map'");

                // retrieve the Google Maps Engine WMS URL
                string url = Properties.Settings.Default.gme_wms_GetCapabilities;

                // replace the map identifier and auth token
                url = url.Replace("{mapId}", MapId);
                url = url.Replace("{authTokenPlusSlash}", ext.getToken().access_token + "/");

                // proactively add the viewable layer (WMS or WMTS) to the map
                ext.addWebMappingServiceToMap(new Uri(url));
            }
            catch (System.Exception ex)
            {
                // log error and warn user
                log.Error(ex);

                // hide the download progress, if it is visible
                downloadProgress.Hide();

                // warn the user of the error
                ext.displayErrorDialog(Properties.Resources.dialog_GoogleMapsEngineDirectoryListing_btnAdd_Click_unknownerror + "\n" + ex.Message);
            }

            // close the dialog immediately
            this.Close();
        }
        /*
         * A function to handle the click event after the user clicks 'Add'
         */
        private void btnAdd_Click(object sender, EventArgs e)
        {
            // disable the button immediately
            this.btnAdd.Enabled = false;

            // create a download progress dialog and show it
            Dialogs.Processing.ProgressDialog downloadProgress = new Processing.ProgressDialog();
            downloadProgress.Show(this);

            // attempt to add the selected map to the user ArcGIS instance
            log.Debug("Attempting to create a new feature class and add it to the map.");
            try
            {
                // get the key out of the key/value pair object
                log.Debug("Fetching the user selected MapId from the DataGridView.");
                string MapId = ((MapsEngine.DataModel.gme.Map)this.dataGridGlobeDirectory.SelectedRows[0].DataBoundItem).id;
                log.Debug("MapId: " + MapId);

                // create a new empty Feature Class to hold the Google Maps Engine catalog results
                log.Debug("Creating a new empty feature class to hold the Google Maps Enigne catalog results");
                IFeatureClass fc = Extension.Data.GeodatabaseUtilities.createGoogleMapsEngineCatalogFeatureClass(ref log, ref ext);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(false, "Preparing to download map '" + MapId + "'.", 1, 0);
                
                // create a new reference to the Google Maps API.
                log.Debug("Creating a new instance of the Google Maps Engine API object.");
                MapsEngine.API.GoogleMapsEngineAPI api = new MapsEngine.API.GoogleMapsEngineAPI(ref log);

                // create a new map object to be defined by the API or MapRoot
                log.Debug("Creating a new empty Map object.");
                MapsEngine.DataModel.gme.Map map;

                // query Google Maps Engine for the layers within this map
                log.Debug("Fetching the Google Maps Engine layers for this map.");
                map = api.getMapById(ext.getToken(), MapId);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(false, "Building local geodatabase for map '" + MapId + "'.", 1, 0);

                // create a new Feature Class Management object
                Data.GoogleMapsEngineFeatureClassManagement fcMngmt = new Data.GoogleMapsEngineFeatureClassManagement(api);

                // populate a feature for every Google Maps Engine Map
                log.Debug("Populate the feature class with the specific MapId");
                fcMngmt.populateFCWithGoogleMapsEngineMap(ref fc, ref map);

                // publish a new download event to the extension
                ext.publishRaiseDownloadProgressChangeEvent(true, "Adding '" + MapId + "' layer to your map.", 1, 1);

                // add the new feature class to the map (auto selecting type "map")
                ext.addFeatureClassToMapAsLayer(ref fc, Properties.Resources.GeodatabaseUtilities_schema_LayerName
                    , "" + Properties.Resources.GeodatabaseUtilities_schema_AssetType_Name + " = 'map'");

                // retrieve the Google Maps Engine WMS URL
                string url = Properties.Settings.Default.gme_wms_GetCapabilities;

                // replace the map identifier and auth token
                url = url.Replace("{mapId}", MapId);
                url = url.Replace("{authTokenPlusSlash}", ext.getToken().access_token + "/");

                // proactively add the viewable layer (WMS or WMTS) to the map
                ext.addWebMappingServiceToMap(new Uri(url));
            }
            catch (System.Exception ex)
            {
                // log error and warn user
                log.Error(ex);

                // hide the download progress, if it is visible
                downloadProgress.Hide();

                // warn the user of the error
                ext.displayErrorDialog(Properties.Resources.dialog_GoogleMapsEngineDirectoryListing_btnAdd_Click_unknownerror + "\n" + ex.Message);
            }

            // close the dialog immediately
            this.Close();
        }