arch(win): deprecate and add a flex-column window example

Deprecate the lv_win widget. A window is just a flex column with a header bar and
a content area, so it can be built directly from lv_obj.

Following the deprecation guidelines:
- @deprecated Doxygen tags and LV_DEPRECATED on lv_win_create
- LV_LOG_DEPRECATED runtime warning in lv_win_create
- migration-v10.mdx entry pointing to the replacement
- the new lv_example_flex_win shows how to build one from base widgets

Live call sites in the kept examples, demos and tests are wrapped with
LV_DEPRECATIONS_IGNORE_BEGIN/END so the -Wdeprecated -Werror build stays clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/src/changelog/migration-v10.mdx

@@ -448,6 +448,13 @@ if you need finer control.
   [`lv_example_flex_list`](common-widget-features/layouts/flex#building-a-list)
   example for a starting point.
 
+### lv_win
+
+- The `lv_win` widget is deprecated. A window is just a flex column with a header
+  bar and a content area, so build one directly from `lv_obj` instead. See the
+  [`lv_example_flex_win`](common-widget-features/layouts/flex#building-a-window)
+  example for a starting point.
+
 ---
 
 ## Drawing

docs/src/common-widget-features/layouts/flex.mdx

@@ -170,6 +170,15 @@ placed from right to left.
 
 You can easily build a list using a column flex with 100% wide buttons and text.
 
+## Building a window
+
+<LvglExample name="lv_example_flex_win" path="layouts/flex/lv_example_flex_win" />
+
+A window is a column flex too: a fixed-height header row on top and a content area
+below that grows to fill the rest with
+<ApiLink name="lv_obj_set_flex_grow" display="lv_obj_set_flex_grow(content, 1)" />.
+The title label grows so the header buttons are pushed to the right edge.
+
 ## Forcing a New Track
 
 <LvglExample name="lv_example_flex_new_track" path="layouts/flex/lv_example_flex_new_track" />

docs/src/widgets/win.mdx

@@ -5,6 +5,14 @@ description: "A header (like a title bar) with a title and buttons, plus a conte
 
 ## Overview
 
+<Callout type="warning" title="Deprecated">
+The `lv_win` widget is deprecated and kept only for backward compatibility. A
+window is just a flex column with a header bar and a content area, so build one
+directly from `lv_obj` instead. See the
+[`lv_example_flex_win`](/common-widget-features/layouts/flex#building-a-window)
+example for a starting point.
+</Callout>
+
 The Window widget is built from a header (like a title bar) with a title
 and optional buttons, plus a content area below.
 

examples/layouts/flex/lv_example_flex.h

@@ -18,6 +18,7 @@ void lv_example_flex_internal_padding(void);
 void lv_example_flex_list(void);
 void lv_example_flex_new_track(void);
 void lv_example_flex_rtl(void);
+void lv_example_flex_win(void);
 
 #ifdef __cplusplus
 } /*extern "C"*/

examples/layouts/flex/lv_example_flex_win.c

@@ -0,0 +1,172 @@
+/**
+ * @file lv_example_flex_win.c
+ */
+
+#include "../../lv_examples.h"
+#if LV_USE_FLEX && LV_BUILD_EXAMPLES
+
+/*A window is a flex column with a header bar on top and a content area below. The
+ *static helpers below build one on top of base widgets.
+ *
+ *The widgets are styled by hand to give the window its look: a flat background, a
+ *grey header bar and a screen-coloured content area.*/
+
+static lv_style_t style_win;
+static lv_style_t style_header;
+static lv_style_t style_content;
+
+/**
+ * Set up the styles that give the window its look.
+ *
+ * The styles are static and stay attached to the widgets that use them, so they are
+ * initialized only once even if the example is created multiple times.
+ */
+static void styles_init(void)
+{
+    static bool inited = false;
+    if(inited) return;
+    inited = true;
+
+    /*Window background: a flat, edge-to-edge column with the base object's card
+     *flattened away (no padding, border or radius).*/
+    lv_style_init(&style_win);
+    lv_style_set_pad_all(&style_win, 0);
+    lv_style_set_pad_gap(&style_win, 0);
+    lv_style_set_border_width(&style_win, 0);
+    lv_style_set_radius(&style_win, 0);
+
+    /*Title bar: a grey header with tight padding.*/
+    lv_style_init(&style_header);
+    lv_style_set_bg_opa(&style_header, LV_OPA_COVER);
+    lv_style_set_bg_color(&style_header, lv_palette_lighten(LV_PALETTE_GREY, 2));
+    lv_style_set_text_color(&style_header, lv_palette_darken(LV_PALETTE_GREY, 4));
+    lv_style_set_pad_all(&style_header, 2);
+    lv_style_set_pad_gap(&style_header, 2);
+    lv_style_set_border_width(&style_header, 0);
+    lv_style_set_radius(&style_header, 0);
+
+    /*Content area: a screen-coloured body with normal padding.*/
+    lv_style_init(&style_content);
+    lv_style_set_bg_opa(&style_content, LV_OPA_COVER);
+    lv_style_set_bg_color(&style_content, lv_palette_lighten(LV_PALETTE_GREY, 4));
+    lv_style_set_pad_all(&style_content, 16);
+    lv_style_set_border_width(&style_content, 0);
+    lv_style_set_radius(&style_content, 0);
+}
+
+/**
+ * Create a window: a flex column holding a header bar and a content area.
+ */
+static lv_obj_t * win_create(lv_obj_t * parent)
+{
+    lv_obj_t * win = lv_obj_create(parent);
+    lv_obj_set_size(win, lv_obj_get_width(parent), lv_obj_get_height(parent));
+    lv_obj_set_flex_flow(win, LV_FLEX_FLOW_COLUMN);
+    lv_obj_add_style(win, &style_win, 0);
+
+    lv_obj_t * header = lv_obj_create(win);
+    lv_obj_set_size(header, lv_pct(100), lv_display_get_dpi(lv_obj_get_display(win)) / 2);
+    lv_obj_set_flex_flow(header, LV_FLEX_FLOW_ROW);
+    lv_obj_set_flex_align(header, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_CENTER);
+    lv_obj_add_style(header, &style_header, 0);
+
+    lv_obj_t * content = lv_obj_create(win);
+    lv_obj_set_width(content, lv_pct(100));
+    lv_obj_set_flex_grow(content, 1);
+    lv_obj_add_style(content, &style_content, 0);
+
+    return win;
+}
+
+static lv_obj_t * win_get_header(lv_obj_t * win)
+{
+    return lv_obj_get_child(win, 0);
+}
+
+static lv_obj_t * win_get_content(lv_obj_t * win)
+{
+    return lv_obj_get_child(win, 1);
+}
+
+/**
+ * Add a title label that takes the free space in the header.
+ */
+static lv_obj_t * win_add_title(lv_obj_t * win, const char * txt)
+{
+    lv_obj_t * title = lv_label_create(win_get_header(win));
+    lv_label_set_long_mode(title, LV_LABEL_LONG_MODE_DOTS);
+    lv_label_set_text(title, txt);
+    lv_obj_set_flex_grow(title, 1);
+    return title;
+}
+
+/**
+ * Add a fixed-width header button with an optional centered icon.
+ */
+static lv_obj_t * win_add_button(lv_obj_t * win, const void * icon, int32_t btn_w)
+{
+    lv_obj_t * btn = lv_button_create(win_get_header(win));
+    lv_obj_set_size(btn, btn_w, lv_pct(100));
+
+#if LV_USE_IMAGE == 1
+    if(icon) {
+        lv_obj_t * img = lv_image_create(btn);
+        lv_image_set_src(img, icon);
+        lv_obj_align(img, LV_ALIGN_CENTER, 0, 0);
+    }
+#endif
+
+    return btn;
+}
+
+static void event_handler(lv_event_t * e)
+{
+    lv_obj_t * obj = lv_event_get_target_obj(e);
+    LV_LOG_USER("Button %d clicked", (int)lv_obj_get_index(obj));
+}
+
+/**
+ * @title Window built from a flex container
+ * @brief Build a window from a flex column.
+ *
+ * The static `win_*` helpers build the window from base widgets: a
+ * `LV_FLEX_FLOW_COLUMN` container with a fixed-height `LV_FLEX_FLOW_ROW` header bar
+ * and a `lv_obj_set_flex_grow` content area below. The title uses
+ * `lv_obj_set_flex_grow` to push the buttons to the right, and the content holds a
+ * long label so the body scrolls.
+ */
+void lv_example_flex_win(void)
+{
+    styles_init();
+
+    lv_obj_t * win = win_create(lv_screen_active());
+    lv_obj_t * btn;
+    btn = win_add_button(win, LV_SYMBOL_LEFT, 40);
+    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);
+
+    win_add_title(win, "A title");
+
+    btn = win_add_button(win, LV_SYMBOL_RIGHT, 40);
+    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);
+
+    btn = win_add_button(win, LV_SYMBOL_CLOSE, 60);
+    lv_obj_add_event_cb(btn, event_handler, LV_EVENT_CLICKED, NULL);
+
+    lv_obj_t * content = win_get_content(win);  /*Content can be added here*/
+    lv_obj_t * label = lv_label_create(content);
+    lv_label_set_text(label, "This is\n"
+                      "a pretty\n"
+                      "long text\n"
+                      "to see how\n"
+                      "the window\n"
+                      "becomes\n"
+                      "scrollable.\n"
+                      "\n"
+                      "\n"
+                      "Some more\n"
+                      "text to be\n"
+                      "sure it\n"
+                      "overflows. :)");
+}
+
+#endif

