Musicreater/msctLib/开发说明兼指南.md

开发说明\|指南
==============

***不要看了，这玩意没啥意义了。***

此文件旨在使后期欲参与开发之人员减轻其开发负担，同时也为了我们正在开发的人员详细说明功能与用法
掌握开发指南之后，在调用函数等的过程中将会更加方便

文件结构
--------

从主文件调用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 暂时不需要


```