Geolocation

Namespace: Wisej.Ext.Geolocation

Assembly: Wisej.Ext.Geolocation (4.1.0.0)

• Component
  • Geolocation

The Geolocation component represents an object able to programmatically obtain the position of the device.

C#

public class Geolocation : Component, IComponent

VB.NET

Public Class Geolocation
    Inherits Component
    Implements IComponent

Constructors

Geolocation()

Initializes a new instance of the Geolocation class.

Use this constructor when creating the component in code. The component uses the browser's geolocation API, so the user is asked for permission the first time a position is requested.

Example:

Creating a geolocation component in code and configuring it before use:

var geolocation = new Wisej.Ext.Geolocation.Geolocation
{
    EnableHighAccuracy = true,
    Timeout = 10000,    // wait up to 10 seconds.
    MaximumAge = 0      // don't accept a cached position.
};

Geolocation(container)

Initializes a new instance of the Geolocation class together with the specified container.

Name	Type	Description
container	IContainer	A IContainer that represents the container for the component.

The component is added to container and is disposed together with it. This is the constructor used by the designer when the component is dropped on a page or form.

Throws:

• ArgumentNullException container is null.

Example:

Creating a geolocation component that is disposed together with the form's components:

public partial class MainPage : Wisej.Web.Page
{
    private System.ComponentModel.IContainer components = new System.ComponentModel.Container();
    private Wisej.Ext.Geolocation.Geolocation geolocation;

    public MainPage()
    {
        InitializeComponent();
        this.geolocation = new Wisej.Ext.Geolocation.Geolocation(this.components);
    }
}

Properties

ActiveWatch

Boolean: Enables or disables active watch mode for this geolocation component. When enabled, the PositionChanged event is fired automatically each time the position of the device changes. (Default: False)

DesignMode

Boolean: Returns a value that indicates whether the IComponent is currently in design mode.

Value: true if the IComponent is in design mode; otherwise, false.

EnableHighAccuracy

Boolean: Indicates the application would like to receive the best possible results. (Default: False)

If true and if the device is able to provide a more accurate position, it will do so. Note that this can result in slower response times or increased power consumption (with a GPS chip on a mobile device for example). On the other hand, if false, the device can take the liberty to save resources by responding more quickly and/or using less power.

LastPosition

Position: Returns the last position detected by the device.

MaximumAge

Int64: Indicates the maximum age in milliseconds of a possible cached position that is acceptable to return. (Default: -1)

If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to -1 the device must return a cached position regardless of its age.

Timeout

Int64: Sets or gets the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. (Default: -1)

Methods

GetCurrentPosition(callback)

Returns the current position of the device.

Parameter	Type	Description
callback	Action<Position>	The method to call when the client returns the position. It receives a Position object that contains the coordinates, or the Status and ErrorMessage if the request failed.

The request is sent to the browser and callback is invoked when the response is received. The request uses the current values of EnableHighAccuracy, Timeout and MaximumAge. Always check Status before using the coordinates.

Throws:

• ArgumentNullException callback is null.

Example:

Requesting the current position and showing it in a label:

private void buttonLocate_Click(object sender, EventArgs e)
{
    this.geolocation1.GetCurrentPosition(position =>
    {
        if (position.Status == Wisej.Ext.Geolocation.StatusCode.Success)
            this.labelPosition.Text = $"{position.Latitude}, {position.Longitude} (±{position.Accuracy} m)";
        else
            AlertBox.Show(position.ErrorMessage ?? position.Status.ToString());
    });
}

GetCurrentPositionAsync()

Asynchronously returns the current position of the device.

Returns: Task<Position>. A Task that completes when the client returns the position. Its result is a Position object that contains the coordinates, or the Status and ErrorMessage if the request failed.

This is the awaitable version of GetCurrentPosition. The task doesn't fault when the position can't be retrieved; check Status on the result instead.

Example:

Awaiting the current position in an event handler:

private async void buttonLocate_Click(object sender, EventArgs e)
{
    var position = await this.geolocation1.GetCurrentPositionAsync();

    if (position.Status == Wisej.Ext.Geolocation.StatusCode.Success)
        this.labelPosition.Text = $"{position.Latitude}, {position.Longitude}";
    else
        AlertBox.Show(position.ErrorMessage ?? position.Status.ToString());
}

OnPositionChanged(e)

Fires the PositionChanged event.

Parameter	Type	Description
e	EventArgs

OnWebEvent(e)

Processes the event from the client.

Parameter	Type	Description
e	WisejEventArgs	Event arguments.

OnWebRender(config)

Renders the client component.

Parameter	Type	Description
config	Object	Dynamic configuration object.

Events

PositionChanged

EventHandler Fired when the location of the browser changes while this component has an active watch.