312 lines
15 KiB
Markdown
312 lines
15 KiB
Markdown
# Golf Score — Application Specification
|
||
|
||
**Platform:** Pebble Time 2 (Emery, 200×228 px, color)
|
||
**Source:** `src/c/golf_score.c`
|
||
**Build output:** `build/golf_score.pbw`
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
A single-file Pebble watchapp for tracking golf strokes and putts across an 18-hole round. The design prioritises one-handed glanceability and minimal button presses during play, with correction and navigation features accessible via long presses.
|
||
|
||
---
|
||
|
||
## 2. Data Model
|
||
|
||
### Core types
|
||
|
||
```c
|
||
typedef struct {
|
||
int8_t strokes; // total shots on this hole, range [0, 99]
|
||
int8_t putts; // putts on this hole, range [0, strokes]
|
||
} HoleScore;
|
||
|
||
static HoleScore s_scores[MAX_HOLES]; // MAX_HOLES = 18
|
||
static int s_current_hole = 0; // index into s_scores, range [0, 17]
|
||
```
|
||
|
||
`int8_t` is used for both fields because:
|
||
- The practical maximum (99) fits in a signed byte.
|
||
- `sizeof(HoleScore)` = 2 bytes, so `sizeof(s_scores)` = 36 bytes — small enough that the entire array is written atomically as a single `persist_write_data` blob (no partial-update complexity).
|
||
|
||
### Invariant
|
||
|
||
`putts <= strokes` at all times. Every mutation point enforces this:
|
||
|
||
| Operation | Enforcement |
|
||
|-----------|-------------|
|
||
| DOWN (−1 stroke) | If `putts > strokes` after decrement, `putts = strokes` |
|
||
| UP long (+1 putt) | If `putts` would exceed `strokes`, `strokes` is raised to match |
|
||
| DOWN long (−1 putt) | Putts floored at 0; strokes unchanged |
|
||
|
||
The invariant was chosen to reflect real golf (putts are a subset of strokes), while keeping the enforcement logic local to each handler rather than centralised — each handler knows exactly which field it owns.
|
||
|
||
### Why putts are tracked separately from strokes
|
||
|
||
Many apps conflate them. Keeping a separate putt count per hole lets the player review putting performance on the scorecard (total putts is a standard handicap metric) without requiring a separate mode. The trade-off is a slightly more complex button map (long-press for putts), which is acceptable because putts happen far less frequently than stroke taps during a hole.
|
||
|
||
---
|
||
|
||
## 3. Persistence
|
||
|
||
```c
|
||
#define PERSIST_KEY_SCORES 0
|
||
#define PERSIST_KEY_HOLE 1
|
||
```
|
||
|
||
| Key | API | Written |
|
||
|-----|-----|---------|
|
||
| 0 | `persist_write_data` / `persist_read_data` | Entire `s_scores[18]` blob (36 bytes) |
|
||
| 1 | `persist_write_int` / `persist_read_int` | `s_current_hole` |
|
||
|
||
**Write points:** after every hole advance (SELECT), after jump-to-hole, after reset, and in `main()` after `app_event_loop()` returns (app exit). Stroke/putt increments during a hole are **not** written immediately to avoid flash wear from rapid taps.
|
||
|
||
**Read point:** once, at the top of `main()` before the window is pushed, so the first render already has the restored state.
|
||
|
||
**Design decision — no per-keypress save:** Pebble's persistent storage is flash-backed and has a finite write endurance. Saving on every UP/DOWN tap would burn through write cycles quickly during an 18-hole round. Losing a single stroke on a crash is an acceptable trade-off; losing an entire hole's worth of scores after a hole advance (which does save) is not.
|
||
|
||
**Design decision — blob vs. individual keys:** Writing the whole array as one blob is simpler than 18×2 individual keys and means the scores are always consistent (either the whole round is there or none of it is). It also fits comfortably within the 256-byte per-value maximum (`sizeof(s_scores)` = 36 bytes).
|
||
|
||
---
|
||
|
||
## 4. Window Architecture
|
||
|
||
### Window stack hierarchy
|
||
|
||
```
|
||
[main_window] ← always at the bottom; never popped by the app
|
||
└─ [settings_window] ← pushed by long SELECT on main
|
||
├─ [scorecard_window] ← pushed by "View Scorecard"
|
||
├─ [hole_picker_window] ← pushed by "Jump to Hole"
|
||
└─ [help_window] ← pushed by "Controls"
|
||
```
|
||
|
||
`main_window` is the only window created at startup and never destroyed during normal operation. All other windows are created on demand and destroy themselves in their `unload` handler (see §4.2).
|
||
|
||
### 4.1 Window lifecycle pattern
|
||
|
||
Every secondary window follows the same pattern:
|
||
|
||
```c
|
||
// Push (caller):
|
||
s_foo_window = window_create();
|
||
window_set_window_handlers(s_foo_window, (WindowHandlers){
|
||
.load = foo_window_load,
|
||
.unload = foo_window_unload,
|
||
});
|
||
window_stack_push(s_foo_window, true);
|
||
|
||
// Unload (self-cleanup):
|
||
static void foo_window_unload(Window *window) {
|
||
// destroy child layers first
|
||
window_destroy(s_foo_window);
|
||
s_foo_window = NULL;
|
||
}
|
||
```
|
||
|
||
Setting the pointer to `NULL` after `window_destroy` prevents dangling pointer use and makes it safe to check `if (s_foo_window)` elsewhere.
|
||
|
||
**Why self-destroy in unload?** The Pebble OS calls `unload` before the window is fully removed from the stack, giving the app a guaranteed cleanup point regardless of whether the window was popped by BACK, by `window_stack_pop`, or by `window_stack_remove`. Centralising cleanup in `unload` means no caller needs to remember to free anything.
|
||
|
||
### 4.2 Return-to-main after settings actions
|
||
|
||
After "Jump to Hole" or "Reset Round" complete, the app needs to pop multiple windows (hole picker + settings, or just settings) and return to main. This cannot be done synchronously inside a `SimpleMenuLayer` select callback because the callback fires while the layer's own event processing is still on the call stack — destroying the window mid-callback would corrupt the stack frame.
|
||
|
||
**Solution: 50 ms deferred timer**
|
||
|
||
```c
|
||
static void return_to_main_cb(void *data) {
|
||
s_return_timer = NULL;
|
||
Window *top;
|
||
while ((top = window_stack_get_top_window()) != NULL && top != s_main_window) {
|
||
window_stack_pop(false);
|
||
}
|
||
layer_mark_dirty(s_canvas_layer);
|
||
}
|
||
|
||
static void schedule_return_to_main(void) {
|
||
if (s_return_timer) app_timer_cancel(s_return_timer);
|
||
s_return_timer = app_timer_register(50, return_to_main_cb, NULL);
|
||
}
|
||
```
|
||
|
||
The 50 ms delay ensures the select callback has returned and the event loop has fully processed before any window is destroyed. The while loop pops whatever is above main without needing to know the exact stack depth, which makes it robust to future navigation changes.
|
||
|
||
Cancelling any existing timer before registering a new one prevents double-pops if an action is somehow triggered twice.
|
||
|
||
---
|
||
|
||
## 5. Main Window — Visual Layout
|
||
|
||
Screen: 200 × 228 px (no system status bar; app owns full screen).
|
||
|
||
```
|
||
y 0–43 GColorJaegerGreen fill (header)
|
||
"HOLE N / 18" GOTHIC_18_BOLD white centered (y=12, h=22)
|
||
y 44–49 gap
|
||
y 50–71 "STROKES" GOTHIC_18_BOLD dark-gray centered
|
||
y 70–127 stroke count BITHAM_42_BOLD black centered
|
||
y 133 divider line GColorLightGray x=[20, w-20]
|
||
y 139–160 "PUTTS" GOTHIC_18_BOLD dark-gray centered
|
||
y 158–215 putt count BITHAM_42_BOLD GColorCobaltBlue centered
|
||
y 216–227 hint bar GColorLightGray fill
|
||
hint text GOTHIC_14 dark-gray trailing-ellipsis centered
|
||
```
|
||
|
||
**Design decisions:**
|
||
|
||
- **Custom Layer instead of TextLayers:** The main screen is drawn by a single `LayerUpdateProc` (`canvas_update_proc`) rather than a collection of TextLayers. This avoids the overhead of multiple layer objects, keeps all layout constants in one place, and gives full control over drawing order (background → header fill → text, all in one pass).
|
||
|
||
- **BITHAM_42_BOLD for counts:** The largest readable number font available as a system font. At 42 pt the count is legible at a glance without raising the watch, which is the primary use case (hand on club, quick look).
|
||
|
||
- **Strokes black, putts cobalt blue:** Colour-coding the two counters avoids misreading at a glance. Blue was chosen for putts as it is visually subordinate to black, reflecting that putts are a subset metric.
|
||
|
||
- **Hint bar at bottom:** The 12 px hint bar is small enough to not compete with the counts but visible enough to remind new users about the long-press bindings. `GTextOverflowModeTrailingEllipsis` ensures it never wraps.
|
||
|
||
- **No status bar:** `StatusBarLayer` would consume 20 px and show a clock the player already has on the watch face. Reclaiming that space for larger number fonts was the right trade-off for a glance-use app.
|
||
|
||
---
|
||
|
||
## 6. Button Map
|
||
|
||
### Main window
|
||
|
||
| Button | Type | Action | Vibration |
|
||
|--------|------|--------|-----------|
|
||
| UP | Short | `strokes++` (max 99) | Short pulse |
|
||
| DOWN | Short | `strokes--` (floor 0); auto-clamp `putts` | None |
|
||
| SELECT | Short | Advance to next hole; save | Short pulse (double on hole 18) |
|
||
| UP | Long 700 ms | `putts++`; auto-raise `strokes` if needed | None |
|
||
| DOWN | Long 700 ms | `putts--` (floor 0) | None |
|
||
| SELECT | Long 700 ms | Push settings window | None |
|
||
|
||
**Why no vibration on DOWN?** A correction is often a recovery from a mis-tap. Adding a vibe would feel punishing and draw attention on the course. The asymmetry (vibe on increment, silent on decrement) also gives tactile confirmation that a stroke was successfully counted without looking.
|
||
|
||
**Why 700 ms long-press threshold?** The Pebble default is 500 ms. 700 ms was chosen to reduce accidental long-press triggers during normal play — a player tapping UP repeatedly at pace will not accidentally trigger the putt increment.
|
||
|
||
**Why long SELECT for settings rather than BACK?** The BACK button's system behaviour (pop window / exit app) cannot be reliably overridden for long press. Using SELECT long-press is the standard Pebble pattern for secondary actions.
|
||
|
||
### Settings window
|
||
|
||
Handled by `SimpleMenuLayer`, which wires UP/DOWN to scroll and SELECT to activate. BACK pops the window via system default.
|
||
|
||
### Scorecard and Help windows
|
||
|
||
`ScrollLayer` wires UP/DOWN to scroll. BACK pops via system default.
|
||
|
||
### Hole picker window
|
||
|
||
`SimpleMenuLayer` as above. Selecting a row calls `hole_picker_select_cb`, which sets `s_current_hole`, saves, and schedules the return-to-main timer.
|
||
|
||
---
|
||
|
||
## 7. Settings Window
|
||
|
||
Implemented as a `SimpleMenuLayer` with one section and four items:
|
||
|
||
| Index | Title | Subtitle | Effect |
|
||
|-------|-------|----------|--------|
|
||
| 0 | View Scorecard | — | Push scorecard window |
|
||
| 1 | Jump to Hole | Go back to any hole | Push hole picker window |
|
||
| 2 | Reset Round | Clears all scores | Zero all scores, reset to hole 1, save, double vibe, return to main |
|
||
| 3 | Controls | Button cheatsheet | Push help window |
|
||
|
||
`SimpleMenuSection` and `SimpleMenuItem` arrays are `static` module-level variables. `SimpleMenuLayer` does not deep-copy the arrays — if they were stack-allocated in `settings_window_load` they would be freed before the layer uses them. Static allocation is the correct pattern here.
|
||
|
||
Items are initialised in `settings_window_load` rather than at file scope because `SimpleMenuItem.callback` is a function pointer that cannot be a compile-time constant in C89/C90 (though it can in C99). Initialising in load keeps the code compatible across SDK versions.
|
||
|
||
---
|
||
|
||
## 8. Hole Picker Window
|
||
|
||
`SimpleMenuLayer` with one section of 18 rows, pre-scrolled to `s_current_hole`.
|
||
|
||
Row content is built in `hole_picker_window_load`:
|
||
|
||
```
|
||
Title: "> Hole N" (current hole)
|
||
" Hole N" (all others)
|
||
Subtitle: "X str / Y ptt" (if played: strokes > 0 OR putts > 0)
|
||
"not played" (otherwise)
|
||
```
|
||
|
||
**Why `> ` prefix instead of a colour or bold?** `SimpleMenuLayer` does not expose per-row styling. A text prefix is the only reliable way to mark the current hole within the system widget. Two leading spaces on non-current rows maintain visual alignment.
|
||
|
||
**Why rebuild titles/subtitles in `window_load` rather than keeping them live?** The data only needs to be accurate when the window opens. Keeping 18×(16+24) = 720 bytes of string buffers permanently resident but only occasionally accurate is wasteful. Building on load is cheap (one pass over 18 `HoleScore` structs) and guarantees the picker reflects current scores even if the user edits a hole and reopens settings.
|
||
|
||
Title/subtitle buffers are `static` for the same reason as settings items — `SimpleMenuLayer` holds pointers into them.
|
||
|
||
---
|
||
|
||
## 9. Scorecard Window
|
||
|
||
A `ScrollLayer` containing a single `TextLayer`. Content is built by `build_scorecard()` into `s_scorecard_buf[700]`.
|
||
|
||
**Buffer sizing:** 18 rows × ~18 chars + header (30 chars) + footer (20 chars) + current-hole marker (2 chars × 1 row) ≈ 370 chars. 700 bytes gives comfortable headroom.
|
||
|
||
The current hole is marked with a trailing ` <` on its row so the player can orient themselves without counting.
|
||
|
||
The content height for the `ScrollLayer` is measured with `graphics_text_layout_get_content_size` at load time using the same font and bounding width as the `TextLayer`. This keeps the scroll range exactly tight to the rendered text — no arbitrary magic number for content height.
|
||
|
||
The scorecard is **read-only**. Reset was moved to the Settings menu to enforce a clear separation: viewing data is non-destructive and accessible, mutating data requires an explicit settings action.
|
||
|
||
---
|
||
|
||
## 10. Help Window
|
||
|
||
A `ScrollLayer` + `TextLayer` displaying `HELP_TEXT`, a `static const char *const` string literal compiled into flash. No heap allocation is needed for the string itself — `text_layer_set_text` holds a pointer to the literal directly.
|
||
|
||
The pattern is identical to the scorecard window but simpler: no `build_*` function, no dynamic buffer, no current-state dependency.
|
||
|
||
---
|
||
|
||
## 11. Static Variable Strategy
|
||
|
||
All window pointers, layer pointers, and string buffers are file-scope `static`. This is the idiomatic Pebble C pattern for several reasons:
|
||
|
||
1. **Pebble heap is small.** Stack frames are limited; large char arrays on the stack risk overflow.
|
||
2. **Layer pointers must outlive the function that creates them.** `window_load` builds the UI, but the layers live until `window_unload`. File-scope statics have the right lifetime automatically.
|
||
3. **`SimpleMenuLayer` does not copy its data.** Section and item arrays must remain valid for the lifetime of the layer — static storage guarantees this.
|
||
|
||
The downside is that only one instance of each secondary window can exist at a time, which is enforced by the navigation structure (settings is modal; its children are modal within it).
|
||
|
||
---
|
||
|
||
## 12. Source File Organisation
|
||
|
||
Functions are ordered bottom-up by dependency so that no forward declarations are needed:
|
||
|
||
```
|
||
1. Persistence (save_scores, load_scores)
|
||
2. Main canvas draw (canvas_update_proc)
|
||
3. Main window button handlers
|
||
4. Scorecard window (build_scorecard, load, unload)
|
||
5. Return-to-main timer (return_to_main_cb, schedule_return_to_main)
|
||
6. Hole picker window (select_cb, load, unload)
|
||
7. Settings callbacks (scorecard_cb, jump_cb, help_cb, reset_cb)
|
||
— defined after the windows they push
|
||
8. Settings window (load, unload, show_settings)
|
||
9. Main window click config and lifecycle
|
||
10. main()
|
||
```
|
||
|
||
This ordering means that every called function is defined before its caller, eliminating the need for a header file or forward declarations.
|
||
|
||
---
|
||
|
||
## 13. Memory Footprint (Emery)
|
||
|
||
| Region | Size |
|
||
|--------|------|
|
||
| `s_scores` | 36 bytes |
|
||
| String buffers (hole_buf, stroke_buf, putt_buf) | 40 bytes |
|
||
| `s_scorecard_buf` | 700 bytes |
|
||
| `s_hole_titles` | 288 bytes (18 × 16) |
|
||
| `s_hole_subtitles` | 432 bytes (18 × 24) |
|
||
| `HELP_TEXT` | ~380 bytes (flash, not RAM) |
|
||
| Total static RAM (approximate) | ~1.5 KB |
|
||
| SDK-reported free heap | 127 KB |
|
||
|
||
The app is extremely light on memory. The largest single allocation is `s_scorecard_buf` at 700 bytes. All secondary window layers are allocated in their `load` handlers and freed in `unload`, so only one secondary window's layer objects are in heap at any time.
|