Logo
8.2
  • Introduction
    • Key features
    • Requirements
    • License
    • Repository layout
    • Release policy
      • Release cycle
      • Branches
      • Changelog
      • Version support
    • FAQ
      • Where can I ask questions?
      • Is my MCU/hardware supported?
      • Is my display supported?
      • LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem?
      • My display driver is not called. What have I missed?
      • Why is the display driver called only once? Only the upper part of the display is refreshed.
      • Why do I see only garbage on the screen?
      • Why do I see nonsense colors on the screen?
      • How to speed up my UI?
      • How to reduce flash/ROM usage?
      • How to reduce the RAM usage
      • How to work with an operating system?
  • Examples
    • Get started
      • A button with a label and react on click event
      • Create styles from scratch for buttons
      • Create a slider and write its value on a label
    • Styles
      • Size styles
      • Background styles
      • Border styles
      • Outline styles
      • Shadow styles
      • Image styles
      • Text styles
      • Line styles
      • Transition
      • Using multiple styles
      • Local styles
      • Add styles to parts and states
      • Extending the current theme
    • Animations
      • Start animation on an event
      • Playback animation
      • Animation timeline
    • Events
      • Button click event
      • Handle multiple events
      • Event bubbling
    • Layouts
      • Flex
        • A simple row and a column layout with flexbox
        • Arrange items in rows with wrap and even spacing
        • Demonstrate flex grow
        • Demonstrate flex grow.
        • Demonstrate column and row gap style properties
        • RTL base direction changes order of the items
      • Grid
        • A simple grid
        • Demonstrate cell placement and span
        • Demonstrate grid's "free unit"
        • Demonstrate track placement
        • Demonstrate column and row gap
        • Demonstrate RTL direction on grid
    • Scrolling
      • Nested scrolling
      • Snapping
      • Floating button
      • Styling the scrollbars
      • Right to left scrolling
      • Translate on scroll
    • Widgets
      • Base object
        • Base objects with custom styles
        • Make an object draggable
      • Arc
        • Simple Arc
        • Loader with Arc
      • Bar
        • Simple Bar
        • Styling a bar
        • Temperature meter
        • Stripe pattern and range value
        • Bar with LTR and RTL base direction
        • Custom drawer to show the current value
      • Button
        • Simple Buttons
        • Styling buttons
        • Gummy button
      • Button matrix
        • Simple Button matrix
        • Custom buttons
        • Pagination
      • Calendar
        • Calendar with header
      • Canvas
        • Drawing on the Canvas and rotate
        • Transparent Canvas with chroma keying
      • Chart
        • Line Chart
        • Faded area line chart with custom division lines
        • Axis ticks and labels with scrolling
        • Show the value of the pressed points
        • Display 1000 data points with zooming and scrolling
        • Show cursor on the clicked point
        • Scatter chart
        • Stacked area chart
      • Checkbox
        • Simple Checkboxes
        • Checkboxes as radio buttons
      • Colorwheel
        • Simple Colorwheel
      • Dropdown
        • Simple Drop down list
        • Drop down in four directions
        • Menu
      • Image
        • Image from variable and symbol
        • Image recoloring
        • Rotate and zoom
        • Image offset and styling
      • Image button
        • Simple Image button
      • Keyboard
        • Keyboard with text area
      • Label
        • Line wrap, recoloring and scrolling
        • Text shadow
        • Show LTR, RTL and Chinese texts
        • Draw label with gradient color
      • LED
        • LED with custom style
      • Line
        • Simple Line
      • List
        • Simple List
        • Sorting a List using up and down buttons
      • Menu
        • Simple Menu
        • Simple Menu with root btn
        • Simple Menu with custom header
        • Simple Menu with floating btn to add new menu page
        • Complex Menu
      • Meter
        • Simple meter
        • A meter with multiple arcs
        • A clock from a meter
        • Pie chart
      • Message box
        • Simple Message box
      • Roller
        • Simple Roller
        • Styling the roller
        • add fade mask to roller
      • Slider
        • Simple Slider
        • Slider with custom style
        • Slider with extended drawer
      • Span
        • Span with custom styles
      • Spinbox
        • Simple Spinbox
      • Spinner
        • Simple spinner
      • Switch
        • Simple Switch
      • Table
        • Simple table
        • Lightweighted list from table
      • Tabview
        • Simple Tabview
        • Tabs on the left, styling and no scrolling
      • Textarea
        • Simple Text area
        • Text area with password field
        • Text auto-formatting
      • Tabview
        • Tileview with content
      • Window
        • Simple window
  • Get started
    • Quick overview
      • Get started in a simulator
      • Add LVGL into your project
      • Learn the basics
        • Widgets
        • Events
        • Parts
        • States
        • Styles
        • Themes
      • Examples
        • A button with a label and react on click event
        • Create styles from scratch for buttons
        • Create a slider and write its value on a label
      • Micropython
    • Simulator on PC
      • Select an IDE
      • Set-up Eclipse CDT
        • Install Eclipse CDT
        • Install SDL 2
        • Pre-configured project
        • Add the pre-configured project to Eclipse CDT
        • Compile and Run
    • STM32
    • NXP
      • Creating new project with LVGL
      • Adding HW acceleration for NXP iMX RT platforms using PXP (PiXel Pipeline) engine for existing projects
        • Features supported:
        • Basic configuration:
        • Basic initialization:
        • Project setup:
        • Advanced configuration:
    • Espressif (ESP32 chip series)
      • LVGL demo project for ESP32
      • Using LVGL in your ESP-IDF project
        • Prerequisites
        • Obtaining LVGL
        • Configuration
      • Using lvgl_esp32_drivers in ESP-IDF project
    • Arduino
      • Get the LVGL Arduino library
      • Set up drivers
      • Configure LVGL
      • Initialize and run LVGL
      • Use the examples and demos
      • Debugging and logging
    • Micropython
      • What is Micropython?
        • Highlights of Micropython
      • Why Micropython + LVGL?
        • Here are some advantages of using LVGL in Micropython:
        • Micropython + LVGL could be used for:
      • So what does it look like?
        • A simple example
      • How can I use it?
        • Online Simulator
        • PC Simulator
        • Embedded platform
      • Where can I find more information?
    • Tasmota and berry
      • What is Tasmota?
      • What is Berry?
        • Highlights of Berry
      • Why LVGL + Tasmota + Berry?
        • Tasmota + Berry + LVGL could be used for:
      • So what does it look like?
        • A simple example
      • How can I use it?
      • Where can I find more information?
        • Tasmota Documentation
        • Berry Documentation
        • Tasmota LVGL Berry documentation
    • NuttX RTOS
      • What is NuttX?
        • Highlights of NuttX
      • Why NuttX + LVGL?
        • Here are some advantages of using LVGL in NuttX
        • NuttX + LVGL could be used for
      • How to get started with NuttX and LVGL?
        • First you need to install the pre-requisites on your system
        • Now let's create a workspace to save our files
        • Clone the NuttX and Apps repositories:
        • Configure NuttX to use the stm32f429i-disco board and the LVGL Demo
        • Flashing the firmware in the board using OpenOCD:
      • Where can I find more information?
    • RT-Thread RTOS
      • What is RT-Thread?
      • How to run LVGL on RT-Thread?
    • CMake
      • Espressif (ESP32)
      • MicroPython
      • Zephyr
      • Prerequisites
        • Make
        • Ninja
      • Building LVGL with CMake
        • Additional CMake options
      • Building LVGL examples with CMake
      • Building LVGL drivers and demos with CMake
  • Porting
    • Set up a project
      • Get the library
      • Add lvgl to your project
        • Automatically add files
        • Make and CMake
        • Other platforms and tools
        • Demos and Examples
      • Configuration file
      • Initialization
    • Display interface
      • Draw buffer
      • Buffering modes
        • One buffer
        • Two buffers
        • Full refresh
        • Direct mode
      • Display driver
        • Mandatory fields
        • Optional fields
        • Examples
      • Rotation
      • Further reading
      • API
    • Input device interface
      • Types of input devices
        • Touchpad, mouse or any pointer
        • Keypad or keyboard
        • Encoder
        • Button
      • Other features
        • Parameters
        • Feedback
        • Associating with a display
        • Buffered reading
      • Further reading
      • API
    • Tick interface
      • API
    • Task Handler
    • Sleep management
    • Operating system and interrupts
      • Tasks and threads
      • Interrupts
    • Logging
      • Log level
      • Printing logs
        • Logging with printf
        • Custom log function
      • Add logs
    • Add custom GPU
      • Draw context
        • Fields
        • Initialization
      • Software renderer
        • Blend callback
      • Extend the software renderer
        • New blend callback
        • New rectangle drawer
      • Fully custom draw engine
  • Overview
    • Objects
      • Attributes
        • Basic attributes
        • Specific attributes
      • Working mechanisms
        • Parent-child structure
        • Moving together
        • Visibility only on the parent
        • Create and delete objects
      • Screens
        • Create screens
        • Get the active screen
        • Load screens
        • Layers
        • Handling multiple displays
      • Parts
      • States
      • Snapshot
    • Positions, sizes, and layouts
      • Overview
        • Units
        • Boxing model
        • Important notes
      • Position
        • Simple way
        • Align
      • Size
        • Simple way
      • Using styles
      • Translation
      • Transformation
        • Min and Max size
      • Layout
        • Overview
        • Built-in layout
        • Flags
        • Adding new layouts
      • Examples
    • Styles
      • States
      • Cascading styles
      • Inheritance
      • Parts
      • Initialize styles and set/get properties
      • Add and remove styles to a widget
        • Add styles
        • Remove styles
        • Report style changes
        • Get a property's value on an object
      • Local styles
      • Properties
        • Typical background properties
      • Transitions
      • Color filter
      • Themes
        • Extending themes
      • Examples
        • Size styles
        • Background styles
        • Border styles
        • Outline styles
        • Shadow styles
        • Image styles
        • Arc styles
        • Text styles
        • Line styles
        • Transition
        • Using multiple styles
        • Local styles
        • Add styles to parts and states
        • Extending the current theme
      • API
    • Style properties
      • Size and position
        • width
        • min_width
        • max_width
        • height
        • min_height
        • max_height
        • x
        • y
        • align
        • transform_width
        • transform_height
        • translate_x
        • translate_y
        • transform_zoom
        • transform_angle
      • Padding
        • pad_top
        • pad_bottom
        • pad_left
        • pad_right
        • pad_row
        • pad_column
      • Background
        • bg_color
        • bg_opa
        • bg_grad_color
        • bg_grad_dir
        • bg_main_stop
        • bg_grad_stop
        • bg_grad
        • bg_dither_mode
        • bg_img_src
        • bg_img_opa
        • bg_img_recolor
        • bg_img_recolor_opa
        • bg_img_tiled
      • Border
        • border_color
        • border_opa
        • border_width
        • border_side
        • border_post
      • Outline
        • outline_width
        • outline_color
        • outline_opa
        • outline_pad
      • Shadow
        • shadow_width
        • shadow_ofs_x
        • shadow_ofs_y
        • shadow_spread
        • shadow_color
        • shadow_opa
      • Image
        • img_opa
        • img_recolor
        • img_recolor_opa
      • Line
        • line_width
        • line_dash_width
        • line_dash_gap
        • line_rounded
        • line_color
        • line_opa
      • Arc
        • arc_width
        • arc_rounded
        • arc_color
        • arc_opa
        • arc_img_src
      • Text
        • text_color
        • text_opa
        • text_font
        • text_letter_space
        • text_line_space
        • text_decor
        • text_align
      • Miscellaneous
        • radius
        • clip_corner
        • opa
        • color_filter_dsc
        • color_filter_opa
        • anim_time
        • anim_speed
        • transition
        • blend_mode
        • layout
        • base_dir
    • Scroll
      • Overview
        • Scrollbar
        • Events
      • Basic example
      • Features of scrolling
        • Scrollable
        • Scroll chain
        • Scroll momentum
        • Elastic scroll
        • Snapping
        • Scroll one
        • Scroll on focus
      • Scroll manually
      • Self size
      • Examples
        • Nested scrolling
        • Snapping
        • Floating button
        • Styling the scrollbars
        • Right to left scrolling
        • Translate on scroll
    • Layers
      • Order of creation
      • Bring to the foreground
      • Top and sys layers
    • Events
      • Add events to the object
      • Remove event(s) from an object
      • Event codes
        • Input device events
        • Drawing events
        • Other events
        • Special events
        • Custom events
      • Sending events
        • Refresh event
      • Fields of lv_event_t
      • Event bubbling
      • Examples
        • Button click event
        • Handle multiple events
        • Event bubbling
    • Input devices
      • Pointers
        • Cursor
        • Gestures
      • Keypad and encoder
        • Groups
        • Styling
      • API
        • Input device
        • Groups
    • Displays
      • Multiple display support
        • Using only one display
        • Mirror display
        • Split image
      • Screens
        • Transparent screens
      • Features of displays
        • Inactivity
        • Background
      • API
    • Colors
      • Creating colors
        • RGB
        • HSV
        • Palette
        • Modify and mix colors
        • Built-in colors
      • Opacity
      • Color types
        • Convert color
      • API
    • Fonts
      • Unicode support
      • Built-in fonts
        • Normal fonts
        • Special fonts
      • Special features
        • Bidirectional support
        • Arabic and Persian support
        • Subpixel rendering
        • Compressed fonts
      • Add a new font
      • Add new symbols
      • Load a font at run-time
      • Add a new font engine
      • Use font fallback
    • Images
      • Store images
        • Variables
        • Files
      • Color formats
      • Add and use images
        • Online converter
        • Manually create an image
        • Use images
      • Image decoder
        • Custom image formats
        • Register an image decoder
        • Manually use an image decoder
      • Image caching
        • Cache size
        • Value of images
        • Memory usage
        • Clean the cache
      • API
        • Image buffer
    • File system
      • Ready to use drivers
      • Adding a driver
        • Registering a driver
        • Implementing the callbacks
        • Other callbacks
      • Usage example
      • Use drives for images
      • API
    • Animations
      • Create an animation
      • Animation path
      • Speed vs time
      • Delete animations
      • Timeline
      • Examples
        • Start animation on an event
        • Playback animation
        • Animation timeline
      • API
    • Timers
      • Create a timer
      • Ready and Reset
      • Set parameters
      • Repeat count
      • Measure idle time
      • Asynchronous calls
      • API
    • Drawing
      • Mechanism of screen refreshing
      • Masking
        • Using masks
      • Hook drawing
        • Main drawing
        • Post drawing
        • Part drawing
        • Others
    • New widget
  • Widgets
    • Base object (lv_obj)
      • Overview
        • Coordinates
        • Parents and children
        • Display and Screens
        • Events
        • Styles
        • Flags
        • Groups
        • Extended click area
      • Events
      • Keys
      • Example
        • Base objects with custom styles
        • Make an object draggable
      • API
    • Core widgets
      • Arc (lv_arc)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Bar (lv_bar)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Button (lv_btn)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Button matrix (lv_btnmatrix)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Canvas (lv_canvas)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Checkbox (lv_checkbox)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Drop-down list (lv_dropdown)
        • Overview
        • Parts and Styles
        • Usage
        • Overview
        • Events
        • Keys
        • Example
        • API
      • Image (lv_img)
        • Overview
        • Parts and Styles
        • Usage
        • Transformations
        • Events
        • Keys
        • Example
        • API
      • Label (lv_label)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Line (lv_line)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Roller (lv_roller)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Slider (lv_slider)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Switch (lv_switch)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Table (lv_table)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Text area (lv_textarea)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
    • Extra widgets
      • Animation Image (lv_animimg)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Calendar (lv_calendar)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Headers
        • Example
        • API
      • Chart (lv_chart)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Color wheel (lv_colorwheel)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Image button (lv_imgbtn)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Keyboard (lv_keyboard)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Examples
        • API
      • LED (lv_led)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • List (lv_list)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Menu (lv_menu)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Meter (lv_meter)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Message box (lv_msgbox)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Span (lv_span)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Spinbox (lv_spinbox)
        • Overview
        • Parts and Styles
        • Events
        • Keys
        • Example
        • API
        • Example
      • Spinner (lv_spinner)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Tabview (lv_tabview)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Tile view (lv_tileview)
        • Overview
        • Parts and Styles
        • Usage
        • Events
        • Keys
        • Example
        • API
      • Window (lv_win)
        • Overview
        • Parts and Styles
        • Usage
        • Get the parts
        • Events
        • Keys
        • Example
        • API
  • Layouts
    • Flex
      • Overview
      • Terms
      • Simple interface
        • Flex flow
        • Flex align
        • Flex grow
      • Style interface
        • Internal padding
      • Other features
        • RTL
        • New track
      • Example
        • A simple row and a column layout with flexbox
        • Arrange items in rows with wrap and even spacing
        • Demonstrate flex grow
        • Demonstrate flex grow.
        • Demonstrate column and row gap style properties
        • RTL base direction changes order of the items
      • API
    • Grid
      • Overview
      • Terms
      • Simple interface
        • Grid descriptors
        • Grid items
        • Grid align
      • Style interface
        • Internal padding
      • Other features
        • RTL
      • Example
        • A simple grid
        • Demonstrate cell placement and span
        • Demonstrate grid's "free unit"
        • Demonstrate track placement
        • Demonstrate column and row gap
        • Demonstrate RTL direction on grid
      • API
  • 3rd party libraries
    • File System Interfaces
      • Usage
    • BMP decoder
      • Limitations
      • Example
        • Open a BMP image from file
      • API
    • JPG decoder
      • Overview
      • Usage
      • Converter
        • Converting JPG to C array
        • Converting JPG to SJPG
      • Example
        • Load an SJPG image
      • API
    • PNG decoder
      • Example
        • Open a PNG image from file and variable
      • API
    • GIF decoder
      • Convert GIF files to C array
      • Use GIF images from file
      • Memory requirements
      • Example
        • Open a GIF image from file and variable
      • API
    • FreeType support
      • Install FreeType
      • Add FreeType to your project
      • Usage
      • Example
        • Open a front with FreeType
      • Learn more
      • API
    • QR code
      • Get started
      • Notes
      • Example
        • Create a QR Code
      • API
    • Lottie player
      • Build Rlottie
      • Usage
        • Use Rlottie from file
        • Use Rlottie from raw string data
      • Getting animations
      • Controlling animations
      • Example
        • Load a Lottie animation from raw data
        • Load a Lottie animation from a file
      • API
    • FFmpeg support
      • Install FFmpeg
      • Add FFmpeg to your project
      • Usage
      • Example
        • Decode image
        • Decode video
      • API
  • Others
    • Snapshot
      • Usage
        • Free the Image
        • Use Existing Buffer
      • Example
        • Simple snapshot example
      • API
    • Monkey
      • Usage
      • Example
        • Touchpad monkey example
        • Encoder monkey example
        • Button monkey example
      • API
    • Grid navigation
      • Usage
      • Focusable objects
      • Example
        • Basic grid navigation
        • Grid navigation on a list
        • Nested grid navigations
      • API
  • Contributing
    • Introduction
    • Pull request
      • From GitHub
      • From command line
      • Commit message format
    • Developer Certification of Origin (DCO)
      • Overview
      • Accepted licenses and copyright notices
        • Your own work
        • Use code from online source
        • Use MIT licensed code
        • Use GPL licensed code
    • Ways to contribute
      • Give LVGL a Star
      • Tell what you have achieved
      • Write examples
      • Improve the docs
      • Report bugs
      • Send fixes
      • Join the conversations in the Forum
      • Add features
      • Become a maintainer
      • Move your project repository under LVGL organization
  • Changelog
    • v8.2.0 31 January 2022
      • Overview
      • Breaking Changes
      • Architectural
      • New Features
      • Performance
      • Fixes
      • Examples
      • Docs
      • CI and tests
    • v8.1.0 10 November 2021
      • Overview
      • Breaking Changes
      • Architectural
      • New Features
      • Performance
      • Fixes
      • Examples
      • Docs
      • CI and tests
      • Others
    • v8.0.2 (16.07.2021)
    • v8.0.1 (14.06.2021)
    • v8.0.0 (01.06.2021)
      • Directory structure
      • Widget changes
      • New scrolling
      • New layouts
      • Styles
      • Events
      • Driver changes
      • Other changes
      • New release policy
      • Migrating from v7 to v8
    • v7.11.0 (16.03.2021)
      • New features
      • Bugfixes
    • v7.10.1 (16.02.2021)
      • Bugfixes
    • v7.10.0 (02.02.2021)
      • New features
      • Bugfixes
    • v7.9.1 (19.01.2021)
      • Bugfixes
    • v7.9.0 (05.01.2021)
      • New features
      • Bugfixes
    • v7.8.1 (15.12.2020)
      • Bugfixes
    • v7.8.0 (01.12.2020)
      • New features
      • Bugfixes
    • v7.7.2 (17.11.2020)
      • Bugfixes
    • v7.7.1 (03.11.2020)
      • Bugfixes
    • v7.7.0 (20.10.2020)
      • New features
      • Bugfixes
    • v7.6.1 (06.10.2020)
      • Bugfixes
    • v7.6.0 (22.09.2020)
      • New features
      • Bugfixes
    • v7.5.0 (15.09.2020)
      • New features
      • Bugfixes
    • v7.4.0 (01.09.2020)
      • New features
      • Bugfixes
    • v7.3.1 (18.08.2020)
      • Bugfixes
    • v7.3.0 (04.08.2020)
      • New features
      • Bugfixes
    • v7.2.0 (21.07.2020)
      • New features
      • Bugfixes
    • v7.1.0 (07.07.2020)
      • New features
      • Bugfixes
    • v7.0.2 (16.06.2020)
      • Bugfixes
    • v7.0.1 (01.06.2020)
      • Bugfixes
    • v7.0.0 (18.05.2020)
      • Documentation
      • Legal changes
      • New drawing system
      • New style system
      • GPU integration
      • Renames
      • Reworked and improved object
      • New object types
      • Others
      • Demos
      • New release policy
      • Migrating from v6 to v7
  • Roadmap
    • v8.2
    • Ideas
