The slot engine, zones, fonts, icon cache, and weather icons and labels. More...

Files
file	src/c/pebble/ui/engine/engine.c
	The skin-neutral slot engine. Builds one layer per slot and repaints them all on a store change.
file	src/c/pebble/ui/engine/engine.h
	The skin-neutral slot engine: builds one layer per slot from a face's slot list and repaints them all when a store changes. A slot is either a text-slot (a TextLayer built from a Zone, so the font-fit tiers still apply) or a draw-slot (a custom layer whose update_proc paints a gauge, icon, or panel). A face supplies a build callback. A dynamic face (the grid) re-runs it on a layout change. This is the shared core a face's own engine sits on.
file	src/c/pebble/ui/fonts.c
	Font registry implementation. A flat id-indexed table of loaded handles.
file	src/c/pebble/ui/fonts.h
	Font registry. A face loads its custom fonts once, each under a small integer slot id, and the rest of the ui looks them up by id so layout tables can stay static, carrying an id rather than a live GFont handle. The registry does not care which fonts they are. The face owns the slots and what they mean. See the face's own draw/fonts.h. This just maps an id to its handle.
file	src/c/pebble/ui/icon_cache.c
	Icon store. A small cache that maps a resource id to its picture and is shared across a face, so each icon loads once and is freed in one place. Also carries the palette tint and the auto-trim margin scan.
file	src/c/pebble/ui/icon_cache.h
	A small load-once icon store keyed by resource id, shared across a face so each icon picture loads a single time and frees in one place. Alongside it sits the palette tint and an optional auto-trim that measures each icon's transparent border so a caller can pin the visible art instead of the padded bitmap box.
file	src/c/pebble/ui/readouts.c
	Text formatters shared by the faces, bound to the engine's text-slots.
file	src/c/pebble/ui/readouts.h
	Text formatters shared by the faces: pull a value from a store, honour the relevant setting, and format it into a buffer. Each matches the engine's text-slot signature, so a slot binds straight to one (e.g. { .zone = &s_zones[ZONE_TIME], .text = readout_time }).
file	src/c/pebble/ui/weather/icons.c
	Weather-icon resource lookup implementation.
file	src/c/pebble/ui/weather/icons.h
	Condition-string to weather-icon resource lookup.
file	src/c/pebble/ui/weather/icons_table.g.h
	Condition token to weather icon resource lookup.
file	src/c/pebble/ui/zone.c
	Layout primitives implementation.
file	src/c/pebble/ui/zone.h
	Layout primitives. Defines paintable areas and their text alignments.

Data Structures
struct	EngineSlot
	One slot of a face. Set zone (+ text) for a text-slot, or frame (+ draw) for a draw-slot. Never both. A text-slot with no text stays empty, and so does a draw-slot with no draw. More...
struct	IconMargins
	The transparent border around an icon's opaque art, in pixels per side. More...
struct	Zone
	Everything needed to present one text slot. Where it sits, and which registered font, alignment, and colour to use, plus up to three smaller font and rect tiers to step down to when the text would overflow. More...

Macros
#define	ENGINE_SLOTS_MAX 10
#define	ENGINE_MAX_SLOTS ENGINE_SLOTS_MAX
	The old name for ENGINE_SLOTS_MAX, deprecated. A face that sets it or reads it gets the same cap.
#define	FONT_SLOTS_MAX 24
#define	ICON_AUTOTRIM 1
#define	ICON_TRIM_LOG 0

Typedefs
typedef uint8_t(*)	EngineBuild(EngineSlot *out, uint8_t max, GRect bounds)
	Fills the caller's slots and returns the count. A static face returns a fixed list. A dynamic face works it out from settings.
typedef uint8_t	FontId
	A font slot id. The face defines its slots as 0 to FONT_SLOTS_MAX-1 and the registry treats the id as a plain index.

Functions
void	engine_init (Window *window, EngineBuild build)
	Build the slot layers for a face and paint them once.
void	engine_deinit (void)
	Tear down the slot layers.
void	engine_rebuild (void)
	Rebuild the slot layers (after a layout or theme change).
void	engine_mark_dirty (void)
	Repaint every slot: text-slots re-pull + fit, draw-slots mark dirty.
void	engine_mark_dirty_tags (uint32_t changed)
	Repaint only the slots whose tags intersect changed (plus any slot with no tags). Lets a face route a store change to just the slots that read from it.
void	fonts_register (FontId id, GFont handle)
	Store a loaded font handle under its slot id.
void	fonts_register_system (FontId id, GFont handle)
	Store a system font handle under its slot id, without taking ownership.
