LVGL庫入門教程02-基本控制元件與互動

LVGL 本質上是一個 GUI 庫，它包含大量的控制元件(widget)，即按鈕、標簽、滑塊、選單欄這種具有一定人機互動特征的組合圖形，LVGL 在設計時，采用了一定面向物件編程的設計思路，有效降低了代碼撰寫的難度，

LVGL 和大多數 GUI 庫的作業方式都是類似的，其代碼撰寫的基礎思路為：

• 創建 GUI 根表單物件
• 在表單上繪制各種控制元件
• 為控制元件撰寫回應函式函式
• 在主事件回圈中等待用戶觸發事件回應

如果之前有 GUI 庫的使用經驗的話，應該可以比較容易明白 LVGL 代碼的撰寫思路，

標簽

標簽(label)應該是 GUI 最簡單也是最基礎的控制元件之一，標簽的作用就是顯示一小段說明文字，接下來通過介紹標簽來介紹 LVGL 控制元件的創建、布局與設定屬性，

標簽的創建

通過以下函式可以創建一個標簽：

lv_obj_t* lv_label_create(lv_obj_t* parent);

lv_obj_t 是 LVGL 所有控制元件的通用型別，包括根表單在內的所有控制元件都使用該結構描述，

引數 parent 指定了標簽需要被放在哪一個父容器中，由于一個較大的專案內會存在許多控制元件，因此往往需要將一個較大的視窗劃分為若干結構，每一個結構放入用途相似的的控制元件，使用戶更易熟悉如何操作，例如，一個文本編輯器視窗可能會按功能分為頂層選單欄、側邊導航欄、底部狀態欄以及中間的編輯區，每個區域的控制元件都可以安排在各欄內統一調整，

最基本的父容器就是整個顯示屏視窗物件，可以使用 lv_scr_act() 函式獲取當前的視窗物件，作業系統上的視窗可以設定一些屬性，例如視窗大小、標題文字、圖示等，不過嵌入式螢屏往往是固定的，因此視窗物件一般只作控制元件的父容器使用，

使用以下代碼就可以在當前視窗中創建一個標簽了：

lv_obj_t* label01 = lv_label_create(lv_scr_act());

創建得到的標簽沒有任何可顯示的內容，可以呼叫 lv_label_set_text() 為標簽添加上文字：

lv_label_set_text(label01, "Hello, world!");

這樣就可以在螢屏中顯示一些文本了，LVGL 支持直接顯示 Unicode 文字，只要在源檔案使用 UTF-8 編碼即可，如果要顯示變數的值，LVGL 也提供了 lv_label_set_text_fmt() 函式，可以直接格式化文本，

接下來編譯工程并下載，就可以看到顯示的效果了：

標簽的布局

以上創建的標簽默認放在螢屏的左上角，并且如果創建多個標簽等控制元件，它們都會被重疊放置在左上角，如果需要將控制元件安排到合適的位置，就需要安排它們的布局，一般情況下，可以用以下函式重新調整一個控制元件的布局：

void lv_obj_align(lv_obj_t* obj, lv_align_t align, lv_coord_t x_ofs, lv_coord_t y_ofs);

align 指定了控制元件的對齊方式，可以檢查列舉型別 lv_align_t 來獲取支持的對齊方式，x_ofs 和 y_ofs 是對齊后的額外偏移量，正值表示額外向右下偏移，

LVGL 包含了許多列舉型別，如果不知道該如何傳值，可以查看頭檔案包含的列舉值，

和大多數 GUI 庫一樣，螢屏的左上角為坐標原點 (0, 0) ，往右為 x 軸正向，往下為 y 軸正向，坐標的單位為像素或解析度，

例如，如果額外給以上標簽添加對齊：

lv_obj_align(label01, LV_ALIGN_CENTER, 0, -30);

那么它就會出現在螢屏中間向上 30 像素的位置：

如果要創建更靈活的布局，可以使用 lv_obj_create() 創建一個基本物件，這種直接創建的基本物件一般用作框架，然后通過嵌套框架的形式組織對齊，例如：

/* outer widget align */
lv_obj_t* cont_top = lv_obj_create(lv_scr_act());
lv_obj_t* cont_bottom = lv_obj_create(lv_scr_act());
lv_obj_align(cont_top, LV_ALIGN_TOP_LEFT, 0, 0);
lv_obj_align(cont_bottom, LV_ALIGN_BOTTOM_RIGHT, 0, 0);
/* inner widget align */
lv_obj_t* label_top = lv_label_create(cont_top);
lv_label_set_text(label_top, "At Top Left");
lv_obj_align(label_top, LV_ALIGN_CENTER, 0, 0);
lv_obj_t* label_bottom = lv_label_create(cont_bottom);
lv_label_set_text(label_bottom, "At Bottom Right");
lv_obj_align(label_bottom, LV_ALIGN_CENTER, 0, 0);

