docs(examples): add get_started XML examples (#10151)

docs/src/getting_started/examples.mdx

@@ -10,16 +10,16 @@ was created and therefore has an [Active Screen](/common-widget-features/screens
 
 ### A very simple *hello world* label
 
-<LvglExample name="lv_example_get_started_1" path="get_started/lv_example_get_started_1" />
+<LvglExample name="lv_example_get_started_hello_world" path="get_started/get_started_hello_world/lv_example_get_started_hello_world" />
 
 ### A button with a label and react on click event
 
-<LvglExample name="lv_example_get_started_2" path="get_started/lv_example_get_started_2" />
+<LvglExample name="lv_example_get_started_button" path="get_started/lv_example_get_started_button" />
 
 ### Create styles from scratch for buttons
 
-<LvglExample name="lv_example_get_started_3" path="get_started/lv_example_get_started_3" />
+<LvglExample name="lv_example_get_started_styles" path="get_started/get_started_styles/lv_example_get_started_styles" />
 
 ### Create a slider and write its value on a label
 
-<LvglExample name="lv_example_get_started_4" path="get_started/lv_example_get_started_4" />
+<LvglExample name="lv_example_get_started_slider" path="get_started/get_started_slider/lv_example_get_started_slider" />

docs/src/getting_started/porting.mdx

@@ -12,11 +12,29 @@ A more detailed description is available at [Overview](/integration/overview).
 
 
 The main steps are the following:
-1. **Driver Initialization**:  It is the user's responsibility to set up the clock, timers, peripherals, etc.
-2. **Call <ApiLink name="lv_init" display="lv_init()" />**: Initialize LVGL itself.
-3. **Create display and input devices and set up the tick**:  Create display(s) (<ApiLink name="lv_display_t" />) and input device(s) (<ApiLink name="lv_indev_t" />) and set up their callbacks.
-4. **Create the UI**:  Call LVGL functions to create screens, widgets, styles, animations, events, etc.
-5. **Call <ApiLink name="lv_timer_handler" display="lv_timer_handler()" /> in a loop**: This handles all the LVGL-related tasks, such as refreshing display(s), reading input devices, firing events based on user input, running animations, and running user-created timers.
+<Steps>
+
+<Step>
+**Driver Initialization**:  It is the user's responsibility to set up the clock, timers, peripherals, etc.
+</Step>
+
+<Step>
+**Call <ApiLink name="lv_init" display="lv_init()" />**: Initialize LVGL itself.
+</Step>
+
+<Step>
+**Create display and input devices and set up the tick**:  Create display(s) (<ApiLink name="lv_display_t" />) and input device(s) (<ApiLink name="lv_indev_t" />) and set up their callbacks.
+</Step>
+
+<Step>
+**Create the UI**:  Call LVGL functions to create screens, widgets, styles, animations, events, etc.
+</Step>
+
+<Step>
+**Call <ApiLink name="lv_timer_handler" display="lv_timer_handler()" /> in a loop**: This handles all the LVGL-related tasks, such as refreshing display(s), reading input devices, firing events based on user input, running animations, and running user-created timers.
+</Step>
+
+</Steps>
 
 This is just a brief example of how to add LVGL to a new project.
 

examples/get_started/get_started_hello_world/lv_example_get_started_hello_world.c

@@ -0,0 +1,26 @@
+/**
+ * @file lv_example_get_started_hello_world.c
+ */
+
+#include "../../lv_examples.h"
+#if LV_BUILD_EXAMPLES
+
+/**
+ * @title Hello world label
+ * @brief Paint the screen background and center a label on it.
+ *
+ * The view sets its own `style_bg_color` to a dark teal and `style_text_color`
+ * to white. The label sets no color of its own — it inherits white from the
+ * view — and `align="center"` places it in the middle of the display.
+ */
+void lv_example_get_started_hello_world(void)
+{
+    lv_obj_t * screen = lv_screen_active();
+    lv_obj_set_style_bg_color(screen, lv_color_hex(0x003a57), 0);
+    lv_obj_set_style_text_color(screen, lv_color_hex(0xffffff), 0);
+
+    lv_obj_t * label = lv_label_create(screen);
+    lv_obj_set_align(label, LV_ALIGN_CENTER);
+    lv_label_set_text(label, "Hello world");
+}
+#endif

examples/get_started/get_started_hello_world/lv_example_get_started_hello_world.xml

@@ -0,0 +1,13 @@
+<!--
+ @title Hello world label
+ @brief Paint the screen background and center a label on it.
+
+ The view sets its own `style_bg_color` to a dark teal and `style_text_color`
+ to white. The label sets no color of its own — it inherits white from the
+ view — and `align="center"` places it in the middle of the display.
+-->
+<screen>
+	<view style_bg_color="0x003a57" style_text_color="0xffffff">
+		<lv_label name="label" align="center" text="Hello world" />
+	</view>
+</screen>

examples/get_started/get_started_slider/lv_example_get_started_slider.c

@@ -0,0 +1,44 @@
+/**
+ * @file lv_example_get_started_slider.c
+ */
+
+#include "../../lv_examples.h"
+#if LV_BUILD_EXAMPLES
+
+/**
+ * @title Slider with live value
+ * @brief Mirror a slider's value into a label through a shared subject.
+ *
+ * The slider writes its position to `subject_value` with `bind_value`, and the
+ * label reads the same subject with `bind_text` + `bind_text-fmt="%d"`. Because
+ * both refer to one subject, dragging the slider updates the label with no event
+ * callback — the binding keeps the two in sync.
+ */
+void lv_example_get_started_slider(void)
+{
+    static lv_subject_t subject_value;
+
+    static bool inited = false;
+
+    if(!inited) {
+        lv_subject_init_int(&subject_value, 50);
+        lv_subject_set_min_value_int(&subject_value, 0);
+        lv_subject_set_max_value_int(&subject_value, 100);
+        inited = true;
+    }
+
+    lv_obj_t * screen = lv_screen_active();
+
+    /* 💡 Drag the slider; the label tracks it because both share `subject_value`. */
+    lv_obj_t * label = lv_label_create(screen);
+    lv_obj_set_align(label, LV_ALIGN_CENTER);
+    lv_obj_set_y(label, -20);
+    lv_label_bind_text(label, &subject_value, "%d");
+
+    lv_obj_t * slider = lv_slider_create(screen);
+    lv_obj_set_align(slider, LV_ALIGN_CENTER);
+    lv_obj_set_y(slider, 20);
+    lv_obj_set_width(slider, lv_pct(90));
+    lv_slider_bind_value(slider, &subject_value);
+}
+#endif

examples/get_started/get_started_slider/lv_example_get_started_slider.xml

@@ -0,0 +1,16 @@
+<!--
+ @title Slider with live value
+ @brief Mirror a slider's value into a label through a shared subject.
+
+ The slider writes its position to `subject_value` with `bind_value`, and the
+ label reads the same subject with `bind_text` + `bind_text-fmt="%d"`. Because
+ both refer to one subject, dragging the slider updates the label with no event
+ callback — the binding keeps the two in sync.
+-->
+<screen>
+	<view>
+		<!-- 💡 Drag the slider; the label tracks it because both share `subject_value`. -->
+		<lv_label name="label" align="center" y="-20" bind_text="subject_value" bind_text-fmt="%d" />
+		<lv_slider name="slider" align="center" y="20" width="90%" bind_value="subject_value" />
+	</view>
+</screen>

examples/get_started/get_started_styles/lv_example_get_started_styles.c

@@ -0,0 +1,75 @@
+/**
+ * @file lv_example_get_started_styles.c
+ */
+
+#include "../../lv_examples.h"
+#if LV_BUILD_EXAMPLES
+
+/**
+ * @title Styles from scratch for buttons
+ * @brief Build named button styles, then add a pressed state and an accent variant.
+ *
+ * `style_button` is the shared base: a rounded vertical grey gradient with a thin
+ * translucent border. The first button adds `style_button_pressed` on the
+ * `pressed` selector so its gradient darkens while held. The second stacks
+ * `style_button_red` to repaint only the gradient and sets a local circular
+ * radius, showing how a small style plus one local property re-skins a button
+ * without redefining the base.
+ */
+void lv_example_get_started_styles(void)
+{
+    static lv_style_t style_button;
+    static lv_style_t style_button_pressed;
+    static lv_style_t style_button_red;
+
+    static bool inited = false;
+
+    if(!inited) {
+        lv_style_init(&style_button);
+        lv_style_set_radius(&style_button, 10);
+        lv_style_set_bg_opa(&style_button, (255 * 100 / 100));
+        lv_style_set_bg_color(&style_button, lv_color_hex(0xeeeeee));
+        lv_style_set_bg_grad_color(&style_button, lv_color_hex(0x9e9e9e));
+        lv_style_set_bg_grad_dir(&style_button, LV_GRAD_DIR_VER);
+        lv_style_set_border_color(&style_button, lv_color_hex(0x000000));
+        lv_style_set_border_opa(&style_button, (255 * 20 / 100));
+        lv_style_set_border_width(&style_button, 2);
+        lv_style_set_text_color(&style_button, lv_color_hex(0x000000));
+
+        lv_style_init(&style_button_pressed);
+        lv_style_set_bg_color(&style_button_pressed, lv_color_hex(0xbdbdbd));
+        lv_style_set_bg_grad_color(&style_button_pressed, lv_color_hex(0x757575));
+
+        lv_style_init(&style_button_red);
+        lv_style_set_bg_color(&style_button_red, lv_color_hex(0xf44336));
+        lv_style_set_bg_grad_color(&style_button_red, lv_color_hex(0xffcdd2));
+
+        inited = true;
+    }
+
+    lv_obj_t * screen = lv_screen_active();
+
+    /* Base style + a pressed-state override */
+    lv_obj_t * button_1 = lv_button_create(screen);
+    lv_obj_set_align(button_1, LV_ALIGN_CENTER);
+    lv_obj_set_y(button_1, -35);
+    lv_obj_set_size(button_1, 120, 50);
+    lv_obj_add_style(button_1, &style_button, 0);
+    lv_obj_add_style(button_1, &style_button_pressed, LV_STATE_PRESSED);
+    lv_obj_t * label_1 = lv_label_create(button_1);
+    lv_obj_set_align(label_1, LV_ALIGN_CENTER);
+    lv_label_set_text(label_1, "Button");
+
+    /* Base + accent variant + a local circular radius */
+    lv_obj_t * button_2 = lv_button_create(screen);
+    lv_obj_set_align(button_2, LV_ALIGN_CENTER);
+    lv_obj_set_y(button_2, 35);
+    lv_obj_set_size(button_2, 120, 50);
+    lv_obj_set_style_radius(button_2, 25, 0);
+    lv_obj_add_style(button_2, &style_button, 0);
+    lv_obj_add_style(button_2, &style_button_red, 0);
+    lv_obj_t * label_2 = lv_label_create(button_2);
+    lv_obj_set_align(label_2, LV_ALIGN_CENTER);
+    lv_label_set_text(label_2, "Button 2");
+}
+#endif

examples/get_started/get_started_styles/lv_example_get_started_styles.xml

@@ -0,0 +1,51 @@
+<!--
+ @title Styles from scratch for buttons
+ @brief Build named button styles, then add a pressed state and an accent variant.
+
+ `style_button` is the shared base: a rounded vertical grey gradient with a thin
+ translucent border. The first button adds `style_button_pressed` on the
+ `pressed` selector so its gradient darkens while held. The second stacks
+ `style_button_red` to repaint only the gradient and sets a local circular
+ radius, showing how a small style plus one local property re-skins a button
+ without redefining the base.
+-->
+<screen>
+	<styles>
+		<!-- Shared base look: rounded grey vertical gradient with a thin border -->
+		<style name="style_button"
+			radius="10"
+			bg_opa="100%"
+			bg_color="0xeeeeee"
+			bg_grad_color="0x9e9e9e"
+			bg_grad_dir="ver"
+			border_color="0x000000"
+			border_opa="20%"
+			border_width="2"
+			text_color="0x000000" />
+		<!-- Pressed state: darker gradient stops -->
+		<style name="style_button_pressed"
+			bg_color="0xbdbdbd"
+			bg_grad_color="0x757575" />
+		<!-- Accent variant: repaint only the gradient red -->
+		<style name="style_button_red"
+			bg_color="0xf44336"
+			bg_grad_color="0xffcdd2" />
+	</styles>
+
+	<view>
+		<!-- 💡 Hold the first button to see `style_button_pressed` darken its gradient. -->
+		<!-- Base style + a pressed-state override -->
+		<lv_button name="button_1" align="center" y="-35" width="120" height="50">
+			<style name="style_button" />
+			<style name="style_button_pressed" selector="pressed" />
+			<lv_label name="label_1" align="center" text="Button" />
+		</lv_button>
+
+		<!-- Base + accent variant + a local circular radius -->
+		<lv_button name="button_2" align="center" y="35" width="120" height="50" style_radius="25">
+			<style name="style_button" />
+			<style name="style_button_red" />
+			<lv_label name="label_2" align="center" text="Button 2" />
+		</lv_button>
+	</view>
+</screen>

examples/get_started/lv_example_get_started.h

@@ -25,10 +25,10 @@ extern "C" {
 /**********************
  * GLOBAL PROTOTYPES
  **********************/
-void lv_example_get_started_1(void);
-void lv_example_get_started_2(void);
-void lv_example_get_started_3(void);
-void lv_example_get_started_4(void);
+void lv_example_get_started_button(void);
+void lv_example_get_started_hello_world(void);
+void lv_example_get_started_slider(void);
+void lv_example_get_started_styles(void);
 
 /**********************
  *      MACROS
@@ -39,3 +39,4 @@ void lv_example_get_started_4(void);
 #endif
 
 #endif /*LV_EXAMPLE_GET_STARTED_H*/
+

examples/get_started/lv_example_get_started_1.c

@@ -1,24 +0,0 @@
-#include "../lv_examples.h"
-#if LV_BUILD_EXAMPLES && LV_USE_LABEL
-
-/**
- * @title Hello world label
- * @brief Set the screen background color and place a centered label.
- *
- * Sets the active screen's background color, creates a label with the text
- * `Hello world`, sets the screen's text color to white, and centers the
- * label on the screen.
- */
-void lv_example_get_started_1(void)
-{
-    /*Change the active screen's background color*/
-    lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
-
-    /*Create a white label, set its text and align it to the center*/
-    lv_obj_t * label = lv_label_create(lv_screen_active());
-    lv_label_set_text(label, "Hello world");
-    lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
-    lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
-}
-
-#endif

examples/get_started/lv_example_get_started_3.c

@@ -1,92 +0,0 @@
-#include "../lv_examples.h"
-#if LV_USE_BUTTON && LV_BUILD_EXAMPLES
-
-static lv_style_t style_btn;
-static lv_style_t style_button_pressed;
-static lv_style_t style_button_red;
-
-static lv_color_t darken(const lv_color_filter_dsc_t * dsc, lv_color_t color, lv_opa_t opa)
-{
-    LV_UNUSED(dsc);
-    return lv_color_darken(color, opa);
-}
-
-static void style_init(void)
-{
-    /*Create a simple button style*/
-    lv_style_init(&style_btn);
-    lv_style_set_radius(&style_btn, 10);
-    lv_style_set_bg_opa(&style_btn, LV_OPA_COVER);
-    lv_style_set_bg_color(&style_btn, lv_palette_lighten(LV_PALETTE_GREY, 3));
-    lv_style_set_bg_grad_color(&style_btn, lv_palette_main(LV_PALETTE_GREY));
-    lv_style_set_bg_grad_dir(&style_btn, LV_GRAD_DIR_VER);
-
-    lv_style_set_border_color(&style_btn, lv_color_black());
-    lv_style_set_border_opa(&style_btn, LV_OPA_20);
-    lv_style_set_border_width(&style_btn, 2);
-
-    lv_style_set_text_color(&style_btn, lv_color_black());
-
-    /*Create a style for the pressed state.
-     *Use a color filter to simply modify all colors in this state*/
-    static lv_color_filter_dsc_t color_filter;
-    lv_color_filter_dsc_init(&color_filter, darken);
-    lv_style_init(&style_button_pressed);
-    lv_style_set_color_filter_dsc(&style_button_pressed, &color_filter);
-    lv_style_set_color_filter_opa(&style_button_pressed, LV_OPA_20);
-
-    /*Create a red style. Change only some colors.*/
-    lv_style_init(&style_button_red);
-    lv_style_set_bg_color(&style_button_red, lv_palette_main(LV_PALETTE_RED));
-    lv_style_set_bg_grad_color(&style_button_red, lv_palette_lighten(LV_PALETTE_RED, 3));
-}
-
-/**
- * @title Styles from scratch for buttons
- * @brief Build reusable button styles and apply them with a pressed-state override.
- *
- * Three `lv_style_t` objects are initialized: a base grey gradient style with
- * rounded corners and a thin border, a pressed style that applies a darken
- * color filter at `LV_OPA_20`, and a red style that overrides only the
- * background colors. Two buttons strip their theme styles with
- * `lv_obj_remove_style_all`, adopt the base style for the default state and
- * the pressed style for `LV_STATE_PRESSED`; the second also stacks the red
- * style and sets a local `LV_RADIUS_CIRCLE` radius.
- */
-void lv_example_get_started_3(void)
-{
-    /*Initialize the style*/
-    style_init();
-
-    /*Create a button and use the new styles*/
-    lv_obj_t * btn = lv_button_create(lv_screen_active());
-    /* Remove the styles coming from the theme
-     * Note that size and position are also stored as style properties
-     * so lv_obj_remove_style_all will remove the set size and position too */
-    lv_obj_remove_style_all(btn);
-    lv_obj_set_pos(btn, 10, 10);
-    lv_obj_set_size(btn, 120, 50);
-    lv_obj_add_style(btn, &style_btn, 0);
-    lv_obj_add_style(btn, &style_button_pressed, LV_STATE_PRESSED);
-
-    /*Add a label to the button*/
-    lv_obj_t * label = lv_label_create(btn);
-    lv_label_set_text(label, "Button");
-    lv_obj_center(label);
-
-    /*Create another button and use the red style too*/
-    lv_obj_t * btn2 = lv_button_create(lv_screen_active());
-    lv_obj_remove_style_all(btn2);                      /*Remove the styles coming from the theme*/
-    lv_obj_set_pos(btn2, 10, 80);
-    lv_obj_set_size(btn2, 120, 50);
-    lv_obj_add_style(btn2, &style_btn, 0);
-    lv_obj_add_style(btn2, &style_button_red, 0);
-    lv_obj_add_style(btn2, &style_button_pressed, LV_STATE_PRESSED);
-    lv_obj_set_style_radius(btn2, LV_RADIUS_CIRCLE, 0); /*Add a local style too*/
-
-    label = lv_label_create(btn2);
-    lv_label_set_text(label, "Button 2");
-    lv_obj_center(label);
-}
-
-#endif

examples/get_started/lv_example_get_started_4.c

@@ -1,38 +0,0 @@
-#include "../lv_examples.h"
-#if LV_BUILD_EXAMPLES && LV_USE_SLIDER
-
-static lv_obj_t * label;
-
-static void slider_event_cb(lv_event_t * e)
-{
-    lv_obj_t * slider = lv_event_get_target_obj(e);
-
-    /*Refresh the text*/
-    lv_label_set_text_fmt(label, "%" LV_PRId32, lv_slider_get_value(slider));
-    lv_obj_align_to(label, slider, LV_ALIGN_OUT_TOP_MID, 0, -15);    /*Align top of the slider*/
-}
-
-/**
- * @title Slider with live value label
- * @brief Mirror a slider's value into a label anchored above it.
- *
- * A 200 px wide slider is centered on the active screen with a label placed
- * 15 px above it via `lv_obj_align_to` and `LV_ALIGN_OUT_TOP_MID`. An
- * `LV_EVENT_VALUE_CHANGED` callback reads `lv_slider_get_value` and rewrites
- * the label text, re-aligning it after each update.
- */
-void lv_example_get_started_4(void)
-{
-    /*Create a slider in the center of the display*/
-    lv_obj_t * slider = lv_slider_create(lv_screen_active());
-    lv_obj_set_width(slider, 200);                          /*Set the width*/
-    lv_obj_center(slider);                                  /*Align to the center of the parent (screen)*/
-    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);     /*Assign an event function*/
-
-    /*Create a label above the slider*/
-    label = lv_label_create(lv_screen_active());
-    lv_label_set_text(label, "0");
-    lv_obj_align_to(label, slider, LV_ALIGN_OUT_TOP_MID, 0, -15);    /*Align top of the slider*/
-}
-
-#endif

examples/get_started/lv_example_get_started_button.c

@@ -24,7 +24,7 @@ static void btn_event_cb(lv_event_t * e)
  * `LV_EVENT_ALL` and on `LV_EVENT_CLICKED` the callback updates its child
  * label with `lv_label_set_text_fmt` to show an incrementing counter.
  */
-void lv_example_get_started_2(void)
+void lv_example_get_started_button(void)
 {
     lv_obj_t * btn = lv_button_create(lv_screen_active());     /*Add a button the current screen*/
     lv_obj_set_pos(btn, 10, 10);                            /*Set its position*/

examples/lv_examples_api_map.h

@@ -36,6 +36,12 @@ extern "C" {
  *      MACROS
  **********************/
 
+/* get_started */
+#define lv_example_get_started_1       lv_example_get_started_hello_world
+#define lv_example_get_started_2       lv_example_get_started_button
+#define lv_example_get_started_3       lv_example_get_started_slider
+#define lv_example_get_started_4       lv_example_get_started_styles
+
 /* animimg */
 #define lv_example_animimg_1       lv_example_animimg_play
 

scripts/generate_examples.py

@@ -52,8 +52,10 @@ ROOT_METADATA = {"project.xml", "globals.xml"}
 # widget in, so these examples get gated on `LV_BUILD_EXAMPLES` alone —
 # emitting `LV_USE_STYLES` / `LV_USE_SCROLL` / `LV_USE_OBJ` (undefined)
 # would make the `#if` false and silently drop every example in those
-# folders.
-TOPICS_WITHOUT_LV_USE = {"scroll", "styles", "obj"}
+# folders. `get_started` is a mixed-widget intro topic with no single
+# `LV_USE_GET_STARTED` macro, so it gets the same `LV_BUILD_EXAMPLES`-only
+# treatment.
+TOPICS_WITHOUT_LV_USE = {"scroll", "styles", "obj", "get_started"}
 
 # Categories that group several independent topics, each with its own
 # `LV_USE_<TOPIC>` macro and `lv_example_<topic>.h` header. For these the