minigui-docs/programming-guide-zh/MiniGUIProgGuideAppendixD-zh.md

# 新控件集的开发规范

## 1 术语及其含义

- MiniGUI 新控件集（MiniGUI New Control Set，mGNCS）。新控件集不仅仅实现了多种可定制、可扩展的控件类，同时也实现了资源管理功能，以及对其他常用功能的面向对象封装，如主窗口、对话框、菜单等。
- 风格（Style）。用于控制窗口或者控件基本外观和行为的标志。
   - 新控件集的控件风格，仅用于不可动态修改的控件属性，例如进度条是垂直的还是水平的，就可以用风格来实现。在各控件的实现中，应尽量减少风格的使用。
   - 除保留 `WS_`、`WS_EX_` 等系统全局风格之外，MiniGUI 固有控件集定义的各控件风格不在新控件集中使用，新控件集中的控件风格将被重新定义。
   - 新控件集中，控件不再具有扩展风格。
- 属性（Property）。控件属性是一个新增的概念，一般用于那些可动态设置（如编辑框中的插入符位置），或动态改变（如列表框中的列表项数目）的控件特性。mGNCS 提供统一的接口（`getProperty`/`setProperty`）来获取或设置控件的属性。
- 渲染器（Renderer）。在 mGNCS 中，指控制主窗口或者控件外观的绘制方法集合，全称为“外观渲染器（Look and Feel Renderer）”，一般简称为“渲染器”。
   - 在新控件集中，每种可见的控件都会有自己的渲染器。为了和 MiniGUI 3.0 引入的渲染器相区别，我们将 MiniGUI 3.0 的渲染器称为“全局渲染器（global renderer）”，将新控件集引入的渲染器称为“控件渲染器（control renderer）”：
   - 全局渲染器作用于主窗口、老控件集以及新控件集的系统组件（如边框、标题栏、滚动条等非客户区元素）。
   - 控件渲染器仅作用于新控件集各个控件的客户区绘制。
- 窗口类名（Window Class Name）。为了和控件类的名称相区别，我们将 MiniGUI 用于子窗口的类名称为“窗口类名”。如静态框的控件类名为 `mStatic` ，而静态框的窗口类名为 `static_` 。
- 事件（Event）。在 MiniGUI 的传统编程模式中，存在消息（Message）和通知（Notification）两个概念，它们有各自的作用，但对应用程序开发者而言，它们均用于应用程序处理特定的事件。因此，从应用开发者看来，通知也好，消息也好，本质上都是一样的。因此，mGNCS 将消息和通知抽象为事件，从应用开发者角度看，每一个事件对应一个事件的处理器（Event Handler）。

## 2 新控件集的接口命名规范

新控件集的接口命名通常和类的名称有关，因此，在本文后面的规范描述中，类名的全小写方式、全大写方式、大小写混写方式、大写简写方式分别用 `<classname>`、`<CLASSNAME>`、`<ClassName>`、`<CLSNM>` 表示。

- 类名（指包含有方法，即函数指针的结构体）。新控件虽然采用 C 语言实现，但因为采用 OOP 思想，故而采用大小写混写的方式表示“类”的名称，并使用小写字母 m 作为前缀，如 `mWidget` ，以及对应的 `mWidgetClass` 。
- 一般性结构体。使用类似 MiniGUI 接口的全大写方式命名，并使用 `NCS<CLSNM>_` 作为前缀。
- 函数及参数的命名规范。
   - 新控件集新增全局的一般性函数，使用 `ncs` 作为函数名前缀，之后是描述函数功能的动宾短语，并使用大小写混写的方法命名，如 `ncsCreateWindow` 。
   - 面向控件开发者的函数接口，第一个参数应该是 `mWidget*` 或者对应的子类类型指针。
   - 控件类的方法命名：动宾短语，单词连写，除第一个单词外，其他单词的第一个字母大写，如 `void (*moveContent) (mWidget *)` 。
   - 控件类中的消息回调函数的命名规范为： `on<MessageName>` ，如 `void (*onSetFocus) (mWidget *)` 。
   - 控件消息的参数顺序和约定：按照 MiniGUI 定义的消息规范，定义其顺序和名字。
   - 控件渲染器接口的命名规范为： `<className>Renderer` 。
   - 渲染器接口的内部函数参数约定：第一个是 `mWidget*` 或者对应的子类类型指针，第二个参数一般为 `HDC` 。
   - 在新控件集中，凡是和 C++ 成员函数等同的函数，表示本对象的指针变量命名为 `self` ，而本对象对应的类指针为 `_class` 。
   - 函数接口中的参数名称，均使用 Java JDK 的风格进行命名（第一个单词全小写，其后的单词大小写混写），不再使用匈牙利命名法。
   - 只读的指针型参数类型和返回值类型，必须使用 `const` 关键词做修饰。
