PositionSource QML Type
El tipo PositionSource proporciona la posición actual del dispositivo. Más información...
| Import Statement: | import QtPositioning |
Propiedades
- active : bool
- name : string
- parameters : list<PluginParameter>
(since QtPositioning 5.14) - position : Position
- preferredPositioningMethods : enumeration
- sourceError : enumeration
- supportedPositioningMethods : enumeration
- updateInterval : int
- valid : bool
Métodos
- var backendProperty(string name)
(since Qt Positioning 5.14) - bool setBackendProperty(string name, var value)
(since Qt Positioning 5.14) - void start()
- void stop()
- void update(int timeout)
Descripción detallada
El tipo PositionSource proporciona información sobre la posición actual del dispositivo del usuario. La posición está disponible como un objeto de tipo « Position », que contiene todos los parámetros estándar que suelen ofrecer el GPS y otros sistemas similares, incluyendo la longitud, la latitud, la velocidad y los detalles de precisión.
Dado que hay diferentes fuentes de posición disponibles en distintas plataformas y dispositivos, estas se clasifican según su tipo básico (Satélite, No satélite y Todos los métodos de posicionamiento). Los métodos disponibles para la plataforma actual se pueden enumerar en la propiedad supportedPositioningMethods.
Para indicar qué métodos son adecuados para su aplicación, configure la propiedad ` preferredPositioningMethods `. Si los métodos preferidos no están disponibles, se elegirá en su lugar la fuente predeterminada de datos de ubicación para la plataforma. Si no hay ninguna fuente predeterminada disponible (ya sea porque no hay ninguna instalada para la plataforma de ejecución o porque está desactivada), la propiedad ` valid ` se establecerá en `false`.
La propiedad ` updateInterval ` puede utilizarse entonces para indicar con qué frecuencia desea su aplicación recibir actualizaciones de posición. Los métodos ` start()`, ` stop()` y ` update()` pueden utilizarse para controlar el funcionamiento de `PositionSource`, así como la propiedad ` active `, cuyo valor, cuando se establece, equivale a llamar a ` start()` o ` stop()`.
Cuando el PositionSource está activo, las actualizaciones de posición se pueden recuperar simplemente utilizando la propiedad ` position ` en un enlace (como valor de la propiedad de otro elemento) o proporcionando una implementación del controlador de señales ` onPositionChanged `.
Ejemplo de uso
El siguiente ejemplo muestra un PositionSource sencillo que se utiliza para recibir actualizaciones cada segundo y mostrar la longitud y la latitud en la consola.
PositionSource {
id: src
updateInterval: 1000
active: true
onPositionChanged: {
var coord = src.position.coordinate;
console.log("Coordinate:", coord.longitude, coord.latitude);
}
}Control del estado de funcionamiento
Como se ha mencionado anteriormente, PositionSource ofrece dos formas de controlar su estado de funcionamiento:
- Utilizando la propiedad vinculable « active ».
- Mediante los métodos ` start()` y ` stop()`.
Nota: Es muy importante no mezclar estos enfoques. Si se utiliza una propiedad vinculable ` active ` para controlar el objeto `PositionSource`, pero posteriormente se llama a ` start()` o ` stop()` desde otra parte del código, el enlace se rompe, lo que puede provocar, por ejemplo, que un elemento de la interfaz de usuario ya no esté conectado a ningún objeto subyacente.
Consideremos el siguiente ejemplo de código incorrecto en el que la propiedad ` active ` está vinculada al estado de un cuadro de selección (CheckBox), y la llamada a ` stop()` en el controlador de señal ` onClicked ` rompe dicha vinculación.
Window {
width: 640
height: 480
visible: true
PositionSource {
id: posSource
name: "geoclue2"
active: cb.checked
}
Column {
anchors.centerIn: parent
spacing: 20
CheckBox {
id: cb
}
Button {
id: btn
text: "Stop"
onClicked: {
posSource.stop()
}
}
}
}Al hacer clic en el botón «Stop», se ejecuta ` stop()`, y se rompe el enlace de la propiedad ` active `. En este momento, el elemento de la interfaz de usuario `CheckBox` ya no controla el objeto `PositionSource`.
Una solución sencilla en este caso es actualizar el estado del CheckBox desde el controlador de onClicked. En cuanto se desmarque el CheckBox, se notificará a la propiedad active y el estado del objeto PositionSource se actualizará en consecuencia. La interfaz de usuario también se mantendrá en un estado coherente.
Button {
id: btn
text: "Stop"
onClicked: {
cb.checked = false
}
}Nota: El uso de update() para solicitar una única actualización de posición no tiene ningún efecto sobre los enlaces de la propiedad active, por lo que pueden utilizarse conjuntamente sin ningún problema.
Véase también QtPositioning::Position, QGeoPositionInfoSource, PluginParameter y Propiedades vinculables de Qt.
Documentación sobre propiedades
active : bool
Esta propiedad indica si la fuente de posición está activa. Establecer esta propiedad en «false» equivale a llamar a ` stop`, y establecerla en «true» equivale a llamar a ` start`.
Véase también start, stop y update.
name : string
Esta propiedad contiene el nombre interno único del complemento que proporciona actualmente la información de posición.
Al configurar esta propiedad, se hace que PositionSource utilice un proveedor de posicionamiento concreto. Si PositionSource está activo en el momento en que se modifica la propiedad «name», pasará a estar inactivo. Si no se puede cargar el proveedor de posicionamiento especificado, la fuente de posición dejará de ser válida.
Al modificar la propiedad «name», es posible que también cambien las propiedades « updateInterval », « supportedPositioningMethods » y « preferredPositioningMethods ».
parameters : list<PluginParameter> [default, since QtPositioning 5.14]
Esta propiedad contiene la lista de parámetros del complemento.
Esta propiedad se introdujo en QtPositioning 5.14.
position : Position
Esta propiedad contiene los últimos datos de posición conocidos. Es una propiedad de solo lectura.
El tipo «Position» cuenta con diferentes variables miembro de posición, cuya validez puede comprobarse mediante las funciones de validez adecuadas (por ejemplo, a veces una actualización no incluye datos de velocidad o altitud).
Sin embargo, siempre que se haya recibido una señal positionChanged, se puede dar por hecho que, como mínimo, position::coordinate::latitude, position::coordinate::longitude y position::timestamp son válidas.
Véase también start, stop y update.
preferredPositioningMethods : enumeration
Esta propiedad contiene los métodos de posicionamiento preferidos de la fuente actual.
| Constante | Descripción |
|---|---|
PositionSource.NoPositioningMethods | No hay ningún método de posicionamiento preferido. |
PositionSource.SatellitePositioningMethods | Se deben preferir los métodos de posicionamiento basados en satélites, como el GPS. |
PositionSource.NonSatellitePositioningMethods | Se deben preferir los métodos no basados en satélites. |
PositionSource.AllPositioningMethods | Cualquier método de posicionamiento es aceptable. |
sourceError : enumeration
Esta propiedad contiene el último error que se produjo con PositionSource.
| Constante | Descripción |
|---|---|
PositionSource.AccessError | El establecimiento de la conexión con el backend de posicionamiento remoto ha fallado porque la aplicación carecía de los privilegios necesarios. |
PositionSource.ClosedError | El backend de posicionamiento cerró la conexión, lo que ocurre, por ejemplo, cuando el usuario desactiva los servicios de localización. En cuanto se vuelvan a activar los servicios de localización, se reanudarán las actualizaciones periódicas. |
PositionSource.NoError | No se ha producido ningún error. |
PositionSource.UnknownSourceError | Se ha producido un error no identificado. |
PositionSource.UpdateTimeoutError | No se ha podido recuperar la posición actual dentro del tiempo de espera especificado, o este PositionSource ha determinado que no podrá proporcionar más actualizaciones periódicas. |
supportedPositioningMethods : enumeration
Esta propiedad contiene los métodos de posicionamiento compatibles con la fuente actual.
| Constante | Descripción |
|---|---|
PositionSource.NoPositioningMethods | No se admiten métodos de posicionamiento (no hay fuente). |
PositionSource.SatellitePositioningMethods | Se admiten métodos de posicionamiento basados en satélites, como el GPS. |
PositionSource.NonSatellitePositioningMethods | Se admiten métodos no basados en satélites. |
PositionSource.AllPositioningMethods | Se admiten tanto los métodos de posicionamiento basados en satélites como los no basados en satélites. |
updateInterval : int
Esta propiedad establece el intervalo deseado entre actualizaciones (en milisegundos).
Véase también QGeoPositionInfoSource::updateInterval().
valid : bool
Esta propiedad es «true» si el objeto « PositionSource » ha obtenido un complemento de backend válido para proporcionar datos. Si es «false», los demás métodos de « PositionSource » no tendrán ningún efecto.
Las aplicaciones deben comprobar esta propiedad para determinar si el posicionamiento está disponible y habilitado en la plataforma de ejecución, y actuar en consecuencia.
Documentación de métodos
[since Qt Positioning 5.14] var backendProperty(string name)
Devuelve el valor de la propiedad específica del backend denominada « name », si existe. En caso contrario, incluso si se invoca sobre un « PositionSource » no inicializado, el valor devuelto no será válido. Las propiedades específicas de backend compatibles se enumeran y describen en Qt Positioning plugins#Default plugins.
Este método se introdujo en Qt Positioning 5.14.
Véase también setBackendProperty y QGeoPositionInfoSource::setBackendProperty.
[since Qt Positioning 5.14] bool setBackendProperty(string name, var value)
Establece la propiedad específica del backend denominada « name » en « value ». Devuelve «true» si se realiza correctamente y «false» en caso contrario, incluso si se invoca sobre un « PositionSource » no inicializado. Las propiedades específicas del backend compatibles se enumeran y describen en Qt Positioning plugins#Default plugins.
Este método se introdujo en Qt Positioning 5.14.
Véase también backendProperty y QGeoPositionInfoSource::setBackendProperty.
void start()
Solicita actualizaciones a la fuente de ubicación. Utiliza ` updateInterval ` si está definido; en caso contrario, se utiliza el intervalo predeterminado. Si no hay ninguna fuente disponible, este método no tiene ningún efecto.
Nota: Al llamar a este método se rompen los enlaces de la propiedad active.
Véase también stop(), update() y active.
void stop()
Detiene las actualizaciones procedentes de la fuente de ubicación. Si no hay ninguna fuente disponible o esta no está activa, este método no tiene ningún efecto.
Nota: Al llamar a este método se rompen los enlaces de la propiedad ` active `.
Véase también start(), update() y active.
void update(int timeout)
Un método práctico para solicitar una única actualización desde la fuente de ubicación. Si no hay ninguna fuente disponible, este método no tiene ningún efecto.
Si la fuente de posición no está activa, se activará durante el tiempo que sea necesario para recibir una actualización, o hasta que se agote el tiempo de espera de la solicitud. El tiempo de espera de la solicitud depende de la fuente.
El tiempo de espera de la solicitud ( timeout ) se especifica en milisegundos. Si el tiempo de espera de la solicitud ( timeout ) es cero (el valor por defecto), se establece por defecto en un periodo de tiempo de espera razonable y adecuado para la fuente.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.