M5Window

M5Window is a widget that can be used to create windows in the user interface.

UiFlow2 Example

window event

Open the window_core2_example.m5f2 project in UiFlow2.

This example creates a window and associates it with events.

UiFlow2 Code Block:

example.png

Example output:

None

MicroPython Example

window event

This example creates a window and associates it with events.

MicroPython Code Block:

  1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
  2#
  3# SPDX-License-Identifier: MIT
  4
  5import os, sys, io
  6import M5
  7from M5 import *
  8import m5ui
  9import lvgl as lv
 10
 11
 12page0 = None
 13window0 = None
 14btn_lav = None
 15title_fmk = None
 16btn_nzk = None
 17btn_dkc = None
 18label_wgy = None
 19
 20
 21def btn_lav_clicked_event(event_struct):
 22    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 23
 24    label_wgy.set_text(str("Left Btn was clicked"))
 25
 26
 27def btn_nzk_clicked_event(event_struct):
 28    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 29
 30    label_wgy.set_text(str("Right Btn was clicked"))
 31
 32
 33def btn_dkc_clicked_event(event_struct):
 34    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 35
 36    window0.set_flag(lv.obj.FLAG.HIDDEN, True)
 37
 38
 39def btn_lav_event_handler(event_struct):
 40    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 41    event = event_struct.code
 42    if event == lv.EVENT.CLICKED and True:
 43        btn_lav_clicked_event(event_struct)
 44    return
 45
 46
 47def btn_nzk_event_handler(event_struct):
 48    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 49    event = event_struct.code
 50    if event == lv.EVENT.CLICKED and True:
 51        btn_nzk_clicked_event(event_struct)
 52    return
 53
 54
 55def btn_dkc_event_handler(event_struct):
 56    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 57    event = event_struct.code
 58    if event == lv.EVENT.CLICKED and True:
 59        btn_dkc_clicked_event(event_struct)
 60    return
 61
 62
 63def setup():
 64    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 65
 66    M5.begin()
 67    Widgets.setRotation(1)
 68    m5ui.init()
 69    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
 70    window0 = m5ui.M5Win(x=0, y=0, w=320, h=240, parent=page0)
 71    btn_lav = window0.add_button(icon=lv.SYMBOL.LEFT, w=40)
 72    title_fmk = window0.add_title("This is a window")
 73    btn_nzk = window0.add_button(icon=lv.SYMBOL.RIGHT, w=40)
 74    btn_dkc = window0.add_button(icon=lv.SYMBOL.CLOSE, w=60)
 75    label_wgy = window0.add_text("This is label_wgy", x=0, y=0)
 76
 77    btn_lav.add_event_cb(btn_lav_event_handler, lv.EVENT.ALL, None)
 78    btn_nzk.add_event_cb(btn_nzk_event_handler, lv.EVENT.ALL, None)
 79    btn_dkc.add_event_cb(btn_dkc_event_handler, lv.EVENT.ALL, None)
 80
 81    page0.screen_load()
 82
 83
 84def loop():
 85    global page0, window0, btn_lav, title_fmk, btn_nzk, btn_dkc, label_wgy
 86    M5.update()
 87
 88
 89if __name__ == "__main__":
 90    try:
 91        setup()
 92        while True:
 93            loop()
 94    except (Exception, KeyboardInterrupt) as e:
 95        try:
 96            m5ui.deinit()
 97            from utility import print_error_msg
 98
 99            print_error_msg(e)
100        except ImportError:
101            print("please update to latest firmware")

Example output:

None

API

M5Win

class m5ui.win.M5Win(*args, **kwargs)

Bases: win

Create a window object.

Parameters:

  • x (int) – The x position of the window.

  • y (int) – The y position of the window.

  • w (int) – The width of the window.

  • h (int) – The height of the window.

  • parent (lv.obj) – The parent object to attach the window to. If not specified, the window will be attached to the default screen.

UiFlow2 Code Block:

None

MicroPython Code Block:

from m5ui import M5Win
import lvgl as lv

m5ui.init()
win0 = M5Win(x=120, y=80, w=60, h=30, parent=page0)
delete()

Delete the item from the window.

UiFlow2 Code Block:

label_delete.png

button_delete.png

title_delete.png

MicroPython Code Block:

label_0.delete()

button_0.delete()

text_0.delete()
set_text(txt)

Set text of the window button/label/title.

Parameters:

txt (str) – The text to set for the window button/label/title.

Returns:

None

UiFlow2 Code Block:

button_set_text.png

label_set_text.png

title_set_text.png

MicroPython Code Block:

button_0.set_text("Select an option")

label_0.set_text("M5Stack")

title_0.set_text("Hello M5Stack")
set_style_text_font(font, part)

Set the font of the window button text.

Parameters:

  • font (lv.lv_font_t) – The font to set.

  • part (int) – The part of the object to apply the style to (e.g., lv.PART.MAIN).

Returns:

None

