com.google.gwt.geolocation.client

## Class Geolocation

- java.lang.Object
- - com.google.gwt.geolocation.client.Geolocation

-     public class Geolocation
      extends java.lang.Object

  Implements the HTML5 Geolocation interface.

  You can obtain a user's position by first calling `Geolocation.getIfSupported()`

  Once you have a `Geolocation`, you can request the user's current position by calling `getCurrentPosition(Callback)` or `watchPosition(Callback)`.

  The first time an application requests the user's position, the browser will prompt the user for permission. If the user grants permission, the browser will locate the user and report it back to your application. If the user declines permission, the callback's `Callback.onFailure(Object)` method will be called with a `PositionError` with its code set to `PositionError.PERMISSION_DENIED`.

  Experimental API: This API is still under development and is subject to change.

  This may not be supported on all browsers.

  See Also:
    W3C Geolocation API, Dive Into HTML5 - Geolocation

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Geolocation.PositionOptions` Additional options for receiving the user's location.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Geolocation()` Should be instantiated by `getIfSupported()`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearWatch(int watchId)` Stops watching the user's position.
    `void` | `getCurrentPosition(Callback<Position,PositionError> callback)` Calls the callback with the user's current position.
    `void` | `getCurrentPosition(Callback<Position,PositionError> callback, Geolocation.PositionOptions options)` Calls the callback with the user's current position, with additional options.
    `static Geolocation` | `getIfSupported()` Returns a `Geolocation` if the browser supports this feature, and `null` otherwise.
    `static boolean` | `isSupported()` Returns `true` if the browser supports geolocation.
    `int` | `watchPosition(Callback<Position,PositionError> callback)` Repeatedly calls the given callback with the user's position, as it changes.
    `int` | `watchPosition(Callback<Position,PositionError> callback, Geolocation.PositionOptions options)` Repeatedly calls the given callback with the user's position, as it changes, with additional options.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Geolocation

          protected Geolocation()

      Should be instantiated by `getIfSupported()`.

  - ### Method Detail

    - #### getIfSupported

          public static Geolocation getIfSupported()

      Returns a `Geolocation` if the browser supports this feature, and `null` otherwise.

    - #### isSupported

          public static boolean isSupported()

      Returns `true` if the browser supports geolocation.

    - #### clearWatch

          public void clearWatch(int watchId)

      Stops watching the user's position.
      Parameters:
        `watchId` - the ID of a position watch as returned by a previous call to `watchPosition(Callback)`.

    - #### getCurrentPosition

          public void getCurrentPosition(Callback<Position,PositionError> callback)

      Calls the callback with the user's current position.

    - #### getCurrentPosition

          public void getCurrentPosition(Callback<Position,PositionError> callback,
                                Geolocation.PositionOptions options)

      Calls the callback with the user's current position, with additional options.

    - #### watchPosition

          public int watchPosition(Callback<Position,PositionError> callback)

      Repeatedly calls the given callback with the user's position, as it changes.

      The frequency of these updates is entirely up to the browser. There is no guarantee that updates will be received at any set interval, but are instead designed to be sent when the user's position changes. This method should be used instead of polling the user's current position.

      Returns:
        the ID of this watch, which can be passed to `clearWatch(int)` to stop watching the user's position.

    - #### watchPosition

          public int watchPosition(Callback<Position,PositionError> callback,
                          Geolocation.PositionOptions options)

      Repeatedly calls the given callback with the user's position, as it changes, with additional options.

      The frequency of these updates is entirely up to the browser. There is no guarantee that updates will be received at any set interval, but are instead designed to be sent when the user's position changes. This method should be used instead of polling the user's current position.

      If the browser does not support geolocation, this method will do nothing, and will return -1.

      Returns:
        the ID of this watch, which can be passed to `clearWatch(int)` to stop watching the user's position.