Develop

docs/api_reference/ui/ui_checkbox.md

@@ -0,0 +1,137 @@
+# UICheckBox
+
+A clickable checkbox UI element.
+
+## Description
+
+`UICheckBox` is a clickable checkbox that can be toggled between checked and unchecked states. It supports both physical (keyboard/gamepad) and touch input. It can trigger a callback function when its state changes and integrates with UI layouts for automatic navigation.
+
+## Namespace
+
+```cpp
+namespace pixelroot32::graphics::ui {
+    class UICheckBox : public UIElement {
+        // ...
+    };
+}
+```
+
+## Inheritance
+
+- Inherits from: `UIElement`
+
+## Constructors
+
+### UICheckBox(string label, uint8_t index, float x, float y, float w, float h, bool checked = false, function<void(bool)> callback = nullptr, int fontSize = 2)
+
+Constructs a new UICheckBox.
+
+**Parameters:**
+- `label` (std::string): Checkbox label text
+- `index` (uint8_t): Navigation index (for D-pad navigation in layouts)
+- `x` (float): X position
+- `y` (float): Y position
+- `w` (float): Width
+- `h` (float): Height
+- `checked` (bool, optional): Initial checked state. Default: `false`
+- `callback` (std::function<void(bool)>, optional): Function to call when the state changes. Default: `nullptr`
+- `fontSize` (int, optional): Text size multiplier. Default: `2`
+
+**Example:**
+```cpp
+#include "graphics/ui/UICheckBox.h"
+
+void onCheckChanged(bool checked) {
+    if (checked) {
+        // Sound enabled
+    } else {
+        // Sound disabled
+    }
+}
+
+// Create checkbox
+pixelroot32::graphics::ui::UICheckBox* soundCheckbox = new pixelroot32::graphics::ui::UICheckBox(
+    "Enable Sound",
+    0,  // index
+    64.0f, 64.0f,  // position
+    120.0f, 20.0f, // size
+    true,          // initial state
+    onCheckChanged,
+    1              // font size
+);
+```
+
+## Public Methods
+
+### void setStyle(Color textCol, Color bgCol, bool drawBg = false)
+
+Configures the checkbox's visual style.
+
+**Parameters:**
+- `textCol` (`Color`): Color of the text
+- `bgCol` (`Color`): Color of the background
+- `drawBg` (bool, optional): Whether to draw the background rectangle. Default: `false`
+
+**Returns:**
+- `void`
+
+### void setChecked(bool checked)
+
+Sets the checked state.
+
+**Parameters:**
+- `checked` (bool): True if checked
+
+**Returns:**
+- `void`
+
+### bool isChecked() const
+
+Checks if the checkbox is currently checked.
+
+**Returns:**
+- `bool`: `true` if checked
+
+### void toggle()
+
+Toggles the checkbox state and triggers the callback.
+
+**Returns:**
+- `void`
+
+### void setSelected(bool selected)
+
+Sets the selection state (e.g., focused via D-pad).
+
+**Parameters:**
+- `selected` (bool): True if selected
+
+**Returns:**
+- `void`
+
+### bool getSelected() const
+
+Checks if the checkbox is currently selected.
+
+**Returns:**
+- `bool`: `true` if selected
+
+## Callbacks
+
+### onCheckChanged
+
+The `onCheckChanged` callback is a `std::function<void(bool)>` that is triggered whenever the checkbox state changes via `setChecked()` or `toggle()`.
+
+```cpp
+checkbox->onCheckChanged = [](bool isChecked) {
+    Serial.println(isChecked ? "Checked!" : "Unchecked!");
+};
+```
+
+## Navigation & Layouts
+
+`UICheckBox` is designed to work seamlessly with `UILayout` containers (like `UIVerticalLayout`). 
+
+- **Focusable**: Returns `true` for `isFocusable()`, allowing it to receive focus in a layout.
+- **Input Handling**: When selected (focused), it listens for the button index provided in the constructor (typically the 'A' button) to toggle its state.
+- **Visual Feedback**: When selected, it displays a selection indicator (usually a `>` character) if no background is drawn, or highlights its text/border.

docs/api_reference/ui/ui_element.md