這里先將外層的框架在螢屏上對齊，然后再在框內創建標簽，讓標簽在框架內對齊，效果為：

通過這種嵌套的對齊方式，可以先讓一些基礎控制元件在框架內對齊，然后再讓框架之間相對對齊，這種對齊方式更靈活，而且方便日后調整各個控制元件的相對位置，

LVGL 的所有控制元件都是以這種相對位置的形式組織的，官方檔案提供了一張圖片，可以很清楚地描述所有的相對對齊方式：

由于居中對齊經常用到，可以直接使用 lv_obj_center(*obj*) 函式設定無偏移的居中對齊，

默認的基本控制元件是有樣式的，并且注意到它們長寬都是固定的，如果包含的控制元件過長，它還會提供一個滾動條，如果需要調整控制元件的尺寸，可以使用函式，lv_obj_set_width() 和 lv_obj_set_height() 分別調整長寬，或使用 lv_obj_set_size() 一并調整：

lv_obj_t* cont = lv_obj_create(lv_scr_act());
lv_obj_t* label = lv_label_create(cont);
lv_label_set_text(label, "Helllllo, world!");
lv_obj_set_size(cont, 160, 50);
lv_obj_center(cont);
lv_obj_center(label);

所有的控制元件都具有寬度和高度基本屬性，因此這幾個函式對任意的控制元件都有效，

標簽的長模式和顏色調整

框架包含的控制元件過長會提供一個滾動條，確保包含的內容都可見，標簽在創建時，它的寬度會適應包含文本的寬度，如果給一個標簽重新調整尺寸，使得它的寬度小于文本的寬度，那么它包含的文本就會自動折疊：

lv_obj_t* label01 = lv_label_create(lv_scr_act());
lv_label_set_text(label01, "A very loooooooooooooooong text");
lv_obj_set_width(label01, 100);

如果文本確實過長，超過了標簽的長寬極限，那么可以使用函式

void lv_label_set_long_mode(lv_obj_t * obj, lv_label_long_mode_t long_mode);

給標簽設定一個長模式，標簽一共有 5 種長模式，每種模式的表現形式如下：

如果文本顯示時有多行，那么可以使用

void lv_obj_set_style_text_align(lv_obj_t* obj, lv_text_align_t value, lv_style_selector_t selector);

將文本垂直對齊，第三個引數 selector 是設定樣式用的，這里可以暫時不用理會，

以下動圖展示了三種長模式：顯示省略號、換行并居中對齊，以及回圈滾動：

需要注意的是，除了滾動以外的其它模式如果沒有明確高度，都會在文本過長時優先嘗試調整標簽高度，

滾動是一種特殊的影片，在后續介紹到影片時還可以創建更豐富的影片效果，可以自行調整文本的滾動行為，

標簽的文本可以改變顏色，LVGL 里，調整顏色是通過特殊格式的文本作用的，為了改變顏色，首先需要啟用這一模式：

lv_label_set_recolor(label01, true);

重新調整顏色的文本格式為：

#RRGGBB text#

這樣 text 對應的文本就會顯示為 #RRGGBB 對應的色值，如果螢屏使用的是 16bit 的顏色也不要緊，LVGL 會自動轉換顏色，

例如：

lv_label_set_text(label01, "#0000ff Re-color# #ff00ff text# #ff0000 of a# label.");

顯示效果為：

按鈕

按鈕(button)也是一個比較基礎的控制元件，按鈕除了可以顯示一些提示文字外，還可以點擊并獲取回應，接下來通過介紹按鈕來介紹為控制元件系結事件的一般方式，

按鈕的創建和事件系結

按鈕的創建和布局方式都與標簽類似：

lv_obj_t* btn01 = lv_btn_create(lv_scr_act());
lv_obj_align(btn01, LV_ALIGN_CENTER, 0, -40);

但是注意，創建得到的按鈕只是一個簡單的形狀，為了給它添加說明文本，需要在其中創建一個標簽：

lv_obj_t* label01 = lv_label_create(btn01);
lv_label_set_text(label01, "Button");
lv_obj_center(label01);

顯示的效果為：

按鈕不同于框架，按鈕會自動調整寬高來適應其包含的標簽大小，

