Settings

Loads, saves, and syncs a face's settings from its field table. More...

Files
file	src/c/pebble/system/settings/setting_values.h
	Named values for the multi-choice settings.
file	src/c/pebble/system/settings/settings.c
	The persist API implementation.
file	src/c/pebble/system/settings/settings.h
	The persist API. A per-face SettingField table drives versioned load and save, sanitizing, the typed reads, and the AppMessage round trip, so the shared code never names or hardcodes a single field.
file	src/c/pebble/system/settings/settings_catalog.h
	The shared catalog of known settings. A KNOWN_* macro per setting bakes in its neutral wire key, encoding, bounds, default, and side effects.

Data Structures
struct	SettingField
	Blueprint for a single setting. More...
struct	SettingsSchema
	A face's persistence identity. More...
struct	SettingsInbound
	Carries what an inbound settings message changed, so the caller can react. More...

Macros
#define	SETTINGS_BLOB_SIZE(blob)
	The size of a settings struct, for a schema's blob_size, and a build that stops when the struct is too big to save.
#define	KNOWN_TEMPERATURE_UNIT(off)
	Setting definition for Temperature Unit (Celsius or Fahrenheit).
#define	KNOWN_DATE_FORMAT(off, dflt)
	Setting definition for Date Format.
#define	KNOWN_THEME(off, count)
	Setting definition for Theme.
#define	KNOWN_HEADER_FONT(off, count)
	Setting definition for Header Font, an index into the face's own header font table.
#define	KNOWN_STEPS_MODE(off, count)
	Setting definition for Steps Mode.
#define	KNOWN_DISTANCE_UNIT(off, count)
	Setting definition for Distance Unit.
#define	KNOWN_TIME_FORMAT(off, count)
	Setting definition for Time Format.
#define	KNOWN_BLUETOOTH_ICON(off)
	Setting definition for Bluetooth Icon.
#define	KNOWN_QUIET_TIME_ICON(off)
	Setting definition for the Quiet Time Icon.
#define	KNOWN_BLUETOOTH_VIBE_CONNECT(off, count)
	Setting definition for Bluetooth Vibe Connect.
#define	KNOWN_BLUETOOTH_VIBE_DISCONNECT(off, count)
	Setting definition for Bluetooth Vibe Disconnect.
#define	KNOWN_HOURLY_VIBE(off, count)
	Setting definition for the Hourly Vibration (a VibeChoice fired at the top of each hour).
#define	KNOWN_BATTERY_DISPLAY(off, count)
	Setting definition for Battery Display (icon + percent / icon / percent).

Typedefs
typedef struct SettingsSchema	SettingsSchema
	A face's persistence identity.

Enumerations
enum	TimeFormat {   TIME_FORMAT_SYSTEM = 0 , TIME_FORMAT_12H = 1 , TIME_FORMAT_24H = 2 , TIME_FORMAT_BEATS = 3 ,   TIME_FORMAT_12H_NO_LEAD = 4 , TIME_FORMAT_COUNT }
	SETTING_TIME_FORMAT choices. More...
enum	StepsMode { STEPS_MODE_STEPS = 0 , STEPS_MODE_MILES = 1 , STEPS_MODE_KM = 2 , STEPS_MODE_COUNT }
	SETTING_STEPS_MODE choices. More...
enum	DistanceUnit { DISTANCE_UNIT_KM = 0 , DISTANCE_UNIT_MILES = 1 , DISTANCE_UNIT_COUNT }
	SETTING_DISTANCE_UNIT choices. The standalone Distance panel picks its own unit separate from the Steps panel's STEPS_MODE. More...
enum	VibeChoice {   VIBE_NONE = 0 , VIBE_SHORT = 1 , VIBE_LONG = 2 , VIBE_DOUBLE = 3 ,   VIBE_COUNT }
	Bluetooth connect/disconnect vibe pattern choices. More...
enum	BatteryDisplay { BATTERY_DISPLAY_BOTH = 0 , BATTERY_DISPLAY_ICON = 1 , BATTERY_DISPLAY_PERCENT = 2 , BATTERY_DISPLAY_COUNT }
	SETTING_BATTERY_DISPLAY choices: what the battery readout shows. More...
