Update docs

Author: ThomasFarstrike

docs/apps/app-lifecycle.md

@@ -140,6 +140,32 @@ def onPause(self, screen):
 
 **Important:** Call `super().onPause(screen)` to properly track foreground state.
 
+### onBackPressed(screen)
+
+Called when the user performs the back/close gesture (e.g. swiping from the left edge) **before** the activity is paused. This is the right place to ask the user for confirmation when there is unsaved work.
+
+Return `True` to consume the event and keep the activity in the foreground. In that case the activity is responsible for calling `finish()` later when it is ready to close. Return `False` (the default) to let the framework finish the activity normally.
+
+```python
+def onBackPressed(self, screen):
+    if self._has_unsaved_changes():
+        # Show a dialog; return True so the activity stays alive
+        self._show_exit_confirm()
+        return True
+    return False
+```
+
+In the dialog callback, call `self.finish()` to actually close the activity:
+
+```python
+def _on_exit_confirmed(self, dialog):
+    dialog.close()
+    self._save_changes()
+    self.finish()
+```
+
+**Important:** `finish()` does **not** call `onBackPressed()` again, so your dialog callbacks can safely call it.
+
 ### onStop(screen)
 
 Called when the activity is no longer visible (fully covered by another activity).
@@ -189,7 +215,7 @@ Activity Stack:
 
 1. **Starting a new activity:** Current activity receives `onPause()` → `onStop()`, new activity receives `onCreate()` → `onStart()` → `onResume()`
 
-2. **Going back:** Current activity receives `onPause()` → `onStop()` → `onDestroy()`, previous activity receives `onResume()`
+2. **Going back:** Framework first calls `onBackPressed()`. If it returns `True`, the activity stays foreground and must call `finish()` itself when ready. If it returns `False`, the current activity receives `onPause()` → `onStop()` → `onDestroy()`, and the previous activity receives `onResume()`
 
 ## Starting Activities
 
@@ -404,6 +430,8 @@ class NetworkAwareActivity(Activity):
 ✅ Check `has_foreground()` before updating UI from async operations  
 ✅ Use `setContentView()` at the end of `onCreate()`  
 ✅ Clean up resources in `onDestroy()`  
+✅ Use `onBackPressed()` to ask before discarding unsaved changes  
+
 
 ### Don'ts
 
@@ -412,6 +440,8 @@ class NetworkAwareActivity(Activity):
 ❌ Don't update UI from background threads without `update_ui_threadsafe_if_foreground()`  
 ❌ Don't assume the activity is still visible after async operations  
 ❌ Don't store references to LVGL objects after `onDestroy()`  
+❌ Don't show back-navigation confirmation dialogs in `onPause()` - use `onBackPressed()` instead  
+
 
 ## Services — Background Components
 
