1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qml-application-permissions.html
6 \title QML Application Permissions
7 \brief Managing application permissions via QML
9 Many features of today's devices and operating systems can have
10 significant privacy, security, and performance implications if
11 misused. It's therefore increasingly common for platforms to
12 require explicit consent from the user before accessing these
15 The \l{Qt QML Core} module exposes the Qt C++
16 \l [QtCore] {Application Permissions} functionality to QML via a set of
17 permission types that can be used to check or request permission in a cross
20 \annotatedlist qml-permissions
24 To check and request a specific permission in your application,
25 include an instance of the appropriate permission type, and set
26 any of its properties if needed:
30 id: calendarPermission
31 accessMode: CalendarPermission.ReadWrite
35 The type can be used to check the current state of the
36 permissions, for example to drive a state based UI:
41 name: "waitingForPermission"
42 when: calendarPermission.status == Qt.PermissionStatus.Undetermined
43 PropertyChanges { target: permissionRequestItem; visible: true }
46 name: "permissionDenied"
47 when: calendarPermission.status == Qt.PermissionStatus.Denied
48 PropertyChanges { target: permissionDeniedItem; visible: true }
53 In the example above, two permission specific items will be overlaid if the
54 permission status is not granted. The request UI could perhaps look like:
58 id: permissionRequestItem
63 anchors.centerIn: parent
64 text: qsTr("We need your permission to access the calendar."
65 + "Please tap this screen to request permission.")
71 onClicked: calendarPermission.request()
76 With a corresponding denied UI:
80 id: permissionDeniedItem
85 anchors.centerIn: parent
86 text: qsTr("We need your permission to access the calendar,"
87 + "but permission was not granted. Please resolve.")
92 \section2 Changing permission properties
94 The properties of a permission can be changed, even after
95 a request has been initiated by calling `request()`. This
96 will update the status, if it changes a result of the new
97 property values, but will not result in an automatic request
98 using the new set of properties.
100 For example, if upgrading an already granted calendar permission
101 for access mode \c Qt.CalendarPermission.ReadOnly to
102 \c Qt.CalendarPermission.ReadWrite, the platform will
103 respond in one of three ways:
106 \li By implicitly granting the extended permission, for example
107 because the platform doesn't distinguish between the two
108 access modes, which will result in no state change.
109 \li By moving the status back to \ Undetermined, so that
110 the user can be consulted again for access to the now
112 \li By moving the status to \c Denied, for example if permissions
113 can not be upgraded once initially requested.
116 All these states should then move the application's UI into
117 the appropriate state, where the user is informed of the
118 new state, with the possibility of requesting the new
119 permission if possible, or reverting to a less extensive
122 \section2 Interaction between permission items
124 Although the permission state is ultimately tied to the
125 underlying application, each permission item reports its own
126 status independently of all other items, and needs to be
127 independently requested if needed.
129 For example, requesting calendar access for one item will
130 not update the status of another CalendarPermission item,
131 even if these have the exact same properties.
135 \include qmlpermissions.qdocinc {type-docs} {CalendarPermission} {QCalendarPermission} {calendar}
139 \include qmlpermissions.qdocinc {status-docs} {CalendarPermission}
142 \include qmlpermissions.qdocinc {request-docs} {CalendarPermission}
145 \include qmlpermissions.qdocinc {type-docs} {ContactsPermission} {QContactsPermission} {contacts}
149 \include qmlpermissions.qdocinc {status-docs} {ContactsPermission}
152 \include qmlpermissions.qdocinc {request-docs} {ContactsPermission}
155 \include qmlpermissions.qdocinc {type-docs} {CameraPermission} {QCameraPermission} {camera}
159 \include qmlpermissions.qdocinc {status-docs} {CameraPermission}
162 \include qmlpermissions.qdocinc {request-docs} {CameraPermission}
165 \include qmlpermissions.qdocinc {type-docs} {MicrophonePermission} {QMicrophonePermission} {microphone}
169 \include qmlpermissions.qdocinc {status-docs} {MicrophonePermission}
172 \include qmlpermissions.qdocinc {request-docs} {MicrophonePermission}
175 \include qmlpermissions.qdocinc {type-docs} {BluetoothPermission} {QBluetoothPermission} {Bluetooth peripherals}
179 \include qmlpermissions.qdocinc {status-docs} {BluetoothPermission}
182 \include qmlpermissions.qdocinc {request-docs} {BluetoothPermission}
185 \include qmlpermissions.qdocinc {type-docs} {LocationPermission} {QLocationPermission} {location}
189 \include qmlpermissions.qdocinc {status-docs} {LocationPermission}
192 \include qmlpermissions.qdocinc {request-docs} {LocationPermission}