UiFlow2 Code Block:

button_set_font.png

MicroPython Code Block:

button_0.set_style_text_font(lv.font_montserrat_14, lv.PART.MAIN | lv.STATE.DEFAULT)
set_text_color(color, opa, part)

Set the color of the window button/label/title.

Parameters:

  • color (int) – The color to set.

  • opa (int) – The opacity of the color.

  • part (int) – The part of the object to apply the style to (e.g., lv.PART.MAIN).

Returns:

None

UiFlow2 Code Block:

button_set_text_color.png

label_set_text_color.png

title_set_text_color.png

MicroPython Code Block:

button_0.set_text_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)

label_0.set_text_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)

title_0.set_text_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)
set_bg_color(color, opa, part)

Set the background color of the window button/label/title.

Parameters:

  • color (int) – The color to set.

  • opa (int) – The opacity of the color.

  • part (int) – The part of the object to apply the style to (e.g., lv.PART.MAIN).

Returns:

None

UiFlow2 Code Block:

button_set_bg_color.png

label_set_bg_color.png

title_set_bg_color.png

MicroPython Code Block:

button_0.set_bg_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)

label_0.set_bg_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)

title_0.set_bg_color(lv.color_hex(0x000000), 255, lv.PART.MAIN | lv.STATE.DEFAULT)
set_long_mode(mode)

Set the long mode of the window label/title.

Parameters:

mode (int) – The long mode to set.

UiFlow2 Code Block:

label_set_long_mode.png

title_set_long_mode.png

MicroPython Code Block:

label_0.set_long_mode(lv.label.LONG_MODE.WRAP)
set_flag(flag, value)

Set a flag on the object. If value is True, the flag is added; if False, the flag is removed.

Parameters:

  • flag (int) – The flag to set.

  • value (bool) – If True, the flag is added; if False, the flag is removed.

UiFlow2 Code Block:

button_set_flag.png

label_set_flag.png

title_set_flag.png

MicroPython Code Block:

window_0.set_flag(lv.obj.FLAG.HIDDEN, True)
set_pos(x, y)

Set the position of the window.

Parameters:

  • x (int) – The x-coordinate of the window.

  • y (int) – The y-coordinate of the window.

UiFlow2 Code Block:

set_pos.png

MicroPython Code Block:

window_0.set_pos(100, 100)
set_x(x)

Set the x-coordinate of the window.

Parameters:

x (int) – The x-coordinate of the window.

UiFlow2 Code Block:

set_x.png

MicroPython Code Block:

window_0.set_x(100)
set_y(y)

Set the y-coordinate of the window.

Parameters:

y (int) – The y-coordinate of the window.

UiFlow2 Code Block:

set_y.png

MicroPython Code Block:

window_0.set_y(100)
set_size(width, height)

Set the size of the window.

Parameters:

  • width (int) – The width of the window.

  • height (int) – The height of the window.

Returns:

None

UiFlow2 Code Block:

set_size.png

MicroPython Code Block:

window_0.set_size(100, 50)
align_to(obj, align, x, y)

Align the windowto another object.

Parameters:

  • obj (lv.obj) – The object to align to.

  • align (int) – The alignment type.

  • x (int) – The x-offset from the aligned object.

  • y (int) – The y-offset from the aligned object.

UiFlow2 Code Block:

align_to.png

MicroPython Code Block:

window_0.align_to(page_0, lv.ALIGN.CENTER, 0, 0)
set_state(state, value)

Set the state of the bar. If value is True, the state is set; if False, the state is unset.

Parameters:

  • state (int) – The state to set.

  • value (bool) – If True, the state is set; if False, the state is unset.

Returns:

None

UiFlow2 Code Block:

button_set_state.png

MicroPython Code Block:

window_0.set_state(lv.STATE.PRESSED, True)
toggle_flag(flag)

Toggle a flag on the object. If the flag is set, it is removed; if not set, it is added.

Parameters:

flag (int) – The flag to toggle.

Returns:

None

UiFlow2 Code Block:

button_toggle_flag.png

MicroPython Code Block:

window_0.toggle_flag(lv.obj.FLAG.HIDDEN)
set_style_radius(radius, part)

Set the corner radius of the window button.

Parameters:

  • radius (int) – The radius to set.

  • part (int) – The part of the object to apply the style to (e.g., lv.PART.MAIN).

Returns:

None

UiFlow2 Code Block:

button_set_radius.png

MicroPython Code Block:

button_0.set_style_radius(10, lv.PART.MAIN | lv.STATE.DEFAULT)
set_shadow(color, opa, align, offset_x, offset_y)

Set a shadow for the label/title.

Parameters:

  • color (int) – The color of the shadow in hexadecimal format or an integer.

  • opa (int) – The opacity of the shadow (0-255).

  • align (int) – The alignment of the shadow relative to the label/title.

  • offset_x (int) – The horizontal offset of the shadow.

  • offset_y (int) – The vertical offset of the shadow.

