Pressure Stall Information 壓力失速信息 Date: April, 2018 Author: Johannes Weiner [email protected] 當CPU、MEM或者IO設備被爭奪時,工作負載就會經受延遲增加,吞吐量損失和運行時被OOM殺死的風險。 如果沒 ...
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 種長模式,每種模式的表現形式如下:
枚舉值 | 說明 |
---|---|
LV_LABEL_LONG_WRAP |
將過寬的文本換行,以多行的方式顯示所有文本 |
LV_LABEL_LONG_DOT |
將過長的文本隱藏並以省略號代替 |
LV_LABEL_LONG_SCROLL |
將文本來回滾動顯示 |
LV_LABEL_LONG_SCROLL_CIRCULAR |
將文本迴圈滾動顯示 |
LV_LABEL_LONG_CLIP |
去除過長部分的文本 |
如果文本顯示時有多行,那麼可以使用
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 官方文檔——控制項。在此可以查看更多文中沒有提到的控制項類型和使用細節,並查看官方編寫的示例代碼。