Spinbox （微调框）(lv_spinbox)

Overview（概述）

显示原文

Spinbox contains an integer displayed as a decimal number with a possible fixed decimal point position and a configurable number of digits. The value can be increased or decreased by Keys or API functions. Under the hood Spinbox is a Text area（文本框） (lv_textarea) with behaviors extended to enable a numeric value to be viewed and modified with configurable constraints.

微调框（Spinbox）包含一个以十进制数形式显示的整数，该整数可能具有固定的小数点位置以及可配置的数位数量。其数值可以通过按键或应用程序编程接口（API）函数来增加或减少。在底层，微调框是一个:ref:`lv_textarea`（文本输入框），其行为经过扩展，以便能够在可配置的约束条件下查看和修改数值。

Parts and Styles（部分和样式）

显示原文

Spinbox's parts are identical to those of Text Area.

微调框（Spinbox）的部件与 Text Area 控件相同。

Value, range and step（值、范围和步长）

显示原文

lv_spinbox_set_value(spinbox, 1234) sets a new value on the Spinbox.
lv_spinbox_increment(spinbox) and lv_spinbox_decrement(spinbox) increments/decrements the value of the Spinbox according to the currently-selected digit.
lv_spinbox_set_range(spinbox, -1000, 2500) sets its range. If the value is changed by lv_spinbox_set_value(spinbox), by Keys, by lv_spinbox_increment(spinbox) or lv_spinbox_decrement(spinbox) this range will be respected.
lv_spinbox_set_step(spinbox, 100) sets which digit to change on increment/decrement. Only multiples of ten can be set.
lv_spinbox_set_cursor_pos(spinbox, 1) sets the cursor to a specific digit to change on increment/decrement. Position '0' sets the cursor to the least significant digit.

If an encoder is used as input device, the selected digit is shifted to the right by default whenever the encoder button is clicked. To change this behaviour to shifting to the left, the lv_spinbox_set_digit_step_direction(spinbox, LV_DIR_LEFT) can be used

lv_spinbox_set_value(spinbox, 1234) 在微调框上设置一个新值。
lv_spinbox_increment(spinbox) 和 :cpp:expr:`lv_spinbox_decrement(spinbox)`会根据当前所选数位来增加 / 减少微调框（Spinbox）的值。
lv_spinbox_set_range(spinbox, -1000, 2500)`用于设置其取值范围。如果通过 :cpp:expr:`lv_spinbox_set_value(spinbox)、按键操作、:cpp:expr:`lv_spinbox_increment(spinbox)`或者 :cpp:expr:`lv_spinbox_decrement(spinbox)`来改变数值，将会遵循这个取值范围。
:cpp:expr:`lv_spinbox_set_step(spinbox, 100)`用于设置在进行增加 / 减少操作时要改变的数位。只能设置为 10 的倍数。
:cpp:expr:`lv_spinbox_set_cursor_pos(spinbox, 1)`可将光标设置到特定数位上，以便在进行增加 / 减少操作时改变该数位的值。位置 “0” 会将光标设置到最低有效数位上。

如果将编码器用作输入设备，则所选数字将移至默认情况下，每当单击编码器按钮时，该键都是右键。将此行为更改为转移在左侧，可以使用函数 lv_spinbox_set_digit_step_direction(spinbox, LV_DIR_LEFT) 设置

Format（格式）

显示原文

lv_spinbox_set_digit_format(spinbox, digit_count, separator_position) sets the number format. digit_count is the total number of digits to display. separator_position is the number of leading digits before the decimal point. Pass 0 for separator_position to display no decimal point.

lv_spinbox_set_digit_format(spinbox, digit_count, separator_position) 设置数字格式。 digit_count 指的是要显示的数字的总位数。 separator_position 是小数点前的前导数位的数量。若想不显示小数点，可将 separator_position 设为 0。

Rollover（翻转）

显示原文

lv_spinbox_set_rollover(spinbox, true / false) enables/disabled rollover mode. If either the minimum or maximum value is reached with rollover enabled, and the user attempts to continue changing the value in the same direction, the value will change to the other limit. If rollover is disabled the value will stop at the minimum or maximum value.

:cpp:expr:`lv_spinbox_set_rollover(spinbox, true/false)`用于启用 / 禁用循环模式。如果启用了循环模式，当达到最小值或最大值时，用户仍试图继续沿相同方向更改数值，那么该数值将会变为另一个极限值（即从最大值变为最小值，或从最小值变为最大值）。如果禁用了循环模式，数值将会在达到最小值或最大值时停止变化。

Events（事件）

显示原文

LV_EVENT_VALUE_CHANGED Sent when the value has changed.

Keys（按键）

显示原文

LV_KEY_LEFT/RIGHT With Keypad move the cursor left/right. With Encoder decrement/increment the selected digit.
LV_KEY_UP/DOWN With Keypad and Encoder increment/decrement the value.
LV_KEY_ENTER With Encoder, move focus to next digit. If focus is on last digit, focus moves to first digit.

Example

Simple Spinbox

#include "../../lv_examples.h"
#if LV_USE_SPINBOX && LV_BUILD_EXAMPLES

static lv_obj_t * spinbox;

static void lv_spinbox_increment_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    if(code == LV_EVENT_SHORT_CLICKED || code  == LV_EVENT_LONG_PRESSED_REPEAT) {
        lv_spinbox_increment(spinbox);
    }
}

static void lv_spinbox_decrement_event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    if(code == LV_EVENT_SHORT_CLICKED || code == LV_EVENT_LONG_PRESSED_REPEAT) {
        lv_spinbox_decrement(spinbox);
    }
}

void lv_example_spinbox_1(void)
{
    spinbox = lv_spinbox_create(lv_screen_active());
    lv_spinbox_set_range(spinbox, -1000, 25000);
    lv_spinbox_set_digit_format(spinbox, 5, 2);
    lv_spinbox_step_prev(spinbox);
    lv_obj_set_width(spinbox, 100);
    lv_obj_center(spinbox);

    int32_t h = lv_obj_get_height(spinbox);

    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, h, h);
    lv_obj_align_to(btn, spinbox, LV_ALIGN_OUT_RIGHT_MID, 5, 0);
    lv_obj_set_style_bg_image_src(btn, LV_SYMBOL_PLUS, 0);
    lv_obj_add_event_cb(btn, lv_spinbox_increment_event_cb, LV_EVENT_ALL,  NULL);

    btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, h, h);
    lv_obj_align_to(btn, spinbox, LV_ALIGN_OUT_LEFT_MID, -5, 0);
    lv_obj_set_style_bg_image_src(btn, LV_SYMBOL_MINUS, 0);
    lv_obj_add_event_cb(btn, lv_spinbox_decrement_event_cb, LV_EVENT_ALL, NULL);
}

#endif

API

lv_types.h

lv_spinbox.h