觸發事件

觸發事件是SDK最重要的一環，透過觸發事件來完成應用層對應的工作。本章節將完整介紹SAILS Android SDK的觸發事件。

定位引擎觸發事件Listeners

定位點改變事件

透過setOnLocationChangeLEventListener，事實上，由於本定位引擎採用多種定位融合技術，每秒有10次以上的定位更新達到絕佳的定位體驗，故在定位點改變事件中，SDK會以每0.1秒呼叫此觸發事件，開發者可以透過isLocationFix來判斷用戶是否在該場域並且定位引擎已經計算出位置。

mSails.setOnLocationChangeEventListener(new SAILS.OnLocationChangeEventListener() {
    @Override
    public void OnLocationChange() {
    //本觸發事件每0.1秒執行一次
        if(mSails.isLocationFix()) { //isLocationFix可用來判斷用戶位置是否已被計算出來

        }
    }
});

用戶樓層改變事件

當定位引擎判斷該用戶所在樓層的位置變化時，會呼叫此觸發事件，帶入之參數為切換的樓層名稱。

mSails.setOnFloorChangeListener(new SAILS.OnFloorChangeListener() {
    @Override
    public void onFloorChanged(String floorName) {
        //用戶所在樓層位置改變時會進行此工作
    }
});

向量地圖引擎觸發事件Listeners

對於地圖來說，不外乎就是當用戶點選地圖、樓層變換、模式變換時應用層會需要啟動對應的工作。以下我們列出地圖端的觸發事件以及它的使用方式：

點擊POI區域(LocationRegion)觸發事件 OnRegionClick Listener

當用戶點擊地圖時，該點擊位置是在地圖中LocationRegion（區塊tag有設為navi=true，皆為LocationRegion物件）的範圍內則會啟動本觸發，而觸發的反饋為LocationRegion的List。會為List的原因在於，地圖區塊可能會有重疊，點擊位置有可能有超過一個區塊的範圍內，而回傳會以該LocationRegion所設定的level值由大至小依序排列。通常開發者取第一個LocationRegion物件即可。

mSailsMapView.setOnRegionClickListener(new SAILSMapView.OnRegionClickListener() {
  @Override
  public void onClick(List<LocationRegion> list) {
   //點擊觸發工作
  }
});

長點擊POI區域(LocationRegion)觸發事件 OnRegionLongClickListener

長點擊觸發設定與短點擊一致，請參考上面說明。

地圖點擊觸發事件 OnMapClickListener

當用戶點擊地圖時，若開發者想要取得點擊地圖的x與y座標，則可參考本觸發事件。

mSailsMapView.setOnMapClickListener(new SAILSMapView.OnMapClickListener() {
  @Override
  public void onClick(int x, int y) {
   //地圖點擊事件工作，(x,y)為點擊座標
  }
});

本觸發物件通常用來判斷用戶點擊的區域是否為icon(marker)的區域，開發者可以使用MarkerManager中的getLocationRetionByMarkerXY(x,y)將點擊觸發之XY座標帶進，來判斷為何者LocationRegion中的Marker被點擊到：

List<LocationRegion> lrlist = mSailsMapView.getMarkerManager().getLocationRegionByMarkerXY(x, y);

地圖點擊無物件觸發事件 OnClickNothingListener

當用戶點擊地圖時無對應之LocationRegion被點擊到則會觸發此事件，通常此觸發事件用來判斷用戶是否意圖將上個動作所產生的圖示/指示清除。

變換樓層觸發事件 OnFloorChangedListener

當樓層被切換時會觸發此事件。本觸發事件與SAILS類別中的onFloorChangedListener不同的地方在於前者為地圖因被執行loadFloorMap而觸發，而後者是因定位引擎判別用戶所在樓層改變而產生的觸發程序。

SAILSMapView的OnFloorChangedListener動作順序如下： SAILSMapView地圖樓層切換(loadFloorMap被呼叫)->執行onFloorChangedBefore()->SAILSMapView執行切換的樓層地圖繪製->SAILSMapView繪製完成->執行onFloorChangedAfter()

本觸發事件通常用來更新應用層的樓層顯示，例如Spinner下拉表單的更新。

mSailsMapView.setOnFloorChangedListener(new SAILSMapView.OnFloorChangedListener() {
    @Override
    public void onFloorChangedBefore(String floorName) {
      //執行欲切換樓層前的工作
    }

    @Override
    public void onFloorChangedAfter(String floorName) {
      //執行切換樓層並顯示後的工作
    }
});

變換地圖模式時觸發事件 OnModeChangedListener

當地圖模式有變動時會呼叫此事件。通常本觸發事件用來控制地圖中心/方向鎖定之按鈕顯示狀態。

mSailsMapView.setOnModeChangedListener(new SAILSMapView.OnModeChangedListener() {
    @Override
    public void onModeChanged(int mode) {
        //執行模式變換時的工作
    }
});

路徑規劃觸發事件Listeners

路徑規劃完整觸發事件如下：

mSailsMapView.getRoutingManager().setOnRoutingUpdateListener(new com.sails.engine.PathRoutingManager.OnRoutingUpdateListener() {
    @Override
    public void onArrived(LocationRegion locationRegion) {
        //已到達目的地之工作
    }

    @Override
    public void onRouteSuccess() {
       //路徑規劃成功之工作
    }

    @Override
    public void onRouteFail() {
       //路徑規劃失敗之工作
    }

    @Override
    public void onPathDrawFinish() {
      //路徑繪製完成之工作
    }

    @Override
    public void onTotalDistanceRefresh(int distanceInMeter) {
      //起訖點距離改變時之工作
    }

    @Override
    public void onReachNearestTransferDistanceRefresh(int currentDistance, int nodeType) {
      //用戶離最近的樓層切換轉換節點的工作

    }

    @Override
    public void onSwitchFloorInfoRefresh(List<SwitchFloorInfo> list, int index) {
      //樓層切換更新觸發之工作
    }
});

以下針對各個事件說明：

onArrived

當用戶抵達目的地時會觸發此事件並帶入目的地之LocationRegion

onRouteSuccess

當執行路徑規劃時可以成功進行路徑規劃會觸發此事件，亦即起訖點的路徑可以被規劃出來。

onRouteFail

當執行路徑規劃時無法成功進行路徑規劃會觸發此事件，通常路徑無法被規劃的以下原因：

• 未繪製或位上傳Path.xml
• Path內的末節點並未被起迄LocationRegion所包覆
• 切換樓層的節點id並未設定正確
• 在指定的路徑規劃模式下無法規劃路徑

onPathDrawFinish

當路徑繪製完成時會觸發此事件。

onTotalDistanceRefresh

起訖點距離改變時會觸發此事件，並帶入所剩距離(單位為公尺)

onReachNearestTransferDistanceRefresh

用戶至最近轉換樓層節點時的觸發事件，帶入的第一個參數為目前至目的地之距離，第二參數為該切換樓層的節點形式，該節點會有以下幾種可能的形式：

• SwitchFloorInfo.STAIR
• SwitchFloorInfo.ESCALATOR
• SwitchFloorInfo.ELEVATOR
• SwitchFloorInfo.DESTINATION

onSwitchFloorInfoRefresh

透過SwitchFloorInfo的資訊開發者可以取得

• 每層欲往上樓層或往下樓層走的資訊
• 轉換樓層的形式：電梯、手扶梯、樓梯
• 該樓層切換點之經緯度