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’s Info.plist file.
- macOS: The com.apple.security.device.camera entitlement must be enabled, and NSCameraUsageDescription must be defined in the app’s Info.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 app: App¶: The app with which the camera is associated

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, or None if the photo was cancelled.

Raises:

PermissionError – if the app does not have permission to use the camera.

Return type:

PhotoResult

class toga.hardware.camera.CameraDevice(impl)¶

property has_flash: bool¶: Does the device have a flash?

property id: str¶: A unique identifier for the device

property name: str¶: A human-readable name for the device