Inclinometer Inclinometer Inclinometer Inclinometer Class

Definition

Represents an inclinometer sensor.

This sensor returns pitch, roll, and yaw values that correspond to rotation angles around the x, y, and z axes, respectively.

For an example implementation, see the inclinometer sample https://github.com/Microsoft/Windows-universal-samples/tree/master/Samples/Inclinometer.

public : sealed class Inclinometer : IInclinometer, IInclinometer2, IInclinometerDeviceIdpublic sealed class Inclinometer : IInclinometer, IInclinometer2, IInclinometerDeviceIdPublic NotInheritable Class Inclinometer Implements IInclinometer, IInclinometer2, IInclinometerDeviceId// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Sensor data is provided relative to the device's fixed sensor coordinate system, and is independent of display orientation. For applications that rely on sensor data for input control or to manipulate elements on the screen, the developer must take current display orientation into account and compensate the data appropriately. For more info about the sensor coordinate system, see Sensor data and display orientation.

The following example demonstrates how a Windows Store app built with XAML and C# uses the GetDefault method to establish a connection to an inclinometer. If no integrated inclinometer is found, the method will return a null value.

_inclinometer = Inclinometer.GetDefault();

The following example demonstrates how a Windows Store app built with XAML registers a ReadingChanged event handler.

private void ScenarioEnable(object sender, RoutedEventArgs e)
{
    if (_inclinometer != null)
    {
        // Establish the report interval
        _inclinometer.ReportInterval = _desiredReportInterval;

        Window.Current.VisibilityChanged += new WindowVisibilityChangedEventHandler(VisibilityChanged);
        _inclinometer.ReadingChanged += new TypedEventHandler<Inclinometer, InclinometerReadingChangedEventArgs>(ReadingChanged);

        ScenarioEnableButton.IsEnabled = false;
        ScenarioDisableButton.IsEnabled = true;
    }
    else
    {
        rootPage.NotifyUser("No inclinometer found", NotifyType.StatusMessage);
    }
}

The following example shows the ReadingChanged event handler.

async private void ReadingChanged(object sender, InclinometerReadingChangedEventArgs e)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        InclinometerReading reading = e.Reading;
        ScenarioOutput_X.Text = String.Format("{0,5:0.00}", reading.PitchDegrees);
        ScenarioOutput_Y.Text = String.Format("{0,5:0.00}", reading.RollDegrees);
        ScenarioOutput_Z.Text = String.Format("{0,5:0.00}", reading.YawDegrees);
    });
}

Properties

DeviceId DeviceId DeviceId DeviceId

Gets the device identifier.

public : PlatForm::String DeviceId { get; }public string DeviceId { get; }Public ReadOnly Property DeviceId As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The device identifier.

MaxBatchSize MaxBatchSize MaxBatchSize MaxBatchSize

Gets the maximum number of events that can be batched by the sensor.

public : unsigned int MaxBatchSize { get; }public uint MaxBatchSize { get; }Public ReadOnly Property MaxBatchSize As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The maximum number of batched events.

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

A sensor may not support batched data collection. In that case, this property will be 0. Otherwise, this determines the maximum number of events the sensor can gather before submitting them. This in turn will determine the maximum supported ReportLatency. The maximum latency equals the ReportInterval times the MaxBatchSize. For more information about sensor batching, see Sensors.

MinimumReportInterval MinimumReportInterval MinimumReportInterval MinimumReportInterval

Gets the minimum report interval supported by the inclinometer.

public : unsigned int MinimumReportInterval { get; }public uint MinimumReportInterval { get; }Public ReadOnly Property MinimumReportInterval As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The minimum ReportInterval supported by the sensor.

See Also

ReadingTransform ReadingTransform ReadingTransform ReadingTransform

Gets or sets the transformation that needs to be applied to sensor data. Transformations to be applied are tied to the display orientation with which to align the sensor data.

public : DisplayOrientations ReadingTransform { get; set; }public DisplayOrientations ReadingTransform { get; set; }Public ReadWrite Property ReadingTransform As DisplayOrientations// You can use this property in JavaScript.
Value
DisplayOrientations DisplayOrientations DisplayOrientations DisplayOrientations