Returns:

None

UiFlow2 Code Block:

label_set_shadow.png

title_set_shadow.png

MicroPython Code Block:

label_0.set_shadow(color=0x000000, opa=128, align=lv.ALIGN.BOTTOM_RIGHT, offset_x=5, offset_y=5)
unset_shadow()

Remove the shadow from the label/title.

UiFlow2 Code Block:

label_unset_shadow.png

title_unset_shadow.png

MicroPython Code Block:

label_0.unset_shadow()
get_text()

Get the text of the button/label/title.

Returns:

The text of the button/label/title.

Return type:

str

UiFlow2 Code Block:

button_get_text.png

label_get_text.png

title_get_text.png

MicroPython Code Block:

button_0.get_text()

label_0.get_text()

text_0.get_text()
toggle_state(state)

Toggle the state of the button. If the state is set, it is unset; if not set, it is set.

Parameters:

state (int) – The state to toggle.

Returns:

None

UiFlow2 Code Block:

button_toggle_state.png

MicroPython Code Block:

button_0.toggle_state(lv.STATE.PRESSED)
add_event_cb(handler, event, user_data)

Add an event callback to the button. The callback will be called when the specified event occurs.

Parameters:

  • handler (function) – The callback function to call.

  • event (int) – The event to listen for.

  • user_data (Any) – Optional user data to pass to the callback.

Returns:

None

UiFlow2 Code Block:

button_event.png

MicroPython Code Block:

def btn_ono_clicked_event(event_struct):
    global page0, window_0, label_lkg, btn_ono, btn_pjm, label0

    print('hello M5')


def btn_ono_event_handler(event_struct):
    global page0, window_0, label_lkg, btn_ono, btn_pjm, label0
    event = event_struct.code
    if event == lv.EVENT.CLICKED and True:
        btn_ono_clicked_event(event_struct)
    return

btn_ono.add_event_cb(btn_ono_event_handler, lv.EVENT.ALL, None)
add_title(text, text_c=2171169, text_opa=255, bg_c=14737632, bg_opa=255, font=lvgl.font_montserrat_14)

Add a title label to the window.

Parameters:

  • text (str) – The text to display on the window.

  • text_c (int) – The text color of the label in hexadecimal format.

  • text_opa (int) – The text opacity of the label (0-255).

  • bg_c (int) – The background color of the label in hexadecimal format.

  • bg_opa (int) – The background opacity of the label (0-255).

  • font (lv.font) – The font to use for the label.

Returns:

The created label object m5ui.M5Label.

Return type:

lv.obj

UiFlow2 Code Block:

add_title.png

add_title2.png

MicroPython Code Block:

win0.add_title("A title", text_c=0x212121, text_opa=255, bg_c=0xE0E0E0, bg_opa=255, font=lv.font_montserrat_14)
add_text(text, x=0, y=0, text_c=2171169, text_opa=255, bg_c=16185078, bg_opa=255, font=lvgl.font_montserrat_14)

Add a text label to the window.

Parameters:

  • text (str) – The text to display on the window.

  • x (int) – The x position of the label.

  • y (int) – The y position of the label.

  • text_c (int) – The text color of the label in hexadecimal format.

  • text_opa (int) – The text opacity of the label (0-255).

  • bg_c (int) – The background color of the label in hexadecimal format.

  • bg_opa (int) – The background opacity of the label (0-255).

  • font (lv.font) – The font to use for the label.

Returns:

The created label object m5ui.M5Label.

Return type:

lv.obj

UiFlow2 Code Block:

add_text.png

add_text2.png

MicroPython Code Block:

win0.add_text("A title", text_c=0x212121, text_opa=255, bg_c=0xF6F6F6, bg_opa=255, font=lv.font_montserrat_14)
add_button(icon=None, text='', w=80, bg_c=2201331, bg_opa=255, text_c=16777215, text_opa=255, font=lvgl.font_montserrat_14)

Add a button to the window.

Parameters:

  • icon (int) – The icon to display on the button.

  • text (str) – The text to display on the button.

  • h (int) – The height of the button.

  • bg_c (int) – The background color of the button in hexadecimal format.

  • bg_opa (int) – The background opacity of the button (0-255).

  • text_c (int) – The text color of the button in hexadecimal format.

  • text_opa (int) – The text opacity of the button (0-255).

  • font (lv.font) – The font to use for the button text.

Returns:

The created button object m5ui.M5Button.

Return type:

lv.obj

UiFlow2 Code Block:

add_button.png

add_button2.png

MicroPython Code Block:

win0.add_button(icon=lv.SYMBOL.BULLET, text_c=0xffffff, text_opa=255, bg_c=0x2196f3, bg_opa=255, font=lv.font_montserrat_14)

win0.add_button(text='M5', text_c=0xffffff, text_opa=255, bg_c=0x2196f3, bg_opa=255, font=lv.font_montserrat_14)