map_suite_mobile_for_android_quick_start_guide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
map_suite_mobile_for_android_quick_start_guide [2017/02/20 07:42] tgwikiupdate [Download the Sample] |
map_suite_mobile_for_android_quick_start_guide [2017/03/21 05:54] (current) tgwikiupdate Review page |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Map Suite Quick Start Guide For Android ====== | + | ====== Map Suite Quickstart Guide For Android ====== |
| - | <div msgbox>The Map Suite Android Edition illustrated QuickStart Guide will guide you through the process of creating a sample application and will help you become familiar with Map Suite. This edition of the QuickStart Guide supports Android Edition 10.0.0 and higher, and will show you how to create an Android application using Map Suite Android Edition. | + | <div msgbox>The Map Suite Mobile for Android illustrated Quickstart Guide will guide you through the process of creating a sample application and will help you become familiar with Map Suite. This edition of the Quickstart Guide supports Map Suite Mobile for Android 10.0.0 and higher and will show you how to create an Android application using Map Suite Mobile for Android. |
| - | If you want to build an iOS application using the standard Map Suite iOS Edition product, please see the [[map_suite_mobile_for_iOS_quick_start_guide|iOS QuickStart Guide]] instead.</div> | + | If you want to build an iOS application using the standard Map Suite Mobile for iOS product, please see the [[map_suite_mobile_for_iOS_quick_start_guide|iOS QuickStart Guide]] instead.</div> |
| Welcome to Map Suite™ from ThinkGeo, a full-featured mapping control that makes it easy for any Microsoft .NET developer to add mapping functionality to a Microsoft .NET application quickly and efficiently. Using the intuitive object model, even developers inexperienced with Geographic Information Systems (GIS) can have fully functional maps working in minutes. | Welcome to Map Suite™ from ThinkGeo, a full-featured mapping control that makes it easy for any Microsoft .NET developer to add mapping functionality to a Microsoft .NET application quickly and efficiently. Using the intuitive object model, even developers inexperienced with Geographic Information Systems (GIS) can have fully functional maps working in minutes. | ||
| Line 11: | Line 11: | ||
| How do we begin taking advantage of the power of Map Suite? The best way to learn is to make a sample application with it. | How do we begin taking advantage of the power of Map Suite? The best way to learn is to make a sample application with it. | ||
| ===== Download the Sample ===== | ===== Download the Sample ===== | ||
| - | <faicon fa fa-download fa-lg> {{https://github.com/ThinkGeo/QuickstartSample-ForAndroid|Download Sample Code From This Exercise}} | + | <faicon fa fa-download fa-lg> {{https://github.com/ThinkGeo/QuickstartSample-ForAndroid|Download Sample Code From GitHub}} |
| ===== Setting up the Environment ===== | ===== Setting up the Environment ===== | ||
| - | Please follow our [[Map Suite Android Edition Installation Guide|Android Edition Installation Guide]] for Xamarin Android development environment. | + | Please follow our [[Map Suite Mobile for Android Installation Guide|Map Suite Mobile for Android Installation Guide]] for Xamarin Android development environment. |
| - | Let's start by creating a new Android project in Microsoft Visual Studio (2012 or newer) named HelloWorld (see Figure 1). We can create the project with .NET Framework 4.5. | + | Let's start by creating a new Android project in Microsoft Visual Studio (2012 or newer) named Quickstart(see Figure 1). We can create the project with .NET Framework 4.5. |
| - | {{androidedition:QSG_Android_Img01.png}} | + | {{mapsuite10:android:Map_Suite_QSG_NewProject.png}} |
| \\ | \\ | ||
| //Figure 1. Creating a new project in the Visual Studio IDE.// | //Figure 1. Creating a new project in the Visual Studio IDE.// | ||
| - | The project HelloWorld is created in a new solution called HelloWorld. The wizard creates a single Android Application. Choose Android version (4.0.3 or higher) for the project: | + | The project QuickstartSample is created in a new solution called QuickstartSample. The wizard creates a single Android Application. Choose Android version (4.0.3 or higher) for the project: |
| - | {{androidedition:QSG_Android_Select_API.png}} | + | {{mapsuite10:android:Map_Suite_QSG_AndroidVersion.png}} |
| Now we are going to install MapSuite Mobile for iOS NuGet package. Let's open NuGet Manager dialog and install following three NuGet packages. | Now we are going to install MapSuite Mobile for iOS NuGet package. Let's open NuGet Manager dialog and install following three NuGet packages. | ||
| - | {{mapsuite10:android:open_nuget_manager.png}} | + | {{mapsuite10:android:Map_Suite_QSG_NuGetManager.png}} |
| \\ | \\ | ||
| //Figure 2. Open NuGet Manager UI in the Visual Studio IDE.// | //Figure 2. Open NuGet Manager UI in the Visual Studio IDE.// | ||
| - | {{mapsuite10:android:android_install_android.png}} | + | {{mapsuite10:android:Map_Suite_QSG_InstallAndroidPackage.png}} |
| \\ | \\ | ||
| //Figure 3. Install Android Package.// | //Figure 3. Install Android Package.// | ||
| - | {{mapsuite10:android:android_install_shapefile.png}} | ||
| - | \\ | ||
| - | //Figure 4. Install Shapefile Package.// | ||
| Next we need to prepare our map data. There are two ways to copy data to phone or tablet. The first way is using android ddms tool. We can find the tool under "[android-sdk]\tools\ddms.bat". | Next we need to prepare our map data. There are two ways to copy data to phone or tablet. The first way is using android ddms tool. We can find the tool under "[android-sdk]\tools\ddms.bat". | ||
| Line 46: | Line 43: | ||
| {{androidedition:QSG_Android_AddData1.jpg}} | {{androidedition:QSG_Android_AddData1.jpg}} | ||
| - | Create a new folder under sdcard named "Android Sample". | + | Create a new folder under sdcard named "Android.Sample". |
| {{androidedition:QSG_Android_AddData2.jpg}} | {{androidedition:QSG_Android_AddData2.jpg}} | ||
| Line 56: | Line 53: | ||
| The second way to copy data to phone or tablet is by using code. Create a new folder named AppData under "Assets", then add the map data to it. Make sure the resources’ build action is AndroidAsset. | The second way to copy data to phone or tablet is by using code. Create a new folder named AppData under "Assets", then add the map data to it. Make sure the resources’ build action is AndroidAsset. | ||
| - | {{androidedition: QSG_Android_PrepareData.jpg}} | + | {{mapsuite10:android:Map_Suite_QSG_AppData.png}} |
| Then we can use code to copy data to a special location. There are two kinds of data paths: | Then we can use code to copy data to a special location. There are two kinds of data paths: | ||
| - | One is under our application, like "/data/data/HelloWorld.HelloWorld/AppData/". | + | One is under our application, like "/data/data/QuickstartSample.QuickstartSample/AppData/". |
| The other one is under the sdcard, like "/mnt/sdcard/Android.Sample/GetStarted/". | The other one is under the sdcard, like "/mnt/sdcard/Android.Sample/GetStarted/". | ||
| Line 97: | Line 94: | ||
| ===== Adding the Map View to our App ===== | ===== Adding the Map View to our App ===== | ||
| - | |||
| - | We are going to add more project | ||
| - | |||
| - | {{androidedition:QSG_Android_AddReference.png}} | ||
| - | |||
| - | **Note: Although it is not a ThinkGeo assembly, you also need to add "System.Windows.dll " to the references. System.Windows can be found on the .NET tab of the Add Reference dialog. If you don't do this, you will get the following error when you compile the project:**"The type 'System.Collections.Specialized.INotifyCollectionChanged' is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Windows, Version=2.0.5.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e, Retargetable=Yes'." | ||
| - | |||
| - | {{androidedition:QSG_Android_AddSystemWindows.png}} | ||
| Open the Resources\layout\Main.axml file. Remove the default button node, and insert MapView node in the axml. | Open the Resources\layout\Main.axml file. Remove the default button node, and insert MapView node in the axml. | ||
| Line 121: | Line 110: | ||
| </code> | </code> | ||
| - | Now we have our "AndroidEdition.dll" and "MapSuitePortableCore.dll" referenced and a MapView added. | + | Now we have our "ThinkGeo.MapSuite.Android.dll" and "ThinkGeo.MapSuite.dll" referenced and a MapView added. |
| - | ===== Map Suite Android "Hello World" Sample ===== | + | ===== Map Suite Android "Quickstart Sample" ===== |
| After completing this section, we'll be able to draw a map with the MapView using our own data. First, let's have a look at the data and the important objects we'll use. | After completing this section, we'll be able to draw a map with the MapView using our own data. First, let's have a look at the data and the important objects we'll use. | ||
| - | ==== Map Suite Android "Hello World" ==== | + | ==== Map Suite Android "Quickstart Sample" ==== |
| - | The first step in creating our "Hello World" sample application is to set references to the ''ThinkGeo.MapSuite'', ''ThinkGeo.MapSuite.Android'' and ''ThinkGeo.MapSuite.Shapes'' namespaces at the very top of our code, since we'll use many classes within them. Set the reference like this: | + | The first step in creating our "Quickstart sample" application is to set references to the "ThinkGeo.MapSuite", "ThinkGeo.MapSuite.Android" and "ThinkGeo.MapSuite.Shapes" namespaces at the very top of our code, since we'll use many classes within them. Add the references like this: |
| <code csharp> | <code csharp> | ||
| Line 136: | Line 125: | ||
| ==== Display World Map ==== | ==== Display World Map ==== | ||
| - | Now the project is ready, Map Suite Runtime license is required for running and debugging your product. Please open the Product Center, then generate your license by steps like login account → activate or start evaluation → continue debugging → get runtime license. For more details, please refer to (http://wiki.thinkgeo.com/wiki/map_suite_runtime_license_guide_for_mobile). | + | Now the project is ready, Map Suite Runtime license is required for running and debugging your product. Please open the Product Center, then generate your license. For more details, please refer to (http://wiki.thinkgeo.com/wiki/map_suite_runtime_license_guide_for_mobile). |
| Now, Let's add a base overlay to display the world map witch called "WorldStreetsAndImageryOverlay". | Now, Let's add a base overlay to display the world map witch called "WorldStreetsAndImageryOverlay". | ||
| Line 159: | Line 148: | ||
| | | ||
| // Set a proper extent for the map. The extent is the geographical area you want it to display. | // Set a proper extent for the map. The extent is the geographical area you want it to display. | ||
| - | mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26); | + | mapView.CurrentExtent = new RectangleShape(-134, 70, -56, 7); |
| } | } | ||
| </code> | </code> | ||
| - | If we compile and run what we have now, our map should look like the one below. (see Figure 3). | + | If we compile and run what we have now, our map should look like the one below. (see Figure 5). |
| - | {{androidedition:QSG_Android_Img10.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowBaseMap.png?300}} |
| \\ | \\ | ||
| - | //Figure 3. A simple map of Europe.// | + | //Figure 5. A sample map of Europe.// |
| ==== Display Countries On Map ==== | ==== Display Countries On Map ==== | ||
| - | Now let's look at a code sample to bring this concept to fruition. We'll look at Shapefiles relating to the entire world. In our example, we have one such Shapefile: | + | Now let's look at a code sample to bring this concept to fruition. We'll look at ShapeFiles relating to the entire world. In our example, we have one such ShapeFile: |
| - | * Worldwide country borders (Countries02.shp) | + | * Worldwide country borders (cntry02.shp) |
| (NOTE: The data used here can be found in the attached sample above at "\Assets\AppData" folder. The data files' build action should be “AndroidAssets”.) | (NOTE: The data used here can be found in the attached sample above at "\Assets\AppData" folder. The data files' build action should be “AndroidAssets”.) | ||
| - | Our next step is to define and add our layers. All of our sample code is placed in the OnCreate method of the MainActivity.cs. So our MapView can load and render the data, we can add logic to check the data to avoid coping it every time. | + | Our next step is to define and add our layers. All of the following code can be placed in the "OnCreate" method of the MainActivity.cs. So our MapView can load and render the data, we can add logic to check the data to avoid coping it every time. |
| <code csharp> | <code csharp> | ||
| Line 184: | Line 173: | ||
| SetContentView(Resource.Layout.Main); | SetContentView(Resource.Layout.Main); | ||
| - | // Copy the required shapefiles to Device. | + | // Copy the required ShapeFiles to Device. |
| string targetDirectory = (@"/mnt/sdcard/Android.Sample/GetStarted/"); | string targetDirectory = (@"/mnt/sdcard/Android.Sample/GetStarted/"); | ||
| CopySampleData(targetDirectory); | CopySampleData(targetDirectory); | ||
| Line 211: | Line 200: | ||
| overlay.Layers.Add(worldLayer); | overlay.Layers.Add(worldLayer); | ||
| - | mapView.Overlays.Add("Countries02", overlay); | + | mapView.Overlays.Add("cntry02", overlay); |
| - | mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26); | + | mapView.CurrentExtent = new RectangleShape(-134, 70, -56, 7); |
| } | } | ||
| </code> | </code> | ||
| Line 219: | Line 208: | ||
| If we compile and run what we have now, our map should look like the one below. (see Figure 4). | If we compile and run what we have now, our map should look like the one below. (see Figure 4). | ||
| - | {{androidedition:QSG_Android_Img08.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowShapeFile.png?300}} |
| \\ | \\ | ||
| - | //Figure 4. A simple map of Europe.// | + | //Figure 4. A sample map of Europe.// |
| - | So what has occurred here? We've created a layer and added it to the Map, and the Map has rendered it according to its default style parameters. We've also used ZoomLevel to display the map the way we want. | + | So what has occurred here? We have created a layer and added it to the map and the map has rendered according to its default style parameters. Also, we have used ZoomLevel to display the map the way that we want. |
| - | **NOTE:** It is important that the MapUnit property of a Map object be set using the ''GeographyUnit'' Enumeration. This is because the coordinates stored in a Shapefile can be in decimal degrees (a format of latitude and longitude), feet, meters, or another unit system, and our map has no way to know what the Shapefile's unit of measurement is until we tell it. This information is normally found somewhere in the Shapefile's documentation (also referred to as its metadata), or within its supplemental data file, as discussed in the section on Shapefiles. It may also come as a separate .txt, .xml, or .html file that begins with the same file name as the main Shapefile. | + | **NOTE:** It is important that the "MapUnit" property of a Map object be set using the "GeographyUnit" enumeration. This is because the coordinates stored in a ShapeFile can be in DecimalDegrees (a format of latitude and longitude), feet, meters, or another unit system. Our map has no way to know what the ShapeFile's unit of measurement is until we set it. This information is normally found somewhere in the ShapeFile's documentation (also referred to as its metadata), or within its supplemental data file, as discussed in the section on ShapeFiles. It may also come as a separate .txt, .xml, or .html file that begins with the same file name as the main ShapeFile. |
| ==== Navigate the Map ==== | ==== Navigate the Map ==== | ||
| - | Now you can display and navigate your map. Pan by dragging the map, zoom in by double-clicking, track zoom in by drawing a rectangle with your left mouse button mouse while holding the shift key, or zoom in and out with the mouse wheel. Very powerful for just couple lines of code, isn't it? | + | With the code above, you can both display a map and navigate it. You can pan by touch on the device and move finger around; zoom in/out by pinch on the screen with two fingers; double tap to zoom in to the next zoom level. Very powerful for just couple lines of code, isn’t it? |
| - | That was an easy start! Now let's add a second Shapefile to the sample, so we'll have a total of two layers: | + | That was an easy start! Now, let's add second ShapeFile to the sample, so we'll have a total of two layers: |
| - | -World country borders ("Countries02.shp") | + | -World country borders ("cntry02.shp") |
| - | - World capitals ("WorldCapitals.shp") | + | - World capitals ("capital.shp") |
| <code csharp> | <code csharp> | ||
| Line 272: | Line 261: | ||
| overlay.Layers.Add(capitalLayer); | overlay.Layers.Add(capitalLayer); | ||
| - | mapView.Overlays.Add("Countries02", overlay); | + | mapView.Overlays.Add("cntry02", overlay); |
| - | mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26); | + | mapView.CurrentExtent = new RectangleShape(-134, 70, -56, 7); |
| } | } | ||
| </code> | </code> | ||
| - | And the result is as following (Figure 5): | + | And the result is as follows (Figure 5): |
| - | {{androidedition:QSG_Android_Img09.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowPointStyle.png?300}} |
| \\ | \\ | ||
| //Figure 5. A map of Europe with the additional borders and capitals layers displayed.// | //Figure 5. A map of Europe with the additional borders and capitals layers displayed.// | ||
| ===== How to Use TextStyle ===== | ===== How to Use TextStyle ===== | ||
| - | TextStyle is used to label items on map. While the features themselves are drawn from information in the Shapefile, they're labeled with feature names or other attributes contained in the .dbf file. For example, the Shapefile containing capitals of the world has a corresponding .dbf file with the field "CITY_NAME". We can use this field to label the cities on our map. | + | A TextStyle is used to label items on map. As every ShapeFile has a relative .dbf file that includes descriptions for every record, the most common way to use TextStyles is for labeling. For example, Capital ShapeFile's corresponding .dbf file contains the field "CITY_NAME". We can use this field to label the cities on our map. |
| - | {{androidedition:QSG_WPFDesktop_Img10.png}} | + | {{mapsuite10:android:Map_Suite_QSG_DBFDetails.png}} |
| Map Suite includes several built-in TextStyles to help us quickly apply attractive city labels. We can simply pick the TextStyle we like and use it. | Map Suite includes several built-in TextStyles to help us quickly apply attractive city labels. We can simply pick the TextStyle we like and use it. | ||
| Line 320: | Line 309: | ||
| capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.Capital3("CITY_NAME"); | capitalLabelLayer.ZoomLevelSet.ZoomLevel01.DefaultTextStyle = TextStyles.Capital3("CITY_NAME"); | ||
| capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20; | capitalLabelLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20; | ||
| - | // As the map is drawn by tiles, it needs to draw on the margin to make sure the text is complete after joining the tiles together. | + | |
| - | // Change the number below (to 0, for example) to better understand how this works. | + | |
| - | capitalLabelLayer.DrawingMarginPercentage = 50; | + | |
| LayerOverlay overlay = new LayerOverlay(); | LayerOverlay overlay = new LayerOverlay(); | ||
| overlay.Opacity = 0.8; | overlay.Opacity = 0.8; | ||
| Line 331: | Line 317: | ||
| overlay.Layers.Add(capitalLabelLayer); | overlay.Layers.Add(capitalLabelLayer); | ||
| - | mapView.Overlays.Add("Countries02", overlay); | + | mapView.Overlays.Add("cntry02", overlay); |
| - | mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26); | + | mapView.CurrentExtent = new RectangleShape(-134, 70, -56, 7); |
| } | } | ||
| </code> | </code> | ||
| Line 339: | Line 325: | ||
| The result is as follows (Figure 6): | The result is as follows (Figure 6): | ||
| - | {{androidedition:QSG_Android_Img11.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowTextStyle.png?300}} |
| \\ | \\ | ||
| //Figure 6. Europe map with TextStyle applied.// | //Figure 6. Europe map with TextStyle applied.// | ||
| - | Now that we know how to render text and symbols, let's create custom Styles and TextStyles. We'll also specify different ranges of ZoomLevels, and apply varying custom Styles and TextStyles to the same layer at different ZoomLevel ranges. | + | Now that we know how to render text and symbols, let's create customized Styles and TextStyles. We'll also specify different ranges of ZoomLevels, and apply varying customized Styles and TextStyles to the same layer at different ZoomLevel ranges. |
| <code csharp> | <code csharp> | ||
| Line 357: | Line 343: | ||
| mapView.MapUnit = GeographyUnit.DecimalDegree; | mapView.MapUnit = GeographyUnit.DecimalDegree; | ||
| | | ||
| - | |||
| WorldStreetsAndImageryOverlay worldStreetsAndImageryOverlay = new WorldStreetsAndImageryOverlay(); | WorldStreetsAndImageryOverlay worldStreetsAndImageryOverlay = new WorldStreetsAndImageryOverlay(); | ||
| mapView.Overlays.Add("WorldStreetsAndImageryOverlay", worldStreetsAndImageryOverlay); | mapView.Overlays.Add("WorldStreetsAndImageryOverlay", worldStreetsAndImageryOverlay); | ||
| Line 384: | Line 369: | ||
| // The TextStyle we set here is available from ZoomLevel06 to ZoomLevel20. | // The TextStyle we set here is available from ZoomLevel06 to ZoomLevel20. | ||
| capitalLabelLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20; | capitalLabelLayer.ZoomLevelSet.ZoomLevel06.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20; | ||
| - | |||
| - | capitalLabelLayer.DrawingMarginPercentage = 50; | ||
| LayerOverlay overlay = new LayerOverlay(); | LayerOverlay overlay = new LayerOverlay(); | ||
| Line 394: | Line 377: | ||
| overlay.Layers.Add(capitalLabelLayer); | overlay.Layers.Add(capitalLabelLayer); | ||
| - | mapView.Overlays.Add("Countries02", overlay); | + | mapView.Overlays.Add("cntry02", overlay); |
| - | mapView.CurrentExtent = new RectangleShape(5, 78, 30, 26); | + | mapView.CurrentExtent = new RectangleShape(-134, 70, -56, 7); |
| } | } | ||
| </code> | </code> | ||
| Line 402: | Line 385: | ||
| Can you imagine what the map will look like now? Below is the result. At first it looks like Figure 7, then like Figure 8 as you zoom in further. | Can you imagine what the map will look like now? Below is the result. At first it looks like Figure 7, then like Figure 8 as you zoom in further. | ||
| - | {{androidedition:QSG_Android_Img12.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowLowZoomLevel.png?300}} |
| \\ | \\ | ||
| - | //Figure 7. Map of Europe before zooming out.// | + | //Figure 7. A map of Europe with two ZoomLevels, before zooming in.// |
| - | {{androidedition:QSG_Android_Img13.png}} | + | {{mapsuite10:android:Map_Suite_QSG_ShowHeightZoomLevel.png?300}} |
| \\ | \\ | ||
| - | //Figure 8. Map of Europe after zooming out.// | + | //Figure 8. The same map with two ZoomLevels, after zooming in.// |
| ===== Summary ===== | ===== Summary ===== | ||
| Line 419: | Line 402: | ||
| - A Layer can have one-to-many ZoomLevels. ZoomLevels help to define ranges (upper and lower scales) of when a Layer should be shown or hidden. | - A Layer can have one-to-many ZoomLevels. ZoomLevels help to define ranges (upper and lower scales) of when a Layer should be shown or hidden. | ||
| - | |||
| - | <faicon fa fa-download fa-lg> {{filehistory:HelloWorld Android.zip|Download Sample Code From This Exercise}} //(1.5 MB)// | ||
map_suite_mobile_for_android_quick_start_guide.1487576574.txt.gz · Last modified: 2017/02/20 07:42 by tgwikiupdate