A DisplayOrientations -typed value that specifies the display orientation with which to align the sensor data.

ReadingType ReadingType ReadingType ReadingType

Gets the sensor reading type.

public : SensorReadingType ReadingType { get; }public SensorReadingType ReadingType { get; }Public ReadOnly Property ReadingType As SensorReadingType// You can use this property in JavaScript.
Value
SensorReadingType SensorReadingType SensorReadingType SensorReadingType

A SensorReadingType -typed value that specifies the sensor reading type.

ReportInterval ReportInterval ReportInterval ReportInterval

Gets or sets the current report interval for the inclinometer.

public : unsigned int ReportInterval { get; set; }public uint ReportInterval { get; set; }Public ReadWrite Property ReportInterval As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The current report interval.

Remarks

The report interval is specified in milliseconds.

The report interval will be set to a default value that will vary based on the sensor driver’s implementation. If your app does not want to use this default value, you should set the report interval to a non-zero value prior to registering an event handler or calling GetCurrentReading. The sensor will then attempt to allocate resources to satisfy the application’s requirements but the sensor also has to balance the needs of other apps using the sensor.

Changes to the report interval after an event handler has been registered or GetCurrentReading has been called may apply to the delivery of subsequent sensor readings.

Conversely, when an application is finished with the sensor, it should explicitly return the sensor to its default report interval by setting it to zero. This is important for power conservation, especially when using a language that may keep the sensor object active for an indefinite period prior to garbage collection.

The application should consult the MinimumReportInterval property prior to setting the report interval to ensure that the sensor can honor the requested report interval. Setting a value below the minimum supported interval will either trigger an exception or have undefined results.

Although the application can set this value to request a particular report interval, the driver will determine the actual report interval, based on internal logic. For example, the driver might use the shortest report interval that is requested by any caller.

Setting a value of zero requests the driver to use its default report interval. As with requesting a specific interval, the driver may choose a different interval based on other client requests and internal logic.

The Sensor platform automatically sets the change sensitivity for inclinometers based on the current report interval. This table specifies the change sensitivity values for given intervals.

Current report interval (specified in milliseconds)Change sensitivity (specified in degrees)
1 ms – 16 ms0.01 degreees
17 ms – 32 ms0.5 degrees
>= 33 ms2 degrees
See Also

ReportLatency ReportLatency ReportLatency ReportLatency

Gets or sets the delay between batches of sensor information.

public : unsigned int ReportLatency { get; set; }public uint ReportLatency { get; set; }Public ReadWrite Property ReportLatency As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The delay between batches of sensor information in milliseconds.

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

This property is in reference to the frequency of ReadingChanged events.

Not all sensors support ReportLatency. If the sensor does not support this property, it will function the same as if you set this value to 0. Setting this value to 0 will use the default latency for the sensor.

If you set ReportLatency to a value higher than the maximum supported latency, the sensor will use the maximum supported latency. However, this property will not change in value. The maximum possible ReportLatency equals the MaxBatchSize times the ReportInterval.

Be aware that multiple applications could be dependent on a single sensor. Each of those applications can set a different value for ReportLatency. In this scenario, the sensor needs to try to accommodate the lowest value for ReportLatency. Because of this, the actual latency may not match the latency defined by this property in your application. This property corresponds to your ideal latency, which may not be the same latency on the sensor.

For more information about sensor batching, see Sensors.

Methods

FromIdAsync(String) FromIdAsync(String) FromIdAsync(String) FromIdAsync(String)

Asynchronously obtains the sensor from its identifier.

public : static IAsyncOperation<Inclinometer> FromIdAsync(PlatForm::String deviceId)public static IAsyncOperation<Inclinometer> FromIdAsync(String deviceId)Public Static Function FromIdAsync(deviceId As String) As IAsyncOperation( Of Inclinometer )// You can use this method in JavaScript.
Parameters
deviceId
PlatForm::String String String String

