イベント

マップ イベントの概要

ブラウザ内の JavaScript は「イベント駆動型」です。つまり、JavaScript では操作に対してイベントを作り、プログラムは目的のイベントを「リッスン」します。たとえばブラウザ内では、ユーザーのマウスとキーボードの操作によって、DOM 内に反映されるイベントが生成されます。特定のイベントを監視しているプログラムは、それらのイベントの JavaScript イベントリスナを登録して、これらのイベントが受信されたときにコードを実行します。

Google Maps API は、Maps API オブジェクトのカスタム イベントを定義することで、このイベント モデルを増強します。Maps API イベントは、標準の DOM イベントとは異なる個別のイベントである点に注意してください。ただし、ブラウザごとに異なる DOM イベント モデルが実装されているため、Maps API では、さまざまなブラウザ固有の性質に対処しなくても、これらの DOM イベントをリッスンしたり応答したりできる機能を備えています。

イベントリスナ

Google Maps API 内のイベントは、GEvent 名前空間内のユーティリティ関数を使用してイベントリスナを登録することで処理されます。各 Maps API オブジェクトは、いくつかの名前付きイベントをエクスポートします。たとえば GMap2 オブジェクトは、click、dblclick、move イベントを含む多数のイベントをエクスポートします。各イベントは特定のコンテキスト内で発生して、そのコンテキストを識別する引数を渡すことができます。たとえば mousemove イベントは、ユーザーがマップ オブジェクト内でマウスを動かしたときに発生して、マウスが配置されている地理的位置の GLatLng を渡します。

GMap2 イベントとこれらが生成する引数の全リストについては、GMap2.Events を参照してください。

これらのイベントの通知に登録するには、静的メソッド GEvent.addListener() を使用してください。このメソッドは、オブジェクト、リッスン対象のイベント、指定されたイベントの発生時に呼び出す関数を取ります。たとえば次のコード スニペットは、ユーザーが地図上でクリックするたびにアラートを表示します。

var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
GEvent.addListener(map, "click", function() {
  alert("You clicked the map.");
});

例を表示 (event-simple.html)

リスナは、イベントのコンテキストを取得することもできます。次のサンプル コードでは、ユーザーが地図をドラッグした後の、地図の中心の緯度と経度を表示します。

var map = new GMap2(document.getElementById("map"));
GEvent.addListener(map, "moveend", function() {
  var center = map.getCenter();
  document.getElementById("message").innerHTML = center.toString();
});
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

例を表示 (event-context.html)

イベントリスナでクロージャを使用する

イベントリスナを実行するときは、オブジェクトにプライベート データと永続データの両方を添付することが一般に有効です。JavaScript は「プライベート」インスタンス データをサポートしていませんが、内部関数が外部変数にアクセスすることを可能にするクロージャをサポートしています。イベントリスナ内でクロージャを使用すると、イベントが発生したオブジェクトには通常添付されていない変数にアクセスできるので便利です。

次の例では、イベントリスナ内で関数クロージャを使用して、一連のマーカーに秘密のメッセージを割り当てています。各マーカーをクリックすると、そのマーカー自体には含まれていない秘密のメッセージの一部が表示されます。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// Creates a marker at the given point
// The five markers show a secret message when clicked
// but that message is not within the marker's instance data

function createMarker(point, number) {
  var marker = new GMarker(point);
  var message = ["This","is","the","secret","message"];
  marker.value = number;
  GEvent.addListener(marker, "click", function() {
    var myHtml = "<b>#" + number + "</b><br/>" + message[number -1];
    map.openInfoWindowHtml(point, myHtml);
  });
  return marker;
}

// Add 5 markers to the map at random locations
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 5; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
    southWest.lng() + lngSpan * Math.random());
  map.addOverlay(createMarker(point, i + 1));
}

例を表示 (event-closure.html)

渡された引数をイベントで使用する

