【emWin实战教程V2.0】第54章 MULTIEDIT-多行文本控件

ti

转最新版本教程
本章节为大家讲解STemWin支持的多行文本控件，多行文本控件主要用于文本的编辑功能和文本的显示，比如制作一个简单的阅读器，使用此控件非常合适。
54.1 初学者重要提示
54.2 多行文本控件基础知识
54.3 使用GUIBuilder创建多行文本控件并用模拟器显示出来
54.4 官方WIDGET_MultieditTryIt.c实例
54.5 实验例程说明（RTOS）
54.6 实验例程说明（裸机）
54.7 总结

lee_st · 2017-3-11 16:31:14

54.1  初学者重要提示

1、初学者爱问的问题简单汇总：

      （1）问题1：多行文本控件中的光标可以去掉吗？
      答：可以的，通过函数WM_DisableWindow禁止多行文本控件即可，此时就看不到光标了，但是仍然可以操作多行文本控件添加或删除字符。或者通过函数MULTIEDIT_SetFocussable禁止聚焦也是可以的。
      （2）问题2：多行文本中的光标如何闪烁起来？
      答：通过函数MULTIEDIT_EnableBlink可以设置多行文本控件的闪烁周期。
      （3）问题3：多行文本中部分API函数容易使用错误，已经在本章节的54.2.3小节开头进行说明。
2、多行文本控件没有皮肤色。

lee_st · 2017-3-11 16:31:26

3、多行文本控件的所有API函数在emWin手册中都有讲解，下图是中文版手册里面API函数位置：

lee_st · 2017-3-11 16:31:37

下图是英文版手册里面API函数的位置：

lee_st · 2017-3-11 16:31:50

54.2 多行文本控件基础知识

MULTIEDIT控件可编辑多行文本，它既可以被用作简单的文本编辑器，也可以用来显示静态文本，做一个简易的文本阅读器很方便，并且支持滚动条。下表显示了MULTIEDIT控件的外观：

lee_st · 2017-3-11 16:32:01

早期版本，多行文本控件默认的显示效果如下：

现在版本，默认的显示效果如下（扁平化效果）：

lee_st · 2017-3-11 16:32:13

4.2.1 多行文本控件支持的通知代码

多行文本支持的通知代码主要是用来处理多行文本消息用的，多行文本控件主要支持五种消息事件，点击消息，释放消息，移开消息(点击了多行文本，且从多行文本所在的区域移开了但没有释放)，滚动条位置更改消息和多行文本控件的数值（内容）被更新消息。比如用户通过触摸屏点击了多行文本，窗口管理器会给多行文本父窗口回调函数发送消息WM_NOTIFY_PARENT来通知父窗口，进而再区分是五种消息中的哪一种，用户就可以在相应的消息代码里面加入要实现的功能。

以下事件是作为WM_NOTIFY_PARENT消息的一部分由多行文本控件发送给其父窗口，用来区分不同的多行文本消息。

实际项目中主要使用多行文本控件的点击消息或者释放消息，通过点击后弹出一个小键盘，往此控件里面输入文本，其它的消息类型很少用到。

lee_st · 2017-3-11 16:32:26

54.2.2 多行文本控件支持的键盘反应（输入聚焦）

多行文本控件支持输入聚焦，也支持外置键盘或者类似外置键盘的输入设备给多行文本控件发消息。当前仅支持以下七种按键消息：
（输入聚焦是一个重要的知识点，使用外置键盘或者类似外置键盘的输入设备要用到）

特别注意一点，对于多行文本来说，要先聚焦到这个控件上了，给多行文本发送按键消息才会有反应。

lee_st · 2017-3-11 16:32:40

54.2.3 多行文本控件API函数

   多行文本控件的API函数比较多，虽然调用都不难，但是容易理解错误，我们这里把几个容易理解错误的函数特别解释下：
1、函数MULTIEDIT_GetTextSize
   此函数返回的是当前多行文本控件所显示的字符数占用的大小。
2、函数MULTIEDIT_SetBufferSize
      函数MULTIEDIT_SetBufferSize设置的是多行文本控件支持的最大缓冲大小，含提示符和文本。这个函数的作用是作为字符的缓冲，用于临时记录提示符和文本。

lee_st · 2017-3-11 16:32:50

