diff --git a/docs/api_reference/ui/ui_checkbox.md b/docs/api_reference/ui/ui_checkbox.md new file mode 100644 index 0000000..252d102 --- /dev/null +++ b/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 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, 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` 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. diff --git a/docs/api_reference/ui/ui_element.md b/docs/api_reference/ui/ui_element.md index ce0f04b..b9567df 100644 --- a/docs/api_reference/ui/ui_element.md +++ b/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 diff --git a/docs/api_reference/ui/ui_label.md b/docs/api_reference/ui/ui_label.md index 3912050..4a98c4b 100644 --- a/docs/api_reference/ui/ui_label.md +++ b/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 diff --git a/docs/manual/game_development/user_interface.md b/docs/manual/game_development/user_interface.md index 32c1e0c..55c733f 100644 --- a/docs/manual/game_development/user_interface.md +++ b/docs/manual/game_development/user_interface.md @@ -64,6 +64,40 @@ startButton->setStyle( addEntity(startButton); ``` +### UICheckBox + +Create interactive checkboxes: + +```cpp +#include + +// 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: diff --git a/mkdocs.yml b/mkdocs.yml index 3ff2ba8..e346aae 100644 --- a/mkdocs.yml +++ b/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