diff --git a/docs/README.md b/docs/README.md index d4a19641..7939772e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -208,7 +208,7 @@ if __name__ == "__main__": -## 五、原理说明 +## 五、原理说明与进阶示例 在`PyGUIAdapter`中,函数是界面的基本单元,一个函数便对应了一个窗口,函数的参数列表则定义了窗口中的控件。`PyGUIAdapter`自动实现了“`输入(Input)-处理(Process)-输出(Output)`”链条中“`输入(Input)`”和“`输出(Output)`”这两个环节,因此,绝大多数情况下,开发者唯一需要关注的就是如何实现“`处理(Process)`”,即程序的核心功能或者说业务逻辑。 @@ -223,9 +223,7 @@ GUI创建和管理的过程对于开发者而言是透明的,开发者几乎 > `PyGUIAdapter`充分利用了Python的类型注解机制。在`PyGUIAdapter`中,函数参数的类型注解不是可有可无的,它是生成参数控件的决定因素之一。 > 虽然,并不是说不使用类型注解就完全无法利用`PyGUIAdapter`——`PyGUIAdapter`也允许开发者手动为每一个参数显式地指定控件——但是,这样会在很大程度上失去使用`PyGUIAdapter`的意义。所以,**我们强烈建议开发者对函数参数使用类型注解**。 - - -#### (一)异常处理 +### (一)异常处理 下面,以前文`equation_solver`程序为例,对`PyGUIAdapter`中的异常处理机制进行说明。 @@ -235,7 +233,7 @@ GUI创建和管理的过程对于开发者而言是透明的,开发者几乎 对于函数中的异常,`PyGUIAdapter`的默认策略是:**捕获它们,弹窗提醒用户,并在程序输出区域打印出异常信息。** 这样的设计主要是**为了增强程序的`健壮性`,防止未捕获的异常导致整个程序崩溃**。 -#### (二)在函数中打印信息 +### (二)在函数中打印信息 > 关于这一主题,以下文档作了更为详细的说明:[向窗口输出信息](adapter/output.md) @@ -307,9 +305,7 @@ if __name__ == "__main__": - - -#### (三)校验函数参数 +### (三)校验函数参数 虽然`PyGUIAdapter`对程序中的未捕获异常进行了处理,但仍然鼓励开发者尽力预见并避免可能发生的异常,这是提高程序健壮性、稳定性的基础之一。程序中的异常或错误,很多时候都源自于未经检验的用户输入,基于**“永远不要相信用户的输入”**这一共识,开发者应当对函数参数进行必要校验。 @@ -321,7 +317,7 @@ if __name__ == "__main__": **对于函数中抛出的`ParameterError`,`PyGUIAdapter`将进行弹窗提示,并在对应参数控件所在的区域,以醒目的方式提醒用户其输入了一个不合法的值。** -#### (四)为参数添加描述信息 +### (四)为参数添加描述信息 为了使参数的含义、用途更加明确,一个好的实践是界面上为参数添加适当的描述信息。在`PyGUIAdapter`中,有多种方法可以做到这一点,其中最简单也最自然的一种方法是在函数的文档字符串(`docstring`)对这些参数进行描述。很多开发者已经习惯于编写函数的`docstring`,而且现在的IDE或代码编辑器也已经足够智能,可以根据函数的签名,自动生成`docstring`模板,比如下面这样: @@ -339,7 +335,7 @@ if __name__ == "__main__": -#### (五)配置控件属性 +### (五)配置控件属性 为了提高程序的健壮性或增强用户体验,`PyGUIAdapter`允许开发者对函数参数控件的属性进行配置。比如,在当前示例函数中,参数`a`、`b`、`c`控件的初始值都是`0`,这显然是不合理的。另外,参数`a`、`b`、`c`的控件目前都只能输入小数点后两位数,无法满足输入更高精度数字的需求。下面,我们将通过对参数控件进行配置,来解决这两个问题。 @@ -415,7 +411,7 @@ if __name__ == "__main__": 在`PyGUIAdapter`中,不同的参数类型往往对应不同的控件类型,而不同类型的控件具有不同的可配置属性,开发者可以阅读这篇文档,来了解`PyGUIAdapter`内置的控件类型和对应的数据类型,以及其可供开发者配置的属性:[内置控件类型一览](widgets/types_and_widgets.md)。 -#### (六)配置窗口属性——一个“小窗口”模式的简单示例 +### (六)配置窗口属性——一个“小窗口”模式的简单示例 `PyGUIAdapter`运行开发者对窗口进行配置,调整窗口某些属性。比如下面的示例,实现了所谓的小窗口模式。 @@ -479,7 +475,7 @@ if __name__ == "__main__": - [函数选择窗口(FnSelectWindow)](windows/fn_select_window.md) - [函数执行窗口(FnExecuteWindow)](windows/fn_exec_window.md) -#### (七)添加工具栏与菜单 +### (七)添加工具栏与菜单 `PyGUIAdapter`允许开发者向窗口添加工具栏和菜单,并为工具栏按钮或菜单项的`动作(Action)`设置事件响应函数。