KikoPlay 扩展App开发参考 - UI

June 2, 2024 · View on GitHub

2023.09 By Kikyou，本文档适用于KikoPlay 1.0.0及以上版本

KikoPlay通过xml描述app的ui结构，app.xml根节点必须为window元素，通过include节点包含的其他文件没有这个限制。 可以通过xml属性来设置ui元素的各种状态、布局及事件响应方法。

ui元素由KikoPlay管理，在lua中将ui对象设置为nil并不会删除对象。

有一类元素可以起到容器的作用，它能容纳多个子元素，并按一定的方式进行排列布局。例如，hview是一个水平布局的容器，以下xml在hview中放置了三个按钮，它们将在水平方向上排列，同时第一个按钮和第二个按钮之间有可伸缩的空白。

<hview>
    <button id="bt1" title="Btn1" view-depend:trailing-stretch="1" />
    <button title="Btn2" />
    <button title="Btn3" />
</hview>

如果ui节点拥有id属性，可在lua中通过函数kiko.ui.get(id)获取元素对象。ui元素拥有一些公共方法，例如读取/修改属性的方法：

local btn = kiko.ui.get("btn1")
local btn_title = btn:getopt("title")  -- 获取按钮标题
btn:setopt("title", btn_title .. "_new_title")  -- 修改按钮标题

公共属性和方法

所有ui元素都具有如下属性，可以在xml或lua程序中读取/设置，但对于某些ui元素可能无效。

属性含义取值
idui元素的id
x元素的x坐标，在有布局的容器中可能失效
y元素的y坐标，在有布局的容器中可能失效
w宽度，在有布局的容器中可能失效
h高度，在有布局的容器中可能失效
max_w的最大宽度
max_h最大高度
min_w最小宽度
min_h最小高度
visible是否可见true/false
enable是否启用true/false
tooltip工具提示
h_size_policy宽度调整策略
影响元素在带有布局的容器中的宽度		fix: 固定
min: 当前宽度为最小宽度，容器有多余空间就扩张
max: 当前宽度为最大宽度，容器缩小时尽量缩小
prefer: 当前尺寸为最佳尺寸，被动扩张/收缩
expand: 主动扩张，尽可能占据空间
min_expand: 当前宽度为最小高度，尽可能扩张
ignore: 忽略尺寸，可随意扩张/收缩
v_size_policy高度调整策略取值同h_size_policy

以下方法为ui元素均支持的公共方法：

  • function getopt(property)

    property： string

    返回：不同属性返回类型不同

    获取ui元素的属性property，不存在返回nil

  • function setopt(property, val)

    property： string

    val: 不同属性类型不同

    返回：true/false

    设置ui元素的属性property为val

  • function data(key)

    key： string

    返回：string

    读取ui元素data中为key的属性。常见用法是在xml中设置属性data:key，之后在lua代码中读取，用于存储一些附加属性。

  • function setstyle(file, vals)

    file： string

    vals： table，变量表，可选

    返回：无

    设置ui元素的样式，具体见样式。如果file是有效文件路径，会读取文件内容设置样式，否则会直接将file作为样式内容进行设置。KikoPlay会对样式中出现在vals里的变量进行替换，参考样式

  • function addchild(content)

    content： string

    返回：成功返回子ui元素，失败返回nil

    为ui元素添加子节点，节点内容用xml描述。如果content是有效文件路径，会读取文件内容，否则会直接解析content。

  • function getchild(id)

    id： string

    返回：成功返回子ui元素，失败返回nil

    获取ui元素指定id的子节点。

  • function removechild(child)

    child： string/ui元素

    返回：空

    删除ui元素的子节点。

  • function parent()

    返回：ui元素的父元素，如果没有返回nil

    获取ui元素的父元素。

  • function onevent(event, func)

    event： string

    func: function

    返回：空

    绑定事件event响应函数为func。同一个事件只能绑定一个响应函数，重复绑定之前的会失效。

  • function adjustsize()

    返回：空

    自动调整ui元素的尺寸来适应内容。

事件绑定

在xml中，事件绑定通过属性来设置。事件在event命名空间内，即属性名为 event:事件名，例如为按钮的点击事件绑定处理函数：

 <button title="btn" event:click="onBtnClick"/>

