Input device interface(输入设备接口)

Types of input devices(输入设备的类型)

查看原文

To register an input device an lv_indev_drv_t variable has to be initialized:

要注册输入设备,必须初始化一个 lv_indev_drv_t 变量:

lv_indev_drv_t indev_drv;
lv_indev_drv_init(&indev_drv);      /*Basic initialization*/
indev_drv.type =...                 /*See below.*/
indev_drv.read_cb =...              /*See below.*/
/*Register the driver in LVGL and save the created input device object*/
lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv);
查看原文

type can be

  • LV_INDEV_TYPE_POINTER touchpad or mouse

  • LV_INDEV_TYPE_KEYPAD keyboard or keypad

  • LV_INDEV_TYPE_ENCODER encoder with left/right turn and push options

  • LV_INDEV_TYPE_BUTTON external buttons virtually pressing the screen

read_cb is a function pointer which will be called periodically to report the current state of an input device.

Visit Input devices to learn more about input devices in general.

type 可以是

  • LV_INDEV_TYPE_POINTER 触摸板或鼠标

  • LV_INDEV_TYPE_KEYPAD 键盘或小键盘

  • LV_INDEV_TYPE_ENCODER 编码器,带有左/右转和推动选项

  • LV_INDEV_TYPE_BUTTON 外部按钮虚拟按下屏幕

read_cb 是一个函数指针,它将被定期调用以报告输入设备的当前状态。

访问 输入设备 以了解有关输入设备的更多信息。

Touchpad, mouse or any pointer(触摸板、鼠标或任何指针)

查看原文

Input devices that can click points on the screen belong to this category.

可以点击屏幕上的点的输入设备属于这一类。

indev_drv.type = LV_INDEV_TYPE_POINTER;
indev_drv.read_cb = my_input_read;

...

void my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data)
{
  if(touchpad_pressed) {
    data->point.x = touchpad_x;
    data->point.y = touchpad_y;
    data->state = LV_INDEV_STATE_PRESSED;
  } else {
    data->state = LV_INDEV_STATE_RELEASED; 
  }
}
查看原文

To set a mouse cursor use lv_indev_set_cursor(my_indev, &img_cursor). (my_indev is the return value of lv_indev_drv_register)

要设置鼠标光标,请使用 lv_indev_set_cursor(my_indev, &img_cursor)。 (my_indevlv_indev_drv_register 的返回值)

Keypad or keyboard(键盘或键盘)

查看原文

Full keyboards with all the letters or simple keypads with a few navigation buttons belong here.

To use a keyboard/keypad:

  • Register a read_cb function with LV_INDEV_TYPE_KEYPAD type.

  • An object group has to be created: lv_group_t * g = lv_group_create() and objects have to be added to it with lv_group_add_obj(g, obj)

  • The created group has to be assigned to an input device: lv_indev_set_group(my_indev, g) (my_indev is the return value of lv_indev_drv_register)

  • Use LV_KEY_... to navigate among the objects in the group. See lv_core/lv_group.h for the available keys.

带有所有字母的全键盘或带有几个导航按钮的简单键盘都属于这里。

要使用键盘/小键盘:

  • 注册一个带有 LV_INDEV_TYPE_KEYPAD 类型的 read_cb 函数。

  • 必须创建一个对象组:lv_group_t * g = lv_group_create() 并且对象必须使用 lv_group_add_obj(g, obj) 添加到其中

  • 创建的组必须分配给输入设备:lv_indev_set_group(my_indev, g)my_indevlv_indev_drv_register 的返回值)

  • 使用LV_KEY_... 在组中的对象之间导航。有关可用密钥,请参阅“lv_core/lv_group.h”。

indev_drv.type = LV_INDEV_TYPE_KEYPAD;
indev_drv.read_cb = keyboard_read;

...

void keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
  data->key = last_key();            /*Get the last pressed or released key*/

  if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED;
  else data->state = LV_INDEV_STATE_RELEASED;
}

Encoder(编码器)

查看原文

With an encoder you can do 4 things:

  1. Press its button

  2. Long-press its button

  3. Turn left

  4. Turn right

In short, the Encoder input devices work like this:

  • By turning the encoder you can focus on the next/previous object.

  • When you press the encoder on a simple object (like a button), it will be clicked.

  • If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby turning the encoder you can navigate inside the object.

  • To leave edit mode press long the button.

To use an Encoder (similarly to the Keypads) the objects should be added to groups.

