---
name: garmin-watchface
description: Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C. Use when working on a Connect IQ watch face or app - creating one, fixing layout that clips or overlaps, capturing simulator screenshots, adding app settings, widening device support, or preparing a Connect IQ Store submission. Encodes the traps that silently produce a passing build and a broken face.
---

# Garmin Connect IQ watch faces

Monkey C gives you almost no safety net. The compiler is happy to build a face
that draws off the bottom of the screen, a test suite that contains no tests, and
a colour that is not the colour you get. Everything below is a failure mode that
looked like success first.

**Read `reference/` files as needed: do not read them all up front.**

| File | When |
| --- | --- |
| `reference/display.md` | Choosing colours, brightness, legibility; **AMOLED always-on and burn-in** |
| `reference/layout.md` | Positioning anything; content clipped, overlapping, or off-screen |
| `reference/testing.md` | Writing tests; a suspiciously clean test run |
| `reference/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
| `reference/devices.md` | Adding device support, launcher icons, API levels |
| `reference/store.md` | Publishing, listing copy, IP questions |
| `reference/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |

## Tools

Run these rather than reinventing them. All are standalone.

```bash
bin/ciq-doctor                    # toolchain check: SDK, JDK, key, devices
bin/ciq-devices                   # survey installed devices by resolution
bin/ciq-devices --same-as fenix6pro   # products you can add with no code change
bin/ciq-capture out.png           # calibrated simulator screenshot
bin/ciq-capture out.png --face --size 260   # cropped + masked to the round display
bin/ciq-calibrate                 # re-derive the display rect if capture looks wrong
bin/ciq-release                   # pre-submission check: package, screenshots, icon, keys, copy
```

`bin/ciq-release` is what you run before opening the store portal. Every check
in it is something otherwise discovered halfway through the submission form --
a stale screenshot set, an icon still copied from the last project, or copy
containing a character the description validator rejects.

