Camera¶
A sensor that can capture photos and/or video.
Usage¶
Cameras attached to a device running an app can be accessed using the
camera
attribute. This attribute exposes an API that allows you to
check if you have have permission to access the camera device; and if permission exists,
capture photographs.
The Camera API is asynchronous. This means the methods that have long-running behavior
(such as requesting permissions and taking photographs) must be await
-ed, rather
than being invoked directly. This means they must be invoked from inside an asynchronous
handler:
import toga
class MyApp(toga.App):
...
async def time_for_a_selfie(self, widget, **kwargs):
photo = await self.camera.take_photo()
Most platforms will require some form of device permission to access the camera. The
permission APIs are paired with the specific actions performed on those APIs - that is,
to take a photo, you require Camera.has_permission
, which you can request using
Camera.request_permission()
.
Toga will confirm whether the app has been granted permission to use the camera before invoking any camera API. If permission has not yet been granted, the platform may request access at the time of first camera access; however, this is not guaranteed to be the behavior on all platforms.
Notes¶
Apps that use a camera must be configured to provide permission to the camera device. The permissions required are platform specific:
iOS:
NSCameraUsageDescription
must be defined in the app’sInfo.plist
file.macOS: The
com.apple.security.device.camera
entitlement must be enabled, andNSCameraUsageDescription
must be defined in the app’sInfo.plist
file.Android: The
android.permission.CAMERA
permission must be declared.
The iOS simulator implements the iOS Camera APIs, but is not able to take photographs. To test your app’s Camera usage, you must use a physical iOS device.
Reference¶
- class toga.hardware.camera.Camera(app)¶
- Parameters:
app (App)
- property devices: list[CameraDevice]¶
The list of available camera devices.
- property has_permission: bool¶
Does the user have permission to use camera devices?
If the platform requires the user to explicitly confirm permission, and the user has not yet given permission, this will return
False
.
- request_permission()¶
Request sufficient permissions to capture photos.
If permission has already been granted, this will return without prompting the user.
This is an asynchronous method. If you invoke this method in synchronous context, it will start the process of requesting permissions, but will return immediately. The return value can be awaited in an asynchronous context, but cannot be used directly.
- Returns:
An asynchronous result; when awaited, returns True if the app has permission to take a photo; False otherwise.
- Return type:
PermissionResult
- take_photo(device=None, flash=FlashMode.AUTO)¶
Capture a photo using one of the device’s cameras.
If the platform requires permission to access the camera, and the user hasn’t previously provided that permission, this will cause permission to be requested.
This is an asynchronous method. If you invoke this method in synchronous context, it will start the process of taking a photo, but will return immediately. The return value can be awaited in an asynchronous context, but cannot be used directly.
- Parameters:
device (CameraDevice | None) – The initial camera device to use. If a device is not specified, a default camera will be used. Depending on the hardware available, the user may be able to change the camera used to capture the image at runtime.
flash (FlashMode) – The initial flash mode to use; defaults to “auto”. Depending on the hardware available, this may be modified by the user at runtime.
- Returns:
An asynchronous result; when awaited, returns the
toga.Image
captured by the camera, orNone
if the photo was cancelled.- Raises:
PermissionError – if the app does not have permission to use the camera.
- Return type:
PhotoResult