From e0723e21638476827c9efe2c76022b9151d18cae Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Wed, 18 Dec 2024 19:15:24 +0800 Subject: [PATCH 01/10] docs: update connecting_lvgl.rst --- .../connecting_lvgl.rst | 118 ++++++++++++++++-- 1 file changed, 107 insertions(+), 11 deletions(-) diff --git a/docs/intro/add-lvgl-to-your-project/connecting_lvgl.rst b/docs/intro/add-lvgl-to-your-project/connecting_lvgl.rst index 867775e6..7380ff84 100644 --- a/docs/intro/add-lvgl-to-your-project/connecting_lvgl.rst +++ b/docs/intro/add-lvgl-to-your-project/connecting_lvgl.rst @@ -1,14 +1,18 @@ .. _connecting_lvgl: -================================ -Connecting LVGL to Your Hardware -================================ +========================================================= +Connecting LVGL to Your Hardware（将 LVGL 连接到您的硬件） +========================================================= .. _initializing_lvgl: -Initializing LVGL -***************** +Initializing LVGL（初始化LVGL） +****************************** +.. raw:: html + +
+ 显示原文 After you have: - :ref:`acquired LVGL `, @@ -37,13 +41,41 @@ you will need to complete a few more steps to get your project up and running wi 8. Thereafter #include "lvgl/lvgl.h" in source files wherever you need to use LVGL functions. +.. raw:: html + +
+
+在完成以下操作后： +- :ref:`acquired LVGL `， +- 将相应的 LVGL 文件添加到您的项目中，并且 +- 为您的项目 :ref:`created a lv_conf.h file `， + +您还需要再完成几个步骤，才能让您的项目搭载 LVGL 启动并运行起来。 + +1.在系统执行的早期调用 :cpp:func:`lv_init` 对 LVGL 进行一次初始化。 + 在进行任何其他 LVGL 调用之前，都需要先完成此项操作。 + +2.初始化您的驱动程序。 + +3.连接 :ref:`tick_interface`。 + +4.连接 :ref:`display_interface`。 +5.连接 :ref:`indev_interface`。 +6.每隔几毫秒调用一次 :cpp:func:`lv_timer_handler`来驱动 LVGL 中与时间相关的任务，以管理 LVGL 定时器。有关不同的实现方式，请参考 :ref:`timer_handler` 部分。 + +7.（可选）使用 :cpp:func:`lv_display_set_theme` 设置一个主题。 + +8.此后，在任何需要使用 LVGL 函数的源文件中包含 “lvgl/lvgl.h” 头文件。 .. _tick_interface: -Tick Interface -************** +Tick Interface（滴答（Tick）接口） +********************************** +.. raw:: html +
+ 显示原文 LVGL needs awareness of what time it is (i.e. elapsed time in milliseconds) for all of its tasks for which time is a factor: refreshing displays, reading user input, firing events, animations, etc. @@ -89,12 +121,49 @@ For example this works, but LVGL's timing will be incorrect as the execution tim lv_tick_inc(5); my_delay_ms(5); +.. raw:: html + +
+
+LVGL 需要知晓当前时间（即已过去的毫秒数），因为对于所有受时间因素影响的任务来说这很关键，这些任务包括刷新显示屏、读取用户输入、触发事件、实现动画效果等等。 + +.. 图像：/misc/intro_data_flow.png + : 缩放比例：75% + : 替代文本：LVGL 数据流程 + : 对齐方式：居中 +有两种方式可将此信息提供给 LVGL： + +1. 通过调用 :cpp:expr:`lv_tick_set_cb(my_get_milliseconds_function)` 为 LVGL 提供一个回调函数，以获取系统已过去的毫秒数。 +:cpp:expr:`my_get_milliseconds_function()` 需要返回自系统启动以来所经过的毫秒数。许多平台都有内置函数，可直接使用。例如： + + - SDL： ``lv_tick_set_cb(SDL_GetTicks);`` + - Arduino： ``lv_tick_set_cb(my_tick_get_cb);``; ，其中 ``my_tick_get_cb`` 是： + ``static uint32_t my_tick_get_cb(void) { return millis(); }`` + - FreeRTOS： ``lv_tick_set_cb(xTaskGetTickCount);`` + - STM32： ``lv_tick_set_cb(HAL_GetTick);`` + - ESP32： ``lv_tick_set_cb(my_tick_get_cb);`` ，其中 ``my_tick_get_cb``是对 ``esp_timer_get_time() / 1000;`` 的一个封装函数。 +2. 周期性地调用 :cpp:expr:`lv_tick_inc(x)`，其中 ``x`` 是自上次调用以来所经过的毫秒数。如果从一个中断服务程序（ISR）中调用 :cpp:func:`lv_tick_inc`，那么它应该来自高优先级中断，或者是在系统高负载时不能错过的中断。 + .. 注意： :cpp:func:lv_tick_inc 是可以从中断里调用的两个 LVGL 函数之一。如需了解更多信息，请参阅 :ref:`threading` 部分。 +这些滴答数（毫秒数）应该独立于微控制器（MCU）的任何其他活动。 + +例如，下面这种做法可行，但由于没有考虑到 :c:func:`lv_timer_handler` 的执行时间，LVGL 的计时将会不准确： + +.. code-block:: c + + // Bad idea + lv_timer_handler(); + lv_tick_inc(5); + my_delay_ms(5); .. _display_interface: -Display Interface -***************** +Display Interface（显示接口） +***************************** +.. raw:: html + +
+ 显示原文 LVGL needs to be supplied with knowledge about each display panel you want it to use. Specificially: @@ -103,13 +172,26 @@ Specificially: - how to send those rendered pixels to it (:ref:`flush_callback`). See the respective links for how to supply LVGL with this knowledge. +.. raw:: html + +
+
+需要向 LVGL 提供有关您希望它使用的每个显示面板的相关信息。具体来说，需要提供以下信息： +- 其像素格式和尺寸(:ref:`creating_a_display`)； +- 应在何处为其渲染像素(:ref:`draw_buffers`)； +- 如何将那些渲染好的像素发送给它(:ref:`flush_callback`)。 +有关如何向 LVGL 提供这些信息，请查看相应的链接内容。 .. _indev_interface: Input-Device Interface ********************** +.. raw:: html + +
+ 显示原文 LVGL needs to know how to get input from all user-input devices that will be used in your project. LVGL supports a wide variety of user-input devices: @@ -123,8 +205,22 @@ your project. LVGL supports a wide variety of user-input devices: - etc. See :ref:`indev_creation` to see how to do this. - - +.. raw:: html + +
+
+LVGL 需要知道如何从项目中将要使用的所有用户输入设备获取输入信息。LVGL 支持各种各样的用户输入设备： + +- 触摸屏； +- 触摸板； +- 鼠标； +- 旋钮； +- 编码器； +- 小键盘； +- 键盘； +- 等等。 + +查看 :ref:`indev_creation` 部分，了解如何进行相关操作。 API *** From 4e7dd5184e5590ccb7101a470c6b390413b57f77 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Wed, 18 Dec 2024 19:20:56 +0800 Subject: [PATCH 02/10] docs: update getting_lvgl.rst --- .../add-lvgl-to-your-project/getting_lvgl.rst | 36 +++++++++++++++---- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/intro/add-lvgl-to-your-project/getting_lvgl.rst b/docs/intro/add-lvgl-to-your-project/getting_lvgl.rst index 6db04bb6..c75a9baa 100644 --- a/docs/intro/add-lvgl-to-your-project/getting_lvgl.rst +++ b/docs/intro/add-lvgl-to-your-project/getting_lvgl.rst @@ -1,9 +1,13 @@ .. _getting_lvgl: -============ -Getting LVGL -============ - +======================== +Getting LVGL（获取 LVGL） +======================== +.. raw:: html + +
+ 显示原文 + LVGL is available on GitHub: https://github.com/lvgl/lvgl. You can clone it or @@ -14,12 +18,32 @@ The graphics library itself is the ``lvgl`` directory. It contains several directories but to use LVGL you only need the ``.c`` and ``.h`` files under the ``src`` directory, plus ``lvgl/lvgl.h``, and ``lvgl/lv_version.h``. +.. raw:: html + +
+
+ +LVGL 在 GitHub 上可用：https://github.com/lvgl/lvgl。 + +您可以克隆它，或者从 `Download `__ 库的最新版本。 -Demos and Examples ------------------- +图形库本身是 ``lvgl`` 目录。它包含几个目录，但要使用 LVGL，您只需要 ``src`` 目录下的 ``.c`` 和 ``.h`` 文件，以及 ``lvgl/lvgl.h`` 和 ``lvgl/lv_version.h``。 + +Demos and Examples（演示与示例） +-------------------------------- +.. raw:: html + +
+ 显示原文 The ``lvgl`` directory also contains an ``examples`` and a ``demos`` directory. If your project needs examples and/or demos, add the these directories to your project. If ``make`` or :ref:`build_cmake` handle the examples and demos directories, no extra action is required. +.. raw:: html + +
+
+ +``lvgl`` 目录还包含一个 ``examples``（示例）目录和一个 ``demos``（演示）目录。如果您的项目需要示例和 / 或演示程序，将这些目录添加到您的项目中。如果 ``make``（构建工具）或 :ref:`build_cmake`（CMake 构建方式）能够处理示例和演示目录，则无需额外操作。 \ No newline at end of file From 48f520ee63bee432d439d79ae4954832b5bf5f9f Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Wed, 18 Dec 2024 19:24:03 +0800 Subject: [PATCH 03/10] docs: update other_platforms.rst --- .../add-lvgl-to-your-project/other_platforms.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/intro/add-lvgl-to-your-project/other_platforms.rst b/docs/intro/add-lvgl-to-your-project/other_platforms.rst index e317e483..866fbd5d 100644 --- a/docs/intro/add-lvgl-to-your-project/other_platforms.rst +++ b/docs/intro/add-lvgl-to-your-project/other_platforms.rst @@ -1,11 +1,20 @@ .. _other_platforms: -========================= -Other Platforms and Tools -========================= +=========================================== +Other Platforms and Tools（其他平台和工具） +=========================================== +.. raw:: html + +
+ 显示原文 See :ref:`Integration ` to see how to use LVGL on different platforms. There, you will find many platform-specific descriptions e.g. for ESP32, Arduino, NXP, RT-Thread, NuttX, etc. +.. raw:: html +
+
+ +查看 :ref:`Integration ` 部分，了解如何在不同平台上使用 LVGL。在那里，你会找到许多特定于平台的描述，例如针对 ESP32、Arduino、恩智浦（NXP）、RT-Thread、NuttX 等平台的描述。 From 326a7647a7c37dd3189b22cecd1d968171663e38 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Wed, 18 Dec 2024 19:52:54 +0800 Subject: [PATCH 04/10] docs: update threading.rst --- .../add-lvgl-to-your-project/threading.rst | 221 ++++++++++++++++-- 1 file changed, 206 insertions(+), 15 deletions(-) diff --git a/docs/intro/add-lvgl-to-your-project/threading.rst b/docs/intro/add-lvgl-to-your-project/threading.rst index 53edea76..f41e1155 100644 --- a/docs/intro/add-lvgl-to-your-project/threading.rst +++ b/docs/intro/add-lvgl-to-your-project/threading.rst @@ -1,14 +1,17 @@ .. _threading: -======================== -Threading Considerations -======================== +============================================ +Threading Considerations（线程相关注意事项） +============================================ .. _threading_definitions: -Definitions -*********** +Definitions（定义） +******************* +.. raw:: html +
+ 显示原文 .. _thread: Thread @@ -53,14 +56,49 @@ Atomic Data (partially-changed) state, even from a CPU interrupt or exception. With such values, no special protection is required by programmers to ensure all threads see it in a consistent state. +.. raw:: html +
+
+.. _thread: +线程 + 在本文档的语境中，线程是指 CPU 指令的任何序列。 + 在 “裸机” 实现（即无操作系统）的情况下，线程包括： + + - 执行 while (1) 循环来运行系统的主线程，以及 + - 中断。 + + 当在操作系统下运行时，线程包括： + + - 每个任务（或进程）， + - 中断，以及 + - 高级操作系统可在一个进程内拥有多个 “执行线程”。 + +.. _atomic operation: +原子操作 + 如果操作 X 是原子操作，这意味着任何观察该操作的线程看到的要么是操作尚未开始的状态，要么是已完成的状态，而不会看到任何处于部分完成状态的情况。 + + 如果其他线程能看到该操作处于部分执行状态，或者能够干扰它，那么操作 X 就不是原子操作。 + + 如果一个原子操作可能失败，其实现必须将资源恢复到操作开始前的状态。对于其他线程来说，必须看起来好像该操作尚未开始一样。 +.. _atomic data: +.. _atomic: +.. _non-atomic data: + +原子数据 + 如果任何观察数据（即变量或数据结构的内容）的线程总是能看到它处于一致状态，就好像对它的操作要么尚未开始，要么已成功完成，而不会处于部分更改或其他不一致的状态，那么该数据就是原子数据。 + + 当读取或写入一个值通过 1 条 CPU 指令开始并完成时，它自动就是原子的，因为它永远不会处于不一致（部分更改）的状态，即使是来自 CPU 中断或异常情况也是如此。对于这样的值，程序员不需要采取特殊保护措施来确保所有线程看到它处于一致状态。 .. _lvgl_and_threads: -LVGL and Threads -**************** +LVGL and Threads（LVGL 与线程） +****************************** +.. raw:: html +
+ 显示原文 LVGL is **not thread-safe**. That means it is the programmer's responsibility to see that no LVGL function is @@ -104,11 +142,50 @@ before any other LVGL function is started. If you are using an OS, there are a few other options. See below. +.. raw:: html + +
+
+ +LVGL **并非线程安全的**。 + +这意味着程序员有责任确保在另一个线程中正在进行 LVGL 调用时，不会有其他 LVGL 函数被调用。这包括对 :cpp:func:`lv_timer_handler` 的调用。 + +.. 注意:: + 假设上述情况属实，那么在以下情况中调用 LVGL 函数是安全的： + + - 在 :ref:`event callbacks ` 中，以及 + - 在 :ref:`timer callbacks ` 中 + + 因为驱动这两者的线程就是调用 :cpp:func:`lv_timer_handler` 的线程。 + +原因： + +LVGL 管理着许多复杂的数据结构，而这些结构属于 “系统资源”，必须防止其他线程在其处于不一致状态时 “看到” 它们。很大比例的 LVGL 函数（以 ``lv_`` 开头的函数）要么从这些数据结构中读取数据，要么对其进行更改。那些更改数据结构的函数在执行期间会使数据处于不一致状态（因为此类更改是多步骤的操作序列），但会在函数返回前将其恢复到一致状态。基于这个原因，在启动任何其他 LVGL 函数之前，必须允许每个 LVGL 函数完成执行。 + +.. _os_exception: + +.. 告诫：：上述情况的例外： + + 以下两个 LVGL 函数可以从任何线程中被调用： + + - :cpp:func:`lv_tick_inc`（如需了解更多信息，请参阅 :ref:`tick_interface`），以及 + - :cpp:func:`lv_display_flush_ready`（如需了解更多信息，请参阅 :ref:`flush_callback`） + + 这样做可行的原因是它们所更改的 LVGL 数据是 :ref:`atomic `。 + + 如果中断必须向调用 LVGL 函数的应用程序的某个部分传递信息，可设置一个标志或其他原子值，供调用 LVGL 的线程（或者你创建的 :ref:`LVGL Timer `）读取并采取相应行动。 + + 如果您正在使用操作系统，还有其他一些可选方案。详见下文。 .. _tasks: -Tasks -***** +Tasks（任务） +************ +.. raw:: html + +
+ 显示原文 Under an OS, it is common to have many threads of execution ("tasks" in some OSes) performing services for the application. In some cases, such threads can acquire data that should be shown (or otherwise reflected) in the user interface, and doing @@ -118,12 +195,23 @@ Yet it still remains the programmer's responsibility to see that no LVGL functio called while another LVGL call is in progress. How do you do this? +.. raw:: html +
+
+在操作系统下，应用程序通常会有许多执行线程（在某些操作系统中称为 “任务”）来提供服务。在某些情况下，这些线程可以获取应该在用户界面中显示（或以其他方式体现）的数据，并且这样做需要调用 LVGL 来显示（或更改）这些数据。 +然而，程序员仍然有责任确保在另一个 LVGL 调用正在进行时，不会调用其他 LVGL 函数。 + +要怎么做呢？ .. _gateway thread: -Method 1: Use a Gateway Thread -------------------------------- +Method 1: Use a Gateway Thread（方法 1：使用网关线程） +------------------------------------------------------- +.. raw:: html + +
+ 显示原文 A "Gateway Thread" (or "Gateway Task" in some OSes) is a thread (task) that the system designer designates to *exclusively* manage a system resource. An example is management of a remote chip, such as an EEPROM or other device that always needs to @@ -162,10 +250,31 @@ in an inconsistent state. Use of a `Gateway Thread`_ avoids the CPU-overhead (and coding overhead) of using a MUTEX to protect LVGL data structures. +.. raw:: html + +
+
+“网关线程”（在某些操作系统中称为 “网关任务”）是系统设计者指定用来 “专门” 管理系统资源的线程（任务）。例如，对远程芯片（如 EEPROM 或其他设备）的管理，在开始新操作之前，总是需要使其处于一致状态。另一个例子是对 I2C 总线（或任何数据总线）上多个设备的管理。在这种情况下，I2C 总线就是 “专门管理的资源”，只有一个线程对其进行管理，就能确保每项已启动的操作在启动另一项与之相关的操作之前能够完成。 + +LVGL 的数据结构是一种需要此类保护的系统资源。 + +使用这种方法，所有部件（Widget）及其他 LVGL 资源的创建、修改和删除（即除上述 :ref:`exceptions ` 中提到的函数之外的所有 LVGL 函数调用）都由该线程来进行调用。这意味着该线程也是 :cpp:func:`lv_timer_handler` 的唯一调用者。（如需了解更多信息，请参阅 :ref:`add_lvgl_to_your_project`将LVGL添加到您的项目中。） + +通过确保没有其他线程 “查看” 这些数据结构，这能保证 LVGL 的数据结构 “看起来” 是原子的（所有使用这些数据的线程 “看到” 的都是其处于一致状态）。这是通过程序员的规范来强制实施的，即确保 `Gateway Thread`_ 是唯一进行 LVGL 调用的线程（除上述 :ref:`exceptions ` 中提到的情况外）。 + +如果与用户界面相关的 `atomic data`_ 在另一个线程（即由另一个任务或在中断中）进行了更新，调用 LVGL 函数的线程可以直接读取该数据，而无需担心其处于不一致状态。（为避免不必要的 CPU 开销，可以提供一种机制 [比如由更新线程设置一个标志]，以便仅在会导致最终用户可见的更改时才更新用户界面。） + +如果与用户界面相关的 `non-atomic data`_ 在另一个线程（即由另一个任务或在中断中）进行了更新，将该数据传递给调用 LVGL 函数的线程的另一种（且安全的）方式是，通过队列或其他操作系统机制将该数据的私有副本传递给该线程，这种机制可保护数据不被看到处于不一致状态。 +使用 `Gateway Thread`_ 可避免使用互斥锁（MUTEX）来保护 LVGL 数据结构所产生的 CPU 开销（以及编码开销）。 -Method 2: Use a MUTEX ----------------------- + +Method 2: Use a MUTEX（方法 2：使用互斥锁） +------------------------------------------- +.. raw:: html + +
+ 显示原文 A MUTEX stands for "MUTually EXclusive" and is a synchronization primative that protects the state of a system resource from being modified or accessed by multiple threads of execution at once. In other words, it makes data so protected "appear" @@ -235,14 +344,67 @@ This pseudocode illustrates the concept of using a MUTEX: thread_sleep(2000); } } +.. raw:: html + +
+
+互斥锁（MUTEX）是 “Mutually Exclusive（互斥）” 的缩写，它是一种同步原语，用于保护系统资源的状态，防止其同时被多个执行线程修改或访问。换句话说，它能使受其保护的数据 “看起来” 是原子的（所有使用这些数据的线程 “看到” 的都是其处于一致状态）。大多数操作系统都提供互斥锁。 + +系统设计者会为单个系统资源分配一个互斥锁。分配之后，互斥锁由程序员通过以下方式来执行此类保护： + +1. 在访问或修改该资源之前获取互斥锁（也称作加锁），并且 + +2. 在访问或修改完成之后释放互斥锁（也称作解锁）。 + +如果一个线程试图获取（加锁）互斥锁，而此时另一个线程 “持有” 该互斥锁，那么这个线程就会等待另一个线程释放（解锁）它，之后才被允许继续执行。 + +需要明确的是：无论是从该资源读取数据的线程，还是修改该资源的线程，都必须这样做。 + +如果使用互斥锁来保护 LVGL 的数据结构，这意味着每一次 LVGL 函数调用（或一组函数调用）之前都必须先执行步骤 1，之后执行步骤 2，包括对 :cpp:func:`lv_timer_handler` 的调用也不例外。 +.. 注意:: +如果您的操作系统与 LVGL 集成（在 ``lv_conf.h`` 文件中，宏 :c:macro:`LV_USE_OS` 的值不是 ``LV_OS_NONE``），您可以使用 :cpp:func:`lv_lock()` 和 :cpp:func:`lv_unlock()` 来执行步骤 1 和步骤 2。 + +在这种情况下， :cpp:func:`lv_timer_handler` 会在内部调用 :cpp:func:`lv_lock()` 和 :cpp:func:`lv_unlock()`，所以您不必在对 :cpp:func:`lv_timer_handler` 的调用前后加上这两个函数调用。 + +如果您的操作系统未与 LVGL 集成，那么这些调用要么立即返回且无任何效果，要么会被链接器优化掉。 +要启用 :cpp:func:`lv_lock()` 和 :cpp:func:`lv_unlock()`，需将 ``LV_OS_NONE``设置为非 ``LV_OS_NONE`` 的值。 +以下伪代码阐释了使用互斥锁的概念： +.. code-block:: c + + void lvgl_thread(void) + { + while(1) { + uint32_t time_till_next; + time_till_next = lv_timer_handler(); /* lv_lock/lv_unlock is called internally */ + thread_sleep(time_till_next); /* sleep for a while */ + } + } + void other_thread(void) + { + /* You must always hold (lock) the MUTEX while calling LVGL functions. */ + lv_lock(); + lv_obj_t *img = lv_image_create(lv_screen_active()); + lv_unlock(); + + while(1) { + lv_lock(); + /* Change to next image. */ + lv_image_set_src(img, next_image); + lv_unlock(); + thread_sleep(2000); + } + } .. _sleep_management: -Sleep Management -**************** +Sleep Management（睡眠管理） +*************************** +.. raw:: html +
+ 显示原文 The MCU can go to sleep when no user input has been received for a certain period. In this case, the main ``while(1)`` could look like this: @@ -273,5 +435,34 @@ function to signal a wake-up (press, touch, click, etc.) has happened: In addition to :cpp:func:`lv_display_get_inactive_time` you can check :cpp:func:`lv_anim_count_running` to see if all animations have finished. +.. raw:: html + +
+
+ +当在一定时间段内未接收到用户输入时，微控制器（MCU）可以进入睡眠状态。在这种情况下，主 ``while(1)`` 循环可能看起来像这样： + +.. code-block:: c + + while(1) { + /* Normal operation (no sleep) in < 1 sec inactivity */ + if(lv_display_get_inactive_time(NULL) < 1000) { + lv_timer_handler(); + } + /* Sleep after 1 sec inactivity */ + else { + timer_stop(); /* Stop the timer where lv_tick_inc() is called */ + sleep(); /* Sleep the MCU */ + } + my_delay_ms(5); + } + +你还应该将以下代码行添加到输入设备读取函数中，以表示唤醒（按下、触摸、点击等）操作已发生： + +.. code-block:: c + lv_tick_inc(LV_DEF_REFR_PERIOD); /* 唤醒时强制任务执行 */ + timer_start(); /* 在调用 lv_tick_inc () 的地方重启定时器 */ + lv_timer_handler(); /* 手动调用`lv_timer_handler()`来处理唤醒事件 */ +除了 :cpp:func:`lv_display_get_inactive_time` 之外，你还可以检查 :cpp:func:`lv_anim_count_running` ，以查看所有动画是否都已完成。 \ No newline at end of file From 0616efa52183ea5296660dcb2fef79addf556700 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Wed, 18 Dec 2024 19:58:04 +0800 Subject: [PATCH 05/10] docs: update timer_handler.rst --- .../timer_handler.rst | 60 ++++++++++++++++++- 1 file changed, 57 insertions(+), 3 deletions(-) diff --git a/docs/intro/add-lvgl-to-your-project/timer_handler.rst b/docs/intro/add-lvgl-to-your-project/timer_handler.rst index f517baa2..3a6f9cd0 100644 --- a/docs/intro/add-lvgl-to-your-project/timer_handler.rst +++ b/docs/intro/add-lvgl-to-your-project/timer_handler.rst @@ -1,9 +1,12 @@ .. _timer_handler: -============= -Timer Handler -============= +=============================== +Timer Handler（定时器处理程序） +=============================== +.. raw:: html +
+ 显示原文 To drive the timers of LVGL you need to call :cpp:func:`lv_timer_handler` periodically in one of the following: @@ -57,7 +60,58 @@ In an OS environment, you can use it together with the **delay** or } See :ref:`timer` section to learn more about timers. +.. raw:: html +
+
+要驱动 LVGL 的定时器，需要在以下情况之一中定期调用 :cpp:func:`lv_timer_handler` 函数： +- 在 *main()* 函数的 *while(1)* 循环中，或者 +- 在操作系统任务中定期调用。（请参阅 :ref:`lvgl_and_threads` 。） + +.. 图像:: /misc/intro_data_flow.png + : 缩放比例: 75 % + : 替代文本: LVGL 数据流程图 + : 对齐方式: 居中 + +示例： + +.. code-block:: c + + while(1) { + uint32_t time_till_next = lv_timer_handler(); + my_delay_ms(time_till_next); + } + +如果想在主循环中使用 :cpp:func:`lv_timer_handler` ，提供了一个辅助函数 :cpp:func:`lv_timer_handler_run_in_period` 来简化为 LVGL 提供时间感知的操作： + +.. code-block:: c + + while(1) { + ... + lv_timer_handler_run_in_period(5); /* run lv_timer_handler() every 5ms */ + ... + } + +或者使用由 LVGL 自动计算出的休眠时间： + +.. code-block:: c + + while(1) { + ... + lv_timer_periodic_handler(); + ... + } + +在操作系统环境中，可以将它与操作系统提供的 **延迟** 或 **休眠** 功能一起使用，以便在可能的情况下释放 CPU 资源： + +.. code-block:: c + + while (1) { + uint32_t time_till_next = lv_timer_handler(); + os_delay_ms(time_till_next); /* delay to avoid unnecessary polling */ + } + +要了解更多关于定时器的内容，请参阅 :ref:`timer` 部分。 API *** From 83f9eaf174ee421a715dec3eafc77e11abf81c3c Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Tue, 24 Dec 2024 19:06:39 +0800 Subject: [PATCH 06/10] docs: update basics.rst --- docs/intro/basics.rst | 447 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 404 insertions(+), 43 deletions(-) diff --git a/docs/intro/basics.rst b/docs/intro/basics.rst index 4f4b20bc..940dcab1 100644 --- a/docs/intro/basics.rst +++ b/docs/intro/basics.rst @@ -1,22 +1,33 @@ .. _lvgl_basics: -============================ -LVGL Basics（LVGL基础知识） -============================ +======================== +LVGL Basics（LVGL 基础） +======================== +.. raw:: html +
+ 显示原文 LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create an embedded GUI with easy-to-use graphical elements, beautiful visual effects, and a low memory footprint. How does it do this? +.. raw:: html +
+
+LVGL（轻量且通用的图形库）是一个免费的开源图形库，它提供了创建嵌入式图形用户界面（GUI）所需的一切，包含易于使用的图形元素、出色的视觉效果，并且占用内存少。 +它是如何做到这些的呢？ .. _basic_data_flow: -Overview of LVGL's Data Flow -**************************** +Overview of LVGL's Data Flow（LVGL 数据流概述） +********************************************** +.. raw:: html +
+ 显示原文 .. figure:: /misc/intro_data_flow.png :scale: 75 % :alt: LVGL Data Flow @@ -38,29 +49,58 @@ drives LVGL's timers which, in turn, perform all of LVGL's time-related tasks: - runs any animations, and - runs user-created timers. +.. raw:: html +
+
+ +.. 图:: /misc/intro_data_flow.png + : 缩放: 75% + : 替代文本: LVGL 数据流 + : 对齐: 居中 + : 图宽: 图像 + + LVGL 数据流概述 + +您为每个物理显示面板创建一个 :ref:`display`，在它们上面创建 :ref:`basics_screen_widgets`，再将 :ref:`basics_widgets` 添加到这些屏幕上。为了处理触摸、鼠标、键盘等输入，您要为每种输入 :ref:`create an Input Device `。:ref:`tick_interface` 会告知 LVGL 当前时间。:ref:`timer_handler` 驱动 LVGL 的定时器，这些定时器进而执行 LVGL 所有与时间相关的任务： + +- 定期刷新显示内容； +- 读取输入设备； +- 触发事件； +- 运行动画； +- 运行用户创建的定时器。 .. _applications_job: -Application's Job ------------------ +Application's Job（应用程序的任务） +---------------------------------- +.. raw:: html +
+ 显示原文 After initialization, the application's job is merely to create Widget Trees when they are needed, manage events those Widgets generate (by way of user interaction and other things), and delete them when they are no longer needed. LVGL takes care of the rest. +.. raw:: html - +
+
+初始化之后，应用程序的任务仅仅是在需要时创建部件树，管理这些部件因用户交互及其他情况而生成的事件，并在不再需要时删除它们。其余的工作则由 LVGL 负责。 .. _basics_major_concepts: -Major Concepts -************** +Major Concepts（主要概念） +************************** .. _display-vs-screen: -Display vs Screen ------------------ +Display vs Screen（显示（Display）与屏幕（Screen）） +--------------------------------------------------- +.. raw:: html + +
+ 显示原文 Before we get into any details about Widgets, let us first clarify the difference between two terms that you will hereafter see frequently: @@ -69,37 +109,74 @@ between two terms that you will hereafter see frequently: to be used by LVGL. - A **Screen** is the "root" Widget in the Widget Trees mentioned above, and are "attached to" a particular :ref:`display`. +.. raw:: html +
+
+在深入探讨部件的任何细节之前，让我们首先厘清两个你之后会频繁看到的术语之间的区别： -Default Display ---------------- +- **显示设备** 或 **显示面板** 是用于显示像素的物理硬件。 +- 一个 :ref:`display` 对象是内存中的一个对象，它代表一个供 LVGL 使用的 **显示设备**。 +- **屏幕** 是上述部件树中的 “根” 部件，并且 “依附于” 特定的 :ref:`display` 对象。 +Default Display（默认显示设备） +-------------------------------- +.. raw:: html + +
+ 显示原文 When the first :ref:`display` object is created, it becomes the Default Display. Many functions related to Screen Widgets use the default display. See :ref:`default_display` for more information. +.. raw:: html +
+
+当第一个 :ref:`display` 对象被创建时，它成为默认显示器。 +许多与屏幕小部件相关的功能使用默认显示器。 +有关更多信息，请参见 :ref:`default_display`。 .. _basics_screen_widgets: -Screen Widgets --------------- +Screen Widgets（屏幕部件） +--------------------------- +.. raw:: html + +
+ 显示原文 In this documentation, the term "Screen Widget" is frequently shortened to just "Screen". But it is important to understand that a "Screen" is simply any :ref:`Widget ` created without a parent --- the "root" of each Widget Tree. See :ref:`screens` for more details. +.. raw:: html +
+
+在本文档中，“屏幕小部件”一词经常缩写为“屏幕”。但重要的是要理解，“屏幕”只是任何没有父级的 :ref:`小部件 ` —— 每个小部件树的“根”。 -Active Screen -------------- +有关更多详细信息，请参见 :ref:`screens`。 +Active Screen（活动屏幕） +------------------------ +.. raw:: html +
+ 显示原文 The Active Screen is the screen (and its child Widgets) currently being displayed. See :ref:`active_screen` for more information. +.. raw:: html - +
+
+活动屏幕是当前显示的屏幕（及其子小部件）。 +有关更多信息，请参见 :ref:`active_screen`。 .. _basics_widgets: -Widgets -------- +Widgets（小部件） +------------------ +.. raw:: html + +
+ 显示原文 After LVGL is initialized (see :ref:`initializing_lvgl`), to create an interactive user interface, an application next creates a tree of Widgets that LVGL can render to the associated display, and with which the user can interact. @@ -149,12 +226,43 @@ RAM (e.g. for quick re-display again later). Doing so: If multiple Screens are maintained in RAM simultaneously, it is up to the system designer as to how they are managed. +.. raw:: html + +
+
+在初始化 LVGL 之后（参见 :ref:`initializing_lvgl`），为了创建一个交互式用户界面，应用程序接下来会创建一个小部件树，LVGL 可以将其渲染到相关显示器上，并与用户进行交互。 + +小部件是“智能”的 LVGL 图形元素，例如 :ref:`基本小部件 `（简单的矩形和 :ref:`屏幕`）、按钮、标签、复选框、开关、滑块、图表等。请参见 :ref:`widgets` 以查看完整列表。 + +为了构建这个小部件树，应用程序首先获取一个屏幕小部件的指针。系统设计人员可以自由使用与 :ref:`display` 一起创建的默认屏幕和/或创建自己的屏幕。要创建一个新的屏幕小部件，只需在创建小部件时将父级参数传递为 NULL。从技术上讲，这可以是任何类型的小部件，但在大多数情况下，它是一个 :ref:`基本小部件 `。（另一种用作屏幕的小部件类型的示例是 :ref:`lv_image` 小部件，用于提供背景图像。） + +然后，应用程序将小部件作为树中的子节点添加到这个屏幕中。小部件在创建时会自动作为子节点添加到其父小部件中——小部件的父级作为创建小部件的函数的第一个参数传递。添加后，我们说父小部件“包含”子小部件。 + +任何小部件都可以包含其他小部件。例如，如果您希望按钮具有文本，请创建一个标签小部件并将其作为子节点添加到按钮中。 + +每个子小部件都成为其父小部件的“一部分”。由于这种关系： +- 当父小部件移动时，其子小部件也会随之移动； +- 当父小部件被删除时，其子小部件也会随之删除； +- 子小部件仅在其父小部件的边界内可见；任何超出父小部件边界的子小部件部分都会被裁剪（即不渲染）。 +屏幕（及其子小部件）可以在任何时候创建和删除 *除了* 当屏幕是 :ref:`活动屏幕 ` 时。如果您想在加载新屏幕时删除当前屏幕，请调用 :cpp:func:`lv_screen_load_anim` 并为 ``auto_del`` 参数传递 ``true``。如果您想在加载新屏幕时将当前屏幕保留在 RAM 中，请为 ``auto_del`` 参数传递 ``false``，或调用 :cpp:func:`lv_screen_active` 以加载新屏幕。 + +系统设计人员可以自由地在 RAM 中保留任意数量的屏幕（及其子小部件）（例如，以便稍后快速重新显示）。这样做： + +- 需要更多的 RAM，但 +- 可以节省反复创建屏幕及其子小部件的时间； +- 当屏幕复杂且/或可以频繁成为 :ref:`活动屏幕 ` 时，这会很方便。 + +如果多个屏幕同时保存在 RAM 中，系统设计人员可以自行决定如何管理它们。 .. _basics_creating_widgets: -Creating Widgets -~~~~~~~~~~~~~~~~ +Creating Widgets（创建小部件） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ 显示原文 Widgets are created by calling functions that look like this:: lv__create(parent) @@ -167,12 +275,29 @@ For example: .. code-block:: c lv_obj_t * slider1 = lv_slider_create(lv_screen_active()); +.. raw:: html + +
+
+小部件是通过调用如下函数创建的:: + + lv__create(parent) + +该调用将返回一个 :cpp:type:`lv_obj_t` ``*`` 指针，稍后可以使用该指针引用小部件以设置其属性。 + +例如： +.. code-block:: c + lv_obj_t * slider1 = lv_slider_create(lv_screen_active()); .. _basics_modifying_widgets: -Modifying Widgets -~~~~~~~~~~~~~~~~~ +Modifying Widgets（修改小部件） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ 显示原文 Attributes common to all Widgets are set by functions that look like this:: lv_obj_set_(widget, ) @@ -205,21 +330,67 @@ or view it on GitHub, e.g. - https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/lv_slider.h . +.. raw:: html + +
+
+所有小部件的通用属性通过如下函数设置:: + + lv_obj_set_(widget, ) + +例如： + +.. code-block:: c + + lv_obj_set_x(slider1, 30); + lv_obj_set_y(slider1, 10); + lv_obj_set_size(slider1, 200, 50); + +除了这些属性，小部件还可以有特定类型的属性，这些属性通过如下函数设置:: + + lv__set_(widget, ) + +例如： + +.. code-block:: c + lv_slider_set_value(slider1, 70, LV_ANIM_ON); + +要查看完整的 API，请访问相关小部件的文档，参见 :ref:`widgets` 或研究源代码中的相关头文件，例如： + +- lvgl/src/widgets/slider/lv_slider.h + +或在 GitHub 上查看，例如： + +- https://github.com/lvgl/lvgl/blob/master/src/widgets/slider/lv_slider.h 。 .. _basics_deleting_widgets: -Deleting Widgets -~~~~~~~~~~~~~~~~ +Deleting Widgets（删除小部件） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ 显示原文 To delete any widget and its children:: lv_obj_delete(lv_obj_t * widget) +.. raw:: html +
+
+要删除任何小部件及其子小部件:: + + lv_obj_delete(lv_obj_t * widget) .. _basics_events: -Events ------- +Events（事件） +-------------- +.. raw:: html + +
+ 显示原文 Events are used to inform the application that something has happened with a Widget. You can assign one or more callbacks to a Widget which will be called when the @@ -258,13 +429,49 @@ The Widget that triggered the event can be retrieved with: lv_obj_t * obj = lv_event_get_target(e); To learn all features of the events go to the :ref:`events` section. +.. raw:: html + +
+
+事件用于通知应用程序某个小部件发生了某些事情。 +您可以为小部件分配一个或多个回调，当小部件被点击、释放、拖动、删除等时，这些回调将被调用。 + +回调的分配方式如下： + +.. code-block:: c + + lv_obj_add_event_cb(btn, my_btn_event_cb, LV_EVENT_CLICKED, NULL); + + ... + + void my_btn_event_cb(lv_event_t * e) + { + printf("Clicked\n"); + } + +:cpp:enumerator:`LV_EVENT_ALL` 可以用来代替 :cpp:enumerator:`LV_EVENT_CLICKED` 以调用所有事件的回调。（注意：事件非常多！这对于调试或了解给定小部件发生了哪些事件很有用，或者如果应用程序由于某种原因需要处理所有事件，也很有用。） + +事件回调接收参数 :cpp:expr:`lv_event_t * e`，其中包含当前事件代码和其他与事件相关的信息。可以使用以下代码检索当前事件代码： + +.. code-block:: c + + lv_event_code_t code = lv_event_get_code(e); + +可以使用以下代码检索触发事件的小部件： + +.. code-block:: c + lv_obj_t * obj = lv_event_get_target(e); +要了解事件的所有功能，请参见 :ref:`events` 部分。 .. _basics_parts: -Parts ------ +Parts（部件） +------------- +.. raw:: html +
+ 显示原文 Widgets are built from one or more *parts*. For example, a button has only one part called :cpp:enumerator:`LV_PART_MAIN`. However, a :ref:`lv_slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR` @@ -273,13 +480,23 @@ and :cpp:enumerator:`LV_PART_KNOB`. By using parts you can apply different styles to sub-elements of a widget. (See below.) Read the Widget's documentation to learn which parts it uses. +.. raw:: html +
+
+小部件由一个或多个*部件*构成。例如，一个按钮只有一个部件，称为 :cpp:enumerator:`LV_PART_MAIN`。然而，一个 :ref:`lv_slider` 有 :cpp:enumerator:`LV_PART_MAIN`、:cpp:enumerator:`LV_PART_INDICATOR` 和 :cpp:enumerator:`LV_PART_KNOB`。 +通过使用部件，您可以将不同的样式应用于小部件的子元素。（见下文。） + +阅读小部件的文档以了解它使用了哪些部件。 .. _basics_states: -States ------- +States（状态） +--------------- +.. raw:: html +
+ 显示原文 Widgets can be in a combination of the following states: - :cpp:enumerator:`LV_STATE_DEFAULT`: Normal, released state @@ -307,13 +524,40 @@ To manually add or remove states use: lv_obj_add_state(widget, LV_STATE_...); lv_obj_remove_state(widget, LV_STATE_...); +.. raw:: html +
+
+小部件可以处于以下状态的组合中： +- :cpp:enumerator:`LV_STATE_DEFAULT`: 正常，释放状态 +- :cpp:enumerator:`LV_STATE_CHECKED`: 切换或选中状态 +- :cpp:enumerator:`LV_STATE_FOCUSED`: 通过键盘或编码器聚焦或通过触摸板/鼠标点击 +- :cpp:enumerator:`LV_STATE_FOCUS_KEY`: 通过键盘或编码器聚焦，但不通过触摸板/鼠标 +- :cpp:enumerator:`LV_STATE_EDITED`: 通过编码器编辑 +- :cpp:enumerator:`LV_STATE_HOVERED`: 被鼠标悬停 +- :cpp:enumerator:`LV_STATE_PRESSED`: 正在被按下 +- :cpp:enumerator:`LV_STATE_SCROLLED`: 正在滚动 +- :cpp:enumerator:`LV_STATE_DISABLED`: 禁用 + +例如，如果按下一个小部件，它将自动进入 :cpp:enumerator:`LV_STATE_FOCUSED` 和 :cpp:enumerator:`LV_STATE_PRESSED` 状态，当你释放它时，:cpp:enumerator:`LV_STATE_PRESSED` 状态将被移除，而 :cpp:enumerator:`LV_STATE_FOCUSED` 状态仍然保持活动。 + +要检查小部件是否处于给定状态，请使用 :cpp:expr:`lv_obj_has_state(widget, LV_STATE_...)`。如果小部件当前处于该状态，它将返回 ``true``。 + +要手动添加或移除状态，请使用： + +.. code-block:: c + + lv_obj_add_state(widget, LV_STATE_...); + lv_obj_remove_state(widget, LV_STATE_...); .. _basics_styles: -Styles ------- +Styles（样式） +-------------- +.. raw:: html +
+ 显示原文 A style instance contains properties such as background color, border width, font, etc. that describe the appearance of Widgets. @@ -386,25 +630,95 @@ style which resides inside the Widget and is used only by that Widget: lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED); To learn all the features of styles see :ref:`styles`. +.. raw:: html + +
+
+样式实例包含描述小部件外观的属性，例如背景颜色、边框宽度、字体等。 + +样式保存在 :cpp:struct:`lv_style_t` 对象中。只有它们的指针保存在小部件中，因此需要将它们定义为静态或全局变量。在使用样式之前，需要使用 :cpp:expr:`lv_style_init(&style1)` 进行初始化。之后，可以添加属性来配置样式。例如： + +.. code-block:: c + + static lv_style_t style1; + lv_style_init(&style1); + lv_style_set_bg_color(&style1, lv_color_hex(0xa03080)) + lv_style_set_border_width(&style1, 2)) + +有关更多详细信息，请参见 :ref:`style_properties_overview`。 + +要查看完整列表，请参见 :ref:`style_properties`。 + +样式是通过小部件的部件和状态的按位或组合来分配的。例如，要在滑块被按下时将此样式用于滑块的指示器： + +.. code-block:: c + + lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR | LV_STATE_PRESSED); + +如果 *part* 是 :cpp:enumerator:`LV_PART_MAIN`，则可以省略： + +.. code-block:: c + + lv_obj_add_style(btn1, &style1, LV_STATE_PRESSED); /* 等同于 LV_PART_MAIN | LV_STATE_PRESSED */ + +同样，:cpp:enumerator:`LV_STATE_DEFAULT` 也可以省略： + +.. code-block:: c + + lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR); /* 等同于 LV_PART_INDICATOR | LV_STATE_DEFAULT */ + +对于 :cpp:enumerator:`LV_STATE_DEFAULT` | :cpp:enumerator:`LV_PART_MAIN`，只需传递 ``0``： + +.. code-block:: c + + lv_obj_add_style(btn1, &style1, 0); /* 等同于 LV_PART_MAIN | LV_STATE_DEFAULT */ +样式可以级联（类似于 CSS）。这意味着您可以向小部件的某个部件添加更多样式。例如 ``style_btn`` 可以设置默认按钮外观，而 ``style_btn_red`` 可以覆盖背景颜色使按钮变红： +.. code-block:: c + + lv_obj_add_style(btn1, &style_btn, 0); + lv_obj_add_style(btn1, &style1_btn_red, 0); + +如果当前状态未设置某个属性，则将使用 :cpp:enumerator:`LV_STATE_DEFAULT` 的样式。如果在默认状态下未定义该属性，则使用默认值。 + +某些属性（特别是与文本相关的属性）可以继承。这意味着如果在小部件中未设置某个属性，它将在其父级中搜索。例如，您可以在屏幕的样式中设置一次字体，屏幕上的所有文本将默认继承它。 + +本地样式属性也可以添加到小部件中。这会创建一个驻留在小部件内部并且仅由该小部件使用的样式： + +.. code-block:: c + + lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED); + +要了解样式的所有功能，请参见 :ref:`styles`。 .. _basics_themes: -Themes ------- +Themes（主题） +--------------- +.. raw:: html +
+ 显示原文 Themes are the default styles for Widgets. Styles from a theme are applied automatically when Widgets are created. The theme for your application is a compile time configuration set in ``lv_conf.h``. +.. raw:: html +
+
+主题是小部件的默认样式。主题中的样式在创建小部件时会自动应用。 +应用程序的主题是在 ``lv_conf.h`` 中设置的编译时配置。 .. _basics_micropython: MicroPython ----------- +.. raw:: html +
+ 显示原文 LVGL can even be used with :ref:`micropython`. .. code-block:: python @@ -421,13 +735,33 @@ LVGL can even be used with :ref:`micropython`. label.set_text('Hello World!') lv.screen_load(scr) +.. raw:: html + +
+
+LVGL 甚至可以与 :ref:`micropython` 一起使用。 +.. code-block:: python + + # 初始化 + import display_driver + import lvgl as lv + # 创建一个带标签的按钮 + scr = lv.obj() + btn = lv.button(scr) + btn.align(lv.ALIGN.CENTER, 0, 0) + label = lv.label(btn) + label.set_text('Hello World!') + lv.screen_load(scr) .. _going_deeper: -Going Deeper -************* +Going Deeper（深入了解） +************************ +.. raw:: html +
+ 显示原文 There are several good ways ways to gain deeper knowledge of LVGL. Here is one recommended order of documents to read and things to play with while you are advancing your knowledge: @@ -450,13 +784,34 @@ advancing your knowledge: .. _ready-to-use projects: https://github.com/lvgl?q=lv_port_&type=&language= .. _forum: https://forum.lvgl.io/ - - +.. raw:: html + +
+
+有几种很好的方法可以深入了解 LVGL。以下是推荐的阅读文档顺序和在您提高知识时可以尝试的内容： + +1. 如果还没有阅读，请从文档的 :ref:`introduction` 页面开始。（5 分钟） +2. 查看 `在线演示`_ 以了解 LVGL 的实际应用。（3 分钟） +3. 如果还没有完成，请阅读 :ref:`lvgl_basics`（上文）。（15 分钟） +4. 设置一个 LVGL :ref:`simulator`。（10 分钟） +5. 看看一些 :ref:`examples` 及其代码。 +6. 将 LVGL 添加到您的项目中。参见 :ref:`add_lvgl_to_your_project` 或查看 `现成的项目`_。 +7. 阅读 :ref:`main_components` 页面以更好地理解该库。（2-3 小时） +8. 浏览 :ref:`widgets` 的文档以了解可用的内容。 +9. 如果有问题，请访问 `论坛`_。 +10. 阅读 :ref:`contributing` 指南，了解如何帮助改进 LVGL。（15 分钟） + +.. _在线演示: https://lvgl.io/demos +.. _现成的项目: https://github.com/lvgl?q=lv_port_&type=&language= +.. _论坛: https://forum.lvgl.io/ .. _basics_examples: -Basic Examples -************** +Basic Examples（基本示例） +************************** +.. raw:: html +
+ 显示原文 Below are several basic examples. They include the application code that produces the Widget Tree needed to make LVGL render the examples shown. Each example assumes a LVGL has undergone normal initialization, meaning that a ``lv_display_t`` object @@ -465,4 +820,10 @@ was created and therefore has an :ref:`active_screen`. .. include:: ../examples/get_started/index.rst +.. raw:: html + +
+
+以下是几个基本示例。它们包含生成小部件树的应用程序代码，以使 LVGL 渲染所示示例。每个示例都假设 LVGL 已经进行了正常初始化，这意味着创建了一个 ``lv_display_t`` 对象，因此有一个 :ref:`active_screen`。 +.. include:: ../examples/get_started/index.rst \ No newline at end of file From 71117d7def35b20abf9af2edf968b039a78e9f11 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Tue, 24 Dec 2024 19:07:36 +0800 Subject: [PATCH 07/10] docs: update index.rst --- docs/intro/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/intro/index.rst b/docs/intro/index.rst index a5e6ea74..72a9930b 100644 --- a/docs/intro/index.rst +++ b/docs/intro/index.rst @@ -2,10 +2,17 @@ Introduction（介绍） ==================== +.. raw:: html +
+ 显示原文 .. toctree:: :maxdepth: 1 introduction basics add-lvgl-to-your-project/index +.. raw:: html + +
+
\ No newline at end of file From 80439fabdbd74e39c0139c79f10d14f592e60b8a Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Tue, 24 Dec 2024 19:22:48 +0800 Subject: [PATCH 08/10] docs: update introduction.rst --- docs/intro/introduction.rst | 422 ++++++++++++++++++++++++++++++------ 1 file changed, 357 insertions(+), 65 deletions(-) diff --git a/docs/intro/introduction.rst b/docs/intro/introduction.rst index dc8450be..a76b0a04 100644 --- a/docs/intro/introduction.rst +++ b/docs/intro/introduction.rst @@ -3,15 +3,24 @@ ==================== Introduction（介绍） ==================== +.. raw:: html +
+ 显示原文 LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create an embedded GUI with easy-to-use graphical elements, beautiful visual effects, and a low memory footprint. +.. raw:: html +
+
+LVGL（轻量且多功能的图形库）是一个免费且开源的图形库，提供了创建嵌入式 GUI 所需的一切，包括易于使用的图形元素、美丽的视觉效果和低内存占用。 +Key features（主要特性） +------------------------- +.. raw:: html -Key features ------------- - +
+ 显示原文 - Powerful building blocks such as :ref:`buttons, charts, lists, sliders, images `, etc. - Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling - Various input devices such as touchpad, mouse, keyboard, encoder, etc. @@ -29,13 +38,35 @@ Key features - Tutorials, examples, themes for rapid GUI design - Documentation is available online - Free and open-source under MIT license - - +.. raw:: html + +
+
+- 强大的构建模块，例如 :ref:`按钮、图表、列表、滑块、图像 ` 等。 +- 具有动画、抗锯齿、不透明度、平滑滚动的高级图形 +- 各种输入设备，如触摸板、鼠标、键盘、编码器等 +- 支持多语言，采用 UTF-8 编码 +- 支持多显示器，甚至支持混合颜色格式 +- 完全可定制的图形元素，具有类似 CSS 的样式 +- 硬件无关：可与任何微控制器或显示器一起使用 +- 可扩展：能够在内存较少的情况下运行（64 kB Flash，16 kB RAM） +- 支持但不要求 :ref:`操作系统 `、外部内存和 :ref:`GPU ` +- 即使使用高级图形效果也能进行单帧缓冲操作 +- 用 C 语言编写，以实现最大兼容性（兼容 C++） +- :ref:`模拟器 ` 可在没有嵌入式硬件的 PC 上开始嵌入式 GUI 设计 +- 在模拟器下开发的用户代码可以与固件共享，使 UI 开发更高效 +- 绑定到 :ref:`MicroPython` +- 教程、示例、主题，用于快速 GUI 设计 +- 文档可在线获取 +- 在 MIT 许可证下免费开源 .. _requirements: -Requirements ------------- +Requirements（要求） +-------------------- +.. raw:: html +
+ 显示原文 Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are: * 16, 32 or 64 bit microcontroller or processor @@ -56,11 +87,36 @@ Basically, every modern controller which is able to drive a display is suitable .. note:: *Memory usage may vary depending on architecture, compiler and build options.* +.. raw:: html + +
+
+基本上，任何能够驱动显示器的现代控制器都适合运行 LVGL。最低要求是： + +* 16、32 或 64 位微控制器或处理器 +* 推荐 > 16 MHz 时钟速度 +* Flash/ROM：> 64 kB 用于非常基本的组件（推荐 > 180 kB） +* RAM： + * 静态 RAM 使用量：~2 kB，具体取决于使用的功能和小部件类型 + * 栈：> 2 kB（推荐 > 8 kB） + * 动态数据（堆）：> 2 kB（如果使用许多 GUI 小部件，推荐 > 48 kB）。 + 通过 ``lv_conf.h`` 中的 :c:macro:`LV_MEM_SIZE` 设置。 + * 显示缓冲区：> *“水平分辨率”* 像素（推荐 > 10 倍 *“水平分辨率”*） + * MCU 或外部显示控制器中的一个帧缓冲区 +* C99 或更新的编译器 +* 基本的 C（或 C++）知识： + * `指针 `__。 + * `结构体 `__。 + * `回调 `__。 +.. note:: + *内存使用量可能因架构、编译器和构建选项而异。* +License（许可证） +---------------- +.. raw:: html -License -------- - +
+ 显示原文 The LVGL project (including all repositories) is licensed under the `MIT license `__. This means you can use it even in commercial projects. @@ -70,11 +126,25 @@ Although you can get LVGL for free there is a massive amount of work behind it. To make the LVGL project sustainable, please consider :ref:`contributing` to the project. You can choose from many different ways of contributing See :ref:`contributing` such as simply writing a tweet about you using LVGL, fixing bugs, translating the documentation, or even becoming a maintainer. +.. raw:: html +
+
+LVGL 项目（包括所有代码库）是根据 `MIT 许可证 `__ 授权的。 +这意味着您甚至可以在商业项目中使用它。 -Repository layout ------------------ +这不是强制性的，但如果您能在论坛的 `我的项目 `__ 类别中写几句话介绍您的项目，或者发送私人消息给 `lvgl.io `__，我们将不胜感激。 +虽然您可以免费获得 LVGL，但其背后有大量的工作。这是由一群志愿者在他们的空闲时间为您提供的。 + +为了使 LVGL 项目可持续发展，请考虑 :ref:`贡献` 给该项目。 +您可以选择多种不同的方式进行贡献，参见 :ref:`贡献`，例如简单地发一条关于您使用 LVGL 的推文、修复错误、翻译文档，甚至成为维护者。 +Repository layout（代码库布局） +--------------------------------- +.. raw:: html + +
+ 显示原文 All repositories of the LVGL project are hosted on `GitHub `_. You will find these repositories there: @@ -85,11 +155,26 @@ You will find these repositories there: * `sim `__: Source of the `online simulator's site `__ * `lv_port_* `__: LVGL ports to development boards or environments * `lv_binding_* `__: Bindings to other languages - - -Release policy --------------- - +.. raw:: html + +
+
+LVGL 项目的所有代码库都托管在 `GitHub `_ 上。 + +您可以在那里找到这些代码库： + +* `lvgl `__: 库本身，包含许多 `示例 `_ 和 `演示 `__。 +* `lv_drivers `__: 显示和输入设备驱动程序 +* `blog `__: `博客网站 `__ 的源码 +* `sim `__: `在线模拟器网站 `__ 的源码 +* `lv_port_* `__: LVGL 移植到开发板或环境 +* `lv_binding_* `__: 绑定到其他语言 +Release policy（发布政策） +---------------------------- +.. raw:: html + +
+ 显示原文 The core repositories follow the rules of `Semantic Versioning `__: * Major version: incompatible API changes. E.g. v5.0.0, v6.0.0 @@ -97,36 +182,75 @@ The core repositories follow the rules of `Semantic Versioning +
+核心代码库遵循 `语义化版本控制 `__ 的规则： -Release cycle -^^^^^^^^^^^^^ +* 主版本：不兼容的 API 更改。例如 v5.0.0，v6.0.0 +* 次版本：新的但向后兼容的功能。例如 v6.1.0，v6.2.0 +* 补丁版本：向后兼容的错误修复。例如 v6.1.1，v6.1.2 +每次发布都会创建类似 `vX.Y.Z` 的标签。 +Release cycle（发布周期） +^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 * Bug fixes: released on demand even weekly * Minor releases: every 3-4 months * Major releases: approximately yearly +.. raw:: html -Branches -^^^^^^^^ +
+
+* 错误修复：根据需求发布，甚至每周发布 +* 次版本发布：每 3-4 个月 +* 主版本发布：大约每年一次 +Branches（分支） +^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 The core repositories have at least the following branches: * `master`: latest version, patches are merged directly here * `release/vX.Y`: stable versions of the minor releases * `fix/some-description`: temporary branches for bug fixes * `feat/some-description`: temporary branches for features - - -Change log -^^^^^^^^^^ - +.. raw:: html + +
+
+核心代码库至少有以下分支： + +* `master`：最新版本，补丁直接合并到这里 +* `release/vX.Y`：次版本发布的稳定版本 +* `fix/some-description`：用于错误修复的临时分支 +* `feat/some-description`：用于新功能的临时分支 +Change log（变更日志） +^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 The changes are recorded in :ref:`changelog`. +.. raw:: html -Version support -^^^^^^^^^^^^^^^ +
+
+变更记录在 :ref:`changelog` 中。 +Version support（版本支持） +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 Before v8 the last minor release of each major series was supported for 1 year. Starting from v8, every minor release is supported for 1 year. @@ -156,25 +280,69 @@ Starting from v8, every minor release is supported for 1 year. +---------+--------------+--------------+--------+ |v9.2 | Aug 26, 2024 | Aug 26, 2025 | Yes | +---------+--------------+--------------+--------+ +.. raw:: html +
+
+在 v8 之前，每个主要系列的最后一个次版本发布支持 1 年。 +从 v8 开始，每个次版本发布支持 1 年。 -FAQ ---- ++---------+--------------+--------------+--------+ +| 版本 | 发布日期 | 支持结束 | 活跃 | ++=========+==============+==============+========+ +|v5.3 | 2019年2月1日 | 2020年2月1日 | 否 | ++---------+--------------+--------------+--------+ +|v6.1 | 2019年11月26日| 2020年11月26日| 否 | ++---------+--------------+--------------+--------+ +|v7.11 | 2021年3月16日 | 2022年3月16日 | 否 | ++---------+--------------+--------------+--------+ +|v8.0 | 2021年6月1日 | 2022年6月1日 | 否 | ++---------+--------------+--------------+--------+ +|v8.1 | 2021年11月10日| 2022年11月10日| 否 | ++---------+--------------+--------------+--------+ +|v8.2 | 2022年1月31日 | 2023年1月31日 | 否 | ++---------+--------------+--------------+--------+ +|v8.3 | 2022年7月6日 | 2025年1月1日 | 是 | ++---------+--------------+--------------+--------+ +|v8.4 | 2024年3月19日 | 2025年3月20日 | 是 | ++---------+--------------+--------------+--------+ +|v9.0 | 2024年1月22日 | 2025年1月22日 | 是 | ++---------+--------------+--------------+--------+ +|v9.1 | 2024年3月20日 | 2025年3月20日 | 是 | ++---------+--------------+--------------+--------+ +|v9.2 | 2024年8月26日 | 2025年8月26日 | 是 | ++---------+--------------+--------------+--------+ +FAQ（常见问题） +---------------- -Where can I ask questions? -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Where can I ask questions?（我在哪里提问？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 You can ask questions in the forum: https://forum.lvgl.io/. We use `GitHub issues `_ for development related discussion. You should use them only if your question or issue is tightly related to the development of the library. Before posting a question, please read this FAQ section since you might find the answer to your issue here as well. +.. raw:: html + +
+
+您可以在论坛提问：https://forum.lvgl.io/。 +我们使用 `GitHub issues `_ 进行与开发相关的讨论。 +只有当您的问题或问题与库的开发紧密相关时，才应使用它们。 -Is my MCU/hardware supported? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +在发布问题之前，请阅读此常见问题解答部分，因为您可能会在这里找到问题的答案。 +Is my MCU/hardware supported?（我的 MCU/硬件受支持吗？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 Every MCU which is capable of driving a display via parallel port, SPI, RGB interface or anything else and fulfills the :ref:`requirements` is supported by LVGL. This includes: @@ -183,11 +351,24 @@ This includes: * Bluetooth, GSM, Wi-Fi modules like Nordic NRF, Espressif ESP32 and Raspberry Pi Pico W * Linux with frame buffer device such as /dev/fb0. This includes Single-board computers like the Raspberry Pi * Anything else with a strong enough MCU and a peripheral to drive a display +.. raw:: html +
+
+每个能够通过并行端口、SPI、RGB 接口或其他方式驱动显示器并满足 :ref:`要求` 的 MCU 都受 LVGL 支持。 -Is my display supported? -^^^^^^^^^^^^^^^^^^^^^^^^ +这包括： + +* “常见” MCU，如 STM32F、STM32H、NXP Kinetis、LPC、iMX、dsPIC33、PIC32、SWM341 等。 +* 蓝牙、GSM、Wi-Fi 模块，如 Nordic NRF、Espressif ESP32 和 Raspberry Pi Pico W +* 带有帧缓冲设备（如 /dev/fb0）的 Linux。这包括像 Raspberry Pi 这样的单板计算机 +* 任何其他具有足够强大 MCU 和驱动显示器的外设的设备 +Is my display supported?（我的显示器受支持吗？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 LVGL needs just one simple driver function to copy an array of pixels into a given area of the display. If you can do this with your display then you can use it with LVGL. @@ -201,11 +382,29 @@ Some examples of the supported display types: * or any other display where you can control the color/state of the pixels See the :ref:`display` section to learn more. +.. raw:: html +
+
+LVGL 只需要一个简单的驱动函数将像素数组复制到显示器的给定区域。 +如果您的显示器可以做到这一点，那么您就可以在 LVGL 中使用它。 -LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +一些受支持的显示器类型示例： +* 具有 16 位或 24 位色深的 TFT +* 带有 HDMI 端口的显示器 +* 小型单色显示器 +* 灰度显示器 +* 甚至 LED 矩阵 +* 或任何其他您可以控制像素颜色/状态的显示器 + +请参阅 :ref:`display` 部分以了解更多信息。 +LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem?（LVGL 不启动、随机崩溃或显示器上没有任何内容。可能的问题是什么？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 * Try increasing :c:macro:`LV_MEM_SIZE`. * Be sure your display works without LVGL. E.g. paint it to red on start up. * Enable :ref:`logging`. @@ -213,28 +412,54 @@ LVGL doesn't start, randomly crashes or nothing is drawn on the display. What ca * If you use an RTOS: * Increase the stack size of the task that calls :cpp:func:`lv_timer_handler`. * Be sure you are using one of the methods for thread management as described in :ref:`threading`. - - -My display driver is not called. What have I missed? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +.. raw:: html + +
+
+* 尝试增加 :c:macro:`LV_MEM_SIZE`。 +* 确保您的显示器在没有 LVGL 的情况下工作。例如，在启动时将其涂成红色。 +* 启用 :ref:`日志记录`。 +* 在 ``lv_conf.h`` 中启用断言（``LV_USE_ASSERT_...``）。 +* 如果您使用 RTOS： + * 增加调用 :cpp:func:`lv_timer_handler` 的任务的堆栈大小。 + * 确保您使用的是 :ref:`线程管理 ` 中描述的方法之一。 +My display driver is not called. What have I missed?（我的显示驱动程序没有被调用。我错过了什么？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 Be sure you are calling :cpp:expr:`lv_tick_inc(x)` as prescribed in :ref:`tick_interface` and are calling :cpp:func:`lv_timer_handler` as prescribed in :ref:`timer_handler`. Learn more in the :ref:`tick_interface` and :ref:`timer_handler` sections. +.. raw:: html +
+
+确保您按照 :ref:`tick_interface` 中的规定调用 :cpp:expr:`lv_tick_inc(x)`，并按照 :ref:`timer_handler` 中的规定调用 :cpp:func:`lv_timer_handler`。 -Why is the display driver called only once? Only the upper part of the display is refreshed. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +在 :ref:`tick_interface` 和 :ref:`timer_handler` 部分了解更多信息。 +Why is the display driver called only once? Only the upper part of the display is refreshed.（为什么显示驱动程序只被调用一次？只有显示器的上部分被刷新。） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 Be sure you are calling :cpp:expr:`lv_display_flush_ready(drv)` at the end of your "*display flush callback*" as per :ref:`flush_callback` section. +.. raw:: html +
+
+确保您在 "*显示刷新回调*" 的末尾调用 :cpp:expr:`lv_display_flush_ready(drv)`，如 :ref:`flush_callback` 部分所述。 +Why do I see only garbage on the screen?（为什么我只看到屏幕上的垃圾？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html -Why do I see only garbage on the screen? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +
+ 显示原文 There is probably a bug in your display driver. Try the following code without using LVGL. You should see a square with red-blue gradient. .. code-block:: c @@ -259,46 +484,113 @@ There is probably a bug in your display driver. Try the following code without u a.x2 = a.x1 + BUF_W - 1; a.y2 = a.y1 + BUF_H - 1; my_flush_cb(NULL, &a, buf); +.. raw:: html +
+
+您的显示驱动程序可能有错误。尝试以下代码而不使用 LVGL。您应该会看到一个红蓝渐变的方块。 -Why do I see nonsense colors on the screen? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: c -The configured LVGL color format is probably not compatible with your display's color format. Check :c:macro:`LV_COLOR_DEPTH` in *lv_conf.h*. + #define BUF_W 20 + #define BUF_H 10 + lv_color_t buf[BUF_W * BUF_H]; + lv_color_t * buf_p = buf; + uint16_t x, y; + for(y = 0; y < BUF_H; y++) { + lv_color_t c = lv_color_mix(LV_COLOR_BLUE, LV_COLOR_RED, (y * 255) / BUF_H); + for(x = 0; x < BUF_W; x++){ + (*buf_p) = c; + buf_p++; + } + } -How do I speed up my UI? -^^^^^^^^^^^^^^^^^^^^^^^^ + lv_area_t a; + a.x1 = 10; + a.y1 = 40; + a.x2 = a.x1 + BUF_W - 1; + a.y2 = a.y1 + BUF_H - 1; + my_flush_cb(NULL, &a, buf); +Why do I see nonsense colors on the screen?（为什么我在屏幕上看到无意义的颜色？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 +The configured LVGL color format is probably not compatible with your display's color format. Check :c:macro:`LV_COLOR_DEPTH` in *lv_conf.h*. +.. raw:: html + +
+
+配置的 LVGL 颜色格式可能与您的显示器颜色格式不兼容。请检查 *lv_conf.h* 中的 :c:macro:`LV_COLOR_DEPTH`。 +How do I speed up my UI?（如何加速我的 UI？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 - Turn on compiler optimization and enable instruction- and data-caching if your MCU has them. - Increase the size of the display buffer. - Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background. - Increase the clock speed of the SPI or parallel port if you use them to drive the display. - If your display has an SPI port consider changing to a model with a parallel interface because it has much higher throughput. - Keep the display buffer in internal RAM (not in external SRAM) because LVGL uses it a lot and it should have fast access time. - - -How do I reduce flash/ROM usage? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +.. raw:: html + +
+
+- 打开编译器优化，并启用指令和数据缓存（如果您的 MCU 具有这些功能）。 +- 增加显示缓冲区的大小。 +- 使用两个显示缓冲区，并在后台使用 DMA（或类似外设）刷新缓冲区。 +- 如果您使用 SPI 或并行端口驱动显示器，请提高其时钟速度。 +- 如果您的显示器有 SPI 端口，考虑更换为具有并行接口的型号，因为它具有更高的吞吐量。 +- 将显示缓冲区保存在内部 RAM 中（而不是外部 SRAM），因为 LVGL 经常使用它，并且它应该具有快速的访问时间。 +How do I reduce flash/ROM usage?（如何减少 Flash/ROM 使用量？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 You can disable unused features (such as animations, file system, GPU etc.) and widget types in *lv_conf.h*. If you are using GCC/CLANG you can add `-fdata-sections -ffunction-sections` compiler flags and `--gc-sections` linker flag to remove unused functions and variables from the final binary. If possible, add the `-flto` compiler flag to enable link-time-optimisation together with `-Os` for GCC or `-Oz` for CLANG. +.. raw:: html +
+
+您可以在 *lv_conf.h* 中禁用未使用的功能（例如动画、文件系统、GPU 等）和小部件类型。 -How do I reduce RAM usage? -^^^^^^^^^^^^^^^^^^^^^^^^^^ +如果您使用的是 GCC/CLANG，可以添加 `-fdata-sections -ffunction-sections` 编译器标志和 `--gc-sections` 链接器标志，以从最终二进制文件中删除未使用的函数和变量。如果可能，添加 `-flto` 编译器标志以启用链接时优化，并结合 `-Os`（用于 GCC）或 `-Oz`（用于 CLANG）。 +How do I reduce RAM usage?（如何减少 RAM 使用量？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html +
+ 显示原文 * Lower the size of the *Display buffer*. * Reduce :c:macro:`LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create Widgets like buttons, labels, etc. * To work with lower :c:macro:`LV_MEM_SIZE` you can create Widgets only when required and delete them when they are not needed anymore. - - -How do I use LVGL with an operating system? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +.. raw:: html + +
+
+* 降低 *显示缓冲区* 的大小。 +* 减少 *lv_conf.h* 中的 :c:macro:`LV_MEM_SIZE`。这部分内存在创建按钮、标签等小部件时使用。 +* 为了使用较低的 :c:macro:`LV_MEM_SIZE`，您可以在需要时创建小部件，并在不再需要时删除它们。 +How do I use LVGL with an operating system?（如何在操作系统中使用 LVGL？） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. raw:: html + +
+ 显示原文 To work with an operating system where tasks can interrupt each other (preemptively), you must ensure that no LVGL function call be called while another LVGL call is in progress. There are several ways to do this. See the :ref:`threading` section to learn more. +.. raw:: html + +
+
+在任务可以相互中断（抢占式）的操作系统中工作时，必须确保在一个 LVGL 函数调用进行时不会调用另一个 LVGL 函数。有几种方法可以做到这一点。请参阅 :ref:`threading` 部分以了解更多信息。 \ No newline at end of file From 4ca8b1f56a4bc3c330906f51b99e1f07766d7435 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Tue, 24 Dec 2024 19:29:51 +0800 Subject: [PATCH 09/10] docs: update CHANGELOG.rst --- docs/CHANGELOG.rst | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index ce7dd8bb..23893dd6 100755 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -13,17 +13,17 @@ Changelog（更新日志） It's huge release with many interesting updates: -- Built-in `Wayland driver `__ -- `OpenGL ES and GLFW driver `__ with support for external textures -- `Renesas GLCDC `__ driver +- Built-in :ref:`Wayland driver ` +- :ref:`OpenGL ES and GLFW driver ` with support for external textures +- :ref:`renesas_glcdc` driver - L8 and I1 rendering support - Matrix transformations during rendering -- New `file system interfaces `__: LittleFS, ESP LittleFS, Arduino FS +- New :ref:`file system interfaces `: LittleFS, ESP LittleFS, Arduino FS - SDL renderer improvements (supporting all draw task types and improving speed) -- Radial, Conic, and Skew `gradients supported `__ by software rendering and VG-Lite -- `QNX `__ and `MQX `__ support -- `Mouse hover handling `__ -- `Lottie `__ support +- Radial, Conic, and Skew `gradients supported `__ by software rendering and VG-Lite +- :ref:`qnx` and :ref:`mqx` support +- :ref:`Mouse hover handling ` +- :ref:`lv_lottie` support - CI tests for UEFI builds And many smaller fixes and features @@ -37,19 +37,19 @@ And many smaller fixes and features `v9.2 `__ 2024年8月26日 ------------------------------------------------------------------------------ -这是一个巨大的版本更新，包含许多有趣的更新： +这是一个包含许多有趣更新的大版本： -- 内置 Wayland 驱动 `Wayland driver `__ -- `OpenGL ES and GLFW driver `__ 支持外部纹理 -- `Renesas GLCDC `__ 驱动 -- L8 和 I1 渲染支持 +- 内置 :ref:`Wayland 驱动 ` +- :ref:`OpenGL ES 和 GLFW 驱动 `，支持外部纹理 +- :ref:`renesas_glcdc` 驱动 +- 支持 L8 和 I1 渲染 - 渲染期间的矩阵变换 -- 新的 `文件系统接口 `__: LittleFS, ESP LittleFS, Arduino FS -- SDL 渲染器改进（支持所有绘图任务类型并提高速度） -- 软件渲染和 VG-Lite 支持的 `径向、圆锥和倾斜渐变 `__ -- `QNX `__ 和 `MQX `__ 支持 -- `Mouse hover handling `__ -- `Lottie `__ 支持 +- 新的 :ref:`文件系统接口 `：LittleFS、ESP LittleFS、Arduino FS +- SDL 渲染器改进（支持所有绘制任务类型并提高速度） +- 通过软件渲染和 VG-Lite 支持径向、锥形和倾斜 `渐变 `__ +- :ref:`qnx` 和 :ref:`mqx` 支持 +- :ref:`鼠标悬停处理 ` +- :ref:`lv_lottie` 支持 - UEFI 构建的 CI 测试 以及许多较小的修复和功能 @@ -337,7 +337,7 @@ Fixes（修复） - **fix(sdl): handle if the window_id is not set correctly in SDL** `6194 `__ - **fix(drivers): drm driver not initialising with small screens** `6244 `__ - **fix(freetype): fix potential multi-threaded data conflicts** `6252 `__ -- **fix(vglite): build issues ** `6245 `__ +- **fix(vglite): build issues** `6245 `__ - **fix(canvas): lv_canvas_set_px for indexed images** `6226 `__ - **fix(snapshot): fix memleak in lv_snapshot** `6147 `__ - **fix(span): fix span incorrect max height calculation** `6243 `__ From d7254a92de50a65a6401e37d34871b64acd07e87 Mon Sep 17 00:00:00 2001 From: 100ask <100ask@100ask.com> Date: Tue, 24 Dec 2024 19:37:59 +0800 Subject: [PATCH 10/10] docs: update CODING_STYLE.rst --- docs/CODING_STYLE.rst | 365 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 331 insertions(+), 34 deletions(-) diff --git a/docs/CODING_STYLE.rst b/docs/CODING_STYLE.rst index 61d5cd1a..99f277f0 100755 --- a/docs/CODING_STYLE.rst +++ b/docs/CODING_STYLE.rst @@ -112,6 +112,11 @@ Coding guide（编码指南）
显示原文 +- Editor: + + - Set editor to use 4 spaces for tab indentations (instead of tab characters). + - Exception: the **Kconfig** file and any make files require leading tab characters + on child items. - Functions: @@ -132,7 +137,10 @@ Coding guide（编码指南）