enum	SettingId {   SETTING_TEMPERATURE_UNIT , SETTING_DATE_FORMAT , SETTING_THEME , SETTING_STEPS_MODE ,   SETTING_DISTANCE_UNIT , SETTING_TIME_FORMAT , SETTING_BLUETOOTH_ICON , SETTING_QUIET_TIME_ICON ,   SETTING_BLUETOOTH_VIBE_CONNECT , SETTING_BLUETOOTH_VIBE_DISCONNECT , SETTING_HOURLY_VIBE , SETTING_BATTERY_DISPLAY ,   SETTING_HEADER_FONT , SETTING_COUNT }
	Identity of a known (shared) setting, used for typed reads and indexing. More...
enum	SettingType { SETTING_BOOL , SETTING_ENUM_U8 , SETTING_CSTRING , SETTING_COLOR }
	How a setting encodes on the wire and how the sanitize pass clamps it. More...

Functions
void	settings_init (const SettingsSchema *schema)
	Load a face's settings from their saved blobs, applying defaults first.
bool	settings_was_fresh (void)
	Whether the watch booted with no saved settings, because storage was wiped by a fresh install or an update. Lets the phone know it should push its own config back rather than trust the watch's defaults.
void	settings_save (void)
	Persist the active face's structs under their keys (the whole chain).
void	settings_mark_restored (void)
	Clears settings_was_fresh once a save or restore from the settings page has been saved.
uint8_t	settings_u8 (SettingId id)
	Read a known uint8/bool setting by id.
const char *	settings_str (SettingId id)
	Read a known string setting by id.
void	settings_set_u8 (SettingId id, uint8_t value)
	Write a known uint8 or enum setting by id. In memory only, does not persist.
uint8_t	settings_enum_count (SettingId id)
	How many values an enum setting allows (its sanitize ceiling).
uint32_t	settings_serialized_size_max (void)
	The most outbox bytes every field of the active face could ever take once written.
bool	settings_serialize (DictionaryIterator *iter)
	Write every field of the active face into an outbox iterator.
SettingsInbound	settings_apply_inbox (DictionaryIterator *iter)
	Apply any settings present in an inbox message to the active face.

Detailed Description

Loads, saves, and syncs a face's settings from its field table.

A face hands it a field table, and it handles persist and the phone sync without naming any single setting itself.

Macro Definition Documentation

KNOWN_BATTERY_DISPLAY

#define KNOWN_BATTERY_DISPLAY	(		off,
			count )

Value:

{ .id = SETTING_BATTERY_DISPLAY, .message_key = &MESSAGE_KEY_BATTERY_DISPLAY, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Battery Display (icon + percent / icon / percent).

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_BLUETOOTH_ICON

#define KNOWN_BLUETOOTH_ICON

(

off

)

Value:

{ .id = SETTING_BLUETOOTH_ICON, .message_key = &MESSAGE_KEY_CONNECTION_BLUETOOTH_ICON, \
  .type = SETTING_BOOL, .offset = (off), .default_num = 1 }

Setting definition for Bluetooth Icon.

Parameters

off	Offset into the face's settings struct.

KNOWN_BLUETOOTH_VIBE_CONNECT

#define KNOWN_BLUETOOTH_VIBE_CONNECT	(		off,
			count )

Value:

{ .id = SETTING_BLUETOOTH_VIBE_CONNECT, .message_key = &MESSAGE_KEY_CONNECTION_VIBE_CONNECT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Bluetooth Vibe Connect.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_BLUETOOTH_VIBE_DISCONNECT

#define KNOWN_BLUETOOTH_VIBE_DISCONNECT	(		off,
			count )

Value:

{ .id = SETTING_BLUETOOTH_VIBE_DISCONNECT, .message_key = &MESSAGE_KEY_CONNECTION_VIBE_DISCONNECT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Bluetooth Vibe Disconnect.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_DATE_FORMAT

#define KNOWN_DATE_FORMAT	(		off,
			dflt )

Value:

{ .id = SETTING_DATE_FORMAT, .message_key = &MESSAGE_KEY_CLOCK_DATE_FORMAT, \
  .type = SETTING_CSTRING, .offset = (off), .size = 16, .default_str = (dflt), \
  .affects_layout = true }

Setting definition for Date Format.

Parameters

off	Offset into the face's settings struct.
dflt	The default format string.

KNOWN_DISTANCE_UNIT

#define KNOWN_DISTANCE_UNIT	(		off,
			count )

Value:

{ .id = SETTING_DISTANCE_UNIT, .message_key = &MESSAGE_KEY_HEALTH_DISTANCE_UNIT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Distance Unit.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_HEADER_FONT

#define KNOWN_HEADER_FONT	(		off,
			count )

Value:

{ .id = SETTING_HEADER_FONT, .message_key = &MESSAGE_KEY_APPEARANCE_HEADER_FONT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Header Font, an index into the face's own header font table.

Parameters

off	Offset into the face's settings struct.
count	How many fonts the face's table holds.

KNOWN_HOURLY_VIBE

#define KNOWN_HOURLY_VIBE	(		off,
			count )

Value:

{ .id = SETTING_HOURLY_VIBE, .message_key = &MESSAGE_KEY_CLOCK_HOURLY_VIBE, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for the Hourly Vibration (a VibeChoice fired at the top of each hour).

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_QUIET_TIME_ICON

#define KNOWN_QUIET_TIME_ICON

(

off

)

Value:

{ .id = SETTING_QUIET_TIME_ICON, .message_key = &MESSAGE_KEY_APPEARANCE_QUIET_TIME_ICON, \
  .type = SETTING_BOOL, .offset = (off), .default_num = 0 }

Setting definition for the Quiet Time Icon.

Parameters

off	Offset into the face's settings struct.

KNOWN_STEPS_MODE

#define KNOWN_STEPS_MODE	(		off,
			count )

Value:

{ .id = SETTING_STEPS_MODE, .message_key = &MESSAGE_KEY_HEALTH_STEPS_MODE, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Steps Mode.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_TEMPERATURE_UNIT

#define KNOWN_TEMPERATURE_UNIT

(

off

)

Value:

{ .id = SETTING_TEMPERATURE_UNIT, .message_key = &MESSAGE_KEY_WEATHER_TEMPERATURE_UNIT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = 2, .default_num = 0, \
  .affects_weather = true }

Setting definition for Temperature Unit (Celsius or Fahrenheit).

Every face wires this the same way, so it takes no count: there are two units and there is never going to be a third. Changing it converts the weather already on the watch and asks for fresh weather in the new unit.

Parameters

off	Offset into the face's settings struct.

KNOWN_THEME

#define KNOWN_THEME	(		off,
			count )

Value:

{ .id = SETTING_THEME, .message_key = &MESSAGE_KEY_APPEARANCE_THEME, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count) }

Setting definition for Theme.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

KNOWN_TIME_FORMAT

#define KNOWN_TIME_FORMAT	(		off,
			count )

Value:

{ .id = SETTING_TIME_FORMAT, .message_key = &MESSAGE_KEY_CLOCK_TIME_FORMAT, \
  .type = SETTING_ENUM_U8, .offset = (off), .enum_count = (count), \
  .affects_layout = true }

Setting definition for Time Format.

Parameters

off	Offset into the face's settings struct.
count	The number of enum values.

SETTINGS_BLOB_SIZE

#define SETTINGS_BLOB_SIZE

(

blob

)

Value:

(sizeof(blob) + 0 * sizeof(struct { \
    _Static_assert(sizeof(blob) <= PERSIST_DATA_MAX_LENGTH, \
                   "settings struct is over 256 bytes, so move some fields into a companion schema"); \
    char unused; \
}))

The size of a settings struct, for a schema's blob_size, and a build that stops when the struct is too big to save.

One persist key holds at most 256 bytes, and the watch saves only the first 256 bytes of a longer write. The fields past that would come back as their defaults on every launch. settings_init and settings_save log it at runtime, and this stops the build instead, so a face with more than 256 bytes of settings moves some into a companion schema.

Parameters

blob	The settings struct itself, not a pointer to it.

