Musicreater/msctLib/开发说明兼指南.md
2022-05-11 15:19:40 +08:00

257 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

开发说明\|指南
==============
***不要看了,这玩意没啥意义了。***
此文件旨在使后期欲参与开发之人员减轻其开发负担,同时也为了我们正在开发的人员详细说明功能与用法
掌握开发指南之后,在调用函数等的过程中将会更加方便
文件结构
--------
从主文件调用display.py以实现显示调用functions.py以使用功能
functions.py中会调取./addon/目录下的全部功能文件,这些功能文件必须先由./addon/addons.pkl来预先定义好
详细说明
--------
### msctLib
用于支持主要功能
#### display.py
1. class disp
- 参数
1. `**kwgs`对窗口的基础设定 `{ '组件名称' : 函数自设定 }` 例如:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ python
{
'version': '0.0.1', # version指的是当前配置格式的版本
'title': "音·创",
'geometry': '1200x900',
'iconbitmap': ('./resources/musicreater.ico', './resources/musicreater.ico'),
'menu' : { #对setMenu有特殊说明
'文件': {
'新建': <function>,
'打开': <function>,
},
},
'widget': { #对窗口部件又详细说明
'wordview':{
'text':'言·论',
},
'settingbox':{}, #后文详细说明
'tracklist':{},
'operation':{},
'map':{},
},
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 变量
1. `infoBar`
信息显示栏,一个字符串,用于显示一些信息。
2. `title`
窗口标题,字符串
3. `menuWidgets`
对于窗口菜单的设定,其格式如下:
```python
menuWidgets: dist = { # 菜单项目
str"菜单名" : dict{
str"选项名"|None : <function>选项函数
},
...
}
```
注:
`菜单名` : `str` 显示在菜单上的字符串
`选项名` : `str` 显示在菜单选项上的字符串
`选项函数` : `function` 菜单调取的函数(无返回值,无入参)
`选项名` 的布尔值判定为 `False` 的时候,无论 `选项函数` 为何,皆插入一段分割线,但 `选项函数` 不得为空
4. `wordView`
显示在言论上的文字,字符串
5. `buttons`
快捷功能按钮的列表列表的元素为字典字典的键是按钮的名称值为一个元组元组中含有两个元素其中元组的第1个元素为按钮图标是一个图片的路径第2个元素为执行的函数其值应当是一个函数对象。
值得注意的是,每个字典中包含的按钮组件会分到一个组之中,两个组之间会使用分隔符分割
```python
button: list = [
dict{ # 操作按钮部分
str"按钮名称" : tuple(
按钮图标,
执行函数
),
...
},
...
],
```
其中,如果执行图标找不到了或者无法读取了,就会使用“材质丢失”图标作为图标,当然也可以通过函数`setButtonBar`中的参数`defaultMissingTexturePath`来设置默认的在职丢失图标路径,同理,使用`separatorButtonTexturePath`可以设置默认的分割线路径……
但是啊但是我虽然建议用不同的display库来达到不同的显示效果……但我没说你们都带一套自己的图标包撒想要绘制图标包也很简单我们之后应该会出图标包的加载工具
6. `settingBox`
设置框,用于设置音乐的基本属性,例如词作者,曲作者等,设置格式如下:
```python
settingbox: list = [ #设置部分显示的字样及其对应的设置函数
tuple(
设置名称:str,
值类型:tuple,
显示内容:str,
设置操作函数:<function>,
),
...
]
```
其中,值类型可以是如下几个项
1. `('str',)` 字符串类型,使用文本框输入数据
2. `('bool',)` 布尔类型,使用复选框输入数据
3. `('num',最小值:float,最大值:float,步长:float = 1)` 数值类型,使用数值滑动条输入数据
4. `('list',列表项:list)` 单选类型,即列表中多选一,使用单选框输入数据
其中,值操作函数需要有一个参数,用于传递用户提供的设置值。
7. `notemap`
音符数据表,用于存储曲谱信息,存储格式如下
```python
notemap: list = [ # 音轨列表
dict{ # 单个音轨
'instrument' : str"乐器",
'velocity' : int 响度,
# 这里理论上需要写一个小节多少个X分音符
# 以及小节里的都是几分音符
# 但是这个留给以后来支持
int 小节编号 : [ # 一个小节
tuple( # 一个音符
时间 : int,
持续 : int,
乐器 : str,
采样 : float,
响度 : int,
),
...
],
...
},
...
]
```
其中,对于每个音符:
1. 时间 单位:帧 当前音符开始时,距离当前小节开始所经过的帧数
2. 持续 单位:帧 当前音符持续的帧数
3. 乐器 当前音符使用的乐器,需要在乐器列表中有所注册
4. 采样 当前音符在MC的采样音高(不含打击乐器)
5. 响度 单位:格的-1次方 音符播放源距离播放者的距离的倒数
- 函数
1. `setTitle`设置窗口标题
```python
:param title: str 窗口标题
```
修改了变量`self.title`之后需要执行此函数以切换标题,或者通过此函数修改窗口标题信息。
2. `setGeometry`设置窗口大小
```python
:param geometry: str 窗口大小
```
由于不希望您经常修改窗口大小,我就没有把窗口大小的变量放在类里面。只能通过这个函数来修改窗口大小。
3. `setIcon`设置窗口图标
```python
:param bitmap: str 图标路径
:param default: str 设置对于全局的默认图标路径
:retuen bool 是否成功设置图标
```
同上,我们不希望您经常修改窗口图标,所以没有把图标路径作为变量放在类里面。所以你只能通过这个函数修改窗口的图标。
值得注意的是default参数仅在Windows下有效如果在非Windows环境使用default参数将会引发一个错误
4. `setMenu`设置窗口菜单
实例化此类之后会运行这个函数进行窗口根菜单配置,如果当前对象中没有菜单,则会对其依照类中的响应参数进行配置,如果有则返回菜单中的内容(一个字典,键为菜单名称)
2. `setWidget`对窗口部件的放置
```python
wordview: dict = { #言论部分显示的字样
'text': str = 显示内容,
# ... 即可用 tk.Label 的参数
},
button: list = [
dict = {
按钮名称 : tuple(按钮图标,执行函数)
},
],
settingbox: list = [ #设置部分显示的字样及其对应的设置函数置操作函数:<function>,
)
],
map: list = [
音符数据
]
```
注:
值得注意的是在kwgs中修改的部件设置可以在其变量中读取或热修改对应的变量如下
| 参数 | 对应类中的变量 | 变量类型 | 说明 |
|------------|------------------|---------------------------|---------------------|
| wordview | wordview | str | 显示在 言·论 区域的文字 |
| button | button | list[dict{}] | 操作按钮 |
| settingbox | settings | list[ Any ] | 设置项目中的值 |
| tracklist | tracknum | tuple(int,int) | 当前选择到的音轨与音轨总数|
| map | notes | list[ class Note ] | 当前的音符列表 |
####
全曲的设置应该如下:
```python
标题 : str = '无名'
副标题 : str = ''
作曲 : str = '佚名'
作词 : str = ''
歌曲版权信息 : str = ''
# bpm 暂时不需要
```