+- 编辑器： + - 设置编辑器使用4个空格进行缩进（而不是制表符）。 + - 例外： **Kconfig** 文件和任何 make 文件在子项上需要使用前导制表符。 - 功能： @@ -157,31 +165,67 @@ Comments（注释）
显示原文 -Before every function have in ``.h`` files a comment like this: +Before every function prototype in ``.h`` files, include a Doxygen-formatted comment +like this: -.. code:: c +.. code-block:: c - /** - * Return with the screen of an object - * @param obj pointer to an object - * @return pointer to a screen - */ - lv_obj_t * lv_obj_get_screen(lv_obj_t * obj); + /** + * Brief description. Add a blank line + additional paragraphs when more detail is needed. + * @param parent brief description of argument. Additional detail can appear + * on subsequent lines. List of accepted values: + * - value one + * - value two + * - value three + * @return brief description of return value. + */ + type_name_t * lv_function_name(lv_obj_t * parent); + +The normal comment prefix ``/**`` causes the comment to document the code member +*after* the comment. When documenting a code member that is *before* the +comment, such as a struct member, use ``/**<`` like this: + +.. code-block:: c + + /** + * Brief description of struct + * + * When more detail is needed, add a blank line then the detail. + */ + typedef struct { + char *text; /**< Brief description of this member */ + uint16_t length; /**< Brief description of this member */ + } lv_example_type_t; + +- When commenting code, use block comments like this ``/* Description */``, + not end-of-line comments like this ``// Description``. + +- Include a space after the ``/*`` or ``/**<`` and before the ``*/`` for improved readability. -Always use ``/*Something*/`` format and NOT ``//Something`` +- Write readable code to avoid descriptive comments like: ``x++; /* Add 1 to x */``. -Write readable code to avoid descriptive comments like: -``x++; /*Add 1 to x*/``. The code should show clearly what you are -doing. +- The code should show clearly what you are doing. -You should write **why** have you done this: -``x++; /*Because of closing '\0' of the string*/`` +- You should write **why** you did it: ``x++; /* Point to closing '\0' of string */`` -Short "code summaries" of a few lines are accepted. E.g. -``/*Calculate the new coordinates*/`` +- Short "code summaries" of a few lines are accepted: ``/* Calculate new coordinates */`` -In comments use \` \` when referring to a variable. E.g. -:literal:`/\*Update the value of \`x_act`*/` +- In comments use back-quotes (\`...\`) when referring to a code element, such as a variable, type, + or struct name: ``/* Update value of `x_act` */`` + +- When adding or modifying comments, priorities are (in order of importance): + + 1. clarity (the ease with which other programmers can understand your intention), + 2. readability (the ease with which other programmers can read your comments), + 3. brevity (the quality of using few words when speaking or writing). + +- Blank lines within comments are desirable when they improve clarity and readability. + +- Remember, when you are writing source code, you are not just teaching the computer + what to do, but also teaching other programmers how it works, not only users of the + API, but also future maintainers of your source code. Comments add information + about what you were thinking when the code was written, and **why** you did things + that way---information that cannot be conveyed by the source code alone. .. raw:: html @@ -190,27 +234,277 @@ In comments use \` \` when referring to a variable. E.g.
-在文件中的每个函数之前都有 ``.h`` 这样的注释： +在 ``.h`` 文件中的每个函数原型之前，包含一个 Doxygen 格式的注释，如下所示： -.. code:: c +.. code-block:: c - /** - * Return with the screen of an object - * @param obj pointer to an object - * @return pointer to a screen - */ - lv_obj_t * lv_obj_get_screen(lv_obj_t * obj); + /** + * 简要描述。当需要更多细节时，添加空行和额外段落。 + * @param parent 参数的简要描述。额外的细节可以出现在后续行中。接受的值列表： + * - 值一 + * - 值二 + * - 值三 + * @return 返回值的简要描述。 + */ + type_name_t * lv_function_name(lv_obj_t * parent); + +普通的注释前缀 ``/**`` 会使注释记录在注释后的代码成员。当记录注释在注释前的代码成员时， +例如结构体成员，使用 ``/**<``，如下所示： + +.. code-block:: c + + /** + * 结构体的简要描述 + * + * 当需要更多细节时，添加空行然后添加细节。 + */ + typedef struct { + char *text; /**< 该成员的简要描述 */ + uint16_t length; /**< 该成员的简要描述 */ + } lv_example_type_t; + +- 注释代码时，使用块注释 ``/* 描述 */``，而不是行尾注释 ``// 描述``。 + +- 为了提高可读性，在 ``/*`` 或 ``/**<`` 之后和 ``*/`` 之前包含一个空格。 + +- 编写可读的代码，避免描述性注释，如：``x++; /* x 加 1 */``。 + +- 代码应清楚地显示你在做什么。 + +- 你应该写明 **为什么** 这样做：``x++; /* 指向字符串的结束符 '\0' */`` + +- 接受几行的简短“代码摘要”：``/* 计算新坐标 */`` + +- 在注释中使用反引号（\`...\`）引用代码元素，如变量、类型或结构体名称：``/* 更新 `x_act` 的值 */`` + +- 添加或修改注释时，优先级（按重要性顺序）： + + 1. 清晰度（其他程序员理解你意图的难易程度）， + 2. 可读性（其他程序员阅读你注释的难易程度）， + 3. 简洁性（说话或写作时使用较少词语的质量）。 + +- 当空行能提高清晰度和可读性时，注释中应包含空行。 + +- 记住，当你编写源代码时，你不仅是在教计算机该做什么，还在教其他程序员它是如何工作的， + 不仅是 API 的用户，还有你源代码的未来维护者。注释添加了代码编写时你在想什么以及 + **为什么** 这样做的信息——这些信息是源代码本身无法传达的。 + +Doxygen Comment Specifics（Doxygen 注释细节） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ 显示原文 +Doxygen is the first program in a chain that generates the online LVGL API +documentation from the files in the LVGL repository. Doxygen detects files it should +pay attention to by them having a ``@file`` command inside a Doxygen comment. Doxygen +comments begin with a leading ``/**``. It ignores comments that do not have exactly +two ``*``. + +The following is an illustration of an API function prototype with documentation +illustrating most of the Doxygen commands used in LVGL. + +.. code-block:: c + + /** + * Set alignment of Widgets placed in containers with LV_STYLE_FLEX_FLOW style. + * + * The values for the `..._place` arguments come from the `lv_flex_align_t` + * enumeration and have the same meanings as they do for flex containers in CSS. + * @param obj pointer to flex container. It must have + * `LV_STYLE_FLEX_FLOW` style or nothing will happen. + * @param main_place where to place items on main axis (in their track). + * (Any value of `lv_flex_align_t`.) + * @param cross_place where to place item in track on cross axis. + * - `LV_FLEX_ALIGN_START` + * - `LV_FLEX_ALIGN_END` + * - `LV_FLEX_ALIGN_CENTER` + * @param track_cross_place where to place tracks in cross direction. + * (Any value of `lv_flex_align_t`.) + * Example for a title bar layout: + * @code{.c} + * lv_obj_set_flex_align(title_bar, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_CENTER); + * @endcode + * @see + * - https://css-tricks.com/snippets/css/a-guide-to-flexbox/ + * - see `lv_obj_set_flex_grow()` for additional information. + */ + void lv_obj_set_flex_align(lv_obj_t * widget, lv_flex_align_t main_place, lv_flex_align_t cross_place, + lv_flex_align_t track_cross_place); + + +- Always start Doxygen comment with a brief description of the code element it documents. + +- When more detail is needed, add a blank line below the brief description and add + additional information that may be needed by LVGL API users, including preconditions + for calling the function. Doxygen needs the blank line to separate "brief" from + "detail" portions of the description. + +- Describe function parameters with the ``@param`` command. When a function writes + to the address contained by a pointer parameter, if not already obvious (e.g. when + the parameter name contains the word "out"), include the direction in the command + for clarity: + + ``@param[out] param_name description``. + +- Describe return values with the ``@return`` command. + +- Add at least 2 spaces after Doxygen commands for improved readability. + +- Use back-quotes (\`...\`) around code elements (variables, type names, function names). For type + names and function names, Doxygen generates a hyperlink to that code member's + documentation (when it exists) with or without the single back-quotes. + +- Append empty "()" to function names. Doxygen will not generate a hyperlink to the + function's documentation without this. + +- Use proper grammar for clarity. Descriptions of parameters do not need periods + after them unless they are full sentences. + +- Align edges of text around lists of parameters for ease of reading. + +- Lists (e.g. of accepted parameter values) can be created by using the '-' character. + If the list needs to be numbered, numbers can also be used. + +- Place example code in a code block by surrounding it with ``@code{.c}`` and ``@endcode`` commands. + Doxygen doesn't need the ``{.c}`` part, but the downstream software does. + +- Refer reader to additional information using the ``@see`` command. Doxygen adds a + "See also" paragraph. The text following the ``@see`` command will be indented. + +- If you create a new pair of ``.c`` and ``.h`` files (e.g. for a new driver), ensure + a Doxygen comment like this is at the top of each new file. Doxygen will not parse + the file without the ``@file`` command being present. + +.. code-block:: c + + /** + * @file filename.c + * + */ +.. raw:: html + +
+
+Doxygen 是生成在线 LVGL API 文档的链条中的第一个程序，它从 LVGL 仓库中的文件生成文档。 +Doxygen 通过在 Doxygen 注释中包含 ``@file`` 命令来检测它应该关注的文件。Doxygen 注释以 +前导 ``/**`` 开始。它会忽略不完全有两个 ``*`` 的注释。 + +以下是一个带有文档的 API 函数原型示例，展示了 LVGL 中使用的大多数 Doxygen 命令。 + +.. code-block:: c + + /** + * 设置在具有 LV_STYLE_FLEX_FLOW 样式的容器中放置的部件的对齐方式。 + * + * `..._place` 参数的值来自 `lv_flex_align_t` 枚举，并且与 CSS 中的弹性容器具有相同的含义。 + * @param obj 指向弹性容器的指针。它必须具有 `LV_STYLE_FLEX_FLOW` 样式，否则不会发生任何事情。 + * @param main_place 在主轴上放置项目的位置（在它们的轨道中）。 + * （`lv_flex_align_t` 的任何值。） + * @param cross_place 在交叉轴上放置项目的位置。 + * - `LV_FLEX_ALIGN_START` + * - `LV_FLEX_ALIGN_END` + * - `LV_FLEX_ALIGN_CENTER` + * @param track_cross_place 在交叉方向上放置轨道的位置。 + * （`lv_flex_align_t` 的任何值。） + * 示例标题栏布局： + * @code{.c} + * lv_obj_set_flex_align(title_bar, LV_FLEX_ALIGN_START, LV_FLEX_ALIGN_CENTER, LV_FLEX_ALIGN_CENTER); + * @endcode + * @see + * - https://css-tricks.com/snippets/css/a-guide-to-flexbox/ + * - 参见 `lv_obj_set_flex_grow()` 以获取更多信息。 + */ + void lv_obj_set_flex_align(lv_obj_t * widget, lv_flex_align_t main_place, lv_flex_align_t cross_place, + lv_flex_align_t track_cross_place); + + +- 始终以简要描述代码元素的 Doxygen 注释开始。 + +- 当需要更多细节时，在简要描述下方添加一个空行，并添加 LVGL API 用户可能需要的额外信息， + 包括调用函数的前提条件。Doxygen 需要空行来分隔“简要”部分和“详细”部分。 + +- 使用 ``@param`` 命令描述函数参数。当函数写入指针参数包含的地址时，如果不明显（例如参数名称包含“out”）， + 为了清晰起见，在命令中包含方向： + + ``@param[out] param_name 描述``。 + +- 使用 ``@return`` 命令描述返回值。 + +- 在 Doxygen 命令后至少添加 2 个空格以提高可读性。 + +- 使用反引号（\`...\`）引用代码元素（变量、类型名称、函数名称）。对于类型名称和函数名称， + Doxygen 会生成指向该代码成员文档的超链接（如果存在）。 -始终使用 ``/*Something*/`` 格式而不是 ``//Something`` +- 在函数名称后附加空的“()”。没有这个，Doxygen 将不会生成指向函数文档的超链接。 -编写可读的代码以避免描述性注释，例如 ``x++; /*Add 1 to x*/``。代码应该清楚地显示您在做什么。 +- 使用正确的语法以确保清晰。参数描述不需要句号，除非它们是完整的句子。 -你应该写下 **为什么** 这样做： ``x++; /*Because of closing '\0' of the string*/`` +- 对齐参数列表周围的文本边缘以便于阅读。 -接受几行的简短“代码摘要”。例如 ``/*Calculate the new coordinates*/`` +- 可以使用“-”字符创建列表（例如接受的参数值）。如果需要编号列表，也可以使用数字。 -在注释中引用变量时使用 \` \` 。例如 :literal:`/\*Update the value of \`x_act`*/` +- 将示例代码放在代码块中，使用 ``@code{.c}`` 和 ``@endcode`` 命令将其包围。Doxygen 不需要 ``{.c}`` 部分， + 但下游软件需要。 +- 使用 ``@see`` 命令引用读者获取更多信息。Doxygen 会添加一个“另请参见”段落。``@see`` 命令后的文本将缩进。 + +- 如果创建了一对新的 ``.c`` 和 ``.h`` 文件（例如用于新驱动程序），请确保在每个新文件的顶部都有一个 Doxygen 注释。 + 如果没有 ``@file`` 命令，Doxygen 将不会解析该文件。 + +.. code-block:: c + + /** + * @file filename.c + * + */ +Supported Doxygen Commands（支持的 Doxygen 命令） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ 显示原文 +- ``@file`` + tells Doxygen to parse this file and also supplies documentation about + the file itself when applicable (everything following it in the same comment). +- ``@param name description`` + documents ``name`` as a function parameter, and ``description`` is the text that + follows it until Doxygen encounters a blank line or another Doxygen command. +- ``@return description`` + documents the return value until Doxygen encounters a blank line or another Doxygen command. +- ``@code{.c}/@endcode`` + surrounds code that should be placed in a code block. While Doxygen knows to use C + color-coding of code blocks in a .C file, the downstream part of the documentation + generation sequence does not, so the ``{.c}`` appendage to the ``@code`` command + is necessary. +- ``@note text`` + starts a paragraph where a note can be entered. The note ends with a blank line, + the end of the comment, or another Doxygen command that starts a new section. + If the note contains more than one paragraph, additional paragraphs can be added + by using additional ``@note`` commands. At this writing, ``@par`` commands do not + add additional paragraphs to notes as indicated in the Doxygen documentation. +- ``@see text`` + generates a "See also" pagraph in a highlighted section, helpful when additional + information about a topic can be found elsewhere. +.. raw:: html + +
+
+- ``@file`` + 告诉 Doxygen 解析此文件，并在适用时提供有关文件本身的文档（同一注释中的所有内容）。 +- ``@param name description`` + 将 ``name`` 记录为函数参数，``description`` 是后续文本，直到 Doxygen 遇到空行或另一个 Doxygen 命令。 +- ``@return description`` + 记录返回值，直到 Doxygen 遇到空行或另一个 Doxygen 命令。 +- ``@code{.c}/@endcode`` + 包围应放置在代码块中的代码。虽然 Doxygen 知道在 .C 文件中使用 C 语法高亮显示代码块， + 但文档生成序列的下游部分不知道，因此 ``@code`` 命令的 ``{.c}`` 附加部分是必要的。 +- ``@note text`` + 开始一个可以输入注释的段落。注释以空行、注释结束或另一个开始新部分的 Doxygen 命令结束。 + 如果注释包含多个段落，可以使用额外的 ``@note`` 命令添加额外的段落。目前，``@par`` 命令不会像 + Doxygen 文档中所述那样为注释添加额外的段落。 +- ``@see text`` + 在高亮部分生成一个“另请参见”段落，当有关主题的更多信息可以在其他地方找到时很有帮助。 API Conventions（API规定） -------------------------- @@ -422,19 +716,22 @@ Skipping hooks（跳钩） If you want to skip any particular hook you can do so with: +.. code-block:: console + + SKIP=name-of-the-hook git commit .. raw:: html

-如果你想跳过任何特定的钩子，你可以这样做： - +如果你想跳过任何特定的钩子，可以这样做： -.. code:: console +.. code-block:: console SKIP=name-of-the-hook git commit + Testing hooks（测试钩子） -------------------------