@@ -14,6 +14,7 @@ namespace pixelroot32::graphics::ui {
         GENERIC,
         BUTTON,
         LABEL,
+        CHECKBOX,
         LAYOUT
     };
 
@@ -26,7 +27,7 @@ namespace pixelroot32::graphics::ui {
 ## Inheritance
 
 - Inherits from: `pixelroot32::core::Entity`
-- Inherited by: `UIButton`, `UILabel`, `UIPanel`, and all UI layouts
+- Inherited by: `UIButton`, `UICheckBox`, `UILabel`, `UIPanel`, and all UI layouts
 
 ## Constructors
 
@@ -70,7 +71,7 @@ public:
 Returns the type of the UI element.
 
 **Returns:**
-- `UIElementType`: The type enum value (GENERIC, BUTTON, LABEL, or LAYOUT)
+- `UIElementType`: The type enum value (GENERIC, BUTTON, LABEL, CHECKBOX, or LAYOUT)
 
 ### virtual bool isFocusable() const
 

docs/api_reference/ui/ui_label.md

@@ -56,7 +56,7 @@ scene->addEntity(scoreLabel);
 
 ### void setText(const string& t)
 
-Updates the label's text. Recalculates dimensions if text changes.
+Updates the label's text. Recalculates dimensions immediately using the active font metrics to ensure precise layout.
 
 **Parameters:**
 - `t` (const std::string&): New text
@@ -65,7 +65,7 @@ Updates the label's text. Recalculates dimensions if text changes.
 - `void`
 
 **Notes:**
-- Automatically recalculates width and height
+- Automatically recalculates width and height using `FontManager::textWidth`
 - Use for dynamic text (scores, timers, etc.)
 - Text is stored as `std::string` (consider memory on ESP32)
 
@@ -99,21 +99,17 @@ label->setVisible(true);   // Show
 
 ### void centerX(int screenWidth)
 
-Centers the label horizontally on the screen.
+Centers the label horizontally within a given width (typically the screen width). Recalculates dimensions before positioning to ensure perfect centering.
 
 **Parameters:**
-- `screenWidth` (int): Width of the screen/container
+- `screenWidth` (int): The width to center within (e.g., `engine.getRenderer().getWidth()`)
 
 **Returns:**
 - `void`
 
-**Notes:**
-- Calculates center position based on label width
-- Useful for centered menu text
-
 **Example:**
 ```cpp
-label->centerX(128);  // Center on 128px wide screen
+label->centerX(128); // Center on a 128px screen
 ```
 
 ### void update(unsigned long deltaTime) override

docs/manual/game_development/user_interface.md

@@ -64,6 +64,40 @@ startButton->setStyle(
 addEntity(startButton);
 ```
 
+### UICheckBox
+
+Create interactive checkboxes:
+
+```cpp
+#include <graphics/ui/UICheckBox.h>
+
+// Create a checkbox
+pixelroot32::graphics::ui::UICheckBox* soundCheckbox = new pixelroot32::graphics::ui::UICheckBox(
+    "Enable Sound",                // text
+    4,                             // navigation index
+    50,                            // x position
+    140,                           // y position
+    140,                           // width
+    20,                            // height
+    true,                          // initial checked state
+    [](bool checked) {             // callback function
+        // Checkbox state changed
+        setSoundEnabled(checked);
+    },
+    1                              // font size
+);
+
+// Configure style
+soundCheckbox->setStyle(
+    pixelroot32::graphics::Color::White,   // text color
+    pixelroot32::graphics::Color::Blue,    // background color
+    false                                  // draw background
+);
+
+// Add to scene
+addEntity(soundCheckbox);
+```
+
 ### UIPanel
 
 Create visual containers with background and border:

mkdocs.yml

@@ -60,6 +60,7 @@ nav:
       - UI:
           - UIElement: api_reference/ui/ui_element.md
           - UIButton: api_reference/ui/ui_button.md
+          - UICheckBox: api_reference/ui/ui_checkbox.md
           - UILabel: api_reference/ui/ui_label.md
           - UI Layouts:
               - Vertical Layout: api_reference/ui/ui_layouts/vertical_layout.md