Returns

The struct's size in bytes.

Typedef Documentation

SettingsSchema

typedef struct SettingsSchema SettingsSchema

A face's persistence identity.

Its storage key, current schema version, frozen v1 blob size, the face struct to load into (its first byte must be the uint8_t version), that struct's size, the field table that drives defaults/sanitize/serialization, and an optional migration hook to rescue pre-versioned data.

A face can persist more than one struct by chaining schemas through companion: each schema points to the next and the last one is NULL. settings_init walks the chain so load, save, serialize, and inbox decode all cover every schema. Each link owns its own key, version, and blob, so a domain (e.g. weather or a colour table) can sit in its own key instead of bloating the main one. The typed reads (settings_u8/str) index the whole chain and remember each field's owning schema, so a shared field (id < SETTING_COUNT) can live in any link.

Enumeration Type Documentation

BatteryDisplay

enum BatteryDisplay

SETTING_BATTERY_DISPLAY choices: what the battery readout shows.

Enumerator
BATTERY_DISPLAY_BOTH	Icon and percent.
BATTERY_DISPLAY_ICON	Icon only.
BATTERY_DISPLAY_PERCENT	Percent only.
BATTERY_DISPLAY_COUNT	How many choices this setting has.

DistanceUnit

enum DistanceUnit

SETTING_DISTANCE_UNIT choices. The standalone Distance panel picks its own unit separate from the Steps panel's STEPS_MODE.

Enumerator
DISTANCE_UNIT_KM	Kilometres.
DISTANCE_UNIT_MILES	Miles.
DISTANCE_UNIT_COUNT	How many choices this setting has.

SettingId

enum SettingId

Identity of a known (shared) setting, used for typed reads and indexing.

Face-only settings sit in the same field table but carry an id of SETTING_COUNT or greater, so they are serialized yet never indexed for a shared read.

Enumerator
SETTING_TEMPERATURE_UNIT	Celsius or Fahrenheit.
SETTING_DATE_FORMAT	The date line's format string.
SETTING_THEME	Which theme is active.
SETTING_STEPS_MODE	Steps, miles, or km on the steps readout.
SETTING_DISTANCE_UNIT	Km or miles on the standalone Distance panel.
SETTING_TIME_FORMAT	Which TimeFormat the clock uses.
SETTING_BLUETOOTH_ICON	Whether the bluetooth icon shows.
SETTING_QUIET_TIME_ICON	Whether the Quiet Time mark shows.
SETTING_BLUETOOTH_VIBE_CONNECT	Vibe pattern to fire when the phone connects.
SETTING_BLUETOOTH_VIBE_DISCONNECT	Vibe pattern to fire when the phone drops.
SETTING_HOURLY_VIBE	Vibe pattern to fire on the hour.
SETTING_BATTERY_DISPLAY	What the battery readout shows.
SETTING_HEADER_FONT	Which font the panel header labels use, as an index into the face's header font table.
SETTING_COUNT	How many known settings there are.

SettingType

enum SettingType

How a setting encodes on the wire and how the sanitize pass clamps it.

Enumerator
SETTING_BOOL	Sent as a byte, 0 or 1. default_num holds the default.
SETTING_ENUM_U8	Sent as text holding the number, since Clay sends selects as strings.
SETTING_CSTRING	Sent as text, copied into a fixed buffer.
SETTING_COLOR	Sent as a 0xRRGGBB number, stored as one opaque GColor byte.

StepsMode

enum StepsMode

SETTING_STEPS_MODE choices.

Enumerator
STEPS_MODE_STEPS	Shows the raw step count.
STEPS_MODE_MILES	Shows the distance walked, in miles.
STEPS_MODE_KM	Shows the distance walked, in kilometres.
STEPS_MODE_COUNT	How many choices this setting has.

TimeFormat

enum TimeFormat

SETTING_TIME_FORMAT choices.

