Android引路蜂地图开发示例：基本知识

在正式介绍Android引路蜂地图开发包示例前，有必要先对一些通用的知识进行说明。
1.首先是开放环境。Android 推荐的开发环境是Eclipse，我们的例子也就以Eclipse作为开发IDE。
2.添加Android引路蜂地图开发包库。打开Android属性窗口，添加External JARs。把libgisengine.jar 添加到项目中，如下图所示。

一般可以把libgisengine.jar放在项目的lib 子目录下。

3. 设置license文件。引路蜂地图开发包需要有正确的license文件才能正常运行。license分两部分，一个是guidebee.lic ,一般复制到res aw目录下。

license的另一部分，需在代码中设置与guidebee.lic对应的序列号。

InputStream inputStream = getResources().openRawResource(
     R.raw.guidebee);
   LicenceManager licenceManager = LicenceManager
     .getInstance(inputStream);
   long keys[] = { 0x41c0df1c118b1831L, 0x21884a37bde642bcL,
     0x15c4d489531ac173L, 0x5f9e69136c1e3268L,
     -0x3adaa84e455c5acL, 0x2095f679b184dbdfL, };
   licenceManager.addLicence("GuidebeeMap_JavaSE", keys);

4. 缺省的gis.drawing实现。libgisengine.jar 可以同时用于android和Java SE平台开发。android和Java SE平台用来绘图的API不尽相同。
引路蜂地图开发包示例对不同平台的Graphics进行了抽象。从而可以让同一个库用于不同平台。
在Android平台上，随libgisengine.jar一起使用的还有 AndroidGraphicsFactory.java ,AndroidGraphics.java, AndroidFont.java,AndroidImage.java .这几个类是以源码提供的，是在Android平台上对gis.drawing接口定义的缺省实现。开发人员也可以自行修改并添加到自己的地图项目中。

5. 项目AndroidGISEngineTutorial，所有的例子都在项目AndroidGISEngineTutorial中。这里对几个共用的类进行一些说明。
在包com.pstreets.gisengine定义了
AndroidGISEngineApplication 程序应用类，在这里对license进行了设置，并定义了一些全局共享对象，如RasterMap等，license和RasterMap就所有实例共有的，并且只需要实例化一次。所以在AndroidGISEngineApplication 中进行初始化。
AndroidGISEngineTutorial 为实例的起始Activity,为ListActivity的子类，列出了所有其它实例。这个类基本借用了Android SDK中ApiDemos的代码。
GuidebeeMapView 为地图显示类。为View的子类，前文说过引路蜂地图开发包中RasterMap是一个“智能地图”图像。可以将地图放在任何可以显示Image的地方。GuidebeeMapView主要重载了public void onDraw(Canvas canvas)，用于显示地图。在开发中，也可以使用其它方法来显示地图，比如按钮上，ImageView上，SurfaceView 等， GuidebeeMapView也响应TouchEvent用于平移地图。在实际应用中也可以定义不同的Gester来放大，缩小，移动地图，这些都可以由开发人员自己定制。需要注意的引路蜂地图开发包内部是多线程实现，在UI线程之外调用UI线程方法要使用合适的方法。GuidebeeMapView中使用post来发消息个UI线程以更新地图。
SharedMapInstance 定义了一些共享类对象。为所有实例公用。

6. AndroidGISEngineApplication定义
AndroidGISEngineApplication的详细定义如下

//------------------------------------------------------------------------------
//                         COPYRIGHT 2011 GUIDEBEE
//                           ALL RIGHTS RESERVED.
//                     GUIDEBEE CONFIDENTIAL PROPRIETARY
///////////////////////////////////// REVISIONS ////////////////////////////////
// Date       Name                 Tracking #         Description
// ---------  -------------------  ----------         --------------------------
//22JAN2011  James Shen                              Initial Creation
////////////////////////////////////////////////////////////////////////////////
//--------------------------------- PACKAGE ------------------------------------
package com.pstreets.gisengine;
 
//--------------------------------- IMPORTS ------------------------------------
import java.io.InputStream;
 
import android.app.Application;
import android.preference.PreferenceManager;
 