默认情况下，绑定的事件处理函数要放到app表下。如果要将事件绑定到app表内的其他表里的处理函数，例如app.page1，可以这样写：

<button title="btn" event:click="page1.onBtnClick"/>

这样做可以将扩展App划分为不同模块，事件绑定到不同模块中处理。

在lua中，可以通过成员函数onevent绑定事件处理函数，对于动态创建的ui元素比较有用。

KikoPlay会向事件处理函数传递一个类型为table的参数，对于由ui元素触发的事件，table中都会包含两个成员：

  • srcId：触发事件的ui元素的id
  • src：触发事件的ui元素

容器

容器是一类可以容纳其他ui元素的元素，目前有五种：view, vview, hview, sview, gview。大部分容器包含布局，位于容器中的子元素将会按布局排列。子元素通常需要设置在容器中的位置、距离等布局依赖属性，这类布局依赖属性的命名空间是view-depend，以下是全部的布局依赖属性：

属性含义取值适用容器
leading-spacingui元素位置之前的距离hview, vview
trailing-spacingui元素位置之后的距离hview, vview
leading-stretchui元素位置之前的伸缩因子hview, vview
trailing-stretchui元素位置之后的伸缩因子hview, vview
stretchui元素的伸缩因子hview, vview
align对齐方式可以用或运算组合：
0x1(left) 0x2(right), 0x4(hcenter) 0x8(justify)
0x20(top) 0x40(bottom) 0x80(vcenter) 0x100(baseline)		hview, vview， gview
row行gview
col列gview
row-span行跨度gview
col-span列跨度gview
row-stretch行伸缩因子gview
col-stretch列伸缩因子gview

容器有以下公共属性：

属性含义取值
spacing布局中元素之间的默认距离
content_margin容器的边缘空白格式为 left,top,right,bottom

view

最基础的容器，不包含任何布局。

hview

水平布局容器，子ui元素会按水平排列。

vview

垂直布局容器，子ui元素会按垂直排列。

gview

网格布局，通过row和col布局属性将子ui元素放到不同的网格内。gview还有以下属性：

属性含义取值
h_spacing布局中元素水平方向的默认距离
v_spacing布局中元素垂直方向的默认距离
row-stretch行伸缩因子格式为：row1:stretch1(;row2:stretch2;...)
col-stretch列伸缩因子格式为：col1:stretch1(;col2:stretch2;...)

注意，布局依赖属性中的row-stretch和col-stretch只能设置ui元素所在行/列的伸缩因子，gview的 row-stretch和col-stretch属性可以设置多行/多列。

sview

堆叠布局，在构建多个页面时很有用。sview的每个元素将占据一个页面，可通过属性current_index获取/设置当前页面，页面从1开始。sview还有以下属性：

属性含义取值
current_index当前页从1开始
stack_mode堆叠模式one: 仅当前页面可见(默认)，all: 全部页可见
count页面数量(只读属性)

UI组件

本节将列出扩展App可用的全部UI组件。

button

按钮组件。

属性

属性含义取值
title按钮标题
checkable按钮是否可选中true/false
checked按钮是否已选中， 只有checkable=true才能设置选中true/false
btn_group按钮组，位于同一个按钮组的按钮只有一个可被选中

方法

  • function click()

    返回：空

    模拟按钮点击。

事件

事件table中的参数描述
click点击事件

checkbox

复选框组件。

属性

属性含义取值
title标题
check_state复选框选中状态0：未选中 1：部分选中 2：选中
checked按钮是否已选中， 只有checkable=true才能设置选中true/false
btn_group按钮组，位于同一个按钮组的按钮只有一个可被选中

方法

  • function click()

    返回：空

    模拟点击。

事件

事件table中的参数描述
check_state_changedstate: 复选框选中状态复选框状态变化事件

combo

下拉列表组件。

属性

属性含义取值
text下拉框文本
items列表条目（只写属性）用","分隔多个条目
current_index当前选择项目索引从1开始，未选择为0
editable是否可编辑true/false
count条目数量（只读属性）

