tech.txt

中文编程语言——易语言(可视化编程

    每种数据类型数据的存储格式（用对应的C++数据类型说明）：

    A、如果不为数组：
        SDT_BYTE：     BYTE
        SDT_SHORT：    SHORT
        SDT_INT：      INT
        SDT_INT64：    INT64
        SDT_FLOAT：    FLOAT
        SDT_DOUBLE：   DOUBLE
        SDT_DATE_TIME：DATE
        SDT_BOOL：     BOOL
        SDT_TEXT：为一个指针，指针指向以0结束的字符串数据，如果指针值为NULL表示为空串。

        SDT_BIN：为一个指针，如果为NULL表示为空字节集。指针所指向的数据格式等同于字节数组，即：
            1、一个恒定为数值1的INT；
            2、一个INT记录数据的长度；
            3、相应长度的数据；

        窗口单元和菜单数据类型：
            1、一个DWORD记录窗口模板ID；
            2、一个DWORD记录窗口单元/菜单项的ID。

        复合数据类型（即非窗口单元和菜单的用户或库定义数据类型）：
            为一个必定不为NULL的指针值，该指针所指向的数据格式为：

                顺序排列所有成员，注意任何成员如果数据尺寸小于4个字节，都会被自动对齐到4个字节。
                如以下复合类型：
                    字节型      A
                    短整数型    B
                    整数型      C
                则整个复合类型所占用的空间为 12 个字节，其中 A 和 B 都被对齐到 4 个字节，
            因此 B 从第 4 个字节开始，C 从第 8 个字节开始。

    B、如果为数组：
        为一个必定不为NULL的指针值，该指针所指向的数据格式为：
        1、一个INT记录该数组的维数（必定大于0）。
        2、对应数目的INT值顺序记录对应维的成员数目（必定大于0）。
        3、数组数据本身，格式为：
            A、SDT_TEXT、SDT_BIN：
               为指针数组，每个指针都指向一个单独的数据成员地址（注意指针值可能为NULL，
               此时表示为一个空文本或者空字节集）。
            B、窗口单元、菜单数据类型和简单数据类型：
               为不为数组情况下数据的顺序排列；
            C、复合数据类型：
               为指针数组，每个指针都指向一个单独的数据成员地址。

    C、注意：访问任何数据时，注意只能访问等同该数据长度（即非对齐长度）的数据。比如读
    写一个字节型数据，只能假设只有此一个字节是可以访问的。有此限制的原因是当以传址的
    方式将一个数组成员的指针传递到下一个子程序时，该指针处只有数组成员实际长度是可供
    访问的（数组成员不会以4字节对齐）。

/*****************************************************************/

5、m_pfnNotify 成员说明：

    本函数指针所指向的函数用作接收来自易语言IDE或者运行时环境的通知，其原型定义如下：

    typedef INT (WINAPI *PFN_NOTIFY_LIB) (INT nMsg, DWORD dwParam1 = 0, DWORD dwParam2 = 0);

    例子如下：

    PFN_NOTIFY_SYS g_fnNotifySys = NULL;

    INT WINAPI ProcessNotifyLib (INT nMsg, DWORD dwParam1, DWORD dwParam2)
    {
        INT nRet = NR_OK;

        switch (nMsg)
        {
        case NL_SYS_NOTIFY_FUNCTION:
            g_fnNotifySys = (PFN_NOTIFY_SYS)dwParam1;
            /*
                上面代码获得用作通知信息到易语言IDE或运行时环境的函数指针，获得指针后
            即可建立类似下面函数用作通知信息到易语言IDE或运行时环境。

                INT WINAPI NotifySys (INT nMsg, DWORD dwParam1, DWORD dwParam2)
                {
                    ASSERT (g_fnNotifySys != NULL);
                    if (g_fnNotifySys != NULL)
                        return g_fnNotifySys (nMsg, dwParam1, dwParam2);
                    else
                        return 0;
                }
            */
            break;
        default:
            nRet = NR_ERR;
            break;
        }

        return nRet;
    }

/*****************************************************************/

6、m_nLibConstCount、m_pLibConst 成员说明：

    下面是 LIB_CONST_INFO 的定义：

    struct LIB_CONST_INFO
    {
        LPTSTR    m_szName;
        LPTSTR    m_szEGName;
        LPTSTR    m_szExplain;

        SHORT     m_shtReserved;  // 必须为 1 。

        #define    CT_NUM             1    // sample: 3.1415926
        #define    CT_BOOL            2    // sample: 1
        #define    CT_TEXT            3    // sample: "abc"
        SHORT     m_shtType;

        LPTSTR    m_szText;        // CT_TEXT
        DOUBLE    m_dbValue;       // CT_NUM、CT_BOOL
    };
    typedef LIB_CONST_INFO* PLIB_CONST_INFO;

    例子：

    LIB_CONST_INFO s_ConstInfo [] =
    {
        {    _T("引号"), NULL,   _T("半角双引号"),   1,  CT_TEXT,    _T("\""),   0               },
        {    _T("pi"),   NULL,   NULL,               1,  CT_NUM,     NULL,       3.1415926535    },
        {    _T("藏青"), NULL,   NULL,               1,  CT_NUM,     NULL,       RGB(0,0,128)    },
    };

    m_nLibConstCount 应该等于 m_pLibConst 所指向定义信息数组的成员数目。

/*****************************************************************/

7、m_pfnRunAddInFn、m_szzAddInFnInfo成员说明：

    这两个成员用作为易语言IDE系统添加辅助功能，所提供功能会被自动添加到IDE的“工具”菜单中。

    下面为 PFN_RUN_ADDIN_FN 的定义：

    typedef INT (WINAPI *PFN_RUN_ADDIN_FN) (INT nAddInFnIndex);

    例子：

    INT fnAddInFunc (INT nAddInFnIndex)
    {
        if (nAddInFnIndex == 0)  // 是否为第一个功能?
        {
            // 有关 NotifySys 请见前面的说明。
            HWND hWnd = (HWND)NotifySys (NES_GET_MAIN_HWND);
            if (hWnd != NULL)
                ::MessageBox (hWnd, "这是个辅助工具功能!", "辅助工具", MB_YESNO);
        }
        return 0;
    }

    在 LIB_INFO 中作以下设置：
        m_pfnRunAddInFn = fnAddInFunc;
        m_szzAddInFnInfo = _T("辅助功能1\0这是个用作测试的辅助工具功能。\0\0");

/*****************************************************************/

8、如何定义并实现全局命令（即非对象的方法）：

    需要使用到以下成员：

    INT                 m_nCmdCount;    // 必须等于 m_pBeginCmdInfo 所指向的 CMD_INFO 的数目。
    PCMD_INFO           m_pBeginCmdInfo;
    PFN_EXECUTE_CMD*    m_pCmdsFunc;

    ///////////////////////////////////////////////

    其中 CMD_INFO 用作提供命令定义，具体定义及说明为：

    struct CMD_INFO
    {
        LPTSTR        m_szName;            // 命令中文名称
        LPTSTR        m_szEGName;            // 命令英文名称，可以为空或NULL。

        LPTSTR        m_szExplain;        // 命令详细解释
        SHORT         m_shtCategory;        // 全局命令的所属类别，从1开始，减一后的值为指向LIB_INFO的
                                        // m_szzCategory成员所提供的某个类别字符串的索引。
                                        // 对象成员命令的此值为-1。

        #define        CT_IS_HIDED                    (1 << 2)
            //   本命令是否为隐含命令（即不需要由用户直接输入的命令（如循环结束命令）或被废弃
            // 但为了保持兼容性又要存在的命令）。
        #define        CT_IS_ERROR                    (1 << 3)
            // 本命令在本库中不能使用，具有此标志一定隐含，主要用作在不同语言版本的相同库中使用，
            // 即：A命令在A语言版本库中可能需要实现并使用，但在B语言版本库中可能就不需要。如果
            // 程序中使用了具有此标志的命令，则只能支持该程序调入和编译，而不能支持运行。
            // 如具有此标志，可以不实现本命令的执行部分。
        #define        CT_DISABLED_IN_RELEASE_VER    (1 << 4)
            // 具有本标志的命令在易语言系统编译RELEASE版易程序时将被跳过，本类型命令必须无返回值。
        #define        CT_ALLOW_APPEND_NEW_ARG        (1 << 5)
            //   在本命令的参数表的末尾是否可以添加新的参数，新参数等同于参数表中的最后一个参数。
        #define        CT_RETURN_ARRAY_DATA        (1 << 6)
            // 用于说明m_dtRetType，说明是否为返回数组数据。
        WORD         m_wState;

        /*  !!!!! 千万注意：如果返回值类型定义为 _SDT_ALL ，绝对不能返回数组(即CT_RETURN_ARRAY_DATA
            置位)或复合数据类型的数据(即用户或库自定义数据类型但不包含窗口或菜单单元)，
            因为用户程序无法自动删除复合类型中所分配的额外空间(如文本型或者字节集型成员等)。 */
        DATA_TYPE    m_dtRetType;    // 返回值数据类型。

        WORD         m_wReserved;    // 保留，必须为0。

        // 级别宏，用作为用户提供学习难度说明。
        #define    LVL_SIMPLE          1        // 初级
        #define    LVL_SECONDARY       2        // 中级
        #define    LVL_HIGH            3        // 高级
        SHORT        m_shtUserLevel;    // 命令的学习难度级别，本成员的值为上面的级别宏。

        SHORT        m_shtBitmapIndex;    // 指定图像索引，从1开始，0表示无。减一后的值为指向支持库中名为
                                          // "LIB_BITMAP"的BITMAP资源中某一部分16X13位图的索引。
        SHORT        m_shtBitmapCount;    // 图像数目(用作为IDE提供动画图片).

        INT          m_nArgCount;         // 命令的参数数目
        PARG_INFO    m_pBeginArgInfo;     // 指向本命令的参数定义信息数组
    };
    typedef CMD_INFO* PCMD_INFO;

    ///////////////////////////////////////////////

    CMD_INFO 中使用 ARG_INFO 用作提供命令的参数定义，具体定义及说明为：

    typedef struct
    {
        LPTSTR         m_szName;              // 参数名称
        LPTSTR         m_szExplain;           // 参数详细解释
        SHORT          m_shtBitmapIndex;      // 参见 CMD_INFO 中的同名成员
        SHORT          m_shtBitmapCount;      // 参见 CMD_INFO 中的同名成员

        DATA_TYPE      m_dtDataType;          // 参数的数据类型

        INT            m_nDefault;
            // 系统基本类型参数的默认指定值（在编译时编译器将自动处理）：
            //     1、数值型：直接为数值（如为小数，只能指定其整数部分，
            //          如为长整数，只能指定不超过INT限值的部分）；
            //     2、逻辑型：1等于真，0等于假；
            //     3、文本型：本成员此时为LPTSTR指针，指向默认文本串；
            //     4、其它所有类型参数一律无默认指定值。

        #define        AS_HAS_DEFAULT_VALUE                (1 << 0)
                // 本参数有默认值，默认值在m_nDefault中说明，与下标志互斥。
        #define        AS_DEFAULT_VALUE_IS_EMPTY           (1 << 1)
                // 本参数有默认值，默认值为空，与上标志互斥。
        // 下面五个标志同时只能有一个置位。
        #define        AS_RECEIVE_VAR                      (1 << 2)
                // 为本参数提供数据时必须提供非数组型容器。
        #define        AS_RECEIVE_VAR_ARRAY                (1 << 3)
                // 为本参数提供数据时必须提供数组型容器。
        #define        AS_RECEIVE_VAR_OR_ARRAY             (1 << 4)
                // 为本参数提供数据时必须提供数组或非数组型容器。
        #define        AS_RECEIVE_ARRAY_DATA               (1 << 5)
                // 为本参数提供数据时必须提供数组型数据。
        #define        AS_RECEIVE_ALL_TYPE_DATA            (1 << 6)
                // 为本参数提供数据时可以提供非数组或数组数据。
        DWORD        m_dwState;
    }
    ARG_INFO, *PARG_INFO;

    ///////////////////////////////////////////////

    m_pCmdsFunc 用作提供所有命令的实现函数列表，FN_EXECUTE_CMD 的原型为：

    typedef void (*PFN_EXECUTE_CMD) (PMDATA_INF pRetData, INT nArgCount, PMDATA_INF pArgInf);

    参数说明：
    1、pRetData用作提供返回数据，当对应CMD_INFO中m_dtRetType为_SDT_NULL
       （即定义无返回值）时，pRetData无效；
    2、pArgInf 提供参数数据本身，所指向的 MDATA_INF 数组记录每个输入参数，
       成员数目等同于 nArgCount 。

    MDATA_INF 的定义为：

    struct MDATA_INF
    {
        union
        {
            // 注意当对应参数具有AS_RECEIVE_VAR或AS_RECEIVE_VAR_ARRAY或AS_RECEIVE_VAR_OR_ARRAY
            // 标志定义时将使用下面的第二部分。

            // 第一部分。
            BYTE          m_byte;         // SDT_BYTE 数据类型的数据，下同。
            SHORT         m_short;        // SDT_SHORT
            INT           m_int;          // SDT_INT
            INT64         m_int64;        // SDT_INT64
            FLOAT         m_float;        // SDT_FLOAT
            DOUBLE        m_double;       // SDT_DOUBLE
            DATE          m_date;         // SDT_DATE_TIME
            BOOL          m_bool;         // SDT_BOOL

            char*         m_pText;        // SDT_TEXT，经过系统预处理，即使是空文本，此指针值也不会为NULL，以便于处理。
                                          // 指针所指向数据的格式见前面的描述。
                                          // !!!为了避免修改到常量段(m_pText有可能会指向易程序常量段区域)中
                                          // 的数据，只可读取而不可更改其中的内容，下同。

            LPBYTE        m_pBin;         // SDT_BIN，经过系统预处理，即使是空字节集，此指针值也不会为NULL，以便于处理。