feat(ui): 为 prompt 模块书写文档

plugins/lib/ui/prompt.tin

@@ -16,7 +16,7 @@ PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>)
 ///// prompt 是 PaoTin++ 中非常重要的 UI 插件，现行 UI 的主要元素都是由 prompt 来支撑的。
 /////
 ///// prompt 插件把整个 TinTin++ 屏幕划分为七个区域，从上到下依次为：
-///// 
+/////
 ///// Top line1
 ///// Top line2
 ///// ...
@@ -30,52 +30,52 @@ PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>)
 ///// Bot lineN
 ///// ----------- BotSepBar --------------
 ///// <提示符>:（输入区）
-///// 
+/////
 ///// 输入区前面的提示符部分可以用 API prompt.Change 来修改。
-///// 
+/////
 ///// 除输入区和游戏区之外，剩下五个区域都可以定制，用来显示信息内容（以下称为字段）。
 ///// 每一行都可以有多个字段。字段在视觉上由两部分组成，字段标签和字段内容。
 ///// 其显示样式分别可以控制，并受到几个 prompt 特性的影响，下面会分别予以介绍。
-///// 
+/////
 ///// 字段的编排是高度可定制的，每个字段的标签、内容、颜色、显示风格、行为属性，
 ///// 都可以通过自己修改 #list prompt-fields 来修改。下面是对 #list prompt-fields
 ///// 的格式说明，但不建议直接在此处修改变量，请通过 var/etc/ui-settings.tin 来修改。
 ///// prompt 模块在启动时会自动加载该文件。
-///// 
+/////
 ///// #list prompt-fields 是一个列表，其中中每个元素是一个 tt++ table，代表一个字段。
 ///// tt++ table 由一组选项和与之对应的选项值来组成，用来说明想要定制的字段的选项。
-///// 
+/////
 ///// 下面是所有可供设置的字段选项：
-///// 
+/////
 ///// 1. place 枚举值 可选项: {Top|TopSepBar|MidSepBar|Bot|BotSepBar}
 /////    希望将字段显示在屏幕上的什么位置。
 /////    其中 {Top} 和 {Bot} 支持多行，其它三个只有一行。
 /////    默认为 BotSepBar。
-///// 
+/////
 ///// 2. line 自然数
 /////    只有 place={Top|Bot} 才支持 line，代表第几行，最上面是第一行。
 /////    默认为 1。
-///// 
+/////
 ///// 3. order 自然数
 /////    在同一行中的次序，默认按照在 list 中出现的顺序来排序。
-///// 
+/////
 ///// 4. label 中英文字符串
 /////    字段标签，每个字段都可以有一个标签，显示在内容前面。
 /////    默认为空白。
-///// 
+/////
 ///// 5. color tintin 格式的颜色代码，例如 <ddd>
 /////    字段值的颜色，通过该选项可以为字段值指定一个与配色主题不一样的颜色。
 /////    一般来说只有极个别选项才需要特别的颜色，没必要为每个选项都指定颜色，
 /////    因为那样的话你还不如去设置配色主题，参见下面配色主题的设置。
 /////    默认为空白，代表采用配色主题。
-///// 
+/////
 ///// 6. name 英文字符串 不能为空
 /////    字段名称，必须唯一，不能重复。
-///// 
+/////
 ///// 7. width 整数
 /////    字段内容的宽度，如果字段内容长度变化较大，可以设置一个固定宽度，以免晃动。
 /////    默认为 0，表示按照内容长度自动适配。
-///// 
+/////
 ///// 8. visibility 枚举值 {HideEmpty|HideCool|HideZero|HideLabel|Always}
 /////    含义如下：
 /////     * HideEmpty 如果字段内容为空则不予显示。
@@ -85,7 +85,7 @@ PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>)
 /////     * Always    总是显示该字段的标签和内容。
 /////    所有的 Hide* 选项自动拥有 HideEmpty 语义。
 /////    默认为 HideEmpty。
-///// 
+/////
 ///// 9. cooldown 非负整数
 /////    该字段的有效时间。超过有效时间没有更新的字段将在视觉上予以弱化显示，以提醒
 /////    用户。也就是说，如果 cooldown 不为 0，则该字段被更新时其标签将会以颜色主题
@@ -95,7 +95,7 @@ PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>)
 /////    陈旧的内容遇到 visibility=HideCool 时则不予显示。
 /////    如果 cooldown 为 0，则不会以 CoolLabel 风格显示。
 /////    默认值为 0。
-///// 
+/////
 ///// 10. countdown 枚举值 {Auto|Clock|Seconds}
 /////    倒计时类型的字段。其内容为一个非负整数，代表需要倒计时的秒数，或者也可以夹杂
 /////    于文字内容当中，此时文字内容中所有形如 (%d) 的内容将会被替换成倒计时显示。
