Class LocationDataSource

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  LocationDataSource.Location
      A location update provided by a LocationDataSource, consisting primarily of a Point representing a geographical location, and attributes of location change such as the course (direction of travel), and the velocity (speed of location change).
    • Constructor Summary

      Constructors 
      Constructor Description
      LocationDataSource()
      Creates a default LocationDataSource, and sets up the status changed listeners.
    • Constructor Detail

      • LocationDataSource

        public LocationDataSource()
        Creates a default LocationDataSource, and sets up the status changed listeners. This method should be called by the subclass constructor before performing other work.
        Since:
        100.0.0
    • Method Detail

      • startAsync

        public final void startAsync()
        Asynchronously initializes the location data source and prepares to begin receiving location updates. Calls the onStart() method of a subclass.
        Since:
        100.0.0
      • addStartedListener

        public final void addStartedListener​(Runnable listener)
        Registers the given Runnable to be called when the location data source has successfully started, or has failed to start. The Runnable is called immediately if this location data source has already started (isStarted() is true).

        You can also use LocationDisplay.addDataSourceStatusChangedListener(LocationDisplay.DataSourceStatusChangedListener) in order to be notified when the LocationDataSource associated with a LocationDisplay starts or stops.

        This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

        Parameters:
        listener - a Runnable to be called when the location data source has started
        Since:
        100.0.0
        See Also:
        removeStartedListener(Runnable)
      • removeStartedListener

        public final boolean removeStartedListener​(Runnable listener)
        Unregisters the given Runnable that was previously added using addStartedListener(Runnable).
        Parameters:
        listener - the Runnable to unregister
        Returns:
        true if the Runnable was removed successfully; false otherwise
        Since:
        100.0.0
      • getError

        public final Throwable getError()
        Gets the error generated during the starting process, if the LocationDataSource failed to start. Returns null if it started successfully.
        Returns:
        the error generated during the starting process, or null if it started successfully
        Since:
        100.0.0
      • onStartCompleted

        protected final void onStartCompleted​(Throwable throwable)
        Sets the result status of the starting process, and any error generated during it. This method must be called by the subclass once the location data source has finished its starting process.
        Parameters:
        throwable - the error generated during the starting process, or null if it started successfully
        Since:
        100.0.0
      • setLastKnownLocation

        protected final void setLastKnownLocation​(LocationDataSource.Location location)
        Sets the last known Location, which will be displayed as soon as the data source has been started, until a new location update is received.

        The last known location may not accurately represent the true current location, but indicates to the user that the LocationDataSource is waiting for updated location data. It will be displayed using the LocationDisplay.getAcquiringSymbol().

        Parameters:
        location - the last known location
      • onStart

        protected abstract void onStart()
        Called from startAsync(). Subclasses should implement this method to prepare for starting the data source. The onStartCompleted(Throwable) method must be called by the subclass once the location data source has finished its starting process.
        Since:
        100.0.0
      • stop

        public final void stop()
        Stops receiving the location updates. This method will call the onStop() method implementation of the subclass.
        Since:
        100.0.0
      • onStop

        protected abstract void onStop()
        Called from the stop() method, subclasses should perform any necessary clean-up in this method; for example, stop streaming the location data, release resources, and so on.
        Since:
        100.0.0
      • updateHeading

        protected final void updateHeading​(double heading)
        Called when the data source has a new heading value. The LocationDisplay.getHeading() associated with this LocationDataSource will be updated with this value.
        Parameters:
        heading - the heading angle, in degrees clockwise, relative to north
        Since:
        100.0.0
      • isStarted

        public final boolean isStarted()
        Indicates if this location data source has started successfully. A started LocationDataSource is one that is receiving location updates.
        Returns:
        true if the data source has started successfully; false otherwise
        Since:
        100.0.0