創建的按鈕已經默認具有點擊影片，不過還無法對點擊作出回應，接下來需要給按鈕添加回呼函式，可以使用以下函式為按鈕系結回呼函式：

lv_obj_add_event_cb(lv_obj_t* obj, lv_event_cb_t event_cb, lv_event_code_t filter, void* user_data);

任意可互動控制元件都可以使用該函式添加回呼函式，這里不用管該函式的回傳值，event_cb 是事件的回呼函式，filter 決定按鈕會對哪些事件作出回應，可以在 user_data 傳入一些自定義的資料，

檢查型別 lv_event_cb_t 的定義就可以明白如何撰寫回呼函式，回呼函式有且僅有一個 lv_event_t 型別的引數，該型別是一個比較復雜的結構型別，目前只需要明白它包括的結構成員包括自定義資料 user_data 即可，

例如，以下創建了一個簡單的回呼函式：

static void button_clicked_cb(lv_event_t* e) {
    static uint8_t count = 0;
    count++;
    lv_label_set_text_fmt((lv_obj_t*)e->user_data, "Clicked: %d", count);
}

這里通過自定義引數來修改外部標簽的文本，那么在系結時，就需要這樣傳入引數：

lv_obj_add_event_cb(btn01, button_simple_cb, LV_EVENT_CLICKED, label01);

這里讓按鈕只對點擊事件產生回應，如果要讓按鈕對多個事件回應的話，需要先讓按鈕對所有事件 LV_EVENT_ALL 產生回應的話，然后在回呼函式內進一步判斷事件型別：

lv_event_code_t code = lv_event_get_code(e);
if (code == LV_EVENT_CLICKED) {
    /* ... event handler ... */
}

這就像在中斷函式內判斷中斷源一樣，

不過以上回呼還可以使用另一種不傳入用戶引數的形式完成，首先，通過

lv_obj_t* lv_event_get_target(lv_event_t* e);

可以獲取產生事件的控制元件，然后通過

lv_obj_t* lv_obj_get_child(const lv_obj_t* obj, int32_t id);

獲取該控制元件的子控制元件，在創建控制元件時，需要傳入父容器控制元件，創建時父容器也會通過 id 記錄包含的子控制元件，創建最早的控制元件 id 就是 0 ，第二早的 id 是 1 ，最晚的 id 還可以表示為 -1 等，這樣就可以在事件回呼函式內獲取被點擊按鈕的標簽控制元件物件了，

控制元件的通用行為

LVGL 中，可以通過

void lv_obj_add_flag(lv_obj_t* obj, lv_obj_flag_t f);

為控制元件設定一些通用的標志，來改變控制元件的行為，

例如，以上按鈕都是普遍的按鈕，它們通過點擊來觸發回應，但是還有一部分按鈕，像控制鍵是通過點擊來切換啟用/關閉狀態的，那么此時就可以給按鈕添加一個這樣的標志：

lv_obj_t* btn02 = lv_btn_create(lv_scr_act());
lv_obj_add_flag(btn02, LV_OBJ_FLAG_CHECKABLE);

這樣創建的按鈕可以對 LV_EVENT_VALUE_CHANGED 這個特殊的事件回應，而普通的按鈕不行，不僅如此，切換之后的部分樣式也會發生改變：

可以給一個控制元件添加多個標志，只需要使用按位或運算子 | 連接起來即可，還可以清除一個控制元件的標志，例如，如果給一個框架清除可滾動的標志，那么當它包含長文本時就不再可以滾動顯示全部內容：

lv_obj_t* cont = lv_obj_create(lv_scr_act());
lv_obj_t* label = lv_label_create(cont);
lv_obj_clear_flag(cont, LV_OBJ_FLAG_SCROLLABLE);
lv_label_set_text(label, "A label contains very long text");
lv_obj_set_size(cont, 160, 50);

效果為：

標志是一個很重要的內容，通過為控制元件加上各種標志，可以自定義更多抽象的控制元件型別，例如，具有 LV_OBJ_FLAG_CLICKABLE 標志的控制元件可以回應點擊事件，這種回應不僅包括回呼函式，還關系著點擊時的影片效果，LVGL 一共提供了 27 個獨立的標志，其中有 8 個可供用戶自定義，可以檢查 lv_obj_flag_t 列舉定義來查看包含的所有標志位，

開關

開關的創建

以上創建的通過點擊來切換啟用/關閉狀態的按鈕可以使用開關(switch)代替，創建開關和創建其它控制元件類似：

lv_obj_t* sw = lv_switch_create(lv_scr_act());

