AutoNavi Map API
功能规格说明书
最后更新时间：2010年6月9日
? 2010高德软件有限公司保留版权.
目录
简介 (3)
API概述 (3)
com.autonavi.mapapi包的描述信息 (3)
AutoNavi Map API特点： (3)
兼容android map 接口及功能 (4)
Interface (5)
Interface ItemizedOverlay.OnFocusChangeListener (5)
Interface Overlay.Snappable (5)
Interface Projection (6)
Classes (8)
Class GeoPoint (8)
Class ItemizedOverlay
Class MapActivity (15)
Class MapController (18)
Class MapView (21)
Class https://www.doczj.com/doc/2111965400.html,youtParams (29)
Class MyLocationOverlay (33)
Class Overlay (39)
Class OverlayItem (42)
Class TrackballGestureDetector (45)
Enum (47)
Enum MapView.ReticleDrawMode (47)
简介
简介
API概述
AutoNavi Map API是高德软件公司提供的调用地图的接口方法。文档中定义了14个对象类及接口。用户的应用程序可以通过AutoNavi Map API提供的接口方法操作地图数据，实现位置相关或地图相关应用。例如，通过调用AutoNavi Map API，将地图数据整合到自己的应用中，可以将商户的地理位置信息在地图上进行标注，
以很直观的形式展现给使用者。
com.autonavi.mapapi包的描述信息
本地图包可支持第三方应用显示和控制高德的地图接口功能。要创建一个地图，需要在一个页面布局中扩展MapActivity及实现MapView类。
您必须设置"android:apiKey"才能在您的应用中使用MapView获取地图数据。在模拟器环境中，您可以通过申请调试API秘钥，进行程序开发。但在发布时，您必须申请签名证书的API秘钥，并替换MapView中的调试API秘钥。
AutoNavi Map API特点：
1.简单：
用户场景-- 新手也能做出功能强大的地图应用：
小李是大学在校生，一直酷爱编写程序。在使用android平台手机后一直想自己试做一个应用程序。在https://www.doczj.com/doc/2111965400.html,的网站上下载了api程序包和样例代码后，很容易的就开发出了简单实用的地图应用，这让小李一直兴奋不已。
2．移植性强：
用户场景--原有基于Android Map API的应用程序移植方便:
如某知名跨国公司开发的一款基于Android Map的应用服务软件，在国外非常受欢迎，用户普及率很高。想将此应用移植到中国市场进行推广，但Android Map在中国市场的不被支持。该公司用AutoNavi Map API提供的数据包直接替换Android Map API，没有进行很复杂的代码修改，所有的接口调用甚至函数名都不需要变动，直接就可以使应用正常工作，方便移植性广受好评。
3．强大的标记点：
用户场景--在地图上任意指定位置进行标记：
某知名的点评网站通过调用AutoNavi Map API地图数据开发了一款提供位置服务的应用软件。并将商户的地理信息在地图上进行标注，绘制相应的位置信息描述后，网站信息的展现更加直观了，实用功能性更强。用户可以便捷的查询到商户所在的地理位置。使网站的用户访问量明显提升了。
4．准确高效的定位功能：
用户场景--随时随地查询定位：
某知名的搜索房屋信息的网站开发了一款基于AutoNavi Map API的提供了定位功能的手机应用软件。小李是房地产的销售，他经常要带客户去转楼盘。在这款有定位功能应用的帮助下，他可以清晰辨别自己所处的方位，以及周边楼盘环境情况。他总能高效的完成工作，得到客户的肯定。
兼容android map 接口及功能
用户在阅读下面的文档时，可以通过各个相似功能对象的对比加深对API类方法、属性、用途的理解，从而更好地应用API类服务于自己的领域。
PART I
Interface
CHAPTER 1
Interface ItemizedOverlay.OnFocusChangeListener Overview
这个接口用于对item焦点变化感兴趣的监听器。
Method
onFocusChanged
void onFocusChanged(ItemizedOverlay overlay, OverlayItem newFocus)
在绘制方法中调用，所以这里除了发送消息之类的动作，不要做任何其它的动作。
Parameters:
overlay - 执行这个调用的Overlay
newFocus - 新焦点选中的item, 如果没有则为null
CHAPTER 2
Interface Overlay.Snappable
Overview
public static interface Overlay.Snappable
Overlay的接口定义，这个overlay包含的项目可被对齐（例如，当用户触发一个缩放时，这函数可被调用允许用户把缩放框和一个兴趣点对齐）。
Method
onSnapToItem
boolean onSnapToItem(int x, int y, android.graphics.Point snapPoint, MapView mapView)
检查给定的（x,y）是否和引起当前行为（如缩放）的item足够靠近。
参数:
x - 屏幕的x坐标
y - 屏幕的y坐标
snapPoint - 存放对于给定（x,y）最近的兴趣点（屏幕坐标）。如果没有对齐则不可
触摸。
mapView - 申请对齐的MapView。使用MapView.getProjection()
在屏幕像素和经纬度之间做转换。
返回值:
是否去对齐兴趣点。
CHAPTER 3
Interface Projection
Overview
public interface Projection
Projection接口用于屏幕像素点坐标系统和地球表面经纬度点坐标系统之间的变换。方法MapView.getProjection().返回一个Projection。
Method
toPixels
android.graphics.Point toPixels(GeoPoint in, android.graphics.Point out)
把给定的GeoPoint变换到相对于MapView左上角的屏幕像素坐标。MapView提供
了这种投影变换。
参数：
in –待变换的一对经纬度
out –一个用于输出预先存在的对象；如果为空，将返回一个新分配的像素点。
fromPixels
GeoPoint fromPixels(int x, int y)
该方法用给定的像素坐标创建一个新的GeoPoint。给定的像素点是以MapView的左上角为原点的坐标系统，MapView提供了这个像素转换器(PixelConverter)。
metersToEquatorPixels
float metersToEquatorPixels(float meters)
该方法把以米为计量单位的距离（沿赤道）在当前缩放水平下转换到一个以像素（水
平）为计量单位的距离。在默认的Mercator投影变换下，对于给定的距离，当远离赤
道时，变换后确切的像素数量会增加。
参数:
meter –以米为单位的距离
返回值:
相对给定距离的像素数量。在当前的缩放水平，如果沿赤道测量，返回值可能是个近
似值。
PART II
Classes
CHAPTER 1
Class GeoPoint
Overview
public class GeoPoint extends https://www.doczj.com/doc/2111965400.html,ng.Object
不可变类，表示一对经度和纬度值，以微度的整数形式存储.
Constructor
GeoPoint
public GeoPoint(int latitudeE6, int longitudeE6)
用给定的经度和纬度构造一个GeoPoint，单位微度(度* 1E6).
参数:
latitudeE6 - 该点的纬度. 为保持Mercator投影精确度，其取值范围是[-80,80]。
longitudeE6 - 该点的经度. 可被规范化到(-180, 180]。
GeoPoint (坐标位置偏转)
public GeoPoint(double lat, double lon, MapActivity cnt)
说明：
用给定的屏幕的坐标值和当前创建MapView的MapActivity进行坐标位置偏转，构造一个GeoPoint.
参数:
lat - 该点的屏幕横坐标x.
lon - 该点的屏幕纵坐标y.
cnt- 当前创建MapView的MapActivity.
Method
getLatitudeE6
public int getLatitudeE6()
返回GeoPoint对象的纬度，单位微度(度* 1E6).
返回值:
纬度.
getLongitudeE6
public int getLongitudeE6()
返回GeoPoint对象的经度，单位微度(度* 1E6).
返回值:
经度.
toString
public https://www.doczj.com/doc/2111965400.html,ng.String toString()
覆盖:
类https://www.doczj.com/doc/2111965400.html,ng.Object中的toString方法
equals
public boolean equals(https://www.doczj.com/doc/2111965400.html,ng.Object object)
覆盖:
类https://www.doczj.com/doc/2111965400.html,ng.Object中equals 方法
hashCode
public int hashCode()
覆盖:
类https://www.doczj.com/doc/2111965400.html,ng.Object中hashCode方法
CHAPTER 2
Class ItemizedOverlay
public abstract class ItemizedOverlay
ItemizedOverlay是Overlay的一个基类，它包含了一个OverlayItems列表。它处理从南到北的排序，用于绘制、创建平移边界、为每个点绘制标记点，和维护一个焦点选中的item，同时也负责把一个屏幕点击匹配到item上去，分发焦点改变事件给备选的监听器。
Constructor
ItemizedOverlay
public ItemizedOverlay(android.graphics.drawable.Drawable defaultMarker)
说明：
创建一个新的ItemizedOverlay。
参数：
defaultMarker –对于overlay中的每个item都要被绘制在地图上的一个Drawable；参看draw(android.graphics.Canvas, com.google.android.maps.MapView, boolean)。一个
item或许可以通过方法OverlayItem.getMarker(int)提供一个可以替换的标记点。这个标记点有两种绘制状态：null或R.attr.state_focused。为了能让点击测试正确工作，
两种状态必须有同样的边界。（一个简单的drawable会忽略它自身状态，那意味着它自动有同样的边界。）
注意，为了正确绘制标记点，需要给它添加边界。典型的，这由boundCenterBottom 来完成，和super(boundCenterBottom(marker))一样。
Method
boundCenterBottom
protected static android.graphics.drawable.Drawable
boundCenterBottom(android.graphics.drawable.Drawable balloon)
调整一个drawable边界，使得（0，0）是这个drawable底部最后一行中心的一个像素。如图形一样，对于“pin”是有用的。方便起见，返回和输入同样的drawable。
参数:
balloon - 待调整的drawable
返回值:
和输入同样的drawable.
boundCenter
protected static android.graphics.drawable.Drawable
boundCenter(android.graphics.drawable.Drawable balloon)
调整一个drawable边界，使得（0，0）是这个drawable中心的中心点。如图形一样，对于“途经点标记”是有用的。方便起见，返回和输入同样的drawable。
参数:
balloon - 待调整的drawable
返回值:
和输入同样的drawable
createItem
protected abstract Item createItem(int i)
子类通过该方法创建实体item。这只能从populate()调用；并且缓存起来待以后使用。
size
public abstract int size()
Overlay中item的数量。在populate()执行过程中一次调用，一直存储。
getCenter
public GeoPoint getCenter()
默认情况下，返回第一级别的item。必须首先调用populate()。
getIndexToDraw
protected int getIndexToDraw(int drawingOrder)
返回给定索引对应item的级别。默认情况下，item通过纬度排序。子类可以覆盖这个方法以改变绘制顺序。
draw
public void draw(android.graphics.Canvas canvas,MapView mapView, boolean shadow) 在每个item上绘制一个标记点。首先必须调用populate()。
对应Overlay中的每个item，标记点都要被绘制两次――一次是在绘制阴影阶段，然后是在非阴影阶段。标记点的底中部将和item的地理坐标对齐。
通过覆盖方法getIndexToDraw(int)，绘制的顺序可能会改变。一个item可能通过方法OverlayItem.getMarker(int)获得另外一个标记点。如果那个方法返回null，那么使用默认的标记点。
焦点选中的item总是最后一个绘制，然后放置在其它item之上达到可见。
覆盖:
类Overlay 中的draw
参数:
canvas - 待绘制的画布。注意，这个画布或许已经被实施了某种变换，所以保留其原样。
mapView - 请求绘制的MapView。使用MapView.getProjection()在屏幕坐标和经纬度对之间做变换。
shadow - 如果为true，绘制阴影层。如果为false, 绘制overlay的内容。getLatSpanE6
public int getLatSpanE6()
返回值:
Overlay的纬度范围，在调用populate()过程中计算最北item和最南item之间的差值。
getLonSpanE6
public int getLonSpanE6()
返回值:
Overlay的经度范围，在调用populate()过程中计算最西和最东item之间的差值。
横跨不连续经度的overlay在－180度时会报告非常大的范围。
populate
protected final void populate()
在一个新ItemizedOverlay上执行所有操作的工具方法。子类通过createItem(int)方法提供item。一旦有了数据，子类在调用其它方法前，首先调用这个方法。
setLastFocusedIndex
protected void setLastFocusedIndex(int lastFocusedIndex)
设置最近（或当前）焦点选中的item的索引，如果没有item被选中则设置为-1。
应该记住这个，因为即使用户暂时平移远离了overlay,nextFocus(boolean)也能够重新按顺序浏览一个overlay。通常情况下，子类不需要去设置这个变量，因为当焦点变换时，变量可以自动更新。
setFocus
public void setFocus(Item item)
如果给定的item存在overlay中，强制其为焦点选中。任何注册的ItemizedOverlay.OnFocusChangeListener都将被通知。这不会移动地图，所以如果item不是在中心，用户会感到困惑。如果没有找到这个item，这是一个空操作。
可以传递null取消焦点。
getFocus
public Item getFocus()
Returns:
当前焦点选中的item，如果当前没有item被焦点选中，返回null。
getLastFocusedIndex
public final int getLastFocusedIndex()
Returns:
最近焦点选中item的级别，如果从来没有焦点选中，则返回-1.
getItem
public final Item getItem(int position)
Returns:
给定索引对应的item。
nextFocus
public Item nextFocus(boolean forwards)
返回给定方向上下一个将要被焦点选中的item，如果已经到了行尾，返回null。如果以前没有焦点选中过，返回第一个item，如果没有item则返回null。
onTap
public boolean onTap(GeoPoint p, MapView mapView)
处理一个点击事件。一个点击只有落到一个item上去时才会被处理，可以去覆盖onTap(int)，返回true。
Overrides:
Overlay类中的onTap。
Parameters:
p - 点击的位置点
mapView - 产生点击事件的MapView
Returns:
如果overlay处理了这个点击事件，返回true。
onSnapToItem
public boolean onSnapToItem(int x, int y, android.graphics.Point snapPoint, MapView mapView)
检验给定的（x,y）是否足够接近引起当前动作(例如缩放)的item。
详细说明:
接口Overlay.Snappable中的onSnapToItem。
Parameters:
x - x屏幕坐标。
y - y屏幕坐标。
snapPoint - 用距离给定点（x,y）最近的兴趣点（屏幕坐标）填充。如果没有点击，则不可触摸。
mapView - 请求点击的MapView。使用MapView.getProjection()在屏幕像素和经纬度对之间变换。
Returns:
是否点击了兴趣点
onTrackballEvent
public boolean onTrackballEvent(android.view.MotionEvent event, MapView mapView)
描述是从类Overlay拷贝而来
处理一个跟踪球事件。默认情况下，不做任何动作，返回false。
Overrides:
类Overlay 中的onTrackballEvent
Parameters:
event - 动作事件。
mapView - 产生跟踪球事件的MapView
Returns:
如果overlay处理了点击事件，返回true。
onKeyUp
public boolean onKeyUp(int keyCode, android.view.KeyEvent event, MapView mapView)
描述拷贝自Overlay
处理一个按键放开事件。默认情况下，不做任何动作，返回false。
Overrides:
类Overlay 中的onKeyUp
Parameters:
keyCode - 键码值。
event - 按键事件
mapView - 产生按键事件的MapView
Returns:
如果overlay处理了点击事件，返回true。
onTouchEvent
public boolean onTouchEvent(android.view.MotionEvent event, MapView mapView)
描述拷贝自Overlay
处理一个按键放开事件。默认情况下，不做任何动作，返回false。
Overrides:
类Overlay 中的onTouchEvent
Parameters:
event - 动作事件
mapView - 产生按键事件的MapView
Returns:
如果overlay处理了点击事件，返回true。
hitTest
protected boolean hitTest(Item item, android.graphics.drawable.Drawable marker, int hitX, int hitY)
检查给定的点击测试点是否在一个item标记点范围内。覆盖修改了一个item点击
测试的方法。点击点相对于标记点的范围。默认的实现只检查点击点是否在标记点的可触摸范围内。
Parameters:
item - 进行点击测试的item
marker - item的标记点
hitX - 检查点的x坐标
hitY - 检查点的y坐标
Returns:
如果点击测试点在标记点范围内，返回true。
setOnFocusChangeListener
public void setOnFocusChangeListener(ItemizedOverlay.OnFocusChangeListener l) setDrawFocusedItem
public void setDrawFocusedItem(boolean drawFocusedItem)
设置是否绘制焦点选中的item。默认情况是绘制这个item，但一些用户更偏好于自己去绘制焦点选中的item。
Parameters:
drawFocusedItem -
onTap
protected boolean onTap(int index)
覆盖这个方法去处理一个item上的“点击”事件。这可能是对屏幕上item的触摸点击，或者对位于中心且已选定的item的跟踪球点击。默认情况下，什么都不做，返回false。
Returns:
如果点击事件被处理，返回true；如果想要把这个事件传递给其它overlay，返回false。CHAPTER 3
Class MapActivity
Overview
public abstract class MapActivity extends android.app.Activity
public abstract class MapActivity
extends android.app.Activity
MapActivity是一个基类，它使用代码去管理任何一个Activity繁琐的事务，它的责任包括： Activity生命周期管理
在一个MapView后面创建和销毁服务
一个子类应当在onCreate(android.os.Bundle)创建它自己的MapView，或使用MapView的构造函数（然后用ViewGroup.addView(View)把它加入到布局视图里），或把这个构造(和Layout)留给Layout XML的inflation.
MapAcitivity并不是Andriod库中标准的Package。为了使用它，你必须在你的AndroidManifest.xml文件中添加下面的XML元素做为application元素的子元素。
每个进程只支持一个MapAcitivity。多个MapActivity同时运行很可能让它们之间的交互变得不可预期。
Constructor
MapActivity
public MapActivity()
Method
onCreate
protected void onCreate(android.os.Bundle icicle)
此函数初始化静态工厂类，创建地图对象和交通服务，但并不开启任何线程。子类在调用super.onCreate()后应该创建自身的MapView对象。
Overrides:
onCreate in class android.app.Activity
onNewIntent
public void onNewIntent(android.content.Intent newIntent)
Overrides:
onNewIntent in class android.app.Activity
onResume
protected void onResume()
此函数通知地图去“提前绘制”，即提前装载和解码，以便于第一次绘制显得更加“原子化”。启动交通服务线程，恢复要注册更新的MapView。
Overrides:
onResume in class android.app.Activity
onPause
protected void onPause()
暂停例如交通服务的线程，因为我们不想让它永远在后台运行。同时存储偏好设置。
Overrides:
onPause in class android.app.Activity
onDestroy
protected void onDestroy()
终止所有线程，释放所有资源。
Overrides:
onDestroy in class android.app.Activity
isRouteDisplayed
protected abstract boolean isRouteDisplayed()
为了计算的目的，服务器需要知道是否正在显示任何一种路由信息，例如一组驾车导向标志。子类必须实现这个方法以便真正报告这个信息，否则将违反使用条款。
Returns:
如果正在显示路线信息返回true，否则返回false。
isLocationDisplayed
protected boolean isLocationDisplayed()
为了计算的目的，服务器需要知道你是否正在显示任何一种对终端当前位置基于传感器的位置估算。默认情况下，如果MyLocationOverlay的一个子类通过MapView.getOverlays()被添加，而且已经启动定位功能，这个函数返回true；但是，子类必须覆盖掉这个方法以便真实的报告这个信息，否则违反使用条款。
Returns:
如果正在显示用户的位置信息返回true，否则返回false。
CHAPTER 4
Class MapController
Overview
public final class MapController extends https://www.doczj.com/doc/2111965400.html,ng.Object implements
android.view.View.OnKeyListener
一个工具类，用于控制地图的缩放（zooming）和平移（panning）。
Method
stopPanning
public void stopPanning()
重新设置平移状态，使地图静止。如果收到一个key-down事件但永远没有收到
key-up事件时，这个方法是必须的。
onKey
public boolean onKey(android.view.View v, int keyCode, android.view.KeyEvent event)
处理按键事件，把事件变换为适度的地图平移。在View.OnkeyListener中定义。
Specified by:
onKey in interface android.view.View.OnKeyListener
animateTo
public void animateTo(GeoPoint point)
对以给定的点GeoPoint，开始动画显示地图。
animateTo
public void animateTo(GeoPoint point, android.os.Message message)
对以给定的GeoPoint，开始动画显示地图。如果动画自然结束，则分发给定的消息。
如果动画中途被放弃，则不分发给定的消息。
animateTo
public void animateTo(GeoPoint point, https://www.doczj.com/doc/2111965400.html,ng.Runnable runnable)
对于给定的GeoPoint，开始动画显示地图。
Parameters:
point - 动画显示地图的位置点
runnable - 当动画自然结束，这个回调函数会被UI线程调用。如果动画中途被放弃，这个回调函数不会被调用。
scrollBy
public void scrollBy(int x, int y)
按照给定的像素数据量滚动。没有动画。
Parameters:
x - 水平滚动的像素数
y - 垂直滚动的像素数
setCenter
public void setCenter(GeoPoint point)
在给定的中心点GeoPoint上设置地图视图。没有动画。
stopAnimation
public void stopAnimation(boolean jumpToFinish)
终止所有未完成的动画，有条件的把地图中心修正到已完成的特殊动画的偏移量上去。
Parameters:
jumpToFinish - 如果为true, 在动画末端建立快捷方式。如果为false，则终止动画显示。
setZoom
public int setZoom(int zoomLevel)
设置地图的缩放级别。这个值的取值范围是[1,21], 尽管并非所有的区域都有高缩放级别的地图贴片。这个方法只是直接设定地图的缩放级别；对于渐变动画的缩放，使用zoomIn()或zoomOut().
Parameters:
zoomLevel - 当zoomLevel＝1时，地球赤道是256像素长。每个后续的缩放级别都是前者的两倍。
Returns:
新的缩放级别，取值范围[1,21]。
zoomToSpan
public void zoomToSpan(int latSpanE6, int lonSpanE6)
尝试调整地图的缩放，以便显示给定的经纬度范围。因为缩放只能达到离散的水平，
而且因为地图的比率和给定的比率不匹配，所以匹配的质量是不同的。唯一可以保证的是，缩放后至少新的经度和纬度中的其中之一是相对应参数的2倍。
zoomIn
public boolean zoomIn()
放大一个级别。这是动画缩放的一个步骤。如果你添加了ZoomControls视图（从MapView.getZoomControls()），那么这个函数也可以通过MapView.displayZoomControls(boolean)调用，使得ZoomControls简洁显示，但不取得焦点。
Returns:
如果缩放成功，返回true，如果达到最大极限，返回false。
zoomOut
public boolean zoomOut()
缩小一个级别。这是动画缩放的一个步骤。如果你添加了ZoomControls视图（从MapView.getZoomControls()），那么这个函数也可以通过MapView.displayZoomControls(boolean)调用，使得ZoomControls简洁显示，但不取得焦点。
Returns:
如果成功缩小返回true，如果达到最小极限，则返回false。
zoomInFixing
public boolean zoomInFixing(int xPixel, int yPixel)
放大一个级别。如果添加了ZoomControls视图（从MapView.getZoomControls()），那么这个函数也可以通过MapView.displayZoomControls(boolean)来调用，使得ZoomControls简洁显示，但不取得焦点。
这个放大会平移地图使之保持在屏幕的一个固定点上。通过像素坐标来设定固定点。
Parameters:
xPixel - 地图左边固定点缩放的偏移量。
yPixel - 地图上方固定点缩放的偏移量。
Returns:
如果放大成功，返回true；如果达到最大极限，返回false。
zoomOutFixing
public boolean zoomOutFixing(int xPixel, int yPixel)
缩小一个级别。这是动画缩放的一个步骤。如果添加了ZoomControls视图（从