@@ -460,6 +490,7 @@ Services are declared either programmatically (system services) or via `"service
 | `onStart(screen)` | `onStart()` | MicroPythonOS passes screen |
 | `onResume(screen)` | `onResume()` | MicroPythonOS passes screen |
 | `onPause(screen)` | `onPause()` | MicroPythonOS passes screen |
+| `onBackPressed(screen)` | `onBackPressed()` | MicroPythonOS passes screen; called before `onPause()` on back gesture |
 | `onStop(screen)` | `onStop()` | MicroPythonOS passes screen |
 | `onDestroy(screen)` | `onDestroy()` | MicroPythonOS passes screen |
 | `finish()` | `finish()` | Same purpose |

docs/apps/appstore.md

@@ -11,6 +11,10 @@ App discovery is currently done by downloading the app list from [apps.micropyth
 - **Image Viewer**: Displays images stored in `/data/images/`.
 - **IMU**: Visualize data from the Intertial Measurement Unit, also known as the accellerometer.
 
+## Image Viewer
+
+The **Image Viewer** app displays images stored in `/data/images/`. See [Supported File Formats](../other/supported-file-formats.md) for the list of image formats the OS can decode.
+
 ## Screenshots
 
 <div class="grid">

docs/frameworks/font-manager.md

@@ -1,13 +1,13 @@
 # FontManager
 
-FontManager is a singleton framework for loading, caching, and composing LVGL fonts — including built-in bitmap fonts, TrueType fonts, and emoji image fonts. It uses LVGL's imgfont fallback mechanism to render 20×20 emoji PNGs inline with text, with nearest-neighbour scaling to match any font size.
+FontManager is a singleton framework for loading, caching, and composing LVGL fonts — including built-in bitmap fonts, TrueType fonts, and emoji image fonts. It uses LVGL's imgfont fallback mechanism to render 32×32 emoji PNGs inline with text, with nearest-neighbour scaling to match any font size.
 
 ## Overview
 
 FontManager centralizes all font concerns in a single class:
 
 - **Unified API** - One call (`getFont`) to get any font, with or without emoji support
-- **Emoji Compositing** - Transparently layers 20×20 emoji PNGs via LVGL's imgfont fallback, with nearest-neighbour scaling to match any font size
+- **Emoji Compositing** - Transparently layers 32×32 emoji PNGs via LVGL's imgfont fallback, with nearest-neighbour scaling to match any font size
 - **Lazy Caching** - Fonts and scaled image descriptors are cached on first use; no redundant work on subsequent calls
 - **Android-Inspired** - Follows the same singleton/class-method pattern as other MicroPythonOS frameworks
 
@@ -29,9 +29,13 @@ ttf_font = FontManager.getFont(size=42, ttf="M:apps/com.myapp/assets/MyFont.ttf"
 for info in FontManager.listFonts():
     print(info["name"], info["size"])
 
-# Get all available emoji codepoints
+# Get all available emoji codepoints (base codepoints only)
 for cp in FontManager.getEmojiCodepoints():
     print(hex(cp))
+
+# Get all available emoji strings (full sequences, including flag pairs)
+for s in FontManager.getEmojiStrings():
+    print(s)
 ```
 
 ## Architecture
@@ -56,17 +60,18 @@ Emoji PNGs are stored in `builtin/res/emojis/`:
 
 | Directory | Used for |
 |-----------|----------|
-| `20x20/`  | All fonts — emoji are rendered at 20×20 px and nearest-neighbour scaled up or down by LVGL as needed |
+| `32x32/`  | All fonts — emoji are rendered at 32×32 px and nearest-neighbour scaled up or down by LVGL as needed |
 
-`_imgfont_path_cb` receives the rendering font's pixel height and returns the 20×20 emoji source. LVGL's software renderer performs nearest-neighbour scaling to fit the target font size.
+`_imgfont_path_cb` receives the rendering font's pixel height and returns the 32×32 emoji source. LVGL's software renderer performs nearest-neighbour scaling to fit the target font size.
 
 ### Caching layers
 
 | Cache | Key | Value |
 |-------|-----|-------|
 | `_composed_font_cache` | `(font_id, emoji_size)` | Composed imgfont object |
 | `_ttf_font_cache` | `(path, size)` | `lv.tiny_ttf_create_file` result |
-| `_emoji_maps` | `dir_name` | `{codepoint: src_path}` dict |
+| `_emoji_map` | (none) | `{codepoint: src_path}` dict |
+| `_emoji_strings` | (none) | Sorted list of complete emoji strings |
 | `_imgfont_scaled_src_cache` | `(src, target_height)` | Scaled `lv.image_dsc_t` or original src |
 | `_imgfont_source_size_cache` | `src` | `(width, height)` tuple |
 | `_imgfont_empty_src_cache` | `target_height` | 1×h transparent `lv.image_dsc_t` |
@@ -128,7 +133,9 @@ for info in FontManager.listFonts(emojis=True):
 
 ### `getEmojiCodepoints()`
 
-Return a sorted list of all available emoji codepoints.
+Return a sorted list of the base emoji codepoints available in the emoji map.
+
+For multi-codepoint emoji such as flag sequences (e.g. `"🇸🇻"`), only the first codepoint is returned. Use `getEmojiStrings()` when you need complete, renderable emoji sequences.
 
 **Returns:** list of int
 
@@ -143,6 +150,25 @@ for cp in FontManager.getEmojiCodepoints():
 
 ---
 
