下拉列表控件
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
用途：列表（展示当前选中的项）、下拉列表选择（配置绑定弹出按钮控件，点击后弹出列表，选择后自动关闭列表）。

说明：属性中弹出按钮ID默认为255，当做列表用；不为255，即绑定了弹出按钮，当作下拉列表用（选中列表选项后自动关闭列表）。

属性
---------------------------------
.. image:: image/下拉列表/下拉列表属性.png 
    :align: center
    :alt: 下拉列表属性

|

**基础属性 :**  参考控件概念- :ref:`基础属性`

**坐标属性 :**  参考控件概念- :ref:`坐标属性`
  
**背景属性 :**  参考控件概念- :ref:`背景属性`

**加载属性 :**  参考控件概念- :ref:`加载属性`
  
**文本属性 :**  

.. image:: image/下拉列表/下拉列表文本属性.png 
    :align: center
    :alt: 下拉列表文本属性

|

    + 文本值(str)：选项字符串，如：111\\n222\\n333\\n444，\\n是换行符，一个换行符表示一个选项。（只读）
    
    - 最大长度(size)：文本最大长度(字节),范围0-4096,UTF8编码下中文字符占用3个字节,其他编码中文字符占用2个字节,注意：键盘输入受限于此值(只读)
    
    + 字体(font)：字库id,范围0-65535,65535表示无(读写)

    - 文本颜色(color)：文本默认颜色(读写)

    + 按下颜色(color2)：选中字符的颜色(读写)

    **注意1：** 文本值(str)的换行符由多行文本编辑时自动插入的，打开多行编辑器如下图：

    .. image:: image/下拉列表/下拉列表打开多行编辑器.png 
        :align: center
        :alt: 下拉列表打开多行编辑器    

    |
    
    **注意2：** 下拉列表控件项数是根据选项字符串的换行符自动计算。当背景选为图片时，即使不显示字符也要设置字符串的项数，即换行符。

    **注意3：** 该控件的字库建议设为全缓存方式，且使用字库工具生成时，采用自定义字符方式。
    设置参考： :ref:`字库全缓存什么情况需要勾选？` 

**特有属性 :**  
  
.. image:: image/下拉列表/下拉列表特有属性.png 
    :align: center
    :alt: 下拉列表特有属性

|

    + 当前选中项(val)：选中项，范围：0-(cnt-1),cnt为项数，cnt≤255，等于选项字符串的换行符+1。0表示第一项(读写)

    - 选中项(str)：选中项的字符串(只读)

    + 显示字符与横线(show)：是否显示字符与横线:0-不显示 1-显示(读写)

    - 横线颜色(color)：横线颜色(读写)

    + 隐藏列表(hid)：是否隐藏列表:0-显示 1-隐藏(读写)

    - 弹出按钮ID(btnid)：弹出列表的按钮控件ID（仅当前页面）, 255表示无（只读）

    + 显示文本ID(txtid)：列表选中后关联显示的文本控件ID（仅当前页面）, 255表示无（只读）
  
    .. hint::
        1. 弹出按钮ID不为255，即绑定了按钮控件，选中列表选项后会自动关闭列表
        2. 显示文本ID可以和弹出按钮ID一致

---------------------------------

事件
---------------------------------

**弹起事件：** 控件按下且弹起后执行

**按下事件：** 控件按下后执行

---------------------------------


功能演示
---------------------------------

`点击下载演示工程 <http://www.openedv.com/ATK-Prod/ATK-HMI/file_download/wid_demo/project(wid_demo).zip>`_

.. image:: image/下拉列表/下拉列表功能演示.png 
    :align: center
    :alt: 下拉列表功能演示

|

.. tip:: 
    把工程配置的启动页面(pid)改为当前页面ID可以立即显示此页面。

|

图片背景列表
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. image:: image/下拉列表/图片背景列表.png 
    :align: center
    :alt: 图片背景列表

|

- 功能：点击选择列表菜单，可在模拟器数据返回区查看打印选中项的ID。
- 实现原理：

    1. 导入背景图片，下拉列表控件l1背景设为图片模式，使用多行文本编辑器输入4行，配置不显示字符与横线
    （ 注意： 虽然配置了不显示字符与横线，但仍要输入换行来确定项数）
    
    .. image:: image/下拉列表/图片列表字符串编辑.png 
        :align: center
        :alt: 图片列表字符串编辑

    |

     .. image:: image/下拉列表/图片列表属性.png 
        :align: center
        :alt: 图片列表属性

    |

    2. 下拉列表控件l1的 ``弹起事件`` 编写：
   
    ::

        prints("select id = %d", l1.val); // 调试打印
        // 可以在此调用play()指令播放对应音乐


下拉列表
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. image:: image/下拉列表/下拉列表.png 
    :align: center
    :alt: 下拉列表

|

- 功能：点击按钮Btn弹出下拉列表，选择后可在模拟器数据返回区查看打印选中项的ID。
- 实现原理：
  
    1. 添加文本控件t0，按钮控件b1。下拉列表控件l0的弹出按钮ID、显示文本ID属性分别绑定t0、b1的控件ID。配置如下：

    .. image:: image/下拉列表/下拉列表举例属性.png 
        :align: center
        :alt: 下拉列表举例属性

    |

    2. 下拉列表控件l0的 ``弹起事件`` 编写：
   
    ::

        prints("select id = %d", l0.val); // 调试打印
        // 可以在此执行想要的操作

|
|
|
|
|
|