開關的效果如下，通過單擊可以切換開關狀態：

開關具有標志 LV_OBJ_FLAG_CHECKABLE ，因此可以回應事件 LV_EVENT_VALUE_CHANGED ，

開關的狀態

一個控制元件可以具有多種標志，標志就是控制元件的抽象介面，決定了控制元件具有哪些行為，控制元件還具有多種不同的狀態，在每種狀態下，它的樣式都是不一樣的，可以通過

void lv_obj_add_state(lv_obj_t* obj, lv_state_t state);

給一個控制元件設定不同的狀態來切換樣式，例如，如果給開關設定狀態 LV_STATE_CHECKED ，它會表現出打開的狀態，不同狀態下控制元件接收的回應也不一樣，例如如果給開關加上 LV_STATE_DISABLED 的狀態，點擊時它就無法接收任何回應，連樣式也不會再切換了，

可以在回應函式內通過 lv_obj_has_state(obj, state) 來判斷一個控制元件處于什么狀態，從而決定執行什么樣的代碼，這種方式更貼合控制元件的行為，

每個控制元件都有 9 種獨立的狀態，還有 4 種狀態可以由用戶自由定義，這些狀態都被放在頭檔案 lv_obj.h 中，可以使用按位與運算子 | 給一個控制元件添加多個狀態，例如，可以給一個開關設定為既開啟又只讀 LV_STATE_CHECKED | LV_STATE_DISABLED ，那么它的樣式就會表現為：

狀態是在標志之上的概念，在不同的狀態下控制元件可能具有不同的標志，

基本互動控制元件

下拉串列

下拉串列(drop-down list)也是一個非常簡單的控制元件，下拉串列在點擊后會出現一些選項，點擊選擇后就可以觸發一些事件，

可以通過 lv_dropdown_set_options() 為下拉串列創建串列項：

lv_obj_t* drop01 = lv_dropdown_create(lv_scr_act());
lv_dropdown_set_options(drop01, "STM32F1\n"
                                "STM32F4\n"
                                "STM32H7\n"
                                "STM8");

LVGL 會自動拆分多行本文的每一行并分別創建一個串列項，下拉串列默認的行為是展示第一個串列項，并通過用戶選擇來切換展示的串列項：

下拉串列在選擇串列項時會觸發 LV_EVENT_VALUE_CHANGED 事件，可以通過

uint16_t lv_dropdown_get_selected(const lv_obj_t* obj);
void lv_dropdown_get_selected_str(const lv_obj_t* obj, char* buf, uint32_t buf_size);

來獲取當前選中串列項索引或文本，如果要獲取文本的話需要自行準備一個文本緩沖區，

下拉串列可以通過

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

給它設定一個固定的文本，這樣的下拉串列可以充當下拉選單使用，

下拉串列還可以通過

void lv_dropdown_set_dir(lv_obj_t* obj, lv_dir_t dir);
void lv_dropdown_set_symbol(lv_obj_t* obj, const void* symbol);

修改串列項出現的位置和下拉串列右側的符號，由此可以組合出上拉串列、左拉串列等，

滾動串列

滾動串列(roller)和下拉串列類似，不過它是通過滾動來切換選擇的串列項的，

滾動串列的創建、事件回應和獲取選中值的方式都和下拉串列類似，以下是滾動串列的創建方式：

lv_obj_t* roller01 = lv_roller_create(lv_scr_act());
lv_roller_set_options(roller01,
                      "Monday\nTuesday\nWednesday\n"
                      "Thursday\nFriday\nSaturday\nSunday",
                      LV_ROLLER_MODE_INFINITE);

在設定串列項時滾動串列多了一個引數，代表滾動到底后需要停止還是回圈往復，滾動串列非常適合用于串列項稍微有些多，沒有足夠的空間展示所有串列項的情況，因此，滾動串列還可以使用函式

void lv_roller_set_visible_row_count(lv_obj_t *obj, uint8_t row_cnt);

設定可見的串列項個數，如果設定為偶數，那么會有兩個串列項只顯示一半，就像動圖中展示的一樣，

首發于：http://frozencandles.fun/archives/316

參考資料/延伸閱讀

https://docs.lvgl.io/master/widgets/index.html

LVGL 官方檔案——控制元件，在此可以查看更多文中沒有提到的控制元件型別和使用細節，并查看官方撰寫的示例代碼，

標籤：其他

上一篇：將一部分狀態傳遞給React組件

下一篇：在反應路由器dom中使用導航時，函式作為反應子錯誤無效