方法

  • function append(item)

    function append(items)

    item： string/table，单个item

    items： array of item，多个item 返回：空

    向下拉列表中添加条目，支持同时添加单个或多个条目。

    item：一个字符串，或者一个table：

     {
     ["text"]="条目标题",
     ["data"]="条目附加数据"
 }

    使用table可以设置item的其他属性，这里支持通过data项为item附加一些其他数据，data支持lua的各种数据结构，例如table。示例：

     combo:append("条目1")
 combo:append({"条目2", "条目3"})
 combo:append({["text"]="条目4", ["data"]="test data"})
 combo:append({
     {["text"]="条目5", ["data"]="test data"},
     {["text"]="条目6", ["data"]="test data2"},
     "条目7"
 })

  • function insert(pos, item)

    function insert(pos, items)

    pos： 插入位置，从1开始

    item： string/table，单个item

    items： array of item，多个item 返回：空

    向下拉列表的指定位置插入条目，item和items的定义同append方法。

  • function item(index)

    index： 条目索引，从1开始

    返回：table结构的item

    获取指定位置的item。

  • function remove(index)

    index： 条目索引，从1开始

    返回：空

    删除指定位置的条目。

  • function clear()

    返回：空

    清空列表。

事件

事件table中的参数描述
current_changedindex: 当前选择项目
text: 当前项目的标题
data: 当前项目的data		下拉列表当前选择项目发生变化的事件
text_changedtext: 当前文本对于支持编辑的下拉列表，文本发生变化的事件

label

标签组件，支持设置html、图片。

属性

属性含义取值
title标签内容支持直接设置html
align文本对齐方式可以用或运算组合：
0x1(left) 0x2(right), 0x4(hcenter) 0x8(justify)
0x20(top) 0x40(bottom) 0x80(vcenter) 0x100(baseline)
scale_content是否缩放内容，显示图片时有效true/false，默认false
word_wrap是否自动换行true/false，默认false
open_link点击链接时是否自动打开true/false，默认false
text_selectable文本是否可选true/false，默认false

方法

  • function setimg(filepath)

    function setimg(image)

    filepath：文件路径

    image：image对象

    返回：空

    为label设置图片。可以设置文件路径，也可以直接设置image对象。如果为nil，则清空当前显示图片。

  • function getimg()

    返回：image对象

    获取label当前显示的图片，如果没有返回空。

  • function clear()

    返回：空

    清空标签内容。

事件

事件table中的参数描述
link_clicklink: 点击的链接标签内链接点击事件

list

列表组件，可以展示文本/图片列表，也支持显示包含复杂ui元素的条目。

属性

属性含义取值
count条目数量（只读属性）
current_index当前选择项目索引从1开始，未选择为0
word_wrap文本是否自动换行true/false，默认false
selection_mode选择模式none: 不能选择
single: 单选（默认）
multi：多选
alter_row_color是否用交替颜色绘制背景true/false
disable_h_scroll禁用水平滚动true/false
disable_v_scroll禁用垂直滚动true/false
h_scroll_visible水平滚动条是否可见true/false
v_scroll_visible垂直滚动条是否可见true/false
elide_mode文本太长时，'...'的展示位置left: 左侧
right: 右侧（默认）
middle：中间
none：不展示
view_mode视图模式icon: 图标模式
list: 列表模式（默认）
icon_size图标大小格式为：w,h
grid_size图标模式下网格大小格式为：w,h
is_uniform_size条目是否具有相同尺寸true/false，默认false

