7 频谱样式开发教程
Mashiro_Sorata edited this page 2 years ago

频谱样式开发

上面介绍了ADV-Plugin的一些配置项,现在我们将从零开始开发一个完整的第三方频谱样式项目。 第三方的频谱样式是SAO Utils 2中的一个插件形式存在,ADV-Plugin会识别catalogtop.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属性

AdvpStyleTemplatestyle属性为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属性

AdvpStyleTemplatepreference属性也为Component类型,为样式的可配置选项。推荐使用top.mashiros.widget.advp/qml/api路径下的AdvpPreference.qml组件,其为NERvGear.Preferences.PreferenceGroup的封装,支持NERvGear.Preferences中的各种Preference组件。其中的AdvpPreference组件的version属性为版本号,默认为空字符串""。可在选项列表的最上方查看到version值,若为空则不显示。

defaultValues属性

AdvpStyleTemplatedefaultValues属性为var类型,其主要是preference配置项的值,为Object。因为插件默认配置为defaultValues的配置,所以preference组件中的默认值推荐使用defaultValues中的值。

更多属性与方法可参考QML中的canvas组件,细节可参考下面的demo与SAO Utils 2的官方开发说明。 demo1与demo2的示例教程见对应的wiki页面:
demo1
demo2