diff --git a/Widgets.md b/Widgets.md index 7e2c516..d5ea88d 100644 --- a/Widgets.md +++ b/Widgets.md @@ -1,17 +1,20 @@ -## About +## About Widgets -Widgets are the elements that compose the UI of your custom app. Widgets are defined inside [`firmware\common\ui_widget.hpp`](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.hpp) and widget functions can be found inside [`firmware\common\ui_widget.cpp`](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.cpp). In order to be able to use them, you must `#include "ui_widget.hpp"` into your app .hpp file. -There are different type of widget. here you will find a list of available widget, with their respecting constructor. For all the methods available, you should go and see the [ui_widget.hpp](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.hpp) file. +Widgets are elements to compose the UI of your custom app. Widgets are defined in [`firmware\common\ui_widget.hpp`](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.hpp) and widget functions can be found in [`firmware\common\ui_widget.cpp`](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.cpp). To use them, you must add the line `#include "ui_widget.hpp"` into your app .hpp file. +There are different types of widgets. Here you will find a list of available widgets, with their constructor. For all methods available, you should check the [ui_widget.hpp](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.hpp) file. -## Attach a Generic Widget to Your Application -In order to display a widget into your app, you can either use the function `add_child()` or `add_children()`. -Both those functions shall be called within the code of your `NewAppGameView(NavigationView &nav){}` constructor. The difference between the two function is simple: the first one allows you to add a single widget, while the second one allows you to add an undefined number of widgets. -Widgets must be passed as pointers to the functions. A correct way of calling the two functions would then be: +## Attach a generic Widget to your Application + +To display a widget in your app, you can use the functions `add_child()` for a single widget or `add_children()` to add an undefined number of widgets. +Both functions shall be called within the code of the `NewAppGameView(NavigationView &nav){}` constructor. +Widgets must be passed as pointers to the functions. + +**Declaration and prototype** ``` add_child(&my_widget); ``` -or +or ``` add_children({ &widget_1, @@ -20,10 +23,17 @@ add_children({ ``` ## Available widgets -There are several different widgets, and more might be added, so you should always go and check whether new widgets have been added or not. Here you will find a list of most basic widgets. +There are several widgets available and more might be added. You should always check [ui_widget.hpp](https://github.com/portapack-mayhem/mayhem-firmware/blob/next/firmware/common/ui_widget.hpp) if new widgets have been added. +In this document you will find a list of most basic widgets. + + +*** ### Text -The text widgets add a simple text area to your app. Here you can find it's declaration and prototype: + +The text widget add a simple text area widget in the app. + +**Declaration and prototype** ``` Text my_text_widget{ Rect parent_rect, @@ -31,25 +41,33 @@ Text my_text_widget{ }; ``` -To be noted that `Rect parent_rect` has it's own definition inside another file, but let's say that you would like to add a text widget with the text "Hello World", positioned at the top left corner (spaced 10 from both top margin and left margin), with width 100 and height 24, you cold do it in this way: +**Note:** `Rect parent_rect` has it's own definition inside another file. + +**Example** +Add a text widget with the content "Hello World" positioned at 10x10 px from the top left corner with width 100 and height 24. ``` Text hello_world_text_widget( {10, 10, 100, 24}, // Coordinates are: int:x (px), int:y (px), int:width (px), int:height (px) "Hello world!" ); ``` + +*** ### Button -Buttons allows you to do something when you press them. Here you can find it's declaration and prototype: +Buttons allows to do something when you press it. + +**Declaration and prototype** ``` Button my_button_widget{ Rect parent_rect, std::string text }; ``` -Be aware that every time you create a button, you then have to implement this method: `my_button_widget.on_select = [&nav](Button &){}`. You can leave it empty (even though it should not, as here you define what action the button should perform), but it must be present in your code. +**Note:** Every time you create a button, you have to implement the method `my_button_widget.on_select = [&nav](Button &){}`. It could be empty (even though it shouldn't, as here you define the action for a button), but it must be present in the code. -For example, let's say you want a button called `my_button`, with the same dimensions as the previous widget. You will then do: +**Example** +A button called `my_button`, with the same dimensions as the previous widget. ``` Button my_button( {10, 10, 100, 24}, // Coordinates are: int:x (px), int:y (px), int:width (px), int:height (px) @@ -57,16 +75,21 @@ Button my_button( ); ``` +*** ### Labels -Labels are a text element that can be used to describe other widgets. Here you can find it's declaration and prototype: +Labels are a text element that can be used to describe other widgets. + +**Declaration and prototype** ``` Labels my_label_widget{ std::initializer_list