- 窗口类名。为了不和老控件集的窗口类名冲突，新控件集使用下划线（`_`）作为窗口类名的后缀，如 `static_` 。不使用前缀的原因，是为了在现有 MiniGUI 核心管理窗口类代码的算法下，尽量避免出现哈希冲突。窗口类名的 C 语言宏名称，则以 `NCSCTRL_` 作为前缀，如 `NCSCTRL_STATIC` 。

需要注意的是，由于我们采用的是用 C 语言来实现类似 C++ 语言的面向规则特性，为了防止不必要的错误，我们需要把命名规范当做语法规范来遵守，这样的目的在于：

- 通过各种宏来简化编程。
- 便于通过宏固定编程模式，按照固定的编程模式，易读，易实现，不易出错。
- 编译文档的生成和检索。
- 最大限度减少开发者的学习时间。

## 3 类名称及其标识符的定义规则

类名称、对应的窗口类名及其简写形式由下表给出：

| 类名称 | C 类名 | 窗口类名 Window classname | 类名简写 CLSNM | 备注 |
|:------|:------|:-------------------------|:--------------|:----|
| 超类           | mObject      | - | OBJ    | 非控件类；NCS 类层次关系中的最基础类 |
| 列表项基类     | mItem        | - | ITEM   | 非控件类；用于表述列表项的基础类 |
| 列表项管理器   | mItemManager | - | ITMMNG | 非控件类；用于管理列表项集合的方法类 |
| 列信息类       | mListColumn  | - | LSTCLM | 非控件类；描述列信息类 |
| 行列表项类     | mListItem    | - | LSTITM | 非控件类；管理一行中的列表项集合 |
| 组件基类       | mComponent   | - | CMPT   | 非控件类 |
| 不可见组件基类 | mInvsbComp   | - | IVCMPT | 非控件类 | 
| 定时器         | mTimer       | - | TIMER  | 非控件类 | 
| 控件基类       | mWidget      | `widget_`       | WIDGET | |
| 静态框         | mStatic      | `static_`       | STATIC | |
| 图片框         | mImage       | `image_`        | IMAGE  | |
| 矩形框         | mRect        | `rect_`         | RECT   | |
| 发光二极管标签 | mLEDLabel    | `ledlabel_`     | LEDLBL | |
| 分组框         | mGroupBox    | `groupbox_`     | GRPBOX | |
| 按钮组         | mButtonGroup | `buttongroup_`  | BTNGRP | |
| 按钮           | mButton      | `button_`       | BUTTON | |
| 检查钮         | mCheckButton | `checkbutton_` | CHKBTN | |
| 单选钮         | mRadioButton | `radiobutton_`  | RDOBTN | |
| 面板           | mPanel       | `panel_`        | PANEL  | |
| 组合框         | mCombobox    | `combobox_`     | CMBOX  | |
| 主窗口         | mMainWnd     | `mainwnd_`      | MNWND  | |
| 对话框         | mDialogBox   | `dialogbox_`    | DLGBOX | |
| 可滚动基类     | mScrollWidget| `scrollwidget_` | SWGT   | |
| 容器           | mContainer   | `container_`    | CTNR   | |
| 属性页         | mPage        | `page_`         | PAGE   | |
| 列表型基类     | mItemView    | `itemview_`     | ITEMV  | |
| 列表型         | mListView    | `listview_`     | LISTV  | |
| 图标型         | mIconView    | `iconview_`     | ICONV  | |
| 滚动型         | mScrollView  | `scrollview_`   | SCRLV  | |
| 列表框         | mListBox     | `listbox_`      | LSTBOX | |
| 进度条         | mProgressBar | `progressbar_`  | PRGBAR | |
| 属性表         | mPropSheet   | `propsheet_`    | PRPSHT | |
| 滑动器基类     | mSlider      | `slider_`       | SLIDER | |
| 滑动条         | mTackBar     | `trackbar_`     | TRKBAR | |
| 旋钮基类       | mSpinner     | `spinner_`      | SPNR   | |
| 旋钮框         | mSpinBox     | `spinbox_`      | SPNBOX | |
| 分隔栏         | mSeperator   | `seperator_`    | SPRTR  | |
| 月历           | mMonthCalendar | `monthcalendar_` | CDR | |
| 动画           | mAnimation   | `animation_`    | ANMT   | |
| 工具栏         | mToolBar     | `toolbar_`      | TLBAR  | |
| 滚动条         | mScrollBar     | `scrollbar_`      | SCRLBR  | |
| 编辑框基类     | mEdit        | `edit_`         | EDIT   | |
| 单行编辑框     | mSLEdit      | `sledit_`       | SLEDIT | |
| 多行编辑框     | mMLEdit      | `mledit_`       | MLEDIT | |