使用编码器,您可以做 4 件事:

  1. 按下它的按钮

  2. 长按它的按钮

  3. 左转

  4. 右转

简而言之,编码器输入设备的工作方式如下:

  • 通过转动编码器,您可以专注于下一个/上一个对象。

  • 当您在一个简单的对象(如按钮)上按下编码器时,它将被点击。

  • 如果您按下复杂对象(如列表、消息框等)上的编码器,该对象将进入编辑模式,从而转动编码器您可以在对象内部导航。

  • 要退出编辑模式,请长按按钮。

要使用 Encoder(类似于 Keypads),应将对象添加到组中。

indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_read;

...

void encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
  data->enc_diff = enc_get_new_moves();

  if(enc_pressed()) data->state = LV_INDEV_STATE_PRESSED;
  else data->state = LV_INDEV_STATE_RELEASED;
}

Using buttons with Encoder logic(使用带有编码器逻辑的按钮)

查看原文

In addition to standard encoder behavior, you can also utilize its logic to navigate(focus) and edit widgets using buttons. This is especially handy if you have only few buttons available, or you want to use other buttons in addition to encoder wheel.

You need to have 3 buttons available:

  • LV_KEY_ENTER will simulate press or pushing of the encoder button

  • LV_KEY_LEFT will simulate turning encoder left

  • LV_KEY_RIGHT will simulate turning encoder right

  • other keys will be passed to the focused widget

If you hold the keys it will simulate encoder click with period specified in indev_drv.long_press_rep_time.

除了标准编码器行为之外,您还可以利用其逻辑来使用按钮导航(聚焦)和编辑小部件。 如果您只有几个按钮可用,或者您想使用除编码轮之外的其他按钮,这将特别方便。

您需要有 3 个按钮可用:

  • LV_KEY_ENTER 将模拟按下或按下编码器按钮

  • LV_KEY_LEFT 将模拟向左转动编码器

  • LV_KEY_RIGHT 将模拟向右旋转编码器

  • 其他键将传递给聚焦的小部件

如果您按住这些键,它将模拟编码器点击,并在indev_drv.long_press_rep_time 中指定周期。

indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_with_keys_read;

...

void encoder_with_keys_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
  data->key = last_key();            /*Get the last pressed or released key*/
                                     /* use LV_KEY_ENTER for encoder press */
  if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED;
  else {
      data->state = LV_INDEV_STATE_RELEASED;
      /* Optionally you can also use enc_diff, if you have encoder*/
      data->enc_diff = enc_get_new_moves();
  }
}

Button(按钮)

查看原文

Buttons mean external "hardware" buttons next to the screen which are assigned to specific coordinates of the screen. If a button is pressed it will simulate the pressing on the assigned coordinate. (Similarly to a touchpad)

To assign buttons to coordinates use lv_indev_set_button_points(my_indev, points_array).
points_array should look like const lv_point_t points_array[] =  { {12,30},{60,90}, ...}

按钮表示屏幕旁边的外部“硬件”按钮,这些按钮分配给屏幕的特定坐标。 如果按下按钮,它将模拟按下指定坐标。 (类似于触摸板)

要将按钮分配给坐标,请使用 lv_indev_set_button_points(my_indev, points_array)points_array 应该看起来像 const lv_point_t points_array[] = { {12,30},{60,90}, ...}

重要

The points_array can't go out of scope. Either declare it as a global variable or as a static variable inside a function.

indev_drv.type = LV_INDEV_TYPE_BUTTON;
indev_drv.read_cb = button_read;

...

void button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
    static uint32_t last_btn = 0;   /*Store the last pressed button*/
    int btn_pr = my_btn_read();     /*Get the ID (0,1,2...) of the pressed button*/
    if(btn_pr >= 0) {               /*Is there a button press? (E.g. -1 indicated no button was pressed)*/
       last_btn = btn_pr;           /*Save the ID of the pressed button*/
       data->state = LV_INDEV_STATE_PRESSED;  /*Set the pressed state*/
    } else {
       data->state = LV_INDEV_STATE_RELEASED; /*Set the released state*/
    }

    data->btn = last_btn;            /*Save the last button*/
}

Other features(其它功能)

Parameters(参数)

查看原文