+### `getEmojiStrings()`
+
+Return a sorted list of all available, complete emoji strings.
+
+Unlike `getEmojiCodepoints()`, this returns full sequences: flag emoji include both regional indicators, and emoji with variation selectors keep their trailing selector. This is the preferred API for building a visual list of every supported emoji.
+
+**Returns:** list of str
+
+**Example:**
+
+```python
+from mpos import FontManager
+
+for s in FontManager.getEmojiStrings():
+    print(s)
+```
+
+---
+
 ### `normalizeEmojiText(text)`
 
 Strip Unicode variation selectors (U+FE0E text selector, U+FE0F emoji selector) from a string. Useful before storing or comparing text that may have been pasted from a source that appends these codepoints.
@@ -167,20 +193,21 @@ To keep firmware image size small, the OS bundles ~50 of the most frequently-use
 
 ```
 builtin/res/emojis/
-└── 20x20/       # Pre-rendered at 20×20 px
+└── 32x32/       # Pre-rendered at 32×32 px
     ├── 1F600.png
-    ├── 263A.png
+    ├── 1F3CE-FE0F.png
+    ├── 1F1F8-1F1FB.png
     └── ...
 ```
 
-Files are named by their Unicode codepoint in uppercase hex (e.g. `1F600.png` for 😀). FontManager scans the directory at runtime and builds a `{codepoint: path}` map.
+Files are named by their Unicode codepoint(s) in uppercase hex, with multiple codepoints joined by `-` (e.g. `1F600.png` for 😀, `1F3CE-FE0F.png` for 🏎️, `1F1F8-1F1FB.png` for 🇸🇻). FontManager scans the directory at runtime and builds a `{codepoint: path}` map.
 
 ### Adding new emoji
 
-1. Add a PNG named `<CODEPOINT_HEX>.png` to `20x20/`:
+1. Add a PNG named `<CODEPOINT_HEX>.png` to `32x32/`:
 
 ```bash
-cp original.png 20x20/CODEPOINT.png
+cp original.png 32x32/CODEPOINT.png
 ```
 
 2. The new emoji will be picked up automatically on next boot — no code changes needed.
@@ -196,7 +223,7 @@ internal_filesystem/
 ├── lib/mpos/ui/
 │   └── font_manager.py      # FontManager class
 └── builtin/res/emojis/
-    └── 20x20/               # 20×20 px emoji PNGs
+    └── 32x32/               # 32×32 px emoji PNGs
 ```
 
 ## Related Frameworks

docs/other/supported-file-formats.md

@@ -0,0 +1,31 @@
+# Supported File Formats
+
+MicroPythonOS uses LVGL's built-in image decoders and its own audio stack. The formats below are supported out of the box for apps such as the Image Viewer and Music Player.
+
+## Image formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| PNG | `.png` | Fully supported via LodePNG. |
+| Baseline JPEG | `.jpg`, `.jpeg` | Fully supported via TJpgD. |
+| Progressive JPEG | `.jpg`, `.jpeg` | **Not supported.** Files will decode as `0x0` and appear blank. |
+| RAW | `.raw` | Supported by the Image Viewer app if named as `<name>_<w>x<h>_RGB565.raw` or `<name>_<w>x<h>_GRAY.raw`. |
+
+## Audio formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| Plain PCM WAV | `.wav` | Standard RIFF/WAVE with `WAVE_FORMAT_PCM` (0x0001) or `WAVE_FORMAT_EXTENSIBLE` (0xFFFE) and 16-bit samples. |
+| IMA ADPCM WAV | `.wav` | RIFF/WAVE with `WAVE_FORMAT_ADPCM` (0x0011), decoded by the built-in `adpcm_ima` module. Must have 4 or 16 bits per sample. |
+
+### JPEG conversion
+
+The built-in JPEG decoder only supports baseline JPEGs. The file extension is also treated case-sensitively, so `.JPG` or `.JPEG` will **not** be recognised.
+
+To convert an image to a supported baseline JPEG:
+
+```bash
+convert input.jpg -interlace none output.jpg
+```
+
+`input.jpg` can be any image format that ImageMagick supports (including PNG), and `-interlace none` forces a non-progressive JPEG.

mkdocs.yml

@@ -92,6 +92,7 @@ nav:
   - Other:
       - Release Process: other/release-checklist.md
       - Merge Checklist: other/merge-checklist.md
+      - Supported File Formats: other/supported-file-formats.md
 extra:
   social:
     - icon: fontawesome/brands/github