标识符的命名规则如下：

- 窗口类名标识符。为了不和老控件集的标识符名称冲突，新控件集使用 `NCSCTRL_<CLASSNAME>` 作为窗口类名标识符。
- 控件风格标识符。为了不和老控件集的风格名称冲突，新控件集使用 `NCSS_<CLSNM>_` 作为风格标识符的前缀。
- 控件属性标识符。新控件集使用 `NCSP_<CLSNM>_` 作为控件属性标识符的前缀。
- 控件通知码标识符。为了不和老控件集的通知码名称冲突，新控件集使用 `NCSN_<CLSNM>_` 作为控件通知码标识符的前缀。
- 类特有数据标识符。新控件集使用 `NCSSPEC_<CLSNM>_` 作为类特有数据的标识符前缀；如 mObject 类的特有数据，使用 `NCSSPEC_OBJ_` 作为前缀。 
- 类方法的参数及返回值所使用的标志、状态等。新控件集使用 `NCSF_<CLSNM>_` 作为这种标识符的前缀。 
- 函数接口及类方法的返回值标识符。新控件集使用 `NCSE_<CLSNM>_` 作为这种标识符的前缀。 
- 其他标识符。除上述标识符之外，其他类型的标识符，参照上述方法确定。

### 3.1 控件风格标识符的定义规则

在新控件集中，控件风格个数应该保持到最小，控件风格的取值范围为 0x00000000 ~ 0x0000FFFF，以免和 MiniGUI 定义的窗口风格混淆。

### 3.2 控件属性标识符的定义规则

控件属性标识符的规则：

   1. 在直系继承关系内，属性标识符的值不能重复，即子类的属性标识符不能覆盖父类及其祖先的属性标识符。
   2. 旁系继承关系内，属性标识符可以重复，即一个控件类的属性标识符可以和其兄弟控件类的属性标识符重复。

在技术上，利用 C 语言的枚举类型定义属性标识符，各控件的属性标识符前缀见上表。

   1. 每个控件属性标识符枚举变量中，最后一项定义为 `NCSP_<CLSNAM>_MAX` 。
   2. 每个控件属性标识符从其父类的最大属性标识符加一的值开始定义。
   3. 利用枚举型能够自动加一的特性，顺序定义各个属性。

例如，

```c
// mWidget 
enum mWidgetProp {
        NCSP_WIDGET_RDR,
        NCSP_WIDGET_MAX
};

// mStatic
enum mStaticProp {
        NCSP_STATIC_HALIGN = NCSP_WIDGET_MAX + 1,
        NCSP_STATIC_VALIGN,
        NCSP_STATIC_MAX
};
```

### 3.3 控件通知码的定义规则

控件通知码的规则类似属性标识符的规则。但需要注意的是，mGNCS 中不能使用 0 作为通知码。

## 4 新控件集的函数库以及头文件

尽管 mGNCS 是在开发 mStudio 的过程中引入的，但 mGNCS 也可作为 MiniGUI 3.0 上的一个组件而被单独使用。因此，我们将新控件集按照 MiniGUI 的一个组件来管理，因而定名为 mGNCS，函数库的名称为 `libmgncs`，当前版本为 1.0.0，头文件在系统头文件路径的 mgncs/ 目录下保存，主要的头文件名称为 `mgncs.h`。

当前的 mGNCS 定义了大量的通用控件，在不久的将来，我们还将在当前 mGNCS 的基础上形成针对特定领域的扩展控件集合，这时，将形成一个独立的函数库，其名称采用 `libmgncs4*` 的方式命名，头文件仍将保存在系统头文件路径的 `mgncs/` 目录下。