GFont	fonts_get (FontId id)
	Resolve a slot id to its handle. Falls back to the system font on a miss.
void	fonts_unload_all (void)
	Unload every font the app owns and clear the registry.
GBitmap *	icon_get (uint32_t res)
	Hands back an icon picture from the cache, loading it the first time it is asked for.
GSize	icon_size (uint32_t res)
	The size of an icon in pixels. Gives back GSize(0,0) if it could not load.
IconMargins	icon_margins (uint32_t res)
	The measured transparent margins of a cached icon. Loads and measures it the first time, then returns the cached numbers. All zero when auto-trim is off or the icon could not load.
IconMargins	icon_margins_of (GBitmap *bmp)
	Measures the transparent margins of any bitmap, for icons that live outside the shared cache such as a weather picture that reloads as the weather changes. All zero when auto-trim is off or the bitmap is NULL.
void	icon_tint (GBitmap *bmp, GColor color)
	Paints an icon a different colour. It only works on icons saved as little colour-table pictures. Other kinds it just leaves alone. The see-through pixels stay see-through so the edges keep looking clean.
void	icon_align_trim (GAlign align, IconMargins margins, int trim_dx, int trim_dy)
	The extra offset that pins the opaque box rather than the full bitmap at a given anchor. A right or bottom edge kills the trailing margin. A left or top edge kills the leading one. A centred axis splits the difference so the visible art centres.
void	icons_cleanup (void)
	Frees every icon picture in the cache.
void	readout_time (char *out, size_t n)
	Format the clock per the Time Format setting: 24h, 12h, system, or .beats.
void	readout_meridiem (char *out, size_t n)
	Format the AM/PM marker, or empty on a 24-hour or .beats clock.
void	readout_date (char *out, size_t n)
	Format the date in the chosen format, upper-cased.
bool	readout_date_shows_beats (void)
	Whether the chosen date format ends in a .beats reading.
void	readout_hr (char *out, size_t n)
	Format the heart rate, or "--" when there is no reading.
void	readout_steps (char *out, size_t n)
	Format the step count, or the distance walked per the Steps Mode setting.
void	readout_weather_temp (char *out, size_t n)
	Format the temperature with its unit letter, or "--" when there is no reading.
void	readout_weather_cond (char *out, size_t n)
	Format the condition word, or "--" when there is none.
void	readout_lat (char *out, size_t n)
	Format the latitude string, or "--" when there is no fix.
void	readout_lon (char *out, size_t n)
	Format the longitude string, or "--" when there is no fix.
uint32_t	wx_resource_for (const char *condition)
	Look up the weather-icon resource for a condition abbreviation.
static uint32_t	wx_resource_for_table (const char *condition)
	Finds the icon resource for a condition token.
TextLayer *	zone_make_layer (Layer parent, const Zone zone)
	Creates a transparent text layer for a zone and attaches it to the parent layer.
void	zone_set_text_fit (TextLayer layer, const Zone zone, const char *text)
	Sets a text layer's text, stepping down through the zone's font tiers to find one the text fits in.

Detailed Description

The slot engine, zones, fonts, icon cache, and weather icons and labels.

Everything that puts pixels on the screen, shared by every face's layout.

Macro Definition Documentation

◆ ENGINE_SLOTS_MAX

#define ENGINE_SLOTS_MAX 10

Most slots a single face can declare. Ten covers the largest layout the framework expects, so the slot arrays hold no dead entries. A face that needs more sets it in its appinfo's defines

◆ FONT_SLOTS_MAX

#define FONT_SLOTS_MAX 24

Registry capacity. A face can check its own count against this at build time, so adding a slot past it fails the build with a clear message. A face that needs more sets it in its appinfo's defines.

◆ ICON_AUTOTRIM

#define ICON_AUTOTRIM 1

Auto-trim measures each icon's see-through margin once on load so placement can follow the visible art. Set to 0 to pin the full bitmap box instead

◆ ICON_TRIM_LOG

#define ICON_TRIM_LOG 0

Logs each icon's measured N/E/S/W on first load so you can check the numbers. Off by default in the shared lib so a normal build stays quiet. A face can switch it on

Typedef Documentation

◆ EngineBuild

typedef uint8_t(*) EngineBuild(EngineSlot *out, uint8_t max, GRect bounds)

Fills the caller's slots and returns the count. A static face returns a fixed list. A dynamic face works it out from settings.

Parameters