Maps API イベント システム内の多くのイベントは、そのイベントがトリガされたときに引数を渡します。たとえば GMap2 「クリック」イベントはオーバーレイ上でマップ クリックが起こったとき overlay と overlaylatlng を渡しますが、そうでないときは地図座標の latlng を渡します。これらの引数にアクセスするには、指定された記号をイベントリスナ内の関数に直接渡します。

下の例では、まず latlng 引数が定義されているかどうかチェックして、クリックがマップ タイル上で行われたことを確認します。次にクリックされた座標の上方に 情報ウィンドウを開き、ズーム レベルとともにピクセル空間に変換された座標を表示します。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

GEvent.addListener(map,"click", function(overlay, latlng) {     
  if (latlng) { 
    var myHtml = "The GPoint value is: " + map.fromLatLngToDivPixel(latlng) + " at zoom level " + map.getZoom();
    map.openInfoWindow(latlng, myHtml);
  }
});
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());

例を表示 (event-arguments.html)

イベントをオブジェクト メソッドにバインドする

関数はオブジェクトの特定のインスタンスにイベントリスナを添付したいときに便利です。イベントに応じてオブジェクトのすべてのインスタンスでメソッドを呼び出したい場合は GEvent.bind() を使用します。次の例では、アプリケーション クラス インスタンスはイベントがトリガされるとクラスの状態を変更し、マップ イベントをそれぞれのメソッドにバインドします。

function MyApplication() {
  this.counter = 0;
  this.map = new GMap2(document.getElementById("map"));
  this.map.setCenter(new GLatLng(37.4419, -122.1419), 13);
  GEvent.bind(this.map, "click", this, this.onMapClick);
}

MyApplication.prototype.onMapClick = function() {
  this.counter++;
  alert("You have clicked the map " + this.counter + " " +
        (this.counter == 1 ? "time" : "times"));
}

var application = new MyApplication();

例を表示 (event-bind.html)

DOM イベントをリッスンする

Google Maps API イベント モデルは、独自のカスタム イベントを作成して管理します。ただし DOM も、使用されている特定のブラウザ イベント モデルに従って独自のイベントを作成して送出します。これらのイベントを取得して応答する必要がある場合は、Google Maps API が提供するブラウザに依存しないラッパーを使用することで、カスタム コードを使用せずに DOM イベントをリッスンしてバインドできます。

GEvent.addDomListener() 静的メソッドは、DOM ノード上の DOM イベントのイベント ハンドラを登録します。同様に GEvent.bindDom() 静的メソッドを使用すると、クラスインスタンス上の DOM イベントのイベント ハンドラを登録できます。

イベントリスナを削除する

不要になったイベントリスナは削除する必要があります。リッスン対象のイベントが一度しか発生しない場合でも、削除が必要になることがあります。クロージャ内の名前のない関数を介して定義されたイベントリスナは、削除するのが難しい場合があります。ただし、addListener()、addDomListener()、bind()、bindDom() の各関数は、最終的にハンドラの登録を解除するために使用できる GEventListener ハンドルを返します。

次の例では、クリックに応じて地図上にマーカーを配置します。その後で再びクリックされるとイベントリスナが削除されます。removeOverlay() コードは結果として一度も実行されない点に注目してください。また、イベントリスナ自体からもそのイベントリスナを削除できる点にも注目してください。

function MyApplication() {
  this.counter = 0;
  this.map = new GMap2(document.getElementById("map"));
  this.map.setCenter(new GLatLng(37.4419, -122.1419), 13);
  var myEventListener = GEvent.bind(this.map, "click", this, function(overlay, latlng) {
    if (this.counter == 0) {
      if (latlng) {
        this.map.addOverlay(new GMarker(latlng))
        this.counter++;
      } else if (overlay instanceof GMarker) {
        this.removeOverlay(marker)
      }
    } else {
      GEvent.removeListener(myEventListener);
    }
  }); 
}

function load() {
  var application = new MyApplication();
}

例を表示 (event-removal.html)