Spinbox (lv_spinbox)

Overview

The Spinbox contains a number as text which can be increased or decreased by Keys or API functions. Under the hood the Spinbox is a modified Text area.

Parts and Styles

The parts of the Spinbox are identical to the 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 a range. If the value is changed by lv_spinbox_set_value, by Keys,lv_spinbox_increment/decrement this range will be respected.

lv_spinbox_set_step(spinbox, 100) sets which digits to change on increment/decrement. Only multiples of ten can be set, and not for example 3.

lv_spinbox_set_cursor_pos(spinbox, 1) sets the cursor to a specific digit to change on increment/decrement. For example 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

Format

lv_spinbox_set_digit_format(spinbox, digit_count, separator_position) sets the number format. digit_count is the number of digits excluding the decimal separator and the sign. separator_position is the number of digits before the decimal point. If 0, no decimal point is displayed.

Rollover

lv_spinbox_set_rollover(spinbox, true/false) enables/disabled rollover mode. If either the minimum or maximum value is reached with rollover enabled, the value will change to the other limit. If rollover is disabled the value will remain at the minimum or maximum value.

Events

  • LV_EVENT_VALUE_CHANGED Sent when the value has changed.

See the events of the Text area too.

Learn more about Events.

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 got the next digit. Jump to the first after the last.

Example

Simple Spinbox

C code  

 GitHub
#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_scr_act());
    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);

    lv_coord_t h = lv_obj_get_height(spinbox);

    lv_obj_t * btn = lv_btn_create(lv_scr_act());
    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_img_src(btn, LV_SYMBOL_PLUS, 0);
    lv_obj_add_event_cb(btn, lv_spinbox_increment_event_cb, LV_EVENT_ALL,  NULL);

    btn = lv_btn_create(lv_scr_act());
    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_img_src(btn, LV_SYMBOL_MINUS, 0);
    lv_obj_add_event_cb(btn, lv_spinbox_decrement_event_cb, LV_EVENT_ALL, NULL);
}

#endif

MicroPython code  

 GitHub Simulator
def increment_event_cb(e):
    code = e.get_code()
    if code == lv.EVENT.SHORT_CLICKED or code  == lv.EVENT.LONG_PRESSED_REPEAT:
        spinbox.increment()

def decrement_event_cb(e):
    code = e.get_code()
    if code == lv.EVENT.SHORT_CLICKED or code == lv.EVENT.LONG_PRESSED_REPEAT:
        spinbox.decrement()

spinbox = lv.spinbox(lv.scr_act())
spinbox.set_range(-1000, 25000)
spinbox.set_digit_format(5, 2)
spinbox.step_prev()
spinbox.set_width(100)
spinbox.center()

h = spinbox.get_height()

btn = lv.btn(lv.scr_act())
btn.set_size(h, h)
btn.align_to(spinbox, lv.ALIGN.OUT_RIGHT_MID, 5, 0)
btn.set_style_bg_img_src(lv.SYMBOL.PLUS, 0)
btn.add_event_cb(increment_event_cb, lv.EVENT.ALL,  None)

btn = lv.btn(lv.scr_act())
btn.set_size(h, h)
btn.align_to(spinbox, lv.ALIGN.OUT_LEFT_MID, -5, 0)
btn.set_style_bg_img_src(lv.SYMBOL.MINUS, 0)
btn.add_event_cb(decrement_event_cb, lv.EVENT.ALL, None)

API

Functions

lv_obj_t *lv_spinbox_create(lv_obj_t *parent)

Create a Spinbox object

Parameters

parent -- pointer to an object, it will be the parent of the new spinbox

Returns

pointer to the created spinbox

void lv_spinbox_set_value(lv_obj_t *obj, int32_t i)

Set spinbox value

Parameters
  • obj -- pointer to spinbox

  • i -- value to be set

void lv_spinbox_set_rollover(lv_obj_t *obj, bool b)

Set spinbox rollover function

Parameters
  • obj -- pointer to spinbox

  • b -- true or false to enable or disable (default)

void lv_spinbox_set_digit_format(lv_obj_t *obj, uint8_t digit_count, uint8_t separator_position)

Set spinbox digit format (digit count and decimal format)

Parameters
  • obj -- pointer to spinbox

  • digit_count -- number of digit excluding the decimal separator and the sign

  • separator_position -- number of digit before the decimal point. If 0, decimal point is not shown

void lv_spinbox_set_step(lv_obj_t *obj, uint32_t step)

Set spinbox step

Parameters
  • obj -- pointer to spinbox

  • step -- steps on increment/decrement. Can be 1, 10, 100, 1000, etc the digit that will change.

void lv_spinbox_set_range(lv_obj_t *obj, int32_t range_min, int32_t range_max)

Set spinbox value range

Parameters
  • obj -- pointer to spinbox

  • range_min -- maximum value, inclusive

  • range_max -- minimum value, inclusive

void lv_spinbox_set_cursor_pos(lv_obj_t *obj, uint8_t pos)

Set cursor position to a specific digit for edition

Parameters
  • obj -- pointer to spinbox

  • pos -- selected position in spinbox

void lv_spinbox_set_digit_step_direction(lv_obj_t *obj, lv_dir_t direction)

Set direction of digit step when clicking an encoder button while in editing mode

Parameters
  • obj -- pointer to spinbox

  • direction -- the direction (LV_DIR_RIGHT or LV_DIR_LEFT)

bool lv_spinbox_get_rollover(lv_obj_t *obj)

Get spinbox rollover function status

Parameters

obj -- pointer to spinbox

int32_t lv_spinbox_get_value(lv_obj_t *obj)

Get the spinbox numeral value (user has to convert to float according to its digit format)

Parameters

obj -- pointer to spinbox

Returns

value integer value of the spinbox

int32_t lv_spinbox_get_step(lv_obj_t *obj)

Get the spinbox step value (user has to convert to float according to its digit format)

Parameters

obj -- pointer to spinbox

Returns

value integer step value of the spinbox

void lv_spinbox_step_next(lv_obj_t *obj)

Select next lower digit for edition by dividing the step by 10

Parameters

obj -- pointer to spinbox

void lv_spinbox_step_prev(lv_obj_t *obj)

Select next higher digit for edition by multiplying the step by 10

Parameters

obj -- pointer to spinbox

void lv_spinbox_increment(lv_obj_t *obj)

Increment spinbox value by one step

Parameters

obj -- pointer to spinbox

void lv_spinbox_decrement(lv_obj_t *obj)

Decrement spinbox value by one step

Parameters

obj -- pointer to spinbox

Variables

const lv_obj_class_t lv_spinbox_class
struct lv_spinbox_t

Public Members

lv_textarea_t ta
int32_t value
int32_t range_max
int32_t range_min
int32_t step
uint16_t digit_count
uint16_t dec_point_pos
uint16_t rollover
uint16_t digit_step_dir

Example