examples/others/observer/lv_example_observer_5.c

@@ -1,6 +1,9 @@
 #include "../../lv_examples.h"
 #if LV_USE_OBSERVER && LV_USE_ARC && LV_USE_LABEL && LV_USE_BUTTON && LV_USE_SPINNER && LV_BUILD_EXAMPLES
 
+/*The UI is built from the deprecated `lv_win` widget.*/
+LV_DEPRECATIONS_IGNORE_BEGIN
+
 typedef enum {
     FW_UPDATE_STATE_IDLE,
     FW_UPDATE_STATE_CONNECTING,
@@ -171,4 +174,6 @@ static void fw_upload_manager_observer_cb(lv_observer_t * observer, lv_subject_t
     }
 }
 
+LV_DEPRECATIONS_IGNORE_END
+
 #endif

examples/widgets/win/lv_example_win_toolbar.c

@@ -1,6 +1,9 @@
 #include "../../lv_examples.h"
 #if LV_USE_WIN && LV_BUILD_EXAMPLES
 
+/*This example shows the deprecated `lv_win` widget on purpose.*/
+LV_DEPRECATIONS_IGNORE_BEGIN
+
 static void event_handler(lv_event_t * e)
 {
     lv_obj_t * obj = lv_event_get_target_obj(e);
@@ -12,6 +15,9 @@ static void event_handler(lv_event_t * e)
  * @title Window with title and toolbar buttons
  * @brief A window whose header carries three symbol buttons over a scrollable label body.
  *
+ * @deprecated The `lv_win` widget is deprecated. See `lv_example_flex_win` for the
+ * recommended way to build a window from a flex container.
+ *
  * `lv_win_create` fills the active screen and `lv_win_add_button`
  * places a 40 px `LV_SYMBOL_LEFT`, a 40 px `LV_SYMBOL_RIGHT`, and a
  * 60 px `LV_SYMBOL_CLOSE` button on the header around a
@@ -52,4 +58,6 @@ void lv_example_win_toolbar(void)
                       "overflows. :)");
 }
 