方法

  • function append(item)

    function append(items)

    item： string/table，单个item

    items： array of item，多个item

    返回：list当前条目数量

    向列表中添加条目，支持同时添加单个或多个条目。

    item：一个字符串，或者一个table：

     {
     ["text"]="条目标题",
     ["tip"]="提示内容",
     ["fg"]="前景色",  -- 整数，例如：0xffff00
     ["bg"]="背景色",  -- 整数，例如：0xffff00
     ["align"]="对齐方式",
     ["check"]="是否包含复选框",  -- none: 无复选框，true: 选中，false：未选中
     ["edit"]="是否可编辑",  -- true/false，1.0.3新增
     ["icon"]="图标",  -- 可以是文件路径、图片二进制数据或者Image对象
     ["data"]="条目附加数据", -- 支持lua的各种数据结构，例如table, function
 }

    添加条目的方式和下拉列表combo类似。

  • function insert(pos, item)

    function insert(pos, items)

    pos： 插入位置，从1开始

    item： string/table，单个item

    items： array of item，多个item

    返回：list当前条目数量

    向列表的指定位置插入条目，item和items的定义同append方法。

  • function item(index)

    index： 条目索引，从1开始

    返回：table结构的item

    获取指定位置的item。

  • function remove(index)

    index： 条目索引，从1开始

    返回：空

    删除指定位置的条目。

  • function clear()

    返回：空

    清空列表。

  • function set(index, key, val)

    index： 条目索引，从1开始

    key： 属性

    val： 属性值

    返回：空

    设置指定位置条目的属性，例如list:set(1, "text", "新标题")。

  • function selection()

    返回：选中的items

    获取list中被选中的条目。

  • function scrollto(index)

    index： 条目索引，从1开始

    返回：空

    滚动到指定位置的条目。

  • function setview(index, xml)

    index： 条目索引，从1开始

    xml： 视图xml，可以是文件路径，也可以是xml字符串

    返回：item的ui视图元素

    为指定位置的item设置ui元素视图。这个方法可以构造有复杂内容的item，例如item包含两行文本和一个按钮：

     local idx = comp_list:append("")
 local view = comp_list:setview(idx, string.format([[
     <hview> 
         <vview content_margin="0,0,0,0" view-depend:trailing-stretch="1">
             <label title="这是标题 %d" /> 
             <label title="Test View description......." />
         </vview> 
         <button id="btn" title="Button Test" />
     </hview>
     ]], idx))
 local btn = view:getchild("btn")
 btn:onevent("click", function(param) 
     kiko.log("复杂列表：" .. tostring(idx))
 end)

  • function getview(index)

    index： 条目索引，从1开始

    返回：item的ui视图元素

    获取指定位置item的ui视图元素，未设置返回空。

事件

事件table中的参数描述
item_clickitem: 点击的itemitem单击事件
item_double_clickitem: 点击的itemitem双击事件
item_changeditem: 修改的itemitem编辑事件，1.0.3新增
scroll_edgebottom: 是否滚动到底端滚动到边缘的事件，如果bottom=false，表示滚动到顶端

progress

进度条组件。

属性

属性含义取值
title标题格式，%p 被替换为完成的百分比，%v 被替换为当前值，%m 被替换为全部的步数默认为 %p%
min最小值
max最大值
value当前值
text_visible标题是否可见true/false
align对齐方式可以用或运算组合：
0x1(left) 0x2(right), 0x4(hcenter) 0x8(justify)
0x20(top) 0x40(bottom) 0x80(vcenter) 0x100(baseline)

方法

  • function click()

    返回：空

    模拟点击。

事件

事件table中的参数描述
check_state_changedstate: 复选框选中状态复选框状态变化事件

radio

单选框组件。 默认情况下，在容器同一层的单选框只能有一个被选中。

属性

属性含义取值
title标题
checked是否已选中true/false
btn_group按钮组，位于同一个按钮组的按钮只有一个可被选中

方法

  • function click()

    返回：空

    模拟点击。

事件

事件table中的参数描述
toggledchecked: 是否选中选中状态变化事件

slider

滑动条组件。

属性

属性含义取值
min最小值
max最大值
value当前值
step步长

事件

事件table中的参数描述
value_changedvalue: 当前值滑动条当前值改变事件

textline

单行文本组件。

属性

属性含义取值
text文本内容
placeholder_text提示文本
editable是否可编辑true/false
input_mask通过input_mask可以使文本框只接受特定格式的文本，具体参考这里
echo_mode回显模式，可用于密码输入场景0: 显示输入的字符(默认)
1: 不显示任何内容
2: 显示掩码
3: 编辑时显示输入的字符，否则显示掩码
show_clear_btn显示清空按钮true/false

事件

事件table中的参数描述
text_changedtext: 当前文本文本发生变化的事件
return_pressed按下回车键的事件

textbox

多行文本组件，支持展示html。

属性

属性含义取值
text文本内容
placeholder_text提示文本
editable是否可编辑true/false
open_link是否允许打开链接true/false，默认false
max_line最大行数默认为0表示无限制
word_wrap是否自动换行true/false，默认true
disable_h_scroll禁用水平滚动true/false
disable_v_scroll禁用垂直滚动true/false