@@ -157,7 +157,24 @@ VAR {命令输入提示符} prompt-prompt {Input};
     #return true;
 };
 
-#nop 设置字段值，被设置的字段值将立即显示在屏幕上;
+///=== {
+///// 下面是本模块的一些常用方法：
+/////
+// ## prompt.Set <表格>
+//    将表格中指定的字段和值，设置到 prompt 字典中。如果配置文件中存在该字段的配置，
+//    则会显示到屏幕上。
+//
+//    参数是一个由字段名和字段值组成的表格，例如：
+//
+//    #nop 为 note 字段设置值。;
+//    prompt.Set {{note}{我是一条随手笔记}};
+//
+//    #nop 对大多数字段而言，将值设置为空会隐藏该字段。;
+//    prompt.Set {{note}{}};
+//
+//    #nop 也可同时为多个字段设置值。;
+//    prompt.Set {{foo}{一些值} {bar}{另一些值}};
+// };
 #alias {prompt.Set} {
     #local fields   {%1};
 
@@ -174,15 +191,11 @@ VAR {命令输入提示符} prompt-prompt {Input};
     };
 };
 
-#nop 设置提示符，提示符位于屏幕最下方输入区的首部，用作指示整个游戏所处的状态;
-#alias {prompt.Change} {
-    #local text {%1};
-
-    #var prompt-prompt {$text};
-    #echo {{\r\e[K$prompt-prompt}{-1}};
-};
-
-#nop 设置字段值，被设置的字段值将立即显示在屏幕上，但会在一段时间后消失;
+///=== {
+// ## prompt.SetAwhile <字段名> <字段值> [<持续时间>]
+//    设置字段值，被设置的字段值将立即显示在屏幕上，但会在一段时间后消失。
+//    如果省略持续时间，则默认为 5 秒。
+// };
 #alias {prompt.SetAwhile} {
     #local id    {%1};
     #local value {%2};
@@ -590,17 +603,31 @@ VAR {命令输入提示符} prompt-prompt {Input};
 
 #event {CATCH IAC SB NAWS} {#0};
 
+///=== {
+// ## prompt.Disable
+//    禁止 prompt 更新。一般用作调试，可以防止 prompt 自身的运行产生的大量日志干扰调试。
+//    参见 prompt.Enable。
+// };
 #alias {prompt.Disable} {
     prompt.Set {{disable}{${prompt-icon[DisableRefresh]}}};
     prompt.refresh;
     #untick prompt.refresh;
 };
 
+///=== {
+// ## prompt.Enable
+//    允许 prompt 更新。
+//    参见 prompt.Disable。
+// };
 #alias {prompt.Enable} {
     prompt.Set {{disable}{}};
     Tick prompt.refresh {prompt.refresh} 1;
 };
 
+///=== {
+// ## prompt.ToggleSwitch
+//    在 prompt.Disable 和 prompt.Enable 之间切换。
+// };
 #alias {prompt.ToggleSwitch} {
     #if { "${prompt-dict[disable][value]}" == "" } {
         prompt.Disable;
@@ -619,6 +646,17 @@ VAR {命令输入提示符} prompt-prompt {Input};
     };
 };
 
+///=== {
+// ## prompt.Change <提示符>
+//    设置提示符，提示符位于屏幕最下方输入区的首部，用作指示整个游戏所处的状态。
+// };
+#alias {prompt.Change} {
+    #local text {%1};
+
+    #var prompt-prompt {$text};
+    #echo {{\r\e[K$prompt-prompt}{-1}};
+};
+
 ///=== {
 // ## prompt.HotKeys
 //    显示系统已配置的热键清单。
@@ -645,6 +683,11 @@ VAR {命令输入提示符} prompt-prompt {Input};
     #echo;
 };
 
+///=== {
+// ## prompt.Note <文本>
+//    发表一条随手笔记。随手笔记是个很实用的功能，可以把短期内需要用户注意的事情醒目地显示在屏幕上。
+//    本命令也可写作 NOTE，作用相同。
+// };
 #alias {NOTE} {prompt.Note};
 #alias {prompt.Note} {
     prompt.Set {{note}{%0}};
@@ -657,6 +700,10 @@ VAR {命令输入提示符} prompt-prompt {Input};
     };
 };
 
+///=== {
+// #@ prompt.ScreenWidth
+//    返回屏幕宽度。
+// };
 #func {prompt.ScreenWidth} {
     #if { $prompt-screen-width == 0 } {
         #screen get COLS prompt-screen-width;