Enumerator
TIME_FORMAT_SYSTEM	Follows the watch's own 12 or 24 hour setting.
TIME_FORMAT_12H	12 hour with a leading zero like 06:30
TIME_FORMAT_24H	24 hour clock
TIME_FORMAT_BEATS	Swatch Internet Time, offered as .beats on the settings page.
TIME_FORMAT_12H_NO_LEAD	12 hour without a leading zero like 6:30
TIME_FORMAT_COUNT	How many choices this setting has.

VibeChoice

enum VibeChoice

Bluetooth connect/disconnect vibe pattern choices.

Enumerator
VIBE_NONE	No vibration.
VIBE_SHORT	A single short pulse.
VIBE_LONG	A single long pulse.
VIBE_DOUBLE	Two short pulses.
VIBE_COUNT	How many choices this setting has.

Function Documentation

settings_apply_inbox()

SettingsInbound settings_apply_inbox

(

DictionaryIterator *

iter

)

Apply any settings present in an inbox message to the active face.

Decodes only. The caller persists and reacts based on the returned flags.

A field already holding what the message carries is left alone and flags nothing. The config page sends the whole page on every save, so the flags say what moved rather than what turned up.

Parameters

iter	The dictionary iterator to decode from.

Returns

Which categories of setting changed.

settings_enum_count()

uint8_t settings_enum_count

(

SettingId

id

)

How many values an enum setting allows (its sanitize ceiling).

Lets a walk step through every option of an enum (e.g. every theme) without hand-counting.

Parameters

id	The known enum setting.

Returns

The value count, or 0 if the active face didn't subscribe to it.

settings_init()

void settings_init

(

const SettingsSchema *

schema

)

Load a face's settings from their saved blobs, applying defaults first.

Walks the companion chain so every schema in it is loaded. A saved blob is read only when its size and version fit the schema, or when the schema's migrate hook takes it, and every field read back is cleaned. A blob that fits neither is dropped and the schema stays on its defaults. A schema over the 256 bytes one persist key holds is logged as an error, since it can never be saved whole.

Parameters

schema

The head schema defining the face's settings.

settings_mark_restored()

void settings_mark_restored

(

void

)

Clears settings_was_fresh once a save or restore from the settings page has been saved.

Only that message counts. Anything else the phone sends while the watch is fresh stays in memory, so the phone still sees a fresh watch and pushes its whole config back.

settings_save()

void settings_save

(

void

)

Persist the active face's structs under their keys (the whole chain).

A struct that does not reach flash whole is logged as an error and not tried again.

settings_serialize()

bool settings_serialize

(

DictionaryIterator *

iter

)

Write every field of the active face into an outbox iterator.

Stops at the first field that does not fit. The transport opens its outbox at settings_serialized_size_max, so the whole snapshot fits.

Parameters

iter	The dictionary iterator to encode into.

Returns

True when every field was written, false when the outbox ran out of room partway.

settings_serialized_size_max()

uint32_t settings_serialized_size_max

(

void

)

The most outbox bytes every field of the active face could ever take once written.

Counts each string as filling its whole buffer, so no later settings change can outgrow it. The transport sizes its outbox from this when it opens.

Returns

The bytes the fields could need, not counting the dictionary's own one byte header.

settings_set_u8()

void settings_set_u8	(	SettingId	id,
		uint8_t	value )

Write a known uint8 or enum setting by id. In memory only, does not persist.

The write-side mirror of settings_u8. Does nothing if the active face isn't subscribed to the id. Used by the dev theme walk to force a theme without touching persistence.

Parameters

id	The known setting to write.
value	The value to store.

settings_str()

const char * settings_str

(

SettingId

id

)

Read a known string setting by id.

Parameters

id	The known setting to read.

Returns

The stored string, or "" if the active face did not subscribe to it.

settings_u8()

uint8_t settings_u8

(

SettingId

id

)

Read a known uint8/bool setting by id.

Parameters

id	The known setting to read.

Returns

The stored value, or 0 if the active face did not subscribe to it.

settings_was_fresh()

bool settings_was_fresh

(

void

)

Whether the watch booted with no saved settings, because storage was wiped by a fresh install or an update. Lets the phone know it should push its own config back rather than trust the watch's defaults.

Returns

true when any schema in the chain had no blob at settings_init, or one was reset for a blob it could not read, and no settings page message has landed since.