方法

  • function append(text, is_html)

    text: 文本内容

    is_html: 是否为html，可选，默认false

    返回：空

    在文本框末尾添加文本。

  • function toend()

    返回：空

    光标移动到末尾。

  • function clear()

    返回：空

    清空文本框。

事件

事件table中的参数描述
text_changed文本发生变化的事件

tree

树形列表组件。

属性

属性含义取值
count最外层条目数量（只读属性）
col_count列数量（只读属性）
header_visible列头是否可见true/false，默认true
root_decorated最外层是否显示展开/折叠按钮true/false，默认true
sortable是否可排序true/false，默认false
word_wrap文本是否自动换行true/false，默认false
selection_mode选择模式none: 不能选择
single: 单选（默认）
multi：多选
alter_row_color是否用交替颜色绘制背景true/false
disable_h_scroll禁用水平滚动true/false
disable_v_scroll禁用垂直滚动true/false
elide_mode文本太长时，'...'的展示位置left: 左侧
right: 右侧（默认）
middle：中间
none：不展示

方法

  • function append(item)

    function append(items)

    item： array，单个item，item[i]指定了第i列的内容

    items： array of item，多个item

    返回：添加的item对象。如果添加了单个item，直接返回这个item对象；如果添加了多个条目，返回包含全部item对象的array

    在最外层添加条目，支持同时添加单个或多个条目。

    item：array，item[i]指定了第i列的内容，可以是一个字符串，也可以是table：

     {
     ["text"]="标题",
     ["tip"]="提示内容",
     ["fg"]="前景色",  -- 整数，例如：0xffff00
     ["bg"]="背景色",  -- 整数，例如：0xffff00
     ["align"]="对齐方式",
     ["check"]="是否包含复选框",  -- none: 无复选框，true: 选中，false：未选中
     ["edit"]="是否可编辑",  -- true/false，1.0.3新增
     ["icon"]="图标",  -- 可以是文件路径、图片二进制数据或者Image对象
     ["collapse"]="折叠还是展开",  -- true：折叠 false：展开
     ["data"]="条目附加数据", -- 支持lua的各种数据结构，例如table, function
 }

    示例：

     local tree = kiko.ui.get("tree")
 tree:setheader({"列1", "列2"})  
 tree:append({"text in col1", "text in col2"})  -- 添加一行
 -- 添加两行
 local items = tree:append({
     {"KikoPlay TreeTest", "Kikyou"},
     {{["text"]="00:01", ["bg"]=0xffff00, ["data"]="dt1"}, {["text"]="Hhhhhhhh", ["fg"]=0x0000ff}},
 })

  • function insert(pos, item)

    function insert(pos, items)

    pos： 插入位置，从1开始

    item： array，单个item，item[i]指定了第i列的内容

    items： array of item，多个item

    返回：插入的item对象。如果是单个item，直接返回这个item对象；如果添加了多个条目，返回包含全部item对象的array

    向列表的指定位置插入条目，item和items的定义同append方法。

  • function item(index)

    index： 条目索引，从1开始

    返回：item对象

    获取指定位置的item。

  • function remove(index)

    function remove(item)

    index： item索引，从1开始

    item：item对象

    返回：空

    删除指定位置的item，或删除item对象。

  • function clear()

    返回：空

    清空列表。

  • function indexof(item)

    item： item对象

    返回：item对象在其父节点中的索引

    获取item在父节点中的索引。

  • function selection()

    返回：array of items

    获取选中的items。

  • function setheader(headers)

    headers： array of string

    返回：空

    设置列。

  • function headerwidth(get_or_set, col, width)

    get_or_set： "get"/"set"，获取列宽还是设置列宽

    col： 列索引，从1开始

    width：列宽，如果是"get"，忽略这个参数

    返回：如果是"get"，返回对应列宽，否则为空

    设置/获取指定列的宽度。

item对象方法