out	Where to write the slots.
max	How many slots out holds. Never write past it. The engine cuts a count past max back, but a write past the end has already landed on the engine's other state by then.
bounds	The window's root bounds, handy for a full-window draw-slot (overlays that paint at absolute coords).

Returns: How many slots were written.

Function Documentation

◆ engine_init()

void engine_init	(	Window *	window,
		EngineBuild	build )

Build the slot layers for a face and paint them once.

Parameters

window	The main window.
build	The face's slot-builder.

◆ engine_mark_dirty_tags()

void engine_mark_dirty_tags ( uint32_t changed )

Repaint only the slots whose tags intersect changed (plus any slot with no tags). Lets a face route a store change to just the slots that read from it.

Parameters

changed The dependency bits that changed.

◆ fonts_get()

GFont fonts_get ( FontId id )

Resolve a slot id to its handle. Falls back to the system font on a miss.

Parameters

id	The slot id.

Returns: The font handle.

◆ fonts_register()

void fonts_register	(	FontId	id,
		GFont	handle )

Store a loaded font handle under its slot id.

This is for a handle the app loaded itself with fonts_load_custom_font, so the registry takes on freeing it in fonts_unload_all. A system font must go in through fonts_register_system instead, since the app never owned it, and unloading one is a fault at teardown.

You keep the handle. Registering over a slot that already holds one just overwrites it and the old font stays loaded, so a face swapping a font at runtime needs to hang on to the old handle and unload it first. The same handle may safely sit in more than one slot, since fonts_unload_all clears every copy when it frees it.

A NULL handle goes in like any other and fonts_get then reads that slot as empty and hands back the system font for the rest of the session. fonts_load_custom_font gives you NULL when it cannot load the resource, so passing that straight in quietly parks you on the fallback.

Parameters

id	The slot id.
handle	The loaded font handle.

◆ fonts_register_system()

void fonts_register_system	(	FontId	id,
		GFont	handle )

Store a system font handle under its slot id, without taking ownership.

fonts_get_system_font hands back a handle the firmware owns, so the app must never unload it. Registering one through fonts_register would put it in the queue for fonts_unload_all and fault on the way out. This parks it in the slot and leaves it out of that sweep.

Parameters

id	The slot id.
handle	The system font handle.

◆ fonts_unload_all()

void fonts_unload_all ( void )

Unload every font the app owns and clear the registry.

Only handles registered through fonts_register are freed. System fonts parked with fonts_register_system are left alone, and a handle sitting in several slots is freed once.

◆ icon_align_trim()

void icon_align_trim	(	GAlign	align,
		IconMargins	margins,
		int *	trim_dx,
		int *	trim_dy )

The extra offset that pins the opaque box rather than the full bitmap at a given anchor. A right or bottom edge kills the trailing margin. A left or top edge kills the leading one. A centred axis splits the difference so the visible art centres.

Parameters

	align	The anchor the icon is pinned at.
	margins	The icon's transparent margins.
[out]	trim_dx	Output for the sideways offset.
[out]	trim_dy	Output for the up and down offset.

◆ icon_get()

GBitmap * icon_get ( uint32_t res )

Hands back an icon picture from the cache, loading it the first time it is asked for.

Draw it straight away rather than keeping it. A full cache frees its oldest icon to make room, so a picture held across a lookup of a different icon, such as one set on a BitmapLayer, can be freed underneath it.

Parameters

res	The resource id.

Returns: The cached picture, or NULL if it could not be loaded.

◆ icon_margins()

IconMargins icon_margins ( uint32_t res )

The measured transparent margins of a cached icon. Loads and measures it the first time, then returns the cached numbers. All zero when auto-trim is off or the icon could not load.

Parameters

res	The resource id.

Returns: The N/E/S/W transparent margins.

◆ icon_margins_of()

IconMargins icon_margins_of ( GBitmap * bmp )

Measures the transparent margins of any bitmap, for icons that live outside the shared cache such as a weather picture that reloads as the weather changes. All zero when auto-trim is off or the bitmap is NULL.

Parameters

bmp	The bitmap to scan.

Returns: The N/E/S/W transparent margins.

◆ icon_size()

GSize icon_size ( uint32_t res )

The size of an icon in pixels. Gives back GSize(0,0) if it could not load.

Parameters

res	The resource id.

Returns: The size of the picture.

◆ icon_tint()

void icon_tint	(	GBitmap *	bmp,
		GColor	color )

Paints an icon a different colour. It only works on icons saved as little colour-table pictures. Other kinds it just leaves alone. The see-through pixels stay see-through so the edges keep looking clean.

Parameters