The default value of the following parameters can changed in lv_indev_drv_t:

  • scroll_limit Number of pixels to slide before actually scrolling the object.

  • scroll_throw Scroll throw (momentum) slow-down in [%]. Greater value means faster slow-down.

  • long_press_time Press time to send LV_EVENT_LONG_PRESSED (in milliseconds)

  • long_press_rep_time Interval of sending LV_EVENT_LONG_PRESSED_REPEAT (in milliseconds)

  • read_timer pointer to the lv_timer which reads the input device. Its parameters can be changed by lv_timer_...() functions. LV_INDEV_DEF_READ_PERIOD in lv_conf.h sets the default read period.

以下参数的默认值可以在 lv_indev_drv_t 中更改:

  • scroll_limit 在实际滚动对象之前要滑动的像素数。

  • scroll_throw 滚动投掷(动量)减慢 [%]。更大的价值意味着更快的减速。

  • long_press_time 按下发送 LV_EVENT_LONG_PRESSED 的时间(以毫秒为单位)

  • long_press_rep_time 发送 LV_EVENT_LONG_PRESSED_REPEAT 的间隔(以毫秒为单位)

  • read_timer 指向读取输入设备的 lv_timer 的指针。它的参数可以通过lv_timer_...()函数改变。 lv_conf.h 中的 LV_INDEV_DEF_READ_PERIOD 设置默认读取周期。

Feedback(回调处理)

查看原文

Besides read_cb a feedback_cb callback can be also specified in lv_indev_drv_t. feedback_cb is called when any type of event is sent by the input devices (independently from its type). This allows generating feedback for the user, e.g. to play a sound on LV_EVENT_CLICKED.

除了 read_cb 一个 feedback_cb 回调也可以在 lv_indev_drv_t 中指定。 feedback_cb 在输入设备发送任何类型的事件时被调用(与其类型无关)。这允许为用户生成反馈,例如在“LV_EVENT_CLICKED”上播放声音。

Associating with a display(与显示器关联)

查看原文

Every input device is associated with a display. By default, a new input device is added to the lastly created or the explicitly selected (using lv_disp_set_default()) display. The associated display is stored and can be changed in disp field of the driver.

每个输入设备都与一个显示器相关联。默认情况下,一个新的输入设备被添加到最后创建的或明确选择的(使用 lv_disp_set_default())显示。 相关的显示被存储并可在驱动程序的“disp”字段中更改。

Buffered reading(缓冲读取)

查看原文

By default LVGL calls read_cb periodically. This way there is a chance that some user gestures are missed.

To solve this you can write an event driven driver for your input device that buffers measured data. In read_cb you can set the buffered data instead of reading the input device. You can set the data->continue_reading flag to tell that LVGL there is more data to read and it should call the read_cb again.

默认情况下,LVGL 会定期调用 read_cb。这样就有可能错过一些用户手势。

为了解决这个问题,你可以为你的输入设备编写一个事件驱动的驱动程序来缓冲测量数据。在 read_cb 中,您可以设置缓冲数据而不是读取输入设备。 你可以设置 data->continue_reading 标志来告诉 LVGL 有更多的数据要读取,它应该再次调用 read_cb

Further reading(深入学习)

查看原文

API

@description Input Device HAL interface layer header file

Typedefs

typedef struct _lv_indev_drv_t lv_indev_drv_t

Initialized by the user and registered by 'lv_indev_add()'

typedef struct _lv_indev_proc_t _lv_indev_proc_t

Run time data of input devices Internally used by the library, you should not need to touch it.

typedef struct _lv_indev_t lv_indev_t

The main input device descriptor with driver, runtime data ('proc') and some additional information

Enums

enum lv_indev_type_t

Possible input device types

Values:

enumerator LV_INDEV_TYPE_NONE

Uninitialized state

enumerator LV_INDEV_TYPE_POINTER

Touch pad, mouse, external button

enumerator LV_INDEV_TYPE_KEYPAD

Keypad or keyboard

enumerator LV_INDEV_TYPE_BUTTON

External (hardware button) which is assigned to a specific point of the screen

enumerator LV_INDEV_TYPE_ENCODER

Encoder with only Left, Right turn and a Button

enum lv_indev_state_t

States for input devices

Values:

enumerator LV_INDEV_STATE_RELEASED
enumerator LV_INDEV_STATE_PRESSED

Functions

void lv_indev_drv_init(struct _lv_indev_drv_t *driver)

Initialize an input device driver with default values. It is used to surely have known values in the fields and not memory junk. After it you can set the fields.

参数

driver -- pointer to driver variable to initialize

lv_indev_t *lv_indev_drv_register(struct _lv_indev_drv_t *driver)

Register an initialized input device driver.

参数

driver -- pointer to an initialized 'lv_indev_drv_t' variable (can be local variable)