import com.mapdigit.gis.MapLayer;
import com.mapdigit.gis.raster.MapConfiguration;
import com.mapdigit.gis.raster.MapTileDownloadManager;
import com.mapdigit.gis.raster.RasterMap;
import com.mapdigit.licence.InvalidLicenceException;
import com.mapdigit.licence.LicenceManager;
import com.pstreets.gisengine.drawing.AndroidGraphicsFactory;
 
//[------------------------------ MAIN CLASS ----------------------------------]
//--------------------------------- REVISIONS ----------------------------------
//Date       Name                 Tracking #         Description
//--------   -------------------  -------------      --------------------------
//22JAN2011  James Shen                              Initial Creation
////////////////////////////////////////////////////////////////////////////////
/**
 * GIS Engine tutorial application. Just feed the licence info.
 * <hr>
 * <b>© Copyright 2011 Guidebee, Inc. All Rights Reserved.</b>
 *
 * @version 1.00, 22/01/11
 * @author Guidebee Pty Ltd.
 */
public class AndroidGISEngineApplication extends Application {
 
 @Override
 public void onCreate() {
  PreferenceManager.setDefaultValues(this, R.xml.default_values, false);
  try {
   InputStream inputStream = getResources().openRawResource(
     R.raw.guidebee);
   LicenceManager licenceManager = LicenceManager
     .getInstance(inputStream);
   long keys[] = { 0x41c0df1c118b1831L, 0x21884a37bde642bcL,
     0x15c4d489531ac173L, 0x5f9e69136c1e3268L,
     -0x3adaa84e455c5acL, 0x2095f679b184dbdfL, };
   licenceManager.addLicence("GuidebeeMap_JavaSE", keys);
   MapConfiguration.setParameter(MapConfiguration.IS_CACHE_ON, true);
   MapConfiguration.setParameter(
     MapConfiguration.WORKER_THREAD_NUMBER, 4);
   MapConfiguration.setParameter(
     MapConfiguration.IGNORE_MAP_TYPE_FOR_STORED_MAP, false);
   MapLayer.setAbstractGraphicsFactory(AndroidGraphicsFactory
     .getInstance());
   inputStream.close();
   SharedMapInstance.mapImage = MapLayer.getAbstractGraphicsFactory()
     .createImage(512, 512);
   SharedMapInstance.mapGraphics = SharedMapInstance.mapImage
     .getGraphics();
   SharedMapInstance.mapTileDownloadManager
          = new MapTileDownloadManager();
 
   try {
    SharedMapInstance.map = new RasterMap(1024, 1024,
      SharedMapInstance.mapTileDownloadManager);
   } catch (InvalidLicenceException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
   }
 
   SharedMapInstance.map.setViewSize(512,512);
   SharedMapInstance.mapTileDownloadManager.start();
 
  } catch (Exception e) {
 
  }
 }
 
 @Override
 public void onTerminate() {
  if (SharedMapInstance.mapTileDownloadManager != null) {
   SharedMapInstance.mapTileDownloadManager.stop();
  }
 }
}

47-54 行 设置license信息。
55-59 行 对地图进行配置。可以配置是否使用缓存，工作线程数目，工作线程数目指可以同时下载地图图片的线程数目。
60 行 将Android平台的Gis.Drawing实现连接到地图开发库。
63-79 行 初始化地图对象。mapImage ，mapGraphics是用来显示地图的Bitmap对象，GuidebeeMapView最终在屏幕上显示这个Bitmap对象。一般mapImage 大小需要大于屏幕上显示区域。由于Android手机可以响应屏幕转动，为避免每次需从新设置mapImage ，可以将mapImage 大小设置成比手机屏幕长边大些。以256倍数为优。一般setViewSize可以设成和mapImage 大小一致。而RasterMap本身可以设成比mapImage大些，从而可以提高地图响应性能，以mapImage 的两倍到三倍为好。越大需要的内存越大，在开发过程要综合考虑性能和内存的关系。 RasterMap大小>mapImage大小>=屏幕显示区域大小。
7. GuidebeeMapView 的Layout很简单，如下所示

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android=http://schemas.android.com/apk/res/android
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
  <com.pstreets.gisengine.GuidebeeMapView
     android:id="@+id/guidebeemap_view"
     android:layout_width="fill_parent"
     android:layout_height="fill_parent" />
  
