Skip to content

Commit

Permalink
docs: improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
zimolab committed Oct 8, 2024
1 parent fd093b2 commit 42846e8
Showing 1 changed file with 8 additions and 12 deletions.
20 changes: 8 additions & 12 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ if __name__ == "__main__":



## 五、原理说明
## 五、原理说明与进阶示例

`PyGUIAdapter`中,函数是界面的基本单元,一个函数便对应了一个窗口,函数的参数列表则定义了窗口中的控件。`PyGUIAdapter`自动实现了“`输入(Input)-处理(Process)-输出(Output)`”链条中“`输入(Input)`”和“`输出(Output)`”这两个环节,因此,绝大多数情况下,开发者唯一需要关注的就是如何实现“`处理(Process)`”,即程序的核心功能或者说业务逻辑。

Expand All @@ -223,9 +223,7 @@ GUI创建和管理的过程对于开发者而言是透明的,开发者几乎
> `PyGUIAdapter`充分利用了Python的类型注解机制。在`PyGUIAdapter`中,函数参数的类型注解不是可有可无的,它是生成参数控件的决定因素之一。
> 虽然,并不是说不使用类型注解就完全无法利用`PyGUIAdapter`——`PyGUIAdapter`也允许开发者手动为每一个参数显式地指定控件——但是,这样会在很大程度上失去使用`PyGUIAdapter`的意义。所以,**我们强烈建议开发者对函数参数使用类型注解**


#### (一)异常处理
### (一)异常处理

下面,以前文`equation_solver`程序为例,对`PyGUIAdapter`中的异常处理机制进行说明。

Expand All @@ -235,7 +233,7 @@ GUI创建和管理的过程对于开发者而言是透明的,开发者几乎

对于函数中的异常,`PyGUIAdapter`的默认策略是:**捕获它们,弹窗提醒用户,并在程序输出区域打印出异常信息。** 这样的设计主要是**为了增强程序的`健壮性`,防止未捕获的异常导致整个程序崩溃**

#### (二)在函数中打印信息
### (二)在函数中打印信息

> 关于这一主题,以下文档作了更为详细的说明:[向窗口输出信息](adapter/output.md)
Expand Down Expand Up @@ -307,9 +305,7 @@ if __name__ == "__main__":

<img src="images/ulogging.png" width="60%"/>



#### (三)校验函数参数
### (三)校验函数参数

虽然`PyGUIAdapter`对程序中的未捕获异常进行了处理,但仍然鼓励开发者尽力预见并避免可能发生的异常,这是提高程序健壮性、稳定性的基础之一。程序中的异常或错误,很多时候都源自于未经检验的用户输入,基于**“永远不要相信用户的输入”**这一共识,开发者应当对函数参数进行必要校验。

Expand All @@ -321,7 +317,7 @@ if __name__ == "__main__":

**对于函数中抛出的`ParameterError``PyGUIAdapter`将进行弹窗提示,并在对应参数控件所在的区域,以醒目的方式提醒用户其输入了一个不合法的值。**

#### (四)为参数添加描述信息
### (四)为参数添加描述信息

为了使参数的含义、用途更加明确,一个好的实践是界面上为参数添加适当的描述信息。在`PyGUIAdapter`中,有多种方法可以做到这一点,其中最简单也最自然的一种方法是在函数的文档字符串(`docstring`)对这些参数进行描述。很多开发者已经习惯于编写函数的`docstring`,而且现在的IDE或代码编辑器也已经足够智能,可以根据函数的签名,自动生成`docstring`模板,比如下面这样:

Expand All @@ -339,7 +335,7 @@ if __name__ == "__main__":

<img src="./images/docstring.png" />

#### (五)配置控件属性
### (五)配置控件属性

为了提高程序的健壮性或增强用户体验,`PyGUIAdapter`允许开发者对函数参数控件的属性进行配置。比如,在当前示例函数中,参数`a``b``c`控件的初始值都是`0`,这显然是不合理的。另外,参数`a``b``c`的控件目前都只能输入小数点后两位数,无法满足输入更高精度数字的需求。下面,我们将通过对参数控件进行配置,来解决这两个问题。

Expand Down Expand Up @@ -415,7 +411,7 @@ if __name__ == "__main__":

`PyGUIAdapter`中,不同的参数类型往往对应不同的控件类型,而不同类型的控件具有不同的可配置属性,开发者可以阅读这篇文档,来了解`PyGUIAdapter`内置的控件类型和对应的数据类型,以及其可供开发者配置的属性:[内置控件类型一览](widgets/types_and_widgets.md)

#### (六)配置窗口属性——一个“小窗口”模式的简单示例
### (六)配置窗口属性——一个“小窗口”模式的简单示例

`PyGUIAdapter`运行开发者对窗口进行配置,调整窗口某些属性。比如下面的示例,实现了所谓的小窗口模式。

Expand Down Expand Up @@ -479,7 +475,7 @@ if __name__ == "__main__":
- [函数选择窗口(FnSelectWindow)](windows/fn_select_window.md)
- [函数执行窗口(FnExecuteWindow)](windows/fn_exec_window.md)

#### (七)添加工具栏与菜单
### (七)添加工具栏与菜单

`PyGUIAdapter`允许开发者向窗口添加工具栏和菜单,并为工具栏按钮或菜单项的`动作(Action)`设置事件响应函数。

Expand Down

0 comments on commit 42846e8

Please sign in to comment.