The sensor identifier

Returns
Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

GetCurrentReading() GetCurrentReading() GetCurrentReading() GetCurrentReading()

Gets the current inclinometer reading.

public : InclinometerReading GetCurrentReading()public InclinometerReading GetCurrentReading()Public Function GetCurrentReading() As InclinometerReading// You can use this method in JavaScript.
Returns

Remarks

An application may use this method to poll the sensor for the current reading as an alternative to registering a ReadingChanged event handler. This would be the preferred alternative for an application that updates its user interface at a specific frame rate. Whether polling once or many times, the application must establish a desired ReportInterval. This informs the sensor driver that resources should be allocated to satisfy subsequent polling requests

Before using the return value from this method, the application must first check that the value is not null. (If the value is null and you attempt to retrieve it, Windows will generate an exception.)

The following example demonstrates how a Windows Store app built with XAML and C# retrieves the current reading for the default inclinometer.

private void DisplayCurrentReading(object sender, object args)
{
    InclinometerReading reading = _inclinometer.GetCurrentReading();
    if (reading != null)
    {
        ScenarioOutput_X.Text = String.Format("{0,5:0.00}", reading.PitchDegrees);
        ScenarioOutput_Y.Text = String.Format("{0,5:0.00}", reading.RollDegrees);
        ScenarioOutput_Z.Text = String.Format("{0,5:0.00}", reading.YawDegrees);
    }
}

The following example demonstrates how a Windows Store app built for Windows using JavaScript retrieves the current reading for the default inclinometer.

function getCurrentReading() {
    var reading = inclinometer.getCurrentReading();
    if (reading) {
        document.getElementById("readingOutputX").innerHTML = reading.pitchDegrees.toFixed(2);
        document.getElementById("readingOutputY").innerHTML = reading.rollDegrees.toFixed(2);
        document.getElementById("readingOutputZ").innerHTML = reading.yawDegrees.toFixed(2);
    }
}

GetDefault() GetDefault() GetDefault() GetDefault()

Returns the default inclinometer for absolute readings.

public : static Inclinometer GetDefault()public static Inclinometer GetDefault()Public Static Function GetDefault() As Inclinometer// You can use this method in JavaScript.
Returns

The default inclinometer or null if no inclinometers are found.

Remarks

This method returns the same result as GetDefault(SensorReadingType.Absolute)

This method only returns values for hardware that has been integrated into the computer by the manufacturer. (The inclinometer readings are derived from multiple sensors.) A null value will be returned if the specified sensor is not available in the system.

When a system is in Connected Standby, a call to the GetDefault method will return immediately with a null result.

The following example demonstrates how a Windows Store app built with XAML and C# used this method to establish a connection to the default inclinometer.

_inclinometer = Inclinometer.GetDefault();

The following example demonstrates how a Windows Store app built for Windows using JavaScript used this method to establish a connection to the default inclinometer.

inclinometer = Windows.Devices.Sensors.Inclinometer.getDefault();
See Also

GetDefault(SensorReadingType) GetDefault(SensorReadingType) GetDefault(SensorReadingType) GetDefault(SensorReadingType)

Returns the default inclinometer based on the SensorReadingType.

public : static Inclinometer GetDefault(SensorReadingType sensorReadingtype)public static Inclinometer GetDefault(SensorReadingType sensorReadingtype)Public Static Function GetDefault(sensorReadingtype As SensorReadingType) As Inclinometer// You can use this method in JavaScript.
Parameters
sensorReadingtype
SensorReadingType SensorReadingType SensorReadingType SensorReadingType

The type of sensor to retrieve.

Returns

The default inclinometer or null if no inclinometers are found.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

This method only returns values for hardware that has been integrated into the computer by the manufacturer. (The inclinometer readings are derived from multiple sensors.) A null value will be returned if the specified sensor is not available in the system.

When a system is in Connected Standby, a call to the GetDefault method will return immediately with a null result.

See Also

GetDefaultForRelativeReadings() GetDefaultForRelativeReadings() GetDefaultForRelativeReadings() GetDefaultForRelativeReadings()

