Backlight

Backlight state machine. More...

Functions
void	light_init (void)
	Initialize the backlight service at startup.
void	light_button_pressed (void)
	Handle a button press.
void	light_button_released (void)
	Handle a button release.
void	light_touch_down (void)
	Handle a touch finger-down.
void	light_touch_up (void)
	Release the hold taken by light_touch_down().
void	light_enable_respect_settings (bool enable)
	light_enable() that respects the user's backlight settings.
void	light_reset_user_controlled (void)
	Return to the normal state machine after an app forced the light with light_enable().
void	light_system_color_request (void)
	Make the system color take precedence over any app color.
void	light_system_color_release (void)
	Release a light_system_color_request().
void	light_toggle_enabled (void)
	Toggle the user's backlight enabled setting.
void	light_toggle_ambient_sensor_enabled (void)
	Toggle the user's ambient light sensor setting.
void	light_set_dynamic_mode (BacklightDynamicMode mode)
	Set the dynamic backlight mode.
void	light_allow (bool allowed)
	Allow or disallow the backlight, e.g.
uint8_t	light_get_current_brightness_percent (void)
	Get the current backlight brightness.
bool	light_is_lit_by_touch (void)
	Check whether the backlight was lit by touch alone.
uint32_t	light_get_ambient_lux (void)
	Get the ambient light level.

Detailed Description

Backlight state machine.

Buttons and touches keep the backlight on while held and start a timed fade-out once released. Whether it turns on at all depends on the user's backlight settings and, with the ambient light sensor enabled, on the ambient light level. Apps can force the light on or off, and set its color on platforms with a color backlight. Entities shared with the app SDK are documented in the SDK's Light group.

Function Documentation

light_allow()

void light_allow

(

bool

allowed

)

Allow or disallow the backlight, e.g.

in low power mode.

Disallowing turns the light off.

Parameters

allowed

true to allow the backlight.

light_button_pressed()

void light_button_pressed

(

void

)

Handle a button press.

Turns the backlight on, if allowed, until all buttons are released. Called by the launcher on button down.

light_button_released()

void light_button_released

(

void

)

Handle a button release.

Starts the fade-out timer once no button is held, unless the light is forced on. Called by the launcher on button up.

light_enable_respect_settings()

void light_enable_respect_settings

(

bool

enable

)

light_enable() that respects the user's backlight settings.

When enabling, the light only turns on if the settings and ambient light allow it.

Parameters

enable

true to force the light on, false to turn it off.

light_get_ambient_lux()

uint32_t light_get_ambient_lux

(

void

)

Get the ambient light level.

Screen-compensated and converted with the board's calibration; raw counts pass through on boards without lux coefficients. Served from a short-lived cache; while the backlight is on, the last value read before it turned on is returned.

Returns

Ambient light level in lux.

light_get_current_brightness_percent()

uint8_t light_get_current_brightness_percent

(

void

)

Get the current backlight brightness.

May differ from the configured brightness when dynamic backlight is enabled.

Returns

Brightness in percent, 0-100.

light_init()

void light_init

(

void

)

Initialize the backlight service at startup.

light_is_lit_by_touch()

bool light_is_lit_by_touch

(

void

)

Check whether the backlight was lit by touch alone.

Returns

true if the backlight is on and its current lit period was last started or refreshed by touch contact alone.

light_reset_user_controlled()

void light_reset_user_controlled

(

void

)

Return to the normal state machine after an app forced the light with light_enable().

Also releases a touch hold that never saw its liftoff.

light_set_dynamic_mode()

void light_set_dynamic_mode

(

BacklightDynamicMode

mode

)

Set the dynamic backlight mode.

Briefly turns the light on so the user sees the effect.

Parameters

mode

New mode.

light_system_color_release()

void light_system_color_release

(

void

)

Release a light_system_color_request().

When the count drops to zero, any app color is applied again.

light_system_color_request()

void light_system_color_request

(

void

)

Make the system color take precedence over any app color.

Reference counted: while held, the LED shows the user's default color even if an app set an override. Used by notifications and other modals to show neutral white without clearing the app's color. No-op on platforms without a color backlight.

light_toggle_ambient_sensor_enabled()

void light_toggle_ambient_sensor_enabled

(

void

)

Toggle the user's ambient light sensor setting.

light_toggle_enabled()

void light_toggle_enabled

(

void

)

Toggle the user's backlight enabled setting.

Also clears a forced-on state and briefly shows the result.

light_touch_down()

void light_touch_down

(

void

)

Handle a touch finger-down.

Acts like a button press; repeated calls before light_touch_up() count once.

light_touch_up()

void light_touch_up

(

void

)

Release the hold taken by light_touch_down().

Called on liftoff and on app teardown. No-op if no touch is holding the backlight.