Events

マップイベントの概要

ブラウザ内の 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("地図をクリックしました。");
});

例を表示 (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);

// 指定された地点にマーカーを作成します
// 5 個のマーカーのそれぞれをクリックすると秘密のメッセージが表示されますが、そのメッセージは各マーカーのインスタンスデータには含まれていません

function createMarker(point, number) {
  var marker = new GMarker(point);
  var message = ["これ","は","秘密の","メッセージ","です"];
  marker.value = number;
  GEvent.addListener(marker, "click", function() {
    var myHtml = "<b>#" + number + "</b><br/>" + message[number -1];
    map.openInfoWindowHtml(point, myHtml);
  });
  return marker;
}

// 地図のランダムな場所に 5 個のマーカーを追加します
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 "click" イベントは、2 つの引数(overlay、point) をイベント内で渡します。これらの引数にアクセスするには、指定された記号をイベントリスナ内の関数に直接渡します。

たとえば地図上の "click" イベントは、overlay と point という引数を渡します。これらの引数は、イベントリスナ内で呼び出すコールバック関数内で直接渡します。

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

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

例を表示 (event-arguments.html)

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

オブジェクトの特定のインスタンスにイベントリスナを添付するときは、 関数が便利です。一方、オブジェクトのすべてのインスタンスについて、 イベントに応答してメソッドを呼び出す必要があるときは、GEvent.bind() を使用します。 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("地図をクリックしました  " + 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(marker,point) {
    if (this.counter == 0) {
      if (point) {
        this.map.addOverlay(new GMarker(point))
        this.counter++;
      } else {
        this.removeOverlay(marker)
      }
    } else {
      GEvent.removeListener(myEventListener);
    }
  }); 
}

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

例を表示 (event-removal.html)