3、函数MULTIEDIT_SetMaxNumChars
此函数跟MULTIEDIT_SetBufferSize没有任何关系，函数MULTIEDIT_SetMaxNumChars设置的是多行文本控件最多可以显示的字符数，含提示符和文本。
4、函数MULTIEDIT_AddKey
此函数主要用于键盘或者类似键盘的输入设备给多行文本控件输入字符或者多行文本控件支持的键盘响应命令，比如GUI_KEY_UP，GUI_KEY_DOWN，GUI_KEY_DELETE等。如果使用emWin的按钮设置的软键盘，也可以使用这个函数。

lee_st · 2017-3-11 16:32:58

5、函数MULTIEDIT_AddText
      此函数用于在光标指定的位置添加新的字符串，特别注意所添加的字符串区域必须包含结束符。
6、函数MULTIEDIT_SetText
      此函数用于设置多行文本控件显示字符，调用这个函数显示字符都会将上次的显示清空。
7、函数MULTIEDIT_SetPrompt
      此函数用于设置多行文本控件的提示符，提示符是在多行文本控件里面开头最先显示的，不管什么时候调用这个函数，而且提示符部分不支持光标显示。

lee_st · 2017-3-11 16:33:10

本章节教程配套例子是将多行文本控件配合对话框一起使用的，实际项目中也推荐大家这么做，可以很方便的进行界面管理。在对话框上面使用多行文本控件是通过函数MULTIEDIT_CreateIndirect()来实现的。根据第41章41.7.1小节讲解的_CreateIndirect()函数，GUI_WIDGET_CREATE_INFO结构体类型定义如下：

lee_st · 2017-3-11 16:33:17

typedef struct {
GUI_WIDGET_CREATE_FUNC * pfCreateIndirect;    // 间接创建函数
const char * pName;                           // 控件名(不是所有控件都需要)
I16 Id;                                       // 控件ID
I16 x0, y0, xSize, ySize;                     // 控件的坐标位置和大小
I16 Flags;                                    // 控件用到的标志，没有就写0
I32 Para;                                     // 控件用到的参数，没有就写0
U32 NumExtraBytes;                            // 函数 _SetUserData & _GetUserData用到的
// 额外字节。
} GUI_WIDGET_CREATE_INFO;

lee_st · 2017-3-11 16:33:27

上面结构体成员里面的标记Flags和参数Para是可选的，函数MULTIEDIT_CreateIndirect()都用到了，标记Flags与函数MULTIEDIT_CreateEx的形参BufferSize是等效的，参数Para与函数MULTIEDIT_CreateEx ()的形参ExFlags是等效的，具体这两个形参的含义看emWin官方手册中的说明即可。
这里举一个对话框资源列表里面创建多行文本控件的例子，帮助大家更好的理解：

lee_st · 2017-3-11 16:33:36

/*
*********************************************************************************************************
*                           宏定义
*********************************************************************************************************
*/
#define ID_FRAMEWIN_0  (GUI_ID_USER + 0x00)
#define ID_MULTIEDIT_0 (GUI_ID_USER + 0x01)

/*
*********************************************************************************************************
*                           GUI_WIDGET_CREATE_INFO类型数组
*********************************************************************************************************
*/
static const GUI_WIDGET_CREATE_INFO _aDialogCreate[] =
{
  { FRAMEWIN_CreateIndirect, "Framewin", ID_FRAMEWIN_0, 0, 0, 800, 480, 0, 0x0, 0 },
  { MULTIEDIT_CreateIndirect, "Multiedit", ID_MULTIEDIT_0, 40, 30, 700, 78, 0, 0x0, 0 },
};

lee_st · 2017-3-11 16:33:44

上面的对话框资源列表里面依次创建了框架窗口控件，多行文本控件。多行文本控件的参数和GUI_WIDGET_CREATE_INFO结构成员的对应关系如下：

pfCreateIndirect = MULTIEDIT_CreateIndirect;
pName = "Multiedit";
Id = ID_MULTIEDIT_0;
x0 = 40;
y0 = 30;
xSize = 700;
ySzie = 78;
Flags = 0;
Para = 0x0;
NumExtraBytes = 0;

lee_st · 2017-3-11 16:33:53

对于这个对应关系要注意以下三点：
1、这里的x0和y0坐标位置是相对于对话框资源列表中框架窗口的客户端窗口的位置坐标。
2、参数Para设置为0x0不是说多行文本控件最大可以存入0个字符，配置为0的话应该是有个默认的配置数值，具体是多大，手册上面没有给出，实际应用中建议用户配置此选项。GUIBuilder生成的代码也是将其配置为0，建议用户配置下，做到心中有数。
3、Id号，这里的Id号是用户自定义的，emWin在GUI.h文件中也定义了部分多行文本控件的Id号，用户是可以直接使用的：