item对象包含一系列方法来支持构建树：

  • function append(item)

    function append(items)

    item： array，单个item，item[i]指定了第i列的内容

    items： array of item，多个item

    返回：添加的item对象。如果添加了单个item，直接返回这个item对象；如果添加了多个条目，返回包含全部item对象的array

    为item添加子item，支持同时添加单个或多个条目，参数和tree的append方法相同。 示例：

     local tree = kiko.ui.get("tree")
 tree:setheader({"列1", "列2"})  
 -- 添加两行
 local items = tree:append({
     {"KikoPlay TreeTest", "Kikyou"},
     {{["text"]="00:01", ["bg"]=0xffff00, ["data"]="dt1"}, {["text"]="Hhhhhhhh", ["fg"]=0x0000ff}},
 })
 -- 向第二行添加子item
 items[2]:append({
   {{["text"]="00:01", ["fg"]=0xff0000, ["data"]="dt2"}, "child 1"},
 })

  • function insert(pos, item)

    function insert(pos, items)

    pos： 插入位置，从1开始

    item： array，单个item，item[i]指定了第i列的内容

    items： array of item，多个item

    返回：插入的item对象。如果是单个item，直接返回这个item对象；如果添加了多个条目，返回包含全部item对象的array

    向item下的指定位置插入条目，item和items的定义同append方法。

  • function parent()

    返回：item的父item

    获取item的父item，如果没有返回空。

  • function child(index)

    index： 条目索引，从1开始

    返回：item对象

    获取指定位置的子item。

  • function childcount()

    返回：子item数量

    获取子item数量。

  • function remove(index)

    function remove(item)

    index： item索引，从1开始

    item：item对象

    返回：空

    删除指定位置的子item，或删除子item对象。

  • function clear()

    返回：空

    清空子item。

  • function indexof(item)

    item： item对象

    返回：item对象在其父节点中的索引

    获取item在父节点中的索引。

  • function scrollto()

    返回：空

    滚动到item位置。

  • function get(col, key)

    col： 列索引，从1开始

    key： 属性

    返回：item指定列的属性

    获取item指定列的属性，例如item:get(1, "text")。icon属性无法获取。

  • function set(col, key, val)

    col： 列索引，从1开始

    key： 属性

    val： 属性值

    返回：空

    设置item指定列的属性，例如item:set(1, "text", "新标题")。

事件

事件table中的参数描述
item_clickitem: 点击的itemitem单击事件
item_double_clickitem: 点击的itemitem双击事件
item_changeditem: 修改的itemitem编辑事件，1.0.3新增
scroll_edgebottom: 是否滚动到底端滚动到边缘的事件，如果bottom=false，表示滚动到顶端

player

libmpv播放器组件，1.0.3新增。

方法

  • function property(name)

    name: 属性名称

    返回：err_code(错误码，没有错误为0), content(属性内容)

    获取libmpv属性信息，具体有哪些属性可参考mpv文档

  • function command(cmd)

    cmd: 包含命令每一部分的array

    返回：err_code(错误码，没有错误为0)

    向播放器发送没了，实例：

    player:command({"loadfile", filename}) --加载文件
player:command({"set", "volume", "10"})  -- 设置音量

事件

事件table中的参数描述
click播放区域点击
player_pos_changedpos: 当前位置(s); duration: 总时长(s)播放进度改变事件
player_state_changedstate: 0(播放) 1(暂停) 2(播放到结尾) 3(停止)播放状态变化事件
player_duration_changedduration: 总时长(s)总时长变化事件

window

目前app仅包含一个窗口，由KikoPlay创建。

属性

属性含义取值
title标题
pinned窗口是否顶置true/false
content_margin窗口的边缘空白格式为 left,top,right,bottom

方法

  • function show()

    返回：空

    显示窗口。

  • function raise()

    返回：空

    前置窗口。

  • function message(msg, flag)

    msg: 消息内容，string

    flag：标志

    返回：空

    显示提示消息。flag有以下取值，可以用或运算组合：

     kiko.msg.NM_HIDE           -- 自动隐藏
 kiko.msg.NM_PROCESS        -- 显示loading图标
 kiko.msg.NM_SHOWCANCEL     -- 显示取消按钮，目前无意义
 kiko.msg.NM_ERROR          -- 错误消息
 kiko.msg.NM_DARKNESS_BACK  -- 背景变暗

    默认情况下flag = kiko.msg.NM_HIDE，表示消息过一段时间后会自动隐藏。

UI相关类型

Image

Image类目前提供了简单的图片读写功能。