</LinearLayout>

GuidebeeMapView类定义如下：

package com.pstreets.gisengine;
 
import android.content.Context;
import android.graphics.Bitmap;
import android.graphics.Canvas;
import android.graphics.Paint;
import android.util.AttributeSet;
import android.view.MotionEvent;
import android.view.View;
 
import com.mapdigit.gis.raster.IMapDrawingListener;
import com.mapdigit.gis.raster.IReaderListener;
 
public class GuidebeeMapView extends View implements IReaderListener,
  IMapDrawingListener {
 
  
 Paint p = new Paint();
 boolean isPan = false;
 private float oldX = -1;
 private float oldY = -1;
 
 public boolean onTouchEvent(MotionEvent event) {
  int action = event.getAction();
  switch (action) {
  case MotionEvent.ACTION_DOWN:
   oldX = event.getRawX();
   oldY = event.getRawY();
   isPan = true;
   break;
  case MotionEvent.ACTION_UP:
   oldX = event.getRawX();
   oldY = event.getRawY();
   isPan = false;
   break;
  case MotionEvent.ACTION_MOVE:
   if (isPan) {
    panMap(event.getRawX(), event.getRawY());
    oldX = event.getRawX();
    oldY = event.getRawY();
   }
   break;
  }
  return true;
 }
 
 private void panMap(float x, float y) {
  float dx = x - oldX;
  float dy = y - oldY;
  if (!(dx == 0 && dy == 0))
   SharedMapInstance.map.panDirection((int) dx, (int) dy);
 
 }
 
 final Runnable updateMapCanvas = new Runnable() {
  public void run() {
   invalidate();
  }
 };
 
 public GuidebeeMapView(Context context, AttributeSet attrs, int defStyle) {
  super(context, attrs, defStyle);
  initGuidebeeMap();
 
 }
 
 public GuidebeeMapView(Context context, AttributeSet attrs) {
  super(context, attrs);
  initGuidebeeMap();
 
 }
 
 public GuidebeeMapView(Context context) {
  super(context);
  initGuidebeeMap();
 
 }
 
  
 public void onDraw(Canvas canvas) {
  super.onDraw(canvas);
 
  Bitmap bitmap = (Bitmap) SharedMapInstance.mapImage.getNativeImage();
  int mapWidth=SharedMapInstance.mapImage.getWidth();
  int mapHeight=SharedMapInstance.mapImage.getHeight();
  int screenWidth=getWidth();
  int screenHeight=getHeight();
  canvas.drawBitmap(bitmap, (screenWidth-mapWidth)/2,  (screenHeight-mapHeight)/2, p);
 }
 
 private void initGuidebeeMap() {
  SharedMapInstance.map.setMapDrawingListener(this);
  SharedMapInstance.mapTileDownloadManager.setReaderListener(this);
   
 }
  
 
 @Override
 public void readProgress(int bytes, int total) {
  //System.out.println(bytes);
 
 }
 
 @Override
 public void done() {
  SharedMapInstance.map.paint(SharedMapInstance.mapGraphics);
 
  post(updateMapCanvas);
 
 }
}

94 ,95 添加事件处理函数。
其中 SharedMapInstance.mapTileDownloadManager.setReaderListener(this) 用于监视下载进度。
public void readProgress(int bytes, int total) bytes是下载字节数，total 为该此下载总字节数（可能为0，0表示总长事先未知）
SharedMapInstance.map.setMapDrawingListener(this); 监视图片下载进度。public void done() 表示单个地图图片下载完成。一般在该事件处理中的屏幕上刷新地图。
8. 引路蜂地图开发包对Android平台依赖性不大，可以用于Android各个版本。例子以目前的最低版本1.5为例，可以运行于1.5以上各个平台。
9. 为和Google MapView 有所区别，例子将以Bing中国地图为例，要改成Google地图，只需将例子中地图类型从MapType.MICROSOFTCHINA 改成 MapType.GOOGLECHINA