LVGL
  • »
  • Widgets »
  • Core widgets »
  • Drop-down list (lv_dropdown)
  • Edit on GitHub

Drop-down list (lv_dropdown)¶

Overview¶

The drop-down list allows the user to select one value from a list.

The drop-down list is closed by default and displays a single value or a predefined text. When activated (by click on the drop-down list), a list is created from which the user may select one option. When the user selects a new value, the list is deleted again.

The Drop-down list is added to the default group (if it is set). Besides the Drop-down list is an editable object to allow selecting an option with encoder navigation too.

Parts and Styles¶

The Dropdown widget is built from the elements: "button" and "list" (both not related to the button and list widgets)

Button¶

  • LV_PART_MAIN The background of the button. Uses the typical background properties and text properties for the text on it.

  • LV_PART_INDICATOR Typically an arrow symbol that can be an image or a text (LV_SYMBOL).

The button goes to LV_STATE_CHECKED when it's opened.

List¶

  • LV_PART_MAIN The list itself. Uses the typical background properties. max_height can be used to limit the height of the list.

  • LV_PART_SCROLLBAR The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right.

  • LV_PART_SELECTED Refers to the currently pressed, checked or pressed+checked option. Also uses the typical background properties.

The list is hidden/shown on open/close. To add styles to it use lv_dropdown_get_list(dropdown) to get the list object. For example:

lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, ...)           /*Add the styles to the list*/}`

Alternatively the theme can be extended with the new styles.

Usage¶

Overview¶

Set options¶

Options are passed to the drop-down list as a string with lv_dropdown_set_options(dropdown, options). Options should be separated by \n. For example: "First\nSecond\nThird". This string will be saved in the drop-down list, so it can in a local variable.

The lv_dropdown_add_option(dropdown, "New option", pos) function inserts a new option to pos index.

To save memory the options can set from a static(constant) string too with lv_dropdown_set_static_options(dropdown, options). In this case the options string should be alive while the drop-down list exists and lv_dropdown_add_option can't be used

You can select an option manually with lv_dropdown_set_selected(dropdown, id), where id is the index of an option.

Get selected option¶

The get the index of the selected option, use lv_dropdown_get_selected(dropdown).

lv_dropdown_get_selected_str(dropdown, buf, buf_size) copies the name of the selected option to buf.

Direction¶

The list can be created on any side. The default LV_DIR_BOTTOM can be modified by lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM) function.

If the list would be vertically out of the screen, it will be aligned to the edge.

Symbol¶

A symbol (typically an arrow) can be added to the dropdown list with lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)

If the direction of the drop-down list is LV_DIR_LEFT the symbol will be shown on the left, otherwise on the right.

Show selected¶

The main part can either show the selected option or a static text. If a static is set with lv_dropdown_set_text(dropdown, "Some text") it will be shown regardless to th selected option. If the text is NULL the selected option is displayed on the button.

Manually open/close¶

To manually open or close the drop-down list the lv_dropdown_open/close(dropdown) function can be used.

Events¶

Apart from the Generic events, the following Special events are sent by the drop-down list:

  • LV_EVENT_VALUE_CHANGED Sent when the new option is selected or the list is opened/closed.

  • LV_EVENT_CANCEL Sent when the list is closed

  • LV_EVENT_READY Sent when the list is opened

See the events of the Base object too.

Learn more about Events.

Keys¶

  • LV_KEY_RIGHT/DOWN Select the next option.

  • LV_KEY_LEFT/UP Select the previous option.

  • LY_KEY_ENTER Apply the selected option (Sends LV_EVENT_VALUE_CHANGED event and closes the drop-down list).

Learn more about Keys.

Example¶

Simple Drop down list¶

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        char buf[32];
        lv_dropdown_get_selected_str(obj, buf, sizeof(buf));
        LV_LOG_USER("Option: %s", buf);
    }
}

void lv_example_dropdown_1(void)
{

    /*Create a normal drop down list*/
    lv_obj_t * dd = lv_dropdown_create(lv_scr_act());
    lv_dropdown_set_options(dd, "Apple\n"
                                "Banana\n"
                                "Orange\n"
                                "Cherry\n"
                                "Grape\n"
                                "Raspberry\n"
                                "Melon\n"
                                "Orange\n"
                                "Lemon\n"
                                "Nuts");

    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 20);
    lv_obj_add_event_cb(dd, event_handler, LV_EVENT_ALL, NULL);
}

#endif

MicroPython code  

 GitHub Simulator
def event_handler(e):
    code = e.get_code()
    obj = e.get_target()
    if code == lv.EVENT.VALUE_CHANGED: 
        option = " "*10 # should be large enough to store the option
        obj.get_selected_str(option, len(option))
        # .strip() removes trailing spaces
        print("Option: \"%s\"" % option.strip())

# Create a normal drop down list
dd = lv.dropdown(lv.scr_act())
dd.set_options("\n".join([
    "Apple",
    "Banana",
    "Orange",
    "Cherry",
    "Grape",
    "Raspberry",
    "Melon",
    "Orange",
    "Lemon",
    "Nuts"]))

dd.align(lv.ALIGN.TOP_MID, 0, 20)
dd.add_event_cb(event_handler, lv.EVENT.ALL, None)


Drop down in four directions¶

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES


/**
 * Create a drop down, up, left and right menus
 */
void lv_example_dropdown_2(void)
{
    static const char * opts = "Apple\n"
                               "Banana\n"
                               "Orange\n"
                               "Melon";

    lv_obj_t * dd;
    dd = lv_dropdown_create(lv_scr_act());
    lv_dropdown_set_options_static(dd, opts);
    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 10);

    dd = lv_dropdown_create(lv_scr_act());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_BOTTOM);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_UP);
    lv_obj_align(dd, LV_ALIGN_BOTTOM_MID, 0, -10);

    dd = lv_dropdown_create(lv_scr_act());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_RIGHT);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_RIGHT);
    lv_obj_align(dd, LV_ALIGN_LEFT_MID, 10, 0);

    dd = lv_dropdown_create(lv_scr_act());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_LEFT);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_LEFT);
    lv_obj_align(dd, LV_ALIGN_RIGHT_MID, -10, 0);
}

#endif

MicroPython code  

 GitHub Simulator
#
# Create a drop down, up, left and right menus
#

opts = "\n".join([
    "Apple",
    "Banana",
    "Orange",
    "Melon",
    "Grape",
    "Raspberry"])

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.align(lv.ALIGN.TOP_MID, 0, 10)
dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.BOTTOM)
dd.set_symbol(lv.SYMBOL.UP)
dd.align(lv.ALIGN.BOTTOM_MID, 0, -10)

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.RIGHT)
dd.set_symbol(lv.SYMBOL.RIGHT)
dd.align(lv.ALIGN.LEFT_MID, 10, 0)

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.LEFT)
dd.set_symbol(lv.SYMBOL.LEFT)
dd.align(lv.ALIGN.RIGHT_MID, -10, 0)



Menu¶

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES

static void event_cb(lv_event_t * e)
{
    lv_obj_t * dropdown = lv_event_get_target(e);
    char buf[64];
    lv_dropdown_get_selected_str(dropdown, buf, sizeof(buf));
    LV_LOG_USER("'%s' is selected", buf);
}

/**
 * Create a menu from a drop-down list and show some drop-down list features and styling
 */
void lv_example_dropdown_3(void)
{
    /*Create a drop down list*/
    lv_obj_t * dropdown = lv_dropdown_create(lv_scr_act());
    lv_obj_align(dropdown, LV_ALIGN_TOP_LEFT, 10, 10);
    lv_dropdown_set_options(dropdown, "New project\n"
                                      "New file\n"
                                      "Save\n"
                                      "Save as ...\n"
                                      "Open project\n"
                                      "Recent projects\n"
                                      "Preferences\n"
                                      "Exit");

    /*Set a fixed text to display on the button of the drop-down list*/
    lv_dropdown_set_text(dropdown, "Menu");

    /*Use a custom image as down icon and flip it when the list is opened*/
    LV_IMG_DECLARE(img_caret_down)
    lv_dropdown_set_symbol(dropdown, &img_caret_down);
    lv_obj_set_style_transform_angle(dropdown, 1800, LV_PART_INDICATOR | LV_STATE_CHECKED);

    /*In a menu we don't need to show the last clicked item*/
    lv_dropdown_set_selected_highlight(dropdown, false);

    lv_obj_add_event_cb(dropdown, event_cb, LV_EVENT_VALUE_CHANGED, NULL);
}

#endif

MicroPython code  

 GitHub Simulator
from imagetools import get_png_info, open_png

# Register PNG image decoder
decoder = lv.img.decoder_create()
decoder.info_cb = get_png_info
decoder.open_cb = open_png

# Create an image from the png file
try:
    with open('../../assets/img_caret_down.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_caret_down.png")
    sys.exit()
    
img_caret_down_argb = lv.img_dsc_t({
  'data_size': len(png_data),
  'data': png_data 
})

def event_cb(e):
    dropdown = e.get_target()
    option = " "*64 # should be large enough to store the option
    dropdown.get_selected_str(option, len(option))
    print(option.strip() +" is selected")
#
# Create a menu from a drop-down list and show some drop-down list features and styling
#

# Create a drop down list
dropdown = lv.dropdown(lv.scr_act())
dropdown.align(lv.ALIGN.TOP_LEFT, 10, 10)
dropdown.set_options("\n".join([
    "New project",
    "New file",
    "Open project",
    "Recent projects",
    "Preferences",
    "Exit"]))

# Set a fixed text to display on the button of the drop-down list
dropdown.set_text("Menu")

# Use a custom image as down icon and flip it when the list is opened
# LV_IMG_DECLARE(img_caret_down)
dropdown.set_symbol(img_caret_down_argb)
dropdown.set_style_transform_angle(1800, lv.PART.INDICATOR | lv.STATE.CHECKED)

# In a menu we don't need to show the last clicked item
dropdown.set_selected_highlight(False)

dropdown.add_event_cb(event_cb, lv.EVENT.VALUE_CHANGED, None)


API¶

Functions

LV_EXPORT_CONST_INT(LV_DROPDOWN_POS_LAST)¶
lv_obj_t *lv_dropdown_create(lv_obj_t *parent)¶

Create a drop-down list object

Parameters

parent -- pointer to an object, it will be the parent of the new drop-down list

Returns

pointer to the created drop-down list

void lv_dropdown_set_text(lv_obj_t *obj, const char *txt)¶

Set text of the drop-down list's button. If set to NULL the selected option's text will be displayed on the button. If set to a specific text then that text will be shown regardless of the selected option.

Parameters
  • obj -- pointer to a drop-down list object

  • txt -- the text as a string (Only its pointer is saved)

void lv_dropdown_set_options(lv_obj_t *obj, const char *options)¶

Set the options in a drop-down list from a string. The options will be copied and saved in the object so the options can be destroyed after calling this function

Parameters
  • obj -- pointer to drop-down list object

  • options --

    a string with '

    ' separated options. E.g. "One\nTwo\nThree"

void lv_dropdown_set_options_static(lv_obj_t *obj, const char *options)¶

Set the options in a drop-down list from a static string (global, static or dynamically allocated). Only the pointer of the option string will be saved.

Parameters
  • obj -- pointer to drop-down list object

  • options --

    a static string with '

    ' separated options. E.g. "One\nTwo\nThree"

void lv_dropdown_add_option(lv_obj_t *obj, const char *option, uint32_t pos)¶

Add an options to a drop-down list from a string. Only works for non-static options.

Parameters
  • obj -- pointer to drop-down list object

  • option --

    a string without '

    '. E.g. "Four"

  • pos -- the insert position, indexed from 0, LV_DROPDOWN_POS_LAST = end of string

void lv_dropdown_clear_options(lv_obj_t *obj)¶

Clear all options in a drop-down list. Works with both static and dynamic options.

Parameters

obj -- pointer to drop-down list object

void lv_dropdown_set_selected(lv_obj_t *obj, uint16_t sel_opt)¶

Set the selected option

Parameters
  • obj -- pointer to drop-down list object

  • sel_opt -- id of the selected option (0 ... number of option - 1);

void lv_dropdown_set_dir(lv_obj_t *obj, lv_dir_t dir)¶

Set the direction of the a drop-down list

Parameters
  • obj -- pointer to a drop-down list object

  • dir -- LV_DIR_LEFT/RIGHT/TOP/BOTTOM

void lv_dropdown_set_symbol(lv_obj_t *obj, const void *symbol)¶

Set an arrow or other symbol to display when on drop-down list's button. Typically a down caret or arrow.

Note

angle and zoom transformation can be applied if the symbol is an image. E.g. when drop down is checked (opened) rotate the symbol by 180 degree

Parameters
  • obj -- pointer to drop-down list object

  • symbol -- a text like LV_SYMBOL_DOWN, an image (pointer or path) or NULL to not draw symbol icon

void lv_dropdown_set_selected_highlight(lv_obj_t *obj, bool en)¶

Set whether the selected option in the list should be highlighted or not

Parameters
  • obj -- pointer to drop-down list object

  • en -- true: highlight enabled; false: disabled

lv_obj_t *lv_dropdown_get_list(lv_obj_t *obj)¶

Get the list of a drop-down to allow styling or other modifications

Parameters

obj -- pointer to a drop-down list object

Returns

pointer to the list of the drop-down

const char *lv_dropdown_get_text(lv_obj_t *obj)¶

Get text of the drop-down list's button.

Parameters

obj -- pointer to a drop-down list object

Returns

the text as string, NULL if no text

const char *lv_dropdown_get_options(const lv_obj_t *obj)¶

Get the options of a drop-down list

Parameters

obj -- pointer to drop-down list object

Returns

the options separated by '

'-s (E.g. "Option1\nOption2\nOption3")

uint16_t lv_dropdown_get_selected(const lv_obj_t *obj)¶

Get the index of the selected option

Parameters

obj -- pointer to drop-down list object

Returns

index of the selected option (0 ... number of option - 1);

uint16_t lv_dropdown_get_option_cnt(const lv_obj_t *obj)¶

Get the total number of options

Parameters

obj -- pointer to drop-down list object

Returns

the total number of options in the list

void lv_dropdown_get_selected_str(const lv_obj_t *obj, char *buf, uint32_t buf_size)¶

Get the current selected option as a string

Parameters
  • obj -- pointer to drop-down object

  • buf -- pointer to an array to store the string

  • buf_size -- size of buf in bytes. 0: to ignore it.

const char *lv_dropdown_get_symbol(lv_obj_t *obj)¶

Get the symbol on the drop-down list. Typically a down caret or arrow.

Parameters

obj -- pointer to drop-down list object

Returns

the symbol or NULL if not enabled

bool lv_dropdown_get_selected_highlight(lv_obj_t *obj)¶

Get whether the selected option in the list should be highlighted or not

Parameters

obj -- pointer to drop-down list object

Returns

true: highlight enabled; false: disabled

lv_dir_t lv_dropdown_get_dir(const lv_obj_t *obj)¶

Get the direction of the drop-down list

Parameters

obj -- pointer to a drop-down list object

Returns

LV_DIR_LEF/RIGHT/TOP/BOTTOM

void lv_dropdown_open(lv_obj_t *dropdown_obj)¶

Open the drop.down list

Parameters

obj -- pointer to drop-down list object

void lv_dropdown_close(lv_obj_t *obj)¶

Close (Collapse) the drop-down list

Parameters

obj -- pointer to drop-down list object

bool lv_dropdown_is_open(lv_obj_t *obj)¶

Tells whether the list is opened or not

Parameters

obj -- pointer to a drop-down list object

Returns

true if the list os opened

Variables

const lv_obj_class_t lv_dropdown_class¶
const lv_obj_class_t lv_dropdownlist_class¶
struct lv_dropdown_t¶

Public Members

lv_obj_t obj¶
lv_obj_t *list¶

The dropped down list

const char *text¶

Text to display on the dropdown's button

const void *symbol¶

Arrow or other icon when the drop-down list is closed

char *options¶

Options in a '

' separated list

uint16_t option_cnt¶

Number of options

uint16_t sel_opt_id¶

Index of the currently selected option

uint16_t sel_opt_id_orig¶

Store the original index on focus

uint16_t pr_opt_id¶

Index of the currently pressed option

lv_dir_t dir¶

Direction in which the list should open

uint8_t static_txt¶

1: Only a pointer is saved in options

uint8_t selected_highlight¶

1: Make the selected option highlighted in the list

struct lv_dropdown_list_t¶

Public Members

lv_obj_t obj¶
lv_obj_t *dropdown¶
Next Previous

© Copyright 2021, LVGL Kft. Last updated on Apr 11, 2022.

Built with Sphinx using a theme provided by Read the Docs.