返回

pointer to the new input device or NULL on error

void lv_indev_drv_update(lv_indev_t *indev, struct _lv_indev_drv_t *new_drv)

Update the driver in run time.

参数
  • indev -- pointer to an input device. (return value of lv_indev_drv_register)

  • new_drv -- pointer to the new driver

void lv_indev_delete(lv_indev_t *indev)

Remove the provided input device. Make sure not to use the provided input device afterwards anymore.

参数

indev -- pointer to delete

lv_indev_t *lv_indev_get_next(lv_indev_t *indev)

Get the next input device.

参数

indev -- pointer to the current input device. NULL to initialize.

返回

the next input device or NULL if there are no more. Provide the first input device when the parameter is NULL

void _lv_indev_read(lv_indev_t *indev, lv_indev_data_t *data)

Read data from an input device.

参数
  • indev -- pointer to an input device

  • data -- input device will write its data here

struct lv_indev_data_t
#include <lv_hal_indev.h>

Data structure passed to an input driver to fill

Public Members

lv_point_t point

For LV_INDEV_TYPE_POINTER the currently pressed point

uint32_t key

For LV_INDEV_TYPE_KEYPAD the currently pressed key

uint32_t btn_id

For LV_INDEV_TYPE_BUTTON the currently pressed button

int16_t enc_diff

For LV_INDEV_TYPE_ENCODER number of steps since the previous read

lv_indev_state_t state

LV_INDEV_STATE_REL or LV_INDEV_STATE_PR

bool continue_reading

If set to true, the read callback is invoked again

struct _lv_indev_drv_t
#include <lv_hal_indev.h>

Initialized by the user and registered by 'lv_indev_add()'

Public Members

lv_indev_type_t type

< Input device type Function pointer to read input device data.

void (*read_cb)(struct _lv_indev_drv_t *indev_drv, lv_indev_data_t *data)
void (*feedback_cb)(struct _lv_indev_drv_t*, uint8_t)

Called when an action happened on the input device. The second parameter is the event from lv_event_t

void *user_data
struct _lv_disp_t *disp

< Pointer to the assigned display Timer to periodically read the input device

lv_timer_t *read_timer

Number of pixels to slide before actually drag the object

uint8_t scroll_limit

Drag throw slow-down in [%]. Greater value means faster slow-down

uint8_t scroll_throw

At least this difference should be between two points to evaluate as gesture

uint8_t gesture_min_velocity

At least this difference should be to send a gesture

uint8_t gesture_limit

Long press time in milliseconds

uint16_t long_press_time

Repeated trigger period in long press [ms]

uint16_t long_press_repeat_time
struct _lv_indev_proc_t
#include <lv_hal_indev.h>

Run time data of input devices Internally used by the library, you should not need to touch it.

Public Members

lv_indev_state_t state

Current state of the input device.

uint8_t long_pr_sent
uint8_t reset_query
uint8_t disabled
uint8_t wait_until_release
lv_point_t act_point

Current point of input device.

lv_point_t last_point

Last point of input device.

lv_point_t last_raw_point

Last point read from read_cb.

lv_point_t vect

Difference between act_point and last_point.

lv_point_t scroll_sum
lv_point_t scroll_throw_vect
lv_point_t scroll_throw_vect_ori
struct _lv_obj_t *act_obj
struct _lv_obj_t *last_obj
struct _lv_obj_t *scroll_obj
struct _lv_obj_t *last_pressed
lv_area_t scroll_area
lv_point_t gesture_sum
lv_dir_t scroll_dir
lv_dir_t gesture_dir
uint8_t gesture_sent
struct _lv_indev_proc_t::[anonymous]::[anonymous] pointer
lv_indev_state_t last_state
uint32_t last_key
struct _lv_indev_proc_t::[anonymous]::[anonymous] keypad
union _lv_indev_proc_t::[anonymous] types
uint32_t pr_timestamp

Pressed time stamp

uint32_t longpr_rep_timestamp

Long press repeat time stamp

struct _lv_indev_t
#include <lv_hal_indev.h>

The main input device descriptor with driver, runtime data ('proc') and some additional information

Public Members

struct _lv_indev_drv_t *driver
_lv_indev_proc_t proc
struct _lv_obj_t *cursor

Cursor for LV_INPUT_TYPE_POINTER

struct _lv_group_t *group

Keypad destination group

const lv_point_t *btn_points

Array points assigned to the button ()screen will be pressed here by the buttons