bmp	The picture to recolour (nothing happens if it is NULL).
color	The colour to paint it.

◆ readout_date()

void readout_date	(	char *	out,
		size_t	n )

Format the date in the chosen format, upper-cased.

A format carrying the .beats token gets a reading written into it, so the date line can end in one (0618.672) alongside a normal clock.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_date_shows_beats()

bool readout_date_shows_beats ( void )

Whether the chosen date format ends in a .beats reading.

A face asks this when it builds its TimeConfig. A beat is 86.4 seconds, so a date line carrying one needs the .beats ticker or it sits on a stale reading until the next minute.

Returns: true if the date format carries the .beats token.

◆ readout_hr()

void readout_hr	(	char *	out,
		size_t	n )

Format the heart rate, or "--" when there is no reading.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_lat()

void readout_lat	(	char *	out,
		size_t	n )

Format the latitude string, or "--" when there is no fix.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_lon()

void readout_lon	(	char *	out,
		size_t	n )

Format the longitude string, or "--" when there is no fix.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_meridiem()

void readout_meridiem	(	char *	out,
		size_t	n )

Format the AM/PM marker, or empty on a 24-hour or .beats clock.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_steps()

void readout_steps	(	char *	out,
		size_t	n )

Format the step count, or the distance walked per the Steps Mode setting.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_time()

void readout_time	(	char *	out,
		size_t	n )

Format the clock per the Time Format setting: 24h, 12h, system, or .beats.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_weather_cond()

void readout_weather_cond	(	char *	out,
		size_t	n )

Format the condition word, or "--" when there is none.

The night marker is trimmed, so "CLEAR_NIGHT" reads as "CLEAR". The glyph still uses the full token.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ readout_weather_temp()

void readout_weather_temp	(	char *	out,
		size_t	n )

Format the temperature with its unit letter, or "--" when there is no reading.

Parameters

[out]	out	Output buffer.
	n	Buffer size.

◆ wx_resource_for()

uint32_t wx_resource_for ( const char * condition )

Look up the weather-icon resource for a condition abbreviation.

Parameters

condition The condition abbreviation string.

Returns: The corresponding resource ID.

◆ wx_resource_for_table()

uint32_t wx_resource_for_table ( const char * condition )

static

Finds the icon resource for a condition token.

A token ending in _NIGHT gets its night glyph where the condition has one. An unknown token, or a NULL one, gets the WEATHER_NOW_NA icon.

Parameters

condition The condition token from the phone, such as RAIN or RAIN_NIGHT. May be NULL.

Returns: The RESOURCE_ID_ICON_* resource to load.

◆ zone_make_layer()

TextLayer * zone_make_layer	(	Layer *	parent,
		const Zone *	zone )

Creates a transparent text layer for a zone and attaches it to the parent layer.

Parameters

parent	The parent layer.
zone	The zone properties.

Returns: The new text layer, or NULL when the heap had no room for it. A caller holding NULL has an empty slot, so it must check before passing the layer back in.

◆ zone_set_text_fit()

void zone_set_text_fit	(	TextLayer *	layer,
		const Zone *	zone,
		const char *	text )

Sets a text layer's text, stepping down through the zone's font tiers to find one the text fits in.

It tries the main tier first, then each fallback tier in order, and uses the largest one whose text fits. A face skips a tier by leaving its rect zero-sized, since a zero-filled struct already reads that way. The main tier always exists. If the text fits nowhere, the smallest defined tier wins and the text layer trails an ellipsis as a last resort.

Parameters

layer	The text layer.
zone	The zone specifying the fallback fonts and rects.
text	The text to set.

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ENGINE_SLOTS_MAX

◆ FONT_SLOTS_MAX

◆ ICON_AUTOTRIM

◆ ICON_TRIM_LOG

Typedef Documentation

◆ EngineBuild

Function Documentation

◆ engine_init()

◆ engine_mark_dirty_tags()

◆ fonts_get()

◆ fonts_register()

◆ fonts_register_system()

◆ fonts_unload_all()

◆ icon_align_trim()

◆ icon_get()

◆ icon_margins()

◆ icon_margins_of()

◆ icon_size()

◆ icon_tint()

◆ readout_date()

◆ readout_date_shows_beats()

◆ readout_hr()

◆ readout_lat()

◆ readout_lon()

◆ readout_meridiem()

◆ readout_steps()

◆ readout_time()

◆ readout_weather_cond()

◆ readout_weather_temp()

◆ wx_resource_for()

◆ wx_resource_for_table()

◆ zone_make_layer()

◆ zone_set_text_fit()