创建Image

createimg方法位于kiko.ui中。

  • function createimg(path)

    function createimg(params)

    path: 文件路径

    params：参数table

    {
  ["w"]=100, -- 宽，可选
  ["h"]=100, -- 高，可选
  ["data"]="", --图片二进制数据
  ["format"]=5, --格式，可选，参考 https://doc.qt.io/qt-5/qimage.html#Format-enum
}

    返回：image对象

    可以直接从文件加载，也可以通过params table从二进制数据加载。

    如果指定了宽/高，会对图片进行缩放。

Image对象方法

  • function size()

    返回：w, h

    获取图片尺寸。

  • function save(path)

    path：保存路径，string

    返回：true/false，是否保存成功

    保存图片到文件。

  • function tobytes(format)

    format: 格式，可选，默认为jpg

    返回：图片二进制数据

    将图片保存为二进制数据。

  • function scale(w, h, mode)

    w：宽度

    h：高度

    mode：模式，0:自由缩放(默认) 1:控制比例，确保图片在矩形内 2:控制比例，图片占满矩形

    返回：缩放后的图片

    对图片进行缩放。

通用对话框

kiko.dialog中包含如下函数，用于创建通用对话框：

  • function openfile(options)

    options: table，对话框选项:

    {
  title="对话框标题",
  path=env.app_path, -- 默认路径  
  filter="Images (*.jpg *png);;all (*.*)",  -- 过滤器
  multi = false  -- 是否支持选择多个文件
}

    返回：选择文件返回路径(string, or array of string，对应多个文件)，未选择文件返回nil

    显示打开文件对话框。

  • function savefile(options)

    options: table，对话框选项：

    {
  title="对话框标题",
  path=env.app_path, -- 默认路径  
  filter="Images (*.jpg *png);;all (*.*)",  -- 过滤器
}

    返回：保存文件路径，取消则返回nil

    显示保存文件对话框。

  • function selectdir(options)

    options: table，对话框选项：

    {
  title="对话框标题",
  path=env.app_path, -- 默认路径  
}

    返回：目录路径，取消则返回nil

    显示选择目录对话框。

  • dialog(dialog_config)

    dialog_config：Table，配置对话框显示内容，内容包括：

    {
   ["title"]=string,  --对话框标题，可选
   ["tip"]=string,    --对话框提示信息
   ["text"]=string,   --可选，存在这个字段将在对话框显示一个可供输入的文本框，并设置text为初始值
   ["image"]=string   --可选，内容为图片数据，存在这个字段将在对话框内显示图片
}

    返回：bool，string

    展示一个对话框，第一个返回值表示用户点击接受(true)还是直接关闭(false)，第二个返回值为用户输入的文本

样式

App同样支持Qt里的样式表，通过setstyle对ui元素及其子元素加载样式。具体请参考Qt Style Sheets。写法基本和css一致，KikoPlay做了一些扩展：

  • 变量替换

    标识符前有@表示是一个变量，KikoPlay会尝试进行替换，默认内置的变量：

    @AppPath：app路径
@AppDataPath: app数据路径
@StyleBGMode: 是否启用主题色
@ThemeColor： 主题色
@ThemeColorL1：主题色-提高亮度
@ThemeColorL2
@ThemeColorL3
@ThemeColorL4
@ThemeColorL5
@ThemeColorD1：主题色-降低亮度
@ThemeColorD2
@ThemeColorD3
@ThemeColorD4
@ThemeColorD5

    在setstyle的第二个参数中可以自定义其他变量。

  • 分支控制

    KikoPlay支持在QSS中使用条件语句，需要配合bool类型的变量，例如在启用主题色的情况下设置border-color：

    @if{StyleBGMode}
    border-color:rgb(@ThemeColor);
@else
    border-color:#1CA0E4;
@endif

include节点

通过include节点来包含其他xml文件，这样可以将app划分为不同模块/页面。include节点的属性会应用到被引用的文件的根节点上。示例：

<sview id="page">
    <include content_margin="0,0,0,0"> pages/page_widgets.xml  </include>
    <include content_margin="0,0,0,0"> pages/page_interaction.xml  </include>
    <include content_margin="0,0,0,0"> pages/page_network.xml  </include>
</sview>