==================================
滚筒(lv_roller)
==================================

概述
##################################
滚筒允许通过滚动简单地从多个选项中选择一个选项。



零件和样式
##################################
滚筒的主要部件称为 ``LV_ROLLER_PART_BG`` 。它是一个矩形，并使用所有典型的背景属性。 Roller标签的样式继承自背景的文本样式属性。
要调整选项之间的间距，请使用text_line_space样式属性。填充样式属性设置了侧面的空间。

中间的选定选项可以用 ``LV_ROLLER_PART_SELECTED`` 虚拟零件引用。除了典型的背景属性外，它还使用文本属性来更改所选区域中文本的外观。



用法
##################################

设定选项
**********************************
这些选项作为带有 ``lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL/INFINITE)`` 的字符串传递给Roller。选项应用 ``\n`` 分隔。例如： ``"First\nSecond\nThird"`` 。

``LV_ROLLER_MODE_INFINITE`` 使滚子呈圆形。

可以使用 ``lv_roller_set_selected(roller, id, LV_ANIM_ON/OFF)`` 手动选择选项，其中id是选项的索引。


获取选择的选项
**********************************
使用 ``lv_roller_get_selected(roller)`` 获取当前选定的选项，它将返回选定选项的索引。

``lv_roller_get_selected_str(roller, buf, buf_size)`` 将所选选项的名称复制到 ``buf`` 。


选项对齐
**********************************
要水平对齐标签，请使用 ``lv_roller_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`` 水平对齐标签。


可见行
**********************************
可见行数可以通过 ``lv_roller_set_visible_row_count(roller, num)`` 进行调整


动画时间
**********************************
当滚轴滚动且未完全停在某个选项上时，它将自动滚动到最近的有效选项。可以通过 ``lv_roller_set_anim_time(roller, anim_time)`` 更改此滚动动画的时间。动画时间为零表示没有动画。


事件
##################################
除了 `通用事件`_ ，滚筒还支持以下 `特殊事件`_ ：

- **LV_EVENT_VALUE_CHANGED** 选定新选项时发送


了解有关 `事件`_ 的更多内容。

.. _通用事件: http://lvgl.100ask.net/documentation/03_overview/03_events.html#id2
.. _特殊事件: http://lvgl.100ask.net/documentation/03_overview/03_events.html#id7
.. _事件: http://lvgl.100ask.net/documentation/03_overview/03_events.html



按键处理
##################################
以下按键由按钮处理：

- **LV_KEY_RIGHT/DOWN** 选择下一个选项
- **LV_KEY_LEFT/UP** 选择上一个选项
- **LY_KEY_ENTER** 应用选定的选项（发送LV_EVENT_VALUE_CHANGED事件）


了解有关 `按键`_  的更多内容。

.. _按键: http://lvgl.100ask.net/documentation/03_overview/05_indev.html



范例
##################################

简易滚筒
**********************************

.. figure:: http://photos.100ask.net/lvgl/04_widgets/25_roller/01_lv_ex_roller_1.png
	   
	  创建一个简易的滚筒


上述效果的示例代码：

.. code-block:: c
    :linenos:

	#include "../../../lv_examples.h"
	#include <stdio.h>
	#if LV_USE_ROLLER

	static void event_handler(lv_obj_t * obj, lv_event_t event)
	{
		if(event == LV_EVENT_VALUE_CHANGED) {
			char buf[32];
			lv_roller_get_selected_str(obj, buf, sizeof(buf));
			printf("Selected month: %s\n", buf);
		}
	}


	void lv_ex_roller_1(void)
	{
		lv_obj_t *roller1 = lv_roller_create(lv_scr_act(), NULL);
		lv_roller_set_options(roller1,
							"January\n"
							"February\n"
							"March\n"
							"April\n"
							"May\n"
							"June\n"
							"July\n"
							"August\n"
							"September\n"
							"October\n"
							"November\n"
							"December",
							LV_ROLLER_MODE_INFINITE);

		lv_roller_set_visible_row_count(roller1, 4);
		lv_obj_align(roller1, NULL, LV_ALIGN_CENTER, 0, 0);
		lv_obj_set_event_cb(roller1, event_handler);
	}

	#endif





相关API
##################################
TODO