+LV_DEPRECATIONS_IGNORE_END
+
 #endif

include/lvgl/widgets/lv_win.h

@@ -20,6 +20,15 @@ extern "C" {
  *      DEFINES
  *********************/
 
+/**
+ * @deprecated The `lv_win` widget is deprecated and kept only for backward
+ * compatibility. A window is just a flex column with a header bar and a content
+ * area, so build one directly from `lv_obj` instead. See the `lv_example_flex_win`
+ * example for a starting point.
+ */
+#define LV_WIN_DEPRECATED_MSG \
+    "lv_win is deprecated; build a window from a flex column instead. See the lv_example_flex_win example."
+
 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_win_class;
 
 /**********************
@@ -30,7 +39,9 @@ LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_win_class;
  * Create a window widget
  * @param parent    pointer to a parent widget
  * @return          the created window
+ * @deprecated Use a flex column with a header and content area instead. See `lv_example_flex_win`.
  */
+LV_DEPRECATED(LV_WIN_DEPRECATED_MSG)
 lv_obj_t * lv_win_create(lv_obj_t * parent);
 
 /**
@@ -38,7 +49,9 @@ lv_obj_t * lv_win_create(lv_obj_t * parent);
  * @param obj       pointer to a window widget
  * @param txt       the text of the title
  * @return          the widget where the content of the title can be created
+ * @deprecated The `lv_win` widget is deprecated. See `lv_example_flex_win`.
  */
+LV_DEPRECATED(LV_WIN_DEPRECATED_MSG)
 lv_obj_t * lv_win_add_title(lv_obj_t * win, const char * txt);
 
 /**
@@ -47,21 +60,27 @@ lv_obj_t * lv_win_add_title(lv_obj_t * win, const char * txt);
  * @param icon      an icon to be displayed on the button
  * @param btn_w     width of the button
  * @return          the widget where the content of the button can be created
+ * @deprecated The `lv_win` widget is deprecated. See `lv_example_flex_win`.
  */
+LV_DEPRECATED(LV_WIN_DEPRECATED_MSG)
 lv_obj_t * lv_win_add_button(lv_obj_t * win, const void * icon, int32_t btn_w);
 
 /**
  * Get the header of the window
  * @param win       pointer to a window widget
  * @return          the header of the window
+ * @deprecated The `lv_win` widget is deprecated. See `lv_example_flex_win`.
  */
+LV_DEPRECATED(LV_WIN_DEPRECATED_MSG)
 lv_obj_t * lv_win_get_header(lv_obj_t * win);
 
 /**
  * Get the content of the window
  * @param win       pointer to a window widget
  * @return          the content of the window
+ * @deprecated The `lv_win` widget is deprecated. See `lv_example_flex_win`.
  */
+LV_DEPRECATED(LV_WIN_DEPRECATED_MSG)
 lv_obj_t * lv_win_get_content(lv_obj_t * win);
 /**********************
  *      MACROS

src/widgets/win/lv_win.c

@@ -11,6 +11,9 @@
 #include "../../lvgl.h"
 #if LV_USE_WIN
 
+/*The `lv_win` API is deprecated as a whole and its functions call each other.*/
+LV_DEPRECATIONS_IGNORE_BEGIN
+
 /*********************
  *      DEFINES
  *********************/
@@ -45,6 +48,7 @@ const lv_obj_class_t lv_win_class = {
 
 lv_obj_t * lv_win_create(lv_obj_t * parent)
 {
+    LV_LOG_DEPRECATED(LV_WIN_DEPRECATED_MSG);
     LV_LOG_INFO("begin");
     lv_obj_t * obj = lv_obj_class_create_obj(&lv_win_class, parent);
     lv_obj_class_init_obj(obj);
@@ -53,6 +57,7 @@ lv_obj_t * lv_win_create(lv_obj_t * parent)
 
 lv_obj_t * lv_win_add_title(lv_obj_t * win, const char * txt)
 {
+    LV_LOG_DEPRECATED(LV_WIN_DEPRECATED_MSG);
     lv_obj_t * header = lv_win_get_header(win);
     lv_obj_t * title = lv_label_create(header);
     lv_label_set_long_mode(title, LV_LABEL_LONG_MODE_DOTS);
@@ -63,6 +68,7 @@ lv_obj_t * lv_win_add_title(lv_obj_t * win, const char * txt)
 
 lv_obj_t * lv_win_add_button(lv_obj_t * win, const void * icon, int32_t btn_w)
 {
+    LV_LOG_DEPRECATED(LV_WIN_DEPRECATED_MSG);
     lv_obj_t * header = lv_win_get_header(win);
     lv_obj_t * btn = lv_button_create(header);
     lv_obj_set_size(btn, btn_w, LV_PCT(100));
@@ -78,11 +84,13 @@ lv_obj_t * lv_win_add_button(lv_obj_t * win, const void * icon, int32_t btn_w)
 
 lv_obj_t * lv_win_get_header(lv_obj_t * win)
 {
+    LV_LOG_DEPRECATED(LV_WIN_DEPRECATED_MSG);
     return lv_obj_get_child(win, 0);
 }
 
 lv_obj_t * lv_win_get_content(lv_obj_t * win)
 {
+    LV_LOG_DEPRECATED(LV_WIN_DEPRECATED_MSG);
     return lv_obj_get_child(win, 1);
 }
 
@@ -107,4 +115,6 @@ static void lv_win_constructor(const lv_obj_class_t * class_p, lv_obj_t * obj)
     lv_obj_set_width(cont, LV_PCT(100));
 }
 
+LV_DEPRECATIONS_IGNORE_END
+
 #endif

tests/src/test_cases/widgets/test_win.c

@@ -3,6 +3,9 @@
 #include "../../lvgl_private.h"
 #include "unity/unity.h"
 
+/* These tests exercise the deprecated lv_win widget on purpose. */
+LV_DEPRECATIONS_IGNORE_BEGIN
+
 static lv_obj_t * active_screen = NULL;
 static lv_obj_t * win = NULL;
 static lv_obj_t * header = NULL;
@@ -158,4 +161,6 @@ void test_win_add_multiple_elements(void)
     TEST_ASSERT_EQUAL_SCREENSHOT("widgets/win_02.png");
 }
 
+LV_DEPRECATIONS_IGNORE_END
+
 #endif