SatelliteSource QML Type | Qt Positioning | Qt 6.12.0
Description: The SatelliteSource class provides the satellite information.
Keywords: qmltype

- Qt 6.12
- Qt Positioning
- QML Types
- SatelliteSource
- Qt 6.12.0 Reference Documentation

# SatelliteSource QML Type

The SatelliteSource class provides the satellite information. More...

Import Statement: | `import QtPositioning`
Since: | Qt 6.5

- List of all members, including inherited members

## Properties

- active : bool
- name : string
- parameters : list<PluginParameter>
- satellitesInUse : list<geoSatelliteInfo>
- satellitesInView : list<geoSatelliteInfo>
- sourceError : enumeration
- updateInterval : int
- valid : bool

## Methods

- var backendProperty(string name)
- bool setBackendProperty(string name, var value)
- void start()
- void stop()
- void update(int timeout)

## Detailed Description

The SatelliteSource class provides information about satellites in use and satellites in view. This class is a QML representation of QGeoSatelliteInfoSource.

Like its C++ equivalent, the class supports different plugins. Use the name property to specify the name of the plugin to be used, and provide PluginParameters, if required. If the name property is not set, a default plugin will be used. See Qt Positioning Plugins for more information on the available plugins.

Use the valid property to check the SatelliteSource state.

Use the updateInterval property to indicate how often your application wants to receive the satellite information updates. The start(), stop() and update() methods can be used to control the operation of the SatelliteSource, as well as the active property, which when set is equivalent to calling start() or stop().

When the SatelliteSource is active, satellite information updates can be retrieved using the satellitesInView and satellitesInUse properties.

If an error happens during satellite information updates, use the sourceError property to get the actual error code.

### Example Usage

The following example shows a SatelliteSource which is using the NMEA plugin to receive satellite information updates every second and print the amount of satellites in view and satellites in use to the console.

     SatelliteSource {
         id: source
         name: "nmea"
         active: true
         updateInterval: 1000
         PluginParameter { name: "nmea.source"; value: "serial:/dev/ttyACM0" }

         onSatellitesInUseChanged: {
             console.log("Satellites in use:", source.satellitesInUse.length)
         }
         onSatellitesInViewChanged: {
             console.log("Satellites in view:", source.satellitesInView.length)
         }
     }

See also QGeoSatelliteInfoSource, PluginParameter, and geoSatelliteInfo.

## Property Documentation

### active : bool

This property indicates whether the satellite source is active. Setting this property to `false` equals calling stop, and setting this property to `true` equals calling start.

See also start, stop, and update.

### name : string

This property holds the unique internal name for the plugin currently providing satellite information.

Setting the property causes the SatelliteSource to use a particular backend plugin. If the SatelliteSource is active at the time that the name property is changed, it will become inactive. If the specified backend cannot be loaded the satellite source will become invalid.

Changing the name property may cause the updateInterval property to change as well.

### parameters : list<PluginParameter> `[default read-only]`

This property holds the list of plugin parameters.

See also PluginParameter.

### satellitesInUse : list<geoSatelliteInfo> `[read-only]`

This property holds the list of satellites that are currently in use. These are the satellites that are used to get a "fix" - that is, those used to determine the current position.

### satellitesInView : list<geoSatelliteInfo> `[read-only]`

This property holds the list of satellites that are currently in view.

### sourceError : enumeration `[read-only]`

This property holds the error which last occurred with the backend data provider.

Constant | Description
--- | ---
`SatelliteSource.AccessError` | The connection setup to the satellite backend failed because the application lacked the required privileges.
`SatelliteSource.ClosedError` | The satellite backend closed the connection, which happens for example in case the user is switching location services to off.
`SatelliteSource.NoError` | No error has occurred.
`SatelliteSource.UnknownSourceError` | An unidentified error occurred.
`SatelliteSource.UpdateTimeoutError` | The satellite information could not be retrieved within the specified timeout.

### updateInterval : int

This property holds the desired interval between updates in milliseconds.

### valid : bool `[read-only]`

This property is `true` if the SatelliteSource object has acquired a valid backend plugin to provide data, and `false` otherwise.

Applications should check this property to determine whether providing satellite information is available and enabled on the runtime platform, and react accordingly.

## Method Documentation

### var backendProperty(string name)

Returns the value of the backend-specific property named name, if present. Otherwise, including if called on an uninitialized SatelliteSource, the return value will be invalid.

See also setBackendProperty().

### bool setBackendProperty(string name, var value)

Sets the backend-specific property named name to value. Returns true on success, false otherwise, including if called on an uninitialized SatelliteSource.

See also backendProperty().

### void start()

Requests updates from the satellite source. Uses updateInterval if set, default interval otherwise. If there is no source available, this method has no effect.

See also stop(), update(), and active.

### void stop()

Stops updates from the satellite source. If there is no source available or it is not active, this method has no effect.

See also start(), update(), and active.

### void update(int timeout = 0)

A convenience method to request a single update from the satellite source. If there is no source available, this method has no effect.

If the satellite source is not active, it will be activated for as long as it takes to receive an update, or until the request times out. The request timeout period is plugin-specific.

The timeout is specified in milliseconds. If the timeout is zero (the default value), it defaults to a reasonable timeout period as appropriate for the source.

See also start(), stop(), and active.