Returns the default inclinometer for relative readings.

public : static Inclinometer GetDefaultForRelativeReadings()public static Inclinometer GetDefaultForRelativeReadings()Public Static Function GetDefaultForRelativeReadings() As Inclinometer// You can use this method in JavaScript.
Returns

The default inclinometer or null if no inclinometers are found.

Remarks

This method returns the same result as GetDefault(SensorReadingType.Relative)

GetDeviceSelector(SensorReadingType) GetDeviceSelector(SensorReadingType) GetDeviceSelector(SensorReadingType) GetDeviceSelector(SensorReadingType)

Gets the device selector.

public : static PlatForm::String GetDeviceSelector(SensorReadingType readingType)public static string GetDeviceSelector(SensorReadingType readingType)Public Static Function GetDeviceSelector(readingType As SensorReadingType) As string// You can use this method in JavaScript.
Parameters
readingType
SensorReadingType SensorReadingType SensorReadingType SensorReadingType

The type of sesnsor to retrieve.

Returns
PlatForm::String string string string

Returns the device selector, if it exists; otherwise, null.

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Events

ReadingChanged ReadingChanged ReadingChanged ReadingChanged

Occurs each time the inclinometer reports a new sensor reading.

public : event TypedEventHandler ReadingChanged<Inclinometer,  InclinometerReadingChangedEventArgs>public event TypedEventHandler ReadingChanged<Inclinometer,  InclinometerReadingChangedEventArgs>Public Event ReadingChanged<Inclinometer,  InclinometerReadingChangedEventArgs>// You can use this event in JavaScript.

Remarks

Applications can set the frequency of this event by setting the ReportInterval property.

The following example demonstrates how a Windows Store app built with C# and XAML registered its ReadingChanged event handler.

private void ScenarioEnable(object sender, RoutedEventArgs e)
{
    if (_inclinometer != null)
    {
        // Establish the report interval
        _inclinometer.ReportInterval = _desiredReportInterval;

        Window.Current.VisibilityChanged += new WindowVisibilityChangedEventHandler(VisibilityChanged);
        _inclinometer.ReadingChanged += new TypedEventHandler<Inclinometer, InclinometerReadingChangedEventArgs>(ReadingChanged);

        ScenarioEnableButton.IsEnabled = false;
        ScenarioDisableButton.IsEnabled = true;
    }
    else
    {
        rootPage.NotifyUser("No inclinometer found", NotifyType.StatusMessage);
    }
}

The following example shows the ReadingChanged event handler.

async private void ReadingChanged(object sender, InclinometerReadingChangedEventArgs e)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        InclinometerReading reading = e.Reading;
        ScenarioOutput_X.Text = String.Format("{0,5:0.00}", reading.PitchDegrees);
        ScenarioOutput_Y.Text = String.Format("{0,5:0.00}", reading.RollDegrees);
        ScenarioOutput_Z.Text = String.Format("{0,5:0.00}", reading.YawDegrees);
    });
}

The following example demonstrates how a Windows Store app built with JavaScript registers its ReadingChanged event handler.

function enableReadingChangedScenario() {
    if (inclinometer) {
        // Set the reportInterval to enable the sensor events
        inclinometer.reportInterval = reportInterval;

        document.addEventListener("msvisibilitychange", msVisibilityChangeHandler, false);
        inclinometer.addEventListener("readingchanged", onDataChanged);
        document.getElementById("scenario1Open").disabled = true;
        document.getElementById("scenario1Revoke").disabled = false;
    } else {
        WinJS.log && WinJS.log("No inclinometer found", "sample", "error");
    }
}

The following example shows the ReadingChanged event handler.

function onDataChanged(e) {
    var reading = e.reading;

    document.getElementById("eventOutputX").innerHTML = reading.pitchDegrees.toFixed(2);
    document.getElementById("eventOutputY").innerHTML = reading.rollDegrees.toFixed(2);
    document.getElementById("eventOutputZ").innerHTML = reading.yawDegrees.toFixed(2);
}

See Also