频谱样式开发
上面介绍了ADV-Plugin的一些配置项,现在我们将从零开始开发一个完整的第三方频谱样式项目。
第三方的频谱样式是SAO Utils 2中的一个插件形式存在,ADV-Plugin会识别catalog
为top.mashiros.advp-style
的频谱样式插件并加入样式选项列表中。
目录结构
一个完整的项目目录示例如下,这个Style插件内包含:
top.mashiros.3rd-party-style-demo.advp
├── Demo1.qml
├── Demo2.qml
└── package.json
其中package.json
为SAO Utils 2的插件声明文件,Demo1.qml
为Demo1的样式文件,Demo2.qml
为Demo2的样式文件。
开发接口(API)
在开发过程中推荐将开发者模式中的“显示日志窗口”打开,以便定位错误。
ADV-Plugin的插件接口Qml文件一般使用QtObject,其必须包括style
(Component
类型)、preference
(Component
类型)与defaultValues
(var
类型)这3个属性,可直接使用top.mashiros.widget.advp/qml/api
路径下的AdvpStyleTemplate.qml
组件。
style
属性
AdvpStyleTemplate
的style
属性为Component
类型,为显示在挂件中的组件。一般可使用top.mashiros.widget.advp/qml/api
路径下的AdvpCanvasTemplate.qml
组件,其为Canvas
组件的封装。下面为它的一些常用的属性与函数。
width
:只读,画布的宽度,也为插件的显示宽度。height
:只读,画布的长度,也为插件的显示长度。context
:只读,Canvas的2D上下文。configs
:只读,若此样式包含配置项,则其值为preference
组件所保存的设置值(JSON格式);否则为undefined
。onAudioDataUpdeted
:可写,数据更新时的处理代码,带有一个长度为129数组参数:data
。前64个数据为左声道FFT数据,后64个数据为右声道FFT数据,每一个声道的FFT数据位从低到高对应频谱频率的由低到高。最后一个数据为动态归一化的峰值数据(自动归一化时,第i个频谱数据大小 =data[i]/data[128]
)。onConfigsUpdated
:可写,属性configs
或者context
改变时的处理代码,函数无参数。onCompleted
:可写,组件加载完成时调用,可进行一些初始化操作。requestPaint
:函数,调用此函数使Canvas绘制图形。onVersionUpdated
:可写,版本更新时的处理代码,带有一个参数old
,为旧版本号。默认调用updateObject
函数进行处理。updateObject
:函数,更新对象值,效果参考Object.assign操作,且支持嵌套的一级子对象的更新操作。
如非必要,推荐不写覆盖onVersionUpdated
,使用默认值可防止选项更新后导致插件错误,同时尽可能保留用户设置。版本号更新后,默认会将历史挂件设置值与现有版本的选项默认值合并更新,效果参考Object.assign
操作,且支持嵌套的一级子对象的更新操作,如:
更新前设置值:
{"demo":{"data1":1}}
更新选项的默认值:
{"demo":{"data1":2,"data2":3}}
更新后的设置值:
{"demo":{"data1":1,"data2":3}}
注意:旧设置会覆盖新设置,并添加新增设置,尽量避免更改旧设置的数据类型以免造成插件错误,尽量避免使用两级以上的对象嵌套,如{"demo":{"demo1":{"data":0}}}
。
preference
属性
AdvpStyleTemplate
的preference
属性也为Component
类型,为样式的可配置选项。推荐使用top.mashiros.widget.advp/qml/api
路径下的AdvpPreference.qml
组件,其为NERvGear.Preferences.PreferenceGroup
的封装,支持NERvGear.Preferences中的各种Preference组件。其中的AdvpPreference
组件的version
属性为版本号,默认为空字符串""
。可在选项列表的最上方查看到version
值,若为空则不显示。
defaultValues
属性
AdvpStyleTemplate
的defaultValues
属性为var
类型,其主要是preference
配置项的值,为Object
。因为插件默认配置为defaultValues
的配置,所以preference
组件中的默认值推荐使用defaultValues
中的值。
更多属性与方法可参考QML中的canvas组件,细节可参考下面的demo与SAO Utils 2的官方开发说明。
demo1与demo2的示例教程见对应的wiki页面:
demo1
demo2