feat: 完整支持页面滑动动画

LanFly · LanFly · commit 15032ed952b3 · 2022-07-26T14:50:58.000+08:00
diff --git a/README-en.md b/README-en.md
@@ -0,0 +1,93 @@
+# LVGL-PM
+
+![version v0.1.1](https://img.shields.io/badge/version-v0.1.1-brightgreen)
+![license MIT](https://img.shields.io/badge/license-MIT-green)
+
+**[【中文文档】](./README.md)**
+
+A simple page manager for LVGL.
+
+## Features
+
+simple and easy to use.
+
+- Page lifecycle management
+- Support transition animation
+
+## Example
+
+```c
+#include "pm.h"
+
+void main()
+{
+  lv_pm_init();
+
+  lv_pm_page_t *home = lv_pm_create_page(0);
+  page->onLoad = page_home_onLoad; // you should implement this function
+  page->unLoad = page_home_unLoad; // you should implement this function
+
+  lv_pm_open_page(0, NULL);
+}
+```
+
+## Write a page
+
+```c
+// home.c
+
+#include "home.h"
+
+void page_home_onLoad(lv_obj_t *page)
+{
+  lv_obj_t *label = lv_label_create(page);
+  lv_label_set_text(label, "hello home page");
+}
+
+void page_home_unLoad(lv_obj_t *page)
+{
+  // all children of page will be deleted automatically.
+}
+```
+
+## API
+
+**uint8_t lv_pm_init()**
+
+This function muse be called before using LVGL-PM.
+
+return 0 is OK.
+
+**lv_pm_page_t \*lv_pm_create_page(uint8_t id)**
+
+Create a page and specify an ID. The ID is used for lv_pm_open_page API.
+
+There are 2 lifecycle that must be registered:
+ 
+ 1. onLoad
+ 2. unLoad
+
+**uint8_t lv_pm_open_page(uint8_t id, lv_pm_open_options_t \*behavior)**
+
+Open the page according to the specified ID.
+
+> Warning: A specified page ID can only be opened once at time. In the future version, we will support multi page instances.
+
+**uint8_t lv_pm_back()**
+
+Close the current page and display the previous page. Do nothing if there is only one page or nothing.
+
+## Lifecycle
+
+1. onLoad
+2. willAppear
+3. didAppear
+4. willDisappear
+5. didDisappear
+6. unLoad
+
+## buildin animation
+
+- LV_PM_ANIMA_NONE (support)
+- LV_PM_ANIMA_SLIDE (support)
+- LV_PM_ANIMA_SLIDE_SCALE (not yet)
diff --git a/README.md b/README.md
@@ -1,17 +1,21 @@
 # LVGL-PM
 
-**【中文文档】马上来**
+![version v0.1.1](https://img.shields.io/badge/version-v0.1.1-brightgreen)
+![license MIT](https://img.shields.io/badge/license-MIT-green)
 
-A simple page manager for LVGL.
+**[English Document](./README-en.md)**
 
-## Features
+一个为 LVGL 精心定制的 APP 页面管理器，简单易用，功能强大，支持多种酷炫动画
 
-simple and easy to use.
+## 特性
 
-- Page lifecycle management
-- Support transition animation
+简单、易用、强大
 
-## Example
+- 支持页面全生命周期管理，参考手机 APP 生命周期
+- 支持多种酷炫动画，内置集成
+- 多个页面代码隔离，单文件开发体验
+
+## 使用示例
 
 ```c
 #include "pm.h"
@@ -21,14 +25,14 @@ void main()
   lv_pm_init();
 
   lv_pm_page_t *home = lv_pm_create_page(0);
-  page->onLoad = page_home_onLoad; // you should implement this function
-  page->unLoad = page_home_unLoad; // you should implement this function
+  page->onLoad = page_home_onLoad; // 需要你实现的页面函数
+  page->unLoad = page_home_unLoad; // 需要你实现的页面函数
 
   lv_pm_open_page(0, NULL);
 }
 ```
 
-## Write a page
+## 编写页面
 
 ```c
 // home.c
@@ -37,54 +41,78 @@ void main()
 
 void page_home_onLoad(lv_obj_t *page)
 {
+  // 所有对象都挂载在 page 下面，页面管理器会自动帮你管理内存
   lv_obj_t *label = lv_label_create(page);
   lv_label_set_text(label, "hello home page");
 }
 
 void page_home_unLoad(lv_obj_t *page)
 {
-  // all children of page will be deleted automatically.
+  // onLoad 和 unLoad 必须实现，所有挂载在 page 下的对象都会自动释放
+  // 你只需要释放自己申请的内存
 }
 ```
 
 ## API
 
 **uint8_t lv_pm_init()**
 
-This function muse be called before using LVGL-PM.
+这个函数必须在使用任何页面管理器 API 之前调用
 
-return 0 is OK.
+返回 0 表示 OK，其它值表示错误，你需要自己处理错误
 
 **lv_pm_page_t \*lv_pm_create_page(uint8_t id)**
 
-Create a page and specify an ID. The ID is used for lv_pm_open_page API.
+创建一个路由并且指定路由标识 ID，这个 ID 在打开页面时会用到，必须唯一。
+
+一般 ID 从下标 0 开始，你可以按照页面的顺序来分配 ID
+
+> 注意：默认路由表长度是 10，所以你不能使用超过长度的 ID 值，如果大于 10，你可以使用 `#define LV_PM_PAGE_NUM 20` 指定长度
 
-There are 2 lifecycle that must be registered:
+创建好路由后，你可以注册页面的生命周期函数了，此时并不会真正的创建页面
+
+下面 2 个生命周期是必须实现的:
  
  1. onLoad
  2. unLoad
 
 **uint8_t lv_pm_open_page(uint8_t id, lv_pm_open_options_t \*behavior)**
 
-Open the page according to the specified ID.
+根据指定的路由 ID 打开页面，此时会调用 onLoad 真正创建页面
+
+参数 `behavior`：指定打开页面的行为，过渡动画，打开方式，动画方向。默认为 `NULL`
+
+> 注意：为了页面代码简单，我们并没有实现多实例。所以一个路由 ID 同时只能被打开一次，打开 2 次以上的行为是未定义的，会产生不可预期的错误
+> 在未来的版本中，我们会支持页面多实例
 
-> Warning: A specified page ID can only be opened once at time. In the future version, we will support multi page instances.
+示例：
+```c
+#include "pm.h"
+
+lv_pm_open_options_t options = {
+  .animation = LV_PM_ANIMA_SLIDE // 使用滑动动画打开页面
+};
+
+lv_pm_open_page(0, &options);
+// 或者使用默认行为 lv_pm_open_page(0, NULL);
+```
 
 **uint8_t lv_pm_back()**
 
-Close the current page and display the previous page. Do nothing if there is only one page or nothing.
+关闭当前页面并且显示上一个页面。如果当前只有一个页面或者没有打开页面，则此函数什么也不做
 
-## Lifecycle
+## 完整的生命周期
 
-1. onLoad
-2. willAppear
-3. didAppear
-4. willDisappear
-5. didDisappear
-6. unLoad
+1. onLoad          : 页面创建，你可以在这里执行初始化
+2. willAppear      : 页面即将被展示
+3. didAppear       : 页面已经被完整展示
+4. willDisappear   : 页面即将被隐藏
+5. didDisappear    : 页面已经被隐藏不可见
+6. unLoad          : 页面被关闭，你需要在这里释放所有临时内存，否则可能存在泄漏
 
-## buildin animation
+## 内置过渡动画
 
-- LV_PM_ANIMA_NONE (support)
-- LV_PM_ANIMA_SLIDE (support)
-- LV_PM_ANIMA_SLIDE_SCALE (not yet)
+- [x] LV_PM_ANIMA_NONE: 不使用过渡动画
+- [x] LV_PM_ANIMA_SLIDE: 滑动动画，页面从右往左出现，从左往右消失
+- [ ] LV_PM_ANIMA_SLIDE_SCALE: 滑动并缩放页面，页面从右往左先出现，再放大全屏
+- [ ] 更多动画开发中，欢迎贡献代码，开发过渡动画非常简单
diff --git a/src/anima.c b/src/anima.c
@@ -23,6 +23,12 @@ static void anima_ready_cb(lv_anim_t *anim)
   cb_data->cb(cb_data->pm_page);
 }
 
+/** 
+----------------------------------------------------------------------------------------------------------
+  slide animation
+----------------------------------------------------------------------------------------------------------
+*/
+
 static void _pm_slide_appear(lv_pm_page_t *pm_page, lv_pm_open_options_t *behavior, lv_pm_anima_complete_cb cb)
 {
   lv_coord_t width = lv_disp_get_hor_res(NULL);
@@ -38,12 +44,18 @@ static void _pm_slide_appear(lv_pm_page_t *pm_page, lv_pm_open_options_t *behavi
   lv_anim_init(&appear_anima);
   lv_anim_set_user_data(&appear_anima, (void *)cb_data);
   lv_anim_set_var(&appear_anima, pm_page->page);
-  lv_anim_set_values(&appear_anima, width, 0);
+
+  if (pm_page->_back) {
+    lv_anim_set_values(&appear_anima, -width, 0);
+  } else {
+    lv_anim_set_values(&appear_anima, width, 0);
+  }
+
+  lv_anim_set_path_cb(&appear_anima, lv_anim_path_ease_out);
   lv_anim_set_time(&appear_anima, 500);
   lv_anim_set_repeat_count(&appear_anima, 1);
   lv_anim_set_exec_cb(&appear_anima, translateX_anima_cb);
   lv_anim_set_ready_cb(&appear_anima, anima_ready_cb);
-  lv_anim_set_path_cb(&appear_anima, lv_anim_path_ease_out);
   lv_anim_start(&appear_anima);
 }
 
@@ -62,7 +74,13 @@ static void _pm_slide_disAppear(lv_pm_page_t *pm_page, lv_pm_open_options_t *beh
   lv_anim_init(&disAppear_anima);
   lv_anim_set_user_data(&disAppear_anima, (void *)cb_data);
   lv_anim_set_var(&disAppear_anima, pm_page->page);
-  lv_anim_set_values(&disAppear_anima, 0, -width);
+
+  if (pm_page->_back) {
+    lv_anim_set_values(&disAppear_anima, 0, width);
+  } else {
+    lv_anim_set_values(&disAppear_anima, 0, -width);
+  }
+
   lv_anim_set_time(&disAppear_anima, 500);
   lv_anim_set_repeat_count(&disAppear_anima, 1);
   lv_anim_set_exec_cb(&disAppear_anima, translateX_anima_cb);
@@ -71,6 +89,8 @@ static void _pm_slide_disAppear(lv_pm_page_t *pm_page, lv_pm_open_options_t *beh
   lv_anim_start(&disAppear_anima);
 }
 
+/** --------------------------------------------------------------------------------------------------- */
+
 void _pm_anima_appear(lv_pm_page_t *pm_page, lv_pm_open_options_t *behavior, lv_pm_anima_complete_cb cb)
 {
   if (behavior == NULL || behavior->animation == LV_PM_ANIMA_NONE) {
@@ -105,4 +125,4 @@ void _pm_anima_disAppear(lv_pm_page_t *pm_page, lv_pm_open_options_t *behavior,
     cb(pm_page);
     break;
   }
-}
+}
diff --git a/src/pm.c b/src/pm.c
@@ -58,6 +58,8 @@ lv_pm_page_t *lv_pm_create_page(uint8_t id)
   if (pm_page == NULL) {
     return NULL;
   }
+  memset(pm_page, 0, sizeof(lv_pm_page_t));
+
   lv_pm_router[id] = pm_page;
   lv_obj_t *page = lv_obj_create(lv_scr_act());
   lv_obj_remove_style_all(page);
@@ -82,6 +84,10 @@ uint8_t lv_pm_open_page(uint8_t id, lv_pm_open_options_t *behavior)
   lv_pm_history[lv_pm_history_len] = id;
   lv_pm_page_t *pm_page = lv_pm_router[id];
   lv_obj_t *page = pm_page->page;
+  if (behavior) {
+    pm_page->_options = *behavior;
+  }
+  pm_page->_back = false;
 
   lv_obj_t *screen = lv_scr_act();
   // turn off the scroll bar temporarily when performing animation
@@ -91,18 +97,19 @@ uint8_t lv_pm_open_page(uint8_t id, lv_pm_open_options_t *behavior)
     uint8_t pid = lv_pm_history[lv_pm_history_len - 1];
     lv_pm_page_t *prev_pm_page = lv_pm_router[pid];
     lv_obj_t *prev_page = prev_pm_page->page;
+    prev_pm_page->_back = false;
     if (prev_pm_page->willDisappear) {
       prev_pm_page->willDisappear(prev_page);
     }
-    _pm_anima_disAppear(prev_pm_page, behavior, _disAppear_complete_cb);
+    _pm_anima_disAppear(prev_pm_page, &pm_page->_options, _disAppear_complete_cb);
   }
 
   pm_page->onLoad(page);
   lv_obj_clear_flag(page, LV_OBJ_FLAG_HIDDEN);
   if (pm_page->willAppear) {
     pm_page->willAppear(page);
   }
-  _pm_anima_appear(pm_page, behavior, _appear_complete_cb);
+  _pm_anima_appear(pm_page, &pm_page->_options, _appear_complete_cb);
 
   lv_pm_history_len++;
   return 0;
@@ -115,29 +122,28 @@ uint8_t lv_pm_back()
   }
   uint8_t pid = lv_pm_history[lv_pm_history_len - 1];
   lv_pm_page_t *pm_page = lv_pm_router[pid];
+  pm_page->_back = true;
   lv_obj_t *page = pm_page->page;
   lv_obj_t *screen = lv_scr_act();
   // turn off the scroll bar temporarily when performing animation
   lv_obj_set_scrollbar_mode(screen, LV_SCROLLBAR_MODE_OFF);
-  lv_pm_open_options_t options = {
-    .animation = LV_PM_ANIMA_SLIDE
-  };
 
   if (pm_page->willDisappear) {
     pm_page->willDisappear(page);
   }
-  _pm_anima_disAppear(pm_page, &options, _back_disAppear_complete_cb);
+  _pm_anima_disAppear(pm_page, &pm_page->_options, _back_disAppear_complete_cb);
 
   lv_pm_history_len--;
   uint8_t prev_pid = lv_pm_history[lv_pm_history_len - 1];
   lv_pm_page_t *prev_pm_page = lv_pm_router[prev_pid];
   lv_obj_t *prev_page = prev_pm_page->page;
+  prev_pm_page->_back = true;
 
   if (prev_pm_page->willAppear) {
     prev_pm_page->willAppear(prev_page);
   }
   lv_obj_clear_flag(prev_pm_page->page, LV_OBJ_FLAG_HIDDEN);
-  _pm_anima_appear(prev_pm_page, &options, _back_appear_complete_cb);
+  _pm_anima_appear(prev_pm_page, &pm_page->_options, _back_appear_complete_cb);
 
   return 0;
 }
diff --git a/src/pm.h b/src/pm.h

-Original file line number
+Diff line change
 #define LV_PM_MAJOR 0
 #define LV_PM_MINOR 1
 -#define LV_PM_PATCH 0
 +#define LV_PM_PATCH 1
 typedef void (*lv_pm_lifecycle)(lv_obj_t *page);
   LV_PM_TARGET_RESET = 2
 };
 +typedef struct _lv_pm_open_options_t
 +{
 +  enum LV_PM_PAGE_ANIMA animation;
 +  enum LV_PM_OPEN_TARGET target;
 +  enum LV_PM_ANIMA_DIR direction;
 +} lv_pm_open_options_t;
++
 typedef struct _lv_pm_page_t
+{
   lv_obj_t *page;
   lv_pm_lifecycle willDisappear;
   lv_pm_lifecycle didDisappear;
   lv_pm_lifecycle unLoad;
 +  lv_pm_open_options_t _options;
 +  bool _back;
 } lv_pm_page_t;
 -typedef struct _lv_pm_open_options_t
 -{
 -  enum LV_PM_PAGE_ANIMA animation;
 -  enum LV_PM_OPEN_TARGET target;
 -  enum LV_PM_ANIMA_DIR direction;
 -} lv_pm_open_options_t;
 uint8_t lv_pm_history_len;