`bin/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
a window: without a frontmost check it silently photographs whatever is on top,
and the window moves between simulator restarts. Both failure modes produce a
plausible PNG of the wrong thing.

## The seven things that will bite you

### 1. `make test` can compile zero tests and report success

If `monkey.jungle` sets `base.excludeAnnotations = test`, every `(:test)`
function is stripped from **every** target, including the unit-test build. You
get `BUILD SUCCESSFUL` and a green run with nothing compiled, even when the test
files reference symbols that no longer exist.

Fix: a second jungle passed as an additional `-f`. See
`templates/monkey.test.jungle` and the `test` target in `templates/Makefile`.

**Prove it before you trust it.** Put a deliberately unresolvable symbol in one
test and confirm the build fails:

```monkeyc
return ThisDoesNotExist.definitelyNotAFunction();
```

### 2. Never hardcode a Y coordinate or assume a font height

`dc.getFontHeight()` is the only source of truth, and the numbers are larger than
they look. Measured on fenix 6 Pro:

| Font | Height |
| --- | --- |
| `FONT_XTINY` | 19 |
| `FONT_TINY` | 29 |
| `FONT_SMALL` | 32 |
| `FONT_NUMBER_MEDIUM` | 74 |

**Font tiers already scale with the device.** `FONT_XTINY` is a tier, not a
pixel height: a 454px watch supplies a proportionately taller glyph than a
260px one, unasked. So when text looks wrong at a new resolution, the bug is a
LENGTH that failed to scale, never the font. Do not add screen-size branching
to pick a bigger tier -- doing so double-scales, and labels end up wider than
the containers naming them.

Content drawn past the screen height is simply invisible: no error, no warning,
no clipping indicator. A two-line `FONT_NUMBER_MEDIUM` block is 148px of a 260px
face.

Derive every Y at draw time, and **clamp** so a bottom row cannot be pushed off:

```monkeyc
function clampRuleY(derived as Number, footerH as Number) as Number {
    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
    return derived > maxRuleY ? maxRuleY : derived;
}
```

See `reference/layout.md`.

### 3. The screen is round; your layout is not

Check content against the bezel curve, not the bounding square. A rectangle
inscribed in a circle fails at its **corners** long before its sides.

```monkeyc
function halfWidthAt(y as Number) as Number {
    var dy = y - CENTER;
    var inside = (CENTER * CENTER) - (dy * dy);
    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
}
```

### 4. Colours are quantised, and brightness is reflectance

Many devices snap to a 4×4×4 lattice: `0x00 / 0x55 / 0xAA / 0xFF` per channel. A
colour not already on it is not the colour that ships.

More important: MIP screens are **transflective with no backlight**. A colour's
brightness *is* how much ambient light it returns. Grey reflects about two-thirds
of what white does. Choosing a photographically accurate grey for a large area
makes the whole face read as dim on the wrist while looking fine in the
simulator's backlit LCD.

Corollary: a saturated colour on a glyph reflects only its own channel, making
the thing you want to read the *dimmest* thing on screen.

See `reference/display.md`.

### 5. The simulator lies about settings

It persists app settings and **ignores changed defaults in `properties.xml`**
until you do File → Reset All App Data. A property will keep reading its old
value while the XML plainly says otherwise. This looks exactly like broken
settings code.

Reset also drops the loaded device, so relaunch and re-push afterwards.

See `reference/simulator.md`.

### 6. On AMOLED, the face you designed is the one that fails review

`requiresBurnInProtection` devices must show a restricted always-on frame
between wrist raises. The trap is that the *stronger* your face's identity
(a bright panel, a filled dial), the worse a dimmed version of it performs,
because it still lights most of the screen. The always-on frame has to be a
different drawing: outlines where there were fills, and shifted a few pixels on
a cycle so no pixel is driven continuously.

Also note the flag can be **null** on older products, and a null propagating
into a `Boolean` field throws at the first wrist drop.

See the AMOLED section of `reference/display.md`.

### 7. A watch face CAN have settings on the watch

`AppBase.getSettingsView()` has existed since **API 3.2.0** and the SDK
documents it as "only applicable to watch faces and data fields". Plenty of
store copy (including, at one point, this author's own) claims settings are
reachable only from the phone. They are not.

The override signature must include `or Null` or the compiler rejects it as
narrowing:

```monkeyc
function getSettingsView() as
    [WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates] or Null {
    return [new SettingsMenu(), new SettingsMenuDelegate()];
}
```

Two things to get right in the menu itself:

- `ToggleMenuItem` has **already flipped its own state** by the time `onSelect`
  runs. Read `isEnabled()`; negating the stored value inverts the setting.
- A picker should `setFocus()` the current choice, not open at the top of a long
  list. If the list filters out unavailable options, item position is *not* the
  option id: count the focus row as you build the list.

Keep one module that owns every property read, each wrapped with a default, and
have both the phone path and the on-watch menu go through it. Two readers with
two sets of defaults is exactly how the watch and the phone come to disagree
about what "off" means, and check the fallbacks actually match
`properties.xml`, because nothing enforces that.

## Workflow

### Starting a face

1. `bin/ciq-doctor`: confirm SDK, JDK, developer key, target device installed.
2. Copy `templates/Makefile`, `templates/monkey.jungle`, `templates/monkey.test.jungle`.
3. Generate a fresh app id: `python3 -c "import uuid;print(uuid.uuid4().hex)"`.
4. Split source by responsibility. This structure has held up well:

| Module | Holds |
| --- | --- |
| `Palette.mc` | Colours only, all lattice-exact |
| `Layout.mc` | Geometry, derivations, bezel maths: no drawing |
| `<Widget>.mc` | Drawing primitives (rows, bars, segments) |
| `Fields.mc` | Formatting and thresholds: pure, easy to test |
| `Sensors.mc` | Sensor reads with null handling |
| `<Name>View.mc` | Composition only |

Keeping `Layout` free of `Dc` calls is what makes geometry unit-testable.

### Every change

```bash
make build && make test && make lint
```

`make lint` is level 3 and catches real problems the level 2 build allows.

### Before committing

Capture and *look at it*. Layout bugs are invisible in a passing test run:

```bash
make build && make sim
bin/ciq-capture /tmp/face.png --face --size 260
```

Then Read the PNG. Every layout bug in this skill's history was found by looking,
not by testing.

## Monkey C gotchas

- Module-level functions take **no** visibility modifier. `private` and `hidden`
  are class-only; at module scope they are syntax errors.
- `dc.fillPolygon` wants `Array<[Numeric, Numeric]>`. Cast the literal:
  `[[x, y], ...] as Array<[Numeric, Numeric]>`.
- `getInitialView()` returns
  `[WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates]`.
- `Application.Properties.getValue()` **throws** when a key is absent, which
  happens on a fresh install before settings have ever been written. Wrap every
  read with a default.
- Integer division everywhere. Centring an odd width leaves a 1px skew: write
  tests that allow it rather than forcing constants to stay even.

## Reference watches and homages

If reproducing a real object, get these right before anything else, because they
are what makes it recognisable:

- **Display polarity.** A 1970s LCD is *positive*: dark segments on a pale panel,
  the inverse of every modern face. Getting this backwards turns a crystal into a
  screen.
- **Proportion.** Bezels on vintage digitals are thick; the window is smaller
  than memory suggests.
- **Where the legends sit**: maker's name on the bezel, not the glass.

No system font is a segment display. If you need one, draw it: see
`reference/layout.md` for a working seven-segment renderer, including the ghost
(unlit) segments that are most of what sells the effect.

**Do not print a real brand on the face.** See `reference/store.md`.