1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qsensor.h"
5#include "qsensor_p.h"
6#include "qsensorbackend.h"
7#include "qsensormanager.h"
8#include <QDebug>
9#include <QMetaProperty>
10#include <QTimer>
11
12QT_BEGIN_NAMESPACE
13
14/*!
15 \typedef qrange
16 \relates QSensor
17 \since 5.1
18
19 This type is defined as a QPair.
20
21 \code
22 typedef QPair<int,int> qrange;
23 \endcode
24
25 \sa QPair, qrangelist, QSensor::availableDataRates
26*/
27
28/*!
29 \typedef qrangelist
30 \relates QSensor
31 \since 5.1
32
33 This type is defined as a list of qrange values.
34
35 \code
36 typedef QList<qrange> qrangelist;
37 \endcode
38
39 \sa QList, qrange, QSensor::availableDataRates
40*/
41
42/*!
43 \class qoutputrange
44 \inmodule QtSensors
45 \brief The qoutputrange class holds the specifics of an output range.
46 \since 5.1
47
48 The class is defined as a simple struct.
49
50 \code
51 struct qoutputrange
52 {
53 qreal maximum;
54 qreal minimum;
55 qreal accuracy;
56 };
57 \endcode
58
59 Each output range specifies a minimum and maximum value as well as an accuracy value.
60 The accuracy value represents the resolution of the sensor. It is the smallest change
61 the sensor can detect and is expressed using the same units as the minimum and maximum.
62
63 Sensors must often trade off range for accuracy. To allow the user to determine which of
64 these are more important the sensor may offer several output ranges. One output
65 range may have reduced minimum and maximum values and increased sensitivity. Another output
66 range may have higher minimum and maximum values with reduced sensitivity. Note that higher
67 sensitivities will be represented by smaller accuracy values.
68
69 An example of this tradeoff can be seen by examining the LIS302DL accelerometer. It has only
70 256 possible values to report with. These values are scaled so that they can represent either
71 -2G to +2G (with an accuracy value of 0.015G) or -8G to +8G (with an accuracy value of 0.06G).
72
73 \sa qoutputrangelist, QSensor::outputRanges
74*/
75
76/*!
77 \variable qoutputrange::maximum
78
79 This is the maximum value for this output range.
80 The units are defined by the sensor.
81*/
82
83/*!
84 \variable qoutputrange::minimum
85
86 This is the minimum value for this output range.
87 The units are defined by the sensor.
88*/
89
90/*!
91 \variable qoutputrange::accuracy
92
93 The accuracy value represents the resolution of the sensor. It is the smallest change
94 the sensor can detect and is expressed using the same units as the minimum and maximum.
95*/
96
97/*!
98 \typedef qoutputrangelist
99 \relates QSensor
100 \since 5.1
101
102 This type is defined as a list of qoutputrange values.
103
104 \code
105 typedef QList<qoutputrange> qoutputrangelist;
106 \endcode
107
108 \sa QList, qoutputrange, QSensor::outputRanges
109*/
110
111static void registerTypes()
112{
113 qRegisterMetaType<qrange>(typeName: "qrange");
114 qRegisterMetaType<qrangelist>(typeName: "qrangelist");
115 qRegisterMetaType<qoutputrangelist>(typeName: "qoutputrangelist");
116}
117Q_CONSTRUCTOR_FUNCTION(registerTypes)
118
119// =====================================================================
120
121void QSensorPrivate::init(const QByteArray &sensorType)
122{
123 Q_Q(QSensor);
124 type = sensorType;
125 q->registerInstance(); // so the availableSensorsChanged() signal works
126}
127
128/*!
129 \class QSensor
130 \ingroup sensors_main
131 \inmodule QtSensors
132 \since 5.1
133
134 \brief The QSensor class represents a single hardware sensor.
135
136 The life cycle of a sensor is typically:
137
138 \list
139 \li Create a sub-class of QSensor on the stack or heap.
140 \li Setup as required by the application.
141 \li Start receiving values.
142 \li Sensor data is used by the application.
143 \li Stop receiving values.
144 \endlist
145
146 The sensor data is delivered via QSensorReading and its sub-classes.
147
148 \section1 Orientation
149
150 Some sensors react to screen orientation changes, such as QAccelerometer, QMagnetometer and
151 QRotationSensor. These are so called \e orientable sensors. For orientable sensors,
152 QSensor supports changing the reporting of the reading values based on the orientation of the
153 screen.
154
155 For orientable sensors, the axesOrientationMode property controls how the orientation affects
156 the reading values.
157
158 In the default mode, QSensor::FixedOrientation, the reading values remain
159 unaffected by the orientation. In the QSensor::AutomaticOrientation mode, the reading
160 values are automatically rotated by taking the current screen orientation into account. And
161 finally, in the QSensor::UserOrientation mode, the reading values are rotated
162 according to a user-specified orientation.
163
164 The functionality of this is only available if it is supported by the backend and if the sensor
165 is orientable, which can be checked by calling QSensor::isFeatureSupported()
166 with the QSensor::AxesOrientation flag.
167
168 The orientation values here are always of the screen orientation, not the device orientation.
169 The screen orientation is the orientation of the GUI. For example when rotating a device by 90
170 degrees counter-clockwise, the screen orientation compensates for that by rotating 90 degrees
171 clockwise, to the effect that the GUI is still facing upright after the device has been rotated.
172 Note that applications can lock the screen orientation, for example to force portrait or landscape
173 mode. For locked orientations, orientable sensors will not react with reading changes if the device
174 orientation is changed, as orientable sensors react to screen orientation changes only. This makes
175 sense, as the purpose of orientable sensors is to keep the sensor orientation in sync with the screen
176 orientation.
177
178 The orientation values range from 0 to 270 degrees. The orientation is applied in clockwise direction,
179 e.g. an orientation value of 90 degrees means that the screen has been rotated 90 degress to the right
180 from its origin position, to compensate a device rotation of 90 degrees to the left.
181
182 \sa QSensorReading
183*/
184
185/*!
186 \enum QSensor::Feature
187 \brief Lists optional features a backend might support.
188
189 The features common to all sensor types are:
190
191 \value Buffering The backend supports buffering of readings, controlled by the
192 QSensor::bufferSize property.
193 \value AlwaysOn The backend supports changing the policy on whether to suspend when idle,
194 controlled by the QSensor::alwaysOn property.
195 \value SkipDuplicates The backend supports skipping of same or very similar successive
196 readings. This can be enabled by setting the QSensor::skipDuplicates
197 property to true.
198
199 The features of QMagnetometer are:
200
201 \value GeoValues The backend supports returning geo values, which can be
202 controlled with the QMagnetometer::returnGeoValues property.
203
204 The features of QLightSensor are:
205
206 \value FieldOfView The backend specifies its field of view, which can be
207 read from the QLightSensor::fieldOfView property.
208
209 The features of QAccelerometer are:
210
211 \value AccelerationMode The backend supports switching the acceleration mode
212 of the acceleromter with the QAccelerometer::accelerationMode property.
213
214 The features of QPressureSensor are:
215
216 \value PressureSensorTemperature The backend provides the pressure sensor's die temperature
217
218 The features of all orientable sensors are:
219
220 \value AxesOrientation The backend supports changing the axes orientation from the default of
221 QSensor::FixedOrientation to something else.
222
223 \omitvalue Reserved
224
225 \sa QSensor::isFeatureSupported()
226 \since 5.0
227*/
228
229/*!
230 Construct the \a type sensor as a child of \a parent.
231
232 Do not use this constructor if a derived class exists for the specific sensor type.
233
234 The wrong way is to use the base class constructor:
235 \snippet sensors/creating.cpp 3
236 The right way is to create an instance of the derived class:
237 \snippet sensors/creating.cpp 2
238
239 The derived classes have
240 additional properties and data members which are needed for certain features such as
241 geo value support in QMagnetometer or acceleration mode support in QAccelerometer.
242 These features will only work properly when creating a sensor instance from a QSensor
243 subclass.
244
245 Only use this constructor if there is no derived sensor class available. Note that all
246 built-in sensors have a derived class, so using this constructor should only be necessary
247 when implementing custom sensors.
248*/
249QSensor::QSensor(const QByteArray &type, QObject *parent)
250 : QObject(*new QSensorPrivate, parent)
251{
252 Q_D(QSensor);
253 d->init(sensorType: type);
254}
255
256/*! \internal
257 */
258QSensor::QSensor(const QByteArray &type, QSensorPrivate &dd, QObject* parent)
259 : QObject(dd, parent)
260{
261 Q_D(QSensor);
262 d->init(sensorType: type);
263}
264
265/*! \internal
266 */
267QSensorBackend *QSensor::backend() const
268{
269 Q_D(const QSensor);
270 return d->backend;
271}
272
273/*!
274 Destroy the sensor. Stops the sensor if it has not already been stopped.
275*/
276QSensor::~QSensor()
277{
278 Q_D(QSensor);
279 stop();
280 for (QSensorFilter *filter : d->filters)
281 filter->setSensor(0);
282 delete d->backend;
283 d->backend = 0;
284 // owned by the backend
285 d->device_reading = 0;
286 d->filter_reading = 0;
287 d->cache_reading = 0;
288}
289
290/*!
291 \property QSensor::connectedToBackend
292 \brief a value indicating if the sensor has connected to a backend.
293
294 A sensor that has not been connected to a backend cannot do anything useful.
295
296 Call the connectToBackend() method to force the sensor to connect to a backend
297 immediately. This is automatically called if you call start() so you only need
298 to do this if you need access to sensor properties (ie. to poll the sensor's
299 meta-data before you use it).
300*/
301
302bool QSensor::isConnectedToBackend() const
303{
304 Q_D(const QSensor);
305 return (d->backend != 0);
306}
307
308/*!
309 \property QSensor::identifier
310 \brief the backend identifier for the sensor.
311
312 Note that the identifier is filled out automatically
313 when the sensor is connected to a backend. If you want
314 to connect a specific backend, you should call
315 setIdentifier() before connectToBackend().
316*/
317
318QByteArray QSensor::identifier() const
319{
320 Q_D(const QSensor);
321 return d->identifier;
322}
323
324void QSensor::setIdentifier(const QByteArray &identifier)
325{
326 Q_D(QSensor);
327 if (isConnectedToBackend()) {
328 qWarning() << "ERROR: Cannot call QSensor::setIdentifier while connected to a backend!";
329 return;
330 }
331 if (d->identifier == identifier)
332 return;
333 d->identifier = identifier;
334 emit identifierChanged();
335}
336
337/*!
338 \property QSensor::type
339 \brief the type of the sensor.
340*/
341
342QByteArray QSensor::type() const
343{
344 Q_D(const QSensor);
345 return d->type;
346}
347
348/*!
349 Try to connect to a sensor backend.
350
351 Returns true if a suitable backend could be found, false otherwise.
352
353 The type must be set before calling this method if you are using QSensor directly.
354
355 \sa isConnectedToBackend()
356*/
357bool QSensor::connectToBackend()
358{
359 Q_D(QSensor);
360 if (isConnectedToBackend())
361 return true;
362
363 int dataRate = d->dataRate;
364 int outputRange = d->outputRange;
365
366 d->backend = QSensorManager::createBackend(sensor: this);
367
368 if (d->backend) {
369 // Reset the properties to their default values and re-set them now so
370 // that the logic we've put into the setters gets called.
371 if (dataRate != 0) {
372 d->dataRate = 0;
373 setDataRate(dataRate);
374 }
375 if (outputRange != -1) {
376 d->outputRange = -1;
377 setOutputRange(outputRange);
378 }
379 }
380
381 return isConnectedToBackend();
382}
383
384/*!
385 \property QSensor::busy
386 \brief a value to indicate if the sensor is busy.
387
388 Some sensors may be on the system but unavailable for use.
389 This function will return true if the sensor is busy. You
390 will not be able to start() the sensor.
391
392 Note that this function does not return true if you
393 are using the sensor, only if another process is using
394 the sensor.
395
396 \sa busyChanged()
397*/
398
399bool QSensor::isBusy() const
400{
401 Q_D(const QSensor);
402 return d->busy;
403}
404
405/*!
406 \fn QSensor::busyChanged()
407
408 This signal is emitted when the sensor is no longer busy.
409 This can be used to grab a sensor when it becomes available.
410
411 \code
412 sensor.start();
413 if (sensor.isBusy()) {
414 // need to wait for busyChanged signal and try again
415 }
416 \endcode
417*/
418
419/*!
420 \property QSensor::active
421 \brief a value to indicate if the sensor is active.
422
423 This is true if the sensor is active (returning values). This is false otherwise.
424
425 Note that setting this value to true will not have an immediate effect. Instead,
426 the sensor will be started once the event loop has been reached.
427*/
428void QSensor::setActive(bool active)
429{
430 if (active == isActive())
431 return;
432
433 if (active)
434 QTimer::singleShot(msec: 0, receiver: this, SLOT(start())); // delay ensures all properties have been set if using QML
435 else
436 stop();
437}
438
439bool QSensor::isActive() const
440{
441 Q_D(const QSensor);
442 return d->active;
443}
444
445/*!
446 \property QSensor::alwaysOn
447 \brief a value to indicate if the sensor should remain running when the screen is off.
448
449 Some platforms have a policy of suspending sensors when the screen turns off.
450 Setting this property to true will ensure the sensor continues to run.
451*/
452/*!
453 \fn QSensor::alwaysOnChanged()
454
455 This signal is emitted when the alwaysOn property changes.
456*/
457void QSensor::setAlwaysOn(bool alwaysOn)
458{
459 Q_D(QSensor);
460 if (d->alwaysOn == alwaysOn) return;
461 d->alwaysOn = alwaysOn;
462 emit alwaysOnChanged();
463}
464
465bool QSensor::isAlwaysOn() const
466{
467 Q_D(const QSensor);
468 return d->alwaysOn;
469}
470
471/*!
472 \property QSensor::skipDuplicates
473 \brief Indicates whether duplicate reading values should be omitted.
474 \since 5.1
475
476 When duplicate skipping is enabled, successive readings with the same or very
477 similar values are omitted. This helps reducing the amount of processing done, as less sensor
478 readings are made available. As a consequence, readings arrive at an irregular interval.
479
480 Duplicate skipping is not just enabled for readings that are exactly the same, but also for
481 readings that are quite similar, as each sensor has a bit of jitter even if the device is
482 not moved.
483
484 Support for this property depends on the backend. Use isFeatureSupported() to check if it is
485 supported on the current platform.
486
487 Duplicate skipping is disabled by default.
488
489 Duplicate skipping takes effect when the sensor is started, changing the property while the
490 sensor is active has no immediate effect.
491*/
492bool QSensor::skipDuplicates() const
493{
494 Q_D(const QSensor);
495 return d->skipDuplicates;
496}
497
498/*!
499 Sets the duplicate skipping to \a skipDuplicates.
500
501 \since 5.1
502*/
503void QSensor::setSkipDuplicates(bool skipDuplicates)
504{
505 Q_D(QSensor);
506 if (d->skipDuplicates != skipDuplicates) {
507 d->skipDuplicates = skipDuplicates;
508 emit skipDuplicatesChanged(skipDuplicates);
509 }
510}
511
512/*!
513 \fn QSensor::skipDuplicatesChanged(bool skipDuplicates)
514 \since 5.1
515
516 This signal is emitted when the \a skipDuplicates property changes.
517*/
518
519/*!
520 \property QSensor::availableDataRates
521 \brief the data rates that the sensor supports.
522
523 This is a list of the data rates that the sensor supports.
524 Measured in Hertz.
525
526 Entries in the list can represent discrete rates or a
527 continuous range of rates.
528 A discrete rate is noted by having both values the same.
529
530 Note that this information is not mandatory as not all sensors have a rate at which
531 they run. In such cases, the list will be empty.
532
533 \sa QSensor::dataRate, qrangelist
534*/
535
536qrangelist QSensor::availableDataRates() const
537{
538 Q_D(const QSensor);
539 return d->availableDataRates;
540}
541
542/*!
543 \property QSensor::dataRate
544 \brief the data rate that the sensor should be run at.
545
546 Measured in Hertz.
547
548 The data rate is the maximum frequency at which the sensor can detect changes.
549
550 Setting this property is not portable and can cause conflicts with other
551 applications. Check with the sensor backend and platform documentation for
552 any policy regarding multiple applications requesting a data rate.
553
554 The default value (0) means that the app does not care what the data rate is.
555 Applications should consider using a timer-based poll of the current value or
556 ensure that the code that processes values can run very quickly as the platform
557 may provide updates hundreds of times each second.
558
559 This should be set before calling start() because the sensor may not
560 notice changes to this value while it is running.
561
562 Note that there is no mechanism to determine the current data rate in use by the
563 platform.
564
565 \sa QSensor::availableDataRates
566*/
567
568int QSensor::dataRate() const
569{
570 Q_D(const QSensor);
571 return d->dataRate;
572}
573
574void QSensor::setDataRate(int rate)
575{
576 Q_D(QSensor);
577 if (d->dataRate != rate) {
578 d->dataRate = rate;
579 emit dataRateChanged();
580 }
581}
582
583/*!
584 Checks if a specific feature is supported by the backend.
585
586 QtSensors supports a rich API for controlling and providing information about sensors. Naturally,
587 not all of this functionality can be supported by all of the backends.
588
589 To check if the current backend supports the feature \a feature, call this function.
590
591 The backend needs to be connected, otherwise false will be returned. Calling connectToBackend()
592 or start() will create a connection to the backend.
593
594 Backends have to implement QSensorBackend::isFeatureSupported() to make this work.
595
596 Returns whether or not the feature is supported if the backend is connected, or false if the backend is not connected.
597 \since 5.0
598 */
599bool QSensor::isFeatureSupported(Feature feature) const
600{
601 Q_D(const QSensor);
602 return d->backend && d->backend->isFeatureSupported(feature);
603}
604
605/*!
606 Start retrieving values from the sensor.
607 Returns true if the sensor was started, false otherwise.
608
609 The sensor may fail to start for several reasons.
610
611 Once an application has started a sensor it must wait until the sensor receives a
612 new value before it can query the sensor's values. This is due to how the sensor
613 receives values from the system. Sensors do not (in general) poll for new values,
614 rather new values are pushed to the sensors as they happen.
615
616 For example, this code will not work as intended.
617
618 \badcode
619 sensor->start();
620 sensor->reading()->x(); // no data available
621 \endcode
622
623 To work correctly, the code that accesses the reading should ensure the
624 readingChanged() signal has been emitted.
625
626 \code
627 connect(sensor, SIGNAL(readingChanged()), this, SLOT(checkReading()));
628 sensor->start();
629 }
630 void MyClass::checkReading() {
631 sensor->reading()->x();
632 \endcode
633
634 \sa QSensor::busy
635*/
636bool QSensor::start()
637{
638 Q_D(QSensor);
639 if (isActive())
640 return true;
641 if (!connectToBackend())
642 return false;
643 // Set these flags to their defaults
644 d->active = true;
645 d->busy = false;
646 // Backend will update the flags appropriately
647 d->backend->start();
648 Q_EMIT activeChanged();
649 return isActive();
650}
651
652/*!
653 Stop retrieving values from the sensor.
654
655 This releases the sensor so that other processes can use it.
656
657 \sa QSensor::busy
658*/
659void QSensor::stop()
660{
661 Q_D(QSensor);
662 if (!isConnectedToBackend() || !isActive())
663 return;
664 d->active = false;
665 d->backend->stop();
666 Q_EMIT activeChanged();
667}
668
669/*!
670 \property QSensor::reading
671 \brief the reading class.
672
673 The reading class provides access to sensor readings. The reading object
674 is a volatile cache of the most recent sensor reading that has been received
675 so the application should process readings immediately or save the values
676 somewhere for later processing.
677
678 Note that this will return 0 until a sensor backend is connected to a backend.
679
680 Also note that readings are not immediately available after start() is called.
681 Applications must wait for the readingChanged() signal to be emitted.
682
683 \sa isConnectedToBackend(), start()
684*/
685
686QSensorReading *QSensor::reading() const
687{
688 Q_D(const QSensor);
689 return d->cache_reading;
690}
691
692/*!
693 Add a \a filter to the sensor.
694
695 The sensor does not take ownership of the filter.
696 QSensorFilter will inform the sensor if it is destroyed.
697
698 \sa QSensorFilter
699*/
700void QSensor::addFilter(QSensorFilter *filter)
701{
702 Q_D(QSensor);
703 if (!filter) {
704 qWarning() << "addFilter: passed a null filter!";
705 return;
706 }
707 filter->setSensor(this);
708 d->filters << filter;
709}
710
711/*!
712 Remove \a filter from the sensor.
713
714 \sa QSensorFilter
715*/
716void QSensor::removeFilter(QSensorFilter *filter)
717{
718 Q_D(QSensor);
719 if (!filter) {
720 qWarning() << "removeFilter: passed a null filter!";
721 return;
722 }
723 d->filters.removeOne(t: filter);
724 filter->setSensor(0);
725}
726
727/*!
728 Returns the filters currently attached to the sensor.
729
730 \sa QSensorFilter
731*/
732QList<QSensorFilter*> QSensor::filters() const
733{
734 Q_D(const QSensor);
735 return d->filters;
736}
737
738/*!
739 \fn QSensor::readingChanged()
740
741 This signal is emitted when a new sensor reading is received.
742
743 The sensor reading can be found in the QSensor::reading property. Note that the
744 reading object is a volatile cache of the most recent sensor reading that has
745 been received so the application should process the reading immediately or
746 save the values somewhere for later processing.
747
748 Before this signal has been emitted for the first time, the reading object will
749 have uninitialized data.
750
751 \sa start()
752*/
753
754/*!
755 \fn QSensor::activeChanged()
756
757 This signal is emitted when the QSensor::active property has changed.
758
759 \sa QSensor::active
760*/
761
762/*!
763 \property QSensor::outputRanges
764 \brief a list of output ranges the sensor supports.
765
766 A sensor may have more than one output range. Typically this is done
767 to give a greater measurement range at the cost of lowering accuracy.
768
769 Note that this information is not mandatory. This information is typically only
770 available for sensors that have selectable output ranges (such as typical
771 accelerometers).
772
773 \sa QSensor::outputRange, qoutputrangelist
774*/
775
776qoutputrangelist QSensor::outputRanges() const
777{
778 Q_D(const QSensor);
779 return d->outputRanges;
780}
781
782/*!
783 \property QSensor::outputRange
784 \brief the output range in use by the sensor.
785
786 This value represents the index in the QSensor::outputRanges list to use.
787
788 Setting this property is not portable and can cause conflicts with other
789 applications. Check with the sensor backend and platform documentation for
790 any policy regarding multiple applications requesting an output range.
791
792 The default value (-1) means that the app does not care what the output range is.
793
794 Note that there is no mechanism to determine the current output range in use by the
795 platform.
796
797 \sa QSensor::outputRanges
798*/
799
800int QSensor::outputRange() const
801{
802 Q_D(const QSensor);
803 return d->outputRange;
804}
805
806void QSensor::setOutputRange(int index)
807{
808 Q_D(QSensor);
809 if (index == -1 || !isConnectedToBackend()) {
810 d->outputRange = index;
811 return;
812 }
813 bool warn = true;
814 if (index >= 0 && index < d->outputRanges.size()) {
815 warn = false;
816 d->outputRange = index;
817 }
818 if (warn) {
819 qWarning() << "setOutputRange:" << index << "is not supported by the sensor.";
820 }
821}
822
823/*!
824 \property QSensor::description
825 \brief a descriptive string for the sensor.
826*/
827
828QString QSensor::description() const
829{
830 Q_D(const QSensor);
831 return d->description;
832}
833
834/*!
835 \property QSensor::error
836 \brief the last error code set on the sensor.
837
838 Note that error codes are sensor-specific.
839*/
840
841int QSensor::error() const
842{
843 Q_D(const QSensor);
844 return d->error;
845}
846
847/*!
848 \enum QSensor::AxesOrientationMode
849 \since 5.1
850
851 Describes how reading values are affected by the screen orientation.
852
853 \value FixedOrientation No automatic rotation is applied to the reading values.
854
855 \value AutomaticOrientation The reading values are automatically rotated based on the screen
856 orientation.
857
858 \value UserOrientation The reading values are rotated based on the angle of the userOrientation property.
859
860 \sa QSensor::axesOrientationMode
861*/
862
863/*!
864 \property QSensor::axesOrientationMode
865 \since 5.1
866 \brief The mode that affects how the screen orientation changes reading values.
867
868 When set to FixedOrientation, which is the default mode, no automatic rotation is applied to
869 the reading. This is the only mode available for backends that do not support the
870 QSensor::AxesOrientation feature.
871
872 When set to AutomaticOrientation, the reading values are automatically rotated when the
873 screen orientation changes. In effect, the screen orientation is canceled out.
874
875 As an example, assume the device is rotated by 180 degrees and therefore the screen orientation
876 also is rotated by 180 degrees from the native orientation. Without automatic axes orientation,
877 the reading values would now be changed: Both the X and the Y values would be negated, forcing
878 an application developer to manually cancel out the negation in application code. Automatic
879 axes orientation does this automatically, in this mode the X and Y values would be the same as
880 with the default screen orientation.
881
882 This automatic rotation of the axes is handy is some usecases, for example in a bubble level
883 application that measures how level a surface is by looking at the X axis value of an
884 accelerometer. When the device and screen orientation change by 90 degrees, an application
885 developer does not need to change anything, he can continue using the X axis value even though
886 the device is rotated. Without automatic axes orientation, the application developer would need
887 to look at the Y values instead, thereby adding code to the application that reads from a
888 different axis depending on the screen orientation.
889
890 The UserOrientation mode is quite similar to AutomaticOrientation, only that the screen orientation
891 is manually controlled instead of automatically determined. The angle of the userOrientation
892 property is then used for rotating the reading values.
893
894 Since the rotation of the reading values is based on the screen orientation, Z values will never
895 change, as the Z axis is perpendicular to the screen.
896 As screen orientation changes in 90 degree steps, rotating the reading values is also done in
897 steps of 90 degrees.
898
899 This property is only used for orientable sensors.
900*/
901
902QSensor::AxesOrientationMode QSensor::axesOrientationMode() const
903{
904 Q_D(const QSensor);
905 return d->axesOrientationMode;
906}
907
908void QSensor::setAxesOrientationMode(QSensor::AxesOrientationMode axesOrientationMode)
909{
910 Q_D(QSensor);
911 if (d->axesOrientationMode != axesOrientationMode) {
912 d->axesOrientationMode = axesOrientationMode;
913 emit axesOrientationModeChanged(axesOrientationMode);
914 }
915}
916
917/*!
918 \property QSensor::currentOrientation
919 \since 5.1
920 \brief The current orientation that is used for rotating the reading values.
921
922 This might not be the same as the screen orientation. For example, in the FixedOrientation mode,
923 the reading values are not rotated, and therefore the property is 0.
924
925 In the UserOrientation mode, the readings are rotated based on the userOrientation property,
926 and therefore this property is equal to the userOrientation property.
927
928 In the AutomaticOrientation mode, the readings are rotated based on the screen orientation,
929 and therefore this property will be equal to the current screen orientation.
930
931 This property is set by the backend and only valid for orientable sensors.
932*/
933
934int QSensor::currentOrientation() const
935{
936 Q_D(const QSensor);
937 return d->currentOrientation;
938}
939
940/*!
941 \since 5.1
942 Sets the current screen orientation to \a currentOrientation. This is to be called from the
943 backend whenever the screen orientation or the userOrientation property changes.
944*/
945void QSensor::setCurrentOrientation(int currentOrientation)
946{
947 Q_D(QSensor);
948 if (d->currentOrientation != currentOrientation) {
949 d->currentOrientation = currentOrientation;
950 emit currentOrientationChanged(currentOrientation);
951 }
952}
953
954/*!
955 \property QSensor::userOrientation
956 \since 5.1
957 \brief The angle used for rotating the reading values in the UserOrientation mode.
958
959 When the axesOrientationMode property is set to UserOrientation, the angle for rotating the
960 reading values is taken from this property. In other modes, the property has no effect.
961
962 The default is 0. The only valid values are 0, 90, 180 and 270, as those are the only possible
963 screen orientations.
964
965 This property is only valid for orientable sensors.
966*/
967
968int QSensor::userOrientation() const
969{
970 Q_D(const QSensor);
971 return d->userOrientation;
972}
973
974void QSensor::setUserOrientation(int userOrientation)
975{
976 Q_D(QSensor);
977 if (d->userOrientation != userOrientation) {
978 d->userOrientation = userOrientation;
979 emit userOrientationChanged(userOrientation);
980 }
981}
982
983/*!
984 \fn QSensor::sensorError(int error)
985
986 This signal is emitted when an \a error code is set on the sensor.
987 Note that some errors will cause the sensor to stop working.
988 You should call isActive() to determine if the sensor is still running.
989*/
990
991/*!
992 \fn QSensor::availableSensorsChanged()
993
994 This signal is emitted when the list of available sensors has changed.
995 The sensors available to a program will not generally change over time
996 however some of the available sensors may represent hardware that is not
997 permanently connected. For example, a game controller that is connected
998 via bluetooth would become available when it was on and would become
999 unavailable when it was off.
1000
1001 \sa QSensor::sensorTypes(), QSensor::sensorsForType()
1002*/
1003
1004/*!
1005 \property QSensor::maxBufferSize
1006
1007 The property holds the maximum buffer size.
1008
1009 Note that this may be 1, in which case the sensor does not support any form of buffering.
1010 In that case, isFeatureSupported(QSensor::Buffering) will also return false.
1011
1012 \sa QSensor::bufferSize, QSensor::efficientBufferSize
1013*/
1014
1015int QSensor::maxBufferSize() const
1016{
1017 Q_D(const QSensor);
1018 return d->maxBufferSize;
1019}
1020
1021/*!
1022 \since 5.1
1023 Sets the maximum buffer size to \a maxBufferSize. This is to be called from the
1024 backend.
1025*/
1026void QSensor::setMaxBufferSize(int maxBufferSize)
1027{
1028 Q_D(QSensor);
1029 if (d->maxBufferSize != maxBufferSize) {
1030 d->maxBufferSize = maxBufferSize;
1031 emit maxBufferSizeChanged(maxBufferSize);
1032 }
1033}
1034
1035/*!
1036 \property QSensor::efficientBufferSize
1037
1038 The property holds the most efficient buffer size. Normally this is 1 (which means
1039 no particular size is most efficient). Some sensor drivers have a FIFO buffer which
1040 makes it more efficient to deliver the FIFO's size worth of readings at one time.
1041
1042 \sa QSensor::bufferSize, QSensor::maxBufferSize
1043*/
1044
1045int QSensor::efficientBufferSize() const
1046{
1047 Q_D(const QSensor);
1048 return d->efficientBufferSize;
1049}
1050
1051/*!
1052 \since 5.1
1053 Sets the efficient buffer size to \a efficientBufferSize. This is to be called from the
1054 backend.
1055*/
1056void QSensor::setEfficientBufferSize(int efficientBufferSize)
1057{
1058 Q_D(QSensor);
1059 if (d->efficientBufferSize != efficientBufferSize) {
1060 d->efficientBufferSize = efficientBufferSize;
1061 emit efficientBufferSizeChanged(efficientBufferSize);
1062 }
1063}
1064
1065/*!
1066 \property QSensor::bufferSize
1067
1068 This property holds the size of the buffer. By default, the buffer size is 1,
1069 which means no buffering.
1070 If the maximum buffer size is 1, then buffering is not supported
1071 by the sensor.
1072
1073 Setting bufferSize greater than maxBufferSize will cause maxBufferSize to be used.
1074
1075 Buffering is turned on when bufferSize is greater than 1. The sensor will collect
1076 the requested number of samples and deliver them all to the application at one time.
1077 They will be delivered to the application as a burst of changed readings so it is
1078 particularly important that the application processes each reading immediately or
1079 saves the values somewhere else.
1080
1081 If stop() is called when buffering is on-going, the partial buffer is not delivered.
1082
1083 When the sensor is started with buffering option, values are collected from that
1084 moment onwards. There is no pre-existing buffer that can be utilized.
1085
1086 Some backends only support enabling or disabling the buffer and do not give
1087 control over the size. In this case, the maxBufferSize and efficientBufferSize properties
1088 might not be set at all, even though buffering is supported. Setting the bufferSize property
1089 to any value greater than 1 will enable buffering. After the sensor has been started,
1090 the bufferSize property will be set to the actual value by the backend.
1091
1092 \sa QSensor::maxBufferSize, QSensor::efficientBufferSize
1093*/
1094
1095int QSensor::bufferSize() const
1096{
1097 Q_D(const QSensor);
1098 return d->bufferSize;
1099}
1100
1101void QSensor::setBufferSize(int bufferSize)
1102{
1103 Q_D(QSensor);
1104 if (d->bufferSize != bufferSize) {
1105 d->bufferSize = bufferSize;
1106 emit bufferSizeChanged(bufferSize);
1107 }
1108}
1109
1110// =====================================================================
1111
1112/*!
1113 \class QSensorFilter
1114 \ingroup sensors_main
1115 \inmodule QtSensors
1116
1117 \brief The QSensorFilter class provides an efficient
1118 callback facility for asynchronous notifications of
1119 sensor changes.
1120
1121 Some sensors (eg. the accelerometer) are often accessed very frequently.
1122 This may be slowed down by the use of signals and slots.
1123 The QSensorFilter interface provides a more efficient way for the
1124 sensor to notify your class that the sensor has changed.
1125
1126 Additionally, multiple filters can be added to a sensor. They are called
1127 in order and each filter has the option to modify the values in the reading
1128 or to suppress the reading altogether.
1129
1130 Note that the values in the class returned by QSensor::reading() will
1131 not be updated until after the filters have been run.
1132
1133 \sa filter()
1134*/
1135
1136/*!
1137 \internal
1138*/
1139QSensorFilter::QSensorFilter()
1140 : m_sensor(0)
1141{
1142}
1143
1144/*!
1145 Notifies the attached sensor (if any) that the filter is being destroyed.
1146*/
1147QSensorFilter::~QSensorFilter()
1148{
1149 if (m_sensor)
1150 m_sensor->removeFilter(filter: this);
1151}
1152
1153/*!
1154 \fn QSensorFilter::filter(QSensorReading *reading)
1155
1156 This function is called when the sensor \a reading changes.
1157
1158 The filter can modify the reading.
1159
1160 Returns true to allow the next filter to receive the value.
1161 If this is the last filter, returning true causes the signal
1162 to be emitted and the value is stored in the sensor.
1163
1164 Returns false to drop the reading.
1165*/
1166
1167/*!
1168 \internal
1169*/
1170void QSensorFilter::setSensor(QSensor *sensor)
1171{
1172 m_sensor = sensor;
1173}
1174
1175// =====================================================================
1176
1177/*!
1178 \class QSensorReading
1179 \ingroup sensors_main
1180 \inmodule QtSensors
1181
1182 \brief The QSensorReading class holds the readings from the sensor.
1183
1184 Note that QSensorReading is not particularly useful by itself. The interesting
1185 data for each sensor is defined in a sub-class of QSensorReading.
1186*/
1187
1188/*!
1189 \internal
1190*/
1191QSensorReading::QSensorReading(QObject *parent, QSensorReadingPrivate *_d)
1192 : QObject(parent)
1193 , d(_d?_d:new QSensorReadingPrivate)
1194{
1195}
1196
1197/*!
1198 \internal
1199*/
1200QSensorReading::~QSensorReading()
1201{
1202}
1203
1204/*!
1205 \property QSensorReading::timestamp
1206 \brief the timestamp of the reading.
1207
1208 Timestamps values are microseconds since a fixed point.
1209 You can use timestamps to see how far apart two sensor readings are.
1210
1211 Note that sensor timestamps from different sensors may not be directly
1212 comparable (as they may choose different fixed points for their reference).
1213
1214 \b{Note that some platforms do not deliver timestamps correctly}.
1215 Applications should be prepared for occasional issues that cause timestamps to jump
1216 backwards.
1217*/
1218
1219/*!
1220 Returns the timestamp of the reading.
1221*/
1222quint64 QSensorReading::timestamp() const
1223{
1224 return d->timestamp;
1225}
1226
1227/*!
1228 Sets the \a timestamp of the reading.
1229*/
1230void QSensorReading::setTimestamp(quint64 timestamp)
1231{
1232 d->timestamp = timestamp;
1233}
1234
1235/*!
1236 Returns the number of extra properties that the reading has.
1237
1238 Note that this does not count properties declared in QSensorReading.
1239
1240 As an example, this returns 3 for QAccelerometerReading because
1241 there are 3 properties defined in that class.
1242*/
1243int QSensorReading::valueCount() const
1244{
1245 const QMetaObject *mo = metaObject();
1246 return mo->propertyCount() - mo->propertyOffset();
1247}
1248
1249/*!
1250 Returns the value of the property at \a index.
1251
1252 Note that this function is slower than calling the data function directly.
1253
1254 Here is an example of getting a property via the different mechanisms available.
1255
1256 Accessing directly provides the best performance but requires compile-time knowledge
1257 of the data you are accessing.
1258
1259 \code
1260 QAccelerometerReading *reading = ...;
1261 qreal x = reading->x();
1262 \endcode
1263
1264 You can also access a property by name. To do this you must call QObject::property().
1265
1266 \code
1267 qreal x = reading->property("x").value<qreal>();
1268 \endcode
1269
1270 Finally, you can access values via numeric index.
1271
1272 \code
1273 qreal x = reading->value(0).value<qreal>();
1274 \endcode
1275
1276 Note that value() can only access properties declared with Q_PROPERTY() in sub-classes
1277 of QSensorReading.
1278
1279 \sa valueCount(), QObject::property()
1280*/
1281QVariant QSensorReading::value(int index) const
1282{
1283 // get them meta-object
1284 const QMetaObject *mo = metaObject();
1285
1286 // determine the index of the property we want
1287 index += mo->propertyOffset();
1288
1289 // get the meta-property
1290 QMetaProperty property = mo->property(index);
1291
1292 // read the property
1293 return property.read(obj: this);
1294}
1295
1296/*!
1297 \fn QSensorReading::copyValuesFrom(QSensorReading *other)
1298 \internal
1299
1300 Copy values from other into this reading. Implemented by sub-classes
1301 using the DECLARE_READING() and IMPLEMENT_READING() macros.
1302
1303 Note that this method should only be called by QSensorBackend.
1304*/
1305void QSensorReading::copyValuesFrom(QSensorReading *other)
1306{
1307 QSensorReadingPrivate *my_ptr = d.data();
1308 QSensorReadingPrivate *other_ptr = other->d.data();
1309 /* Do a direct copy of the private class */
1310 *(my_ptr) = *(other_ptr);
1311}
1312
1313/*!
1314 \fn QSensorReading::d_ptr()
1315 \internal
1316 No longer used. Exists to keep the winscw build happy.
1317*/
1318
1319/*!
1320 \macro DECLARE_READING(classname)
1321 \relates QSensorReading
1322 \brief The DECLARE_READING macro adds some required methods to a reading class.
1323
1324 This macro should be used for all reading classes. Pass the \a classname of your reading class.
1325
1326 \snippet sensors/myreading.cpp MyReading-Declaration
1327
1328 \sa IMPLEMENT_READING()
1329*/
1330
1331/*!
1332 \macro IMPLEMENT_READING(classname)
1333 \relates QSensorReading
1334 \brief The IMPLEMENT_READING macro implements the required methods for a reading class.
1335
1336 This macro should be used for all reading classes. It should be placed into a single compilation
1337 unit (source file), not into a header file. Pass the \a classname of your reading class.
1338
1339 \snippet sensors/myreading.cpp IMPLEMENT_READING_MyReading
1340
1341 \sa DECLARE_READING()
1342*/
1343
1344QT_END_NAMESPACE
1345

source code of qtsensors/src/sensors/qsensor.cpp